鸡尾酒

用于在Maypop上运行的应用程序的框架中立浏览器SDK. 它揭露了 与主机相同的对象和能力 /sdk/v1.js 脚本: 身份, KV, Drive, AI, 集成, 多人游戏, 通知, 以及其他 API 在其中 类型 Maypop 合同.

安装

pnpm add @basilica-digital/maypop-sdk

从浏览器代码导入 SDK, 在使用 Maypop 主机前等待 能力:

import { maypop } from "@basilica-digital/maypop-sdk";

await maypop.ready();
const todos = await maypop.kv.list({ prefix: "todo/" });

默认和命名导出与 window.maypop这样 框架代码和脚本可以互操作而无需适配器:

import maypop, { type Maypop } from "@basilica-digital/maypop-sdk";

function currentUser(sdk: Maypop = maypop) {
  return sdk.user;
}

当一个框架在服务器上制作时,模块是安全的导入 。 访问 sDK 仍然扔出,因为能力属于浏览器托管的应用程序 届会。 打电话 getMaypop() 当一个 SSR 框架需要时从只浏览器代码中 明确推迟访问.

反应

React App可以订阅Maypop状态而无需手动协调主机 握手或效果清理:

import {
  useMaypopKV,
  useMaypopMode,
  useMaypopSession,
} from "@basilica-digital/maypop-sdk/react";

export function Counter() {
  const session = useMaypopSession();
  const mode = useMaypopMode();
  const count = useMaypopKV("counter", 0);

  if (session.status === "connecting") return <p>Connecting…</p>;
  if (session.status === "error") return <p>{session.error.message}</p>;

  return (
    <button
      disabled={mode === "read-only" || count.isMutating}
      onClick={() => count.setValue(count.value + 1)}
    >
      {count.value}
    </button>
  );
}

钩子自动使用主机SDK. MaypopProvider 仅需 在测试或未来的本地沙盒主机中注入另一个客户端 :

import { MaypopProvider } from "@basilica-digital/maypop-sdk/react";

<MaypopProvider client={sandboxClient}>
  <App />
</MaypopProvider>

当地发展东道方

维特

将 Maypop 插件添加到现有的 Vite 配置中 :

import { maypop } from "@basilica-digital/maypop-sdk/vite";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [maypop()],
});

建设

将等效插件添加到 Rsbuilding 配置 :

import { defineConfig } from "@rsbuild/core";
import { maypop } from "@basilica-digital/maypop-sdk/rsbuild";

export default defineConfig({
  plugins: [maypop()],
});

下一个.js

包装下一个.js配置 。 包装器只将其沙盒代理添加到 next dev; 构建和生产服务器保留原始配置 :

import { withMaypop } from "@basilica-digital/maypop-sdk/next";

export default withMaypop({
  output: "export",
});

框架的正常开发命令然后作为 Maypop 主机服务其 URL 包括路由程序打开或 刷新深的 URL 。 该应用程序使用生产SDK握手,iframe 权限,和 API 形状。 共享 KV 状态持续到 .maypop/local/kv.json,而驱动元数据与字节持续在 .maypop/local/drive/。 。 。 .

Next.js 绑定器也添加了机器的活跃网络地址到 allowedDevOrigins从另一个设备打开开发服务器 局域网装入并水合其客户端脚本。 任何配置的条目是 保留了下来.

身份、成员、KV、Drive、模拟MCP集成、共享卡预览和a 本地可提供通知收发箱。 他们的能力范围是: 通过报告 maypop.user.scopes; 需要其它能力的API失败 与 maypop/unsupported 当他们到达当地的宿主. maypop.apps.open() 组设置导航仍然无法进行,因为它们需要 Maypop产品外壳而不是应用API.

maypop.notify() 被默认捕获,而不是交付。 打开 开发主机的Maypop徽章,或访问 /_maypop/notifications,改为 检查请求的和已解决的收件人、头衔、身体和深层链接. 接获的电话持续 .maypop/local/notifications.json。 。 。 .

认证开发

创建 .maypop/local/dev.json 选择此机器为认证 能力。 吉特忽略了它与其余部分 .maypop/local/: 它选择一个 开发者账户并能够访问真实的应用数据或可计费的AI呼叫.

混合模式将 KV 和 Drive 保留在本地,同时转发一组明确的 通过账户认证的仅读或非数据能力 maypop auth数字 :

{
  "mode": "hybrid",
  "profile": "dev",
  "remoteCapabilities": ["ai", "members", "link", "mcp", "multiplayer"],
  "notifications": "inspect"
}

ai 包括聊天完成、流传、决定(类型分类、, 在TypeSafe的Jev模型上进行路由,取笑,并评分,图像,视频,音频, 转录,和 maypop.agent (开发主机为它的懒浏览器服务) 块. 这些呼叫使用所选账户的实际允许使用,并可以消费 学分. members 阅读真正的应用程序名册, link 启用服务器侧 URL 脱发, mcp 曝光该应用程序真正的连接 MCP 服务器和工具,以及 multiplayer 在装入Iroh JS/Wasm时使用真实的会合API 本地运行时间 。 KV和Drive继续留在当地,通知留在 探长 连接服务器 maypop mcp connect运行 maypop mcp link 在启动开发服务器之前在应用程序仓库中。 一个混合 配置无法结合真实 mcp 具备 .maypop/local/mcp.json 固定装置.

连接模式跳过本地 KV/ Drive 初始化并发送整个app API 表面到真实的应用程序 :

{
  "mode": "connected",
  "profile": "dev",
  "notifications": "inspect"
}

项目必须已经连接到 maypop init,并选择了 CLI 配置文件必须经过认证,并能够访问该应用程序。 奥米 profile 改为 使用通常的 CLI 选择规则,包括 MAYPOP_PROFILE 和简介 其 API URL 符合寄存器 。 节点开发主机读取 由 : maypop auth 薄荷薄荷, 应用范围会议本身。 保存的 CLI 证书和会话刷新符号 从未接触过应用程序代码,也从未在下列情况下被写入: .maypop/。 。 。 .

真正的通知交付需要连接模式和第二次明确 选入 :

{
  "mode": "connected",
  "notifications": "live"
}

使用 "notifications": "disabled" 完全取消通知许可. 默认是 "inspect" 在每一个开发模式中.

当地身份和受众

Sandbox 模式可以从匿名、读者、作家、编辑或管理员开始 收视者并出露出可塑观众. 这同样是公开的 身份、模式、范围、成员以及作为主机SDK的登录行为:

{
  "mode": "sandbox",
  "viewer": {
    "username": "Visitor",
    "role": "reader",
    "anonymous": true,
    "signInGrantsWrite": true,
    "signedInUsername": "Alice",
    "signedInRole": "writer"
  },
  "members": [
    { "username": "Bob", "role": "editor", "connected": false }
  ],
  "guestCount": 2
}

通话 maypop.signIn() 将本地会话升级 重新装入应用程序为已配置的登录查看器 。 本地API执行 只读 KV、 Drive 和通知范围, 因此直接请求不能绕过 浏览器 SDK 的权限检查 .

本地 KV 写入验证生产密钥和值限制 。 设定 "strictStorage": true 以额外强制执行承诺 .maypop/kv-policy.json 在当地拉和推的时候 预设和高级 政策使用的作用、关键模式和所有权的前提与 平台.

模拟整合和东道方行动

添加 .maypop/local/mcp.json 进行MCP发现、工具包装、呼叫和 代理工具, 不引用真正的外部整合 :

{
  "schemaVersion": 1,
  "servers": [
    {
      "id": "search",
      "name": "Fixture search",
      "url": "mock://search",
      "account": "[email protected]",
      "tools": [
        {
          "name": "lookup",
          "description": "Return a fixed search fixture.",
          "inputSchema": {
            "type": "object",
            "properties": { "query": { "type": "string" } }
          },
          "result": {
            "content": [{ "type": "text", "text": "Fixture result" }],
            "structuredContent": { "items": [] }
          }
        }
      ]
    }
  ]
}

maypop.link.to(path) 返回本地深链接,并 maypop.share() 打开一个 包含一个主机的卡片 。 带a的扣押通知 path 曝光一个 在本地应用程序中打开 动作在收发箱。 本地主机打开这些路 Maypop 这样做——应用程序在输入时加载路径 location.hash 财务报告和审定财务报表 maypop.launchPath ——如此一个应用程序,使这里的路线正确 路线正确 曾经出版。 没有任何人声称曾发表过本地链接,或者 已发出扣押通知.

本地无记名符號是随机的,每一次服务器运行,一个锁可以防止两次 从写入同一数据目录的开发服务器。 用别的 目录或查看器名称 :

maypop({
  dataDirectory: ".maypop/alice",
  username: "Alice",
});

本地主机是开发工具,而不是安全边界. 留着 将开发服务器绑入可信任的界面,除非项目本身是 安全地暴露出来.

这台机器属于什么 .maypop/local/:当地身份, dev.json、MCP固定装置、KV和Drive数据、捕获的通知和 锁上锁 开发服务器用它自己创建 .gitignore,所以它留下来 即使是Git的应用程序 .gitignore 没有提及它. .maypop/kv-policy.json 站在一边,承诺:平台阅读 并应用到每个已发布的版本。 在第一个 运行,服务器将旧版本直接写入 .maypop/ 输入 .maypop/local/它留下了一个旧的 .maypop/.lock 它在哪里,不再读 ; 与 git rm --cached .maypop/.lock。 。 。 .

锁只在写它的过程运行时保存. 它记录 process的 PID 和启动时间, 所以服务器留下的锁 ,或者它的沙盒重新启动并将其PID交给另一个进程 已经接管了 一个不关闭而退出的服务器仍然会去掉其锁.

绑定只会影响框架开发服务器. 生产建筑 仍然是普通的应用程序捆绑. maypop init 记录匹配的构建适配器 内 maypop.toml,以及 maypop publish 构建并上传其静态输出.

主机脚本兼容性

现有应用程序可以继续加载全局架构 :

<script src="https://api.dev.maypop.ai/sdk/v1.js"></script>

导入 @basilica-digital/maypop-sdk 相反,从软件包中安装相同的构件。 两者 窗体使用相同的主机握手和后端 API,两个都曝光 window.maypop。不要在一个应用程序中使用两种表格;运行时间为一元时间, 但一个就够了.

这个包是"Maypop"协议的来宾一面. 在Maypop外边, maypop.ready() 等待兼容的主机。 以上框架的整合 提供主机协议而不要求应用程序更改其SDK 进口.

后端文物

已出版的柏球还包含生成的主机脚本,懒惰能力 块、外壳文件、合同和Iroh WebAssembly运行时间 dist/。 。 。 . Maypop后端针入精确的软件包版本,并将这些文件嵌入其中 二进制,所以后端的构建从不依赖于SDK寄存器的移动分支.

源合同和运行时间可通过 @basilica-digital/maypop-sdk/source/v1 财务报告和审定财务报表 @basilica-digital/maypop-sdk/source/runtime 为了梅波自己的合同工具。 应用 代码应使用上述公共入口.

发展

所有维护的SDK代码都住在 src/ 作为类型脚本. pnpm build 汇编 npm 输入,主机为全球,懒散的能力块, shell 主机,注入脚本, 服务人员、申报和后端文物 dist/ 目录。 生成的 JavaScript 从来不是真理的来源, 不应该是 直接编辑.

伊洛赫跑步时间 iroh/;其生成的约束和WebAssembly是 所犯 iroh/prebuilt/ 因此普通软件包构建不需要 Rust/Wasm工具链。 更改后 iroh/src,安装 wasm32-unknown-unknown 目标, wasm-bindgen-cli 匹配被钉住的箱子 版本,和 二分法 wasm-opt,然后运行 :

just build-iroh

释放

版本跟随SemVer, 标记使用匹配 vX.Y.Z 形式。 在标记之前, 更新 package.json 和锁文件,然后运行:

pnpm install --frozen-lockfile
pnpm test
pnpm pack

正在推动匹配标记运行 npm 出版工作流程 。 第一次发布 必须由 npm 拥有者发布; 在此之后, 配置此寄存器为 软件包的可信出版商 .github/workflows/release.yml。 。 。 .