@fonderie/client 0.2.0 → 0.4.0

package/brain/signatures.md

@@ -5,11 +5,41 @@
 ## @fonderie/client
 
 ```ts
+interface IClientAuthConfig {
+    getRefreshToken?: () => string | undefined;
+    onTokensChanged?: (tokens: ITokens) => void;
+    onAuthError?: () => void;
+}
+
 interface IFonderieClientOptions {
     baseUrl: string;
     accessToken?: string;
+    workspaceId?: string;
+    cache?: ICache;
+    auth?: IClientAuthConfig;
+}
+
+interface IRequestConfig {
+    workspaceId?: string;
+    cache?: number | false;
+    bust?: boolean;
+    invalidate?: string[];
+}
+
+interface ICache {
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T, ttlMs: number): void;
+    dedupe<T>(key: string, fn: () => Promise<T>): Promise<T>;
+    invalidate(fragment: string): void;
+    clear(): void;
 }
 
+interface IMemoryCacheOptions {
+    defaultTtlMs?: number;
+}
+
+function createMemoryCache(opts?: IMemoryCacheOptions): ICache & { defaultTtlMs: number; }
+
 new FonderieClient(opts: IFonderieClientOptions): FonderieClient
   .auth: AuthClient
   .billing: BillingClient
@@ -17,6 +47,15 @@ new FonderieClient(opts: IFonderieClientOptions): FonderieClient
   .audit: AuditClient
   .webhooks: WebhooksClient
   .customers: CustomersClient
+  .setAccessToken(token: string | undefined): void
+  .clearCache(): void
+  .setWorkspaceId(workspaceId: string | undefined): void
+  .request<T = unknown>(opts: { method: string; path: string; body?: unknown; workspaceId?: string | undefined; cache?: number | false | undefined; bust?: boolean | undefined; invalidate?: string[] | undefined; }): Promise<IApiResponse<...>>
+  .get<T = unknown>(path: string, config?: IRequestConfig | undefined): Promise<IApiResponse<T>>
+  .post<T = unknown>(path: string, body?: unknown, config?: IRequestConfig | undefined): Promise<IApiResponse<T>>
+  .put<T = unknown>(path: string, body?: unknown, config?: IRequestConfig | undefined): Promise<IApiResponse<T>>
+  .patch<T = unknown>(path: string, body?: unknown, config?: IRequestConfig | undefined): Promise<IApiResponse<T>>
+  .delete<T = unknown>(path: string, config?: IRequestConfig | undefined): Promise<IApiResponse<T>>
 
 new FonderieApiError(reason: string, explanation: string, status: number, details?: unknown): FonderieApiError
   .reason: string

package/dist/index.cjs

@@ -29,10 +29,48 @@ __export(index_exports, {
   FonderieApiError: () => FonderieApiError,
   FonderieClient: () => FonderieClient,
   WebhooksClient: () => WebhooksClient,
-  WorkspacesClient: () => WorkspacesClient
+  WorkspacesClient: () => WorkspacesClient,
+  createMemoryCache: () => createMemoryCache
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/cache.ts
+function createMemoryCache(opts = {}) {
+  const store = /* @__PURE__ */ new Map();
+  const inflight = /* @__PURE__ */ new Map();
+  const defaultTtlMs = opts.defaultTtlMs ?? 6e4;
+  return {
+    defaultTtlMs,
+    get(key) {
+      const entry = store.get(key);
+      if (!entry) return void 0;
+      if (Date.now() > entry.expiresAt) {
+        store.delete(key);
+        return void 0;
+      }
+      return entry.value;
+    },
+    set(key, value, ttlMs) {
+      store.set(key, { value, expiresAt: Date.now() + ttlMs });
+    },
+    dedupe(key, fn) {
+      const existing = inflight.get(key);
+      if (existing) return existing;
+      const req = fn().finally(() => inflight.delete(key));
+      inflight.set(key, req);
+      return req;
+    },
+    invalidate(fragment) {
+      for (const key of store.keys()) if (key.includes(fragment)) store.delete(key);
+      for (const key of inflight.keys()) if (key.includes(fragment)) inflight.delete(key);
+    },
+    clear() {
+      store.clear();
+      inflight.clear();
+    }
+  };
+}
+
 // src/http.ts
 var FonderieApiError = class extends Error {
   constructor(reason, explanation, status, details) {
@@ -49,24 +87,52 @@ var FonderieApiError = class extends Error {
   details;
 };
 var HttpClient = class {
-  constructor(baseUrl) {
+  constructor(baseUrl, deps = {}) {
     this.baseUrl = baseUrl;
+    this.cache = deps.cache;
+    this.defaultTtlMs = deps.defaultTtlMs ?? 6e4;
+    this.refresh = deps.refresh;
   }
   baseUrl;
+  cache;
+  defaultTtlMs;
+  refresh;
   async request(opts) {
-    const headers = {
-      "Content-Type": "application/json"
-    };
+    const method = opts.method.toUpperCase();
+    const cache = this.cache;
+    if (cache && method === "GET" && opts.cache !== false) {
+      const key = `GET ${opts.path}::ws=${opts.workspaceId ?? ""}`;
+      if (!opts.bust) {
+        const hit = cache.get(key);
+        if (hit !== void 0) return hit;
+      }
+      const ttl = typeof opts.cache === "number" ? opts.cache : this.defaultTtlMs;
+      return cache.dedupe(key, async () => {
+        const data2 = await this.exec(opts);
+        cache.set(key, data2, ttl);
+        return data2;
+      });
+    }
+    const data = await this.exec(opts);
+    if (cache && method !== "GET") {
+      const resource = opts.path.split("?")[0]?.split("/").filter(Boolean)[0];
+      if (resource) cache.invalidate(`/${resource}`);
+      for (const fragment of opts.invalidate ?? []) cache.invalidate(fragment);
+    }
+    return data;
+  }
+  async exec(opts, retried = false) {
+    const headers = { "Content-Type": "application/json" };
     if (opts.token) headers["Authorization"] = `Bearer ${opts.token}`;
     if (opts.cookie) headers["Cookie"] = opts.cookie;
     if (opts.workspaceId) headers["X-Workspace-ID"] = opts.workspaceId;
-    const fetchInit = {
-      method: opts.method,
-      headers,
-      credentials: "include"
-    };
+    const fetchInit = { method: opts.method, headers, credentials: "include" };
     if (opts.body !== void 0) fetchInit.body = JSON.stringify(opts.body);
     const res = await fetch(`${this.baseUrl}${opts.path}`, fetchInit);
+    if (res.status === 401 && this.refresh && !retried && !opts.path.startsWith("/auth/")) {
+      const newToken = await this.refresh();
+      if (newToken) return this.exec({ ...opts, token: newToken }, true);
+    }
     if (res.status === 204) {
       if (!res.ok) throw new FonderieApiError("unknown", res.statusText, res.status);
       return void 0;
@@ -1062,15 +1128,110 @@ var FonderieClient = class {
   webhooks;
   customers;
   http;
+  tokens;
+  workspaceId;
+  cache;
+  authConfig;
+  refreshing = null;
   constructor(opts) {
-    this.http = new HttpClient(opts.baseUrl);
-    const tokens = new TokenStore(opts.accessToken);
-    this.auth = new AuthClient(this.http, tokens);
-    this.billing = new BillingClient(this.http, tokens);
-    this.workspaces = new WorkspacesClient(this.http, tokens);
-    this.audit = new AuditClient(this.http, tokens);
-    this.webhooks = new WebhooksClient(this.http, tokens);
-    this.customers = new CustomersClient(this.http, tokens);
+    this.tokens = new TokenStore(opts.accessToken);
+    this.workspaceId = opts.workspaceId;
+    this.cache = opts.cache;
+    this.authConfig = opts.auth;
+    this.http = new HttpClient(opts.baseUrl, {
+      cache: opts.cache,
+      defaultTtlMs: opts.cache?.defaultTtlMs,
+      refresh: opts.auth ? () => this.doRefresh() : void 0
+    });
+    this.auth = new AuthClient(this.http, this.tokens);
+    this.billing = new BillingClient(this.http, this.tokens);
+    this.workspaces = new WorkspacesClient(this.http, this.tokens);
+    this.audit = new AuditClient(this.http, this.tokens);
+    this.webhooks = new WebhooksClient(this.http, this.tokens);
+    this.customers = new CustomersClient(this.http, this.tokens);
+  }
+  // Single-flight refresh: POST /auth/refresh with the app-supplied refresh
+  // token, store the new access token, notify the app, return it for the retry.
+  doRefresh() {
+    if (this.refreshing) return this.refreshing;
+    this.refreshing = (async () => {
+      const refreshToken = this.authConfig?.getRefreshToken?.();
+      if (!refreshToken) {
+        this.authConfig?.onAuthError?.();
+        return void 0;
+      }
+      try {
+        const { result } = await this.auth.refreshTokens(refreshToken);
+        const tokens = result.tokens;
+        this.tokens.set(tokens.access);
+        this.authConfig?.onTokensChanged?.(tokens);
+        return tokens.access;
+      } catch {
+        this.tokens.set(void 0);
+        this.authConfig?.onAuthError?.();
+        return void 0;
+      } finally {
+        this.refreshing = null;
+      }
+    })();
+    return this.refreshing;
+  }
+  // The JWT used to authenticate every request — the typed modules and the
+  // generic transport share one token store. Passing undefined signs out and
+  // clears the cache (so no session's data survives a logout).
+  setAccessToken(token) {
+    this.tokens.set(token);
+    if (!token) this.clearCache();
+  }
+  // Drop all cached responses (e.g. on switching accounts).
+  clearCache() {
+    this.cache?.clear();
+  }
+  // Default X-Workspace-ID for the generic transport, also propagated to the
+  // workspace-scoped modules so one call configures the whole client.
+  setWorkspaceId(workspaceId) {
+    this.workspaceId = workspaceId;
+    this.billing.setWorkspaceId(workspaceId);
+    this.workspaces.setWorkspaceId(workspaceId);
+    this.customers.setWorkspaceId(workspaceId);
+  }
+  // ── Generic transport ──────────────────────────────────────────────────────
+  // A Fonderie-aware HTTP client for endpoints outside the typed modules (an
+  // app's own routes on the same backend). It attaches the shared JWT and
+  // X-Workspace-ID automatically and returns Fonderie's { reason, explanation,
+  // result } envelope — so you don't hand-roll auth for custom endpoints.
+  request(opts) {
+    return this.http.request({
+      method: opts.method,
+      path: opts.path,
+      body: opts.body,
+      token: this.tokens.get(),
+      workspaceId: opts.workspaceId ?? this.workspaceId,
+      cache: opts.cache,
+      bust: opts.bust,
+      invalidate: opts.invalidate
+    });
+  }
+  get(path, config) {
+    return this.request({
+      method: "GET",
+      path,
+      workspaceId: config?.workspaceId,
+      cache: config?.cache,
+      bust: config?.bust
+    });
+  }
+  post(path, body, config) {
+    return this.request({ method: "POST", path, body, workspaceId: config?.workspaceId, invalidate: config?.invalidate });
+  }
+  put(path, body, config) {
+    return this.request({ method: "PUT", path, body, workspaceId: config?.workspaceId, invalidate: config?.invalidate });
+  }
+  patch(path, body, config) {
+    return this.request({ method: "PATCH", path, body, workspaceId: config?.workspaceId, invalidate: config?.invalidate });
+  }
+  delete(path, config) {
+    return this.request({ method: "DELETE", path, workspaceId: config?.workspaceId, invalidate: config?.invalidate });
   }
 };
 
@@ -1254,6 +1415,7 @@ var CourierAdminClient = class {
   FonderieApiError,
   FonderieClient,
   WebhooksClient,
-  WorkspacesClient
+  WorkspacesClient,
+  createMemoryCache
 });
 //# sourceMappingURL=index.cjs.map