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

package/src/forms/values.js

@@ -0,0 +1,38 @@
+/** 平台值格式，不包含业务字段规则或缺省时区。 */
+export function isPlainDate(value) {
+  if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value)) return false;
+  const [year, month, day] = value.split('-').map(Number);
+  const date = new Date(0);
+  date.setUTCFullYear(year, month - 1, day);
+  return year > 0 && date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day;
+}
+export function isDateTime(value) {
+  if (typeof value !== 'string') return false;
+  const match = /^(\d{4}-\d{2}-\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,3}))?)?(Z|[+-]\d{2}:\d{2})$/.exec(value);
+  return Boolean(match && isPlainDate(match[1]) && +match[2] < 24 && +match[3] < 60 && +(match[4] ?? 0) < 60 && Number.isFinite(Date.parse(value)));
+}
+export function parseNumberDraft(value) {
+  if (value === null || value === '') return { value: null };
+  if (typeof value === 'number') return Number.isFinite(value) ? { value } : { value: null, error: '请输入有效数字' };
+  if (typeof value !== 'string' || value.length > 512 || !/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/.test(value)) return { value: null, error: '请输入有效数字' };
+  const number = Number(value);
+  return Number.isFinite(number) ? { value: number } : { value: null, error: '请输入有效数字' };
+}
+const pad = value => String(value).padStart(2, '0');
+export function instantToLocal(value) {
+  if (!value) return '';
+  if (!isDateTime(value)) return value;
+  const date = new Date(value);
+  return `${String(date.getFullYear()).padStart(4, '0')}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}T${pad(date.getHours())}:${pad(date.getMinutes())}`;
+}
+export function localToInstant(value) {
+  if (!value) return { value: null };
+  const match = /^(\d{4}-\d{2}-\d{2})T(\d{2}):(\d{2})$/.exec(value);
+  if (!match || !isPlainDate(match[1]) || +match[2] > 23 || +match[3] > 59) return { value: null, error: '请输入有效日期时间' };
+  const wall = new Date(value);
+  const utc = new Date(value + ':00.000Z').getTime();
+  const offsets = new Set([-36, 0, 36].map(hours => new Date(wall.getTime() + hours * 3600000).getTimezoneOffset()));
+  const candidates = [...offsets].map(offset => new Date(utc + offset * 60000).toISOString()).filter(instant => instantToLocal(instant) === value);
+  if (candidates.length !== 1) return { value: null, error: '该本地时间不存在或有歧义，请选择其他时间' };
+  return { value: candidates[0] };
+}

package/src/index.d.ts

@@ -0,0 +1,13 @@
+/** App SDK 支持的严格 JSON 值。 */
+export type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+/** 当前 App Bundle 代码 Manifest schema。 */
+export const APP_MANIFEST_SCHEMA_VERSION: "zhike.app-manifest.v1";
+/** 当前 Host SDK ABI 版本。 */
+export const SDK_ABI_VERSION: "2";

package/src/index.js

@@ -0,0 +1,2 @@
+export const APP_MANIFEST_SCHEMA_VERSION = "zhike.app-manifest.v1";
+export const SDK_ABI_VERSION = "2";

package/src/jsx-dev-runtime.d.ts

@@ -0,0 +1,2 @@
+export { jsxDEV, Fragment } from "react/jsx-dev-runtime";
+export { JSX } from "./ui/jsx.generated.js";

package/src/jsx-dev-runtime.js

@@ -0,0 +1 @@
+export { jsxDEV, Fragment } from "react/jsx-dev-runtime";

package/src/jsx-runtime.d.ts

@@ -0,0 +1,2 @@
+export { jsx, jsxs, Fragment } from "react/jsx-runtime";
+export { JSX } from "./ui/jsx.generated.js";

package/src/jsx-runtime.js

@@ -0,0 +1 @@
+export { jsx, jsxs, Fragment } from "react/jsx-runtime";

package/src/project-binding.js

@@ -0,0 +1,84 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+import { normalizeOrigin } from "./config.js";
+import { ZhikeCliError } from "./errors.js";
+
+export const PROJECT_BINDING_PATH = ".zhike/project.json";
+const BINDING_KEYS = [
+  "appId",
+  "appSlug",
+  "organizationId",
+  "platformEnvironment",
+  "schemaVersion",
+];
+
+export function parseProjectBinding(value, expectedEnvironment = null) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw _bindingError();
+  }
+  const keys = Object.keys(value).sort();
+  if (
+    keys.length !== BINDING_KEYS.length ||
+    keys.some((key, index) => key !== BINDING_KEYS[index])
+  ) {
+    throw _bindingError();
+  }
+  const environment = normalizeOrigin(
+    value.platformEnvironment,
+    "platformEnvironment",
+  );
+  if (
+    value.schemaVersion !== 1 ||
+    !/^[0-9A-HJKMNP-TV-Z]{26}$/.test(value.appId) ||
+    !/^[0-9A-HJKMNP-TV-Z]{26}$/.test(value.organizationId) ||
+    !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value.appSlug) ||
+    environment !== value.platformEnvironment
+  ) {
+    throw _bindingError();
+  }
+  if (
+    expectedEnvironment &&
+    environment !== normalizeOrigin(expectedEnvironment, "Developer API URL")
+  ) {
+    throw new ZhikeCliError(
+      "zhike_project_environment_mismatch",
+      "当前项目绑定的 Developer 环境与 CLI 目标环境不一致",
+    );
+  }
+  return Object.freeze({ ...value });
+}
+
+export async function readProjectBinding(projectDirectory, expectedEnvironment) {
+  let content;
+  try {
+    content = await readFile(resolve(projectDirectory, PROJECT_BINDING_PATH), "utf8");
+  } catch (error) {
+    throw new ZhikeCliError(
+      "zhike_project_binding_missing",
+      `当前目录缺少 ${PROJECT_BINDING_PATH}`,
+      { cause: error },
+    );
+  }
+  try {
+    return parseProjectBinding(JSON.parse(content), expectedEnvironment);
+  } catch (error) {
+    if (error instanceof ZhikeCliError) {
+      throw error;
+    }
+    throw _bindingError(error);
+  }
+}
+
+export function serializeProjectBinding(binding) {
+  const validated = parseProjectBinding(binding);
+  return `${JSON.stringify(validated, null, 2)}\n`;
+}
+
+function _bindingError(cause) {
+  return new ZhikeCliError(
+    "zhike_project_binding_invalid",
+    `${PROJECT_BINDING_PATH} 不是受支持的严格 Project Binding`,
+    { cause },
+  );
+}

package/src/server/index.d.ts

@@ -0,0 +1,318 @@
+import type { JsonValue } from "../index.js";
+export { defineWorkflowStep, defineWorkflowStepExecute } from "./steps/index.js";
+export type { WorkflowObjectSchema, WorkflowScalarSchema, WorkflowStepDefinition, WorkflowStepOutcome, WorkflowStepResult, WorkflowSchemaValue } from "./steps/index.js";
+export { defineWorkflowTrigger, defineWorkflowTriggerActivate, defineWorkflowTriggerOnEvent, defineWorkflowTriggerDeactivate } from "./triggers/index.js";
+export type { WorkflowTriggerDefinition, WorkflowTriggerOutcome, WorkflowTriggerEventResult } from "./triggers/index.js";
+export {
+  defineWorkflowBlock,
+  defineWorkflowBlockExecute,
+  defineWorkflowBlockActivate,
+  defineWorkflowBlockTrigger,
+  defineWorkflowBlockDeactivate,
+} from "./workflow-blocks/index.js";
+export type {
+  WorkflowBlockDefinition,
+  WorkflowStepBlockDefinition,
+  WorkflowTriggerBlockDefinition,
+} from "./workflow-blocks/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[];
+}
+
+interface WorkspaceConnectionBase {
+  /** 当前 Workspace Connection 的稳定 ID。 */
+  id: string;
+  /** 当前 Connect/Reconnect generation 的非敏感稳定表示。 */
+  generation: string;
+  /** Secret 或当前 OAuth/OIDC access token，仅存在于本次服务端执行内存。 */
+  value: string;
+}
+
+/** 当前服务端执行可使用的 Workspace 外部系统连接。 */
+export type WorkspaceConnection = WorkspaceConnectionBase & (
+  | {
+    type: "secret";
+    protocol: "secret";
+  }
+  | {
+    type: "oauth2";
+    protocol: "oauth2";
+    /** OAuth 2.0 access token；等同 value。 */
+    accessToken: string;
+  }
+  | {
+    type: "oauth2";
+    protocol: "oidc";
+    /** OIDC access token；等同 value。 */
+    accessToken: string;
+    /** OIDC ID token；仅存在于当前服务端执行内存。 */
+    idToken: string;
+  }
+);
+
+/** 同步读取当前执行的连接快照；未连接或暂不可用时抛出安全错误，不在 getter 内刷新。 */
+export function getWorkspaceConnection(): Readonly<WorkspaceConnection>;
+
+/** 当前 Server Function 调用者在当前 Workspace 内的成员快照。 */
+export interface CurrentUser {
+  /** Workspace 成员 ID；不是平台全局 User ID。 */
+  workspaceMemberId: string;
+  /** 当前 Workspace 中的显示名称。 */
+  displayName: string;
+  /** 当前 Workspace 中的主邮箱。 */
+  primaryEmailAddress: string | null;
+  /** 当前平台用户头像；未绑定平台用户时为空。 */
+  avatarUrl: string | null;
+}
+
+/** 同步读取当前调用者；Lifecycle、Webhook 等无人触发入口会抛出 current_user_unavailable。 */
+export function getCurrentUser(): Readonly<CurrentUser>;
+
+/** 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;
+}