@secondlayer/sdk 10.4.2 → 10.5.0

package/dist/subgraphs/index.d.ts

@@ -39,6 +39,22 @@ 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>;
 }
 /** Per-call options every `request*` method accepts. */
 type RequestOptions = {
@@ -52,6 +68,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>;
@@ -68,7 +85,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;
@@ -582,7 +599,8 @@ interface ConsumerSink<Tx = unknown> {
 type WithSinkTx<TTx> = [TTx] extends [never] ? unknown : {
 	tx: TTx;
 };
-import { StreamsEvent, StreamsEventType } from "@secondlayer/shared/streams-rows";
+import { VmEventType } from "@secondlayer/shared";
+import { StreamsEvent, StreamsEventType, StreamsWireEvent, VmStreamsEvent } from "@secondlayer/shared/streams-rows";
 type StreamsTip = {
 	block_height: number;
 	block_hash: string;
@@ -678,9 +696,11 @@ type StreamsEventsListParams = {
 	cursor?: string | null;
 	fromHeight?: number;
 	toHeight?: number;
-	types?: readonly StreamsEventType[];
+	/** `vm` reads ordinal. Omit for Streams 1.0. */
+	clock?: "classic" | "vm";
+	types?: readonly (StreamsEventType | VmEventType)[];
 	/** Event types to exclude (applied after `types`). */
-	notTypes?: readonly StreamsEventType[];
+	notTypes?: readonly (StreamsEventType | VmEventType)[];
 	contractId?: StreamsFilterValue;
 	sender?: StreamsFilterValue;
 	recipient?: StreamsFilterValue;
@@ -1071,11 +1091,26 @@ type StreamsClient = {
 	}): AsyncIterableIterator<StreamsBatch<StreamsEventOfTypes<T>>>;
 	consume(params?: StreamsConsumeParams): AsyncIterableIterator<StreamsBatch>;
 	events: {
-		/** Narrowing overload, matching `consume`. */
-		list<const T extends readonly StreamsEventType[]>(params: StreamsEventsListParams & {
+		/** `clock: "vm"` pages carry vm rows only (a parallel vocabulary,
+		*  `event_index` = `ordinal`). Never `StreamsEvent`. */
+		list(params: StreamsEventsListParams & {
+			clock: "vm";
+		}): Promise<StreamsEventsEnvelope<VmStreamsEvent>>;
+		/** Narrowing overload, matching `consume`. Classic clock only —
+		*  `clock: "vm"` is overload 1, and a general `StreamsEventsListParams`
+		*  variable (clock unresolved) is the wire-union fallback. */
+		list<const T extends readonly StreamsEventType[]>(params: Omit<StreamsEventsListParams, "clock" | "types" | "notTypes"> & {
 			types: T;
+			notTypes?: readonly StreamsEventType[];
+			clock?: "classic";
 		}): Promise<StreamsEventsEnvelope<StreamsEventOfTypes<T>>>;
-		list(params?: StreamsEventsListParams): Promise<StreamsEventsEnvelope>;
+		list(params?: Omit<StreamsEventsListParams, "clock" | "types" | "notTypes"> & {
+			types?: readonly StreamsEventType[];
+			notTypes?: readonly StreamsEventType[];
+			clock?: "classic";
+		}): Promise<StreamsEventsEnvelope>;
+		/** Unresolved `clock` on a general params variable: the wire union. */
+		list(params: StreamsEventsListParams): Promise<StreamsEventsEnvelope<StreamsWireEvent>>;
 		byTxId(txId: string): Promise<StreamsEventsListEnvelope>;
 		/**
 		* Pull pages from Streams and call `onBatch` after each page.
@@ -1450,8 +1485,38 @@ type IndexPrint = IndexEventBase & {
 		raw_value: string | null;
 	};
 };
+type IndexNestedContractCall = IndexEventBase & {
+	event_type: "nested_contract_call";
+	sender: string | null;
+	caller: string;
+	function_name: string;
+	function_args: unknown;
+	raw_result: string | null;
+};
+type IndexVarSet = IndexEventBase & {
+	event_type: "var_set";
+	var_name: string;
+	raw_value: string;
+};
+type IndexMapSet = IndexEventBase & {
+	event_type: "map_set";
+	map: string;
+	raw_key: string;
+	raw_value: string;
+};
+type IndexMapInsert = IndexEventBase & {
+	event_type: "map_insert";
+	map: string;
+	raw_key: string;
+	raw_value: string;
+};
+type IndexMapDelete = IndexEventBase & {
+	event_type: "map_delete";
+	map: string;
+	raw_key: string;
+};
 /** Decoded chain event, discriminated by `event_type`. */
-type IndexEvent = IndexFtTransfer | IndexNftTransfer | IndexStxTransfer | IndexStxMint | IndexStxBurn | IndexStxLock | IndexFtMint | IndexFtBurn | IndexNftMint | IndexNftBurn | IndexPrint;
+type IndexEvent = IndexFtTransfer | IndexNftTransfer | IndexStxTransfer | IndexStxMint | IndexStxBurn | IndexStxLock | IndexFtMint | IndexFtBurn | IndexNftMint | IndexNftBurn | IndexPrint | IndexNestedContractCall | IndexVarSet | IndexMapSet | IndexMapInsert | IndexMapDelete;
 type IndexEventType = IndexEvent["event_type"];
 /** Fields every read returns regardless of `fields` — the consume contract
 *  (`cursor`, `block_height`) plus the union discriminant. */
@@ -1476,8 +1541,7 @@ type IndexEventOf<T extends IndexEventType> = Extract<IndexEvent, {
 	event_type: T;
 }>;
 type EventsListParams<T extends IndexEventType = IndexEventType> = {
-	/** Required. One of the decoded event types. Passing a literal narrows the
-	*  rows every surface hands back to that event's own shape. */
+	/** Decoded types or VM types (`nested_contract_call`, `map_set`, …). */
 	eventType: T;
 	cursor?: string | null;
 	fromCursor?: string | null;
@@ -1488,6 +1552,12 @@ type EventsListParams<T extends IndexEventType = IndexEventType> = {
 	assetIdentifier?: string;
 	sender?: string;
 	recipient?: string;
+	functionName?: string;
+	caller?: string;
+	map?: string;
+	varName?: string;
+	/** Restrict to one transaction. */
+	txId?: string;
 	fromHeight?: number;
 	toHeight?: number;
 	/** Restrict to contracts conforming to a trait/standard (e.g. "sip-010").

package/dist/subgraphs/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);
@@ -1806,6 +1851,11 @@ class Index extends BaseClient {
       asset_identifier: params.assetIdentifier,
       sender: params.sender,
       recipient: params.recipient,
+      function_name: params.functionName,
+      caller: params.caller,
+      map: params.map,
+      var_name: params.varName,
+      tx_id: params.txId,
       trait: params.trait,
       tx_context: params.txContext ? "true" : undefined
     })}`, undefined, { signal: params.signal });
@@ -2318,6 +2368,7 @@ function createStreamsClient(options) {
       asset_identifier: params.assetIdentifier,
       types: params.types,
       not_types: params.notTypes,
+      clock: params.clock === "vm" ? "vm" : undefined,
       filters: encodeFilters(params.filters)
     })}`);
   }
@@ -2637,5 +2688,5 @@ export {
   Subgraphs
 };
 
-//# debugId=EC50B5FEA0569DC264756E2164756E21
+//# debugId=455A5D582FCD1C3A64756E2164756E21
 //# sourceMappingURL=index.js.map