@secondlayer/sdk 3.3.2 → 3.5.0

package/README.md

@@ -19,9 +19,158 @@ const sl = new SecondLayer({
 });
 ```
 
-## Subgraphs
+## Mental model
 
-Deploy and query subgraphs (custom indexers).
+- `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 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 streams = createStreamsClient({
+  apiKey: process.env.SECONDLAYER_API_KEY!,
+});
+```
+
+Convenience reads:
+
+```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.
+
+Use `client.events.consume` for indexers and ETL jobs. Write your database rows
+inside `onBatch`, then return the cursor you committed. It exits when
+`maxPages`, `maxEmptyPolls`, or `signal` stops it.
+
+```typescript
+import { createStreamsClient } from "@secondlayer/sdk";
+
+const client = createStreamsClient({
+  apiKey: process.env.SECONDLAYER_API_KEY!,
+});
+
+await client.events.consume({
+  types: ["ft_transfer"],
+  batchSize: 100,
+  maxPages: 1,
+  onBatch: async (events, envelope) => {
+    for (const event of events) {
+      console.log(event.cursor, event.tx_id);
+    }
+    return envelope.next_cursor;
+  },
+});
+```
+
+Live stream.
+
+Use `client.events.stream` for live processors and watch-style apps. It follows
+the tip indefinitely. Stop it with an `AbortSignal`.
+
+```typescript
+import { createStreamsClient } from "@secondlayer/sdk";
+
+const client = createStreamsClient({
+  apiKey: process.env.SECONDLAYER_API_KEY!,
+});
+
+const abort = new AbortController();
+process.once("SIGINT", () => abort.abort());
+
+for await (const event of client.events.stream({
+  types: ["ft_transfer"],
+  batchSize: 100,
+  signal: abort.signal,
+})) {
+  console.log(event.cursor, event.tx_id);
+}
+```
+
+Decoder helper.
+
+```typescript
+import {
+  createStreamsClient,
+  decodeFtTransfer,
+  isFtTransfer,
+} from "@secondlayer/sdk";
+
+const client = createStreamsClient({
+  apiKey: process.env.SECONDLAYER_API_KEY!,
+});
+
+for await (const event of client.events.stream({ types: ["ft_transfer"] })) {
+  if (!isFtTransfer(event)) continue;
+  const transfer = decodeFtTransfer(event);
+  console.log(transfer.decoded_payload);
+  break;
+}
+```
+
+Helper convention: each event helper is a pure function with no shared state.
+Use `is<EventName>(event)` as the type guard and `decode<EventName>(event)` as
+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`.
+
+## Stacks Index
+
+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
@@ -37,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";
 }
@@ -102,6 +105,211 @@ declare class Subgraphs extends BaseClient {
 	private createTableClient;
 }
 import { InferSubgraphClient as InferSubgraphClient2 } from "@secondlayer/subgraphs";
+type IndexTip = {
+	block_height: number
+	lag_seconds: number
+};
+type FtTransfer = {
+	cursor: string
+	block_height: number
+	tx_id: string
+	tx_index: number
+	event_index: number
+	event_type: "ft_transfer"
+	contract_id: string
+	asset_identifier: string
+	sender: string
+	recipient: string
+	amount: string
+};
+type FtTransfersEnvelope = {
+	events: FtTransfer[]
+	next_cursor: string | null
+	tip: IndexTip
+	reorgs: never[]
+};
+type FtTransfersListParams = {
+	cursor?: string | null
+	fromCursor?: string | null
+	limit?: number
+	contractId?: string
+	sender?: string
+	recipient?: string
+	fromHeight?: number
+	toHeight?: number
+};
+type FtTransfersWalkParams = Omit<FtTransfersListParams, "limit"> & {
+	batchSize?: number
+	signal?: AbortSignal
+};
+type NftTransfer = {
+	cursor: string
+	block_height: number
+	tx_id: string
+	tx_index: number
+	event_index: number
+	event_type: "nft_transfer"
+	contract_id: string
+	asset_identifier: string
+	sender: string
+	recipient: string
+	value: string
+};
+type NftTransfersEnvelope = {
+	events: NftTransfer[]
+	next_cursor: string | null
+	tip: IndexTip
+	reorgs: never[]
+};
+type NftTransfersListParams = {
+	cursor?: string | null
+	fromCursor?: string | null
+	limit?: number
+	contractId?: string
+	assetIdentifier?: string
+	sender?: string
+	recipient?: string
+	fromHeight?: number
+	toHeight?: number
+};
+type NftTransfersWalkParams = Omit<NftTransfersListParams, "limit"> & {
+	batchSize?: number
+	signal?: AbortSignal
+};
+declare class Index extends BaseClient {
+	constructor(options?: Partial<SecondLayerOptions>);
+	readonly ftTransfers: {
+		list: (params?: FtTransfersListParams) => Promise<FtTransfersEnvelope>
+		walk: (params?: FtTransfersWalkParams) => AsyncIterable<FtTransfer>
+	};
+	readonly nftTransfers: {
+		list: (params?: NftTransfersListParams) => Promise<NftTransfersEnvelope>
+		walk: (params?: NftTransfersWalkParams) => AsyncIterable<NftTransfer>
+	};
+	private listFtTransfers;
+	private listNftTransfers;
+	private walkFtTransfers;
+	private walkNftTransfers;
+}
+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>;
+type StreamsEvent = {
+	cursor: string
+	block_height: number
+	index_block_hash: string
+	burn_block_height: number
+	tx_id: string
+	tx_index: number
+	event_index: number
+	event_type: StreamsEventType
+	contract_id: string | null
+	payload: StreamsEventPayload
+	ts: string
+};
+type StreamsTip = {
+	block_height: number
+	index_block_hash: string
+	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
+	orphaned_range: {
+		from: string
+		to: string
+	}
+	new_canonical_tip: string
+};
+type StreamsEventsEnvelope = {
+	events: StreamsEvent[]
+	next_cursor: string | null
+	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 = {
+	fromCursor?: string | null
+	types?: readonly StreamsEventType[]
+	batchSize?: number
+	emptyBackoffMs?: number
+	maxPages?: number
+	maxEmptyPolls?: number
+	signal?: AbortSignal
+};
+type StreamsEventsConsumeParams = {
+	fromCursor?: string | null
+	mode?: "tail" | "bounded"
+	types?: readonly StreamsEventType[]
+	batchSize?: number
+	onBatch: (events: StreamsEvent[], envelope: StreamsEventsEnvelope) => Promise<string | null | undefined> | string | null | undefined
+	emptyBackoffMs?: number
+	maxPages?: number
+	maxEmptyPolls?: number
+	signal?: AbortSignal
+};
+type StreamsEventsConsumeResult = {
+	cursor: string | null
+	pages: number
+	emptyPolls: number
+};
+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.
+		*
+		* Use `consume` for indexers and ETL jobs that own checkpointing. Return
+		* the checkpoint cursor from `onBatch`. Default `mode: "tail"` keeps
+		* polling when caught up; `mode: "bounded"` exits on the first empty page.
+		* The consumer also exits when `maxPages`, `maxEmptyPolls`, or `signal`
+		* stops it.
+		*/
+		consume(params: StreamsEventsConsumeParams): Promise<StreamsEventsConsumeResult>
+		/**
+		* Follow Streams as an async iterator.
+		*
+		* Use `stream` for live processors and watch-style apps. It tails
+		* indefinitely by default and stops when its `AbortSignal`, `maxPages`, or
+		* `maxEmptyPolls` stops it.
+		*/
+		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 {
@@ -132,6 +340,8 @@ declare class Subscriptions extends BaseClient {
 	}>;
 }
 declare class SecondLayer extends BaseClient {
+	readonly streams: StreamsClient;
+	readonly index: Index;
 	readonly subgraphs: Subgraphs;
 	readonly subscriptions: Subscriptions;
 	constructor(options?: Partial<SecondLayerOptions>);
@@ -154,6 +364,94 @@ 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?: FetchLike2
+};
+declare function createStreamsClient(options: CreateStreamsClientOptions): StreamsClient;
+declare class AuthError extends Error {
+	readonly status = 401;
+	constructor(message?: string);
+}
+declare class RateLimitError extends Error {
+	readonly retryAfter?: string;
+	readonly status = 429;
+	constructor(message?: string, retryAfter?: string);
+}
+declare class ValidationError extends Error {
+	readonly status: number;
+	readonly body?: unknown;
+	constructor(message: string, status: number, body?: unknown);
+}
+declare class StreamsServerError extends Error {
+	readonly status: number;
+	readonly body?: unknown;
+	constructor(message: string, status: number, body?: unknown);
+}
+type FtTransferPayload = {
+	asset_identifier: string
+	sender: string
+	recipient: string
+	amount: string
+};
+type FtTransferEvent = StreamsEvent & {
+	event_type: "ft_transfer"
+	payload: FtTransferPayload
+};
+type DecodedFtTransferPayload = {
+	asset_identifier: string
+	contract_id: string
+	token_name: string | null
+	sender: string
+	recipient: string
+	amount: string
+};
+type DecodedFtTransfer = {
+	cursor: string
+	block_height: number
+	tx_id: string
+	tx_index: number
+	event_index: number
+	event_type: "ft_transfer"
+	decoded_payload: DecodedFtTransferPayload
+	source_cursor: string
+};
+declare function isFtTransfer(event: StreamsEvent): event is FtTransferEvent;
+declare function decodeFtTransfer(event: StreamsEvent): DecodedFtTransfer;
+type NftTransferPayload = {
+	asset_identifier: string
+	sender: string
+	recipient: string
+	value: string | {
+		hex: string
+	}
+};
+type NftTransferEvent = StreamsEvent & {
+	event_type: "nft_transfer"
+	payload: NftTransferPayload
+};
+type DecodedNftTransferPayload = {
+	asset_identifier: string
+	contract_id: string
+	token_name: string | null
+	sender: string
+	recipient: string
+	value: string
+};
+type DecodedNftTransfer = {
+	cursor: string
+	block_height: number
+	tx_id: string
+	tx_index: number
+	event_index: number
+	event_type: "nft_transfer"
+	decoded_payload: DecodedNftTransferPayload
+	source_cursor: string
+};
+declare function isNftTransfer(event: StreamsEvent): event is NftTransferEvent;
+declare function decodeNftTransfer(event: StreamsEvent): DecodedNftTransfer;
+type DecodedEventRow = DecodedFtTransfer | DecodedNftTransfer;
 import { SubgraphAgentSchema as SubgraphAgentSchema3, SubgraphSpecFormat as SubgraphSpecFormat2, SubgraphSpecOptions as SubgraphSpecOptions3 } from "@secondlayer/shared/subgraphs/spec";
 /**
 * Error thrown by {@link SecondLayer} when an API request fails.
@@ -214,4 +512,4 @@ declare class VersionConflictError extends ApiError {
 * ```
 */
 declare function verifyWebhookSignature(rawBody: string, signatureHeader: string, secret: string, toleranceSeconds?: number): boolean;
-export { verifyWebhookSignature, getSubgraph, VersionConflictError, UpdateSubscriptionRequest2 as UpdateSubscriptionRequest, Subscriptions, SubscriptionSummary2 as SubscriptionSummary, SubscriptionStatus, SubscriptionRuntime, SubscriptionFormat, SubscriptionDetail2 as SubscriptionDetail, Subgraphs, SubgraphSpecOptions3 as SubgraphSpecOptions, SubgraphSpecFormat2 as SubgraphSpecFormat, SubgraphAgentSchema3 as SubgraphAgentSchema, SecondLayerOptions, SecondLayer, RotateSecretResponse2 as RotateSecretResponse, ReplayResult2 as ReplayResult, DeliveryRow2 as DeliveryRow, DeadRow2 as DeadRow, CreateSubscriptionResponse2 as CreateSubscriptionResponse, CreateSubscriptionRequest2 as CreateSubscriptionRequest, 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 };