@secondlayer/sdk 5.8.0 → 5.9.0

package/dist/streams/index.d.ts

@@ -13,11 +13,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 = {
@@ -57,12 +67,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
@@ -74,6 +90,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
@@ -86,7 +105,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 FetchLike = (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>
@@ -102,6 +177,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
@@ -116,6 +199,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>
 };
@@ -123,6 +208,20 @@ type CreateStreamsClientOptions = {
 	apiKey: string
 	baseUrl?: string
 	fetchImpl?: FetchLike
+	/**
+	* 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 {
@@ -144,6 +243,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
@@ -410,4 +513,4 @@ type DecodedEventColumns = {
 	payload?: unknown
 };
 type DecodedEventRow = DecodedFtTransfer | DecodedNftTransfer | DecodedStxTransfer | DecodedStxMint | DecodedStxBurn | DecodedStxLock | DecodedFtMint | DecodedFtBurn | DecodedNftMint | DecodedNftBurn | DecodedPrint;
-export { isStxTransfer, isStxMint, isStxLock, isStxBurn, isPrint, isNftTransfer, isNftMint, isNftBurn, isFtTransfer, isFtMint, isFtBurn, decodeStxTransfer, decodeStxMint, decodeStxLock, decodeStxBurn, decodePrint, decodeNftTransfer, decodeNftMint, decodeNftBurn, decodeFtTransfer, decodeFtMint, decodeFtBurn, createStreamsClient, ValidationError, StreamsTip, StreamsServerError, StreamsReorgsListParams, StreamsReorgsListEnvelope, StreamsReorg, StreamsEventsStreamParams, StreamsEventsListParams, StreamsEventsListEnvelope, StreamsEventsEnvelope, StreamsEventsConsumeResult, StreamsEventsConsumeParams, StreamsEventType, StreamsEventPayload, StreamsEvent, StreamsClient, StreamsCanonicalBlock, STREAMS_EVENT_TYPES, RateLimitError, NftTransferPayload, NftTransferEvent, FtTransferPayload, FtTransferEvent, FetchLike, 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, AuthError };
+export { isStxTransfer, isStxMint, isStxLock, isStxBurn, isPrint, isNftTransfer, isNftMint, isNftBurn, isFtTransfer, isFtMint, isFtBurn, decodeStxTransfer, decodeStxMint, decodeStxLock, decodeStxBurn, decodePrint, decodeNftTransfer, decodeNftMint, decodeNftBurn, decodeFtTransfer, decodeFtMint, decodeFtBurn, createStreamsClient, ValidationError, StreamsTip, StreamsSignatureError, StreamsServerError, StreamsReorgsListParams, StreamsReorgsListEnvelope, StreamsReorg, StreamsEventsStreamParams, StreamsEventsListParams, StreamsEventsListEnvelope, StreamsEventsEnvelope, StreamsEventsConsumeResult, StreamsEventsConsumeParams, StreamsEventType, StreamsEventPayload, StreamsEvent, StreamsDumpsManifest, StreamsDumps, StreamsDumpFile, StreamsClient, StreamsCanonicalBlock, STREAMS_EVENT_TYPES, RateLimitError, NftTransferPayload, NftTransferEvent, FtTransferPayload, FtTransferEvent, FetchLike, 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, AuthError };

package/dist/streams/index.js

@@ -1,3 +1,6 @@
+// src/streams/client.ts
+import { ed25519 } from "@secondlayer/shared";
+
 // src/streams/consumer.ts
 async function defaultSleep(ms, signal) {
   if (signal?.aborted)
@@ -26,7 +29,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);
@@ -61,7 +67,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) {
@@ -86,6 +95,9 @@ async function* streamStreamsEvents(opts) {
   }
 }
 
+// src/streams/dumps.ts
+import { createHash } from "node:crypto";
+
 // src/streams/errors.ts
 class AuthError extends Error {
   status = 401;
@@ -127,7 +139,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(/\/+$/, "");
@@ -175,21 +240,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;
@@ -198,6 +310,9 @@ function createStreamsClient(options) {
     appendSearchParam(searchParams, "to_height", params.toHeight);
     appendSearchParam(searchParams, "limit", params.limit);
     appendSearchParam(searchParams, "contract_id", params.contractId);
+    appendSearchParam(searchParams, "sender", params.sender);
+    appendSearchParam(searchParams, "recipient", params.recipient);
+    appendSearchParam(searchParams, "asset_identifier", params.assetIdentifier);
     if (params.types?.length) {
       searchParams.set("types", params.types.join(","));
     }
@@ -216,6 +331,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,
@@ -230,6 +348,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,
@@ -237,6 +358,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: {
@@ -253,6 +397,7 @@ function createStreamsClient(options) {
         return request(`/v1/streams/reorgs${query ? `?${query}` : ""}`);
       }
     },
+    dumps,
     canonical(height) {
       return request(`/v1/streams/canonical/${height}`);
     },
@@ -652,11 +797,12 @@ export {
   decodeFtBurn,
   createStreamsClient,
   ValidationError,
+  StreamsSignatureError,
   StreamsServerError,
   STREAMS_EVENT_TYPES,
   RateLimitError,
   AuthError
 };
 
-//# debugId=3A844A761118CEDE64756E2164756E21
+//# debugId=AC24B4EAD103932F64756E2164756E21
 //# sourceMappingURL=index.js.map