@37signals/fizzy 0.1.0

package/dist/resilience/circuit-breaker.js

@@ -0,0 +1,74 @@
+/**
+ * Circuit breaker for the Fizzy SDK.
+ *
+ * Prevents cascading failures by tracking error rates and temporarily
+ * stopping requests when the failure threshold is exceeded.
+ */
+/**
+ * Circuit breaker implementation using the standard closed/open/half-open pattern.
+ */
+export class CircuitBreaker {
+    state = "closed";
+    failureCount = 0;
+    successCount = 0;
+    lastFailureTime = 0;
+    failureThreshold;
+    resetTimeoutMs;
+    successThreshold;
+    constructor(options) {
+        this.failureThreshold = options?.failureThreshold ?? 5;
+        this.resetTimeoutMs = options?.resetTimeoutMs ?? 30_000;
+        this.successThreshold = options?.successThreshold ?? 1;
+    }
+    /** Current circuit state. */
+    get currentState() {
+        if (this.state === "open" && Date.now() - this.lastFailureTime >= this.resetTimeoutMs) {
+            this.state = "half-open";
+        }
+        return this.state;
+    }
+    /**
+     * Check if a request is allowed through the circuit.
+     * Returns true if the circuit is closed or half-open.
+     */
+    allowRequest() {
+        return this.currentState !== "open";
+    }
+    /**
+     * Record a successful request.
+     */
+    recordSuccess() {
+        if (this.state === "half-open") {
+            this.successCount++;
+            if (this.successCount >= this.successThreshold) {
+                this.state = "closed";
+                this.failureCount = 0;
+                this.successCount = 0;
+            }
+        }
+        else {
+            this.failureCount = 0;
+        }
+    }
+    /**
+     * Record a failed request.
+     */
+    recordFailure() {
+        this.failureCount++;
+        this.lastFailureTime = Date.now();
+        if (this.state === "half-open" || this.failureCount >= this.failureThreshold) {
+            this.state = "open";
+            this.successCount = 0;
+        }
+    }
+    /**
+     * Reset the circuit breaker to closed state.
+     */
+    reset() {
+        this.state = "closed";
+        this.failureCount = 0;
+        this.successCount = 0;
+        this.lastFailureTime = 0;
+    }
+}
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/resilience/circuit-breaker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.js","sourceRoot":"","sources":["../../src/resilience/circuit-breaker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAaH;;GAEG;AACH,MAAM,OAAO,cAAc;IACjB,KAAK,GAAiB,QAAQ,CAAC;IAC/B,YAAY,GAAG,CAAC,CAAC;IACjB,YAAY,GAAG,CAAC,CAAC;IACjB,eAAe,GAAG,CAAC,CAAC;IACX,gBAAgB,CAAS;IACzB,cAAc,CAAS;IACvB,gBAAgB,CAAS;IAE1C,YAAY,OAA+B;QACzC,IAAI,CAAC,gBAAgB,GAAG,OAAO,EAAE,gBAAgB,IAAI,CAAC,CAAC;QACvD,IAAI,CAAC,cAAc,GAAG,OAAO,EAAE,cAAc,IAAI,MAAM,CAAC;QACxD,IAAI,CAAC,gBAAgB,GAAG,OAAO,EAAE,gBAAgB,IAAI,CAAC,CAAC;IACzD,CAAC;IAED,6BAA6B;IAC7B,IAAI,YAAY;QACd,IAAI,IAAI,CAAC,KAAK,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACtF,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC;QAC3B,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED;;;OAGG;IACH,YAAY;QACV,OAAO,IAAI,CAAC,YAAY,KAAK,MAAM,CAAC;IACtC,CAAC;IAED;;OAEG;IACH,aAAa;QACX,IAAI,IAAI,CAAC,KAAK,KAAK,WAAW,EAAE,CAAC;YAC/B,IAAI,CAAC,YAAY,EAAE,CAAC;YACpB,IAAI,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;gBAC/C,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC;gBACtB,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;gBACtB,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;YACxB,CAAC;QACH,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IAED;;OAEG;IACH,aAAa;QACX,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAElC,IAAI,IAAI,CAAC,KAAK,KAAK,WAAW,IAAI,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC7E,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC;YACpB,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC;QACtB,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;QACtB,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;QACtB,IAAI,CAAC,eAAe,GAAG,CAAC,CAAC;IAC3B,CAAC;CACF"}

package/dist/resilience/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Resilience module for the Fizzy SDK.
+ *
+ * Composes circuit breaker, bulkhead, and rate limiter into a unified
+ * configuration and hooks integration.
+ */
+import { CircuitBreaker, type CircuitBreakerOptions } from "./circuit-breaker.js";
+import { Bulkhead, type BulkheadOptions } from "./bulkhead.js";
+import { RateLimiter, type RateLimiterOptions } from "./rate-limiter.js";
+import type { FizzyHooks } from "../hooks.js";
+export { CircuitBreaker, type CircuitBreakerOptions } from "./circuit-breaker.js";
+export { Bulkhead, type BulkheadOptions } from "./bulkhead.js";
+export { RateLimiter, type RateLimiterOptions } from "./rate-limiter.js";
+/**
+ * Unified resilience configuration.
+ */
+export interface ResilienceConfig {
+    /** Circuit breaker options (false to disable) */
+    circuitBreaker?: CircuitBreakerOptions | false;
+    /** Bulkhead / concurrency limiter options (false to disable) */
+    bulkhead?: BulkheadOptions | false;
+    /** Rate limiter options (false to disable) */
+    rateLimiter?: RateLimiterOptions | false;
+}
+/**
+ * Active resilience components created from configuration.
+ */
+export interface ResilienceComponents {
+    circuitBreaker?: CircuitBreaker;
+    bulkhead?: Bulkhead;
+    rateLimiter?: RateLimiter;
+}
+/**
+ * Create resilience components from configuration.
+ */
+export declare function createResilienceComponents(config: ResilienceConfig): ResilienceComponents;
+/**
+ * Creates FizzyHooks that track circuit breaker state from request results.
+ */
+export declare function resilienceHooks(components: ResilienceComponents): FizzyHooks;
+//# sourceMappingURL=index.d.ts.map

package/dist/resilience/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/resilience/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAClF,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,KAAK,EAAE,UAAU,EAA8B,MAAM,aAAa,CAAC;AAE1E,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAClF,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iDAAiD;IACjD,cAAc,CAAC,EAAE,qBAAqB,GAAG,KAAK,CAAC;IAC/C,gEAAgE;IAChE,QAAQ,CAAC,EAAE,eAAe,GAAG,KAAK,CAAC;IACnC,8CAA8C;IAC9C,WAAW,CAAC,EAAE,kBAAkB,GAAG,KAAK,CAAC;CAC1C;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,gBAAgB,GAAG,oBAAoB,CAYzF;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,oBAAoB,GAAG,UAAU,CAY5E"}

package/dist/resilience/index.js

@@ -0,0 +1,46 @@
+/**
+ * Resilience module for the Fizzy SDK.
+ *
+ * Composes circuit breaker, bulkhead, and rate limiter into a unified
+ * configuration and hooks integration.
+ */
+import { CircuitBreaker } from "./circuit-breaker.js";
+import { Bulkhead } from "./bulkhead.js";
+import { RateLimiter } from "./rate-limiter.js";
+export { CircuitBreaker } from "./circuit-breaker.js";
+export { Bulkhead } from "./bulkhead.js";
+export { RateLimiter } from "./rate-limiter.js";
+/**
+ * Create resilience components from configuration.
+ */
+export function createResilienceComponents(config) {
+    return {
+        circuitBreaker: config.circuitBreaker !== false
+            ? new CircuitBreaker(config.circuitBreaker === undefined ? {} : config.circuitBreaker)
+            : undefined,
+        bulkhead: config.bulkhead !== false
+            ? new Bulkhead(config.bulkhead === undefined ? {} : config.bulkhead)
+            : undefined,
+        rateLimiter: config.rateLimiter !== false
+            ? new RateLimiter(config.rateLimiter === undefined ? {} : config.rateLimiter)
+            : undefined,
+    };
+}
+/**
+ * Creates FizzyHooks that track circuit breaker state from request results.
+ */
+export function resilienceHooks(components) {
+    return {
+        onRequestEnd(_info, result) {
+            if (!components.circuitBreaker)
+                return;
+            if (result.statusCode >= 500) {
+                components.circuitBreaker.recordFailure();
+            }
+            else {
+                components.circuitBreaker.recordSuccess();
+            }
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/resilience/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/resilience/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAA8B,MAAM,sBAAsB,CAAC;AAClF,OAAO,EAAE,QAAQ,EAAwB,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAE,WAAW,EAA2B,MAAM,mBAAmB,CAAC;AAGzE,OAAO,EAAE,cAAc,EAA8B,MAAM,sBAAsB,CAAC;AAClF,OAAO,EAAE,QAAQ,EAAwB,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAE,WAAW,EAA2B,MAAM,mBAAmB,CAAC;AAuBzE;;GAEG;AACH,MAAM,UAAU,0BAA0B,CAAC,MAAwB;IACjE,OAAO;QACL,cAAc,EAAE,MAAM,CAAC,cAAc,KAAK,KAAK;YAC7C,CAAC,CAAC,IAAI,cAAc,CAAC,MAAM,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC;YACtF,CAAC,CAAC,SAAS;QACb,QAAQ,EAAE,MAAM,CAAC,QAAQ,KAAK,KAAK;YACjC,CAAC,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC;YACpE,CAAC,CAAC,SAAS;QACb,WAAW,EAAE,MAAM,CAAC,WAAW,KAAK,KAAK;YACvC,CAAC,CAAC,IAAI,WAAW,CAAC,MAAM,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC;YAC7E,CAAC,CAAC,SAAS;KACd,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,UAAgC;IAC9D,OAAO;QACL,YAAY,CAAC,KAAkB,EAAE,MAAqB;YACpD,IAAI,CAAC,UAAU,CAAC,cAAc;gBAAE,OAAO;YAEvC,IAAI,MAAM,CAAC,UAAU,IAAI,GAAG,EAAE,CAAC;gBAC7B,UAAU,CAAC,cAAc,CAAC,aAAa,EAAE,CAAC;YAC5C,CAAC;iBAAM,CAAC;gBACN,UAAU,CAAC,cAAc,CAAC,aAAa,EAAE,CAAC;YAC5C,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/resilience/rate-limiter.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Token bucket rate limiter for the Fizzy SDK.
+ *
+ * Smooths request rates to stay within API rate limits.
+ * Tokens refill at a constant rate; each request consumes one token.
+ */
+export interface RateLimiterOptions {
+    /** Maximum tokens in the bucket (default: 50) */
+    maxTokens?: number;
+    /** Token refill rate — tokens per second (default: 10) */
+    refillRate?: number;
+}
+/**
+ * Token bucket rate limiter.
+ */
+export declare class RateLimiter {
+    private tokens;
+    private readonly maxTokens;
+    private readonly refillRate;
+    private lastRefillTime;
+    constructor(options?: RateLimiterOptions);
+    /** Current number of available tokens. */
+    get availableTokens(): number;
+    /**
+     * Try to consume a token. Returns true if a token was available.
+     */
+    tryAcquire(): boolean;
+    /**
+     * Wait until a token is available, then consume it.
+     */
+    acquire(): Promise<void>;
+    /**
+     * Estimated milliseconds until the next token becomes available.
+     */
+    msUntilNextToken(): number;
+    private refill;
+}
+//# sourceMappingURL=rate-limiter.d.ts.map

package/dist/resilience/rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../../src/resilience/rate-limiter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,kBAAkB;IACjC,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,cAAc,CAAS;gBAEnB,OAAO,CAAC,EAAE,kBAAkB;IAOxC,0CAA0C;IAC1C,IAAI,eAAe,IAAI,MAAM,CAG5B;IAED;;OAEG;IACH,UAAU,IAAI,OAAO;IASrB;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAW9B;;OAEG;IACH,gBAAgB,IAAI,MAAM;IAO1B,OAAO,CAAC,MAAM;CAUf"}

package/dist/resilience/rate-limiter.js

@@ -0,0 +1,69 @@
+/**
+ * Token bucket rate limiter for the Fizzy SDK.
+ *
+ * Smooths request rates to stay within API rate limits.
+ * Tokens refill at a constant rate; each request consumes one token.
+ */
+/**
+ * Token bucket rate limiter.
+ */
+export class RateLimiter {
+    tokens;
+    maxTokens;
+    refillRate;
+    lastRefillTime;
+    constructor(options) {
+        this.maxTokens = options?.maxTokens ?? 50;
+        this.refillRate = options?.refillRate ?? 10;
+        this.tokens = this.maxTokens;
+        this.lastRefillTime = Date.now();
+    }
+    /** Current number of available tokens. */
+    get availableTokens() {
+        this.refill();
+        return this.tokens;
+    }
+    /**
+     * Try to consume a token. Returns true if a token was available.
+     */
+    tryAcquire() {
+        this.refill();
+        if (this.tokens >= 1) {
+            this.tokens--;
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Wait until a token is available, then consume it.
+     */
+    async acquire() {
+        if (this.tryAcquire())
+            return;
+        const waitMs = this.msUntilNextToken();
+        await new Promise((resolve) => setTimeout(resolve, waitMs));
+        // Refill and take the token
+        this.refill();
+        this.tokens = Math.max(0, this.tokens - 1);
+    }
+    /**
+     * Estimated milliseconds until the next token becomes available.
+     */
+    msUntilNextToken() {
+        this.refill();
+        if (this.tokens >= 1)
+            return 0;
+        const deficit = 1 - this.tokens;
+        return Math.ceil((deficit / this.refillRate) * 1000);
+    }
+    refill() {
+        const now = Date.now();
+        const elapsed = (now - this.lastRefillTime) / 1000;
+        const newTokens = elapsed * this.refillRate;
+        if (newTokens > 0) {
+            this.tokens = Math.min(this.maxTokens, this.tokens + newTokens);
+            this.lastRefillTime = now;
+        }
+    }
+}
+//# sourceMappingURL=rate-limiter.js.map

package/dist/resilience/rate-limiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.js","sourceRoot":"","sources":["../../src/resilience/rate-limiter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH;;GAEG;AACH,MAAM,OAAO,WAAW;IACd,MAAM,CAAS;IACN,SAAS,CAAS;IAClB,UAAU,CAAS;IAC5B,cAAc,CAAS;IAE/B,YAAY,OAA4B;QACtC,IAAI,CAAC,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,EAAE,CAAC;QAC1C,IAAI,CAAC,UAAU,GAAG,OAAO,EAAE,UAAU,IAAI,EAAE,CAAC;QAC5C,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC;QAC7B,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACnC,CAAC;IAED,0CAA0C;IAC1C,IAAI,eAAe;QACjB,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,UAAU;QACR,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;YACrB,IAAI,CAAC,MAAM,EAAE,CAAC;YACd,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAO;QACX,IAAI,IAAI,CAAC,UAAU,EAAE;YAAE,OAAO;QAE9B,MAAM,MAAM,GAAG,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACvC,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;QAE5D,4BAA4B;QAC5B,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC7C,CAAC;IAED;;OAEG;IACH,gBAAgB;QACd,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC;YAAE,OAAO,CAAC,CAAC;QAC/B,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;QAChC,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,CAAC;IACvD,CAAC;IAEO,MAAM;QACZ,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,OAAO,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,IAAI,CAAC;QACnD,MAAM,SAAS,GAAG,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC;QAE5C,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;YAClB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;YAChE,IAAI,CAAC,cAAc,GAAG,GAAG,CAAC;QAC5B,CAAC;IACH,CAAC;CACF"}

package/dist/security.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Security utilities for the Fizzy SDK.
+ *
+ * Provides helpers for safely logging HTTP requests without exposing
+ * sensitive information like tokens and cookies.
+ */
+/**
+ * Returns a copy of the headers with sensitive values replaced by "[REDACTED]".
+ */
+export declare function redactHeaders(headers: Headers): Record<string, string>;
+/**
+ * Returns a copy of the header record with sensitive values replaced by "[REDACTED]".
+ */
+export declare function redactHeadersRecord(headers: Record<string, string>): Record<string, string>;
+/**
+ * Checks if a hostname represents localhost for development/testing purposes.
+ */
+export declare function isLocalhost(hostname: string): boolean;
+//# sourceMappingURL=security.d.ts.map

package/dist/security.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../src/security.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAatE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAaxB;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAQrD"}

package/dist/security.js

@@ -0,0 +1,55 @@
+/**
+ * Security utilities for the Fizzy SDK.
+ *
+ * Provides helpers for safely logging HTTP requests without exposing
+ * sensitive information like tokens and cookies.
+ */
+const SENSITIVE_HEADERS = [
+    "authorization",
+    "cookie",
+    "set-cookie",
+    "x-csrf-token",
+];
+/**
+ * Returns a copy of the headers with sensitive values replaced by "[REDACTED]".
+ */
+export function redactHeaders(headers) {
+    const result = {};
+    headers.forEach((value, key) => {
+        const lowerKey = key.toLowerCase();
+        if (SENSITIVE_HEADERS.includes(lowerKey)) {
+            result[key] = "[REDACTED]";
+        }
+        else {
+            result[key] = value;
+        }
+    });
+    return result;
+}
+/**
+ * Returns a copy of the header record with sensitive values replaced by "[REDACTED]".
+ */
+export function redactHeadersRecord(headers) {
+    const result = {};
+    for (const [key, value] of Object.entries(headers)) {
+        const lowerKey = key.toLowerCase();
+        if (SENSITIVE_HEADERS.includes(lowerKey)) {
+            result[key] = "[REDACTED]";
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Checks if a hostname represents localhost for development/testing purposes.
+ */
+export function isLocalhost(hostname) {
+    const normalized = hostname.toLowerCase();
+    return (normalized === "localhost" ||
+        normalized === "127.0.0.1" ||
+        normalized === "::1" ||
+        normalized.endsWith(".localhost"));
+}
+//# sourceMappingURL=security.js.map

package/dist/security.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.js","sourceRoot":"","sources":["../src/security.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,iBAAiB,GAAG;IACxB,eAAe;IACf,QAAQ;IACR,YAAY;IACZ,cAAc;CACf,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,OAAgB;IAC5C,MAAM,MAAM,GAA2B,EAAE,CAAC;IAE1C,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;QAC7B,MAAM,QAAQ,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;QACnC,IAAI,iBAAiB,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YACzC,MAAM,CAAC,GAAG,CAAC,GAAG,YAAY,CAAC;QAC7B,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACtB,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAA+B;IAE/B,MAAM,MAAM,GAA2B,EAAE,CAAC;IAE1C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACnD,MAAM,QAAQ,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;QACnC,IAAI,iBAAiB,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YACzC,MAAM,CAAC,GAAG,CAAC,GAAG,YAAY,CAAC;QAC7B,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACtB,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,QAAgB;IAC1C,MAAM,UAAU,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC;IAC1C,OAAO,CACL,UAAU,KAAK,WAAW;QAC1B,UAAU,KAAK,WAAW;QAC1B,UAAU,KAAK,KAAK;QACpB,UAAU,CAAC,QAAQ,CAAC,YAAY,CAAC,CAClC,CAAC;AACJ,CAAC"}

package/dist/services/base.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Base service class for Fizzy API services.
+ *
+ * Provides shared functionality for all service classes including:
+ * - Error handling with typed FizzyError
+ * - Hooks integration for observability
+ * - Automatic pagination via Link headers
+ */
+import type { FizzyHooks, OperationInfo } from "../hooks.js";
+import { FizzyError } from "../errors.js";
+import { ListResult, type PaginationOptions } from "../pagination.js";
+import type { paths } from "../generated/schema.js";
+import type createClient from "openapi-fetch";
+/**
+ * Raw client type from openapi-fetch.
+ */
+export type RawClient = ReturnType<typeof createClient<paths>>;
+/**
+ * Response type from openapi-fetch methods.
+ */
+export interface FetchResponse<T> {
+    data?: T;
+    error?: unknown;
+    response: Response;
+}
+/**
+ * Abstract base class for all Fizzy API services.
+ */
+export declare abstract class BaseService {
+    protected readonly client: RawClient;
+    protected readonly hooks?: FizzyHooks;
+    /**
+     * Authenticated fetch for pagination follow-up requests.
+     * Provided by createFizzyClient; falls back to unauthenticated fetch.
+     */
+    protected readonly fetchPage: (url: string) => Promise<Response>;
+    constructor(client: RawClient, hooks?: FizzyHooks, fetchPage?: (url: string) => Promise<Response>);
+    /**
+     * Executes an API request with error handling and hooks integration.
+     */
+    protected request<T>(info: OperationInfo, fn: () => Promise<FetchResponse<T>>): Promise<T>;
+    /**
+     * Executes a paginated API request, automatically following Link headers.
+     * Returns a ListResult<T> which extends Array<T>.
+     * Fizzy does not emit X-Total-Count.
+     */
+    protected requestPaginated<T>(info: OperationInfo, fn: () => Promise<FetchResponse<T[]>>, paginationOpts?: PaginationOptions): Promise<ListResult<T>>;
+    private followPagination;
+    protected handleError(response: Response, error?: unknown): Promise<FizzyError>;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/services/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/services/base.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAmB,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAqB,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAEtE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,KAAK,YAAY,MAAM,eAAe,CAAC;AAE9C;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;AAE/D;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAKD;;GAEG;AACH,8BAAsB,WAAW;IAC/B,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IACrC,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAEtC;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAG/D,MAAM,EAAE,SAAS,EACjB,KAAK,CAAC,EAAE,UAAU,EAClB,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,CAAC;IAOhD;;OAEG;cACa,OAAO,CAAC,CAAC,EACvB,IAAI,EAAE,aAAa,EACnB,EAAE,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,GAClC,OAAO,CAAC,CAAC,CAAC;IAgCb;;;;OAIG;cACa,gBAAgB,CAAC,CAAC,EAChC,IAAI,EAAE,aAAa,EACnB,EAAE,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EACrC,cAAc,CAAC,EAAE,iBAAiB,GACjC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;YA6CX,gBAAgB;cAqCd,WAAW,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC;CAOtF"}

package/dist/services/base.js

@@ -0,0 +1,146 @@
+/**
+ * Base service class for Fizzy API services.
+ *
+ * Provides shared functionality for all service classes including:
+ * - Error handling with typed FizzyError
+ * - Hooks integration for observability
+ * - Automatic pagination via Link headers
+ */
+import { FizzyError, errorFromResponse } from "../errors.js";
+import { ListResult } from "../pagination.js";
+import { parseNextLink, resolveURL, isSameOrigin } from "../pagination-utils.js";
+/** Maximum pages to follow as a safety cap against infinite loops. */
+const MAX_PAGES = 10_000;
+/**
+ * Abstract base class for all Fizzy API services.
+ */
+export class BaseService {
+    client;
+    hooks;
+    /**
+     * Authenticated fetch for pagination follow-up requests.
+     * Provided by createFizzyClient; falls back to unauthenticated fetch.
+     */
+    fetchPage;
+    constructor(client, hooks, fetchPage) {
+        this.client = client;
+        this.hooks = hooks;
+        this.fetchPage = fetchPage ?? ((url) => fetch(url, { headers: { Accept: "application/json" } }));
+    }
+    /**
+     * Executes an API request with error handling and hooks integration.
+     */
+    async request(info, fn) {
+        const start = performance.now();
+        let result = { durationMs: 0 };
+        try {
+            this.hooks?.onOperationStart?.(info);
+        }
+        catch { /* hooks must not interrupt */ }
+        try {
+            const { data, error, response } = await fn();
+            result.durationMs = Math.round(performance.now() - start);
+            if (!response.ok || error) {
+                const fizzyError = await this.handleError(response, error);
+                result.error = fizzyError;
+                throw fizzyError;
+            }
+            if (response.status === 204 || data === undefined) {
+                return undefined;
+            }
+            return data;
+        }
+        catch (err) {
+            result.durationMs = Math.round(performance.now() - start);
+            if (err instanceof Error) {
+                result.error = err;
+            }
+            throw err;
+        }
+        finally {
+            try {
+                this.hooks?.onOperationEnd?.(info, result);
+            }
+            catch { /* hooks must not interrupt */ }
+        }
+    }
+    /**
+     * Executes a paginated API request, automatically following Link headers.
+     * Returns a ListResult<T> which extends Array<T>.
+     * Fizzy does not emit X-Total-Count.
+     */
+    async requestPaginated(info, fn, paginationOpts) {
+        const start = performance.now();
+        let result = { durationMs: 0 };
+        try {
+            this.hooks?.onOperationStart?.(info);
+        }
+        catch { /* hooks must not interrupt */ }
+        try {
+            const { data, error, response } = await fn();
+            result.durationMs = Math.round(performance.now() - start);
+            if (!response.ok || error) {
+                const fizzyError = await this.handleError(response, error);
+                result.error = fizzyError;
+                throw fizzyError;
+            }
+            const firstPageItems = data ?? [];
+            const maxItems = paginationOpts?.maxItems;
+            if (maxItems && maxItems > 0 && firstPageItems.length >= maxItems) {
+                const hasMore = firstPageItems.length > maxItems
+                    || parseNextLink(response.headers.get("Link")) !== null;
+                result.durationMs = Math.round(performance.now() - start);
+                return new ListResult(firstPageItems.slice(0, maxItems), { truncated: hasMore });
+            }
+            const { items: allItems, truncated } = await this.followPagination(response, firstPageItems, maxItems);
+            result.durationMs = Math.round(performance.now() - start);
+            return new ListResult(allItems, { truncated });
+        }
+        catch (err) {
+            result.durationMs = Math.round(performance.now() - start);
+            if (err instanceof Error) {
+                result.error = err;
+            }
+            throw err;
+        }
+        finally {
+            try {
+                this.hooks?.onOperationEnd?.(info, result);
+            }
+            catch { /* hooks must not interrupt */ }
+        }
+    }
+    async followPagination(initialResponse, firstPageItems, maxItems) {
+        const allItems = [...firstPageItems];
+        let response = initialResponse;
+        const initialUrl = initialResponse.url;
+        for (let page = 1; page < MAX_PAGES; page++) {
+            const rawNextUrl = parseNextLink(response.headers.get("Link"));
+            if (!rawNextUrl)
+                break;
+            const nextUrl = resolveURL(response.url, rawNextUrl);
+            if (!isSameOrigin(nextUrl, initialUrl)) {
+                break;
+            }
+            response = await this.fetchPage(nextUrl);
+            if (!response.ok) {
+                throw await errorFromResponse(response, response.headers.get("X-Request-Id") ?? undefined);
+            }
+            const pageItems = (await response.json());
+            allItems.push(...pageItems);
+            if (maxItems && maxItems > 0 && allItems.length >= maxItems) {
+                return { items: allItems.slice(0, maxItems), truncated: true };
+            }
+        }
+        const hasMore = parseNextLink(response.headers.get("Link")) !== null;
+        return { items: allItems, truncated: hasMore };
+    }
+    async handleError(response, error) {
+        if (error instanceof FizzyError) {
+            return error;
+        }
+        const requestId = response.headers.get("X-Request-Id") ?? undefined;
+        return errorFromResponse(response, requestId);
+    }
+}
+//# sourceMappingURL=base.js.map

package/dist/services/base.js.map

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

package/dist/webhooks/handler.d.ts

@@ -0,0 +1,62 @@
+/** Webhook event — raw JSON object from Fizzy. */
+export interface WebhookEvent {
+    id?: number;
+    kind?: string;
+    [key: string]: unknown;
+}
+/** Handler function for webhook events. */
+export type WebhookEventHandler = (event: WebhookEvent) => void | Promise<void>;
+/** Middleware function that wraps event processing. Call next() to continue the chain. */
+export type WebhookMiddleware = (event: WebhookEvent, next: () => Promise<void>) => Promise<void>;
+/** Header accessor: either a record of headers or a function that retrieves a header by name. */
+export type HeaderAccessor = Record<string, string | string[] | undefined> | ((name: string) => string | undefined);
+export interface WebhookReceiverOptions {
+    /** HMAC secret for signature verification. If unset, verification is skipped. */
+    secret?: string;
+    /** HTTP header containing the signature (default: "x-fizzy-signature"). */
+    signatureHeader?: string;
+    /** Number of recent event IDs to track for deduplication (default: 1000, 0 to disable). */
+    dedupWindowSize?: number;
+}
+/** Error thrown when webhook signature verification fails. */
+export declare class WebhookVerificationError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Receives and routes webhook events from Fizzy.
+ *
+ * Framework-agnostic: works with raw body bytes and a header accessor.
+ */
+export declare class WebhookReceiver {
+    private readonly secret?;
+    private readonly signatureHeader;
+    private readonly dedupWindowSize;
+    private readonly handlers;
+    private readonly anyHandlers;
+    private readonly middlewareChain;
+    private readonly dedupSeen;
+    private readonly dedupOrder;
+    private readonly dedupPending;
+    constructor(options?: WebhookReceiverOptions);
+    /**
+     * Register a handler for a specific event kind pattern.
+     * Supports exact match ("card_created") and glob patterns ("card_*", "*_created").
+     */
+    on(pattern: string, handler: WebhookEventHandler): this;
+    /** Register a handler that fires for all events. */
+    onAny(handler: WebhookEventHandler): this;
+    /** Add middleware to the processing chain. */
+    use(middleware: WebhookMiddleware): this;
+    /**
+     * Process a raw webhook request.
+     * Returns the parsed WebhookEvent.
+     * @throws {WebhookVerificationError} if signature verification fails
+     */
+    handleRequest(rawBody: string | Buffer, headers: HeaderAccessor): Promise<WebhookEvent>;
+    private getHeader;
+    private claim;
+    private commitSeen;
+    private releaseClaim;
+    private dispatchHandlers;
+}
+//# sourceMappingURL=handler.d.ts.map