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

package/src/server/index.js

@@ -0,0 +1,242 @@
+const SERVER_FUNCTION_MARKER = Symbol.for("zhike.server-function.v1");
+export { defineWorkflowStep, defineWorkflowStepExecute } from "./steps/index.js";
+export { defineWorkflowTrigger, defineWorkflowTriggerActivate, defineWorkflowTriggerOnEvent, defineWorkflowTriggerDeactivate } from "./triggers/index.js";
+export {
+  defineWorkflowBlock,
+  defineWorkflowBlockExecute,
+  defineWorkflowBlockActivate,
+  defineWorkflowBlockTrigger,
+  defineWorkflowBlockDeactivate,
+} from "./workflow-blocks/index.js";
+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;
+  }
+  if (connection.protocol === "oidc" && (typeof connection.idToken !== "string" || !connection.idToken)) {
+    const error = new Error("connection_credential_unavailable");
+    error.code = "connection_credential_unavailable";
+    throw error;
+  }
+  const protocol = connection.type === "secret"
+    ? "secret"
+    : (connection.protocol === "oidc" && typeof connection.idToken === "string" && connection.idToken
+      ? "oidc" : "oauth2");
+  return Object.freeze({
+    id: connection.id,
+    generation: connection.generation,
+    type: connection.type,
+    protocol,
+    value: connection.value,
+    ...(connection.type === "oauth2" ? { accessToken: connection.value } : {}),
+    ...(protocol === "oidc" ? { idToken: connection.idToken } : {}),
+  });
+}
+
+export function getCurrentUser() {
+  const current = globalThis.ZHIKE_CURRENT_USER;
+  if (
+    !current ||
+    typeof current !== "object" ||
+    typeof current.workspaceMemberId !== "string" ||
+    typeof current.displayName !== "string"
+  ) {
+    const error = new Error("current_user_unavailable");
+    error.code = "current_user_unavailable";
+    throw error;
+  }
+  return Object.freeze({
+    workspaceMemberId: current.workspaceMemberId,
+    displayName: current.displayName,
+    primaryEmailAddress: typeof current.primaryEmailAddress === "string" ? current.primaryEmailAddress : null,
+    avatarUrl: typeof current.avatarUrl === "string" ? current.avatarUrl : null,
+  });
+}
+
+// 仅兼容已构建的旧 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/server/steps/index.d.ts

@@ -0,0 +1,71 @@
+export type WorkflowScalarSchema =
+  | { readonly type: "string"; readonly minLength?: number; readonly enum?: readonly string[]; readonly title?: string; readonly description?: string; readonly examples?: readonly string[] }
+  | { readonly type: "number"; readonly title?: string; readonly description?: string; readonly examples?: readonly number[] }
+  | { readonly type: "boolean"; readonly title?: string; readonly description?: string; readonly examples?: readonly boolean[] };
+
+export interface WorkflowObjectSchema {
+  readonly type: "object";
+  readonly properties: Readonly<Record<string, WorkflowScalarSchema>>;
+  readonly required?: readonly string[];
+  readonly additionalProperties: false;
+  readonly title?: string;
+  readonly description?: string;
+  readonly examples?: readonly (string | number | boolean)[];
+}
+
+export interface WorkflowStepOutcome {
+  readonly id: string;
+  readonly label: string;
+  readonly dataSchema: WorkflowObjectSchema | null;
+}
+
+export interface WorkflowStepDefinition<
+  Config extends WorkflowObjectSchema = WorkflowObjectSchema,
+  Outcomes extends readonly WorkflowStepOutcome[] = readonly WorkflowStepOutcome[],
+> {
+  readonly key: string;
+  readonly title: string;
+  readonly description?: string;
+  readonly connection: "workspace" | "none";
+  readonly configSchema: Config;
+  readonly outcomes: Outcomes;
+}
+
+type ScalarValue<S> = S extends { readonly enum: readonly (infer E)[] } ? E
+  : S extends { readonly type: "string" } ? string
+  : S extends { readonly type: "number" } ? number
+  : S extends { readonly type: "boolean" } ? boolean
+  : never;
+
+type RequiredNames<S extends WorkflowObjectSchema> = S["required"] extends readonly string[]
+  ? S["required"][number] : never;
+
+export type WorkflowSchemaValue<S extends WorkflowObjectSchema> = {
+  [K in keyof S["properties"] as K extends RequiredNames<S> ? K : never]-?: ScalarValue<S["properties"][K]>;
+} & {
+  [K in keyof S["properties"] as K extends RequiredNames<S> ? never : K]?: ScalarValue<S["properties"][K]>;
+};
+
+type OutcomeResult<O extends WorkflowStepOutcome> = O extends WorkflowStepOutcome
+  ? O["dataSchema"] extends WorkflowObjectSchema
+    ? { readonly outcome: O["id"]; readonly data: WorkflowSchemaValue<O["dataSchema"]> }
+    : { readonly outcome: O["id"]; readonly data: null }
+  : never;
+
+export type WorkflowStepResult<Outcomes extends readonly WorkflowStepOutcome[]> =
+  OutcomeResult<Outcomes[number]>;
+
+export function defineWorkflowStep<
+  const Config extends WorkflowObjectSchema,
+  const Outcomes extends readonly [WorkflowStepOutcome, ...WorkflowStepOutcome[]],
+>(definition: WorkflowStepDefinition<Config, Outcomes>): WorkflowStepDefinition<Config, Outcomes>;
+
+export function defineWorkflowStepExecute<
+  Config extends WorkflowObjectSchema,
+  Outcomes extends readonly WorkflowStepOutcome[],
+>(
+  step: WorkflowStepDefinition<Config, Outcomes>,
+  execute: (params: Readonly<{ config: WorkflowSchemaValue<Config> }>) =>
+    WorkflowStepResult<Outcomes> | Promise<WorkflowStepResult<Outcomes>>,
+): (params: Readonly<{ config: WorkflowSchemaValue<Config> }>) =>
+  WorkflowStepResult<Outcomes> | Promise<WorkflowStepResult<Outcomes>>;

package/src/server/steps/index.js

@@ -0,0 +1,15 @@
+const STEP_MARKER = Symbol.for("zhike.workflow-step.v1");
+
+export function defineWorkflowStep(definition) {
+  if (!definition || typeof definition !== "object") {
+    throw new TypeError("workflow_step_definition_invalid");
+  }
+  return Object.freeze({ ...definition, [STEP_MARKER]: true });
+}
+
+export function defineWorkflowStepExecute(step, execute) {
+  if (!step?.[STEP_MARKER] || typeof execute !== "function") {
+    throw new TypeError("workflow_step_execute_invalid");
+  }
+  return execute;
+}

package/src/server/triggers/index.d.ts

@@ -0,0 +1,68 @@
+import type { WorkflowObjectSchema, WorkflowSchemaValue } from "../steps/index.js";
+
+export interface WorkflowTriggerOutcome {
+  readonly id: string;
+  readonly label: string;
+  readonly dataSchema: WorkflowObjectSchema;
+}
+
+export interface WorkflowTriggerDefinition<
+  Config extends WorkflowObjectSchema = WorkflowObjectSchema,
+  Outcomes extends readonly WorkflowTriggerOutcome[] = readonly WorkflowTriggerOutcome[],
+> {
+  readonly key: string;
+  readonly title: string;
+  readonly description?: string;
+  readonly connection: "workspace" | "none";
+  readonly requestHeaders?: readonly string[];
+  readonly configSchema: Config;
+  readonly outcomes: Outcomes;
+}
+
+type OutcomeResult<O extends WorkflowTriggerOutcome> = O extends WorkflowTriggerOutcome
+  ? {
+      readonly type: "outcome";
+      readonly id: O["id"];
+      readonly eventKey: string;
+      readonly data: WorkflowSchemaValue<O["dataSchema"]>;
+    }
+  : never;
+
+export type WorkflowTriggerEventResult<Outcomes extends readonly WorkflowTriggerOutcome[]> =
+  | { readonly type: "no-op" }
+  | { readonly type: "error"; readonly code: "invalid_signature"; readonly retryable: false }
+  | OutcomeResult<Outcomes[number]>;
+
+export function defineWorkflowTrigger<
+  const Config extends WorkflowObjectSchema,
+  const Outcomes extends readonly [WorkflowTriggerOutcome, ...WorkflowTriggerOutcome[]],
+>(definition: WorkflowTriggerDefinition<Config, Outcomes>): WorkflowTriggerDefinition<Config, Outcomes>;
+
+export function defineWorkflowTriggerActivate<Config extends WorkflowObjectSchema>(
+  trigger: WorkflowTriggerDefinition<Config>,
+  handler: (params: Readonly<{
+    config: WorkflowSchemaValue<Config>;
+    activationId: string;
+    triggerCallbackUrl: string;
+  }>) => Promise<Readonly<{ subscriptionRef: string | null }>>,
+): typeof handler;
+
+export function defineWorkflowTriggerOnEvent<
+  Config extends WorkflowObjectSchema,
+  Outcomes extends readonly WorkflowTriggerOutcome[],
+>(
+  trigger: WorkflowTriggerDefinition<Config, Outcomes>,
+  handler: (params: Readonly<{
+    config: WorkflowSchemaValue<Config>;
+    body: string;
+    headers: Readonly<Record<string, string>>;
+  }>) => Promise<WorkflowTriggerEventResult<Outcomes>>,
+): typeof handler;
+
+export function defineWorkflowTriggerDeactivate(
+  trigger: WorkflowTriggerDefinition,
+  handler: (params: Readonly<{
+    activationId: string;
+    subscriptionRef: string | null;
+  }>) => Promise<void>,
+): typeof handler;

package/src/server/triggers/index.js

@@ -0,0 +1,27 @@
+const TRIGGER_MARKER = Symbol.for("zhike.workflow-trigger.v1");
+
+export function defineWorkflowTrigger(definition) {
+  if (!definition || typeof definition !== "object" || Array.isArray(definition)) {
+    throw new TypeError("workflow_trigger_definition_invalid");
+  }
+  return Object.freeze({ ...definition, [TRIGGER_MARKER]: true });
+}
+
+function bindTriggerHandler(trigger, handler, kind) {
+  if (!trigger?.[TRIGGER_MARKER] || typeof handler !== "function") {
+    throw new TypeError(`workflow_trigger_${kind}_invalid`);
+  }
+  return handler;
+}
+
+export function defineWorkflowTriggerActivate(trigger, handler) {
+  return bindTriggerHandler(trigger, handler, "activate");
+}
+
+export function defineWorkflowTriggerOnEvent(trigger, handler) {
+  return bindTriggerHandler(trigger, handler, "on_event");
+}
+
+export function defineWorkflowTriggerDeactivate(trigger, handler) {
+  return bindTriggerHandler(trigger, handler, "deactivate");
+}

package/src/server/workflow-blocks/index.d.ts

@@ -0,0 +1,72 @@
+import type {
+  WorkflowObjectSchema,
+  WorkflowSchemaValue,
+  WorkflowStepDefinition,
+  WorkflowStepOutcome,
+  WorkflowStepResult,
+} from "../steps/index.js";
+import type {
+  WorkflowTriggerDefinition,
+  WorkflowTriggerEventResult,
+  WorkflowTriggerOutcome,
+} from "../triggers/index.js";
+
+export type WorkflowStepBlockDefinition<
+  Config extends WorkflowObjectSchema = WorkflowObjectSchema,
+  Outcomes extends readonly WorkflowStepOutcome[] = readonly WorkflowStepOutcome[],
+> = WorkflowStepDefinition<Config, Outcomes> & { readonly type: "step" };
+
+export type WorkflowTriggerBlockDefinition<
+  Config extends WorkflowObjectSchema = WorkflowObjectSchema,
+  Outcomes extends readonly WorkflowTriggerOutcome[] = readonly WorkflowTriggerOutcome[],
+> = WorkflowTriggerDefinition<Config, Outcomes> & { readonly type: "trigger" };
+
+export type WorkflowBlockDefinition = WorkflowStepBlockDefinition | WorkflowTriggerBlockDefinition;
+
+export function defineWorkflowBlock<
+  const Config extends WorkflowObjectSchema,
+  const Outcomes extends readonly [WorkflowStepOutcome, ...WorkflowStepOutcome[]],
+>(definition: WorkflowStepBlockDefinition<Config, Outcomes>): WorkflowStepBlockDefinition<Config, Outcomes>;
+
+export function defineWorkflowBlock<
+  const Config extends WorkflowObjectSchema,
+  const Outcomes extends readonly [WorkflowTriggerOutcome, ...WorkflowTriggerOutcome[]],
+>(definition: WorkflowTriggerBlockDefinition<Config, Outcomes>): WorkflowTriggerBlockDefinition<Config, Outcomes>;
+
+export function defineWorkflowBlockExecute<
+  Config extends WorkflowObjectSchema,
+  Outcomes extends readonly WorkflowStepOutcome[],
+>(
+  block: WorkflowStepBlockDefinition<Config, Outcomes>,
+  execute: (params: Readonly<{ config: WorkflowSchemaValue<Config> }>) =>
+    WorkflowStepResult<Outcomes> | Promise<WorkflowStepResult<Outcomes>>,
+): typeof execute;
+
+export function defineWorkflowBlockActivate<Config extends WorkflowObjectSchema>(
+  block: WorkflowTriggerBlockDefinition<Config>,
+  handler: (params: Readonly<{
+    config: WorkflowSchemaValue<Config>;
+    activationId: string;
+    triggerCallbackUrl: string;
+  }>) => Promise<Readonly<{ subscriptionRef: string | null }>>,
+): typeof handler;
+
+export function defineWorkflowBlockTrigger<
+  Config extends WorkflowObjectSchema,
+  Outcomes extends readonly WorkflowTriggerOutcome[],
+>(
+  block: WorkflowTriggerBlockDefinition<Config, Outcomes>,
+  handler: (params: Readonly<{
+    config: WorkflowSchemaValue<Config>;
+    body: string;
+    headers: Readonly<Record<string, string>>;
+  }>) => Promise<WorkflowTriggerEventResult<Outcomes>>,
+): typeof handler;
+
+export function defineWorkflowBlockDeactivate(
+  block: WorkflowTriggerBlockDefinition,
+  handler: (params: Readonly<{
+    activationId: string;
+    subscriptionRef: string | null;
+  }>) => Promise<void>,
+): typeof handler;

package/src/server/workflow-blocks/index.js

@@ -0,0 +1,32 @@
+const WORKFLOW_BLOCK_MARKER = Symbol.for("zhike.workflow-block.v1");
+
+export function defineWorkflowBlock(definition) {
+  if (!definition || typeof definition !== "object" || Array.isArray(definition) ||
+    !["step", "trigger"].includes(definition.type)) {
+    throw new TypeError("workflow_block_definition_invalid");
+  }
+  return Object.freeze({ ...definition, [WORKFLOW_BLOCK_MARKER]: true });
+}
+
+function bindWorkflowBlockHandler(block, handler, type, kind) {
+  if (!block?.[WORKFLOW_BLOCK_MARKER] || block.type !== type || typeof handler !== "function") {
+    throw new TypeError(`workflow_block_${kind}_invalid`);
+  }
+  return handler;
+}
+
+export function defineWorkflowBlockExecute(block, handler) {
+  return bindWorkflowBlockHandler(block, handler, "step", "execute");
+}
+
+export function defineWorkflowBlockActivate(block, handler) {
+  return bindWorkflowBlockHandler(block, handler, "trigger", "activate");
+}
+
+export function defineWorkflowBlockTrigger(block, handler) {
+  return bindWorkflowBlockHandler(block, handler, "trigger", "trigger");
+}
+
+export function defineWorkflowBlockDeactivate(block, handler) {
+  return bindWorkflowBlockHandler(block, handler, "trigger", "deactivate");
+}

package/src/toolchain/allowed-packages.json

@@ -0,0 +1,7 @@
+{
+  "@77-zhike/qiqi-openapi": {
+    "versions": ["0.1.0"],
+    "targets": ["server"],
+    "subpaths": ["."]
+  }
+}

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;
+}