@markwharton/pwa-core 1.2.0 → 1.3.0

package/dist/shared/auth/types.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Base JWT payload - all tokens include these fields
+ * Projects extend this with their specific fields
+ */
+export interface BaseJwtPayload {
+    iat: number;
+    exp: number;
+}
+/**
+ * Standard user token payload
+ * Used by: azure-pwa-starter, azure-alert-service (admin), onsite-monitor
+ */
+export interface UserTokenPayload extends BaseJwtPayload {
+    authenticated: true;
+    tokenType: 'user' | 'machine';
+}
+/**
+ * Username-based token payload
+ * Used by: financial-tracker
+ */
+export interface UsernameTokenPayload extends BaseJwtPayload {
+    username: string;
+}
+/**
+ * Role-based token payload
+ * Used by: azure-alert-service
+ */
+export interface RoleTokenPayload extends BaseJwtPayload {
+    authenticated: true;
+    tokenType: 'user' | 'machine';
+    role: 'admin' | 'viewer';
+    viewerTokenId?: string;
+}
+/**
+ * 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 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;
+/**
+ * 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/shared/auth/types.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasUsername = hasUsername;
+exports.hasRole = hasRole;
+exports.isAdmin = isAdmin;
+/**
+ * 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 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;
+}
+/**
+ * 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/shared/http/index.d.ts

@@ -0,0 +1,3 @@
+export { HTTP_STATUS } from './status';
+export type { HttpStatus } from './status';
+export type { ErrorResponse } from './types';

package/dist/shared/http/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HTTP_STATUS = void 0;
+var status_1 = require("./status");
+Object.defineProperty(exports, "HTTP_STATUS", { enumerable: true, get: function () { return status_1.HTTP_STATUS; } });

package/dist/shared/http/status.d.ts

@@ -0,0 +1,17 @@
+/**
+ * HTTP status codes - use instead of magic numbers
+ */
+export declare const HTTP_STATUS: {
+    readonly OK: 200;
+    readonly CREATED: 201;
+    readonly NO_CONTENT: 204;
+    readonly BAD_REQUEST: 400;
+    readonly UNAUTHORIZED: 401;
+    readonly FORBIDDEN: 403;
+    readonly NOT_FOUND: 404;
+    readonly CONFLICT: 409;
+    readonly GONE: 410;
+    readonly INTERNAL_ERROR: 500;
+    readonly SERVICE_UNAVAILABLE: 503;
+};
+export type HttpStatus = typeof HTTP_STATUS[keyof typeof HTTP_STATUS];

package/dist/shared/http/status.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HTTP_STATUS = void 0;
+/**
+ * HTTP status codes - use instead of magic numbers
+ */
+exports.HTTP_STATUS = {
+    OK: 200,
+    CREATED: 201,
+    NO_CONTENT: 204,
+    BAD_REQUEST: 400,
+    UNAUTHORIZED: 401,
+    FORBIDDEN: 403,
+    NOT_FOUND: 404,
+    CONFLICT: 409,
+    GONE: 410,
+    INTERNAL_ERROR: 500,
+    SERVICE_UNAVAILABLE: 503
+};

package/dist/shared/http/types.d.ts

@@ -0,0 +1,10 @@
+/**
+ * HTTP module type definitions
+ */
+/**
+ * Standard error response structure
+ */
+export interface ErrorResponse {
+    error: string;
+    details?: string;
+}

package/dist/shared/http/types.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * HTTP module type definitions
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/shared/index.d.ts

@@ -0,0 +1,5 @@
+export type { BaseJwtPayload, UserTokenPayload, UsernameTokenPayload, RoleTokenPayload } from './auth';
+export { hasUsername, hasRole, isAdmin } from './auth';
+export { HTTP_STATUS } from './http';
+export type { HttpStatus } from './http';
+export type { ErrorResponse } from './http';

package/dist/shared/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HTTP_STATUS = exports.isAdmin = exports.hasRole = exports.hasUsername = void 0;
+var auth_1 = require("./auth");
+Object.defineProperty(exports, "hasUsername", { enumerable: true, get: function () { return auth_1.hasUsername; } });
+Object.defineProperty(exports, "hasRole", { enumerable: true, get: function () { return auth_1.hasRole; } });
+Object.defineProperty(exports, "isAdmin", { enumerable: true, get: function () { return auth_1.isAdmin; } });
+// HTTP
+var http_1 = require("./http");
+Object.defineProperty(exports, "HTTP_STATUS", { enumerable: true, get: function () { return http_1.HTTP_STATUS; } });

package/dist/storage/client.d.ts

@@ -1,25 +1,48 @@
 import { TableClient } from '@azure/data-tables';
 /**
- * Initialize storage configuration - call once at startup
+ * Initializes Azure Table Storage configuration. Call once at application startup.
+ * @param config - Storage configuration options
+ * @param config.accountName - Azure Storage account name (for managed identity)
+ * @param config.connectionString - Connection string (for local development)
+ * @example
+ * // Production (Azure with managed identity)
+ * initStorage({ accountName: 'mystorageaccount' });
+ *
+ * // Local development (Azurite)
+ * initStorage({ connectionString: 'UseDevelopmentStorage=true' });
  */
 export declare function initStorage(config: {
     accountName?: string;
     connectionString?: string;
 }): void;
 /**
- * Auto-initialize from environment variables
+ * Initializes storage from environment variables.
+ * Reads STORAGE_ACCOUNT_NAME and AzureWebJobsStorage.
+ * @example
+ * initStorageFromEnv(); // Uses process.env automatically
  */
 export declare function initStorageFromEnv(): void;
 /**
- * Check if using managed identity (Azure) vs connection string (local)
+ * Checks if using Azure managed identity vs local connection string.
+ * @returns True if using managed identity (production), false for connection string (local)
  */
 export declare function useManagedIdentity(): boolean;
 /**
- * Get a TableClient for the specified table
- * Creates table if it doesn't exist, caches client for reuse
+ * Gets a TableClient for the specified table, creating the table if needed.
+ * Clients are cached for reuse across requests.
+ * @param tableName - The Azure Table Storage table name
+ * @returns A configured TableClient instance
+ * @throws Error if storage is not configured
+ * @example
+ * const client = await getTableClient('users');
+ * await client.createEntity({ partitionKey: 'pk', rowKey: 'rk', name: 'John' });
  */
 export declare function getTableClient(tableName: string): Promise<TableClient>;
 /**
- * Clear the client cache (useful for testing)
+ * Clears the TableClient cache. Primarily useful for testing.
+ * @example
+ * afterEach(() => {
+ *   clearTableClientCache();
+ * });
  */
 export declare function clearTableClientCache(): void;

package/dist/storage/client.js

@@ -16,14 +16,26 @@ const tableClients = new Map();
 let storageAccountName;
 let connectionString;
 /**
- * Initialize storage configuration - call once at startup
+ * Initializes Azure Table Storage configuration. Call once at application startup.
+ * @param config - Storage configuration options
+ * @param config.accountName - Azure Storage account name (for managed identity)
+ * @param config.connectionString - Connection string (for local development)
+ * @example
+ * // Production (Azure with managed identity)
+ * initStorage({ accountName: 'mystorageaccount' });
+ *
+ * // Local development (Azurite)
+ * initStorage({ connectionString: 'UseDevelopmentStorage=true' });
  */
 function initStorage(config) {
     storageAccountName = config.accountName;
     connectionString = config.connectionString;
 }
 /**
- * Auto-initialize from environment variables
+ * Initializes storage from environment variables.
+ * Reads STORAGE_ACCOUNT_NAME and AzureWebJobsStorage.
+ * @example
+ * initStorageFromEnv(); // Uses process.env automatically
  */
 function initStorageFromEnv() {
     initStorage({
@@ -32,14 +44,21 @@ function initStorageFromEnv() {
     });
 }
 /**
- * Check if using managed identity (Azure) vs connection string (local)
+ * Checks if using Azure managed identity vs local connection string.
+ * @returns True if using managed identity (production), false for connection string (local)
  */
 function useManagedIdentity() {
     return !!storageAccountName && !connectionString?.includes('UseDevelopmentStorage');
 }
 /**
- * Get a TableClient for the specified table
- * Creates table if it doesn't exist, caches client for reuse
+ * Gets a TableClient for the specified table, creating the table if needed.
+ * Clients are cached for reuse across requests.
+ * @param tableName - The Azure Table Storage table name
+ * @returns A configured TableClient instance
+ * @throws Error if storage is not configured
+ * @example
+ * const client = await getTableClient('users');
+ * await client.createEntity({ partitionKey: 'pk', rowKey: 'rk', name: 'John' });
  */
 async function getTableClient(tableName) {
     // Return cached client if available
@@ -77,7 +96,11 @@ async function getTableClient(tableName) {
     return client;
 }
 /**
- * Clear the client cache (useful for testing)
+ * Clears the TableClient cache. Primarily useful for testing.
+ * @example
+ * afterEach(() => {
+ *   clearTableClientCache();
+ * });
  */
 function clearTableClientCache() {
     tableClients.clear();

package/dist/types.d.ts

@@ -22,14 +22,27 @@ export interface Result<T> {
     statusCode?: number;
 }
 /**
- * Helper to create a success result
+ * Creates a success result with data.
+ * @param data - The success payload
+ * @returns A Result with ok=true and the provided data
+ * @example
+ * return ok({ user: 'john', role: 'admin' });
  */
 export declare function ok<T>(data: T): Result<T>;
 /**
- * Helper to create a success result with no data
+ * Creates a success result with no data.
+ * @returns A Result with ok=true and no data
+ * @example
+ * return okVoid(); // { ok: true }
  */
 export declare function okVoid(): Result<void>;
 /**
- * Helper to create a failure result
+ * Creates a failure result with an error message.
+ * @param error - The error message
+ * @param statusCode - 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>;

package/dist/types.js

@@ -7,19 +7,32 @@ exports.ok = ok;
 exports.okVoid = okVoid;
 exports.err = err;
 /**
- * Helper to create a success result
+ * Creates a success result with data.
+ * @param data - The success payload
+ * @returns A Result with ok=true and the provided data
+ * @example
+ * return ok({ user: 'john', role: 'admin' });
  */
 function ok(data) {
     return { ok: true, data };
 }
 /**
- * Helper to create a success result with no data
+ * Creates a success result with no data.
+ * @returns A Result with ok=true and no data
+ * @example
+ * return okVoid(); // { ok: true }
  */
 function okVoid() {
     return { ok: true };
 }
 /**
- * Helper to create a failure result
+ * Creates a failure result with an error message.
+ * @param error - The error message
+ * @param statusCode - 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

package/package.json

@@ -1,33 +1,29 @@
 {
   "name": "@markwharton/pwa-core",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Shared patterns for Azure PWA projects",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": "./dist/index.js",
     "./types": "./dist/types.js",
-    "./auth": "./dist/auth/index.js",
-    "./http": "./dist/http/index.js",
-    "./storage": "./dist/storage/index.js",
-    "./client": "./dist/client/index.js"
+    "./server": "./dist/server/index.js",
+    "./client": "./dist/client/index.js",
+    "./shared": "./dist/shared/index.js"
   },
   "typesVersions": {
     "*": {
       "types": [
         "dist/types.d.ts"
       ],
-      "auth": [
-        "dist/auth/index.d.ts"
-      ],
-      "http": [
-        "dist/http/index.d.ts"
-      ],
-      "storage": [
-        "dist/storage/index.d.ts"
+      "server": [
+        "dist/server/index.d.ts"
       ],
       "client": [
         "dist/client/index.d.ts"
+      ],
+      "shared": [
+        "dist/shared/index.d.ts"
       ]
     }
   },