@secondlayer/sdk 3.4.0 → 3.5.0

package/README.md

@@ -19,28 +19,48 @@ const sl = new SecondLayer({
 });
 ```
 
+## Mental model
+
+- `sl.streams` reads raw ordered L1 events from Stacks Streams.
+- `sl.index` reads decoded L2 FT/NFT transfer events from Stacks Index.
+- `sl.subgraphs` reads app-specific L3 tables from Stacks Subgraphs.
+
 ## Stacks Streams
 
-Typed HTTP client.
+Typed L1 HTTP client.
 
 `sk-sl_streams_status_public` is a public, non-secret Free-tier key used by the
 Second Layer status page. Production apps should use their own Streams API key.
 
+```typescript
+const tip = await sl.streams.tip();
+const page = await sl.streams.events.list({
+  types: ["ft_transfer"],
+  contractId: "SP...sbtc-token",
+  limit: 10,
+});
+
+console.log({ tip, firstCursor: page.events[0]?.cursor });
+```
+
+`createStreamsClient` remains available for focused Streams-only consumers:
+
 ```typescript
 import { createStreamsClient } from "@secondlayer/sdk";
 
-const client = createStreamsClient({
+const streams = createStreamsClient({
   apiKey: process.env.SECONDLAYER_API_KEY!,
-  baseUrl: process.env.SECONDLAYER_API_URL,
 });
+```
 
-const tip = await client.tip();
-const page = await client.events.list({
-  types: ["ft_transfer"],
-  limit: 10,
-});
+Convenience reads:
 
-console.log({ tip, firstCursor: page.events[0]?.cursor });
+```typescript
+await sl.streams.canonical(182431);
+await sl.streams.events.byTxId("0x...");
+await sl.streams.blocks.events(182431);
+await sl.streams.blocks.events("0xindex-block-hash");
+await sl.streams.reorgs.list({ since: "2026-05-03T00:00:00.000Z" });
 ```
 
 Checkpointed consumer.
@@ -120,9 +140,37 @@ the decoder. Decoders throw when the event type or payload is malformed. Add new
 helpers beside `src/streams/ft-transfer.ts` and export them through
 `src/streams/index.ts`.
 
-## Subgraphs
+## Stacks Index
 
-Deploy and query subgraphs (custom indexers).
+Decoded L2 transfer events.
+
+```typescript
+const ftPage = await sl.index.ftTransfers.list({
+  contractId: "SP...sbtc-token",
+  sender: "SP...",
+  limit: 100,
+});
+
+const nftPage = await sl.index.nftTransfers.list({
+  assetIdentifier: "SP...collection::token",
+  recipient: "SP...",
+});
+```
+
+Backfill with SDK walkers:
+
+```typescript
+for await (const transfer of sl.index.ftTransfers.walk({
+  fromHeight: 0,
+  batchSize: 500,
+})) {
+  console.log(transfer.cursor, transfer.amount);
+}
+```
+
+## Stacks Subgraphs
+
+Deploy and query app-specific L3 tables.
 
 ```typescript
 // List
@@ -138,6 +186,15 @@ const rows = await sl.subgraphs.queryTable("my-subgraph", "transfers", {
   limit: 50,
 });
 
+const { count } = await sl.subgraphs.queryTableCount(
+  "my-subgraph",
+  "transfers",
+);
+
+const spec = await sl.subgraphs.openapi("my-subgraph");
+const source = await sl.subgraphs.getSource("my-subgraph");
+const gaps = await sl.subgraphs.gaps("my-subgraph");
+
 // Deploy
 const result = await sl.subgraphs.deploy({ name, sources, schema, handlerCode });
 ```

package/dist/index.d.ts

@@ -2,11 +2,14 @@ import { ReindexResponse, SubgraphDetail, SubgraphGapsResponse, SubgraphQueryPar
 import { DeploySubgraphRequest, DeploySubgraphResponse } from "@secondlayer/shared/schemas/subgraphs";
 import { SubgraphAgentSchema, SubgraphSpecOptions } from "@secondlayer/shared/subgraphs/spec";
 import { InferSubgraphClient } from "@secondlayer/subgraphs";
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 interface SecondLayerOptions {
 	/** Base URL of the Secondlayer API (trailing slashes are stripped). */
 	baseUrl: string;
 	/** Bearer token for authenticated requests. */
 	apiKey?: string;
+	/** Fetch implementation. Tests and edge runtimes can provide their own. */
+	fetchImpl?: FetchLike;
 	/** Deploy origin label sent as `x-sl-origin` (telemetry). Defaults to `cli`. */
 	origin?: "cli" | "mcp" | "session";
 }
@@ -188,59 +191,6 @@ declare class Index extends BaseClient {
 	private walkFtTransfers;
 	private walkNftTransfers;
 }
-import { CreateSubscriptionRequest, CreateSubscriptionResponse, DeadRow, DeliveryRow, ReplayResult, RotateSecretResponse, SubscriptionDetail, SubscriptionSummary, UpdateSubscriptionRequest } from "@secondlayer/shared/schemas/subscriptions";
-import { CreateSubscriptionRequest as CreateSubscriptionRequest2, CreateSubscriptionResponse as CreateSubscriptionResponse2, DeadRow as DeadRow2, DeliveryRow as DeliveryRow2, ReplayResult as ReplayResult2, RotateSecretResponse as RotateSecretResponse2, SubscriptionDetail as SubscriptionDetail2, SubscriptionFormat, SubscriptionRuntime, SubscriptionStatus, SubscriptionSummary as SubscriptionSummary2, UpdateSubscriptionRequest as UpdateSubscriptionRequest2 } from "@secondlayer/shared/schemas/subscriptions";
-declare class Subscriptions extends BaseClient {
-	list(): Promise<{
-		data: SubscriptionSummary[]
-	}>;
-	get(id: string): Promise<SubscriptionDetail>;
-	create(input: CreateSubscriptionRequest): Promise<CreateSubscriptionResponse>;
-	update(id: string, patch: UpdateSubscriptionRequest): Promise<SubscriptionDetail>;
-	pause(id: string): Promise<SubscriptionDetail>;
-	resume(id: string): Promise<SubscriptionDetail>;
-	delete(id: string): Promise<{
-		ok: true
-	}>;
-	rotateSecret(id: string): Promise<RotateSecretResponse>;
-	recentDeliveries(id: string): Promise<{
-		data: DeliveryRow[]
-	}>;
-	replay(id: string, range: {
-		fromBlock: number
-		toBlock: number
-	}): Promise<ReplayResult>;
-	dead(id: string): Promise<{
-		data: DeadRow[]
-	}>;
-	requeueDead(id: string, outboxId: string): Promise<{
-		ok: true
-	}>;
-}
-declare class SecondLayer extends BaseClient {
-	readonly index: Index;
-	readonly subgraphs: Subgraphs;
-	readonly subscriptions: Subscriptions;
-	constructor(options?: Partial<SecondLayerOptions>);
-}
-/**
-* Returns a typed client for a subgraph defined with `defineSubgraph()`.
-*
-* Accepts a plain options object, a `SecondLayer` instance, or a `Subgraphs` instance.
-*
-* @example
-* ```ts
-* import mySubgraph from './subgraphs/my-subgraph'
-* import { getSubgraph } from '@secondlayer/sdk'
-*
-* const client = getSubgraph(mySubgraph, { apiKey: 'sl_...' })
-* const rows = await client.transfers.findMany({ where: { sender: 'SP...' } })
-* ```
-*/
-declare function getSubgraph<T extends {
-	name: string
-	schema: Record<string, unknown>
-}>(def: T, options?: Partial<SecondLayerOptions> | SecondLayer | Subgraphs): InferSubgraphClient2<T>;
 declare const STREAMS_EVENT_TYPES: readonly ["stx_transfer", "stx_mint", "stx_burn", "stx_lock", "ft_transfer", "ft_mint", "ft_burn", "nft_transfer", "nft_mint", "nft_burn", "print"];
 type StreamsEventType = (typeof STREAMS_EVENT_TYPES)[number];
 type StreamsEventPayload = Record<string, unknown>;
@@ -263,6 +213,13 @@ type StreamsTip = {
 	burn_block_height: number
 	lag_seconds: number
 };
+type StreamsCanonicalBlock = {
+	block_height: number
+	index_block_hash: string
+	burn_block_height: number
+	burn_block_hash: string | null
+	is_canonical: true
+};
 type StreamsReorg = {
 	detected_at: string
 	fork_point_height: number
@@ -278,11 +235,21 @@ type StreamsEventsEnvelope = {
 	tip: StreamsTip
 	reorgs: StreamsReorg[]
 };
+type StreamsEventsListEnvelope = Omit<StreamsEventsEnvelope, "next_cursor">;
+type StreamsReorgsListParams = {
+	since: string
+	limit?: number
+};
+type StreamsReorgsListEnvelope = {
+	reorgs: StreamsReorg[]
+	next_since: string | null
+};
 type StreamsEventsListParams = {
 	cursor?: string | null
 	fromHeight?: number
 	toHeight?: number
 	types?: readonly StreamsEventType[]
+	contractId?: string
 	limit?: number
 };
 type StreamsEventsStreamParams = {
@@ -310,10 +277,11 @@ type StreamsEventsConsumeResult = {
 	pages: number
 	emptyPolls: number
 };
-type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+type FetchLike2 = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 type StreamsClient = {
 	events: {
 		list(params?: StreamsEventsListParams): Promise<StreamsEventsEnvelope>
+		byTxId(txId: string): Promise<StreamsEventsListEnvelope>
 		/**
 		* Pull pages from Streams and call `onBatch` after each page.
 		*
@@ -333,12 +301,73 @@ type StreamsClient = {
 		*/
 		stream(params?: StreamsEventsStreamParams): AsyncIterable<StreamsEvent>
 	}
+	blocks: {
+		events(heightOrHash: number | string): Promise<StreamsEventsListEnvelope>
+	}
+	reorgs: {
+		list(params: StreamsReorgsListParams): Promise<StreamsReorgsListEnvelope>
+	}
+	canonical(height: number): Promise<StreamsCanonicalBlock>
 	tip(): Promise<StreamsTip>
 };
+import { CreateSubscriptionRequest, CreateSubscriptionResponse, DeadRow, DeliveryRow, ReplayResult, RotateSecretResponse, SubscriptionDetail, SubscriptionSummary, UpdateSubscriptionRequest } from "@secondlayer/shared/schemas/subscriptions";
+import { CreateSubscriptionRequest as CreateSubscriptionRequest2, CreateSubscriptionResponse as CreateSubscriptionResponse2, DeadRow as DeadRow2, DeliveryRow as DeliveryRow2, ReplayResult as ReplayResult2, RotateSecretResponse as RotateSecretResponse2, SubscriptionDetail as SubscriptionDetail2, SubscriptionFormat, SubscriptionRuntime, SubscriptionStatus, SubscriptionSummary as SubscriptionSummary2, UpdateSubscriptionRequest as UpdateSubscriptionRequest2 } from "@secondlayer/shared/schemas/subscriptions";
+declare class Subscriptions extends BaseClient {
+	list(): Promise<{
+		data: SubscriptionSummary[]
+	}>;
+	get(id: string): Promise<SubscriptionDetail>;
+	create(input: CreateSubscriptionRequest): Promise<CreateSubscriptionResponse>;
+	update(id: string, patch: UpdateSubscriptionRequest): Promise<SubscriptionDetail>;
+	pause(id: string): Promise<SubscriptionDetail>;
+	resume(id: string): Promise<SubscriptionDetail>;
+	delete(id: string): Promise<{
+		ok: true
+	}>;
+	rotateSecret(id: string): Promise<RotateSecretResponse>;
+	recentDeliveries(id: string): Promise<{
+		data: DeliveryRow[]
+	}>;
+	replay(id: string, range: {
+		fromBlock: number
+		toBlock: number
+	}): Promise<ReplayResult>;
+	dead(id: string): Promise<{
+		data: DeadRow[]
+	}>;
+	requeueDead(id: string, outboxId: string): Promise<{
+		ok: true
+	}>;
+}
+declare class SecondLayer extends BaseClient {
+	readonly streams: StreamsClient;
+	readonly index: Index;
+	readonly subgraphs: Subgraphs;
+	readonly subscriptions: Subscriptions;
+	constructor(options?: Partial<SecondLayerOptions>);
+}
+/**
+* Returns a typed client for a subgraph defined with `defineSubgraph()`.
+*
+* Accepts a plain options object, a `SecondLayer` instance, or a `Subgraphs` instance.
+*
+* @example
+* ```ts
+* import mySubgraph from './subgraphs/my-subgraph'
+* import { getSubgraph } from '@secondlayer/sdk'
+*
+* const client = getSubgraph(mySubgraph, { apiKey: 'sl_...' })
+* const rows = await client.transfers.findMany({ where: { sender: 'SP...' } })
+* ```
+*/
+declare function getSubgraph<T extends {
+	name: string
+	schema: Record<string, unknown>
+}>(def: T, options?: Partial<SecondLayerOptions> | SecondLayer | Subgraphs): InferSubgraphClient2<T>;
 type CreateStreamsClientOptions = {
 	apiKey: string
 	baseUrl?: string
-	fetchImpl?: FetchLike
+	fetchImpl?: FetchLike2
 };
 declare function createStreamsClient(options: CreateStreamsClientOptions): StreamsClient;
 declare class AuthError extends Error {
@@ -483,4 +512,4 @@ declare class VersionConflictError extends ApiError {
 * ```
 */
 declare function verifyWebhookSignature(rawBody: string, signatureHeader: string, secret: string, toleranceSeconds?: number): boolean;
-export { verifyWebhookSignature, isNftTransfer, isFtTransfer, getSubgraph, decodeNftTransfer, decodeFtTransfer, createStreamsClient, VersionConflictError, ValidationError, UpdateSubscriptionRequest2 as UpdateSubscriptionRequest, Subscriptions, SubscriptionSummary2 as SubscriptionSummary, SubscriptionStatus, SubscriptionRuntime, SubscriptionFormat, SubscriptionDetail2 as SubscriptionDetail, Subgraphs, SubgraphSpecOptions3 as SubgraphSpecOptions, SubgraphSpecFormat2 as SubgraphSpecFormat, SubgraphAgentSchema3 as SubgraphAgentSchema, StreamsTip, StreamsServerError, StreamsReorg, StreamsEventsStreamParams, StreamsEventsListParams, StreamsEventsEnvelope, StreamsEventsConsumeResult, StreamsEventsConsumeParams, StreamsEventType, StreamsEventPayload, StreamsEvent, StreamsClient, SecondLayerOptions, SecondLayer, RotateSecretResponse2 as RotateSecretResponse, ReplayResult2 as ReplayResult, RateLimitError, NftTransfersWalkParams, NftTransfersListParams, NftTransfersEnvelope, NftTransferPayload, NftTransferEvent, NftTransfer, IndexTip, Index, FtTransfersWalkParams, FtTransfersListParams, FtTransfersEnvelope, FtTransferPayload, FtTransferEvent, FtTransfer, FetchLike, DeliveryRow2 as DeliveryRow, DecodedNftTransferPayload, DecodedNftTransfer, DecodedFtTransferPayload, DecodedFtTransfer, DecodedEventRow, DeadRow2 as DeadRow, CreateSubscriptionResponse2 as CreateSubscriptionResponse, CreateSubscriptionRequest2 as CreateSubscriptionRequest, AuthError, ApiError };
+export { verifyWebhookSignature, isNftTransfer, isFtTransfer, getSubgraph, decodeNftTransfer, decodeFtTransfer, createStreamsClient, VersionConflictError, ValidationError, UpdateSubscriptionRequest2 as UpdateSubscriptionRequest, Subscriptions, SubscriptionSummary2 as SubscriptionSummary, SubscriptionStatus, SubscriptionRuntime, SubscriptionFormat, SubscriptionDetail2 as SubscriptionDetail, Subgraphs, SubgraphSpecOptions3 as SubgraphSpecOptions, SubgraphSpecFormat2 as SubgraphSpecFormat, SubgraphAgentSchema3 as SubgraphAgentSchema, StreamsTip, StreamsServerError, StreamsReorgsListParams, StreamsReorgsListEnvelope, StreamsReorg, StreamsEventsStreamParams, StreamsEventsListParams, StreamsEventsListEnvelope, StreamsEventsEnvelope, StreamsEventsConsumeResult, StreamsEventsConsumeParams, StreamsEventType, StreamsEventPayload, StreamsEvent, StreamsClient, StreamsCanonicalBlock, SecondLayerOptions, SecondLayer, RotateSecretResponse2 as RotateSecretResponse, ReplayResult2 as ReplayResult, RateLimitError, NftTransfersWalkParams, NftTransfersListParams, NftTransfersEnvelope, NftTransferPayload, NftTransferEvent, NftTransfer, IndexTip, Index, FtTransfersWalkParams, FtTransfersListParams, FtTransfersEnvelope, FtTransferPayload, FtTransferEvent, FtTransfer, FetchLike2 as FetchLike, DeliveryRow2 as DeliveryRow, DecodedNftTransferPayload, DecodedNftTransfer, DecodedFtTransferPayload, DecodedFtTransfer, DecodedEventRow, DeadRow2 as DeadRow, CreateSubscriptionResponse2 as CreateSubscriptionResponse, CreateSubscriptionRequest2 as CreateSubscriptionRequest, AuthError, ApiError };

package/dist/index.js

@@ -381,69 +381,6 @@ class Index extends BaseClient {
   }
 }
 
-// src/subscriptions/client.ts
-class Subscriptions extends BaseClient {
-  async list() {
-    return this.request("GET", "/api/subscriptions");
-  }
-  async get(id) {
-    return this.request("GET", `/api/subscriptions/${id}`);
-  }
-  async create(input) {
-    return this.request("POST", "/api/subscriptions", input);
-  }
-  async update(id, patch) {
-    return this.request("PATCH", `/api/subscriptions/${id}`, patch);
-  }
-  async pause(id) {
-    return this.request("POST", `/api/subscriptions/${id}/pause`);
-  }
-  async resume(id) {
-    return this.request("POST", `/api/subscriptions/${id}/resume`);
-  }
-  async delete(id) {
-    return this.request("DELETE", `/api/subscriptions/${id}`);
-  }
-  async rotateSecret(id) {
-    return this.request("POST", `/api/subscriptions/${id}/rotate-secret`);
-  }
-  async recentDeliveries(id) {
-    return this.request("GET", `/api/subscriptions/${id}/deliveries`);
-  }
-  async replay(id, range) {
-    return this.request("POST", `/api/subscriptions/${id}/replay`, range);
-  }
-  async dead(id) {
-    return this.request("GET", `/api/subscriptions/${id}/dead`);
-  }
-  async requeueDead(id, outboxId) {
-    return this.request("POST", `/api/subscriptions/${id}/dead/${outboxId}/requeue`);
-  }
-}
-
-// src/client.ts
-class SecondLayer extends BaseClient {
-  index;
-  subgraphs;
-  subscriptions;
-  constructor(options = {}) {
-    super(options);
-    this.index = new Index(options);
-    this.subgraphs = new Subgraphs(options);
-    this.subscriptions = new Subscriptions(options);
-  }
-}
-
-// src/subgraphs/get-subgraph.ts
-function getSubgraph(def, options = {}) {
-  if (options instanceof Subgraphs) {
-    return options.typed(def);
-  }
-  if (options instanceof SecondLayer) {
-    return options.subgraphs.typed(def);
-  }
-  return new Subgraphs(options).typed(def);
-}
 // src/streams/consumer.ts
 async function defaultSleep(ms, signal) {
   if (signal?.aborted)
@@ -640,6 +577,7 @@ function createStreamsClient(options) {
     appendSearchParam2(searchParams, "from_height", params.fromHeight);
     appendSearchParam2(searchParams, "to_height", params.toHeight);
     appendSearchParam2(searchParams, "limit", params.limit);
+    appendSearchParam2(searchParams, "contract_id", params.contractId);
     if (params.types?.length) {
       searchParams.set("types", params.types.join(","));
     }
@@ -649,6 +587,9 @@ function createStreamsClient(options) {
   return {
     events: {
       list: listEvents,
+      byTxId(txId) {
+        return request(`/v1/streams/events/${encodeURIComponent(txId)}`);
+      },
       consume(params) {
         return consumeStreamsEvents({
           fromCursor: params.fromCursor,
@@ -676,11 +617,98 @@ function createStreamsClient(options) {
         });
       }
     },
+    blocks: {
+      events(heightOrHash) {
+        return request(`/v1/streams/blocks/${encodeURIComponent(String(heightOrHash))}/events`);
+      }
+    },
+    reorgs: {
+      list(params) {
+        const searchParams = new URLSearchParams;
+        appendSearchParam2(searchParams, "since", params.since);
+        appendSearchParam2(searchParams, "limit", params.limit);
+        const query = searchParams.toString();
+        return request(`/v1/streams/reorgs${query ? `?${query}` : ""}`);
+      }
+    },
+    canonical(height) {
+      return request(`/v1/streams/canonical/${height}`);
+    },
     tip() {
       return request("/v1/streams/tip");
     }
   };
 }
+
+// src/subscriptions/client.ts
+class Subscriptions extends BaseClient {
+  async list() {
+    return this.request("GET", "/api/subscriptions");
+  }
+  async get(id) {
+    return this.request("GET", `/api/subscriptions/${id}`);
+  }
+  async create(input) {
+    return this.request("POST", "/api/subscriptions", input);
+  }
+  async update(id, patch) {
+    return this.request("PATCH", `/api/subscriptions/${id}`, patch);
+  }
+  async pause(id) {
+    return this.request("POST", `/api/subscriptions/${id}/pause`);
+  }
+  async resume(id) {
+    return this.request("POST", `/api/subscriptions/${id}/resume`);
+  }
+  async delete(id) {
+    return this.request("DELETE", `/api/subscriptions/${id}`);
+  }
+  async rotateSecret(id) {
+    return this.request("POST", `/api/subscriptions/${id}/rotate-secret`);
+  }
+  async recentDeliveries(id) {
+    return this.request("GET", `/api/subscriptions/${id}/deliveries`);
+  }
+  async replay(id, range) {
+    return this.request("POST", `/api/subscriptions/${id}/replay`, range);
+  }
+  async dead(id) {
+    return this.request("GET", `/api/subscriptions/${id}/dead`);
+  }
+  async requeueDead(id, outboxId) {
+    return this.request("POST", `/api/subscriptions/${id}/dead/${outboxId}/requeue`);
+  }
+}
+
+// src/client.ts
+class SecondLayer extends BaseClient {
+  streams;
+  index;
+  subgraphs;
+  subscriptions;
+  constructor(options = {}) {
+    super(options);
+    this.streams = createStreamsClient({
+      apiKey: options.apiKey ?? "",
+      baseUrl: options.baseUrl,
+      fetchImpl: options.fetchImpl
+    });
+    this.index = new Index(options);
+    this.subgraphs = new Subgraphs(options);
+    this.subscriptions = new Subscriptions(options);
+  }
+}
+
+// src/subgraphs/get-subgraph.ts
+function getSubgraph(def, options = {}) {
+  if (options instanceof Subgraphs) {
+    return options.typed(def);
+  }
+  if (options instanceof SecondLayer) {
+    return options.subgraphs.typed(def);
+  }
+  return new Subgraphs(options).typed(def);
+}
 // src/streams/ft-transfer.ts
 function requireString(payload, field) {
   const value = payload[field];
@@ -832,5 +860,5 @@ export {
   ApiError
 };
 
-//# debugId=2771C8998C150B3F64756E2164756E21
+//# debugId=EEEF1F40FE614E8264756E2164756E21
 //# sourceMappingURL=index.js.map