totalum-sdk 0.1.0-dev.10

package/totalum-sdk.md

@@ -0,0 +1,1088 @@
+# totalum-sdk
+
+> Generated by `scripts/gen-docs.mjs` from the types and JSDoc of `totalum-sdk`. Do not edit.
+
+The package every Totalum v2 app — and the coding agent building it — uses for Totalum's built-in capabilities: the
+project database (`totalum-sdk/d1`, used through Drizzle) and every integration over HTTPS. Never add a third-party
+SDK or key for something listed here.
+
+## Install and configure
+
+```sh
+npm install --save-exact totalum-sdk
+```
+
+Server-side only (route handlers, server actions, cron handlers, `npx tsx scripts/<name>.ts`). Every namespace reads the
+same environment at call time, never at import; an option of the same name wins:
+
+| Variable | Option | Meaning |
+|---|---|---|
+| `TOTALUM_PROJECT_KEY` | `key` | The project key `tlm_pk_…`. Never `NEXT_PUBLIC_`. Missing → `SDK_NOT_CONFIGURED`. |
+| `TOTALUM_SDK_API_URL` | `apiUrl` | Default `https://sdk-api.totalum.app`. |
+| `TOTALUM_ENV` | `env` | `dev` or `live` (default), sent as `x-totalum-env`: the database `totalum-sdk/d1` targets over HTTPS, and dev vs live usage. |
+| `TOTALUM_FILES_URL` | `filesUrl` | The public files host of `files.url()`. |
+| `TOTALUM_AI_BASE_URL` | `aiBaseUrl` | The exact-OpenRouter gateway `ai.gatewayConfig()` returns. |
+| `TOTALUM_WEBHOOK_SECRET` | argument | The secret `webhooks.verify` checks `Totalum-Signature` with. |
+
+```ts
+import { totalum } from 'totalum-sdk';            // or one namespace: import { totalumFiles } from 'totalum-sdk/files';
+const file = await totalum.files.upload(blob, { name: 'avatar.png' });
+```
+
+## Errors
+
+Every failure throws `TotalumError` (`isTotalumError(e)`) with `errorCode` (frozen), `status`, `details` and
+`requestId`; `TotalumD1Error` (`message` shaped like a native D1 error) and `TotalumWebhookError` extend it. A capped
+or disabled feature (`FEATURE_LIMIT_REACHED` 429, `FEATURE_DISABLED` 403) refuses only its own namespace; at a zero
+balance paid calls answer `INSUFFICIENT_CREDITS` 402.
+
+**Node-only methods** throw `NODE_ONLY` inside a Worker (the preview and the published app both run on Cloudflare
+Workers) and name the HTTPS replacement: `ai.video.wait()`.
+
+Client-side codes: `SDK_NOT_CONFIGURED`, `NOT_SUPPORTED`, `BATCH_FOREIGN_STATEMENT`, `TRANSACTIONS_NOT_SUPPORTED`, `NETWORK_ERROR`, `TIMEOUT`, `RESPONSE_PARSE_ERROR`, `NODE_ONLY`, `WEBHOOK_SECRET_MISSING`, `WEBHOOK_SIGNATURE_INVALID`, `WEBHOOK_TIMESTAMP_EXPIRED`.
+
+Server codes: `SERVICE_UNAUTHORIZED`, `SERVICE_REPLAY`, `ACTOR_MISMATCH`, `PAYLOAD_TOO_LARGE`, `VALIDATION_ERROR`, `PROJECT_NOT_FOUND`, `OPERATION_IN_PROGRESS`, `AGENT_RUNNING`, `PROJECT_MOVED`, `OBJECT_MIGRATING`, `INDEX_SHARD_UNAVAILABLE`, `RATE_LIMIT_EXCEEDED`, `PROJECT_PAUSED_RUNAWAY`, `PROJECT_PAUSED_BALANCE`, `PROJECT_SUSPENDED`, `PROJECT_HIBERNATED`, `PROJECT_DELETED`, `PROJECT_PAUSED_BY_USER`, `LIFECYCLE_NOT_APPLICABLE`, `PROJECT_NOT_PAUSED`, `PAUSE_DUMP_EXPIRED`, `PAUSE_VERIFICATION_FAILED`, `DEPLOYMENT_IN_PROGRESS`, `REACTIVATE_IMPORT_MISMATCH`, `RESUME_IMPORT_MISMATCH`, `INSUFFICIENT_CREDITS`, `VCAAS_INSUFFICIENT_CREDITS`, `PROJECT_CREDIT_LIMIT_REACHED`, `FREE_PROMPTS_DISABLED`, `PLAN_REQUIRED`, `FEATURE_LIMIT_REACHED`, `FEATURE_DISABLED`, `AGENT_ALREADY_RUNNING`, `IMPORT_IN_PROGRESS`, `TOO_MANY_RUN_REQUESTS`, `PROMPT_SECURITY_VIOLATION`, `NO_PROCESS_RUNNING`, `RUN_NOT_FOUND`, `DEPLOYMENT_RUNNING`, `AUTO_EXECUTION_ALREADY_ACTIVE`, `REBUILD_RUNNING`, `SECRET_ALREADY_EXISTS`, `SECRET_LIMIT_EXCEEDED`, `RESERVED_SECRET_NAME`, `DUMP_NOT_FOUND`, `DUMP_INVALID`, `RESTORE_TARGET_NOT_EMPTY`, `ENGINE_NOT_SUPPORTED`, `ENGINE_V2_DISABLED`, `V2_TEMPORARILY_DISABLED`, `ENGINE_REQUEST_NOT_ELIGIBLE`, `ENGINE_MISMATCH`, `INVALID_ENGINE_VERSION`, `PROJECT_ENGINE_MISMATCH`, `ENGINE_UNAVAILABLE`, `PREVIEW_LABEL_TOO_LONG`, `PROJECT_ALREADY_EXISTS`, `CLOUDFLARE_API_ERROR`, `PROVISIONING_BUSY`, `UNAUTHORIZED`, `LEGACY_KEY_NOT_SUPPORTED`, `SANDBOX_KEY_EXPIRED`, `AUTH_RATE_LIMITED`, `FORBIDDEN_SCOPE`, `KEY_ENV_MISMATCH`, `KEY_LIMIT_EXCEEDED`, `LIVE_DB_READ_ONLY`, `LIVE_WRITE_NEEDS_CONFIRMATION`, `DDL_NOT_ALLOWED`, `MIGRATION_IN_PROGRESS`, `MIGRATION_EDITED`, `SCHEMA_OUT_OF_SYNC`, `LIVE_MIGRATION_FAILED`, `DESTRUCTIVE_MIGRATION_NEEDS_CONFIRMATION`, `DEV_DATABASE_NOT_FOUND`, `DATABASE_ROLE_NOT_FOUND`, `BOOKMARK_NOT_FOUND`, `BACKUP_NOT_FOUND`, `BACKUP_NOT_DELETABLE`, `BACKUP_RATE_LIMITED`, `PRE_RESTORE_BACKUP_FAILED`, `RESTORE_VERIFY_FAILED`, `RUN_NOT_LATEST`, `DEV_DATABASE_EXISTS`, `SQL_ERROR`, `SQL_MULTI_STATEMENT`, `SQL_STATEMENT_TOO_LARGE`, `SQL_TOO_MANY_PARAMS`, `STATEMENT_NOT_ALLOWED`, `VIRTUAL_TABLES_NOT_SUPPORTED`, `USE_STORAGE_FOR_FILES`, `D1_TYPE_ERROR`, `MIGRATION_INVALID`, `SYSTEM_TABLE_READ_ONLY`, `SQL_READ_ONLY`, `RESULT_TOO_LARGE`, `NL_QUERY_UNANSWERABLE`, `QUERY_TIMEOUT`, `DB_OVERLOADED`, `D1_TRANSIENT`, `DB_FULL_NEAR_LIMIT`, `IDEMPOTENCY_KEY_REUSED`, `IDEMPOTENT_REPLAY_UNAVAILABLE`, `TABLE_NOT_FOUND`, `SCHEMA_TOO_LARGE_FOR_COUNTS`, `EXEC_REQUIRES_MIGRATE_MODE`, `MIGRATION_UNKNOWN_IN_DB`, `QUERY_LIMIT_EXCEEDED`, `STORAGE_LIMIT_EXCEEDED`, `METER_UNAVAILABLE`, `COLUMN_NOT_FOUND`, `VALUE_NOT_ALLOWED`, `COLUMN_REQUIRED`, `FILTER_TOO_COMPLEX`, `OFFSET_TOO_LARGE`, `BULK_TOO_LARGE`, `NOT_A_JUNCTION_TABLE`, `AMBIGUOUS_RELATION`, `LIVE_WRITE_CONFIRMATION_REQUIRED`, `RECORD_NOT_FOUND`, `DEV_NAME_GUARD`, `PROD_NAME_GUARD`, `INVALID_RUN_REQUEST`, `RUN_ALREADY_ACTIVE`, `RUN_CONFLICT`, `INVALID_CREDENTIALS`, `ADAPTER_UNAVAILABLE`, `DISK_FULL`, `DEPLOY_FIX_ATTEMPTS_EXHAUSTED`, `TOKEN_REVOKED`, `AM_UPDATE_DOWNLOAD_FAILED`, `AM_UPDATE_BAD_SHA`, `AM_UPDATE_BAD_SIGNATURE`, `AM_UPDATE_INCOMPATIBLE_IMAGE`, `AM_UPDATE_START_FAILED`, `AM_VERSION_UNAVAILABLE`, `AM_UPDATE_FAILED`, `RELEASE_CANARY_NOT_PASSED`, `RELEASE_NOT_FOUND`, `RELEASE_ROLLOUT_ACTIVE`, `RELEASE_GUARD_PAUSED`, `RELEASE_BUILD_UNAVAILABLE`, `VISUAL_EDIT_PREVIEW_DEPLOYING`, `VISUAL_EDIT_NOT_PATCHABLE`, `VISUAL_EDIT_BASE_MISMATCH`, `VISUAL_EDIT_TYPECHECK_FAILED`, `INVALID_VISUAL_EDIT`, `IMAGE_VERSION_NOT_FOUND`, `IMAGE_VERSION_NOT_PROMOTABLE`, `REALTIME_TICKET_INVALID`, `REALTIME_TICKET_EXPIRED`, `REALTIME_PERMISSION_DENIED`, `REALTIME_MESSAGE_TOO_LARGE`, `REALTIME_MESSAGE_RATE_EXCEEDED`, `REALTIME_CONNECTION_LIMIT_REACHED`, `REALTIME_ROOM_LIMIT_REACHED`, `CONFIRMATION_REQUIRED`, `MIGRATION_NOT_REVERSIBLE`, `ALREADY_ON_PROVIDER`, `DATABASE_MIGRATING`, `LOGWATCH_INACTIVE`, `AGENT_LOG_READS_LIMIT`, `LOGS_UPSTREAM_ERROR`, `ANALYTICS_INVALID_QUERY`, `ANALYTICS_UPSTREAM_ERROR`, `ANALYTICS_WINDOW_OUT_OF_RETENTION`, `INVALID_CIDR`, `RATE_LIMIT_ABOVE_PLAN`, `RATE_LIMIT_DISABLE_NOT_ALLOWED`, `OWNER_ONLY`, `SIGNING_NOT_CONFIGURED`, `SIGNING_ALREADY_CONFIGURED`, `SIGNING_INVALID_KEYSTORE`, `SIGNING_INVALID_ASC_KEY`, `KEYSTORE_DOWNLOAD_EXPIRED`, `KEYSTORE_NOT_DOWNLOADABLE`, `MOBILE_BUILD_RUNNING`, `MOBILE_BUILD_NOT_FOUND`, `MOBILE_BUILD_NOT_READY`, `DOWNLOAD_EXPIRED`, `PROCESS_IN_PROGRESS`, `SANDBOX_NOT_RUNNING`, `MOBILE_LAYER_MISSING`, `MOBILE_BUILD_FAILED`, `MOBILE_ARTIFACT_INVALID`, `SIGNING_FINGERPRINT_MISMATCH`, `AM_RESTARTED`, `LIMIT_ABOVE_PLAN_CEILING`, `UNKNOWN_FEATURE`, `INVALID_LIMIT`, `FEATURE_NOT_DISABLABLE`, `USE_PUT_LIMITS`, `LIMIT_NOT_USER_EDITABLE`, `NOT_AVAILABLE_FOR_ENGINE`, `INVALID_AMOUNT`, `REFUND_EXCEEDS_CHARGES`, `IDEMPOTENCY_CONFLICT`, `ORGANIZATION_NOT_FOUND`, `ACCOUNT_NOT_FOUND`, `PROVIDER_UNAVAILABLE`, `URL_NOT_ALLOWED`, `JOB_NOT_FOUND`, `FILE_TOO_LARGE`, `UNSUPPORTED_FILE_TYPE`, `FILE_NOT_FOUND`, `FILE_KEY_FORBIDDEN`, `FILE_UPLOAD_ERROR`, `FILE_DOWNLOAD_ERROR`, `FILE_DELETE_ERROR`, `UPLOAD_NOT_COMPLETED`, `MISSING_URL`, `MISSING_INPUT`, `MISSING_EXTRACTION_CONFIG`, `MISSING_QUERY`, `SCRAPE_FAILED`, `EXTRACT_FAILED`, `SCREENSHOT_FAILED`, `SEARCH_FAILED`, `SCRAPE_BLOCKED`, `SESSION_NOT_FOUND`, `SESSION_EXPIRED`, `SESSION_BUSY`, `SESSION_LIMIT_REACHED`, `SESSION_ENDED_INSUFFICIENT_CREDITS`, `ACTION_TIMEOUT`, `ACTION_FAILED`, `UNKNOWN_COMMAND`, `BATCH_TOO_LARGE`, `SKIPPED`, `UPLOAD_TOO_LARGE`, `DOWNLOAD_TOO_LARGE`, `CAPTURE_LIMIT_REACHED`, `CAPTCHA_UNSOLVED`, `BROWSER_CDP_NODE_ONLY`, `DIALOG_NOT_OPEN`, `STEALTH_TIER_UNAVAILABLE`, `DOMAIN_NOT_ALLOWED`, `CONTEXT_SEED_UNSUPPORTED`, `EXTENSION_TOO_LARGE`, `NL_PROVIDER_UNAVAILABLE`, `PROGRAM_TOO_LARGE`, `PROGRAM_UNBOUNDED`, `UNKNOWN_STEP`, `PROGRAM_IN_FLIGHT`, `PROGRAM_TIMEOUT`, `PROGRAM_NOT_FOUND`, `PROGRAM_STEP_FAILED`, `PROGRAM_LIMIT_REACHED`, `CREATE_PDF_FROM_HTML_ERROR`, `GENERATE_PDF_BY_URL_ERROR`, `PDF_TIMEOUT`, `PDF_TOO_LARGE`, `FILENAME_REQUIRED`, `SCANUM_EYE_ARRAY_NOT_SUPPORTED`, `INVALID_EXTRA_FIELD_TYPE`, `SCANUM_EYE_PDF_NOT_SUPPORTED`, `UNSUPPORTED_SCAN_MODEL`, `SCAN_DOCUMENT_ERROR`, `SCAN_INVOICE_ERROR`, `OCR_IMAGE_PROCESSING_ERROR`, `OCR_PDF_PROCESSING_ERROR`, `SCAN_TOO_MANY_PAGES`, `SCAN_PDF_ENCRYPTED`, `SCAN_XFA_UNSUPPORTED`, `AUDIO_FILE_REQUIRED`, `AUDIO_FILE_TOO_LARGE`, `INVALID_AUDIO_FORMAT`, `AUDIO_TRANSCRIPTION_ERROR`, `TTS_TEXT_TOO_LONG`, `TTS_VOICE_UNKNOWN`, `TOO_MANY_AUDIO_TRANSCRIPTIONS`, `EMAIL_SEND_FAILED`, `TOO_MANY_ATTACHMENTS`, `INVALID_ATTACHMENT_URL`, `ATTACHMENT_TOO_LARGE`, `TOO_MANY_RECIPIENTS`, `EMAIL_RECIPIENT_SUPPRESSED`, `EMAIL_DOMAIN_NOT_VERIFIED`, `EMAIL_LOCAL_PART_TAKEN`, `EMAIL_SENDING_PAUSED`, `EMAIL_DOMAINS_REQUIRE_PAID_PLAN`, `SUPPRESSION_PERMANENT`, `DEV_RECIPIENT_NOT_ALLOWED`, `CRON_LIMIT_REACHED`, `INVALID_SCHEDULE`, `CRON_URL_NOT_ALLOWED`, `CRON_JOB_NOT_FOUND`, `CRON_REQUIRES_PUBLISHED_PROJECT`, `URL_NOT_PROJECT_HOST`, `INDEXNOW_ERROR`, `MCP_VERIFY_FAILED`, `MCP_NAME_RESERVED`, `MCP_LIMIT_REACHED`, `MCP_SERVER_NOT_FOUND`, `PAYMENTS_NOT_ENABLED`, `PAYMENTS_LIVE_ONBOARDING_REQUIRED`, `CARD_DATA_NOT_ACCEPTED`, `STRIPE_ERROR`, `STRIPE_RATE_LIMITED`, `PAYMENTS_WEBHOOK_SIGNATURE_INVALID`, `AI_MODEL_NOT_ALLOWED`, `AI_MODEL_UNKNOWN`, `AI_INVALID_SCHEMA`, `AI_CONTENT_BLOCKED`, `AI_CONTEXT_TOO_LONG`, `AI_PROVIDER_QUOTA`, `AI_PROVIDER_UNAVAILABLE`, `AI_STREAM_ERROR`, `AI_VIDEO_JOB_NOT_FOUND`, `AI_VIDEO_FAILED`, `MISSING_VIDEO_URL`, `MISSING_PROMPT`, `INVALID_VIDEO_URL`, `INVALID_VIDEO_URL_PROTOCOL`, `INVALID_MIME_TYPE_HINT`, `VIDEO_TOO_LARGE`, `VIDEO_URL_UNREACHABLE`, `VIDEO_URL_NOT_A_VIDEO`, `YOUTUBE_VIDEO_UNAVAILABLE`, `NO_PAYMENT_METHOD`, `DOMAIN_CONTACT_REQUIRED`, `DOMAIN_UNAVAILABLE`, `DOMAIN_PREMIUM_NOT_ALLOWED`, `TLD_NOT_ALLOWED`, `DOMAIN_LIMIT_REACHED`, `PRICE_CHANGED`, `PAYMENT_FAILED`, `REGISTRATION_FAILED`, `DOMAIN_NOT_RENEWABLE`, `DOMAIN_ALREADY_ATTACHED`, `DNS_RECORD_MANAGED`, `DNS_RECORD_CONFLICT`, `DNS_RECORD_LIMIT`, `DOMAIN_TRANSFER_LOCKED`, `DOMAIN_NOT_FOUND`, `DOMAIN_IN_USE`, `DOMAIN_ALREADY_ADDED`, `NO_DEPLOYMENT`, `REDIRECT_LIMIT_REACHED`, `REDIRECT_INVALID`, `APEX_NOT_FLATTENABLE`, `SECOND_FACTOR_NOT_CONFIGURED`, `PASSWORD_REQUIRED`, `PASSWORD_INCORRECT`, `TOO_MANY_ATTEMPTS`, `CONFIRMATION_MISMATCH`, `INVALID_TOKEN`, `MISSING_PERMISSIONS`, `REPO_NOT_FOUND`, `REPO_MISSING_BRANCHES`, `UNKNOWN`, `SANDBOX_NOT_READY`, `SYNC_FAILED`, `TOKEN_EXPIRED`, `GITHUB_NOT_CONNECTED`, `FIGMA_TOKEN_MISSING`, `FIGMA_TOKEN_MALFORMED`, `FIGMA_TOKEN_INVALID`, `FIGMA_TOKEN_FORBIDDEN`, `FIGMA_RATE_LIMITED`, `FIGMA_UNREACHABLE`, `INVALID_IMPORT_CODE`, `IMPORT_SOURCE_GONE`, `PROJECT_NOT_IMPORTABLE`, `PROJECT_IMPORT_LIMIT_REACHED`, `PROJECT_EXPORT_LIMIT_REACHED`, `VERSION_NOT_FOUND`, `INVALID_CODE_EDIT`, `CODE_EDIT_FAILED`, `BADGE_IN_SOURCE`.
+
+## `totalum-sdk`
+
+Every namespace below on one object (`totalum.files`, `totalum.ai`, …); the root entry also re-exports every subpath's exports, and each subpath can be imported alone (smaller bundles).
+
+### `createTotalum`
+
+```ts
+createTotalum(options?: TotalumOptions)
+```
+
+Every integration namespace on one object, each built on first access with the same options — no I/O
+and no env read until a method is called. The database is `totalumD1()` from `totalum-sdk/d1`, not a namespace.
+
+```ts
+const totalum = createTotalum({ env: 'dev' });
+await totalum.email.send({ to: 'a@b.c', subject: 'Hi', html: '<p>Hi</p>' });
+```
+
+### `totalum`
+
+```ts
+const totalum
+```
+
+The default instance, configured from the environment (`TOTALUM_PROJECT_KEY`, `TOTALUM_SDK_API_URL`, `TOTALUM_ENV`).
+
+## `totalum-sdk/d1`
+
+### `totalumD1`
+
+```ts
+totalumD1(options?: TotalumD1Options): D1Database
+```
+
+A `D1Database` for the project's own database wherever the code runs: the bound
+`TOTALUM_DB` inside a Worker, the libsql adapter when the environment moved to Turso, the local D1 that
+`initOpenNextCloudflareForDev()` binds under `next dev`, and an HTTPS client to SDK-API everywhere else.
+Detection happens on the first statement, never at call time.
+
+## `totalum-sdk/files`
+
+### `totalumFiles`
+
+```ts
+totalumFiles(options?: TotalumFilesOptions)
+```
+
+`totalum.files` over HTTPS with the project key. Every call returns the file
+descriptor `{key, fileName, fileSize, contentType, fileUrl, visibility, createdAt}` meant to be stored as-is in the
+row's file column; failures throw `TotalumError` with SDK-API's frozen code.
+
+#### `files.upload`
+
+```ts
+files.upload(input: string | Blob | ArrayBuffer | Uint8Array<ArrayBufferLike>, opts?: UploadOptions): Promise<{ key: string; fileName: string; fileSize: number; contentType: string; fileUrl: string | null; visibility: 'public-by-link' | 'private'; createdAt: string; etag?: string | undefined; storageClass?: 'Standard' | 'InfrequentAccess' | undefined; name?: string | undefined; url?: string | null | undefined; size?: number | undefined; id?: string | undefined; fileNameId?: string | undefined; }>
+```
+
+Up to 25 MB through SDK-API; larger files go through `getUploadUrl` + `complete`.
+
+#### `files.getUploadUrl`
+
+```ts
+files.getUploadUrl(input: { name: string; contentType: string; size: number; folder?: string | undefined; private?: boolean | undefined; }): Promise<{ uploadUrl: string; key: string; headers: Record<string, string>; expiresAt: string; }>
+```
+
+A presigned PUT (15 min, bound to this type and size) for a direct browser/Node upload; then `complete(key)`.
+
+#### `files.complete`
+
+```ts
+files.complete(key: string): Promise<{ key: string; fileName: string; fileSize: number; contentType: string; fileUrl: string | null; visibility: 'public-by-link' | 'private'; createdAt: string; etag?: string | undefined; storageClass?: 'Standard' | 'InfrequentAccess' | undefined; name?: string | undefined; url?: string | null | undefined; size?: number | undefined; id?: string | undefined; fileNameId?: string | undefined; }>
+```
+
+Registers a file uploaded with `getUploadUrl` and returns its descriptor.
+
+#### `files.list`
+
+```ts
+files.list(q?: Partial<Record<'name' | 'folder' | 'type' | 'createdFrom' | 'createdTo' | 'sizeFrom' | 'sizeTo' | 'cursor' | 'limit', string | number>>): Promise<{ items: { key: string; fileName: string; fileSize: number; contentType: string; fileUrl: string | null; visibility: 'public-by-link' | 'private'; createdAt: string; etag?: string | undefined; storageClass?: 'Standard' | 'InfrequentAccess' | undefined; name?: string | undefined; url?: string | null | undefined; size?: number | undefined; id?: string | undefined; fileNameId?: string | undefined; }[]; nextCursor: string | null; totalBytes: number; fileCount: number; }>
+```
+
+One page of the project's files, newest first: filter by `folder`, `name`, `type`, created and size ranges; `cursor`
+from the previous page's `nextCursor`.
+
+#### `files.get`
+
+```ts
+files.get(key: string): Promise<{ key: string; fileName: string; fileSize: number; contentType: string; fileUrl: string | null; visibility: 'public-by-link' | 'private'; createdAt: string; etag?: string | undefined; storageClass?: 'Standard' | 'InfrequentAccess' | undefined; name?: string | undefined; url?: string | null | undefined; size?: number | undefined; id?: string | undefined; fileNameId?: string | undefined; }>
+```
+
+The descriptor of one file; `FILE_NOT_FOUND` (404) when it does not exist.
+
+#### `files.getSignedUrl`
+
+```ts
+files.getSignedUrl(key: string, opts?: { expiresInSeconds?: number | undefined; download?: boolean | undefined; }): Promise<string>
+```
+
+A presigned GET that R2 verifies: 15 min by default, at most 7 days — the way to hand a private file to a browser.
+
+#### `files.getDownloadUrl`
+
+```ts
+files.getDownloadUrl(key: string, opts?: { expiresInSeconds?: number | undefined; download?: boolean | undefined; }): Promise<string>
+```
+
+Same as `getSignedUrl`.
+
+#### `files.presign`
+
+```ts
+files.presign(keys: string[], opts?: { ttl?: number | undefined; download?: boolean | undefined; }): Promise<Record<string, string>>
+```
+
+Signed GET URLs for many keys at once (`ttl` in seconds, ≤ 7 days).
+
+#### `files.delete`
+
+```ts
+files.delete(keys: string | string[]): Promise<void>
+```
+
+Deletes one key, or up to 1000 keys at once.
+
+#### `files.stream`
+
+```ts
+files.stream(key: string, opts?: { range?: string | undefined; }): Promise<Response>
+```
+
+The object itself (private files included), with `Range` support; errors throw like every other call.
+
+#### `files.url`
+
+```ts
+files.url(key: string): string
+```
+
+Sync, no I/O: the public URL of a `p/` key, or the authenticated SDK-API URL of a private `pv/` key.
+
+## `totalum-sdk/payments`
+
+### `totalumPayments`
+
+```ts
+totalumPayments(options?: TotalumClientOptions)
+```
+
+`totalum.payments` over SDK-API `/v1/payments/*` with a project key (scope `payments`): Stripe
+Connect direct charges on the project's own connected account. Card data never passes through here — send buyers to
+the hosted Checkout `url` (SAQ-A); SDK-API refuses card fields with `CARD_DATA_NOT_ACCEPTED`.
+
+#### `payments.getStatus`
+
+```ts
+payments.getStatus(): Promise<{ enabled: boolean; mode: 'connect' | 'own_key'; accountId: string | null; livemode: boolean; chargesEnabled: boolean; payoutsEnabled: boolean; detailsSubmitted: boolean; requirements: { currentlyDue: string[]; pastDue: string[]; eventuallyDue: string[]; }; applicationFeeBps: number; }>
+```
+
+Whether the project's Stripe account can take payments (charges, payouts, pending requirements).
+
+#### `payments.onboardingLink`
+
+```ts
+payments.onboardingLink(input: { returnUrl: string; refreshUrl: string; type?: 'account_onboarding' | 'account_update' | undefined; country?: string | undefined; }): Promise<{ url: string; expiresAt: string; }>
+```
+
+Stripe's hosted onboarding for the project owner (single use; never for the agent's sandbox key).
+
+#### `payments.createCheckout`
+
+```ts
+payments.createCheckout(input: { mode: 'payment' | 'subscription' | 'setup'; successUrl: string; cancelUrl: string; lineItems?: ({ priceId: string; quantity: number; } | { name: string; unitAmount: number; currency: string; quantity: number; })[] | undefined; currency?: string | undefined; customerEmail?: string | undefined; customerId?: string | undefined; metadata?: Record<string, string> | undefined; allowPromotionCodes?: boolean | undefined; automaticTax?: boolean | undefined; trialDays?: number | undefined; clientReferenceId?: string | undefined; }): Promise<{ id: string; url: string; }>
+```
+
+A hosted Checkout Session: `payment`, `subscription`, or `setup` (save a card for later). Redirect to `url`.
+
+#### `payments.customerPortalLink`
+
+```ts
+payments.customerPortalLink(input: { customerId: string; returnUrl: string; }): Promise<{ url: string; }>
+```
+
+Stripe's hosted portal where a customer manages their subscriptions and saved cards.
+
+## `totalum-sdk/webhooks`
+
+### `verifyWebhook`
+
+```ts
+verifyWebhook(rawBody: string, headers: Headers | Record<string, string | undefined>, secret?: string | undefined, now?: number): Promise<{ id: string; type: string; createdAt: string; projectId: string; env: 'dev' | 'live'; data: Record<string, unknown>; livemode?: boolean | undefined; }>
+```
+
+`totalum.webhooks.verify`: checks `Totalum-Signature: t=…,v1=…` — HMAC-SHA256 keyed with the
+endpoint's secret string over `${t}.${rawBody}` — within ±300 s, and returns the parsed event. Pass the body exactly
+as received (`await request.text()`). `secret` defaults to `TOTALUM_WEBHOOK_SECRET`.
+
+```ts
+const event = await verifyWebhook(await request.text(), request.headers);
+```
+
+### `totalumWebhooks`
+
+```ts
+totalumWebhooks(options?: TotalumClientOptions)
+```
+
+`totalum.webhooks` over SDK-API `/v1/webhooks` (a key with scope `*`): where the project receives its
+signed events (payments, e-mail, browser programs, `project.credits.exhausted`) and the secret they are signed with.
+
+#### `webhooks.verify`
+
+```ts
+webhooks.verify(rawBody: string, headers: Headers | Record<string, string | undefined>, secret?: string | undefined, now?: number): Promise<{ id: string; type: string; createdAt: string; projectId: string; env: 'dev' | 'live'; data: Record<string, unknown>; livemode?: boolean | undefined; }>
+```
+
+Same as `verifyWebhook`: checks `Totalum-Signature` and returns the parsed event.
+
+#### `webhooks.get`
+
+```ts
+webhooks.get(): Promise<{ url: string | null; enabled: boolean; secretPrefix: string | null; }>
+```
+
+The endpoint and the first characters of its secret (the secret itself is shown only by `rotateSecret`).
+
+#### `webhooks.setUrl`
+
+```ts
+webhooks.setUrl(url: string): Promise<{ url: string | null; enabled: boolean; secretPrefix: string | null; }>
+```
+
+Sets the `https://` URL the project's events are delivered to.
+
+#### `webhooks.rotateSecret`
+
+```ts
+webhooks.rotateSecret(): Promise<{ secret: string; }>
+```
+
+A new signing secret, shown once; the old one keeps co-signing for 24 h. Store it as `TOTALUM_WEBHOOK_SECRET`.
+
+## `totalum-sdk/web`
+
+### `totalumWeb`
+
+```ts
+totalumWeb(options?: TotalumClientOptions)
+```
+
+`totalum.web` over SDK-API `/v1/web/*` (scope `web`): Firecrawl scrape/search/map/crawl and Browser
+Run screenshots, charged provider cost × 28 — every result carries `usage.credits`.
+
+#### `web.scrape`
+
+```ts
+web.scrape(url: string, opts?: Omit<{ url: string; formats?: ('screenshot' | 'markdown' | 'html' | 'rawHtml' | 'links' | 'json' | 'summary')[] | undefined; onlyMainContent?: boolean | undefined; waitFor?: number | undefined; timeout?: number | undefined; proxy?: 'basic' | 'stealth' | 'auto' | undefined; location?: { country?: string | undefined; languages?: string[] | undefined; } | undefined; actions?: Record<string, unknown>[] | undefined; schema?: Record<string, unknown> | undefined; prompt?: string | undefined; cacheMaxAgeMs?: number | undefined; }, 'url'>): Promise<{ url: string; statusCode: number; metadata: { sourceURL: string; title?: string | undefined; description?: string | undefined; language?: string | undefined; }; usage: { credits: number; vendor?: string | undefined; units?: number | undefined; vendorCostUsd?: number | undefined; }; markdown?: string | undefined; html?: string | undefined; rawHtml?: string | undefined; links?: string[] | undefined; screenshotUrl?: string | undefined; json?: unknown; summary?: string | undefined; contentUrl?: string | undefined; }>
+```
+
+One page as `markdown`, `html`, `links`, … (Firecrawl).
+
+```ts
+const { markdown } = await web.scrape('https://example.com', { formats: ['markdown'] });
+```
+
+#### `web.search`
+
+```ts
+web.search(query: string, opts?: Omit<{ query: string; limit?: number | undefined; sources?: ('web' | 'news' | 'images')[] | undefined; location?: { country?: string | undefined; city?: string | undefined; } | undefined; timeRange?: 'day' | 'month' | 'week' | 'year' | undefined; scrapeOptions?: { formats?: ('screenshot' | 'markdown' | 'html' | 'rawHtml' | 'links' | 'json' | 'summary')[] | undefined; onlyMainContent?: boolean | undefined; waitFor?: number | undefined; timeout?: number | undefined; proxy?: 'basic' | 'stealth' | 'auto' | undefined; location?: { country?: string | undefined; languages?: string[] | undefined; } | undefined; actions?: Record<string, unknown>[] | undefined; schema?: Record<string, unknown> | undefined; prompt?: string | undefined; cacheMaxAgeMs?: number | undefined; } | undefined; }, 'query'>): Promise<{ web: { title: string; url: string; position: number; snippet?: string | undefined; }[]; news?: { title: string; url: string; position: number; snippet?: string | undefined; }[] | undefined; images?: Record<string, unknown>[] | undefined; scraped?: { url: string; statusCode: number; metadata: { sourceURL: string; title?: string | undefined; description?: string | undefined; language?: string | undefined; }; markdown?: string | undefined; html?: string | undefined; rawHtml?: string | undefined; links?: string[] | undefined; screenshotUrl?: string | undefined; json?: unknown; summary?: string | undefined; contentUrl?: string | undefined; }[] | undefined; } & { usage: { vendor?: string | undefined; units?: number | undefined; credits: number; }; }>
+```
+
+A web search; with `scrapeOptions` each result also carries its page content.
+
+#### `web.map`
+
+```ts
+web.map(url: string, opts?: Omit<{ url: string; search?: string | undefined; limit?: number | undefined; }, 'url'>): Promise<{ links: string[]; } & { usage: { vendor?: string | undefined; units?: number | undefined; credits: number; }; }>
+```
+
+The URLs of a site (sitemap and links), without fetching the pages.
+
+#### `web.crawl`
+
+```ts
+web.crawl(url: string, opts?: Omit<{ url: string; limit?: number | undefined; maxDepth?: number | undefined; includePaths?: string[] | undefined; excludePaths?: string[] | undefined; scrapeOptions?: { formats?: ('screenshot' | 'markdown' | 'html' | 'rawHtml' | 'links' | 'json' | 'summary')[] | undefined; onlyMainContent?: boolean | undefined; waitFor?: number | undefined; timeout?: number | undefined; proxy?: 'basic' | 'stealth' | 'auto' | undefined; location?: { country?: string | undefined; languages?: string[] | undefined; } | undefined; actions?: Record<string, unknown>[] | undefined; schema?: Record<string, unknown> | undefined; prompt?: string | undefined; cacheMaxAgeMs?: number | undefined; } | undefined; webhook?: boolean | undefined; }, 'url'>): Promise<{ jobId: string; estimatedCredits?: number | undefined; }>
+```
+
+`202 {jobId}`: poll `crawlStatus` until the job leaves `running`; that read settles its charge.
+
+#### `web.crawlStatus`
+
+```ts
+web.crawlStatus(jobId: string): Promise<{ jobId: string; status: 'completed' | 'queued' | 'running' | 'failed' | 'cancelled' | 'expired'; total: number; completed: number; creditsUsed: number; data: { url: string; statusCode: number; metadata: { sourceURL: string; title?: string | undefined; description?: string | undefined; language?: string | undefined; }; markdown?: string | undefined; html?: string | undefined; rawHtml?: string | undefined; links?: string[] | undefined; screenshotUrl?: string | undefined; json?: unknown; summary?: string | undefined; contentUrl?: string | undefined; }[]; next?: string | undefined; resultUrl?: string | undefined; }>
+```
+
+The crawl job: `status`, pages so far and their content.
+
+#### `web.cancelCrawl`
+
+```ts
+web.cancelCrawl(jobId: string): Promise<{ jobId: string; status: 'completed' | 'queued' | 'running' | 'failed' | 'cancelled' | 'expired'; total: number; completed: number; creditsUsed: number; data: { url: string; statusCode: number; metadata: { sourceURL: string; title?: string | undefined; description?: string | undefined; language?: string | undefined; }; markdown?: string | undefined; html?: string | undefined; rawHtml?: string | undefined; links?: string[] | undefined; screenshotUrl?: string | undefined; json?: unknown; summary?: string | undefined; contentUrl?: string | undefined; }[]; next?: string | undefined; resultUrl?: string | undefined; }>
+```
+
+Stops a running crawl; pages already crawled are charged.
+
+#### `web.screenshot`
+
+```ts
+web.screenshot(input: { url?: string | undefined; html?: string | undefined; fullPage?: boolean | undefined; viewport?: { width: number; height: number; } | undefined; format?: 'png' | 'jpeg' | 'webp' | undefined; waitForSelector?: string | undefined; inline?: boolean | undefined; }): Promise<{ key: string; url: string; format: 'png' | 'jpeg' | 'webp'; base64?: string | undefined; } & { usage: { vendor?: string | undefined; units?: number | undefined; credits: number; }; }>
+```
+
+A screenshot of a `url` or of inline `html`, stored as a project file (`key`, `url`).
+
+## `totalum-sdk/pdf`
+
+### `totalumPdf`
+
+```ts
+totalumPdf(options?: TotalumClientOptions)
+```
+
+`totalum.pdf` over `/v1/pdf/*` (scope `files:write`): a new file in the project's storage each time.
+
+#### `pdf.fromHtml`
+
+```ts
+pdf.fromHtml(input: { name: string; html?: string | undefined; base64HtmlString?: string | undefined; options?: { format?: string | undefined; landscape?: boolean | undefined; margin?: Record<string, string> | undefined; printBackground?: boolean | undefined; headerTemplate?: string | undefined; footerTemplate?: string | undefined; displayHeaderFooter?: boolean | undefined; } | undefined; waitForSelector?: string | undefined; }): Promise<{ url: string; fileName: string; key: string; } & { usage: { vendor?: string | undefined; units?: number | undefined; credits: number; }; }>
+```
+
+A PDF rendered from HTML, stored as a project file (`key`, `url`).
+
+```ts
+const { url } = await pdf.fromHtml({ html: '<h1>Invoice 12</h1>', name: 'invoice-12' });
+```
+
+#### `pdf.fromUrl`
+
+```ts
+pdf.fromUrl(input: { url: string; name: string; options?: { format?: string | undefined; landscape?: boolean | undefined; margin?: Record<string, string> | undefined; printBackground?: boolean | undefined; headerTemplate?: string | undefined; footerTemplate?: string | undefined; displayHeaderFooter?: boolean | undefined; } | undefined; cookies?: Record<string, unknown>[] | undefined; headers?: Record<string, string> | undefined; }): Promise<{ url: string; fileName: string; key: string; } & { usage: { vendor?: string | undefined; units?: number | undefined; credits: number; }; }>
+```
+
+A PDF of a web page, stored as a project file.
+
+## `totalum-sdk/scan`
+
+### `totalumScan`
+
+```ts
+totalumScan(options?: TotalumClientOptions)
+```
+
+`totalum.scan` over `/v1/scan/*` (scope `scan`): a vision model through Totalum's AI gateway.
+
+#### `scan.document`
+
+```ts
+scan.document(input: { properties: Record<string, Record<string, unknown>>; options?: { model?: 'scanum' | 'scanum-pro' | 'scanum-eye' | 'scanum-eye-pro' | undefined; removeFileAfterScan?: boolean | undefined; returnOcrFullResult?: boolean | undefined; scanDescription?: string | undefined; processEveryPdfPageAsDifferentScan?: boolean | undefined; maxPages?: number | undefined; pdfPages?: number[] | undefined; minimumConfidence?: number | undefined; } | undefined; fileName?: string | undefined; key?: string | undefined; url?: string | undefined; }): Promise<ScanDocumentResult>
+```
+
+Extracts the fields described by `properties` from a document or image (one set per page on request).
+
+#### `scan.ocr`
+
+```ts
+scan.ocr(input: { pages?: number[] | undefined; fileName?: string | undefined; key?: string | undefined; url?: string | undefined; }): Promise<{ text: string; pages: { markdown: string; width: number; height: number; words?: { text: string; bbox: number[]; }[] | undefined; }[]; fullDetails?: unknown; } & { usage: { vendor?: string | undefined; units?: number | undefined; credits: number; }; }>
+```
+
+The text of a document or image, per page as Markdown.
+
+## `totalum-sdk/speech`
+
+### `totalumSpeech`
+
+```ts
+totalumSpeech(options?: TotalumClientOptions)
+```
+
+`totalum.speech` over `/v1/speech/*` (scope `speech`): OpenRouter speech through Totalum.
+
+#### `speech.transcribe`
+
+```ts
+speech.transcribe(input: { audioBase64?: string | undefined; filename?: string | undefined; url?: string | undefined; language?: string | undefined; model?: 'fast' | 'accurate' | undefined; diarize?: boolean | undefined; timestamps?: 'word' | 'segment' | undefined; keyterms?: string[] | undefined; }): Promise<{ text: string; durationSec: number; usage: { credits: number; vendor?: string | undefined; units?: number | undefined; vendorCostUsd?: number | undefined; }; language?: string | undefined; segments?: { start: number; end: number; text: string; }[] | undefined; words?: { word: string; start: number; end: number; }[] | undefined; }>
+```
+
+Speech to text from `audioBase64` or a `url`; optional language, word timestamps and speakers.
+
+#### `speech.synthesize`
+
+```ts
+speech.synthesize(input: { text: string; voice?: string | undefined; language?: string | undefined; model?: 'standard' | 'premium' | undefined; format?: 'mp3' | 'wav' | 'opus' | undefined; speed?: number | undefined; store?: boolean | undefined; }): Promise<{ key: string; url: string; usage: { credits: number; vendor?: string | undefined; units?: number | undefined; vendorCostUsd?: number | undefined; }; } | { audio: ArrayBuffer; contentType: string; credits: number; }>
+```
+
+The audio bytes, or with `store: true` the stored file `{key, url, usage}`; `credits` is the call's hold.
+
+## `totalum-sdk/ai`
+
+### `totalumAi`
+
+```ts
+totalumAi(options?: TotalumAiOptions)
+```
+
+`totalum.ai` over SDK-API `/v1/ai/*` (scope `ai`): aliases `cheap|normal|best` or any
+OpenRouter slug, every call priced `usage.cost × 28` and returned with its credits. No `ai.agent()` — the
+agent loop is the template's `src/agents/` on the Vercel AI SDK, pointed at `gatewayConfig()`.
+
+#### `ai.chat`
+
+```ts
+ai.chat(req: Omit<{ messages: { [x: string]: unknown; role: 'user' | 'system' | 'assistant' | 'tool' | 'developer'; content: unknown; }[]; model?: string | undefined; tools?: Record<string, unknown>[] | undefined; toolChoice?: unknown; parallelToolCalls?: boolean | undefined; responseFormat?: Record<string, unknown> | undefined; temperature?: number | undefined; maxTokens?: number | undefined; reasoning?: { effort: string; } | undefined; serverTools?: ('web_search' | 'image_generation' | 'web_fetch' | 'datetime')[] | undefined; maxToolCalls?: number | undefined; stream?: boolean | undefined; cache?: { ttlSec: number; } | undefined; zdr?: boolean | undefined; fastMode?: boolean | undefined; user?: string | undefined; }, 'stream'>): Promise<ChatResult>
+```
+
+A chat completion; `model` is an alias (`cheap`, `normal`, `best`) or any OpenRouter slug.
+
+```ts
+const { text } = await ai.chat({ model: 'cheap', messages: [{ role: 'user', content: 'Hi' }] });
+```
+
+#### `ai.chat.stream`
+
+```ts
+ai.chat.stream(req: Omit<{ messages: { [x: string]: unknown; role: 'user' | 'system' | 'assistant' | 'tool' | 'developer'; content: unknown; }[]; model?: string | undefined; tools?: Record<string, unknown>[] | undefined; toolChoice?: unknown; parallelToolCalls?: boolean | undefined; responseFormat?: Record<string, unknown> | undefined; temperature?: number | undefined; maxTokens?: number | undefined; reasoning?: { effort: string; } | undefined; serverTools?: ('web_search' | 'image_generation' | 'web_fetch' | 'datetime')[] | undefined; maxToolCalls?: number | undefined; stream?: boolean | undefined; cache?: { ttlSec: number; } | undefined; zdr?: boolean | undefined; fastMode?: boolean | undefined; user?: string | undefined; }, 'stream'>): Promise<ChatStream>
+```
+
+The same request streamed: `raw` is the OpenAI-format SSE (return it from a route), `text()` its deltas,
+`result()` the final result with its credits.
+
+#### `ai.generateObject`
+
+```ts
+ai.generateObject(req: { schema: Record<string, unknown>; prompt?: string | undefined; messages?: { [x: string]: unknown; role: 'user' | 'system' | 'assistant' | 'tool' | 'developer'; content: unknown; }[] | undefined; model?: string | undefined; healing?: boolean | undefined; }): Promise<{ object: unknown; usage: { credits: number; vendor?: string | undefined; units?: number | undefined; vendorCostUsd?: number | undefined; }; }>
+```
+
+A JSON object matching `schema` (JSON Schema).
+
+#### `ai.classify`
+
+```ts
+ai.classify(req: { input: string; options: readonly string[]; model?: string | undefined; instructions?: string | undefined; }): Promise<{ label: string; }>
+```
+
+Sugar over `generateObject`: one of `options`, chosen by the model.
+
+#### `ai.embed`
+
+```ts
+ai.embed(req: { input: string | string[]; model?: string | undefined; }): Promise<{ embeddings: number[][]; usage: { credits: number; vendor?: string | undefined; units?: number | undefined; vendorCostUsd?: number | undefined; }; }>
+```
+
+Embedding vectors for one or more texts.
+
+#### `ai.image.generate`
+
+```ts
+ai.image.generate(req: { prompt: string; model?: string | undefined; aspectRatio?: string | undefined; resolution?: '1K' | '2K' | '4K' | '512' | undefined; quality?: string | undefined; outputFormat?: 'png' | 'jpeg' | 'webp' | undefined; background?: string | undefined; n?: number | undefined; references?: string[] | undefined; fileName?: string | undefined; store?: boolean | undefined; }): Promise<{ images: { key: string; url: string; mediaType: string; width?: number | undefined; height?: number | undefined; }[]; usage: { credits: number; vendor?: string | undefined; units?: number | undefined; vendorCostUsd?: number | undefined; }; fileName?: string | undefined; imageUrl?: string | undefined; }>
+```
+
+Images from a prompt; `store: true` keeps them as project files.
+
+#### `ai.image.edit`
+
+```ts
+ai.image.edit(req: { prompt: string; images: string[]; mask?: string | undefined; fileName?: string | undefined; size?: string | undefined; quality?: string | undefined; outputFormat?: 'png' | 'jpeg' | 'webp' | undefined; background?: string | undefined; inputFidelity?: string | undefined; }): Promise<{ images: { key: string; url: string; mediaType: string; width?: number | undefined; height?: number | undefined; }[]; usage: { credits: number; vendor?: string | undefined; units?: number | undefined; vendorCostUsd?: number | undefined; }; fileName?: string | undefined; imageUrl?: string | undefined; }>
+```
+
+An image edited by a prompt.
+
+#### `ai.video.generate`
+
+```ts
+ai.video.generate(req: { prompt: string; durationSec: number; model?: string | undefined; resolution?: string | undefined; aspectRatio?: string | undefined; firstFrame?: string | undefined; lastFrame?: string | undefined; references?: string[] | undefined; generateAudio?: boolean | undefined; seed?: number | undefined; webhook?: boolean | undefined; }): Promise<{ jobId: string; status: 'queued'; estimatedCredits: number; }>
+```
+
+`202`: the job and the credits reserved for it; poll `get(jobId)` (the clip is stored when it completes).
+
+#### `ai.video.get`
+
+```ts
+ai.video.get(jobId: string): Promise<{ jobId: string; status: 'completed' | 'queued' | 'running' | 'failed' | 'cancelled' | 'expired'; progress?: number | undefined; video?: { key: string; url: string; } | undefined; usage?: { credits: number; vendor?: string | undefined; units?: number | undefined; vendorCostUsd?: number | undefined; } | undefined; error?: { code: string; message: string; } | undefined; }>
+```
+
+The video job: `status`, and the stored clip once completed.
+
+#### `ai.video.wait`
+
+```ts
+ai.video.wait(jobId: string, opts?: { intervalMs?: number | undefined; timeoutMs?: number | undefined; }): Promise<{ jobId: string; status: 'completed' | 'queued' | 'running' | 'failed' | 'cancelled' | 'expired'; progress?: number | undefined; video?: { key: string; url: string; } | undefined; usage?: { credits: number; vendor?: string | undefined; units?: number | undefined; vendorCostUsd?: number | undefined; } | undefined; error?: { code: string; message: string; } | undefined; }>
+```
+
+⚠ NODE-ONLY: polls `get(jobId)` until the job leaves `queued`/`running` (default every 5 s, at most 10 min).
+In a Worker it throws `NODE_ONLY` — store the `jobId` and read `get(jobId)` later instead.
+
+#### `ai.vision.describe`
+
+```ts
+ai.vision.describe(req: { image: string; prompt?: string | undefined; model?: string | undefined; }): Promise<{ text: string; usage: { credits: number; vendor?: string | undefined; units?: number | undefined; vendorCostUsd?: number | undefined; }; }>
+```
+
+A text description of an image (URL, data URL or project file key).
+
+#### `ai.speech.speak`
+
+```ts
+ai.speech.speak(input: { text: string; voice?: string | undefined; language?: string | undefined; model?: 'standard' | 'premium' | undefined; format?: 'mp3' | 'wav' | 'opus' | undefined; speed?: number | undefined; store?: boolean | undefined; }): Promise<{ key: string; url: string; usage: { credits: number; vendor?: string | undefined; units?: number | undefined; vendorCostUsd?: number | undefined; }; } | { audio: ArrayBuffer; contentType: string; credits: number; }>
+```
+
+Same as `speech.synthesize`.
+
+#### `ai.speech.transcribe`
+
+```ts
+ai.speech.transcribe(input: { audioBase64?: string | undefined; filename?: string | undefined; url?: string | undefined; language?: string | undefined; model?: 'fast' | 'accurate' | undefined; diarize?: boolean | undefined; timestamps?: 'word' | 'segment' | undefined; keyterms?: string[] | undefined; }): Promise<{ text: string; durationSec: number; usage: { credits: number; vendor?: string | undefined; units?: number | undefined; vendorCostUsd?: number | undefined; }; language?: string | undefined; segments?: { start: number; end: number; text: string; }[] | undefined; words?: { word: string; start: number; end: number; }[] | undefined; }>
+```
+
+Same as `speech.transcribe`.
+
+#### `ai.models.list`
+
+```ts
+ai.models.list(): Promise<{ aliases: { cheap: string; normal: string; best: string; }; models: { slug: string; name: string; inputModalities: string[]; pricing: Record<string, unknown>; contextLength: number; }[]; denylist?: string[] | undefined; }>
+```
+
+The model aliases and the models a project may call, with their prices.
+
+#### `ai.gatewayConfig`
+
+```ts
+ai.gatewayConfig(): { baseURL: string; apiKey: string; }
+```
+
+The exact OpenRouter API for any OpenRouter/OpenAI client: `new OpenAI(ai.gatewayConfig())`. Server-side only.
+
+## `totalum-sdk/email`
+
+### `totalumEmail`
+
+```ts
+totalumEmail(options?: TotalumClientOptions)
+```
+
+`totalum.email` over SDK-API `/v1/email/*` (scope `email`): Resend, HTML sent byte for byte, charged
+per recipient. On dev only allow-listed recipients are accepted (`DEV_RECIPIENT_NOT_ALLOWED`).
+
+#### `email.send`
+
+```ts
+email.send(msg: { to: string | string[]; subject: string; html?: string | undefined; text?: string | undefined; from?: { name?: string | undefined; localPart?: string | undefined; domain?: string | undefined; } | undefined; replyTo?: string | string[] | undefined; cc?: string | string[] | undefined; bcc?: string | string[] | undefined; headers?: Record<string, string> | undefined; attachments?: { filename: string; url?: string | undefined; content?: string | undefined; contentType?: string | undefined; }[] | undefined; tags?: { name: string; value: string; }[] | undefined; scheduledAt?: string | undefined; idempotencyKey?: string | undefined; bulk?: boolean | undefined; }): Promise<{ success: true; message: 'Email sent successfully'; messageId: string; id: string; status: 'queued' | 'sent'; }>
+```
+
+Sends one e-mail (HTML byte for byte); charged per recipient.
+
+```ts
+await email.send({ to: 'ana@example.com', subject: 'Welcome', html: '<p>Hi Ana</p>' });
+```
+
+#### `email.get`
+
+```ts
+email.get(id: string): Promise<{ id: string; from: string; to: string[]; subject: string; status: 'queued' | 'failed' | 'sent' | 'delivered' | 'delayed' | 'bounced' | 'complained' | 'suppressed'; lastEventAt: string | null; events: { type: string; at: string; detail?: unknown; }[]; } | null>
+```
+
+`null` when the e-mail is not this project's.
+
+## `totalum-sdk/cron`
+
+### `totalumCron`
+
+```ts
+totalumCron(options?: TotalumClientOptions)
+```
+
+`totalum.cron` over SDK-API `/v1/cron/*` (scope `cron`): HTTP jobs against the project's own host,
+fired by Totalum's Scheduler; limits per plan (`429 CRON_LIMIT_REACHED {limit, plan}`, `400 INVALID_SCHEDULE
+{minIntervalSeconds}`). Executions cost nothing.
+
+#### `cron.create`
+
+```ts
+cron.create(input: { name: string; schedule: string | { everyMinutes: number; }; request: { method: 'GET' | 'POST'; url: string; headers?: Record<string, string> | undefined; body?: string | undefined; timeoutMs?: number | undefined; }; enabled?: boolean | undefined; description?: string | undefined; env?: 'dev' | 'live' | undefined; }): Promise<{ id: string; name: string; schedule: string | { everyMinutes: number; }; request: { method: 'GET' | 'POST'; url: string; headers?: Record<string, string> | undefined; body?: string | undefined; timeoutMs?: number | undefined; }; enabled: boolean; status: 'active' | 'paused' | 'paused_failures'; nextRunAt: string | null; createdAt: string; env: 'dev' | 'live'; lastRun?: { at: string; status: number | 'timeout' | 'error' | 'skipped'; latencyMs: number; } | undefined; description?: string | undefined; }>
+```
+
+A job that calls a URL of the project's own host on a cron `schedule` (or `{ everyMinutes }`).
+
+```ts
+await cron.create({
+  name: 'daily-report',
+  schedule: '0 8 * * *',
+  request: { method: 'POST', url: 'https://my-app.totalum-project.com/api/cron/report' },
+});
+```
+
+#### `cron.list`
+
+```ts
+cron.list(): Promise<{ id: string; name: string; schedule: string | { everyMinutes: number; }; request: { method: 'GET' | 'POST'; url: string; headers?: Record<string, string> | undefined; body?: string | undefined; timeoutMs?: number | undefined; }; enabled: boolean; status: 'active' | 'paused' | 'paused_failures'; nextRunAt: string | null; createdAt: string; env: 'dev' | 'live'; lastRun?: { at: string; status: number | 'timeout' | 'error' | 'skipped'; latencyMs: number; } | undefined; description?: string | undefined; }[]>
+```
+
+Every job of the project.
+
+#### `cron.get`
+
+```ts
+cron.get(id: string): Promise<{ id: string; name: string; schedule: string | { everyMinutes: number; }; request: { method: 'GET' | 'POST'; url: string; headers?: Record<string, string> | undefined; body?: string | undefined; timeoutMs?: number | undefined; }; enabled: boolean; status: 'active' | 'paused' | 'paused_failures'; nextRunAt: string | null; createdAt: string; env: 'dev' | 'live'; lastRun?: { at: string; status: number | 'timeout' | 'error' | 'skipped'; latencyMs: number; } | undefined; description?: string | undefined; } | null>
+```
+
+`null` when the job is not this project's.
+
+#### `cron.update`
+
+```ts
+cron.update(id: string, patch: { name?: string | undefined; schedule?: string | { everyMinutes: number; } | undefined; request?: { method: 'GET' | 'POST'; url: string; headers?: Record<string, string> | undefined; body?: string | undefined; timeoutMs?: number | undefined; } | undefined; enabled?: boolean | undefined; description?: string | undefined; env?: 'dev' | 'live' | undefined; }): Promise<{ id: string; name: string; schedule: string | { everyMinutes: number; }; request: { method: 'GET' | 'POST'; url: string; headers?: Record<string, string> | undefined; body?: string | undefined; timeoutMs?: number | undefined; }; enabled: boolean; status: 'active' | 'paused' | 'paused_failures'; nextRunAt: string | null; createdAt: string; env: 'dev' | 'live'; lastRun?: { at: string; status: number | 'timeout' | 'error' | 'skipped'; latencyMs: number; } | undefined; description?: string | undefined; }>
+```
+
+Changes any field of a job (`schedule`, `request`, `enabled`, …).
+
+#### `cron.delete`
+
+```ts
+cron.delete(id: string): Promise<void>
+```
+
+Deletes a job.
+
+#### `cron.pause`
+
+```ts
+cron.pause(id: string): Promise<{ id: string; name: string; schedule: string | { everyMinutes: number; }; request: { method: 'GET' | 'POST'; url: string; headers?: Record<string, string> | undefined; body?: string | undefined; timeoutMs?: number | undefined; }; enabled: boolean; status: 'active' | 'paused' | 'paused_failures'; nextRunAt: string | null; createdAt: string; env: 'dev' | 'live'; lastRun?: { at: string; status: number | 'timeout' | 'error' | 'skipped'; latencyMs: number; } | undefined; description?: string | undefined; }>
+```
+
+Stops a job from firing until `resume`.
+
+#### `cron.resume`
+
+```ts
+cron.resume(id: string): Promise<{ id: string; name: string; schedule: string | { everyMinutes: number; }; request: { method: 'GET' | 'POST'; url: string; headers?: Record<string, string> | undefined; body?: string | undefined; timeoutMs?: number | undefined; }; enabled: boolean; status: 'active' | 'paused' | 'paused_failures'; nextRunAt: string | null; createdAt: string; env: 'dev' | 'live'; lastRun?: { at: string; status: number | 'timeout' | 'error' | 'skipped'; latencyMs: number; } | undefined; description?: string | undefined; }>
+```
+
+Lets a paused job fire again.
+
+#### `cron.runs`
+
+```ts
+cron.runs(id: string, opts?: { limit?: number | undefined; cursor?: string | undefined; }): Promise<{ items: { id: string; scheduledFor: string; startedAt: string | null; status: number | 'timeout' | 'error' | 'skipped'; latencyMs: number | null; error?: string | undefined; responseSnippet?: string | undefined; }[]; nextCursor: string | null; }>
+```
+
+A job's executions, newest first (30 days).
+
+#### `cron.trigger`
+
+```ts
+cron.trigger(id: string): Promise<{ runId: string; }>
+```
+
+Fires a job now, outside its schedule.
+
+## `totalum-sdk/seo`
+
+### `totalumSeo`
+
+```ts
+totalumSeo(options?: TotalumClientOptions)
+```
+
+`totalum.seo` over SDK-API `/v1/seo/*` (scope `seo`): IndexNow for verified custom domains, free.
+
+#### `seo.notifyChanged`
+
+```ts
+seo.notifyChanged(urls: string[]): Promise<{ accepted: number; indexNow: 'error' | 'sent' | 'skipped_no_custom_domain'; sitemapsPinged: boolean; }>
+```
+
+Tells search engines (IndexNow) that these URLs of the project's custom domains changed.
+
+#### `seo.indexNowKey`
+
+```ts
+seo.indexNowKey(): Promise<{ key: string; keyLocation: string; }>
+```
+
+The key the template serves at `/<key>.txt`.
+
+## `totalum-sdk/browser`
+
+### `totalumBrowser`
+
+```ts
+totalumBrowser(options?: TotalumClientOptions)
+```
+
+`totalum.browser` over SDK-API `/v1/browser/*` (scope `browser`): Browserbase sessions driven entirely
+over HTTPS, so every command works from a Worker. A command's refusal throws `TotalumError` with its frozen
+code (`ACTION_TIMEOUT`, `ACTION_FAILED`, …); `actions()` returns every result instead.
+
+#### `browser.session`
+
+```ts
+browser.session(opts?: { proxy?: { enabled: boolean; country?: string | undefined; state?: string | undefined; city?: string | undefined; routes?: { domainPattern: string; mode: 'totalum' | 'none' | 'external'; country?: string | undefined; state?: string | undefined; city?: string | undefined; server?: string | undefined; username?: string | undefined; password?: string | undefined; }[] | undefined; } | undefined; solveCaptchas?: boolean | undefined; captcha?: { imageSelector?: string | undefined; inputSelector?: string | undefined; } | undefined; stealth?: 'basic' | 'off' | 'verified' | undefined; fingerprintOs?: 'mobile' | 'windows' | 'mac' | 'linux' | 'tablet' | undefined; timeoutMinutes?: number | undefined; keepAlive?: boolean | undefined; context?: { id: string; persist?: boolean | undefined; } | undefined; contextId?: string | undefined; blockAds?: boolean | undefined; allowedDomains?: string[] | undefined; ignoreCertificateErrors?: boolean | undefined; caCertificateIds?: string[] | undefined; extensionId?: string | undefined; metadata?: Record<string, string> | undefined; logSession?: boolean | undefined; recordSession?: boolean | undefined; region?: 'eu' | 'us-west-2' | 'us-east-1' | 'eu-central-1' | 'ap-southeast-1' | 'us' | undefined; locale?: string | undefined; timezone?: string | undefined; geolocation?: { latitude: number; longitude: number; accuracy?: number | undefined; } | undefined; userAgent?: string | undefined; extraHeaders?: Record<string, string> | undefined; blockResources?: ('image' | 'media' | 'font')[] | undefined; device?: string | undefined; captureDownloads?: boolean | undefined; viewport?: { width: number; height: number; } | undefined; }): Promise<BrowserSession>
+```
+
+Opens a session with the vendor options and the Totalum-synthesised ones.
+
+#### `browser.sessions.list`
+
+```ts
+browser.sessions.list(q?: { status?: string | undefined; metadata?: string | undefined; limit?: number | undefined; cursor?: string | undefined; }): Promise<{ items: ({ id: string; status: 'running' | 'failed' | 'expired' | 'ended'; startedAt: string; minutes: number; proxyMb: number; captchas: number; credits: number; expiresAt: string; } & { region: string; metadata: Record<string, string> | null; })[]; nextCursor?: string | undefined; }>
+```
+
+The project's sessions, filtered by `status` or `metadata`.
+
+#### `browser.sessions.get`
+
+```ts
+browser.sessions.get(id: string): BrowserSession
+```
+
+A handle on an existing session (no call is made).
+
+#### `browser.programs.get`
+
+```ts
+browser.programs.get(programId: string): Promise<{ programId: string; sessionId: string; status: 'completed' | 'running' | 'failed' | 'pending' | 'timed_out'; steps: { index: number; type: string; ok: boolean; data?: unknown; error?: { code: 'SERVICE_UNAUTHORIZED' | 'SERVICE_REPLAY' | 'ACTOR_MISMATCH' | 'PAYLOAD_TOO_LARGE' | 'VALIDATION_ERROR' | 'PROJECT_NOT_FOUND' | 'OPERATION_IN_PROGRESS' | 'AGENT_RUNNING' | 'PROJECT_MOVED' | 'OBJECT_MIGRATING' | 'INDEX_SHARD_UNAVAILABLE' | 'RATE_LIMIT_EXCEEDED' | 'PROJECT_PAUSED_RUNAWAY' | 'PROJECT_PAUSED_BALANCE' | 'PROJECT_SUSPENDED' | 'PROJECT_HIBERNATED' | 'PROJECT_DELETED' | 'PROJECT_PAUSED_BY_USER' | 'LIFECYCLE_NOT_APPLICABLE' | 'PROJECT_NOT_PAUSED' | 'PAUSE_DUMP_EXPIRED' | 'PAUSE_VERIFICATION_FAILED' | 'DEPLOYMENT_IN_PROGRESS' | 'REACTIVATE_IMPORT_MISMATCH' | 'RESUME_IMPORT_MISMATCH' | 'INSUFFICIENT_CREDITS' | 'VCAAS_INSUFFICIENT_CREDITS' | 'PROJECT_CREDIT_LIMIT_REACHED' | 'FREE_PROMPTS_DISABLED' | 'PLAN_REQUIRED' | 'FEATURE_LIMIT_REACHED' | 'FEATURE_DISABLED' | 'AGENT_ALREADY_RUNNING' | 'IMPORT_IN_PROGRESS' | 'TOO_MANY_RUN_REQUESTS' | 'PROMPT_SECURITY_VIOLATION' | 'NO_PROCESS_RUNNING' | 'RUN_NOT_FOUND' | 'DEPLOYMENT_RUNNING' | 'AUTO_EXECUTION_ALREADY_ACTIVE' | 'REBUILD_RUNNING' | 'SECRET_ALREADY_EXISTS' | 'SECRET_LIMIT_EXCEEDED' | 'RESERVED_SECRET_NAME' | 'DUMP_NOT_FOUND' | 'DUMP_INVALID' | 'RESTORE_TARGET_NOT_EMPTY' | 'ENGINE_NOT_SUPPORTED' | 'ENGINE_V2_DISABLED' | 'V2_TEMPORARILY_DISABLED' | 'ENGINE_REQUEST_NOT_ELIGIBLE' | 'ENGINE_MISMATCH' | 'INVALID_ENGINE_VERSION' | 'PROJECT_ENGINE_MISMATCH' | 'ENGINE_UNAVAILABLE' | 'PREVIEW_LABEL_TOO_LONG' | 'PROJECT_ALREADY_EXISTS' | 'CLOUDFLARE_API_ERROR' | 'PROVISIONING_BUSY' | 'UNAUTHORIZED' | 'LEGACY_KEY_NOT_SUPPORTED' | 'SANDBOX_KEY_EXPIRED' | 'AUTH_RATE_LIMITED' | 'FORBIDDEN_SCOPE' | 'KEY_ENV_MISMATCH' | 'KEY_LIMIT_EXCEEDED' | 'LIVE_DB_READ_ONLY' | 'LIVE_WRITE_NEEDS_CONFIRMATION' | 'DDL_NOT_ALLOWED' | 'MIGRATION_IN_PROGRESS' | 'MIGRATION_EDITED' | 'SCHEMA_OUT_OF_SYNC' | 'LIVE_MIGRATION_FAILED' | 'DESTRUCTIVE_MIGRATION_NEEDS_CONFIRMATION' | 'DEV_DATABASE_NOT_FOUND' | 'DATABASE_ROLE_NOT_FOUND' | 'BOOKMARK_NOT_FOUND' | 'BACKUP_NOT_FOUND' | 'BACKUP_NOT_DELETABLE' | 'BACKUP_RATE_LIMITED' | 'PRE_RESTORE_BACKUP_FAILED' | 'RESTORE_VERIFY_FAILED' | 'RUN_NOT_LATEST' | 'DEV_DATABASE_EXISTS' | 'SQL_ERROR' | 'SQL_MULTI_STATEMENT' | 'SQL_STATEMENT_TOO_LARGE' | 'SQL_TOO_MANY_PARAMS' | 'STATEMENT_NOT_ALLOWED' | 'VIRTUAL_TABLES_NOT_SUPPORTED' | 'USE_STORAGE_FOR_FILES' | 'D1_TYPE_ERROR' | 'MIGRATION_INVALID' | 'SYSTEM_TABLE_READ_ONLY' | 'SQL_READ_ONLY' | 'RESULT_TOO_LARGE' | 'NL_QUERY_UNANSWERABLE' | 'QUERY_TIMEOUT' | 'DB_OVERLOADED' | 'D1_TRANSIENT' | 'DB_FULL_NEAR_LIMIT' | 'IDEMPOTENCY_KEY_REUSED' | 'IDEMPOTENT_REPLAY_UNAVAILABLE' | 'TABLE_NOT_FOUND' | 'SCHEMA_TOO_LARGE_FOR_COUNTS' | 'EXEC_REQUIRES_MIGRATE_MODE' | 'MIGRATION_UNKNOWN_IN_DB' | 'QUERY_LIMIT_EXCEEDED' | 'STORAGE_LIMIT_EXCEEDED' | 'METER_UNAVAILABLE' | 'COLUMN_NOT_FOUND' | 'VALUE_NOT_ALLOWED' | 'COLUMN_REQUIRED' | 'FILTER_TOO_COMPLEX' | 'OFFSET_TOO_LARGE' | 'BULK_TOO_LARGE' | 'NOT_A_JUNCTION_TABLE' | 'AMBIGUOUS_RELATION' | 'LIVE_WRITE_CONFIRMATION_REQUIRED' | 'RECORD_NOT_FOUND' | 'DEV_NAME_GUARD' | 'PROD_NAME_GUARD' | 'INVALID_RUN_REQUEST' | 'RUN_ALREADY_ACTIVE' | 'RUN_CONFLICT' | 'INVALID_CREDENTIALS' | 'ADAPTER_UNAVAILABLE' | 'DISK_FULL' | 'DEPLOY_FIX_ATTEMPTS_EXHAUSTED' | 'TOKEN_REVOKED' | 'AM_UPDATE_DOWNLOAD_FAILED' | 'AM_UPDATE_BAD_SHA' | 'AM_UPDATE_BAD_SIGNATURE' | 'AM_UPDATE_INCOMPATIBLE_IMAGE' | 'AM_UPDATE_START_FAILED' | 'AM_VERSION_UNAVAILABLE' | 'AM_UPDATE_FAILED' | 'RELEASE_CANARY_NOT_PASSED' | 'RELEASE_NOT_FOUND' | 'RELEASE_ROLLOUT_ACTIVE' | 'RELEASE_GUARD_PAUSED' | 'RELEASE_BUILD_UNAVAILABLE' | 'VISUAL_EDIT_PREVIEW_DEPLOYING' | 'VISUAL_EDIT_NOT_PATCHABLE' | 'VISUAL_EDIT_BASE_MISMATCH' | 'VISUAL_EDIT_TYPECHECK_FAILED' | 'INVALID_VISUAL_EDIT' | 'IMAGE_VERSION_NOT_FOUND' | 'IMAGE_VERSION_NOT_PROMOTABLE' | 'REALTIME_TICKET_INVALID' | 'REALTIME_TICKET_EXPIRED' | 'REALTIME_PERMISSION_DENIED' | 'REALTIME_MESSAGE_TOO_LARGE' | 'REALTIME_MESSAGE_RATE_EXCEEDED' | 'REALTIME_CONNECTION_LIMIT_REACHED' | 'REALTIME_ROOM_LIMIT_REACHED' | 'CONFIRMATION_REQUIRED' | 'MIGRATION_NOT_REVERSIBLE' | 'ALREADY_ON_PROVIDER' | 'DATABASE_MIGRATING' | 'LOGWATCH_INACTIVE' | 'AGENT_LOG_READS_LIMIT' | 'LOGS_UPSTREAM_ERROR' | 'ANALYTICS_INVALID_QUERY' | 'ANALYTICS_UPSTREAM_ERROR' | 'ANALYTICS_WINDOW_OUT_OF_RETENTION' | 'INVALID_CIDR' | 'RATE_LIMIT_ABOVE_PLAN' | 'RATE_LIMIT_DISABLE_NOT_ALLOWED' | 'OWNER_ONLY' | 'SIGNING_NOT_CONFIGURED' | 'SIGNING_ALREADY_CONFIGURED' | 'SIGNING_INVALID_KEYSTORE' | 'SIGNING_INVALID_ASC_KEY' | 'KEYSTORE_DOWNLOAD_EXPIRED' | 'KEYSTORE_NOT_DOWNLOADABLE' | 'MOBILE_BUILD_RUNNING' | 'MOBILE_BUILD_NOT_FOUND' | 'MOBILE_BUILD_NOT_READY' | 'DOWNLOAD_EXPIRED' | 'PROCESS_IN_PROGRESS' | 'SANDBOX_NOT_RUNNING' | 'MOBILE_LAYER_MISSING' | 'MOBILE_BUILD_FAILED' | 'MOBILE_ARTIFACT_INVALID' | 'SIGNING_FINGERPRINT_MISMATCH' | 'AM_RESTARTED' | 'LIMIT_ABOVE_PLAN_CEILING' | 'UNKNOWN_FEATURE' | 'INVALID_LIMIT' | 'FEATURE_NOT_DISABLABLE' | 'USE_PUT_LIMITS' | 'LIMIT_NOT_USER_EDITABLE' | 'NOT_AVAILABLE_FOR_ENGINE' | 'INVALID_AMOUNT' | 'REFUND_EXCEEDS_CHARGES' | 'IDEMPOTENCY_CONFLICT' | 'ORGANIZATION_NOT_FOUND' | 'ACCOUNT_NOT_FOUND' | 'PROVIDER_UNAVAILABLE' | 'URL_NOT_ALLOWED' | 'JOB_NOT_FOUND' | 'FILE_TOO_LARGE' | 'UNSUPPORTED_FILE_TYPE' | 'FILE_NOT_FOUND' | 'FILE_KEY_FORBIDDEN' | 'FILE_UPLOAD_ERROR' | 'FILE_DOWNLOAD_ERROR' | 'FILE_DELETE_ERROR' | 'UPLOAD_NOT_COMPLETED' | 'MISSING_URL' | 'MISSING_INPUT' | 'MISSING_EXTRACTION_CONFIG' | 'MISSING_QUERY' | 'SCRAPE_FAILED' | 'EXTRACT_FAILED' | 'SCREENSHOT_FAILED' | 'SEARCH_FAILED' | 'SCRAPE_BLOCKED' | 'SESSION_NOT_FOUND' | 'SESSION_EXPIRED' | 'SESSION_BUSY' | 'SESSION_LIMIT_REACHED' | 'SESSION_ENDED_INSUFFICIENT_CREDITS' | 'ACTION_TIMEOUT' | 'ACTION_FAILED' | 'UNKNOWN_COMMAND' | 'BATCH_TOO_LARGE' | 'SKIPPED' | 'UPLOAD_TOO_LARGE' | 'DOWNLOAD_TOO_LARGE' | 'CAPTURE_LIMIT_REACHED' | 'CAPTCHA_UNSOLVED' | 'BROWSER_CDP_NODE_ONLY' | 'DIALOG_NOT_OPEN' | 'STEALTH_TIER_UNAVAILABLE' | 'DOMAIN_NOT_ALLOWED' | 'CONTEXT_SEED_UNSUPPORTED' | 'EXTENSION_TOO_LARGE' | 'NL_PROVIDER_UNAVAILABLE' | 'PROGRAM_TOO_LARGE' | 'PROGRAM_UNBOUNDED' | 'UNKNOWN_STEP' | 'PROGRAM_IN_FLIGHT' | 'PROGRAM_TIMEOUT' | 'PROGRAM_NOT_FOUND' | 'PROGRAM_STEP_FAILED' | 'PROGRAM_LIMIT_REACHED' | 'CREATE_PDF_FROM_HTML_ERROR' | 'GENERATE_PDF_BY_URL_ERROR' | 'PDF_TIMEOUT' | 'PDF_TOO_LARGE' | 'FILENAME_REQUIRED' | 'SCANUM_EYE_ARRAY_NOT_SUPPORTED' | 'INVALID_EXTRA_FIELD_TYPE' | 'SCANUM_EYE_PDF_NOT_SUPPORTED' | 'UNSUPPORTED_SCAN_MODEL' | 'SCAN_DOCUMENT_ERROR' | 'SCAN_INVOICE_ERROR' | 'OCR_IMAGE_PROCESSING_ERROR' | 'OCR_PDF_PROCESSING_ERROR' | 'SCAN_TOO_MANY_PAGES' | 'SCAN_PDF_ENCRYPTED' | 'SCAN_XFA_UNSUPPORTED' | 'AUDIO_FILE_REQUIRED' | 'AUDIO_FILE_TOO_LARGE' | 'INVALID_AUDIO_FORMAT' | 'AUDIO_TRANSCRIPTION_ERROR' | 'TTS_TEXT_TOO_LONG' | 'TTS_VOICE_UNKNOWN' | 'TOO_MANY_AUDIO_TRANSCRIPTIONS' | 'EMAIL_SEND_FAILED' | 'TOO_MANY_ATTACHMENTS' | 'INVALID_ATTACHMENT_URL' | 'ATTACHMENT_TOO_LARGE' | 'TOO_MANY_RECIPIENTS' | 'EMAIL_RECIPIENT_SUPPRESSED' | 'EMAIL_DOMAIN_NOT_VERIFIED' | 'EMAIL_LOCAL_PART_TAKEN' | 'EMAIL_SENDING_PAUSED' | 'EMAIL_DOMAINS_REQUIRE_PAID_PLAN' | 'SUPPRESSION_PERMANENT' | 'DEV_RECIPIENT_NOT_ALLOWED' | 'CRON_LIMIT_REACHED' | 'INVALID_SCHEDULE' | 'CRON_URL_NOT_ALLOWED' | 'CRON_JOB_NOT_FOUND' | 'CRON_REQUIRES_PUBLISHED_PROJECT' | 'URL_NOT_PROJECT_HOST' | 'INDEXNOW_ERROR' | 'MCP_VERIFY_FAILED' | 'MCP_NAME_RESERVED' | 'MCP_LIMIT_REACHED' | 'MCP_SERVER_NOT_FOUND' | 'PAYMENTS_NOT_ENABLED' | 'PAYMENTS_LIVE_ONBOARDING_REQUIRED' | 'CARD_DATA_NOT_ACCEPTED' | 'STRIPE_ERROR' | 'STRIPE_RATE_LIMITED' | 'PAYMENTS_WEBHOOK_SIGNATURE_INVALID' | 'AI_MODEL_NOT_ALLOWED' | 'AI_MODEL_UNKNOWN' | 'AI_INVALID_SCHEMA' | 'AI_CONTENT_BLOCKED' | 'AI_CONTEXT_TOO_LONG' | 'AI_PROVIDER_QUOTA' | 'AI_PROVIDER_UNAVAILABLE' | 'AI_STREAM_ERROR' | 'AI_VIDEO_JOB_NOT_FOUND' | 'AI_VIDEO_FAILED' | 'MISSING_VIDEO_URL' | 'MISSING_PROMPT' | 'INVALID_VIDEO_URL' | 'INVALID_VIDEO_URL_PROTOCOL' | 'INVALID_MIME_TYPE_HINT' | 'VIDEO_TOO_LARGE' | 'VIDEO_URL_UNREACHABLE' | 'VIDEO_URL_NOT_A_VIDEO' | 'YOUTUBE_VIDEO_UNAVAILABLE' | 'NO_PAYMENT_METHOD' | 'DOMAIN_CONTACT_REQUIRED' | 'DOMAIN_UNAVAILABLE' | 'DOMAIN_PREMIUM_NOT_ALLOWED' | 'TLD_NOT_ALLOWED' | 'DOMAIN_LIMIT_REACHED' | 'PRICE_CHANGED' | 'PAYMENT_FAILED' | 'REGISTRATION_FAILED' | 'DOMAIN_NOT_RENEWABLE' | 'DOMAIN_ALREADY_ATTACHED' | 'DNS_RECORD_MANAGED' | 'DNS_RECORD_CONFLICT' | 'DNS_RECORD_LIMIT' | 'DOMAIN_TRANSFER_LOCKED' | 'DOMAIN_NOT_FOUND' | 'DOMAIN_IN_USE' | 'DOMAIN_ALREADY_ADDED' | 'NO_DEPLOYMENT' | 'REDIRECT_LIMIT_REACHED' | 'REDIRECT_INVALID' | 'APEX_NOT_FLATTENABLE' | 'SECOND_FACTOR_NOT_CONFIGURED' | 'PASSWORD_REQUIRED' | 'PASSWORD_INCORRECT' | 'TOO_MANY_ATTEMPTS' | 'CONFIRMATION_MISMATCH' | 'INVALID_TOKEN' | 'MISSING_PERMISSIONS' | 'REPO_NOT_FOUND' | 'REPO_MISSING_BRANCHES' | 'UNKNOWN' | 'SANDBOX_NOT_READY' | 'SYNC_FAILED' | 'TOKEN_EXPIRED' | 'GITHUB_NOT_CONNECTED' | 'FIGMA_TOKEN_MISSING' | 'FIGMA_TOKEN_MALFORMED' | 'FIGMA_TOKEN_INVALID' | 'FIGMA_TOKEN_FORBIDDEN' | 'FIGMA_RATE_LIMITED' | 'FIGMA_UNREACHABLE' | 'INVALID_IMPORT_CODE' | 'IMPORT_SOURCE_GONE' | 'PROJECT_NOT_IMPORTABLE' | 'PROJECT_IMPORT_LIMIT_REACHED' | 'PROJECT_EXPORT_LIMIT_REACHED' | 'VERSION_NOT_FOUND' | 'INVALID_CODE_EDIT' | 'CODE_EDIT_FAILED' | 'BADGE_IN_SOURCE'; message?: string | undefined; } | undefined; }[]; vars: Record<string, unknown>; startedAt: string; credits: number; result?: unknown; endedAt?: string | undefined; }>
+```
+
+A program's status and, once finished, its results.
+
+#### `browser.programs.wait`
+
+```ts
+browser.programs.wait(programId: string, opts?: { intervalMs?: number | undefined; timeoutMs?: number | undefined; }): Promise<{ programId: string; sessionId: string; status: 'completed' | 'running' | 'failed' | 'pending' | 'timed_out'; steps: { index: number; type: string; ok: boolean; data?: unknown; error?: { code: 'SERVICE_UNAUTHORIZED' | 'SERVICE_REPLAY' | 'ACTOR_MISMATCH' | 'PAYLOAD_TOO_LARGE' | 'VALIDATION_ERROR' | 'PROJECT_NOT_FOUND' | 'OPERATION_IN_PROGRESS' | 'AGENT_RUNNING' | 'PROJECT_MOVED' | 'OBJECT_MIGRATING' | 'INDEX_SHARD_UNAVAILABLE' | 'RATE_LIMIT_EXCEEDED' | 'PROJECT_PAUSED_RUNAWAY' | 'PROJECT_PAUSED_BALANCE' | 'PROJECT_SUSPENDED' | 'PROJECT_HIBERNATED' | 'PROJECT_DELETED' | 'PROJECT_PAUSED_BY_USER' | 'LIFECYCLE_NOT_APPLICABLE' | 'PROJECT_NOT_PAUSED' | 'PAUSE_DUMP_EXPIRED' | 'PAUSE_VERIFICATION_FAILED' | 'DEPLOYMENT_IN_PROGRESS' | 'REACTIVATE_IMPORT_MISMATCH' | 'RESUME_IMPORT_MISMATCH' | 'INSUFFICIENT_CREDITS' | 'VCAAS_INSUFFICIENT_CREDITS' | 'PROJECT_CREDIT_LIMIT_REACHED' | 'FREE_PROMPTS_DISABLED' | 'PLAN_REQUIRED' | 'FEATURE_LIMIT_REACHED' | 'FEATURE_DISABLED' | 'AGENT_ALREADY_RUNNING' | 'IMPORT_IN_PROGRESS' | 'TOO_MANY_RUN_REQUESTS' | 'PROMPT_SECURITY_VIOLATION' | 'NO_PROCESS_RUNNING' | 'RUN_NOT_FOUND' | 'DEPLOYMENT_RUNNING' | 'AUTO_EXECUTION_ALREADY_ACTIVE' | 'REBUILD_RUNNING' | 'SECRET_ALREADY_EXISTS' | 'SECRET_LIMIT_EXCEEDED' | 'RESERVED_SECRET_NAME' | 'DUMP_NOT_FOUND' | 'DUMP_INVALID' | 'RESTORE_TARGET_NOT_EMPTY' | 'ENGINE_NOT_SUPPORTED' | 'ENGINE_V2_DISABLED' | 'V2_TEMPORARILY_DISABLED' | 'ENGINE_REQUEST_NOT_ELIGIBLE' | 'ENGINE_MISMATCH' | 'INVALID_ENGINE_VERSION' | 'PROJECT_ENGINE_MISMATCH' | 'ENGINE_UNAVAILABLE' | 'PREVIEW_LABEL_TOO_LONG' | 'PROJECT_ALREADY_EXISTS' | 'CLOUDFLARE_API_ERROR' | 'PROVISIONING_BUSY' | 'UNAUTHORIZED' | 'LEGACY_KEY_NOT_SUPPORTED' | 'SANDBOX_KEY_EXPIRED' | 'AUTH_RATE_LIMITED' | 'FORBIDDEN_SCOPE' | 'KEY_ENV_MISMATCH' | 'KEY_LIMIT_EXCEEDED' | 'LIVE_DB_READ_ONLY' | 'LIVE_WRITE_NEEDS_CONFIRMATION' | 'DDL_NOT_ALLOWED' | 'MIGRATION_IN_PROGRESS' | 'MIGRATION_EDITED' | 'SCHEMA_OUT_OF_SYNC' | 'LIVE_MIGRATION_FAILED' | 'DESTRUCTIVE_MIGRATION_NEEDS_CONFIRMATION' | 'DEV_DATABASE_NOT_FOUND' | 'DATABASE_ROLE_NOT_FOUND' | 'BOOKMARK_NOT_FOUND' | 'BACKUP_NOT_FOUND' | 'BACKUP_NOT_DELETABLE' | 'BACKUP_RATE_LIMITED' | 'PRE_RESTORE_BACKUP_FAILED' | 'RESTORE_VERIFY_FAILED' | 'RUN_NOT_LATEST' | 'DEV_DATABASE_EXISTS' | 'SQL_ERROR' | 'SQL_MULTI_STATEMENT' | 'SQL_STATEMENT_TOO_LARGE' | 'SQL_TOO_MANY_PARAMS' | 'STATEMENT_NOT_ALLOWED' | 'VIRTUAL_TABLES_NOT_SUPPORTED' | 'USE_STORAGE_FOR_FILES' | 'D1_TYPE_ERROR' | 'MIGRATION_INVALID' | 'SYSTEM_TABLE_READ_ONLY' | 'SQL_READ_ONLY' | 'RESULT_TOO_LARGE' | 'NL_QUERY_UNANSWERABLE' | 'QUERY_TIMEOUT' | 'DB_OVERLOADED' | 'D1_TRANSIENT' | 'DB_FULL_NEAR_LIMIT' | 'IDEMPOTENCY_KEY_REUSED' | 'IDEMPOTENT_REPLAY_UNAVAILABLE' | 'TABLE_NOT_FOUND' | 'SCHEMA_TOO_LARGE_FOR_COUNTS' | 'EXEC_REQUIRES_MIGRATE_MODE' | 'MIGRATION_UNKNOWN_IN_DB' | 'QUERY_LIMIT_EXCEEDED' | 'STORAGE_LIMIT_EXCEEDED' | 'METER_UNAVAILABLE' | 'COLUMN_NOT_FOUND' | 'VALUE_NOT_ALLOWED' | 'COLUMN_REQUIRED' | 'FILTER_TOO_COMPLEX' | 'OFFSET_TOO_LARGE' | 'BULK_TOO_LARGE' | 'NOT_A_JUNCTION_TABLE' | 'AMBIGUOUS_RELATION' | 'LIVE_WRITE_CONFIRMATION_REQUIRED' | 'RECORD_NOT_FOUND' | 'DEV_NAME_GUARD' | 'PROD_NAME_GUARD' | 'INVALID_RUN_REQUEST' | 'RUN_ALREADY_ACTIVE' | 'RUN_CONFLICT' | 'INVALID_CREDENTIALS' | 'ADAPTER_UNAVAILABLE' | 'DISK_FULL' | 'DEPLOY_FIX_ATTEMPTS_EXHAUSTED' | 'TOKEN_REVOKED' | 'AM_UPDATE_DOWNLOAD_FAILED' | 'AM_UPDATE_BAD_SHA' | 'AM_UPDATE_BAD_SIGNATURE' | 'AM_UPDATE_INCOMPATIBLE_IMAGE' | 'AM_UPDATE_START_FAILED' | 'AM_VERSION_UNAVAILABLE' | 'AM_UPDATE_FAILED' | 'RELEASE_CANARY_NOT_PASSED' | 'RELEASE_NOT_FOUND' | 'RELEASE_ROLLOUT_ACTIVE' | 'RELEASE_GUARD_PAUSED' | 'RELEASE_BUILD_UNAVAILABLE' | 'VISUAL_EDIT_PREVIEW_DEPLOYING' | 'VISUAL_EDIT_NOT_PATCHABLE' | 'VISUAL_EDIT_BASE_MISMATCH' | 'VISUAL_EDIT_TYPECHECK_FAILED' | 'INVALID_VISUAL_EDIT' | 'IMAGE_VERSION_NOT_FOUND' | 'IMAGE_VERSION_NOT_PROMOTABLE' | 'REALTIME_TICKET_INVALID' | 'REALTIME_TICKET_EXPIRED' | 'REALTIME_PERMISSION_DENIED' | 'REALTIME_MESSAGE_TOO_LARGE' | 'REALTIME_MESSAGE_RATE_EXCEEDED' | 'REALTIME_CONNECTION_LIMIT_REACHED' | 'REALTIME_ROOM_LIMIT_REACHED' | 'CONFIRMATION_REQUIRED' | 'MIGRATION_NOT_REVERSIBLE' | 'ALREADY_ON_PROVIDER' | 'DATABASE_MIGRATING' | 'LOGWATCH_INACTIVE' | 'AGENT_LOG_READS_LIMIT' | 'LOGS_UPSTREAM_ERROR' | 'ANALYTICS_INVALID_QUERY' | 'ANALYTICS_UPSTREAM_ERROR' | 'ANALYTICS_WINDOW_OUT_OF_RETENTION' | 'INVALID_CIDR' | 'RATE_LIMIT_ABOVE_PLAN' | 'RATE_LIMIT_DISABLE_NOT_ALLOWED' | 'OWNER_ONLY' | 'SIGNING_NOT_CONFIGURED' | 'SIGNING_ALREADY_CONFIGURED' | 'SIGNING_INVALID_KEYSTORE' | 'SIGNING_INVALID_ASC_KEY' | 'KEYSTORE_DOWNLOAD_EXPIRED' | 'KEYSTORE_NOT_DOWNLOADABLE' | 'MOBILE_BUILD_RUNNING' | 'MOBILE_BUILD_NOT_FOUND' | 'MOBILE_BUILD_NOT_READY' | 'DOWNLOAD_EXPIRED' | 'PROCESS_IN_PROGRESS' | 'SANDBOX_NOT_RUNNING' | 'MOBILE_LAYER_MISSING' | 'MOBILE_BUILD_FAILED' | 'MOBILE_ARTIFACT_INVALID' | 'SIGNING_FINGERPRINT_MISMATCH' | 'AM_RESTARTED' | 'LIMIT_ABOVE_PLAN_CEILING' | 'UNKNOWN_FEATURE' | 'INVALID_LIMIT' | 'FEATURE_NOT_DISABLABLE' | 'USE_PUT_LIMITS' | 'LIMIT_NOT_USER_EDITABLE' | 'NOT_AVAILABLE_FOR_ENGINE' | 'INVALID_AMOUNT' | 'REFUND_EXCEEDS_CHARGES' | 'IDEMPOTENCY_CONFLICT' | 'ORGANIZATION_NOT_FOUND' | 'ACCOUNT_NOT_FOUND' | 'PROVIDER_UNAVAILABLE' | 'URL_NOT_ALLOWED' | 'JOB_NOT_FOUND' | 'FILE_TOO_LARGE' | 'UNSUPPORTED_FILE_TYPE' | 'FILE_NOT_FOUND' | 'FILE_KEY_FORBIDDEN' | 'FILE_UPLOAD_ERROR' | 'FILE_DOWNLOAD_ERROR' | 'FILE_DELETE_ERROR' | 'UPLOAD_NOT_COMPLETED' | 'MISSING_URL' | 'MISSING_INPUT' | 'MISSING_EXTRACTION_CONFIG' | 'MISSING_QUERY' | 'SCRAPE_FAILED' | 'EXTRACT_FAILED' | 'SCREENSHOT_FAILED' | 'SEARCH_FAILED' | 'SCRAPE_BLOCKED' | 'SESSION_NOT_FOUND' | 'SESSION_EXPIRED' | 'SESSION_BUSY' | 'SESSION_LIMIT_REACHED' | 'SESSION_ENDED_INSUFFICIENT_CREDITS' | 'ACTION_TIMEOUT' | 'ACTION_FAILED' | 'UNKNOWN_COMMAND' | 'BATCH_TOO_LARGE' | 'SKIPPED' | 'UPLOAD_TOO_LARGE' | 'DOWNLOAD_TOO_LARGE' | 'CAPTURE_LIMIT_REACHED' | 'CAPTCHA_UNSOLVED' | 'BROWSER_CDP_NODE_ONLY' | 'DIALOG_NOT_OPEN' | 'STEALTH_TIER_UNAVAILABLE' | 'DOMAIN_NOT_ALLOWED' | 'CONTEXT_SEED_UNSUPPORTED' | 'EXTENSION_TOO_LARGE' | 'NL_PROVIDER_UNAVAILABLE' | 'PROGRAM_TOO_LARGE' | 'PROGRAM_UNBOUNDED' | 'UNKNOWN_STEP' | 'PROGRAM_IN_FLIGHT' | 'PROGRAM_TIMEOUT' | 'PROGRAM_NOT_FOUND' | 'PROGRAM_STEP_FAILED' | 'PROGRAM_LIMIT_REACHED' | 'CREATE_PDF_FROM_HTML_ERROR' | 'GENERATE_PDF_BY_URL_ERROR' | 'PDF_TIMEOUT' | 'PDF_TOO_LARGE' | 'FILENAME_REQUIRED' | 'SCANUM_EYE_ARRAY_NOT_SUPPORTED' | 'INVALID_EXTRA_FIELD_TYPE' | 'SCANUM_EYE_PDF_NOT_SUPPORTED' | 'UNSUPPORTED_SCAN_MODEL' | 'SCAN_DOCUMENT_ERROR' | 'SCAN_INVOICE_ERROR' | 'OCR_IMAGE_PROCESSING_ERROR' | 'OCR_PDF_PROCESSING_ERROR' | 'SCAN_TOO_MANY_PAGES' | 'SCAN_PDF_ENCRYPTED' | 'SCAN_XFA_UNSUPPORTED' | 'AUDIO_FILE_REQUIRED' | 'AUDIO_FILE_TOO_LARGE' | 'INVALID_AUDIO_FORMAT' | 'AUDIO_TRANSCRIPTION_ERROR' | 'TTS_TEXT_TOO_LONG' | 'TTS_VOICE_UNKNOWN' | 'TOO_MANY_AUDIO_TRANSCRIPTIONS' | 'EMAIL_SEND_FAILED' | 'TOO_MANY_ATTACHMENTS' | 'INVALID_ATTACHMENT_URL' | 'ATTACHMENT_TOO_LARGE' | 'TOO_MANY_RECIPIENTS' | 'EMAIL_RECIPIENT_SUPPRESSED' | 'EMAIL_DOMAIN_NOT_VERIFIED' | 'EMAIL_LOCAL_PART_TAKEN' | 'EMAIL_SENDING_PAUSED' | 'EMAIL_DOMAINS_REQUIRE_PAID_PLAN' | 'SUPPRESSION_PERMANENT' | 'DEV_RECIPIENT_NOT_ALLOWED' | 'CRON_LIMIT_REACHED' | 'INVALID_SCHEDULE' | 'CRON_URL_NOT_ALLOWED' | 'CRON_JOB_NOT_FOUND' | 'CRON_REQUIRES_PUBLISHED_PROJECT' | 'URL_NOT_PROJECT_HOST' | 'INDEXNOW_ERROR' | 'MCP_VERIFY_FAILED' | 'MCP_NAME_RESERVED' | 'MCP_LIMIT_REACHED' | 'MCP_SERVER_NOT_FOUND' | 'PAYMENTS_NOT_ENABLED' | 'PAYMENTS_LIVE_ONBOARDING_REQUIRED' | 'CARD_DATA_NOT_ACCEPTED' | 'STRIPE_ERROR' | 'STRIPE_RATE_LIMITED' | 'PAYMENTS_WEBHOOK_SIGNATURE_INVALID' | 'AI_MODEL_NOT_ALLOWED' | 'AI_MODEL_UNKNOWN' | 'AI_INVALID_SCHEMA' | 'AI_CONTENT_BLOCKED' | 'AI_CONTEXT_TOO_LONG' | 'AI_PROVIDER_QUOTA' | 'AI_PROVIDER_UNAVAILABLE' | 'AI_STREAM_ERROR' | 'AI_VIDEO_JOB_NOT_FOUND' | 'AI_VIDEO_FAILED' | 'MISSING_VIDEO_URL' | 'MISSING_PROMPT' | 'INVALID_VIDEO_URL' | 'INVALID_VIDEO_URL_PROTOCOL' | 'INVALID_MIME_TYPE_HINT' | 'VIDEO_TOO_LARGE' | 'VIDEO_URL_UNREACHABLE' | 'VIDEO_URL_NOT_A_VIDEO' | 'YOUTUBE_VIDEO_UNAVAILABLE' | 'NO_PAYMENT_METHOD' | 'DOMAIN_CONTACT_REQUIRED' | 'DOMAIN_UNAVAILABLE' | 'DOMAIN_PREMIUM_NOT_ALLOWED' | 'TLD_NOT_ALLOWED' | 'DOMAIN_LIMIT_REACHED' | 'PRICE_CHANGED' | 'PAYMENT_FAILED' | 'REGISTRATION_FAILED' | 'DOMAIN_NOT_RENEWABLE' | 'DOMAIN_ALREADY_ATTACHED' | 'DNS_RECORD_MANAGED' | 'DNS_RECORD_CONFLICT' | 'DNS_RECORD_LIMIT' | 'DOMAIN_TRANSFER_LOCKED' | 'DOMAIN_NOT_FOUND' | 'DOMAIN_IN_USE' | 'DOMAIN_ALREADY_ADDED' | 'NO_DEPLOYMENT' | 'REDIRECT_LIMIT_REACHED' | 'REDIRECT_INVALID' | 'APEX_NOT_FLATTENABLE' | 'SECOND_FACTOR_NOT_CONFIGURED' | 'PASSWORD_REQUIRED' | 'PASSWORD_INCORRECT' | 'TOO_MANY_ATTEMPTS' | 'CONFIRMATION_MISMATCH' | 'INVALID_TOKEN' | 'MISSING_PERMISSIONS' | 'REPO_NOT_FOUND' | 'REPO_MISSING_BRANCHES' | 'UNKNOWN' | 'SANDBOX_NOT_READY' | 'SYNC_FAILED' | 'TOKEN_EXPIRED' | 'GITHUB_NOT_CONNECTED' | 'FIGMA_TOKEN_MISSING' | 'FIGMA_TOKEN_MALFORMED' | 'FIGMA_TOKEN_INVALID' | 'FIGMA_TOKEN_FORBIDDEN' | 'FIGMA_RATE_LIMITED' | 'FIGMA_UNREACHABLE' | 'INVALID_IMPORT_CODE' | 'IMPORT_SOURCE_GONE' | 'PROJECT_NOT_IMPORTABLE' | 'PROJECT_IMPORT_LIMIT_REACHED' | 'PROJECT_EXPORT_LIMIT_REACHED' | 'VERSION_NOT_FOUND' | 'INVALID_CODE_EDIT' | 'CODE_EDIT_FAILED' | 'BADGE_IN_SOURCE'; message?: string | undefined; } | undefined; }[]; vars: Record<string, unknown>; startedAt: string; credits: number; result?: unknown; endedAt?: string | undefined; }>
+```
+
+Polls until the program leaves `pending`/`running` (the `browser.program.completed` webhook is the push twin).
+
+## `totalum-sdk/realtime`
+
+### `totalumRealtime`
+
+```ts
+totalumRealtime(options?: TotalumClientOptions)
+```
+
+`totalum.realtime` server side over SDK-API `/v1/realtime/*` (scope `realtime`). The app's own
+server mints a short-lived ticket after its own auth check and hands `{ticket, url}` to the page; the page opens the
+`wss://` `url` and never holds a key. A room costs awake room-minutes × 4, never connections or messages.
+
+#### `realtime.ticket`
+
+```ts
+realtime.ticket(input: { room: string; identity: { id: string; name?: string | undefined; metadata?: Record<string, unknown> | undefined; }; permissions?: { subscribe?: boolean | undefined; publish?: boolean | undefined; } | undefined; ttl?: number | undefined; }): Promise<{ ticket: string; url: string; room: string; identity: { id: string; name?: string | undefined; metadata?: Record<string, unknown> | undefined; }; permissions: { subscribe: boolean; publish: boolean; }; expiresAt: string; }>
+```
+
+A ticket for one room, one identity and one permission set (default subscribe only), valid to join for `ttl`
+seconds (5–300, default 60).
+
+```ts
+const { url } = await realtime.ticket({ room: `chat:${orgId}`, identity: { id: user.id }, permissions: { publish: true } });
+```
+
+#### `realtime.publish`
+
+```ts
+realtime.publish(room: string, input: { data: unknown; event?: string | undefined; identity?: { id: string; name?: string | undefined; } | undefined; }): Promise<{ messageId: string; at: string; connections: number; }>
+```
+
+Publishes one message to every socket subscribed to `room`, from the app's own server (a route handler, a cron
+job): no socket needed. Subscribers receive the same `message` frame a socket publish sends, with `event`
+(default `message`) and `identity` (default `{ id: 'server' }`). Resolves with the message id, its timestamp
+and the number of sockets it was sent to (`0` when nobody is connected — it is not queued).
+
+```ts
+const { connections } = await realtime.publish(`orders:${shopId}`, { event: 'order.created', data: { orderId } });
+```
+
+## `totalum-sdk/logs`
+
+### `totalumLogs`
+
+```ts
+totalumLogs(options?: TotalumClientOptions)
+```
+
+`totalum.logs` over SDK-API `/v1/logs` (scope `logs:read`; the agent's sandbox key reads its dev
+preview for free): the Worker invocations of the published app (`env: 'live'`) or the preview (`'dev'`). Free.
+
+#### `logs.query`
+
+```ts
+logs.query(q?: LogsQuery): Promise<{ items: { ts: string; level: 'error' | 'log' | 'debug' | 'info' | 'warn'; message: string; requestId: string | null; method: string | null; path: string | null; status: number | null; cpuMs: number | null; wallMs: number | null; outcome: string; exception?: { name: string; message: string; stack?: string | undefined; } | undefined; }[]; window: { from: string; to: string; source: 'live' | 'buffer'; }; nextCursor: string | null; sampled: boolean; hint?: string | undefined; }>
+```
+
+Up to `limit` (≤ 500) log lines, newest first; `window` is always the window actually searched.
+
+```ts
+const { items } = await logs.query({ level: 'error', env: 'live' });
+```
+
+## `totalum-sdk/analytics`
+
+### `totalumAnalytics`
+
+```ts
+totalumAnalytics(options?: TotalumClientOptions)
+```
+
+`totalum.analytics` over SDK-API `/v1/analytics/site` (scope `analytics:read`): the site's own traffic. Free.
+
+#### `analytics.site`
+
+```ts
+analytics.site(q?: SiteAnalyticsQuery): Promise<{ window: { from: string; to: string; granularity: 'day' | 'hour' | 'minute'; }; source: 'wae'; approximate: { uniques: boolean; }; cachedAt: string; series?: { [x: string]: number; t: string; }[] | undefined; top?: { [x: string]: number; key: string; share: number; }[] | undefined; }>
+```
+
+Page views, visits, uniques, errors, bytes or TTFB as a series or a top-N.
+
+```ts
+const { top } = await analytics.site({ dimension: 'path', metric: 'page_views', limit: 10 });
+```
+
+## `totalum-sdk/react`
+
+### `useRealtimeChannel`
+
+```ts
+useRealtimeChannel(room: string, options?: RealtimeChannelOptions<M>): { publish: (data: unknown, event?: string) => boolean; status: RealtimeStatus; messages: RealtimeMessage<unknown>[]; others: RealtimePeer<M>[]; }
+```
+
+A room in a client component: `status`, the `messages` received since it opened, `others` (with `presence`), and
+`publish(data, event?)`. Render `status === 'reconnecting'` as an ordinary state, not an error.
+
+```ts
+const { messages, others, publish, status } = useRealtimeChannel(`chat:${roomId}`, { presence: { name } });
+```
+
+## Types
+
+### `BrowserSession`
+
+```ts
+type BrowserSession = {
+  id: string;
+  liveViewUrl: string;
+  expiresAt: string;
+  actions: (batch: { [x: string]: unknown; type: 'pdf' | 'type' | 'waitFor' | 'screenshot' | 'content' | 'captcha.solve' | 'upload' | 'goto' | 'back' | 'forward' | 'reload' | 'pageInfo' | 'click' | 'dblclick' | 'press' | 'hover' | 'scroll' | 'dragAndDrop' | 'select' | 'frames.list' | 'frames.use' | 'tabs.list' | 'tabs.new' | 'tabs.use' | 'tabs.close' | 'evaluate' | 'extract' | 'cookies.get' | 'cookies.set' | 'cookies.clear' | 'storage.get' | 'storage.set' | 'storage.clear' | 'context.save' | 'downloads.list' | 'downloads.get' | 'network.capture' | 'network.log' | 'network.har' | 'network.intercept' | 'network.setHeaders' | 'emulate.viewport' | 'emulate.device' | 'emulate.geolocation' | 'emulate.timezone' | 'emulate.locale' | 'emulate.userAgent' | 'captcha.events' | 'proxy.usage' | 'stealth.get' | 'session.status' | 'session.liveView' | 'session.recording' | 'dialog.handle' | 'page.addInitScript' | 'page.exposeFunction' | 'emulate.media' | 'emulate.network' | 'emulate.cpu' | 'permissions.grant' | 'clipboard.read' | 'clipboard.write' | 'act' | 'observe' | 'session.release' | 'network.subscribe' | 'accessibility.snapshot'; frame?: string | undefined; tabId?: string | undefined; timeoutMs?: number | undefined; }[], opts?: { stopOnError?: boolean | undefined; } | undefined) => Promise<{ ok: boolean; data?: unknown; error?: { code: 'SERVICE_UNAUTHORIZED' | 'SERVICE_REPLAY' | 'ACTOR_MISMATCH' | 'PAYLOAD_TOO_LARGE' | 'VALIDATION_ERROR' | 'PROJECT_NOT_FOUND' | 'OPERATION_IN_PROGRESS' | 'AGENT_RUNNING' | 'PROJECT_MOVED' | 'OBJECT_MIGRATING' | 'INDEX_SHARD_UNAVAILABLE' | 'RATE_LIMIT_EXCEEDED' | 'PROJECT_PAUSED_RUNAWAY' | 'PROJECT_PAUSED_BALANCE' | 'PROJECT_SUSPENDED' | 'PROJECT_HIBERNATED' | 'PROJECT_DELETED' | 'PROJECT_PAUSED_BY_USER' | 'LIFECYCLE_NOT_APPLICABLE' | 'PROJECT_NOT_PAUSED' | 'PAUSE_DUMP_EXPIRED' | 'PAUSE_VERIFICATION_FAILED' | 'DEPLOYMENT_IN_PROGRESS' | 'REACTIVATE_IMPORT_MISMATCH' | 'RESUME_IMPORT_MISMATCH' | 'INSUFFICIENT_CREDITS' | 'VCAAS_INSUFFICIENT_CREDITS' | 'PROJECT_CREDIT_LIMIT_REACHED' | 'FREE_PROMPTS_DISABLED' | 'PLAN_REQUIRED' | 'FEATURE_LIMIT_REACHED' | 'FEATURE_DISABLED' | 'AGENT_ALREADY_RUNNING' | 'IMPORT_IN_PROGRESS' | 'TOO_MANY_RUN_REQUESTS' | 'PROMPT_SECURITY_VIOLATION' | 'NO_PROCESS_RUNNING' | 'RUN_NOT_FOUND' | 'DEPLOYMENT_RUNNING' | 'AUTO_EXECUTION_ALREADY_ACTIVE' | 'REBUILD_RUNNING' | 'SECRET_ALREADY_EXISTS' | 'SECRET_LIMIT_EXCEEDED' | 'RESERVED_SECRET_NAME' | 'DUMP_NOT_FOUND' | 'DUMP_INVALID' | 'RESTORE_TARGET_NOT_EMPTY' | 'ENGINE_NOT_SUPPORTED' | 'ENGINE_V2_DISABLED' | 'V2_TEMPORARILY_DISABLED' | 'ENGINE_REQUEST_NOT_ELIGIBLE' | 'ENGINE_MISMATCH' | 'INVALID_ENGINE_VERSION' | 'PROJECT_ENGINE_MISMATCH' | 'ENGINE_UNAVAILABLE' | 'PREVIEW_LABEL_TOO_LONG' | 'PROJECT_ALREADY_EXISTS' | 'CLOUDFLARE_API_ERROR' | 'PROVISIONING_BUSY' | 'UNAUTHORIZED' | 'LEGACY_KEY_NOT_SUPPORTED' | 'SANDBOX_KEY_EXPIRED' | 'AUTH_RATE_LIMITED' | 'FORBIDDEN_SCOPE' | 'KEY_ENV_MISMATCH' | 'KEY_LIMIT_EXCEEDED' | 'LIVE_DB_READ_ONLY' | 'LIVE_WRITE_NEEDS_CONFIRMATION' | 'DDL_NOT_ALLOWED' | 'MIGRATION_IN_PROGRESS' | 'MIGRATION_EDITED' | 'SCHEMA_OUT_OF_SYNC' | 'LIVE_MIGRATION_FAILED' | 'DESTRUCTIVE_MIGRATION_NEEDS_CONFIRMATION' | 'DEV_DATABASE_NOT_FOUND' | 'DATABASE_ROLE_NOT_FOUND' | 'BOOKMARK_NOT_FOUND' | 'BACKUP_NOT_FOUND' | 'BACKUP_NOT_DELETABLE' | 'BACKUP_RATE_LIMITED' | 'PRE_RESTORE_BACKUP_FAILED' | 'RESTORE_VERIFY_FAILED' | 'RUN_NOT_LATEST' | 'DEV_DATABASE_EXISTS' | 'SQL_ERROR' | 'SQL_MULTI_STATEMENT' | 'SQL_STATEMENT_TOO_LARGE' | 'SQL_TOO_MANY_PARAMS' | 'STATEMENT_NOT_ALLOWED' | 'VIRTUAL_TABLES_NOT_SUPPORTED' | 'USE_STORAGE_FOR_FILES' | 'D1_TYPE_ERROR' | 'MIGRATION_INVALID' | 'SYSTEM_TABLE_READ_ONLY' | 'SQL_READ_ONLY' | 'RESULT_TOO_LARGE' | 'NL_QUERY_UNANSWERABLE' | 'QUERY_TIMEOUT' | 'DB_OVERLOADED' | 'D1_TRANSIENT' | 'DB_FULL_NEAR_LIMIT' | 'IDEMPOTENCY_KEY_REUSED' | 'IDEMPOTENT_REPLAY_UNAVAILABLE' | 'TABLE_NOT_FOUND' | 'SCHEMA_TOO_LARGE_FOR_COUNTS' | 'EXEC_REQUIRES_MIGRATE_MODE' | 'MIGRATION_UNKNOWN_IN_DB' | 'QUERY_LIMIT_EXCEEDED' | 'STORAGE_LIMIT_EXCEEDED' | 'METER_UNAVAILABLE' | 'COLUMN_NOT_FOUND' | 'VALUE_NOT_ALLOWED' | 'COLUMN_REQUIRED' | 'FILTER_TOO_COMPLEX' | 'OFFSET_TOO_LARGE' | 'BULK_TOO_LARGE' | 'NOT_A_JUNCTION_TABLE' | 'AMBIGUOUS_RELATION' | 'LIVE_WRITE_CONFIRMATION_REQUIRED' | 'RECORD_NOT_FOUND' | 'DEV_NAME_GUARD' | 'PROD_NAME_GUARD' | 'INVALID_RUN_REQUEST' | 'RUN_ALREADY_ACTIVE' | 'RUN_CONFLICT' | 'INVALID_CREDENTIALS' | 'ADAPTER_UNAVAILABLE' | 'DISK_FULL' | 'DEPLOY_FIX_ATTEMPTS_EXHAUSTED' | 'TOKEN_REVOKED' | 'AM_UPDATE_DOWNLOAD_FAILED' | 'AM_UPDATE_BAD_SHA' | 'AM_UPDATE_BAD_SIGNATURE' | 'AM_UPDATE_INCOMPATIBLE_IMAGE' | 'AM_UPDATE_START_FAILED' | 'AM_VERSION_UNAVAILABLE' | 'AM_UPDATE_FAILED' | 'RELEASE_CANARY_NOT_PASSED' | 'RELEASE_NOT_FOUND' | 'RELEASE_ROLLOUT_ACTIVE' | 'RELEASE_GUARD_PAUSED' | 'RELEASE_BUILD_UNAVAILABLE' | 'VISUAL_EDIT_PREVIEW_DEPLOYING' | 'VISUAL_EDIT_NOT_PATCHABLE' | 'VISUAL_EDIT_BASE_MISMATCH' | 'VISUAL_EDIT_TYPECHECK_FAILED' | 'INVALID_VISUAL_EDIT' | 'IMAGE_VERSION_NOT_FOUND' | 'IMAGE_VERSION_NOT_PROMOTABLE' | 'REALTIME_TICKET_INVALID' | 'REALTIME_TICKET_EXPIRED' | 'REALTIME_PERMISSION_DENIED' | 'REALTIME_MESSAGE_TOO_LARGE' | 'REALTIME_MESSAGE_RATE_EXCEEDED' | 'REALTIME_CONNECTION_LIMIT_REACHED' | 'REALTIME_ROOM_LIMIT_REACHED' | 'CONFIRMATION_REQUIRED' | 'MIGRATION_NOT_REVERSIBLE' | 'ALREADY_ON_PROVIDER' | 'DATABASE_MIGRATING' | 'LOGWATCH_INACTIVE' | 'AGENT_LOG_READS_LIMIT' | 'LOGS_UPSTREAM_ERROR' | 'ANALYTICS_INVALID_QUERY' | 'ANALYTICS_UPSTREAM_ERROR' | 'ANALYTICS_WINDOW_OUT_OF_RETENTION' | 'INVALID_CIDR' | 'RATE_LIMIT_ABOVE_PLAN' | 'RATE_LIMIT_DISABLE_NOT_ALLOWED' | 'OWNER_ONLY' | 'SIGNING_NOT_CONFIGURED' | 'SIGNING_ALREADY_CONFIGURED' | 'SIGNING_INVALID_KEYSTORE' | 'SIGNING_INVALID_ASC_KEY' | 'KEYSTORE_DOWNLOAD_EXPIRED' | 'KEYSTORE_NOT_DOWNLOADABLE' | 'MOBILE_BUILD_RUNNING' | 'MOBILE_BUILD_NOT_FOUND' | 'MOBILE_BUILD_NOT_READY' | 'DOWNLOAD_EXPIRED' | 'PROCESS_IN_PROGRESS' | 'SANDBOX_NOT_RUNNING' | 'MOBILE_LAYER_MISSING' | 'MOBILE_BUILD_FAILED' | 'MOBILE_ARTIFACT_INVALID' | 'SIGNING_FINGERPRINT_MISMATCH' | 'AM_RESTARTED' | 'LIMIT_ABOVE_PLAN_CEILING' | 'UNKNOWN_FEATURE' | 'INVALID_LIMIT' | 'FEATURE_NOT_DISABLABLE' | 'USE_PUT_LIMITS' | 'LIMIT_NOT_USER_EDITABLE' | 'NOT_AVAILABLE_FOR_ENGINE' | 'INVALID_AMOUNT' | 'REFUND_EXCEEDS_CHARGES' | 'IDEMPOTENCY_CONFLICT' | 'ORGANIZATION_NOT_FOUND' | 'ACCOUNT_NOT_FOUND' | 'PROVIDER_UNAVAILABLE' | 'URL_NOT_ALLOWED' | 'JOB_NOT_FOUND' | 'FILE_TOO_LARGE' | 'UNSUPPORTED_FILE_TYPE' | 'FILE_NOT_FOUND' | 'FILE_KEY_FORBIDDEN' | 'FILE_UPLOAD_ERROR' | 'FILE_DOWNLOAD_ERROR' | 'FILE_DELETE_ERROR' | 'UPLOAD_NOT_COMPLETED' | 'MISSING_URL' | 'MISSING_INPUT' | 'MISSING_EXTRACTION_CONFIG' | 'MISSING_QUERY' | 'SCRAPE_FAILED' | 'EXTRACT_FAILED' | 'SCREENSHOT_FAILED' | 'SEARCH_FAILED' | 'SCRAPE_BLOCKED' | 'SESSION_NOT_FOUND' | 'SESSION_EXPIRED' | 'SESSION_BUSY' | 'SESSION_LIMIT_REACHED' | 'SESSION_ENDED_INSUFFICIENT_CREDITS' | 'ACTION_TIMEOUT' | 'ACTION_FAILED' | 'UNKNOWN_COMMAND' | 'BATCH_TOO_LARGE' | 'SKIPPED' | 'UPLOAD_TOO_LARGE' | 'DOWNLOAD_TOO_LARGE' | 'CAPTURE_LIMIT_REACHED' | 'CAPTCHA_UNSOLVED' | 'BROWSER_CDP_NODE_ONLY' | 'DIALOG_NOT_OPEN' | 'STEALTH_TIER_UNAVAILABLE' | 'DOMAIN_NOT_ALLOWED' | 'CONTEXT_SEED_UNSUPPORTED' | 'EXTENSION_TOO_LARGE' | 'NL_PROVIDER_UNAVAILABLE' | 'PROGRAM_TOO_LARGE' | 'PROGRAM_UNBOUNDED' | 'UNKNOWN_STEP' | 'PROGRAM_IN_FLIGHT' | 'PROGRAM_TIMEOUT' | 'PROGRAM_NOT_FOUND' | 'PROGRAM_STEP_FAILED' | 'PROGRAM_LIMIT_REACHED' | 'CREATE_PDF_FROM_HTML_ERROR' | 'GENERATE_PDF_BY_URL_ERROR' | 'PDF_TIMEOUT' | 'PDF_TOO_LARGE' | 'FILENAME_REQUIRED' | 'SCANUM_EYE_ARRAY_NOT_SUPPORTED' | 'INVALID_EXTRA_FIELD_TYPE' | 'SCANUM_EYE_PDF_NOT_SUPPORTED' | 'UNSUPPORTED_SCAN_MODEL' | 'SCAN_DOCUMENT_ERROR' | 'SCAN_INVOICE_ERROR' | 'OCR_IMAGE_PROCESSING_ERROR' | 'OCR_PDF_PROCESSING_ERROR' | 'SCAN_TOO_MANY_PAGES' | 'SCAN_PDF_ENCRYPTED' | 'SCAN_XFA_UNSUPPORTED' | 'AUDIO_FILE_REQUIRED' | 'AUDIO_FILE_TOO_LARGE' | 'INVALID_AUDIO_FORMAT' | 'AUDIO_TRANSCRIPTION_ERROR' | 'TTS_TEXT_TOO_LONG' | 'TTS_VOICE_UNKNOWN' | 'TOO_MANY_AUDIO_TRANSCRIPTIONS' | 'EMAIL_SEND_FAILED' | 'TOO_MANY_ATTACHMENTS' | 'INVALID_ATTACHMENT_URL' | 'ATTACHMENT_TOO_LARGE' | 'TOO_MANY_RECIPIENTS' | 'EMAIL_RECIPIENT_SUPPRESSED' | 'EMAIL_DOMAIN_NOT_VERIFIED' | 'EMAIL_LOCAL_PART_TAKEN' | 'EMAIL_SENDING_PAUSED' | 'EMAIL_DOMAINS_REQUIRE_PAID_PLAN' | 'SUPPRESSION_PERMANENT' | 'DEV_RECIPIENT_NOT_ALLOWED' | 'CRON_LIMIT_REACHED' | 'INVALID_SCHEDULE' | 'CRON_URL_NOT_ALLOWED' | 'CRON_JOB_NOT_FOUND' | 'CRON_REQUIRES_PUBLISHED_PROJECT' | 'URL_NOT_PROJECT_HOST' | 'INDEXNOW_ERROR' | 'MCP_VERIFY_FAILED' | 'MCP_NAME_RESERVED' | 'MCP_LIMIT_REACHED' | 'MCP_SERVER_NOT_FOUND' | 'PAYMENTS_NOT_ENABLED' | 'PAYMENTS_LIVE_ONBOARDING_REQUIRED' | 'CARD_DATA_NOT_ACCEPTED' | 'STRIPE_ERROR' | 'STRIPE_RATE_LIMITED' | 'PAYMENTS_WEBHOOK_SIGNATURE_INVALID' | 'AI_MODEL_NOT_ALLOWED' | 'AI_MODEL_UNKNOWN' | 'AI_INVALID_SCHEMA' | 'AI_CONTENT_BLOCKED' | 'AI_CONTEXT_TOO_LONG' | 'AI_PROVIDER_QUOTA' | 'AI_PROVIDER_UNAVAILABLE' | 'AI_STREAM_ERROR' | 'AI_VIDEO_JOB_NOT_FOUND' | 'AI_VIDEO_FAILED' | 'MISSING_VIDEO_URL' | 'MISSING_PROMPT' | 'INVALID_VIDEO_URL' | 'INVALID_VIDEO_URL_PROTOCOL' | 'INVALID_MIME_TYPE_HINT' | 'VIDEO_TOO_LARGE' | 'VIDEO_URL_UNREACHABLE' | 'VIDEO_URL_NOT_A_VIDEO' | 'YOUTUBE_VIDEO_UNAVAILABLE' | 'NO_PAYMENT_METHOD' | 'DOMAIN_CONTACT_REQUIRED' | 'DOMAIN_UNAVAILABLE' | 'DOMAIN_PREMIUM_NOT_ALLOWED' | 'TLD_NOT_ALLOWED' | 'DOMAIN_LIMIT_REACHED' | 'PRICE_CHANGED' | 'PAYMENT_FAILED' | 'REGISTRATION_FAILED' | 'DOMAIN_NOT_RENEWABLE' | 'DOMAIN_ALREADY_ATTACHED' | 'DNS_RECORD_MANAGED' | 'DNS_RECORD_CONFLICT' | 'DNS_RECORD_LIMIT' | 'DOMAIN_TRANSFER_LOCKED' | 'DOMAIN_NOT_FOUND' | 'DOMAIN_IN_USE' | 'DOMAIN_ALREADY_ADDED' | 'NO_DEPLOYMENT' | 'REDIRECT_LIMIT_REACHED' | 'REDIRECT_INVALID' | 'APEX_NOT_FLATTENABLE' | 'SECOND_FACTOR_NOT_CONFIGURED' | 'PASSWORD_REQUIRED' | 'PASSWORD_INCORRECT' | 'TOO_MANY_ATTEMPTS' | 'CONFIRMATION_MISMATCH' | 'INVALID_TOKEN' | 'MISSING_PERMISSIONS' | 'REPO_NOT_FOUND' | 'REPO_MISSING_BRANCHES' | 'UNKNOWN' | 'SANDBOX_NOT_READY' | 'SYNC_FAILED' | 'TOKEN_EXPIRED' | 'GITHUB_NOT_CONNECTED' | 'FIGMA_TOKEN_MISSING' | 'FIGMA_TOKEN_MALFORMED' | 'FIGMA_TOKEN_INVALID' | 'FIGMA_TOKEN_FORBIDDEN' | 'FIGMA_RATE_LIMITED' | 'FIGMA_UNREACHABLE' | 'INVALID_IMPORT_CODE' | 'IMPORT_SOURCE_GONE' | 'PROJECT_NOT_IMPORTABLE' | 'PROJECT_IMPORT_LIMIT_REACHED' | 'PROJECT_EXPORT_LIMIT_REACHED' | 'VERSION_NOT_FOUND' | 'INVALID_CODE_EDIT' | 'CODE_EDIT_FAILED' | 'BADGE_IN_SOURCE'; message?: string | undefined; } | undefined; }[]>;
+  program: (program: { steps: BrowserStep[]; vars?: Record<string, unknown> | undefined; timeoutSec?: number | undefined; webhookUrl?: string | undefined; }) => Promise<{ programId: string; status: 'pending'; pollUrl: string; }>;
+  status: () => Promise<{ id: string; status: 'running' | 'failed' | 'expired' | 'ended'; startedAt: string; minutes: number; proxyMb: number; captchas: number; credits: number; expiresAt: string; }>;
+  close: () => Promise<{ minutes: number; proxyMb: number; captchas: number; creditsUsed: number; recordingUrl?: string | undefined; }>;
+}
+```
+
+One method per command, named like the command; the leading arguments are the command's main parameters (`goto(url, rest?)`, `click(target, rest?)`, `type(target, text, rest?)`, …) and the last argument is the rest of its parameters; each resolves to the command's result: `accessibility.snapshot`, `act`, `back`, `captcha.solve`, `click`, `clipboard.read`, `content`, `context.save`, `cookies.get`, `dblclick`, `dialog.handle`, `downloads.list`, `dragAndDrop`, `emulate.viewport`, `evaluate`, `extract`, `forward`, `frames.list`, `goto`, `hover`, `network.capture`, `observe`, `page.addInitScript`, `pageInfo`, `pdf`, `permissions.grant`, `press`, `proxy.usage`, `reload`, `screenshot`, `scroll`, `select`, `session.status`, `stealth.get`, `storage.get`, `tabs.list`, `type`, `upload`, `waitFor`.
+
+### `ChatResult`
+
+```ts
+type ChatResult = {
+  id: string;
+  model: string;
+  text: string;
+  toolCalls: ToolCall[];
+  finishReason: string | null;
+  usage: ChatUsage;
+  raw: unknown;
+}
+```
+
+### `ChatStream`
+
+```ts
+type ChatStream = {
+  raw: ReadableStream<Uint8Array<ArrayBufferLike>>;
+  text: () => AsyncIterable<string>;
+  result: () => Promise<ChatResult>;
+}
+```
+
+### `D1Database`
+
+```ts
+type D1Database = {
+  prepare: (sql: string) => D1PreparedStatement;
+  batch: <T = unknown>(statements: D1PreparedStatement[]) => Promise<D1Result<T>[]>;
+  exec: (sql: string) => Promise<D1ExecResult>;
+  dump: () => Promise<ArrayBuffer>;
+  withSession: (constraintOrBookmark?: string | undefined) => D1DatabaseSession;
+}
+```
+
+### `LogsQuery`
+
+```ts
+type LogsQuery = {
+  limit?: number;
+  env?: 'dev' | 'live';
+  requestId?: string;
+  status?: string;
+  to?: string;
+  from?: string;
+  source?: 'live' | 'auto' | 'buffer';
+  level?: 'error' | 'log' | 'debug' | 'info' | 'warn';
+  q?: string;
+  path?: string;
+}
+```
+
+### `RealtimeChannelOptions`
+
+```ts
+type RealtimeChannelOptions = {
+  /** The app's route that mints the ticket; it receives `{ room }` and answers `{ url }` or `{ data: { url } }`. */
+  ticketUrl?: string;
+  /** Or mint the ticket yourself. */
+  getTicket?: ((room: string) => Promise<{ url: string; }>);
+  /** Announce this connection's presence with this metadata (name, colour…); `others` lists everyone else's. */
+  presence?: M;
+  /** Messages kept in memory, newest last (default 100). */
+  keep?: number;
+  /** Tests only. */
+  WebSocket?: { new (url: string | URL, protocols?: string | string[] | undefined): WebSocket; prototype: WebSocket; readonly CONNECTING: 0; readonly OPEN: 1; readonly CLOSING: 2; readonly CLOSED: 3; };
+}
+```
+
+### `ScanDocumentResult`
+
+```ts
+type ScanDocumentResult = {
+  data: Record<string, unknown> | Record<string, unknown>[];
+  metadata: { usageUnits: number; exactUsageUnits: number; pages: number; provider: string; credits: number; };
+}
+```
+
+### `SiteAnalyticsQuery`
+
+```ts
+type SiteAnalyticsQuery = {
+  /** ISO; default the last 7 days. */
+  from?: string;
+  to?: string;
+  /** `minute` only within the last 30 minutes. */
+  granularity?: 'day' | 'hour' | 'minute';
+  /** Up to 4. */
+  metric?: 'uniques' | 'bytes' | 'errors' | 'page_views' | 'hits' | 'ttfb_p50' | 'ttfb_p95' | ('uniques' | 'bytes' | 'errors' | 'page_views' | 'hits' | 'ttfb_p50' | 'ttfb_p95')[];
+  /** Omit for a time series (`series`); set for a top-N (`top`). */
+  dimension?: 'browser' | 'country' | 'status' | 'device' | 'path' | 'hostname' | 'os' | 'referrer';
+  /** Top-N, ≤ 100. */
+  limit?: number;
+  bots?: 'exclude' | 'include' | 'only';
+  /** `dev` = the preview host, `live` = the published and custom hosts; omitted = both. */
+  env?: 'dev' | 'live';
+}
+```
+
+### `TotalumAiOptions`
+
+```ts
+type TotalumAiOptions = {
+  /** The exact-OpenRouter gateway `gatewayConfig()` returns; default `TOTALUM_AI_BASE_URL`, else `https://ai.totalum.app/api/v1`. */
+  aiBaseUrl?: string;
+  /** Project key `tlm_pk_…`; default `TOTALUM_PROJECT_KEY`. Server-side only. */
+  key?: string;
+  /** Default `TOTALUM_SDK_API_URL`, else `https://sdk-api.totalum.app`. */
+  apiUrl?: string;
+  /** Sent as `x-totalum-env` on every call (the database it targets, and dev vs live usage); default `TOTALUM_ENV`, else `live`. */
+  env?: 'dev' | 'live';
+}
+```
+
+### `TotalumClientOptions`
+
+```ts
+type TotalumClientOptions = {
+  /** Project key `tlm_pk_…`; default `TOTALUM_PROJECT_KEY`. Server-side only. */
+  key?: string;
+  /** Default `TOTALUM_SDK_API_URL`, else `https://sdk-api.totalum.app`. */
+  apiUrl?: string;
+  /** Sent as `x-totalum-env` on every call (the database it targets, and dev vs live usage); default `TOTALUM_ENV`, else `live`. */
+  env?: 'dev' | 'live';
+}
+```
+
+### `TotalumD1Options`
+
+```ts
+type TotalumD1Options = {
+  /** `'migrate'` (scripts/migrate.ts only) sends `x-totalum-migrate: 1` and enables `exec()`; default `'query'`. */
+  mode?: 'query' | 'migrate';
+  /** Migrate mode only: sends `x-totalum-migrate-destructive: 1`. */
+  destructive?: boolean;
+  /** An explicit binding wins over detection (plain Workers: `env.TOTALUM_DB`; tests: a Miniflare D1). */
+  binding?: D1Database;
+  /** `'https'` forces the HTTPS path even inside a Worker (the conformance corpus); default `'auto'`. */
+  transport?: 'auto' | 'https';
+  /** Project key `tlm_pk_…`; default `TOTALUM_PROJECT_KEY`. Server-side only. */
+  key?: string;
+  /** Default `TOTALUM_SDK_API_URL`, else `https://sdk-api.totalum.app`. */
+  apiUrl?: string;
+  /** Sent as `x-totalum-env` on every call (the database it targets, and dev vs live usage); default `TOTALUM_ENV`, else `live`. */
+  env?: 'dev' | 'live';
+}
+```
+
+### `TotalumFilesOptions`
+
+```ts
+type TotalumFilesOptions = {
+  /** The public files host; default `TOTALUM_FILES_URL`, else `https://files.totalum-project.com`. */
+  filesUrl?: string;
+  /** Project key `tlm_pk_…`; default `TOTALUM_PROJECT_KEY`. Server-side only. */
+  key?: string;
+  /** Default `TOTALUM_SDK_API_URL`, else `https://sdk-api.totalum.app`. */
+  apiUrl?: string;
+  /** Sent as `x-totalum-env` on every call (the database it targets, and dev vs live usage); default `TOTALUM_ENV`, else `live`. */
+  env?: 'dev' | 'live';
+}
+```
+
+### `TotalumOptions`
+
+```ts
+type TotalumOptions = {
+  /** The exact-OpenRouter gateway `gatewayConfig()` returns; default `TOTALUM_AI_BASE_URL`, else `https://ai.totalum.app/api/v1`. */
+  aiBaseUrl?: string;
+  /** Project key `tlm_pk_…`; default `TOTALUM_PROJECT_KEY`. Server-side only. */
+  key?: string;
+  /** Default `TOTALUM_SDK_API_URL`, else `https://sdk-api.totalum.app`. */
+  apiUrl?: string;
+  /** Sent as `x-totalum-env` on every call (the database it targets, and dev vs live usage); default `TOTALUM_ENV`, else `live`. */
+  env?: 'dev' | 'live';
+  /** The public files host; default `TOTALUM_FILES_URL`, else `https://files.totalum-project.com`. */
+  filesUrl?: string;
+}
+```
+
+### `UploadOptions`
+
+```ts
+type UploadOptions = {
+  name?: string;
+  contentType?: string;
+  /** `true` stores the file under the private prefix: no public URL, read it through `getSignedUrl`. */
+  private?: boolean;
+  folder?: string;
+}
+```