@37signals/fizzy 0.1.0

package/dist/auth/cookie-auth.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Cookie-based authentication strategy for the Fizzy SDK.
+ *
+ * CookieAuth sets the Cookie header for session-based authentication,
+ * used by mobile and web clients.
+ */
+import type { AuthStrategy } from "../auth-strategy.js";
+/**
+ * Provider for cookie values — either a static string or an async function.
+ */
+export type CookieProvider = string | (() => Promise<string>);
+/**
+ * Cookie-based authentication strategy.
+ * Sets the Cookie header with the provided session cookie.
+ */
+export declare class CookieAuth implements AuthStrategy {
+    private cookieProvider;
+    constructor(cookieProvider: CookieProvider);
+    authenticate(headers: Headers): Promise<void>;
+}
+/**
+ * Creates a CookieAuth strategy from a CookieProvider.
+ */
+export declare function cookieAuth(cookieProvider: CookieProvider): AuthStrategy;
+//# sourceMappingURL=cookie-auth.d.ts.map

package/dist/auth/cookie-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookie-auth.d.ts","sourceRoot":"","sources":["../../src/auth/cookie-auth.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;AAE9D;;;GAGG;AACH,qBAAa,UAAW,YAAW,YAAY;IAC7C,OAAO,CAAC,cAAc,CAAiB;gBAE3B,cAAc,EAAE,cAAc;IAIpC,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;CAOpD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,cAAc,EAAE,cAAc,GAAG,YAAY,CAEvE"}

package/dist/auth/cookie-auth.js

@@ -0,0 +1,29 @@
+/**
+ * Cookie-based authentication strategy for the Fizzy SDK.
+ *
+ * CookieAuth sets the Cookie header for session-based authentication,
+ * used by mobile and web clients.
+ */
+/**
+ * Cookie-based authentication strategy.
+ * Sets the Cookie header with the provided session cookie.
+ */
+export class CookieAuth {
+    cookieProvider;
+    constructor(cookieProvider) {
+        this.cookieProvider = cookieProvider;
+    }
+    async authenticate(headers) {
+        const cookie = typeof this.cookieProvider === "function"
+            ? await this.cookieProvider()
+            : this.cookieProvider;
+        headers.set("Cookie", cookie);
+    }
+}
+/**
+ * Creates a CookieAuth strategy from a CookieProvider.
+ */
+export function cookieAuth(cookieProvider) {
+    return new CookieAuth(cookieProvider);
+}
+//# sourceMappingURL=cookie-auth.js.map

package/dist/auth/cookie-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookie-auth.js","sourceRoot":"","sources":["../../src/auth/cookie-auth.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH;;;GAGG;AACH,MAAM,OAAO,UAAU;IACb,cAAc,CAAiB;IAEvC,YAAY,cAA8B;QACxC,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC;IACvC,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,OAAgB;QACjC,MAAM,MAAM,GACV,OAAO,IAAI,CAAC,cAAc,KAAK,UAAU;YACvC,CAAC,CAAC,MAAM,IAAI,CAAC,cAAc,EAAE;YAC7B,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC;QAC1B,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAChC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,cAA8B;IACvD,OAAO,IAAI,UAAU,CAAC,cAAc,CAAC,CAAC;AACxC,CAAC"}

package/dist/auth/magic-link.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Magic-link passwordless login flow for the Fizzy SDK.
+ *
+ * Two-step orchestrator:
+ * 1. CreateSession — sends a magic link to the user's email
+ * 2. RedeemMagicLink — exchanges the magic link token for a session
+ */
+import type { AuthStrategy } from "../auth-strategy.js";
+/**
+ * Result of the magic link request step.
+ */
+export interface MagicLinkRequestResult {
+    /** Whether the magic link email was sent successfully */
+    sent: boolean;
+    /** User-facing message (e.g., "Check your email") */
+    message: string;
+}
+/**
+ * Result of the magic link redemption step.
+ */
+export interface MagicLinkRedeemResult {
+    /** The session token to use for subsequent requests */
+    sessionToken: string;
+    /** The authentication strategy configured with the session */
+    auth: AuthStrategy;
+}
+/**
+ * Options for the magic link flow.
+ */
+export interface MagicLinkFlowOptions {
+    /** Base URL of the Fizzy API (defaults to https://fizzy.do) */
+    baseUrl?: string;
+    /** User-Agent header for requests */
+    userAgent?: string;
+}
+/**
+ * Orchestrates the magic-link passwordless login flow.
+ *
+ * @example
+ * ```ts
+ * const flow = new MagicLinkFlow();
+ *
+ * // Step 1: Request the magic link
+ * const { sent } = await flow.requestLink("user@example.com");
+ *
+ * // Step 2: User clicks the link, you capture the token
+ * const { auth } = await flow.redeemToken(token);
+ *
+ * // Step 3: Use the auth strategy with the client
+ * const client = createFizzyClient({ auth });
+ * ```
+ */
+export declare class MagicLinkFlow {
+    private readonly baseUrl;
+    private readonly userAgent;
+    constructor(options?: MagicLinkFlowOptions);
+    /**
+     * Step 1: Request a magic link be sent to the user's email.
+     */
+    requestLink(email: string): Promise<MagicLinkRequestResult>;
+    /**
+     * Step 2: Redeem a magic link token for a session.
+     */
+    redeemToken(token: string): Promise<MagicLinkRedeemResult>;
+}
+//# sourceMappingURL=magic-link.d.ts.map

package/dist/auth/magic-link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"magic-link.d.ts","sourceRoot":"","sources":["../../src/auth/magic-link.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGxD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,yDAAyD;IACzD,IAAI,EAAE,OAAO,CAAC;IACd,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAC;IACrB,8DAA8D;IAC9D,IAAI,EAAE,YAAY,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qCAAqC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,OAAO,CAAC,EAAE,oBAAoB;IAK1C;;OAEG;IACG,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAsBjE;;OAEG;IACG,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAgCjE"}

package/dist/auth/magic-link.js

@@ -0,0 +1,78 @@
+/**
+ * Magic-link passwordless login flow for the Fizzy SDK.
+ *
+ * Two-step orchestrator:
+ * 1. CreateSession — sends a magic link to the user's email
+ * 2. RedeemMagicLink — exchanges the magic link token for a session
+ */
+import { FizzyError } from "../errors.js";
+/**
+ * Orchestrates the magic-link passwordless login flow.
+ *
+ * @example
+ * ```ts
+ * const flow = new MagicLinkFlow();
+ *
+ * // Step 1: Request the magic link
+ * const { sent } = await flow.requestLink("user@example.com");
+ *
+ * // Step 2: User clicks the link, you capture the token
+ * const { auth } = await flow.redeemToken(token);
+ *
+ * // Step 3: Use the auth strategy with the client
+ * const client = createFizzyClient({ auth });
+ * ```
+ */
+export class MagicLinkFlow {
+    baseUrl;
+    userAgent;
+    constructor(options) {
+        this.baseUrl = options?.baseUrl ?? "https://fizzy.do";
+        this.userAgent = options?.userAgent ?? "fizzy-sdk-ts/0.1.0";
+    }
+    /**
+     * Step 1: Request a magic link be sent to the user's email.
+     */
+    async requestLink(email) {
+        const response = await fetch(`${this.baseUrl}/sessions`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "User-Agent": this.userAgent,
+                Accept: "application/json",
+            },
+            body: JSON.stringify({ email }),
+        });
+        if (!response.ok) {
+            throw new FizzyError("api_error", `Magic link request failed: ${response.status} ${response.statusText}`, { httpStatus: response.status });
+        }
+        return { sent: true, message: "Check your email for the magic link" };
+    }
+    /**
+     * Step 2: Redeem a magic link token for a session.
+     */
+    async redeemToken(token) {
+        const response = await fetch(`${this.baseUrl}/sessions/redeem`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "User-Agent": this.userAgent,
+                Accept: "application/json",
+            },
+            body: JSON.stringify({ token }),
+        });
+        if (!response.ok) {
+            throw new FizzyError("auth_required", `Magic link redemption failed: ${response.status} ${response.statusText}`, { httpStatus: response.status, hint: "The magic link may have expired. Request a new one." });
+        }
+        const body = await response.json();
+        const sessionToken = body.session_token ?? body.token;
+        if (!sessionToken || typeof sessionToken !== "string") {
+            throw new FizzyError("api_error", "No session token in magic link response");
+        }
+        // Import CookieAuth dynamically to avoid circular dependency at module level
+        const { CookieAuth } = await import("./cookie-auth.js");
+        const auth = new CookieAuth(sessionToken);
+        return { sessionToken, auth };
+    }
+}
+//# sourceMappingURL=magic-link.js.map

package/dist/auth/magic-link.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"magic-link.js","sourceRoot":"","sources":["../../src/auth/magic-link.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAgC1C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,aAAa;IACP,OAAO,CAAS;IAChB,SAAS,CAAS;IAEnC,YAAY,OAA8B;QACxC,IAAI,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,kBAAkB,CAAC;QACtD,IAAI,CAAC,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,oBAAoB,CAAC;IAC9D,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,WAAW,CAAC,KAAa;QAC7B,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,OAAO,WAAW,EAAE;YACvD,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,YAAY,EAAE,IAAI,CAAC,SAAS;gBAC5B,MAAM,EAAE,kBAAkB;aAC3B;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,CAAC;SAChC,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,UAAU,CAClB,WAAW,EACX,8BAA8B,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,EACtE,EAAE,UAAU,EAAE,QAAQ,CAAC,MAAM,EAAE,CAChC,CAAC;QACJ,CAAC;QAED,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,qCAAqC,EAAE,CAAC;IACxE,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,WAAW,CAAC,KAAa;QAC7B,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,OAAO,kBAAkB,EAAE;YAC9D,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,YAAY,EAAE,IAAI,CAAC,SAAS;gBAC5B,MAAM,EAAE,kBAAkB;aAC3B;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,CAAC;SAChC,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,UAAU,CAClB,eAAe,EACf,iCAAiC,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,EACzE,EAAE,UAAU,EAAE,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,qDAAqD,EAAE,CAC7F,CAAC;QACJ,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAgD,CAAC;QACjF,MAAM,YAAY,GAAG,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,KAAK,CAAC;QAEtD,IAAI,CAAC,YAAY,IAAI,OAAO,YAAY,KAAK,QAAQ,EAAE,CAAC;YACtD,MAAM,IAAI,UAAU,CAAC,WAAW,EAAE,yCAAyC,CAAC,CAAC;QAC/E,CAAC;QAED,6EAA6E;QAC7E,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAC;QACxD,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,YAAY,CAAC,CAAC;QAE1C,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;IAChC,CAAC;CACF"}

package/dist/auth-strategy.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Authentication strategy for the Fizzy SDK.
+ *
+ * AuthStrategy controls how authentication is applied to HTTP requests.
+ * Fizzy supports Bearer tokens and Cookie sessions.
+ */
+import type { TokenProvider } from "./client.js";
+/**
+ * AuthStrategy controls how authentication is applied to HTTP requests.
+ * Called before every HTTP request to apply credentials to headers.
+ */
+export interface AuthStrategy {
+    /**
+     * Apply authentication to the given request headers.
+     * Called before every HTTP request.
+     */
+    authenticate(headers: Headers): Promise<void>;
+}
+/**
+ * Bearer token authentication strategy.
+ * Sets the Authorization header with "Bearer {token}".
+ */
+export declare class BearerAuth implements AuthStrategy {
+    private tokenProvider;
+    constructor(tokenProvider: TokenProvider);
+    authenticate(headers: Headers): Promise<void>;
+}
+/**
+ * Creates a BearerAuth strategy from a TokenProvider.
+ */
+export declare function bearerAuth(tokenProvider: TokenProvider): AuthStrategy;
+//# sourceMappingURL=auth-strategy.d.ts.map

package/dist/auth-strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-strategy.d.ts","sourceRoot":"","sources":["../src/auth-strategy.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C;AAED;;;GAGG;AACH,qBAAa,UAAW,YAAW,YAAY;IAC7C,OAAO,CAAC,aAAa,CAAgB;gBAEzB,aAAa,EAAE,aAAa;IAIlC,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;CAOpD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,aAAa,EAAE,aAAa,GAAG,YAAY,CAErE"}

package/dist/auth-strategy.js

@@ -0,0 +1,29 @@
+/**
+ * Authentication strategy for the Fizzy SDK.
+ *
+ * AuthStrategy controls how authentication is applied to HTTP requests.
+ * Fizzy supports Bearer tokens and Cookie sessions.
+ */
+/**
+ * Bearer token authentication strategy.
+ * Sets the Authorization header with "Bearer {token}".
+ */
+export class BearerAuth {
+    tokenProvider;
+    constructor(tokenProvider) {
+        this.tokenProvider = tokenProvider;
+    }
+    async authenticate(headers) {
+        const token = typeof this.tokenProvider === "function"
+            ? await this.tokenProvider()
+            : this.tokenProvider;
+        headers.set("Authorization", `Bearer ${token}`);
+    }
+}
+/**
+ * Creates a BearerAuth strategy from a TokenProvider.
+ */
+export function bearerAuth(tokenProvider) {
+    return new BearerAuth(tokenProvider);
+}
+//# sourceMappingURL=auth-strategy.js.map

package/dist/auth-strategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-strategy.js","sourceRoot":"","sources":["../src/auth-strategy.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAgBH;;;GAGG;AACH,MAAM,OAAO,UAAU;IACb,aAAa,CAAgB;IAErC,YAAY,aAA4B;QACtC,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;IACrC,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,OAAgB;QACjC,MAAM,KAAK,GACT,OAAO,IAAI,CAAC,aAAa,KAAK,UAAU;YACtC,CAAC,CAAC,MAAM,IAAI,CAAC,aAAa,EAAE;YAC5B,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC;QACzB,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,UAAU,KAAK,EAAE,CAAC,CAAC;IAClD,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,aAA4B;IACrD,OAAO,IAAI,UAAU,CAAC,aAAa,CAAC,CAAC;AACvC,CAAC"}

package/dist/cache/etag-cache.d.ts

@@ -0,0 +1,49 @@
+/**
+ * In-memory ETag cache for the Fizzy SDK.
+ *
+ * Provides HTTP conditional request support using ETag/If-None-Match headers.
+ * Entries are isolated by auth token hash to prevent cache poisoning across
+ * different auth contexts.
+ */
+export interface ETagCacheOptions {
+    /** Maximum number of cached responses (default: 1000) */
+    maxEntries?: number;
+    /** Maximum number of token hash entries (default: 100) */
+    maxTokenHashes?: number;
+}
+/**
+ * In-memory ETag cache with token-hash isolation.
+ * Uses Map insertion-order iteration to approximate LRU eviction.
+ */
+export declare class ETagCache {
+    private readonly cache;
+    private readonly maxEntries;
+    private readonly maxTokenHashes;
+    private readonly hashTokenMap;
+    private readonly pendingHashes;
+    constructor(options?: ETagCacheOptions);
+    /**
+     * Get the stored ETag for a URL (if any).
+     */
+    getETag(cacheKey: string): string | undefined;
+    /**
+     * Get the stored response body for a URL (if any).
+     */
+    getBody(cacheKey: string): string | undefined;
+    /**
+     * Store an ETag and response body.
+     */
+    set(cacheKey: string, etag: string, body: string): void;
+    /**
+     * Derive a cache key from URL and auth header.
+     */
+    getCacheKey(url: string, authHeader: string | null): Promise<string>;
+    /** Number of cached entries. */
+    get size(): number;
+    /** Clear all cached entries. */
+    clear(): void;
+    private getTokenHash;
+    private evictOldest;
+    private evictOldestHash;
+}
+//# sourceMappingURL=etag-cache.d.ts.map

package/dist/cache/etag-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"etag-cache.d.ts","sourceRoot":"","sources":["../../src/cache/etag-cache.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,MAAM,WAAW,gBAAgB;IAC/B,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;IACvD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6B;IAC1D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAsC;gBAExD,OAAO,CAAC,EAAE,gBAAgB;IAKtC;;OAEG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI7C;;OAEG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI7C;;OAEG;IACH,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAKvD;;OAEG;IACG,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC;IAK1E,gCAAgC;IAChC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,gCAAgC;IAChC,KAAK,IAAI,IAAI;YAIC,YAAY;IA2B1B,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,eAAe;CAMxB"}

package/dist/cache/etag-cache.js

@@ -0,0 +1,95 @@
+/**
+ * In-memory ETag cache for the Fizzy SDK.
+ *
+ * Provides HTTP conditional request support using ETag/If-None-Match headers.
+ * Entries are isolated by auth token hash to prevent cache poisoning across
+ * different auth contexts.
+ */
+/**
+ * In-memory ETag cache with token-hash isolation.
+ * Uses Map insertion-order iteration to approximate LRU eviction.
+ */
+export class ETagCache {
+    cache = new Map();
+    maxEntries;
+    maxTokenHashes;
+    hashTokenMap = new Map();
+    pendingHashes = new Map();
+    constructor(options) {
+        this.maxEntries = options?.maxEntries ?? 1000;
+        this.maxTokenHashes = options?.maxTokenHashes ?? 100;
+    }
+    /**
+     * Get the stored ETag for a URL (if any).
+     */
+    getETag(cacheKey) {
+        return this.cache.get(cacheKey)?.etag;
+    }
+    /**
+     * Get the stored response body for a URL (if any).
+     */
+    getBody(cacheKey) {
+        return this.cache.get(cacheKey)?.body;
+    }
+    /**
+     * Store an ETag and response body.
+     */
+    set(cacheKey, etag, body) {
+        this.evictOldest();
+        this.cache.set(cacheKey, { etag, body });
+    }
+    /**
+     * Derive a cache key from URL and auth header.
+     */
+    async getCacheKey(url, authHeader) {
+        const tokenHash = await this.getTokenHash(authHeader);
+        return `${tokenHash}:${url}`;
+    }
+    /** Number of cached entries. */
+    get size() {
+        return this.cache.size;
+    }
+    /** Clear all cached entries. */
+    clear() {
+        this.cache.clear();
+    }
+    async getTokenHash(authHeader) {
+        if (!authHeader)
+            return "";
+        const cached = this.hashTokenMap.get(authHeader);
+        if (cached)
+            return cached;
+        const pending = this.pendingHashes.get(authHeader);
+        if (pending)
+            return pending;
+        const promise = (async () => {
+            const data = new TextEncoder().encode(authHeader);
+            const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+            const hashArray = new Uint8Array(hashBuffer);
+            const hash = Array.from(hashArray.slice(0, 8))
+                .map((b) => b.toString(16).padStart(2, "0"))
+                .join("");
+            this.evictOldestHash();
+            this.hashTokenMap.set(authHeader, hash);
+            return hash;
+        })();
+        this.pendingHashes.set(authHeader, promise);
+        promise.finally(() => this.pendingHashes.delete(authHeader));
+        return promise;
+    }
+    evictOldest() {
+        if (this.cache.size >= this.maxEntries) {
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey)
+                this.cache.delete(firstKey);
+        }
+    }
+    evictOldestHash() {
+        if (this.hashTokenMap.size >= this.maxTokenHashes) {
+            const firstKey = this.hashTokenMap.keys().next().value;
+            if (firstKey)
+                this.hashTokenMap.delete(firstKey);
+        }
+    }
+}
+//# sourceMappingURL=etag-cache.js.map

package/dist/cache/etag-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"etag-cache.js","sourceRoot":"","sources":["../../src/cache/etag-cache.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Fizzy TypeScript SDK Client
+ *
+ * Creates a type-safe client for the Fizzy API using openapi-fetch.
+ * Includes middleware for authentication, retry with exponential backoff,
+ * ETag-based caching, and account scoping via forAccount().
+ */
+import createClient from "openapi-fetch";
+import type { paths } from "./generated/schema.js";
+import type { FizzyHooks } from "./hooks.js";
+import { parseNextLink, resolveURL, isSameOrigin } from "./pagination-utils.js";
+import { type AuthStrategy } from "./auth-strategy.js";
+export type { paths };
+/**
+ * Raw client type from openapi-fetch.
+ */
+export type RawClient = ReturnType<typeof createClient<paths>>;
+/**
+ * Enhanced Fizzy client with hooks support and service accessors.
+ */
+export interface FizzyClient extends RawClient {
+    readonly raw: RawClient;
+    readonly hooks?: FizzyHooks;
+    /**
+     * Returns a new client scoped to the given account ID.
+     * The new client shares auth strategy, hooks, and settings but
+     * targets a different account URL prefix.
+     */
+    forAccount(accountId: string): FizzyClient;
+}
+/**
+ * Token provider — either a static token string or an async function that returns a token.
+ */
+export type TokenProvider = string | (() => Promise<string>);
+/**
+ * Configuration options for creating a Fizzy client.
+ */
+export interface FizzyClientOptions {
+    /** Fizzy account ID (found in your Fizzy URL) */
+    accountId?: string;
+    /** Bearer access token or async function that returns one */
+    accessToken?: TokenProvider;
+    /** Authentication strategy (alternative to accessToken for custom auth schemes) */
+    auth?: AuthStrategy;
+    /** Base URL override (defaults to https://fizzy.do) */
+    baseUrl?: string;
+    /** User-Agent header (defaults to fizzy-sdk-ts/VERSION (api:API_VERSION)) */
+    userAgent?: string;
+    /** Enable ETag-based caching (defaults to false) */
+    enableCache?: boolean;
+    /** Enable automatic retry on 429/503 (defaults to true) */
+    enableRetry?: boolean;
+    /** Request timeout in milliseconds (defaults to 30000) */
+    requestTimeoutMs?: number;
+    /** Hooks for observability (logging, metrics, tracing) */
+    hooks?: FizzyHooks;
+}
+export declare const VERSION = "0.1.0";
+export declare const API_VERSION = "2026-03-01";
+/**
+ * Creates a type-safe Fizzy API client with built-in middleware for:
+ * - Authentication (Bearer token or Cookie session)
+ * - Retry with exponential backoff (respects Retry-After header)
+ * - ETag-based HTTP caching
+ *
+ * @example
+ * ```ts
+ * import { createFizzyClient } from "@37signals/fizzy";
+ *
+ * const client = createFizzyClient({
+ *   accessToken: process.env.FIZZY_TOKEN!,
+ * });
+ *
+ * const { data, error } = await client.GET("/boards.json");
+ * ```
+ */
+export declare function createFizzyClient(options: FizzyClientOptions): FizzyClient;
+/**
+ * Normalizes a URL path by replacing numeric IDs with placeholder tokens.
+ * For example: /boards/456/cards/789 -> /boards/{boardId}/cards/{cardNumber}
+ */
+export declare function normalizeUrlPath(url: string): string;
+/**
+ * Fetches all pages of a paginated resource using Link header pagination.
+ */
+export declare function fetchAllPages<T>(initialResponse: Response, parse: (response: Response) => Promise<T[]>, authHeader?: string): Promise<T[]>;
+/**
+ * Async generator that yields pages of results one at a time.
+ */
+export declare function paginateAll<T>(initialResponse: Response, parse: (response: Response) => Promise<T[]>, authHeader?: string): AsyncGenerator<T[], void, unknown>;
+export { parseNextLink, resolveURL, isSameOrigin };
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,YAAiC,MAAM,eAAe,CAAC;AAE9D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAEnD,OAAO,KAAK,EAAE,UAAU,EAA8B,MAAM,YAAY,CAAC;AAGzE,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAChF,OAAO,EAAE,KAAK,YAAY,EAAc,MAAM,oBAAoB,CAAC;AAuBnE,YAAY,EAAE,KAAK,EAAE,CAAC;AAEtB;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;AAE/D;;GAEG;AACH,MAAM,WAAW,WAAY,SAAQ,SAAS;IAC5C,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAE5B;;;;OAIG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,CAAC;CAI5C;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;AAE7D;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,WAAW,CAAC,EAAE,aAAa,CAAC;IAC5B,mFAAmF;IACnF,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,2DAA2D;IAC3D,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,0DAA0D;IAC1D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,0DAA0D;IAC1D,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAED,eAAO,MAAM,OAAO,UAAU,CAAC;AAC/B,eAAO,MAAM,WAAW,eAAe,CAAC;AAIxC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,WAAW,CAkH1E;AAsLD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAsDpD;AAoID;;GAEG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,eAAe,EAAE,QAAQ,EACzB,KAAK,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,OAAO,CAAC,CAAC,EAAE,CAAC,EAC3C,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,CAAC,EAAE,CAAC,CA0Bd;AAED;;GAEG;AACH,wBAAuB,WAAW,CAAC,CAAC,EAClC,eAAe,EAAE,QAAQ,EACzB,KAAK,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,OAAO,CAAC,CAAC,EAAE,CAAC,EAC3C,UAAU,CAAC,EAAE,MAAM,GAClB,cAAc,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,CAuBpC;AAGD,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC"}