@markwharton/pwa-core 3.3.0 → 3.4.0

package/dist/client.d.ts

@@ -23,6 +23,15 @@ export interface ApiClientConfig {
     /** Optional request timeout in milliseconds (default: 30000) */
     timeout?: number;
 }
+/**
+ * Configuration for initSessionApiClient
+ */
+export interface SessionApiClientConfig {
+    /** Optional callback for 401 responses (e.g., redirect to login) */
+    onUnauthenticated?: () => void;
+    /** Optional request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
 /**
  * Custom error class for API errors.
  * Preserves HTTP status code and error message from the server.
@@ -189,3 +198,110 @@ export declare function apiCallVoid(url: string, options?: RequestInit): Promise
  * }
  */
 export declare function apiCallSafe<T>(url: string, options?: RequestInit): Promise<ApiResponse<T>>;
+/**
+ * Initializes the session-based API client.
+ * Uses cookies (credentials: 'include') instead of Bearer tokens.
+ * @param config - Client configuration
+ * @example
+ * initSessionApiClient({
+ *   onUnauthenticated: () => window.location.href = '/login',
+ *   timeout: 60000
+ * });
+ */
+export declare function initSessionApiClient(config: SessionApiClientConfig): void;
+/**
+ * Makes a cookie-authenticated API call. Throws ApiError on non-2xx responses.
+ * Uses credentials: 'include' to send session cookies.
+ * @typeParam T - The expected response data type
+ * @param url - The API endpoint URL
+ * @param options - Optional fetch options (method, body, headers)
+ * @returns The parsed JSON response
+ * @throws ApiError on non-2xx HTTP status or timeout
+ * @example
+ * const user = await sessionApiCall<User>('/api/auth/me');
+ */
+export declare function sessionApiCall<T>(url: string, options?: RequestInit): Promise<T>;
+/**
+ * Makes a cookie-authenticated GET request.
+ * @typeParam T - The expected response data type
+ * @param url - The API endpoint URL
+ * @returns The parsed JSON response
+ * @throws ApiError on non-2xx HTTP status
+ */
+export declare function sessionApiGet<T>(url: string): Promise<T>;
+/**
+ * Makes a cookie-authenticated POST request.
+ * @typeParam T - The expected response data type
+ * @param url - The API endpoint URL
+ * @param body - Optional request body (will be JSON stringified)
+ * @returns The parsed JSON response
+ * @throws ApiError on non-2xx HTTP status
+ */
+export declare function sessionApiPost<T>(url: string, body?: unknown): Promise<T>;
+/**
+ * Makes a cookie-authenticated PUT request.
+ * @typeParam T - The expected response data type
+ * @param url - The API endpoint URL
+ * @param body - Optional request body (will be JSON stringified)
+ * @returns The parsed JSON response
+ * @throws ApiError on non-2xx HTTP status
+ */
+export declare function sessionApiPut<T>(url: string, body?: unknown): Promise<T>;
+/**
+ * Makes a cookie-authenticated PATCH request.
+ * @typeParam T - The expected response data type
+ * @param url - The API endpoint URL
+ * @param body - Optional request body (will be JSON stringified)
+ * @returns The parsed JSON response
+ * @throws ApiError on non-2xx HTTP status
+ */
+export declare function sessionApiPatch<T>(url: string, body?: unknown): Promise<T>;
+/**
+ * Makes a cookie-authenticated DELETE request.
+ * @typeParam T - The expected response data type
+ * @param url - The API endpoint URL
+ * @returns The parsed JSON response
+ * @throws ApiError on non-2xx HTTP status
+ */
+export declare function sessionApiDelete<T>(url: string): Promise<T>;
+/**
+ * Makes a cookie-authenticated API call with Result-style error handling.
+ * Unlike sessionApiCall, this never throws - errors are returned in the response.
+ * @typeParam T - The expected response data type
+ * @param url - The API endpoint URL
+ * @param options - Optional fetch options (method, body, headers)
+ * @returns ApiResponse with ok, status, data (on success), or error (on failure)
+ */
+export declare function sessionApiCallSafe<T>(url: string, options?: RequestInit): Promise<ApiResponse<T>>;
+/**
+ * Makes a cookie-authenticated API call expecting no response body.
+ * @param url - The API endpoint URL
+ * @param options - Optional fetch options (method, body, headers)
+ * @throws ApiError on non-2xx HTTP status or timeout
+ */
+export declare function sessionApiCallVoid(url: string, options?: RequestInit): Promise<void>;
+/**
+ * Checks if an HTTP status code indicates a retryable error.
+ * @param status - The HTTP status code (or undefined for network errors)
+ * @returns True for 408, 425, 429, 5xx, or undefined (network error)
+ * @example
+ * if (isRetryableStatus(error.status)) { retry(); }
+ */
+export declare function isRetryableStatus(status: number | undefined): boolean;
+/**
+ * Makes a cookie-authenticated API call with exponential backoff retry.
+ * Retries on retryable status codes (408, 425, 429, 5xx, network errors).
+ * @typeParam T - The expected response data type
+ * @param url - The API endpoint URL
+ * @param options - Optional fetch options
+ * @param maxRetries - Maximum number of retries (default: 3)
+ * @param initialDelayMs - Initial retry delay in ms (default: 1000)
+ * @returns The parsed JSON response
+ * @throws ApiError if all retries fail
+ * @example
+ * const result = await sessionApiCallWithRetry<AuthResponse>('/api/auth/verify', {
+ *   method: 'POST',
+ *   body: JSON.stringify({ token })
+ * });
+ */
+export declare function sessionApiCallWithRetry<T>(url: string, options?: RequestInit, maxRetries?: number, initialDelayMs?: number): Promise<T>;

package/dist/client.js

@@ -16,6 +16,17 @@ exports.apiPatch = apiPatch;
 exports.apiDelete = apiDelete;
 exports.apiCallVoid = apiCallVoid;
 exports.apiCallSafe = apiCallSafe;
+exports.initSessionApiClient = initSessionApiClient;
+exports.sessionApiCall = sessionApiCall;
+exports.sessionApiGet = sessionApiGet;
+exports.sessionApiPost = sessionApiPost;
+exports.sessionApiPut = sessionApiPut;
+exports.sessionApiPatch = sessionApiPatch;
+exports.sessionApiDelete = sessionApiDelete;
+exports.sessionApiCallSafe = sessionApiCallSafe;
+exports.sessionApiCallVoid = sessionApiCallVoid;
+exports.isRetryableStatus = isRetryableStatus;
+exports.sessionApiCallWithRetry = sessionApiCallWithRetry;
 // =============================================================================
 // ApiError Class
 // =============================================================================
@@ -360,3 +371,262 @@ async function apiCallSafe(url, options = {}) {
         clearTimeout(timeoutId);
     }
 }
+// =============================================================================
+// Session API Client (cookie-based auth)
+// =============================================================================
+// Session API client state
+let sessionOnUnauthenticated = null;
+let sessionRequestTimeout = 30000;
+/**
+ * Initializes the session-based API client.
+ * Uses cookies (credentials: 'include') instead of Bearer tokens.
+ * @param config - Client configuration
+ * @example
+ * initSessionApiClient({
+ *   onUnauthenticated: () => window.location.href = '/login',
+ *   timeout: 60000
+ * });
+ */
+function initSessionApiClient(config) {
+    sessionOnUnauthenticated = config.onUnauthenticated ?? null;
+    sessionRequestTimeout = config.timeout ?? 30000;
+}
+/** Handle 401 unauthenticated callback for session API */
+function handleUnauthenticated(status) {
+    if (status === 401 && sessionOnUnauthenticated) {
+        sessionOnUnauthenticated();
+    }
+}
+/**
+ * Makes a cookie-authenticated API call. Throws ApiError on non-2xx responses.
+ * Uses credentials: 'include' to send session cookies.
+ * @typeParam T - The expected response data type
+ * @param url - The API endpoint URL
+ * @param options - Optional fetch options (method, body, headers)
+ * @returns The parsed JSON response
+ * @throws ApiError on non-2xx HTTP status or timeout
+ * @example
+ * const user = await sessionApiCall<User>('/api/auth/me');
+ */
+async function sessionApiCall(url, options = {}) {
+    const headers = {
+        'Content-Type': 'application/json',
+        ...options.headers
+    };
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), sessionRequestTimeout);
+    try {
+        const response = await fetch(url, {
+            ...options,
+            headers,
+            credentials: 'include',
+            signal: controller.signal
+        });
+        if (!response.ok) {
+            handleUnauthenticated(response.status);
+            const errorMessage = await extractErrorMessage(response);
+            throw new ApiError(response.status, errorMessage);
+        }
+        const text = await response.text();
+        if (!text) {
+            throw new ApiError(response.status, 'Empty response body');
+        }
+        return JSON.parse(text);
+    }
+    catch (error) {
+        handleApiError(error);
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+/**
+ * Makes a cookie-authenticated GET request.
+ * @typeParam T - The expected response data type
+ * @param url - The API endpoint URL
+ * @returns The parsed JSON response
+ * @throws ApiError on non-2xx HTTP status
+ */
+async function sessionApiGet(url) {
+    return sessionApiCall(url, { method: 'GET' });
+}
+/**
+ * Makes a cookie-authenticated POST request.
+ * @typeParam T - The expected response data type
+ * @param url - The API endpoint URL
+ * @param body - Optional request body (will be JSON stringified)
+ * @returns The parsed JSON response
+ * @throws ApiError on non-2xx HTTP status
+ */
+async function sessionApiPost(url, body) {
+    return sessionApiCall(url, {
+        method: 'POST',
+        body: body ? JSON.stringify(body) : undefined
+    });
+}
+/**
+ * Makes a cookie-authenticated PUT request.
+ * @typeParam T - The expected response data type
+ * @param url - The API endpoint URL
+ * @param body - Optional request body (will be JSON stringified)
+ * @returns The parsed JSON response
+ * @throws ApiError on non-2xx HTTP status
+ */
+async function sessionApiPut(url, body) {
+    return sessionApiCall(url, {
+        method: 'PUT',
+        body: body ? JSON.stringify(body) : undefined
+    });
+}
+/**
+ * Makes a cookie-authenticated PATCH request.
+ * @typeParam T - The expected response data type
+ * @param url - The API endpoint URL
+ * @param body - Optional request body (will be JSON stringified)
+ * @returns The parsed JSON response
+ * @throws ApiError on non-2xx HTTP status
+ */
+async function sessionApiPatch(url, body) {
+    return sessionApiCall(url, {
+        method: 'PATCH',
+        body: body ? JSON.stringify(body) : undefined
+    });
+}
+/**
+ * Makes a cookie-authenticated DELETE request.
+ * @typeParam T - The expected response data type
+ * @param url - The API endpoint URL
+ * @returns The parsed JSON response
+ * @throws ApiError on non-2xx HTTP status
+ */
+async function sessionApiDelete(url) {
+    return sessionApiCall(url, { method: 'DELETE' });
+}
+/**
+ * Makes a cookie-authenticated API call with Result-style error handling.
+ * Unlike sessionApiCall, this never throws - errors are returned in the response.
+ * @typeParam T - The expected response data type
+ * @param url - The API endpoint URL
+ * @param options - Optional fetch options (method, body, headers)
+ * @returns ApiResponse with ok, status, data (on success), or error (on failure)
+ */
+async function sessionApiCallSafe(url, options = {}) {
+    const headers = {
+        'Content-Type': 'application/json',
+        ...options.headers
+    };
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), sessionRequestTimeout);
+    try {
+        const response = await fetch(url, {
+            ...options,
+            headers,
+            credentials: 'include',
+            signal: controller.signal
+        });
+        if (!response.ok) {
+            handleUnauthenticated(response.status);
+            const errorMessage = await extractErrorMessage(response);
+            return { ok: false, status: response.status, error: errorMessage };
+        }
+        const text = await response.text();
+        const data = text ? JSON.parse(text) : undefined;
+        return { ok: true, status: response.status, data };
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'AbortError') {
+            return { ok: false, status: 0, error: 'Request timeout' };
+        }
+        return { ok: false, status: 0, error: 'Network error' };
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+/**
+ * Makes a cookie-authenticated API call expecting no response body.
+ * @param url - The API endpoint URL
+ * @param options - Optional fetch options (method, body, headers)
+ * @throws ApiError on non-2xx HTTP status or timeout
+ */
+async function sessionApiCallVoid(url, options = {}) {
+    const headers = {
+        'Content-Type': 'application/json',
+        ...options.headers
+    };
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), sessionRequestTimeout);
+    try {
+        const response = await fetch(url, {
+            ...options,
+            headers,
+            credentials: 'include',
+            signal: controller.signal
+        });
+        if (!response.ok) {
+            handleUnauthenticated(response.status);
+            const errorMessage = await extractErrorMessage(response);
+            throw new ApiError(response.status, errorMessage);
+        }
+    }
+    catch (error) {
+        handleApiError(error);
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+// =============================================================================
+// Retryable Request Helper
+// =============================================================================
+/**
+ * Checks if an HTTP status code indicates a retryable error.
+ * @param status - The HTTP status code (or undefined for network errors)
+ * @returns True for 408, 425, 429, 5xx, or undefined (network error)
+ * @example
+ * if (isRetryableStatus(error.status)) { retry(); }
+ */
+function isRetryableStatus(status) {
+    if (status === undefined)
+        return true; // Network error
+    if (status === 408 || status === 425 || status === 429)
+        return true;
+    if (status >= 500)
+        return true;
+    return false;
+}
+/**
+ * Makes a cookie-authenticated API call with exponential backoff retry.
+ * Retries on retryable status codes (408, 425, 429, 5xx, network errors).
+ * @typeParam T - The expected response data type
+ * @param url - The API endpoint URL
+ * @param options - Optional fetch options
+ * @param maxRetries - Maximum number of retries (default: 3)
+ * @param initialDelayMs - Initial retry delay in ms (default: 1000)
+ * @returns The parsed JSON response
+ * @throws ApiError if all retries fail
+ * @example
+ * const result = await sessionApiCallWithRetry<AuthResponse>('/api/auth/verify', {
+ *   method: 'POST',
+ *   body: JSON.stringify({ token })
+ * });
+ */
+async function sessionApiCallWithRetry(url, options, maxRetries = 3, initialDelayMs = 1000) {
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await sessionApiCall(url, options);
+        }
+        catch (error) {
+            lastError = error;
+            const status = error instanceof ApiError ? error.status : undefined;
+            if (!isRetryableStatus(status) || attempt === maxRetries) {
+                throw error;
+            }
+            // Exponential backoff
+            const delay = initialDelayMs * Math.pow(2, attempt);
+            await new Promise(resolve => setTimeout(resolve, delay));
+        }
+    }
+    throw lastError;
+}