@synapsor/client 0.1.2 → 0.1.3

package/README.md

@@ -45,7 +45,7 @@ npm install @synapsor/client
 ```js
 import { Synapsor } from "@synapsor/client";
 
-const db = await Synapsor.connect("https://dev-api.synapsor.ai", {
+const db = await Synapsor.connect("https://synapsor.ai", {
   apiKey: process.env.SYNAPSOR_API_KEY,
 });
 
@@ -61,11 +61,112 @@ const ctx = await db.invokeAgentCapability("chat.prepare_llm_context", { questio
 
 Use database-scoped API keys from the Synapsor control panel for hosted projects.
 
+## Agent Workflows
+
+Use `agentRuns` when an agent framework owns routing, but Synapsor should own
+the durable workflow contract: session scope, capability calls, evidence,
+proposal branches, outbox actions, settlement, and replay.
+
+```js
+const run = await db.agentRuns.start({
+  workflow: "billing.late_fee_waiver_flow",
+  version: "2026-05-27",
+  input: { user_request: "Can we waive this late fee?" },
+});
+
+const answer = await run.invokeCapability("support.answer_ticket_question", {
+  stepKey: "answer_ticket_question",
+  arguments: { question: "Can we waive this late fee?" },
+  responseEnvelope: true,
+});
+
+const proposal = await run.invokeCapability("billing.propose_late_fee_waiver", {
+  stepKey: "propose_waiver",
+  arguments: { amount_cents: 2500 },
+  mode: "propose_only",
+  autoBranch: true,
+  responseEnvelope: true,
+});
+
+const action = await run.proposeExternalAction("stripe.issue_refund", {
+  stepKey: "refund_customer",
+  arguments: { charge_id: "ch_123", amount_cents: 2500 },
+  idempotencyKey: "refund:TCK_1001:2500",
+});
+
+await run.checkpoint("before_worker_claim", {
+  payload: { reason: "external action queued" },
+});
+await run.complete({ decision: "waiver_proposed" }, { status: "waiting_approval" });
+const graph = await run.explain();
+```
+
+Replay a stored capability run by using the numeric `agent_run_id` returned by
+Synapsor. Deterministic replay returns the captured persisted run; comparison
+modes can inspect the original snapshot, current state, a commit version, a
+timestamp, or a review branch.
+
+```js
+const replay = await db.replayAgentRun(123, {
+  mode: "original_snapshot",
+});
+
+const branchReplay = await db.replayAgentRun(123, {
+  mode: "branch",
+  branchName: "review_run_123",
+});
+```
+
+Workers should claim and confirm side effects through the outbox namespace:
+
+```js
+const task = await db.externalActions.claim({
+  queue: "billing_external_actions",
+  workerId: "billing-worker-1",
+});
+await db.externalActions.confirm(task.action_instance_id, {
+  status: "succeeded",
+  providerRequestId: "re_456",
+  response: { status: "succeeded" },
+});
+```
+
+## External DB Writeback Worker
+
+For existing Postgres/MySQL integrations, keep Synapsor in proposal mode. The
+agent stages an evidence-backed external write proposal, a human or settlement
+policy approves it, and a trusted worker in your app environment applies the
+approved change back to your existing database with parameterized SQL.
+
+```js
+import { createExternalDbWritebackWorker } from "@synapsor/client/external-db-writeback";
+
+const worker = createExternalDbWritebackWorker({
+  synapsorApiKey: process.env.SYNAPSOR_API_KEY,
+  sourceName: "app_postgres",
+  execute: async ({ sql, params }) => {
+    // Use your own Postgres/MySQL client here. The model never provides SQL.
+    return appDb.query(sql, params);
+  },
+});
+
+await worker.pollOnce();
+```
+
+The worker validates Synapsor-provided mapping metadata, only writes allowlisted
+columns, adds tenant and primary-key guards, checks optional conflict columns,
+and reports `applied`, `conflict`, or `failed` back to Synapsor idempotently.
+
 ## API Surface
 
 - `execute(sql)` and `query(sql)`
 - `setSession({...})`
 - `invokeAgentCapability(name, args, options)`
+- `agentRuns.start(...)`, `run.invokeCapability(...)`, `run.checkpoint(...)`, `run.complete(...)`, `run.explain(...)`
+- `replayAgentRun(id, { mode, version, timestamp, branchName })`
+- `externalActions.claim(...)` and `externalActions.confirm(...)`
+- `createAgentEval(...)` / `evals.create(...)` for run-history or `sourceTable` dataset evals
+- `evals.run(...).failures()`
 - `listCapabilities(query)`
 - `rememberFact({...})`
 - `proposeMemoryFact({...})`
@@ -77,6 +178,10 @@ Use database-scoped API keys from the Synapsor control panel for hosted projects
 - `checkFactForAction({...})`
 - branch helpers: `createBranch`, `useBranch`, `diffBranch`, `mergeBranch`, `dropBranch`
 - write lifecycle helpers: `previewWrite`, `approveWrite`, `commitWrite`, `rejectWrite`, `settleWrite`
+- external DB writeback worker: `createExternalDbWritebackWorker` from `@synapsor/client/external-db-writeback`
 - `readResource(uri)`
 
-Errors from Synapsor become `SynapsorError` with `status` and `payload`.
+Errors from Synapsor become `SynapsorError` with `status`, `code`,
+`requestId`, `retryable`, and the raw `payload`. Include `requestId` when
+opening support or incident tickets so server, gateway, and runtime logs can be
+joined without exposing secrets.

package/bin/synapsor.mjs

@@ -157,6 +157,49 @@ function mapError(error) {
   return String(error || "REQUEST_FAILED").toUpperCase();
 }
 
+function flagValue(args, names, fallback = "") {
+  const aliases = Array.isArray(names) ? names : [names];
+  for (let i = 0; i < args.length; i += 1) {
+    if (aliases.includes(args[i])) return args[i + 1] || fallback;
+  }
+  return fallback;
+}
+
+function csvFlag(args, name) {
+  const value = flagValue(args, name, "");
+  return value ? value.split(",").map((item) => item.trim()).filter(Boolean) : [];
+}
+
+function resolveSecretRef(value) {
+  const text = String(value || "").trim();
+  if (text.startsWith("env:")) {
+    const envName = text.slice(4);
+    const resolved = process.env[envName] || "";
+    if (!resolved) throw new Error(`SECRET_ENV_REQUIRED: ${envName} is not set`);
+    return resolved;
+  }
+  return text;
+}
+
+function scopedProject(globals) {
+  return globals.project || process.env.SYNAPSOR_PROJECT_ID || "";
+}
+
+function scopedDatabase(globals) {
+  return globals.db || process.env.SYNAPSOR_DATABASE_ID || "";
+}
+
+async function resolveSourceId(globals, nameOrId) {
+  const text = String(nameOrId || "").trim();
+  if (!text) throw new Error("SOURCE_REQUIRED: provide an external source name or source_id");
+  if (text.startsWith("src_")) return text;
+  const query = scopedProject(globals) ? `?project_id=${encodeURIComponent(scopedProject(globals))}` : "";
+  const listed = await request(globals, "GET", `/v1/control/external-sources${query}`);
+  const match = (listed.sources || []).find((source) => source.name === text || source.source_id === text);
+  if (!match) throw new Error(`NOT_FOUND: external source not found: ${text}`);
+  return match.source_id;
+}
+
 async function confirm(globals, label) {
   if (globals.yes) return;
   const rl = createInterface({ input, output });
@@ -221,6 +264,98 @@ async function main(argv = process.argv.slice(2)) {
     }
   }
 
+  if (cmd === "sources") {
+    if (sub === "list") {
+      const query = scopedProject(globals) ? `?project_id=${encodeURIComponent(scopedProject(globals))}` : "";
+      const payload = await request(globals, "GET", `/v1/control/external-sources${query}`);
+      return print(payload.sources || [], globals);
+    }
+    if (sub === "show") {
+      const sourceId = await resolveSourceId(globals, third);
+      return print(await request(globals, "GET", `/v1/control/external-sources/${encodeURIComponent(sourceId)}`), globals);
+    }
+    if (sub === "create" && ["postgres", "mysql"].includes(third)) {
+      const kind = third;
+      const defaultName = kind === "mysql" ? "app_mysql" : "app_postgres";
+      const envHint = kind === "mysql" ? "APP_MYSQL_URL" : "APP_POSTGRES_URL";
+      const name = flagValue(rest, "--name", defaultName);
+      const url = resolveSecretRef(flagValue(rest, "--url", ""));
+      const ssl = flagValue(rest, "--ssl", "require");
+      const mode = flagValue(rest, "--mode", "read-only");
+      const projectId = scopedProject(globals);
+      const databaseId = scopedDatabase(globals);
+      if (!projectId || !databaseId) throw new Error("PROJECT_AND_DATABASE_REQUIRED: use --project <project_id> --db <database_id> or SYNAPSOR_PROJECT_ID/SYNAPSOR_DATABASE_ID");
+      if (!url) throw new Error(`${kind.toUpperCase()}_URL_REQUIRED: usage \`synapsor sources create ${kind} --name ${defaultName} --url env:${envHint} --project <project> --db <database>\``);
+      return print(await request(globals, "POST", "/v1/control/external-sources", {
+        project_id: projectId,
+        database_id: databaseId,
+        kind,
+        name,
+        connection: { url, ssl_mode: ssl },
+        mode,
+      }), globals);
+    }
+    if (["test", "inspect", "generate", "doctor", "disable"].includes(sub)) {
+      const sourceId = await resolveSourceId(globals, third);
+      if (sub === "test") return print(await request(globals, "POST", `/v1/control/external-sources/${encodeURIComponent(sourceId)}/test`, {}), globals);
+      if (sub === "inspect") {
+        const schema = flagValue(rest, "--schema", "public");
+        const database = flagValue(rest, "--database", "");
+        const payload = database ? { database, include_views: true } : { schemas: [schema], include_views: true };
+        return print(await request(globals, "POST", `/v1/control/external-sources/${encodeURIComponent(sourceId)}/inspect`, payload), globals);
+      }
+      if (sub === "generate") {
+        const generated = await request(globals, "POST", `/v1/control/external-sources/${encodeURIComponent(sourceId)}/generate`, {
+          template: flagValue(rest, "--template", "support-ticket-agent"),
+          namespace: flagValue(rest, "--namespace", "support"),
+        });
+        const outDir = flagValue(rest, "--out", "");
+        if (outDir && Array.isArray(generated.files)) {
+          await mkdir(outDir, { recursive: true });
+          const written = [];
+          for (const file of generated.files) {
+            const relative = String(file.path || "generated.txt").replace(/^[/\\]+/, "").replace(/\.\.[/\\]/g, "");
+            const path = join(outDir, relative);
+            await mkdir(dirname(path), { recursive: true });
+            await writeFile(path, String(file.contents || ""));
+            written.push(path);
+          }
+          return print({ ok: true, source_id: generated.source_id, capability: generated.capability, out: outDir, files_written: written }, globals);
+        }
+        return print(generated, globals);
+      }
+      if (sub === "doctor") {
+        const database = flagValue(rest, "--database", "");
+        const payload = database ? { database } : { schemas: [flagValue(rest, "--schema", "public")] };
+        return print(await request(globals, "POST", `/v1/control/external-sources/${encodeURIComponent(sourceId)}/doctor`, payload), globals);
+      }
+      await confirm(globals, "Disabling an external source blocks future reads but keeps audit/evidence history.");
+      return print(await request(globals, "POST", `/v1/control/external-sources/${encodeURIComponent(sourceId)}/disable`, {}), globals);
+    }
+    if (sub === "import") {
+      const sourceId = await resolveSourceId(globals, third);
+      const schema = flagValue(rest, "--schema", "public");
+      const database = flagValue(rest, "--database", "");
+      const tables = csvFlag(rest, "--tables");
+      const tenantColumn = flagValue(rest, "--tenant-column", "");
+      const mode = flagValue(rest, "--mode", "live-read");
+      if (!tables.length) throw new Error("TABLES_REQUIRED: pass --tables tickets,customers,policy_chunks");
+      if (!tenantColumn && !rest.includes("--single-tenant")) throw new Error("TENANT_COLUMN_REQUIRED: pass --tenant-column tenant_id or --single-tenant");
+      return print(await request(globals, "POST", `/v1/control/external-sources/${encodeURIComponent(sourceId)}/import`, {
+        tables: tables.map((table) => ({
+          ...(database ? { database } : {}),
+          schema,
+          name: table,
+          alias_schema: flagValue(rest, "--alias-schema", database ? "external_shop" : "external_support"),
+          alias_name: table,
+          tenant_column: tenantColumn || undefined,
+          single_tenant: rest.includes("--single-tenant"),
+          mode,
+        })),
+      }), globals);
+    }
+  }
+
   if (cmd === "sql") {
     const db = globals.db || "";
     let sql = args.slice(1).join(" ").trim();
@@ -271,6 +406,19 @@ Usage:
   synapsor projects create <name>
   synapsor db list --project <project>
   synapsor db create <name> --project <project>
+  synapsor sources create postgres --name app_postgres --url env:APP_POSTGRES_URL --ssl require --mode read-only --project <project> --db <database>
+  synapsor sources create mysql --name app_mysql --url env:APP_MYSQL_URL --ssl require --mode read-only --project <project> --db <database>
+  synapsor sources test app_postgres --project <project>
+  synapsor sources inspect app_postgres --schema public --project <project>
+  synapsor sources inspect app_mysql --database shopdb --project <project>
+  synapsor sources import app_postgres --schema public --tables tickets,customers,policy_chunks --tenant-column tenant_id --project <project>
+  synapsor sources import app_mysql --database shopdb --tables orders,customers,refund_policies --tenant-column tenant_id --project <project>
+  synapsor sources generate app_postgres --template support-ticket-agent --namespace support --project <project>
+  synapsor sources generate app_mysql --template ecommerce-order-agent --namespace ecommerce --project <project>
+  synapsor sources list --project <project>
+  synapsor sources show app_postgres --project <project>
+  synapsor sources doctor app_postgres --project <project>
+  synapsor sources disable app_postgres --project <project> --yes
   synapsor sql --db <database> "SELECT 1;"
   synapsor sql --db <database> --file ./query.sql
   synapsor invoke <capability> --db <database> --json '{"ticket_id":"TICK-1001"}'

package/external-db-writeback.mjs

@@ -0,0 +1,266 @@
+function quoteIdentifier(kind, identifier) {
+  const text = String(identifier || "");
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(text)) {
+    throw new Error(`UNSAFE_IDENTIFIER: ${text}`);
+  }
+  return kind === "mysql" ? `\`${text}\`` : `"${text}"`;
+}
+
+function placeholder(kind, index) {
+  return kind === "mysql" ? "?" : `$${index}`;
+}
+
+function assertAllowedColumns(proposal, columns, label) {
+  const allowed = new Set((proposal.allowed_columns || []).map(String));
+  const blocked = columns.filter((column) => !allowed.has(String(column)));
+  if (blocked.length) {
+    throw new Error(`WRITEBACK_COLUMN_NOT_ALLOWED: ${label} ${blocked.join(",")}`);
+  }
+}
+
+export function buildExternalWritebackSql(proposal, { kind = undefined } = {}) {
+  const sourceKind = kind || proposal.source_kind || "postgres";
+  if (!["postgres", "mysql"].includes(sourceKind)) {
+    throw new Error(`UNSUPPORTED_WRITEBACK_KIND: ${sourceKind}`);
+  }
+  const operation = String(proposal.operation || "update").toLowerCase();
+  if (!["update", "insert", "delete"].includes(operation)) {
+    throw new Error(`UNSUPPORTED_WRITEBACK_OPERATION: ${operation}`);
+  }
+  const schema = String(proposal.external_schema || proposal.external_catalog || "");
+  const table = String(proposal.external_table || "");
+  if (!schema || !table) {
+    throw new Error("WRITEBACK_TABLE_REQUIRED: proposal must include external_schema and external_table");
+  }
+  const tableRef = `${quoteIdentifier(sourceKind, schema)}.${quoteIdentifier(sourceKind, table)}`;
+  const changes = proposal.changes && typeof proposal.changes === "object" ? proposal.changes : {};
+  const primaryKey = proposal.primary_key && typeof proposal.primary_key === "object" ? proposal.primary_key : {};
+  const conflict = proposal.conflict && typeof proposal.conflict === "object" ? proposal.conflict : {};
+  const tenantColumn = proposal.tenant_column ? String(proposal.tenant_column) : "";
+  const tenantId = proposal.tenant_id;
+  const conflictColumn = proposal.conflict_column ? String(proposal.conflict_column) : "";
+  const params = [];
+  const where = [];
+
+  function pushParam(value) {
+    params.push(value);
+    return placeholder(sourceKind, params.length);
+  }
+
+  function appendWhereClauses() {
+    for (const column of pkColumns) {
+      where.push(`${quoteIdentifier(sourceKind, column)} = ${pushParam(primaryKey[column])}`);
+    }
+    if (tenantColumn) {
+      assertAllowedColumns(proposal, [tenantColumn], "tenant");
+      where.push(`${quoteIdentifier(sourceKind, tenantColumn)} = ${pushParam(tenantId)}`);
+    }
+    if (conflictColumn && Object.prototype.hasOwnProperty.call(conflict, conflictColumn)) {
+      assertAllowedColumns(proposal, [conflictColumn], "conflict");
+      where.push(`${quoteIdentifier(sourceKind, conflictColumn)} = ${pushParam(conflict[conflictColumn])}`);
+    }
+  }
+
+  if (operation === "insert") {
+    const insertColumns = Object.keys(changes);
+    if (tenantColumn && !insertColumns.includes(tenantColumn)) {
+      insertColumns.push(tenantColumn);
+      changes[tenantColumn] = tenantId;
+    }
+    if (!insertColumns.length) {
+      throw new Error("WRITEBACK_INSERT_VALUES_REQUIRED");
+    }
+    assertAllowedColumns(proposal, insertColumns, "insert");
+    const columnSql = insertColumns.map((column) => quoteIdentifier(sourceKind, column)).join(", ");
+    const valueSql = insertColumns.map((column) => pushParam(changes[column])).join(", ");
+    return {
+      sql: `INSERT INTO ${tableRef} (${columnSql}) VALUES (${valueSql})`,
+      params,
+      operation,
+      expectedRowCount: 1,
+    };
+  }
+
+  const pkColumns = Object.keys(primaryKey);
+  if (!pkColumns.length) {
+    throw new Error("WRITEBACK_PRIMARY_KEY_REQUIRED");
+  }
+  assertAllowedColumns(proposal, pkColumns, "primary_key");
+
+  if (operation === "delete") {
+    appendWhereClauses();
+    return {
+      sql: `DELETE FROM ${tableRef} WHERE ${where.join(" AND ")}`,
+      params,
+      operation,
+      expectedRowCount: 1,
+    };
+  }
+
+  const changeColumns = Object.keys(changes);
+  if (!changeColumns.length) {
+    throw new Error("WRITEBACK_UPDATE_VALUES_REQUIRED");
+  }
+  assertAllowedColumns(proposal, changeColumns, "update");
+  const protectedColumns = new Set([...pkColumns, tenantColumn, conflictColumn].filter(Boolean));
+  const protectedChanges = changeColumns.filter((column) => protectedColumns.has(column));
+  if (protectedChanges.length) {
+    throw new Error(`WRITEBACK_PROTECTED_COLUMN_CHANGE: ${protectedChanges.join(",")}`);
+  }
+  const setSql = changeColumns
+    .map((column) => `${quoteIdentifier(sourceKind, column)} = ${pushParam(changes[column])}`)
+    .join(", ");
+  appendWhereClauses();
+  return {
+    sql: `UPDATE ${tableRef} SET ${setSql} WHERE ${where.join(" AND ")}`,
+    params,
+    operation,
+    expectedRowCount: 1,
+  };
+}
+
+async function request({ baseUrl, apiKey, fetchImpl }, method, path, body) {
+  const response = await fetchImpl(`${baseUrl.replace(/\/+$/, "")}${path}`, {
+    method,
+    headers: {
+      accept: "application/json",
+      authorization: `Bearer ${apiKey}`,
+      ...(body === undefined ? {} : { "content-type": "application/json" }),
+    },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  const text = await response.text();
+  let payload = {};
+  if (text.trim()) {
+    payload = JSON.parse(text);
+  }
+  if (!response.ok || payload.ok === false) {
+    const error = new Error(payload.message || payload.error || `HTTP ${response.status}`);
+    error.payload = payload;
+    throw error;
+  }
+  return payload;
+}
+
+function rowCountFromResult(result) {
+  if (typeof result === "number") return result;
+  if (!result || typeof result !== "object") return 0;
+  return Number(result.rowCount ?? result.affectedRows ?? result.rowsAffected ?? 0);
+}
+
+async function executeWithDb(db, built, proposal, kind) {
+  if (!db) {
+    throw new Error("WRITEBACK_EXECUTOR_REQUIRED: pass execute({sql, params}) or db client");
+  }
+  if (typeof db === "function") {
+    return db({ ...built, proposal, kind });
+  }
+  if (typeof db.execute === "function") {
+    return db.execute(built.sql, built.params);
+  }
+  if (typeof db.query === "function") {
+    return db.query(built.sql, built.params);
+  }
+  throw new Error("WRITEBACK_EXECUTOR_REQUIRED: db must expose execute() or query()");
+}
+
+export function createExternalDbWritebackWorker(options = {}) {
+  const {
+    baseUrl = "https://synapsor.ai",
+    synapsorApiKey = process.env.SYNAPSOR_API_KEY,
+    sourceId = "",
+    sourceName = "",
+    projectId = "",
+    kind = undefined,
+    db = undefined,
+    execute = undefined,
+    fetchImpl = globalThis.fetch,
+    pollIntervalMs = 5000,
+    dryRun = false,
+  } = options;
+  if (!synapsorApiKey) {
+    throw new Error("SYNAPSOR_API_KEY_REQUIRED");
+  }
+  if (!fetchImpl) {
+    throw new Error("FETCH_REQUIRED");
+  }
+  let stopped = false;
+  let timer = null;
+  const client = { baseUrl, apiKey: synapsorApiKey, fetchImpl };
+
+  async function resolveSourceId() {
+    if (sourceId) return sourceId;
+    if (!sourceName) return "";
+    const query = projectId ? `?project_id=${encodeURIComponent(projectId)}` : "";
+    const listed = await request(client, "GET", `/v1/control/external-sources${query}`);
+    const match = (listed.sources || []).find((source) => source.name === sourceName || source.source_id === sourceName);
+    if (!match) throw new Error(`SOURCE_NOT_FOUND: ${sourceName}`);
+    return match.source_id;
+  }
+
+  async function pollOnce() {
+    const resolvedSourceId = await resolveSourceId();
+    const params = new URLSearchParams();
+    if (resolvedSourceId) params.set("source_id", resolvedSourceId);
+    if (projectId) params.set("project_id", projectId);
+    params.set("status", "approved");
+    const listed = await request(client, "GET", `/v1/control/external-writebacks/proposals?${params.toString()}`);
+    const results = [];
+    for (const proposal of listed.proposals || []) {
+      const built = buildExternalWritebackSql(proposal, { kind: kind || proposal.source_kind });
+      if (dryRun) {
+        results.push({ proposal_id: proposal.proposal_id, dryRun: true, ...built });
+        continue;
+      }
+      try {
+        const rawResult = await executeWithDb(execute || db, built, proposal, kind || proposal.source_kind);
+        const affectedRows = rowCountFromResult(rawResult);
+        const status = affectedRows === built.expectedRowCount ? "applied" : "conflict";
+        const reported = await request(
+          client,
+          "POST",
+          `/v1/control/external-writebacks/proposals/${encodeURIComponent(proposal.proposal_id)}/apply-result`,
+          {
+            status,
+            idempotency_key: proposal.idempotency_key,
+            external_commit_metadata: {
+              affected_rows: String(affectedRows),
+              operation: built.operation,
+            },
+          },
+        );
+        results.push({ proposal_id: proposal.proposal_id, status, affectedRows, reported });
+      } catch (error) {
+        await request(
+          client,
+          "POST",
+          `/v1/control/external-writebacks/proposals/${encodeURIComponent(proposal.proposal_id)}/apply-result`,
+          {
+            status: "failed",
+            idempotency_key: proposal.idempotency_key,
+            error: error.message || String(error),
+          },
+        );
+        results.push({ proposal_id: proposal.proposal_id, status: "failed", error: error.message || String(error) });
+      }
+    }
+    return { ok: true, count: results.length, results };
+  }
+
+  async function start() {
+    stopped = false;
+    while (!stopped) {
+      await pollOnce();
+      await new Promise((resolve) => {
+        timer = setTimeout(resolve, pollIntervalMs);
+      });
+    }
+  }
+
+  function stop() {
+    stopped = true;
+    if (timer) clearTimeout(timer);
+  }
+
+  return { pollOnce, start, stop };
+}