@secondlayer/sdk 6.9.1 → 6.10.0

package/dist/streams/index.d.ts

@@ -171,6 +171,23 @@ type StreamsEventsStreamParams = {
 	maxEmptyPolls?: number
 	signal?: AbortSignal
 };
+type StreamsEventsSubscribeParams = {
+	/** Resume strictly after this cursor; omit to live-tail from the tip. */
+	fromCursor?: string | null
+	types?: readonly StreamsEventType[]
+	notTypes?: readonly StreamsEventType[]
+	contractId?: StreamsFilterValue
+	sender?: StreamsFilterValue
+	recipient?: StreamsFilterValue
+	assetIdentifier?: string
+	/** Abort to unsubscribe (the returned function does the same). */
+	signal?: AbortSignal
+	/** Called for each pushed event, in order. */
+	onEvent: (event: StreamsEvent) => void | Promise<void>
+	/** Called on a connection error; the subscription auto-reconnects from the
+	*  last delivered cursor unless the signal has aborted. */
+	onError?: (err: unknown) => void
+};
 /**
 * The checkpoint the SDK computes for a batch. Persist `cursor` inside the same
 * transaction as your projection writes, then resume from it via `fromCursor`.
@@ -276,6 +293,11 @@ type StreamsDumpsManifest = {
 		to_block: number
 	}
 	files: StreamsDumpFile[]
+	/** ed25519 signature over the manifest's canonical bytes. Absent on legacy
+	*  unsigned manifests. Verified by `list()` when `verifyDumpsManifest` is on. */
+	signature?: string
+	/** Short id of the signing public key. */
+	key_id?: string
 };
 type StreamsDumps = {
 	/** Fetch and parse the latest dumps manifest. */
@@ -315,6 +337,13 @@ type StreamsClient = {
 		* `maxEmptyPolls` stops it.
 		*/
 		stream(params?: StreamsEventsStreamParams): AsyncIterable<StreamsEvent>
+		/**
+		* Subscribe to the real-time SSE push surface. Calls `onEvent` for each new
+		* canonical event as the server pushes it (chain cadence, not poll-bounded),
+		* and verifies each frame's inline ed25519 signature when the client was
+		* created with `verify`. Returns an unsubscribe function.
+		*/
+		subscribe(params: StreamsEventsSubscribeParams): () => void
 	}
 	blocks: {
 		events(heightOrHash: number | string): Promise<StreamsEventsListEnvelope>
@@ -359,6 +388,12 @@ type CreateStreamsClientOptions = {
 	verify?: boolean | {
 		publicKey: string
 	}
+	/**
+	* Verify the bulk dumps manifest's ed25519 signature in `client.dumps.list()`
+	* before trusting any file sha256 (default off). Uses the same key source as
+	* `verify`. Default off until historical manifests carry signatures.
+	*/
+	verifyDumpsManifest?: boolean
 };
 declare function createStreamsClient(options: CreateStreamsClientOptions): StreamsClient;
 declare class AuthError extends Error {
@@ -653,4 +688,4 @@ declare const Cursor: {
 	}
 };
 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, StreamsUsage, StreamsTip, StreamsSignatureError, StreamsServerError, StreamsReorgsListParams, StreamsReorgsListEnvelope, StreamsReorgContext, StreamsReorg, StreamsEventsStreamParams, StreamsEventsListParams, StreamsEventsListEnvelope, StreamsEventsEnvelope, StreamsEventsConsumeResult, StreamsEventsConsumeParams, StreamsEventType, StreamsEventPayload, StreamsEvent, StreamsDumpsManifest, StreamsDumps, StreamsDumpFile, StreamsClient, StreamsCanonicalBlock, StreamsBatchContext, 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, Cursor, 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, StreamsUsage, StreamsTip, StreamsSignatureError, StreamsServerError, StreamsReorgsListParams, StreamsReorgsListEnvelope, StreamsReorgContext, StreamsReorg, StreamsEventsSubscribeParams, StreamsEventsStreamParams, StreamsEventsListParams, StreamsEventsListEnvelope, StreamsEventsEnvelope, StreamsEventsConsumeResult, StreamsEventsConsumeParams, StreamsEventType, StreamsEventPayload, StreamsEvent, StreamsDumpsManifest, StreamsDumps, StreamsDumpFile, StreamsClient, StreamsCanonicalBlock, StreamsBatchContext, 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, Cursor, AuthError };

package/dist/streams/index.js

@@ -1,5 +1,5 @@
 // src/streams/client.ts
-import { ed25519 } from "@secondlayer/shared";
+import { ed25519 as ed255192 } from "@secondlayer/shared";
 
 // src/errors.ts
 class ApiError extends Error {
@@ -317,6 +317,7 @@ async function* streamStreamsEvents(opts) {
 
 // src/streams/dumps.ts
 import { createHash } from "node:crypto";
+import { verifyStreamsBulkManifestSignature } from "@secondlayer/shared/streams-bulk-manifest";
 function createStreamsDumps(opts) {
   const baseUrl = opts.baseUrl?.replace(/\/+$/, "");
   function requireBaseUrl() {
@@ -334,7 +335,17 @@ function createStreamsDumps(opts) {
     if (!res.ok) {
       throw new StreamsServerError(`Could not fetch dumps manifest (${res.status}).`, res.status);
     }
-    return await res.json();
+    const manifest = await res.json();
+    if (opts.verifyManifest) {
+      if (!opts.loadPublicKeyPem) {
+        throw new StreamsSignatureError("Manifest verification is on but no signing key source is configured.");
+      }
+      const publicKeyPem = await opts.loadPublicKeyPem();
+      if (!verifyStreamsBulkManifestSignature(manifest, publicKeyPem)) {
+        throw new StreamsSignatureError("Dumps manifest signature is missing or invalid.");
+      }
+    }
+    return manifest;
   }
   async function download(file) {
     const res = await opts.fetchImpl(fileUrl(file));
@@ -351,6 +362,135 @@ function createStreamsDumps(opts) {
   return { list, fileUrl, download };
 }
 
+// src/streams/subscribe.ts
+import { ed25519 } from "@secondlayer/shared";
+function subscribeStreamsEvents(opts) {
+  const { params } = opts;
+  const controller = new AbortController;
+  const external = params.signal;
+  if (external) {
+    if (external.aborted)
+      controller.abort();
+    else
+      external.addEventListener("abort", () => controller.abort(), {
+        once: true
+      });
+  }
+  let cursor = params.fromCursor ?? null;
+  const reconnectDelayMs = opts.reconnectDelayMs ?? 1000;
+  const run = async () => {
+    while (!controller.signal.aborted) {
+      try {
+        const url = `${opts.baseUrl}/v1/streams/events/stream${buildQuery({
+          from_cursor: cursor ?? undefined,
+          types: params.types,
+          not_types: params.notTypes,
+          contract_id: params.contractId,
+          sender: params.sender,
+          recipient: params.recipient,
+          asset_identifier: params.assetIdentifier
+        })}`;
+        const res = await opts.fetchImpl(url, {
+          headers: {
+            Authorization: `Bearer ${opts.apiKey}`,
+            Accept: "text/event-stream"
+          },
+          signal: controller.signal
+        });
+        if (!res.ok) {
+          throw new StreamsServerError(`Streams SSE returned ${res.status}.`, res.status);
+        }
+        if (!res.body) {
+          throw new StreamsServerError("Streams SSE response has no body.", 0);
+        }
+        for await (const frame of parseSseFrames(res.body, controller.signal)) {
+          if (frame.event === "ping" || !frame.data)
+            continue;
+          let parsed;
+          try {
+            parsed = JSON.parse(frame.data);
+          } catch {
+            continue;
+          }
+          if (!parsed.event)
+            continue;
+          if (opts.verify) {
+            const key = await opts.loadKey();
+            if (!parsed.sig || !ed25519.verifyEd25519(JSON.stringify(parsed.event), parsed.sig, key.publicKey)) {
+              throw new StreamsSignatureError("Streams SSE frame signature is missing or invalid.");
+            }
+          }
+          cursor = parsed.event.cursor ?? cursor;
+          await params.onEvent(parsed.event);
+        }
+      } catch (err) {
+        if (controller.signal.aborted)
+          return;
+        params.onError?.(err);
+        await sleep(reconnectDelayMs, controller.signal);
+      }
+    }
+  };
+  run();
+  return () => controller.abort();
+}
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    if (signal.aborted)
+      return resolve();
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+async function* parseSseFrames(body, signal) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder;
+  let buffer = "";
+  try {
+    while (!signal.aborted) {
+      const { value, done } = await reader.read();
+      if (done)
+        break;
+      buffer += decoder.decode(value, { stream: true });
+      let sep = buffer.indexOf(`
+
+`);
+      while (sep !== -1) {
+        yield parseFrame(buffer.slice(0, sep));
+        buffer = buffer.slice(sep + 2);
+        sep = buffer.indexOf(`
+
+`);
+      }
+    }
+  } finally {
+    try {
+      await reader.cancel();
+    } catch {}
+  }
+}
+function parseFrame(raw) {
+  let event;
+  const data = [];
+  for (const line of raw.split(`
+`)) {
+    if (line.startsWith("data:")) {
+      data.push(line.slice(line.startsWith("data: ") ? 6 : 5));
+    } else if (line.startsWith("event:")) {
+      event = line.slice(line.startsWith("event: ") ? 7 : 6).trim();
+    }
+  }
+  return { event, data: data.length > 0 ? data.join(`
+`) : undefined };
+}
+
 // src/streams/client.ts
 function cursorTuple(cursor) {
   if (!cursor)
@@ -410,10 +550,6 @@ 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 keyPromise = null;
   function loadKey() {
     if (keyPromise)
@@ -421,8 +557,9 @@ function createStreamsClient(options) {
     keyPromise = (async () => {
       if (typeof verify === "object") {
         return {
-          keyId: ed25519.ed25519KeyId(verify.publicKey),
-          publicKey: ed25519.loadEd25519PublicKey(verify.publicKey)
+          keyId: ed255192.ed25519KeyId(verify.publicKey),
+          publicKeyPem: verify.publicKey,
+          publicKey: ed255192.loadEd25519PublicKey(verify.publicKey)
         };
       }
       const res = await fetchImpl(`${baseUrl}/public/streams/signing-key`);
@@ -434,12 +571,19 @@ function createStreamsClient(options) {
         throw new StreamsSignatureError("Signing key response missing key.");
       }
       return {
-        keyId: body.key_id ?? ed25519.ed25519KeyId(body.public_key_pem),
-        publicKey: ed25519.loadEd25519PublicKey(body.public_key_pem)
+        keyId: body.key_id ?? ed255192.ed25519KeyId(body.public_key_pem),
+        publicKeyPem: body.public_key_pem,
+        publicKey: ed255192.loadEd25519PublicKey(body.public_key_pem)
       };
     })();
     return keyPromise;
   }
+  const dumps = createStreamsDumps({
+    baseUrl: options.dumpsBaseUrl,
+    fetchImpl,
+    verifyManifest: options.verifyDumpsManifest ?? false,
+    loadPublicKeyPem: async () => (await loadKey()).publicKeyPem
+  });
   async function request(path) {
     const response = await fetchImpl(`${baseUrl}${path}`, {
       headers: { Authorization: `Bearer ${options.apiKey}` }
@@ -464,7 +608,7 @@ function createStreamsClient(options) {
           throw new StreamsSignatureError(`Response signed with key '${responseKeyId}' not served by the signing-key endpoint.`);
         }
       }
-      if (!ed25519.verifyEd25519(text, signature, key.publicKey)) {
+      if (!ed255192.verifyEd25519(text, signature, key.publicKey)) {
         throw new StreamsSignatureError;
       }
     }
@@ -549,6 +693,16 @@ function createStreamsClient(options) {
           fetchEvents
         });
       },
+      subscribe(params) {
+        return subscribeStreamsEvents({
+          baseUrl,
+          apiKey: options.apiKey,
+          fetchImpl,
+          verify: Boolean(verify),
+          loadKey,
+          params
+        });
+      },
       async replay(params) {
         const fromCursor = params.from === "genesis" ? null : params.from ?? null;
         const fromBlock = fromCursor ? cursorTuple(fromCursor)[0] : 0;
@@ -914,5 +1068,5 @@ export {
   AuthError
 };
 
-//# debugId=7AB22CC73A3769A464756E2164756E21
+//# debugId=202DB745ED61199F64756E2164756E21
 //# sourceMappingURL=index.js.map