@secondlayer/sdk 10.4.3 → 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;

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);
@@ -2643,5 +2688,5 @@ export {
   Subgraphs
 };
 
-//# debugId=B66CAEBD81B3C1B764756E2164756E21
+//# debugId=455A5D582FCD1C3A64756E2164756E21
 //# sourceMappingURL=index.js.map