@secondlayer/sdk 10.4.3 → 10.5.0

package/dist/index.d.ts

@@ -39,6 +39,31 @@ interface SecondLayerOptions {
 	*  retry policy instead of stalling a walk or consume loop forever. `0`
 	*  disables the timeout. */
 	requestTimeoutMs?: number;
+	/** Where GET responses carrying an `ETag` are kept, so a repeat read sends
+	*  `If-None-Match` and a finalized page comes back as a free `304`.
+	*  Defaults to an in-memory store of the last 64 pages. Pass your own to
+	*  keep it across processes (a file, a KV), or `false` to turn it off. */
+	etagCache?: EtagCache | false;
+}
+/** One cached GET response: its validator and the body it validated. */
+type EtagEntry = {
+	etag: string;
+	body: string;
+};
+/** Storage for `etagCache`. Keys are full request URLs. Either method may be
+*  async, so a disk or KV store works as well as a Map. */
+interface EtagCache {
+	get(key: string): EtagEntry | undefined | Promise<EtagEntry | undefined>;
+	set(key: string, entry: EtagEntry): void | Promise<void>;
+}
+/** Bounded in-memory `EtagCache`. Evicts the least recently used page, so a
+*  long walk can't hold more than `limit` page bodies. */
+declare class MemoryEtagCache implements EtagCache {
+	private readonly limit;
+	private entries;
+	constructor(limit?: number);
+	get(key: string): EtagEntry | undefined;
+	set(key: string, entry: EtagEntry): void;
 }
 /** Default per-request budget. Long enough for a 1000-row filtered page on a
 *  cold cache, short enough that a half-open connection surfaces as a retry. */
@@ -72,6 +97,7 @@ declare abstract class BaseClient {
 	protected origin: "cli" | "mcp" | "session";
 	protected fetchImpl: FetchLike;
 	protected requestTimeoutMs: number;
+	protected etagCache: EtagCache | null;
 	constructor(options?: Partial<SecondLayerOptions>);
 	static authHeaders(apiKey?: string): Record<string, string>;
 	protected request<T>(method: string, path: string, body?: unknown, opts?: RequestOptions): Promise<T>;
@@ -88,7 +114,7 @@ declare abstract class BaseClient {
 	/** Issue the HTTP request and map non-2xx statuses onto the error family.
 	*  `signal` is the combined caller-plus-timeout signal from `request*`;
 	*  subclasses that stream a body call this directly and read it themselves. */
-	protected fetchResponse(method: string, path: string, body?: unknown, signal?: AbortSignal): Promise<Response>;
+	protected fetchResponse(method: string, path: string, body?: unknown, signal?: AbortSignal, extraHeaders?: Record<string, string>): Promise<Response>;
 }
 interface SubgraphSource {
 	name: string;
@@ -3189,4 +3215,4 @@ declare function verifySecondlayerSignature(rawBody: string, headers: WebhookHea
 declare function decodeChainWebhook(rawBody: string): ChainWebhookDelivery;
 import { RewardSet as RewardSet2 } from "@secondlayer/shared/node/consensus";
 import { decodeClarityValue, toJsonSafe } from "@secondlayer/shared/streams-rows";
-export { verifyWebhookSignature, verifyTransactionProof, verify as verifyStandardWebhooksHeaders, verifySecondlayerSignature, trigger, toJsonSafe, shutdownSignal, resolveBaseUrl, resolveApiKey, resolveAccountKey, 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, decode, createStreamsClient, createArchiveClient, contextField, consumerHealth, consumeIndexFeed, WithSinkTx, Webhooks, WebhookTestResult2 as WebhookTestResult, WebhookSummary2 as WebhookSummary, WebhookStatus, WebhookRuntime, WebhookKind, WebhookHeaderInput, WebhookFormat, WebhookDetail2 as WebhookDetail, WalkOptions, VmStreamsEvent, ValidationError, UpdateWebhookRequest2 as UpdateWebhookRequest, TransactionsWalkParams, TransactionsListParams, TransactionsEnvelope, TransactionProofVerifyResult, TransactionProof, TransactionEnvelope, Subgraphs, SubgraphSpecOptions3 as SubgraphSpecOptions, SubgraphSpecFormat2 as SubgraphSpecFormat, SubgraphOperationStatus, SubgraphAgentSchema3 as SubgraphAgentSchema, StreamsWireEvent2 as StreamsWireEvent, StreamsTip, StreamsSubscription, 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, SinkTx, SecondLayerOptions, SecondLayerErrorOptions, SecondLayerError, SecondLayerArchive, SecondLayer, SbtcWithdrawalsWalkParams, SbtcWithdrawalsListParams, SbtcWithdrawalsEnvelope, SbtcWithdrawalSweptConfirmedEvent, SbtcWithdrawalStatus, SbtcWithdrawalEvent, SbtcWithdrawalEnvelope, SbtcSummaryEnvelope, SbtcResource, SbtcEventsWalkParams, SbtcEventsListParams, SbtcEventsEnvelope, SbtcEventsConsumeParams, SbtcEventTopic2 as SbtcEventTopic, SbtcDepositsWalkParams, SbtcDepositsListParams, SbtcDepositsEnvelope, SbtcDepositsConsumeParams, SbtcDepositEvent, SbtcDepositEnvelope, RotateSecretResponse2 as RotateSecretResponse, RewardSet2 as RewardSet, RequestOptions, ReplayResult2 as ReplayResult, RateLimitError, PublicStatus2 as PublicStatus, PrintSchemaResponse, PoxResource, PoxCyclesWalkParams, PoxCyclesListParams, PoxCyclesEnvelope, PoxCycleEnvelope, Pox5Resource, Pox5EventsWalkParams, Pox5EventsListParams, Pox5EventsEnvelope, NftTransfersWalkParams, NftTransfersResource, NftTransfersListParams, NftTransfersEnvelope, NftTransferPayload2 as NftTransferPayload, NftTransferEvent, NftTransfer, MempoolWalkParams, MempoolTransactionEnvelope, MempoolListParams, MempoolEnvelope, LoadedArchive, LOCAL_API_URL, InsufficientArchiveCreditsError, InstanceStatus, InstanceState, InstanceIssue, InstanceDiagnosis3 as InstanceDiagnosis, InstanceClient, IndexVarSet, IndexTransaction, IndexTip, IndexStxTransfer, IndexStxMint, IndexStxLock, IndexStxBurn, IndexStackingAction, IndexSbtcWithdrawalPhase, IndexSbtcWithdrawalDetail, IndexSbtcWithdrawal, IndexSbtcSummary, IndexSbtcEvent, IndexSbtcDepositDetail, IndexSbtcDeposit, IndexReorg, IndexPrint, IndexPoxFunctionCount, IndexPoxCycle, IndexPox5EventTopic, IndexPox5Event, IndexPostCondition, IndexNftTransfer, IndexNftMint, IndexNftBurn, IndexNestedContractCall, IndexMempoolTransaction, IndexMapSet, IndexMapInsert, IndexMapDelete, IndexFtTransfer, IndexFtMint, IndexFtBurn, IndexFeedItem, IndexFeedFetcher, IndexFeedEnvelope, IndexEventsResource, IndexEventTypeFilters, IndexEventType, IndexEventOf, IndexEventFields, IndexEvent, IndexDiscovery, IndexContractCall, IndexConsumeOptions, IndexCanonicalBlock, IndexBlock, IndexAlwaysFields, Index, INSTANCE_TOKEN_ENV, INDEX_MAX_PAGE_SIZE, FtTransfersWalkParams, FtTransfersResource, FtTransfersListParams, FtTransfersEnvelope, FtTransferPayload2 as 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_REQUEST_TIMEOUT_MS, Cursor, CreateWebhookResponse2 as CreateWebhookResponse, CreateWebhookRequest2 as CreateWebhookRequest, CreateArchiveClientOptions, ContractsListParams, ContractsEnvelope, Contracts, ContractSummary, ContractConformance, ContractCallsWalkParams, ContractCallsListParams, ContractCallsEnvelope, ContractCallsConsumeParams, ContextSnapshot, ContextFieldError, ContextField, ContextAccount, ConsumerSink, ConsumerHealth, 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, BlocksWalkParams, BlocksListParams, BlocksEnvelope, BlockEnvelope, AuthError, ArchiveVerifyResult, ArchiveVerifyRangeStatus, ArchiveVerifyInput, ArchiveStatus, ArchiveSignatureError, ArchiveQuote, ArchivePartition, ArchiveManifest, ArchiveLoadOptions, ArchiveGateNotConfiguredError, ArchiveFlow, ArchiveFetchResult, ArchiveFetchItem, ArchiveDataset, ArchiveCreditsBalance, ArchiveClient, ArchiveAuthError, ApiError, ActiveSubgraphOperation, ACCOUNT_KEY_ENV };
+export { verifyWebhookSignature, verifyTransactionProof, verify as verifyStandardWebhooksHeaders, verifySecondlayerSignature, trigger, toJsonSafe, shutdownSignal, resolveBaseUrl, resolveApiKey, resolveAccountKey, 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, decode, createStreamsClient, createArchiveClient, contextField, consumerHealth, consumeIndexFeed, WithSinkTx, Webhooks, WebhookTestResult2 as WebhookTestResult, WebhookSummary2 as WebhookSummary, WebhookStatus, WebhookRuntime, WebhookKind, WebhookHeaderInput, WebhookFormat, WebhookDetail2 as WebhookDetail, WalkOptions, VmStreamsEvent, ValidationError, UpdateWebhookRequest2 as UpdateWebhookRequest, TransactionsWalkParams, TransactionsListParams, TransactionsEnvelope, TransactionProofVerifyResult, TransactionProof, TransactionEnvelope, Subgraphs, SubgraphSpecOptions3 as SubgraphSpecOptions, SubgraphSpecFormat2 as SubgraphSpecFormat, SubgraphOperationStatus, SubgraphAgentSchema3 as SubgraphAgentSchema, StreamsWireEvent2 as StreamsWireEvent, StreamsTip, StreamsSubscription, 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, SinkTx, SecondLayerOptions, SecondLayerErrorOptions, SecondLayerError, SecondLayerArchive, SecondLayer, SbtcWithdrawalsWalkParams, SbtcWithdrawalsListParams, SbtcWithdrawalsEnvelope, SbtcWithdrawalSweptConfirmedEvent, SbtcWithdrawalStatus, SbtcWithdrawalEvent, SbtcWithdrawalEnvelope, SbtcSummaryEnvelope, SbtcResource, SbtcEventsWalkParams, SbtcEventsListParams, SbtcEventsEnvelope, SbtcEventsConsumeParams, SbtcEventTopic2 as SbtcEventTopic, SbtcDepositsWalkParams, SbtcDepositsListParams, SbtcDepositsEnvelope, SbtcDepositsConsumeParams, SbtcDepositEvent, SbtcDepositEnvelope, RotateSecretResponse2 as RotateSecretResponse, RewardSet2 as RewardSet, RequestOptions, ReplayResult2 as ReplayResult, RateLimitError, PublicStatus2 as PublicStatus, PrintSchemaResponse, PoxResource, PoxCyclesWalkParams, PoxCyclesListParams, PoxCyclesEnvelope, PoxCycleEnvelope, Pox5Resource, Pox5EventsWalkParams, Pox5EventsListParams, Pox5EventsEnvelope, NftTransfersWalkParams, NftTransfersResource, NftTransfersListParams, NftTransfersEnvelope, NftTransferPayload2 as NftTransferPayload, NftTransferEvent, NftTransfer, MempoolWalkParams, MempoolTransactionEnvelope, MempoolListParams, MempoolEnvelope, MemoryEtagCache, LoadedArchive, LOCAL_API_URL, InsufficientArchiveCreditsError, InstanceStatus, InstanceState, InstanceIssue, InstanceDiagnosis3 as InstanceDiagnosis, InstanceClient, IndexVarSet, IndexTransaction, IndexTip, IndexStxTransfer, IndexStxMint, IndexStxLock, IndexStxBurn, IndexStackingAction, IndexSbtcWithdrawalPhase, IndexSbtcWithdrawalDetail, IndexSbtcWithdrawal, IndexSbtcSummary, IndexSbtcEvent, IndexSbtcDepositDetail, IndexSbtcDeposit, IndexReorg, IndexPrint, IndexPoxFunctionCount, IndexPoxCycle, IndexPox5EventTopic, IndexPox5Event, IndexPostCondition, IndexNftTransfer, IndexNftMint, IndexNftBurn, IndexNestedContractCall, IndexMempoolTransaction, IndexMapSet, IndexMapInsert, IndexMapDelete, IndexFtTransfer, IndexFtMint, IndexFtBurn, IndexFeedItem, IndexFeedFetcher, IndexFeedEnvelope, IndexEventsResource, IndexEventTypeFilters, IndexEventType, IndexEventOf, IndexEventFields, IndexEvent, IndexDiscovery, IndexContractCall, IndexConsumeOptions, IndexCanonicalBlock, IndexBlock, IndexAlwaysFields, Index, INSTANCE_TOKEN_ENV, INDEX_MAX_PAGE_SIZE, FtTransfersWalkParams, FtTransfersResource, FtTransfersListParams, FtTransfersEnvelope, FtTransferPayload2 as FtTransferPayload, FtTransferEvent, FtTransfer, FetchLike2 as FetchLike, EventsWalkParams, EventsListParams, EventsEnvelope, EventsConsumeParams, EtagEntry, EtagCache, 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_REQUEST_TIMEOUT_MS, Cursor, CreateWebhookResponse2 as CreateWebhookResponse, CreateWebhookRequest2 as CreateWebhookRequest, CreateArchiveClientOptions, ContractsListParams, ContractsEnvelope, Contracts, ContractSummary, ContractConformance, ContractCallsWalkParams, ContractCallsListParams, ContractCallsEnvelope, ContractCallsConsumeParams, ContextSnapshot, ContextFieldError, ContextField, ContextAccount, ConsumerSink, ConsumerHealth, 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, BlocksWalkParams, BlocksListParams, BlocksEnvelope, BlockEnvelope, AuthError, ArchiveVerifyResult, ArchiveVerifyRangeStatus, ArchiveVerifyInput, ArchiveStatus, ArchiveSignatureError, ArchiveQuote, ArchivePartition, ArchiveManifest, ArchiveLoadOptions, ArchiveGateNotConfiguredError, ArchiveFlow, ArchiveFetchResult, ArchiveFetchItem, ArchiveDataset, ArchiveCreditsBalance, ArchiveClient, ArchiveAuthError, ApiError, ActiveSubgraphOperation, ACCOUNT_KEY_ENV };

package/dist/index.js

@@ -156,6 +156,30 @@ function parseRetryAfter(value) {
 }
 
 // src/base.ts
+class MemoryEtagCache {
+  limit;
+  entries = new Map;
+  constructor(limit = 64) {
+    this.limit = limit;
+  }
+  get(key) {
+    const entry = this.entries.get(key);
+    if (entry) {
+      this.entries.delete(key);
+      this.entries.set(key, entry);
+    }
+    return entry;
+  }
+  set(key, entry) {
+    this.entries.delete(key);
+    this.entries.set(key, entry);
+    if (this.entries.size > this.limit) {
+      const oldest = this.entries.keys().next().value;
+      if (oldest !== undefined)
+        this.entries.delete(oldest);
+    }
+  }
+}
 var DEFAULT_REQUEST_TIMEOUT_MS = 30000;
 function abortError() {
   return new DOMException("This operation was aborted", "AbortError");
@@ -266,12 +290,14 @@ class BaseClient {
   origin;
   fetchImpl;
   requestTimeoutMs;
+  etagCache;
   constructor(options = {}) {
     this.baseUrl = resolveBaseUrl(options.baseUrl);
     this.apiKey = resolveApiKey(options.apiKey);
     this.origin = options.origin ?? "cli";
     this.requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
     this.fetchImpl = options.fetchImpl ?? ((...args) => fetch(...args));
+    this.etagCache = options.etagCache === false ? null : options.etagCache ?? new MemoryEtagCache;
   }
   static authHeaders(apiKey) {
     const headers = {
@@ -284,11 +310,25 @@ class BaseClient {
   }
   async request(method, path, body, opts = {}) {
     return this.withRequestBudget(opts.signal, async (signal) => {
-      const response = await this.fetchResponse(method, path, body, signal);
+      const cacheKey = method === "GET" && this.etagCache ? `${this.baseUrl}${path}` : null;
+      const cached = cacheKey ? await this.etagCache?.get(cacheKey) : undefined;
+      const response = await this.fetchResponse(method, path, body, signal, cached ? { "If-None-Match": cached.etag } : undefined);
       if (response.status === 204) {
         return;
       }
-      return await raceAbort(response.json(), signal);
+      if (response.status === 304) {
+        if (!cached) {
+          throw new ApiError(304, "Not Modified without a cached copy");
+        }
+        return JSON.parse(cached.body);
+      }
+      const etag = cacheKey ? response.headers.get("ETag") : null;
+      if (!cacheKey || !etag) {
+        return await raceAbort(response.json(), signal);
+      }
+      const text = await raceAbort(response.text(), signal);
+      await this.etagCache?.set(cacheKey, { etag, body: text });
+      return JSON.parse(text);
     });
   }
   async requestOrNull(method, path, body, opts = {}) {
@@ -331,9 +371,12 @@ class BaseClient {
       callerSignal?.removeEventListener("abort", forward);
     }
   }
-  async fetchResponse(method, path, body, signal) {
+  async fetchResponse(method, path, body, signal, extraHeaders) {
     const url = `${this.baseUrl}${path}`;
-    const headers = BaseClient.authHeaders(this.apiKey);
+    const headers = {
+      ...BaseClient.authHeaders(this.apiKey),
+      ...extraHeaders
+    };
     headers["x-sl-origin"] = this.origin;
     let serializedBody;
     if (body !== undefined && body !== null) {
@@ -358,6 +401,8 @@ class BaseClient {
         throw 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.status === 304)
+      return response;
     if (!response.ok) {
       const errorBody = signal ? await raceAbort(response.text(), signal) : await response.text();
       const envelope = parseErrorEnvelope(errorBody);
@@ -2918,6 +2963,7 @@ export {
   SecondLayerError,
   SecondLayer,
   RateLimitError,
+  MemoryEtagCache,
   LOCAL_API_URL,
   InsufficientArchiveCreditsError,
   Index,
@@ -2934,5 +2980,5 @@ export {
   ACCOUNT_KEY_ENV
 };
 
-//# debugId=1A9F98DFDABD122264756E2164756E21
+//# debugId=0B87C7F2FE748A2E64756E2164756E21
 //# sourceMappingURL=index.js.map