@markwharton/pwa-core 1.2.0 → 1.3.0

package/dist/client/api.d.ts

@@ -1,37 +1,98 @@
 import { ApiResponse } from './types';
 /**
- * Initialize the API client
+ * Initializes the API client with token retrieval and optional 401 handler.
+ * Call once at application startup.
+ * @param config - Client configuration
+ * @param config.getToken - Function that returns the current auth token (or null)
+ * @param config.onUnauthorized - Optional callback for 401 responses (e.g., redirect to login)
+ * @example
+ * initApiClient({
+ *   getToken: () => localStorage.getItem('token'),
+ *   onUnauthorized: () => window.location.href = '/login'
+ * });
  */
 export declare function initApiClient(config: {
     getToken: () => string | null;
     onUnauthorized?: () => void;
 }): void;
 /**
- * Make an authenticated API call
+ * Makes an authenticated API call. Throws ApiError on non-2xx responses.
+ * @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
+ * @example
+ * const user = await apiCall<User>('/api/users/123');
  */
 export declare function apiCall<T>(url: string, options?: RequestInit): Promise<T>;
 /**
- * GET request helper
+ * Makes an 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
+ * @example
+ * const users = await apiGet<User[]>('/api/users');
  */
 export declare function apiGet<T>(url: string): Promise<T>;
 /**
- * POST request helper
+ * Makes an 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
+ * @example
+ * const user = await apiPost<User>('/api/users', { name: 'John' });
  */
 export declare function apiPost<T>(url: string, body?: unknown): Promise<T>;
 /**
- * PUT request helper
+ * Makes an 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
+ * @example
+ * const user = await apiPut<User>('/api/users/123', { name: 'Jane' });
  */
 export declare function apiPut<T>(url: string, body?: unknown): Promise<T>;
 /**
- * PATCH request helper
+ * Makes an 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
+ * @example
+ * const user = await apiPatch<User>('/api/users/123', { status: 'active' });
  */
 export declare function apiPatch<T>(url: string, body?: unknown): Promise<T>;
 /**
- * DELETE request helper
+ * Makes an 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
+ * @example
+ * await apiDelete('/api/users/123');
  */
 export declare function apiDelete<T>(url: string): Promise<T>;
 /**
- * Alternative: Response wrapper style (like financial-tracker's authJsonFetch)
- * Preserves actual HTTP status code on success
+ * Makes an authenticated API call with Result-style error handling.
+ * Unlike apiCall, this never throws - errors are returned in the response.
+ * Preserves actual HTTP status code on success (not always 200).
+ * @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)
+ * @example
+ * const response = await apiCallSafe<User>('/api/users/123');
+ * if (response.ok) {
+ *   console.log(response.data);
+ * } else {
+ *   console.error(response.error);
+ * }
  */
 export declare function apiCallSafe<T>(url: string, options?: RequestInit): Promise<ApiResponse<T>>;

package/dist/client/api.js

@@ -17,14 +17,30 @@ let getToken = null;
 // Callback for 401 responses (e.g., redirect to login)
 let onUnauthorized = null;
 /**
- * Initialize the API client
+ * Initializes the API client with token retrieval and optional 401 handler.
+ * Call once at application startup.
+ * @param config - Client configuration
+ * @param config.getToken - Function that returns the current auth token (or null)
+ * @param config.onUnauthorized - Optional callback for 401 responses (e.g., redirect to login)
+ * @example
+ * initApiClient({
+ *   getToken: () => localStorage.getItem('token'),
+ *   onUnauthorized: () => window.location.href = '/login'
+ * });
  */
 function initApiClient(config) {
     getToken = config.getToken;
     onUnauthorized = config.onUnauthorized ?? null;
 }
 /**
- * Make an authenticated API call
+ * Makes an authenticated API call. Throws ApiError on non-2xx responses.
+ * @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
+ * @example
+ * const user = await apiCall<User>('/api/users/123');
  */
 async function apiCall(url, options = {}) {
     const token = getToken?.();
@@ -61,13 +77,26 @@ async function apiCall(url, options = {}) {
     return JSON.parse(text);
 }
 /**
- * GET request helper
+ * Makes an 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
+ * @example
+ * const users = await apiGet<User[]>('/api/users');
  */
 async function apiGet(url) {
     return apiCall(url, { method: 'GET' });
 }
 /**
- * POST request helper
+ * Makes an 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
+ * @example
+ * const user = await apiPost<User>('/api/users', { name: 'John' });
  */
 async function apiPost(url, body) {
     return apiCall(url, {
@@ -76,7 +105,14 @@ async function apiPost(url, body) {
     });
 }
 /**
- * PUT request helper
+ * Makes an 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
+ * @example
+ * const user = await apiPut<User>('/api/users/123', { name: 'Jane' });
  */
 async function apiPut(url, body) {
     return apiCall(url, {
@@ -85,7 +121,14 @@ async function apiPut(url, body) {
     });
 }
 /**
- * PATCH request helper
+ * Makes an 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
+ * @example
+ * const user = await apiPatch<User>('/api/users/123', { status: 'active' });
  */
 async function apiPatch(url, body) {
     return apiCall(url, {
@@ -94,14 +137,32 @@ async function apiPatch(url, body) {
     });
 }
 /**
- * DELETE request helper
+ * Makes an 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
+ * @example
+ * await apiDelete('/api/users/123');
  */
 async function apiDelete(url) {
     return apiCall(url, { method: 'DELETE' });
 }
 /**
- * Alternative: Response wrapper style (like financial-tracker's authJsonFetch)
- * Preserves actual HTTP status code on success
+ * Makes an authenticated API call with Result-style error handling.
+ * Unlike apiCall, this never throws - errors are returned in the response.
+ * Preserves actual HTTP status code on success (not always 200).
+ * @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)
+ * @example
+ * const response = await apiCallSafe<User>('/api/users/123');
+ * if (response.ok) {
+ *   console.log(response.data);
+ * } else {
+ *   console.error(response.error);
+ * }
  */
 async function apiCallSafe(url, options = {}) {
     const token = getToken?.();

package/dist/client/apiError.d.ts

@@ -1,21 +1,38 @@
 /**
- * Custom error class for API errors
- * Preserves status code and error message from server
+ * Custom error class for API errors.
+ * Preserves HTTP status code and error message from the server.
+ * @example
+ * try {
+ *   await apiGet('/users/123');
+ * } catch (error) {
+ *   if (error instanceof ApiError && error.isNotFound()) {
+ *     console.log('User not found');
+ *   }
+ * }
  */
 export declare class ApiError extends Error {
     status: number;
     details?: string | undefined;
+    /**
+     * Creates a new ApiError instance.
+     * @param status - The HTTP status code
+     * @param message - The error message
+     * @param details - Optional additional error details
+     */
     constructor(status: number, message: string, details?: string | undefined);
     /**
-     * Check if this is an authentication error
+     * Checks if this is a 401 Unauthorized error.
+     * @returns True if status is 401
      */
     isUnauthorized(): boolean;
     /**
-     * Check if this is a not found error
+     * Checks if this is a 404 Not Found error.
+     * @returns True if status is 404
      */
     isNotFound(): boolean;
     /**
-     * Check if this is a validation error
+     * Checks if this is a 400 Bad Request error.
+     * @returns True if status is 400
      */
     isBadRequest(): boolean;
 }

package/dist/client/apiError.js

@@ -2,10 +2,24 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ApiError = void 0;
 /**
- * Custom error class for API errors
- * Preserves status code and error message from server
+ * Custom error class for API errors.
+ * Preserves HTTP status code and error message from the server.
+ * @example
+ * try {
+ *   await apiGet('/users/123');
+ * } catch (error) {
+ *   if (error instanceof ApiError && error.isNotFound()) {
+ *     console.log('User not found');
+ *   }
+ * }
  */
 class ApiError extends Error {
+    /**
+     * Creates a new ApiError instance.
+     * @param status - The HTTP status code
+     * @param message - The error message
+     * @param details - Optional additional error details
+     */
     constructor(status, message, details) {
         super(message);
         this.status = status;
@@ -13,19 +27,22 @@ class ApiError extends Error {
         this.name = 'ApiError';
     }
     /**
-     * Check if this is an authentication error
+     * Checks if this is a 401 Unauthorized error.
+     * @returns True if status is 401
      */
     isUnauthorized() {
         return this.status === 401;
     }
     /**
-     * Check if this is a not found error
+     * Checks if this is a 404 Not Found error.
+     * @returns True if status is 404
      */
     isNotFound() {
         return this.status === 404;
     }
     /**
-     * Check if this is a validation error
+     * Checks if this is a 400 Bad Request error.
+     * @returns True if status is 400
      */
     isBadRequest() {
         return this.status === 400;

package/dist/http/responses.d.ts

@@ -1,33 +1,82 @@
 import { HttpResponseInit, InvocationContext } from '@azure/functions';
 /**
- * Create a 400 Bad Request response
+ * Creates a 400 Bad Request response.
+ * @param message - The error message to return
+ * @returns Azure Functions HttpResponseInit object
+ * @example
+ * if (!body.email) return badRequestResponse('Email is required');
  */
 export declare function badRequestResponse(message: string): HttpResponseInit;
 /**
- * Create a 401 Unauthorized response
+ * Creates a 401 Unauthorized response.
+ * @param message - The error message (default: 'Unauthorized')
+ * @returns Azure Functions HttpResponseInit object
+ * @example
+ * if (!token) return unauthorizedResponse();
  */
 export declare function unauthorizedResponse(message?: string): HttpResponseInit;
 /**
- * Create a 403 Forbidden response
+ * Creates a 403 Forbidden response.
+ * @param message - The error message (default: 'Forbidden')
+ * @returns Azure Functions HttpResponseInit object
+ * @example
+ * if (!isAdmin(payload)) return forbiddenResponse('Admin access required');
  */
 export declare function forbiddenResponse(message?: string): HttpResponseInit;
 /**
- * Create a 404 Not Found response
+ * Creates a 404 Not Found response.
+ * @param resource - The name of the resource that wasn't found
+ * @returns Azure Functions HttpResponseInit object
+ * @example
+ * if (!user) return notFoundResponse('User');
+ * // Returns: { error: 'User not found' }
  */
 export declare function notFoundResponse(resource: string): HttpResponseInit;
 /**
- * Create a 409 Conflict response
+ * Creates a 409 Conflict response.
+ * @param message - The conflict error message
+ * @returns Azure Functions HttpResponseInit object
+ * @example
+ * if (existingUser) return conflictResponse('Email already registered');
  */
 export declare function conflictResponse(message: string): HttpResponseInit;
 /**
- * Handle unexpected errors safely (logs details, returns generic message)
+ * Handles unexpected errors safely by logging details and returning a generic message.
+ * Use in catch blocks to avoid exposing internal error details to clients.
+ * @param error - The caught error
+ * @param context - Azure Functions InvocationContext for logging
+ * @returns Azure Functions HttpResponseInit with 500 status
+ * @example
+ * try {
+ *   await riskyOperation();
+ * } catch (error) {
+ *   return handleFunctionError(error, context);
+ * }
  */
 export declare function handleFunctionError(error: unknown, context: InvocationContext): HttpResponseInit;
 /**
- * Check if an Azure Table Storage error is "not found"
+ * Checks if an error is an Azure Table Storage "not found" error.
+ * @param error - The caught error
+ * @returns True if error has statusCode 404
+ * @example
+ * try {
+ *   await tableClient.getEntity(pk, rk);
+ * } catch (error) {
+ *   if (isNotFoundError(error)) return notFoundResponse('Entity');
+ *   throw error;
+ * }
  */
 export declare function isNotFoundError(error: unknown): boolean;
 /**
- * Check if an Azure Table Storage error is "conflict"
+ * Checks if an error is an Azure Table Storage "conflict" error.
+ * @param error - The caught error
+ * @returns True if error has statusCode 409
+ * @example
+ * try {
+ *   await tableClient.createEntity(entity);
+ * } catch (error) {
+ *   if (isConflictError(error)) return conflictResponse('Entity already exists');
+ *   throw error;
+ * }
  */
 export declare function isConflictError(error: unknown): boolean;

package/dist/http/responses.js

@@ -10,7 +10,11 @@ exports.isNotFoundError = isNotFoundError;
 exports.isConflictError = isConflictError;
 const status_1 = require("./status");
 /**
- * Create a 400 Bad Request response
+ * Creates a 400 Bad Request response.
+ * @param message - The error message to return
+ * @returns Azure Functions HttpResponseInit object
+ * @example
+ * if (!body.email) return badRequestResponse('Email is required');
  */
 function badRequestResponse(message) {
     return {
@@ -19,7 +23,11 @@ function badRequestResponse(message) {
     };
 }
 /**
- * Create a 401 Unauthorized response
+ * Creates a 401 Unauthorized response.
+ * @param message - The error message (default: 'Unauthorized')
+ * @returns Azure Functions HttpResponseInit object
+ * @example
+ * if (!token) return unauthorizedResponse();
  */
 function unauthorizedResponse(message = 'Unauthorized') {
     return {
@@ -28,7 +36,11 @@ function unauthorizedResponse(message = 'Unauthorized') {
     };
 }
 /**
- * Create a 403 Forbidden response
+ * Creates a 403 Forbidden response.
+ * @param message - The error message (default: 'Forbidden')
+ * @returns Azure Functions HttpResponseInit object
+ * @example
+ * if (!isAdmin(payload)) return forbiddenResponse('Admin access required');
  */
 function forbiddenResponse(message = 'Forbidden') {
     return {
@@ -37,7 +49,12 @@ function forbiddenResponse(message = 'Forbidden') {
     };
 }
 /**
- * Create a 404 Not Found response
+ * Creates a 404 Not Found response.
+ * @param resource - The name of the resource that wasn't found
+ * @returns Azure Functions HttpResponseInit object
+ * @example
+ * if (!user) return notFoundResponse('User');
+ * // Returns: { error: 'User not found' }
  */
 function notFoundResponse(resource) {
     return {
@@ -46,7 +63,11 @@ function notFoundResponse(resource) {
     };
 }
 /**
- * Create a 409 Conflict response
+ * Creates a 409 Conflict response.
+ * @param message - The conflict error message
+ * @returns Azure Functions HttpResponseInit object
+ * @example
+ * if (existingUser) return conflictResponse('Email already registered');
  */
 function conflictResponse(message) {
     return {
@@ -55,7 +76,17 @@ function conflictResponse(message) {
     };
 }
 /**
- * Handle unexpected errors safely (logs details, returns generic message)
+ * Handles unexpected errors safely by logging details and returning a generic message.
+ * Use in catch blocks to avoid exposing internal error details to clients.
+ * @param error - The caught error
+ * @param context - Azure Functions InvocationContext for logging
+ * @returns Azure Functions HttpResponseInit with 500 status
+ * @example
+ * try {
+ *   await riskyOperation();
+ * } catch (error) {
+ *   return handleFunctionError(error, context);
+ * }
  */
 function handleFunctionError(error, context) {
     const message = error instanceof Error ? error.message : 'Unknown error';
@@ -66,7 +97,16 @@ function handleFunctionError(error, context) {
     };
 }
 /**
- * Check if an Azure Table Storage error is "not found"
+ * Checks if an error is an Azure Table Storage "not found" error.
+ * @param error - The caught error
+ * @returns True if error has statusCode 404
+ * @example
+ * try {
+ *   await tableClient.getEntity(pk, rk);
+ * } catch (error) {
+ *   if (isNotFoundError(error)) return notFoundResponse('Entity');
+ *   throw error;
+ * }
  */
 function isNotFoundError(error) {
     return (error instanceof Error &&
@@ -74,7 +114,16 @@ function isNotFoundError(error) {
         error.statusCode === 404);
 }
 /**
- * Check if an Azure Table Storage error is "conflict"
+ * Checks if an error is an Azure Table Storage "conflict" error.
+ * @param error - The caught error
+ * @returns True if error has statusCode 409
+ * @example
+ * try {
+ *   await tableClient.createEntity(entity);
+ * } catch (error) {
+ *   if (isConflictError(error)) return conflictResponse('Entity already exists');
+ *   throw error;
+ * }
  */
 function isConflictError(error) {
     return (error instanceof Error &&

package/dist/index.d.ts

@@ -1,5 +1,3 @@
 export * from './types';
-export * from './auth';
-export * from './http';
-export * from './storage';
-export * from './client';
+export * from './server';
+export * from './shared';

package/dist/index.js

@@ -14,9 +14,10 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-// Main entry point - re-export everything
+// Core types (universal)
 __exportStar(require("./types"), exports);
-__exportStar(require("./auth"), exports);
-__exportStar(require("./http"), exports);
-__exportStar(require("./storage"), exports);
-__exportStar(require("./client"), exports);
+// Server utilities (for convenience, but prefer ./server)
+__exportStar(require("./server"), exports);
+// Shared utilities
+__exportStar(require("./shared"), exports);
+// Note: Client utilities available via ./client subpath

package/dist/server/auth/apiKey.d.ts

@@ -0,0 +1,44 @@
+import { Result } from '../../types';
+/**
+ * API Key utilities for machine-to-machine authentication
+ */
+/**
+ * Extracts API key from the X-API-Key header.
+ * @param request - Request object with headers.get() method
+ * @returns The API key string, or null if not present
+ * @example
+ * const apiKey = extractApiKey(request);
+ */
+export declare function extractApiKey(request: {
+    headers: {
+        get(name: string): string | null;
+    };
+}): string | null;
+/**
+ * Hashes an API key using SHA-256 for secure storage.
+ * Store this hash in your database, never the raw key.
+ * @param apiKey - The raw API key to hash
+ * @returns The SHA-256 hash as a hex string
+ * @example
+ * const hash = hashApiKey(rawKey);
+ * await db.save({ apiKeyHash: hash });
+ */
+export declare function hashApiKey(apiKey: string): string;
+/**
+ * Validates an API key against a stored hash.
+ * @param apiKey - The API key from the request
+ * @param storedHash - The hash stored in your database
+ * @returns Result with ok=true if valid, or error message if invalid
+ * @example
+ * const result = validateApiKey(apiKey, user.apiKeyHash);
+ * if (!result.ok) return httpUnauthorized();
+ */
+export declare function validateApiKey(apiKey: string, storedHash: string): Result<void>;
+/**
+ * Generates a cryptographically secure API key.
+ * @returns A random 64-character hex string (32 bytes)
+ * @example
+ * const apiKey = generateApiKey();
+ * // Return to user once, store hash in database
+ */
+export declare function generateApiKey(): string;

package/dist/server/auth/apiKey.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractApiKey = extractApiKey;
+exports.hashApiKey = hashApiKey;
+exports.validateApiKey = validateApiKey;
+exports.generateApiKey = generateApiKey;
+const crypto_1 = require("crypto");
+const types_1 = require("../../types");
+/**
+ * API Key utilities for machine-to-machine authentication
+ */
+/**
+ * Extracts API key from the X-API-Key header.
+ * @param request - Request object with headers.get() method
+ * @returns The API key string, or null if not present
+ * @example
+ * const apiKey = extractApiKey(request);
+ */
+function extractApiKey(request) {
+    return request.headers.get('X-API-Key');
+}
+/**
+ * Hashes an API key using SHA-256 for secure storage.
+ * Store this hash in your database, never the raw key.
+ * @param apiKey - The raw API key to hash
+ * @returns The SHA-256 hash as a hex string
+ * @example
+ * const hash = hashApiKey(rawKey);
+ * await db.save({ apiKeyHash: hash });
+ */
+function hashApiKey(apiKey) {
+    return (0, crypto_1.createHash)('sha256').update(apiKey).digest('hex');
+}
+/**
+ * Validates an API key against a stored hash.
+ * @param apiKey - The API key from the request
+ * @param storedHash - The hash stored in your database
+ * @returns Result with ok=true if valid, or error message if invalid
+ * @example
+ * const result = validateApiKey(apiKey, user.apiKeyHash);
+ * if (!result.ok) return httpUnauthorized();
+ */
+function validateApiKey(apiKey, storedHash) {
+    const keyHash = hashApiKey(apiKey);
+    if (keyHash === storedHash) {
+        return (0, types_1.okVoid)();
+    }
+    return (0, types_1.err)('Invalid API key');
+}
+/**
+ * Generates a cryptographically secure API key.
+ * @returns A random 64-character hex string (32 bytes)
+ * @example
+ * const apiKey = generateApiKey();
+ * // Return to user once, store hash in database
+ */
+function generateApiKey() {
+    return (0, crypto_1.randomBytes)(32).toString('hex');
+}

package/dist/server/auth/index.d.ts

@@ -0,0 +1,2 @@
+export { initAuth, getJwtSecret, extractToken, validateToken, generateToken, generateLongLivedToken } from './token';
+export { extractApiKey, hashApiKey, validateApiKey, generateApiKey } from './apiKey';