mokelay-server-core

Core server utilities for Mokelay.

Custom Blocks

宿主服务可以通过 createMokelayOrchestrationHandler 注册自己的 Block：

createMokelayOrchestrationHandler({
  blockDefinitions: {
    example: {
      executor: async ({ inputs }) => ({ value: inputs.value }),
      allowedOutputs: ['value'],
    },
  },
})

需要数据库连接的 Block 设置 requiresDatasource: true，并在 DSL 的 inputs.datasource 中声明数据源。自定义名称不能覆盖内置 Block。

Terminal Responses

API JSON 支持旧版顶层 response，也支持按结束点配置的 responses：

{
  "responses": {
    "success_block": { "ok": true },
    "false_node": { "ok": false }
  }
}

当流程结束在 nextBlock: null 时，普通 block 使用 block UUID，controller 分支使用 node UUID，starter 直接结束时使用 starter。运行时优先使用 responses[terminalUuid]，未配置时回退到顶层 response。

普通 Block（包括 executeFragment）可选配置 errorNextBlock。Block 执行失败时，未配置该字段会保持原有抛错行为；配置为另一个 Block UUID 时进入错误分支，配置为 null 时以当前 Block UUID 作为终点并选择对应的 responses。这适用于 OAuth callback 等必须把后续编排错误转换成重定向响应的流程。

Fragments

复用编排使用 fragment: true 与 params 声明，不配置 HTTP method/request，也不能通过 HTTP 路由直接执行：

{
  "uuid": "format_name",
  "fragment": true,
  "params": ["name"],
  "blocks": [{ "uuid": "starter", "nextBlock": null }],
  "response": { "name": { "template": "{{params.name}}" } }
}

普通 API 通过 executeFragment Block 调用；fragmentUuid 必须是字面量，outputs 固定为 ["result"]。Fragment 只能访问自己的 params、blocks 与调用链共享的 now，V1 不支持 Fragment 嵌套。

Fragment 与调用方使用同一所有权域，内置和用户编排不能互相引用：

• 内置 API 位于 server/assets/mokelay-apis/{uuid}.json，只能引用 server/assets/mokelay-apis/fragment/{uuid}.json（Nitro 使用相同的 asset key 结构）。内置 Fragment 不查询数据库或 R2。
• 用户 API 来自 R2/数据库，只能引用 apis 表中 status=published AND fragment=true 的记录。用户 Fragment 不查询内置 assets 或 R2。
• 两个域即使存在相同 Fragment UUID，也会各自解析本域定义。HTTP 顶层加载只检查 mokelay-apis/ 根目录，因此 fragment/ 下的内置配置不能被独立访问。

普通 HTTP API 从 R2 读取前会检查数据库中的当前元数据；如果 UUID 已成为 Fragment、数据库记录已删除或类型检查失败，会拒绝执行旧 R2 对象。未配置 Mokelay 数据库的 R2-only 部署仍可直接读取 R2，但用户 Fragment 仍要求数据库中的已发布记录。宿主注入 loadApiJson 时，该 loader 继续同时负责顶层 API 与其 Fragment，方便测试及自定义嵌入；自定义 Block 不能绕过 executeFragment 直接调用 Fragment。

直接调用 executeApiJson(event, rawApiJson, options) 时，raw DSL 默认视为用户 API；执行内置 raw DSL 需要设置 options.apiJsonSource: "system"。createMokelayOrchestrationHandler 会根据顶层 API 的实际加载位置自动判定来源，不需要设置该选项。

Publish

npm run publish:npm

This checks npm auth, prompts npm login when needed, runs typecheck/build/test, bumps the patch version, and publishes to npm.