Something went wrong. Try again.
Connected apps with 3rd-party data hosts
jsr.io/@civility
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162/** * @module Error-code registry docs * * Renders `ErrorCodes` into the Markdown table in `README.md`, build-time * only — not exported from `mod.ts`, so descriptions never ship in app * bundles. `deno task docs` rewrites the README; `--check` verifies it; * `__tests__/docs.test.ts` fails the suite on drift. */
import { ErrorCodes, type KnownErrorCode } from './lib/codes.ts'
/** One-line "use when" description per code; `Record<KnownErrorCode, string>` keeps keys in sync with the registry. */export const ErrorCodeDescriptions: Record<KnownErrorCode, string> = { // Auth 'auth.invalid_credentials': 'Login failed — wrong email/password.', 'auth.session_expired': 'Token was valid but expired.', 'auth.email_not_verified': 'User must verify email before this action.', 'auth.user_exists': 'Signup collided with an existing account.', 'auth.unauthorized': 'Request is missing or has an invalid token.', 'auth.token_required': 'A required header/token was missing from request.', 'auth.user_not_found': 'Lookup by user id returned nothing.', 'auth.invite_required': 'Signup needs an invite (closed beta) — none sent.', 'auth.invite_invalid': 'Invite token unknown, expired, revoked, or used.', 'auth.mfa_required': "Action needs the user's MFA second factor first.", 'auth.magic_link_expired': 'Passwordless sign-in link is invalid or expired.', 'auth.csrf_origin_mismatch': 'Cookie-authed mutation from a disallowed origin.',
// Sync 'sync.push_conflict': 'Server rejected a push because of a conflict.', 'sync.history_pruned': "Client's watermark is below changes the server has pruned; full re-sync required.", 'sync.app_not_found': 'App id does not exist on this server.', 'sync.token_not_found': 'Sync token has been deleted or never existed.', 'sync.share_not_found': 'Public share is unknown, revoked, or on a different app.', 'sync.method_not_allowed': 'HTTP method not valid for the endpoint.', 'sync.request_timeout': 'Client aborted the request after the timeout.', 'sync.network_error': 'fetch() failed before a response was received.', 'sync.archive_unsupported': 'Account archive was written in a format this server cannot read.', 'sync.archive_incomplete': 'Account archive is missing its manifest, or a part is short — it was truncated.', 'sync.archive_in_progress': 'An account archive is already being built or applied; only one runs at a time.',
// Validation 'validation.schema_mismatch': 'Payload failed schema validation.', 'validation.invalid_patch': 'JSON Patch could not be applied.', 'validation.missing_field': 'Required field missing from request body.', 'validation.invalid_request': 'Request body malformed for this endpoint.',
// Quota 'quota.storage_exceeded': "User's storage limit reached.", 'quota.db_exceeded': "User's change-log (database) quota reached.", 'quota.blob_exceeded': "User's blob storage quota reached.", 'quota.rate_limited': 'Too many requests in a window.', 'quota.blob_too_large': 'Single blob exceeds `maxBlobSizeBytes`.',
// Permission 'permission.insufficient_scope': 'Token lacks required read/write/delete level.', 'permission.app_not_authorized': 'App has not been granted access to this data.', 'permission.grant_not_found': 'Cross-app grant does not exist or was revoked.', 'permission.active_grants': 'App still has active grants; delete blocked unless forced.',
// Blob 'blob.not_found': 'Blob hash not present on server.', 'blob.upload_failed': 'Upload to object storage failed server-side.', 'blob.download_failed': 'Download from object storage failed server-side.', 'blob.invalid_hash': 'Hash format rejected (must be `sha256:<hex>`).', 'blob.empty_body': 'Upload request had no body.', 'blob.url_unavailable': 'Signed/CDN URL could not be produced.',
// Sharing (cross-app data access) 'sharing.type_unresolved': 'Shared type document could not be resolved.', 'sharing.grant_not_found': 'Share grant unknown or already revoked.', 'sharing.not_supported': 'Cross-app sharing unavailable for this app/server.',
// CivServices 'services.no_supported_mode': 'No execution mode is available for this service on this host.', 'services.grant_denied': 'The app lacks a grant covering this service.', 'services.quota_exceeded': 'A per-grant or per-credential quota is used up for the period.', 'services.credential_missing': 'No credential resolved for the requested service.', 'services.credential_unwrap': 'The proxy could not open the sealed credential.', 'services.input_invalid': "Input failed the service's declared schema.", 'services.upstream_error': 'The upstream provider failed or was unreachable.', 'services.egress_denied': "Requested host is outside the service's allowed egress.", 'services.rate_limited': 'Too many invocations — retry after a delay.',
// Internal / catch-all 'internal.server_error': 'Uncaught server error — bug or runtime failure.', 'internal.unknown': 'Client could not parse a non-standard error body.',}
/** Markers delimiting the generated block in `README.md`. */export const TABLE_START = '<!-- error-codes:start — generated from codes.ts by `deno task docs`; do not edit -->'export const TABLE_END = '<!-- error-codes:end -->'
/** * Render the registry as a Markdown table (code, default HTTP status, * description). Columns are padded to `deno fmt`'s table style so the * generated block survives a format pass unchanged. */export function renderErrorCodesTable(): string { const header = ['Code', 'HTTP', 'Use when'] const rows = (Object.keys(ErrorCodes) as KnownErrorCode[]).map((code) => [ `\`${code}\``, String(ErrorCodes[code].httpStatus), ErrorCodeDescriptions[code], ]) const widths = header.map((h, i) => Math.max(h.length, ...rows.map((row) => row[i].length)) ) const line = (cells: string[]) => `| ${cells.map((cell, i) => cell.padEnd(widths[i])).join(' | ')} |` return [ line(header), `| ${widths.map((w) => '-'.repeat(w)).join(' | ')} |`, ...rows.map(line), ].join('\n')}
/** * Return `readme` with the block between the markers replaced by a freshly * rendered table. Throws if the markers are missing or out of order. */export function spliceReadme(readme: string): string { const start = readme.indexOf(TABLE_START) const end = readme.indexOf(TABLE_END) if (start === -1 || end === -1 || end < start) { throw new Error('README.md is missing the error-codes markers') } return readme.slice(0, start + TABLE_START.length) + '\n\n' + renderErrorCodesTable() + '\n\n' + readme.slice(end)}
if (import.meta.main) { const readmeUrl = new URL('./README.md', import.meta.url) const current = await Deno.readTextFile(readmeUrl) const next = spliceReadme(current) if (next === current) { console.log('README.md error-code table is up to date') } else if (Deno.args.includes('--check')) { console.error('README.md error-code table is stale — run `deno task docs`') Deno.exit(1) } else { await Deno.writeTextFile(readmeUrl, next) console.log('README.md error-code table updated') }}