@deepexi/datasense-connector 3.0.1 → 3.1.0

package/test/build.test.ts

@@ -0,0 +1,159 @@
+/**
+ * 发布构建：dist 的清单与产物齐全；npm pack 后在 Node 下 ESM import 与 CJS require 都能加载；
+ * dist 与源码下的 `loadGuestRuntime()` 都返回能被 `createGuestSession` 启动的 guest 运行时。
+ */
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { existsSync } from 'node:fs';
+import { mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { createGuestSession, loadGuestRuntime } from '../src/runtime';
+import { descriptor, push, rawConnector } from './fixtures/descriptor';
+
+const PACKAGE_DIR = path.resolve(import.meta.dir, '..');
+const WORKSPACE = JSON.parse(await readFile(path.join(PACKAGE_DIR, 'package.json'), 'utf8')) as { name: string; version: string };
+
+let base = '';
+let out = '';
+
+async function run(command: string[], cwd: string): Promise<string> {
+  const child = Bun.spawn(command, { cwd, stdout: 'pipe', stderr: 'pipe' });
+  const [stdout, stderr, code] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]);
+  if (code !== 0) throw new Error(`${command.join(' ')} exited with ${code}\n${stdout}\n${stderr}`);
+  return stdout;
+}
+
+async function listFiles(dir: string): Promise<string[]> {
+  const files: string[] = [];
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) files.push(...await listFiles(full));
+    else files.push(path.relative(out, full));
+  }
+  return files;
+}
+
+/** 用 guest 会话启动一段 guest 运行时，跑一个 check 作业，返回结果消息。 */
+function bootCheck(guest: string): Promise<Record<string, unknown>> {
+  const desc = descriptor({ check: true, pushes: { default: push({}) } });
+  const code = rawConnector(desc, `check: defineCheck(() => {}), pushes: { default: definePush('default', { map() {} }) },`);
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error('guest did not answer')), 10_000);
+    const session = createGuestSession((json) => {
+      const message = JSON.parse(json) as { type: string; id?: number; method?: string };
+      if (message.type === 'call') {
+        session.handle(JSON.stringify({ type: 'reply', id: message.id, ok: true, value: null }));
+        return;
+      }
+      clearTimeout(timer);
+      resolve(message as Record<string, unknown>);
+    });
+    session.handle(JSON.stringify({
+      type: 'execute', guest, code, expect: { name: 'demo', version: '1.0.0' }, job: { kind: 'check', config: {}, secretFields: [] },
+    }));
+  });
+}
+
+beforeAll(async () => {
+  base = await mkdtemp(path.join(os.tmpdir(), 'sdk-build-'));
+  out = path.join(base, 'dist');
+  await run([process.execPath, 'scripts/build.ts', '--outdir', out], PACKAGE_DIR);
+}, 120_000);
+
+afterAll(async () => {
+  if (base) await rm(base, { recursive: true, force: true });
+});
+
+describe('build output', () => {
+  test('package.json is publishable and does not touch the workspace manifest', async () => {
+    const manifest = JSON.parse(await readFile(path.join(out, 'package.json'), 'utf8')) as Record<string, unknown>;
+    expect(manifest.name).toBe('@deepexi/datasense-connector');
+    expect(manifest.version).toBe(WORKSPACE.version);
+    expect(manifest.dependencies).toEqual({});
+    expect(manifest.peerDependencies).toEqual({ postgres: expect.any(String) });
+    expect(manifest.peerDependenciesMeta).toEqual({ postgres: { optional: true } });
+    const exportsMap = manifest.exports as Record<string, Record<string, string> | string>;
+    for (const entry of ['.', './testing', './runtime']) {
+      const target = exportsMap[entry] as Record<string, string>;
+      expect(Object.keys(target).sort()).toEqual(['import', 'require', 'types']);
+      for (const file of Object.values(target)) expect(existsSync(path.join(out, file))).toBe(true);
+    }
+    const workspaceNow = JSON.parse(await readFile(path.join(PACKAGE_DIR, 'package.json'), 'utf8')) as { exports: Record<string, string> };
+    expect(workspaceNow.exports['.']).toBe('./src/index.ts');
+  });
+
+  test('js, d.ts, guest.cjs, child.cjs and README are emitted; postgres and typescript are not bundled', async () => {
+    const files = await listFiles(out);
+    expect(files).toContain('index.js');
+    expect(files).toContain('index.d.ts');
+    expect(files).toContain('testing/index.js');
+    expect(files).toContain('testing/index.d.ts');
+    expect(files).toContain('runtime/index.d.ts');
+    expect(files).toContain('guest.cjs');
+    expect(files).toContain('testing/child.cjs');
+    expect(files).toContain('README.md');
+    expect(files.filter((file) => file.includes('.test.'))).toEqual([]);
+    const testingCjs = await readFile(path.join(out, 'cjs/testing.cjs'), 'utf8');
+    expect(testingCjs).not.toContain('function postgres(');
+    expect(testingCjs).not.toContain(PACKAGE_DIR);
+    const esm = await readFile(path.join(out, 'testing/index.js'), 'utf8');
+    expect(esm).toMatch(/from '\.\/engine\.js'/);
+  });
+
+  test('js drops source comments; d.ts keeps doc comments', async () => {
+    for (const file of ['index.js', 'validate.js', 'testing/index.js', 'cjs/testing.cjs', 'guest.cjs']) {
+      expect(await readFile(path.join(out, file), 'utf8')).not.toContain('/**');
+    }
+    expect(await readFile(path.join(out, 'validate.d.ts'), 'utf8')).toContain('/**');
+  });
+
+  test('dist loadGuestRuntime returns guest.cjs, which boots in a guest session', async () => {
+    const runtime = await import(path.join(out, 'runtime/index.js')) as { loadGuestRuntime(): Promise<string>; GUEST_ENTRY_PATH: string };
+    const guest = await runtime.loadGuestRuntime();
+    expect(guest).toBe(await readFile(path.join(out, 'guest.cjs'), 'utf8'));
+    expect(guest).toContain('bootGuest');
+    expect(runtime.GUEST_ENTRY_PATH.endsWith(path.join('dist', 'runtime', 'guest', 'index.js'))).toBe(true);
+    expect(existsSync(runtime.GUEST_ENTRY_PATH)).toBe(true);
+    const outcome = await bootCheck(guest);
+    expect(outcome.type).toBe('result');
+  });
+
+  test('source loadGuestRuntime (Bun) boots in a guest session', async () => {
+    const guest = await loadGuestRuntime();
+    expect(guest).toContain('bootGuest');
+    const outcome = await bootCheck(guest);
+    expect(outcome.type).toBe('result');
+    expect((outcome.result as { kind: string }).kind).toBe('check');
+  });
+});
+
+describe('Node compatibility', () => {
+  const node = Bun.which('node');
+  const npm = Bun.which('npm');
+
+  test.skipIf(!node || !npm)('npm pack + npm install: ESM import and CJS require work under Node', async () => {
+    const project = path.join(base, 'consumer');
+    await run(['mkdir', '-p', project], base);
+    await writeFile(path.join(project, 'package.json'), JSON.stringify({ name: 'consumer', version: '1.0.0', private: true }));
+    const packed = (await run([npm as string, 'pack', out, '--pack-destination', base, '--silent'], base)).trim().split('\n').pop() as string;
+    await run([npm as string, 'install', '--no-audit', '--no-fund', '--silent', path.join(base, packed)], project);
+    const esm = await run([node as string, '--input-type=module', '-e', "import('@deepexi/datasense-connector').then((m) => console.log(m.SDK_VERSION))"], project);
+    expect(esm.trim()).toBe(WORKSPACE.version);
+    const cjs = await run([node as string, '-e', [
+      "const testing = require('@deepexi/datasense-connector/testing');",
+      "const sdk = require('@deepexi/datasense-connector');",
+      "console.log([typeof testing.createLocalGateway, typeof testing.createVmExecutor, sdk.SDK_VERSION].join(' '));",
+    ].join('\n')], project);
+    expect(cjs.trim()).toBe(`function function ${WORKSPACE.version}`);
+    const guest = await run([node as string, '--input-type=module', '-e', [
+      "import { loadGuestRuntime } from '@deepexi/datasense-connector/runtime';",
+      "const guest = await loadGuestRuntime();",
+      "console.log(guest.includes('bootGuest'));",
+    ].join('\n')], project);
+    expect(guest.trim()).toBe('true');
+  }, 180_000);
+
+  if (!node || !npm) test('node is missing: Node compatibility checks are skipped', () => {
+    console.warn('node/npm not found on PATH; skipped the npm pack + Node import check');
+  });
+});

package/test/define.test-d.ts

@@ -0,0 +1,182 @@
+/**
+ * 编写 API 的类型行为（只由 `bun run ts-check` 检查，不被 bun test 运行）：每个 `@ts-expect-error` 都必须真的报错，
+ * 否则 tsc 报「未使用的 @ts-expect-error」。
+ *
+ * 两种 D 各测一遍：
+ * - `Codegen`：按 shared codegen（`.ontos/types.ts`）的写法手写——顶层 interface、各层 readonly、列全部必填；
+ * - `Literal`：`DescriptorTypes<typeof 描述字面量>`。
+ */
+import {
+  defineCheck, defineOperation, defineStream, defineSuggestColumns,
+  type DescriptorTypes, type GeneratedDescriptor,
+} from '../src';
+
+// ---------------------------------------------------------------------------
+// 按 codegen 形状手写的 D
+
+interface Codegen {
+  readonly streams: {
+    readonly orders: {
+      readonly tables: {
+        readonly orders: { readonly id: string; readonly amount: string };
+        readonly order_lines: { readonly order_id: string; readonly line_no: number };
+      };
+      readonly params: { readonly pageSize?: number };
+    };
+  };
+  readonly pushes: Record<never, never>;
+  readonly operations: {
+    readonly create_followup: {
+      readonly idempotency: 'unsupported';
+      readonly input: { readonly customerId: string };
+      readonly output: { readonly followupId: string; readonly note?: string };
+    };
+    readonly update_note: {
+      readonly idempotency: 'supported';
+      readonly input: { readonly id: string };
+      readonly output: { readonly ok: boolean };
+    };
+  };
+  readonly extensibleStreams: Record<never, never>;
+  readonly config: { readonly baseUrl: string };
+  readonly secrets: { readonly token: string };
+}
+
+// codegen 包已绑定版本的写法能编译
+export function boundStream<N extends keyof Codegen['streams'] & string>(
+  name: N,
+  fn: Parameters<typeof defineStream<Codegen, N>>[1],
+): ReturnType<typeof defineStream<Codegen, N>> {
+  return defineStream<Codegen, N>(name, fn);
+}
+
+boundStream('orders', async function* (ctx, input) {
+  const base: string = ctx.config.baseUrl;
+  const size: number | undefined = input.streamConfig.pageSize;
+  yield ctx.record('orders', { id: `${base}${size ?? 0}`, amount: '1.00' });
+  yield ctx.record('order_lines', { order_id: 'o1', line_no: 1 });
+  // @ts-expect-error 表名 order 不存在
+  yield ctx.record('order', { id: 'x', amount: '1' });
+  // @ts-expect-error id 声明为 string
+  yield ctx.record('orders', { id: 1, amount: '1' });
+  // @ts-expect-error 配置项是 baseUrl，不是 baseURL
+  void ctx.config.baseURL;
+  // @ts-expect-error baseUrl 不是 secret
+  void ctx.secrets.baseUrl;
+  const token: string = ctx.secrets.token;
+  void token;
+});
+
+// @ts-expect-error 数据流 customers 不在描述里
+boundStream('customers', async function* () {});
+
+defineCheck<Codegen>(async (ctx) => {
+  const base: string = ctx.config.baseUrl;
+  void base;
+  // @ts-expect-error 配置项是 baseUrl，不是 baseURL
+  void ctx.config.baseURL;
+});
+
+// unsupported 必须给 lookup
+defineOperation<Codegen, 'create_followup'>('create_followup', {
+  async run(_ctx, params) { return { followupId: params.customerId }; },
+  async lookup() { return { status: 'not_applied' as const }; },
+});
+// @ts-expect-error unsupported 没给 lookup
+defineOperation<Codegen, 'create_followup'>('create_followup', {
+  async run(_ctx, params) { return { followupId: params.customerId }; },
+});
+// supported 时 lookup 可选
+defineOperation<Codegen, 'update_note'>('update_note', {
+  async run() { return { ok: true }; },
+});
+defineOperation<Codegen, 'update_note'>('update_note', {
+  // @ts-expect-error 输出缺必填字段 ok
+  async run() { return {}; },
+});
+
+// @ts-expect-error 没有可扩展表时没有可用的数据流名
+defineSuggestColumns<Codegen, 'orders'>('orders', async () => []);
+
+// ---------------------------------------------------------------------------
+// 从描述字面量推出的 D
+
+export const literal = {
+  config: {
+    baseUrl: { type: 'url', title: 'Base URL', description: 'x', placeholder: null, optional: false },
+    region: { type: 'enum', values: ['cn', 'us'], title: 'Region', description: 'x', placeholder: null, optional: true },
+    token: { type: 'secret', title: 'Token', description: 'x', placeholder: null, optional: false },
+  },
+  streams: {
+    orders: {
+      params: {},
+      tables: {
+        orders: { primaryKey: ['id'], extensible: false, columns: { id: { type: 'string' }, amount: { type: 'decimal', precision: 12, scale: 2 } } },
+        order_lines: { primaryKey: ['order_id', 'line_no'], extensible: false, columns: { order_id: { type: 'string' }, line_no: { type: 'integer' } } },
+      },
+    },
+    customers: {
+      params: {},
+      tables: { customers: { primaryKey: ['id'], extensible: true, columns: { id: { type: 'string' }, name: { type: 'string' } } } },
+    },
+  },
+  pushes: {},
+  operations: {
+    create_followup: {
+      idempotency: 'unsupported',
+      input: { customerId: { type: 'string', optional: false } },
+      output: { followupId: { type: 'string', optional: false }, note: { type: 'string', optional: true } },
+    },
+  },
+} as const;
+
+type Literal = DescriptorTypes<typeof literal>;
+
+// 推出的类型满足 GeneratedDescriptor
+const satisfied: GeneratedDescriptor = null as unknown as Literal;
+void satisfied;
+
+defineStream<Literal, 'orders'>('orders', async function* (ctx) {
+  const base: string = ctx.config.baseUrl;
+  const region: 'cn' | 'us' | undefined = ctx.config.region;
+  void region;
+  // 非主键列可缺省
+  yield ctx.record('orders', { id: base });
+  // @ts-expect-error 表名 order 不存在
+  yield ctx.record('order', { id: 'x' });
+  // @ts-expect-error id 声明为 string
+  yield ctx.record('orders', { id: 1 });
+  // @ts-expect-error 主键列必填
+  yield ctx.record('order_lines', { order_id: 'o1' });
+  // @ts-expect-error 不可扩展表不接受未声明字段
+  yield ctx.record('orders', { id: 'x', foo: 1 });
+  // @ts-expect-error 配置项是 baseUrl，不是 baseURL
+  void ctx.config.baseURL;
+  // @ts-expect-error baseUrl 不是 secret
+  void ctx.secrets.baseUrl;
+  const token: string = ctx.secrets.token;
+  void token;
+});
+
+defineStream<Literal, 'customers'>('customers', async function* (ctx) {
+  // 可扩展表接受额外字段
+  yield ctx.record('customers', { id: 'c1', vip_level: 'gold' });
+});
+
+// @ts-expect-error unsupported 没给 lookup
+defineOperation<Literal, 'create_followup'>('create_followup', {
+  async run(_ctx, params) { return { followupId: params.customerId }; },
+});
+defineOperation<Literal, 'create_followup'>('create_followup', {
+  // @ts-expect-error 输出缺必填字段 followupId
+  async run() { return { note: 'x' }; },
+  async lookup() { return { status: 'not_applied' as const }; },
+});
+
+// 有可扩展表的数据流可以写建议列，table 只能是它的可扩展表
+defineSuggestColumns<Literal, 'customers'>('customers', async (_ctx, input) => {
+  const table: 'customers' = input.table;
+  return [{ name: 'vip_level', type: 'string', title: table }];
+});
+// @ts-expect-error orders 没有可扩展表
+defineSuggestColumns<Literal, 'orders'>('orders', async () => []);

package/test/fixtures/acceptance.ts

@@ -0,0 +1,156 @@
+/**
+ * 两个验收连接器（`test/fixtures/connectors/{http-pull,pg-pull}`，按描述布局）的录制输入：
+ * 录制脚本 `record-acceptance.ts` 与测试 `test/testing/acceptance-fixtures.test.ts` 共用。
+ *
+ * 录下的用例放在连接器目录的 `streams/<数据流>/tests/<用例名>/`（`readFixtureDir(<连接器目录>)` 读）。
+ */
+import path from 'node:path';
+import postgres from 'postgres';
+import ts from 'typescript';
+import {
+  createLocalGateway, createRecorder, createVmExecutor, loadLocalConnector, serializeFixture,
+  type ConnectorFixtureFile, type FixtureCase, type LocalGatewayOptions, type LocalRunResult,
+} from '../../src/testing';
+
+export const CONNECTORS_DIR = path.resolve(import.meta.dir, 'connectors');
+export const HTTP_PULL_DIR = path.join(CONNECTORS_DIR, 'http-pull');
+export const PG_PULL_DIR = path.join(CONNECTORS_DIR, 'pg-pull');
+
+// ---------------------------------------------------------------------------
+// http-pull：假上游两页
+
+export const HTTP_SECRETS = { token: 'tok-secret-1' };
+export const HTTP_CONFIG = { baseUrl: 'https://api.example.com/v1' };
+
+const PAGES: Record<string, { items: Array<{ id: string; name: string; updatedAt: string }>; nextCursor: string | null }> = {
+  first: {
+    items: [
+      { id: 'a', name: 'Alpha', updatedAt: '2026-10-01T00:00:00.000Z' },
+      { id: 'b', name: 'Beta', updatedAt: '2026-10-02T00:00:00.000Z' },
+    ],
+    nextCursor: 'p2',
+  },
+  p2: { items: [{ id: 'c', name: 'Gamma', updatedAt: '2026-10-03T00:00:00.000Z' }], nextCursor: null },
+};
+
+/** 假上游：鉴权头不是 `Bearer <token>` 时回 401；没有 cursor 回第一页，`cursor=p2` 回第二页。 */
+export function twoPageFetch(): typeof fetch {
+  const impl = async (input: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    const url = new URL(typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url);
+    if (new Headers(init?.headers).get('authorization') !== `Bearer ${HTTP_SECRETS.token}`) return new Response('unauthorized', { status: 401 });
+    return Response.json(PAGES[url.searchParams.get('cursor') ?? 'first']);
+  };
+  return impl as typeof fetch;
+}
+
+export const HTTP_CASE_NAME = 'basic';
+export const HTTP_CASE: FixtureCase = {
+  kind: 'pull',
+  stream: 'items',
+  mode: 'full',
+  config: HTTP_CONFIG,
+  secrets: HTTP_SECRETS,
+  expect: { records: { items: 3 }, checkpoints: 2 },
+};
+
+// ---------------------------------------------------------------------------
+// pg-pull：本机 :15432 的 Postgres 里建一个模式
+
+export const PG_TARGET = { host: 'localhost', port: 15432, database: 'postgres', user: 'admin', password: 'password' };
+export const PG_SCHEMA = 'sdk_fixture_pg_pull';
+
+export const PG_CASE_NAME = 'customers-full';
+export const PG_CASE: FixtureCase = {
+  kind: 'pull',
+  stream: 'customers',
+  mode: 'full',
+  streamConfig: { pageSize: 2 },
+  config: { schema: PG_SCHEMA },
+  expect: { records: { customers: 3 }, checkpoints: 2 },
+};
+
+/** 本机 :15432 的 Postgres 能否连上：能连上返回 null，否则返回原因。测试文件在顶层 await 一次，配合 skipIf 使用。 */
+export async function localPgUnavailable(): Promise<string | null> {
+  const sql = postgres({ ...PG_TARGET, username: PG_TARGET.user, max: 1, connect_timeout: 5, onnotice: () => {} });
+  try {
+    await sql`select 1`;
+    return null;
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  } finally {
+    await sql.end({ timeout: 5 }).catch(() => undefined);
+  }
+}
+
+/** 重建录制用的模式与数据；连不上时返回 false，连上之后的 SQL 错误照常抛出。 */
+export async function preparePgSchema(): Promise<boolean> {
+  const sql = postgres({ ...PG_TARGET, username: PG_TARGET.user, max: 1, connect_timeout: 5, onnotice: () => {} });
+  try {
+    try {
+      await sql`select 1`;
+    } catch {
+      return false;
+    }
+    await sql.unsafe(`drop schema if exists ${PG_SCHEMA} cascade`);
+    await sql.unsafe(`create schema ${PG_SCHEMA}`);
+    await sql.unsafe(`create table ${PG_SCHEMA}.customers (
+      id text primary key, name text not null, balance numeric(12,2), active boolean, joined date, updated_at timestamptz, profile jsonb)`);
+    await sql.unsafe(`create table ${PG_SCHEMA}.orders (id text primary key, customer_id text, amount integer, updated_at timestamptz)`);
+    await sql.unsafe(`insert into ${PG_SCHEMA}.customers values
+      ('c1', 'Ada', 120.50, true, '2026-01-02', '2026-10-01T08:00:00Z', '{"tier":"gold"}'),
+      ('c2', 'Bob', 0, false, '2026-02-03', '2026-10-02T08:00:00Z', null),
+      ('c3', 'Cyd', null, null, null, null, '{"tags":["x"]}')`);
+    return true;
+  } finally {
+    await sql.end({ timeout: 5 }).catch(() => undefined);
+  }
+}
+
+export async function dropPgSchema(): Promise<void> {
+  const sql = postgres({ ...PG_TARGET, username: PG_TARGET.user, max: 1, connect_timeout: 5, onnotice: () => {} });
+  try {
+    await sql.unsafe(`drop schema if exists ${PG_SCHEMA} cascade`);
+  } catch {
+    // 连不上时什么也不做
+  } finally {
+    await sql.end({ timeout: 5 }).catch(() => undefined);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 录制
+
+/**
+ * 按 CLI `read --record` 的做法录一个拉取用例：源码目录经 `loadLocalConnector` 在 vm 子进程里执行（作业表取描述里该数据流的表），
+ * 本地模拟网关的往来交给录制器，最后 `serializeFixture`。
+ */
+export async function recordPullCase(
+  sourceDir: string,
+  name: string,
+  fixtureCase: Extract<FixtureCase, { kind: 'pull' }>,
+  gateway: Omit<LocalGatewayOptions, 'onExchange' | 'secrets'>,
+): Promise<{ files: ConnectorFixtureFile[]; result: LocalRunResult }> {
+  const secrets = fixtureCase.secrets ?? {};
+  const recorder = createRecorder({ secrets });
+  const host = createLocalGateway({ ...gateway, secrets, onExchange: (exchange) => recorder.onExchange(exchange) });
+  const connector = await loadLocalConnector(sourceDir, { typescript: ts });
+  try {
+    const tables = Object.keys(connector.descriptor.streams[fixtureCase.stream]?.tables ?? {});
+    const result = await createVmExecutor(connector).run({
+      kind: 'pull', config: fixtureCase.config, secretFields: Object.keys(secrets), stream: fixtureCase.stream, mode: fixtureCase.mode,
+      state: fixtureCase.state ?? null, streamConfig: fixtureCase.streamConfig ?? {}, tables,
+    }, host, fixtureCase.limit !== undefined ? { limit: fixtureCase.limit } : {});
+    return { files: serializeFixture(name, { case: fixtureCase, exchanges: recorder.exchanges() }), result };
+  } finally {
+    await host.close();
+  }
+}
+
+export function recordHttpPull(): Promise<{ files: ConnectorFixtureFile[]; result: LocalRunResult }> {
+  return recordPullCase(HTTP_PULL_DIR, HTTP_CASE_NAME, HTTP_CASE as Extract<FixtureCase, { kind: 'pull' }>, { hosts: ['api.example.com'], fetch: twoPageFetch() });
+}
+
+/** 先 `preparePgSchema()`。 */
+export function recordPgPull(): Promise<{ files: ConnectorFixtureFile[]; result: LocalRunResult }> {
+  return recordPullCase(PG_PULL_DIR, PG_CASE_NAME, PG_CASE as Extract<FixtureCase, { kind: 'pull' }>, { hosts: [], db: PG_TARGET });
+}

package/test/fixtures/connectors/http-pull/.ontos/descriptor.json

@@ -0,0 +1,72 @@
+{
+  "name": "http_pull",
+  "version": "1.0.0",
+  "title": "HTTP pull",
+  "description": "Acceptance fixture: pull from a paginated HTTP API",
+  "icon": null,
+  "config": {
+    "baseUrl": {
+      "type": "url",
+      "title": "Base URL",
+      "description": "Base URL",
+      "placeholder": null,
+      "optional": false
+    },
+    "token": {
+      "type": "secret",
+      "title": "Token",
+      "description": "Token",
+      "placeholder": null,
+      "optional": false
+    }
+  },
+  "hosts": [],
+  "db": null,
+  "rateLimit": null,
+  "check": false,
+  "streams": {
+    "items": {
+      "title": "Items",
+      "description": "Items",
+      "syncModes": [
+        "full",
+        "incremental"
+      ],
+      "snapshot": "complete",
+      "params": {},
+      "tables": {
+        "items": {
+          "title": "Items",
+          "description": "Items",
+          "primaryKey": [
+            "id"
+          ],
+          "extensible": false,
+          "columns": {
+            "id": {
+              "type": "string",
+              "title": "ID",
+              "description": null
+            },
+            "name": {
+              "type": "string",
+              "title": "Name",
+              "description": null
+            },
+            "updated_at": {
+              "type": "instant",
+              "title": "Updated at",
+              "description": null
+            }
+          },
+          "retention": null,
+          "purgeColumns": null,
+          "indexes": []
+        }
+      },
+      "suggestColumns": false
+    }
+  },
+  "pushes": {},
+  "operations": {}
+}

package/test/fixtures/connectors/http-pull/.ontos/types.ts

@@ -0,0 +1,61 @@
+/* eslint-disable @typescript-eslint/no-empty-object-type -- 原样保留 shared codegen 的产物（空能力组生成 `{}`） */
+// 由 ontos admin connector codegen 根据连接器描述生成。不要手改。
+import {
+  defineCheck as defineCheckFor,
+  defineOperation as defineOperationFor,
+  definePush as definePushFor,
+  defineStream as defineStreamFor,
+  defineSuggestColumns as defineSuggestColumnsFor,
+} from '@deepexi/datasense-connector';
+
+/** 这份描述绑定到编写 API 上的类型参数。 */
+export interface GeneratedDescriptor {
+  readonly streams: {
+    readonly items: { readonly tables: { readonly items: { readonly id: string; readonly name: string; readonly updated_at: string; }; }; readonly params: {  }; };
+  };
+  readonly pushes: {
+    
+  };
+  readonly operations: {
+    
+  };
+  readonly extensibleStreams: {
+    
+  };
+  readonly config: { readonly baseUrl: string; };
+  readonly secrets: { readonly token: string; };
+}
+
+export function defineStream<N extends keyof GeneratedDescriptor['streams'] & string>(
+  name: N,
+  fn: Parameters<typeof defineStreamFor<GeneratedDescriptor, N>>[1],
+): ReturnType<typeof defineStreamFor<GeneratedDescriptor, N>> {
+  return defineStreamFor<GeneratedDescriptor, N>(name, fn);
+}
+
+export function definePush<N extends keyof GeneratedDescriptor['pushes'] & string>(
+  name: N,
+  fn: Parameters<typeof definePushFor<GeneratedDescriptor, N>>[1],
+): ReturnType<typeof definePushFor<GeneratedDescriptor, N>> {
+  return definePushFor<GeneratedDescriptor, N>(name, fn);
+}
+
+export function defineOperation<N extends keyof GeneratedDescriptor['operations'] & string>(
+  name: N,
+  fn: Parameters<typeof defineOperationFor<GeneratedDescriptor, N>>[1],
+): ReturnType<typeof defineOperationFor<GeneratedDescriptor, N>> {
+  return defineOperationFor<GeneratedDescriptor, N>(name, fn);
+}
+
+export function defineCheck(
+  fn: Parameters<typeof defineCheckFor<GeneratedDescriptor>>[0],
+): ReturnType<typeof defineCheckFor<GeneratedDescriptor>> {
+  return defineCheckFor<GeneratedDescriptor>(fn);
+}
+
+export function defineSuggestColumns<N extends keyof GeneratedDescriptor['extensibleStreams'] & string>(
+  name: N,
+  fn: Parameters<typeof defineSuggestColumnsFor<GeneratedDescriptor, N>>[1],
+): ReturnType<typeof defineSuggestColumnsFor<GeneratedDescriptor, N>> {
+  return defineSuggestColumnsFor<GeneratedDescriptor, N>(name, fn);
+}

package/test/fixtures/connectors/http-pull/package.json

@@ -0,0 +1,5 @@
+{
+  "dependencies": {
+    "@deepexi/datasense-connector": "^3.0.0"
+  }
+}

package/test/fixtures/connectors/http-pull/streams/items/index.ts

@@ -0,0 +1,37 @@
+/**
+ * 验收夹具：从分页的 HTTP API 拉数（`http_pull@1.0.0`，只作 SDK 测试夹具）。
+ *
+ * 上游接口：`GET <baseUrl>/items[?updatedSince=<ISO>]` 返回 `{ items, nextCursor }`，条目按 `updatedAt` 升序；
+ * 有下一页时 `GET <baseUrl>/items?cursor=<nextCursor>`（游标自带首页的过滤条件）。鉴权 `Authorization: Bearer <token>`，
+ * 脚本里的 `ctx.secrets.token` 只是凭证句柄，出站网关替换成明文。
+ *
+ * 断点 `{ updatedSince, cursor? }`：每页之后提交一次，`updatedSince` 是至今见过的最大 `updatedAt`，`cursor` 是下一页；
+ * 最后一页之后只剩 `{ updatedSince }`。
+ */
+import { defineStream } from '../../.ontos/types';
+import { mapItem, type RawItem } from './map';
+
+interface ItemsPage { items: RawItem[]; nextCursor?: string | null }
+interface ItemsState { updatedSince: string | null; cursor?: string }
+
+export default defineStream('items', async function* (ctx, input) {
+  const state = input.state as ItemsState | undefined;
+  const url = `${ctx.config.baseUrl.replace(/\/+$/, '')}/items`;
+  let high = state?.updatedSince ?? null;
+  let cursor = state?.cursor;
+  // 续跑沿用断点的游标；新的一次增量从 updatedSince 起，全量从头读。
+  const since = cursor === undefined && input.mode === 'incremental' ? high : null;
+  for (let page = 1; ; page += 1) {
+    const query: Record<string, string> = cursor !== undefined ? { cursor } : since !== null ? { updatedSince: since } : {};
+    const response = await ctx.http.get<ItemsPage>(url, { query, headers: { authorization: `Bearer ${ctx.secrets.token}` } });
+    for (const raw of response.data.items) {
+      const row = mapItem(raw);
+      if (high === null || row.updated_at > high) high = row.updated_at;
+      yield ctx.record('items', row);
+    }
+    cursor = response.data.nextCursor ?? undefined;
+    ctx.log.info(`page ${page}: ${response.data.items.length} item(s), next cursor ${cursor ?? 'none'}`);
+    yield ctx.checkpoint(cursor !== undefined ? { updatedSince: high, cursor } : { updatedSince: high });
+    if (cursor === undefined) return;
+  }
+});