lsh-framework 3.1.5 → 3.1.7

package/dist/lib/lsh-error.js

@@ -0,0 +1,406 @@
+/**
+ * LSH Error Handling Utilities
+ *
+ * Provides standardized error handling across the LSH codebase:
+ * - LSHError class for structured errors with codes and context
+ * - Error extraction utilities for safe error handling in catch blocks
+ * - Error code constants for consistent error identification
+ *
+ * @example
+ * ```typescript
+ * import { LSHError, ErrorCodes, extractErrorMessage } from './lsh-error.js';
+ *
+ * // Throw a structured error
+ * throw new LSHError(
+ *   ErrorCodes.SECRETS_ENCRYPTION_FAILED,
+ *   'Failed to encrypt secret',
+ *   { secretKey: 'DATABASE_URL', teamId: 'team_123' }
+ * );
+ *
+ * // Safe error extraction in catch block
+ * try {
+ *   await doSomething();
+ * } catch (error) {
+ *   console.error(extractErrorMessage(error));
+ * }
+ * ```
+ */
+// ============================================================================
+// ERROR CODES
+// ============================================================================
+/**
+ * Standardized error codes for LSH operations.
+ * Use these instead of magic strings for consistent error handling.
+ *
+ * Naming convention: CATEGORY_SPECIFIC_ERROR
+ * - AUTH_* : Authentication errors
+ * - SECRETS_* : Secrets management errors
+ * - DB_* : Database errors
+ * - DAEMON_* : Daemon/job errors
+ * - API_* : API server errors
+ * - CONFIG_* : Configuration errors
+ * - VALIDATION_* : Input validation errors
+ */
+export const ErrorCodes = {
+    // Authentication errors
+    AUTH_UNAUTHORIZED: 'AUTH_UNAUTHORIZED',
+    AUTH_INVALID_CREDENTIALS: 'AUTH_INVALID_CREDENTIALS',
+    AUTH_EMAIL_NOT_VERIFIED: 'AUTH_EMAIL_NOT_VERIFIED',
+    AUTH_EMAIL_ALREADY_EXISTS: 'AUTH_EMAIL_ALREADY_EXISTS',
+    AUTH_INVALID_TOKEN: 'AUTH_INVALID_TOKEN',
+    AUTH_TOKEN_EXPIRED: 'AUTH_TOKEN_EXPIRED',
+    AUTH_FORBIDDEN: 'AUTH_FORBIDDEN',
+    AUTH_INSUFFICIENT_PERMISSIONS: 'AUTH_INSUFFICIENT_PERMISSIONS',
+    // Secrets management errors
+    SECRETS_ENCRYPTION_FAILED: 'SECRETS_ENCRYPTION_FAILED',
+    SECRETS_DECRYPTION_FAILED: 'SECRETS_DECRYPTION_FAILED',
+    SECRETS_KEY_NOT_FOUND: 'SECRETS_KEY_NOT_FOUND',
+    SECRETS_PUSH_FAILED: 'SECRETS_PUSH_FAILED',
+    SECRETS_PULL_FAILED: 'SECRETS_PULL_FAILED',
+    SECRETS_ROTATION_FAILED: 'SECRETS_ROTATION_FAILED',
+    SECRETS_ENV_PARSE_FAILED: 'SECRETS_ENV_PARSE_FAILED',
+    SECRETS_NOT_FOUND: 'SECRETS_NOT_FOUND',
+    // Database errors
+    DB_CONNECTION_FAILED: 'DB_CONNECTION_FAILED',
+    DB_QUERY_FAILED: 'DB_QUERY_FAILED',
+    DB_NOT_FOUND: 'DB_NOT_FOUND',
+    DB_ALREADY_EXISTS: 'DB_ALREADY_EXISTS',
+    DB_CONSTRAINT_VIOLATION: 'DB_CONSTRAINT_VIOLATION',
+    DB_TIMEOUT: 'DB_TIMEOUT',
+    // Daemon errors
+    DAEMON_NOT_RUNNING: 'DAEMON_NOT_RUNNING',
+    DAEMON_ALREADY_RUNNING: 'DAEMON_ALREADY_RUNNING',
+    DAEMON_START_FAILED: 'DAEMON_START_FAILED',
+    DAEMON_STOP_FAILED: 'DAEMON_STOP_FAILED',
+    DAEMON_CONNECTION_FAILED: 'DAEMON_CONNECTION_FAILED',
+    DAEMON_IPC_ERROR: 'DAEMON_IPC_ERROR',
+    // Job errors
+    JOB_NOT_FOUND: 'JOB_NOT_FOUND',
+    JOB_ALREADY_RUNNING: 'JOB_ALREADY_RUNNING',
+    JOB_START_FAILED: 'JOB_START_FAILED',
+    JOB_STOP_FAILED: 'JOB_STOP_FAILED',
+    JOB_TIMEOUT: 'JOB_TIMEOUT',
+    JOB_INVALID_SCHEDULE: 'JOB_INVALID_SCHEDULE',
+    // API errors
+    API_NOT_CONFIGURED: 'API_NOT_CONFIGURED',
+    API_INVALID_REQUEST: 'API_INVALID_REQUEST',
+    API_RATE_LIMITED: 'API_RATE_LIMITED',
+    API_INTERNAL_ERROR: 'API_INTERNAL_ERROR',
+    API_WEBHOOK_VERIFICATION_FAILED: 'API_WEBHOOK_VERIFICATION_FAILED',
+    // Configuration errors
+    CONFIG_MISSING_ENV_VAR: 'CONFIG_MISSING_ENV_VAR',
+    CONFIG_INVALID_VALUE: 'CONFIG_INVALID_VALUE',
+    CONFIG_FILE_NOT_FOUND: 'CONFIG_FILE_NOT_FOUND',
+    CONFIG_PARSE_ERROR: 'CONFIG_PARSE_ERROR',
+    // Validation errors
+    VALIDATION_REQUIRED_FIELD: 'VALIDATION_REQUIRED_FIELD',
+    VALIDATION_INVALID_FORMAT: 'VALIDATION_INVALID_FORMAT',
+    VALIDATION_OUT_OF_RANGE: 'VALIDATION_OUT_OF_RANGE',
+    VALIDATION_COMMAND_INJECTION: 'VALIDATION_COMMAND_INJECTION',
+    // Billing errors
+    BILLING_TIER_LIMIT_EXCEEDED: 'BILLING_TIER_LIMIT_EXCEEDED',
+    BILLING_SUBSCRIPTION_REQUIRED: 'BILLING_SUBSCRIPTION_REQUIRED',
+    BILLING_PAYMENT_REQUIRED: 'BILLING_PAYMENT_REQUIRED',
+    BILLING_STRIPE_ERROR: 'BILLING_STRIPE_ERROR',
+    // Resource errors
+    RESOURCE_NOT_FOUND: 'RESOURCE_NOT_FOUND',
+    RESOURCE_ALREADY_EXISTS: 'RESOURCE_ALREADY_EXISTS',
+    RESOURCE_CONFLICT: 'RESOURCE_CONFLICT',
+    // General errors
+    INTERNAL_ERROR: 'INTERNAL_ERROR',
+    NOT_IMPLEMENTED: 'NOT_IMPLEMENTED',
+    SERVICE_UNAVAILABLE: 'SERVICE_UNAVAILABLE',
+};
+// ============================================================================
+// LSH ERROR CLASS
+// ============================================================================
+/**
+ * Structured error class for LSH operations.
+ *
+ * Features:
+ * - Error code for programmatic handling
+ * - Context object for debugging information
+ * - HTTP status code mapping for API responses
+ * - Stack trace preservation
+ * - Serialization support
+ *
+ * @example
+ * ```typescript
+ * throw new LSHError(
+ *   ErrorCodes.SECRETS_NOT_FOUND,
+ *   'Secret not found',
+ *   { secretId: 'secret_123', environment: 'production' }
+ * );
+ * ```
+ */
+export class LSHError extends Error {
+    /** Error code for programmatic handling */
+    code;
+    /** Additional context for debugging */
+    context;
+    /** HTTP status code for API responses */
+    statusCode;
+    /** Timestamp when error occurred */
+    timestamp;
+    constructor(code, message, context, statusCode) {
+        super(message);
+        this.name = 'LSHError';
+        this.code = code;
+        this.context = context;
+        this.statusCode = statusCode ?? getDefaultStatusCode(code);
+        this.timestamp = new Date();
+        // Maintain proper stack trace in V8 environments
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, LSHError);
+        }
+    }
+    /**
+     * Serialize error for logging or API response.
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            context: this.context,
+            statusCode: this.statusCode,
+            timestamp: this.timestamp.toISOString(),
+            stack: this.stack,
+        };
+    }
+    /**
+     * Create user-friendly string representation.
+     */
+    toString() {
+        const contextStr = this.context ? ` (${JSON.stringify(this.context)})` : '';
+        return `[${this.code}] ${this.message}${contextStr}`;
+    }
+}
+// ============================================================================
+// ERROR UTILITIES
+// ============================================================================
+/**
+ * Safely extract error message from unknown error type.
+ * Use this in catch blocks instead of (error as Error).message.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await riskyOperation();
+ * } catch (error) {
+ *   console.error('Failed:', extractErrorMessage(error));
+ * }
+ * ```
+ */
+export function extractErrorMessage(error) {
+    if (error instanceof LSHError) {
+        return error.toString();
+    }
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    if (error && typeof error === 'object' && 'message' in error) {
+        return String(error.message);
+    }
+    return String(error);
+}
+/**
+ * Safely extract error details for logging.
+ * Returns structured object with message, stack, and code if available.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await riskyOperation();
+ * } catch (error) {
+ *   logger.error('Operation failed', extractErrorDetails(error));
+ * }
+ * ```
+ */
+export function extractErrorDetails(error) {
+    if (error instanceof LSHError) {
+        return {
+            message: error.message,
+            stack: error.stack,
+            code: error.code,
+            context: error.context,
+        };
+    }
+    if (error instanceof Error) {
+        return {
+            message: error.message,
+            stack: error.stack,
+            code: error.code,
+        };
+    }
+    return {
+        message: extractErrorMessage(error),
+    };
+}
+/**
+ * Check if an error is an LSHError with a specific code.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await getSecret();
+ * } catch (error) {
+ *   if (isLSHError(error, ErrorCodes.SECRETS_NOT_FOUND)) {
+ *     // Handle not found case
+ *   }
+ *   throw error;
+ * }
+ * ```
+ */
+export function isLSHError(error, code) {
+    if (!(error instanceof LSHError))
+        return false;
+    if (code && error.code !== code)
+        return false;
+    return true;
+}
+/**
+ * Wrap an unknown error as an LSHError.
+ * Useful for ensuring consistent error types in APIs.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await externalApi.call();
+ * } catch (error) {
+ *   throw wrapAsLSHError(error, ErrorCodes.API_INTERNAL_ERROR);
+ * }
+ * ```
+ */
+export function wrapAsLSHError(error, code = ErrorCodes.INTERNAL_ERROR, context) {
+    if (error instanceof LSHError) {
+        // Add additional context if provided
+        if (context) {
+            return new LSHError(error.code, error.message, {
+                ...error.context,
+                ...context,
+            });
+        }
+        return error;
+    }
+    const message = extractErrorMessage(error);
+    const details = extractErrorDetails(error);
+    return new LSHError(code, message, {
+        ...context,
+        originalStack: details.stack,
+        originalCode: details.code,
+    });
+}
+// ============================================================================
+// HTTP STATUS CODE MAPPING
+// ============================================================================
+/**
+ * Get default HTTP status code for an error code.
+ * Used by LSHError constructor and API responses.
+ */
+function getDefaultStatusCode(code) {
+    // 400 Bad Request
+    if (code.startsWith('VALIDATION_'))
+        return 400;
+    if (code === ErrorCodes.API_INVALID_REQUEST)
+        return 400;
+    if (code === ErrorCodes.CONFIG_INVALID_VALUE)
+        return 400;
+    // 401 Unauthorized
+    if (code === ErrorCodes.AUTH_UNAUTHORIZED)
+        return 401;
+    if (code === ErrorCodes.AUTH_INVALID_CREDENTIALS)
+        return 401;
+    if (code === ErrorCodes.AUTH_INVALID_TOKEN)
+        return 401;
+    if (code === ErrorCodes.AUTH_TOKEN_EXPIRED)
+        return 401;
+    // 402 Payment Required
+    if (code === ErrorCodes.BILLING_PAYMENT_REQUIRED)
+        return 402;
+    if (code === ErrorCodes.BILLING_SUBSCRIPTION_REQUIRED)
+        return 402;
+    // 403 Forbidden
+    if (code === ErrorCodes.AUTH_FORBIDDEN)
+        return 403;
+    if (code === ErrorCodes.AUTH_INSUFFICIENT_PERMISSIONS)
+        return 403;
+    if (code === ErrorCodes.AUTH_EMAIL_NOT_VERIFIED)
+        return 403;
+    // 404 Not Found
+    if (code.endsWith('_NOT_FOUND'))
+        return 404;
+    if (code === ErrorCodes.DB_NOT_FOUND)
+        return 404;
+    // 409 Conflict
+    if (code.endsWith('_ALREADY_EXISTS'))
+        return 409;
+    if (code === ErrorCodes.RESOURCE_CONFLICT)
+        return 409;
+    if (code === ErrorCodes.DB_CONSTRAINT_VIOLATION)
+        return 409;
+    // 429 Too Many Requests
+    if (code === ErrorCodes.API_RATE_LIMITED)
+        return 429;
+    if (code === ErrorCodes.BILLING_TIER_LIMIT_EXCEEDED)
+        return 429;
+    // 501 Not Implemented
+    if (code === ErrorCodes.NOT_IMPLEMENTED)
+        return 501;
+    // 503 Service Unavailable
+    if (code === ErrorCodes.SERVICE_UNAVAILABLE)
+        return 503;
+    if (code === ErrorCodes.DB_CONNECTION_FAILED)
+        return 503;
+    // 504 Gateway Timeout
+    if (code === ErrorCodes.DB_TIMEOUT)
+        return 504;
+    if (code === ErrorCodes.JOB_TIMEOUT)
+        return 504;
+    // Default to 500 Internal Server Error
+    return 500;
+}
+// ============================================================================
+// FACTORY FUNCTIONS
+// ============================================================================
+/**
+ * Create a not found error.
+ */
+export function notFoundError(resource, id, context) {
+    const message = id ? `${resource} '${id}' not found` : `${resource} not found`;
+    return new LSHError(ErrorCodes.RESOURCE_NOT_FOUND, message, { resource, id, ...context });
+}
+/**
+ * Create an already exists error.
+ */
+export function alreadyExistsError(resource, identifier, context) {
+    const message = identifier
+        ? `${resource} '${identifier}' already exists`
+        : `${resource} already exists`;
+    return new LSHError(ErrorCodes.RESOURCE_ALREADY_EXISTS, message, {
+        resource,
+        identifier,
+        ...context,
+    });
+}
+/**
+ * Create a validation error.
+ */
+export function validationError(message, field, context) {
+    return new LSHError(ErrorCodes.VALIDATION_REQUIRED_FIELD, message, { field, ...context });
+}
+/**
+ * Create an unauthorized error.
+ */
+export function unauthorizedError(message = 'Unauthorized', context) {
+    return new LSHError(ErrorCodes.AUTH_UNAUTHORIZED, message, context);
+}
+/**
+ * Create a forbidden error.
+ */
+export function forbiddenError(message = 'Insufficient permissions', context) {
+    return new LSHError(ErrorCodes.AUTH_FORBIDDEN, message, context);
+}

package/dist/lib/saas-auth.js

@@ -378,7 +378,29 @@ export class AuthService {
         await this.supabase.from('users').update({ password_hash: newHash }).eq('id', userId);
     }
     /**
-     * Map database user to User type
+     * Transform Supabase user record to domain model.
+     *
+     * Maps database snake_case columns to TypeScript camelCase properties:
+     * - `email_verified` → `emailVerified` (boolean)
+     * - `email_verification_token` → `emailVerificationToken` (nullable string)
+     * - `email_verification_expires_at` → `emailVerificationExpiresAt` (nullable Date)
+     * - `password_hash` → `passwordHash` (nullable, null for OAuth-only users)
+     * - `oauth_provider` → `oauthProvider` ('google' | 'github' | 'microsoft' | null)
+     * - `oauth_provider_id` → `oauthProviderId` (nullable)
+     * - `first_name` → `firstName` (nullable)
+     * - `last_name` → `lastName` (nullable)
+     * - `avatar_url` → `avatarUrl` (nullable)
+     * - `last_login_at` → `lastLoginAt` (nullable Date)
+     * - `last_login_ip` → `lastLoginIp` (nullable)
+     * - `deleted_at` → `deletedAt` (nullable Date, for soft delete)
+     *
+     * Security note: passwordHash is included in domain model but should
+     * never be exposed in API responses.
+     *
+     * @param dbUser - Supabase record from 'users' table
+     * @returns Domain User object
+     * @see DbUserRecord in database-types.ts for input shape
+     * @see User in saas-types.ts for output shape
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- DB row type varies by schema
     mapDbUserToUser(dbUser) {
@@ -404,7 +426,22 @@ export class AuthService {
         };
     }
     /**
-     * Map database organization to Organization type
+     * Transform Supabase organization record to domain model.
+     *
+     * Used when fetching user's organizations via the organization_members join.
+     * Identical mapping logic to OrganizationService.mapDbOrgToOrg().
+     *
+     * Maps database snake_case columns to TypeScript camelCase properties:
+     * - `stripe_customer_id` → `stripeCustomerId`
+     * - `subscription_tier` → `subscriptionTier` (SubscriptionTier type)
+     * - `subscription_status` → `subscriptionStatus` (SubscriptionStatus type)
+     * - `subscription_expires_at` → `subscriptionExpiresAt` (nullable Date)
+     * - `deleted_at` → `deletedAt` (nullable Date)
+     *
+     * @param dbOrg - Supabase record from 'organizations' table (via join)
+     * @returns Domain Organization object
+     * @see DbOrganizationRecord in database-types.ts for input shape
+     * @see Organization in saas-types.ts for output shape
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- DB row type varies by schema
     mapDbOrgToOrg(dbOrg) {

package/dist/lib/saas-billing.js

@@ -154,7 +154,22 @@ export class BillingService {
         }
     }
     /**
-     * Verify webhook signature
+     * Verify Stripe webhook signature and parse event payload.
+     *
+     * In production, this should use Stripe's signature verification:
+     * ```typescript
+     * const event = stripe.webhooks.constructEvent(
+     *   payload, signature, this.stripeWebhookSecret
+     * );
+     * ```
+     *
+     * Current implementation parses JSON without verification (TODO: implement proper verification).
+     *
+     * @param payload - Raw webhook body as string
+     * @param _signature - Stripe-Signature header value (not yet used)
+     * @returns Parsed Stripe event object
+     * @throws Error if payload is not valid JSON
+     * @see https://stripe.com/docs/webhooks/signatures
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Stripe event structure
     verifyWebhookSignature(payload, _signature) {
@@ -168,7 +183,16 @@ export class BillingService {
         }
     }
     /**
-     * Handle checkout completed
+     * Handle Stripe checkout.session.completed webhook event.
+     *
+     * Called when a customer completes checkout. The actual subscription
+     * creation is handled by the customer.subscription.created event.
+     *
+     * Extracts organization_id from session.metadata to link the checkout
+     * to the correct organization.
+     *
+     * @param session - Stripe checkout session object
+     * @see StripeCheckoutSession in database-types.ts for partial type
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Stripe checkout session object
     async handleCheckoutCompleted(session) {
@@ -181,7 +205,20 @@ export class BillingService {
         console.log(`Checkout completed for organization ${organizationId}`);
     }
     /**
-     * Handle subscription updated
+     * Handle Stripe customer.subscription.created/updated webhook events.
+     *
+     * Creates or updates subscription record in database and syncs tier
+     * to the organization. Key operations:
+     * 1. Extracts organization_id from subscription.metadata
+     * 2. Determines tier from price ID (maps Stripe price → 'free' | 'pro' | 'enterprise')
+     * 3. Upserts subscription record with all billing details
+     * 4. Updates organization's subscription_tier and subscription_status
+     * 5. Logs audit event
+     *
+     * Timestamps from Stripe are Unix timestamps (seconds), converted to ISO strings.
+     *
+     * @param subscription - Stripe subscription object
+     * @see StripeSubscriptionEvent in database-types.ts for partial type
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Stripe subscription object
     async handleSubscriptionUpdated(subscription) {
@@ -235,7 +272,17 @@ export class BillingService {
         });
     }
     /**
-     * Handle subscription deleted
+     * Handle Stripe customer.subscription.deleted webhook event.
+     *
+     * Called when a subscription is canceled (immediate or at period end).
+     * Operations:
+     * 1. Marks subscription as 'canceled' with canceled_at timestamp
+     * 2. Downgrades organization to 'free' tier
+     * 3. Updates organization subscription_status to 'canceled'
+     * 4. Logs audit event
+     *
+     * @param subscription - Stripe subscription object
+     * @see StripeSubscriptionEvent in database-types.ts for partial type
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Stripe subscription object
     async handleSubscriptionDeleted(subscription) {
@@ -268,7 +315,15 @@ export class BillingService {
         });
     }
     /**
-     * Handle invoice paid
+     * Handle Stripe invoice.paid webhook event.
+     *
+     * Records successful payment in the invoices table. Extracts organization_id
+     * from invoice.subscription_metadata (set during checkout).
+     *
+     * Amounts are in cents (e.g., 1000 = $10.00). Currency is uppercased.
+     *
+     * @param invoice - Stripe invoice object
+     * @see StripeInvoiceEvent in database-types.ts for partial type
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Stripe invoice object
     async handleInvoicePaid(invoice) {
@@ -291,7 +346,16 @@ export class BillingService {
         }, { onConflict: 'stripe_invoice_id' });
     }
     /**
-     * Handle invoice payment failed
+     * Handle Stripe invoice.payment_failed webhook event.
+     *
+     * Called when payment fails (declined card, insufficient funds, etc.).
+     * Updates organization subscription_status to 'past_due' and logs audit event.
+     *
+     * Note: Does not immediately downgrade tier. Stripe will retry payment
+     * according to your dunning settings. Downgrade happens on subscription.deleted.
+     *
+     * @param invoice - Stripe invoice object
+     * @see StripeInvoiceEvent in database-types.ts for partial type
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Stripe invoice object
     async handleInvoicePaymentFailed(invoice) {
@@ -358,7 +422,26 @@ export class BillingService {
         return (data || []).map(this.mapDbInvoiceToInvoice);
     }
     /**
-     * Map database subscription to Subscription type
+     * Transform Supabase subscription record to domain model.
+     *
+     * Maps database snake_case columns to TypeScript camelCase properties:
+     * - `organization_id` → `organizationId`
+     * - `stripe_subscription_id` → `stripeSubscriptionId` (Stripe sub_xxx ID)
+     * - `stripe_price_id` → `stripePriceId` (Stripe price_xxx ID)
+     * - `stripe_product_id` → `stripeProductId` (Stripe prod_xxx ID)
+     * - `tier` → `tier` (SubscriptionTier: 'free' | 'pro' | 'enterprise')
+     * - `status` → `status` (SubscriptionStatus)
+     * - `current_period_start` → `currentPeriodStart` (nullable Date)
+     * - `current_period_end` → `currentPeriodEnd` (nullable Date)
+     * - `cancel_at_period_end` → `cancelAtPeriodEnd` (boolean)
+     * - `trial_start` → `trialStart` (nullable Date)
+     * - `trial_end` → `trialEnd` (nullable Date)
+     * - `canceled_at` → `canceledAt` (nullable Date)
+     *
+     * @param dbSub - Supabase record from 'subscriptions' table
+     * @returns Domain Subscription object
+     * @see DbSubscriptionRecord in database-types.ts for input shape
+     * @see Subscription in saas-types.ts for output shape
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- DB row type varies by schema
     mapDbSubscriptionToSubscription(dbSub) {
@@ -383,7 +466,22 @@ export class BillingService {
         };
     }
     /**
-     * Map database invoice to Invoice type
+     * Transform Supabase invoice record to domain model.
+     *
+     * Maps database snake_case columns to TypeScript camelCase properties:
+     * - `organization_id` → `organizationId`
+     * - `stripe_invoice_id` → `stripeInvoiceId` (Stripe in_xxx ID)
+     * - `amount_due` → `amountDue` (in cents, e.g., 1000 = $10.00)
+     * - `amount_paid` → `amountPaid` (in cents)
+     * - `invoice_date` → `invoiceDate` (Date)
+     * - `due_date` → `dueDate` (nullable Date)
+     * - `paid_at` → `paidAt` (nullable Date)
+     * - `invoice_pdf_url` → `invoicePdfUrl` (Stripe-hosted PDF URL)
+     *
+     * @param dbInvoice - Supabase record from 'invoices' table
+     * @returns Domain Invoice object
+     * @see DbInvoiceRecord in database-types.ts for input shape
+     * @see Invoice in saas-types.ts for output shape
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- DB row type varies by schema
     mapDbInvoiceToInvoice(dbInvoice) {