@secondlayer/sdk 5.8.0 → 6.0.0

package/README.md

@@ -19,9 +19,12 @@ const sl = new SecondLayer({
 });
 ```
 
-Reads are public during open beta — no key needed. Writes require an `sk-sl_`
-API key, created in the platform console at
-https://secondlayer.tools/platform/api-keys.
+`sl.index` and `sl.subgraphs` reads are anonymous — no key needed. **`sl.streams`
+reads require a bearer token** (`apiKey`) and resolve a per-tier tenant; a
+publicly-known free-tier token exists but a bearer is always required. Writes
+require an `sk-sl_` API key, created in the platform console at
+https://secondlayer.tools/platform/api-keys. (Public Streams bulk dumps —
+`client.dumps`, `events.replay` — need no key.)
 
 ## Mental model
 
@@ -31,16 +34,20 @@ https://secondlayer.tools/platform/api-keys.
 
 ## Stacks Streams
 
-Typed L1 HTTP client. Reads are public — no key needed.
+Typed L1 HTTP client. Reads require a bearer token (`apiKey`).
 
 ```typescript
 const tip = await sl.streams.tip();
+// tip.finalized_height — highest immutable (past Bitcoin-anchored finality) block
 const page = await sl.streams.events.list({
   types: ["ft_transfer"],
   contractId: "SP...sbtc-token",
+  sender: "SP...",       // exact payload sender (events that have one)
+  recipient: "SP...",    // exact payload recipient
+  assetIdentifier: "SP...token::asset", // exact FT/NFT asset id
   limit: 10,
 });
-
+// each event carries `finalized: boolean`
 console.log({ tip, firstCursor: page.events[0]?.cursor });
 ```
 
@@ -50,10 +57,19 @@ console.log({ tip, firstCursor: page.events[0]?.cursor });
 import { createStreamsClient } from "@secondlayer/sdk";
 
 const streams = createStreamsClient({
-  apiKey: process.env.SL_SERVICE_KEY!, // sk-sl_...
+  apiKey: process.env.SL_API_KEY!, // sk-sl_... — required for reads
+  // verify: true,                 // verify ed25519 X-Signature on every read
+  //                               // (auto-fetches the public key; { publicKey } pins a PEM)
+  // dumpsBaseUrl: process.env.SL_STREAMS_DUMPS_URL, // required to use client.dumps
 });
 ```
 
+Verified responses: every Streams read is signed (ed25519 `X-Signature` +
+`X-Signature-KeyId`). Pass `verify: true` to check it on every read (or
+`{ publicKey }` to pin a PEM); a missing/bad signature throws
+`StreamsSignatureError`. The public key is at
+`GET /public/streams/signing-key`.
+
 Convenience reads:
 
 ```typescript
@@ -102,6 +118,46 @@ for await (const event of streams.events.stream({
 }
 ```
 
+Bulk parquet dumps.
+
+Finalized history is published as public parquet files. Set `dumpsBaseUrl`
+(or `SL_STREAMS_DUMPS_URL`) — no API key needed for dumps. The SDK does **not**
+decode parquet; `download` hands you sha256-verified bytes to process with your
+own tooling.
+
+```typescript
+const streams = createStreamsClient({
+  apiKey: process.env.SL_API_KEY!,
+  dumpsBaseUrl: process.env.SL_STREAMS_DUMPS_URL!,
+});
+
+const manifest = await streams.dumps.list();       // parse the manifest
+for (const file of manifest.files) {
+  const bytes = await streams.dumps.download(file); // fetch + verify sha256
+  await myParquetReader(bytes);
+}
+```
+
+Backfill then tail (`events.replay`).
+
+Backfills from bulk dumps, then tails live from the manifest's
+`latest_finalized_cursor` — no gap or dupe at the seam. `onDumpFile` hands you
+each finalized file; `onBatch` receives live events after the seam.
+
+```typescript
+await streams.events.replay({
+  from: lastCheckpoint,
+  async onDumpFile(file) {
+    const bytes = await streams.dumps.download(file);
+    await ingestParquet(bytes); // your tooling
+  },
+  async onBatch(events, envelope) {
+    for (const event of events) await handle(event);
+    return envelope.next_cursor;
+  },
+});
+```
+
 Decoder helper.
 
 ```typescript

package/dist/index.d.ts

@@ -346,8 +346,77 @@ declare class Index extends BaseClient {
 }
 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 = {
+/** 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. */
+type StreamsClarityValue = string | {
+	hex: string
+} | Record<string, unknown>;
+type StxTransferPayload = {
+	sender: string
+	recipient: string
+	amount: string
+	memo?: string
+};
+type StxMintPayload = {
+	recipient: string
+	amount: string
+};
+type StxBurnPayload = {
+	sender: string
+	amount: string
+};
+type StxLockPayload = {
+	locked_address: string
+	locked_amount: string
+	unlock_height: string
+};
+type FtTransferPayload = {
+	asset_identifier: string
+	sender: string
+	recipient: string
+	amount: string
+};
+type FtMintPayload = {
+	asset_identifier: string
+	recipient: string
+	amount: string
+};
+type FtBurnPayload = {
+	asset_identifier: string
+	sender: string
+	amount: string
+};
+type NftTransferPayload = {
+	asset_identifier: string
+	sender: string
+	recipient: string
+	value: StreamsClarityValue
+	/** Canonical serialized hex of `value`, when the stream carries it. */
+	raw_value?: string
+};
+type NftMintPayload = {
+	asset_identifier: string
+	recipient: string
+	value: StreamsClarityValue
+	raw_value?: string
+};
+type NftBurnPayload = {
+	asset_identifier: string
+	sender: string
+	value: StreamsClarityValue
+	raw_value?: string
+};
+type PrintPayload = {
+	contract_id?: string | null
+	topic?: string
+	value?: unknown
+	raw_value?: string
+};
+/** Union of every Streams payload shape, discriminated by `event_type` on the
+*  parent `StreamsEvent`. */
+type StreamsEventPayload = StxTransferPayload | StxMintPayload | StxBurnPayload | StxLockPayload | FtTransferPayload | FtMintPayload | FtBurnPayload | NftTransferPayload | NftMintPayload | NftBurnPayload | PrintPayload;
+type StreamsEventBase = {
 	cursor: string
 	block_height: number
 	block_hash: string
@@ -355,15 +424,33 @@ type StreamsEvent = {
 	tx_id: string
 	tx_index: number
 	event_index: number
-	event_type: StreamsEventType
 	contract_id: string | null
-	payload: StreamsEventPayload
 	ts: string
-};
+	/**
+	* True when this event's block is past the finality boundary (immutable).
+	* Optional for back-compat; the API always sets it on Streams responses.
+	*/
+	finalized?: boolean
+};
+type StreamsEventOf<
+	T extends StreamsEventType,
+	P
+> = StreamsEventBase & {
+	event_type: T
+	payload: P
+};
+/** A raw Streams event. Discriminated on `event_type`, so `event.payload`
+*  narrows to the matching payload shape once the type is checked. */
+type StreamsEvent = StreamsEventOf<"stx_transfer", StxTransferPayload> | StreamsEventOf<"stx_mint", StxMintPayload> | StreamsEventOf<"stx_burn", StxBurnPayload> | StreamsEventOf<"stx_lock", StxLockPayload> | StreamsEventOf<"ft_transfer", FtTransferPayload> | StreamsEventOf<"ft_mint", FtMintPayload> | StreamsEventOf<"ft_burn", FtBurnPayload> | StreamsEventOf<"nft_transfer", NftTransferPayload> | StreamsEventOf<"nft_mint", NftMintPayload> | StreamsEventOf<"nft_burn", NftBurnPayload> | StreamsEventOf<"print", PrintPayload>;
 type StreamsTip = {
 	block_height: number
 	block_hash: string
 	burn_block_height: number
+	/**
+	* Highest Stacks block past the burn-confirmation finality boundary.
+	* Optional for back-compat; the API always sets it.
+	*/
+	finalized_height?: number
 	lag_seconds: number
 };
 type StreamsCanonicalBlock = {
@@ -397,18 +484,29 @@ type StreamsReorgsListEnvelope = {
 	reorgs: StreamsReorg[]
 	next_since: string | null
 };
+/** A filter that matches a single value or any value in a list. */
+type StreamsFilterValue = string | readonly string[];
 type StreamsEventsListParams = {
 	cursor?: string | null
 	fromHeight?: number
 	toHeight?: number
 	types?: readonly StreamsEventType[]
-	contractId?: string
+	/** Event types to exclude (applied after `types`). */
+	notTypes?: readonly StreamsEventType[]
+	contractId?: StreamsFilterValue
+	sender?: StreamsFilterValue
+	recipient?: StreamsFilterValue
+	assetIdentifier?: string
 	limit?: number
 };
 type StreamsEventsStreamParams = {
 	fromCursor?: string | null
 	types?: readonly StreamsEventType[]
-	contractId?: string
+	notTypes?: readonly StreamsEventType[]
+	contractId?: StreamsFilterValue
+	sender?: StreamsFilterValue
+	recipient?: StreamsFilterValue
+	assetIdentifier?: string
 	batchSize?: number
 	emptyBackoffMs?: number
 	maxPages?: number
@@ -419,7 +517,11 @@ type StreamsEventsConsumeParams = {
 	fromCursor?: string | null
 	mode?: "tail" | "bounded"
 	types?: readonly StreamsEventType[]
-	contractId?: string
+	notTypes?: readonly StreamsEventType[]
+	contractId?: StreamsFilterValue
+	sender?: StreamsFilterValue
+	recipient?: StreamsFilterValue
+	assetIdentifier?: string
 	batchSize?: number
 	onBatch: (events: StreamsEvent[], envelope: StreamsEventsEnvelope) => Promise<string | null | undefined> | string | null | undefined
 	emptyBackoffMs?: number
@@ -432,7 +534,63 @@ type StreamsEventsConsumeResult = {
 	pages: number
 	emptyPolls: number
 };
+type StreamsEventsReplayParams = {
+	/** Start point: `"genesis"` (default) or a `<block>:<index>` cursor. */
+	from?: "genesis" | string
+	/**
+	* Called once per finalized dump file, in block order, before live tailing.
+	* Process the parquet with your own tooling (e.g. DuckDB) — the SDK does not
+	* decode parquet. Use `client.dumps.download(file)` to fetch + verify bytes.
+	*/
+	onDumpFile: (file: StreamsDumpFile) => Promise<void> | void
+	/** Called per live page after the dump phase, like `consume`. */
+	onBatch: (events: StreamsEvent[], envelope: StreamsEventsEnvelope) => Promise<string | null | undefined> | string | null | undefined
+	mode?: "tail" | "bounded"
+	batchSize?: number
+	emptyBackoffMs?: number
+	maxPages?: number
+	maxEmptyPolls?: number
+	signal?: AbortSignal
+};
 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 = {
+	path: string
+	from_block: number
+	to_block: number
+	min_cursor: string | null
+	max_cursor: string | null
+	row_count: number
+	byte_size: number
+	sha256: string
+	schema_version: number
+	created_at: string
+};
+type StreamsDumpsManifest = {
+	dataset: string
+	network: string
+	version: string
+	schema_version: number
+	generated_at: string
+	producer_version: string
+	finality_lag_blocks: number
+	/** Cursor at the end of the finalized bulk coverage — hand to live tailing. */
+	latest_finalized_cursor: string | null
+	coverage: {
+		from_block: number
+		to_block: number
+	}
+	files: StreamsDumpFile[]
+};
+type StreamsDumps = {
+	/** Fetch and parse the latest dumps manifest. */
+	list(): Promise<StreamsDumpsManifest>
+	/** Absolute URL for a manifest file. */
+	fileUrl(file: StreamsDumpFile): string
+	/** Download a parquet file and verify its sha256 against the manifest. */
+	download(file: StreamsDumpFile): Promise<Uint8Array>
+};
 type StreamsClient = {
 	events: {
 		list(params?: StreamsEventsListParams): Promise<StreamsEventsEnvelope>
@@ -448,6 +606,14 @@ type StreamsClient = {
 		*/
 		consume(params: StreamsEventsConsumeParams): 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
+		* order, then tails live from the manifest's `latest_finalized_cursor`
+		* (exclusive input → no gap or duplicate at the seam). Requires
+		* `dumpsBaseUrl`.
+		*/
+		replay(params: StreamsEventsReplayParams): Promise<StreamsEventsConsumeResult>
+		/**
 		* Follow Streams as an async iterator.
 		*
 		* Use `stream` for live processors and watch-style apps. It tails
@@ -462,6 +628,8 @@ type StreamsClient = {
 	reorgs: {
 		list(params: StreamsReorgsListParams): Promise<StreamsReorgsListEnvelope>
 	}
+	/** Bulk parquet dumps. Requires `dumpsBaseUrl` on the client. */
+	dumps: StreamsDumps
 	canonical(height: number): Promise<StreamsCanonicalBlock>
 	tip(): Promise<StreamsTip>
 };
@@ -523,6 +691,20 @@ type CreateStreamsClientOptions = {
 	apiKey: string
 	baseUrl?: string
 	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`.
+	*/
+	dumpsBaseUrl?: string
+	/**
+	* Verify the ed25519 `X-Signature` on every response (default off). Pass
+	* `true` to fetch the server's public key from
+	* `/public/streams/signing-key`, or `{ publicKey }` to pin a known PEM. A
+	* failed or missing signature throws `StreamsSignatureError`.
+	*/
+	verify?: boolean | {
+		publicKey: string
+	}
 };
 declare function createStreamsClient(options: CreateStreamsClientOptions): StreamsClient;
 declare class AuthError extends Error {
@@ -544,16 +726,13 @@ declare class StreamsServerError extends Error {
 	readonly body?: unknown;
 	constructor(message: string, status: number, body?: unknown);
 }
-type FtTransferPayload = {
-	asset_identifier: string
-	sender: string
-	recipient: string
-	amount: string
-};
-type FtTransferEvent = StreamsEvent & {
+/** Thrown when response signature verification is enabled and fails. */
+declare class StreamsSignatureError extends Error {
+	constructor(message?: string);
+}
+type FtTransferEvent = Extract<StreamsEvent, {
 	event_type: "ft_transfer"
-	payload: FtTransferPayload
-};
+}>;
 type DecodedFtTransferPayload = {
 	asset_identifier: string
 	contract_id: string
@@ -574,18 +753,9 @@ type DecodedFtTransfer = {
 };
 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 & {
+type NftTransferEvent = Extract<StreamsEvent, {
 	event_type: "nft_transfer"
-	payload: NftTransferPayload
-};
+}>;
 type DecodedNftTransferPayload = {
 	asset_identifier: string
 	contract_id: string
@@ -1054,4 +1224,4 @@ declare function toJsonSafe(value: unknown): unknown;
 /** Decode a hex-encoded Clarity value to JSON-safe JS (uints as strings,
 *  buffers as `0x…` hex, tuples as objects). Returns the input hex on failure. */
 declare function decodeClarityValue(hex: string): unknown;
-export { verifyWebhookSignature, toJsonSafe, isStxTransfer, isStxMint, isStxLock, isStxBurn, isPrint, isNftTransfer, isNftMint, isNftBurn, isFtTransfer, isFtMint, isFtBurn, getSubgraph, decodeStxTransfer, decodeStxMint, decodeStxLock, decodeStxBurn, decodePrint, decodeNftTransfer, decodeNftMint, decodeNftBurn, decodeFtTransfer, decodeFtMint, decodeFtBurn, decodeClarityValue, 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, Pox4CallsParams, NftTransfersWalkParams, NftTransfersListParams, NftTransfersEnvelope, NftTransferPayload, NftTransferEvent, NftTransfer, IndexTip, IndexEventType, IndexEvent, IndexContractCall, Index, FtTransfersWalkParams, FtTransfersListParams, FtTransfersEnvelope, FtTransferPayload, FtTransferEvent, FtTransfer, FetchLike2 as FetchLike, EventsWalkParams, EventsListParams, EventsEnvelope, DeliveryRow2 as DeliveryRow, 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, DeadRow2 as DeadRow, Datasets, DatasetRow, CursorListParams, CursorEnvelope, CreateSubscriptionResponse2 as CreateSubscriptionResponse, CreateSubscriptionRequest2 as CreateSubscriptionRequest, ContractCallsWalkParams, ContractCallsListParams, ContractCallsEnvelope, CURSOR_SLUGS, AuthError, ApiError };
+export { verifyWebhookSignature, toJsonSafe, isStxTransfer, isStxMint, isStxLock, isStxBurn, isPrint, isNftTransfer, isNftMint, isNftBurn, isFtTransfer, isFtMint, isFtBurn, getSubgraph, decodeStxTransfer, decodeStxMint, decodeStxLock, decodeStxBurn, decodePrint, decodeNftTransfer, decodeNftMint, decodeNftBurn, decodeFtTransfer, decodeFtMint, decodeFtBurn, decodeClarityValue, 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, StreamsSignatureError, StreamsServerError, StreamsReorgsListParams, StreamsReorgsListEnvelope, StreamsReorg, StreamsEventsStreamParams, StreamsEventsListParams, StreamsEventsListEnvelope, StreamsEventsEnvelope, StreamsEventsConsumeResult, StreamsEventsConsumeParams, StreamsEventType, StreamsEventPayload, StreamsEvent, StreamsDumpsManifest, StreamsDumps, StreamsDumpFile, StreamsClient, StreamsCanonicalBlock, SecondLayerOptions, SecondLayer, RotateSecretResponse2 as RotateSecretResponse, ReplayResult2 as ReplayResult, RateLimitError, Pox4CallsParams, NftTransfersWalkParams, NftTransfersListParams, NftTransfersEnvelope, NftTransferPayload, NftTransferEvent, NftTransfer, IndexTip, IndexEventType, IndexEvent, IndexContractCall, Index, FtTransfersWalkParams, FtTransfersListParams, FtTransfersEnvelope, FtTransferPayload, FtTransferEvent, FtTransfer, FetchLike2 as FetchLike, EventsWalkParams, EventsListParams, EventsEnvelope, DeliveryRow2 as DeliveryRow, 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, DeadRow2 as DeadRow, Datasets, DatasetRow, CursorListParams, CursorEnvelope, CreateSubscriptionResponse2 as CreateSubscriptionResponse, CreateSubscriptionRequest2 as CreateSubscriptionRequest, ContractCallsWalkParams, ContractCallsListParams, ContractCallsEnvelope, CURSOR_SLUGS, AuthError, ApiError };