@markwharton/pwa-core 1.1.0 → 1.2.1

package/dist/__tests__/client/apiError.test.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const apiError_1 = require("../../client/apiError");
+(0, vitest_1.describe)('ApiError', () => {
+    (0, vitest_1.describe)('constructor', () => {
+        (0, vitest_1.it)('sets status, message, and name', () => {
+            const error = new apiError_1.ApiError(404, 'Not found');
+            (0, vitest_1.expect)(error.status).toBe(404);
+            (0, vitest_1.expect)(error.message).toBe('Not found');
+            (0, vitest_1.expect)(error.name).toBe('ApiError');
+        });
+        (0, vitest_1.it)('sets optional details', () => {
+            const error = new apiError_1.ApiError(400, 'Validation failed', 'Field "email" is required');
+            (0, vitest_1.expect)(error.details).toBe('Field "email" is required');
+        });
+        (0, vitest_1.it)('extends Error', () => {
+            const error = new apiError_1.ApiError(500, 'Server error');
+            (0, vitest_1.expect)(error).toBeInstanceOf(Error);
+        });
+    });
+    (0, vitest_1.describe)('isUnauthorized', () => {
+        (0, vitest_1.it)('returns true for 401 status', () => {
+            const error = new apiError_1.ApiError(401, 'Unauthorized');
+            (0, vitest_1.expect)(error.isUnauthorized()).toBe(true);
+        });
+        (0, vitest_1.it)('returns false for other statuses', () => {
+            (0, vitest_1.expect)(new apiError_1.ApiError(400, 'Bad request').isUnauthorized()).toBe(false);
+            (0, vitest_1.expect)(new apiError_1.ApiError(403, 'Forbidden').isUnauthorized()).toBe(false);
+            (0, vitest_1.expect)(new apiError_1.ApiError(404, 'Not found').isUnauthorized()).toBe(false);
+            (0, vitest_1.expect)(new apiError_1.ApiError(500, 'Server error').isUnauthorized()).toBe(false);
+        });
+    });
+    (0, vitest_1.describe)('isNotFound', () => {
+        (0, vitest_1.it)('returns true for 404 status', () => {
+            const error = new apiError_1.ApiError(404, 'Not found');
+            (0, vitest_1.expect)(error.isNotFound()).toBe(true);
+        });
+        (0, vitest_1.it)('returns false for other statuses', () => {
+            (0, vitest_1.expect)(new apiError_1.ApiError(400, 'Bad request').isNotFound()).toBe(false);
+            (0, vitest_1.expect)(new apiError_1.ApiError(401, 'Unauthorized').isNotFound()).toBe(false);
+            (0, vitest_1.expect)(new apiError_1.ApiError(403, 'Forbidden').isNotFound()).toBe(false);
+            (0, vitest_1.expect)(new apiError_1.ApiError(500, 'Server error').isNotFound()).toBe(false);
+        });
+    });
+    (0, vitest_1.describe)('isBadRequest', () => {
+        (0, vitest_1.it)('returns true for 400 status', () => {
+            const error = new apiError_1.ApiError(400, 'Bad request');
+            (0, vitest_1.expect)(error.isBadRequest()).toBe(true);
+        });
+        (0, vitest_1.it)('returns false for other statuses', () => {
+            (0, vitest_1.expect)(new apiError_1.ApiError(401, 'Unauthorized').isBadRequest()).toBe(false);
+            (0, vitest_1.expect)(new apiError_1.ApiError(403, 'Forbidden').isBadRequest()).toBe(false);
+            (0, vitest_1.expect)(new apiError_1.ApiError(404, 'Not found').isBadRequest()).toBe(false);
+            (0, vitest_1.expect)(new apiError_1.ApiError(500, 'Server error').isBadRequest()).toBe(false);
+        });
+    });
+});

package/dist/__tests__/http/responses.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/http/responses.test.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const responses_1 = require("../../http/responses");
+const status_1 = require("../../http/status");
+(0, vitest_1.describe)('HTTP response helpers', () => {
+    (0, vitest_1.describe)('badRequestResponse', () => {
+        (0, vitest_1.it)('returns 400 status with error message', () => {
+            const response = (0, responses_1.badRequestResponse)('Invalid input');
+            (0, vitest_1.expect)(response.status).toBe(status_1.HTTP_STATUS.BAD_REQUEST);
+            (0, vitest_1.expect)(response.jsonBody).toEqual({ error: 'Invalid input' });
+        });
+    });
+    (0, vitest_1.describe)('unauthorizedResponse', () => {
+        (0, vitest_1.it)('returns 401 status with default message', () => {
+            const response = (0, responses_1.unauthorizedResponse)();
+            (0, vitest_1.expect)(response.status).toBe(status_1.HTTP_STATUS.UNAUTHORIZED);
+            (0, vitest_1.expect)(response.jsonBody).toEqual({ error: 'Unauthorized' });
+        });
+        (0, vitest_1.it)('returns 401 status with custom message', () => {
+            const response = (0, responses_1.unauthorizedResponse)('Token expired');
+            (0, vitest_1.expect)(response.status).toBe(status_1.HTTP_STATUS.UNAUTHORIZED);
+            (0, vitest_1.expect)(response.jsonBody).toEqual({ error: 'Token expired' });
+        });
+    });
+    (0, vitest_1.describe)('forbiddenResponse', () => {
+        (0, vitest_1.it)('returns 403 status with default message', () => {
+            const response = (0, responses_1.forbiddenResponse)();
+            (0, vitest_1.expect)(response.status).toBe(status_1.HTTP_STATUS.FORBIDDEN);
+            (0, vitest_1.expect)(response.jsonBody).toEqual({ error: 'Forbidden' });
+        });
+        (0, vitest_1.it)('returns 403 status with custom message', () => {
+            const response = (0, responses_1.forbiddenResponse)('Admin access required');
+            (0, vitest_1.expect)(response.status).toBe(status_1.HTTP_STATUS.FORBIDDEN);
+            (0, vitest_1.expect)(response.jsonBody).toEqual({ error: 'Admin access required' });
+        });
+    });
+    (0, vitest_1.describe)('notFoundResponse', () => {
+        (0, vitest_1.it)('returns 404 status with resource name', () => {
+            const response = (0, responses_1.notFoundResponse)('User');
+            (0, vitest_1.expect)(response.status).toBe(status_1.HTTP_STATUS.NOT_FOUND);
+            (0, vitest_1.expect)(response.jsonBody).toEqual({ error: 'User not found' });
+        });
+    });
+    (0, vitest_1.describe)('conflictResponse', () => {
+        (0, vitest_1.it)('returns 409 status with error message', () => {
+            const response = (0, responses_1.conflictResponse)('Resource already exists');
+            (0, vitest_1.expect)(response.status).toBe(status_1.HTTP_STATUS.CONFLICT);
+            (0, vitest_1.expect)(response.jsonBody).toEqual({ error: 'Resource already exists' });
+        });
+    });
+    (0, vitest_1.describe)('handleFunctionError', () => {
+        (0, vitest_1.it)('logs error and returns 500 response', () => {
+            const mockContext = {
+                error: vitest_1.vi.fn()
+            };
+            const error = new Error('Database connection failed');
+            const response = (0, responses_1.handleFunctionError)(error, mockContext);
+            (0, vitest_1.expect)(response.status).toBe(status_1.HTTP_STATUS.INTERNAL_ERROR);
+            (0, vitest_1.expect)(response.jsonBody).toEqual({ error: 'Internal server error' });
+            (0, vitest_1.expect)(mockContext.error).toHaveBeenCalledWith('Function error: Database connection failed');
+        });
+        (0, vitest_1.it)('handles non-Error objects', () => {
+            const mockContext = {
+                error: vitest_1.vi.fn()
+            };
+            const response = (0, responses_1.handleFunctionError)('string error', mockContext);
+            (0, vitest_1.expect)(response.status).toBe(status_1.HTTP_STATUS.INTERNAL_ERROR);
+            (0, vitest_1.expect)(mockContext.error).toHaveBeenCalledWith('Function error: Unknown error');
+        });
+        (0, vitest_1.it)('handles null/undefined errors', () => {
+            const mockContext = {
+                error: vitest_1.vi.fn()
+            };
+            const response = (0, responses_1.handleFunctionError)(null, mockContext);
+            (0, vitest_1.expect)(response.status).toBe(status_1.HTTP_STATUS.INTERNAL_ERROR);
+            (0, vitest_1.expect)(mockContext.error).toHaveBeenCalledWith('Function error: Unknown error');
+        });
+    });
+    (0, vitest_1.describe)('isNotFoundError', () => {
+        (0, vitest_1.it)('returns true for 404 error', () => {
+            const error = Object.assign(new Error('Not found'), { statusCode: 404 });
+            (0, vitest_1.expect)((0, responses_1.isNotFoundError)(error)).toBe(true);
+        });
+        (0, vitest_1.it)('returns false for other status codes', () => {
+            const error = Object.assign(new Error('Conflict'), { statusCode: 409 });
+            (0, vitest_1.expect)((0, responses_1.isNotFoundError)(error)).toBe(false);
+        });
+        (0, vitest_1.it)('returns false for non-Error objects', () => {
+            (0, vitest_1.expect)((0, responses_1.isNotFoundError)({ statusCode: 404 })).toBe(false);
+        });
+        (0, vitest_1.it)('returns false for errors without statusCode', () => {
+            (0, vitest_1.expect)((0, responses_1.isNotFoundError)(new Error('Not found'))).toBe(false);
+        });
+    });
+    (0, vitest_1.describe)('isConflictError', () => {
+        (0, vitest_1.it)('returns true for 409 error', () => {
+            const error = Object.assign(new Error('Conflict'), { statusCode: 409 });
+            (0, vitest_1.expect)((0, responses_1.isConflictError)(error)).toBe(true);
+        });
+        (0, vitest_1.it)('returns false for other status codes', () => {
+            const error = Object.assign(new Error('Not found'), { statusCode: 404 });
+            (0, vitest_1.expect)((0, responses_1.isConflictError)(error)).toBe(false);
+        });
+        (0, vitest_1.it)('returns false for non-Error objects', () => {
+            (0, vitest_1.expect)((0, responses_1.isConflictError)({ statusCode: 409 })).toBe(false);
+        });
+        (0, vitest_1.it)('returns false for errors without statusCode', () => {
+            (0, vitest_1.expect)((0, responses_1.isConflictError)(new Error('Conflict'))).toBe(false);
+        });
+    });
+});

package/dist/__tests__/http/status.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/http/status.test.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const status_1 = require("../../http/status");
+(0, vitest_1.describe)('HTTP_STATUS', () => {
+    (0, vitest_1.it)('has correct status codes', () => {
+        (0, vitest_1.expect)(status_1.HTTP_STATUS.OK).toBe(200);
+        (0, vitest_1.expect)(status_1.HTTP_STATUS.CREATED).toBe(201);
+        (0, vitest_1.expect)(status_1.HTTP_STATUS.NO_CONTENT).toBe(204);
+        (0, vitest_1.expect)(status_1.HTTP_STATUS.BAD_REQUEST).toBe(400);
+        (0, vitest_1.expect)(status_1.HTTP_STATUS.UNAUTHORIZED).toBe(401);
+        (0, vitest_1.expect)(status_1.HTTP_STATUS.FORBIDDEN).toBe(403);
+        (0, vitest_1.expect)(status_1.HTTP_STATUS.NOT_FOUND).toBe(404);
+        (0, vitest_1.expect)(status_1.HTTP_STATUS.CONFLICT).toBe(409);
+        (0, vitest_1.expect)(status_1.HTTP_STATUS.GONE).toBe(410);
+        (0, vitest_1.expect)(status_1.HTTP_STATUS.INTERNAL_ERROR).toBe(500);
+        (0, vitest_1.expect)(status_1.HTTP_STATUS.SERVICE_UNAVAILABLE).toBe(503);
+    });
+    (0, vitest_1.it)('is immutable (const assertion)', () => {
+        // TypeScript const assertion makes the object readonly
+        // This test verifies the values haven't been accidentally modified
+        const statusCodes = Object.values(status_1.HTTP_STATUS);
+        (0, vitest_1.expect)(statusCodes).toContain(200);
+        (0, vitest_1.expect)(statusCodes).toContain(404);
+        (0, vitest_1.expect)(statusCodes).toContain(500);
+    });
+});

package/dist/__tests__/storage/client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/storage/client.test.js

@@ -0,0 +1,173 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+// Create mock functions
+const mockCreateTable = vitest_1.vi.fn();
+const mockFromConnectionString = vitest_1.vi.fn();
+// Mock @azure/data-tables
+vitest_1.vi.mock('@azure/data-tables', () => {
+    class MockTableClient {
+        constructor() {
+            this.createTable = mockCreateTable;
+        }
+    }
+    MockTableClient.fromConnectionString = mockFromConnectionString;
+    return {
+        TableClient: MockTableClient,
+        TableServiceClient: class MockTableServiceClient {
+        }
+    };
+});
+// Mock @azure/identity
+vitest_1.vi.mock('@azure/identity', () => ({
+    DefaultAzureCredential: class MockDefaultAzureCredential {
+    }
+}));
+(0, vitest_1.describe)('Storage client', () => {
+    (0, vitest_1.beforeEach)(() => {
+        vitest_1.vi.resetModules();
+        vitest_1.vi.clearAllMocks();
+        mockCreateTable.mockResolvedValue(undefined);
+        mockFromConnectionString.mockReturnValue({
+            createTable: vitest_1.vi.fn().mockResolvedValue(undefined)
+        });
+        // Reset environment
+        delete process.env.STORAGE_ACCOUNT_NAME;
+        delete process.env.AzureWebJobsStorage;
+    });
+    (0, vitest_1.describe)('initStorage', () => {
+        (0, vitest_1.it)('accepts configuration object', async () => {
+            const { initStorage, useManagedIdentity } = await Promise.resolve().then(() => __importStar(require('../../storage/client')));
+            initStorage({ accountName: 'myaccount' });
+            (0, vitest_1.expect)(useManagedIdentity()).toBe(true);
+        });
+        (0, vitest_1.it)('accepts connection string', async () => {
+            const { initStorage, useManagedIdentity } = await Promise.resolve().then(() => __importStar(require('../../storage/client')));
+            initStorage({ connectionString: 'DefaultEndpointsProtocol=https;AccountName=test' });
+            (0, vitest_1.expect)(useManagedIdentity()).toBe(false);
+        });
+    });
+    (0, vitest_1.describe)('initStorageFromEnv', () => {
+        (0, vitest_1.it)('reads STORAGE_ACCOUNT_NAME', async () => {
+            process.env.STORAGE_ACCOUNT_NAME = 'testaccount';
+            const { initStorageFromEnv, useManagedIdentity } = await Promise.resolve().then(() => __importStar(require('../../storage/client')));
+            initStorageFromEnv();
+            (0, vitest_1.expect)(useManagedIdentity()).toBe(true);
+        });
+        (0, vitest_1.it)('reads AzureWebJobsStorage', async () => {
+            process.env.AzureWebJobsStorage = 'UseDevelopmentStorage=true';
+            const { initStorageFromEnv, useManagedIdentity } = await Promise.resolve().then(() => __importStar(require('../../storage/client')));
+            initStorageFromEnv();
+            (0, vitest_1.expect)(useManagedIdentity()).toBe(false);
+        });
+    });
+    (0, vitest_1.describe)('useManagedIdentity', () => {
+        (0, vitest_1.it)('returns true when accountName is set without development storage', async () => {
+            const { initStorage, useManagedIdentity } = await Promise.resolve().then(() => __importStar(require('../../storage/client')));
+            initStorage({ accountName: 'prodaccount' });
+            (0, vitest_1.expect)(useManagedIdentity()).toBe(true);
+        });
+        (0, vitest_1.it)('returns false when using development storage', async () => {
+            const { initStorage, useManagedIdentity } = await Promise.resolve().then(() => __importStar(require('../../storage/client')));
+            initStorage({
+                accountName: 'devaccount',
+                connectionString: 'UseDevelopmentStorage=true'
+            });
+            (0, vitest_1.expect)(useManagedIdentity()).toBe(false);
+        });
+        (0, vitest_1.it)('returns false when only connection string is set', async () => {
+            const { initStorage, useManagedIdentity } = await Promise.resolve().then(() => __importStar(require('../../storage/client')));
+            initStorage({ connectionString: 'DefaultEndpointsProtocol=https' });
+            (0, vitest_1.expect)(useManagedIdentity()).toBe(false);
+        });
+    });
+    (0, vitest_1.describe)('getTableClient', () => {
+        (0, vitest_1.it)('throws if storage not configured', async () => {
+            const { getTableClient } = await Promise.resolve().then(() => __importStar(require('../../storage/client')));
+            await (0, vitest_1.expect)(getTableClient('test')).rejects.toThrow('Storage not configured. Set STORAGE_ACCOUNT_NAME or AzureWebJobsStorage.');
+        });
+        (0, vitest_1.it)('creates table client with managed identity', async () => {
+            const { initStorage, getTableClient, clearTableClientCache } = await Promise.resolve().then(() => __importStar(require('../../storage/client')));
+            initStorage({ accountName: 'testaccount' });
+            clearTableClientCache();
+            const client = await getTableClient('mytable');
+            (0, vitest_1.expect)(client).toBeDefined();
+        });
+        (0, vitest_1.it)('creates table client with connection string', async () => {
+            const { initStorage, getTableClient, clearTableClientCache } = await Promise.resolve().then(() => __importStar(require('../../storage/client')));
+            initStorage({ connectionString: 'DefaultEndpointsProtocol=https;AccountName=test' });
+            clearTableClientCache();
+            await getTableClient('mytable');
+            (0, vitest_1.expect)(mockFromConnectionString).toHaveBeenCalledWith('DefaultEndpointsProtocol=https;AccountName=test', 'mytable');
+        });
+        (0, vitest_1.it)('caches table client', async () => {
+            const { initStorage, getTableClient, clearTableClientCache } = await Promise.resolve().then(() => __importStar(require('../../storage/client')));
+            initStorage({ accountName: 'testaccount' });
+            clearTableClientCache();
+            const client1 = await getTableClient('mytable');
+            const client2 = await getTableClient('mytable');
+            (0, vitest_1.expect)(client1).toBe(client2);
+        });
+        (0, vitest_1.it)('handles 409 conflict (table exists)', async () => {
+            mockCreateTable.mockRejectedValue({ statusCode: 409 });
+            const { initStorage, getTableClient, clearTableClientCache } = await Promise.resolve().then(() => __importStar(require('../../storage/client')));
+            initStorage({ accountName: 'testaccount' });
+            clearTableClientCache();
+            // Should not throw
+            const client = await getTableClient('existingtable');
+            (0, vitest_1.expect)(client).toBeDefined();
+        });
+        (0, vitest_1.it)('throws on other errors', async () => {
+            mockCreateTable.mockRejectedValue({ statusCode: 500, message: 'Server error' });
+            const { initStorage, getTableClient, clearTableClientCache } = await Promise.resolve().then(() => __importStar(require('../../storage/client')));
+            initStorage({ accountName: 'testaccount' });
+            clearTableClientCache();
+            await (0, vitest_1.expect)(getTableClient('mytable')).rejects.toMatchObject({ statusCode: 500 });
+        });
+    });
+    (0, vitest_1.describe)('clearTableClientCache', () => {
+        (0, vitest_1.it)('clears cached clients', async () => {
+            const { initStorage, getTableClient, clearTableClientCache } = await Promise.resolve().then(() => __importStar(require('../../storage/client')));
+            initStorage({ accountName: 'testaccount' });
+            clearTableClientCache();
+            await getTableClient('mytable');
+            clearTableClientCache();
+            // After clearing, a new call should create a new client
+            const client2 = await getTableClient('mytable');
+            (0, vitest_1.expect)(client2).toBeDefined();
+        });
+    });
+});

package/dist/__tests__/storage/keys.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/storage/keys.test.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const keys_1 = require("../../storage/keys");
+(0, vitest_1.describe)('generateRowKey', () => {
+    (0, vitest_1.it)('returns 32-character hex string', () => {
+        const key = (0, keys_1.generateRowKey)('test-identifier');
+        (0, vitest_1.expect)(key).toHaveLength(32);
+        (0, vitest_1.expect)(key).toMatch(/^[a-f0-9]+$/);
+    });
+    (0, vitest_1.it)('produces consistent hash for same input', () => {
+        const key1 = (0, keys_1.generateRowKey)('same-input');
+        const key2 = (0, keys_1.generateRowKey)('same-input');
+        (0, vitest_1.expect)(key1).toBe(key2);
+    });
+    (0, vitest_1.it)('produces different hashes for different inputs', () => {
+        const key1 = (0, keys_1.generateRowKey)('input-1');
+        const key2 = (0, keys_1.generateRowKey)('input-2');
+        (0, vitest_1.expect)(key1).not.toBe(key2);
+    });
+    (0, vitest_1.it)('handles empty string', () => {
+        const key = (0, keys_1.generateRowKey)('');
+        (0, vitest_1.expect)(key).toHaveLength(32);
+        (0, vitest_1.expect)(key).toMatch(/^[a-f0-9]+$/);
+    });
+    (0, vitest_1.it)('handles special characters', () => {
+        const key = (0, keys_1.generateRowKey)('https://example.com/path?query=value&foo=bar');
+        (0, vitest_1.expect)(key).toHaveLength(32);
+        (0, vitest_1.expect)(key).toMatch(/^[a-f0-9]+$/);
+    });
+    (0, vitest_1.it)('handles unicode characters', () => {
+        const key = (0, keys_1.generateRowKey)('日本語テスト');
+        (0, vitest_1.expect)(key).toHaveLength(32);
+        (0, vitest_1.expect)(key).toMatch(/^[a-f0-9]+$/);
+    });
+    (0, vitest_1.it)('handles long strings', () => {
+        const longString = 'x'.repeat(10000);
+        const key = (0, keys_1.generateRowKey)(longString);
+        (0, vitest_1.expect)(key).toHaveLength(32);
+        (0, vitest_1.expect)(key).toMatch(/^[a-f0-9]+$/);
+    });
+    (0, vitest_1.it)('produces URL-safe keys', () => {
+        const key = (0, keys_1.generateRowKey)('some-identifier');
+        // Row keys should not contain these characters
+        (0, vitest_1.expect)(key).not.toMatch(/[\/\\#?\s]/);
+    });
+});

package/dist/__tests__/types.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/types.test.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const types_1 = require("../types");
+(0, vitest_1.describe)('Result helpers', () => {
+    (0, vitest_1.describe)('ok', () => {
+        (0, vitest_1.it)('creates success result with data', () => {
+            const result = (0, types_1.ok)({ name: 'test' });
+            (0, vitest_1.expect)(result.ok).toBe(true);
+            (0, vitest_1.expect)(result.data).toEqual({ name: 'test' });
+            (0, vitest_1.expect)(result.error).toBeUndefined();
+        });
+        (0, vitest_1.it)('works with primitive values', () => {
+            (0, vitest_1.expect)((0, types_1.ok)(42).data).toBe(42);
+            (0, vitest_1.expect)((0, types_1.ok)('hello').data).toBe('hello');
+            (0, vitest_1.expect)((0, types_1.ok)(true).data).toBe(true);
+        });
+        (0, vitest_1.it)('works with null', () => {
+            const result = (0, types_1.ok)(null);
+            (0, vitest_1.expect)(result.ok).toBe(true);
+            (0, vitest_1.expect)(result.data).toBeNull();
+        });
+    });
+    (0, vitest_1.describe)('okVoid', () => {
+        (0, vitest_1.it)('creates success result without data', () => {
+            const result = (0, types_1.okVoid)();
+            (0, vitest_1.expect)(result.ok).toBe(true);
+            (0, vitest_1.expect)(result.data).toBeUndefined();
+            (0, vitest_1.expect)(result.error).toBeUndefined();
+        });
+    });
+    (0, vitest_1.describe)('err', () => {
+        (0, vitest_1.it)('creates failure result with error message', () => {
+            const result = (0, types_1.err)('Something went wrong');
+            (0, vitest_1.expect)(result.ok).toBe(false);
+            (0, vitest_1.expect)(result.error).toBe('Something went wrong');
+            (0, vitest_1.expect)(result.data).toBeUndefined();
+            (0, vitest_1.expect)(result.statusCode).toBeUndefined();
+        });
+        (0, vitest_1.it)('creates failure result with status code', () => {
+            const result = (0, types_1.err)('Not found', 404);
+            (0, vitest_1.expect)(result.ok).toBe(false);
+            (0, vitest_1.expect)(result.error).toBe('Not found');
+            (0, vitest_1.expect)(result.statusCode).toBe(404);
+        });
+        (0, vitest_1.it)('excludes statusCode when not provided', () => {
+            const result = (0, types_1.err)('Error');
+            (0, vitest_1.expect)('statusCode' in result).toBe(false);
+        });
+        (0, vitest_1.it)('includes statusCode when provided', () => {
+            const result = (0, types_1.err)('Error', 500);
+            (0, vitest_1.expect)('statusCode' in result).toBe(true);
+            (0, vitest_1.expect)(result.statusCode).toBe(500);
+        });
+    });
+});

package/dist/auth/apiKey.d.ts

@@ -3,7 +3,11 @@ import { Result } from '../types';
  * API Key utilities for machine-to-machine authentication
  */
 /**
- * Extract API key from X-API-Key header
+ * 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: {
@@ -11,17 +15,30 @@ export declare function extractApiKey(request: {
     };
 }): string | null;
 /**
- * Hash an API key for secure storage
- * Store this hash, not the raw 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 });
  */
 export declare function hashApiKey(apiKey: string): string;
 /**
- * Validate API key against stored hash
- *
- * @returns Result indicating success or failure with error message
+ * 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>;
 /**
- * Generate a new API key (random 32-byte hex string)
+ * 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/auth/apiKey.js

@@ -10,22 +10,35 @@ const types_1 = require("../types");
  * API Key utilities for machine-to-machine authentication
  */
 /**
- * Extract API key from X-API-Key header
+ * 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');
 }
 /**
- * Hash an API key for secure storage
- * Store this hash, not the raw 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');
 }
 /**
- * Validate API key against stored hash
- *
- * @returns Result indicating success or failure with error message
+ * 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);
@@ -35,7 +48,11 @@ function validateApiKey(apiKey, storedHash) {
     return (0, types_1.err)('Invalid API key');
 }
 /**
- * Generate a new API key (random 32-byte hex string)
+ * 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');