@discover-cloud/shared 1.0.11 → 1.2.0

package/dist/dtos/response.dto.js

@@ -1,6 +1,25 @@
 "use strict";
-/* ====================================================================
-   RESPONSE DTOs
-   Shared HTTP response shapes used across all services.
-==================================================================== */
+/**
+ * RESPONSE DTOs  (@discover-cloud/shared)
+ * ─────────────────────────────────────────
+ * Shared HTTP response shapes used across all services.
+ * Every response — success or error — is wrapped in the ApiSuccessResponse
+ * or ApiErrorResponse envelope so clients have a consistent shape to key on.
+ *
+ * Envelope shape:
+ *   {
+ *     success: true,
+ *     data: T,
+ *     meta: { requestId, timestamp }
+ *   }
+ *   or
+ *   {
+ *     success: false,
+ *     error: { code, message, details? },
+ *     meta: { requestId, timestamp }
+ *   }
+ *
+ * The success() and failure() utils in shared/utils construct these
+ * envelopes — don't build them manually in controllers.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });

package/dist/dtos/user-service.dto.d.ts

@@ -1,4 +1,11 @@
 import { OrganizationRole, MembershipStatus, OrganizationStatus, Theme, Currency } from "../enums";
+/**
+ * USER SERVICE DTOs  (@discover-cloud/shared)
+ * ─────────────────────────────────────────────
+ * Shapes returned by the user service over HTTP.
+ * All timestamps are ISO 8601 strings — JSON has no Date type.
+ * Domain models use Date internally; mappers convert at the boundary.
+ */
 export interface UserDto {
     id: string;
     email: string;

package/dist/enums/domain.enums.d.ts

@@ -1,8 +1,11 @@
 /**
- * DOMAIN STATUS & CONFIGURATION ENUMS
- * ──────────────────────────────────────
+ * DOMAIN STATUS & CONFIGURATION ENUMS  (@discover-cloud/shared)
+ * ───────────────────────────────────────────────────────────────
  * General-purpose enums for entity lifecycle, UI preferences, and
- * configuration. Permission-related enums live in permissions.types.ts.
+ * cloud provider configuration.
+ *
+ * Permission-related enums (AccountRole, GlobalPermission, OrganizationRole,
+ * OrgPermission) live in permissions.enums.ts, not here.
  */
 export declare enum AccountStatus {
     ACTIVE = "ACTIVE",
@@ -40,17 +43,45 @@ export declare enum CloudProvider {
     GCP = "GCP",
     AZURE = "AZURE"
 }
+/**
+ * AWS auth methods.
+ *
+ * ACCESS_KEY           — Long-lived Access Key ID + Secret Access Key.
+ *                         Simplest to set up; least preferred for production.
+ * IAM_ROLE             — Cross-account role assumption via Role ARN + External ID.
+ *                         Recommended for production AWS integrations.
+ * IAM_IDENTITY_CENTER  — AWS SSO / IAM Identity Center (formerly AWS SSO).
+ *                         Used in organisations with centralised identity.
+ * IAM_ROLES_ANYWHERE   — Certificate-based role assumption for non-AWS workloads.
+ */
 export declare enum AwsAuthMethod {
-    ACCESS_KEY = "ACCESS_KEY",// Access Key ID + Secret
-    IAM_ROLE = "IAM_ROLE",// Role ARN + External ID
-    IAM_IDENTITY_CENTER = "IAM_IDENTITY_CENTER",// SSO
+    ACCESS_KEY = "ACCESS_KEY",
+    IAM_ROLE = "IAM_ROLE",
+    IAM_IDENTITY_CENTER = "IAM_IDENTITY_CENTER",
     IAM_ROLES_ANYWHERE = "IAM_ROLES_ANYWHERE"
 }
+/**
+ * GCP auth methods.
+ *
+ * SERVICE_ACCOUNT_KEY            — JSON key file for a GCP service account.
+ *                                   Simpler but requires secure key storage.
+ * WORKLOAD_IDENTITY              — Keyless auth using Workload Identity Federation.
+ *                                   Preferred for production.
+ * SERVICE_ACCOUNT_IMPERSONATION  — Short-lived tokens via service account impersonation.
+ */
 export declare enum GcpAuthMethod {
     SERVICE_ACCOUNT_KEY = "SERVICE_ACCOUNT_KEY",
     WORKLOAD_IDENTITY = "WORKLOAD_IDENTITY",
     SERVICE_ACCOUNT_IMPERSONATION = "SERVICE_ACCOUNT_IMPERSONATION"
 }
+/**
+ * Azure auth methods.
+ *
+ * SERVICE_PRINCIPAL_SECRET      — Client ID + Client Secret for an app registration.
+ * SERVICE_PRINCIPAL_CERTIFICATE — Client ID + certificate (more secure than secret).
+ * MANAGED_IDENTITY_USER         — User-assigned managed identity.
+ * MANAGED_IDENTITY_SYSTEM       — System-assigned managed identity (tied to the resource).
+ */
 export declare enum AzureAuthMethod {
     SERVICE_PRINCIPAL_SECRET = "SERVICE_PRINCIPAL_SECRET",
     SERVICE_PRINCIPAL_CERTIFICATE = "SERVICE_PRINCIPAL_CERTIFICATE",
@@ -58,20 +89,20 @@ export declare enum AzureAuthMethod {
     MANAGED_IDENTITY_SYSTEM = "MANAGED_IDENTITY_SYSTEM"
 }
 export declare enum CloudAccountStatus {
-    PENDING = "PENDING",// Connected, never synced
-    ACTIVE = "ACTIVE",// Last sync succeeded
-    ERROR = "ERROR",// Last sync failed
+    PENDING = "PENDING",// Connected but never successfully synced
+    ACTIVE = "ACTIVE",// Last sync completed successfully
+    ERROR = "ERROR",// Last sync failed — check lastErrorMsg
     INACTIVE = "INACTIVE"
 }
 export declare enum SyncStatus {
-    PENDING = "PENDING",
-    RUNNING = "RUNNING",
-    SUCCESS = "SUCCESS",
-    FAILED = "FAILED",
+    PENDING = "PENDING",// Queued, not yet picked up by the scheduler
+    RUNNING = "RUNNING",// Currently in progress
+    SUCCESS = "SUCCESS",// All fetches completed without error
+    FAILED = "FAILED",// All fetches failed; no data was written
     PARTIAL = "PARTIAL"
 }
 export declare enum SyncType {
-    FULL = "FULL",// All data types
+    FULL = "FULL",// All data types in one job
     COSTS = "COSTS",// Cost records only
     RESOURCES = "RESOURCES",// Resource inventory only
     BUDGETS = "BUDGETS"

package/dist/enums/domain.enums.js

@@ -1,9 +1,12 @@
 "use strict";
 /**
- * DOMAIN STATUS & CONFIGURATION ENUMS
- * ──────────────────────────────────────
+ * DOMAIN STATUS & CONFIGURATION ENUMS  (@discover-cloud/shared)
+ * ───────────────────────────────────────────────────────────────
  * General-purpose enums for entity lifecycle, UI preferences, and
- * configuration. Permission-related enums live in permissions.types.ts.
+ * cloud provider configuration.
+ *
+ * Permission-related enums (AccountRole, GlobalPermission, OrganizationRole,
+ * OrgPermission) live in permissions.enums.ts, not here.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SyncType = exports.SyncStatus = exports.CloudAccountStatus = exports.AzureAuthMethod = exports.GcpAuthMethod = exports.AwsAuthMethod = exports.CloudProvider = exports.Currency = exports.Theme = exports.MembershipStatus = exports.OrganizationStatus = exports.AccountStatus = void 0;
@@ -54,8 +57,8 @@ var Currency;
 })(Currency || (exports.Currency = Currency = {}));
 /* ====================================================================
    CLOUD PROVIDERS
-   Used by cloud-service for account connections and insights-service
-   for storing normalized cost/resource data.
+   Used by cloud-service for account connections, and by insights-service
+   for normalising cost/resource data across providers.
 ==================================================================== */
 var CloudProvider;
 (function (CloudProvider) {
@@ -66,8 +69,20 @@ var CloudProvider;
 /* ====================================================================
    CLOUD ACCOUNT AUTH METHODS
    Discriminator for which credential shape is stored per provider.
-   Each provider has its own enum — only one is set per CloudAccount.
+   Each provider has its own enum — exactly one is set per CloudAccount
+   and determines how the credential cipher stores + retrieves secrets.
 ==================================================================== */
+/**
+ * AWS auth methods.
+ *
+ * ACCESS_KEY           — Long-lived Access Key ID + Secret Access Key.
+ *                         Simplest to set up; least preferred for production.
+ * IAM_ROLE             — Cross-account role assumption via Role ARN + External ID.
+ *                         Recommended for production AWS integrations.
+ * IAM_IDENTITY_CENTER  — AWS SSO / IAM Identity Center (formerly AWS SSO).
+ *                         Used in organisations with centralised identity.
+ * IAM_ROLES_ANYWHERE   — Certificate-based role assumption for non-AWS workloads.
+ */
 var AwsAuthMethod;
 (function (AwsAuthMethod) {
     AwsAuthMethod["ACCESS_KEY"] = "ACCESS_KEY";
@@ -75,12 +90,29 @@ var AwsAuthMethod;
     AwsAuthMethod["IAM_IDENTITY_CENTER"] = "IAM_IDENTITY_CENTER";
     AwsAuthMethod["IAM_ROLES_ANYWHERE"] = "IAM_ROLES_ANYWHERE";
 })(AwsAuthMethod || (exports.AwsAuthMethod = AwsAuthMethod = {}));
+/**
+ * GCP auth methods.
+ *
+ * SERVICE_ACCOUNT_KEY            — JSON key file for a GCP service account.
+ *                                   Simpler but requires secure key storage.
+ * WORKLOAD_IDENTITY              — Keyless auth using Workload Identity Federation.
+ *                                   Preferred for production.
+ * SERVICE_ACCOUNT_IMPERSONATION  — Short-lived tokens via service account impersonation.
+ */
 var GcpAuthMethod;
 (function (GcpAuthMethod) {
     GcpAuthMethod["SERVICE_ACCOUNT_KEY"] = "SERVICE_ACCOUNT_KEY";
     GcpAuthMethod["WORKLOAD_IDENTITY"] = "WORKLOAD_IDENTITY";
     GcpAuthMethod["SERVICE_ACCOUNT_IMPERSONATION"] = "SERVICE_ACCOUNT_IMPERSONATION";
 })(GcpAuthMethod || (exports.GcpAuthMethod = GcpAuthMethod = {}));
+/**
+ * Azure auth methods.
+ *
+ * SERVICE_PRINCIPAL_SECRET      — Client ID + Client Secret for an app registration.
+ * SERVICE_PRINCIPAL_CERTIFICATE — Client ID + certificate (more secure than secret).
+ * MANAGED_IDENTITY_USER         — User-assigned managed identity.
+ * MANAGED_IDENTITY_SYSTEM       — System-assigned managed identity (tied to the resource).
+ */
 var AzureAuthMethod;
 (function (AzureAuthMethod) {
     AzureAuthMethod["SERVICE_PRINCIPAL_SECRET"] = "SERVICE_PRINCIPAL_SECRET";
@@ -90,6 +122,7 @@ var AzureAuthMethod;
 })(AzureAuthMethod || (exports.AzureAuthMethod = AzureAuthMethod = {}));
 /* ====================================================================
    CLOUD ACCOUNT STATUS
+   Lifecycle state of a connected cloud account.
 ==================================================================== */
 var CloudAccountStatus;
 (function (CloudAccountStatus) {
@@ -100,6 +133,7 @@ var CloudAccountStatus;
 })(CloudAccountStatus || (exports.CloudAccountStatus = CloudAccountStatus = {}));
 /* ====================================================================
    SYNC JOB
+   Tracks the lifecycle and scope of a single sync run.
 ==================================================================== */
 var SyncStatus;
 (function (SyncStatus) {

package/dist/enums/permissions.enums.d.ts

@@ -1,9 +1,17 @@
 /**
- * ACCOUNT ROLES
- * ──────────────
- * Platform-level roles assigned to every account.
- * Ordered from highest to lowest privilege.
+ * PERMISSION ENUMS  (@discover-cloud/shared)
+ * ────────────────────────────────────────────
+ * Platform-level roles and permissions. These are the single source of
+ * truth for the entire permission system — the Redis permission cache,
+ * JWT payloads, and route guards all derive from these definitions.
  *
+ * File layout:
+ *   AccountRole        — platform-level account roles (highest → lowest privilege)
+ *   GlobalPermission   — platform-wide permissions derived from AccountRole
+ *   OrganizationRole   — per-org roles (future)
+ *   OrgPermission      — per-org permissions checked by tenant middleware (future)
+ */
+/**
  * SUPERADMIN  — Full platform control. Internal engineering / founders only.
  *               Can impersonate users, access all data, manage platform config.
  *
@@ -26,40 +34,6 @@ export declare enum AccountRole {
     MODERATOR = "MODERATOR",
     USER = "USER"
 }
-/**
- * GLOBAL PERMISSIONS
- * ───────────────────
- * Platform-wide permissions derived from AccountRole.
- * These are checked at the gateway / service middleware level.
- *
- * Naming convention: VERB_NOUN or VERB_SCOPE_NOUN
- *
- * Account management
- *   MANAGE_ACCOUNTS      — Create, update, suspend, delete any account
- *   VIEW_ANY_ACCOUNT     — Read any account's profile and metadata
- *   IMPERSONATE_ACCOUNT  — Act as another user (SUPERADMIN only — support tooling)
- *   SUSPEND_ACCOUNT      — Suspend / unsuspend an account without full delete
- *   DELETE_ACCOUNT       — Hard delete an account and all associated data
- *
- * Cloud cost data (platform-level, not per-org)
- *   VIEW_ANY_COST_DATA   — Read any user's cloud cost reports (support/admin use)
- *   EXPORT_ANY_COST_DATA — Export cost data for any user (compliance, support)
- *   MANAGE_COST_ALERTS   — Create/edit/delete cost alert rules platform-wide
- *
- * Platform operations
- *   VIEW_SYSTEM_LOGS     — Access platform audit logs and system events
- *   VIEW_SYSTEM_HEALTH   — Read service health, metrics dashboards
- *   MANAGE_PLATFORM_CONFIG — Modify platform-wide settings (limits, features)
- *
- * Support tooling
- *   SUPPORT_VIEW         — Read-only access to user data for support purposes
- *   SUPPORT_WRITE        — Ability to make support-sanctioned changes on behalf of users
- *
- * Future-proofing (define now, assign later)
- *   MANAGE_BILLING       — Access to subscription and billing management
- *   MODERATE_CONTENT     — Moderate user-generated content (alerts, comments, etc.)
- *   MANAGE_INTEGRATIONS  — Manage platform-level cloud provider integrations
- */
 export declare enum GlobalPermission {
     MANAGE_ACCOUNTS = "MANAGE_ACCOUNTS",
     VIEW_ANY_ACCOUNT = "VIEW_ANY_ACCOUNT",
@@ -79,11 +53,6 @@ export declare enum GlobalPermission {
     MANAGE_INTEGRATIONS = "MANAGE_INTEGRATIONS"
 }
 /**
- * ORGANIZATION ROLES  (future work)
- * ────────────────────────────────────
- * Defined now so the type system is ready when org support ships.
- * No permissions are assigned yet — see orgRolePermissions below.
- *
  * OWNER   — Created the org. Full control, including deletion and billing.
  * ADMIN   — Manages members and org settings. Cannot delete the org.
  * EDITOR  — Can create/edit cost reports and dashboards within the org.
@@ -97,15 +66,6 @@ export declare enum OrganizationRole {
     VIEWER = "VIEWER",
     BILLING = "BILLING"
 }
-/**
- * ORG PERMISSIONS  (future work)
- * ────────────────────────────────
- * Granular org-scoped permissions. Checked by tenant middleware in each
- * service via DB lookup — NOT in the JWT (org membership changes too
- * frequently to embed reliably).
- *
- * Naming: VERB_RESOURCE
- */
 export declare enum OrgPermission {
     DELETE_ORG = "DELETE_ORG",
     MANAGE_ORG_SETTINGS = "MANAGE_ORG_SETTINGS",

package/dist/enums/permissions.enums.js

@@ -1,12 +1,24 @@
 "use strict";
+/**
+ * PERMISSION ENUMS  (@discover-cloud/shared)
+ * ────────────────────────────────────────────
+ * Platform-level roles and permissions. These are the single source of
+ * truth for the entire permission system — the Redis permission cache,
+ * JWT payloads, and route guards all derive from these definitions.
+ *
+ * File layout:
+ *   AccountRole        — platform-level account roles (highest → lowest privilege)
+ *   GlobalPermission   — platform-wide permissions derived from AccountRole
+ *   OrganizationRole   — per-org roles (future)
+ *   OrgPermission      — per-org permissions checked by tenant middleware (future)
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OrgPermission = exports.OrganizationRole = exports.GlobalPermission = exports.AccountRole = void 0;
+/* ====================================================================
+   ACCOUNT ROLES
+   Ordered from highest to lowest privilege.
+==================================================================== */
 /**
- * ACCOUNT ROLES
- * ──────────────
- * Platform-level roles assigned to every account.
- * Ordered from highest to lowest privilege.
- *
  * SUPERADMIN  — Full platform control. Internal engineering / founders only.
  *               Can impersonate users, access all data, manage platform config.
  *
@@ -30,70 +42,55 @@ var AccountRole;
     AccountRole["MODERATOR"] = "MODERATOR";
     AccountRole["USER"] = "USER";
 })(AccountRole || (exports.AccountRole = AccountRole = {}));
-/**
- * GLOBAL PERMISSIONS
- * ───────────────────
- * Platform-wide permissions derived from AccountRole.
- * These are checked at the gateway / service middleware level.
- *
- * Naming convention: VERB_NOUN or VERB_SCOPE_NOUN
- *
- * Account management
- *   MANAGE_ACCOUNTS      — Create, update, suspend, delete any account
- *   VIEW_ANY_ACCOUNT     — Read any account's profile and metadata
- *   IMPERSONATE_ACCOUNT  — Act as another user (SUPERADMIN only — support tooling)
- *   SUSPEND_ACCOUNT      — Suspend / unsuspend an account without full delete
- *   DELETE_ACCOUNT       — Hard delete an account and all associated data
- *
- * Cloud cost data (platform-level, not per-org)
- *   VIEW_ANY_COST_DATA   — Read any user's cloud cost reports (support/admin use)
- *   EXPORT_ANY_COST_DATA — Export cost data for any user (compliance, support)
- *   MANAGE_COST_ALERTS   — Create/edit/delete cost alert rules platform-wide
- *
- * Platform operations
- *   VIEW_SYSTEM_LOGS     — Access platform audit logs and system events
- *   VIEW_SYSTEM_HEALTH   — Read service health, metrics dashboards
- *   MANAGE_PLATFORM_CONFIG — Modify platform-wide settings (limits, features)
- *
- * Support tooling
- *   SUPPORT_VIEW         — Read-only access to user data for support purposes
- *   SUPPORT_WRITE        — Ability to make support-sanctioned changes on behalf of users
- *
- * Future-proofing (define now, assign later)
- *   MANAGE_BILLING       — Access to subscription and billing management
- *   MODERATE_CONTENT     — Moderate user-generated content (alerts, comments, etc.)
- *   MANAGE_INTEGRATIONS  — Manage platform-level cloud provider integrations
- */
+/* ====================================================================
+   GLOBAL PERMISSIONS
+   Platform-wide permissions derived from AccountRole.
+   Checked at the gateway / service middleware level via Redis cache.
+
+   Naming convention: VERB_NOUN or VERB_SCOPE_NOUN
+==================================================================== */
 var GlobalPermission;
 (function (GlobalPermission) {
-    // Account management
+    // ── Account management ────────────────────────────────────────────
+    // MANAGE_ACCOUNTS      — Create, update, suspend, delete any account
+    // VIEW_ANY_ACCOUNT     — Read any account's profile and metadata
+    // IMPERSONATE_ACCOUNT  — Act as another user (SUPERADMIN only)
+    // SUSPEND_ACCOUNT      — Suspend / unsuspend without full delete
+    // DELETE_ACCOUNT       — Hard delete an account and all associated data
     GlobalPermission["MANAGE_ACCOUNTS"] = "MANAGE_ACCOUNTS";
     GlobalPermission["VIEW_ANY_ACCOUNT"] = "VIEW_ANY_ACCOUNT";
     GlobalPermission["IMPERSONATE_ACCOUNT"] = "IMPERSONATE_ACCOUNT";
     GlobalPermission["SUSPEND_ACCOUNT"] = "SUSPEND_ACCOUNT";
     GlobalPermission["DELETE_ACCOUNT"] = "DELETE_ACCOUNT";
-    // Cloud cost data (platform-level)
+    // ── Cloud cost data (platform-level, not per-org) ─────────────────
+    // VIEW_ANY_COST_DATA   — Read any user's cloud cost reports
+    // EXPORT_ANY_COST_DATA — Export cost data for any user (compliance)
+    // MANAGE_COST_ALERTS   — Create/edit/delete alert rules platform-wide
     GlobalPermission["VIEW_ANY_COST_DATA"] = "VIEW_ANY_COST_DATA";
     GlobalPermission["EXPORT_ANY_COST_DATA"] = "EXPORT_ANY_COST_DATA";
     GlobalPermission["MANAGE_COST_ALERTS"] = "MANAGE_COST_ALERTS";
-    // Platform operations
+    // ── Platform operations ───────────────────────────────────────────
+    // VIEW_SYSTEM_LOGS       — Access platform audit logs and system events
+    // VIEW_SYSTEM_HEALTH     — Read service health and metrics dashboards
+    // MANAGE_PLATFORM_CONFIG — Modify platform-wide settings (limits, features)
     GlobalPermission["VIEW_SYSTEM_LOGS"] = "VIEW_SYSTEM_LOGS";
     GlobalPermission["VIEW_SYSTEM_HEALTH"] = "VIEW_SYSTEM_HEALTH";
     GlobalPermission["MANAGE_PLATFORM_CONFIG"] = "MANAGE_PLATFORM_CONFIG";
-    // Support tooling
+    // ── Support tooling ───────────────────────────────────────────────
+    // SUPPORT_VIEW  — Read-only access to user data for support purposes
+    // SUPPORT_WRITE — Support-sanctioned changes on behalf of users
     GlobalPermission["SUPPORT_VIEW"] = "SUPPORT_VIEW";
     GlobalPermission["SUPPORT_WRITE"] = "SUPPORT_WRITE";
-    // Future — define now so they exist in the type system before the features ship
+    // ── Future — defined now so they exist in the type system ─────────
     GlobalPermission["MANAGE_BILLING"] = "MANAGE_BILLING";
     GlobalPermission["MODERATE_CONTENT"] = "MODERATE_CONTENT";
     GlobalPermission["MANAGE_INTEGRATIONS"] = "MANAGE_INTEGRATIONS";
 })(GlobalPermission || (exports.GlobalPermission = GlobalPermission = {}));
+/* ====================================================================
+   ORGANIZATION ROLES  (future work)
+   Defined now so the type system is ready when org support ships.
+==================================================================== */
 /**
- * ORGANIZATION ROLES  (future work)
- * ────────────────────────────────────
- * Defined now so the type system is ready when org support ships.
- * No permissions are assigned yet — see orgRolePermissions below.
- *
  * OWNER   — Created the org. Full control, including deletion and billing.
  * ADMIN   — Manages members and org settings. Cannot delete the org.
  * EDITOR  — Can create/edit cost reports and dashboards within the org.
@@ -108,15 +105,14 @@ var OrganizationRole;
     OrganizationRole["VIEWER"] = "VIEWER";
     OrganizationRole["BILLING"] = "BILLING";
 })(OrganizationRole || (exports.OrganizationRole = OrganizationRole = {}));
-/**
- * ORG PERMISSIONS  (future work)
- * ────────────────────────────────
- * Granular org-scoped permissions. Checked by tenant middleware in each
- * service via DB lookup — NOT in the JWT (org membership changes too
- * frequently to embed reliably).
- *
- * Naming: VERB_RESOURCE
- */
+/* ====================================================================
+   ORG PERMISSIONS  (future work)
+   Granular org-scoped permissions checked by tenant middleware in each
+   service via DB lookup — NOT embedded in the JWT (org membership changes
+   too frequently to embed reliably).
+
+   Naming: VERB_RESOURCE
+==================================================================== */
 var OrgPermission;
 (function (OrgPermission) {
     // Org management
@@ -132,7 +128,7 @@ var OrgPermission;
     OrgPermission["EXPORT_COST_DATA"] = "EXPORT_COST_DATA";
     OrgPermission["MANAGE_COST_REPORTS"] = "MANAGE_COST_REPORTS";
     OrgPermission["MANAGE_ALERTS"] = "MANAGE_ALERTS";
-    // Integrations within org
+    // Cloud account integrations within org
     OrgPermission["MANAGE_CLOUD_ACCOUNTS"] = "MANAGE_CLOUD_ACCOUNTS";
     OrgPermission["VIEW_CLOUD_ACCOUNTS"] = "VIEW_CLOUD_ACCOUNTS";
     // Billing within org

package/dist/errors/app-error.d.ts

@@ -1,19 +1,22 @@
 /**
- * APP ERROR
- * ──────────
- * Base class for all known operational errors.
- * Subclasses map to specific HTTP status codes and error codes.
+ * APP ERROR  (@discover-cloud/shared)
+ * ─────────────────────────────────────
+ * Base class for all known operational errors across every service.
+ * Subclasses (see http-errors.ts) map to specific HTTP status codes and
+ * error codes that the global error handler serialises into responses.
  *
- * GlobalErrorHandler catches instanceof AppError and maps it to a
- * structured error response — no duck-typing, no accidental matches.
- *
- * Changes vs original:
- *   - details?: any → details?: unknown
- *     `any` disabled TypeScript's type checking on the most variable field.
- *     Callers that need a specific details shape should cast after instanceof.
- *   - Object.freeze(this) retained — prevents accidental mutation of thrown errors.
- *     Note: freeze is shallow. If details is an object, its contents are mutable.
- *     This is acceptable — details is for logging/response context, not program logic.
+ * Design decisions:
+ *   - GlobalErrorHandler catches `instanceof AppError` — no duck-typing,
+ *     no accidental matches on arbitrary thrown objects.
+ *   - details?: unknown (not any) — TypeScript's type checking is preserved
+ *     on the most variable field. Callers that need a specific details shape
+ *     should cast after an instanceof guard.
+ *   - Object.freeze(this) — prevents accidental post-construction mutation of
+ *     a thrown error. Freeze is shallow: if details is an object, its contents
+ *     remain mutable. This is acceptable — details is for logging/response
+ *     context, not program logic.
+ *   - captureStackTrace — strips the AppError constructor frame from the stack
+ *     so the trace points to the throw site, not the base class constructor.
  */
 export declare class AppError extends Error {
     readonly code: string;

package/dist/errors/app-error.js

@@ -2,21 +2,24 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AppError = void 0;
 /**
- * APP ERROR
- * ──────────
- * Base class for all known operational errors.
- * Subclasses map to specific HTTP status codes and error codes.
+ * APP ERROR  (@discover-cloud/shared)
+ * ─────────────────────────────────────
+ * Base class for all known operational errors across every service.
+ * Subclasses (see http-errors.ts) map to specific HTTP status codes and
+ * error codes that the global error handler serialises into responses.
  *
- * GlobalErrorHandler catches instanceof AppError and maps it to a
- * structured error response — no duck-typing, no accidental matches.
- *
- * Changes vs original:
- *   - details?: any → details?: unknown
- *     `any` disabled TypeScript's type checking on the most variable field.
- *     Callers that need a specific details shape should cast after instanceof.
- *   - Object.freeze(this) retained — prevents accidental mutation of thrown errors.
- *     Note: freeze is shallow. If details is an object, its contents are mutable.
- *     This is acceptable — details is for logging/response context, not program logic.
+ * Design decisions:
+ *   - GlobalErrorHandler catches `instanceof AppError` — no duck-typing,
+ *     no accidental matches on arbitrary thrown objects.
+ *   - details?: unknown (not any) — TypeScript's type checking is preserved
+ *     on the most variable field. Callers that need a specific details shape
+ *     should cast after an instanceof guard.
+ *   - Object.freeze(this) — prevents accidental post-construction mutation of
+ *     a thrown error. Freeze is shallow: if details is an object, its contents
+ *     remain mutable. This is acceptable — details is for logging/response
+ *     context, not program logic.
+ *   - captureStackTrace — strips the AppError constructor frame from the stack
+ *     so the trace points to the throw site, not the base class constructor.
  */
 class AppError extends Error {
     constructor(code, statusCode, message, details) {
@@ -24,7 +27,8 @@ class AppError extends Error {
         this.code = code;
         this.statusCode = statusCode;
         this.details = details;
-        this.name = this.constructor.name;
+        this.name = this.constructor.name; // "NotFoundError", "ConflictError", etc.
+        // Available in V8 (Node.js / Chrome) — no-ops gracefully in other engines.
         if (typeof Error.captureStackTrace === "function") {
             Error.captureStackTrace(this, this.constructor);
         }

package/dist/errors/http-errors.d.ts

@@ -1,15 +1,22 @@
 import { AppError } from "./app-error";
 /**
- * HTTP ERRORS
- * ────────────
+ * HTTP ERRORS  (@discover-cloud/shared)
+ * ───────────────────────────────────────
  * Typed subclasses of AppError for every common HTTP error status.
- * GlobalErrorHandler catches these via instanceof AppError and maps
- * statusCode + code directly to the response.
+ *
+ * GlobalErrorHandler catches these via `instanceof AppError` and maps
+ * statusCode + code directly to the response — no additional switch/if needed.
  *
  * Usage:
  *   throw new NotFoundError("Account not found");
  *   throw new ConflictError("Email already in use");
- *   throw new BadRequestError("Invalid input", { field: "email" });
+ *   throw new BadRequestError("Validation failed", { field: "email" });
+ *
+ * Adding a new error type:
+ *   1. Add a subclass here following the existing pattern.
+ *   2. Pick the correct HTTP status code.
+ *   3. Choose a SCREAMING_SNAKE_CASE code that is stable across versions
+ *      (clients may key on it for error handling).
  */
 export declare class BadRequestError extends AppError {
     constructor(message?: string, details?: unknown);