@secondlayer/sdk 6.35.0 → 6.37.0

package/dist/streams/index.d.ts

@@ -274,6 +274,18 @@ type StreamsEventsConsumeParams = {
 	* stale rows from an orphaned fork are left in place).
 	*/
 	onReorg?: (reorg: StreamsReorg, ctx: StreamsReorgContext) => Promise<void> | void
+	/** Page-fetch retries after the first failure (429/5xx/network only —
+	*  4xx and handler throws always propagate). Default 3; `0` disables. */
+	retryCount?: number
+	/** Base retry delay in ms; the n-th retry waits `retryDelay * n`. A server
+	*  `Retry-After` overrides it. Default 1000. */
+	retryDelay?: number
+	/** Void observer, called before each retry sleep (metrics/logging). */
+	onError?: (err: unknown, ctx: {
+		attempt: number
+		retriesLeft: number
+		delayMs: number
+	}) => void
 	emptyBackoffMs?: number
 	maxPages?: number
 	maxEmptyPolls?: number
@@ -500,27 +512,105 @@ type CreateStreamsClientOptions = {
 	verifyDumpsManifest?: boolean
 };
 declare function createStreamsClient(options: CreateStreamsClientOptions): StreamsClient;
-declare class AuthError extends Error {
-	readonly status = 401;
+/** Options accepted by every error in the family. */
+interface SecondLayerErrorOptions {
+	cause?: Error;
+	details?: string;
+	/** Stable machine-readable code (e.g. `UPGRADE_REQUIRED`, `BYO_BREAKING_CHANGE`). */
+	code?: string;
+	/** Docs page that explains this failure and its fix. */
+	docsUrl?: string;
+	/** Extra context lines appended to the message (DDL to run, next steps). */
+	metaMessages?: string[];
+	/** Whether retrying the SAME request can succeed (429/5xx/network). */
+	retryable?: boolean;
+	/** Parsed `Retry-After`, in seconds — set on rate limits that carry it. */
+	retryAfterSeconds?: number;
+}
+/**
+* Root of the SDK error family. Implements the same protocol as `BaseError`
+* in `@secondlayer/stacks` (`shortMessage`, `cause`, `toJSON`) so a failed
+* chain read and a failed platform read serialize and introspect identically.
+* It intentionally does NOT extend that class: `BaseError.details` is a
+* `string`, while {@link ByoBreakingChangeError.details} is the documented
+* structured migration plan — and cross-package `instanceof` is unreliable
+* under per-package bundling anyway (match on `code`/`name` across packages).
+*
+* `retryable` is the signal the consume loops act on: 429/5xx/network are
+* retryable, 4xx and body-serialization failures are not.
+*/
+declare class SecondLayerError extends Error {
+	name: string;
+	/** The one-line failure, without the appended context blocks. */
+	shortMessage: string;
+	code?: string;
+	docsUrl?: string;
+	metaMessages?: string[];
+	retryable: boolean;
+	retryAfterSeconds?: number;
+	constructor(shortMessage: string, options?: SecondLayerErrorOptions);
+	/**
+	* Walk the cause chain. With a predicate, returns the first error matching
+	* it (or `null`); without one, returns the deepest cause. Mirrors viem's
+	* `error.walk()` so cross-library error handling reads the same.
+	*/
+	walk(fn?: (err: unknown) => boolean): unknown;
+	toJSON(): {
+		name: string
+		message: string
+		shortMessage: string
+		cause: string | undefined
+		code: string | undefined
+		docsUrl: string | undefined
+		retryable: boolean
+		retryAfterSeconds: number | undefined
+	};
+}
+/**
+* Error thrown by {@link SecondLayer} when an API request fails.
+* Includes the HTTP status code for programmatic error handling.
+*
+* @example
+* ```ts
+* try {
+*   await client.subgraphs.get("my-subgraph");
+* } catch (err) {
+*   if (err instanceof ApiError && err.status === 404) {
+*     console.log("Subgraph not found");
+*   }
+* }
+* ```
+*/
+declare class ApiError extends SecondLayerError {
+	/** HTTP status code (0 for network errors). */
+	status: number;
+	/** Raw response body (parsed JSON if possible) — preserved for callers that need error details. */
+	body?: unknown;
+	constructor(status: number, message: string, body?: unknown, code?: string, options?: SecondLayerErrorOptions);
+}
+/** Thrown on a 401 — by both the platform clients and Streams. */
+declare class AuthError extends ApiError {
+	readonly status: 401;
 	constructor(message?: string);
 }
-declare class RateLimitError extends Error {
+/** Thrown on a 429 — by both the platform clients and Streams. `retryable`,
+*  with `retryAfterSeconds` parsed from the `Retry-After` header when sent. */
+declare class RateLimitError extends ApiError {
+	/** Raw `Retry-After` header value (seconds or HTTP-date). */
 	readonly retryAfter?: string;
-	readonly status = 429;
+	readonly status: 429;
 	constructor(message?: string, retryAfter?: string);
 }
-declare class ValidationError extends Error {
-	readonly status: number;
-	readonly body?: unknown;
+/** Thrown on a 4xx the caller can fix (bad cursor, bad params). Never retried. */
+declare class ValidationError extends ApiError {
 	constructor(message: string, status: number, body?: unknown);
 }
-declare class StreamsServerError extends Error {
-	readonly status: number;
-	readonly body?: unknown;
+/** Thrown on a 5xx from the Streams API. `retryable`. */
+declare class StreamsServerError extends ApiError {
 	constructor(message: string, status: number, body?: unknown);
 }
 /** Thrown when response signature verification is enabled and fails. */
-declare class StreamsSignatureError extends Error {
+declare class StreamsSignatureError extends SecondLayerError {
 	constructor(message?: string);
 }
 type FtTransferEvent = Extract<StreamsEvent, {

package/dist/streams/index.js

@@ -2,19 +2,129 @@
 import { ed25519 as ed255192 } from "@secondlayer/shared";
 
 // src/errors.ts
-class ApiError extends Error {
+var DOCS_BASE = "https://www.secondlayer.tools";
+
+class SecondLayerError extends Error {
+  name = "SecondLayerError";
+  shortMessage;
+  code;
+  docsUrl;
+  metaMessages;
+  retryable;
+  retryAfterSeconds;
+  constructor(shortMessage, options = {}) {
+    const detailBlocks = [
+      ...options.metaMessages ?? [],
+      ...options.details ? [options.details] : [],
+      ...options.docsUrl ? [`Docs: ${options.docsUrl}`] : []
+    ];
+    const message = [
+      shortMessage,
+      detailBlocks.length > 0 ? `
+${detailBlocks.join(`
+`)}` : ""
+    ].join("");
+    super(message, options.cause ? { cause: options.cause } : undefined);
+    this.shortMessage = shortMessage;
+    this.code = options.code;
+    this.docsUrl = options.docsUrl;
+    this.metaMessages = options.metaMessages;
+    this.retryable = options.retryable ?? false;
+    this.retryAfterSeconds = options.retryAfterSeconds;
+  }
+  walk(fn) {
+    let err = this;
+    let last = this;
+    while (err != null) {
+      if (fn?.(err))
+        return err;
+      last = err;
+      err = err.cause;
+    }
+    return fn ? null : last;
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      shortMessage: this.shortMessage,
+      cause: this.cause instanceof Error ? this.cause.message : undefined,
+      code: this.code,
+      docsUrl: this.docsUrl,
+      retryable: this.retryable,
+      retryAfterSeconds: this.retryAfterSeconds
+    };
+  }
+}
+function statusRetryable(status) {
+  return status === 429 || status >= 500;
+}
+function docsFor(status, code) {
+  if (code === "UPGRADE_REQUIRED" || code === "PLAN_REQUIRED" || status === 402)
+    return `${DOCS_BASE}/docs/authentication#pay-as-you-go-credits`;
+  if (status === 429 || status === 401)
+    return `${DOCS_BASE}/docs/authentication`;
+  return;
+}
+
+class ApiError extends SecondLayerError {
   status;
   body;
-  code;
-  constructor(status, message, body, code) {
-    super(message);
+  constructor(status, message, body, code, options = {}) {
+    super(message, {
+      code,
+      retryable: options.retryable ?? statusRetryable(status),
+      docsUrl: options.docsUrl ?? docsFor(status, code),
+      ...options.cause ? { cause: options.cause } : {},
+      ...options.details ? { details: options.details } : {},
+      ...options.metaMessages ? { metaMessages: options.metaMessages } : {},
+      ...options.retryAfterSeconds !== undefined ? { retryAfterSeconds: options.retryAfterSeconds } : {}
+    });
     this.status = status;
     this.body = body;
-    this.code = code;
     this.name = "ApiError";
   }
 }
 
+class AuthError extends ApiError {
+  status = 401;
+  constructor(message = "API key invalid or expired.") {
+    super(401, message);
+    this.name = "AuthError";
+  }
+}
+
+class RateLimitError extends ApiError {
+  retryAfter;
+  status = 429;
+  constructor(message = "Rate limited. Try again later.", retryAfter) {
+    super(429, message, undefined, undefined, {
+      retryable: true,
+      retryAfterSeconds: parseRetryAfter(retryAfter)
+    });
+    this.retryAfter = retryAfter;
+    this.name = "RateLimitError";
+  }
+}
+
+class ValidationError extends ApiError {
+  constructor(message, status, body) {
+    super(status, message, body, undefined, { retryable: false });
+    this.name = "ValidationError";
+  }
+}
+function parseRetryAfter(value) {
+  if (!value)
+    return;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0)
+    return seconds;
+  const date = Date.parse(value);
+  if (!Number.isNaN(date))
+    return Math.max(0, (date - Date.now()) / 1000);
+  return;
+}
+
 class VersionConflictError extends ApiError {
   currentVersion;
   expectedVersion;
@@ -29,7 +139,13 @@ class VersionConflictError extends ApiError {
 class ByoBreakingChangeError extends ApiError {
   details;
   constructor(message, details) {
-    super(422, message, details, "BYO_BREAKING_CHANGE");
+    super(422, message, details, "BYO_BREAKING_CHANGE", {
+      metaMessages: [
+        "Review and run manually on your database:",
+        details.plan.dropStatement,
+        ...details.plan.statements
+      ]
+    });
     this.name = "ByoBreakingChangeError";
     this.details = details;
   }
@@ -69,10 +185,12 @@ class BaseClient {
   baseUrl;
   apiKey;
   origin;
+  fetchImpl;
   constructor(options = {}) {
     this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
     this.apiKey = resolveApiKey(options.apiKey);
     this.origin = options.origin ?? "cli";
+    this.fetchImpl = options.fetchImpl ?? ((...args) => fetch(...args));
   }
   static authHeaders(apiKey) {
     const headers = {
@@ -113,27 +231,27 @@ class BaseClient {
         serializedBody = JSON.stringify(body, (_key, value) => typeof value === "bigint" ? value.toString() : value);
       } catch (err) {
         const detail = err instanceof Error ? err.message : String(err);
-        throw new ApiError(0, `Failed to serialize request body: ${detail}`);
+        throw new ApiError(0, `Failed to serialize request body: ${detail}`, undefined, undefined, { retryable: false });
       }
     }
     let response;
     try {
-      response = await fetch(url, {
+      response = await this.fetchImpl(url, {
         method,
         headers,
         body: serializedBody
       });
-    } catch {
-      throw new ApiError(0, `Cannot reach API at ${this.baseUrl}. Check your connection or try again.`);
+    } catch (err) {
+      throw new ApiError(0, `Cannot reach API at ${this.baseUrl}. Check your connection or try again.`, undefined, undefined, { retryable: true, cause: err instanceof Error ? err : undefined });
     }
     if (!response.ok) {
       if (response.status === 401) {
-        throw new ApiError(401, "API key invalid or expired.");
+        throw new AuthError;
       }
       if (response.status === 429) {
         const retryAfter = response.headers.get("Retry-After");
         const msg = retryAfter ? `Rate limited. Wait ${retryAfter} seconds.` : "Rate limited. Try again later.";
-        throw new ApiError(429, msg);
+        throw new RateLimitError(msg, retryAfter ?? undefined);
       }
       if (response.status >= 500) {
         throw new ApiError(response.status, `Server error. Try again or check status at ${this.baseUrl}/health`);
@@ -168,47 +286,14 @@ class BaseClient {
 }
 
 // src/streams/errors.ts
-class AuthError extends Error {
-  status = 401;
-  constructor(message = "API key invalid or expired.") {
-    super(message);
-    this.name = "AuthError";
-  }
-}
-
-class RateLimitError extends Error {
-  retryAfter;
-  status = 429;
-  constructor(message = "Rate limited. Try again later.", retryAfter) {
-    super(message);
-    this.retryAfter = retryAfter;
-    this.name = "RateLimitError";
-  }
-}
-
-class ValidationError extends Error {
-  status;
-  body;
-  constructor(message, status, body) {
-    super(message);
-    this.status = status;
-    this.body = body;
-    this.name = "ValidationError";
-  }
-}
-
-class StreamsServerError extends Error {
-  status;
-  body;
+class StreamsServerError extends ApiError {
   constructor(message, status, body) {
-    super(message);
-    this.status = status;
-    this.body = body;
+    super(status, message, body, undefined, { retryable: true });
     this.name = "StreamsServerError";
   }
 }
 
-class StreamsSignatureError extends Error {
+class StreamsSignatureError extends SecondLayerError {
   constructor(message = "Streams response signature verification failed.") {
     super(message);
     this.name = "StreamsSignatureError";
@@ -238,6 +323,19 @@ var Cursor = {
 function reorgKey(reorg) {
   return `${reorg.detected_at}|${reorg.fork_point_height}|${reorg.new_canonical_tip}`;
 }
+function assertFinalizedCheckpoint(returned, checkpoint) {
+  if (returned === null || returned === undefined)
+    return;
+  if (returned === checkpoint)
+    return;
+  const r = Cursor.parse(returned);
+  const c = checkpoint === null ? null : Cursor.parse(checkpoint);
+  const above = c === null || r.blockHeight > c.blockHeight || r.blockHeight === c.blockHeight && r.eventIndex > c.eventIndex;
+  if (above) {
+    const boundary = c ? ` ("${checkpoint}")` : " (none delivered yet)";
+    throw new ValidationError(`onBatch returned cursor "${returned}", above the last delivered finalized event${boundary}. With finalizedOnly, events past that point were filtered out and will be re-read once finalized — committing beyond it skips them permanently. Return ctx.cursor (or nothing); never envelope.next_cursor.`, 400);
+  }
+}
 function batchContext(cursor, height, tipHeight) {
   return {
     cursor,
@@ -246,6 +344,41 @@ function batchContext(cursor, height, tipHeight) {
     blocksBehind: height === null ? null : Math.max(0, tipHeight - height)
   };
 }
+var MAX_RETRY_AFTER_MS = 300000;
+function errRetryable(err) {
+  if (err && typeof err === "object" && "retryable" in err) {
+    return err.retryable === true;
+  }
+  return err instanceof TypeError;
+}
+function errRetryAfterMs(err) {
+  if (err && typeof err === "object" && "retryAfterSeconds" in err) {
+    const seconds = err.retryAfterSeconds;
+    if (typeof seconds === "number" && Number.isFinite(seconds)) {
+      return Math.min(seconds * 1000, MAX_RETRY_AFTER_MS);
+    }
+  }
+  return;
+}
+async function fetchPageWithRetry(fetchPage, opts) {
+  const retryCount = opts.retryCount ?? 3;
+  const retryDelay = opts.retryDelay ?? 1000;
+  for (let attempt = 0;; attempt++) {
+    try {
+      return await fetchPage();
+    } catch (err) {
+      const retriesLeft = retryCount - attempt;
+      if (retriesLeft <= 0 || !errRetryable(err) || opts.signal?.aborted) {
+        throw err;
+      }
+      const delayMs = errRetryAfterMs(err) ?? retryDelay * (attempt + 1);
+      opts.onError?.(err, { attempt, retriesLeft, delayMs });
+      await opts.sleep(delayMs, opts.signal);
+      if (opts.signal?.aborted)
+        throw err;
+    }
+  }
+}
 async function defaultSleep(ms, signal) {
   if (signal?.aborted)
     return;
@@ -272,7 +405,7 @@ async function consumeStreamsEvents(opts) {
   let emptyPolls = 0;
   let height = null;
   while (pages < maxPages && emptyPolls < maxEmptyPolls && !opts.signal?.aborted) {
-    const envelope = await opts.fetchEvents({
+    const envelope = await fetchPageWithRetry(() => opts.fetchEvents({
       cursor,
       limit: opts.batchSize,
       types: opts.types,
@@ -281,6 +414,12 @@ async function consumeStreamsEvents(opts) {
       sender: opts.sender,
       recipient: opts.recipient,
       assetIdentifier: opts.assetIdentifier
+    }), {
+      retryCount: opts.retryCount,
+      retryDelay: opts.retryDelay,
+      onError: opts.onError,
+      sleep,
+      signal: opts.signal
     });
     pages++;
     if (!finalizedOnly && opts.onReorg) {
@@ -302,6 +441,8 @@ async function consumeStreamsEvents(opts) {
     const checkpoint = finalizedOnly ? emitted.at(-1)?.cursor ?? cursor : envelope.next_cursor;
     height = emitted.at(-1)?.block_height ?? height;
     const returnedCursor = await opts.onBatch(emitted, envelope, batchContext(checkpoint, height, envelope.tip.block_height));
+    if (finalizedOnly)
+      assertFinalizedCheckpoint(returnedCursor, checkpoint);
     const nextCursor = returnedCursor ?? checkpoint;
     if (nextCursor && nextCursor !== cursor) {
       cursor = nextCursor;
@@ -785,7 +926,10 @@ function createStreamsClient(options) {
           emptyBackoffMs: params.emptyBackoffMs,
           maxPages: params.maxPages,
           maxEmptyPolls: params.maxEmptyPolls,
-          signal: params.signal
+          signal: params.signal,
+          retryCount: params.retryCount,
+          retryDelay: params.retryDelay,
+          onError: params.onError
         });
       },
       stream(params = {}) {
@@ -1181,5 +1325,5 @@ export {
   AuthError
 };
 
-//# debugId=2B52BCE7E3B3A40964756E2164756E21
+//# debugId=9793637197EFD6F364756E2164756E21
 //# sourceMappingURL=index.js.map