@markwharton/pwa-core 1.1.0 → 1.2.1

package/dist/auth/token.d.ts

@@ -1,29 +1,56 @@
 import { Result } from '../types';
 /**
- * Initialize JWT secret - call once at startup
- * Fails fast if secret is missing or too short
+ * Initializes the JWT authentication system. Call once at application startup.
+ * @param secret - The JWT secret key (from environment variable)
+ * @param minLength - Minimum required secret length (default: 32)
+ * @throws Error if secret is missing or too short
+ * @example
+ * initAuth(process.env.JWT_SECRET);
  */
 export declare function initAuth(secret: string | undefined, minLength?: number): void;
 /**
- * Get the JWT secret (throws if not initialized)
+ * Gets the configured JWT secret.
+ * @returns The JWT secret string
+ * @throws Error if initAuth() has not been called
  */
 export declare function getJwtSecret(): string;
 /**
- * Extract Bearer token from Authorization header
+ * Extracts the Bearer token from an Authorization header.
+ * @param authHeader - The Authorization header value
+ * @returns The token string, or null if not a valid Bearer token
+ * @example
+ * const token = extractToken(request.headers.get('Authorization'));
  */
 export declare function extractToken(authHeader: string | null): string | null;
 /**
- * Validate and decode a JWT token
- * Generic type allows project-specific payload shapes
- *
- * @returns Result with decoded payload or error message
+ * Validates and decodes a JWT token.
+ * @typeParam T - The expected payload type (extends object)
+ * @param token - The JWT token string to validate
+ * @returns Result with decoded payload on success, or error message on failure
+ * @example
+ * const result = validateToken<UserPayload>(token);
+ * if (result.ok) {
+ *   console.log(result.data.username);
+ * }
  */
 export declare function validateToken<T extends object>(token: string): Result<T>;
 /**
- * Generate a JWT token with custom payload
+ * Generates a signed JWT token with the given payload.
+ * @typeParam T - The payload type (extends object)
+ * @param payload - The data to encode in the token
+ * @param expiresIn - Token expiration time (default: '7d')
+ * @returns The signed JWT token string
+ * @example
+ * const token = generateToken({ userId: '123', role: 'admin' }, '1h');
  */
 export declare function generateToken<T extends object>(payload: T, expiresIn?: string): string;
 /**
- * Generate a long-lived token (e.g., for machine/API access)
+ * Generates a long-lived JWT token for machine/API access.
+ * @typeParam T - The payload type (extends object)
+ * @param payload - The data to encode in the token
+ * @param expiresInDays - Token expiration in days (default: 3650 ≈ 10 years)
+ * @returns The signed JWT token string
+ * @example
+ * const apiToken = generateLongLivedToken({ machineId: 'server-1' });
  */
 export declare function generateLongLivedToken<T extends object>(payload: T, expiresInDays?: number): string;

package/dist/auth/token.js

@@ -17,8 +17,12 @@ const types_1 = require("../types");
  */
 let jwtSecret = null;
 /**
- * Initialize JWT secret - call once at startup
- * Fails fast if secret is missing or too short
+ * Initializes the JWT authentication system. Call once at application startup.
+ * @param secret - The JWT secret key (from environment variable)
+ * @param minLength - Minimum required secret length (default: 32)
+ * @throws Error if secret is missing or too short
+ * @example
+ * initAuth(process.env.JWT_SECRET);
  */
 function initAuth(secret, minLength = 32) {
     if (!secret || secret.length < minLength) {
@@ -27,7 +31,9 @@ function initAuth(secret, minLength = 32) {
     jwtSecret = secret;
 }
 /**
- * Get the JWT secret (throws if not initialized)
+ * Gets the configured JWT secret.
+ * @returns The JWT secret string
+ * @throws Error if initAuth() has not been called
  */
 function getJwtSecret() {
     if (!jwtSecret) {
@@ -36,7 +42,11 @@ function getJwtSecret() {
     return jwtSecret;
 }
 /**
- * Extract Bearer token from Authorization header
+ * Extracts the Bearer token from an Authorization header.
+ * @param authHeader - The Authorization header value
+ * @returns The token string, or null if not a valid Bearer token
+ * @example
+ * const token = extractToken(request.headers.get('Authorization'));
  */
 function extractToken(authHeader) {
     if (!authHeader?.startsWith('Bearer ')) {
@@ -45,10 +55,15 @@ function extractToken(authHeader) {
     return authHeader.slice(7);
 }
 /**
- * Validate and decode a JWT token
- * Generic type allows project-specific payload shapes
- *
- * @returns Result with decoded payload or error message
+ * Validates and decodes a JWT token.
+ * @typeParam T - The expected payload type (extends object)
+ * @param token - The JWT token string to validate
+ * @returns Result with decoded payload on success, or error message on failure
+ * @example
+ * const result = validateToken<UserPayload>(token);
+ * if (result.ok) {
+ *   console.log(result.data.username);
+ * }
  */
 function validateToken(token) {
     try {
@@ -64,13 +79,25 @@ function validateToken(token) {
     }
 }
 /**
- * Generate a JWT token with custom payload
+ * Generates a signed JWT token with the given payload.
+ * @typeParam T - The payload type (extends object)
+ * @param payload - The data to encode in the token
+ * @param expiresIn - Token expiration time (default: '7d')
+ * @returns The signed JWT token string
+ * @example
+ * const token = generateToken({ userId: '123', role: 'admin' }, '1h');
  */
 function generateToken(payload, expiresIn = '7d') {
     return jsonwebtoken_1.default.sign(payload, getJwtSecret(), { expiresIn });
 }
 /**
- * Generate a long-lived token (e.g., for machine/API access)
+ * Generates a long-lived JWT token for machine/API access.
+ * @typeParam T - The payload type (extends object)
+ * @param payload - The data to encode in the token
+ * @param expiresInDays - Token expiration in days (default: 3650 ≈ 10 years)
+ * @returns The signed JWT token string
+ * @example
+ * const apiToken = generateLongLivedToken({ machineId: 'server-1' });
  */
 function generateLongLivedToken(payload, expiresInDays = 3650) {
     return jsonwebtoken_1.default.sign(payload, getJwtSecret(), { expiresIn: `${expiresInDays}d` });

package/dist/auth/types.d.ts

@@ -32,14 +32,32 @@ export interface RoleTokenPayload extends BaseJwtPayload {
     viewerTokenId?: string;
 }
 /**
- * Type guard to check if payload has a username
+ * Type guard to check if a JWT payload contains a username field.
+ * @param payload - The JWT payload to check
+ * @returns True if payload has a string username field
+ * @example
+ * if (hasUsername(payload)) {
+ *   console.log(payload.username); // TypeScript knows username exists
+ * }
  */
 export declare function hasUsername(payload: BaseJwtPayload): payload is UsernameTokenPayload;
 /**
- * Type guard to check if payload has a role
+ * Type guard to check if a JWT payload contains a role field.
+ * @param payload - The JWT payload to check
+ * @returns True if payload has a role field
+ * @example
+ * if (hasRole(payload)) {
+ *   console.log(payload.role); // 'admin' | 'viewer'
+ * }
  */
 export declare function hasRole(payload: BaseJwtPayload): payload is RoleTokenPayload;
 /**
- * Type guard to check if payload is admin
+ * Checks if a JWT payload represents an admin user.
+ * @param payload - The JWT payload to check
+ * @returns True if payload has role='admin'
+ * @example
+ * if (!isAdmin(payload)) {
+ *   return httpForbidden('Admin access required');
+ * }
  */
 export declare function isAdmin(payload: BaseJwtPayload): boolean;

package/dist/auth/types.js

@@ -4,19 +4,37 @@ exports.hasUsername = hasUsername;
 exports.hasRole = hasRole;
 exports.isAdmin = isAdmin;
 /**
- * Type guard to check if payload has a username
+ * Type guard to check if a JWT payload contains a username field.
+ * @param payload - The JWT payload to check
+ * @returns True if payload has a string username field
+ * @example
+ * if (hasUsername(payload)) {
+ *   console.log(payload.username); // TypeScript knows username exists
+ * }
  */
 function hasUsername(payload) {
     return 'username' in payload && typeof payload.username === 'string';
 }
 /**
- * Type guard to check if payload has a role
+ * Type guard to check if a JWT payload contains a role field.
+ * @param payload - The JWT payload to check
+ * @returns True if payload has a role field
+ * @example
+ * if (hasRole(payload)) {
+ *   console.log(payload.role); // 'admin' | 'viewer'
+ * }
  */
 function hasRole(payload) {
     return 'role' in payload;
 }
 /**
- * Type guard to check if payload is admin
+ * Checks if a JWT payload represents an admin user.
+ * @param payload - The JWT payload to check
+ * @returns True if payload has role='admin'
+ * @example
+ * if (!isAdmin(payload)) {
+ *   return httpForbidden('Admin access required');
+ * }
  */
 function isAdmin(payload) {
     return hasRole(payload) && payload.role === 'admin';

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;