@secondlayer/sdk 6.37.0 → 6.38.0

package/dist/sinks/kysely.d.ts

@@ -0,0 +1,108 @@
+import { Kysely, Transaction } from "kysely";
+/**
+* A consumer sink: the destination adapter a consume loop writes through.
+*
+* Without a sink, the user owns the three hard parts of a durable indexer —
+* checkpoint persistence, rows+cursor atomicity, and reorg rollback — and
+* the reasoning that makes them safe lives in doc comments. A sink owns all
+* three: the loop loads its committed cursor, hands the handler a
+* transaction, commits rows AND cursor atomically, and rolls back reorgs
+* without any user code. Crucially, a sink also closes the silent-skip
+* hazard where omitting `onReorg` meant reorgs were ignored forever: with a
+* sink attached, rollback is unconditional.
+*
+* The interface is dependency-free on purpose: implementations with real
+* database drivers live behind subpath exports (`@secondlayer/sdk/sinks/*`)
+* so the root entry ships no DB dependency.
+*/
+interface ConsumerSink<Tx = unknown> {
+	/** Phantom marker carrying `Tx` in a directly-inferable position, so the
+	*  consume loops' `TTx` type parameter resolves from the `sink` option
+	*  (never set at runtime). */
+	readonly _tx?: Tx;
+	/** The committed checkpoint, or `null` on first run. Called once, before
+	*  the first page. Implementations may create their checkpoint storage
+	*  here and SHOULD validate their rollback preconditions (e.g. that every
+	*  declared table carries the height column). */
+	loadCursor(): Promise<string | null>;
+	/**
+	* Apply one batch atomically: open a transaction, run `write(tx)` (the
+	* user's inserts), and commit the rows AND `cursor` together. A throw
+	* from `write` must abort the whole transaction — leaving neither rows
+	* nor cursor, so a crashed batch is simply re-read on restart.
+	*/
+	commitBatch(cursor: string, write: (tx: Tx) => Promise<void> | void): Promise<void>;
+	/**
+	* Roll the projection back to the fork: delete everything AT OR ABOVE
+	* `forkPointHeight` (inclusive `>=` — the new chain re-supplies the fork
+	* block) and commit `rewindCursor` in the SAME transaction. Deleting
+	* without the rewound cursor is the classic silent-gap bug: a crash
+	* between the two writes resumes above the fork and the deleted range is
+	* never re-read.
+	*/
+	rollback(forkPointHeight: number, rewindCursor: string): Promise<void>;
+}
+/**
+* Column present on EVERY declared table — `keyof` a union of row types is
+* the intersection of their keys, so a column missing from any one table is
+* a compile error at the `height:` option.
+*/
+type CommonColumn<
+	DB,
+	T extends keyof DB
+> = keyof DB[T] & string;
+interface KyselySinkOptions<
+	DB,
+	T extends keyof DB & string
+> {
+	/** Checkpoint identity AND concurrency key: the cursor row's primary key,
+	*  and the input to `pg_try_advisory_xact_lock(hashtext(id))` — a second
+	*  consumer with the same id fails loudly instead of double-writing. */
+	id: string;
+	/** Rollback scope. On a reorg, rows AT OR ABOVE the fork point are deleted
+	*  from exactly these tables (inclusive `>=` — the new chain re-supplies
+	*  the fork block). A table you write but don't declare keeps orphaned
+	*  rows forever, so declare everything the handler touches. */
+	tables: readonly T[];
+	/** The block-height stamp column, present on every declared table (compile
+	*  and first-use checked). Height-stamp rollback is correct for
+	*  APPEND-ONLY projections (one row per event/call); aggregates that
+	*  mutate rows (balances, counters) can't be rolled back this way — use a
+	*  subgraph for those. */
+	height: CommonColumn<DB, T>;
+	/** Checkpoint table name. Default `sl_consumer_checkpoints` (created on
+	*  first use). */
+	checkpointTable?: string;
+}
+/**
+* A {@link ConsumerSink} over a Kysely Postgres database — keyed on the
+* QUERY BUILDER (not the driver) so the `DB` schema generic flows through:
+* `tables` is `(keyof DB)[]`, `height` must exist on every declared table,
+* and `ctx.tx` inside `onBatch` is a fully typed `Transaction<DB>`.
+*
+* What it owns (so your indexer doesn't):
+* - the checkpoint table + cursor load on start;
+* - rows AND cursor committed in ONE transaction per batch — a handler
+*   throw aborts both, so a crashed batch is re-read on restart with no
+*   gaps and no double-writes;
+* - reorg rollback: delete `>= fork_point_height` from every declared table
+*   and commit the rewound cursor atomically (the crash-between-the-two-
+*   writes gap is unrepresentable);
+* - a per-id advisory lock, so two replicas of the same consumer can't
+*   interleave commits.
+*
+* ```ts
+* const sink = kyselySink(db, { id: "sales", tables: ["sales"], height: "block_height" });
+* await index.contractCalls.consume({
+*   contractId: MARKETPLACE, functionName: "purchase-asset", fromHeight: 0,
+*   sink,
+*   onBatch: (calls, _env, ctx) =>
+*     ctx.tx.insertInto("sales").values(calls.map(toSale)).execute(),
+* });
+* ```
+*/
+declare function kyselySink<
+	DB,
+	T extends keyof DB & string
+>(db: Kysely<DB>, options: KyselySinkOptions<DB, T>): ConsumerSink<Transaction<DB>>;
+export { kyselySink, KyselySinkOptions };

package/dist/sinks/kysely.js

@@ -0,0 +1,236 @@
+// src/sinks/kysely.ts
+import { sql } from "kysely";
+
+// src/errors.ts
+var DOCS_BASE = "https://www.secondlayer.tools";
+
+class SecondLayerError extends Error {
+  name = "SecondLayerError";
+  shortMessage;
+  code;
+  docsUrl;
+  metaMessages;
+  retryable;
+  retryAfterSeconds;
+  constructor(shortMessage, options = {}) {
+    const detailBlocks = [
+      ...options.metaMessages ?? [],
+      ...options.details ? [options.details] : [],
+      ...options.docsUrl ? [`Docs: ${options.docsUrl}`] : []
+    ];
+    const message = [
+      shortMessage,
+      detailBlocks.length > 0 ? `
+${detailBlocks.join(`
+`)}` : ""
+    ].join("");
+    super(message, options.cause ? { cause: options.cause } : undefined);
+    this.shortMessage = shortMessage;
+    this.code = options.code;
+    this.docsUrl = options.docsUrl;
+    this.metaMessages = options.metaMessages;
+    this.retryable = options.retryable ?? false;
+    this.retryAfterSeconds = options.retryAfterSeconds;
+  }
+  walk(fn) {
+    let err = this;
+    let last = this;
+    while (err != null) {
+      if (fn?.(err))
+        return err;
+      last = err;
+      err = err.cause;
+    }
+    return fn ? null : last;
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      shortMessage: this.shortMessage,
+      cause: this.cause instanceof Error ? this.cause.message : undefined,
+      code: this.code,
+      docsUrl: this.docsUrl,
+      retryable: this.retryable,
+      retryAfterSeconds: this.retryAfterSeconds
+    };
+  }
+}
+function statusRetryable(status) {
+  return status === 429 || status >= 500;
+}
+function docsFor(status, code) {
+  if (code === "UPGRADE_REQUIRED" || code === "PLAN_REQUIRED" || status === 402)
+    return `${DOCS_BASE}/docs/authentication#pay-as-you-go-credits`;
+  if (status === 429 || status === 401)
+    return `${DOCS_BASE}/docs/authentication`;
+  return;
+}
+
+class ApiError extends SecondLayerError {
+  status;
+  body;
+  constructor(status, message, body, code, options = {}) {
+    super(message, {
+      code,
+      retryable: options.retryable ?? statusRetryable(status),
+      docsUrl: options.docsUrl ?? docsFor(status, code),
+      ...options.cause ? { cause: options.cause } : {},
+      ...options.details ? { details: options.details } : {},
+      ...options.metaMessages ? { metaMessages: options.metaMessages } : {},
+      ...options.retryAfterSeconds !== undefined ? { retryAfterSeconds: options.retryAfterSeconds } : {}
+    });
+    this.status = status;
+    this.body = body;
+    this.name = "ApiError";
+  }
+}
+
+class AuthError extends ApiError {
+  status = 401;
+  constructor(message = "API key invalid or expired.") {
+    super(401, message);
+    this.name = "AuthError";
+  }
+}
+
+class RateLimitError extends ApiError {
+  retryAfter;
+  status = 429;
+  constructor(message = "Rate limited. Try again later.", retryAfter) {
+    super(429, message, undefined, undefined, {
+      retryable: true,
+      retryAfterSeconds: parseRetryAfter(retryAfter)
+    });
+    this.retryAfter = retryAfter;
+    this.name = "RateLimitError";
+  }
+}
+
+class ValidationError extends ApiError {
+  constructor(message, status, body) {
+    super(status, message, body, undefined, { retryable: false });
+    this.name = "ValidationError";
+  }
+}
+function parseRetryAfter(value) {
+  if (!value)
+    return;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0)
+    return seconds;
+  const date = Date.parse(value);
+  if (!Number.isNaN(date))
+    return Math.max(0, (date - Date.now()) / 1000);
+  return;
+}
+
+class VersionConflictError extends ApiError {
+  currentVersion;
+  expectedVersion;
+  constructor(currentVersion, expectedVersion, message = `Version conflict: expected ${expectedVersion}, current ${currentVersion}`) {
+    super(409, message, { currentVersion, expectedVersion });
+    this.currentVersion = currentVersion;
+    this.expectedVersion = expectedVersion;
+    this.name = "VersionConflictError";
+  }
+}
+
+class ByoBreakingChangeError extends ApiError {
+  details;
+  constructor(message, details) {
+    super(422, message, details, "BYO_BREAKING_CHANGE", {
+      metaMessages: [
+        "Review and run manually on your database:",
+        details.plan.dropStatement,
+        ...details.plan.statements
+      ]
+    });
+    this.name = "ByoBreakingChangeError";
+    this.details = details;
+  }
+}
+function isByoBreakingDetails(x) {
+  if (!x || typeof x !== "object")
+    return false;
+  const d = x;
+  const plan = d.plan;
+  return Array.isArray(d.reasons) && !!plan && typeof plan === "object" && typeof plan.dropStatement === "string";
+}
+
+// src/sinks/kysely.ts
+function kyselySink(db, options) {
+  const checkpointTable = options.checkpointTable ?? "sl_consumer_checkpoints";
+  if (options.tables.length === 0) {
+    throw new ValidationError("kyselySink: `tables` is empty — declare every table the handler writes, or reorg rollback is a no-op and orphaned rows persist forever.", 400);
+  }
+  const ident = (name) => {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+      throw new ValidationError(`kyselySink: invalid identifier "${name}" (letters, digits, underscores only).`, 400);
+    }
+    return `"${name}"`;
+  };
+  const cp = ident(checkpointTable);
+  const heightCol = ident(options.height);
+  for (const table of options.tables)
+    ident(table);
+  async function acquireLock(tx) {
+    const locked = await sql`
+			SELECT pg_try_advisory_xact_lock(hashtext(${options.id})) AS "ok"
+		`.execute(tx);
+    if (!locked.rows[0]?.ok) {
+      throw new ValidationError(`kyselySink: another consumer holds the "${options.id}" lock — two replicas of the same consumer would interleave commits. Stop the other instance or use a distinct id.`, 409);
+    }
+  }
+  async function upsertCursor(tx, cursor) {
+    await sql`
+			INSERT INTO ${sql.raw(cp)} (id, cursor) VALUES (${options.id}, ${cursor})
+			ON CONFLICT (id) DO UPDATE SET cursor = EXCLUDED.cursor
+		`.execute(tx);
+  }
+  return {
+    async loadCursor() {
+      await sql.raw(`CREATE TABLE IF NOT EXISTS ${cp} (id text PRIMARY KEY, cursor text NOT NULL)`).execute(db);
+      for (const table of options.tables) {
+        const col = await sql`
+					SELECT EXISTS (
+						SELECT 1 FROM information_schema.columns
+						WHERE table_name = ${table} AND column_name = ${options.height}
+					) AS "ok"
+				`.execute(db);
+        if (!col.rows[0]?.ok) {
+          throw new ValidationError(`kyselySink: table "${table}" has no "${String(options.height)}" column — the height stamp is what makes reorg rollback possible. Add the column (or fix \`height\`).`, 400);
+        }
+      }
+      const row = await sql`
+				SELECT cursor FROM ${sql.raw(cp)} WHERE id = ${options.id}
+			`.execute(db);
+      return row.rows[0]?.cursor ?? null;
+    },
+    async commitBatch(cursor, write) {
+      await db.transaction().execute(async (tx) => {
+        await acquireLock(tx);
+        await write(tx);
+        await upsertCursor(tx, cursor);
+      });
+    },
+    async rollback(forkPointHeight, rewindCursor) {
+      await db.transaction().execute(async (tx) => {
+        await acquireLock(tx);
+        for (const table of options.tables) {
+          await sql`
+						DELETE FROM ${sql.raw(ident(table))}
+						WHERE ${sql.raw(heightCol)} >= ${forkPointHeight}
+					`.execute(tx);
+        }
+        await upsertCursor(tx, rewindCursor);
+      });
+    }
+  };
+}
+export {
+  kyselySink
+};
+
+//# debugId=667BFBBF3BF09CCB64756E2164756E21
+//# sourceMappingURL=kysely.js.map

package/dist/sinks/kysely.js.map

@@ -0,0 +1,11 @@
+{
+  "version": 3,
+  "sources": ["../src/sinks/kysely.ts", "../src/errors.ts"],
+  "sourcesContent": [
+    "import { type Kysely, type Transaction, sql } from \"kysely\";\nimport { ValidationError } from \"../errors.ts\";\nimport type { ConsumerSink } from \"./types.ts\";\n\n/**\n * Column present on EVERY declared table — `keyof` a union of row types is\n * the intersection of their keys, so a column missing from any one table is\n * a compile error at the `height:` option.\n */\ntype CommonColumn<DB, T extends keyof DB> = keyof DB[T] & string;\n\nexport interface KyselySinkOptions<DB, T extends keyof DB & string> {\n\t/** Checkpoint identity AND concurrency key: the cursor row's primary key,\n\t *  and the input to `pg_try_advisory_xact_lock(hashtext(id))` — a second\n\t *  consumer with the same id fails loudly instead of double-writing. */\n\tid: string;\n\t/** Rollback scope. On a reorg, rows AT OR ABOVE the fork point are deleted\n\t *  from exactly these tables (inclusive `>=` — the new chain re-supplies\n\t *  the fork block). A table you write but don't declare keeps orphaned\n\t *  rows forever, so declare everything the handler touches. */\n\ttables: readonly T[];\n\t/** The block-height stamp column, present on every declared table (compile\n\t *  and first-use checked). Height-stamp rollback is correct for\n\t *  APPEND-ONLY projections (one row per event/call); aggregates that\n\t *  mutate rows (balances, counters) can't be rolled back this way — use a\n\t *  subgraph for those. */\n\theight: CommonColumn<DB, T>;\n\t/** Checkpoint table name. Default `sl_consumer_checkpoints` (created on\n\t *  first use). */\n\tcheckpointTable?: string;\n}\n\n/**\n * A {@link ConsumerSink} over a Kysely Postgres database — keyed on the\n * QUERY BUILDER (not the driver) so the `DB` schema generic flows through:\n * `tables` is `(keyof DB)[]`, `height` must exist on every declared table,\n * and `ctx.tx` inside `onBatch` is a fully typed `Transaction<DB>`.\n *\n * What it owns (so your indexer doesn't):\n * - the checkpoint table + cursor load on start;\n * - rows AND cursor committed in ONE transaction per batch — a handler\n *   throw aborts both, so a crashed batch is re-read on restart with no\n *   gaps and no double-writes;\n * - reorg rollback: delete `>= fork_point_height` from every declared table\n *   and commit the rewound cursor atomically (the crash-between-the-two-\n *   writes gap is unrepresentable);\n * - a per-id advisory lock, so two replicas of the same consumer can't\n *   interleave commits.\n *\n * ```ts\n * const sink = kyselySink(db, { id: \"sales\", tables: [\"sales\"], height: \"block_height\" });\n * await index.contractCalls.consume({\n *   contractId: MARKETPLACE, functionName: \"purchase-asset\", fromHeight: 0,\n *   sink,\n *   onBatch: (calls, _env, ctx) =>\n *     ctx.tx.insertInto(\"sales\").values(calls.map(toSale)).execute(),\n * });\n * ```\n */\nexport function kyselySink<DB, T extends keyof DB & string>(\n\tdb: Kysely<DB>,\n\toptions: KyselySinkOptions<DB, T>,\n): ConsumerSink<Transaction<DB>> {\n\tconst checkpointTable = options.checkpointTable ?? \"sl_consumer_checkpoints\";\n\tif (options.tables.length === 0) {\n\t\tthrow new ValidationError(\n\t\t\t\"kyselySink: `tables` is empty — declare every table the handler writes, or reorg rollback is a no-op and orphaned rows persist forever.\",\n\t\t\t400,\n\t\t);\n\t}\n\n\t/** `sql.raw`-safe identifier (we interpolate table/column names). */\n\tconst ident = (name: string): string => {\n\t\tif (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {\n\t\t\tthrow new ValidationError(\n\t\t\t\t`kyselySink: invalid identifier \"${name}\" (letters, digits, underscores only).`,\n\t\t\t\t400,\n\t\t\t);\n\t\t}\n\t\treturn `\"${name}\"`;\n\t};\n\tconst cp = ident(checkpointTable);\n\tconst heightCol = ident(options.height as string);\n\tfor (const table of options.tables) ident(table);\n\n\tasync function acquireLock(tx: Transaction<DB>): Promise<void> {\n\t\tconst locked = await sql<{ ok: boolean }>`\n\t\t\tSELECT pg_try_advisory_xact_lock(hashtext(${options.id})) AS \"ok\"\n\t\t`.execute(tx);\n\t\tif (!locked.rows[0]?.ok) {\n\t\t\tthrow new ValidationError(\n\t\t\t\t`kyselySink: another consumer holds the \"${options.id}\" lock — two replicas of the same consumer would interleave commits. Stop the other instance or use a distinct id.`,\n\t\t\t\t409,\n\t\t\t);\n\t\t}\n\t}\n\n\tasync function upsertCursor(\n\t\ttx: Transaction<DB>,\n\t\tcursor: string,\n\t): Promise<void> {\n\t\t// Identifiers via validated sql.raw; VALUES via bound parameters.\n\t\tawait sql`\n\t\t\tINSERT INTO ${sql.raw(cp)} (id, cursor) VALUES (${options.id}, ${cursor})\n\t\t\tON CONFLICT (id) DO UPDATE SET cursor = EXCLUDED.cursor\n\t\t`.execute(tx);\n\t}\n\n\treturn {\n\t\tasync loadCursor() {\n\t\t\tawait sql\n\t\t\t\t.raw(\n\t\t\t\t\t`CREATE TABLE IF NOT EXISTS ${cp} (id text PRIMARY KEY, cursor text NOT NULL)`,\n\t\t\t\t)\n\t\t\t\t.execute(db);\n\t\t\t// First-use validation of the rollback precondition: every declared\n\t\t\t// table must exist and carry the height column. Failing here beats a\n\t\t\t// rollback that silently deletes nothing during a reorg.\n\t\t\tfor (const table of options.tables) {\n\t\t\t\tconst col = await sql<{ ok: boolean }>`\n\t\t\t\t\tSELECT EXISTS (\n\t\t\t\t\t\tSELECT 1 FROM information_schema.columns\n\t\t\t\t\t\tWHERE table_name = ${table} AND column_name = ${options.height as string}\n\t\t\t\t\t) AS \"ok\"\n\t\t\t\t`.execute(db);\n\t\t\t\tif (!col.rows[0]?.ok) {\n\t\t\t\t\tthrow new ValidationError(\n\t\t\t\t\t\t`kyselySink: table \"${table}\" has no \"${String(options.height)}\" column — the height stamp is what makes reorg rollback possible. Add the column (or fix \\`height\\`).`,\n\t\t\t\t\t\t400,\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t}\n\t\t\tconst row = await sql<{ cursor: string }>`\n\t\t\t\tSELECT cursor FROM ${sql.raw(cp)} WHERE id = ${options.id}\n\t\t\t`.execute(db);\n\t\t\treturn row.rows[0]?.cursor ?? null;\n\t\t},\n\n\t\tasync commitBatch(cursor, write) {\n\t\t\tawait db.transaction().execute(async (tx) => {\n\t\t\t\tawait acquireLock(tx);\n\t\t\t\tawait write(tx);\n\t\t\t\tawait upsertCursor(tx, cursor);\n\t\t\t});\n\t\t},\n\n\t\tasync rollback(forkPointHeight, rewindCursor) {\n\t\t\tawait db.transaction().execute(async (tx) => {\n\t\t\t\tawait acquireLock(tx);\n\t\t\t\t// INCLUSIVE of the fork block: the new canonical chain re-supplies\n\t\t\t\t// it, and the consumer rewinds to re-read from `fork:0`.\n\t\t\t\tfor (const table of options.tables) {\n\t\t\t\t\t// Identifiers via validated sql.raw; the height bound as a parameter.\n\t\t\t\t\tawait sql`\n\t\t\t\t\t\tDELETE FROM ${sql.raw(ident(table))}\n\t\t\t\t\t\tWHERE ${sql.raw(heightCol)} >= ${forkPointHeight}\n\t\t\t\t\t`.execute(tx);\n\t\t\t\t}\n\t\t\t\tawait upsertCursor(tx, rewindCursor);\n\t\t\t});\n\t\t},\n\t};\n}\n",
+    "import type { ByoBreakingChangeDetails } from \"@secondlayer/shared/errors\";\n\nexport type { ByoBreakingChangeDetails };\n\nconst DOCS_BASE = \"https://www.secondlayer.tools\";\n\n/** Options accepted by every error in the family. */\nexport interface SecondLayerErrorOptions {\n\tcause?: Error;\n\tdetails?: string;\n\t/** Stable machine-readable code (e.g. `UPGRADE_REQUIRED`, `BYO_BREAKING_CHANGE`). */\n\tcode?: string;\n\t/** Docs page that explains this failure and its fix. */\n\tdocsUrl?: string;\n\t/** Extra context lines appended to the message (DDL to run, next steps). */\n\tmetaMessages?: string[];\n\t/** Whether retrying the SAME request can succeed (429/5xx/network). */\n\tretryable?: boolean;\n\t/** Parsed `Retry-After`, in seconds — set on rate limits that carry it. */\n\tretryAfterSeconds?: number;\n}\n\n/**\n * Root of the SDK error family. Implements the same protocol as `BaseError`\n * in `@secondlayer/stacks` (`shortMessage`, `cause`, `toJSON`) so a failed\n * chain read and a failed platform read serialize and introspect identically.\n * It intentionally does NOT extend that class: `BaseError.details` is a\n * `string`, while {@link ByoBreakingChangeError.details} is the documented\n * structured migration plan — and cross-package `instanceof` is unreliable\n * under per-package bundling anyway (match on `code`/`name` across packages).\n *\n * `retryable` is the signal the consume loops act on: 429/5xx/network are\n * retryable, 4xx and body-serialization failures are not.\n */\nexport class SecondLayerError extends Error {\n\toverride name = \"SecondLayerError\";\n\t/** The one-line failure, without the appended context blocks. */\n\tshortMessage: string;\n\tcode?: string;\n\tdocsUrl?: string;\n\tmetaMessages?: string[];\n\tretryable: boolean;\n\tretryAfterSeconds?: number;\n\n\tconstructor(shortMessage: string, options: SecondLayerErrorOptions = {}) {\n\t\tconst detailBlocks = [\n\t\t\t...(options.metaMessages ?? []),\n\t\t\t...(options.details ? [options.details] : []),\n\t\t\t...(options.docsUrl ? [`Docs: ${options.docsUrl}`] : []),\n\t\t];\n\t\tconst message = [\n\t\t\tshortMessage,\n\t\t\tdetailBlocks.length > 0 ? `\\n${detailBlocks.join(\"\\n\")}` : \"\",\n\t\t].join(\"\");\n\t\tsuper(message, options.cause ? { cause: options.cause } : undefined);\n\t\tthis.shortMessage = shortMessage;\n\t\tthis.code = options.code;\n\t\tthis.docsUrl = options.docsUrl;\n\t\tthis.metaMessages = options.metaMessages;\n\t\tthis.retryable = options.retryable ?? false;\n\t\tthis.retryAfterSeconds = options.retryAfterSeconds;\n\t}\n\n\t/**\n\t * Walk the cause chain. With a predicate, returns the first error matching\n\t * it (or `null`); without one, returns the deepest cause. Mirrors viem's\n\t * `error.walk()` so cross-library error handling reads the same.\n\t */\n\twalk(fn?: (err: unknown) => boolean): unknown {\n\t\t// biome-ignore lint/suspicious/noExplicitAny: cause chains are untyped by nature\n\t\tlet err: any = this;\n\t\tlet last: unknown = this;\n\t\twhile (err != null) {\n\t\t\tif (fn?.(err)) return err;\n\t\t\tlast = err;\n\t\t\terr = err.cause;\n\t\t}\n\t\treturn fn ? null : last;\n\t}\n\n\ttoJSON(): {\n\t\tname: string;\n\t\tmessage: string;\n\t\tshortMessage: string;\n\t\tcause: string | undefined;\n\t\tcode: string | undefined;\n\t\tdocsUrl: string | undefined;\n\t\tretryable: boolean;\n\t\tretryAfterSeconds: number | undefined;\n\t} {\n\t\treturn {\n\t\t\tname: this.name,\n\t\t\tmessage: this.message,\n\t\t\tshortMessage: this.shortMessage,\n\t\t\tcause: this.cause instanceof Error ? this.cause.message : undefined,\n\t\t\tcode: this.code,\n\t\t\tdocsUrl: this.docsUrl,\n\t\t\tretryable: this.retryable,\n\t\t\tretryAfterSeconds: this.retryAfterSeconds,\n\t\t};\n\t}\n}\n\n/** Retryability of an HTTP status: 429 and 5xx are transient. */\nfunction statusRetryable(status: number): boolean {\n\treturn status === 429 || status >= 500;\n}\n\n/** Docs page for a status/code pair, when one exists. */\nfunction docsFor(status: number, code?: string): string | undefined {\n\tif (code === \"UPGRADE_REQUIRED\" || code === \"PLAN_REQUIRED\" || status === 402)\n\t\treturn `${DOCS_BASE}/docs/authentication#pay-as-you-go-credits`;\n\tif (status === 429 || status === 401)\n\t\treturn `${DOCS_BASE}/docs/authentication`;\n\treturn undefined;\n}\n\n/**\n * Error thrown by {@link SecondLayer} when an API request fails.\n * Includes the HTTP status code for programmatic error handling.\n *\n * @example\n * ```ts\n * try {\n *   await client.subgraphs.get(\"my-subgraph\");\n * } catch (err) {\n *   if (err instanceof ApiError && err.status === 404) {\n *     console.log(\"Subgraph not found\");\n *   }\n * }\n * ```\n */\nexport class ApiError extends SecondLayerError {\n\tconstructor(\n\t\t/** HTTP status code (0 for network errors). */\n\t\tpublic status: number,\n\t\tmessage: string,\n\t\t/** Raw response body (parsed JSON if possible) — preserved for callers that need error details. */\n\t\tpublic body?: unknown,\n\t\t/** Stable machine-readable code from the API's `{error, code}` error envelope. */\n\t\tcode?: string,\n\t\toptions: SecondLayerErrorOptions = {},\n\t) {\n\t\tsuper(message, {\n\t\t\tcode,\n\t\t\tretryable: options.retryable ?? statusRetryable(status),\n\t\t\tdocsUrl: options.docsUrl ?? docsFor(status, code),\n\t\t\t...(options.cause ? { cause: options.cause } : {}),\n\t\t\t...(options.details ? { details: options.details } : {}),\n\t\t\t...(options.metaMessages ? { metaMessages: options.metaMessages } : {}),\n\t\t\t...(options.retryAfterSeconds !== undefined\n\t\t\t\t? { retryAfterSeconds: options.retryAfterSeconds }\n\t\t\t\t: {}),\n\t\t});\n\t\tthis.name = \"ApiError\";\n\t}\n}\n\n/** Thrown on a 401 — by both the platform clients and Streams. */\nexport class AuthError extends ApiError {\n\toverride readonly status = 401 as const;\n\n\tconstructor(message = \"API key invalid or expired.\") {\n\t\tsuper(401, message);\n\t\tthis.name = \"AuthError\";\n\t}\n}\n\n/** Thrown on a 429 — by both the platform clients and Streams. `retryable`,\n *  with `retryAfterSeconds` parsed from the `Retry-After` header when sent. */\nexport class RateLimitError extends ApiError {\n\toverride readonly status = 429 as const;\n\n\tconstructor(\n\t\tmessage = \"Rate limited. Try again later.\",\n\t\t/** Raw `Retry-After` header value (seconds or HTTP-date). */\n\t\treadonly retryAfter?: string,\n\t) {\n\t\tsuper(429, message, undefined, undefined, {\n\t\t\tretryable: true,\n\t\t\tretryAfterSeconds: parseRetryAfter(retryAfter),\n\t\t});\n\t\tthis.name = \"RateLimitError\";\n\t}\n}\n\n/** Thrown on a 4xx the caller can fix (bad cursor, bad params). Never retried. */\nexport class ValidationError extends ApiError {\n\tconstructor(message: string, status: number, body?: unknown) {\n\t\tsuper(status, message, body, undefined, { retryable: false });\n\t\tthis.name = \"ValidationError\";\n\t}\n}\n\n/** Parse a `Retry-After` header: delta-seconds or an HTTP-date. */\nexport function parseRetryAfter(value?: string | null): number | undefined {\n\tif (!value) return undefined;\n\tconst seconds = Number(value);\n\tif (Number.isFinite(seconds) && seconds >= 0) return seconds;\n\tconst date = Date.parse(value);\n\tif (!Number.isNaN(date)) return Math.max(0, (date - Date.now()) / 1000);\n\treturn undefined;\n}\n\n/**\n * Thrown on optimistic-concurrency conflict when a deploy supplies an\n * `expectedVersion` that no longer matches the server's stored version.\n */\nexport class VersionConflictError extends ApiError {\n\tconstructor(\n\t\tpublic currentVersion: string,\n\t\tpublic expectedVersion: string,\n\t\tmessage = `Version conflict: expected ${expectedVersion}, current ${currentVersion}`,\n\t) {\n\t\tsuper(409, message, { currentVersion, expectedVersion });\n\t\tthis.name = \"VersionConflictError\";\n\t}\n}\n\n/**\n * Thrown when a BYO subgraph deploy is refused for a breaking schema change.\n * The deploy did NOT run — `details.plan` carries the DROP + rebuild DDL to run\n * manually on your own database, plus the breaking `reasons` and the `diff`.\n * The same DDL is surfaced on `metaMessages`, so a bare `console.error(err)`\n * already shows the operator what to run.\n *\n * @example\n * ```ts\n * try {\n *   await client.subgraphs.deploy(bundle);\n * } catch (err) {\n *   if (err instanceof ByoBreakingChangeError) {\n *     console.log(err.details.plan.dropStatement);\n *     console.log(err.details.plan.statements.join(\";\\n\"));\n *   }\n * }\n * ```\n */\nexport class ByoBreakingChangeError extends ApiError {\n\treadonly details: ByoBreakingChangeDetails;\n\tconstructor(message: string, details: ByoBreakingChangeDetails) {\n\t\tsuper(422, message, details, \"BYO_BREAKING_CHANGE\", {\n\t\t\tmetaMessages: [\n\t\t\t\t\"Review and run manually on your database:\",\n\t\t\t\tdetails.plan.dropStatement,\n\t\t\t\t...details.plan.statements,\n\t\t\t],\n\t\t});\n\t\tthis.name = \"ByoBreakingChangeError\";\n\t\tthis.details = details;\n\t}\n}\n\n/** Narrow an unknown error body's `details` to {@link ByoBreakingChangeDetails}. */\nexport function isByoBreakingDetails(\n\tx: unknown,\n): x is ByoBreakingChangeDetails {\n\tif (!x || typeof x !== \"object\") return false;\n\tconst d = x as Record<string, unknown>;\n\tconst plan = d.plan as Record<string, unknown> | undefined;\n\treturn (\n\t\tArray.isArray(d.reasons) &&\n\t\t!!plan &&\n\t\ttypeof plan === \"object\" &&\n\t\ttypeof plan.dropStatement === \"string\"\n\t);\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "667BFBBF3BF09CCB64756E2164756E21",
+  "names": []
+}

package/dist/streams/index.d.ts

@@ -1,4 +1,145 @@
 import { STREAMS_EVENT_TYPES, StreamsEventType } from "@secondlayer/shared";
+/**
+* A consumer sink: the destination adapter a consume loop writes through.
+*
+* Without a sink, the user owns the three hard parts of a durable indexer —
+* checkpoint persistence, rows+cursor atomicity, and reorg rollback — and
+* the reasoning that makes them safe lives in doc comments. A sink owns all
+* three: the loop loads its committed cursor, hands the handler a
+* transaction, commits rows AND cursor atomically, and rolls back reorgs
+* without any user code. Crucially, a sink also closes the silent-skip
+* hazard where omitting `onReorg` meant reorgs were ignored forever: with a
+* sink attached, rollback is unconditional.
+*
+* The interface is dependency-free on purpose: implementations with real
+* database drivers live behind subpath exports (`@secondlayer/sdk/sinks/*`)
+* so the root entry ships no DB dependency.
+*/
+interface ConsumerSink<Tx = unknown> {
+	/** Phantom marker carrying `Tx` in a directly-inferable position, so the
+	*  consume loops' `TTx` type parameter resolves from the `sink` option
+	*  (never set at runtime). */
+	readonly _tx?: Tx;
+	/** The committed checkpoint, or `null` on first run. Called once, before
+	*  the first page. Implementations may create their checkpoint storage
+	*  here and SHOULD validate their rollback preconditions (e.g. that every
+	*  declared table carries the height column). */
+	loadCursor(): Promise<string | null>;
+	/**
+	* Apply one batch atomically: open a transaction, run `write(tx)` (the
+	* user's inserts), and commit the rows AND `cursor` together. A throw
+	* from `write` must abort the whole transaction — leaving neither rows
+	* nor cursor, so a crashed batch is simply re-read on restart.
+	*/
+	commitBatch(cursor: string, write: (tx: Tx) => Promise<void> | void): Promise<void>;
+	/**
+	* Roll the projection back to the fork: delete everything AT OR ABOVE
+	* `forkPointHeight` (inclusive `>=` — the new chain re-supplies the fork
+	* block) and commit `rewindCursor` in the SAME transaction. Deleting
+	* without the rewound cursor is the classic silent-gap bug: a crash
+	* between the two writes resumes above the fork and the deleted range is
+	* never re-read.
+	*/
+	rollback(forkPointHeight: number, rewindCursor: string): Promise<void>;
+}
+/** `ctx` gains `tx` exactly when a sink is attached; without one the shape
+*  is unchanged (an intersection with `unknown` is an identity, so
+*  contextual typing of `onBatch` callbacks never degrades to a union). */
+type WithSinkTx<TTx> = [TTx] extends [never] ? unknown : {
+	tx: TTx
+};
+type IndexEventBase = {
+	cursor: string
+	block_height: number
+	block_time?: string | null
+	tx_id: string
+	tx_index: number
+	event_index: number
+	contract_id: string | null
+	/** Submitting-transaction context, present only when `txContext: true` was
+	*  requested. `tx_sender` is the real tx sender — distinct from a transfer's
+	*  asset `sender`, and the only place a `print` event's sender is available.
+	*  Lets a consumer build per-event tx context without a `/v1/index/transactions`
+	*  call per event. */
+	tx_sender?: string | null
+	tx_type?: string | null
+	tx_status?: string | null
+	tx_contract_id?: string | null
+	tx_function_name?: string | null
+};
+type IndexFtTransfer = IndexEventBase & {
+	event_type: "ft_transfer"
+	asset_identifier: string
+	sender: string
+	recipient: string
+	amount: string
+};
+type IndexNftTransfer = IndexEventBase & {
+	event_type: "nft_transfer"
+	asset_identifier: string
+	sender: string
+	recipient: string
+	value: string
+};
+type IndexStxTransfer = IndexEventBase & {
+	event_type: "stx_transfer"
+	sender: string
+	recipient: string
+	amount: string
+	memo: string | null
+};
+type IndexStxMint = IndexEventBase & {
+	event_type: "stx_mint"
+	recipient: string
+	amount: string
+};
+type IndexStxBurn = IndexEventBase & {
+	event_type: "stx_burn"
+	sender: string
+	amount: string
+};
+type IndexStxLock = IndexEventBase & {
+	event_type: "stx_lock"
+	sender: string
+	amount: string
+	payload: {
+		unlock_height: string | null
+	}
+};
+type IndexFtMint = IndexEventBase & {
+	event_type: "ft_mint"
+	asset_identifier: string
+	recipient: string
+	amount: string
+};
+type IndexFtBurn = IndexEventBase & {
+	event_type: "ft_burn"
+	asset_identifier: string
+	sender: string
+	amount: string
+};
+type IndexNftMint = IndexEventBase & {
+	event_type: "nft_mint"
+	asset_identifier: string
+	recipient: string
+	value: string
+};
+type IndexNftBurn = IndexEventBase & {
+	event_type: "nft_burn"
+	asset_identifier: string
+	sender: string
+	value: string
+};
+type IndexPrint = IndexEventBase & {
+	event_type: "print"
+	payload: {
+		topic: string | null
+		value: unknown
+		raw_value: string | null
+	}
+};
+/** Decoded chain event, discriminated by `event_type`. */
+type IndexEvent = IndexFtTransfer | IndexNftTransfer | IndexStxTransfer | IndexStxMint | IndexStxBurn | IndexStxLock | IndexFtMint | IndexFtBurn | IndexNftMint | IndexNftBurn | IndexPrint;
 /** A Clarity value as Streams serves it: the canonical hex string, a typed
 *  object carrying that hex (`{ hex }`), or a decoded Clarity-JSON object.
 *  Decode helpers (`decodeNftTransfer`, etc.) resolve it to a concrete value. */
@@ -243,8 +384,28 @@ type StreamsBatchContext = ConsumerBatchContext;
 type StreamsReorgContext = {
 	cursor: string
 };
-type StreamsEventsConsumeParams = {
+type StreamsEventsConsumeParams<
+	TTx = never,
+	D extends boolean = false
+> = {
 	fromCursor?: string | null
+	/**
+	* Deliver events pre-decoded as the flat, `event_type`-discriminated rows
+	* Index serves (`IndexEvent`), so Streams consumption reads identically
+	* to Index consumption — no guard+decode pairs in your handler.
+	*/
+	decoded?: D
+	/**
+	* Destination adapter that owns the checkpoint + rollback transaction
+	* (e.g. `kyselySink` from `@secondlayer/sdk/sinks/kysely`). With a sink:
+	* the loop resumes from the sink's committed cursor, `onBatch` receives
+	* `ctx.tx` and must write ONLY through it (rows and cursor commit in one
+	* transaction), reorg rollback is automatic, and `onBatch`'s return value
+	* is ignored.
+	*/
+	sink?: ConsumerSink<TTx>
+	/** Fires once per page, before `onBatch` and before any early return. */
+	onProgress?: (ctx: ConsumerBatchContext) => void
 	mode?: "tail" | "bounded"
 	/**
 	* Emit only finalized (immutable) events and never surface reorgs. The SDK
@@ -265,7 +426,7 @@ type StreamsEventsConsumeParams = {
 	* transaction as your writes. Returning a cursor overrides `ctx.cursor` as
 	* the resume point (advanced manual control); returning nothing uses it.
 	*/
-	onBatch: (events: StreamsEvent[], envelope: StreamsEventsEnvelope, ctx: StreamsBatchContext) => void | string | null | undefined | Promise<void> | Promise<string | null | undefined>
+	onBatch: (events: D extends true ? IndexEvent[] : StreamsEvent[], envelope: StreamsEventsEnvelope, ctx: StreamsBatchContext & WithSinkTx<TTx>) => void | string | null | undefined | Promise<void> | Promise<string | null | undefined>
 	/**
 	* Roll your projection back to `reorg.fork_point_height`, persisting
 	* `ctx.cursor` in the same transaction. Called once per *new* reorg
@@ -351,7 +512,7 @@ type StreamsEventsReplayParams = {
 	maxEmptyPolls?: number
 	signal?: AbortSignal
 };
-type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+type FetchLike2 = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 /** One bulk parquet file in the dumps manifest. `path` is the object key under
 *  the dumps base URL. */
 type StreamsDumpFile = {
@@ -423,7 +584,12 @@ type StreamsClient = {
 		* The consumer also exits when `maxPages`, `maxEmptyPolls`, or `signal`
 		* stops it.
 		*/
-		consume(params: StreamsEventsConsumeParams): Promise<StreamsEventsConsumeResult>
+		consume<
+			TTx = never,
+			D extends boolean = false
+		>(params: StreamsEventsConsumeParams<TTx, D> & {
+			sink?: ConsumerSink<TTx>
+		}): Promise<StreamsEventsConsumeResult>
 		/**
 		* Backfill from bulk dumps, then continue live from the dump→live seam in
 		* one call. Iterates finalized dump files (via `onDumpFile`) in block
@@ -476,7 +642,7 @@ type StreamsUsage = {
 type CreateStreamsClientOptions = {
 	apiKey: string
 	baseUrl?: string
-	fetchImpl?: FetchLike
+	fetchImpl?: FetchLike2
 	/**
 	* Public base URL for bulk parquet dumps (the R2/CDN bucket root). Required
 	* to use `client.dumps`. See `GET /public/streams/dumps/manifest`.
@@ -512,6 +678,22 @@ type CreateStreamsClientOptions = {
 	verifyDumpsManifest?: boolean
 };
 declare function createStreamsClient(options: CreateStreamsClientOptions): StreamsClient;
+/**
+* Decode a raw Streams event into the SAME flat, `event_type`-discriminated
+* row shape Index serves — so Streams consumption reads identically to Index
+* consumption, with one call instead of eleven guard+decode pairs.
+*
+* ```ts
+* for (const event of envelope.events) {
+*   const row = decode(event);
+*   if (row.event_type === "ft_transfer") row.amount; // string, narrowed
+* }
+* ```
+*
+* Prefer `decoded: true` on `streams.events.consume` — then decoding never
+* appears in your code at all.
+*/
+declare function decode(event: StreamsEvent): IndexEvent;
 /** Options accepted by every error in the family. */
 interface SecondLayerErrorOptions {
 	cause?: Error;
@@ -893,4 +1075,4 @@ declare const Cursor: {
 	}
 };
 type DecodedEventRow = DecodedFtTransfer | DecodedNftTransfer | DecodedStxTransfer | DecodedStxMint | DecodedStxBurn | DecodedStxLock | DecodedFtMint | DecodedFtBurn | DecodedNftMint | DecodedNftBurn | DecodedPrint;
-export { isStxTransfer, isStxMint, isStxLock, isStxBurn, isPrint, isNftTransfer, isNftMint, isNftBurn, isFtTransfer, isFtMint, isFtBurn, decodeStxTransfer, decodeStxMint, decodeStxLock, decodeStxBurn, decodePrint, decodeNftTransfer, decodeNftMint, decodeNftBurn, decodeFtTransfer, decodeFtMint, decodeFtBurn, createStreamsClient, ValidationError, StreamsUsage, StreamsTip, StreamsSignatureError, StreamsServerError, StreamsReorgsListParams, StreamsReorgsListEnvelope, StreamsReorgContext, StreamsReorg, StreamsEventsSubscribeParams, StreamsEventsStreamParams, StreamsEventsListParams, StreamsEventsListEnvelope, StreamsEventsEnvelope, StreamsEventsConsumeResult, StreamsEventsConsumeParams, StreamsEventType, StreamsEventPayload, StreamsEvent, StreamsDumpsManifest, StreamsDumps, StreamsDumpFile, StreamsConsumeParams, StreamsClient, StreamsCanonicalBlock, StreamsBatchContext, StreamsBatch, STREAMS_EVENT_TYPES, RateLimitError, NftTransferPayload, NftTransferEvent, FtTransferPayload, FtTransferEvent, FetchLike, DecodedStxTransferPayload, DecodedStxTransfer, DecodedStxMintPayload, DecodedStxMint, DecodedStxLockPayload, DecodedStxLock, DecodedStxBurnPayload, DecodedStxBurn, DecodedPrintValue, DecodedPrintPayload, DecodedPrint, DecodedNftTransferPayload, DecodedNftTransfer, DecodedNftMintPayload, DecodedNftMint, DecodedNftBurnPayload, DecodedNftBurn, DecodedFtTransferPayload, DecodedFtTransfer, DecodedFtMintPayload, DecodedFtMint, DecodedFtBurnPayload, DecodedFtBurn, DecodedEventRow, DecodedEventColumns, Cursor, ConsumerBatchContext, AuthError };
+export { isStxTransfer, isStxMint, isStxLock, isStxBurn, isPrint, isNftTransfer, isNftMint, isNftBurn, isFtTransfer, isFtMint, isFtBurn, decodeStxTransfer, decodeStxMint, decodeStxLock, decodeStxBurn, decodePrint, decodeNftTransfer, decodeNftMint, decodeNftBurn, decodeFtTransfer, decodeFtMint, decodeFtBurn, decode, createStreamsClient, ValidationError, StreamsUsage, StreamsTip, StreamsSignatureError, StreamsServerError, StreamsReorgsListParams, StreamsReorgsListEnvelope, StreamsReorgContext, StreamsReorg, StreamsEventsSubscribeParams, StreamsEventsStreamParams, StreamsEventsListParams, StreamsEventsListEnvelope, StreamsEventsEnvelope, StreamsEventsConsumeResult, StreamsEventsConsumeParams, StreamsEventType, StreamsEventPayload, StreamsEvent, StreamsDumpsManifest, StreamsDumps, StreamsDumpFile, StreamsConsumeParams, StreamsClient, StreamsCanonicalBlock, StreamsBatchContext, StreamsBatch, STREAMS_EVENT_TYPES, RateLimitError, NftTransferPayload, NftTransferEvent, FtTransferPayload, FtTransferEvent, FetchLike2 as FetchLike, DecodedStxTransferPayload, DecodedStxTransfer, DecodedStxMintPayload, DecodedStxMint, DecodedStxLockPayload, DecodedStxLock, DecodedStxBurnPayload, DecodedStxBurn, DecodedPrintValue, DecodedPrintPayload, DecodedPrint, DecodedNftTransferPayload, DecodedNftTransfer, DecodedNftMintPayload, DecodedNftMint, DecodedNftBurnPayload, DecodedNftBurn, DecodedFtTransferPayload, DecodedFtTransfer, DecodedFtMintPayload, DecodedFtMint, DecodedFtBurnPayload, DecodedFtBurn, DecodedEventRow, DecodedEventColumns, Cursor, ConsumerBatchContext, AuthError };