@deepexi/datasense-connector 3.0.1 → 3.1.0

package/src/define.ts

@@ -0,0 +1,267 @@
+/**
+ * 编写 API：每个能力目录的 `index.ts` 默认导出一个 `defineStream` / `definePush` / `defineOperation` 的结果，
+ * 根目录 `check.ts` 默认导出 `defineCheck` 的结果，数据流目录的 `suggest-columns.ts` 默认导出 `defineSuggestColumns` 的结果。
+ *
+ * 泛型参数 `D` 是按连接器描述生成的类型（`GeneratedDescriptor` 的形状），由 `ontos admin connector codegen` 生成到
+ * `.ontos/types.ts`：那个文件导出已绑定 `D` 的同名函数，作者从它导入，于是表名、列类型、配置项与操作契约都在本地类型检查里核对。
+ * 生成文件可以直接写出各项类型，也可以把描述写成 `as const` 字面量后用 `DescriptorTypes<typeof descriptor>` 推出。
+ *
+ * 运行时这些函数只做最基本的参数检查，返回冻结的普通对象（带 `__ontos` 标记与名字）；guest 运行时加载时按连接器描述核对
+ * 名字与实现是否一一对应。
+ */
+import type { SuggestedColumn } from './descriptor';
+import type {
+  CheckContext, CheckpointItem, LookupResult, OperationContext, OperationHandlers, PullContext, PushContext, PushHandler, PushRequest, RecordItem,
+  RemoveItem, StreamFunction, StreamInput, StreamItem,
+} from './types';
+
+// ---------------------------------------------------------------------------
+// 生成的类型形状
+
+/** 一张表的行类型：主键列必填，其余列可缺省或为 null；可扩展表另带 `[field: string]: unknown`。 */
+export type GeneratedRow = object;
+
+export interface GeneratedStream {
+  tables: { [table: string]: GeneratedRow };
+  /** 数据流参数的值类型（`input.streamConfig`）。 */
+  params: object;
+}
+
+export interface GeneratedPush {
+  tables: { [table: string]: GeneratedRow };
+}
+
+export interface GeneratedOperation {
+  input: object;
+  output: object;
+  idempotency: 'supported' | 'unsupported';
+}
+
+/**
+ * 按连接器描述生成的类型（`.ontos/types.ts` 里的 `D`）。各项请写成类型别名（`type X = { … }`），不要写成 `interface`：
+ * interface 没有隐式索引签名，赋不给这里的 `{ [name: string]: … }`。
+ */
+export interface GeneratedDescriptor {
+  /** 非 secret 配置项的值类型（`ctx.config`）；`optional: true` 的项是可选属性。 */
+  config: object;
+  /** secret 配置项名 → string（`ctx.secrets`，值是凭证句柄或 `exposeToScript` 的明文）。 */
+  secrets: object;
+  streams: { [name: string]: GeneratedStream };
+  /** 含可扩展表的数据流，`tables` 只含可扩展表；没有时为 `{}`（于是 `defineSuggestColumns` 无名可用）。 */
+  extensibleStreams: { [name: string]: GeneratedStream };
+  pushes: { [name: string]: GeneratedPush };
+  operations: { [name: string]: GeneratedOperation };
+}
+
+// ---------------------------------------------------------------------------
+// 带类型的 ctx
+
+type Simplify<T> = { [K in keyof T]: T[K] } & {};
+
+/** check、数据流、建议列共用的 ctx 底座：`config` / `secrets` 按描述定型。 */
+export type ConnectorContext<D extends GeneratedDescriptor> = Omit<CheckContext, 'config' | 'secrets'> & {
+  readonly config: Readonly<D['config']>;
+  readonly secrets: Readonly<D['secrets']>;
+};
+
+type StreamTables<D extends GeneratedDescriptor, N extends keyof D['streams']> = D['streams'][N]['tables'];
+type PushTables<D extends GeneratedDescriptor, N extends keyof D['pushes']> = D['pushes'][N]['tables'];
+
+export type StreamContext<D extends GeneratedDescriptor, N extends keyof D['streams'] & string> =
+  Omit<PullContext, 'config' | 'secrets' | 'record' | 'remove' | 'checkpoint'> & {
+    readonly config: Readonly<D['config']>;
+    readonly secrets: Readonly<D['secrets']>;
+    record<T extends keyof StreamTables<D, N> & string>(table: T, row: StreamTables<D, N>[T]): RecordItem;
+    remove<T extends keyof StreamTables<D, N> & string>(table: T, key: Partial<StreamTables<D, N>[T]>): RemoveItem;
+    checkpoint(state: unknown): CheckpointItem;
+  };
+
+export type StreamInputOf<D extends GeneratedDescriptor, N extends keyof D['streams'] & string> =
+  Omit<StreamInput, 'streamConfig'> & { streamConfig: Readonly<D['streams'][N]['params']> };
+
+export type StreamFn<D extends GeneratedDescriptor, N extends keyof D['streams'] & string> =
+  (ctx: StreamContext<D, N>, input: StreamInputOf<D, N>) => AsyncIterable<StreamItem>;
+
+export type PushContextOf<D extends GeneratedDescriptor, N extends keyof D['pushes'] & string> = Omit<PushContext, 'config' | 'record' | 'remove'> & {
+  readonly config: Readonly<D['config']>;
+  record<T extends keyof PushTables<D, N> & string>(table: T, row: PushTables<D, N>[T]): void;
+  remove<T extends keyof PushTables<D, N> & string>(table: T, key: Partial<PushTables<D, N>[T]>): void;
+};
+
+export interface PushImpl<D extends GeneratedDescriptor, N extends keyof D['pushes'] & string> {
+  verify?(ctx: PushContextOf<D, N>, req: PushRequest): void | Promise<void>;
+  map(ctx: PushContextOf<D, N>, req: PushRequest): void | Promise<void>;
+}
+
+export type OperationContextOf<D extends GeneratedDescriptor> = Omit<OperationContext, 'config' | 'secrets'> & {
+  readonly config: Readonly<D['config']>;
+  readonly secrets: Readonly<D['secrets']>;
+};
+
+type OperationInput<D extends GeneratedDescriptor, N extends keyof D['operations']> = D['operations'][N]['input'];
+type OperationOutput<D extends GeneratedDescriptor, N extends keyof D['operations']> = D['operations'][N]['output'];
+
+type LookupFn<D extends GeneratedDescriptor, N extends keyof D['operations'] & string> = (
+  ctx: OperationContextOf<D>,
+  input: { idempotencyKey: string; params: OperationInput<D, N> },
+) => LookupResult<OperationOutput<D, N>> | Promise<LookupResult<OperationOutput<D, N>>>;
+
+/** 操作的实现：`idempotency: 'unsupported'` 时必须实现 `lookup`（结果不明时平台据此确认），`supported` 时可选。 */
+export type OperationImpl<D extends GeneratedDescriptor, N extends keyof D['operations'] & string> = {
+  run(ctx: OperationContextOf<D>, params: OperationInput<D, N>, meta: { idempotencyKey: string }): OperationOutput<D, N> | Promise<OperationOutput<D, N>>;
+  /** 纯函数（拿不到 `ctx`），推演与试运行时代替 `run` 返回模拟输出。 */
+  simulate?(params: OperationInput<D, N>): OperationOutput<D, N>;
+} & (D['operations'][N]['idempotency'] extends 'unsupported' ? { lookup: LookupFn<D, N> } : { lookup?: LookupFn<D, N> });
+
+export type CheckFn<D extends GeneratedDescriptor> = (ctx: ConnectorContext<D>) => void | Promise<void>;
+
+export type SuggestFn<D extends GeneratedDescriptor, N extends keyof D['extensibleStreams'] & string> = (
+  ctx: ConnectorContext<D>,
+  input: { table: keyof D['extensibleStreams'][N]['tables'] & string },
+) => SuggestedColumn[] | Promise<SuggestedColumn[]>;
+
+// ---------------------------------------------------------------------------
+// 运行时的实现对象
+
+export interface StreamImpl { readonly __ontos: 'stream'; readonly name: string; readonly run: StreamFunction }
+export interface PushImplBrand { readonly __ontos: 'push'; readonly name: string; readonly handler: PushHandler }
+export interface OperationImplBrand { readonly __ontos: 'operation'; readonly name: string; readonly handlers: OperationHandlers }
+export interface CheckImpl { readonly __ontos: 'check'; readonly run: (ctx: CheckContext) => void | Promise<void> }
+export type SuggestColumnsFunction = (ctx: CheckContext, input: { table: string }) => SuggestedColumn[] | Promise<SuggestedColumn[]>;
+export interface SuggestImpl { readonly __ontos: 'suggest'; readonly name: string; readonly run: SuggestColumnsFunction }
+
+function requireName(fn: string, name: unknown): string {
+  if (typeof name !== 'string' || name.length === 0) throw new TypeError(`${fn}() needs the capability name as its first argument`);
+  return name;
+}
+
+function requireFunction(fn: string, what: string, value: unknown): void {
+  if (typeof value !== 'function') throw new TypeError(`${fn}(): ${what} must be a function`);
+}
+
+/** 数据流实现：`streams/<名>/index.ts` 的默认导出；函数是 async generator，只 `yield` `ctx.record` / `ctx.remove` / `ctx.checkpoint` 的结果。 */
+export function defineStream<D extends GeneratedDescriptor, N extends keyof D['streams'] & string>(name: N, fn: StreamFn<D, N>): StreamImpl {
+  requireFunction('defineStream', 'the stream', fn);
+  return Object.freeze({ __ontos: 'stream', name: requireName('defineStream', name), run: fn as unknown as StreamFunction });
+}
+
+/** 推送实现：`pushes/<名>/index.ts` 的默认导出；先 `verify`（可选）再 `map`。 */
+export function definePush<D extends GeneratedDescriptor, N extends keyof D['pushes'] & string>(name: N, impl: PushImpl<D, N>): PushImplBrand {
+  const checkedName = requireName('definePush', name);
+  if (impl === null || typeof impl !== 'object') throw new TypeError('definePush(): the implementation must be an object with map()');
+  requireFunction('definePush', 'map', impl.map);
+  if (impl.verify !== undefined) requireFunction('definePush', 'verify', impl.verify);
+  return Object.freeze({ __ontos: 'push', name: checkedName, handler: impl as unknown as PushHandler });
+}
+
+/** 连接器操作实现：`operations/<名>/index.ts` 的默认导出。 */
+export function defineOperation<D extends GeneratedDescriptor, N extends keyof D['operations'] & string>(name: N, impl: OperationImpl<D, N>): OperationImplBrand {
+  const checkedName = requireName('defineOperation', name);
+  if (impl === null || typeof impl !== 'object') throw new TypeError('defineOperation(): the implementation must be an object with run()');
+  const handlers = impl as unknown as Partial<OperationHandlers>;
+  requireFunction('defineOperation', 'run', handlers.run);
+  if (handlers.lookup !== undefined) requireFunction('defineOperation', 'lookup', handlers.lookup);
+  if (handlers.simulate !== undefined) requireFunction('defineOperation', 'simulate', handlers.simulate);
+  return Object.freeze({ __ontos: 'operation', name: checkedName, handlers: impl as unknown as OperationHandlers });
+}
+
+/** 检查连通：根目录 `check.ts` 的默认导出（有配置项时必须实现）。 */
+export function defineCheck<D extends GeneratedDescriptor>(fn: CheckFn<D>): CheckImpl {
+  requireFunction('defineCheck', 'the check', fn);
+  return Object.freeze({ __ontos: 'check', run: fn as unknown as CheckImpl['run'] });
+}
+
+/** 建议列：`streams/<名>/suggest-columns.ts` 的默认导出，从外部系统读出可扩展表的可用字段。 */
+export function defineSuggestColumns<D extends GeneratedDescriptor, N extends keyof D['extensibleStreams'] & string>(name: N, fn: SuggestFn<D, N>): SuggestImpl {
+  requireFunction('defineSuggestColumns', 'the suggestion function', fn);
+  return Object.freeze({ __ontos: 'suggest', name: requireName('defineSuggestColumns', name), run: fn as unknown as SuggestColumnsFunction });
+}
+
+// ---------------------------------------------------------------------------
+// 从描述字面量推出生成类型
+
+type Prop<T, K extends PropertyKey> = T extends { readonly [P in K]: infer V } ? V : never;
+type Entries<T> = T extends object ? T : Record<never, never>;
+
+type ColumnValue<C> =
+  Prop<C, 'type'> extends 'string' | 'date' | 'instant' ? string
+    : Prop<C, 'type'> extends 'integer' ? number
+      : Prop<C, 'type'> extends 'decimal' ? number | string
+        : Prop<C, 'type'> extends 'boolean' ? boolean
+          : unknown;
+
+type PrimaryKeyOf<T> = Prop<T, 'primaryKey'> extends ReadonlyArray<infer K> ? K & string : never;
+
+type RowOf<T> = Simplify<
+  { [K in keyof Entries<Prop<T, 'columns'>> as K extends PrimaryKeyOf<T> ? K : never]: ColumnValue<Entries<Prop<T, 'columns'>>[K]> }
+  & { [K in keyof Entries<Prop<T, 'columns'>> as K extends PrimaryKeyOf<T> ? never : K]?: ColumnValue<Entries<Prop<T, 'columns'>>[K]> | null }
+  & (Prop<T, 'extensible'> extends true ? { [field: string]: unknown } : unknown)
+>;
+
+type ConfigValue<F> =
+  Prop<F, 'type'> extends 'string' | 'url' ? string
+    : Prop<F, 'type'> extends 'integer' ? number
+      : Prop<F, 'type'> extends 'decimal' ? number | string
+        : Prop<F, 'type'> extends 'boolean' ? boolean
+          : Prop<F, 'type'> extends 'enum' ? (Prop<F, 'values'> extends ReadonlyArray<infer V> ? V : string)
+            : unknown;
+
+type IsSecret<F> = Prop<F, 'type'> extends 'secret' ? true : false;
+type IsOptional<F> = Prop<F, 'optional'> extends true ? true : false;
+
+type ConfigValues<C> = Simplify<
+  { [K in keyof Entries<C> as IsSecret<Entries<C>[K]> extends true ? never : IsOptional<Entries<C>[K]> extends true ? never : K]: ConfigValue<Entries<C>[K]> }
+  & { [K in keyof Entries<C> as IsSecret<Entries<C>[K]> extends true ? never : IsOptional<Entries<C>[K]> extends true ? K : never]?: ConfigValue<Entries<C>[K]> }
+>;
+
+type SecretValues<C> = Simplify<
+  { [K in keyof Entries<C> as IsSecret<Entries<C>[K]> extends true ? (IsOptional<Entries<C>[K]> extends true ? never : K) : never]: string }
+  & { [K in keyof Entries<C> as IsSecret<Entries<C>[K]> extends true ? (IsOptional<Entries<C>[K]> extends true ? K : never) : never]?: string }
+>;
+
+type FieldValue<F> =
+  Prop<F, 'type'> extends 'object' ? FieldValues<Prop<F, 'fields'>>
+    : Prop<F, 'type'> extends 'array' ? Array<FieldValue<Prop<F, 'item'>>>
+      : ColumnValue<F>;
+
+type FieldValues<Fs> = Simplify<
+  { [K in keyof Entries<Fs> as IsOptional<Entries<Fs>[K]> extends true ? never : K]: FieldValue<Entries<Fs>[K]> }
+  & { [K in keyof Entries<Fs> as IsOptional<Entries<Fs>[K]> extends true ? K : never]?: FieldValue<Entries<Fs>[K]> | null }
+>;
+
+type TableRows<Tables> = { [T in keyof Entries<Tables>]: RowOf<Entries<Tables>[T]> };
+type ExtensibleRows<Tables> = { [T in keyof Entries<Tables> as Prop<Entries<Tables>[T], 'extensible'> extends true ? T : never]: RowOf<Entries<Tables>[T]> };
+type HasExtensible<Tables> = keyof ExtensibleRows<Tables> extends never ? false : true;
+
+/** 描述字面量的最小形状（只读数组也可以，便于 `as const`）。 */
+export interface DescriptorLiteral {
+  readonly config: object;
+  readonly streams: object;
+  readonly pushes: object;
+  readonly operations: object;
+}
+
+/**
+ * 从描述字面量（`as const`）推出 `GeneratedDescriptor`：
+ * 列 string / date / instant → string，integer → number，decimal → number | string，boolean → boolean，json → unknown；
+ * 配置项 url → string，enum → 取值的联合；操作字段 object / array 递归展开；`optional: true` 的项为可选属性。
+ */
+export type DescriptorTypes<C extends DescriptorLiteral> = {
+  config: ConfigValues<C['config']>;
+  secrets: SecretValues<C['config']>;
+  streams: { [N in keyof Entries<C['streams']>]: { tables: TableRows<Prop<Entries<C['streams']>[N], 'tables'>>; params: ConfigValues<Prop<Entries<C['streams']>[N], 'params'>> } };
+  extensibleStreams: {
+    [N in keyof Entries<C['streams']> as HasExtensible<Prop<Entries<C['streams']>[N], 'tables'>> extends true ? N : never]: {
+      tables: ExtensibleRows<Prop<Entries<C['streams']>[N], 'tables'>>;
+      params: ConfigValues<Prop<Entries<C['streams']>[N], 'params'>>;
+    };
+  };
+  pushes: { [N in keyof Entries<C['pushes']>]: { tables: TableRows<Prop<Entries<C['pushes']>[N], 'tables'>> } };
+  operations: {
+    [N in keyof Entries<C['operations']>]: {
+      input: FieldValues<Prop<Entries<C['operations']>[N], 'input'>>;
+      output: FieldValues<Prop<Entries<C['operations']>[N], 'output'>>;
+      idempotency: Prop<Entries<C['operations']>[N], 'idempotency'> extends 'unsupported' ? 'unsupported' : 'supported';
+    };
+  };
+};

package/src/descriptor.ts

@@ -0,0 +1,116 @@
+/**
+ * 连接器描述（JSON 形式）。
+ *
+ * 源码包里按能力分目录的 YAML（`ontos-connector.yaml`、`streams/<名>/stream.yaml`…）由平台（shared）解析、校验后规整成这份 JSON：
+ * 列的简写已展开，缺省值已补齐。SDK 不解析 YAML，只认这份 JSON：运行时取打包产物里嵌入的 `descriptor`，本地取 `.ontos/descriptor.json`。
+ * shared 有一份同形的定义，两者可以互相赋值。
+ */
+
+/** 多语言文字：纯字符串对所有语言相同；语言表显示时取界面语言 → `en-US` → 第一项。 */
+export type LocalizedText = string | Partial<Record<'zh-CN' | 'en-US', string>>;
+
+export type ColumnType = 'string' | 'integer' | 'decimal' | 'boolean' | 'date' | 'instant' | 'json';
+
+export interface ColumnDescriptor {
+  type: ColumnType;
+  /** 只有 `decimal` 有。 */
+  precision?: number;
+  scale?: number;
+  title: LocalizedText;
+  description: LocalizedText | null;
+}
+
+export interface TableDescriptor {
+  title: LocalizedText;
+  description: LocalizedText;
+  primaryKey: string[];
+  /** 可扩展：建连接时可以为它加扩展列，记录里的额外字段不算未声明字段。 */
+  extensible: boolean;
+  columns: Record<string, ColumnDescriptor>;
+  retention: { column: string; days: number } | null;
+  purgeColumns: { tenant?: string; user?: string } | null;
+  indexes: string[][];
+}
+
+/** 配置项（连接配置与数据流参数）。`secret` 只出现在连接配置里，值走 Secret 引用。 */
+export interface ConfigField {
+  type: 'string' | 'url' | 'integer' | 'decimal' | 'boolean' | 'secret' | 'enum';
+  title: LocalizedText;
+  description: LocalizedText;
+  placeholder: LocalizedText | null;
+  optional: boolean;
+  default?: string | number | boolean;
+  /** 只有 `enum` 有。 */
+  values?: string[];
+  /** 只有 `secret` 有：脚本可取明文（审阅标记，不是安全边界）。 */
+  exposeToScript?: boolean;
+}
+
+/** 连接器操作的入参与输出字段。 */
+export interface ValueField {
+  type: ColumnType | 'object' | 'array';
+  title: LocalizedText;
+  description: LocalizedText;
+  optional: boolean;
+  precision?: number;
+  scale?: number;
+  /** 只有 `object` 有。 */
+  fields?: Record<string, ValueField>;
+  /** 只有 `array` 有。 */
+  item?: ValueField;
+}
+
+export interface StreamDescriptor {
+  title: LocalizedText;
+  description: LocalizedText;
+  syncModes: Array<'full' | 'incremental'>;
+  snapshot: 'complete' | 'partial';
+  params: Record<string, ConfigField>;
+  tables: Record<string, TableDescriptor>;
+  /** 数据流目录里有 `suggest-columns.ts`。 */
+  suggestColumns: boolean;
+}
+
+export interface PushDescriptor {
+  title: LocalizedText;
+  description: LocalizedText;
+  tables: Record<string, TableDescriptor>;
+}
+
+export interface OperationDescriptor {
+  title: LocalizedText;
+  description: LocalizedText;
+  effect: 'create' | 'update' | 'delete';
+  risk: 'low' | 'medium' | 'high' | 'critical';
+  idempotency: 'supported' | 'unsupported';
+  input: Record<string, ValueField>;
+  output: Record<string, ValueField>;
+}
+
+export interface ConnectorDescriptor {
+  name: string;
+  version: string;
+  title: LocalizedText;
+  description: LocalizedText;
+  icon: 'icon.svg' | 'icon.png' | null;
+  config: Record<string, ConfigField>;
+  /** 额外的固定出站主机（精确主机名或 `*.后缀`）；`url` 配置项的主机自动加入白名单。 */
+  hosts: string[];
+  db: { engine: 'postgresql' } | null;
+  rateLimit: { perSecond: number; concurrency: number } | null;
+  /** 根目录有 `check.ts`。 */
+  check: boolean;
+  streams: Record<string, StreamDescriptor>;
+  pushes: Record<string, PushDescriptor>;
+  operations: Record<string, OperationDescriptor>;
+}
+
+/** `suggestColumns` 给出的一条建议列；文字只用单语字符串（由使用者选定后成为扩展列）。 */
+export interface SuggestedColumn {
+  name: string;
+  type: ColumnType;
+  precision?: number;
+  scale?: number;
+  title: string;
+  description?: string;
+}

package/src/errors.ts

@@ -0,0 +1,105 @@
+/** 连接器抛给平台的错误；`code` 稳定，平台据此决定拒收、失败或重试。 */
+export class ConnectorError extends Error {
+  readonly code: string;
+
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = 'ConnectorError';
+    this.code = code;
+  }
+}
+
+/** 凭证失效：停止运行，连接标为凭证失效。 */
+class AuthError extends ConnectorError {
+  constructor(message: string) {
+    super('AUTH_ERROR', message);
+    this.name = 'AuthError';
+  }
+}
+
+/** 被来源限流：等 `retryAfterMs` 后重试当前请求。 */
+class RateLimited extends ConnectorError {
+  readonly retryAfterMs: number;
+
+  constructor(retryAfterMs: number, message?: string) {
+    super('RATE_LIMITED', message ?? `rate limited, retry after ${retryAfterMs} ms`);
+    this.name = 'RateLimited';
+    this.retryAfterMs = retryAfterMs;
+  }
+}
+
+/** 瞬时错误：指数退避重试当前请求，超过次数后运行失败，下次从断点续跑。 */
+class TransientError extends ConnectorError {
+  constructor(message: string) {
+    super('TRANSIENT_ERROR', message);
+    this.name = 'TransientError';
+  }
+}
+
+class SchemaError extends ConnectorError {
+  constructor(message: string) {
+    super('SCHEMA_ERROR', message);
+    this.name = 'SchemaError';
+  }
+}
+
+class FatalError extends ConnectorError {
+  constructor(message: string) {
+    super('FATAL_ERROR', message);
+    this.name = 'FatalError';
+  }
+}
+
+class RejectedPayload extends ConnectorError {
+  constructor(message: string) {
+    super('REJECTED_PAYLOAD', message);
+    this.name = 'RejectedPayload';
+  }
+}
+
+/** 连接器操作：外部系统明确拒绝（如库存不足）。平台不重试；`details.code` 是外部系统的业务码。 */
+class RejectedError extends ConnectorError {
+  readonly details: { code?: string } | undefined;
+
+  constructor(message: string, details?: { code?: string }) {
+    super('REJECTED', message);
+    this.name = 'RejectedError';
+    this.details = details;
+  }
+}
+
+/** 连接器操作：不知道外部系统是否已经执行（如请求发出后连接断开）。平台不重发，转入查询确认。 */
+class IndeterminateError extends ConnectorError {
+  constructor(message: string) {
+    super('INDETERMINATE', message);
+    this.name = 'IndeterminateError';
+  }
+}
+
+/** 保留名字但尚未开放的能力（如 `ctx.files`）。 */
+class NotAvailable extends ConnectorError {
+  constructor(feature: string) {
+    super('NOT_AVAILABLE', `${feature} is not available yet`);
+    this.name = 'NotAvailable';
+  }
+}
+
+export interface RateLimitedError extends ConnectorError {
+  readonly retryAfterMs: number;
+}
+
+export interface RejectedOperationError extends ConnectorError {
+  readonly details: { code?: string } | undefined;
+}
+
+export const errors: {
+  AuthError: new (message: string) => ConnectorError;
+  RateLimited: new (retryAfterMs: number, message?: string) => RateLimitedError;
+  TransientError: new (message: string) => ConnectorError;
+  SchemaError: new (message: string) => ConnectorError;
+  FatalError: new (message: string) => ConnectorError;
+  RejectedPayload: new (message: string) => ConnectorError;
+  NotAvailable: new (feature: string) => ConnectorError;
+  RejectedError: new (message: string, details?: { code?: string }) => RejectedOperationError;
+  IndeterminateError: new (message: string) => ConnectorError;
+} = Object.freeze({ AuthError, RateLimited, TransientError, SchemaError, FatalError, RejectedPayload, NotAvailable, RejectedError, IndeterminateError });

package/src/index.ts

@@ -0,0 +1,108 @@
+export type {
+  ArrayType,
+  CheckContext,
+  CheckpointItem,
+  ConnectorCache,
+  ConnectorCrypto,
+  ConnectorDb,
+  ConnectorLog,
+  ConnectorOperationEffect,
+  ConnectorOperationRisk,
+  ConnectorRateLimit,
+  ConnectorSignal,
+  ConnectorTime,
+  CursorPaginateOptions,
+  DigestEncoding,
+  HashAlgorithm,
+  HmacAlgorithm,
+  HttpAuth,
+  HttpClient,
+  HttpMethod,
+  HttpOptions,
+  HttpResponse,
+  KeysetPaginateOptions,
+  LinkPaginateOptions,
+  LookupResult,
+  ObjectType,
+  OffsetPaginateOptions,
+  OperationContext,
+  OperationHandlers,
+  Page,
+  PagePaginateOptions,
+  Paginate,
+  PullContext,
+  PushContext,
+  PushHandler,
+  PushRequest,
+  RecordItem,
+  RemoveItem,
+  ScalarKind,
+  ScalarType,
+  SdkType,
+  SecretType,
+  SignAlgorithm,
+  StreamFunction,
+  StreamInput,
+  StreamItem,
+  SyncMode,
+  TableDeclaration,
+} from './types';
+export type {
+  ColumnDescriptor,
+  ColumnType,
+  ConfigField,
+  ConnectorDescriptor,
+  LocalizedText,
+  OperationDescriptor,
+  PushDescriptor,
+  StreamDescriptor,
+  SuggestedColumn,
+  TableDescriptor,
+  ValueField,
+} from './descriptor';
+export type {
+  CheckFn,
+  CheckImpl,
+  ConnectorContext,
+  DescriptorLiteral,
+  DescriptorTypes,
+  GeneratedDescriptor,
+  GeneratedOperation,
+  GeneratedPush,
+  GeneratedRow,
+  GeneratedStream,
+  OperationContextOf,
+  OperationImpl,
+  OperationImplBrand,
+  PushContextOf,
+  PushImpl,
+  PushImplBrand,
+  StreamContext,
+  StreamFn,
+  StreamImpl,
+  StreamInputOf,
+  SuggestColumnsFunction,
+  SuggestFn,
+  SuggestImpl,
+} from './define';
+export { defineCheck, defineOperation, definePush, defineStream, defineSuggestColumns } from './define';
+export type { RateLimitedError, RejectedOperationError } from './errors';
+export { ConnectorError, errors } from './errors';
+export type { DeclarationIssue } from './validate';
+export {
+  DEFAULT_PUSH_NAME,
+  OPERATION_NAME_PATTERN,
+  PRESENTATION_LIMITS,
+  RESERVED_PUSH_NAMES,
+  SDK_NAME_PATTERN,
+  SUGGESTED_COLUMNS_MAX,
+  validateConfig,
+  validateOperationValue,
+  validateSuggestedColumns,
+} from './validate';
+
+/** SDK 版本，等于本包 `package.json` 的 `version`；meta 打包校验 `dependencies` 范围与 runner 都用它。 */
+export const SDK_VERSION: string = '3.1.0';
+
+/** runner 支持的 SDK 主版本集合；连接器 `dependencies` 里 SDK 的下限主版本必须在其中。 */
+export const SUPPORTED_SDK_MAJORS: readonly number[] = [3];

package/src/internal/location.ts

@@ -0,0 +1,23 @@
+/**
+ * 包内文件定位（宿主侧，不进 guest）。同一份源码有三种运行形态：
+ * - 源码（Bun 直接执行 `src/*.ts`，工作区里的 runner、connector 与测试）：`PACKAGE_ROOT` 是 `src/`；
+ * - dist 的 ESM（`dist/**\/*.js`，tsc 编译）：`PACKAGE_ROOT` 是 `dist/`；
+ * - dist 的 CJS（`dist/cjs/*.cjs`，构建脚本打包时用 `__dirname` 版本替换本模块）：`PACKAGE_ROOT` 同样是 `dist/`。
+ *
+ * 本文件只用 `import.meta.url`，不用 Bun 专有的 `import.meta.dir`，Node 下同样可用。
+ */
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const self = fileURLToPath(import.meta.url);
+
+/** 当前是否直接从源码（`.ts`）执行。 */
+export const IS_SOURCE: boolean = self.endsWith('.ts');
+
+/** `src/`（源码）或 `dist/`（构建产物）。 */
+export const PACKAGE_ROOT: string = path.resolve(path.dirname(self), '..');
+
+/** 源码与 dist 下同一模块的路径：`relative` 不带扩展名，源码取 `.ts`，dist 取 `.js`。 */
+export function moduleFile(relative: string): string {
+  return path.join(PACKAGE_ROOT, `${relative}${IS_SOURCE ? '.ts' : '.js'}`);
+}