@aimee.shop/sdk 0.0.1

package/dist/core/http-client.d.ts

@@ -0,0 +1,88 @@
+import { type AxiosRequestConfig } from 'axios';
+import type { AuthChain } from './auth/auth-chain.js';
+import { ZiftrError } from './errors/index.js';
+import { type RetryOptions } from './retry.js';
+/**
+ * Configuration options for the HTTP client
+ */
+export interface HttpClientOptions {
+    /** Request timeout in milliseconds */
+    timeout: number;
+    /** Enable debug logging */
+    debug: boolean;
+    /** Auth chain for adding authorization headers */
+    authChain: AuthChain;
+    /** Function to get current tenant ID */
+    getTenantId: () => string | undefined;
+    /** Function to get current store ID */
+    getStoreId: () => string | undefined;
+    /** Optional request interceptor hook */
+    onRequest?: (config: AxiosRequestConfig) => AxiosRequestConfig | Promise<AxiosRequestConfig>;
+    /** Optional response interceptor hook */
+    onResponse?: <T>(response: T) => T | Promise<T>;
+    /** Optional error handler hook. Called once per request, after retries are exhausted */
+    onError?: (error: ZiftrError) => void | Promise<void>;
+    /** Automatic retry policy. On by default; disable with { enabled: false } */
+    retry?: RetryOptions;
+    /** Wait implementation between retries; injectable for deterministic tests */
+    sleepFn?: (ms: number) => Promise<void>;
+    /** Randomness source for backoff jitter in [0, 1); injectable for deterministic tests */
+    randomFn?: () => number;
+}
+/**
+ * Structural transport interface used by resource clients.
+ *
+ * Resource clients depend on this shape instead of the concrete HttpClient class so platform
+ * packages can consume the public SDK HttpClient instance without duplicating private class
+ * identity across package builds.
+ */
+export interface HttpClientTransport {
+    getTenantId(): string | undefined;
+    get<T>(url: string, config?: AxiosRequestConfig): Promise<T>;
+    post<T>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<T>;
+    patch<T>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<T>;
+    put<T>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<T>;
+    delete<T>(url: string, config?: AxiosRequestConfig): Promise<T>;
+    stream(url: string, data?: unknown): Promise<Response>;
+}
+/**
+ * HTTP client wrapper around axios with:
+ * - Automatic auth header injection
+ * - Tenant/store context headers
+ * - Error transformation to typed ZiftrError classes
+ * - Debug logging
+ * - Request/response hooks
+ */
+export declare class HttpClient implements HttpClientTransport {
+    private readonly client;
+    private readonly options;
+    private readonly retryPolicy;
+    private readonly sleep;
+    private readonly random;
+    constructor(options: HttpClientOptions);
+    /**
+     * Get the current tenant ID from the SDK context.
+     * Used by RBAC clients that need tenant_id as a query parameter.
+     */
+    getTenantId(): string | undefined;
+    private setupInterceptors;
+    /**
+     * Run a request through the retry policy. Re-invoking fn() re-runs the request
+     * interceptor, so each attempt gets fresh auth/tenant headers.
+     */
+    private withRetry;
+    private reportError;
+    private transformError;
+    /**
+     * POST and return the raw streaming Response (SSE). NOT retried: the request is
+     * non-idempotent and the body may be partially consumed by the time an error surfaces.
+     */
+    stream(url: string, data?: unknown): Promise<Response>;
+    private transformStreamError;
+    get<T>(url: string, config?: AxiosRequestConfig): Promise<T>;
+    post<T>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<T>;
+    patch<T>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<T>;
+    put<T>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<T>;
+    delete<T>(url: string, config?: AxiosRequestConfig): Promise<T>;
+}
+//# sourceMappingURL=http-client.d.ts.map

package/dist/core/http-client.d.ts.map

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

package/dist/core/http-client.js

@@ -0,0 +1,293 @@
+import axios from 'axios';
+import { ZiftrError, ApiError, AuthenticationError, AuthorizationError, ConfigurationError, ValidationError, NotFoundError, ConflictError, NotModifiedError, RateLimitError, } from './errors/index.js';
+import { resolveRetryPolicy, retryDelayMs, shouldRetry, } from './retry.js';
+import { isGeoRestrictedErrorDetails } from './types/geo.js';
+/** Reject CR/LF/NUL so context values cannot smuggle extra HTTP headers. */
+function assertSafeHeaderValue(name, value) {
+    if (/[\r\n\0]/.test(value)) {
+        throw new ConfigurationError(`Invalid characters in ${name} header value (CR, LF, and NUL are not allowed)`);
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function getStringProperty(record, key) {
+    const value = record[key];
+    return typeof value === 'string' ? value : undefined;
+}
+function isFieldError(value) {
+    if (!isRecord(value))
+        return false;
+    const field = value.field;
+    const message = value.message;
+    const code = value.code;
+    return (typeof field === 'string' &&
+        typeof message === 'string' &&
+        (code === undefined || typeof code === 'string'));
+}
+function getFieldErrors(record) {
+    const errors = record?.errors;
+    if (!Array.isArray(errors))
+        return [];
+    return errors.filter(isFieldError);
+}
+/**
+ * HTTP client wrapper around axios with:
+ * - Automatic auth header injection
+ * - Tenant/store context headers
+ * - Error transformation to typed ZiftrError classes
+ * - Debug logging
+ * - Request/response hooks
+ */
+export class HttpClient {
+    client;
+    options;
+    retryPolicy;
+    sleep;
+    random;
+    constructor(options) {
+        this.options = options;
+        this.retryPolicy = resolveRetryPolicy(options.retry);
+        this.sleep = options.sleepFn ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+        this.random = options.randomFn ?? Math.random;
+        this.client = axios.create({
+            timeout: options.timeout,
+            headers: { 'Content-Type': 'application/json' },
+        });
+        this.setupInterceptors();
+    }
+    /**
+     * Get the current tenant ID from the SDK context.
+     * Used by RBAC clients that need tenant_id as a query parameter.
+     */
+    getTenantId() {
+        return this.options.getTenantId();
+    }
+    setupInterceptors() {
+        // Request interceptor - add auth and tenant headers
+        this.client.interceptors.request.use(async (config) => {
+            // Add auth headers
+            const authHeaders = await this.options.authChain.getAuthHeaders();
+            for (const [name, value] of Object.entries(authHeaders)) {
+                assertSafeHeaderValue(name, value);
+            }
+            Object.assign(config.headers, authHeaders);
+            // Add tenant context headers
+            const tenantId = this.options.getTenantId();
+            const storeId = this.options.getStoreId();
+            if (tenantId) {
+                assertSafeHeaderValue('x-tenant-id', tenantId);
+                config.headers['x-tenant-id'] = tenantId;
+            }
+            if (storeId) {
+                assertSafeHeaderValue('x-store-id', storeId);
+                config.headers['x-store-id'] = storeId;
+            }
+            // Per-call headers (e.g. withCustomer Authorization) are not always set via
+            // the auth chain; re-check after merge so CRLF cannot slip through.
+            const authorization = config.headers.Authorization ?? config.headers.authorization;
+            if (typeof authorization === 'string') {
+                assertSafeHeaderValue('Authorization', authorization);
+            }
+            // Debug logging (temporarily disabled)
+            // if (this.options.debug) {
+            //   console.log(`[ZiftrSDK] ${config.method?.toUpperCase()} ${config.url}`);
+            //   console.log(
+            //     '[ZiftrSDK] Auth header:',
+            //     config.headers.Authorization ? 'Bearer ***' : 'MISSING',
+            //   );
+            //   console.log('[ZiftrSDK] x-tenant-id:', config.headers['x-tenant-id'] || 'not set');
+            //   console.log('[ZiftrSDK] x-store-id:', config.headers['x-store-id'] || 'not set');
+            // }
+            // User hook
+            if (this.options.onRequest) {
+                const modified = await this.options.onRequest(config);
+                Object.assign(config, modified);
+                return config;
+            }
+            return config;
+        });
+        // Response interceptor - transform errors
+        this.client.interceptors.response.use(async (response) => {
+            if (this.options.onResponse) {
+                return this.options.onResponse(response);
+            }
+            return response;
+        }, async (error) => {
+            // onError fires in withRetry once retries are exhausted, not per attempt.
+            // ZiftrErrors (e.g. auth-chain failures) pass through untransformed so they
+            // keep their real statusCode instead of becoming retryable network errors.
+            if (error instanceof ZiftrError)
+                throw error;
+            if (axios.isAxiosError(error))
+                throw this.transformError(error);
+            throw error;
+        });
+    }
+    /**
+     * Run a request through the retry policy. Re-invoking fn() re-runs the request
+     * interceptor, so each attempt gets fresh auth/tenant headers.
+     */
+    async withRetry(method, fn) {
+        let attempt = 1;
+        let elapsedDelayMs = 0;
+        for (;;) {
+            try {
+                return await fn();
+            }
+            catch (error) {
+                if (!(error instanceof ZiftrError))
+                    throw error;
+                if (!shouldRetry(error, method, attempt, elapsedDelayMs, this.retryPolicy)) {
+                    await this.reportError(error);
+                    throw error;
+                }
+                const delayMs = retryDelayMs(error, attempt, this.retryPolicy, this.random);
+                if (elapsedDelayMs + delayMs > this.retryPolicy.maxTotalDelayMs) {
+                    await this.reportError(error);
+                    throw error;
+                }
+                await this.sleep(delayMs);
+                elapsedDelayMs += delayMs;
+                attempt += 1;
+            }
+        }
+    }
+    async reportError(error) {
+        if (this.options.onError) {
+            await this.options.onError(error);
+        }
+    }
+    transformError(error) {
+        const status = error.response?.status ?? 0;
+        const data = isRecord(error.response?.data) ? error.response.data : undefined;
+        const message = data ? (getStringProperty(data, 'message') ?? error.message) : error.message;
+        switch (status) {
+            case 304:
+                return new NotModifiedError(message);
+            case 400:
+                if (isGeoRestrictedErrorDetails(data)) {
+                    return new ApiError(message, 400, getStringProperty(data, 'code') ?? 'UNKNOWN', data);
+                }
+                return new ValidationError(message, getFieldErrors(data));
+            case 401:
+                return new AuthenticationError(message);
+            case 403:
+                return new AuthorizationError(message);
+            case 404:
+                return new NotFoundError(message);
+            case 409:
+                return new ConflictError(message);
+            case 429: {
+                const retryAfterHeader = error.response?.headers?.['retry-after'];
+                const retryAfter = parseInt(typeof retryAfterHeader === 'string' ? retryAfterHeader : '60', 10);
+                return new RateLimitError(message, retryAfter);
+            }
+            default:
+                return new ApiError(message, status, data ? (getStringProperty(data, 'code') ?? 'UNKNOWN') : 'UNKNOWN', data);
+        }
+    }
+    // ==================== Streaming ====================
+    /**
+     * POST and return the raw streaming Response (SSE). NOT retried: the request is
+     * non-idempotent and the body may be partially consumed by the time an error surfaces.
+     */
+    async stream(url, data) {
+        const authHeaders = await this.options.authChain.getAuthHeaders();
+        for (const [name, value] of Object.entries(authHeaders)) {
+            assertSafeHeaderValue(name, value);
+        }
+        const tenantId = this.options.getTenantId();
+        const storeId = this.options.getStoreId();
+        const headers = {
+            'Content-Type': 'application/json',
+            ...authHeaders,
+        };
+        if (tenantId) {
+            assertSafeHeaderValue('x-tenant-id', tenantId);
+            headers['x-tenant-id'] = tenantId;
+        }
+        if (storeId) {
+            assertSafeHeaderValue('x-store-id', storeId);
+            headers['x-store-id'] = storeId;
+        }
+        const response = await fetch(url, {
+            method: 'POST',
+            headers,
+            body: data ? JSON.stringify(data) : undefined,
+        });
+        if (!response.ok) {
+            throw await this.transformStreamError(response);
+        }
+        return response;
+    }
+    async transformStreamError(response) {
+        let data;
+        try {
+            const json = await response.json();
+            if (isRecord(json))
+                data = json;
+        }
+        catch {
+            /* ignore parse errors */
+        }
+        const message = data
+            ? (getStringProperty(data, 'message') ?? response.statusText)
+            : response.statusText;
+        switch (response.status) {
+            case 304:
+                return new NotModifiedError(message);
+            case 400:
+                if (isGeoRestrictedErrorDetails(data)) {
+                    return new ApiError(message, 400, data ? (getStringProperty(data, 'code') ?? 'UNKNOWN') : 'UNKNOWN', data);
+                }
+                return new ValidationError(message, getFieldErrors(data));
+            case 401:
+                return new AuthenticationError(message);
+            case 403:
+                return new AuthorizationError(message);
+            case 404:
+                return new NotFoundError(message);
+            case 409:
+                return new ConflictError(message);
+            case 429: {
+                const retryAfter = parseInt(response.headers.get('retry-after') ?? '60', 10);
+                return new RateLimitError(message, retryAfter);
+            }
+            default:
+                return new ApiError(message, response.status, data ? (getStringProperty(data, 'code') ?? 'UNKNOWN') : 'UNKNOWN', data);
+        }
+    }
+    // ==================== HTTP Methods ====================
+    async get(url, config) {
+        return this.withRetry('GET', async () => {
+            const response = await this.client.get(url, config);
+            return response.data;
+        });
+    }
+    async post(url, data, config) {
+        return this.withRetry('POST', async () => {
+            const response = await this.client.post(url, data, config);
+            return response.data;
+        });
+    }
+    async patch(url, data, config) {
+        return this.withRetry('PATCH', async () => {
+            const response = await this.client.patch(url, data, config);
+            return response.data;
+        });
+    }
+    async put(url, data, config) {
+        return this.withRetry('PUT', async () => {
+            const response = await this.client.put(url, data, config);
+            return response.data;
+        });
+    }
+    async delete(url, config) {
+        return this.withRetry('DELETE', async () => {
+            const response = await this.client.delete(url, config);
+            return response.data;
+        });
+    }
+}
+//# sourceMappingURL=http-client.js.map

package/dist/core/http-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-client.js","sourceRoot":"","sources":["../../../../src/core/http-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAKN,MAAM,OAAO,CAAC;AAEf,OAAO,EACL,UAAU,EACV,QAAQ,EACR,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,eAAe,EACf,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,cAAc,GAEf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAGL,kBAAkB,EAClB,YAAY,EACZ,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,2BAA2B,EAAE,MAAM,gBAAgB,CAAC;AAE7D,4EAA4E;AAC5E,SAAS,qBAAqB,CAAC,IAAY,EAAE,KAAa;IACxD,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,kBAAkB,CAC1B,yBAAyB,IAAI,iDAAiD,CAC/E,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,iBAAiB,CAAC,MAA+B,EAAE,GAAW;IACrE,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1B,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACvD,CAAC;AAED,SAAS,YAAY,CAAC,KAAc;IAClC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACnC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IAC1B,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC9B,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;IACxB,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,OAAO,OAAO,KAAK,QAAQ;QAC3B,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,IAAI,KAAK,QAAQ,CAAC,CACjD,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CAAC,MAA2C;IACjE,MAAM,MAAM,GAAG,MAAM,EAAE,MAAM,CAAC;IAC9B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,EAAE,CAAC;IACtC,OAAO,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;AACrC,CAAC;AA+CD;;;;;;;GAOG;AACH,MAAM,OAAO,UAAU;IACJ,MAAM,CAAgB;IACtB,OAAO,CAAoB;IAC3B,WAAW,CAAsB;IACjC,KAAK,CAAgC;IACrC,MAAM,CAAe;IAEtC,YAAY,OAA0B;QACpC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,WAAW,GAAG,kBAAkB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACrD,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,OAAO,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;QAC5F,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAC,MAAM,CAAC;QAC9C,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;YACzB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;SAChD,CAAC,CAAC;QACH,IAAI,CAAC,iBAAiB,EAAE,CAAC;IAC3B,CAAC;IAED;;;OAGG;IACH,WAAW;QACT,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;IACpC,CAAC;IAEO,iBAAiB;QACvB,oDAAoD;QACpD,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,MAAkC,EAAE,EAAE;YAChF,mBAAmB;YACnB,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,cAAc,EAAE,CAAC;YAClE,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC;gBACxD,qBAAqB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YACrC,CAAC;YACD,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;YAE3C,6BAA6B;YAC7B,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;YAC5C,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;YAC1C,IAAI,QAAQ,EAAE,CAAC;gBACb,qBAAqB,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;gBAC/C,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,GAAG,QAAQ,CAAC;YAC3C,CAAC;YACD,IAAI,OAAO,EAAE,CAAC;gBACZ,qBAAqB,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;gBAC7C,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,GAAG,OAAO,CAAC;YACzC,CAAC;YAED,4EAA4E;YAC5E,oEAAoE;YACpE,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,CAAC,aAAa,IAAI,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC;YACnF,IAAI,OAAO,aAAa,KAAK,QAAQ,EAAE,CAAC;gBACtC,qBAAqB,CAAC,eAAe,EAAE,aAAa,CAAC,CAAC;YACxD,CAAC;YAED,uCAAuC;YACvC,4BAA4B;YAC5B,6EAA6E;YAC7E,iBAAiB;YACjB,iCAAiC;YACjC,+DAA+D;YAC/D,OAAO;YACP,wFAAwF;YACxF,sFAAsF;YACtF,IAAI;YAEJ,YAAY;YACZ,IAAI,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;gBAC3B,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;gBACtD,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;gBAChC,OAAO,MAAM,CAAC;YAChB,CAAC;YAED,OAAO,MAAM,CAAC;QAChB,CAAC,CAAC,CAAC;QAEH,0CAA0C;QAC1C,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAC,GAAG,CACnC,KAAK,EAAE,QAAQ,EAAE,EAAE;YACjB,IAAI,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;gBAC5B,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;YAC3C,CAAC;YACD,OAAO,QAAQ,CAAC;QAClB,CAAC,EACD,KAAK,EAAE,KAAc,EAAE,EAAE;YACvB,0EAA0E;YAC1E,4EAA4E;YAC5E,2EAA2E;YAC3E,IAAI,KAAK,YAAY,UAAU;gBAAE,MAAM,KAAK,CAAC;YAC7C,IAAI,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC;gBAAE,MAAM,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;YAChE,MAAM,KAAK,CAAC;QACd,CAAC,CACF,CAAC;IACJ,CAAC;IAED;;;OAGG;IACK,KAAK,CAAC,SAAS,CAAI,MAAc,EAAE,EAAoB;QAC7D,IAAI,OAAO,GAAG,CAAC,CAAC;QAChB,IAAI,cAAc,GAAG,CAAC,CAAC;QACvB,SAAS,CAAC;YACR,IAAI,CAAC;gBACH,OAAO,MAAM,EAAE,EAAE,CAAC;YACpB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,CAAC,CAAC,KAAK,YAAY,UAAU,CAAC;oBAAE,MAAM,KAAK,CAAC;gBAChD,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;oBAC3E,MAAM,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;oBAC9B,MAAM,KAAK,CAAC;gBACd,CAAC;gBACD,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;gBAC5E,IAAI,cAAc,GAAG,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,eAAe,EAAE,CAAC;oBAChE,MAAM,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;oBAC9B,MAAM,KAAK,CAAC;gBACd,CAAC;gBACD,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;gBAC1B,cAAc,IAAI,OAAO,CAAC;gBAC1B,OAAO,IAAI,CAAC,CAAC;YACf,CAAC;QACH,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,WAAW,CAAC,KAAiB;QACzC,IAAI,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;YACzB,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;IAEO,cAAc,CAAC,KAAiB;QACtC,MAAM,MAAM,GAAG,KAAK,CAAC,QAAQ,EAAE,MAAM,IAAI,CAAC,CAAC;QAC3C,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;QAC9E,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC;QAE7F,QAAQ,MAAM,EAAE,CAAC;YACf,KAAK,GAAG;gBACN,OAAO,IAAI,gBAAgB,CAAC,OAAO,CAAC,CAAC;YACvC,KAAK,GAAG;gBACN,IAAI,2BAA2B,CAAC,IAAI,CAAC,EAAE,CAAC;oBACtC,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,GAAG,EAAE,iBAAiB,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,SAAS,EAAE,IAAI,CAAC,CAAC;gBACxF,CAAC;gBACD,OAAO,IAAI,eAAe,CAAC,OAAO,EAAE,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC;YAC5D,KAAK,GAAG;gBACN,OAAO,IAAI,mBAAmB,CAAC,OAAO,CAAC,CAAC;YAC1C,KAAK,GAAG;gBACN,OAAO,IAAI,kBAAkB,CAAC,OAAO,CAAC,CAAC;YACzC,KAAK,GAAG;gBACN,OAAO,IAAI,aAAa,CAAC,OAAO,CAAC,CAAC;YACpC,KAAK,GAAG;gBACN,OAAO,IAAI,aAAa,CAAC,OAAO,CAAC,CAAC;YACpC,KAAK,GAAG,CAAC,CAAC,CAAC;gBACT,MAAM,gBAAgB,GAAG,KAAK,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAC,aAAa,CAAC,CAAC;gBAClE,MAAM,UAAU,GAAG,QAAQ,CACzB,OAAO,gBAAgB,KAAK,QAAQ,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,IAAI,EAC9D,EAAE,CACH,CAAC;gBACF,OAAO,IAAI,cAAc,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;YACjD,CAAC;YACD;gBACE,OAAO,IAAI,QAAQ,CACjB,OAAO,EACP,MAAM,EACN,IAAI,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,EACjE,IAAI,CACL,CAAC;QACN,CAAC;IACH,CAAC;IAED,sDAAsD;IAEtD;;;OAGG;IACH,KAAK,CAAC,MAAM,CAAC,GAAW,EAAE,IAAc;QACtC,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,cAAc,EAAE,CAAC;QAClE,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC;YACxD,qBAAqB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACrC,CAAC;QACD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;QAC5C,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;QAE1C,MAAM,OAAO,GAA2B;YACtC,cAAc,EAAE,kBAAkB;YAClC,GAAG,WAAW;SACf,CAAC;QACF,IAAI,QAAQ,EAAE,CAAC;YACb,qBAAqB,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;YAC/C,OAAO,CAAC,aAAa,CAAC,GAAG,QAAQ,CAAC;QACpC,CAAC;QACD,IAAI,OAAO,EAAE,CAAC;YACZ,qBAAqB,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;YAC7C,OAAO,CAAC,YAAY,CAAC,GAAG,OAAO,CAAC;QAClC,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAChC,MAAM,EAAE,MAAM;YACd,OAAO;YACP,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;SAC9C,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,MAAM,IAAI,CAAC,oBAAoB,CAAC,QAAQ,CAAC,CAAC;QAClD,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;IAEO,KAAK,CAAC,oBAAoB,CAAC,QAAkB;QACnD,IAAI,IAAyC,CAAC;QAC9C,IAAI,CAAC;YACH,MAAM,IAAI,GAAY,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YAC5C,IAAI,QAAQ,CAAC,IAAI,CAAC;gBAAE,IAAI,GAAG,IAAI,CAAC;QAClC,CAAC;QAAC,MAAM,CAAC;YACP,yBAAyB;QAC3B,CAAC;QAED,MAAM,OAAO,GAAG,IAAI;YAClB,CAAC,CAAC,CAAC,iBAAiB,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,QAAQ,CAAC,UAAU,CAAC;YAC7D,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC;QAExB,QAAQ,QAAQ,CAAC,MAAM,EAAE,CAAC;YACxB,KAAK,GAAG;gBACN,OAAO,IAAI,gBAAgB,CAAC,OAAO,CAAC,CAAC;YACvC,KAAK,GAAG;gBACN,IAAI,2BAA2B,CAAC,IAAI,CAAC,EAAE,CAAC;oBACtC,OAAO,IAAI,QAAQ,CACjB,OAAO,EACP,GAAG,EACH,IAAI,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,EACjE,IAAI,CACL,CAAC;gBACJ,CAAC;gBACD,OAAO,IAAI,eAAe,CAAC,OAAO,EAAE,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC;YAC5D,KAAK,GAAG;gBACN,OAAO,IAAI,mBAAmB,CAAC,OAAO,CAAC,CAAC;YAC1C,KAAK,GAAG;gBACN,OAAO,IAAI,kBAAkB,CAAC,OAAO,CAAC,CAAC;YACzC,KAAK,GAAG;gBACN,OAAO,IAAI,aAAa,CAAC,OAAO,CAAC,CAAC;YACpC,KAAK,GAAG;gBACN,OAAO,IAAI,aAAa,CAAC,OAAO,CAAC,CAAC;YACpC,KAAK,GAAG,CAAC,CAAC,CAAC;gBACT,MAAM,UAAU,GAAG,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC,CAAC;gBAC7E,OAAO,IAAI,cAAc,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;YACjD,CAAC;YACD;gBACE,OAAO,IAAI,QAAQ,CACjB,OAAO,EACP,QAAQ,CAAC,MAAM,EACf,IAAI,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,EACjE,IAAI,CACL,CAAC;QACN,CAAC;IACH,CAAC;IAED,yDAAyD;IAEzD,KAAK,CAAC,GAAG,CAAI,GAAW,EAAE,MAA2B;QACnD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,KAAK,IAAI,EAAE;YACtC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAI,GAAG,EAAE,MAAM,CAAC,CAAC;YACvD,OAAO,QAAQ,CAAC,IAAI,CAAC;QACvB,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,IAAI,CAAI,GAAW,EAAE,IAAc,EAAE,MAA2B;QACpE,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,KAAK,IAAI,EAAE;YACvC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAI,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;YAC9D,OAAO,QAAQ,CAAC,IAAI,CAAC;QACvB,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,KAAK,CAAI,GAAW,EAAE,IAAc,EAAE,MAA2B;QACrE,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE;YACxC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAI,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;YAC/D,OAAO,QAAQ,CAAC,IAAI,CAAC;QACvB,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,GAAG,CAAI,GAAW,EAAE,IAAc,EAAE,MAA2B;QACnE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,KAAK,IAAI,EAAE;YACtC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAI,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;YAC7D,OAAO,QAAQ,CAAC,IAAI,CAAC;QACvB,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,MAAM,CAAI,GAAW,EAAE,MAA2B;QACtD,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;YACzC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAI,GAAG,EAAE,MAAM,CAAC,CAAC;YAC1D,OAAO,QAAQ,CAAC,IAAI,CAAC;QACvB,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/core/retry.d.ts

@@ -0,0 +1,48 @@
+import { type ZiftrError } from './errors/index.js';
+/**
+ * Options for automatic retry of failed requests.
+ *
+ * Retries are ON by default. Policy:
+ * - 429 (rate limit) is retried for ALL methods, honoring the server's retry-after.
+ * - Idempotent requests (GET/HEAD) are additionally retried on the configured
+ *   statuses (default 502/503/504) and on network errors (no response).
+ * - Waits use full-jitter exponential backoff, capped per-wait by maxDelayMs and
+ *   across the whole request by maxTotalDelayMs.
+ *
+ * Disable with `retry: { enabled: false }`.
+ */
+export interface RetryOptions {
+    /** Enable automatic retries. Default: true */
+    enabled?: boolean;
+    /** Maximum attempts including the initial request. Default: 3 */
+    maxAttempts?: number;
+    /** Base delay for exponential backoff in milliseconds. Default: 300 */
+    baseDelayMs?: number;
+    /** Cap for a single backoff wait in milliseconds (also caps honored retry-after). Default: 10000 */
+    maxDelayMs?: number;
+    /** Total wait budget across all retries in milliseconds; retrying stops once exceeded. Default: 30000 */
+    maxTotalDelayMs?: number;
+    /** Statuses retried for idempotent (GET/HEAD) requests. 429 is always retried for all methods. Default: [429, 502, 503, 504] */
+    retryStatuses?: number[];
+}
+export type ResolvedRetryPolicy = Required<RetryOptions>;
+export declare const DEFAULT_RETRY_POLICY: ResolvedRetryPolicy;
+export declare function resolveRetryPolicy(options?: RetryOptions): ResolvedRetryPolicy;
+/**
+ * Decide whether a failed attempt is eligible for another try.
+ *
+ * @param attempt 1-based attempt number that just failed
+ * @param elapsedDelayMs total time already spent waiting between attempts
+ */
+export declare function shouldRetry(error: ZiftrError, method: string, attempt: number, elapsedDelayMs: number, policy: ResolvedRetryPolicy): boolean;
+/**
+ * Compute the wait before the next attempt: full-jitter exponential backoff,
+ * raised to the server's retry-after for rate limits, capped at maxDelayMs.
+ * (transformError defaults retry-after to 60s when the header is absent, so the
+ * cap is what keeps a missing header from stalling every attempt for a minute.)
+ *
+ * @param attempt 1-based attempt number that just failed
+ * @param random source of randomness in [0, 1); injectable for deterministic tests
+ */
+export declare function retryDelayMs(error: ZiftrError, attempt: number, policy: ResolvedRetryPolicy, random: () => number): number;
+//# sourceMappingURL=retry.d.ts.map

package/dist/core/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../../../src/core/retry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsC,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAExF;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oGAAoG;IACpG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yGAAyG;IACzG,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gIAAgI;IAChI,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC,YAAY,CAAC,CAAC;AAEzD,eAAO,MAAM,oBAAoB,EAAE,mBAOlC,CAAC;AAEF,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,mBAAmB,CAE9E;AAOD;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAiBT;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,mBAAmB,EAC3B,MAAM,EAAE,MAAM,MAAM,GACnB,MAAM,CASR"}

package/dist/core/retry.js

@@ -0,0 +1,57 @@
+import { ConfigurationError, RateLimitError } from './errors/index.js';
+export const DEFAULT_RETRY_POLICY = {
+    enabled: true,
+    maxAttempts: 3,
+    baseDelayMs: 300,
+    maxDelayMs: 10_000,
+    maxTotalDelayMs: 30_000,
+    retryStatuses: [429, 502, 503, 504],
+};
+export function resolveRetryPolicy(options) {
+    return { ...DEFAULT_RETRY_POLICY, ...options };
+}
+const IDEMPOTENT_METHODS = new Set(['GET', 'HEAD']);
+/** statusCode 0 means the request never got a response (network error / timeout) */
+const NETWORK_ERROR_STATUS = 0;
+/**
+ * Decide whether a failed attempt is eligible for another try.
+ *
+ * @param attempt 1-based attempt number that just failed
+ * @param elapsedDelayMs total time already spent waiting between attempts
+ */
+export function shouldRetry(error, method, attempt, elapsedDelayMs, policy) {
+    if (!policy.enabled)
+        return false;
+    if (attempt >= policy.maxAttempts)
+        return false;
+    if (elapsedDelayMs >= policy.maxTotalDelayMs)
+        return false;
+    // Permanent client-side config failures (e.g. header injection guards) share
+    // statusCode 0 with network errors; never retry them.
+    if (error instanceof ConfigurationError)
+        return false;
+    // Rate limits are safe to retry regardless of method: the server did not process the request.
+    if (error instanceof RateLimitError)
+        return true;
+    if (!IDEMPOTENT_METHODS.has(method.toUpperCase()))
+        return false;
+    return (error.statusCode === NETWORK_ERROR_STATUS || policy.retryStatuses.includes(error.statusCode));
+}
+/**
+ * Compute the wait before the next attempt: full-jitter exponential backoff,
+ * raised to the server's retry-after for rate limits, capped at maxDelayMs.
+ * (transformError defaults retry-after to 60s when the header is absent, so the
+ * cap is what keeps a missing header from stalling every attempt for a minute.)
+ *
+ * @param attempt 1-based attempt number that just failed
+ * @param random source of randomness in [0, 1); injectable for deterministic tests
+ */
+export function retryDelayMs(error, attempt, policy, random) {
+    const ceiling = Math.min(policy.maxDelayMs, policy.baseDelayMs * 2 ** (attempt - 1));
+    const backoff = random() * ceiling;
+    if (error instanceof RateLimitError) {
+        return Math.min(Math.max(error.retryAfter * 1000, backoff), policy.maxDelayMs);
+    }
+    return backoff;
+}
+//# sourceMappingURL=retry.js.map

package/dist/core/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../../../src/core/retry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAmB,MAAM,mBAAmB,CAAC;AA+BxF,MAAM,CAAC,MAAM,oBAAoB,GAAwB;IACvD,OAAO,EAAE,IAAI;IACb,WAAW,EAAE,CAAC;IACd,WAAW,EAAE,GAAG;IAChB,UAAU,EAAE,MAAM;IAClB,eAAe,EAAE,MAAM;IACvB,aAAa,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC;CACpC,CAAC;AAEF,MAAM,UAAU,kBAAkB,CAAC,OAAsB;IACvD,OAAO,EAAE,GAAG,oBAAoB,EAAE,GAAG,OAAO,EAAE,CAAC;AACjD,CAAC;AAED,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;AAEpD,oFAAoF;AACpF,MAAM,oBAAoB,GAAG,CAAC,CAAC;AAE/B;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CACzB,KAAiB,EACjB,MAAc,EACd,OAAe,EACf,cAAsB,EACtB,MAA2B;IAE3B,IAAI,CAAC,MAAM,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAClC,IAAI,OAAO,IAAI,MAAM,CAAC,WAAW;QAAE,OAAO,KAAK,CAAC;IAChD,IAAI,cAAc,IAAI,MAAM,CAAC,eAAe;QAAE,OAAO,KAAK,CAAC;IAE3D,6EAA6E;IAC7E,sDAAsD;IACtD,IAAI,KAAK,YAAY,kBAAkB;QAAE,OAAO,KAAK,CAAC;IAEtD,8FAA8F;IAC9F,IAAI,KAAK,YAAY,cAAc;QAAE,OAAO,IAAI,CAAC;IAEjD,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;QAAE,OAAO,KAAK,CAAC;IAEhE,OAAO,CACL,KAAK,CAAC,UAAU,KAAK,oBAAoB,IAAI,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,KAAK,CAAC,UAAU,CAAC,CAC7F,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAiB,EACjB,OAAe,EACf,MAA2B,EAC3B,MAAoB;IAEpB,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,WAAW,GAAG,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC;IACrF,MAAM,OAAO,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC;IAEnC,IAAI,KAAK,YAAY,cAAc,EAAE,CAAC;QACpC,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,GAAG,IAAI,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IACjF,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}