@secondlayer/sdk 10.4.3 → 10.6.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;
@@ -108,7 +125,6 @@ interface SubgraphRowsEnvelope<T = unknown> {
 interface BundleSubgraphResponse {
 	ok: true;
 	name: string;
-	version: string | null;
 	description: string | null;
 	sources: Record<string, Record<string, unknown>>;
 	schema: Record<string, unknown>;
@@ -2651,4 +2667,4 @@ declare function getSubgraph<T extends {
 	schema: Record<string, unknown>;
 }>(def: T, options?: Partial<SecondLayerOptions> | SecondLayer | Subgraphs): InferSubgraphClient2<T>;
 import { SubgraphAgentSchema as SubgraphAgentSchema2, SubgraphSpecFormat, SubgraphSpecOptions as SubgraphSpecOptions2 } from "@secondlayer/shared/subgraphs/spec";
-export { getSubgraph, Subgraphs, SubgraphSpecOptions2 as SubgraphSpecOptions, SubgraphSpecFormat, SubgraphAgentSchema2 as SubgraphAgentSchema, SecondLayerOptions };
+export { SecondLayerOptions, SubgraphAgentSchema2 as SubgraphAgentSchema, SubgraphSpecFormat, SubgraphSpecOptions2 as SubgraphSpecOptions, Subgraphs, getSubgraph };

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);
@@ -1280,7 +1325,7 @@ async function defaultSleep(ms, signal) {
   });
 }
 async function consumeStreamsEvents(opts) {
-  const sleep3 = opts.sleep ?? defaultSleep;
+  const sleep = opts.sleep ?? defaultSleep;
   const mode = opts.mode ?? "tail";
   const finalizedOnly = opts.finalizedOnly ?? false;
   const emptyBackoffMs = opts.emptyBackoffMs ?? 500;
@@ -1310,7 +1355,7 @@ async function consumeStreamsEvents(opts) {
       retryCount: opts.retryCount,
       retryDelay: opts.retryDelay,
       onError: opts.onError,
-      sleep: sleep3,
+      sleep,
       signal: opts.signal
     });
     pages++;
@@ -1342,7 +1387,7 @@ async function consumeStreamsEvents(opts) {
           retryCount: opts.retryCount,
           retryDelay: opts.retryDelay,
           onError: opts.onError,
-          sleep: sleep3,
+          sleep,
           signal: opts.signal
         });
         if (listed.next_since !== null)
@@ -1405,7 +1450,7 @@ async function consumeStreamsEvents(opts) {
       if (mode === "bounded") {
         return { cursor, pages, emptyPolls };
       }
-      await sleep3(emptyBackoffMs, opts.signal);
+      await sleep(emptyBackoffMs, opts.signal);
       continue;
     }
     return { cursor, pages, emptyPolls };
@@ -1413,7 +1458,7 @@ async function consumeStreamsEvents(opts) {
   return { cursor, pages, emptyPolls };
 }
 async function* iterateStreamsBatches(opts) {
-  const sleep3 = opts.sleep ?? defaultSleep;
+  const sleep = opts.sleep ?? defaultSleep;
   let cursor = opts.fromCursor ?? null;
   while (!opts.signal?.aborted) {
     const envelope = await opts.fetchEvents({
@@ -1441,12 +1486,12 @@ async function* iterateStreamsBatches(opts) {
     if (!advanced && envelope.events.length === 0) {
       if (opts.signal?.aborted)
         return;
-      await sleep3(opts.intervalMs, opts.signal);
+      await sleep(opts.intervalMs, opts.signal);
     }
   }
 }
 async function* streamStreamsEvents(opts) {
-  const sleep3 = opts.sleep ?? defaultSleep;
+  const sleep = opts.sleep ?? defaultSleep;
   const emptyBackoffMs = opts.emptyBackoffMs ?? 500;
   const maxPages = opts.maxPages ?? Number.POSITIVE_INFINITY;
   const maxEmptyPolls = opts.maxEmptyPolls ?? Number.POSITIVE_INFINITY;
@@ -1481,7 +1526,7 @@ async function* streamStreamsEvents(opts) {
       emptyPolls++;
       if (emptyPolls >= maxEmptyPolls || pages >= maxPages)
         return;
-      await sleep3(emptyBackoffMs, opts.signal);
+      await sleep(emptyBackoffMs, opts.signal);
       continue;
     }
     return;
@@ -1490,7 +1535,7 @@ async function* streamStreamsEvents(opts) {
 
 // src/index-api/consumer.ts
 async function consumeIndexFeed(opts) {
-  const sleep3 = opts.sleep ?? defaultSleep;
+  const sleep = opts.sleep ?? defaultSleep;
   const mode = opts.mode ?? "tail";
   const finalizedOnly = opts.finalizedOnly ?? false;
   const batchSize = opts.batchSize ?? 200;
@@ -1514,7 +1559,7 @@ async function consumeIndexFeed(opts) {
       retryCount: opts.retryCount,
       retryDelay: opts.retryDelay,
       onError: opts.onError,
-      sleep: sleep3,
+      sleep,
       signal: opts.signal
     });
     pages++;
@@ -1577,7 +1622,7 @@ async function consumeIndexFeed(opts) {
       if (mode === "bounded") {
         return { cursor, pages, emptyPolls };
       }
-      await sleep3(emptyBackoffMs, opts.signal);
+      await sleep(emptyBackoffMs, opts.signal);
       continue;
     }
     return { cursor, pages, emptyPolls };
@@ -2639,9 +2684,9 @@ function getSubgraph(def, options = {}) {
   return new Subgraphs(options).typed(def);
 }
 export {
-  getSubgraph,
-  Subgraphs
+  Subgraphs,
+  getSubgraph
 };
 
-//# debugId=B66CAEBD81B3C1B764756E2164756E21
+//# debugId=8E4B27D4BE8A894F64756E2164756E21
 //# sourceMappingURL=index.js.map