@secondlayer/sdk 5.8.0 → 5.9.0

package/README.md

@@ -50,7 +50,7 @@ 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_...
 });
 ```
 

package/dist/index.d.ts

@@ -359,11 +359,21 @@ type StreamsEvent = {
 	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 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 = {
@@ -403,12 +413,18 @@ type StreamsEventsListParams = {
 	toHeight?: number
 	types?: readonly StreamsEventType[]
 	contractId?: string
+	sender?: string
+	recipient?: string
+	assetIdentifier?: string
 	limit?: number
 };
 type StreamsEventsStreamParams = {
 	fromCursor?: string | null
 	types?: readonly StreamsEventType[]
 	contractId?: string
+	sender?: string
+	recipient?: string
+	assetIdentifier?: string
 	batchSize?: number
 	emptyBackoffMs?: number
 	maxPages?: number
@@ -420,6 +436,9 @@ type StreamsEventsConsumeParams = {
 	mode?: "tail" | "bounded"
 	types?: readonly StreamsEventType[]
 	contractId?: string
+	sender?: string
+	recipient?: string
+	assetIdentifier?: string
 	batchSize?: number
 	onBatch: (events: StreamsEvent[], envelope: StreamsEventsEnvelope) => Promise<string | null | undefined> | string | null | undefined
 	emptyBackoffMs?: number
@@ -432,7 +451,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 +523,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 +545,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 +608,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,6 +643,10 @@ declare class StreamsServerError extends Error {
 	readonly body?: unknown;
 	constructor(message: string, status: number, body?: unknown);
 }
+/** Thrown when response signature verification is enabled and fails. */
+declare class StreamsSignatureError extends Error {
+	constructor(message?: string);
+}
 type FtTransferPayload = {
 	asset_identifier: string
 	sender: string
@@ -1054,4 +1157,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 };

package/dist/index.js

@@ -501,6 +501,9 @@ class Index extends BaseClient {
   }
 }
 
+// src/streams/client.ts
+import { ed25519 } from "@secondlayer/shared";
+
 // src/streams/consumer.ts
 async function defaultSleep(ms, signal) {
   if (signal?.aborted)
@@ -529,7 +532,10 @@ async function consumeStreamsEvents(opts) {
       cursor,
       limit: opts.batchSize,
       types: opts.types,
-      contractId: opts.contractId
+      contractId: opts.contractId,
+      sender: opts.sender,
+      recipient: opts.recipient,
+      assetIdentifier: opts.assetIdentifier
     });
     pages++;
     const returnedCursor = await opts.onBatch(envelope.events, envelope);
@@ -564,7 +570,10 @@ async function* streamStreamsEvents(opts) {
       cursor,
       limit: opts.batchSize,
       types: opts.types,
-      contractId: opts.contractId
+      contractId: opts.contractId,
+      sender: opts.sender,
+      recipient: opts.recipient,
+      assetIdentifier: opts.assetIdentifier
     });
     pages++;
     for (const event of envelope.events) {
@@ -589,6 +598,9 @@ async function* streamStreamsEvents(opts) {
   }
 }
 
+// src/streams/dumps.ts
+import { createHash } from "node:crypto";
+
 // src/streams/errors.ts
 class AuthError extends Error {
   status = 401;
@@ -630,7 +642,60 @@ class StreamsServerError extends Error {
   }
 }
 
+class StreamsSignatureError extends Error {
+  constructor(message = "Streams response signature verification failed.") {
+    super(message);
+    this.name = "StreamsSignatureError";
+  }
+}
+
+// src/streams/dumps.ts
+function createStreamsDumps(opts) {
+  const baseUrl = opts.baseUrl?.replace(/\/+$/, "");
+  function requireBaseUrl() {
+    if (!baseUrl) {
+      throw new StreamsServerError("Streams dumps require `dumpsBaseUrl` on createStreamsClient.", 0);
+    }
+    return baseUrl;
+  }
+  function fileUrl(file) {
+    return `${requireBaseUrl()}/${file.path.replace(/^\/+/, "")}`;
+  }
+  async function list() {
+    const url = `${requireBaseUrl()}/manifest/latest.json`;
+    const res = await opts.fetchImpl(url);
+    if (!res.ok) {
+      throw new StreamsServerError(`Could not fetch dumps manifest (${res.status}).`, res.status);
+    }
+    return await res.json();
+  }
+  async function download(file) {
+    const res = await opts.fetchImpl(fileUrl(file));
+    if (!res.ok) {
+      throw new StreamsServerError(`Could not download dump ${file.path} (${res.status}).`, res.status);
+    }
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    const digest = createHash("sha256").update(bytes).digest("hex");
+    if (digest !== file.sha256) {
+      throw new StreamsSignatureError(`Dump ${file.path} sha256 mismatch (expected ${file.sha256}, got ${digest}).`);
+    }
+    return bytes;
+  }
+  return { list, fileUrl, download };
+}
+
 // src/streams/client.ts
+function cursorTuple(cursor) {
+  if (!cursor)
+    return [-1, -1];
+  const [block, index] = cursor.split(":");
+  return [Number(block), Number(index)];
+}
+function maxCursor(a, b) {
+  const [ah, ai] = cursorTuple(a);
+  const [bh, bi] = cursorTuple(b);
+  return ah > bh || ah === bh && ai >= bi ? a : b;
+}
 var DEFAULT_STREAMS_BASE_URL = "https://api.secondlayer.tools";
 function normalizeBaseUrl(baseUrl) {
   return baseUrl.replace(/\/+$/, "");
@@ -678,21 +743,68 @@ async function mapStreamsError(response) {
 function createStreamsClient(options) {
   const baseUrl = normalizeBaseUrl(options.baseUrl ?? DEFAULT_STREAMS_BASE_URL);
   const fetchImpl = options.fetchImpl ?? ((input, init) => fetch(input, init));
+  const verify = options.verify ?? false;
+  const dumps = createStreamsDumps({
+    baseUrl: options.dumpsBaseUrl,
+    fetchImpl
+  });
+  let publicKeyPromise = null;
+  function getPublicKey() {
+    if (publicKeyPromise)
+      return publicKeyPromise;
+    publicKeyPromise = (async () => {
+      if (typeof verify === "object") {
+        return ed25519.loadEd25519PublicKey(verify.publicKey);
+      }
+      const res = await fetchImpl(`${baseUrl}/public/streams/signing-key`);
+      if (!res.ok) {
+        throw new StreamsSignatureError(`Could not fetch signing key (${res.status}).`);
+      }
+      const body = await res.json();
+      if (!body.public_key_pem) {
+        throw new StreamsSignatureError("Signing key response missing key.");
+      }
+      return ed25519.loadEd25519PublicKey(body.public_key_pem);
+    })();
+    return publicKeyPromise;
+  }
   async function request(path) {
     const response = await fetchImpl(`${baseUrl}${path}`, {
       headers: { Authorization: `Bearer ${options.apiKey}` }
     });
     if (!response.ok)
       await mapStreamsError(response);
-    return await response.json();
+    const text = await response.text();
+    if (verify) {
+      const signature = response.headers.get("X-Signature");
+      if (!signature) {
+        throw new StreamsSignatureError("Response is missing X-Signature.");
+      }
+      const publicKey = await getPublicKey();
+      if (!ed25519.verifyEd25519(text, signature, publicKey)) {
+        throw new StreamsSignatureError;
+      }
+    }
+    return JSON.parse(text);
   }
   const fetchEvents = async ({
     cursor,
     limit,
     types,
-    contractId
+    contractId,
+    sender,
+    recipient,
+    assetIdentifier
   }) => {
-    return listEvents({ cursor, limit, types, contractId });
+    return listEvents({
+      cursor,
+      limit,
+      types,
+      contractId,
+      sender,
+      recipient,
+      assetIdentifier
+    });
   };
   async function listEvents(params = {}) {
     const searchParams = new URLSearchParams;
@@ -701,6 +813,9 @@ function createStreamsClient(options) {
     appendSearchParam2(searchParams, "to_height", params.toHeight);
     appendSearchParam2(searchParams, "limit", params.limit);
     appendSearchParam2(searchParams, "contract_id", params.contractId);
+    appendSearchParam2(searchParams, "sender", params.sender);
+    appendSearchParam2(searchParams, "recipient", params.recipient);
+    appendSearchParam2(searchParams, "asset_identifier", params.assetIdentifier);
     if (params.types?.length) {
       searchParams.set("types", params.types.join(","));
     }
@@ -719,6 +834,9 @@ function createStreamsClient(options) {
           mode: params.mode,
           types: params.types,
           contractId: params.contractId,
+          sender: params.sender,
+          recipient: params.recipient,
+          assetIdentifier: params.assetIdentifier,
           batchSize: params.batchSize ?? 100,
           fetchEvents,
           onBatch: params.onBatch,
@@ -733,6 +851,9 @@ function createStreamsClient(options) {
           fromCursor: params.fromCursor,
           types: params.types,
           contractId: params.contractId,
+          sender: params.sender,
+          recipient: params.recipient,
+          assetIdentifier: params.assetIdentifier,
           batchSize: params.batchSize ?? 100,
           emptyBackoffMs: params.emptyBackoffMs,
           maxPages: params.maxPages,
@@ -740,6 +861,29 @@ function createStreamsClient(options) {
           signal: params.signal,
           fetchEvents
         });
+      },
+      async replay(params) {
+        const fromCursor = params.from === "genesis" ? null : params.from ?? null;
+        const fromBlock = fromCursor ? cursorTuple(fromCursor)[0] : 0;
+        const manifest = await dumps.list();
+        const files = manifest.files.filter((file) => file.to_block >= fromBlock).sort((a, b) => a.from_block - b.from_block || a.to_block - b.to_block);
+        for (const file of files) {
+          if (params.signal?.aborted)
+            break;
+          await params.onDumpFile(file);
+        }
+        const seam = maxCursor(fromCursor, manifest.latest_finalized_cursor);
+        return consumeStreamsEvents({
+          fromCursor: seam,
+          mode: params.mode ?? "tail",
+          batchSize: params.batchSize ?? 100,
+          fetchEvents,
+          onBatch: params.onBatch,
+          emptyBackoffMs: params.emptyBackoffMs,
+          maxPages: params.maxPages,
+          maxEmptyPolls: params.maxEmptyPolls,
+          signal: params.signal
+        });
       }
     },
     blocks: {
@@ -756,6 +900,7 @@ function createStreamsClient(options) {
         return request(`/v1/streams/reorgs${query ? `?${query}` : ""}`);
       }
     },
+    dumps,
     canonical(height) {
       return request(`/v1/streams/canonical/${height}`);
     },
@@ -1402,6 +1547,7 @@ export {
   ValidationError,
   Subscriptions,
   Subgraphs,
+  StreamsSignatureError,
   StreamsServerError,
   SecondLayer,
   RateLimitError,
@@ -1412,5 +1558,5 @@ export {
   ApiError
 };
 
-//# debugId=45667C0DA2C290D964756E2164756E21
+//# debugId=54289A1292072EB864756E2164756E21
 //# sourceMappingURL=index.js.map