@secondlayer/sdk 6.36.0 → 6.37.1

package/dist/subgraphs/index.d.ts

@@ -277,6 +277,8 @@ declare class Contracts extends BaseClient {
 		includeAbi?: boolean
 	}): Promise<ContractSummary | null>;
 }
+import { Pox5EventTopic } from "@secondlayer/stacks/pox5";
+import { SbtcEventTopic } from "@secondlayer/stacks/sbtc";
 import { InferredTopicSchema } from "@secondlayer/subgraphs";
 import { RewardSet } from "@secondlayer/shared/node/consensus";
 import { MerkleProofStep } from "@secondlayer/shared/node/nakamoto";
@@ -587,6 +589,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
@@ -774,6 +788,23 @@ type StreamsUsage = {
 	}
 };
 type Sleep = (ms: number, signal?: AbortSignal) => Promise<void>;
+/** Options shared by both consume loops' page-fetch retry. Vocabulary matches
+*  `@secondlayer/stacks` transports (`retryCount`/`retryDelay`) — one retry
+*  language across the family, not a third. */
+type PageRetryOptions = {
+	/** Retries after the first failure. Default 3; `0` disables. */
+	retryCount?: number
+	/** Base delay in ms; the n-th retry waits `retryDelay * n` (matches the
+	*  stacks transport). A server `Retry-After` overrides it. Default 1000. */
+	retryDelay?: number
+	/** Void observer, called before each retry sleep (metrics/logging). The
+	*  retry policy owns the decision; this cannot change it. */
+	onError?: (err: unknown, ctx: {
+		attempt: number
+		retriesLeft: number
+		delayMs: number
+	}) => void
+};
 /** Minimum shape a consumed Index row must expose. */
 type IndexFeedItem = {
 	cursor: string
@@ -815,6 +846,15 @@ type IndexConsumeOptions<
 	maxPages?: number
 	maxEmptyPolls?: number
 	signal?: AbortSignal
+	/** 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. Cannot change the retry
+	*  decision — the policy owns it. */
+	onError?: PageRetryOptions["onError"]
 };
 type IndexTip = {
 	block_height: number
@@ -1374,8 +1414,6 @@ type PrintSchemaResponse = {
 	}
 	tip: IndexTip
 };
-/** The decoded `sbtc_events` topics. */
-type SbtcEventTopic = "completed-deposit" | "withdrawal-create" | "withdrawal-accept" | "withdrawal-reject" | "key-rotation" | "update-protocol-contract";
 type SbtcWithdrawalStatus = "REQUESTED" | "ACCEPTED" | "REJECTED";
 /** A completed sBTC peg-in, keyed by `bitcoin_txid` (deposits carry no
 *  `request_id`). One terminal `completed-deposit` event per deposit. */
@@ -1665,10 +1703,10 @@ interface PoxResource {
 		get(rewardCycle: number): Promise<PoxCycleEnvelope | null>
 	};
 }
-/** The decoded `pox-5` boot-contract print topics (SIP-045 Bitcoin Staking).
-*  Declared locally rather than imported from the server packages — the SDK is
-*  published and owns its own dependency surface (same as {@link SbtcEventTopic}). */
-type IndexPox5EventTopic = "set-bond-admin" | "set-pause-admin" | "pause-rewards" | "setup-bond" | "add-to-allowlist" | "register-for-bond" | "update-bond-registration" | "register-signer" | "stake" | "stake-update" | "announce-l1-early-exit" | "unstake-sbtc" | "unstake" | "calculate-rewards" | "bond-distribution" | "claim-rewards" | "claim-staker-rewards-for-signer" | "grant-signer-key" | "revoke-signer-grant";
+/** The decoded `pox-5` boot-contract print topics (SIP-045 Bitcoin Staking) —
+*  one source of truth in `@secondlayer/stacks/pox5` (already a dependency;
+*  the old "SDK owns its own dependency surface" rationale predated that). */
+type IndexPox5EventTopic = Pox5EventTopic;
 /** A raw decoded PoX-5 print event. Promoted fields cover the hot query paths;
 *  `data` always carries the full decoded tuple, including nested shapes
 *  (`btc-lockup`, `bond-rewards`, `bond-periods`) that have no flat column. */

package/dist/subgraphs/index.js

@@ -1,17 +1,127 @@
 // 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;
@@ -26,7 +136,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;
   }
@@ -112,7 +228,7 @@ 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;
@@ -122,17 +238,17 @@ class BaseClient {
         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`);
@@ -426,47 +542,14 @@ class Contracts extends 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";
@@ -517,6 +600,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;
@@ -543,7 +661,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,
@@ -552,6 +670,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) {
@@ -682,10 +806,16 @@ async function consumeIndexFeed(opts) {
   let emptyPolls = 0;
   let height = null;
   while (pages < maxPages && emptyPolls < maxEmptyPolls && !opts.signal?.aborted) {
-    const envelope = await opts.fetchPage({
+    const envelope = await fetchPageWithRetry(() => opts.fetchPage({
       cursor,
       fromHeight: cursor === null ? opts.fromHeight : undefined,
       limit: batchSize
+    }), {
+      retryCount: opts.retryCount,
+      retryDelay: opts.retryDelay,
+      onError: opts.onError,
+      sleep,
+      signal: opts.signal
     });
     pages++;
     if (!finalizedOnly && opts.onReorg) {
@@ -1574,7 +1704,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 = {}) {
@@ -1809,5 +1942,5 @@ export {
   Subgraphs
 };
 
-//# debugId=13B6D7F76CAEAFE964756E2164756E21
+//# debugId=A36A74FD0514129964756E2164756E21
 //# sourceMappingURL=index.js.map