@77-zhike/app-sdk 0.2.0-d7b1.2

package/src/server/index.d.ts

@@ -0,0 +1,268 @@
+import type { JsonValue } from "../index.js";
+
+/** 当前执行的 App API Token；由可信 Runtime Module 在服务端模块求值前注入。 */
+export const ZHIKE_API_TOKEN: string;
+
+/** 由调用方选择稳定操作身份；SDK 不生成 Key 或自动重试。 */
+export interface IdempotencyOptions { idempotencyKey?: string }
+
+/** App Settings 条件写入要求使用刚读取到的 revision。 */
+export interface VersionCondition extends IdempotencyOptions { expectedRevision: number }
+
+/** 当前 App 的单个持久化配置。 */
+export interface AppSetting { key: string; value: JsonValue; revision: number }
+
+/** 只列出当前 App 的有效配置，不含清空元数据。 */
+export function getSettings(): Promise<Readonly<{ items: AppSetting[] }>>;
+
+/** 不存在时返回 null/revision=0，清空后的 null 保留正 revision。 */
+export function getSetting(key: string): Promise<Readonly<AppSetting>>;
+
+/** null 清空；容量、大小和深度限制由平台原子校验。 */
+export function setSetting(key: string, value: JsonValue, options: VersionCondition): Promise<Readonly<AppSetting>>;
+
+/** 当前 App Installation 隔离的字符串 KV。 */
+export interface AppKv {
+  /** 读取字符串；不存在或已过期时返回 null。 */
+  get(key: string): Promise<string | null>;
+  /** 原子覆盖字符串，可选正整数 TTL 秒数。 */
+  set(key: string, value: string, options?: { ttlInSeconds?: number }): Promise<void>;
+  /** 幂等删除字符串。 */
+  delete(key: string): Promise<void>;
+}
+
+/** 当前执行可用的 Installation 级 KV。 */
+export const kv: AppKv;
+
+/** 当前 Installation 已激活的稳定 Webhook Handler。 */
+export interface WebhookHandler {
+  /** 平台生成的稳定 Handler ID。 */
+  id: string;
+  /** 与源码文件对应的稳定名称。 */
+  fileName: string;
+  /** 可注册到外部系统或 Workspace Webhook 的平台回调地址。 */
+  url: string;
+}
+
+/** 幂等激活当前 Manifest 已声明的稳定 Webhook Handler。 */
+export function createWebhookHandler(input: {
+  /** `src/app/webhooks/<fileName>.webhook.ts` 中的 fileName。 */
+  fileName: string;
+}): Promise<Readonly<WebhookHandler>>;
+
+/** 列出当前 Installation 已激活的 Webhook Handlers。 */
+export function listWebhookHandlers(): Promise<readonly Readonly<WebhookHandler>[]>;
+
+/** 幂等停用当前 Installation 自己的 Webhook Handler。 */
+export function deleteWebhookHandler(id: string): Promise<void>;
+
+/** Workspace Webhook 当前公开的 Record 事件目录。 */
+export type WorkspaceWebhookRecordEventType =
+  | "record.created"
+  | "record.updated"
+  | "record.deleted"
+  | "record.archived"
+  | "record.restored";
+
+/** Workspace Webhook 当前公开的 Task 事件目录。 */
+export type WorkspaceWebhookTaskEventType =
+  | "task.created"
+  | "task.updated"
+  | "task.deleted";
+
+/** Workspace Webhook 当前公开的 Note 事件目录。 */
+export type WorkspaceWebhookNoteEventType =
+  | "note.created"
+  | "note.updated"
+  | "note.deleted";
+
+/** Workspace Webhook 当前公开的 Activity 事件目录。 */
+export type WorkspaceWebhookActivityEventType =
+  | "activity.created"
+  | "activity.updated"
+  | "activity.deleted";
+
+/** Workspace Webhook 当前公开的 Worklist Entry 事件目录。 */
+export type WorkspaceWebhookListEntryEventType =
+  | "list-entry.created"
+  | "list-entry.updated"
+  | "list-entry.deleted";
+
+/** Webhook 通知中的可信操作者引用。 */
+export interface WorkspaceWebhookActorReference {
+  /** 操作者类型。 */
+  type: "human" | "agent" | "automation" | "integration" | "system";
+  /** 稳定主体 ID；无具体主体的 system 操作可以为空。 */
+  id: string | null;
+}
+
+/** Webhook 通知中的 Record 与可选字段 Slug。 */
+export interface WorkspaceWebhookRecordIdentity {
+  /** 当前 Workspace ID。 */
+  workspaceId: string;
+  /** 当前公开对象 Slug。 */
+  objectSlug: string;
+  /** Record 实例 ID。 */
+  recordId: string;
+  /** 仅 `record.updated` 存在的当前公开字段 Slug。 */
+  fieldSlug?: string;
+}
+
+/** 最小 Record Webhook Event；业务值需要通过 Record API 查询。 */
+export interface WorkspaceWebhookRecordEvent {
+  /** Record 事件类型。 */
+  eventType: WorkspaceWebhookRecordEventType;
+  /** 事件涉及的资源 identity。 */
+  id: WorkspaceWebhookRecordIdentity;
+  /** source fact 无可信 actor 时为空。 */
+  actor: WorkspaceWebhookActorReference | null;
+}
+
+/** Webhook 通知中的 Task identity。 */
+export interface WorkspaceWebhookTaskIdentity {
+  /** 当前 Workspace ID。 */
+  workspaceId: string;
+  /** Task 实例 ID。 */
+  taskId: string;
+}
+
+/** 最小 Task Webhook Event；业务值需要通过 Task API 查询。 */
+export interface WorkspaceWebhookTaskEvent {
+  /** Task 事件类型。 */
+  eventType: WorkspaceWebhookTaskEventType;
+  /** 事件涉及的 Task identity。 */
+  id: WorkspaceWebhookTaskIdentity;
+  /** source fact 无可信 actor 时为空。 */
+  actor: WorkspaceWebhookActorReference | null;
+}
+
+/** Webhook 通知中的 Note identity。 */
+export interface WorkspaceWebhookNoteIdentity {
+  /** 当前 Workspace ID。 */
+  workspaceId: string;
+  /** Note 实例 ID。 */
+  noteId: string;
+}
+
+/** 最小 Note Webhook Event；正文和其他业务值需要通过 Note API 查询。 */
+export interface WorkspaceWebhookNoteEvent {
+  /** Note 事件类型。 */
+  eventType: WorkspaceWebhookNoteEventType;
+  /** 事件涉及的 Note identity。 */
+  id: WorkspaceWebhookNoteIdentity;
+  /** source fact 无可信 actor 时为空。 */
+  actor: WorkspaceWebhookActorReference | null;
+}
+
+/** Webhook 通知中的 Activity identity。 */
+export interface WorkspaceWebhookActivityIdentity {
+  /** 当前 Workspace ID。 */
+  workspaceId: string;
+  /** Activity 实例 ID。 */
+  activityId: string;
+}
+
+/** 最小 Activity Webhook Event；业务值需要通过 Activity API 查询。 */
+export interface WorkspaceWebhookActivityEvent {
+  /** Activity 事件类型。 */
+  eventType: WorkspaceWebhookActivityEventType;
+  /** 事件涉及的 Activity identity。 */
+  id: WorkspaceWebhookActivityIdentity;
+  /** source fact 无可信 actor 时为空。 */
+  actor: WorkspaceWebhookActorReference | null;
+}
+
+/** Webhook 通知中的 Worklist Entry identity。 */
+export interface WorkspaceWebhookListEntryIdentity {
+  workspaceId: string;
+  listId: string;
+  entryId: string;
+  objectSlug: string;
+  recordId: string;
+  /** 仅 `list-entry.updated` 存在。 */
+  fieldSlug?: string;
+}
+
+/** 最小 Worklist Entry Webhook Event；业务值需要通过 Entry API 回查。 */
+export interface WorkspaceWebhookListEntryEvent {
+  eventType: WorkspaceWebhookListEntryEventType;
+  id: WorkspaceWebhookListEntryIdentity;
+  actor: WorkspaceWebhookActorReference | null;
+}
+
+/** Workspace Webhook 当前公开的封闭事件联合。 */
+export type WorkspaceWebhookEvent =
+  | WorkspaceWebhookRecordEvent
+  | WorkspaceWebhookTaskEvent
+  | WorkspaceWebhookNoteEvent
+  | WorkspaceWebhookActivityEvent
+  | WorkspaceWebhookListEntryEvent;
+
+/** Workspace Webhook HTTP 请求体。 */
+export interface WorkspaceWebhookBody {
+  /** 当前 Webhook ID。 */
+  webhookId: string;
+  /** 本次投递携带的事件；接收方不得假设永久只有一条。 */
+  events: WorkspaceWebhookEvent[];
+}
+
+/** 当前服务端执行可使用的 Workspace 外部系统连接。 */
+export interface WorkspaceConnection {
+  /** 当前 Workspace Connection 的稳定 ID。 */
+  id: string;
+  /** 当前 Connect/Reconnect generation 的非敏感稳定表示。 */
+  generation: string;
+  /** 当前凭据类型。 */
+  type: "secret" | "oauth2";
+  /** Secret 或当前 OAuth access token，仅存在于本次服务端执行内存。 */
+  value: string;
+}
+
+/** 同步读取当前执行的连接快照；未连接或暂不可用时抛出安全错误，不在 getter 内刷新。 */
+export function getWorkspaceConnection(): Readonly<WorkspaceConnection>;
+
+/** Server Function 的一期函数合同。 */
+export type ServerFunction<TArgs extends JsonValue[] = JsonValue[], TResult extends JsonValue = JsonValue> =
+  (...args: TArgs) => Promise<TResult>;
+
+/** App 安装通知处理器取得的可信参数。 */
+export interface AppInstalledParams {
+  /** 当前 Installation 的稳定 ID。 */
+  installationId: string;
+  /** 当前 Workspace 的稳定 ID。 */
+  workspaceId: string;
+}
+
+/** App 卸载通知处理器取得的可信参数。 */
+export interface AppUninstalledParams {
+  /** 当前 Installation 的稳定 ID。 */
+  installationId: string;
+  /** 当前 Workspace 的稳定 ID。 */
+  workspaceId: string;
+}
+
+/** Connection 建立前 interceptor 取得的可信参数。 */
+export interface ConnectionAddedParams {
+  /** 本次候选 Connection，只在当前 interceptor 执行内可用。 */
+  connection: Readonly<WorkspaceConnection>;
+}
+
+/** Connection 移除前 interceptor 取得的可信参数。 */
+export interface ConnectionRemovedParams {
+  /** 本次待移除 Connection，只在当前 interceptor 执行内可用。 */
+  connection: Readonly<WorkspaceConnection>;
+}
+
+
+/** 在前端调用的服务端函数中，写入前按当前可信调用者重新校验管理员权限；不接受前端自报角色。 */
+export function requireWorkspaceAdmin(): Promise<void>;
+
+/** 平台注入的单次 Webhook 执行上下文，不能由入站请求覆盖。 */
+export interface WebhookContext {
+  /** 本次入站请求的可信执行 ID；不是业务幂等保证。 */
+  readonly invocationId: string;
+  /** 每次实际执行的独立记录 ID。 */
+  readonly attemptId: string;
+  /** 从 1 开始的业务尝试序号。 */
+  readonly attemptNumber: number;
+}

package/src/server/index.js

@@ -0,0 +1,201 @@
+const SERVER_FUNCTION_MARKER = Symbol.for("zhike.server-function.v1");
+const LIFECYCLE_EVENT_MARKER = Symbol.for("zhike.lifecycle-event.v1");
+const WEBHOOK_HANDLER_MARKER = Symbol.for("zhike.webhook-handler.v1");
+const WORKSPACE_CONNECTION_EVENTS = new Set([
+  "app-installed",
+  "app-uninstalled",
+  "connection-added",
+  "connection-removed",
+]);
+
+export const ZHIKE_API_TOKEN = globalThis.ZHIKE_API_TOKEN;
+const ZHIKE_OPEN_API_BASE_URL = "https://api-clm.77hub.com/v1";
+export const kv = globalThis.ZHIKE_APP_KV;
+
+function requireSettingKey(key) {
+  if (typeof key !== "string" || !key || key === "." || key === "..") {
+    throw new TypeError("setting_key_invalid");
+  }
+  return encodeURIComponent(key);
+}
+
+async function requestAppSetting(path, { method = "GET", value, expectedRevision, idempotencyKey } = {}) {
+  const token = globalThis.ZHIKE_API_TOKEN ?? ZHIKE_API_TOKEN;
+  if (typeof token !== "string" || token.length === 0) {
+    const error = new Error("open_api_token_unavailable");
+    error.code = "open_api_token_unavailable";
+    throw error;
+  }
+  const headers = { authorization: `Bearer ${token}` };
+  if (idempotencyKey !== undefined) {
+    if (typeof idempotencyKey !== "string" || !/^[!-~]{1,200}$/.test(idempotencyKey)) {
+      throw new TypeError("idempotency_key_invalid");
+    }
+    headers["idempotency-key"] = idempotencyKey;
+  }
+  if (value !== undefined) {
+    if (!Number.isSafeInteger(expectedRevision) || expectedRevision < 0) {
+      throw new TypeError("expected_revision_invalid");
+    }
+    headers["if-match"] = `"${expectedRevision}"`;
+    headers["content-type"] = "application/json";
+  }
+  const response = await fetch(`${ZHIKE_OPEN_API_BASE_URL}${path}`, {
+    method,
+    headers,
+    ...(value === undefined ? {} : { body: JSON.stringify({ value }) }),
+  });
+  if (!response.ok) {
+    const body = await response.json().catch(() => ({}));
+    const code = typeof body.code === "string" && /^[a-z_]{1,100}$/.test(body.code)
+      ? body.code
+      : "app_setting_request_failed";
+    const error = new Error(code);
+    error.code = code;
+    error.status = response.status;
+    error.requestId = typeof body.requestId === "string" ? body.requestId : null;
+    throw error;
+  }
+  return Object.freeze(await response.json());
+}
+
+/** 读取当前 App 的全部有效配置。 */
+export const getSettings = () => requestAppSetting("/app-settings");
+/** 读取当前 App 的单个配置及 revision。 */
+export const getSetting = (key) => requestAppSetting(`/app-settings/${requireSettingKey(key)}`);
+/** 条件写入当前 App 的单个配置；null 清空但保留 revision。 */
+export const setSetting = (key, value, options = {}) => {
+  if (value === undefined) throw new TypeError("setting_value_required");
+  return requestAppSetting(`/app-settings/${requireSettingKey(key)}`, {
+    method: "PUT",
+    value,
+    expectedRevision: options.expectedRevision,
+    idempotencyKey: options.idempotencyKey,
+  });
+};
+
+export async function createWebhookHandler({ fileName } = {}) {
+  if (typeof fileName !== "string" || !/^[a-z][a-z0-9-]{0,63}$/.test(fileName)) {
+    const error = new Error("webhook_handler_file_name_invalid");
+    error.code = "webhook_handler_file_name_invalid";
+    throw error;
+  }
+  const capability = globalThis.ZHIKE_WEBHOOK_HANDLER_CAPABILITY;
+  const handler = capability?.create
+    ? await capability.create(fileName)
+    : globalThis.ZHIKE_WEBHOOK_HANDLERS?.[fileName];
+  if (
+    !handler ||
+    typeof handler !== "object" ||
+    handler.fileName !== fileName ||
+    typeof handler.id !== "string" ||
+    typeof handler.url !== "string"
+  ) {
+    const error = new Error("webhook_handler_not_declared");
+    error.code = "webhook_handler_not_declared";
+    throw error;
+  }
+  return Object.freeze({ id: handler.id, fileName, url: handler.url });
+}
+
+export async function listWebhookHandlers() {
+  const capability = globalThis.ZHIKE_WEBHOOK_HANDLER_CAPABILITY;
+  const handlers = capability?.list
+    ? await capability.list()
+    : Object.values(globalThis.ZHIKE_WEBHOOK_HANDLERS ?? {});
+  if (!Array.isArray(handlers)) {
+    const error = new Error("webhook_handler_runtime_unavailable");
+    error.code = "webhook_handler_runtime_unavailable";
+    throw error;
+  }
+  return Object.freeze(handlers.map((handler) => Object.freeze({ ...handler })));
+}
+
+export async function deleteWebhookHandler(id) {
+  if (typeof id !== "string" || id.length === 0) {
+    const error = new Error("webhook_handler_id_invalid");
+    error.code = "webhook_handler_id_invalid";
+    throw error;
+  }
+  const capability = globalThis.ZHIKE_WEBHOOK_HANDLER_CAPABILITY;
+  if (!capability?.delete) {
+    const error = new Error("webhook_handler_runtime_unavailable");
+    error.code = "webhook_handler_runtime_unavailable";
+    throw error;
+  }
+  await capability.delete(id);
+}
+
+// 同步读取本次执行快照；旧 dispatcher 的 exact lifecycle global 仅作兼容。
+export function getWorkspaceConnection() {
+  const current = globalThis.ZHIKE_CURRENT_WORKSPACE_CONNECTION;
+  const connection = globalThis.ZHIKE_WORKSPACE_CONNECTION ??
+    (current?.status === "ready" ? current.connection : null);
+  if (
+    !connection ||
+    typeof connection !== "object" ||
+    typeof connection.id !== "string" ||
+    typeof connection.generation !== "string" ||
+    !["oauth2", "secret"].includes(connection.type) ||
+    typeof connection.value !== "string"
+  ) {
+    const code = ["connection_not_configured", "connection_not_connected", "connection_credential_unavailable", "connection_temporarily_unavailable"].includes(current?.code)
+      ? current.code : "connection_unavailable";
+    const error = new Error(code);
+    error.code = code;
+    throw error;
+  }
+  return Object.freeze({
+    id: connection.id,
+    generation: connection.generation,
+    type: connection.type,
+    value: connection.value,
+  });
+}
+
+// 仅兼容已构建的旧 Bundle；新源码入口由 .server.ts 的默认 async 函数确定。
+export function defineServerFunction(handler) {
+  if (typeof handler !== "function") {
+    throw new TypeError("Server Function handler 必须是函数");
+  }
+  Object.defineProperty(handler, SERVER_FUNCTION_MARKER, { value: true });
+  return handler;
+}
+
+// 仅保留已发布旧 Bundle 的运行时兼容；新源码必须使用约定式默认 async function。
+export function defineLifecycleEvent(definition) {
+  if (!definition || typeof definition !== "object" || Array.isArray(definition)) {
+    throw new TypeError("Lifecycle Event definition 必须是对象");
+  }
+  if (!WORKSPACE_CONNECTION_EVENTS.has(definition.event)) {
+    throw new TypeError("Lifecycle Event 类型不受支持");
+  }
+  if (typeof definition.handler !== "function") {
+    throw new TypeError("Lifecycle Event handler 必须是函数");
+  }
+  return Object.freeze({ ...definition, [LIFECYCLE_EVENT_MARKER]: true });
+}
+
+export function defineWebhookHandler(definition) {
+  if (!definition || typeof definition !== "object" || Array.isArray(definition)) {
+    throw new TypeError("Webhook Handler definition 必须是对象");
+  }
+  if (!Array.isArray(definition.methods) || definition.methods.length === 0) {
+    throw new TypeError("Webhook Handler methods 不能为空");
+  }
+  if (typeof definition.handler !== "function") {
+    throw new TypeError("Webhook Handler handler 必须是函数");
+  }
+  return Object.freeze({ ...definition, [WEBHOOK_HANDLER_MARKER]: true });
+}
+
+
+export async function requireWorkspaceAdmin() {
+  const check = globalThis.ZHIKE_CALLER_CAPABILITY?.requireWorkspaceAdmin;
+  if (typeof check !== "function") {
+    const error = new Error("runtime_function_caller_unavailable");
+    error.code = "runtime_function_caller_unavailable";
+    throw error;
+  }
+  await check();
+}

package/src/toolchain/canonical-json.js

@@ -0,0 +1,17 @@
+export function canonicalJsonBytes(value) {
+  return Buffer.from(`${JSON.stringify(sortJson(value))}\n`, "utf8");
+}
+
+function sortJson(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortJson);
+  }
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.keys(value)
+        .sort()
+        .map((key) => [key, sortJson(value[key])]),
+    );
+  }
+  return value;
+}

package/src/toolchain/index.js

@@ -0,0 +1,103 @@
+import { createHash } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+import { TOOLING_VERSION } from "../config.js";
+import { ZhikeCliError } from "../errors.js";
+import { readProjectBinding } from "../project-binding.js";
+
+export { discoverAppSources } from "./source-discovery.js";
+export {
+  APP_BUNDLE_CONTENT_TYPE,
+  APP_BUNDLE_PACKAGE_FORMAT,
+  APP_MANIFEST_MEDIA_TYPE,
+  JAVASCRIPT_MEDIA_TYPE,
+  buildAppBundle,
+} from "./real-build.js";
+export {
+  APP_BUNDLE_ALLOWED_MEMBERS,
+  APP_BUNDLE_MEMBER_MAX_BYTES,
+  APP_BUNDLE_TAR_MAX_BYTES,
+  createTransportTar,
+  parseTransportTar,
+} from "./transport-tar.js";
+
+export const MOCK_PACKAGE_FORMAT = "zhike.mock-build.v1";
+export const MOCK_ARTIFACT_KIND = "mock";
+export const MOCK_ARTIFACT_MAX_BYTES = 1024 * 1024;
+
+export async function buildMockArtifact({
+  projectDirectory = process.cwd(),
+  expectedEnvironment = null,
+  writeToDist = false,
+} = {}) {
+  await readProjectBinding(projectDirectory, expectedEnvironment);
+  const payload = {
+    format: MOCK_PACKAGE_FORMAT,
+    kind: MOCK_ARTIFACT_KIND,
+    payload: {
+      message: "qiqizhike developer app mock build",
+    },
+    toolingVersion: TOOLING_VERSION,
+  };
+  const bytes = Buffer.from(`${JSON.stringify(payload)}\n`, "utf8");
+  if (bytes.byteLength > MOCK_ARTIFACT_MAX_BYTES) {
+    throw new ZhikeCliError(
+      "zhike_mock_artifact_too_large",
+      "Mock Artifact 超过 1 MiB 上限",
+    );
+  }
+  const result = Object.freeze({
+    bytes,
+    size: bytes.byteLength,
+    sha256: createHash("sha256").update(bytes).digest("hex"),
+    packageFormat: MOCK_PACKAGE_FORMAT,
+    kind: MOCK_ARTIFACT_KIND,
+    toolingVersion: TOOLING_VERSION,
+  });
+  if (writeToDist) {
+    const distDirectory = resolve(projectDirectory, "dist");
+    await mkdir(distDirectory, { recursive: true });
+    await writeFile(resolve(distDirectory, "mock-build.json"), bytes, {
+      flag: "w",
+    });
+  }
+  return result;
+}
+
+export function validateMockArtifact(bytes) {
+  if (!Buffer.isBuffer(bytes) || bytes.byteLength > MOCK_ARTIFACT_MAX_BYTES) {
+    throw new ZhikeCliError(
+      "zhike_mock_artifact_invalid",
+      "Mock Artifact 无效或超过 1 MiB 上限",
+    );
+  }
+  let value;
+  try {
+    value = JSON.parse(bytes.toString("utf8"));
+  } catch (error) {
+    throw new ZhikeCliError(
+      "zhike_mock_artifact_invalid",
+      "Mock Artifact 不是有效 JSON",
+      { cause: error },
+    );
+  }
+  const keys = Object.keys(value).sort();
+  if (
+    keys.join(",") !== "format,kind,payload,toolingVersion" ||
+    value.format !== MOCK_PACKAGE_FORMAT ||
+    value.kind !== MOCK_ARTIFACT_KIND ||
+    value.toolingVersion !== TOOLING_VERSION ||
+    !value.payload ||
+    typeof value.payload !== "object" ||
+    Array.isArray(value.payload) ||
+    Object.keys(value.payload).join(",") !== "message" ||
+    value.payload.message !== "qiqizhike developer app mock build"
+  ) {
+    throw new ZhikeCliError(
+      "zhike_mock_artifact_invalid",
+      "Mock Artifact 不符合 zhike.mock-build.v1 严格合同",
+    );
+  }
+  return value;
+}