@lark-base-open/base-database-app-sdk 0.0.0-stage → 0.0.1-alpha.1

package/examples/development-context.ts

@@ -0,0 +1,17 @@
+import type { SiteRuntimeContext } from "@lark-base-open/base-database-app-sdk/page";
+export function localAddress(context: SiteRuntimeContext): string | undefined {
+  const development = context.development;
+  if (!development) return undefined;
+  const env: "preview" = development.projectEnv;
+  const version: string | null = development.artifactVersion;
+  // @ts-expect-error 轻量上下文没有服务端会话 ID。
+  development.sessionId;
+  // @ts-expect-error 轻量上下文没有服务端租约。
+  development.expiresAt;
+  return `${development.localOrigin} (${env}, ${version ?? "local"})`;
+}
+
+import { siteRuntime } from "@lark-base-open/base-database-app-sdk/page";
+export async function readDevelopmentOrigin() {
+  return (await siteRuntime.getRuntimeContext()).development?.localOrigin;
+}

package/examples/http.ts

@@ -0,0 +1,12 @@
+import { invokeHttp, fetch as hostFetch } from '@lark-base-open/base-database-app-sdk/page';
+export async function loadUser(signal: AbortSignal) {
+  const response = await invokeHttp({ url: '/space/api/user', signal });
+  if (!response.ok) throw new Error(`HTTP ${response.status}`);
+  const data: unknown = await response.json();
+  return data;
+}
+export async function loadWithFetch() {
+  const response = await hostFetch('/space/api/user');
+  if (!response.ok) throw new Error(`HTTP ${response.status}`);
+  return response.json() as Promise<unknown>;
+}

package/examples/link.ts

@@ -0,0 +1,10 @@
+import { siteRuntime, hasCapability, openLink } from '@lark-base-open/base-database-app-sdk/page';
+import type { SiteRuntimeContext } from '@lark-base-open/base-database-app-sdk/page';
+export async function canOpenLink() {
+  const context: SiteRuntimeContext = await siteRuntime.getRuntimeContext();
+  return hasCapability(context, 'link.open');
+}
+// 在点击之前查询能力。用户点击时立即调用，避免因等待查询失去用户激活。
+export function onSupportedLinkClick(url: string) {
+  return openLink(url);
+}

package/examples/mock.ts

@@ -0,0 +1,8 @@
+import { createMockHost } from '@lark-base-open/base-database-app-sdk/testing';
+import { createSiteRuntimeClient } from '@lark-base-open/base-database-app-sdk/page';
+export async function testUser() {
+  const host = createMockHost({ capabilities: { 'function.invoke': { version: 1 } } });
+  const runtime = createSiteRuntimeClient(host.channel);
+  try { return await runtime.getCurrentUser(); }
+  finally { host.dispose(); }
+}

package/examples/msw.ts

@@ -0,0 +1,5 @@
+import { createHttpHandlers } from '@lark-base-open/base-database-app-sdk/testing';
+export const handlers = createHttpHandlers([
+  { method: 'post', url: 'https://service.example/items', status: 201, body: { id: 'item-1' } },
+]);
+// 交给 MSW setupServer(...handlers) 或 setupWorker(...handlers)。

package/examples/page.ts

@@ -0,0 +1,6 @@
+import { siteRuntime, installLinkGuard, classifyRuntimeError } from '@lark-base-open/base-database-app-sdk/page';
+export function mountPage() {
+  const cleanup = installLinkGuard({ onDiagnostic: diagnostic => console.warn(diagnostic) });
+  void siteRuntime.ready().catch(error => console.warn(classifyRuntimeError(error)));
+  return cleanup;
+}

package/examples/server.ts

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import {
+  defineFunction,
+  bindFunctionRuntime,
+} from "@lark-base-open/base-database-app-sdk/server";
+// 实际工程将 input/output 放独立 contract.ts，CLI 只提取 Schema 依赖图。
+const input = z.object({ title: z.string().min(1) });
+const ignored = z.object({
+  id: z.string(),
+  name: z.string(),
+  reason: z.string(),
+});
+const output = z.discriminatedUnion("status", [
+  z.object({
+    status: z.literal("success"),
+    appliedIds: z.array(z.string()),
+    notFoundIds: z.tuple([]),
+    ignoredFields: z.tuple([]),
+    attachments: z.json().optional(),
+    noop: z.boolean().optional(),
+  }),
+  z.object({
+    status: z.literal("partial"),
+    appliedIds: z.array(z.string()),
+    notFoundIds: z.array(z.string()),
+    ignoredFields: z.array(ignored),
+    attachments: z.json().optional(),
+  }),
+  z.object({
+    status: z.literal("failed"),
+    code: z.string(),
+    upstreamCode: z.number().optional(),
+    retryable: z.literal(false),
+    appliedIds: z.tuple([]),
+  }),
+  z.object({
+    status: z.literal("unknown"),
+    code: z.string(),
+    retryable: z.literal(false),
+    requestedIds: z.array(z.string()).optional(),
+    logid: z.string().optional(),
+  }),
+]);
+const handler = defineFunction({
+  input,
+  output,
+  handler: (params, ctx) =>
+    ctx.records.create(
+      { baseToken: "baseFromCatalog", tableId: "tblFromCatalog" },
+      [{ title: params.title }],
+    ),
+});
+// 此绑定入口由 CLI 生成；业务 handler 不选择区域、不持有身份凭据。
+export default bindFunctionRuntime(handler, {
+  platformEnv: "online",
+  brand: "feishu",
+});

package/examples/shared.ts

@@ -0,0 +1,10 @@
+import { classifyRuntimeError, type WriteResult } from '@lark-base-open/base-database-app-sdk/shared';
+export function writeMessage(result: WriteResult): string {
+  switch (result.status) {
+    case 'success': return `已写入 ${result.appliedIds.length} 条`;
+    case 'partial': return '部分完成，请检查缺失记录和忽略字段';
+    case 'failed': return '请求未发送，请修正输入或运行环境';
+    case 'unknown': return '结果待核对，请勿直接重试';
+  }
+}
+export const describeError = classifyRuntimeError;

package/examples/start-base-app.tsx

@@ -0,0 +1,8 @@
+import { startBaseApp } from '@lark-base-open/base-database-app-sdk/page';
+import '@lark-base-open/base-database-app-sdk/page/styles.css';
+function App() { return <main>订单工作台</main>; }
+export function mountApp() {
+  const app = startBaseApp({ app: App, locale: 'zh', theme: 'host' });
+  void app.ready.catch(() => console.warn('应用启动失败'));
+  return () => app.dispose(); // 卸载或 HMR 时调用。
+}

package/examples/upgrade.ts

@@ -0,0 +1,7 @@
+// 模板 1 可先迁移 helper 导入；切换启动入口与模板 2 是独立的手动步骤。
+import { installLinkGuard, siteRuntime, classifyRuntimeError } from '@lark-base-open/base-database-app-sdk/page';
+export function initializeRuntime() {
+  const uninstall = installLinkGuard();
+  void siteRuntime.ready().catch(error => console.warn(classifyRuntimeError(error)));
+  return uninstall;
+}

package/examples/upload.ts

@@ -0,0 +1,18 @@
+import { requireCapability, siteRuntime } from '@lark-base-open/base-database-app-sdk/page';
+export async function upload(baseToken: string, tableId: string, file: File) {
+  await requireCapability('attachment.upload');
+  let dimensions: { image_width: number; image_height: number } | undefined;
+  if (!file.type) throw new Error('无法识别文件类型');
+  if (file.type.startsWith('image/')) {
+    const url = URL.createObjectURL(file);
+    try {
+      const image = new Image(); image.src = url; await image.decode();
+      if (image.naturalWidth <= 0 || image.naturalHeight <= 0) throw new Error('无法读取图片尺寸');
+      dimensions = { image_width: image.naturalWidth, image_height: image.naturalHeight };
+    } finally { URL.revokeObjectURL(url); }
+  }
+  const result = await siteRuntime.uploadAttachment({ baseToken, tableId, file,
+    onProgress: ({ loaded, total }) => console.info(`${loaded}/${total}`) });
+  return { file_token: result.fileToken, ...dimensions };
+  // 下一步经业务 FaaS 挂载；上传成功不代表单元格写入成功。
+}

package/examples/vite.ts

@@ -0,0 +1,2 @@
+import { baseAppDevelopmentPairingPlugin } from '@lark-base-open/base-database-app-sdk/vite';
+export const plugins = [baseAppDevelopmentPairingPlugin()];

package/package.json

@@ -1,6 +1,121 @@
 {
   "name": "@lark-base-open/base-database-app-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1-alpha.1",
+  "description": "Base Database 页面与服务端 SDK、平台组件及测试工具",
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    "./page": {
+      "types": "./dist/page.d.ts",
+      "import": "./dist/page.js"
+    },
+    "./server": {
+      "import": {
+        "types": "./dist/server.d.ts",
+        "default": "./dist/server.js"
+      },
+      "require": {
+        "types": "./dist/server.d.cts",
+        "default": "./dist/server.cjs"
+      }
+    },
+    "./shared": {
+      "import": {
+        "types": "./dist/shared.d.ts",
+        "default": "./dist/shared.js"
+      },
+      "require": {
+        "types": "./dist/shared.d.cts",
+        "default": "./dist/shared.cjs"
+      }
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    },
+    "./components": {
+      "types": "./dist/components.d.ts",
+      "import": "./dist/components.js"
+    },
+    "./page/styles.css": "./dist/theme.css",
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "import": "./dist/vite.js"
+    },
+    "./development-pairing.json": "./development-pairing.json",
+    "./codegen": {
+      "import": {
+        "types": "./dist/codegen.d.ts",
+        "default": "./dist/codegen.js"
+      },
+      "require": {
+        "types": "./dist/codegen.d.cts",
+        "default": "./dist/codegen.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "examples",
+    "README.md",
+    "LICENSE",
+    "capabilities.json",
+    "development-pairing.json"
+  ],
+  "scripts": {
+    "build": "node scripts/sync-capabilities.mjs && tsup && tsup --config tsup.cjs.config.ts && cp src/page/theme.css dist/theme.css",
+    "test": "node scripts/sync-capabilities.mjs --check && npm run build && node --import tsx --test test/*.test.ts && npm run test:types && npm run test:components",
+    "test:types": "tsc -p tsconfig.examples.json && tsc -p tsconfig.server.json && tsc -p tsconfig.cjs.json",
+    "test:browser": "node test/browser/verify.mjs && node test/browser/ui-verify.mjs",
+    "test:components": "vitest run",
+    "docs:exports": "node scripts/doc-exports.mjs"
+  },
+  "dependencies": {
+    "@lark-base-open/base-site-channel": "0.1.6",
+    "@radix-ui/react-popover": "1.2.0",
+    "@standard-schema/spec": "1.0.0",
+    "cmdk": "1.1.1",
+    "json-schema-to-typescript": "16.0.0"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "5.104.1",
+    "msw": "2.11.6",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "peerDependenciesMeta": {
+    "msw": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@testing-library/react": "16.3.0",
+    "@types/node": "22.15.0",
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
+    "jsdom": "26.1.0",
+    "msw": "2.11.6",
+    "pngjs": "7.0.0",
+    "tsup": "6.7.0",
+    "tsx": "4.20.3",
+    "typescript": "5.8.3",
+    "vitest": "3.2.4",
+    "zod": "4.2.1"
+  },
+  "typesVersions": {
+    "*": {
+      "server": [
+        "dist/server.d.cts"
+      ],
+      "shared": [
+        "dist/shared.d.cts"
+      ],
+      "codegen": [
+        "dist/codegen.d.cts"
+      ]
+    }
+  }
+}