@markwharton/pwa-core 3.5.0 → 4.0.0

package/dist/client.d.ts

@@ -2,9 +2,17 @@
  * pwa-core/client - Browser-side API client utilities
  *
  * This module has NO Node.js dependencies and is designed for browser use.
+ *
+ * Supports two auth strategies via a single API surface:
+ * - Token (Bearer): initApiClient() — sends Authorization header
+ * - Session (Cookie): initSessionApiClient() — sends credentials: 'include'
+ *
+ * All api* functions (apiCall, apiGet, apiPost, etc.) work with whichever
+ * strategy was initialized. The sessionApi* names are deprecated aliases.
  */
 /**
- * API response wrapper for safe calls
+ * API response wrapper for safe calls.
+ * @deprecated Use ApiResponse — will be removed in next major version.
  */
 export interface ApiResponse<T> {
     ok: boolean;
@@ -13,7 +21,7 @@ export interface ApiResponse<T> {
     error?: string;
 }
 /**
- * Configuration for initApiClient
+ * Configuration for initApiClient (Bearer token auth)
  */
 export interface ApiClientConfig {
     /** Function that returns the current auth token (or null) */
@@ -24,7 +32,7 @@ export interface ApiClientConfig {
     timeout?: number;
 }
 /**
- * Configuration for initSessionApiClient
+ * Configuration for initSessionApiClient (cookie auth)
  */
 export interface SessionApiClientConfig {
     /** Optional callback for 401 responses (e.g., redirect to login) */
@@ -81,7 +89,7 @@ export declare class ApiError extends Error {
     isServerError(): boolean;
 }
 /**
- * Initializes the API client with token retrieval and optional configuration.
+ * Initializes the API client with Bearer token authentication.
  * Call once at application startup.
  * @param config - Client configuration
  * @example
@@ -92,6 +100,18 @@ export declare class ApiError extends Error {
  * });
  */
 export declare function initApiClient(config: ApiClientConfig): void;
+/**
+ * Initializes the session-based API client.
+ * Uses cookies (credentials: 'include') instead of Bearer tokens.
+ * After calling this, use apiCall/apiGet/apiPost etc. (same functions as token auth).
+ * @param config - Client configuration
+ * @example
+ * initSessionApiClient({
+ *   onUnauthenticated: () => window.location.href = '/login',
+ *   timeout: 60000
+ * });
+ */
+export declare function initSessionApiClient(config: SessionApiClientConfig): void;
 /**
  * Extract a user-friendly error message from an API error.
  * Use in catch blocks to convert errors to displayable strings.
@@ -108,6 +128,7 @@ export declare function initApiClient(config: ApiClientConfig): void;
 export declare function getApiErrorMessage(error: unknown, fallback: string): string;
 /**
  * Makes an authenticated API call. Throws ApiError on non-2xx responses.
+ * Works with both token (Bearer) and session (cookie) auth strategies.
  * @typeParam T - The expected response data type
  * @param url - The API endpoint URL
  * @param options - Optional fetch options (method, body, headers)
@@ -198,88 +219,6 @@ 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)
@@ -289,8 +228,9 @@ export declare function sessionApiCallVoid(url: string, options?: RequestInit):
  */
 export declare function isRetryableStatus(status: number | undefined): boolean;
 /**
- * Makes a cookie-authenticated API call with exponential backoff retry.
+ * Makes an authenticated API call with exponential backoff retry.
  * Retries on retryable status codes (408, 425, 429, 5xx, network errors).
+ * Works with both token and session auth strategies.
  * @typeParam T - The expected response data type
  * @param url - The API endpoint URL
  * @param options - Optional fetch options
@@ -299,9 +239,27 @@ export declare function isRetryableStatus(status: number | undefined): boolean;
  * @returns The parsed JSON response
  * @throws ApiError if all retries fail
  * @example
- * const result = await sessionApiCallWithRetry<AuthResponse>('/api/auth/verify', {
+ * const result = await apiCallWithRetry<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>;
+export declare function apiCallWithRetry<T>(url: string, options?: RequestInit, maxRetries?: number, initialDelayMs?: number): Promise<T>;
+/** @deprecated Use apiCall after initSessionApiClient */
+export declare const sessionApiCall: typeof apiCall;
+/** @deprecated Use apiGet after initSessionApiClient */
+export declare const sessionApiGet: typeof apiGet;
+/** @deprecated Use apiPost after initSessionApiClient */
+export declare const sessionApiPost: typeof apiPost;
+/** @deprecated Use apiPut after initSessionApiClient */
+export declare const sessionApiPut: typeof apiPut;
+/** @deprecated Use apiPatch after initSessionApiClient */
+export declare const sessionApiPatch: typeof apiPatch;
+/** @deprecated Use apiDelete after initSessionApiClient */
+export declare const sessionApiDelete: typeof apiDelete;
+/** @deprecated Use apiCallSafe after initSessionApiClient */
+export declare const sessionApiCallSafe: typeof apiCallSafe;
+/** @deprecated Use apiCallVoid after initSessionApiClient */
+export declare const sessionApiCallVoid: typeof apiCallVoid;
+/** @deprecated Use apiCallWithRetry after initSessionApiClient */
+export declare const sessionApiCallWithRetry: typeof apiCallWithRetry;

package/dist/client.js

@@ -3,10 +3,18 @@
  * pwa-core/client - Browser-side API client utilities
  *
  * This module has NO Node.js dependencies and is designed for browser use.
+ *
+ * Supports two auth strategies via a single API surface:
+ * - Token (Bearer): initApiClient() — sends Authorization header
+ * - Session (Cookie): initSessionApiClient() — sends credentials: 'include'
+ *
+ * All api* functions (apiCall, apiGet, apiPost, etc.) work with whichever
+ * strategy was initialized. The sessionApi* names are deprecated aliases.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ApiError = void 0;
+exports.sessionApiCallWithRetry = exports.sessionApiCallVoid = exports.sessionApiCallSafe = exports.sessionApiDelete = exports.sessionApiPatch = exports.sessionApiPut = exports.sessionApiPost = exports.sessionApiGet = exports.sessionApiCall = exports.ApiError = void 0;
 exports.initApiClient = initApiClient;
+exports.initSessionApiClient = initSessionApiClient;
 exports.getApiErrorMessage = getApiErrorMessage;
 exports.apiCall = apiCall;
 exports.apiGet = apiGet;
@@ -16,17 +24,8 @@ 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;
+exports.apiCallWithRetry = apiCallWithRetry;
 // =============================================================================
 // ApiError Class
 // =============================================================================
@@ -92,29 +91,35 @@ class ApiError extends Error {
     }
 }
 exports.ApiError = ApiError;
-// =============================================================================
-// Module State
-// =============================================================================
-// Token getter function - set by consuming app
-let getToken = null;
-// Callback for 401 responses (e.g., redirect to login)
-let onUnauthorized = null;
-// Request timeout in milliseconds (default: 30 seconds)
-let requestTimeout = 30000;
+let clientState = null;
 // =============================================================================
 // Internal Helpers
 // =============================================================================
-/** Prepare headers with optional auth token */
-function prepareHeaders(options) {
-    const token = getToken?.();
+/** Get the active client state or throw */
+function getState() {
+    if (!clientState) {
+        throw new Error('API client not initialized. Call initApiClient() or initSessionApiClient() first.');
+    }
+    return clientState;
+}
+/** Prepare headers and fetch options based on auth strategy */
+function prepareFetchOptions(options) {
+    const state = getState();
     const headers = {
         'Content-Type': 'application/json',
         ...options.headers
     };
-    if (token) {
-        headers['Authorization'] = `Bearer ${token}`;
+    const fetchOptions = { ...options };
+    if (state.strategy === 'token') {
+        const token = state.getToken?.();
+        if (token) {
+            headers['Authorization'] = `Bearer ${token}`;
+        }
     }
-    return headers;
+    else {
+        fetchOptions.credentials = 'include';
+    }
+    return { headers, fetchOptions };
 }
 /** Extract error message from failed response */
 async function extractErrorMessage(response) {
@@ -126,10 +131,10 @@ async function extractErrorMessage(response) {
         return 'Request failed';
     }
 }
-/** Handle 401 unauthorized callback */
+/** Handle 401 unauthorized/unauthenticated callback */
 function handleUnauthorized(status) {
-    if (status === 401 && onUnauthorized) {
-        onUnauthorized();
+    if (status === 401 && clientState?.onUnauthorized) {
+        clientState.onUnauthorized();
     }
 }
 /** Handle catch block for throwing API functions */
@@ -143,10 +148,10 @@ function handleApiError(error) {
     throw error;
 }
 // =============================================================================
-// Public API
+// Initialization
 // =============================================================================
 /**
- * Initializes the API client with token retrieval and optional configuration.
+ * Initializes the API client with Bearer token authentication.
  * Call once at application startup.
  * @param config - Client configuration
  * @example
@@ -157,10 +162,34 @@ function handleApiError(error) {
  * });
  */
 function initApiClient(config) {
-    getToken = config.getToken;
-    onUnauthorized = config.onUnauthorized ?? null;
-    requestTimeout = config.timeout ?? 30000;
+    clientState = {
+        strategy: 'token',
+        getToken: config.getToken,
+        onUnauthorized: config.onUnauthorized,
+        timeout: config.timeout ?? 30000,
+    };
 }
+/**
+ * Initializes the session-based API client.
+ * Uses cookies (credentials: 'include') instead of Bearer tokens.
+ * After calling this, use apiCall/apiGet/apiPost etc. (same functions as token auth).
+ * @param config - Client configuration
+ * @example
+ * initSessionApiClient({
+ *   onUnauthenticated: () => window.location.href = '/login',
+ *   timeout: 60000
+ * });
+ */
+function initSessionApiClient(config) {
+    clientState = {
+        strategy: 'session',
+        onUnauthorized: config.onUnauthenticated,
+        timeout: config.timeout ?? 30000,
+    };
+}
+// =============================================================================
+// Public API — Works with both token and session strategies
+// =============================================================================
 /**
  * Extract a user-friendly error message from an API error.
  * Use in catch blocks to convert errors to displayable strings.
@@ -185,6 +214,7 @@ function getApiErrorMessage(error, fallback) {
 }
 /**
  * Makes an authenticated API call. Throws ApiError on non-2xx responses.
+ * Works with both token (Bearer) and session (cookie) auth strategies.
  * @typeParam T - The expected response data type
  * @param url - The API endpoint URL
  * @param options - Optional fetch options (method, body, headers)
@@ -194,12 +224,13 @@ function getApiErrorMessage(error, fallback) {
  * const user = await apiCall<User>('/api/users/123');
  */
 async function apiCall(url, options = {}) {
-    const headers = prepareHeaders(options);
+    const state = getState();
+    const { headers, fetchOptions } = prepareFetchOptions(options);
     const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), requestTimeout);
+    const timeoutId = setTimeout(() => controller.abort(), state.timeout);
     try {
         const response = await fetch(url, {
-            ...options,
+            ...fetchOptions,
             headers,
             signal: controller.signal
         });
@@ -304,12 +335,13 @@ async function apiDelete(url) {
  * await apiCallVoid('/api/action', { method: 'POST' });
  */
 async function apiCallVoid(url, options = {}) {
-    const headers = prepareHeaders(options);
+    const state = getState();
+    const { headers, fetchOptions } = prepareFetchOptions(options);
     const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), requestTimeout);
+    const timeoutId = setTimeout(() => controller.abort(), state.timeout);
     try {
         const response = await fetch(url, {
-            ...options,
+            ...fetchOptions,
             headers,
             signal: controller.signal
         });
@@ -343,12 +375,13 @@ async function apiCallVoid(url, options = {}) {
  * }
  */
 async function apiCallSafe(url, options = {}) {
-    const headers = prepareHeaders(options);
+    const state = getState();
+    const { headers, fetchOptions } = prepareFetchOptions(options);
     const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), requestTimeout);
+    const timeoutId = setTimeout(() => controller.abort(), state.timeout);
     try {
         const response = await fetch(url, {
-            ...options,
+            ...fetchOptions,
             headers,
             signal: controller.signal
         });
@@ -372,211 +405,6 @@ async function apiCallSafe(url, options = {}) {
     }
 }
 // =============================================================================
-// 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
 // =============================================================================
 /**
@@ -596,8 +424,9 @@ function isRetryableStatus(status) {
     return false;
 }
 /**
- * Makes a cookie-authenticated API call with exponential backoff retry.
+ * Makes an authenticated API call with exponential backoff retry.
  * Retries on retryable status codes (408, 425, 429, 5xx, network errors).
+ * Works with both token and session auth strategies.
  * @typeParam T - The expected response data type
  * @param url - The API endpoint URL
  * @param options - Optional fetch options
@@ -606,16 +435,16 @@ function isRetryableStatus(status) {
  * @returns The parsed JSON response
  * @throws ApiError if all retries fail
  * @example
- * const result = await sessionApiCallWithRetry<AuthResponse>('/api/auth/verify', {
+ * const result = await apiCallWithRetry<AuthResponse>('/api/auth/verify', {
  *   method: 'POST',
  *   body: JSON.stringify({ token })
  * });
  */
-async function sessionApiCallWithRetry(url, options, maxRetries = 3, initialDelayMs = 1000) {
+async function apiCallWithRetry(url, options, maxRetries = 3, initialDelayMs = 1000) {
     let lastError;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
         try {
-            return await sessionApiCall(url, options);
+            return await apiCall(url, options);
         }
         catch (error) {
             lastError = error;
@@ -630,3 +459,24 @@ async function sessionApiCallWithRetry(url, options, maxRetries = 3, initialDela
     }
     throw lastError;
 }
+// =============================================================================
+// Deprecated Aliases — Use apiCall/apiGet/apiPost etc. after initSessionApiClient
+// =============================================================================
+/** @deprecated Use apiCall after initSessionApiClient */
+exports.sessionApiCall = apiCall;
+/** @deprecated Use apiGet after initSessionApiClient */
+exports.sessionApiGet = apiGet;
+/** @deprecated Use apiPost after initSessionApiClient */
+exports.sessionApiPost = apiPost;
+/** @deprecated Use apiPut after initSessionApiClient */
+exports.sessionApiPut = apiPut;
+/** @deprecated Use apiPatch after initSessionApiClient */
+exports.sessionApiPatch = apiPatch;
+/** @deprecated Use apiDelete after initSessionApiClient */
+exports.sessionApiDelete = apiDelete;
+/** @deprecated Use apiCallSafe after initSessionApiClient */
+exports.sessionApiCallSafe = apiCallSafe;
+/** @deprecated Use apiCallVoid after initSessionApiClient */
+exports.sessionApiCallVoid = apiCallVoid;
+/** @deprecated Use apiCallWithRetry after initSessionApiClient */
+exports.sessionApiCallWithRetry = apiCallWithRetry;

package/dist/server.d.ts

@@ -23,12 +23,11 @@ export declare function initAuth(config: {
 /**
  * Initializes JWT authentication from environment variables.
  * Reads JWT_SECRET from process.env.
- * @param minLength - Minimum required secret length (default: 32)
  * @throws Error if JWT_SECRET is missing or too short
  * @example
  * initAuthFromEnv(); // Uses process.env.JWT_SECRET
  */
-export declare function initAuthFromEnv(minLength?: number): void;
+export declare function initAuthFromEnv(): void;
 /**
  * Gets the configured JWT secret.
  * @returns The JWT secret string
@@ -75,50 +74,31 @@ export declare function generateToken<T extends object>(payload: T, expiresIn?:
  * const apiToken = generateLongLivedToken({ machineId: 'server-1' });
  */
 export declare function generateLongLivedToken<T extends object>(payload: T, expiresInDays?: number): string;
-/**
- * Successful auth result with typed payload.
- */
-export interface AuthSuccess<T extends BaseJwtPayload> {
-    authorized: true;
-    payload: T;
-}
-/**
- * Failed auth result with HTTP response.
- */
-export interface AuthFailure {
-    authorized: false;
-    response: HttpResponseInit;
-}
-/**
- * Discriminated union for auth results.
- * Use `auth.authorized` to narrow the type.
- */
-export type AuthResult<T extends BaseJwtPayload> = AuthSuccess<T> | AuthFailure;
 /** Default token expiry string for generateToken (7 days) */
 export declare const DEFAULT_TOKEN_EXPIRY = "7d";
 /** Default token expiry in seconds (7 days = 604800 seconds) */
 export declare const DEFAULT_TOKEN_EXPIRY_SECONDS: number;
 /**
- * Validates auth header and returns typed payload or error response.
+ * Validates auth header and returns typed payload or error result.
  * @typeParam T - The expected payload type (extends BaseJwtPayload)
  * @param authHeader - The Authorization header value
- * @returns AuthResult with payload on success, or HTTP response on failure
+ * @returns Result with payload on success, or error with status on failure
  * @example
  * const auth = requireAuth<UsernameTokenPayload>(request.headers.get('Authorization'));
- * if (!auth.authorized) return auth.response;
- * console.log(auth.payload.username);
+ * if (!auth.ok) return resultToResponse(auth);
+ * console.log(auth.data.username);
  */
-export declare function requireAuth<T extends BaseJwtPayload>(authHeader: string | null): AuthResult<T>;
+export declare function requireAuth<T extends BaseJwtPayload>(authHeader: string | null): Result<T>;
 /**
  * Requires admin role. Use with RoleTokenPayload.
  * @param authHeader - The Authorization header value
- * @returns AuthResult with RoleTokenPayload on success, or HTTP response on failure
+ * @returns Result with RoleTokenPayload on success, or error with status on failure
  * @example
  * const auth = requireAdmin(request.headers.get('Authorization'));
- * if (!auth.authorized) return auth.response;
+ * if (!auth.ok) return resultToResponse(auth);
  * // User is admin
  */
-export declare function requireAdmin(authHeader: string | null): AuthResult<RoleTokenPayload>;
+export declare function requireAdmin(authHeader: string | null): Result<RoleTokenPayload>;
 /**
  * Extracts API key from the X-API-Key header.
  * @param request - Request object with headers.get() method
@@ -259,12 +239,14 @@ export declare function initErrorHandling(config?: {
  * Initializes error handling from environment variables.
  * Currently a no-op but provides consistent API for future error config
  * (e.g., ERROR_LOG_LEVEL, ERROR_INCLUDE_STACK).
- * @param callback - Optional callback invoked when handleFunctionError is called (fire-and-forget)
+ * @param config - Optional config with onError callback invoked when handleFunctionError is called (fire-and-forget)
  * @example
  * initErrorHandlingFromEnv(); // Uses process.env automatically
- * initErrorHandlingFromEnv((op, msg) => sendAlert(op, msg));
+ * initErrorHandlingFromEnv({ onError: (op, msg) => sendAlert(op, msg) });
  */
-export declare function initErrorHandlingFromEnv(callback?: ErrorCallback): void;
+export declare function initErrorHandlingFromEnv(config?: {
+    onError?: ErrorCallback;
+}): void;
 /**
  * Handles unexpected errors safely by logging details and returning a generic message.
  * Use in catch blocks to avoid exposing internal error details to clients.
@@ -397,15 +379,16 @@ export declare function upsertEntity<T extends {
 }>(client: TableClient, entity: T): Promise<void>;
 /**
  * Deletes an entity from Azure Table Storage.
- * Returns true on success, false on error (swallows errors).
+ * Returns ok(true) if deleted, ok(false) if not found (not an error), err() on real failures.
  * @param client - The TableClient instance
  * @param partitionKey - The partition key
  * @param rowKey - The row key
- * @returns True if deleted successfully, false on error
+ * @returns Result with true if deleted, false if not found, or error on failure
  * @example
- * const deleted = await deleteEntity(client, 'session', sessionId);
+ * const result = await deleteEntity(client, 'session', sessionId);
+ * if (!result.ok) console.error(result.error);
  */
-export declare function deleteEntity(client: TableClient, partitionKey: string, rowKey: string): Promise<boolean>;
+export declare function deleteEntity(client: TableClient, partitionKey: string, rowKey: string): Promise<Result<boolean>>;
 /**
  * Lists all entities in a partition.
  * @typeParam T - The entity type
@@ -458,7 +441,8 @@ export interface SessionAuthConfig {
     allowedDomain?: string;
     /** Emails that get isAdmin=true */
     adminEmails?: string[];
-    /** Custom email validation callback (overrides default allowedEmails/allowedDomain check). Supports async for database lookups. */
+    /** Additional email validation. Called after built-in domain/admin checks reject.
+     *  Can only widen access, never narrow it. Supports async for database lookups. */
     isEmailAllowed?: (email: string) => boolean | Promise<boolean>;
     /** Base URL for magic links and SWA preview URL validation */
     appBaseUrl?: string;
@@ -480,16 +464,25 @@ export declare function initSessionAuth(config: SessionAuthConfig): void;
 /**
  * Initializes session auth from environment variables.
  * Reads: SESSION_COOKIE_NAME, APP_BASE_URL, ALLOWED_EMAILS, ALLOWED_DOMAIN, ADMIN_EMAILS.
- * @param sendEmail - Required callback to send magic link emails
- * @param overrides - Optional config overrides (e.g., isEmailAllowed callback)
+ * Only callbacks go in the config object — data comes from env vars.
+ * Use initSessionAuth() directly for full control.
+ * @param config - Required config with sendEmail callback and optional isEmailAllowed
  * @throws Error if sendEmail is not provided
  * @example
- * initSessionAuthFromEnv(async (to, magicLink) => {
- *   await resend.emails.send({ to, html: `<a href="${magicLink}">Sign In</a>` });
- *   return true;
- * }, { isEmailAllowed: async (email) => lookupInDatabase(email) });
+ * initSessionAuthFromEnv({
+ *   sendEmail: async (to, magicLink) => {
+ *     await resend.emails.send({ to, html: `<a href="${magicLink}">Sign In</a>` });
+ *     return true;
+ *   },
+ *   isEmailAllowed: async (email) => lookupInDatabase(email),
+ * });
  */
-export declare function initSessionAuthFromEnv(sendEmail: (to: string, magicLink: string) => Promise<boolean>, overrides?: Partial<Omit<SessionAuthConfig, 'sendEmail'>>): void;
+export declare function initSessionAuthFromEnv(config: {
+    sendEmail: (to: string, magicLink: string) => Promise<boolean>;
+    /** Additional email validation. Called after built-in domain/admin checks reject.
+     *  Can only widen access, never narrow it. */
+    isEmailAllowed?: (email: string) => boolean | Promise<boolean>;
+}): void;
 /**
  * Parses cookies from a request's Cookie header.
  * @param request - Request object with headers.get() method
@@ -582,37 +575,37 @@ export declare function verifyMagicLink(token: string): Promise<Result<{
  * Validates a session cookie and returns the user and session info.
  * Performs sliding window refresh if the session is close to expiry.
  * @param request - Request object with headers.get() method
- * @returns User, session, and optional refreshed cookie, or null if invalid
+ * @returns Result with user, session, and optional refreshed cookie
  * @example
  * const result = await validateSession(request);
- * if (!result) return unauthorizedResponse();
+ * if (!result.ok) return unauthorizedResponse();
  */
 export declare function validateSession(request: {
     headers: {
         get(name: string): string | null;
     };
-}): Promise<{
+}): Promise<Result<{
     user: SessionUser;
     session: SessionInfo;
     refreshedCookie?: string;
-} | null>;
+}>>;
 /**
  * Convenience function: validates session and returns user with optional refresh headers.
  * @param request - Request object with headers.get() method
- * @returns User and optional Set-Cookie headers, or null if not authenticated
+ * @returns Result with user and optional Set-Cookie headers
  * @example
  * const result = await getSessionUser(request);
- * if (!result) return unauthorizedResponse();
- * return { headers: result.headers, jsonBody: { user: result.user } };
+ * if (!result.ok) return resultToResponse(result);
+ * const { user, headers } = result.data!;
  */
 export declare function getSessionUser(request: {
     headers: {
         get(name: string): string | null;
     };
-}): Promise<{
+}): Promise<Result<{
     user: SessionUser;
     headers?: Record<string, string>;
-} | null>;
+}>>;
 /**
  * Destroys the current session and returns a logout cookie string.
  * @param request - Request object with headers.get() method
@@ -703,4 +696,14 @@ export declare function hasKeyVaultReferences(): boolean;
  * }
  */
 export declare function resolveKeyVaultReferences(): Promise<number>;
+/**
+ * Convert a failed Result to an HttpResponseInit.
+ * Use after checking `!result.ok` to return the error as an HTTP response.
+ * @param result - A failed Result (ok=false)
+ * @returns HttpResponseInit with the error status and message
+ * @example
+ * const auth = requireAuth<UsernameTokenPayload>(authHeader);
+ * if (!auth.ok) return resultToResponse(auth);
+ */
+export declare function resultToResponse(result: Result<unknown>): HttpResponseInit;
 export { Result, ok, okVoid, err, getErrorMessage, BaseJwtPayload, UserTokenPayload, UsernameTokenPayload, RoleTokenPayload, hasUsername, hasRole, isAdmin, HTTP_STATUS, HttpStatus, ErrorResponse, SessionUser, SessionInfo, MagicLinkRequest, SessionAuthResponse } from './shared';

package/dist/server.js

@@ -101,6 +101,7 @@ exports.deleteExpiredSessions = deleteExpiredSessions;
 exports.deleteExpiredMagicLinks = deleteExpiredMagicLinks;
 exports.hasKeyVaultReferences = hasKeyVaultReferences;
 exports.resolveKeyVaultReferences = resolveKeyVaultReferences;
+exports.resultToResponse = resultToResponse;
 const crypto_1 = require("crypto");
 const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
 const data_tables_1 = require("@azure/data-tables");
@@ -130,15 +131,13 @@ function initAuth(config) {
 /**
  * Initializes JWT authentication from environment variables.
  * Reads JWT_SECRET from process.env.
- * @param minLength - Minimum required secret length (default: 32)
  * @throws Error if JWT_SECRET is missing or too short
  * @example
  * initAuthFromEnv(); // Uses process.env.JWT_SECRET
  */
-function initAuthFromEnv(minLength = 32) {
+function initAuthFromEnv() {
     initAuth({
         secret: process.env.JWT_SECRET,
-        minLength
     });
 }
 /**
@@ -225,41 +224,41 @@ exports.DEFAULT_TOKEN_EXPIRY_SECONDS = DEFAULT_TOKEN_EXPIRY_DAYS * 24 * 60 * 60;
 // Auth Helpers
 // =============================================================================
 /**
- * Validates auth header and returns typed payload or error response.
+ * Validates auth header and returns typed payload or error result.
  * @typeParam T - The expected payload type (extends BaseJwtPayload)
  * @param authHeader - The Authorization header value
- * @returns AuthResult with payload on success, or HTTP response on failure
+ * @returns Result with payload on success, or error with status on failure
  * @example
  * const auth = requireAuth<UsernameTokenPayload>(request.headers.get('Authorization'));
- * if (!auth.authorized) return auth.response;
- * console.log(auth.payload.username);
+ * if (!auth.ok) return resultToResponse(auth);
+ * console.log(auth.data.username);
  */
 function requireAuth(authHeader) {
     const token = extractToken(authHeader);
     if (!token) {
-        return { authorized: false, response: unauthorizedResponse() };
+        return (0, shared_1.err)('Unauthorized', shared_1.HTTP_STATUS.UNAUTHORIZED);
     }
     const result = validateToken(token);
     if (!result.ok) {
-        return { authorized: false, response: unauthorizedResponse(result.error) };
+        return (0, shared_1.err)(result.error ?? 'Unauthorized', shared_1.HTTP_STATUS.UNAUTHORIZED);
     }
-    return { authorized: true, payload: result.data };
+    return (0, shared_1.ok)(result.data);
 }
 /**
  * Requires admin role. Use with RoleTokenPayload.
  * @param authHeader - The Authorization header value
- * @returns AuthResult with RoleTokenPayload on success, or HTTP response on failure
+ * @returns Result with RoleTokenPayload on success, or error with status on failure
  * @example
  * const auth = requireAdmin(request.headers.get('Authorization'));
- * if (!auth.authorized) return auth.response;
+ * if (!auth.ok) return resultToResponse(auth);
  * // User is admin
  */
 function requireAdmin(authHeader) {
     const auth = requireAuth(authHeader);
-    if (!auth.authorized)
+    if (!auth.ok)
         return auth;
-    if (!(0, shared_1.isAdmin)(auth.payload)) {
-        return { authorized: false, response: forbiddenResponse('Admin access required') };
+    if (!(0, shared_1.isAdmin)(auth.data)) {
+        return (0, shared_1.err)('Admin access required', shared_1.HTTP_STATUS.FORBIDDEN);
     }
     return auth;
 }
@@ -459,14 +458,14 @@ function initErrorHandling(config = {}) {
  * Initializes error handling from environment variables.
  * Currently a no-op but provides consistent API for future error config
  * (e.g., ERROR_LOG_LEVEL, ERROR_INCLUDE_STACK).
- * @param callback - Optional callback invoked when handleFunctionError is called (fire-and-forget)
+ * @param config - Optional config with onError callback invoked when handleFunctionError is called (fire-and-forget)
  * @example
  * initErrorHandlingFromEnv(); // Uses process.env automatically
- * initErrorHandlingFromEnv((op, msg) => sendAlert(op, msg));
+ * initErrorHandlingFromEnv({ onError: (op, msg) => sendAlert(op, msg) });
  */
-function initErrorHandlingFromEnv(callback) {
+function initErrorHandlingFromEnv(config) {
     // Future: read ERROR_LOG_LEVEL, ERROR_INCLUDE_STACK, etc. from process.env
-    initErrorHandling({ callback });
+    initErrorHandling({ callback: config?.onError });
 }
 /**
  * Handles unexpected errors safely by logging details and returning a generic message.
@@ -695,21 +694,25 @@ async function upsertEntity(client, entity) {
 }
 /**
  * Deletes an entity from Azure Table Storage.
- * Returns true on success, false on error (swallows errors).
+ * Returns ok(true) if deleted, ok(false) if not found (not an error), err() on real failures.
  * @param client - The TableClient instance
  * @param partitionKey - The partition key
  * @param rowKey - The row key
- * @returns True if deleted successfully, false on error
+ * @returns Result with true if deleted, false if not found, or error on failure
  * @example
- * const deleted = await deleteEntity(client, 'session', sessionId);
+ * const result = await deleteEntity(client, 'session', sessionId);
+ * if (!result.ok) console.error(result.error);
  */
 async function deleteEntity(client, partitionKey, rowKey) {
     try {
         await client.deleteEntity(partitionKey, rowKey);
-        return true;
+        return (0, shared_1.ok)(true);
     }
-    catch {
-        return false;
+    catch (error) {
+        if (isNotFoundError(error)) {
+            return (0, shared_1.ok)(false);
+        }
+        return (0, shared_1.err)((0, shared_1.getErrorMessage)(error, 'Delete failed'));
     }
 }
 /**
@@ -788,16 +791,20 @@ function initSessionAuth(config) {
 /**
  * Initializes session auth from environment variables.
  * Reads: SESSION_COOKIE_NAME, APP_BASE_URL, ALLOWED_EMAILS, ALLOWED_DOMAIN, ADMIN_EMAILS.
- * @param sendEmail - Required callback to send magic link emails
- * @param overrides - Optional config overrides (e.g., isEmailAllowed callback)
+ * Only callbacks go in the config object — data comes from env vars.
+ * Use initSessionAuth() directly for full control.
+ * @param config - Required config with sendEmail callback and optional isEmailAllowed
  * @throws Error if sendEmail is not provided
  * @example
- * initSessionAuthFromEnv(async (to, magicLink) => {
- *   await resend.emails.send({ to, html: `<a href="${magicLink}">Sign In</a>` });
- *   return true;
- * }, { isEmailAllowed: async (email) => lookupInDatabase(email) });
+ * initSessionAuthFromEnv({
+ *   sendEmail: async (to, magicLink) => {
+ *     await resend.emails.send({ to, html: `<a href="${magicLink}">Sign In</a>` });
+ *     return true;
+ *   },
+ *   isEmailAllowed: async (email) => lookupInDatabase(email),
+ * });
  */
-function initSessionAuthFromEnv(sendEmail, overrides) {
+function initSessionAuthFromEnv(config) {
     const allowedEmailsStr = process.env.ALLOWED_EMAILS;
     const adminEmailsStr = process.env.ADMIN_EMAILS;
     initSessionAuth({
@@ -810,8 +817,8 @@ function initSessionAuthFromEnv(sendEmail, overrides) {
         adminEmails: adminEmailsStr
             ? adminEmailsStr.split(',').map(e => e.trim().toLowerCase())
             : undefined,
-        ...overrides,
-        sendEmail
+        isEmailAllowed: config.isEmailAllowed,
+        sendEmail: config.sendEmail,
     });
 }
 /**
@@ -1007,10 +1014,11 @@ async function createMagicLink(email, request) {
     if (!isValidEmail(normalizedEmail)) {
         return (0, shared_1.err)('Valid email required', shared_1.HTTP_STATUS.BAD_REQUEST);
     }
-    // Check allowlist (custom callback overrides default)
-    const emailAllowed = config.isEmailAllowed
-        ? await config.isEmailAllowed(normalizedEmail)
-        : isEmailAllowed(normalizedEmail);
+    // Check allowlist (built-in first, custom extends — can only widen access)
+    const emailAllowed = isEmailAllowed(normalizedEmail)
+        || (config.isEmailAllowed
+            ? await config.isEmailAllowed(normalizedEmail)
+            : false);
     if (!emailAllowed) {
         return (0, shared_1.err)('Email not allowed', shared_1.HTTP_STATUS.FORBIDDEN);
     }
@@ -1123,10 +1131,10 @@ async function verifyMagicLink(token) {
  * Validates a session cookie and returns the user and session info.
  * Performs sliding window refresh if the session is close to expiry.
  * @param request - Request object with headers.get() method
- * @returns User, session, and optional refreshed cookie, or null if invalid
+ * @returns Result with user, session, and optional refreshed cookie
  * @example
  * const result = await validateSession(request);
- * if (!result) return unauthorizedResponse();
+ * if (!result.ok) return unauthorizedResponse();
  */
 async function validateSession(request) {
     const config = getSessionAuthConfig();
@@ -1134,20 +1142,20 @@ async function validateSession(request) {
     const cookies = parseCookies(request);
     const sessionId = cookies[cookieName];
     if (!sessionId)
-        return null;
+        return (0, shared_1.err)('No session cookie', shared_1.HTTP_STATUS.UNAUTHORIZED);
     try {
         const sessionsClient = await getTableClient(SESSIONS_TABLE);
         const sessionEntity = await getEntityIfExists(sessionsClient, SESSION_PARTITION, sessionId);
         if (!sessionEntity)
-            return null;
+            return (0, shared_1.err)('Invalid session', shared_1.HTTP_STATUS.UNAUTHORIZED);
         // Check expiry
         if (new Date(sessionEntity.expiresAt) < new Date())
-            return null;
+            return (0, shared_1.err)('Session expired', shared_1.HTTP_STATUS.UNAUTHORIZED);
         // Get user
         const usersClient = await getTableClient(USERS_TABLE);
         const userEntity = await getEntityIfExists(usersClient, USER_PARTITION, sessionEntity.email.toLowerCase());
         if (!userEntity)
-            return null;
+            return (0, shared_1.err)('User not found', shared_1.HTTP_STATUS.UNAUTHORIZED);
         const user = {
             id: userEntity.id,
             email: userEntity.email,
@@ -1179,30 +1187,30 @@ async function validateSession(request) {
             await upsertEntity(sessionsClient, updatedSession);
             refreshedCookie = createSessionCookie(sessionId);
         }
-        return { user, session, refreshedCookie };
+        return (0, shared_1.ok)({ user, session, refreshedCookie });
     }
     catch {
-        return null;
+        return (0, shared_1.err)('Session validation failed', shared_1.HTTP_STATUS.UNAUTHORIZED);
     }
 }
 // --- Session Operations ---
 /**
  * Convenience function: validates session and returns user with optional refresh headers.
  * @param request - Request object with headers.get() method
- * @returns User and optional Set-Cookie headers, or null if not authenticated
+ * @returns Result with user and optional Set-Cookie headers
  * @example
  * const result = await getSessionUser(request);
- * if (!result) return unauthorizedResponse();
- * return { headers: result.headers, jsonBody: { user: result.user } };
+ * if (!result.ok) return resultToResponse(result);
+ * const { user, headers } = result.data!;
  */
 async function getSessionUser(request) {
     const result = await validateSession(request);
-    if (!result)
-        return null;
-    const headers = result.refreshedCookie
-        ? { 'Set-Cookie': result.refreshedCookie }
+    if (!result.ok)
+        return result;
+    const headers = result.data.refreshedCookie
+        ? { 'Set-Cookie': result.data.refreshedCookie }
         : undefined;
-    return { user: result.user, headers };
+    return (0, shared_1.ok)({ user: result.data.user, headers });
 }
 /**
  * Destroys the current session and returns a logout cookie string.
@@ -1239,13 +1247,13 @@ async function destroySession(request) {
 function withSessionAuth(handler) {
     return async (request, context) => {
         const result = await getSessionUser(request);
-        if (!result) {
+        if (!result.ok) {
             return unauthorizedResponse('Not authenticated');
         }
-        const response = await handler(request, context, result);
+        const response = await handler(request, context, result.data);
         // Merge refresh cookie headers
-        if (result.headers) {
-            response.headers = { ...result.headers, ...response.headers };
+        if (result.data.headers) {
+            response.headers = { ...result.data.headers, ...response.headers };
         }
         return response;
     };
@@ -1265,16 +1273,16 @@ function withSessionAuth(handler) {
 function withSessionAdminAuth(handler) {
     return async (request, context) => {
         const result = await getSessionUser(request);
-        if (!result) {
+        if (!result.ok) {
             return unauthorizedResponse('Not authenticated');
         }
-        if (!result.user.isAdmin) {
+        if (!result.data.user.isAdmin) {
             return forbiddenResponse('Admin access required');
         }
-        const response = await handler(request, context, result);
+        const response = await handler(request, context, result.data);
         // Merge refresh cookie headers
-        if (result.headers) {
-            response.headers = { ...result.headers, ...response.headers };
+        if (result.data.headers) {
+            response.headers = { ...result.data.headers, ...response.headers };
         }
         return response;
     };
@@ -1295,8 +1303,8 @@ async function deleteExpiredSessions() {
     let deleted = 0;
     for (const session of sessions) {
         if (new Date(session.expiresAt) < now) {
-            const success = await deleteEntity(client, SESSION_PARTITION, session.rowKey);
-            if (success)
+            const result = await deleteEntity(client, SESSION_PARTITION, session.rowKey);
+            if (result.ok && result.data)
                 deleted++;
         }
     }
@@ -1317,8 +1325,8 @@ async function deleteExpiredMagicLinks() {
     let deleted = 0;
     for (const link of links) {
         if (new Date(link.expiresAt) < now || link.used) {
-            const success = await deleteEntity(client, MAGICLINK_PARTITION, link.rowKey);
-            if (success)
+            const result = await deleteEntity(client, MAGICLINK_PARTITION, link.rowKey);
+            if (result.ok && result.data)
                 deleted++;
         }
     }
@@ -1432,6 +1440,24 @@ async function resolveKeyVaultReferences() {
     return resolved;
 }
 // =============================================================================
+// Result Conversion Helper
+// =============================================================================
+/**
+ * Convert a failed Result to an HttpResponseInit.
+ * Use after checking `!result.ok` to return the error as an HTTP response.
+ * @param result - A failed Result (ok=false)
+ * @returns HttpResponseInit with the error status and message
+ * @example
+ * const auth = requireAuth<UsernameTokenPayload>(authHeader);
+ * if (!auth.ok) return resultToResponse(auth);
+ */
+function resultToResponse(result) {
+    return {
+        status: result.status ?? shared_1.HTTP_STATUS.INTERNAL_ERROR,
+        jsonBody: { error: result.error ?? 'Unknown error' }
+    };
+}
+// =============================================================================
 // Re-exports from shared (for convenience)
 // =============================================================================
 var shared_2 = require("./shared");

package/dist/shared.d.ts

@@ -15,13 +15,13 @@
  * { ok: false, error: 'Token expired' }
  *
  * // With status code (HTTP/push operations)
- * { ok: false, error: 'Subscription expired', statusCode: 410 }
+ * { ok: false, error: 'Subscription expired', status: 410 }
  */
 export interface Result<T> {
     ok: boolean;
     data?: T;
     error?: string;
-    statusCode?: number;
+    status?: number;
 }
 /**
  * Creates a success result with data.
@@ -41,13 +41,13 @@ export declare function okVoid(): Result<void>;
 /**
  * Creates a failure result with an error message.
  * @param error - The error message
- * @param statusCode - Optional HTTP status code for API/push operations
+ * @param status - Optional HTTP status code for API/push operations
  * @returns A Result with ok=false and the error details
  * @example
  * return err('Token expired');
  * return err('Subscription gone', 410);
  */
-export declare function err<T>(error: string, statusCode?: number): Result<T>;
+export declare function err<T = never>(error: string, status?: number): Result<T>;
 /**
  * Base JWT payload - all tokens include these fields
  * Projects extend this with their specific fields

package/dist/shared.js

@@ -35,15 +35,15 @@ function okVoid() {
 /**
  * Creates a failure result with an error message.
  * @param error - The error message
- * @param statusCode - Optional HTTP status code for API/push operations
+ * @param status - Optional HTTP status code for API/push operations
  * @returns A Result with ok=false and the error details
  * @example
  * return err('Token expired');
  * return err('Subscription gone', 410);
  */
-function err(error, statusCode) {
-    return statusCode !== undefined
-        ? { ok: false, error, statusCode }
+function err(error, status) {
+    return status !== undefined
+        ? { ok: false, error, status }
         : { ok: false, error };
 }
 // =============================================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markwharton/pwa-core",
-  "version": "3.5.0",
+  "version": "4.0.0",
   "description": "Shared patterns for Azure PWA projects",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",