@faable/sdk-base 1.1.3 → 1.3.0

package/dist/FaableApi.d.ts

@@ -1,12 +1,27 @@
-import { AuthInterface } from "./types/AuthInterface.js";
-import { Fetcher, FetcherCreateParams } from "./fetcher/Fetcher.js";
-import { Paginator, PaginatorOptions } from "./helpers/paginator.js";
+import type { AuthInterface } from "./types/AuthInterface.js";
+import type { Fetcher, FetcherCreateParams } from "./fetcher/Fetcher.js";
+import type { Paginator, PaginatorOptions } from "./helpers/paginator.js";
 export type ApiParams = {
     baseURL?: string;
     fetcher?: FetcherCreateParams;
     auth?: AuthInterface<any, any>;
     debug?: boolean;
     paginator?: Partial<PaginatorOptions>;
+    /**
+     * Opt-in in-memory ETag cache for GET requests. When enabled, the fetcher
+     * remembers each GET's `ETag` and replays it as `If-None-Match`; a `304 Not
+     * Modified` reuses the previously parsed body instead of re-downloading it.
+     * Correctness relies on the server changing the ETag whenever the resource
+     * changes (no client-side invalidation needed — a write bumps the server
+     * ETag, so the next GET gets a fresh `200`). Off by default.
+     *
+     * `true` uses the default cap; pass `{ maxEntries }` to size the bounded LRU
+     * for the client's key cardinality (e.g. a controller polling many apps +
+     * deployments wants a larger cap than a one-shot script).
+     */
+    etagCache?: boolean | {
+        maxEntries?: number;
+    };
 };
 export declare abstract class FaableApi<Params extends ApiParams = ApiParams> {
     fetcher: Fetcher;

package/dist/FaableApi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FaableApi.d.ts","sourceRoot":"","sources":["../src/FaableApi.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEpE,OAAO,EAEL,SAAS,EACT,gBAAgB,EACjB,MAAM,wBAAwB,CAAC;AAEhC,MAAM,MAAM,SAAS,GAAG;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B,IAAI,CAAC,EAAE,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC/B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACvC,CAAC;AAEF,8BAAsB,SAAS,CAAC,MAAM,SAAS,SAAS,GAAG,SAAS;IAClE,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,SAAS,EAAE,SAAS,CAAC;IAC/B,SAAS,aAAa,MAAM,CAAC,EAAE,MAAM;IAMrC,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,QAAQ,MAAM,IAAI,EAAE,MAAM,KAAK,GAAG,EAAE,MAAM,GAAG,GAAG,EACtE,IAAI,EAAE,CAAC,EACP,MAAM,CAAC,EAAE,MAAM,GACd,YAAY,CAAC,CAAC,CAAC;CAInB"}
+{"version":3,"file":"FaableApi.d.ts","sourceRoot":"","sources":["../src/FaableApi.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAGzE,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1E,MAAM,MAAM,SAAS,GAAG;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B,IAAI,CAAC,EAAE,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC/B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACtC;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/C,CAAC;AAEF,8BAAsB,SAAS,CAAC,MAAM,SAAS,SAAS,GAAG,SAAS;IAClE,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,SAAS,EAAE,SAAS,CAAC;IAC/B,SAAS,aAAa,MAAM,CAAC,EAAE,MAAM;IAMrC,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,QAAQ,MAAM,IAAI,EAAE,MAAM,KAAK,GAAG,EAAE,MAAM,GAAG,GAAG,EACtE,IAAI,EAAE,CAAC,EACP,MAAM,CAAC,EAAE,MAAM,GACd,YAAY,CAAC,CAAC,CAAC;CAInB"}

package/dist/FaableApi.js

@@ -1,5 +1,5 @@
 import { fetcher_axios } from "./fetcher/fetcher_axios.js";
-import { buildPaginator, } from "./helpers/paginator.js";
+import { buildPaginator } from "./helpers/paginator.js";
 export class FaableApi {
     fetcher;
     paginator;

package/dist/auth/apikey.d.ts

@@ -1,4 +1,4 @@
-import { StrategyInterface } from "../types/StrategyInterface.js";
+import type { StrategyInterface } from "../types/StrategyInterface.js";
 export type ApikeyAuthParams = Partial<[apikey: string]>;
 export declare const createApikeyAuth: StrategyInterface<ApikeyAuthParams>;
 //# sourceMappingURL=apikey.d.ts.map

package/dist/auth/apikey.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apikey.d.ts","sourceRoot":"","sources":["../../src/auth/apikey.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAGlE,MAAM,MAAM,gBAAgB,GAAG,OAAO,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAEzD,eAAO,MAAM,gBAAgB,EAAE,iBAAiB,CAAC,gBAAgB,CAoBhE,CAAC"}
+{"version":3,"file":"apikey.d.ts","sourceRoot":"","sources":["../../src/auth/apikey.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAGvE,MAAM,MAAM,gBAAgB,GAAG,OAAO,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAEzD,eAAO,MAAM,gBAAgB,EAAE,iBAAiB,CAAC,gBAAgB,CAoBhE,CAAC"}

package/dist/auth/client_credentials/client_credentials.d.ts

@@ -1,4 +1,4 @@
-import { StrategyInterface } from "../../types/StrategyInterface.js";
+import type { StrategyInterface } from "../../types/StrategyInterface.js";
 type Params = {
     client_id: string;
     client_secret: string;

package/dist/auth/client_credentials/client_credentials.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client_credentials.d.ts","sourceRoot":"","sources":["../../../src/auth/client_credentials/client_credentials.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAKrE,KAAK,MAAM,GAAG;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG,OAAO,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AAWrE,eAAO,MAAM,uBAAuB,EAAE,iBAAiB,CACrD,2BAA2B,CAgG5B,CAAC"}
+{"version":3,"file":"client_credentials.d.ts","sourceRoot":"","sources":["../../../src/auth/client_credentials/client_credentials.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAK1E,KAAK,MAAM,GAAG;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG,OAAO,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AAWrE,eAAO,MAAM,uBAAuB,EAAE,iBAAiB,CACrD,2BAA2B,CAgG5B,CAAC"}

package/dist/auth/client_credentials/store.d.ts

@@ -1,4 +1,4 @@
-import { ClientCredentialsResponse } from "./types.js";
+import type { ClientCredentialsResponse } from "./types.js";
 type TokenStoreOptions = {
     debug?: boolean;
 };

package/dist/auth/client_credentials/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/auth/client_credentials/store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAEvD,KAAK,iBAAiB,GAAG;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,eAAO,MAAM,gBAAgB,eAAe,iBAAiB;kCAStB,yBAAyB;kBAPlD,yBAAyB;aAC9B,MAAM;;;kBADD,yBAAyB;aAC9B,MAAM;;CAkBd,CAAC"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/auth/client_credentials/store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAE5D,KAAK,iBAAiB,GAAG;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,eAAO,MAAM,gBAAgB,eAAe,iBAAiB;kCAStB,yBAAyB;kBAPlD,yBAAyB;aAC9B,MAAM;;;kBADD,yBAAyB;aAC9B,MAAM;;CAkBd,CAAC"}

package/dist/fetcher/fetcher_axios.d.ts

@@ -1,4 +1,4 @@
-import { Fetcher } from "./Fetcher.js";
-import { ApiParams } from "../FaableApi.js";
+import type { Fetcher } from "./Fetcher.js";
+import type { ApiParams } from "../FaableApi.js";
 export declare const fetcher_axios: (params?: ApiParams) => Fetcher;
 //# sourceMappingURL=fetcher_axios.d.ts.map

package/dist/fetcher/fetcher_axios.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fetcher_axios.d.ts","sourceRoot":"","sources":["../../src/fetcher/fetcher_axios.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,OAAO,EAAiB,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAiB5C,eAAO,MAAM,aAAa,YAAY,SAAS,KAAQ,OAwEtD,CAAC"}
+{"version":3,"file":"fetcher_axios.d.ts","sourceRoot":"","sources":["../../src/fetcher/fetcher_axios.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAiB,MAAM,cAAc,CAAC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAiBjD,eAAO,MAAM,aAAa,YAAY,SAAS,KAAQ,OAkItD,CAAC"}

package/dist/fetcher/fetcher_axios.js

@@ -1,4 +1,4 @@
-import axios from "axios";
+import axios, { AxiosError } from "axios";
 import { FaableApiError } from "../helpers/FaableApiError.js";
 const handleErrorInterceptor = async (e) => {
     if (!e.isAxiosError) {
@@ -32,13 +32,63 @@ export const fetcher_axios = (params = {}) => {
         }
         return res;
     }, handleErrorInterceptor);
+    // Opt-in in-memory ETag cache (per fetcher instance). Keyed by url + params
+    // so each list cursor / expanded GET caches independently. Server-driven
+    // invalidation only — a changed resource changes its ETag, so the
+    // conditional request returns a fresh 200 instead of 304.
+    //
+    // Bounded LRU: a long-lived client keeps minting distinct keys (e.g. a new
+    // `GET /deployment/:id` per deploy), so an unbounded map would leak. The Map
+    // preserves insertion order; every access re-inserts its key (moving it to
+    // the most-recent end) and inserts past the cap evict the least-recently-used
+    // (oldest) entry.
+    const etagOpt = params.etagCache;
+    const etagEnabled = etagOpt === true || (typeof etagOpt === "object" && etagOpt !== null);
+    const ETAG_CACHE_MAX = (typeof etagOpt === "object" && etagOpt?.maxEntries) || 1000;
+    const etagCache = new Map();
+    const etagKey = (url, p) => `${url}::${p ? JSON.stringify(p) : ""}`;
+    const etagTouch = (key, entry) => {
+        etagCache.delete(key);
+        etagCache.set(key, entry);
+        if (etagCache.size > ETAG_CACHE_MAX) {
+            etagCache.delete(etagCache.keys().next().value);
+        }
+    };
+    // Conditional GET against the cache. Replays the stored ETag as
+    // `If-None-Match`; a `304` serves the cached parsed body, a `200` refreshes
+    // it. Shared by `get` and the GET path of `request` so paginated lists
+    // (the paginator calls `request`) cache page-by-page too — each page is a
+    // distinct (url + params incl. cursor) key, and the API folds a per-resource
+    // generation counter into every page's ETag, so any write invalidates all
+    // pages (server-driven, never stale).
+    const etagGet = async (cfg) => {
+        const key = etagKey(cfg.url ?? "", cfg.params);
+        const cached = etagCache.get(key);
+        const res = await instance.request({
+            ...cfg,
+            headers: {
+                ...cfg.headers,
+                ...(cached ? { "If-None-Match": cached.etag } : {}),
+            },
+            // Accept 304 so axios resolves (instead of routing it through the
+            // error interceptor) and we can serve the cached body.
+            validateStatus: (s) => (s >= 200 && s < 300) || s === 304,
+        });
+        if (res.status === 304 && cached) {
+            etagTouch(key, cached); // mark as recently used
+            return cached.data;
+        }
+        const etag = res.headers?.etag;
+        if (etag) {
+            etagTouch(key, { etag, data: res.data });
+        }
+        return res.data;
+    };
     return {
         get: async (url, config) => {
-            const res = await instance.request({
-                method: "GET",
-                url,
-                ...config,
-            });
+            if (etagEnabled)
+                return etagGet({ method: "GET", url, ...config });
+            const res = await instance.request({ method: "GET", url, ...config });
             return res.data;
         },
         delete: async (url, config) => {
@@ -62,6 +112,12 @@ export const fetcher_axios = (params = {}) => {
             return res.data;
         },
         request: async (params) => {
+            // The paginator issues its page requests through `request` (method
+            // omitted → axios defaults to GET), so route GETs through the ETag cache
+            // too — otherwise lists would never be cached.
+            const method = (params.method ?? "GET").toString().toUpperCase();
+            if (etagEnabled && method === "GET")
+                return etagGet(params);
             const res = await instance.request(params);
             return res.data;
         },

package/dist/helpers/FaableApiError.d.ts

@@ -1,4 +1,4 @@
-import { FetcherResponse } from "../fetcher/Fetcher.js";
+import type { FetcherResponse } from "../fetcher/Fetcher.js";
 type Status = "not-found" | "created" | "ok" | "unauthorized" | "bad-request" | "internal-server-error" | "service-unavailable" | "bad-gateway";
 export declare const build_error_message: (message?: string, response?: FetcherResponse) => string;
 export declare class FaableApiError extends Error {

package/dist/helpers/FaableApiError.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FaableApiError.d.ts","sourceRoot":"","sources":["../../src/helpers/FaableApiError.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,KAAK,MAAM,GACP,WAAW,GACX,SAAS,GACT,IAAI,GACJ,cAAc,GACd,aAAa,GACb,uBAAuB,GACvB,qBAAqB,GACrB,aAAa,CAAC;AAYlB,eAAO,MAAM,mBAAmB,aACpB,MAAM,aACL,eAAe,WAO3B,CAAC;AAEF,qBAAa,cAAe,SAAQ,KAAK;IACvC,gBAAgB,UAAQ;IACxB,QAAQ,CAAC,EAAE,eAAe,CAAC;gBACf,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,eAAe;IAOxD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;CAI/B"}
+{"version":3,"file":"FaableApiError.d.ts","sourceRoot":"","sources":["../../src/helpers/FaableApiError.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,KAAK,MAAM,GACP,WAAW,GACX,SAAS,GACT,IAAI,GACJ,cAAc,GACd,aAAa,GACb,uBAAuB,GACvB,qBAAqB,GACrB,aAAa,CAAC;AAYlB,eAAO,MAAM,mBAAmB,aACpB,MAAM,aACL,eAAe,WAO3B,CAAC;AAEF,qBAAa,cAAe,SAAQ,KAAK;IACvC,gBAAgB,UAAQ;IACxB,QAAQ,CAAC,EAAE,eAAe,CAAC;gBACf,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,eAAe;IAOxD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;CAI/B"}

package/dist/helpers/paginator.d.ts

@@ -1,4 +1,4 @@
-import { Fetcher, FetcherRequestParams } from "../fetcher/Fetcher.js";
+import type { Fetcher, FetcherRequestParams } from "../fetcher/Fetcher.js";
 export interface Page<T> {
     next: string | null;
     results: T[];

package/dist/helpers/paginator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paginator.d.ts","sourceRoot":"","sources":["../../src/helpers/paginator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAGtE,MAAM,WAAW,IAAI,CAAC,CAAC;IACrB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,CAAC,EAAE,CAAC;CACd;AACD,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC;AAE1D,MAAM,MAAM,gBAAgB,GAAG;IAC7B,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,eAAO,MAAM,cAAc,YAChB,OAAO,YACN,OAAO,CAAC,gBAAgB,CAAC,MAO3B,CAAC,OAAO,oBAAoB;;;oBAoCX;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE;CAWhE,CAAC"}
+{"version":3,"file":"paginator.d.ts","sourceRoot":"","sources":["../../src/helpers/paginator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAG3E,MAAM,WAAW,IAAI,CAAC,CAAC;IACrB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,CAAC,EAAE,CAAC;CACd;AACD,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC;AAE1D,MAAM,MAAM,gBAAgB,GAAG;IAC7B,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,eAAO,MAAM,cAAc,YAChB,OAAO,YACN,OAAO,CAAC,gBAAgB,CAAC,MAO3B,CAAC,OAAO,oBAAoB;;;oBAoCX;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE;CAWhE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faable/sdk-base",
-  "version": "1.1.3",
+  "version": "1.3.0",
   "author": "Marc Pomar <marc@faable.com>",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",