@lark-base-open/base-database-cli 1.3.9 → 1.4.3

package/templates/database-starter/page/src/lib/database-runtime.ts

@@ -4,6 +4,7 @@ import {
   getSiteAIFunctionTask as getRuntimeAIFunctionTask,
   invokeSiteAIFunctionStream as invokeRuntimeAIFunctionStream,
   invokeHttp,
+  openLink,
   siteRuntime,
   fetch as siteRuntimeFetch,
   type CallSiteAIFunctionParams as RuntimeCallSiteAIFunctionParams,
@@ -59,6 +60,8 @@ export interface DatabaseAttachmentRef {
   fieldId: string
   recordId: string
   fileToken: string
+  name?: string
+  mimeType?: string
 }
 
 /** 产物环境沿用 site.v1 协议的规范类型，避免两侧各自声明后漂移。 */
@@ -87,7 +90,10 @@ export type SiteAIMessage =
     }
 
 type WithSiteAIMessages<T> = T extends unknown
-  ? Omit<T, 'messages'> & { messages?: SiteAIMessage[] }
+  ? Omit<T, 'messages' | 'variables' | 'params'> & {
+      messages?: SiteAIMessage[]
+      params?: Record<string, unknown>
+    }
   : never
 
 export type CallSiteAIFunctionParams =
@@ -95,8 +101,8 @@ export type CallSiteAIFunctionParams =
 
 export type InvokeSiteAIFunctionStreamParams = Omit<
   RuntimeInvokeSiteAIFunctionStreamParams,
-  'messages'
-> & { messages: SiteAIMessage[] }
+  'messages' | 'variables' | 'params'
+> & { messages: SiteAIMessage[]; params?: Record<string, unknown> }
 
 /** 单帧增量与可取消的流句柄。 */
 export type { SiteAIStreamDelta, SiteAIFunctionStreamHandle }
@@ -145,6 +151,8 @@ const FUNCTION_ID_PATTERN = /^[A-Za-z0-9_-]+$/
 const DATABASE_RUNTIME_GATEWAY_PREFIX = '/space/api/bitable/site/v1'
 const ATTACHMENT_DOWNLOAD_URL_PATH =
   '/space/api/box/file/temporary_download_url'
+const COVER_NOT_SUPPORTED = '90002005'
+const COVER_NOT_FOUND = '90002006'
 const PREVIEW_ENV: DatabaseEnv = 'preview'
 
 let databaseContextPromise: Promise<DatabaseContext> | null = null
@@ -402,7 +410,11 @@ export function hasRunnableMediaTask(
 export async function createSiteAIFunctionTask(
   params: CallSiteAIFunctionParams,
 ): Promise<SiteAIMediaTask> {
-  return normalizeSiteAIMediaTask(await createRuntimeAIFunctionTask(params))
+  return normalizeSiteAIMediaTask(
+    await createRuntimeAIFunctionTask(
+      params as unknown as RuntimeCallSiteAIFunctionParams,
+    ),
+  )
 }
 
 /** 轮询文生图或文生视频任务进度与最终资源。 */
@@ -577,6 +589,31 @@ function attachmentRequestError(operation: string, cause: unknown): Error {
   )
 }
 
+async function readSvgCoverError(
+  blob: Blob,
+  logId?: string,
+): Promise<Error | undefined> {
+  let body: unknown
+  try {
+    body = JSON.parse(await blob.text())
+  } catch {
+    return undefined
+  }
+  if (!isRecord(body) || String(body.code).trim() !== COVER_NOT_FOUND)
+    return undefined
+  return Object.assign(
+    new Error(
+      `File Type Not Support Covers (code ${COVER_NOT_SUPPORTED}${logId ? `, LogID ${logId}` : ''})`,
+    ),
+    {
+      code: COVER_NOT_SUPPORTED,
+      originalCode: COVER_NOT_FOUND,
+      cause: body,
+      logId,
+    },
+  )
+}
+
 /** 宿主用当前访问者身份同源取图，返回可创建本地 URL 的图片字节。
  * 调用方在替换或卸载时取消请求并释放自己创建的 Blob URL。
  */
@@ -609,23 +646,31 @@ export async function fetchAttachmentCover(
   }).catch((cause: unknown) => {
     throw attachmentRequestError('Attachment image request', cause)
   })
+  const logId = response.headers.get('x-tt-logid')?.trim() || undefined
+  const blob = await response.blob()
+  // Box 的缺封面响应可能是 HTTP 202，不能只依赖 response.ok。
+  const svg =
+    ref.name?.trim().toLowerCase().endsWith('.svg') ||
+    ref.mimeType?.split(';')[0]?.trim().toLowerCase() === 'image/svg+xml'
+  if (svg && !blob.type.startsWith('image/')) {
+    const error = await readSvgCoverError(blob, logId)
+    if (error) throw error
+  }
   if (!response.ok) {
-    const logId = response.headers.get('x-tt-logid')
     throw new Error(
       `Failed to load attachment image: HTTP ${response.status}${logId ? `, LogID ${logId}` : ''}`,
     )
   }
-  const blob = await response.blob()
   if (!blob.size || !blob.type.startsWith('image/')) {
     throw new Error('The host did not return a valid image')
   }
   return blob
 }
 
-/** 经父页面 bridge 取短时效自证链接；原文件由浏览器下载，不进入页面 JavaScript。
+/** 经父页面 bridge 取短时效自证链接；原文件不进入页面 JavaScript。
  * 下载链接不代表附件增删已完成，也不提供并发或重试保证。
  *
- * @returns 可直接交给 a.href 的下载链接。
+ * @returns 临时链接，供需要 URL 本身的能力使用。用户下载请调用 openAttachmentDownload。
  */
 export async function fetchAttachmentDownloadUrl(
   context: DatabaseContext,
@@ -697,6 +742,20 @@ export async function fetchAttachmentDownloadUrl(
   return url
 }
 
+/** 请求宿主打开附件原文件。浏览器是否完成落盘由浏览器决定，不能据此报告下载完成。
+ * 每次点击都重新获取临时 URL，避免缓存签名链接；不要在 iframe 内创建 a[download]。
+ */
+export async function openAttachmentDownload(
+  context: DatabaseContext,
+  ref: DatabaseAttachmentRef,
+): Promise<void> {
+  const url = await fetchAttachmentDownloadUrl(context, ref)
+  const result = await openLink(url)
+  if (!result.opened) {
+    throw new Error('The host did not open the attachment download link')
+  }
+}
+
 /** 构造运行态读取应用信息的统一网关地址。
  *
  * @param context 当前应用上下文。
@@ -736,7 +795,7 @@ export function buildDatabaseInvokeFunctionPath(
 
   const path =
     `${DATABASE_RUNTIME_GATEWAY_PREFIX}/${encodeURIComponent(context.token)}` +
-    `/invoke_function/${encodeURIComponent(functionId)}`
+    `/functions/${encodeURIComponent(functionId)}/invoke`
 
   return context.env === PREVIEW_ENV
     ? `${path}?env=${encodeURIComponent(PREVIEW_ENV)}`
@@ -750,7 +809,7 @@ export function buildDatabaseInvokeFunctionPath(
  * 4xx/5xx 直接抛错，业务码由调用方按 operation 契约校验一次顶层 code。
  *
  * @param functionId Base Database Function ID。
- * @param params 函数入参：Database Function 用数组，FaaS 用业务对象。
+ * @param params 函数入参：SQL / Mutation 用命名对象，FaaS 用业务对象。
  * @returns 统一包裹的函数响应。
  */
 export type DatabaseFunctionInvocation<Inputs extends object> = [
@@ -794,15 +853,20 @@ export async function invokeDatabaseFunction<Data = unknown>(
 /** 每组参数应用同一份已发布 Mutation 声明；总记录数最多 200。 */
 export async function invokeDatabaseMutationBatch<Data = unknown>(
   functionId: string,
-  parameterGroups: unknown[][],
+  parameterGroups: Record<string, unknown>[],
 ): Promise<DatabaseFunctionResponse<Data>> {
   if (
     !Array.isArray(parameterGroups) ||
     parameterGroups.length < 1 ||
     parameterGroups.length > 200 ||
-    parameterGroups.some((params) => !Array.isArray(params))
+    parameterGroups.some(
+      (params) =>
+        params === null || typeof params !== 'object' || Array.isArray(params),
+    )
   ) {
-    throw new TypeError('Mutation batch requires 1 to 200 parameter arrays')
+    throw new TypeError(
+      'Mutation batch requires 1 to 200 named parameter objects',
+    )
   }
   const context = await resolveDatabaseContext()
   if (!context.token) throw new Error('应用 token 未确定，无法调用 Mutation')

package/templates/database-starter/server-functions/scripts/run-tsc.mjs

@@ -1,4 +1,5 @@
 import { readdirSync, rmSync } from 'node:fs'
+import { createRequire } from 'node:module'
 import { join } from 'node:path'
 import { spawnSync } from 'node:child_process'
 
@@ -18,13 +19,13 @@ if (!hasTypeScriptSource('functions')) {
   process.exit(0)
 }
 
-const executable = process.platform === 'win32' ? 'tsc.cmd' : 'tsc'
+const tsc = createRequire(import.meta.url).resolve('typescript/bin/tsc')
 const args = ['-p', 'tsconfig.json']
 if (mode === 'check') {
   args.push('--noEmit')
 }
 
-const result = spawnSync(executable, args, { stdio: 'inherit' })
+const result = spawnSync(process.execPath, [tsc, ...args], { stdio: 'inherit' })
 if (result.error) {
   throw result.error
 }

package/templates/database-starter-v2/README.md

@@ -0,0 +1,25 @@
+# Base Database 应用
+
+基于飞书多维表格的业务应用。
+
+## Background
+
+workspace 工程结构。
+
+## Requested features
+
+页面启动与服务端问候示例。
+
+## Implemented capabilities
+
+页面展示应用标题，hello Function 接收姓名并返回问候文本。
+
+## Status and limitations
+
+模板使用已正式发布的 SDK；远端构建与业务系统仍需单独验收。
+
+## Local project
+
+workspace 使用唯一根 npm workspace（page、server）和根 package-lock.json，SDK 正式版本由 page、server 的 package.json 精确固定，需提供 codegen 入口；缺失时按 CLI 报错给出的安装命令执行，版本与新建工程模板一致；安装依赖后执行 contracts generate，再运行 check。
+
+安装后阅读 node_modules/@lark-base-open/base-database-app-sdk/docs/README.md。运行 contracts generate → check；本地 check 使用 CLI 内置平台构建器。云端根 npm ci 后直接调用平台构建器，Page 执行 npm run build --workspace page，不从工程脚本调用 CLI。classic 仅保留存量兼容。

package/templates/database-starter-v2/base-app.config.ts

@@ -0,0 +1,10 @@
+import { createElement } from 'react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import type { StartBaseAppOptions } from '@lark-base-open/base-database-app-sdk/page';
+import App from './page/src/App';
+const queryClient = new QueryClient();
+export default {
+  app: App,
+  providers: (children) =>
+    createElement(QueryClientProvider, { client: queryClient }, children),
+} satisfies StartBaseAppOptions;

package/templates/database-starter-v2/database-functions/README.md

@@ -0,0 +1 @@
+业务函数目录；格式与模板 1 相同。参阅 lark-base-database Skill。

package/templates/database-starter-v2/gitignore

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+.base-database-cli/
+.env
+.env.*
+*.tsbuildinfo

package/templates/database-starter-v2/mutations/README.md

@@ -0,0 +1 @@
+业务函数目录；格式与模板 1 相同。参阅 lark-base-database Skill。