@secondlayer/sdk 6.35.0 → 6.37.0

package/dist/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;
   }
@@ -66,10 +182,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 = {
@@ -110,27 +228,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`);
@@ -424,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";
@@ -494,6 +579,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,
@@ -502,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;
@@ -528,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,
@@ -537,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) {
@@ -558,6 +697,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;
@@ -665,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) {
@@ -691,6 +838,8 @@ async function consumeIndexFeed(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;
@@ -1555,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 = {}) {
@@ -2094,11 +2246,17 @@ class X402SpendGuardError extends Error {
   }
 }
 function b64encode(value) {
-  return Buffer.from(JSON.stringify(value), "utf8").toString("base64");
+  const utf8 = new TextEncoder().encode(JSON.stringify(value));
+  let binary = "";
+  for (const byte of utf8)
+    binary += String.fromCharCode(byte);
+  return btoa(binary);
 }
 function b64decodeJson(value) {
   try {
-    return JSON.parse(Buffer.from(value, "base64").toString("utf8"));
+    const binary = atob(value);
+    const utf8 = Uint8Array.from(binary, (ch) => ch.charCodeAt(0));
+    return JSON.parse(new TextDecoder().decode(utf8));
   } catch {
     return null;
   }
@@ -2368,8 +2526,9 @@ import {
   stacksTxid,
   verifyTxMerkleProof
 } from "@secondlayer/shared/node/nakamoto";
+import { hexToBytes } from "@secondlayer/stacks/utils";
 var strip = (h) => h.startsWith("0x") ? h.slice(2) : h;
-var bytes = (h) => Uint8Array.from(Buffer.from(strip(h), "hex"));
+var bytes = (h) => hexToBytes(h);
 async function fetchRewardSet(opts) {
   const f = opts.fetchImpl ?? fetch;
   const res = await f(`${opts.nodeUrl.replace(/\/+$/, "")}/v3/stacker_set/${opts.cycle}`);
@@ -2446,6 +2605,7 @@ export {
   readX402Receipt,
   readX402Challenge,
   payAndRetry,
+  parseRetryAfter,
   isStxTransfer,
   isStxMint,
   isStxLock,
@@ -2483,6 +2643,7 @@ export {
   Subgraphs,
   StreamsSignatureError,
   StreamsServerError,
+  SecondLayerError,
   SecondLayer,
   RateLimitError,
   Projects,
@@ -2496,5 +2657,5 @@ export {
   ApiError
 };
 
-//# debugId=D5B171025CDFC80A64756E2164756E21
+//# debugId=D57E218C0E8C77C464756E2164756E21
 //# sourceMappingURL=index.js.map