@secondlayer/sdk 6.36.0 → 6.37.0

package/dist/index.d.ts

@@ -641,6 +641,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
@@ -829,6 +841,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
@@ -878,6 +907,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"]
 };
 /**
 * Checkpointed pull loop over a cursor-paginated Index feed — the Index port
@@ -2217,27 +2255,141 @@ type CreateStreamsClientOptions = {
 	verifyDumpsManifest?: boolean
 };
 declare function createStreamsClient(options: CreateStreamsClientOptions): StreamsClient;
-declare class AuthError extends Error {
-	readonly status = 401;
+import { ByoBreakingChangeDetails } from "@secondlayer/shared/errors";
+/** 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;
+/** Parse a `Retry-After` header: delta-seconds or an HTTP-date. */
+declare function parseRetryAfter(value?: string | null): number | undefined;
+/**
+* Thrown on optimistic-concurrency conflict when a deploy supplies an
+* `expectedVersion` that no longer matches the server's stored version.
+*/
+declare class VersionConflictError extends ApiError {
+	currentVersion: string;
+	expectedVersion: string;
+	constructor(currentVersion: string, expectedVersion: string, message?: string);
+}
+/**
+* Thrown when a BYO subgraph deploy is refused for a breaking schema change.
+* The deploy did NOT run — `details.plan` carries the DROP + rebuild DDL to run
+* manually on your own database, plus the breaking `reasons` and the `diff`.
+* The same DDL is surfaced on `metaMessages`, so a bare `console.error(err)`
+* already shows the operator what to run.
+*
+* @example
+* ```ts
+* try {
+*   await client.subgraphs.deploy(bundle);
+* } catch (err) {
+*   if (err instanceof ByoBreakingChangeError) {
+*     console.log(err.details.plan.dropStatement);
+*     console.log(err.details.plan.statements.join(";
+"));
+*   }
+* }
+* ```
+*/
+declare class ByoBreakingChangeError extends ApiError {
+	readonly details: ByoBreakingChangeDetails;
+	constructor(message: string, details: ByoBreakingChangeDetails);
+}
+/** 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, {
@@ -2677,62 +2829,6 @@ type PayAndRetryOptions = Omit<WithX402Options, never> & {
 */
 declare function payAndRetry(doFetch: X402FetchFn, opts: PayAndRetryOptions): Promise<Response>;
 import { SubgraphAgentSchema as SubgraphAgentSchema3, SubgraphSpecFormat as SubgraphSpecFormat2, SubgraphSpecOptions as SubgraphSpecOptions3 } from "@secondlayer/shared/subgraphs/spec";
-import { ByoBreakingChangeDetails } from "@secondlayer/shared/errors";
-/**
-* 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 Error {
-	/** 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;
-	/** Stable machine-readable code from the API's `{error, code}` error envelope. */
-	code?: string;
-	constructor(status: number, message: string, body?: unknown, code?: string);
-}
-/**
-* Thrown on optimistic-concurrency conflict when a deploy supplies an
-* `expectedVersion` that no longer matches the server's stored version.
-*/
-declare class VersionConflictError extends ApiError {
-	currentVersion: string;
-	expectedVersion: string;
-	constructor(currentVersion: string, expectedVersion: string, message?: string);
-}
-/**
-* Thrown when a BYO subgraph deploy is refused for a breaking schema change.
-* The deploy did NOT run — `details.plan` carries the DROP + rebuild DDL to run
-* manually on your own database, plus the breaking `reasons` and the `diff`.
-*
-* @example
-* ```ts
-* try {
-*   await client.subgraphs.deploy(bundle);
-* } catch (err) {
-*   if (err instanceof ByoBreakingChangeError) {
-*     console.log(err.details.plan.dropStatement);
-*     console.log(err.details.plan.statements.join(";
-"));
-*   }
-* }
-* ```
-*/
-declare class ByoBreakingChangeError extends ApiError {
-	readonly details: ByoBreakingChangeDetails;
-	constructor(message: string, details: ByoBreakingChangeDetails);
-}
 import { ChainWebhookDelivery } from "@secondlayer/shared";
 import { StandardWebhooksHeaders } from "@secondlayer/shared/crypto/standard-webhooks";
 import { StandardWebhooksHeaders as StandardWebhooksHeaders2, verify } from "@secondlayer/shared/crypto/standard-webhooks";
@@ -2896,4 +2992,4 @@ declare function toJsonSafe(value: unknown): unknown;
 /** Decode a hex-encoded Clarity value to JSON-safe JS (uints as strings,
 *  buffers as `0x…` hex, tuples as objects). Returns the input hex on failure. */
 declare function decodeClarityValue(hex: string): unknown;
-export { withX402, verifyWebhookSignature, verifyTransactionProof, verify as verifyStandardWebhooksHeaders, verifySecondlayerSignature, trigger, toJsonSafe, selectOffer, resolveApiKey, resolveAccountNonce, readX402Receipt, readX402Challenge, payAndRetry, isStxTransfer, isStxMint, isStxLock, isStxBurn, isPrint, isNftTransfer, isNftMint, isNftBurn, isFtTransfer, isFtMint, isFtBurn, getSubgraph, fetchRewardSet, decodeStxTransfer, decodeStxMint, decodeStxLock, decodeStxBurn, decodePrint, decodeNftTransfer, decodeNftMint, decodeNftBurn, decodeFtTransfer, decodeFtMint, decodeFtBurn, decodeClarityValue, decodeChainWebhook, createX402Client, createStreamsClient, consumeIndexFeed, buildSignedX402Payment, X402SpendGuardError, X402Result, X402Receipt, X402Fetch, X402ClientOptions, X402Client, X402Challenge, X402Accept, WithX402Options, WebhookHeaderInput, VersionConflictError, ValidationError, UpdateSubscriptionRequest2 as UpdateSubscriptionRequest, UpdateProjectParams, TransactionsWalkParams, TransactionsListParams, TransactionsEnvelope, TransactionProofVerifyResult, TransactionProof, TransactionEnvelope, Subscriptions, SubscriptionSummary2 as SubscriptionSummary, SubscriptionStatus, SubscriptionRuntime, SubscriptionKind, SubscriptionFormat, SubscriptionDetail2 as SubscriptionDetail, Subgraphs, SubgraphSpecOptions3 as SubgraphSpecOptions, SubgraphSpecFormat2 as SubgraphSpecFormat, SubgraphOperationStatus, SubgraphAgentSchema3 as SubgraphAgentSchema, StreamsUsage, StreamsTip, StreamsSignatureError, StreamsServerError, StreamsReorgsListParams, StreamsReorgsListEnvelope, StreamsReorgContext, StreamsReorg, StreamsEventsSubscribeParams, StreamsEventsStreamParams, StreamsEventsListParams, StreamsEventsListEnvelope, StreamsEventsEnvelope, StreamsEventsConsumeResult, StreamsEventsConsumeParams, StreamsEventType, StreamsEventPayload, StreamsEvent, StreamsDumpsManifest, StreamsDumps, StreamsDumpFile, StreamsConsumeParams, StreamsClient, StreamsCanonicalBlock, StreamsBatchContext, StreamsBatch, StandardWebhooksHeaders2 as StandardWebhooksHeaders, StackingWalkParams, StackingListParams, StackingEnvelope, SelectOfferOptions, SecondLayerOptions, SecondLayer, ScopedKeyProduct, SbtcWithdrawalsWalkParams, SbtcWithdrawalsListParams, SbtcWithdrawalsEnvelope, SbtcWithdrawalSweptConfirmedEvent, SbtcWithdrawalStatus, SbtcWithdrawalEvent, SbtcWithdrawalEnvelope, SbtcSummaryEnvelope, SbtcResource, SbtcEventsWalkParams, SbtcEventsListParams, SbtcEventsEnvelope, SbtcEventsConsumeParams, SbtcEventTopic, SbtcDepositsWalkParams, SbtcDepositsListParams, SbtcDepositsEnvelope, SbtcDepositsConsumeParams, SbtcDepositEvent, SbtcDepositEnvelope, RotateSecretResponse2 as RotateSecretResponse, RewardSet2 as RewardSet, ReplayResult2 as ReplayResult, RateLimitError, Projects, ProjectTeamMember, ProjectTeam, ProjectInvitation, Project, PrintSchemaResponse, PoxResource, PoxCyclesWalkParams, PoxCyclesListParams, PoxCyclesEnvelope, PoxCycleEnvelope, Pox5Resource, Pox5EventsWalkParams, Pox5EventsListParams, Pox5EventsEnvelope, PayAndRetryOptions, NftTransfersWalkParams, NftTransfersResource, NftTransfersListParams, NftTransfersEnvelope, NftTransferPayload, NftTransferEvent, NftTransfer, MempoolWalkParams, MempoolTransactionEnvelope, MempoolListParams, MempoolEnvelope, IndexUsage, IndexTransaction, IndexTip, IndexStxTransfer, IndexStxMint, IndexStxLock, IndexStxBurn, IndexStackingAction, IndexSbtcWithdrawalPhase, IndexSbtcWithdrawalDetail, IndexSbtcWithdrawal, IndexSbtcSummary, IndexSbtcEvent, IndexSbtcDepositDetail, IndexSbtcDeposit, IndexReorg, IndexPrint, IndexPoxFunctionCount, IndexPoxCycle, IndexPox5EventTopic, IndexPox5Event, IndexPostCondition, IndexNftTransfer, IndexNftMint, IndexNftBurn, IndexMempoolTransaction, IndexFtTransfer, IndexFtMint, IndexFtBurn, IndexFeedItem, IndexFeedFetcher, IndexFeedEnvelope, IndexEventsResource, IndexEventTypeFilters, IndexEventType, IndexEventOf, IndexEvent, IndexDiscovery, IndexContractCall, IndexConsumeOptions, IndexCanonicalBlock, IndexBlock, Index, FtTransfersWalkParams, FtTransfersResource, FtTransfersListParams, FtTransfersEnvelope, FtTransferPayload, FtTransferEvent, FtTransfer, FetchLike2 as FetchLike, EventsWalkParams, EventsListParams, EventsEnvelope, EventsConsumeParams, DeliveryRow2 as DeliveryRow, 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, DeadRow2 as DeadRow, DEFAULT_PREFER_ASSETS, Cursor, CreateSubscriptionResponse2 as CreateSubscriptionResponse, CreateSubscriptionRequest2 as CreateSubscriptionRequest, CreateProjectParams, CreateApiKeyResponse, CreateApiKeyParams, ContractsListParams, ContractsEnvelope, Contracts, ContractSummary, ContractConformance, ContractCallsWalkParams, ContractCallsListParams, ContractCallsEnvelope, ContractCallsConsumeParams, ContextSnapshot, ContextProject, ContextApiKey, ContextAccount, ConsumerBatchContext, ChainWebhookEnvelope, ChainWebhookDelivery2 as ChainWebhookDelivery, ChainTxLevelEvent, ChainTriggerType, ChainTrigger, ChainTestDelivery, ChainStxTransferData, ChainStxMintData, ChainStxLockData, ChainStxBurnData, ChainReorgRollbackEnvelope, ChainReorgRollbackDelivery, ChainReorgOrphanedEntry, ChainPrintEventData, ChainNftTransferData, ChainNftMintData, ChainNftBurnData, ChainFtTransferData, ChainFtMintData, ChainFtBurnData, ChainEventEnvelope, ChainApplyEnvelopeOf, ChainApplyEnvelope, ChainApplyDeliveryOf, CanonicalWalkParams, CanonicalListParams, CanonicalEnvelope, ByoBreakingChangeError, ByoBreakingChangeDetails, BuildSignedX402PaymentOptions, BlocksWalkParams, BlocksListParams, BlocksEnvelope, BlockEnvelope, AuthError, ApiKeys, ApiKeySummary, ApiError, ActiveSubgraphOperation };
+export { withX402, verifyWebhookSignature, verifyTransactionProof, verify as verifyStandardWebhooksHeaders, verifySecondlayerSignature, trigger, toJsonSafe, selectOffer, resolveApiKey, resolveAccountNonce, readX402Receipt, readX402Challenge, payAndRetry, parseRetryAfter, isStxTransfer, isStxMint, isStxLock, isStxBurn, isPrint, isNftTransfer, isNftMint, isNftBurn, isFtTransfer, isFtMint, isFtBurn, getSubgraph, fetchRewardSet, decodeStxTransfer, decodeStxMint, decodeStxLock, decodeStxBurn, decodePrint, decodeNftTransfer, decodeNftMint, decodeNftBurn, decodeFtTransfer, decodeFtMint, decodeFtBurn, decodeClarityValue, decodeChainWebhook, createX402Client, createStreamsClient, consumeIndexFeed, buildSignedX402Payment, X402SpendGuardError, X402Result, X402Receipt, X402Fetch, X402ClientOptions, X402Client, X402Challenge, X402Accept, WithX402Options, WebhookHeaderInput, VersionConflictError, ValidationError, UpdateSubscriptionRequest2 as UpdateSubscriptionRequest, UpdateProjectParams, TransactionsWalkParams, TransactionsListParams, TransactionsEnvelope, TransactionProofVerifyResult, TransactionProof, TransactionEnvelope, Subscriptions, SubscriptionSummary2 as SubscriptionSummary, SubscriptionStatus, SubscriptionRuntime, SubscriptionKind, SubscriptionFormat, SubscriptionDetail2 as SubscriptionDetail, Subgraphs, SubgraphSpecOptions3 as SubgraphSpecOptions, SubgraphSpecFormat2 as SubgraphSpecFormat, SubgraphOperationStatus, SubgraphAgentSchema3 as SubgraphAgentSchema, StreamsUsage, StreamsTip, StreamsSignatureError, StreamsServerError, StreamsReorgsListParams, StreamsReorgsListEnvelope, StreamsReorgContext, StreamsReorg, StreamsEventsSubscribeParams, StreamsEventsStreamParams, StreamsEventsListParams, StreamsEventsListEnvelope, StreamsEventsEnvelope, StreamsEventsConsumeResult, StreamsEventsConsumeParams, StreamsEventType, StreamsEventPayload, StreamsEvent, StreamsDumpsManifest, StreamsDumps, StreamsDumpFile, StreamsConsumeParams, StreamsClient, StreamsCanonicalBlock, StreamsBatchContext, StreamsBatch, StandardWebhooksHeaders2 as StandardWebhooksHeaders, StackingWalkParams, StackingListParams, StackingEnvelope, SelectOfferOptions, SecondLayerOptions, SecondLayerErrorOptions, SecondLayerError, SecondLayer, ScopedKeyProduct, SbtcWithdrawalsWalkParams, SbtcWithdrawalsListParams, SbtcWithdrawalsEnvelope, SbtcWithdrawalSweptConfirmedEvent, SbtcWithdrawalStatus, SbtcWithdrawalEvent, SbtcWithdrawalEnvelope, SbtcSummaryEnvelope, SbtcResource, SbtcEventsWalkParams, SbtcEventsListParams, SbtcEventsEnvelope, SbtcEventsConsumeParams, SbtcEventTopic, SbtcDepositsWalkParams, SbtcDepositsListParams, SbtcDepositsEnvelope, SbtcDepositsConsumeParams, SbtcDepositEvent, SbtcDepositEnvelope, RotateSecretResponse2 as RotateSecretResponse, RewardSet2 as RewardSet, ReplayResult2 as ReplayResult, RateLimitError, Projects, ProjectTeamMember, ProjectTeam, ProjectInvitation, Project, PrintSchemaResponse, PoxResource, PoxCyclesWalkParams, PoxCyclesListParams, PoxCyclesEnvelope, PoxCycleEnvelope, Pox5Resource, Pox5EventsWalkParams, Pox5EventsListParams, Pox5EventsEnvelope, PayAndRetryOptions, NftTransfersWalkParams, NftTransfersResource, NftTransfersListParams, NftTransfersEnvelope, NftTransferPayload, NftTransferEvent, NftTransfer, MempoolWalkParams, MempoolTransactionEnvelope, MempoolListParams, MempoolEnvelope, IndexUsage, IndexTransaction, IndexTip, IndexStxTransfer, IndexStxMint, IndexStxLock, IndexStxBurn, IndexStackingAction, IndexSbtcWithdrawalPhase, IndexSbtcWithdrawalDetail, IndexSbtcWithdrawal, IndexSbtcSummary, IndexSbtcEvent, IndexSbtcDepositDetail, IndexSbtcDeposit, IndexReorg, IndexPrint, IndexPoxFunctionCount, IndexPoxCycle, IndexPox5EventTopic, IndexPox5Event, IndexPostCondition, IndexNftTransfer, IndexNftMint, IndexNftBurn, IndexMempoolTransaction, IndexFtTransfer, IndexFtMint, IndexFtBurn, IndexFeedItem, IndexFeedFetcher, IndexFeedEnvelope, IndexEventsResource, IndexEventTypeFilters, IndexEventType, IndexEventOf, IndexEvent, IndexDiscovery, IndexContractCall, IndexConsumeOptions, IndexCanonicalBlock, IndexBlock, Index, FtTransfersWalkParams, FtTransfersResource, FtTransfersListParams, FtTransfersEnvelope, FtTransferPayload, FtTransferEvent, FtTransfer, FetchLike2 as FetchLike, EventsWalkParams, EventsListParams, EventsEnvelope, EventsConsumeParams, DeliveryRow2 as DeliveryRow, 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, DeadRow2 as DeadRow, DEFAULT_PREFER_ASSETS, Cursor, CreateSubscriptionResponse2 as CreateSubscriptionResponse, CreateSubscriptionRequest2 as CreateSubscriptionRequest, CreateProjectParams, CreateApiKeyResponse, CreateApiKeyParams, ContractsListParams, ContractsEnvelope, Contracts, ContractSummary, ContractConformance, ContractCallsWalkParams, ContractCallsListParams, ContractCallsEnvelope, ContractCallsConsumeParams, ContextSnapshot, ContextProject, ContextApiKey, ContextAccount, ConsumerBatchContext, ChainWebhookEnvelope, ChainWebhookDelivery2 as ChainWebhookDelivery, ChainTxLevelEvent, ChainTriggerType, ChainTrigger, ChainTestDelivery, ChainStxTransferData, ChainStxMintData, ChainStxLockData, ChainStxBurnData, ChainReorgRollbackEnvelope, ChainReorgRollbackDelivery, ChainReorgOrphanedEntry, ChainPrintEventData, ChainNftTransferData, ChainNftMintData, ChainNftBurnData, ChainFtTransferData, ChainFtMintData, ChainFtBurnData, ChainEventEnvelope, ChainApplyEnvelopeOf, ChainApplyEnvelope, ChainApplyDeliveryOf, CanonicalWalkParams, CanonicalListParams, CanonicalEnvelope, ByoBreakingChangeError, ByoBreakingChangeDetails, BuildSignedX402PaymentOptions, BlocksWalkParams, BlocksListParams, BlocksEnvelope, BlockEnvelope, AuthError, ApiKeys, ApiKeySummary, ApiError, ActiveSubgraphOperation };

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;
   }
@@ -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 = {}) {
@@ -2472,6 +2605,7 @@ export {
   readX402Receipt,
   readX402Challenge,
   payAndRetry,
+  parseRetryAfter,
   isStxTransfer,
   isStxMint,
   isStxLock,
@@ -2509,6 +2643,7 @@ export {
   Subgraphs,
   StreamsSignatureError,
   StreamsServerError,
+  SecondLayerError,
   SecondLayer,
   RateLimitError,
   Projects,
@@ -2522,5 +2657,5 @@ export {
   ApiError
 };
 
-//# debugId=7D05343D5E23B9E764756E2164756E21
+//# debugId=D57E218C0E8C77C464756E2164756E21
 //# sourceMappingURL=index.js.map