/** * @module Error code registry * * Central registry of known error codes, each a domain-prefixed string like * `auth.invalid_credentials` mapped to its canonical HTTP status. Package-specific * codes under a known domain are allowed via the `${ErrorDomain}.${string}` * fallback in `ErrorCode`. */ export type ErrorDomain = | 'auth' | 'sync' | 'validation' | 'quota' | 'permission' | 'blob' | 'billing' | 'sharing' | 'services' | 'internal' /** * Listed as a literal union so JSR can publish without slow-types. * `Record` keeps `ErrorCodes` in sync with status. */ export type KnownErrorCode = // Auth | 'auth.invalid_credentials' | 'auth.session_expired' | 'auth.email_not_verified' | 'auth.user_exists' | 'auth.unauthorized' | 'auth.token_required' | 'auth.user_not_found' | 'auth.invite_required' | 'auth.invite_invalid' | 'auth.mfa_required' | 'auth.magic_link_expired' | 'auth.csrf_origin_mismatch' // Sync | 'sync.push_conflict' | 'sync.history_pruned' | 'sync.app_not_found' | 'sync.token_not_found' | 'sync.share_not_found' | 'sync.method_not_allowed' | 'sync.request_timeout' | 'sync.network_error' | 'sync.archive_unsupported' | 'sync.archive_incomplete' | 'sync.archive_in_progress' // Validation | 'validation.schema_mismatch' | 'validation.invalid_patch' | 'validation.missing_field' | 'validation.invalid_request' // Quota | 'quota.storage_exceeded' | 'quota.db_exceeded' | 'quota.blob_exceeded' | 'quota.rate_limited' | 'quota.blob_too_large' // Permission | 'permission.insufficient_scope' | 'permission.app_not_authorized' | 'permission.grant_not_found' | 'permission.active_grants' // Blob | 'blob.not_found' | 'blob.upload_failed' | 'blob.download_failed' | 'blob.invalid_hash' | 'blob.empty_body' | 'blob.url_unavailable' // Sharing (cross-app data access) | 'sharing.type_unresolved' | 'sharing.grant_not_found' | 'sharing.not_supported' // CivServices (credentialed egress — client runtime and server proxy) | 'services.no_supported_mode' | 'services.grant_denied' | 'services.quota_exceeded' | 'services.credential_missing' | 'services.credential_unwrap' | 'services.input_invalid' | 'services.upstream_error' | 'services.egress_denied' | 'services.rate_limited' // Internal / catch-all | 'internal.server_error' | 'internal.unknown' /** Central registry of known error codes and their default HTTP status codes. */ export const ErrorCodes: Record = { // Auth 'auth.invalid_credentials': { httpStatus: 401 }, 'auth.session_expired': { httpStatus: 401 }, 'auth.email_not_verified': { httpStatus: 403 }, 'auth.user_exists': { httpStatus: 409 }, 'auth.unauthorized': { httpStatus: 401 }, 'auth.token_required': { httpStatus: 400 }, 'auth.user_not_found': { httpStatus: 404 }, 'auth.invite_required': { httpStatus: 403 }, 'auth.invite_invalid': { httpStatus: 403 }, 'auth.mfa_required': { httpStatus: 403 }, 'auth.magic_link_expired': { httpStatus: 401 }, 'auth.csrf_origin_mismatch': { httpStatus: 403 }, // Sync 'sync.push_conflict': { httpStatus: 409 }, 'sync.history_pruned': { httpStatus: 410 }, 'sync.app_not_found': { httpStatus: 404 }, 'sync.token_not_found': { httpStatus: 404 }, 'sync.share_not_found': { httpStatus: 404 }, 'sync.method_not_allowed': { httpStatus: 405 }, 'sync.request_timeout': { httpStatus: 408 }, 'sync.network_error': { httpStatus: 0 }, 'sync.archive_unsupported': { httpStatus: 400 }, 'sync.archive_incomplete': { httpStatus: 422 }, 'sync.archive_in_progress': { httpStatus: 409 }, // Validation 'validation.schema_mismatch': { httpStatus: 422 }, 'validation.invalid_patch': { httpStatus: 422 }, 'validation.missing_field': { httpStatus: 400 }, 'validation.invalid_request': { httpStatus: 400 }, // Quota 'quota.storage_exceeded': { httpStatus: 413 }, 'quota.db_exceeded': { httpStatus: 429 }, 'quota.blob_exceeded': { httpStatus: 429 }, 'quota.rate_limited': { httpStatus: 429 }, 'quota.blob_too_large': { httpStatus: 413 }, // Permission 'permission.insufficient_scope': { httpStatus: 403 }, 'permission.app_not_authorized': { httpStatus: 403 }, 'permission.grant_not_found': { httpStatus: 404 }, 'permission.active_grants': { httpStatus: 409 }, // Blob 'blob.not_found': { httpStatus: 404 }, 'blob.upload_failed': { httpStatus: 500 }, 'blob.download_failed': { httpStatus: 500 }, 'blob.invalid_hash': { httpStatus: 400 }, 'blob.empty_body': { httpStatus: 400 }, 'blob.url_unavailable': { httpStatus: 500 }, // Sharing (cross-app data access) 'sharing.type_unresolved': { httpStatus: 422 }, 'sharing.grant_not_found': { httpStatus: 404 }, 'sharing.not_supported': { httpStatus: 501 }, // CivServices 'services.no_supported_mode': { httpStatus: 400 }, 'services.grant_denied': { httpStatus: 403 }, 'services.quota_exceeded': { httpStatus: 429 }, 'services.credential_missing': { httpStatus: 401 }, 'services.credential_unwrap': { httpStatus: 400 }, 'services.input_invalid': { httpStatus: 400 }, 'services.upstream_error': { httpStatus: 502 }, 'services.egress_denied': { httpStatus: 403 }, 'services.rate_limited': { httpStatus: 429 }, // Internal / catch-all 'internal.server_error': { httpStatus: 500 }, 'internal.unknown': { httpStatus: 500 }, } /** * Any code matching the `domain.specifier` shape. Use this as the broad public * type — `KnownErrorCode` narrows to the ones documented in the registry. */ export type ErrorCode = KnownErrorCode | `${ErrorDomain}.${string}` /** Extract the domain half of an error code. */ export function domainOf(code: ErrorCode): ErrorDomain { return code.split('.', 1)[0] as ErrorDomain } /** * Look up the default HTTP status for a known code, falling back to 500 for * codes that aren't in the registry. */ export function httpStatusFor(code: ErrorCode): number { const entry = (ErrorCodes as Record)[code] return entry?.httpStatus ?? 500 }