@deepexi/datasense-connector 3.0.1 → 3.1.0

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

@@ -0,0 +1,12 @@
+/**
+ * 上游条目 → 表 `items` 的一行。上游契约：每个条目都有字符串 `id`、`name` 与 ISO 8601 的 `updatedAt`；
+ * 不符合契约的条目说明上游改了接口，直接抛错让运行失败（调用栈经 sourcemap 映射回本文件）。
+ */
+export interface RawItem { id?: unknown; name?: unknown; updatedAt?: unknown }
+
+export function mapItem(raw: RawItem): { id: string; name: string; updated_at: string } {
+  if (typeof raw.id !== 'string' || typeof raw.updatedAt !== 'string') {
+    throw new TypeError(`upstream item is missing id or updatedAt: ${JSON.stringify(raw)}`);
+  }
+  return { id: raw.id, name: typeof raw.name === 'string' ? raw.name : '', updated_at: raw.updatedAt };
+}

package/test/fixtures/connectors/http-pull/streams/items/tests/basic/case.json

@@ -0,0 +1,15 @@
+{
+  "mode": "full",
+  "config": {
+    "baseUrl": "https://api.example.com/v1"
+  },
+  "secrets": {
+    "token": "***"
+  },
+  "expect": {
+    "records": {
+      "items": 3
+    },
+    "checkpoints": 2
+  }
+}

package/test/fixtures/connectors/http-pull/streams/items/tests/basic/exchanges.ndjson

@@ -0,0 +1,2 @@
+{"seq":1,"kind":"http","request":{"method":"GET","url":"https://api.example.com/v1/items","headers":{"authorization":"***"},"body":null,"bodyEncoding":"utf8"},"response":{"status":200,"headers":{"content-type":"application/json;charset=utf-8"},"body":"{\"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\"}","bodyEncoding":"utf8"},"error":null}
+{"seq":2,"kind":"http","request":{"method":"GET","url":"https://api.example.com/v1/items?cursor=p2","headers":{"authorization":"***"},"body":null,"bodyEncoding":"utf8"},"response":{"status":200,"headers":{"content-type":"application/json;charset=utf-8"},"body":"{\"items\":[{\"id\":\"c\",\"name\":\"Gamma\",\"updatedAt\":\"2026-10-03T00:00:00.000Z\"}],\"nextCursor\":null}","bodyEncoding":"utf8"},"error":null}

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

@@ -0,0 +1,151 @@
+{
+  "name": "pg_pull",
+  "version": "1.0.0",
+  "title": "PostgreSQL pull",
+  "description": "Acceptance fixture: pull from an existing PostgreSQL database",
+  "icon": null,
+  "config": {
+    "schema": {
+      "type": "string",
+      "title": "Schema",
+      "description": "Schema",
+      "placeholder": null,
+      "optional": false
+    }
+  },
+  "hosts": [],
+  "db": {
+    "engine": "postgresql"
+  },
+  "rateLimit": null,
+  "check": false,
+  "streams": {
+    "orders": {
+      "title": "Orders",
+      "description": "Orders",
+      "syncModes": [
+        "incremental"
+      ],
+      "snapshot": "partial",
+      "params": {
+        "pageSize": {
+          "type": "integer",
+          "title": "Page size",
+          "description": "Page size",
+          "placeholder": null,
+          "optional": true,
+          "default": 1000
+        }
+      },
+      "tables": {
+        "orders": {
+          "title": "Orders",
+          "description": "Orders",
+          "primaryKey": [
+            "id"
+          ],
+          "extensible": false,
+          "columns": {
+            "id": {
+              "type": "string",
+              "title": "ID",
+              "description": null
+            },
+            "customer_id": {
+              "type": "string",
+              "title": "Customer",
+              "description": null
+            },
+            "amount": {
+              "type": "integer",
+              "title": "Amount",
+              "description": null
+            },
+            "updated_at": {
+              "type": "instant",
+              "title": "Updated at",
+              "description": null
+            }
+          },
+          "retention": null,
+          "purgeColumns": null,
+          "indexes": []
+        }
+      },
+      "suggestColumns": false
+    },
+    "customers": {
+      "title": "Customers",
+      "description": "Customers",
+      "syncModes": [
+        "full"
+      ],
+      "snapshot": "complete",
+      "params": {
+        "pageSize": {
+          "type": "integer",
+          "title": "Page size",
+          "description": "Page size",
+          "placeholder": null,
+          "optional": true,
+          "default": 1000
+        }
+      },
+      "tables": {
+        "customers": {
+          "title": "Customers",
+          "description": "Customers",
+          "primaryKey": [
+            "id"
+          ],
+          "extensible": true,
+          "columns": {
+            "id": {
+              "type": "string",
+              "title": "ID",
+              "description": null
+            },
+            "name": {
+              "type": "string",
+              "title": "Name",
+              "description": null
+            },
+            "balance": {
+              "type": "decimal",
+              "title": "Balance",
+              "description": null,
+              "precision": 12,
+              "scale": 2
+            },
+            "active": {
+              "type": "boolean",
+              "title": "Active",
+              "description": null
+            },
+            "joined": {
+              "type": "date",
+              "title": "Joined",
+              "description": null
+            },
+            "updated_at": {
+              "type": "instant",
+              "title": "Updated at",
+              "description": null
+            },
+            "profile": {
+              "type": "json",
+              "title": "Profile",
+              "description": null
+            }
+          },
+          "retention": null,
+          "purgeColumns": null,
+          "indexes": []
+        }
+      },
+      "suggestColumns": false
+    }
+  },
+  "pushes": {},
+  "operations": {}
+}

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

@@ -0,0 +1,62 @@
+/* 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 orders: { readonly tables: { readonly orders: { readonly id: string; readonly customer_id: string; readonly amount: number; readonly updated_at: string; }; }; readonly params: { readonly pageSize?: number; }; };
+    readonly customers: { readonly tables: { readonly customers: { readonly id: string; readonly name: string; readonly balance: string; readonly active: boolean; readonly joined: string; readonly updated_at: string; readonly profile: unknown; }; }; readonly params: { readonly pageSize?: number; }; };
+  };
+  readonly pushes: {
+    
+  };
+  readonly operations: {
+    
+  };
+  readonly extensibleStreams: {
+    readonly customers: GeneratedDescriptor['streams']['customers'];
+  };
+  readonly config: { readonly schema: string; };
+  readonly secrets: {  };
+}
+
+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/pg-pull/lib/sql.ts

@@ -0,0 +1,14 @@
+/** 双引号引用标识符（模式名、表名不能走参数）。 */
+export function quoteIdent(name: string): string {
+  return `"${name.replaceAll('"', '""')}"`;
+}
+
+export function relationOf(schema: string, table: string): string {
+  return `${quoteIdent(schema)}.${quoteIdent(table)}`;
+}
+
+const DEFAULT_PAGE_SIZE = 1000;
+
+export function pageSizeOf(value: unknown): number {
+  return typeof value === 'number' && Number.isInteger(value) && value > 0 ? value : DEFAULT_PAGE_SIZE;
+}

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

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

package/test/fixtures/connectors/pg-pull/streams/customers/index.ts

@@ -0,0 +1,30 @@
+/**
+ * `customers`：全量完整快照，按 `id` 键分页，断点 `{ id }` 让一次全量中途失败后从断点续跑；本轮没出现的主键被平台软删除。
+ * 表可扩展：来源表新增的列原样带上，建连接时加了扩展列就落库。
+ */
+import { defineStream, type GeneratedDescriptor } from '../../.ontos/types';
+import { pageSizeOf, relationOf } from '../../lib/sql';
+
+interface CustomerKey { id: string }
+
+/** 数据库行按来源库的列原样带上（可能有 null），生成的行类型不含 null，这里按行类型交给 `ctx.record`。 */
+type Row = GeneratedDescriptor['streams']['customers']['tables']['customers'];
+
+export default defineStream('customers', async function* (ctx, input) {
+  const relation = relationOf(ctx.config.schema, 'customers');
+  const limit = pageSizeOf(input.streamConfig.pageSize);
+  const start = input.state as CustomerKey | undefined;
+  const pages = ctx.paginate.keyset<Record<string, unknown>, CustomerKey>({
+    query: (last) => {
+      const after = last ?? start;
+      return after
+        ? ctx.db.query(`select * from ${relation} where id > $1 order by id limit $2`, [after.id, limit])
+        : ctx.db.query(`select * from ${relation} order by id limit $1`, [limit]);
+    },
+    key: (row) => ({ id: String(row.id) }),
+  });
+  for await (const page of pages) {
+    for (const row of page.rows) yield ctx.record('customers', row as Row);
+    yield ctx.checkpoint({ id: String((page.rows[page.rows.length - 1] as Record<string, unknown>).id) } satisfies CustomerKey);
+  }
+});

package/test/fixtures/connectors/pg-pull/streams/customers/tests/customers-full/case.json

@@ -0,0 +1,15 @@
+{
+  "mode": "full",
+  "streamConfig": {
+    "pageSize": 2
+  },
+  "config": {
+    "schema": "sdk_fixture_pg_pull"
+  },
+  "expect": {
+    "records": {
+      "customers": 3
+    },
+    "checkpoints": 2
+  }
+}

package/test/fixtures/connectors/pg-pull/streams/customers/tests/customers-full/exchanges.ndjson

@@ -0,0 +1,3 @@
+{"seq":1,"kind":"db","sql":"select * from \"sdk_fixture_pg_pull\".\"customers\" order by id limit $1","params":[2],"fields":[{"name":"id","dataTypeId":25},{"name":"name","dataTypeId":25},{"name":"balance","dataTypeId":1700},{"name":"active","dataTypeId":16},{"name":"joined","dataTypeId":1082},{"name":"updated_at","dataTypeId":1184},{"name":"profile","dataTypeId":3802}],"rows":[{"id":"c1","name":"Ada","balance":"120.50","active":true,"joined":"2026-01-02","updated_at":"2026-10-01T08:00:00.000Z","profile":{"tier":"gold"}},{"id":"c2","name":"Bob","balance":"0.00","active":false,"joined":"2026-02-03","updated_at":"2026-10-02T08:00:00.000Z","profile":null}],"error":null}
+{"seq":2,"kind":"db","sql":"select * from \"sdk_fixture_pg_pull\".\"customers\" where id > $1 order by id limit $2","params":["c2",2],"fields":[{"name":"id","dataTypeId":25},{"name":"name","dataTypeId":25},{"name":"balance","dataTypeId":1700},{"name":"active","dataTypeId":16},{"name":"joined","dataTypeId":1082},{"name":"updated_at","dataTypeId":1184},{"name":"profile","dataTypeId":3802}],"rows":[{"id":"c3","name":"Cyd","balance":null,"active":null,"joined":null,"updated_at":null,"profile":{"tags":["x"]}}],"error":null}
+{"seq":3,"kind":"db","sql":"select * from \"sdk_fixture_pg_pull\".\"customers\" where id > $1 order by id limit $2","params":["c3",2],"fields":[],"rows":[],"error":null}

package/test/fixtures/connectors/pg-pull/streams/orders/index.ts

@@ -0,0 +1,32 @@
+/**
+ * `orders`：增量，按 `(updated_at, id)` 键分页，每页之后提交断点 `{ updatedAt, id }`（最后一行的键）。
+ * 来源库由连接每个环境的平台字段 `db` 决定，配置 `schema` 是来源表所在的模式；表结构固定写在描述里。
+ */
+import { defineStream, type GeneratedDescriptor } from '../../.ontos/types';
+import { pageSizeOf, relationOf } from '../../lib/sql';
+
+interface OrderKey { updatedAt: string; id: string }
+
+/** 数据库行按来源库的列原样带上（可能有 null），生成的行类型不含 null，这里按行类型交给 `ctx.record`。 */
+type Row = GeneratedDescriptor['streams']['orders']['tables']['orders'];
+
+export default defineStream('orders', async function* (ctx, input) {
+  const relation = relationOf(ctx.config.schema, 'orders');
+  const limit = pageSizeOf(input.streamConfig.pageSize);
+  // 重新同步（全量）时平台不给断点，从头读。
+  const start = input.state as OrderKey | undefined;
+  const pages = ctx.paginate.keyset<Record<string, unknown>, OrderKey>({
+    query: (last) => {
+      const after = last ?? start;
+      return after
+        ? ctx.db.query(`select * from ${relation} where (updated_at, id) > ($1::timestamptz, $2) order by updated_at, id limit $3`, [after.updatedAt, after.id, limit])
+        : ctx.db.query(`select * from ${relation} order by updated_at, id limit $1`, [limit]);
+    },
+    key: (row) => ({ updatedAt: String(row.updated_at), id: String(row.id) }),
+  });
+  for await (const page of pages) {
+    for (const row of page.rows) yield ctx.record('orders', row as Row);
+    const last = page.rows[page.rows.length - 1] as Record<string, unknown>;
+    yield ctx.checkpoint({ updatedAt: String(last.updated_at), id: String(last.id) } satisfies OrderKey);
+  }
+});

package/test/fixtures/descriptor.ts

@@ -0,0 +1,54 @@
+/** 测试用的连接器描述构造器：只写关心的部分，其余按规整后的缺省值补齐。 */
+import type {
+  ColumnDescriptor, ColumnType, ConfigField, ConnectorDescriptor, OperationDescriptor, PushDescriptor, StreamDescriptor, TableDescriptor, ValueField,
+} from '../../src/index';
+
+export function column(type: ColumnType, extra: Partial<ColumnDescriptor> = {}): ColumnDescriptor {
+  return { type, title: extra.title ?? type, description: null, ...extra };
+}
+
+export function table(columns: Record<string, ColumnType | ColumnDescriptor>, primaryKey: string[], extra: Partial<TableDescriptor> = {}): TableDescriptor {
+  const expanded: Record<string, ColumnDescriptor> = {};
+  for (const [name, value] of Object.entries(columns)) expanded[name] = typeof value === 'string' ? { type: value, title: name, description: null } : value;
+  return {
+    title: 'Table', description: 'A table', primaryKey, extensible: false, columns: expanded, retention: null, purgeColumns: null, indexes: [], ...extra,
+  };
+}
+
+export function stream(tables: Record<string, TableDescriptor>, extra: Partial<StreamDescriptor> = {}): StreamDescriptor {
+  return { title: 'Stream', description: 'A stream', syncModes: ['full', 'incremental'], snapshot: 'partial', params: {}, tables, suggestColumns: false, ...extra };
+}
+
+export function push(tables: Record<string, TableDescriptor>): PushDescriptor {
+  return { title: 'Push', description: 'A push', tables };
+}
+
+export function configField(type: ConfigField['type'], extra: Partial<ConfigField> = {}): ConfigField {
+  return { type, title: 'Field', description: 'A field', placeholder: null, optional: false, ...extra };
+}
+
+export function valueField(type: ValueField['type'], extra: Partial<ValueField> = {}): ValueField {
+  return { type, title: 'Field', description: 'A field', optional: false, ...extra };
+}
+
+export function operation(input: Record<string, ValueField>, output: Record<string, ValueField>, extra: Partial<OperationDescriptor> = {}): OperationDescriptor {
+  return { title: 'Operation', description: 'An operation', effect: 'create', risk: 'low', idempotency: 'supported', input, output, ...extra };
+}
+
+export function descriptor(overrides: Partial<ConnectorDescriptor> = {}): ConnectorDescriptor {
+  return {
+    name: 'demo', version: '1.0.0', title: 'Demo', description: 'Demo connector', icon: null,
+    config: {}, hosts: [], db: null, rateLimit: null, check: false, streams: {}, pushes: {}, operations: {},
+    ...overrides,
+  };
+}
+
+/**
+ * 手写的 CommonJS 连接器产物（与虚拟入口同形，避开打包器的常量折叠），从 guest 的 `require` 取 SDK。
+ * `implementations` 是 `implementations` 对象字面量里的成员（如 `streams: { items: defineStream('items', async function* () {}) }`）。
+ */
+export function rawConnector(desc: ConnectorDescriptor, implementations: string, header = ''): string {
+  return `const { defineStream, definePush, defineOperation, defineCheck, defineSuggestColumns, errors } = require('@deepexi/datasense-connector');
+${header}
+module.exports = { descriptor: ${JSON.stringify(desc)}, implementations: { ${implementations} } };`;
+}

package/test/fixtures/kingdee-example.ts

@@ -0,0 +1,82 @@
+/**
+ * 设计 `connector-runtime.md` §4.2 的金蝶云星辰示例，按描述 + 编写 API 改写，用来确认带类型的编写 API 能写出真实连接器：
+ * 包的 `ts-check` 覆盖本文件。`D` 按 codegen（`.ontos/types.ts`）的形状手写：顶层 interface、各层 readonly、列与配置按类型映射。
+ * HTTP 响应体、断点与会话用显式类型（原文是无类型的 JS 写法）。
+ */
+import { defineCheck, defineStream, errors, type ConnectorContext, type HttpAuth } from '../../src/index';
+
+/** 描述 `kingdee_jdy@1.0.0` 的生成类型（`hosts: ['api.kingdee.com', '*.jdy.com']`，`rateLimit: { perSecond: 10, concurrency: 4 }`）。 */
+interface D {
+  readonly streams: {
+    readonly sales_order: {
+      readonly tables: {
+        readonly sales_order: {
+          readonly id: string; readonly bill_no: string; readonly biz_date: string; readonly modified_at: string; readonly amount: string; readonly raw: unknown;
+        };
+        readonly sales_order_line: { readonly order_id: string; readonly line_no: number; readonly sku_id: string; readonly qty: string };
+      };
+      readonly params: Record<never, never>;
+    };
+  };
+  readonly pushes: Record<never, never>;
+  readonly operations: Record<never, never>;
+  readonly extensibleStreams: Record<never, never>;
+  readonly config: { readonly accountId: string };
+  readonly secrets: { readonly clientId: string; readonly clientSecret: string; readonly appKey: string; readonly appSecret: string };
+}
+
+interface SalesOrderPage { rows: Array<{ id: string; modify_time: string }>; total_page: number }
+interface SalesOrderDetail {
+  id: string; bill_no: string; bill_date: string; modify_time: string; total_amount: string;
+  material_entity: Array<{ seq: number; material_id: string; qty: string }>;
+}
+interface TokenResponse { errcode: number; data: { 'app-token': string; domain: string } }
+
+export const check = defineCheck<D>(async (ctx) => {
+  await session(ctx);
+});
+
+export const salesOrder = defineStream<D, 'sales_order'>('sales_order', async function* (ctx, { mode, state }) {
+  const auth = await session(ctx);
+  const since = mode === 'incremental' ? (state as { modifiedSince?: string } | undefined)?.modifiedSince : undefined;
+
+  for await (const page of ctx.paginate.page({
+    firstPage: 1,
+    request: (n) => ctx.http.get<SalesOrderPage>('/jdy/v2/scm/sal_order', {
+      query: { page: n, page_size: 100, modify_start_time: since }, auth,
+    }),
+    rows: (res) => res.data.rows,
+    totalPages: (res) => res.data.total_page,
+  })) {
+    const details = await ctx.map(page.rows, (row) =>
+      ctx.http.get<SalesOrderDetail>('/jdy/v2/scm/sal_order_detail', { query: { id: row.id }, auth }), { concurrency: 4 });
+
+    for (const d of details) {
+      yield ctx.record('sales_order', {
+        id: d.data.id, bill_no: d.data.bill_no,
+        biz_date: d.data.bill_date,
+        modified_at: ctx.time.toUtc(d.data.modify_time, 'Asia/Shanghai'),
+        amount: d.data.total_amount, raw: d.data,
+      });
+      for (const line of d.data.material_entity) {
+        yield ctx.record('sales_order_line', {
+          order_id: d.data.id, line_no: line.seq, sku_id: line.material_id, qty: line.qty,
+        });
+      }
+    }
+    yield ctx.checkpoint({ modifiedSince: page.maxOf((row) => row.modify_time) });
+  }
+});
+
+// 登录换会话：签名由网关用句柄代算，脚本看不到 appSecret 明文
+async function session(ctx: ConnectorContext<D>): Promise<HttpAuth> {
+  const cached = await ctx.cache.getOrSet('session', 3000, async () => {
+    const signature = await ctx.crypto.hmac('sha256', ctx.secrets.appSecret, ctx.secrets.appKey);
+    const res = await ctx.http.get<TokenResponse>('https://api.kingdee.com/jdyconnector/app_management/kingdee_auth_token', {
+      query: { app_key: ctx.secrets.appKey, app_signature: signature },
+    });
+    if (res.data.errcode !== 0) throw new errors.AuthError(String(res.data.errcode));
+    return JSON.stringify({ headers: { 'app-token': res.data.data['app-token'] }, baseUrl: `https://${res.data.data.domain}` });
+  });
+  return JSON.parse(cached) as HttpAuth;
+}

package/test/fixtures/record-acceptance.ts

@@ -0,0 +1,32 @@
+/**
+ * 重新录制两个验收连接器的测试用例（需要本机 :15432 的 Postgres）：
+ *
+ *   bun packages/ontos-connector-sdk/test/fixtures/record-acceptance.ts
+ *
+ * 输出到 `test/fixtures/connectors/{http-pull,pg-pull}/streams/<数据流>/tests/<用例名>/`，提交进仓库，测试只回放不重录（http-pull 另有一条重录对比）。
+ */
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import type { ConnectorFixtureFile } from '../../src/testing';
+import {
+  dropPgSchema, HTTP_CASE_NAME, HTTP_PULL_DIR, PG_CASE_NAME, PG_PULL_DIR, preparePgSchema, recordHttpPull, recordPgPull,
+} from './acceptance';
+
+async function write(root: string, name: string, recorded: { files: ConnectorFixtureFile[]; result: { error: unknown; records: unknown[] } }): Promise<void> {
+  if (recorded.result.error) throw new Error(`recording ${name} failed: ${JSON.stringify(recorded.result.error)}`);
+  for (const file of recorded.files) await rm(path.dirname(path.join(root, file.path)), { recursive: true, force: true });
+  for (const file of recorded.files) {
+    const target = path.join(root, file.path);
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, file.content);
+  }
+  console.log(`${name}: ${recorded.result.records.length} record(s), ${recorded.files.map((file) => file.path).join(', ')}`);
+}
+
+await write(HTTP_PULL_DIR, HTTP_CASE_NAME, await recordHttpPull());
+if (!await preparePgSchema()) throw new Error('Postgres on localhost:15432 is not reachable');
+try {
+  await write(PG_PULL_DIR, PG_CASE_NAME, await recordPgPull());
+} finally {
+  await dropPgSchema();
+}