@secondlayer/sdk 6.40.1 → 6.41.0

package/AGENTS.md

@@ -0,0 +1,107 @@
+# @secondlayer/sdk — notes for coding agents
+
+Five facts that are load-bearing. Everything else you can infer from the types;
+these you cannot, and getting them wrong produces code that looks correct and
+silently loses or corrupts data.
+
+## 1. Reads need no key
+
+`/v1/index/*` and the public subgraph reads are open. Construct the client with
+no credentials and start reading:
+
+```ts
+import { Index } from "@secondlayer/sdk";
+
+const sl = new Index();
+const { events } = await sl.events.list({ eventType: "ft_transfer" });
+```
+
+Keys are for Streams, writes, and higher rate limits. Do not invent an
+`apiKey` requirement or send a placeholder — an empty Bearer is worse than none.
+
+## 2. Cursors are opaque
+
+A cursor is `"<block_height>:<event_index>"`, and that is an implementation
+detail you may read but must never construct, parse into, or compare
+arithmetically. Pass back exactly what you were handed:
+
+```ts
+let cursor: string | null = null;
+for (;;) {
+  const page = await sl.events.list({ eventType: "ft_transfer", cursor });
+  if (page.events.length === 0) break;
+  cursor = page.next_cursor;      // ✓
+  // cursor = `${lastHeight}:0`;  // ✗ — skips events, silently
+}
+```
+
+`Cursor.atHeight(h)` exists for "start at the foot of block h"; use it rather
+than hand-rolling a sentinel.
+
+## 3. Reorg rollback is INCLUSIVE
+
+`onReorg` hands you `reorg.fork_point_height`. Delete rows at
+`_block_height >= forkHeight`, not `>`. The fork block itself is replaced, so an
+exclusive delete leaves exactly one block of orphaned rows behind — the hardest
+kind of corruption to notice, because everything downstream still looks
+consistent.
+
+```ts
+onReorg: async (reorg, ctx) => {
+  await tx.deleteFrom("my_rows").where("height", ">=", reorg.fork_point_height).execute();
+  await saveCursor(tx, ctx.cursor);
+},
+```
+
+## 4. Rows and the cursor commit in ONE transaction
+
+If they commit separately, a crash between them either replays a batch (double
+counts) or skips it (missing rows). There is no ordering that avoids both.
+
+Prefer a sink, which owns this by construction — you write rows, it commits them
+with the checkpoint and handles the rollback:
+
+```ts
+import { kyselySink } from "@secondlayer/sdk/sinks/kysely";
+
+await sl.streams.events.consume({
+  sink: kyselySink(db, { id: "my-indexer", tables: ["transfers"], height: "height" }),
+  onBatch: async (events, _envelope, ctx) => {
+    for (const e of events) await ctx.tx.insertInto("transfers").values(...).execute();
+  },
+});
+```
+
+Hand-rolling it is allowed, but the checkpoint write must be inside the same
+transaction as the row writes.
+
+## 5. `walk()` is not reorg-safe
+
+`walk()` iterates a fixed range for backfills and analysis. It does not surface
+reorgs and does not rewind. Anything writing durable state off the tip belongs
+in `consume()` with `onReorg` (or a sink). Use `walk()` for history that is
+already final.
+
+---
+
+## Shapes worth knowing
+
+- **`decoded: true`** on `streams.events.consume` delivers the flat,
+  `event_type`-discriminated rows Index serves, so Streams and Index handlers
+  read identically. Prefer it over the individual `is*`/`decode*` helpers.
+- **Labelled filters**: `filters: { <label>: {...} }` plus `on: { <label>: handler }`
+  runs two unrelated concerns through one loop, one cursor, one checkpoint. Each
+  label's declared `types` narrows its handler.
+- **Field selection**: `fields: ["recipient", "amount"]` on Index reads projects
+  the SELECT server-side; unrequested columns are absent from the row *and* the
+  type. `cursor`, `block_height`, and `event_type` always come back.
+- **Errors**: everything derives from `SecondLayerError` — `code`, `retryable`,
+  `retryAfterSeconds`, `docsUrl`, and `walk(predicate)` to find a cause. Retries
+  are built in (`retryCount`/`retryDelay`); `onError` is a void observer, not a
+  retry decision.
+
+## More
+
+- Docs, full text: <https://secondlayer.tools/llms-full.txt>
+- Any page as markdown: append `.md` (e.g. `/docs/streams.md`)
+- Deeper agent skill: `bunx skills add ryanwaits/secondlayer`

package/dist/index.d.ts

@@ -1375,7 +1375,7 @@ type EventsWalkParams<T extends IndexEventType = IndexEventType> = Omit<EventsLi
 type EventsConsumeParams<
 	T extends IndexEventType = IndexEventType,
 	TTx = never
-> = Omit<EventsListParams<T>, "cursor" | "fromCursor" | "limit"> & IndexConsumeOptions<IndexEventOf<T>, EventsEnvelope<T>, TTx>;
+> = Omit<EventsListParams<T>, "cursor" | "fromCursor" | "limit" | "fields"> & IndexConsumeOptions<IndexEventOf<T>, EventsEnvelope<T>, TTx>;
 type IndexContractCall = {
 	cursor: string
 	block_height: number
@@ -2066,6 +2066,14 @@ interface NftTransfersResource {
 }
 /** `index.events` — callable shorthand for `.list()`; `eventType` is required. */
 interface IndexEventsResource {
+	/** Narrowing overload for the callable shorthand — same wire path as
+	*  `list`, so it must narrow identically. */
+	<
+		T extends IndexEventType,
+		const F extends keyof IndexEventOf<T> & string
+	>(params: EventsListParams<T> & {
+		fields: readonly F[]
+	}): Promise<EventsEnvelope<T, IndexEventFields<T, F>>>;
 	<T extends IndexEventType>(params: EventsListParams<T>): Promise<EventsEnvelope<T>>;
 	/** Narrowing overload: `fields` shrinks the returned row type to exactly
 	*  the requested columns plus {@link IndexAlwaysFields}. `const F` means no
@@ -2077,6 +2085,15 @@ interface IndexEventsResource {
 		fields: readonly F[]
 	}): Promise<EventsEnvelope<T, IndexEventFields<T, F>>>;
 	list<T extends IndexEventType>(params: EventsListParams<T>): Promise<EventsEnvelope<T>>;
+	/** Narrowing overload, matching `list`: `walk` forwards `fields` to the
+	*  wire, so without this the yielded rows are stripped while the type
+	*  still promises every column. */
+	walk<
+		T extends IndexEventType,
+		const F extends keyof IndexEventOf<T> & string
+	>(params: EventsWalkParams<T> & {
+		fields: readonly F[]
+	}): AsyncIterable<IndexEventFields<T, F>>;
 	walk<T extends IndexEventType>(params: EventsWalkParams<T>): AsyncIterable<IndexEventOf<T>>;
 	consume<
 		T extends IndexEventType,