diff --git a/.agents/skills/hyperbug-development/SKILL.md b/.agents/skills/hyperbug-development/SKILL.md new file mode 100644 index 0000000..31d6f96 --- /dev/null +++ b/.agents/skills/hyperbug-development/SKILL.md @@ -0,0 +1,35 @@ +--- +name: hyperbug-development +description: "Implement or fix HyperBug product features, backend contracts and adapters, or frontend workflows according to the repository plan. Use for feature development and application behavior changes; use hyperbug-maintenance for dependency upgrades, migrations, releases, and operational recovery." +--- + +# HyperBug Development + +Develop the requested HyperBug capability within its accepted architecture and delivery gates. This is repository-specific guidance; it does not authorize unrelated features or deployment. + +## Begin with the current state + +Read [root guidance](../../../AGENTS.md), [master progress](../../../docs/plan/PROGRESS.md), and [session handoffs](references/session-handoffs.md). Identify the owning module and read its plan and latest progress entry before editing. Source policies and their refinements are indexed in [SOURCES](../../../docs/plan/SOURCES.md). + +G0 must pass before application work. Complete the backend acceptance gate in module 10 before starting the product SPA; each post-MVP feature also accepts its backend before its UI. Backend-owned authorization pages and minimal protocol test fixtures are distinct from product SPA work. + +Use the selected checklist IDs to bound the change. Inspect existing package scripts and implementation rather than treating planned paths, command names, or source version snapshots as installed facts. + +## Read only the relevant references + +| Work | Reference | +| --- | --- | +| Endpoints, domain/application services, persistence adapters, queues, or plugins | [Backend development](references/backend.md) | +| Static SPA, browser auth, forms, components, or backend-owned HTML | [Frontend development](references/frontend.md) | +| Authentication, permissions, credentials, content, uploads, trust boundaries, or review/ADR decisions | [Security and review boundaries](references/security.md) | +| Selecting verification or deciding acceptance | [Testing and evidence](references/testing.md) | +| Any session start, checkpoint, or finish | [Session handoffs](references/session-handoffs.md) | +| A feature needs a schema/data migration | [Database changes](../hyperbug-maintenance/references/database-migrations.md) | + +## Implement and close the batch + +Keep domain/public contracts independent of runtime infrastructure. Share product, authorization, and consistency semantics across both production profiles; allow optimized adapter implementations. Backend writes need server validation, object permissions, required audit/timeline events, and bounded work from their first implementation. + +Fetch current library documentation and relevant web guidance using the rules in root guidance. Record unresolved assumptions instead of silently weakening a baseline or changing the chosen stack. + +Verify the changed behavior and affected contracts using the testing reference. Update relevant specifications and guidance in English. Complete only evidence-backed checklist items, then record progress, changed files, verification, next actions, and next-session cautions in every affected progress record. Follow the session reference even when the batch only investigated a failure. diff --git a/.agents/skills/hyperbug-development/agents/openai.yaml b/.agents/skills/hyperbug-development/agents/openai.yaml new file mode 100644 index 0000000..fa9b9e9 --- /dev/null +++ b/.agents/skills/hyperbug-development/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "HyperBug Development" + short_description: "Develop HyperBug within its architecture and plan" + default_prompt: "Use $hyperbug-development to implement the next eligible HyperBug checklist item and record the session handoff." diff --git a/.agents/skills/hyperbug-development/references/backend.md b/.agents/skills/hyperbug-development/references/backend.md new file mode 100644 index 0000000..9fdf0e3 --- /dev/null +++ b/.agents/skills/hyperbug-development/references/backend.md @@ -0,0 +1,32 @@ +# Backend development + +Read for backend features, API contracts, repositories, queues, and plugins. Use [SOURCES](../../../../docs/plan/SOURCES.md) to locate TECH-STACK §§3–30, 38–54, the relevant PRODUCT scope, and the owning [module](../../../../docs/plan/README.md#module-index). + +## Boundaries that determine implementation + +- Domain entities and public schemas have no infrastructure dependencies. Application services use repository/security/blob/queue/workflow ports. Adapters implement the ports; runtime composition roots supply them. +- Share Elysia routes and middleware in the server package. Runtime startup belongs in the Workers/Node entry points; D1 bindings, PostgreSQL pools, R2 buckets, S3 clients, and workflow objects must not leak into the domain. +- Publish versioned REST/OpenAPI and framework-independent DTOs. Clients do not import server implementation types or require Elysia to consume the contract. +- Keep Cloudflare and self-host behavior equivalent while allowing separate SQL, FTS, indexes, transactions, and infrastructure integrations. Resolve package/API details through current documentation; do not assume Node tooling capabilities exist in Workers. +- Preserve User/Staff separation, project-local Issue numbers, simple Open/Closed state, and optional provider integrations. Core is usable without an email, SSO, or CAPTCHA plugin. + +## Complete a backend capability + +Choose the owning checklist and define the request/response/error contract, object permissions, invariant, transaction intent, event/audit requirements, and resource bounds before exposing the route. + +Implement domain/application behavior, each required repository adapter, route validation/error mapping, and contract evidence as one coherent feature. Where a mutation needs timeline/audit/outbox records, prove the intended atomic outcome. A zero-row conditional update is not automatically an exception or rollback. + +Use [database changes](../../hyperbug-maintenance/references/database-migrations.md) for schema work and [security](security.md) for credentials, permissions, content, or trust boundaries. + +## Query and side-effect decisions + +Use bounded keyset/cursor pagination with stable unique tie-breakers and indexes matched to filter/sort/join patterns. Batch hydration rather than querying relations per result. Keep the structured search AST independent of FTS5 and PostgreSQL syntax and enforce current authorization even with stale indexes. + +Record non-critical effects through the outbox/queue path. Assume at-least-once execution; bound fan-out/retries/concurrency and retain recoverable failures. Workflow steps need bounded checkpoints and replay-safe writes. See modules 08–09 for index dispatch and workflow handoffs. + +Use upload intents, direct object-store upload, and verified finalization; do not buffer ordinary uploads through the API. Check object identity/immutability as well as declared metadata. Native plugins are trusted application code; declared permissions are not a sandbox. + +## Acceptance + +Use [testing](testing.md) to select both-runtime contract, authorization, concurrency, migration, and resource-bound checks. Record real versus emulated results and unresolved profile differences. Update public specifications/client contracts where affected and finish the [session handoff](session-handoffs.md). + diff --git a/.agents/skills/hyperbug-development/references/frontend.md b/.agents/skills/hyperbug-development/references/frontend.md new file mode 100644 index 0000000..6b8b937 --- /dev/null +++ b/.agents/skills/hyperbug-development/references/frontend.md @@ -0,0 +1,36 @@ +# Frontend development + +Read for product SPA work and backend-owned HTML/auth fixtures. First inspect G1 in [master progress](../../../../docs/plan/PROGRESS.md). Before G1 passes, work on the relevant backend contract/test fixture; do not scaffold the product SPA. A post-MVP feature needs its own backend acceptance before UI work. + +## Research and compatibility + +Follow root Context7 rules for the selected React/TanStack/Vite/UI APIs. Use the available modern-web-guidance skill before relevant HTML/CSS/client-side work: action-oriented search, relevant guide retrieval, then implementation/fallback review. Use its current instructions rather than hard-coding an old skill-version command here. + +Record guide IDs, lookup date, feature status, and fallback in the owning progress entry or linked design record. If guidance is unavailable, record the gap; do not claim compliance based on a remembered guide. + +The project baseline is Baseline Widely Available and WCAG 2.2 AA. Newly Available features require detection and usable fallback; Limited Availability cannot become a core dependency without the specified decision/review. Avoid blanket polyfills. Browser support does not replace keyboard, screen-reader, touch, zoom, contrast, and reduced-motion checks. + +## Static application and state + +The build must run on generic static hosting and Cloudflare Pages without SSR, Pages Functions, or a mandatory proxy. Runtime configuration contains public values only and can change the API origin without recompilation. Align deployment CSP with configured API/auth/media origins. + +Use Router for URL/navigation state, Query for remote state, Form for form state, and React for local UI. Preserve shareable filters/sort/search, back/forward behavior, request cancellation, and bounded cache/page accumulation. Invalidate or partition user-specific state on identity changes. + +Browser access tokens remain in memory; no localStorage, sessionStorage, IndexedDB, or persistent refresh token. Use top-level PKCE recovery and business API requests with omitted credentials. Short-lived one-shot redirect state/verifiers are distinct from access tokens and follow module 11's policy. Cookie-backed authorization pages retain their own CSRF defenses. + +## Forms, content, and interaction + +Use semantic controls, visible labels, associated help/errors, server-error mapping, and deliberate focus management. Coordinate visual/ARIA validation after interaction, handle IME composition, and keep drafts recoverable without leaking them across principals. Browser validation does not replace backend validation. + +Render Markdown through the shared versioned sanitizer after raw HTML parsing; never introduce a separate feature allowlist. Upload directly through the accepted intent/finalize protocol and show safe retry/expiry/quota outcomes. + +Native dialogs or established accessible primitives must provide focus placement/restoration, Escape where appropriate, and explicit close/cancel. Additional platform dismissal gestures are progressive enhancements. + +Profile long timelines before optimizing. If applying content-visibility to confirmed offscreen content, reserve intrinsic size, verify sequential keyboard/find-in-page behavior, and retain ordinary rendering without support. Keep optional provider/admin resources out of the initial bundle when practical. + +## Adapt guidance to HyperBug + +Do not copy guide examples that add SSR fallback, cookie-based business authentication, inline script handlers, relaxed CSP, or a second sanitizer. Reviewed provider SDK origins differ from arbitrary remote plugin JavaScript. Native plugin UI is build-time composition. + +Sources: ARCHITECTURE §§7–21, SECURITY §§7–20, 40–61, and PERFORMANCE §§25–34 via [SOURCES](../../../../docs/plan/SOURCES.md). Apply [testing](testing.md) and [session handoffs](session-handoffs.md) to close the work. + diff --git a/.agents/skills/hyperbug-development/references/security.md b/.agents/skills/hyperbug-development/references/security.md new file mode 100644 index 0000000..40e4baa --- /dev/null +++ b/.agents/skills/hyperbug-development/references/security.md @@ -0,0 +1,29 @@ +# Security and review boundaries + +Read when work changes security behavior or when deciding review/ADR scope. Authoritative requirements are in SECURITY and PERFORMANCE through [SOURCES](../../../../docs/plan/SOURCES.md); this reference routes decisions rather than replacing those baselines. + +## Core policy checks + +| Change surface | Invariants and source sections | +| --- | --- | +| Identity/auth | User and Staff are distinct; email matching grants no Staff privilege. PKCE S256, exact redirects, one-use codes, short-lived opaque tokens, immediate revocation, and first-party authorization sessions. SECURITY §§7–44. | +| Authorization | Check object/project permissions on the server, including searches and delayed jobs. Fail closed on verification errors; require assurance/recent authentication where specified. SECURITY §§35–39, 141, 158–159. | +| Credentials/keys | Hash non-recoverable credentials; use mature crypto and AES-256-GCM envelope encryption for recoverable secrets, contextual AAD, unique nonces, key IDs/rotation. Do not lower memory-hard password parameters to fit a runtime. SECURITY §§28–34, 67–91, 148–150. | +| Content/uploads | Final tree sanitization after raw HTML parse; centralized versioned policy. Reauthorize uploads/finalization, verify actual objects, isolate dangerous media, and prevent post-validation overwrite. SECURITY §§53–66, 99–105. | +| Cross-origin/cache | Explicit origins; no ambient cookies for business APIs; CSRF protection for cookie flows. Never reuse private responses through shared caches or weaken CSP for an ordinary plugin. SECURITY §§40–52, 132–136. | +| External/plugin | Central SSRF/redirect/size/timeout limits; scoped secret/capability access. Native code is trusted, not sandboxed; plugins cannot disable Core policy. SECURITY §§92–98, 106–123. | +| Audit/retention | Redact logs/errors; required security actions get append-only audit records. Bound and document retention without silently deleting audit history. SECURITY §§110–116, 139–149. | + +CORS is not authentication, CAPTCHA is not authorization, and a cache hit is not a permission check. Provider failure cannot mean successful security verification. Do not claim uploads were scanned without a scanner or full PQ authentication from hosting alone. + +## Review and decision routing + +- Apply focused security review to authentication/authorization, crypto/password/token storage, sanitization, CSP/CORS, uploads, plugin runtime, outbound fetch, SSO/CAPTCHA, and KMS changes (SECURITY §154). Ordinary feature work does not automatically require a separate exhaustive repository audit. +- Write a security ADR for a new auth flow, persistent browser credential, cipher/password algorithm/key provider, plugin execution model, weaker CSP, raw HTML capability, cross-origin trust, or public-key signature algorithm (SECURITY §155). +- Deviations from SECURITY MUST/MUST NOT require both an ADR and security review (§2). Resolve uncertainty explicitly before embedding a weaker behavior. +- Review hot queries/indexes, list/search/pagination, bulk/cache/fan-out, plugin hooks, uploads/import/export, auth cost, and large dependencies for performance (PERFORMANCE §75). +- Record an ADR for pagination/cache/search/replication/denormalization architecture, sync-to-async shifts, coordination objects, changed queue delivery semantics, or a large persistent frontend dependency (PERFORMANCE §76); core framework/database/service/browser-baseline changes also follow ARCHITECTURE §49. +- Record review evidence and rationale in the owning module's progress entry or linked decision file. A review requirement is not automatically a new user-approval requirement for routine authorized implementation. + +Use [testing](testing.md) for adversarial acceptance evidence and the maintenance [deployment reference](../../hyperbug-maintenance/references/deployment.md) for operational key/incident work. + diff --git a/.agents/skills/hyperbug-development/references/session-handoffs.md b/.agents/skills/hyperbug-development/references/session-handoffs.md new file mode 100644 index 0000000..ed2f050 --- /dev/null +++ b/.agents/skills/hyperbug-development/references/session-handoffs.md @@ -0,0 +1,27 @@ +# Session handoffs + +This is the shared session reference for both project skills. The canonical checklist, status definitions, and entry template are in [EXECUTION](../../../../docs/plan/EXECUTION.md); read it instead of creating a competing log format. + +## Start + +Read [master progress](../../../../docs/plan/PROGRESS.md), the owning [module plan](../../../../docs/plan/README.md#module-index), its same-named file under `docs/plan/progress/`, and affected prerequisite records. Inspect actual files/versions/uncommitted changes. Record the intended stable checklist IDs and verify gates before dependent work. + +For maintenance, use the module that owns the changed artifact: foundation/dependencies 01, persistence 02, security 03–04, content 07, async 09, deployment/recovery 13, or the relevant feature/integration module. A multi-module change updates every affected record. Use [COVERAGE](../../../../docs/plan/COVERAGE.md) for ownership; do not execute unrelated future modules just to obtain a log owner. + +## Checkpoint + +Update the current status and append or update the current session entry after a meaningful batch, a decision/failure/blocker, or before handing off context. Record partial completion honestly and leave unfinished checkboxes unchecked. Preserve earlier session history. + +## Finish every session + +Append a concise English entry with the [required template](../../../../docs/plan/EXECUTION.md#required-session-entry-template): + +- Scope/checklist IDs, actual progress, and a summary of what changed. +- Changed paths/artifacts and commands/checks with environments, results, and evidence; state explicitly when a check was not run. +- Decisions/deviations and blockers with concrete resolution steps. +- Ordered next actions and next-session cautions: unfinished migrations, version uncertainty, uncommitted work, missing environment access, or invariants that must not be lost. + +This applies even to planning, investigation, review, failed attempts, and no-code work. A session that only answers a user question and changes no repository state is exempt unless the user asks for a record. Mark plan items complete only when their stated outcome and verification are complete. Update master/gate status when it changes; an initialized log or proposed procedure is not implementation evidence. + +Never put secrets, private payloads, live credentials, or signed capabilities into handoffs. Link long reports instead of copying them. Keep records usable without chat history; do not claim commits, tests, deployments, or compatibility that did not happen. + diff --git a/.agents/skills/hyperbug-development/references/testing.md b/.agents/skills/hyperbug-development/references/testing.md new file mode 100644 index 0000000..b5fbc6b --- /dev/null +++ b/.agents/skills/hyperbug-development/references/testing.md @@ -0,0 +1,29 @@ +# Testing and acceptance evidence + +Read when choosing checks or deciding whether a checklist/gate is complete. Module-specific acceptance cases remain authoritative; use [COVERAGE](../../../../docs/plan/COVERAGE.md) to find integration owners. + +## Choose checks from the changed behavior + +| Change | Meaningful evidence | +| --- | --- | +| Domain rule/API | Unit and HTTP/contract cases for valid, invalid, forbidden, missing, and conflicting operations; public DTO/OpenAPI compatibility. | +| Persistence | Shared repository suite on D1/workerd and PostgreSQL, fresh/upgrade migrations, rollback/conditional-write behavior, concurrent operations, and stable pagination. | +| Credentials/trust/content | Relevant security regressions: permission loss/BOLA, PKCE/state/replay, expiry/revocation, key rotation/tamper, CORS/CSRF, sanitizer corpus, upload/SSRF boundaries. | +| Queue/workflow/plugin | Duplicate/out-of-order/invalid messages, crash after a side effect, retry/DLQ/lease recovery, timeouts, enable/disable/version mismatch, and bounded fan-out. | +| Blob adapter | Declared PUT/GET/HEAD/DELETE/presign/multipart/abort/metadata/streaming behavior on the actual claimed provider/version. | +| Browser flow | E2E against both profiles, cross-site auth with third-party cookies blocked, keyboard/focus/screen-reader/touch/zoom checks, cache isolation, CSP and relevant failure states. | +| Performance | Representative fixtures with auth/security active; query plans/counts/rows, latency/error rate/CPU/memory where measurable, queue lag, and bundle/CWV regression. | +| Guidance/docs only | Metadata, relative links, reachable references, actual workflow walkthroughs, and checklist/status consistency. Application tests are unnecessary when behavior did not change. | + +Run existing relevant checks first. Inspect actual package scripts/tool configuration before invoking a command; do not fabricate a planned script. Add tests for new invariants and meaningful failure modes, not assertions that merely restate implementation. + +## Report what the evidence proves + +Record the command/check, software versions, fixture, runtime/provider, result, and evidence location. Separate passed, failed, not run, mock, emulator, real local service, and staging results. A mock proves neither live S3 compatibility nor Workers behavior. Source research proves neither installation nor runtime support. + +Do not substitute a narrow test for a gate requiring both full deployment profiles. Module 10 opens G1 only after its defined backend matrix; module 13 owns MVP deployment/recovery acceptance. If required access is unavailable, keep the affected gate incomplete and name the missing check. + +Benchmark realistic data with bounded authorized loads. Establish regression thresholds from measured baselines; do not invent SLA promises or hide regressions by raising thresholds indefinitely. Security parameters, authorization, and accessibility stay active. + +Use [session handoffs](session-handoffs.md) for results, unresolved failures, and next steps. + diff --git a/.agents/skills/hyperbug-maintenance/SKILL.md b/.agents/skills/hyperbug-maintenance/SKILL.md new file mode 100644 index 0000000..78457b1 --- /dev/null +++ b/.agents/skills/hyperbug-maintenance/SKILL.md @@ -0,0 +1,36 @@ +--- +name: hyperbug-maintenance +description: "Maintain HyperBug dependencies, database migrations, deployment and release procedures, secrets, backups, and incident recovery. Use for repository upkeep and operational changes; use hyperbug-development for new product behavior or feature implementation." +--- + +# HyperBug Maintenance + +Make the requested maintenance change incrementally, preserving the documented product behavior and both supported deployment profiles. Do not treat this skill as permission to publish, delete production data, rotate live credentials, or contact external parties. + +## Establish the change boundary + +Read [root guidance](../../../AGENTS.md), [master progress](../../../docs/plan/PROGRESS.md), the owning module's plan/progress, and [session handoffs](../hyperbug-development/references/session-handoffs.md). Inspect the actual versions, scripts, deployment state, and uncommitted work before choosing commands. + +Define the affected artifact, behavior/data that must survive, verification environment, and recovery path. Keep a dependency update or operational repair separate from unrelated feature expansion. If the task crosses into product behavior, also use [development guidance](../hyperbug-development/SKILL.md). + +## Select the maintenance procedure + +| Work | Read | +| --- | --- | +| Package/toolchain upgrades or compatibility drift | [Dependency updates](references/dependencies.md) | +| Schema changes, migration tooling, backfills, or data repair | [Database changes](references/database-migrations.md) | +| Deployments, releases, rollback, backup/restore, key rotation, or incident recovery | [Deployment and recovery](references/deployment.md) | +| Sensitive changes or deciding whether review/ADR is required | [Shared security and review boundaries](../hyperbug-development/references/security.md) | +| Verification and support claims | [Shared testing and evidence](../hyperbug-development/references/testing.md) | + +The shared references are intentionally owned by the adjacent development skill; keep the two repository skills together. Authoritative policy remains in [SOURCES](../../../docs/plan/SOURCES.md) and its linked baselines. + +## Execute incrementally + +1. Record the selected checklist IDs and reproduce the problem or establish the current compatibility/recovery baseline. +2. Prepare the smallest coherent update, including affected migrations/configuration/docs. Verify exact dependency resolutions and current provider/CLI behavior through root documentation rules. +3. Exercise the relevant runtime, migration, security, performance, and recovery checks before any authorized rollout. Distinguish local fixtures from live compatibility evidence. +4. For retrying mutations, inspect current external state after an ambiguous result before retrying. Stop repeating a failing rollout at its documented failure threshold; recover or leave a concrete blocker instead of broadening privileges or deleting data to force success. +5. Refresh actual commands, supported-version records, and operator guidance. Log the outcome and next-session cautions in each affected progress record, and change master/gate status only when supported by evidence. + +Prepare a concrete reviewable artifact before asking for any genuinely missing authorization. Routine reversible work already within scope does not require an extra approval ritual. Never report a prepared release as published or a proposed recovery procedure as exercised. diff --git a/.agents/skills/hyperbug-maintenance/agents/openai.yaml b/.agents/skills/hyperbug-maintenance/agents/openai.yaml new file mode 100644 index 0000000..e6a1979 --- /dev/null +++ b/.agents/skills/hyperbug-maintenance/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "HyperBug Maintenance" + short_description: "Maintain HyperBug dependencies, data, and releases" + default_prompt: "Use $hyperbug-maintenance to perform the requested HyperBug maintenance change, verify its impact, and update progress." diff --git a/.agents/skills/hyperbug-maintenance/references/database-migrations.md b/.agents/skills/hyperbug-maintenance/references/database-migrations.md new file mode 100644 index 0000000..5aa35cf --- /dev/null +++ b/.agents/skills/hyperbug-maintenance/references/database-migrations.md @@ -0,0 +1,30 @@ +# Database migrations and repair + +Read for schema, index, repository, backfill, migration-tool, or data-repair changes. Locate TECH-STACK §§9–13, 48, 54 and PERFORMANCE §§7–19, 54–57 through [SOURCES](../../../../docs/plan/SOURCES.md). Read the actual DATA-MODEL when it exists; it is a planned artifact until module 02 creates it. + +## Define the data invariant first + +State the business invariant, old/new representation, compatibility window, data/retention impact, and transaction intent. Public IDs, project Issue numbers, actor identity, timestamps, uniqueness, and event/audit/outbox semantics must remain explicit. + +Keep separate D1/SQLite and PostgreSQL schemas/migration histories. Share repository behavior rather than SQL text or a presumed universal Drizzle transaction API. Check current driver/runtime documentation before choosing transaction operations. + +D1 batches and PostgreSQL interactive transactions have different capabilities. Prove atomic business outcomes, including conditional zero-row/conflict cases, instead of assuming every failed precondition throws and rolls back. Do not perform read-check-write integrity enforcement without addressing concurrency. + +## Prepare and inspect + +Generate using installed reviewed tooling, then inspect actual SQL: destructive changes, renames, defaults/nullability, foreign keys, uniqueness, indexes/FTS, conversion/backfill cost, and table locking/rebuild behavior. + +For deployed data, choose an explicit expand/backfill/contract or justified alternative, with bounded resumable batches, checkpoints, concurrency control, and old/new application compatibility. Estimate work from representative data. Do not rewrite migrations already applied to shared environments. + +Keep migration credentials scoped and separate from normal application capabilities where practical. External plugins do not gain arbitrary Core SQL; trusted plugin migrations need namespaces and review. + +## Verify before an authorized rollout + +Run empty-database and prior-schema upgrade cases on both adapters, shared repository contracts, concurrency/idempotency/cursor checks, and relevant query plans/counts/rows. Restore a representative backup when validating an operational migration/recovery claim. + +Define failure detection, stop/retry conditions, and recovery before mutation. Application rollback does not undo an irreversible schema change. Document a safe forward fix or coordinated restore when reversal would lose data; retain the key versions required to read restored encrypted records. + +For production repair, identify the exact environment and selected records, prepare a dry-run/result preview where possible, and use only current session authorization. Do not repeat ambiguous mutations without inspecting actual state. + +Update model/API/operator documentation and the owning module progress records with migration IDs, tested starting/ending versions, evidence, remaining backfill work, and next-session cautions. + diff --git a/.agents/skills/hyperbug-maintenance/references/dependencies.md b/.agents/skills/hyperbug-maintenance/references/dependencies.md new file mode 100644 index 0000000..28d6a1a --- /dev/null +++ b/.agents/skills/hyperbug-maintenance/references/dependencies.md @@ -0,0 +1,26 @@ +# Dependency updates + +Read for toolchain, framework, ORM, driver, build/test, or provider SDK updates. Source policy: TECH-STACK §§2, 8, 12, 31–40, 52–53 and SECURITY §§124–128 through [SOURCES](../../../../docs/plan/SOURCES.md). + +## Establish the actual update + +Inspect manifests, the lockfile, package scripts, runtime configuration, and dependency callers. If the workspace has not been scaffolded, module 01 version verification is the next action; do not fabricate an upgrade from a version that was never installed. + +Fetch current documentation through root Context7 rules, including migration notes and exact package/export names. Verify package availability in official sources/registries. Record old/new exact resolutions, dependency purpose, compatibility constraints, and the update rationale. + +Preserve declared major policies: Node 24, PostgreSQL 18.x, TypeScript 7, pnpm 11, and React 19; Vite/Vitest follow reviewed latest stable updates. These are project choices, not assertions that dated source patch versions remain current. Unavailable or incompatible required versions need an explicit blocker/decision rather than a silent downgrade. + +## Review risk and apply a coherent change + +Consider maintenance/security history, transitive dependencies, license, install scripts, ESM/type quality, runtime compatibility, native/WASM code, and browser bundle impact. + +Prereleases are allowed when justified: tooling/framework/ORM risk differs from drivers, auth, sanitizers, crypto, and persistent storage. Follow the source policy; do not interpret allowed as preferred. Keep crypto mature/audited and sanitizer stable by default. Review ORM/migration-tool upgrades together and inspect generated migration changes. + +Use the repository's package manager and a single lockfile. Record exact resolutions; CI/release installation is frozen, not a floating latest/rc lookup. Retain the approved lifecycle-script controls. Do not bundle unrelated major upgrades into an incident fix. + +## Validate and record + +Use the actual targeted commands from the workspace: type/build/test/contract/runtime checks plus the affected [test matrix](../../hyperbug-development/references/testing.md). Elysia changes need routing/validation/OpenAPI/encapsulation and Workers/Node verification; database changes also use [migration guidance](database-migrations.md). + +Inspect API/schema drift, bundle/query/performance changes, and review-triggered decisions. Keep an experimental next-version lane distinct from required production checks. Document the accepted resolution and recovery path, update commands/runbooks when needed, and leave a [session handoff](../../hyperbug-development/references/session-handoffs.md). + diff --git a/.agents/skills/hyperbug-maintenance/references/deployment.md b/.agents/skills/hyperbug-maintenance/references/deployment.md new file mode 100644 index 0000000..3e1be41 --- /dev/null +++ b/.agents/skills/hyperbug-maintenance/references/deployment.md @@ -0,0 +1,36 @@ +# Deployment, release, and recovery + +Read for packaging, rollout, rollback, backup/restore, secret rotation, and incidents. Module [13](../../../../docs/plan/modules/13-mvp-release-and-operations.md) owns release acceptance. Existing authorization determines whether this task prepares artifacts, uses staging, or changes production. + +## Prepare the concrete operation + +Identify environment, current/target version, artifacts, migrations, configuration, credentials source, expected checks, and stop/recovery criteria. Inspect live state when the task concerns a running deployment. Refresh provider/CLI documentation through root rules; do not turn a planned runbook command into an assumed installed tool. + +Support both official profiles: Cloudflare-native and Node/PostgreSQL/S3 with Graphile Worker. Frontend and backend releases are independent. Keep runtime config public, static SPA fallbacks/cache rules valid, and CSP/CORS aligned with exact frontend/API/auth/media origins. Preview defaults to staging rather than wildcard access to production. + +Only list a provider/version as tested when its compatibility suite has actually run. Workers + PostgreSQL/Hyperdrive and generic S3-compatible branding do not establish support by themselves. + +## Release and rollback + +Build from reviewed exact dependencies/frozen lockfile; retain artifact hashes and reproducible metadata, with provenance/signing where supported. Run relevant [acceptance checks](../../hyperbug-development/references/testing.md), migration/upgrade evidence, configuration validation, and secret/license/dependency checks. + +Sequence database compatibility, backend/worker deployment, then independently configured frontend as the specific release requires. Define smoke checks and thresholds before rollout. On failure, stop the rollout and apply its recovery path; inspect ambiguous deployment state before retrying. + +Roll back application artifacts only when compatible with the current schema. Use the [migration procedure](database-migrations.md) for forward fixes or coordinated restores. Do not claim publication from a prepared artifact, nor successful recovery from an unexercised runbook. + +## Backup and restore + +Back up database records, referenced blobs, non-secret configuration, and access to required encryption-key versions through appropriate secret management. Define a consistency point and retention policy; do not expose keys in ordinary backups/logs. + +Rehearse restoration in an isolated authorized environment. Verify schema/application versions, counts and relationships, attachment readability, encrypted data, outbox/jobs, and search rebuild. Avoid replaying notifications/webhooks to real recipients during a restore drill. Record measured recovery duration/data loss rather than promising unmeasured recovery objectives. + +## Secrets and incidents + +For planned rotation, inventory key consumers and stored key IDs, introduce the new version, retain current/previous overlap as policy permits, migrate or rewrap retained data, and verify reads/writes before retirement. Include HMAC/token/blind-index/signing keys where affected. Never retire a key still needed by retained data or recoverable backups. + +For confirmed compromise, follow explicit emergency revocation and containment; planned overlap must not keep a compromised credential trusted. Record affected scope and recovery evidence without logging secrets. Preserve relevant diagnostic/audit evidence under the retention policy. + +During an outage, distinguish critical verification failures from non-critical provider effects. Keep authentication/authorization fail closed; recover queued effects with bounded retries, idempotency, and audited replay. Inspect DLQ growth, queue lag, expired leases, search drift, and attachment cleanup as relevant. + +Update the maintenance reference/runbook only with verified commands and lessons, then complete the shared [session handoff](../../hyperbug-development/references/session-handoffs.md). Prepare reviewable output before seeking any actually missing authorization; a skill does not grant production access or permission to message others. + diff --git a/.claude/skills b/.claude/skills new file mode 120000 index 0000000..2b7a412 --- /dev/null +++ b/.claude/skills @@ -0,0 +1 @@ +../.agents/skills \ No newline at end of file diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..78336fc --- /dev/null +++ b/.env.example @@ -0,0 +1,6 @@ +HYPERBUG_ENV=local +ALLOWED_ORIGINS=http://localhost:5173 +MAX_BODY_BYTES=65536 +REQUEST_TIMEOUT_MS=10000 +HOST=127.0.0.1 +PORT=3000 diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..77bcd9e --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,16 @@ +version: 2 +updates: + - package-ecosystem: npm + directory: / + schedule: + interval: weekly + open-pull-requests-limit: 5 + ignore: + - dependency-name: pnpm + update-types: [version-update:semver-major] + - dependency-name: typescript + update-types: [version-update:semver-major] + - package-ecosystem: github-actions + directory: / + schedule: + interval: weekly diff --git a/.github/workflows/backend.yml b/.github/workflows/backend.yml new file mode 100644 index 0000000..bb9e71f --- /dev/null +++ b/.github/workflows/backend.yml @@ -0,0 +1,70 @@ +name: Backend Tests +on: + push: + pull_request: +permissions: + contents: read +jobs: + quality: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - uses: actions/setup-node@v7 + with: + node-version: 24 + - run: corepack enable + - run: pnpm install --frozen-lockfile + - run: pnpm db:check + - run: pnpm typecheck + - run: pnpm lint + - run: pnpm format:check + - run: pnpm test:unit + - run: pnpm test:contract + - run: pnpm scan:secrets + - run: pnpm scan:licenses + - run: pnpm audit --audit-level high + - run: pnpm build + runtime: + strategy: + fail-fast: false + matrix: + profile: [node, workerd] + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - uses: actions/setup-node@v7 + with: + node-version: 24 + - run: corepack enable + - run: pnpm install --frozen-lockfile + - run: pnpm test:${{ matrix.profile }} + + postgres: + runs-on: ubuntu-latest + services: + database: + image: postgres:18.6 + env: + POSTGRES_HOST_AUTH_METHOD: trust + POSTGRES_DB: hyperbug_test + ports: + - 5432:5432 + options: >- + --health-cmd "pg_isready -U postgres -d hyperbug_test" + --health-interval 5s + --health-timeout 5s + --health-retries 10 + env: + PGHOST: 127.0.0.1 + PGPORT: 5432 + PGUSER: postgres + PGDATABASE: hyperbug_test + HYPERBUG_TEST_POSTGRES: '1' + steps: + - uses: actions/checkout@v7 + - uses: actions/setup-node@v7 + with: + node-version: 24 + - run: corepack enable + - run: pnpm install --frozen-lockfile + - run: pnpm exec vitest run --project postgres diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml new file mode 100644 index 0000000..83f7995 --- /dev/null +++ b/.github/workflows/codeql.yml @@ -0,0 +1,109 @@ +# For most projects, this workflow file will not need changing; you simply need +# to commit it to your repository. +# +# You may wish to alter this file to override the set of languages analyzed, +# or to provide custom queries or build logic. +# +# ******** NOTE ******** +# We have attempted to detect the languages in your repository. Please check +# the `language` matrix defined below to confirm you have the correct set of +# supported CodeQL languages. +# +name: 'CodeQL' + +on: + push: + branches: ['main'] + # Scan every pull request targeting main. These are the default activity + # types, listed explicitly so that PR submission and later head-branch + # updates are auditable here: `opened` covers submission, `synchronize` + # covers new commits pushed to the PR, and `reopened` covers a PR brought + # back after being closed. A PR with a merge conflict does not trigger + # the workflow until the conflict is resolved. + pull_request: + branches: ['main'] + types: [opened, synchronize, reopened] + # No `schedule` trigger by choice: analysis runs only when a commit + # arrives. CodeQL ships new and updated queries over time, so a dormant + # branch or a newly disclosed vulnerability class will not surface until + # the next push or pull request. Re-add a cron here to restore periodic + # scanning. + +jobs: + analyze: + name: Analyze (${{ matrix.language }}) + # Runner size impacts CodeQL analysis time. To learn more, please see: + # - https://gh.io/recommended-hardware-resources-for-running-codeql + # - https://gh.io/supported-runners-and-hardware-resources + # - https://gh.io/using-larger-runners (GitHub.com only) + # Consider using larger runners or machines with greater resources for possible analysis time improvements. + runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }} + permissions: + # required for all workflows + security-events: write + + # required to fetch internal or private CodeQL packs + packages: read + + # only required for workflows in private repositories + actions: read + contents: read + + strategy: + fail-fast: false + matrix: + include: + # CodeQL supports the following values keywords for 'language': 'actions', 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'rust', 'swift' + # Use `c-cpp` to analyze code written in C, C++ or both + # Use 'java-kotlin' to analyze code written in Java, Kotlin or both + # Use 'javascript-typescript' to analyze code written in JavaScript, TypeScript or both + # To learn more about changing the languages that are analyzed or customizing the build mode for your analysis, + # see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning. + # If you are analyzing a compiled language, you can modify the 'build-mode' for that language to customize how + # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages + - language: javascript-typescript + build-mode: none + steps: + - name: Checkout repository + uses: actions/checkout@v7 + + # Add any setup steps before running the `github/codeql-action/init` action. + # This includes steps like installing compilers or runtimes (`actions/setup-node` + # or others). This is typically only required for manual builds. + # - name: Setup runtime (example) + # uses: actions/setup-example@v1 + + # Initializes the CodeQL tools for scanning. + - name: Initialize CodeQL + uses: github/codeql-action/init@v4 + with: + languages: ${{ matrix.language }} + build-mode: ${{ matrix.build-mode }} + # If you wish to specify custom queries, you can do so here or in a config file. + # By default, queries listed here will override any specified in a config file. + # Prefix the list here with "+" to use these queries and those in the config file. + + # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs + # queries: security-extended,security-and-quality + + # If the analyze step fails for one of the languages you are analyzing with + # "We were unable to automatically build your code", modify the matrix above + # to set the build mode to "manual" for that language. Then modify this step + # to build your code. + # ℹ️ Command-line programs to run using the OS shell. + # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun + - name: Run manual build steps + if: matrix.build-mode == 'manual' + shell: bash + run: | + echo 'If you are using a "manual" build mode for one or more of the' \ + 'languages you are analyzing, replace this with the commands to build' \ + 'your code, for example:' + echo ' make bootstrap' + echo ' make release' + exit 1 + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v4 + with: + category: '/language:${{matrix.language}}' diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..1722db8 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,61 @@ +name: Documentation + +on: + push: + branches: [main] + paths: + - 'docs/**' + - 'package.json' + - 'pnpm-lock.yaml' + - 'pnpm-workspace.yaml' + - '.github/workflows/docs.yml' + pull_request: + paths: + - 'docs/**' + - 'package.json' + - 'pnpm-lock.yaml' + - 'pnpm-workspace.yaml' + - '.github/workflows/docs.yml' + workflow_dispatch: + +permissions: + contents: read + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - uses: actions/setup-node@v7 + with: + node-version: 24 + - run: corepack enable + - run: pnpm install --frozen-lockfile + - name: Build documentation + env: + DOCS_BASE: /${{ github.event.repository.name }}/ + run: pnpm docs:build + - name: Upload Pages artifact + if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main' + uses: actions/upload-pages-artifact@v5 + with: + path: docs/.vitepress/dist + + deploy: + if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main' + needs: build + runs-on: ubuntu-latest + permissions: + pages: write + id-token: write + concurrency: + group: github-pages + cancel-in-progress: false + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - uses: actions/configure-pages@v6 + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v5 diff --git a/.gitignore b/.gitignore index 872d5f6..789c52a 100644 --- a/.gitignore +++ b/.gitignore @@ -141,3 +141,25 @@ dist vite.config.js.timestamp-* vite.config.ts.timestamp-* .vite/ + +# Vim files +*.swp +*.swo +*~ +*.un~ + +# Local temporary files +tmp/ + +# macOS system +.DS_Store +_MACOSX + +# Windows system +desktop.ini + +# HyperBug local runtime state +.wrangler/ +.dev.vars +.dev.vars.* +.local/ diff --git a/.node-version b/.node-version new file mode 100644 index 0000000..a45fd52 --- /dev/null +++ b/.node-version @@ -0,0 +1 @@ +24 diff --git a/.oxfmtrc.json b/.oxfmtrc.json new file mode 100644 index 0000000..51a64cc --- /dev/null +++ b/.oxfmtrc.json @@ -0,0 +1,21 @@ +{ + "$schema": "./node_modules/oxfmt/configuration_schema.json", + "printWidth": 80, + "proseWrap": "preserve", + "singleQuote": true, + "trailingComma": "all", + "indentStyle": "space", + "indentWidth": 2, + "sortPackageJson": false, + "sortImports": false, + "ignorePatterns": [ + "node_modules/**", + "dist/**", + "pnpm-lock.yaml", + "docs/**", + ".local/**", + ".agents/**", + "**/migrations/**", + "**/worker-configuration.d.ts" + ] +} diff --git a/.oxlintrc.json b/.oxlintrc.json new file mode 100644 index 0000000..c234f94 --- /dev/null +++ b/.oxlintrc.json @@ -0,0 +1,301 @@ +{ + "$schema": "./node_modules/oxlint/configuration_schema.json", + "plugins": ["import"], + "categories": { + "correctness": "error", + "suspicious": "warn", + "perf": "warn" + }, + "rules": { + "import/extensions": [ + "error", + "ignorePackages", + { + "ts": "always", + "tsx": "always", + "js": "always" + } + ], + "no-await-in-loop": "warn" + }, + "overrides": [ + { + "files": ["packages/domain/**/*.ts"], + "rules": { + "no-restricted-imports": [ + "error", + { + "patterns": [ + { + "group": ["*", "!./**", "../**"], + "message": "packages/domain is a leaf package: no imports outside itself and no external dependencies." + } + ] + } + ] + } + }, + { + "files": ["packages/contracts/**/*.ts"], + "rules": { + "no-restricted-imports": [ + "error", + { + "patterns": [ + { + "group": ["*", "!./**", "../**", "!@sinclair/typebox"], + "message": "packages/contracts may depend only on @sinclair/typebox, so a client can read the contract without Elysia." + } + ] + } + ] + } + }, + { + "files": ["packages/security/**/*.ts"], + "rules": { + "no-restricted-imports": [ + "error", + { + "patterns": [ + { + "group": [ + "*", + "!./**", + "../**", + "!unified", + "!remark-parse", + "!remark-gfm", + "!remark-rehype", + "!rehype-raw", + "!rehype-sanitize", + "!hast-util-to-html", + "!hast", + "!yaml" + ], + "message": "packages/security may import only reviewed platform-neutral content libraries; no infrastructure dependencies." + } + ] + } + ] + } + }, + { + "files": ["packages/config/**/*.ts"], + "rules": { + "no-restricted-imports": [ + "error", + { + "patterns": [ + { + "group": ["*", "!./**", "../**"], + "message": "packages/config is a leaf package: no imports outside itself and no external dependencies." + } + ] + } + ] + } + }, + { + "files": ["packages/plugin-api/**/*.ts"], + "rules": { + "no-restricted-imports": [ + "error", + { + "patterns": [ + { + "group": [ + "*", + "!./**", + "../**", + "!@sinclair/typebox", + "!@sinclair/typebox/**" + ], + "message": "packages/plugin-api is the public contract: only @sinclair/typebox may be imported, so one contract serves both profiles." + } + ] + } + ] + } + }, + { + "files": ["packages/plugin-sdk/**/*.ts"], + "rules": { + "no-restricted-imports": [ + "error", + { + "patterns": [ + { + "group": ["*", "!./**", "../**", "!@hyperbug/plugin-api"], + "message": "packages/plugin-sdk may import only @hyperbug/plugin-api; the SDK re-exports the contract without host dependencies." + } + ] + } + ] + } + }, + { + "files": ["packages/plugin-runtime/**/*.ts"], + "rules": { + "no-restricted-imports": [ + "error", + { + "patterns": [ + { + "group": ["*", "!./**", "../**", "!@hyperbug/plugin-api"], + "message": "packages/plugin-runtime currently may import only @hyperbug/plugin-api; Core integration dependencies arrive with module 05.2." + } + ] + } + ] + } + }, + { + "files": ["packages/observability/**/*.ts"], + "rules": { + "no-restricted-imports": [ + "error", + { + "patterns": [ + { + "group": ["*", "!./**", "../**"], + "message": "packages/observability is a leaf package: no imports outside itself and no external dependencies." + } + ] + } + ] + } + }, + { + "files": ["packages/application/**/*.ts"], + "rules": { + "no-restricted-imports": [ + "error", + { + "patterns": [ + { + "group": [ + "*", + "!./**", + "../**", + "!@hyperbug/domain", + "!@hyperbug/contracts", + "!@hyperbug/plugin-api" + ], + "message": "packages/application may import only @hyperbug/domain, @hyperbug/contracts and @hyperbug/plugin-api." + } + ] + } + ] + } + }, + { + "files": ["packages/testing/**/*.ts"], + "rules": { + "no-restricted-imports": [ + "error", + { + "patterns": [ + { + "group": [ + "*", + "!./**", + "../**", + "!@hyperbug/contracts", + "!@hyperbug/domain", + "!@hyperbug/application" + ], + "message": "packages/testing may import only @hyperbug/contracts, @hyperbug/domain and @hyperbug/application." + } + ] + } + ] + } + }, + { + "files": [ + "packages/database/d1/**/*.ts", + "packages/database/postgres/**/*.ts" + ], + "rules": { + "no-restricted-imports": [ + "error", + { + "patterns": [ + { + "group": [ + "*", + "!./**", + "../**", + "!@hyperbug/domain", + "!@hyperbug/application", + "!@hyperbug/security", + "!@hyperbug/plugin-api", + "!drizzle-orm", + "!drizzle-orm/**", + "!drizzle-kit", + "!pg", + "!@cloudflare/workers-types", + "!@hyperbug/security/**" + ], + "message": "database adapters may import only @hyperbug/domain, @hyperbug/application, @hyperbug/security, @hyperbug/plugin-api and their own persistence libraries; persistence types stay out of the domain." + } + ] + } + ] + } + }, + { + "files": ["packages/server/**/*.ts"], + "rules": { + "no-restricted-imports": [ + "error", + { + "patterns": [ + { + "group": [ + "*", + "!./**", + "../**", + "!@hyperbug/application", + "!@hyperbug/domain", + "!@hyperbug/contracts", + "!@hyperbug/security", + "!@hyperbug/config", + "!@hyperbug/observability", + "!elysia", + "!elysia/**", + "!@simplewebauthn/server", + "!@simplewebauthn/server/**", + "!@hyperbug/plugin-api", + "!@hyperbug/security/**" + ], + "message": "packages/server may import only the shared server-side packages, Elysia and the pinned WebAuthn verifier and @hyperbug/plugin-api." + } + ] + } + ] + } + }, + { + "files": [ + "tests/**/*.ts", + "tooling/**/*.ts", + "tooling/**/*.mjs", + "packages/database/**/migrations/**/*.ts" + ], + "rules": { + "no-await-in-loop": "off" + } + }, + { + "files": ["apps/web/**/*.ts", "apps/web/**/*.tsx"], + "plugins": ["react", "jsx-a11y"], + "rules": { + "react/rules-of-hooks": "error", + "react/exhaustive-deps": "error", + "react/react-in-jsx-scope": "off" + } + } + ] +} diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..512a318 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,3 @@ +{ + "markdown.validate.enabled": true +} diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..9b57c0f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,53 @@ +# HyperBug repository guidance + +HyperBug is a public-first issue tracker with a static frontend and two first-class backend profiles. Start from the current repository state and the requested task scope. + +## Project skills + +- [hyperbug-development](.agents/skills/hyperbug-development/SKILL.md): use for product features, backend/API/adapter changes, and frontend workflows. +- [hyperbug-maintenance](.agents/skills/hyperbug-maintenance/SKILL.md): use for dependency updates, database migrations, releases, deployment, and operational recovery. + +Read the applicable skill and only the references relevant to the work. For feature changes that also require migrations, combine the development workflow with the maintenance migration reference. + +## Planning and session continuity + +Read [the plan](docs/plan/README.md), [master progress](docs/plan/PROGRESS.md), the owning module's checklist, and its latest progress record before implementation. Follow [EXECUTION](docs/plan/EXECUTION.md) at session start, meaningful checkpoints, and session end. + +Every session must append a concise entry to each affected module's progress document: progress, change summary, files/artifacts, verification results, decisions/blockers, next actions, and next-session cautions. This includes investigation, failed attempts, reviews, and documentation-only sessions. Mark checklist items complete only when their actual outcomes are verified. Exception: a session that only answers a user question and changes no repository state (a read-only check, comparison, measurement, or explanation) needs no progress entry unless the user asks for one; the entry requirement still applies whenever the session implements, reviews, migrates, deploys, or otherwise changes repository state. + +Create and validate guidance skills before application implementation (G0). Backend acceptance in module 10 (G1) precedes product SPA development. Each post-MVP increment also completes backend acceptance before its UI. Follow the current plan gates; a request for one module does not authorize implementing the rest of the roadmap. + +Maintain human-facing reader documentation under `docs/site/` in both English and Simplified Chinese, with matching page paths and synchronized content. Reader-facing repository entry points may also be bilingual. Write engineering documentation and substantive updates in English, including skills, plans, progress logs, specifications, ADRs, and internal runbooks. Existing initial-architecture documents remain historical inputs unless translation is separately requested. Product localization is a separate concern. + +## Architecture and policy sources + +[SOURCES](docs/plan/SOURCES.md) links the initial specifications and records their refinements. PRODUCT owns scope; SECURITY owns minimum security policy; PERFORMANCE prioritizes correctness/security over optimization; TECH-STACK refines the older runtime/profile/version choices. + +Both Workers/D1/R2/Queues/Workflows and Node 24/PostgreSQL 18.x/S3-compatible storage/Graphile Worker are required. Share domain semantics, public contracts, application services, and Elysia routes; keep infrastructure types in adapters/composition roots. The frontend remains independently hosted and uses the public API. Plugins provide mechanisms without weakening Core policy. + +Use the skills' review and testing references for changes to security, persistent data, public contracts, or resource-intensive paths. Do not silently relax a normative baseline to accommodate a dependency or provider. Routine implementation choices do not imply a new user-approval step. + +## Current documentation lookup + + + +Use Context7 MCP whenever the task asks about a library, framework, SDK, API, CLI tool, or cloud service, including syntax, configuration, migration, library-specific debugging, setup, and CLI usage. Do this even for familiar tools. Prefer it over general web search for library documentation. + +Do not trigger this solely for refactoring, scripts from scratch, business-logic debugging, code review, or general programming concepts. If those tasks introduce an actual library/API question, look up that question. Record lookup dates, references, and remaining gaps. If the tool or coverage is unavailable, document the limitation and consult official sources or a focused runtime experiment; do not invent documentation or claim an unperformed lookup. + + +For HTML/CSS/client-side JavaScript work, use the available modern-web-guidance skill: search by the intended action, retrieve relevant guides, then check implementation against them. Record guide IDs, current compatibility status, and chosen fallbacks. Preserve Baseline Widely Available, WCAG 2.2 AA, the static SPA boundary, and memory-only browser access tokens. Treat newer capabilities as progressive enhancements under the project's policy. + +## Commands and evidence + +Use commands actually defined by the repository and installed tooling. A command proposed in a plan is not proof that it exists. Exact source version examples are snapshots; verify availability before installation. Record unavailable checks and keep dependent gates incomplete rather than replacing required evidence with mock-only results. + +## Commit messages + +Write every commit message in English using Conventional Commits: `type(scope): description`, with the scope optional and the description in the imperative mood, lower case, and without a trailing period. + +Choose the type that matches the change: `feat`, `fix`, `docs`, `test`, `ci`, `refactor`, `perf`, `build`, `chore`, or `revert`. Keep each commit to one coherent change, and use the message body to explain rationale and verification when the subject alone does not. + +Record a breaking change with `!` after the type or scope and a `BREAKING CHANGE:` footer. Reference an issue in the footer as `Refs: #123`. + +No commit-msg hook enforces this convention yet, so it depends on author discipline during review. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e69de29 diff --git a/PRIVACY.md b/PRIVACY.md new file mode 100644 index 0000000..e69de29 diff --git a/PRIVACY_zh-CN.md b/PRIVACY_zh-CN.md new file mode 100644 index 0000000..e69de29 diff --git a/README.md b/README.md new file mode 100644 index 0000000..0fbda41 --- /dev/null +++ b/README.md @@ -0,0 +1,88 @@ +**English** | [**简体中文**](README_zh-CN.md) + +# HyperBug + +[![License: Apache 2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg?style=flat-square&label=License)](LICENSE) +[![Version](https://img.shields.io/github/v/release/EIHRTeam/HyperBug?style=flat-square&label=Version&color=blue)](https://github.com/EIHRTeam/HyperBug/releases/latest)
+[![CodeQL](https://github.com/EIHRTeam/HyperBug/actions/workflows/codeql.yml/badge.svg)](https://github.com/EIHRTeam/HyperBug/actions/workflows/codeql.yml) +[![Backend Tests](https://github.com/EIHRTeam/HyperBug/actions/workflows/backend.yml/badge.svg)](https://github.com/EIHRTeam/HyperBug/actions/workflows/backend.yml) +
+[![TypeScript 7](https://img.shields.io/badge/TypeScript-7-blue.svg?logo=typescript&style=flat-square&logoColor=white)](https://www.typescriptlang.org/) +[![Elysia 1.4](docs/assets/Elysia-1.4-E34798.svg)](https://elysiajs.com/) +[![Node.js 24](https://img.shields.io/badge/Node.js-24-339933.svg?style=flat-square&logo=node.js&logoColor=white)](.node-version) +[![Cloudflare Workers](https://img.shields.io/badge/Cloudflare-Workers-yellow.svg?style=flat-square&logo=cloudflare&logoColor=white)](https://workers.cloudflare.com/) +[![PostgreSQL 18](https://img.shields.io/badge/PostgreSQL-18-blue.svg?style=flat-square&logo=postgresql&logoColor=white)](https://www.postgresql.org/) + +> [!IMPORTANT] +> This project is still in early development stage and may contain major defects or breaking changes. DO NOT use in production. + +A modern, lightweight, cloud-native, serverless-first, GitHub Issues-style issue-tracking platform. + +## Documentation + +Read the [English documentation](docs/site/index.md) or [简体中文文档](docs/site/zh-CN/index.md). The guides are still outlines. The [VitePress site workflow](docs/development/DOCUMENTATION.md) covers local preview and GitHub Pages deployment. For the current backend workspace, see [backend development](docs/development/README.md). + +## Highlights + +## Quick Start + +### Deployment + +#### Backend + +| Profile | Runtime | Database | Object storage | Queue and workflow | +| --------------- | ------------------ | ------------- | -------------- | ------------------ | +| A — Cloudflare | Cloudflare Workers | D1 | R2 | Queues, Workflows | +| B — Self-hosted | Node.js 24 | PostgreSQL 18 | S3-compatible | Graphile Worker | + +#### Frontend + +### Development + +```sh +git clone git@github.com:EIHRTeam/HyperBug.git +cd HyperBug +pnpm install --frozen-lockfile +pnpm dev # Run the API and static frontend locally +pnpm test # Unit, contract, and integration tests +pnpm lint # Lint and formatting checks +pnpm typecheck # Strict type checking across the workspace +pnpm build # Build API and static frontend artifacts +``` + +Run `pnpm run` to view the complete script list, including formatting, migration, and profile-specific integration test commands. Migrations are applied through the workspace migration command for the selected profile, delegating to the D1 migration adapter or PostgreSQL migration set. All dependencies are pinned by the committed lockfile, and lifecycle install scripts are restricted by policy. + +```text +repo/ +├── apps/ +│ ├── web/ # Static SPA, independently deployed +│ ├── api-cloudflare/ # Workers entry point +│ └── api-node/ # Node 24 entry point +├── packages/ +│ ├── contracts/ # Public DTOs, REST/OpenAPI docs, generated API client +│ ├── domain/ # Entities, invariants, policies +│ ├── application/ # Use cases and application services +│ ├── server/ # Shared Elysia routes and middleware +│ ├── security/ # Cryptography, tokens, sanitization, audit, abuse controls +│ ├── database/ # Contracts plus D1 and PostgreSQL adapters +│ ├── blob/ # Contracts plus R2 and S3 adapters +│ ├── queue/ # Contracts plus Cloudflare and Graphile adapters +│ ├── workflow/, search/, plugin-api/, observability/ +└── tooling/ +``` + +See [CONTRIBUTING.md](CONTRIBUTING.md) for details. + +## Legal + +### Copyright + +Copyright © 2026 Endfield Industries Human Resource Team, licensed under the [Apache License Version 2.0](LICENSE). + +### Disclaimer + +Neither this project nor the Endfield Industries Human Resource Team (EIHRTeam) has any affiliation or relationship, financial or otherwise, with Shanghai Hypergryph Network Technology Co., Ltd., Gryph Frontier Pte. Ltd., or any of their respective affiliates or related entities. + +### Other + +#### Privacy diff --git a/README_zh-CN.md b/README_zh-CN.md new file mode 100644 index 0000000..3a8e6dd --- /dev/null +++ b/README_zh-CN.md @@ -0,0 +1,88 @@ +[**English**](README.md) | **简体中文** + +# HyperBug + +[![License: Apache 2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg?style=flat-square&label=License)](LICENSE) +[![Version](https://img.shields.io/github/v/release/EIHRTeam/HyperBug?style=flat-square&label=Version&color=blue)](https://github.com/EIHRTeam/HyperBug/releases/latest)
+[![CodeQL](https://github.com/EIHRTeam/HyperBug/actions/workflows/codeql.yml/badge.svg)](https://github.com/EIHRTeam/HyperBug/actions/workflows/codeql.yml) +[![Backend Tests](https://github.com/EIHRTeam/HyperBug/actions/workflows/backend.yml/badge.svg)](https://github.com/EIHRTeam/HyperBug/actions/workflows/backend.yml) +
+[![TypeScript 7](https://img.shields.io/badge/TypeScript-7-blue.svg?logo=typescript&style=flat-square&logoColor=white)](https://www.typescriptlang.org/) +[![Elysia 1.4](docs/assets/Elysia-1.4-E34798.svg)](https://elysiajs.com/) +[![Node.js 24](https://img.shields.io/badge/Node.js-24-339933.svg?style=flat-square&logo=node.js&logoColor=white)](.node-version) +[![Cloudflare Workers](https://img.shields.io/badge/Cloudflare-Workers-yellow.svg?style=flat-square&logo=cloudflare&logoColor=white)](https://workers.cloudflare.com/) +[![PostgreSQL 18](https://img.shields.io/badge/PostgreSQL-18-blue.svg?style=flat-square&logo=postgresql&logoColor=white)](https://www.postgresql.org/) + +> [!IMPORTANT] +> 本项目尚处早期开发阶段，可能包含重大缺陷或破坏性更改，请勿用于生产环境 + +现代化、轻量化、云原生、Serverless 优先的类 GitHub Issue 问题跟踪平台解决方案 + +## 文档 + +阅读[简体中文文档](docs/site/zh-CN/index.md)或 [English documentation](docs/site/index.md)。指南目前仍为提纲；[VitePress 站点维护说明](docs/development/DOCUMENTATION.md)介绍本地预览与 GitHub Pages 部署。现有后端工作区请参阅[后端开发指南](docs/development/README.md)。 + +## 亮点 + +## 快速开始 + +### 部署 + +#### 后端 + +| Profile | 运行时 | 数据库 | 对象存储 | 队列与工作流 | +| -------------- | ------------------ | --------------- | -------- | ----------------- | +| A — Cloudflare | Cloudflare Workers | D1 | R2 | Queues、Workflows | +| B — 自托管 | Node.js 24 | PostgreSQL 18.x | S3 兼容 | Graphile Worker | + +#### 前端 + +### 开发 + +```sh +git clone git@github.com:EIHRTeam/HyperBug.git +cd HyperBug +pnpm install --frozen-lockfile +pnpm dev # 本地运行 API 与静态前端 +pnpm test # 单元、契约与集成测试 +pnpm lint # Lint 与格式检查 +pnpm typecheck # 全工作区严格类型检查 +pnpm build # 构建 API 产物与静态前端产物 +``` + +运行 `pnpm run` 可查看完整脚本列表，其中包含格式化、迁移与按 Profile 划分的集成测试命令；迁移通过所选 Profile 对应的工作区迁移命令执行，分别委托给 D1 迁移适配器或 PostgreSQL 迁移集。所有依赖都由已提交的 lockfile 固定，生命周期安装脚本受策略限制。 + +```text +repo/ +├── apps/ +│ ├── web/ # 静态 SPA，独立部署 +│ ├── api-cloudflare/ # Workers 入口 +│ └── api-node/ # Node 24 入口 +├── packages/ +│ ├── contracts/ # 公开 DTO、REST/OpenAPI 文档、生成的 API 客户端 +│ ├── domain/ # 实体、不变量、策略 +│ ├── application/ # 用例与应用服务 +│ ├── server/ # 共享 Elysia 路由与中间件 +│ ├── security/ # 密码学、令牌、清洗、审计、滥用防护 +│ ├── database/ # contracts + d1 与 postgres 适配器 +│ ├── blob/ # contracts + r2 与 s3 适配器 +│ ├── queue/ # contracts + cloudflare 与 graphile 适配器 +│ ├── workflow/, search/, plugin-api/, observability/ +└── tooling/ +``` + +详请参见 [CONTRIBUTING.md](CONTRIBUTING.md) + +## 法律 + +### 版权 + +Copyright © 2026 Endfield Industries Human Resource Team, licensed under [Apache License, Version 2.0.](LICENSE) + +### 免责声明 + +本项目及终末地工业人事部与上海市鹰角网络科技有限公司、Gryph Frontier Pte. Ltd.，及其各自的关联实体之间没有任何组织或资金上的联系。 + +### 其他 + +#### 隐私 diff --git a/apps/api-cloudflare/ingress-configuration.d.ts b/apps/api-cloudflare/ingress-configuration.d.ts new file mode 100644 index 0000000..52ffde4 --- /dev/null +++ b/apps/api-cloudflare/ingress-configuration.d.ts @@ -0,0 +1,34 @@ +/* eslint-disable */ +// Generated by Wrangler by running `wrangler types --config=apps/api-cloudflare/wrangler-ingress.jsonc --include-runtime=false --env-interface=GatewayEnv apps/api-cloudflare/ingress-configuration.d.ts` (hash: 63acac08f74c7d9d690b3b0d30f3d1d5) +interface __BaseEnv_GatewayEnv { + HYPERBUG_INGRESS_KEY: string; + API: + | Fetcher /* hyperbug-api-staging */ + | Fetcher /* hyperbug-api */ + | Fetcher /* hyperbug-api-local */; +} +declare namespace Cloudflare { + interface GlobalProps { + mainModule: typeof import('./src/ingress'); + } + interface StagingEnv { + HYPERBUG_INGRESS_KEY: string; + API: Fetcher /* hyperbug-api-staging */; + } + interface ProductionEnv { + HYPERBUG_INGRESS_KEY: string; + API: Fetcher /* hyperbug-api */; + } + interface Env extends __BaseEnv_GatewayEnv {} +} +interface GatewayEnv extends __BaseEnv_GatewayEnv {} +type StringifyValues> = { + [Binding in keyof EnvType]: EnvType[Binding] extends string + ? EnvType[Binding] + : string; +}; +declare namespace NodeJS { + interface ProcessEnv extends StringifyValues< + Pick + > {} +} diff --git a/apps/api-cloudflare/package.json b/apps/api-cloudflare/package.json new file mode 100644 index 0000000..730f1b1 --- /dev/null +++ b/apps/api-cloudflare/package.json @@ -0,0 +1,17 @@ +{ + "name": "@hyperbug/api-cloudflare", + "version": "0.0.0", + "private": true, + "type": "module", + "dependencies": { + "@hyperbug/config": "workspace:*", + "@hyperbug/database-d1": "workspace:*", + "@hyperbug/observability": "workspace:*", + "@hyperbug/security": "workspace:*", + "@hyperbug/server": "workspace:*", + "elysia": "1.4.30", + "libsodium-sumo": "0.8.4", + "@hyperbug/application": "workspace:*", + "@hyperbug/blob-r2": "workspace:*" + } +} diff --git a/apps/api-cloudflare/src/abuse-keys.ts b/apps/api-cloudflare/src/abuse-keys.ts new file mode 100644 index 0000000..e849af6 --- /dev/null +++ b/apps/api-cloudflare/src/abuse-keys.ts @@ -0,0 +1,19 @@ +import { RateLimitFailure, SecretAbuseKeyProvider } from '@hyperbug/security'; + +/** A dedicated Worker Secret binding, separate from ordinary vars and keys. */ +export function createWorkerAbuseKeyProvider( + secretBinding: string, +): SecretAbuseKeyProvider { + return new SecretAbuseKeyProvider({ + async read(signal) { + if ( + signal.aborted || + typeof secretBinding !== 'string' || + secretBinding.length < 1 || + secretBinding.length > 16384 + ) + throw new RateLimitFailure(); + return secretBinding; + }, + }); +} diff --git a/apps/api-cloudflare/src/async-budget.ts b/apps/api-cloudflare/src/async-budget.ts new file mode 100644 index 0000000..c694e61 --- /dev/null +++ b/apps/api-cloudflare/src/async-budget.ts @@ -0,0 +1,118 @@ +import type { + D1Database, + D1PreparedStatement, + R2Bucket, +} from '@cloudflare/workers-types'; +import { MINIMUM_ASYNC_LIMITS, AsyncError } from '@hyperbug/application/async'; + +/** Count before I/O, including every SQL statement in an atomic batch. */ +export function minimumInvocationBudget() { + let queries = 0, + subrequests = 0, + reads = 0, + writes = 0, + reporting = false; + const take = (sql = 0, external = 0) => { + if ( + queries + sql > + (reporting + ? MINIMUM_ASYNC_LIMITS.queries + : MINIMUM_ASYNC_LIMITS.queries - 5) || + subrequests + sql + external > + (reporting + ? MINIMUM_ASYNC_LIMITS.subrequests + : MINIMUM_ASYNC_LIMITS.subrequests - 5) + ) + throw new AsyncError('transient'); + queries += sql; + subrequests += sql + external; + }; + const result = (value: unknown) => { + for (const item of Array.isArray(value) ? value : [value]) { + const meta = ( + item as { meta?: { rows_read?: number; rows_written?: number } } + )?.meta; + reads += meta?.rows_read ?? 0; + writes += meta?.rows_written ?? 0; + } + if ( + reads > MINIMUM_ASYNC_LIMITS.invocationReads || + writes > MINIMUM_ASYNC_LIMITS.invocationWrites + ) + throw new AsyncError('transient'); + return value; + }; + const originals = new WeakMap(); + const statement = (raw: D1PreparedStatement): D1PreparedStatement => { + const wrapped = { + bind: (...values: unknown[]) => statement(raw.bind(...values)), + async first(column?: string) { + take(1); + const value = await raw.all>(); + result(value); + const row = value.results[0]; + return ( + row ? (column === undefined ? row : row[column]) : null + ) as T | null; + }, + async run() { + take(1); + return result(await raw.run()); + }, + async all() { + take(1); + return result(await raw.all()); + }, + raw() { + throw new AsyncError('unsupported'); + }, + } as D1PreparedStatement; + originals.set(wrapped, raw); + return wrapped; + }; + return { + db(raw: D1Database): D1Database { + return { + prepare: (sql: string) => statement(raw.prepare(sql)), + async batch(items: D1PreparedStatement[]) { + take(items.length); + return result( + await raw.batch( + items.map((item) => originals.get(item) ?? item), + ), + ); + }, + exec() { + throw new AsyncError('unsupported'); + }, + withSession() { + throw new AsyncError('unsupported'); + }, + dump: () => raw.dump(), + } as D1Database; + }, + bucket(raw: R2Bucket): R2Bucket { + return new Proxy(raw, { + get(target, key) { + const member = Reflect.get(target, key); + return typeof member === 'function' + ? (...args: unknown[]) => { + take(0, 1); + return member.apply(target, args); + } + : member; + }, + }); + }, + fetch(request: Request) { + take(0, 1); + return fetch(request); + }, + diagnostics() { + reporting = true; + }, + snapshot() { + return { queries, subrequests, reads, writes }; + }, + }; +} diff --git a/apps/api-cloudflare/src/async-minimum.ts b/apps/api-cloudflare/src/async-minimum.ts new file mode 100644 index 0000000..76e282c --- /dev/null +++ b/apps/api-cloudflare/src/async-minimum.ts @@ -0,0 +1,144 @@ +import type { D1Database } from '@cloudflare/workers-types'; +import { + createD1AsyncStore, + createD1MinimumAsyncStore, + createD1MinimumJobStore, + createD1PluginRegistryStore, + createD1PluginSettingsStore, + createD1ExpiredCleanupStore, +} from '@hyperbug/database-d1/async'; +import { + createAsyncProcessor, + createAsyncEventHandler, + runConformanceStep, + runScheduledUploadCleanup, + MINIMUM_ASYNC_LIMITS, +} from '@hyperbug/application/async'; +import { loadAsyncMaintenancePolicy } from '@hyperbug/config'; +import { minimumInvocationBudget } from './async-budget.ts'; +import type { WorkerUploadBindings } from './uploads.ts'; + +/** A single phase per existing Cron tick. No queue or Workflow binding is used. */ +export async function runMinimumAsyncTick(input: { + db: D1Database; + scheduledTime: number; + now?: () => number; + bindings: WorkerUploadBindings & { + ASYNC_ORPHAN_RETENTION_SECONDS?: unknown; + ASYNC_TERMINAL_RETENTION_SECONDS?: unknown; + }; + sessionRetentionMs: number; +}) { + const clock = input.now ?? Date.now, + budget = minimumInvocationBudget(), + db = budget.db(input.db); + const minimum = createD1MinimumAsyncStore(db); + const phase = Math.floor(input.scheduledTime / 300000) % 5; + let outcome = 'done'; + let jobState: { checkpoint: number; terminal: boolean } | null = null; + try { + if (phase === 0) { + const token = crypto.randomUUID(), + admission = await minimum.admitAndClaim(clock(), token), + refs = admission.references; + if (!admission.admitted) outcome = 'quota-exhausted'; + if (refs[0]) { + const process = createAsyncProcessor({ + store: minimum.executionStore(), + clock, + token: () => token, + handle: createAsyncEventHandler({ + search: minimum.searchStore(), + registry: createD1PluginRegistryStore(db), + settings: createD1PluginSettingsStore(db), + tier: 'cloudflare-minimum', + }), + }); + await process(refs[0]); + } + } else if (phase === 4) { + const minimumJobs = createD1MinimumJobStore(db), + selection = await minimumJobs.admit(clock()), + jobs = minimumJobs.store; + if (!selection.admitted) outcome = 'quota-exhausted'; + if (selection.job) { + if (selection.job.maxSteps > MINIMUM_ASYNC_LIMITS.steps) + await jobs.cancel(selection.job.id, clock()); + else + jobState = await runConformanceStep( + jobs, + { version: 1, jobId: selection.job.id }, + clock, + ); + } + } else if (!(await minimum.reserve(clock()))) outcome = 'quota-exhausted'; + else if (phase === 1) { + await createD1ExpiredCleanupStore(db).purgeExpired( + clock(), + input.sessionRetentionMs, + 1, + ); + } else if (phase === 2) { + const store = createD1AsyncStore(db); + const { configureWorkerUploads } = await import('./uploads.ts'); + const uploads = configureWorkerUploads( + db, + { + ...input.bindings, + ...(input.bindings.HYPERBUG_UPLOAD_BLOB + ? { + HYPERBUG_UPLOAD_BLOB: budget.bucket( + input.bindings.HYPERBUG_UPLOAD_BLOB, + ), + } + : {}), + }, + budget.fetch, + ); + if (uploads) + await runScheduledUploadCleanup( + store, + uploads, + loadAsyncMaintenancePolicy(input.bindings).orphanRetentionMs, + clock, + ); + } else if (phase === 3) { + const store = createD1AsyncStore(db); + await store.purgeTerminal( + Math.max( + 0, + clock() - + loadAsyncMaintenancePolicy(input.bindings).terminalRetentionMs, + ), + 1, + ); + await store.purgeJobs( + Math.max( + 0, + clock() - + loadAsyncMaintenancePolicy(input.bindings).terminalRetentionMs, + ), + 1, + ); + } + } catch { + // Leases/source/checkpoints survive budget limits and interrupted I/O. + outcome = 'bounded-error'; + } + budget.diagnostics(); + const backlog = await minimum.backlog().catch(() => null); + const report = { + component: 'async-minimum', + phase, + outcome, + job: jobState, + ...budget.snapshot(), + backlog, + ageMs: + backlog?.oldestAt === null || !backlog + ? null + : Math.max(0, clock() - backlog.oldestAt), + }; + console.log(JSON.stringify(report)); + return report; +} diff --git a/apps/api-cloudflare/src/async-processing.ts b/apps/api-cloudflare/src/async-processing.ts new file mode 100644 index 0000000..614e912 --- /dev/null +++ b/apps/api-cloudflare/src/async-processing.ts @@ -0,0 +1,57 @@ +import type { + D1Database, + Queue, + MessageBatch, +} from '@cloudflare/workers-types'; +import { + createD1AsyncStore, + createD1SearchIndexStore, + createD1PluginRegistryStore, + createD1PluginSettingsStore, +} from '@hyperbug/database-d1'; +import { + createAsyncEventHandler, + createAsyncProcessor, + createOutboxDispatcher, + type AsyncPluginBinding, + type TaskReference, +} from '@hyperbug/application'; +import { + createCloudflareTaskQueue, + consumeCloudflareBatch, +} from './task-queue.ts'; +export function configureCloudflareAsync( + db: D1Database, + queue: Queue | null, + bindings: readonly AsyncPluginBinding[] = [], +) { + const store = createD1AsyncStore(db); + const report = (metric: unknown) => + console.log(JSON.stringify({ component: 'async', metric })); + const process = createAsyncProcessor({ + store, + handle: createAsyncEventHandler({ + search: createD1SearchIndexStore(db), + registry: createD1PluginRegistryStore(db), + settings: createD1PluginSettingsStore(db), + bindings, + }), + telemetry: report, + }); + const dispatch = queue + ? createOutboxDispatcher({ + store, + queue: createCloudflareTaskQueue(queue), + telemetry: report, + }) + : null; + return { + store, + async dispatch() { + if (!dispatch) throw new Error('Async queue unavailable'); + await dispatch(); + }, + queue: (batch: MessageBatch) => + consumeCloudflareBatch(batch, process), + }; +} diff --git a/apps/api-cloudflare/src/attachment-scanner.ts b/apps/api-cloudflare/src/attachment-scanner.ts new file mode 100644 index 0000000..9ca7c0a --- /dev/null +++ b/apps/api-cloudflare/src/attachment-scanner.ts @@ -0,0 +1,96 @@ +import type { + Fetcher, + AbortController as PlatformAbortController, +} from '@cloudflare/workers-types'; +import { createR2BlobDigest } from '@hyperbug/blob-r2'; +import { + createScannerServiceClient, + scannerServiceUrl, + type AttachmentScanner, +} from '@hyperbug/application'; +declare const AbortController: typeof PlatformAbortController; + +/** Explicit private service capability; no ambient Internet fetch, endpoint selection or retry. */ +export function configureWorkerAttachmentScanner( + binding: Pick | undefined, + secret: string | undefined, +): AttachmentScanner | null { + if (binding === undefined && secret === undefined) return null; + try { + if (!binding || typeof binding.fetch !== 'function' || secret === undefined) + throw new Error(); + return createScannerServiceClient( + { + async send(input) { + const controller = new AbortController(); + const abort = () => controller.abort(); + const cleanup = () => + input.signal.removeEventListener('abort', abort); + input.signal.addEventListener('abort', abort, { once: true }); + if (input.signal.aborted) abort(); + try { + const response = await binding.fetch(scannerServiceUrl, { + method: 'POST', + headers: input.headers, + body: input.body, + signal: controller.signal, + redirect: 'manual', + }); + const source = response.body?.getReader(); + if (!source) cleanup(); + const body = source + ? new ReadableStream( + { + async pull(sink) { + try { + const next = await source.read(); + if (next.done) { + sink.close(); + source.releaseLock(); + cleanup(); + return; + } + if (!(next.value instanceof Uint8Array)) + throw new Error(); + sink.enqueue(next.value); + } catch { + cleanup(); + void source + .cancel() + .catch(() => {}) + .finally(() => source.releaseLock()); + sink.error( + new Error('Scanner service response failed'), + ); + } + }, + async cancel() { + try { + await source.cancel(); + } finally { + source.releaseLock(); + cleanup(); + } + }, + }, + { highWaterMark: 0 }, + ) + : null; + return { + status: response.status, + contentType: response.headers.get('content-type'), + body, + }; + } catch (error) { + cleanup(); + throw error; + } + }, + }, + createR2BlobDigest, + secret, + ); + } catch { + throw new Error('Invalid attachment scanner service configuration'); + } +} diff --git a/apps/api-cloudflare/src/composition.ts b/apps/api-cloudflare/src/composition.ts new file mode 100644 index 0000000..7e90102 --- /dev/null +++ b/apps/api-cloudflare/src/composition.ts @@ -0,0 +1,478 @@ +import { runMinimumAsyncTick } from './async-minimum.ts'; +import { loadAsyncMaintenancePolicy } from '@hyperbug/config'; +import { createD1AsyncStore } from '@hyperbug/database-d1'; +import { runScheduledUploadCleanup } from '@hyperbug/application'; +import { createCloudflareWorkflowAdapter, d1JobStore } from './workflow.ts'; +import type { AsyncPluginBinding } from '@hyperbug/application'; +import { configureCloudflareAsync } from './async-processing.ts'; +import { expiredCleanupBatchSize } from '@hyperbug/application'; +import { configureWorkerUploads } from './uploads.ts'; +import { CloudflareAdapter } from 'elysia/adapter/cloudflare-worker'; +import { + configureOptionalTurnstile, + createApp, + parseBootstrapEnrollmentCode, + parseOAuthClients, + parsePasskeyConfiguration, + createBoundMinimumLoginAdmission, +} from '@hyperbug/server'; +import { loadConfig, type DeploymentConfig } from '@hyperbug/config'; +import { jsonTelemetry } from '@hyperbug/observability'; +import { createCloudflareTurnstileVerifier } from './turnstile.ts'; +import { + adaptMinimumPasswordService, + auditEvent, + createMinimumPasswordService, + withMinimumPasswordUpgrade, + minimumTierAccountLockoutPolicy, + type AccountPasswordService, + minimumTierPasswordPolicy, + type MinimumPasswordService, +} from '@hyperbug/security'; +import { createWorkerAbuseKeyProvider } from './abuse-keys.ts'; +import { + createD1AccountAdministration, + createD1AccountLockoutStore, + createD1AccountRegistrationStore, + createD1AccountRecoveryStore, + createD1AccountSessionStore, + createD1AuditRepository, + createD1KeyRegistry, + createD1OAuthStores, + createD1PasskeyStores, + createD1PluginRegistryStore, + createD1PluginEventOutbox, + createD1PluginSettingsStore, + createD1ProjectRoleStore, + createD1ProjectStore, + createD1Repository, + createD1SearchStore, + createD1SearchIndexStore, + createD1CommentStore, + createD1ReactionStore, + createD1TimelineStore, + createD1RateCounterStore, + createD1ExpiredCleanupStore, + createD1StaffEnrollmentStore, + createD1TaxonomyStore, + createD1ContentDefinitionStore, + createD1AttachmentStore, +} from '@hyperbug/database-d1'; +import { createCloudflareVolumetricLimiter } from './rate-limit.ts'; +import { createWorkerKeyProvider } from './key-provider.ts'; +import { createIngressAttestation } from './ingress-attestation.ts'; + +export function createCloudflareApi( + env: Env, + standardFactory?: (deployment: DeploymentConfig) => AccountPasswordService, + asyncPlugins: readonly AsyncPluginBinding[] = [], +) { + // Workers permits AOT compilation during module initialization, before requests. + const config = loadConfig(env, 'cloudflare'); + const captcha = configureOptionalTurnstile( + { + secret: env.TURNSTILE_SECRET, + siteKey: env.TURNSTILE_SITE_KEY, + hostname: env.TURNSTILE_HOSTNAME, + environment: config.environment, + }, + createCloudflareTurnstileVerifier, + ); + const auditRepository = env.DB ? createD1AuditRepository(env.DB) : null; + const abuse = env.DB + ? { + provider: createWorkerAbuseKeyProvider(env.HYPERBUG_ABUSE_KEY_RING), + store: createD1RateCounterStore(env.DB), + limiter: createCloudflareVolumetricLimiter(env.ABUSE_VOLUMETRIC), + auditAppend: auditRepository?.append ?? null, + } + : null; + const keyProvider = env.DB + ? createWorkerKeyProvider( + env.HYPERBUG_KEY_RING, + createD1KeyRegistry(env.DB), + config.security.authorization.timeoutMs, + ) + : null; + const ingress = env.HYPERBUG_INGRESS_KEY + ? createIngressAttestation(env.HYPERBUG_INGRESS_KEY) + : null; + const accountStore = env.DB ? createD1AccountRegistrationStore(env.DB) : null; + // Optional operator-channel enrollment code: absent disarms the bootstrap + // route; a present but malformed value must refuse startup instead of + // silently disabling enrollment. Not declared required anywhere, so the + // binding is read through a narrowed view of the generated environment. + const bootstrapSecret = ( + env as { + HYPERBUG_BOOTSTRAP_ENROLLMENT?: string; + } + ).HYPERBUG_BOOTSTRAP_ENROLLMENT; + const bootstrapCode = + bootstrapSecret === undefined + ? null + : parseBootstrapEnrollmentCode(bootstrapSecret); + if (bootstrapSecret !== undefined && bootstrapCode === null) + throw new Error('Invalid bootstrap enrollment configuration'); + const staffEnrollmentStore = env.DB + ? createD1StaffEnrollmentStore(env.DB) + : null; + // Optional registered public clients: absent disarms the code flow; a present + // but malformed registry refuses startup instead of running a broken flow. + // Not declared required anywhere, so the binding is read through a narrowed + // view of the generated environment. + const oauthSecret = ( + env as { + HYPERBUG_OAUTH_CLIENTS?: string; + } + ).HYPERBUG_OAUTH_CLIENTS; + const oauthClients = parseOAuthClients(oauthSecret); + const oauthCodeStore = env.DB ? createD1OAuthStores(env.DB) : null; + const projectRoleStore = env.DB ? createD1ProjectRoleStore(env.DB) : null; + const projectStore = env.DB ? createD1ProjectStore(env.DB) : null; + const issueRepository = env.DB ? createD1Repository(env.DB) : null; + const commentStore = env.DB ? createD1CommentStore(env.DB) : null; + const reactionStore = env.DB ? createD1ReactionStore(env.DB) : null; + const timelineStore = env.DB ? createD1TimelineStore(env.DB) : null; + const taxonomyStore = env.DB ? createD1TaxonomyStore(env.DB) : null; + const pluginRegistry = env.DB ? createD1PluginRegistryStore(env.DB) : null; + const pluginSettings = env.DB ? createD1PluginSettingsStore(env.DB) : null; + const asyncRuntime = + env.DB && config.deployment.tier === 'standard' + ? configureCloudflareAsync( + env.DB, + ( + env as { + ASYNC_TASKS?: import('@cloudflare/workers-types').Queue< + import('@hyperbug/application').TaskReference + >; + } + ).ASYNC_TASKS ?? null, + asyncPlugins, + ) + : null; + const pluginEventOutbox = env.DB ? createD1PluginEventOutbox(env.DB) : null; + const accountAdministration = env.DB + ? createD1AccountAdministration(env.DB) + : null; + // A complete relying-party selection without the session/key prerequisites + // refuses startup instead of silently disabling passkey authentication. + // Not declared required anywhere, so the bindings are read through a + // narrowed view of the generated environment. + const passkeyVars = env as { + PASSKEY_RP_ID?: string; + PASSKEY_RP_NAME?: string; + PASSKEY_ORIGIN?: string; + }; + const passkeyConfig = parsePasskeyConfiguration({ + rpId: passkeyVars.PASSKEY_RP_ID, + rpName: passkeyVars.PASSKEY_RP_NAME, + origin: passkeyVars.PASSKEY_ORIGIN, + }); + const passkey = + passkeyConfig && env.DB && keyProvider + ? { + ...passkeyConfig, + store: createD1PasskeyStores(env.DB), + passwordStore: createD1AccountRegistrationStore(env.DB), + sessionStore: createD1AccountSessionStore(env.DB), + keyProvider, + } + : null; + // A correctly acknowledged minimum-tier selection is activated through the + // audited enablement contract: the startup warning, one persisted + // deployment.enablement event (a deterministic id makes cold starts + // idempotent — only the first request of the first isolate writes it) and + // the peppered password service preflight through the loader-based adapter. + const minimumTierEnabled = config.deployment.tier === 'cloudflare-minimum'; + const enablementEventId = '80fad34e-66c5-4c63-a0c1-1a2e7a35b3f2'; + if (minimumTierEnabled) + console.warn( + `HyperBug minimum tier enabled (acknowledged): degradations ${config.deployment.degradationIds.join(',')} active; PBKDF2 passwords use the disclosed Minimum exception; the tier runs without independent 13.G6 acceptance.`, + ); + const recordTierEnablement = async (): Promise => { + const recorded = await env + .DB!.prepare('SELECT id FROM audit_events WHERE id = ?') + .bind(enablementEventId) + .first(); + if (recorded !== null) return; + try { + await auditRepository!.append( + auditEvent({ + id: enablementEventId, + projectId: null, + actorId: null, + systemActor: 'core.deployment', + action: 'deployment.enablement', + targetId: 'cloudflare-minimum', + result: 'success', + requestId: enablementEventId, + createdAt: Date.now(), + metadata: { + v: 1, + acknowledgement: 'minimum-v2', + outcome: 'enabled', + }, + }), + new AbortController().signal, + ); + } catch { + // A racing cold start may have written the same deterministic id. + const raced = await env + .DB!.prepare('SELECT id FROM audit_events WHERE id = ?') + .bind(enablementEventId) + .first(); + if (raced === null) + throw new Error('The minimum tier enablement audit write failed'); + } + }; + let minimumService: Promise | null = null; + const loadMinimumPasswordService = (): Promise => + (minimumService ??= (async () => { + // Runtime prerequisite check: the audited activation needs the database, + // its audit repository and the key provider. (Cloudflare's upload-time + // module validation runs without live bindings, so a module-scope check + // here would falsely refuse valid uploads; this runs per isolate.) + if (!env.DB || !auditRepository || !keyProvider) + throw new Error( + 'The minimum tier requires its audited enablement trail', + ); + await recordTierEnablement(); + return createMinimumPasswordService( + keyProvider!, + minimumTierPasswordPolicy, + // B15's ten-login burst exposed single-slot saturation; bound native + // PBKDF2 work separately from durable account/IP admission. + 10, + ); + })().catch((error: unknown) => { + minimumService = null; + throw error; + })); + const minimumPassword = minimumTierEnabled + ? adaptMinimumPasswordService(loadMinimumPasswordService) + : null; + + const standardPassword = + config.deployment.tier === 'standard' + ? (() => { + if (!standardFactory) + throw new Error( + 'The Minimum entry requires cloudflare-minimum configuration', + ); + const standard = standardFactory(config.deployment); + return keyProvider + ? withMinimumPasswordUpgrade( + standard, + adaptMinimumPasswordService(() => + createMinimumPasswordService( + keyProvider, + minimumTierPasswordPolicy, + ), + ), + ) + : standard; + })() + : null; + const minimumLoginAdmission = minimumTierEnabled + ? createBoundMinimumLoginAdmission( + captcha.gate, + { + lockout: minimumTierAccountLockoutPolicy, + rateTimeoutMs: config.security.authorization.timeoutMs, + lockoutTimeoutMs: config.security.authorization.timeoutMs, + }, + abuse && env.DB + ? { + provider: abuse.provider, + rateStore: abuse.store, + lockoutStore: createD1AccountLockoutStore(env.DB), + ...(ingress ? { clientAddress: ingress.verify } : {}), + } + : null, + ) + : null; + const uploads = configureWorkerUploads( + env.DB ?? null, + env as unknown as Parameters[1], + ); + const app = createApp({ + adapter: CloudflareAdapter, + config, + telemetry: jsonTelemetry((line) => console.log(line)), + ready: async (signal) => { + if (minimumTierEnabled && !activationComplete) return false; + if ( + !abuse || + !env.DB || + typeof env.ABUSE_VOLUMETRIC?.limit !== 'function' || + signal.aborted + ) + return false; + try { + await abuse.provider.active(signal); + if (signal.aborted) return false; + if (!keyProvider) return false; + await keyProvider.current('token-hmac'); + if (signal.aborted) return false; + const result = await env.DB.prepare( + 'SELECT 1 FROM rate_limit_counters, password_credentials, authorization_sessions LIMIT 0', + ).all(); + return !signal.aborted && result.success === true; + } catch { + return false; + } + }, + captcha: captcha.gate, + captchaSiteKey: captcha.siteKey, + abuse: abuse + ? { + ...abuse, + ...(ingress ? { clientAddress: ingress.verify } : {}), + } + : null, + keyProvider, + standardPassword: standardPassword ?? null, + minimumPassword, + minimumLoginAdmission, + registrationStore: accountStore, + passwordStore: accountStore, + sessionStore: env.DB ? createD1AccountSessionStore(env.DB) : null, + recoveryStore: env.DB ? createD1AccountRecoveryStore(env.DB) : null, + passkey, + // The shared server requires a complete OAuth dependency set. During + // upload validation the parsed registry stays in this root, whose fetch + // guard refuses all requests until native resources are present. + oauthClients: env.DB && keyProvider ? oauthClients : [], + oauthCodeStore, + projectRoleStore, + projectStore, + issueRepository, + searchStore: env.DB ? createD1SearchStore(env.DB) : null, + searchIndexStore: env.DB ? createD1SearchIndexStore(env.DB) : null, + commentStore, + reactionStore, + timelineStore, + taxonomyStore, + contentDefinitionStore: env.DB + ? createD1ContentDefinitionStore(env.DB) + : null, + attachmentStore: env.DB ? createD1AttachmentStore(env.DB) : null, + mediaOrigin: + (env as { HYPERBUG_MEDIA_ORIGIN?: string }).HYPERBUG_MEDIA_ORIGIN ?? null, + uploads, + pluginRegistry, + pluginSettings, + pluginEventOutbox, + accountAdministration, + auditAppend: auditRepository?.append ?? null, + auditRepository, + bootstrapCode, + staffEnrollmentStore, + bootstrapState: staffEnrollmentStore + ? async () => (await staffEnrollmentStore.countActiveStaff()) === 0 + : null, + }).compile(); + + // Request-local I/O starts lazily; only sensitive routes wait for activation. + let activationComplete = false; + let tierActivation: Promise | null = null; + const ensureTierActivated = (): Promise => + (tierActivation ??= loadMinimumPasswordService() + .then(() => { + activationComplete = true; + }) + .catch((error: unknown) => { + tierActivation = null; + throw error; + })); + + return { + async fetch(request: Request) { + // Cloudflare validates modules at upload without live native bindings. + // Validate configuration above; require binding-dependent auth resources + // before the first runtime request can reach any route. + if (oauthClients.length > 0 && (!env.DB || !keyProvider)) + throw new Error('Invalid OAuth client configuration'); + if (passkeyConfig && (!env.DB || !keyProvider)) + throw new Error('Invalid passkey configuration'); + void uploads?.intents; + if (minimumTierEnabled) { + const path = new URL(request.url).pathname; + const publicRead = + (request.method === 'GET' || request.method === 'HEAD') && + !request.headers.has('authorization') && + !request.headers.has('cookie') && + path.startsWith('/api/v1/') && + !path.startsWith('/api/v1/account') && + !path.startsWith('/api/v1/admin'); + const activationExempt = + path === '/health/live' || + path === '/health/ready' || + path === '/api/v1/instance' || + publicRead || + request.method === 'OPTIONS'; + if (!activationExempt) await ensureTierActivated(); + } + return app.fetch(request); + }, + async queue(batch: MessageBatch) { + if (!asyncRuntime) throw new Error('Async consumer unavailable'); + await asyncRuntime.queue(batch); + }, + async scheduled(controller: ScheduledController, bindings: Env) { + if (!bindings.DB) throw new Error('Expired cleanup unavailable'); + const cleanupConfig = loadConfig(bindings, 'cloudflare'); + if (cleanupConfig.deployment.tier === 'cloudflare-minimum') { + await runMinimumAsyncTick({ + db: bindings.DB, + scheduledTime: controller.scheduledTime, + bindings: bindings as Env & + import('./uploads.ts').WorkerUploadBindings, + sessionRetentionMs: + cleanupConfig.security.retentionSeconds.expiredSessions * 1000, + }); + return; + } + await createD1ExpiredCleanupStore(bindings.DB).purgeExpired( + Date.now(), + cleanupConfig.security.retentionSeconds.expiredSessions * 1000, + expiredCleanupBatchSize, + ); + const maintenance = createD1AsyncStore(bindings.DB); + const policy = loadAsyncMaintenancePolicy( + bindings as { + ASYNC_ORPHAN_RETENTION_SECONDS?: string; + ASYNC_TERMINAL_RETENTION_SECONDS?: string; + }, + ); + await maintenance.purgeTerminal( + Math.max(0, Date.now() - policy.terminalRetentionMs), + 10, + ); + await maintenance.purgeJobs( + Math.max(0, Date.now() - policy.terminalRetentionMs), + 10, + ); + if (uploads) + await runScheduledUploadCleanup( + maintenance, + uploads, + policy.orphanRetentionMs, + ); + const workflow = bindings.ASYNC_WORKFLOW; + if (workflow) { + const adapter = createCloudflareWorkflowAdapter( + d1JobStore(bindings.DB), + workflow, + ); + await maintenance.recoverableJobs(Date.now(), 1).then((ids) => + ids.reduce(async (previous, id) => { + await previous; + await adapter.resume(id); + }, Promise.resolve()), + ); + } + await asyncRuntime?.dispatch(); + }, + } satisfies ExportedHandler; +} diff --git a/apps/api-cloudflare/src/index.ts b/apps/api-cloudflare/src/index.ts new file mode 100644 index 0000000..c73a5c6 --- /dev/null +++ b/apps/api-cloudflare/src/index.ts @@ -0,0 +1,14 @@ +import { env } from 'cloudflare:workers'; +import { createCloudflareApi } from './composition.ts'; +import { createCloudflareStandardPasswordService } from './standard-password.ts'; +import { initialStandardPasswordPolicy } from '@hyperbug/security'; + +export default createCloudflareApi(env, (deployment) => + createCloudflareStandardPasswordService( + deployment, + initialStandardPasswordPolicy, + initialStandardPasswordPolicy.maximum.memoryKiB, + ), +); + +export { HyperBugWorkflow } from './workflow.ts'; diff --git a/apps/api-cloudflare/src/ingress-attestation.ts b/apps/api-cloudflare/src/ingress-attestation.ts new file mode 100644 index 0000000..b8986b8 --- /dev/null +++ b/apps/api-cloudflare/src/ingress-attestation.ts @@ -0,0 +1,106 @@ +import { canonicalIpAddress, RateLimitFailure } from '@hyperbug/security'; + +const addressHeader = 'x-hyperbug-ingress-ip'; +const timeHeader = 'x-hyperbug-ingress-time'; +const signatureHeader = 'x-hyperbug-ingress-signature'; +const maxAgeMs = 5000; + +function decode(value: string, length: number): Uint8Array { + if ( + typeof value !== 'string' || + !new RegExp(`^[A-Za-z0-9_-]{${length}}$`).test(value) + ) + throw new RateLimitFailure(); + try { + const bytes = Uint8Array.from( + atob(value.replaceAll('-', '+').replaceAll('_', '/') + '='), + (character) => character.charCodeAt(0), + ); + if (bytes.length !== 32 || encode(buffer(bytes)) !== value) + throw new RateLimitFailure(); + return bytes; + } catch { + throw new RateLimitFailure(); + } +} + +function encode(bytes: ArrayBuffer): string { + return btoa(String.fromCharCode(...new Uint8Array(bytes))) + .replaceAll('+', '-') + .replaceAll('/', '_') + .replaceAll('=', ''); +} + +function buffer(bytes: Uint8Array): ArrayBuffer { + const copy = new Uint8Array(bytes.byteLength); + copy.set(bytes); + return copy.buffer; +} + +function payload(request: Request, ip: string, issuedAt: string): Uint8Array { + const url = new URL(request.url); + return new TextEncoder().encode( + `hyperbug-ingress-v1\n${request.method}\n${url.pathname}${url.search}\n${ip}\n${issuedAt}`, + ); +} + +/** Share only with a controlled public ingress Worker and a private API Worker. */ +export function createIngressAttestation(secret: string) { + const material = decode(secret, 43); + const key = crypto.subtle.importKey( + 'raw', + buffer(material), + { name: 'HMAC', hash: 'SHA-256' }, + false, + ['sign', 'verify'], + ); + return Object.freeze({ + async sign(request: Request, rawIp: string): Promise { + const ip = canonicalIpAddress(rawIp); + const issuedAt = String(Date.now()); + const headers = new Headers(request.headers); + headers.delete(addressHeader); + headers.delete(timeHeader); + headers.delete(signatureHeader); + for (const name of [ + 'cf-connecting-ip', + 'x-real-ip', + 'true-client-ip', + 'x-forwarded-for', + 'forwarded', + 'cf-worker', + ]) + headers.delete(name); + const signature = await crypto.subtle.sign( + 'HMAC', + await key, + buffer(payload(request, ip, issuedAt)), + ); + headers.set(addressHeader, ip); + headers.set(timeHeader, issuedAt); + headers.set(signatureHeader, encode(signature)); + return headers; + }, + async verify(request: Request): Promise { + const ip = canonicalIpAddress(request.headers.get(addressHeader)); + const issuedAt = request.headers.get(timeHeader); + const signature = request.headers.get(signatureHeader); + if ( + request.signal.aborted || + typeof issuedAt !== 'string' || + !/^\d{13}$/.test(issuedAt) || + Math.abs(Date.now() - Number(issuedAt)) > maxAgeMs || + typeof signature !== 'string' + ) + throw new RateLimitFailure(); + const valid = await crypto.subtle.verify( + 'HMAC', + await key, + buffer(decode(signature, 43)), + buffer(payload(request, ip, issuedAt)), + ); + if (!valid || request.signal.aborted) throw new RateLimitFailure(); + return ip; + }, + }); +} diff --git a/apps/api-cloudflare/src/ingress.ts b/apps/api-cloudflare/src/ingress.ts new file mode 100644 index 0000000..6ca0c92 --- /dev/null +++ b/apps/api-cloudflare/src/ingress.ts @@ -0,0 +1,37 @@ +import { env } from 'cloudflare:workers'; +import { canonicalIpAddress } from '@hyperbug/security'; +import { createIngressAttestation } from './ingress-attestation.ts'; + +/** Public edge entry; API is reachable only through its service binding. */ +const attestation = createIngressAttestation(env.HYPERBUG_INGRESS_KEY); +const unavailable = () => + new Response(null, { + status: 503, + headers: { + 'cache-control': 'no-store', + 'x-content-type-options': 'nosniff', + }, + }); +export default { + async fetch(request, gatewayEnv) { + try { + if (request.headers.has('cf-worker')) return unavailable(); + const ip = canonicalIpAddress(request.headers.get('cf-connecting-ip')); + // Cloudflare substitutes this address for cross-zone Worker subrequests. + if (ip === '2a06:98c0:3600::103') return unavailable(); + // The edge force-sets x-real-ip to the connecting address on this + // platform (observed deployed on workers.dev and custom domains; + // client-supplied values are overwritten), so a direct client cannot + // arrive without it. A same-zone Worker subrequest can still set it + // (Cloudflare's header reference), so keep it as a divergence tripwire: + // provenance itself is always the canonical cf-connecting-ip. + const claimedRealIp = request.headers.get('x-real-ip'); + if (claimedRealIp !== null && canonicalIpAddress(claimedRealIp) !== ip) + return unavailable(); + const headers = await attestation.sign(request, ip); + return await gatewayEnv.API.fetch(new Request(request, { headers })); + } catch { + return unavailable(); + } + }, +} satisfies ExportedHandler; diff --git a/apps/api-cloudflare/src/key-provider.ts b/apps/api-cloudflare/src/key-provider.ts new file mode 100644 index 0000000..93a1382 --- /dev/null +++ b/apps/api-cloudflare/src/key-provider.ts @@ -0,0 +1,29 @@ +import { + CryptoFailure, + SecretKeyProvider, + type KeyLifecycle, +} from '@hyperbug/security'; + +/** Pass the generated Env's Worker Secret binding, never a vars/config default. */ +export function createWorkerKeyProvider( + secretBinding: string, + lifecycle: KeyLifecycle, + timeoutMs = 1000, +): SecretKeyProvider { + return new SecretKeyProvider( + { + async read(signal) { + if ( + signal.aborted || + typeof secretBinding !== 'string' || + secretBinding.length === 0 || + secretBinding.length > 16384 + ) + throw new CryptoFailure(); + return secretBinding; + }, + }, + lifecycle, + timeoutMs, + ); +} diff --git a/apps/api-cloudflare/src/minimum-password.ts b/apps/api-cloudflare/src/minimum-password.ts new file mode 100644 index 0000000..97e457a --- /dev/null +++ b/apps/api-cloudflare/src/minimum-password.ts @@ -0,0 +1,26 @@ +import type { DeploymentConfig } from '@hyperbug/config'; +import { + createMinimumPasswordService, + CryptoFailure, + minimumTierPasswordPolicy, + type KeyProvider, + type MinimumPasswordPolicy, + type MinimumPasswordService, +} from '@hyperbug/security'; + +/** Separate opt-in tier; standard paid Workers retain Argon2id. */ +export async function createCloudflareMinimumPasswordService( + deployment: DeploymentConfig, + provider: KeyProvider, + policy: MinimumPasswordPolicy, +): Promise { + if (deployment?.tier !== 'cloudflare-minimum') throw new CryptoFailure(); + // The measured plan fit is a hard ceiling: a configured policy above it + // would exceed the Free per-invocation CPU budget on every verification. + if ( + policy.maximumIterations > minimumTierPasswordPolicy.maximumIterations || + policy.currentIterations > minimumTierPasswordPolicy.maximumIterations + ) + throw new CryptoFailure(); + return createMinimumPasswordService(provider, policy); +} diff --git a/apps/api-cloudflare/src/minimum.ts b/apps/api-cloudflare/src/minimum.ts new file mode 100644 index 0000000..305bbec --- /dev/null +++ b/apps/api-cloudflare/src/minimum.ts @@ -0,0 +1,5 @@ +import { env } from 'cloudflare:workers'; +import { createCloudflareApi } from './composition.ts'; + +// No Argon2id runtime or Wasm import enters this profile's dependency graph. +export default createCloudflareApi(env); diff --git a/apps/api-cloudflare/src/outbound.ts b/apps/api-cloudflare/src/outbound.ts new file mode 100644 index 0000000..d25fea9 --- /dev/null +++ b/apps/api-cloudflare/src/outbound.ts @@ -0,0 +1,6 @@ +import { createOutboundFetcher, type OutboundLimits } from '@hyperbug/security'; + +/** Workers egress uses platform fetch under the shared fixed-destination policy. */ +export function createCloudflareOutboundFetcher(limits: OutboundLimits) { + return createOutboundFetcher(limits, fetch); +} diff --git a/apps/api-cloudflare/src/rate-limit.ts b/apps/api-cloudflare/src/rate-limit.ts new file mode 100644 index 0000000..10350b1 --- /dev/null +++ b/apps/api-cloudflare/src/rate-limit.ts @@ -0,0 +1,26 @@ +import { validVolumetricKey, type VolumetricLimiter } from '@hyperbug/security'; + +export interface WorkersRateLimitBinding { + limit(options: { key: string }): Promise<{ success: boolean }>; +} + +/** Cloudflare's binding is location scoped and eventually consistent. */ +export function createCloudflareVolumetricLimiter( + binding: WorkersRateLimitBinding, +): VolumetricLimiter { + return { + async consume(digest, nowMs) { + if (!validVolumetricKey(digest, nowMs)) + return { allowed: false, reason: 'unavailable' }; + try { + const outcome = await binding.limit({ key: digest }); + if (outcome.success === true) return { allowed: true }; + if (outcome.success === false) + return { allowed: false, reason: 'limited' }; + } catch { + // An unavailable limiter never grants the dependent request. + } + return { allowed: false, reason: 'unavailable' }; + }, + }; +} diff --git a/apps/api-cloudflare/src/standard-password.ts b/apps/api-cloudflare/src/standard-password.ts new file mode 100644 index 0000000..2c268c4 --- /dev/null +++ b/apps/api-cloudflare/src/standard-password.ts @@ -0,0 +1,196 @@ +/// +/* oxlint-disable no-underscore-dangle -- libsodium's raw Wasm exports use leading underscores. */ +import sodiumFactory from 'libsodium-sumo'; +import sodiumWasm from './vendor/libsodium-sumo-0.8.4.wasm'; +import type { DeploymentConfig } from '@hyperbug/config'; +import { + createStandardPasswordService, + CryptoFailure, + snapshotStandardPasswordPolicy, + validArgon2idParameters, + type Argon2idParameters, + type Argon2idProvider, + type StandardPasswordPolicy, + type StandardPasswordService, +} from '@hyperbug/security'; + +const saltBytes = 16; +const verifierBytes = 32; + +type Sodium = Awaited>; +let sodium: Promise | undefined; + +function loadSodium(): Promise { + // The factory uses CSPRNG during initialization; Workers forbids this in + // global scope, so instantiate on the first request and reuse the instance. + return (sodium ??= sodiumFactory({ + getRandomValue: () => crypto.getRandomValues(new Uint32Array(1))[0]!, + instantiateWasm(imports, receive) { + const instance = new WebAssembly.Instance(sodiumWasm, imports); + receive(instance, sodiumWasm); + return instance.exports; + }, + }).then((loaded) => { + if (loaded._sodium_init() < 0) throw new CryptoFailure(); + return loaded; + })); +} + +function alloc(loaded: Sodium, bytes: number): number { + const pointer = loaded._malloc(bytes); + if (!Number.isSafeInteger(pointer) || pointer <= 0) throw new CryptoFailure(); + return pointer; +} + +function wipeAndFree(loaded: Sodium, pointer: number, bytes: number): void { + if (pointer <= 0) return; + loaded.HEAPU8.fill(0, pointer, pointer + bytes); + loaded._free(pointer); +} + +/** Candidate for paid-capable standard Workers only; no account route is wired. */ +export function createCloudflareArgon2idProvider( + maximumMemoryKiB: number, +): Argon2idProvider { + if ( + !Number.isSafeInteger(maximumMemoryKiB) || + maximumMemoryKiB < 19 * 1024 || + maximumMemoryKiB > 1_048_576 + ) + throw new CryptoFailure(); + let active = false; + const derive = async ( + password: Uint8Array, + salt: Uint8Array, + parameters: Argon2idParameters, + signal?: AbortSignal, + ): Promise => { + let cost: Argon2idParameters; + try { + cost = Object.freeze({ + memoryKiB: parameters.memoryKiB, + passes: parameters.passes, + parallelism: parameters.parallelism, + }); + } catch { + throw new CryptoFailure(); + } + // libsodium's pwhash ABI does not expose a lane-count argument. + if ( + !(password instanceof Uint8Array) || + password.byteLength < 1 || + password.byteLength > 1024 || + !(salt instanceof Uint8Array) || + salt.byteLength !== saltBytes || + !validArgon2idParameters(cost) || + cost.parallelism !== 1 || + cost.memoryKiB > maximumMemoryKiB || + signal?.aborted || + active + ) + throw new CryptoFailure(); + active = true; + const message = Uint8Array.from(password); + const nonce = Uint8Array.from(salt); + let loaded: Sodium | undefined; + let messagePtr = 0; + let noncePtr = 0; + let outputPtr = 0; + try { + loaded = await loadSodium(); + if (signal?.aborted) throw new CryptoFailure(); + messagePtr = alloc(loaded, message.byteLength); + noncePtr = alloc(loaded, saltBytes); + outputPtr = alloc(loaded, verifierBytes); + loaded.HEAPU8.set(message, messagePtr); + loaded.HEAPU8.set(nonce, noncePtr); + const result = loaded._crypto_pwhash( + outputPtr, + verifierBytes, + 0, + messagePtr, + message.byteLength, + 0, + noncePtr, + cost.passes, + 0, + cost.memoryKiB * 1024, + 2, + ); + if (result !== 0 || signal?.aborted) throw new CryptoFailure(); + return Uint8Array.from( + loaded.HEAPU8.subarray(outputPtr, outputPtr + verifierBytes), + ); + } catch { + throw new CryptoFailure(); + } finally { + if (loaded) { + wipeAndFree(loaded, outputPtr, verifierBytes); + wipeAndFree(loaded, noncePtr, saltBytes); + wipeAndFree(loaded, messagePtr, message.byteLength); + } + message.fill(0); + nonce.fill(0); + active = false; + } + }; + return Object.freeze({ + derive, + async matches( + password: Uint8Array, + salt: Uint8Array, + verifier: Uint8Array, + parameters: Argon2idParameters, + signal?: AbortSignal, + ): Promise { + if ( + !(verifier instanceof Uint8Array) || + verifier.byteLength !== verifierBytes + ) + throw new CryptoFailure(); + const expected = Uint8Array.from(verifier); + let derived: Uint8Array | undefined; + let loaded: Sodium | undefined; + let left = 0; + let right = 0; + try { + derived = await derive(password, salt, parameters, signal); + loaded = await loadSodium(); + if (signal?.aborted) throw new CryptoFailure(); + left = alloc(loaded, verifierBytes); + right = alloc(loaded, verifierBytes); + loaded.HEAPU8.set(derived, left); + loaded.HEAPU8.set(expected, right); + return loaded._crypto_verify_32(left, right) === 0; + } catch { + throw new CryptoFailure(); + } finally { + if (loaded) { + wipeAndFree(loaded, right, verifierBytes); + wipeAndFree(loaded, left, verifierBytes); + } + derived?.fill(0); + expected.fill(0); + } + }, + }); +} + +/** Paid-capable standard Workers only; reject unsupported stored-cost policy. */ +export function createCloudflareStandardPasswordService( + deployment: DeploymentConfig, + policy: StandardPasswordPolicy, + maximumMemoryKiB: number, +): StandardPasswordService { + if (deployment?.tier !== 'standard') throw new CryptoFailure(); + const selected = snapshotStandardPasswordPolicy(policy); + if ( + selected.maximum.parallelism !== 1 || + selected.maximum.memoryKiB > maximumMemoryKiB + ) + throw new CryptoFailure(); + return createStandardPasswordService( + createCloudflareArgon2idProvider(maximumMemoryKiB), + selected, + ); +} diff --git a/apps/api-cloudflare/src/task-queue.ts b/apps/api-cloudflare/src/task-queue.ts new file mode 100644 index 0000000..f474364 --- /dev/null +++ b/apps/api-cloudflare/src/task-queue.ts @@ -0,0 +1,46 @@ +import { + ASYNC_LIMITS, + AsyncError, + validateTaskReference, + type TaskQueue, + type TaskReference, +} from '@hyperbug/application'; +import type { Queue, MessageBatch } from '@cloudflare/workers-types'; + +export function createCloudflareTaskQueue( + queue: Queue, +): TaskQueue { + const schedule = async (reference: TaskReference, delayMs: number) => { + validateTaskReference(reference); + if ( + !Number.isInteger(delayMs) || + delayMs < 0 || + delayMs > ASYNC_LIMITS.maxDelayMs + ) + throw new AsyncError('invalid'); + await queue.send(reference, { + contentType: 'json', + delaySeconds: Math.ceil(delayMs / 1000), + }); + }; + return { enqueue: (reference) => schedule(reference, 0), schedule }; +} +export async function consumeCloudflareBatch( + batch: MessageBatch, + process: (value: unknown) => Promise<'ack' | 'retry'>, +): Promise { + // Sequential within a batch, platform max_concurrency=2; excess is never silently accepted. + await batch.messages.reduce(async (previous, message, index) => { + await previous; + if (index >= ASYNC_LIMITS.batch) { + message.retry({ delaySeconds: 30 }); + return; + } + try { + if ((await process(message.body)) === 'ack') message.ack(); + else message.retry({ delaySeconds: 30 }); + } catch { + message.retry({ delaySeconds: 30 }); + } + }, Promise.resolve()); +} diff --git a/apps/api-cloudflare/src/turnstile.ts b/apps/api-cloudflare/src/turnstile.ts new file mode 100644 index 0000000..e418e1a --- /dev/null +++ b/apps/api-cloudflare/src/turnstile.ts @@ -0,0 +1,13 @@ +import { + createTurnstileVerifier, + turnstileOutboundLimits, +} from '@hyperbug/server'; +import { createCloudflareOutboundFetcher } from './outbound.ts'; + +/** Optional Workers provider using platform fetch under the fixed catalog. */ +export function createCloudflareTurnstileVerifier(secret: string) { + return createTurnstileVerifier( + secret, + createCloudflareOutboundFetcher(turnstileOutboundLimits), + ); +} diff --git a/apps/api-cloudflare/src/uploads.ts b/apps/api-cloudflare/src/uploads.ts new file mode 100644 index 0000000..666a873 --- /dev/null +++ b/apps/api-cloudflare/src/uploads.ts @@ -0,0 +1,75 @@ +import type { D1Database, R2Bucket } from '@cloudflare/workers-types'; +import { + createR2BlobStore, + createR2BlobAuthorization, + createR2BlobDigest, + createR2MultipartReconciler, + type R2SigningConfig, +} from '@hyperbug/blob-r2'; +import { createD1UploadIntentStore } from '@hyperbug/database-d1'; +import { + defaultUploadQuota, + defaultUploadMultipart, + validateMultipartPolicy, + type BlobMultipartPolicy, + type UploadDependencies, +} from '@hyperbug/application'; + +export interface WorkerUploadBindings { + HYPERBUG_UPLOAD_BLOB?: R2Bucket; + HYPERBUG_UPLOAD_STORAGE?: string; +} +/** Native CRUD binding plus a private signing secret for the same operator-selected bucket. */ +export function configureWorkerUploads( + db: D1Database | null, + bindings: WorkerUploadBindings, + transport?: (outbound: Request) => Promise, +): UploadDependencies | null { + if ( + bindings.HYPERBUG_UPLOAD_BLOB === undefined && + bindings.HYPERBUG_UPLOAD_STORAGE === undefined + ) + return null; + let phase = 'bindings'; + try { + if (!bindings.HYPERBUG_UPLOAD_STORAGE) throw new Error(); + phase = 'configuration'; + const config = JSON.parse( + bindings.HYPERBUG_UPLOAD_STORAGE, + ) as R2SigningConfig & { multipart?: BlobMultipartPolicy }; + // Validate static policy now; native bindings may be absent during + // upload-time module validation. Acquire them on the first runtime request. + phase = 'blob-policy'; + const multipart = validateMultipartPolicy( + config.multipart ?? defaultUploadMultipart, + ); + phase = 'signing'; + const capabilities = createR2BlobAuthorization(config); + phase = 'reconciliation'; + const multipartReconciler = createR2MultipartReconciler(config, transport); + let native: Pick | null = null; + const live = () => { + if (native) return native; + if (!db || !bindings.HYPERBUG_UPLOAD_BLOB) + throw new Error('Invalid upload storage configuration (bindings)'); + native = { + intents: createD1UploadIntentStore(db, defaultUploadQuota), + blobs: createR2BlobStore(bindings.HYPERBUG_UPLOAD_BLOB, multipart), + }; + return native; + }; + return { + get intents() { + return live().intents; + }, + get blobs() { + return live().blobs; + }, + capabilities, + createDigest: createR2BlobDigest, + multipartReconciler, + }; + } catch { + throw new Error(`Invalid upload storage configuration (${phase})`); + } +} diff --git a/apps/api-cloudflare/src/vendor.d.ts b/apps/api-cloudflare/src/vendor.d.ts new file mode 100644 index 0000000..321a3e6 --- /dev/null +++ b/apps/api-cloudflare/src/vendor.d.ts @@ -0,0 +1,45 @@ +declare module '*.wasm' { + const module: WebAssembly.Module; + export default module; +} + +declare namespace Cloudflare { + interface Env { + TURNSTILE_SECRET?: string; + TURNSTILE_SITE_KEY?: string; + TURNSTILE_HOSTNAME?: string; + } +} + +declare module 'libsodium-sumo' { + interface RawSodium { + HEAPU8: Uint8Array; + _malloc(bytes: number): number; + _free(pointer: number): void; + _sodium_init(): number; + _crypto_pwhash( + output: number, + outputLength: number, + outputLengthHigh: number, + password: number, + passwordLength: number, + passwordLengthHigh: number, + salt: number, + passes: number, + passesHigh: number, + memoryBytes: number, + algorithm: number, + ): number; + _crypto_verify_32(left: number, right: number): number; + } + export default function sodiumFactory(options: { + getRandomValue(): number; + instantiateWasm( + imports: WebAssembly.Imports, + receive: ( + instance: WebAssembly.Instance, + module: WebAssembly.Module, + ) => void, + ): WebAssembly.Exports; + }): Promise; +} diff --git a/apps/api-cloudflare/src/vendor/libsodium-sumo-0.8.4.wasm b/apps/api-cloudflare/src/vendor/libsodium-sumo-0.8.4.wasm new file mode 100644 index 0000000..1e7c6e1 Binary files /dev/null and b/apps/api-cloudflare/src/vendor/libsodium-sumo-0.8.4.wasm differ diff --git a/apps/api-cloudflare/src/vendor/libsodium-sumo-LICENSE.txt b/apps/api-cloudflare/src/vendor/libsodium-sumo-LICENSE.txt new file mode 100644 index 0000000..1322d77 --- /dev/null +++ b/apps/api-cloudflare/src/vendor/libsodium-sumo-LICENSE.txt @@ -0,0 +1,16 @@ +Copyright (c) 2015-2026 +Ahmad Ben Mrad +Frank Denis +Ryan Lester + +Permission to use, copy, modify, and/or distribute this software for any +purpose with or without fee is hereby granted, provided that the above +copyright notice and this permission notice appear in all copies. + +THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. diff --git a/apps/api-cloudflare/src/workflow.ts b/apps/api-cloudflare/src/workflow.ts new file mode 100644 index 0000000..1e17942 --- /dev/null +++ b/apps/api-cloudflare/src/workflow.ts @@ -0,0 +1,90 @@ +import { + WorkflowEntrypoint, + type WorkflowEvent, + type WorkflowStep, +} from 'cloudflare:workers'; +import { createD1AsyncStore } from '@hyperbug/database-d1'; +import { + runConformanceStep, + validateWorkflowReference, + type WorkflowReference, + type WorkflowAdapter, + type JobStore, +} from '@hyperbug/application'; +import type { D1Database } from '@cloudflare/workers-types'; +/** Only methods used by the adapter; runtime-generated and package bindings differ in optional newer APIs. */ +export interface WorkflowBinding { + create(options: { id: string; params: WorkflowReference }): Promise; + get(id: string): Promise<{ + status(): Promise<{ status: string }>; + restart(): Promise; + resume(): Promise; + terminate(): Promise; + }>; +} + +export function d1JobStore(db: D1Database): JobStore { + const store = createD1AsyncStore(db); + return { ...store, claim: store.claimJob }; +} +export class HyperBugWorkflow extends WorkflowEntrypoint< + { DB: D1Database }, + WorkflowReference +> { + async run(event: WorkflowEvent, step: WorkflowStep) { + const reference = validateWorkflowReference(event.payload), + store = d1JobStore(this.env.DB); + // Named retry-safe steps; large results belong behind artifact references, never step state. + const execute = async ( + index: number, + ): Promise<{ checkpoint: number; terminal: boolean }> => { + if (index >= 16) throw new Error('Workflow step ceiling exhausted'); + const result = await step.do( + `checkpoint-${index}`, + { + retries: { limit: 4, delay: '1 second', backoff: 'exponential' }, + timeout: '1 second', + }, + () => runConformanceStep(store, reference, Date.now, index), + ); + return result.terminal ? result : execute(index + 1); + }; + return execute(0); + } +} +export function createCloudflareWorkflowAdapter( + store: JobStore, + binding: WorkflowBinding, +): WorkflowAdapter { + const start = async (jobId: string, maxSteps: number) => { + await store.create(jobId, maxSteps, Date.now()); + await binding.create({ id: jobId, params: { version: 1, jobId } }); + }; + return { + start, + async resume(jobId) { + validateWorkflowReference({ version: 1, jobId }); + const job = await store.get(jobId); + if (!job) throw new Error('Workflow missing'); + if (job.status === 'completed' || job.status === 'cancelled') return; + let instance; + try { + instance = await binding.get(jobId); + } catch { + // A fixed ID makes creation safe to retry after an ambiguous get failure. + // Creation errors propagate; status/restart errors never trigger creation. + await binding.create({ id: jobId, params: { version: 1, jobId } }); + return; + } + const status = await instance.status(); + if (status.status === 'errored' || status.status === 'terminated') + await instance.restart(); + else if (status.status === 'paused') await instance.resume(); + }, + async cancel(jobId) { + validateWorkflowReference({ version: 1, jobId }); + await store.cancel(jobId, Date.now()); + await (await binding.get(jobId)).terminate(); + }, + }; +} diff --git a/apps/api-cloudflare/tsconfig.ingress.json b/apps/api-cloudflare/tsconfig.ingress.json new file mode 100644 index 0000000..fef7d2e --- /dev/null +++ b/apps/api-cloudflare/tsconfig.ingress.json @@ -0,0 +1,13 @@ +{ + "extends": "../../tsconfig.json", + "compilerOptions": { + "lib": ["ES2023"], + "types": ["@cloudflare/workers-types"] + }, + "include": [ + "src/ingress.ts", + "src/ingress-attestation.ts", + "ingress-configuration.d.ts" + ], + "exclude": ["worker-configuration.d.ts"] +} diff --git a/apps/api-cloudflare/tsconfig.json b/apps/api-cloudflare/tsconfig.json new file mode 100644 index 0000000..205dec1 --- /dev/null +++ b/apps/api-cloudflare/tsconfig.json @@ -0,0 +1,13 @@ +{ + "extends": "../../tsconfig.json", + "compilerOptions": { + "lib": ["ES2023"], + "types": [] + }, + "include": [ + "src/**/*.ts", + "worker-configuration.d.ts", + "../../tests/fixtures/async-workflow-worker.ts" + ], + "exclude": ["src/ingress.ts", "ingress-configuration.d.ts"] +} diff --git a/apps/api-cloudflare/worker-configuration.d.ts b/apps/api-cloudflare/worker-configuration.d.ts new file mode 100644 index 0000000..892afce --- /dev/null +++ b/apps/api-cloudflare/worker-configuration.d.ts @@ -0,0 +1,16114 @@ +/* eslint-disable */ +// Generated by Wrangler by running `wrangler types --config=apps/api-cloudflare/wrangler.jsonc apps/api-cloudflare/worker-configuration.d.ts` (hash: e2165a0d43455aba23ab07c1dec2440c) +// Runtime types generated with workerd@1.20260926.1 2026-09-16 cache_option_enabled,enable_request_signal,nodejs_compat +interface __BaseEnv_Env { + DB?: D1Database; + ABUSE_VOLUMETRIC: RateLimit; + HYPERBUG_ENV: "local" | "staging" | "production"; + ALLOWED_ORIGINS?: "http://localhost:5173"; + HYPERBUG_DEPLOYMENT_TIER?: "cloudflare-minimum"; + HYPERBUG_DEGRADATION_ACK?: "minimum-v2"; + HYPERBUG_KEY_RING: string; + HYPERBUG_ABUSE_KEY_RING: string; + ASYNC_TASKS?: Queue; + TURNSTILE_SECRET?: string; + TURNSTILE_SITE_KEY?: string; + TURNSTILE_HOSTNAME?: string; + ASYNC_WORKFLOW?: Workflow[0]['payload']>; + HYPERBUG_INGRESS_KEY?: string; +} +declare namespace Cloudflare { + interface GlobalProps { + mainModule: typeof import("./src/index"); + } + interface MinimumLocalEnv { + DB: D1Database; + ABUSE_VOLUMETRIC: RateLimit; + HYPERBUG_ENV: "local"; + ALLOWED_ORIGINS: "http://localhost:5173"; + HYPERBUG_DEPLOYMENT_TIER: "cloudflare-minimum"; + HYPERBUG_DEGRADATION_ACK: "minimum-v2"; + HYPERBUG_KEY_RING: string; + HYPERBUG_ABUSE_KEY_RING: string; + } + interface LocalTurnstileEnv { + DB: D1Database; + ASYNC_TASKS: Queue; + ABUSE_VOLUMETRIC: RateLimit; + HYPERBUG_ENV: "local"; + ALLOWED_ORIGINS: "http://localhost:5173"; + HYPERBUG_KEY_RING: string; + HYPERBUG_ABUSE_KEY_RING: string; + TURNSTILE_SECRET: string; + TURNSTILE_SITE_KEY: string; + TURNSTILE_HOSTNAME: string; + ASYNC_WORKFLOW: Workflow[0]['payload']>; + } + interface StagingEnv { + ASYNC_TASKS: Queue; + ABUSE_VOLUMETRIC: RateLimit; + HYPERBUG_ENV: "staging"; + HYPERBUG_KEY_RING: string; + HYPERBUG_ABUSE_KEY_RING: string; + HYPERBUG_INGRESS_KEY: string; + ASYNC_WORKFLOW: Workflow[0]['payload']>; + } + interface ProductionEnv { + ASYNC_TASKS: Queue; + ABUSE_VOLUMETRIC: RateLimit; + HYPERBUG_ENV: "production"; + HYPERBUG_KEY_RING: string; + HYPERBUG_ABUSE_KEY_RING: string; + HYPERBUG_INGRESS_KEY: string; + ASYNC_WORKFLOW: Workflow[0]['payload']>; + } + interface Env extends __BaseEnv_Env {} +} +interface Env extends __BaseEnv_Env {} +type StringifyValues> = { + [Binding in keyof EnvType]: EnvType[Binding] extends string ? EnvType[Binding] : string; +}; +declare namespace NodeJS { + interface ProcessEnv extends StringifyValues> {} +} + +// Begin runtime types +/*! ***************************************************************************** +Copyright (c) Cloudflare. All rights reserved. +Copyright (c) Microsoft Corporation. All rights reserved. + +Licensed under the Apache License, Version 2.0 (the "License"); you may not use +this file except in compliance with the License. You may obtain a copy of the +License at http://www.apache.org/licenses/LICENSE-2.0 +THIS CODE IS PROVIDED ON AN *AS IS* BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY IMPLIED +WARRANTIES OR CONDITIONS OF TITLE, FITNESS FOR A PARTICULAR PURPOSE, +MERCHANTABLITY OR NON-INFRINGEMENT. +See the Apache Version 2.0 License for specific language governing permissions +and limitations under the License. +***************************************************************************** */ +/* eslint-disable */ +// noinspection JSUnusedGlobalSymbols +declare var onmessage: never; +/** + * The **`DOMException`** interface represents an abnormal event (called an exception) that occurs as a result of calling a method or accessing a property of a web API. This is how error conditions are described in web APIs. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMException) + */ +declare class DOMException extends Error { + constructor(message?: string, name?: string); + /** + * The **`message`** read-only property of the DOMException interface returns a string representing a message or description associated with the given error name. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMException/message) + */ + readonly message: string; + /** + * The **`name`** read-only property of the DOMException interface returns a string that contains one of the strings associated with an error name. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMException/name) + */ + readonly name: string; + /** + * The **`code`** read-only property of the DOMException interface returns one of the legacy error code constants, or 0 if none match. + * @deprecated + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMException/code) + */ + readonly code: number; + static readonly INDEX_SIZE_ERR: number; + static readonly DOMSTRING_SIZE_ERR: number; + static readonly HIERARCHY_REQUEST_ERR: number; + static readonly WRONG_DOCUMENT_ERR: number; + static readonly INVALID_CHARACTER_ERR: number; + static readonly NO_DATA_ALLOWED_ERR: number; + static readonly NO_MODIFICATION_ALLOWED_ERR: number; + static readonly NOT_FOUND_ERR: number; + static readonly NOT_SUPPORTED_ERR: number; + static readonly INUSE_ATTRIBUTE_ERR: number; + static readonly INVALID_STATE_ERR: number; + static readonly SYNTAX_ERR: number; + static readonly INVALID_MODIFICATION_ERR: number; + static readonly NAMESPACE_ERR: number; + static readonly INVALID_ACCESS_ERR: number; + static readonly VALIDATION_ERR: number; + static readonly TYPE_MISMATCH_ERR: number; + static readonly SECURITY_ERR: number; + static readonly NETWORK_ERR: number; + static readonly ABORT_ERR: number; + static readonly URL_MISMATCH_ERR: number; + static readonly QUOTA_EXCEEDED_ERR: number; + static readonly TIMEOUT_ERR: number; + static readonly INVALID_NODE_TYPE_ERR: number; + static readonly DATA_CLONE_ERR: number; + get stack(): any; + set stack(value: any); +} +type WorkerGlobalScopeEventMap = { + fetch: FetchEvent; + scheduled: ScheduledEvent; + queue: QueueEvent; + unhandledrejection: PromiseRejectionEvent; + rejectionhandled: PromiseRejectionEvent; +}; +declare abstract class WorkerGlobalScope extends EventTarget { + EventTarget: typeof EventTarget; +} +/* The **`console`** object provides access to the debugging console (e.g., the Web console in Firefox). * + * The **`console`** object provides access to the debugging console (e.g., the Web console in Firefox). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/console) + */ +interface Console { + "assert"(condition?: boolean, ...data: any[]): void; + /** + * The **`console.clear()`** static method clears the console if possible. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/clear_static) + */ + clear(): void; + /** + * The **`console.count()`** static method logs the number of times that this particular call to count() has been called. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/count_static) + */ + count(label?: string): void; + /** + * The **`console.countReset()`** static method resets counter used with console.count(). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/countReset_static) + */ + countReset(label?: string): void; + /** + * The **`console.debug()`** static method outputs a message to the console at the "debug" log level. The message is only displayed to the user if the console is configured to display debug output. In most cases, the log level is configured within the console UI. This log level might correspond to the Debug or Verbose log level. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/debug_static) + */ + debug(...data: any[]): void; + /** + * The **`console.dir()`** static method displays a list of the properties of the specified JavaScript object. In browser consoles, the output is presented as a hierarchical listing with disclosure triangles that let you see the contents of child objects. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/dir_static) + */ + dir(item?: any, options?: any): void; + /** + * The **`console.dirxml()`** static method displays an interactive tree of the descendant elements of the specified XML/HTML element. If it is not possible to display as an element the JavaScript Object view is shown instead. The output is presented as a hierarchical listing of expandable nodes that let you see the contents of child nodes. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/dirxml_static) + */ + dirxml(...data: any[]): void; + /** + * The **`console.error()`** static method outputs a message to the console at the "error" log level. The message is only displayed to the user if the console is configured to display error output. In most cases, the log level is configured within the console UI. The message may be formatted as an error, with red colors and call stack information. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/error_static) + */ + error(...data: any[]): void; + /** + * The **`console.group()`** static method creates a new inline group in the Web console log, causing any subsequent console messages to be indented by an additional level, until console.groupEnd() is called. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/group_static) + */ + group(...data: any[]): void; + /** + * The **`console.groupCollapsed()`** static method creates a new inline group in the console. Unlike console.group(), however, the new group is created collapsed. The user will need to use the disclosure button next to it to expand it, revealing the entries created in the group. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/groupCollapsed_static) + */ + groupCollapsed(...data: any[]): void; + /** + * The **`console.groupEnd()`** static method exits the current inline group in the console. See Using groups in the console in the console documentation for details and examples. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/groupEnd_static) + */ + groupEnd(): void; + /** + * The **`console.info()`** static method outputs a message to the console at the "info" log level. The message is only displayed to the user if the console is configured to display info output. In most cases, the log level is configured within the console UI. The message may receive special formatting, such as a small "i" icon next to it. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/info_static) + */ + info(...data: any[]): void; + /** + * The **`console.log()`** static method outputs a message to the console. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/log_static) + */ + log(...data: any[]): void; + /** + * The **`console.table()`** static method displays tabular data as a table. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/table_static) + */ + table(tabularData?: any, properties?: string[]): void; + /** + * The **`console.time()`** static method starts a timer you can use to track how long an operation takes. You give each timer a unique name, and may have up to 10,000 timers running on a given page. When you call console.timeEnd() with the same name, the browser will output the time, in milliseconds, that elapsed since the timer was started. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/time_static) + */ + time(label?: string): void; + /** + * The **`console.timeEnd()`** static method stops a timer that was previously started by calling console.time(). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/timeEnd_static) + */ + timeEnd(label?: string): void; + /** + * The **`console.timeLog()`** static method logs the current value of a timer that was previously started by calling console.time(). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/timeLog_static) + */ + timeLog(label?: string, ...data: any[]): void; + /* The **`console.timeStamp()`** static method adds a single marker to the browser's Performance tool (Firefox bug 1387528, Chrome). This lets you correlate a point in your code with the other events recorded in the timeline, such as layout and paint events. */ + timeStamp(label?: string): void; + /** + * The **`console.trace()`** static method outputs a stack trace to the console. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/trace_static) + */ + trace(...data: any[]): void; + /** + * The **`console.warn()`** static method outputs a warning message to the console at the "warning" log level. The message is only displayed to the user if the console is configured to display warning output. In most cases, the log level is configured within the console UI. The message may receive special formatting, such as yellow colors and a warning icon. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/warn_static) + */ + warn(...data: any[]): void; +} +declare const console: Console; +type BufferSource = ArrayBufferView | ArrayBuffer; +type TypedArray = Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array | BigInt64Array | BigUint64Array; +declare namespace WebAssembly { + class CompileError extends Error { + constructor(message?: string); + } + class RuntimeError extends Error { + constructor(message?: string); + } + type ValueType = "anyfunc" | "externref" | "f32" | "f64" | "i32" | "i64" | "v128"; + interface GlobalDescriptor { + value: ValueType; + mutable?: boolean; + } + class Global { + constructor(descriptor: GlobalDescriptor, value?: any); + value: any; + valueOf(): any; + } + type ImportValue = ExportValue | number; + type ModuleImports = Record; + type Imports = Record; + type ExportValue = Function | Global | Memory | Table; + type Exports = Record; + class Instance { + constructor(module: Module, imports?: Imports); + readonly exports: Exports; + } + interface MemoryDescriptor { + initial: number; + maximum?: number; + shared?: boolean; + } + class Memory { + constructor(descriptor: MemoryDescriptor); + readonly buffer: ArrayBuffer; + grow(delta: number): number; + } + type ImportExportKind = "function" | "global" | "memory" | "table"; + interface ModuleExportDescriptor { + kind: ImportExportKind; + name: string; + } + interface ModuleImportDescriptor { + kind: ImportExportKind; + module: string; + name: string; + } + abstract class Module { + static customSections(module: Module, sectionName: string): ArrayBuffer[]; + static exports(module: Module): ModuleExportDescriptor[]; + static imports(module: Module): ModuleImportDescriptor[]; + } + type TableKind = "anyfunc" | "externref"; + interface TableDescriptor { + element: TableKind; + initial: number; + maximum?: number; + } + class Table { + constructor(descriptor: TableDescriptor, value?: any); + readonly length: number; + get(index: number): any; + grow(delta: number, value?: any): number; + set(index: number, value?: any): void; + } + function instantiate(module: Module, imports?: Imports): Promise; + function validate(bytes: BufferSource): boolean; +} +/** + * The **`ServiceWorkerGlobalScope`** interface of the Service Worker API represents the global execution context of a service worker. + * Available only in secure contexts. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ServiceWorkerGlobalScope) + */ +interface ServiceWorkerGlobalScope extends WorkerGlobalScope { + DOMException: typeof DOMException; + WorkerGlobalScope: typeof WorkerGlobalScope; + btoa(data: string): string; + atob(data: string): string; + setTimeout(callback: (...args: any[]) => void, msDelay?: number): number; + setTimeout(callback: (...args: Args) => void, msDelay?: number, ...args: Args): number; + clearTimeout(timeoutId: number | null): void; + setInterval(callback: (...args: any[]) => void, msDelay?: number): number; + setInterval(callback: (...args: Args) => void, msDelay?: number, ...args: Args): number; + clearInterval(timeoutId: number | null): void; + queueMicrotask(task: Function): void; + structuredClone(value: T, options?: StructuredSerializeOptions): T; + reportError(error: any): void; + fetch(input: RequestInfo | URL, init?: RequestInit): Promise; + self: ServiceWorkerGlobalScope; + crypto: Crypto; + caches: CacheStorage; + scheduler: Scheduler; + performance: Performance; + Cloudflare: Cloudflare; + readonly origin: string; + Event: typeof Event; + ExtendableEvent: typeof ExtendableEvent; + CustomEvent: typeof CustomEvent; + PromiseRejectionEvent: typeof PromiseRejectionEvent; + FetchEvent: typeof FetchEvent; + TailEvent: typeof TailEvent; + TraceEvent: typeof TailEvent; + ScheduledEvent: typeof ScheduledEvent; + MessageEvent: typeof MessageEvent; + CloseEvent: typeof CloseEvent; + ReadableStreamDefaultReader: typeof ReadableStreamDefaultReader; + ReadableStreamBYOBReader: typeof ReadableStreamBYOBReader; + ReadableStream: typeof ReadableStream; + WritableStream: typeof WritableStream; + WritableStreamDefaultWriter: typeof WritableStreamDefaultWriter; + TransformStream: typeof TransformStream; + ByteLengthQueuingStrategy: typeof ByteLengthQueuingStrategy; + CountQueuingStrategy: typeof CountQueuingStrategy; + ErrorEvent: typeof ErrorEvent; + MessageChannel: typeof MessageChannel; + MessagePort: typeof MessagePort; + EventSource: typeof EventSource; + ReadableStreamBYOBRequest: typeof ReadableStreamBYOBRequest; + ReadableStreamDefaultController: typeof ReadableStreamDefaultController; + ReadableByteStreamController: typeof ReadableByteStreamController; + WritableStreamDefaultController: typeof WritableStreamDefaultController; + TransformStreamDefaultController: typeof TransformStreamDefaultController; + CompressionStream: typeof CompressionStream; + DecompressionStream: typeof DecompressionStream; + TextEncoderStream: typeof TextEncoderStream; + TextDecoderStream: typeof TextDecoderStream; + Headers: typeof Headers; + Body: typeof Body; + Request: typeof Request; + Response: typeof Response; + WebSocket: typeof WebSocket; + WebSocketPair: typeof WebSocketPair; + WebSocketRequestResponsePair: typeof WebSocketRequestResponsePair; + AbortController: typeof AbortController; + AbortSignal: typeof AbortSignal; + TextDecoder: typeof TextDecoder; + TextEncoder: typeof TextEncoder; + navigator: Navigator; + Navigator: typeof Navigator; + URL: typeof URL; + URLSearchParams: typeof URLSearchParams; + URLPattern: typeof URLPattern; + Blob: typeof Blob; + File: typeof File; + FormData: typeof FormData; + Crypto: typeof Crypto; + SubtleCrypto: typeof SubtleCrypto; + CryptoKey: typeof CryptoKey; + CacheStorage: typeof CacheStorage; + Cache: typeof Cache; + FixedLengthStream: typeof FixedLengthStream; + IdentityTransformStream: typeof IdentityTransformStream; + HTMLRewriter: typeof HTMLRewriter; +} +declare function addEventListener(type: Type, handler: EventListenerOrEventListenerObject, options?: EventTargetAddEventListenerOptions | boolean): void; +declare function removeEventListener(type: Type, handler: EventListenerOrEventListenerObject, options?: EventTargetEventListenerOptions | boolean): void; +/** + * The **`dispatchEvent()`** method of the EventTarget sends an Event to the object, (synchronously) invoking the affected event listeners in the appropriate order. The normal event processing rules (including the capturing and optional bubbling phase) also apply to events dispatched manually with dispatchEvent(). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventTarget/dispatchEvent) + */ +declare function dispatchEvent(event: WorkerGlobalScopeEventMap[keyof WorkerGlobalScopeEventMap]): boolean; +/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/btoa) */ +declare function btoa(data: string): string; +/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/atob) */ +declare function atob(data: string): string; +/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/setTimeout) */ +declare function setTimeout(callback: (...args: any[]) => void, msDelay?: number): number; +/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/setTimeout) */ +declare function setTimeout(callback: (...args: Args) => void, msDelay?: number, ...args: Args): number; +/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/clearTimeout) */ +declare function clearTimeout(timeoutId: number | null): void; +/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/setInterval) */ +declare function setInterval(callback: (...args: any[]) => void, msDelay?: number): number; +/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/setInterval) */ +declare function setInterval(callback: (...args: Args) => void, msDelay?: number, ...args: Args): number; +/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/clearInterval) */ +declare function clearInterval(timeoutId: number | null): void; +/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/queueMicrotask) */ +declare function queueMicrotask(task: Function): void; +/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/structuredClone) */ +declare function structuredClone(value: T, options?: StructuredSerializeOptions): T; +/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/reportError) */ +declare function reportError(error: any): void; +/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/fetch) */ +declare function fetch(input: RequestInfo | URL, init?: RequestInit): Promise; +declare const self: ServiceWorkerGlobalScope; +/** +* The Web Crypto API provides a set of low-level functions for common cryptographic tasks. +* The Workers runtime implements the full surface of this API, but with some differences in +* the [supported algorithms](https://developers.cloudflare.com/workers/runtime-apis/web-crypto/#supported-algorithms) +* compared to those implemented in most browsers. +* +* [Cloudflare Docs Reference](https://developers.cloudflare.com/workers/runtime-apis/web-crypto/) +*/ +declare const crypto: Crypto; +/** +* The Cache API allows fine grained control of reading and writing from the Cloudflare global network cache. +* +* [Cloudflare Docs Reference](https://developers.cloudflare.com/workers/runtime-apis/cache/) +*/ +declare const caches: CacheStorage; +/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/scheduler) */ +declare const scheduler: Scheduler; +/** +* The Workers runtime supports a subset of the Performance API, used to measure timing and performance, +* as well as timing of subrequests and other operations. +* +* [Cloudflare Docs Reference](https://developers.cloudflare.com/workers/runtime-apis/performance/) +*/ +declare const performance: Performance; +declare const Cloudflare: Cloudflare; +declare const origin: string; +declare const navigator: Navigator; +interface TestController { +} +interface ExecutionContext { + waitUntil(promise: Promise): void; + passThroughOnException(): void; + readonly exports: Cloudflare.Exports; + readonly props: Props; + cache?: CacheContext; + readonly access?: CloudflareAccessContext; + tracing: Tracing; + abort(reason?: any): void; +} +type ExportedHandlerFetchHandler = (request: Request>, env: Env, ctx: ExecutionContext) => Response | Promise; +type ExportedHandlerConnectHandler = (socket: Socket, env: Env, ctx: ExecutionContext) => void | Promise; +type ExportedHandlerTailHandler = (events: TraceItem[], env: Env, ctx: ExecutionContext) => void | Promise; +type ExportedHandlerTraceHandler = (traces: TraceItem[], env: Env, ctx: ExecutionContext) => void | Promise; +type ExportedHandlerTailStreamHandler = (event: TailStream.TailEvent, env: Env, ctx: ExecutionContext) => TailStream.TailEventHandlerType | undefined | Promise; +type ExportedHandlerScheduledHandler = (controller: ScheduledController, env: Env, ctx: ExecutionContext) => void | Promise; +type ExportedHandlerQueueHandler = (batch: MessageBatch, env: Env, ctx: ExecutionContext) => void | Promise; +type ExportedHandlerTestHandler = (controller: TestController, env: Env, ctx: ExecutionContext) => void | Promise; +interface ExportedHandler { + fetch?: ExportedHandlerFetchHandler; + connect?: ExportedHandlerConnectHandler; + tail?: ExportedHandlerTailHandler; + trace?: ExportedHandlerTraceHandler; + tailStream?: ExportedHandlerTailStreamHandler; + scheduled?: ExportedHandlerScheduledHandler; + test?: ExportedHandlerTestHandler; + email?: EmailExportedHandler; + queue?: ExportedHandlerQueueHandler; +} +interface StructuredSerializeOptions { + transfer?: any[]; +} +declare abstract class Navigator { + sendBeacon(url: string, body?: BodyInit): boolean; + readonly userAgent: string; + readonly hardwareConcurrency: number; + readonly platform: string; + readonly language: string; + readonly languages: string[]; +} +interface AlarmInvocationInfo { + readonly isRetry: boolean; + readonly retryCount: number; + readonly scheduledTime: number; +} +interface Cloudflare { + readonly compatibilityFlags: Record; +} +interface CachePurgeError { + code: number; + message: string; +} +interface CachePurgeResult { + success: boolean; + errors: CachePurgeError[]; +} +interface CachePurgeOptions { + tags?: string[]; + pathPrefixes?: string[]; + purgeEverything?: boolean; +} +interface CacheContext { + purge(options: CachePurgeOptions): Promise; +} +interface CloudflareAccessContext { + readonly aud: string; + getIdentity(): Promise; +} +declare abstract class ColoLocalActorNamespace { + get(actorId: string): Fetcher; +} +interface DurableObject { + fetch(request: Request): Response | Promise; + connect?(socket: Socket): void | Promise; + alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise; + webSocketMessage?(ws: WebSocket, message: string | ArrayBuffer): void | Promise; + webSocketClose?(ws: WebSocket, code: number, reason: string, wasClean: boolean): void | Promise; + webSocketError?(ws: WebSocket, error: unknown): void | Promise; +} +type DurableObjectStub = Fetcher & { + readonly id: DurableObjectId; + readonly name?: string; +}; +interface DurableObjectId { + toString(): string; + equals(other: DurableObjectId): boolean; + readonly name?: string; + readonly jurisdiction?: string; +} +declare abstract class DurableObjectNamespace { + newUniqueId(options?: DurableObjectNamespaceNewUniqueIdOptions): DurableObjectId; + idFromName(name: string): DurableObjectId; + idFromString(id: string): DurableObjectId; + get(id: DurableObjectId, options?: DurableObjectNamespaceGetDurableObjectOptions): DurableObjectStub; + getByName(name: string, options?: DurableObjectNamespaceGetDurableObjectOptions): DurableObjectStub; + jurisdiction(jurisdiction: DurableObjectJurisdiction): DurableObjectNamespace; +} +type DurableObjectJurisdiction = "eu" | "fedramp" | "fedramp-high" | "us"; +interface DurableObjectNamespaceNewUniqueIdOptions { + jurisdiction?: DurableObjectJurisdiction; +} +type DurableObjectLocationHint = "wnam" | "enam" | "sam" | "weur" | "eeur" | "apac" | "apac-ne" | "apac-se" | "oc" | "afr" | "me"; +type DurableObjectRoutingMode = "primary-only"; +interface DurableObjectNamespaceGetDurableObjectOptions { + locationHint?: DurableObjectLocationHint; + routingMode?: DurableObjectRoutingMode; +} +interface DurableObjectClass<_T extends Rpc.DurableObjectBranded | undefined = undefined> { +} +interface DurableObjectState { + waitUntil(promise: Promise): void; + readonly exports: Cloudflare.Exports; + readonly props: Props; + readonly id: DurableObjectId; + readonly storage: DurableObjectStorage; + container?: Container; + facets: DurableObjectFacets; + blockConcurrencyWhile(callback: () => Promise): Promise; + acceptWebSocket(ws: WebSocket, tags?: string[]): void; + getWebSockets(tag?: string): WebSocket[]; + setWebSocketAutoResponse(maybeReqResp?: WebSocketRequestResponsePair): void; + getWebSocketAutoResponse(): WebSocketRequestResponsePair | null; + getWebSocketAutoResponseTimestamp(ws: WebSocket): Date | null; + setHibernatableWebSocketEventTimeout(timeoutMs?: number): void; + getHibernatableWebSocketEventTimeout(): number | null; + getTags(ws: WebSocket): string[]; + abort(reason?: string, options?: DurableObjectAbortOptions): void; +} +interface DurableObjectTransaction { + get(key: string, options?: DurableObjectGetOptions): Promise; + get(keys: string[], options?: DurableObjectGetOptions): Promise>; + list(options?: DurableObjectListOptions): Promise>; + put(key: string, value: T, options?: DurableObjectPutOptions): Promise; + put(entries: Record, options?: DurableObjectPutOptions): Promise; + delete(key: string, options?: DurableObjectPutOptions): Promise; + delete(keys: string[], options?: DurableObjectPutOptions): Promise; + rollback(): void; + getAlarm(options?: DurableObjectGetAlarmOptions): Promise; + setAlarm(scheduledTime: number | Date, options?: DurableObjectSetAlarmOptions): Promise; + deleteAlarm(options?: DurableObjectSetAlarmOptions): Promise; +} +interface DurableObjectStorage { + get(key: string, options?: DurableObjectGetOptions): Promise; + get(keys: string[], options?: DurableObjectGetOptions): Promise>; + list(options?: DurableObjectListOptions): Promise>; + put(key: string, value: T, options?: DurableObjectPutOptions): Promise; + put(entries: Record, options?: DurableObjectPutOptions): Promise; + delete(key: string, options?: DurableObjectPutOptions): Promise; + delete(keys: string[], options?: DurableObjectPutOptions): Promise; + deleteAll(options?: DurableObjectPutOptions): Promise; + transaction(closure: (txn: DurableObjectTransaction) => Promise): Promise; + getAlarm(options?: DurableObjectGetAlarmOptions): Promise; + setAlarm(scheduledTime: number | Date, options?: DurableObjectSetAlarmOptions): Promise; + deleteAlarm(options?: DurableObjectSetAlarmOptions): Promise; + sync(): Promise; + sql: SqlStorage; + kv: SyncKvStorage; + transactionSync(closure: () => T): T; + getCurrentBookmark(): Promise; + getBookmarkForTime(timestamp: number | Date): Promise; + onNextSessionRestoreBookmark(bookmark: string): Promise; +} +interface DurableObjectAbortOptions { + retryAlarm?: boolean; +} +interface DurableObjectListOptions { + start?: string; + startAfter?: string; + end?: string; + prefix?: string; + reverse?: boolean; + limit?: number; + allowConcurrency?: boolean; + noCache?: boolean; +} +interface DurableObjectGetOptions { + allowConcurrency?: boolean; + noCache?: boolean; +} +interface DurableObjectGetAlarmOptions { + allowConcurrency?: boolean; +} +interface DurableObjectPutOptions { + allowConcurrency?: boolean; + allowUnconfirmed?: boolean; + noCache?: boolean; +} +interface DurableObjectSetAlarmOptions { + allowConcurrency?: boolean; + allowUnconfirmed?: boolean; +} +declare class WebSocketRequestResponsePair { + constructor(request: string, response: string); + get request(): string; + get response(): string; +} +interface DurableObjectFacets { + get(name: string, getStartupOptions: () => FacetStartupOptions | Promise>): Fetcher; + abort(name: string, reason: any): void; + delete(name: string): void; + clone(src: string, dst: string): void; +} +interface FacetStartupOptions { + id?: DurableObjectId | string; + class: DurableObjectClass; +} +interface AnalyticsEngineDataset { + writeDataPoint(event?: AnalyticsEngineDataPoint): void; +} +interface AnalyticsEngineDataPoint { + indexes?: ((ArrayBuffer | string) | null)[]; + doubles?: number[]; + blobs?: ((ArrayBuffer | string) | null)[]; +} +/** + * The **`Event`** interface represents an event which takes place on an EventTarget. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event) + */ +declare class Event { + constructor(type: string, init?: EventInit); + /** + * The **`type`** read-only property of the Event interface returns a string containing the event's type. It is set when the event is constructed and is the name commonly used to refer to the specific event, such as click, load, or error. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/type) + */ + get type(): string; + /** + * The **`eventPhase`** read-only property of the Event interface indicates which phase of the event flow is currently being evaluated. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/eventPhase) + */ + get eventPhase(): number; + /** + * The read-only **`composed`** property of the Event interface returns a boolean value which indicates whether or not the event will propagate across the shadow DOM boundary into the standard DOM. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/composed) + */ + get composed(): boolean; + /** + * The **`bubbles`** read-only property of the Event interface indicates whether the event bubbles up through the DOM tree or not. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/bubbles) + */ + get bubbles(): boolean; + /** + * The **`cancelable`** read-only property of the Event interface indicates whether the event can be canceled, and therefore prevented as if the event never happened. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/cancelable) + */ + get cancelable(): boolean; + /** + * The **`defaultPrevented`** read-only property of the Event interface returns a boolean value indicating whether or not the call to Event.preventDefault() canceled the event. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/defaultPrevented) + */ + get defaultPrevented(): boolean; + /** + * The Event property **`returnValue`** indicates whether the default action for this event has been prevented or not. + * @deprecated + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/returnValue) + */ + get returnValue(): boolean; + /** + * The **`currentTarget`** read-only property of the Event interface identifies the element to which the event handler has been attached. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/currentTarget) + */ + get currentTarget(): EventTarget | undefined; + /** + * The read-only **`target`** property of the Event interface is a reference to the object onto which the event was dispatched. It is different from Event.currentTarget when the event handler is called during the bubbling or capturing phase of the event. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/target) + */ + get target(): EventTarget | undefined; + /** + * The deprecated **`Event.srcElement`** is an alias for the Event.target property. Use Event.target instead. + * @deprecated + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/srcElement) + */ + get srcElement(): EventTarget | undefined; + /** + * The **`timeStamp`** read-only property of the Event interface returns the time (in milliseconds) at which the event was created. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/timeStamp) + */ + get timeStamp(): number; + /** + * The **`isTrusted`** read-only property of the Event interface is a boolean value that is true when the event was generated by the user agent (including via user actions and programmatic methods such as HTMLElement.focus()), and false when the event was dispatched via EventTarget.dispatchEvent(). The only exception is the click event, which initializes the isTrusted property to false in user agents. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/isTrusted) + */ + get isTrusted(): boolean; + /** + * The **`cancelBubble`** property of the Event interface is deprecated. Use Event.stopPropagation() instead. Setting its value to true before returning from an event handler prevents propagation of the event. In later implementations, setting this to false does nothing. See Browser compatibility for details. + * @deprecated + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/cancelBubble) + */ + get cancelBubble(): boolean; + /** + * The **`cancelBubble`** property of the Event interface is deprecated. Use Event.stopPropagation() instead. Setting its value to true before returning from an event handler prevents propagation of the event. In later implementations, setting this to false does nothing. See Browser compatibility for details. + * @deprecated + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/cancelBubble) + */ + set cancelBubble(value: boolean); + /** + * The **`stopImmediatePropagation()`** method of the Event interface prevents other listeners of the same event from being called. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/stopImmediatePropagation) + */ + stopImmediatePropagation(): void; + /** + * The **`preventDefault()`** method of the Event interface tells the user agent that the event is being explicitly handled, so its default action, such as page scrolling, link navigation, or pasting text, should not be taken. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/preventDefault) + */ + preventDefault(): void; + /** + * The **`stopPropagation()`** method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases. It does not, however, prevent any default behaviors from occurring; for instance, clicks on links are still processed. If you want to stop those behaviors, see the preventDefault() method. It also does not prevent propagation to other event-handlers of the current element. If you want to stop those, see stopImmediatePropagation(). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/stopPropagation) + */ + stopPropagation(): void; + /** + * The **`composedPath()`** method of the Event interface returns the event's path which is an array of the objects on which listeners will be invoked. This does not include nodes in shadow trees if the shadow root was created with its ShadowRoot.mode closed. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/composedPath) + */ + composedPath(): EventTarget[]; + static readonly NONE: number; + static readonly CAPTURING_PHASE: number; + static readonly AT_TARGET: number; + static readonly BUBBLING_PHASE: number; +} +interface EventInit { + bubbles?: boolean; + cancelable?: boolean; + composed?: boolean; +} +type EventListener = (event: EventType) => void; +interface EventListenerObject { + handleEvent(event: EventType): void; +} +type EventListenerOrEventListenerObject = EventListener | EventListenerObject; +/** + * The **`EventTarget`** interface is implemented by objects that can receive events and may have listeners for them. In other words, any target of events implements the three methods associated with this interface. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventTarget) + */ +declare class EventTarget = Record> { + constructor(); + /** + * The **`addEventListener()`** method of the EventTarget interface sets up a function that will be called whenever the specified event is delivered to the target. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventTarget/addEventListener) + */ + addEventListener(type: Type, handler: EventListenerOrEventListenerObject, options?: EventTargetAddEventListenerOptions | boolean): void; + /** + * The **`removeEventListener()`** method of the EventTarget interface removes an event listener previously registered with EventTarget.addEventListener() from the target. The event listener to be removed is identified using a combination of the event type, the event listener function itself, and various optional options that may affect the matching process; see Matching event listeners for removal. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventTarget/removeEventListener) + */ + removeEventListener(type: Type, handler: EventListenerOrEventListenerObject, options?: EventTargetEventListenerOptions | boolean): void; + /** + * The **`dispatchEvent()`** method of the EventTarget sends an Event to the object, (synchronously) invoking the affected event listeners in the appropriate order. The normal event processing rules (including the capturing and optional bubbling phase) also apply to events dispatched manually with dispatchEvent(). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventTarget/dispatchEvent) + */ + dispatchEvent(event: EventMap[keyof EventMap]): boolean; +} +interface EventTargetEventListenerOptions { + capture?: boolean; +} +interface EventTargetAddEventListenerOptions { + capture?: boolean; + passive?: boolean; + once?: boolean; + signal?: AbortSignal; +} +interface EventTargetHandlerObject { + handleEvent: (event: Event) => any | undefined; +} +/** + * The **`AbortController`** interface represents a controller object that allows you to abort one or more Web requests as and when desired. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortController) + */ +declare class AbortController { + constructor(); + /** + * The **`signal`** read-only property of the AbortController interface returns an AbortSignal object instance, which can be used to communicate with/abort an asynchronous operation as desired. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortController/signal) + */ + get signal(): AbortSignal; + /** + * The **`abort()`** method of the AbortController interface aborts an asynchronous operation before it has completed. This is able to abort fetch requests, the consumption of any response bodies, or streams. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortController/abort) + */ + abort(reason?: any): void; +} +/** + * The **`AbortSignal`** interface represents a signal object that allows you to communicate with an asynchronous operation (such as a fetch request) and abort it if required via an AbortController object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal) + */ +declare abstract class AbortSignal extends EventTarget { + /** + * The **`AbortSignal.abort()`** static method returns an AbortSignal that is already set as aborted (and which does not trigger an abort event). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/abort_static) + */ + static abort(reason?: any): AbortSignal; + /** + * The **`AbortSignal.timeout()`** static method returns an AbortSignal that will automatically abort after a specified time. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/timeout_static) + */ + static timeout(delay: number): AbortSignal; + /** + * The **`AbortSignal.any()`** static method takes an iterable of abort signals and returns an AbortSignal. The returned abort signal is aborted when any of the input iterable abort signals are aborted. The abort reason will be set to the reason of the first signal that is aborted. If any of the given abort signals are already aborted then so will be the returned AbortSignal. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/any_static) + */ + static any(signals: AbortSignal[]): AbortSignal; + /** + * The **`aborted`** read-only property returns a value that indicates whether the asynchronous operations the signal is communicating with are aborted (true) or not (false). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/aborted) + */ + get aborted(): boolean; + /** + * The **`reason`** read-only property returns a JavaScript value that indicates the abort reason. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/reason) + */ + get reason(): any; + /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/abort_event) */ + get onabort(): any | null; + /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/abort_event) */ + set onabort(value: any | null); + /** + * The **`throwIfAborted()`** method throws the signal's abort reason if the signal has been aborted; otherwise it does nothing. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/throwIfAborted) + */ + throwIfAborted(): void; +} +/** + * The **`Scheduler`** interface of the Prioritized Task Scheduling API provides methods for scheduling prioritized tasks. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Scheduler) + */ +interface Scheduler { + wait(delay: number, maybeOptions?: SchedulerWaitOptions): Promise; +} +interface SchedulerWaitOptions { + signal?: AbortSignal; +} +/** + * The **`ExtendableEvent`** interface extends the lifetime of the install and activate events dispatched on the global scope as part of the service worker lifecycle. This ensures that any functional events (like FetchEvent) are not dispatched until it upgrades database schemas and deletes the outdated cache entries. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ExtendableEvent) + */ +declare abstract class ExtendableEvent extends Event { + /** + * The **`ExtendableEvent.waitUntil()`** method tells the event dispatcher that work is ongoing. It can also be used to detect whether that work was successful. In service workers, waitUntil() tells the browser that work is ongoing until the promise settles, and it shouldn't terminate the service worker if it wants that work to complete. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ExtendableEvent/waitUntil) + */ + waitUntil(promise: Promise): void; +} +/** + * The **`CustomEvent`** interface can be used to attach custom data to an event generated by an application. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomEvent) + */ +declare class CustomEvent extends Event { + constructor(type: string, init?: CustomEventCustomEventInit); + /** + * The read-only **`detail`** property of the CustomEvent interface returns any data passed when initializing the event. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomEvent/detail) + */ + get detail(): T; +} +interface CustomEventCustomEventInit { + bubbles?: boolean; + cancelable?: boolean; + composed?: boolean; + detail?: any; +} +/** + * The **`Blob`** interface represents a blob, which is a file-like object of immutable, raw data; they can be read as text or binary data, or converted into a ReadableStream so its methods can be used for processing the data. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob) + */ +declare class Blob { + constructor(bits?: ((ArrayBuffer | ArrayBufferView) | string | Blob)[], options?: BlobOptions); + /** + * The **`size`** read-only property of the Blob interface returns the size of the Blob or File in bytes. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/size) + */ + get size(): number; + /** + * The **`type`** read-only property of the Blob interface returns the MIME type of the file. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/type) + */ + get type(): string; + /** + * The **`slice()`** method of the Blob interface creates and returns a new Blob object which contains data from a subset of the blob on which it's called. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/slice) + */ + slice(start?: number, end?: number, type?: string): Blob; + /** + * The **`arrayBuffer()`** method of the Blob interface returns a Promise that resolves with the contents of the blob as binary data contained in an ArrayBuffer. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/arrayBuffer) + */ + arrayBuffer(): Promise; + /** + * The **`bytes()`** method of the Blob interface returns a Promise that resolves with a Uint8Array containing the contents of the blob as an array of bytes. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/bytes) + */ + bytes(): Promise; + /** + * The **`text()`** method of the Blob interface returns a Promise that resolves with a string containing the contents of the blob, interpreted as UTF-8. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/text) + */ + text(): Promise; + /** + * The **`stream()`** method of the Blob interface returns a ReadableStream which upon reading returns the data contained within the Blob. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/stream) + */ + stream(): ReadableStream; +} +interface BlobOptions { + type?: string; +} +/** + * The **`File`** interface provides information about files and allows JavaScript in a web page to access their content. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/File) + */ +declare class File extends Blob { + constructor(bits: ((ArrayBuffer | ArrayBufferView) | string | Blob)[] | undefined, name: string, options?: FileOptions); + /** + * The **`name`** read-only property of the File interface returns the name of the file represented by a File object. For security reasons, the path is excluded from this property. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/File/name) + */ + get name(): string; + /** + * The **`lastModified`** read-only property of the File interface provides the last modified date of the file as the number of milliseconds since the Unix epoch (January 1, 1970 at midnight). Files without a known last modified date return the current date. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/File/lastModified) + */ + get lastModified(): number; +} +interface FileOptions { + type?: string; + lastModified?: number; +} +/** +* The Cache API allows fine grained control of reading and writing from the Cloudflare global network cache. +* +* [Cloudflare Docs Reference](https://developers.cloudflare.com/workers/runtime-apis/cache/) +*/ +declare abstract class CacheStorage { + /** + * The **`open()`** method of the CacheStorage interface returns a Promise that resolves to the Cache object matching the cacheName. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CacheStorage/open) + */ + open(cacheName: string): Promise; + readonly default: Cache; +} +/** +* The Cache API allows fine grained control of reading and writing from the Cloudflare global network cache. +* +* [Cloudflare Docs Reference](https://developers.cloudflare.com/workers/runtime-apis/cache/) +*/ +declare abstract class Cache { + /* [Cloudflare Docs Reference](https://developers.cloudflare.com/workers/runtime-apis/cache/#delete) */ + delete(request: RequestInfo | URL, options?: CacheQueryOptions): Promise; + /* [Cloudflare Docs Reference](https://developers.cloudflare.com/workers/runtime-apis/cache/#match) */ + match(request: RequestInfo | URL, options?: CacheQueryOptions): Promise; + /* [Cloudflare Docs Reference](https://developers.cloudflare.com/workers/runtime-apis/cache/#put) */ + put(request: RequestInfo | URL, response: Response): Promise; +} +interface CacheQueryOptions { + ignoreMethod?: boolean; +} +/** +* The Web Crypto API provides a set of low-level functions for common cryptographic tasks. +* The Workers runtime implements the full surface of this API, but with some differences in +* the [supported algorithms](https://developers.cloudflare.com/workers/runtime-apis/web-crypto/#supported-algorithms) +* compared to those implemented in most browsers. +* +* [Cloudflare Docs Reference](https://developers.cloudflare.com/workers/runtime-apis/web-crypto/) +*/ +declare abstract class Crypto { + /** + * The **`Crypto.subtle`** read-only property returns a SubtleCrypto which can then be used to perform low-level cryptographic operations. + * Available only in secure contexts. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Crypto/subtle) + */ + get subtle(): SubtleCrypto; + /** + * The **`Crypto.getRandomValues()`** method lets you get cryptographically strong random values. The array given as the parameter is filled with random numbers (random in its cryptographic meaning). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Crypto/getRandomValues) + */ + getRandomValues(buffer: T): T; + /** + * The **`randomUUID()`** method of the Crypto interface is used to generate a v4 UUID using a cryptographically secure random number generator. + * Available only in secure contexts. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Crypto/randomUUID) + */ + randomUUID(): string; + DigestStream: typeof DigestStream; +} +/** + * The **`SubtleCrypto`** interface of the Web Crypto API provides a number of low-level cryptographic functions. + * Available only in secure contexts. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/SubtleCrypto) + */ +declare abstract class SubtleCrypto { + /** + * The **`encrypt()`** method of the SubtleCrypto interface encrypts data. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/SubtleCrypto/encrypt) + */ + encrypt(algorithm: string | SubtleCryptoEncryptAlgorithm, key: CryptoKey, plainText: ArrayBuffer | ArrayBufferView): Promise; + /** + * The **`decrypt()`** method of the SubtleCrypto interface decrypts some encrypted data. It takes as arguments a key to decrypt with, some optional extra parameters, and the data to decrypt (also known as "ciphertext"). It returns a Promise which will be fulfilled with the decrypted data (also known as "plaintext"). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/SubtleCrypto/decrypt) + */ + decrypt(algorithm: string | SubtleCryptoEncryptAlgorithm, key: CryptoKey, cipherText: ArrayBuffer | ArrayBufferView): Promise; + /** + * The **`sign()`** method of the SubtleCrypto interface generates a digital signature. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/SubtleCrypto/sign) + */ + sign(algorithm: string | SubtleCryptoSignAlgorithm, key: CryptoKey, data: ArrayBuffer | ArrayBufferView): Promise; + /** + * The **`verify()`** method of the SubtleCrypto interface verifies a digital signature. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/SubtleCrypto/verify) + */ + verify(algorithm: string | SubtleCryptoSignAlgorithm, key: CryptoKey, signature: ArrayBuffer | ArrayBufferView, data: ArrayBuffer | ArrayBufferView): Promise; + /** + * The **`digest()`** method of the SubtleCrypto interface generates a digest of the given data, using the specified hash function. A digest is a short fixed-length value derived from some variable-length input. Cryptographic digests should exhibit collision-resistance, meaning that it's hard to come up with two different inputs that have the same digest value. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/SubtleCrypto/digest) + */ + digest(algorithm: string | SubtleCryptoHashAlgorithm, data: ArrayBuffer | ArrayBufferView): Promise; + /** + * The **`generateKey()`** method of the SubtleCrypto interface is used to generate a new key (for symmetric algorithms) or key pair (for public-key algorithms). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/SubtleCrypto/generateKey) + */ + generateKey(algorithm: string | SubtleCryptoGenerateKeyAlgorithm, extractable: boolean, keyUsages: string[]): Promise; + /** + * The **`deriveKey()`** method of the SubtleCrypto interface can be used to derive a secret key from a master key. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/SubtleCrypto/deriveKey) + */ + deriveKey(algorithm: string | SubtleCryptoDeriveKeyAlgorithm, baseKey: CryptoKey, derivedKeyAlgorithm: string | SubtleCryptoImportKeyAlgorithm, extractable: boolean, keyUsages: string[]): Promise; + /** + * The **`deriveBits()`** method of the SubtleCrypto interface can be used to derive an array of bits from a base key. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/SubtleCrypto/deriveBits) + */ + deriveBits(algorithm: string | SubtleCryptoDeriveKeyAlgorithm, baseKey: CryptoKey, length?: number | null): Promise; + /** + * The **`importKey()`** method of the SubtleCrypto interface imports a key: that is, it takes as input a key in an external, portable format and gives you a CryptoKey object that you can use in the Web Crypto API. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/SubtleCrypto/importKey) + */ + importKey(format: string, keyData: (ArrayBuffer | ArrayBufferView) | JsonWebKey, algorithm: string | SubtleCryptoImportKeyAlgorithm, extractable: boolean, keyUsages: string[]): Promise; + /** + * The **`exportKey()`** method of the SubtleCrypto interface exports a key: that is, it takes as input a CryptoKey object and gives you the key in an external, portable format. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/SubtleCrypto/exportKey) + */ + exportKey(format: string, key: CryptoKey): Promise; + /** + * The **`wrapKey()`** method of the SubtleCrypto interface "wraps" a key. This means that it exports the key in an external, portable format, then encrypts the exported key. Wrapping a key helps protect it in untrusted environments, such as inside an otherwise unprotected data store or in transmission over an unprotected network. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/SubtleCrypto/wrapKey) + */ + wrapKey(format: string, key: CryptoKey, wrappingKey: CryptoKey, wrapAlgorithm: string | SubtleCryptoEncryptAlgorithm): Promise; + /** + * The **`unwrapKey()`** method of the SubtleCrypto interface "unwraps" a key. This means that it takes as its input a key that has been exported and then encrypted (also called "wrapped"). It decrypts the key and then imports it, returning a CryptoKey object that can be used in the Web Crypto API. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/SubtleCrypto/unwrapKey) + */ + unwrapKey(format: string, wrappedKey: ArrayBuffer | ArrayBufferView, unwrappingKey: CryptoKey, unwrapAlgorithm: string | SubtleCryptoEncryptAlgorithm, unwrappedKeyAlgorithm: string | SubtleCryptoImportKeyAlgorithm, extractable: boolean, keyUsages: string[]): Promise; + timingSafeEqual(a: ArrayBuffer | ArrayBufferView, b: ArrayBuffer | ArrayBufferView): boolean; +} +/** + * The **`CryptoKey`** interface of the Web Crypto API represents a cryptographic key obtained from one of the SubtleCrypto methods generateKey(), deriveKey(), importKey(), or unwrapKey(). + * Available only in secure contexts. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CryptoKey) + */ +declare abstract class CryptoKey { + /** + * The read-only **`type`** property of the CryptoKey interface indicates which kind of key is represented by the object. It can have the following values: + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CryptoKey/type) + */ + readonly type: string; + /** + * The read-only **`extractable`** property of the CryptoKey interface indicates whether or not the key may be extracted using SubtleCrypto.exportKey() or SubtleCrypto.wrapKey(). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CryptoKey/extractable) + */ + readonly extractable: boolean; + /** + * The read-only **`algorithm`** property of the CryptoKey interface returns an object describing the algorithm for which this key can be used, and any associated extra parameters. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CryptoKey/algorithm) + */ + readonly algorithm: CryptoKeyKeyAlgorithm | CryptoKeyAesKeyAlgorithm | CryptoKeyHmacKeyAlgorithm | CryptoKeyRsaKeyAlgorithm | CryptoKeyEllipticKeyAlgorithm | CryptoKeyArbitraryKeyAlgorithm; + /** + * The read-only **`usages`** property of the CryptoKey interface indicates what can be done with the key. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CryptoKey/usages) + */ + readonly usages: string[]; +} +interface CryptoKeyPair { + publicKey: CryptoKey; + privateKey: CryptoKey; +} +interface JsonWebKey { + kty: string; + use?: string; + key_ops?: string[]; + alg?: string; + ext?: boolean; + crv?: string; + x?: string; + y?: string; + d?: string; + n?: string; + e?: string; + p?: string; + q?: string; + dp?: string; + dq?: string; + qi?: string; + oth?: RsaOtherPrimesInfo[]; + k?: string; +} +interface RsaOtherPrimesInfo { + r?: string; + d?: string; + t?: string; +} +interface SubtleCryptoDeriveKeyAlgorithm { + name: string; + salt?: (ArrayBuffer | ArrayBufferView); + iterations?: number; + hash?: (string | SubtleCryptoHashAlgorithm); + $public?: CryptoKey; + info?: (ArrayBuffer | ArrayBufferView); +} +interface SubtleCryptoEncryptAlgorithm { + name: string; + iv?: (ArrayBuffer | ArrayBufferView); + additionalData?: (ArrayBuffer | ArrayBufferView); + tagLength?: number; + counter?: (ArrayBuffer | ArrayBufferView); + length?: number; + label?: (ArrayBuffer | ArrayBufferView); +} +interface SubtleCryptoGenerateKeyAlgorithm { + name: string; + hash?: (string | SubtleCryptoHashAlgorithm); + modulusLength?: number; + publicExponent?: (ArrayBuffer | ArrayBufferView); + length?: number; + namedCurve?: string; +} +interface SubtleCryptoHashAlgorithm { + name: string; +} +interface SubtleCryptoImportKeyAlgorithm { + name: string; + hash?: (string | SubtleCryptoHashAlgorithm); + length?: number; + namedCurve?: string; + compressed?: boolean; +} +interface SubtleCryptoSignAlgorithm { + name: string; + hash?: (string | SubtleCryptoHashAlgorithm); + dataLength?: number; + saltLength?: number; +} +interface CryptoKeyKeyAlgorithm { + name: string; +} +interface CryptoKeyAesKeyAlgorithm { + name: string; + length: number; +} +interface CryptoKeyHmacKeyAlgorithm { + name: string; + hash: CryptoKeyKeyAlgorithm; + length: number; +} +interface CryptoKeyRsaKeyAlgorithm { + name: string; + modulusLength: number; + publicExponent: ArrayBuffer | ArrayBufferView; + hash?: CryptoKeyKeyAlgorithm; +} +interface CryptoKeyEllipticKeyAlgorithm { + name: string; + namedCurve: string; +} +interface CryptoKeyArbitraryKeyAlgorithm { + name: string; + hash?: CryptoKeyKeyAlgorithm; + namedCurve?: string; + length?: number; +} +declare class DigestStream extends WritableStream { + constructor(algorithm: string | SubtleCryptoHashAlgorithm, options?: DigestStreamOptions); + readonly digest: Promise; + get bytesWritten(): number | bigint; +} +interface DigestStreamOptions { + toWellFormed?: boolean; +} +/** + * The **`TextDecoder`** interface represents a decoder for a specific text encoding, such as UTF-8, ISO-8859-2, or GBK. A decoder takes an array of bytes as input and returns a JavaScript string. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/TextDecoder) + */ +declare class TextDecoder { + constructor(label?: string, options?: TextDecoderConstructorOptions); + /** + * The **`TextDecoder.decode()`** method returns a string containing text decoded from the buffer passed as a parameter. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/TextDecoder/decode) + */ + decode(input?: (ArrayBuffer | ArrayBufferView), options?: TextDecoderDecodeOptions): string; + get encoding(): string; + get fatal(): boolean; + get ignoreBOM(): boolean; +} +/** + * The **`TextEncoder`** interface enables you to encode a JavaScript string using UTF-8. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/TextEncoder) + */ +declare class TextEncoder { + constructor(); + /** + * The **`TextEncoder.encode()`** method takes a string as input, and returns a Uint8Array containing the string encoded using UTF-8. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/TextEncoder/encode) + */ + encode(input?: string): Uint8Array; + /** + * The **`TextEncoder.encodeInto()`** method takes a string to encode and a destination Uint8Array to put resulting UTF-8 encoded text into, and returns an object indicating the progress of the encoding. This is potentially more performant than the encode() method — especially when the target buffer is a view into a Wasm heap. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/TextEncoder/encodeInto) + */ + encodeInto(input: string, buffer: Uint8Array): TextEncoderEncodeIntoResult; + get encoding(): string; +} +interface TextDecoderConstructorOptions { + fatal: boolean; + ignoreBOM: boolean; +} +interface TextDecoderDecodeOptions { + stream: boolean; +} +interface TextEncoderEncodeIntoResult { + read: number; + written: number; +} +/** + * The **`ErrorEvent`** interface represents events providing information related to errors in scripts or in files. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ErrorEvent) + */ +declare class ErrorEvent extends Event { + constructor(type: string, init?: ErrorEventErrorEventInit); + /** + * The **`filename`** read-only property of the ErrorEvent interface returns a string containing the name of the script file in which the error occurred. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ErrorEvent/filename) + */ + get filename(): string; + /** + * The **`message`** read-only property of the ErrorEvent interface returns a string containing a human-readable error message describing the problem. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ErrorEvent/message) + */ + get message(): string; + /** + * The **`lineno`** read-only property of the ErrorEvent interface returns an integer containing the line number of the script file on which the error occurred. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ErrorEvent/lineno) + */ + get lineno(): number; + /** + * The **`colno`** read-only property of the ErrorEvent interface returns an integer containing the column number of the script file on which the error occurred. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ErrorEvent/colno) + */ + get colno(): number; + /** + * The **`error`** read-only property of the ErrorEvent interface returns a JavaScript value, such as an Error or DOMException, representing the error associated with this event. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ErrorEvent/error) + */ + get error(): any; +} +interface ErrorEventErrorEventInit { + bubbles?: boolean; + cancelable?: boolean; + composed?: boolean; + message?: string; + filename?: string; + lineno?: number; + colno?: number; + error?: any; +} +/** + * The **`MessageEvent`** interface represents a message received by a target object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/MessageEvent) + */ +declare class MessageEvent extends Event { + constructor(type: string, initializer?: MessageEventInit); + /** + * The **`data`** read-only property of the MessageEvent interface represents the data sent by the message emitter. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/MessageEvent/data) + */ + readonly data: any; + /** + * The **`origin`** read-only property of the MessageEvent interface is a string representing the origin of the message emitter. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/MessageEvent/origin) + */ + readonly origin: string | null; + /** + * The **`lastEventId`** read-only property of the MessageEvent interface is a string representing a unique ID for the event. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/MessageEvent/lastEventId) + */ + readonly lastEventId: string; + /** + * The **`source`** read-only property of the MessageEvent interface is a MessageEventSource (which can be a WindowProxy, MessagePort, or ServiceWorker object) representing the message emitter. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/MessageEvent/source) + */ + readonly source: MessagePort | null; + /** + * The **`ports`** read-only property of the MessageEvent interface is an array of MessagePort objects containing all MessagePort objects sent with the message, in order. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/MessageEvent/ports) + */ + readonly ports: MessagePort[]; +} +interface MessageEventInit { + bubbles?: boolean; + cancelable?: boolean; + composed?: boolean; + data?: any; + origin?: string; + lastEventId?: string; + source?: (MessagePort | null); + ports?: MessagePort[]; +} +/** + * The **`PromiseRejectionEvent`** interface represents events which are sent to the global script context when JavaScript Promises are rejected. These events are particularly useful for telemetry and debugging purposes. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/PromiseRejectionEvent) + */ +declare abstract class PromiseRejectionEvent extends Event { + /** + * The PromiseRejectionEvent interface's **`promise`** read-only property indicates the JavaScript Promise which was rejected. You can examine the event's PromiseRejectionEvent.reason property to learn why the promise was rejected. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/PromiseRejectionEvent/promise) + */ + readonly promise: Promise; + /** + * The PromiseRejectionEvent **`reason`** read-only property is any JavaScript value or Object which provides the reason passed into Promise.reject(). This in theory provides information about why the promise was rejected. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/PromiseRejectionEvent/reason) + */ + readonly reason: any; +} +/** + * The **`FormData`** interface provides a way to construct a set of key/value pairs representing form fields and their values, which can be sent using the fetch(), XMLHttpRequest.send() or navigator.sendBeacon() methods. It uses the same format a form would use if the encoding type were set to "multipart/form-data". + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData) + */ +declare class FormData { + constructor(); + /** + * The **`append()`** method of the FormData interface appends a new value onto an existing key inside a FormData object, or adds the key if it does not already exist. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData/append) + */ + append(name: string, value: string | Blob): void; + /** + * The **`append()`** method of the FormData interface appends a new value onto an existing key inside a FormData object, or adds the key if it does not already exist. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData/append) + */ + append(name: string, value: string): void; + /** + * The **`append()`** method of the FormData interface appends a new value onto an existing key inside a FormData object, or adds the key if it does not already exist. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData/append) + */ + append(name: string, value: Blob, filename?: string): void; + /** + * The **`delete()`** method of the FormData interface deletes a key and its value(s) from a FormData object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData/delete) + */ + delete(name: string): void; + /** + * The **`get()`** method of the FormData interface returns the first value associated with a given key from within a FormData object. If you expect multiple values and want all of them, use the getAll() method instead. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData/get) + */ + get(name: string): (File | string) | null; + /** + * The **`getAll()`** method of the FormData interface returns all the values associated with a given key from within a FormData object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData/getAll) + */ + getAll(name: string): (File | string)[]; + /** + * The **`has()`** method of the FormData interface returns whether a FormData object contains a certain key. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData/has) + */ + has(name: string): boolean; + /** + * The **`set()`** method of the FormData interface sets a new value for an existing key inside a FormData object, or adds the key/value if it does not already exist. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData/set) + */ + set(name: string, value: string | Blob): void; + /** + * The **`set()`** method of the FormData interface sets a new value for an existing key inside a FormData object, or adds the key/value if it does not already exist. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData/set) + */ + set(name: string, value: string): void; + /** + * The **`set()`** method of the FormData interface sets a new value for an existing key inside a FormData object, or adds the key/value if it does not already exist. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData/set) + */ + set(name: string, value: Blob, filename?: string): void; + entries(): IterableIterator<[ + key: string, + value: File | string + ]>; + keys(): IterableIterator; + values(): IterableIterator<(File | string)>; + forEach(callback: (this: This, value: File | string, key: string, parent: FormData) => void, thisArg?: This): void; + [Symbol.iterator](): IterableIterator<[ + key: string, + value: File | string + ]>; +} +interface ContentOptions { + html?: boolean; +} +declare class HTMLRewriter { + constructor(); + on(selector: string, handlers: HTMLRewriterElementContentHandlers): HTMLRewriter; + onDocument(handlers: HTMLRewriterDocumentContentHandlers): HTMLRewriter; + transform(response: Response): Response; +} +interface HTMLRewriterElementContentHandlers { + element?(element: Element): void | Promise; + comments?(comment: Comment): void | Promise; + text?(element: Text): void | Promise; +} +interface HTMLRewriterDocumentContentHandlers { + doctype?(doctype: Doctype): void | Promise; + comments?(comment: Comment): void | Promise; + text?(text: Text): void | Promise; + end?(end: DocumentEnd): void | Promise; +} +interface Doctype { + readonly name: string | null; + readonly publicId: string | null; + readonly systemId: string | null; +} +interface Element { + tagName: string; + readonly attributes: IterableIterator; + readonly removed: boolean; + readonly namespaceURI: string; + getAttribute(name: string): string | null; + hasAttribute(name: string): boolean; + setAttribute(name: string, value: string): Element; + removeAttribute(name: string): Element; + before(content: string | ReadableStream | Response, options?: ContentOptions): Element; + after(content: string | ReadableStream | Response, options?: ContentOptions): Element; + prepend(content: string | ReadableStream | Response, options?: ContentOptions): Element; + append(content: string | ReadableStream | Response, options?: ContentOptions): Element; + replace(content: string | ReadableStream | Response, options?: ContentOptions): Element; + remove(): Element; + removeAndKeepContent(): Element; + setInnerContent(content: string | ReadableStream | Response, options?: ContentOptions): Element; + onEndTag(handler: (tag: EndTag) => void | Promise): void; +} +interface EndTag { + name: string; + before(content: string | ReadableStream | Response, options?: ContentOptions): EndTag; + after(content: string | ReadableStream | Response, options?: ContentOptions): EndTag; + remove(): EndTag; +} +interface Comment { + text: string; + readonly removed: boolean; + before(content: string, options?: ContentOptions): Comment; + after(content: string, options?: ContentOptions): Comment; + replace(content: string, options?: ContentOptions): Comment; + remove(): Comment; +} +interface Text { + readonly text: string; + readonly lastInTextNode: boolean; + readonly removed: boolean; + before(content: string | ReadableStream | Response, options?: ContentOptions): Text; + after(content: string | ReadableStream | Response, options?: ContentOptions): Text; + replace(content: string | ReadableStream | Response, options?: ContentOptions): Text; + remove(): Text; +} +interface DocumentEnd { + append(content: string, options?: ContentOptions): DocumentEnd; +} +/** + * This is the event type for fetch events dispatched on the service worker global scope. It contains information about the fetch, including the request and how the receiver will treat the response. It provides the event.respondWith() method, which allows us to provide a response to this fetch. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FetchEvent) + */ +declare abstract class FetchEvent extends ExtendableEvent { + /** + * The **`request`** read-only property of the FetchEvent interface returns the Request that triggered the event handler. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FetchEvent/request) + */ + readonly request: Request; + /** + * The **`respondWith()`** method of FetchEvent prevents the browser's default fetch handling, and allows you to provide a promise for a Response yourself. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FetchEvent/respondWith) + */ + respondWith(promise: Response | Promise): void; + passThroughOnException(): void; +} +type HeadersInit = Headers | Iterable> | Record; +/** + * The **`Headers`** interface of the Fetch API allows you to perform various actions on HTTP request and response headers. These actions include retrieving, setting, adding to, and removing headers from the list of the request's headers. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Headers) + */ +declare class Headers { + constructor(init?: HeadersInit); + /** + * The **`get()`** method of the Headers interface returns a byte string of all the values of a header within a Headers object with a given name. If the requested header doesn't exist in the Headers object, it returns null. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Headers/get) + */ + get(name: string): string | null; + getAll(name: string): string[]; + /** + * The **`getSetCookie()`** method of the Headers interface returns an array containing the values of all Set-Cookie headers associated with a response. This allows Headers objects to handle having multiple Set-Cookie headers, which wasn't possible prior to its implementation. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Headers/getSetCookie) + */ + getSetCookie(): string[]; + /** + * The **`has()`** method of the Headers interface returns a boolean stating whether a Headers object contains a certain header. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Headers/has) + */ + has(name: string): boolean; + /** + * The **`set()`** method of the Headers interface sets a new value for an existing header inside a Headers object, or adds the header if it does not already exist. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Headers/set) + */ + set(name: string, value: string): void; + /** + * The **`append()`** method of the Headers interface appends a new value onto an existing header inside a Headers object, or adds the header if it does not already exist. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Headers/append) + */ + append(name: string, value: string): void; + /** + * The **`delete()`** method of the Headers interface deletes a header from the current Headers object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Headers/delete) + */ + delete(name: string): void; + forEach(callback: (this: This, value: string, key: string, parent: Headers) => void, thisArg?: This): void; + entries(): IterableIterator<[ + key: string, + value: string + ]>; + keys(): IterableIterator; + values(): IterableIterator; + [Symbol.iterator](): IterableIterator<[ + key: string, + value: string + ]>; +} +type BodyInit = ReadableStream | string | ArrayBuffer | ArrayBufferView | Blob | URLSearchParams | FormData | Iterable | AsyncIterable; +declare abstract class Body { + /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/body) */ + get body(): ReadableStream | null; + /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/bodyUsed) */ + get bodyUsed(): boolean; + /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/arrayBuffer) */ + arrayBuffer(): Promise; + /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/bytes) */ + bytes(): Promise; + /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/text) */ + text(): Promise; + /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/json) */ + json(): Promise; + /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/formData) */ + formData(): Promise; + /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/blob) */ + blob(): Promise; +} +/** + * The **`Response`** interface of the Fetch API represents the response to a request. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response) + */ +declare var Response: { + prototype: Response; + new (body?: BodyInit | null, init?: ResponseInit): Response; + error(): Response; + redirect(url: string, status?: number): Response; + json(any: any, maybeInit?: (ResponseInit | Response)): Response; +}; +/** + * The **`Response`** interface of the Fetch API represents the response to a request. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response) + */ +interface Response extends Body { + /** + * The **`clone()`** method of the Response interface creates a clone of a response object, identical in every way, but stored in a different variable. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/clone) + */ + clone(): Response; + /** + * The **`status`** read-only property of the Response interface contains the HTTP status codes of the response. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/status) + */ + status: number; + /** + * The **`statusText`** read-only property of the Response interface contains the status message corresponding to the HTTP status code in Response.status. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/statusText) + */ + statusText: string; + /** + * The **`headers`** read-only property of the Response interface contains the Headers object associated with the response. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/headers) + */ + headers: Headers; + /** + * The **`ok`** read-only property of the Response interface contains a Boolean stating whether the response was successful (status in the range 200-299) or not. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/ok) + */ + ok: boolean; + /** + * The **`redirected`** read-only property of the Response interface indicates whether or not the response is the result of a request you made which was redirected. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/redirected) + */ + redirected: boolean; + /** + * The **`url`** read-only property of the Response interface contains the URL of the response. The value of the url property will be the final URL obtained after any redirects. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/url) + */ + url: string; + webSocket: WebSocket | null; + cf: any | undefined; + /** + * The **`type`** read-only property of the Response interface contains the type of the response. The type determines whether scripts are able to access the response body and headers. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/type) + */ + type: "default" | "error"; +} +interface ResponseInit { + status?: number; + statusText?: string; + headers?: HeadersInit; + cf?: any; + webSocket?: (WebSocket | null); + encodeBody?: "automatic" | "manual"; +} +type RequestInfo> = Request | string; +/** + * The **`Request`** interface of the Fetch API represents a resource request. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request) + */ +declare var Request: { + prototype: Request; + new >(input: RequestInfo | URL, init?: RequestInit): Request; +}; +/** + * The **`Request`** interface of the Fetch API represents a resource request. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request) + */ +interface Request> extends Body { + /** + * The **`clone()`** method of the Request interface creates a copy of the current Request object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/clone) + */ + clone(): Request; + /** + * The **`method`** read-only property of the Request interface contains the request's method (GET, POST, etc.) + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/method) + */ + method: string; + /** + * The **`url`** read-only property of the Request interface contains the URL of the request. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/url) + */ + url: string; + /** + * The **`headers`** read-only property of the Request interface contains the Headers object associated with the request. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/headers) + */ + headers: Headers; + /** + * The **`redirect`** read-only property of the Request interface contains the mode for how redirects are handled. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/redirect) + */ + redirect: string; + fetcher: Fetcher | null; + /** + * The read-only **`signal`** property of the Request interface returns the AbortSignal associated with the request. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/signal) + */ + signal: AbortSignal; + cf?: Cf; + /** + * The **`integrity`** read-only property of the Request interface contains the subresource integrity value of the request. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/integrity) + */ + integrity: string; + /** + * The **`keepalive`** read-only property of the Request interface contains the request's keepalive setting (true or false), which indicates whether the browser will keep the associated request alive if the page that initiated it is unloaded before the request is complete. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/keepalive) + */ + keepalive: boolean; + /** + * The **`cache`** read-only property of the Request interface contains the cache mode of the request. It controls how the request will interact with the browser's HTTP cache. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/cache) + */ + cache?: "no-store" | "no-cache"; +} +interface RequestInit { + /* A string to set request's method. */ + method?: string; + /* A Headers object, an object literal, or an array of two-item arrays to set request's headers. */ + headers?: HeadersInit; + /* A BodyInit object or null to set request's body. */ + body?: BodyInit | null; + /* A string indicating whether request follows redirects, results in an error upon encountering a redirect, or returns the redirect (in an opaque fashion). Sets request's redirect. */ + redirect?: string; + fetcher?: (Fetcher | null); + cf?: Cf; + /* A string indicating how the request will interact with the browser's cache to set request's cache. */ + cache?: "no-store" | "no-cache"; + /* A cryptographic hash of the resource to be fetched by request. Sets request's integrity. */ + integrity?: string; + /* An AbortSignal to set request's signal. */ + signal?: (AbortSignal | null); + encodeResponseBody?: "automatic" | "manual"; +} +type Service Rpc.WorkerEntrypointBranded) | Rpc.WorkerEntrypointBranded | ExportedHandler | undefined = undefined> = T extends new (...args: any[]) => Rpc.WorkerEntrypointBranded ? Fetcher> : T extends Rpc.WorkerEntrypointBranded ? Fetcher : T extends Exclude ? never : Fetcher; +type Fetcher = (T extends Rpc.EntrypointBranded ? Rpc.Provider : unknown) & { + fetch(input: RequestInfo | URL, init?: RequestInit): Promise; + connect(address: SocketAddress | string, options?: SocketOptions): Socket; +}; +interface KVNamespaceListKey { + name: Key; + expiration?: number; + metadata?: Metadata; +} +type KVNamespaceListResult = { + list_complete: false; + keys: KVNamespaceListKey[]; + cursor: string; + cacheStatus: string | null; +} | { + list_complete: true; + keys: KVNamespaceListKey[]; + cacheStatus: string | null; +}; +interface KVNamespace { + get(key: Key, options?: Partial>): Promise; + get(key: Key, type: "text"): Promise; + get(key: Key, type: "json"): Promise; + get(key: Key, type: "arrayBuffer"): Promise; + get(key: Key, type: "stream"): Promise; + get(key: Key, options?: KVNamespaceGetOptions<"text">): Promise; + get(key: Key, options?: KVNamespaceGetOptions<"json">): Promise; + get(key: Key, options?: KVNamespaceGetOptions<"arrayBuffer">): Promise; + get(key: Key, options?: KVNamespaceGetOptions<"stream">): Promise; + get(key: Array, type: "text"): Promise>; + get(key: Array, type: "json"): Promise>; + get(key: Array, options?: Partial>): Promise>; + get(key: Array, options?: KVNamespaceGetOptions<"text">): Promise>; + get(key: Array, options?: KVNamespaceGetOptions<"json">): Promise>; + list(options?: KVNamespaceListOptions): Promise>; + put(key: Key, value: string | ArrayBuffer | ArrayBufferView | ReadableStream, options?: KVNamespacePutOptions): Promise; + getWithMetadata(key: Key, options?: Partial>): Promise>; + getWithMetadata(key: Key, type: "text"): Promise>; + getWithMetadata(key: Key, type: "json"): Promise>; + getWithMetadata(key: Key, type: "arrayBuffer"): Promise>; + getWithMetadata(key: Key, type: "stream"): Promise>; + getWithMetadata(key: Key, options: KVNamespaceGetOptions<"text">): Promise>; + getWithMetadata(key: Key, options: KVNamespaceGetOptions<"json">): Promise>; + getWithMetadata(key: Key, options: KVNamespaceGetOptions<"arrayBuffer">): Promise>; + getWithMetadata(key: Key, options: KVNamespaceGetOptions<"stream">): Promise>; + getWithMetadata(key: Array, type: "text"): Promise>>; + getWithMetadata(key: Array, type: "json"): Promise>>; + getWithMetadata(key: Array, options?: Partial>): Promise>>; + getWithMetadata(key: Array, options?: KVNamespaceGetOptions<"text">): Promise>>; + getWithMetadata(key: Array, options?: KVNamespaceGetOptions<"json">): Promise>>; + delete(key: Key): Promise; +} +interface KVNamespaceListOptions { + limit?: number; + prefix?: (string | null); + cursor?: (string | null); +} +interface KVNamespaceGetOptions { + type: Type; + cacheTtl?: number; +} +interface KVNamespacePutOptions { + expiration?: number; + expirationTtl?: number; + metadata?: (any | null); +} +interface KVNamespaceGetWithMetadataResult { + value: Value | null; + metadata: Metadata | null; + cacheStatus: string | null; +} +type QueueContentType = "text" | "bytes" | "json" | "v8"; +interface Queue { + metrics(): Promise; + send(message: Body, options?: QueueSendOptions): Promise; + sendBatch(messages: Iterable>, options?: QueueSendBatchOptions): Promise; +} +interface QueueSendMetrics { + backlogCount: number; + backlogBytes: number; + oldestMessageTimestamp?: Date; +} +interface QueueSendMetadata { + metrics: QueueSendMetrics; +} +interface QueueSendResponse { + metadata: QueueSendMetadata; +} +interface QueueSendBatchMetrics { + backlogCount: number; + backlogBytes: number; + oldestMessageTimestamp?: Date; +} +interface QueueSendBatchMetadata { + metrics: QueueSendBatchMetrics; +} +interface QueueSendBatchResponse { + metadata: QueueSendBatchMetadata; +} +interface QueueSendOptions { + contentType?: QueueContentType; + delaySeconds?: number; +} +interface QueueSendBatchOptions { + delaySeconds?: number; +} +interface MessageSendRequest { + body: Body; + contentType?: QueueContentType; + delaySeconds?: number; +} +interface QueueMetrics { + backlogCount: number; + backlogBytes: number; + oldestMessageTimestamp?: Date; +} +interface MessageBatchMetrics { + backlogCount: number; + backlogBytes: number; + oldestMessageTimestamp?: Date; +} +interface MessageBatchMetadata { + metrics: MessageBatchMetrics; +} +interface QueueRetryOptions { + delaySeconds?: number; +} +interface Message { + readonly id: string; + readonly timestamp: Date; + readonly body: Body; + readonly attempts: number; + retry(options?: QueueRetryOptions): void; + ack(): void; +} +interface QueueEvent extends ExtendableEvent { + readonly messages: readonly Message[]; + readonly queue: string; + readonly metadata: MessageBatchMetadata; + retryAll(options?: QueueRetryOptions): void; + ackAll(): void; +} +interface MessageBatch { + readonly messages: readonly Message[]; + readonly queue: string; + readonly metadata: MessageBatchMetadata; + retryAll(options?: QueueRetryOptions): void; + ackAll(): void; +} +interface R2Error extends Error { + readonly name: string; + readonly code: number; + readonly message: string; + readonly action: string; + readonly stack: any; +} +interface R2ListOptions { + limit?: number; + prefix?: string; + cursor?: string; + delimiter?: string; + startAfter?: string; + include?: ("httpMetadata" | "customMetadata")[]; +} +interface R2Bucket { + head(key: string): Promise; + get(key: string, options: R2GetOptions & { + onlyIf: R2Conditional | Headers; + }): Promise; + get(key: string, options?: R2GetOptions): Promise; + put(key: string, value: ReadableStream | ArrayBuffer | ArrayBufferView | string | null | Blob, options?: R2PutOptions & { + onlyIf: R2Conditional | Headers; + }): Promise; + put(key: string, value: ReadableStream | ArrayBuffer | ArrayBufferView | string | null | Blob, options?: R2PutOptions): Promise; + createMultipartUpload(key: string, options?: R2MultipartOptions): Promise; + resumeMultipartUpload(key: string, uploadId: string): R2MultipartUpload; + delete(keys: string | string[]): Promise; + list(options?: R2ListOptions): Promise; +} +interface R2MultipartUpload { + readonly key: string; + readonly uploadId: string; + uploadPart(partNumber: number, value: ReadableStream | (ArrayBuffer | ArrayBufferView) | string | Blob, options?: R2UploadPartOptions): Promise; + abort(): Promise; + complete(uploadedParts: R2UploadedPart[]): Promise; +} +interface R2UploadedPart { + partNumber: number; + etag: string; +} +declare abstract class R2Object { + readonly key: string; + readonly version: string; + readonly size: number; + readonly etag: string; + readonly httpEtag: string; + readonly checksums: R2Checksums; + readonly uploaded: Date; + readonly httpMetadata?: R2HTTPMetadata; + readonly customMetadata?: Record; + readonly range?: R2Range; + readonly storageClass: string; + readonly ssecKeyMd5?: string; + writeHttpMetadata(headers: Headers): void; +} +interface R2ObjectBody extends R2Object { + get body(): ReadableStream; + get bodyUsed(): boolean; + arrayBuffer(): Promise; + bytes(): Promise; + text(): Promise; + json(): Promise; + blob(): Promise; +} +type R2Range = { + offset: number; + length?: number; +} | { + offset?: number; + length: number; +} | { + suffix: number; +}; +interface R2Conditional { + etagMatches?: string; + etagDoesNotMatch?: string; + uploadedBefore?: Date; + uploadedAfter?: Date; + secondsGranularity?: boolean; +} +interface R2GetOptions { + onlyIf?: (R2Conditional | Headers); + range?: (R2Range | Headers); + ssecKey?: (ArrayBuffer | string); +} +interface R2PutOptions { + onlyIf?: (R2Conditional | Headers); + httpMetadata?: (R2HTTPMetadata | Headers); + customMetadata?: Record; + md5?: ((ArrayBuffer | ArrayBufferView) | string); + sha1?: ((ArrayBuffer | ArrayBufferView) | string); + sha256?: ((ArrayBuffer | ArrayBufferView) | string); + sha384?: ((ArrayBuffer | ArrayBufferView) | string); + sha512?: ((ArrayBuffer | ArrayBufferView) | string); + storageClass?: string; + ssecKey?: (ArrayBuffer | string); +} +interface R2MultipartOptions { + httpMetadata?: (R2HTTPMetadata | Headers); + customMetadata?: Record; + storageClass?: string; + ssecKey?: (ArrayBuffer | string); +} +interface R2Checksums { + readonly md5?: ArrayBuffer; + readonly sha1?: ArrayBuffer; + readonly sha256?: ArrayBuffer; + readonly sha384?: ArrayBuffer; + readonly sha512?: ArrayBuffer; + toJSON(): R2StringChecksums; +} +interface R2StringChecksums { + md5?: string; + sha1?: string; + sha256?: string; + sha384?: string; + sha512?: string; +} +interface R2HTTPMetadata { + contentType?: string; + contentLanguage?: string; + contentDisposition?: string; + contentEncoding?: string; + cacheControl?: string; + cacheExpiry?: Date; +} +type R2Objects = { + objects: R2Object[]; + delimitedPrefixes: string[]; +} & ({ + truncated: true; + cursor: string; +} | { + truncated: false; +}); +interface R2UploadPartOptions { + ssecKey?: (ArrayBuffer | string); +} +declare abstract class ScheduledEvent extends ExtendableEvent { + readonly scheduledTime: number; + readonly cron: string; + noRetry(): void; +} +interface ScheduledController { + readonly scheduledTime: number; + readonly cron: string; + noRetry(): void; +} +interface QueuingStrategy { + highWaterMark?: (number | bigint); + size?: (chunk: T) => number | bigint; +} +interface UnderlyingSink { + type?: string; + start?: (controller: WritableStreamDefaultController) => void | Promise; + write?: (chunk: W, controller: WritableStreamDefaultController) => void | Promise; + abort?: (reason: any) => void | Promise; + close?: () => void | Promise; +} +interface UnderlyingByteSource { + type: "bytes"; + autoAllocateChunkSize?: number; + start?: (controller: ReadableByteStreamController) => void | Promise; + pull?: (controller: ReadableByteStreamController) => void | Promise; + cancel?: (reason: any) => void | Promise; +} +interface UnderlyingSource { + type?: "" | undefined; + start?: (controller: ReadableStreamDefaultController) => void | Promise; + pull?: (controller: ReadableStreamDefaultController) => void | Promise; + cancel?: (reason: any) => void | Promise; + expectedLength?: (number | bigint); +} +interface Transformer { + readableType?: string; + writableType?: string; + start?: (controller: TransformStreamDefaultController) => void | Promise; + transform?: (chunk: I, controller: TransformStreamDefaultController) => void | Promise; + flush?: (controller: TransformStreamDefaultController) => void | Promise; + cancel?: (reason: any) => void | Promise; + expectedLength?: number; +} +interface StreamPipeOptions { + preventAbort?: boolean; + preventCancel?: boolean; + /** + * Pipes this readable stream to a given writable stream destination. The way in which the piping process behaves under various error conditions can be customized with a number of passed options. It returns a promise that fulfills when the piping process completes successfully, or rejects if any errors were encountered. + * + * Piping a stream will lock it for the duration of the pipe, preventing any other consumer from acquiring a reader. + * + * Errors and closures of the source and destination streams propagate as follows: + * + * An error in this source readable stream will abort destination, unless preventAbort is truthy. The returned promise will be rejected with the source's error, or with any error that occurs during aborting the destination. + * + * An error in destination will cancel this source readable stream, unless preventCancel is truthy. The returned promise will be rejected with the destination's error, or with any error that occurs during canceling the source. + * + * When this source readable stream closes, destination will be closed, unless preventClose is truthy. The returned promise will be fulfilled once this process completes, unless an error is encountered while closing the destination, in which case it will be rejected with that error. + * + * If destination starts out closed or closing, this source readable stream will be canceled, unless preventCancel is true. The returned promise will be rejected with an error indicating piping to a closed stream failed, or with any error that occurs during canceling the source. + * + * The signal option can be set to an AbortSignal to allow aborting an ongoing pipe operation via the corresponding AbortController. In this case, this source readable stream will be canceled, and destination aborted, unless the respective options preventCancel or preventAbort are set. + */ + preventClose?: boolean; + signal?: AbortSignal; +} +type ReadableStreamReadResult = { + done: false; + value: R; +} | { + done: true; + value?: undefined; +}; +/** + * The **`ReadableStream`** interface of the Streams API represents a readable stream of byte data. The Fetch API offers a concrete instance of a ReadableStream through the body property of a Response object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStream) + */ +interface ReadableStream { + /** + * The **`locked`** read-only property of the ReadableStream interface returns whether or not the readable stream is locked to a reader. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStream/locked) + */ + get locked(): boolean; + /** + * The **`cancel()`** method of the ReadableStream interface returns a Promise that resolves when the stream is canceled. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStream/cancel) + */ + cancel(reason?: any): Promise; + /** + * The **`getReader()`** method of the ReadableStream interface creates a reader and locks the stream to it. While the stream is locked, no other reader can be acquired until this one is released. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStream/getReader) + */ + getReader(): ReadableStreamDefaultReader; + /** + * The **`getReader()`** method of the ReadableStream interface creates a reader and locks the stream to it. While the stream is locked, no other reader can be acquired until this one is released. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStream/getReader) + */ + getReader(options: ReadableStreamGetReaderOptions): ReadableStreamBYOBReader; + /** + * The **`pipeThrough()`** method of the ReadableStream interface provides a chainable way of piping the current stream through a transform stream or any other writable/readable pair. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStream/pipeThrough) + */ + pipeThrough(transform: ReadableWritablePair, options?: StreamPipeOptions): ReadableStream; + /** + * The **`pipeTo()`** method of the ReadableStream interface pipes the current ReadableStream to a given WritableStream and returns a Promise that fulfills when the piping process completes successfully, or rejects if any errors were encountered. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStream/pipeTo) + */ + pipeTo(destination: WritableStream, options?: StreamPipeOptions): Promise; + /** + * The **`tee()`** method of the ReadableStream interface tees the current readable stream, returning a two-element array containing the two resulting branches as new ReadableStream instances. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStream/tee) + */ + tee(): [ + ReadableStream, + ReadableStream + ]; + values(options?: ReadableStreamValuesOptions): AsyncIterableIterator; + [Symbol.asyncIterator](options?: ReadableStreamValuesOptions): AsyncIterableIterator; +} +/** + * The **`ReadableStream`** interface of the Streams API represents a readable stream of byte data. The Fetch API offers a concrete instance of a ReadableStream through the body property of a Response object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStream) + */ +declare const ReadableStream: { + prototype: ReadableStream; + new (underlyingSource: UnderlyingByteSource, strategy?: QueuingStrategy): ReadableStream; + new (underlyingSource?: UnderlyingSource, strategy?: QueuingStrategy): ReadableStream; +}; +/** + * The **`ReadableStreamDefaultReader`** interface of the Streams API represents a default reader that can be used to read stream data supplied from a network (such as a fetch request). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamDefaultReader) + */ +declare class ReadableStreamDefaultReader { + constructor(stream: ReadableStream); + get closed(): Promise; + cancel(reason?: any): Promise; + /** + * The **`read()`** method of the ReadableStreamDefaultReader interface returns a Promise providing access to the next chunk in the stream's internal queue. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamDefaultReader/read) + */ + read(): Promise>; + /** + * The **`releaseLock()`** method of the ReadableStreamDefaultReader interface releases the reader's lock on the stream. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamDefaultReader/releaseLock) + */ + releaseLock(): void; +} +/** + * The **`ReadableStreamBYOBReader`** interface of the Streams API defines a reader for a ReadableStream that supports zero-copy reading from an underlying byte source. It is used for efficient copying from underlying sources where the data is delivered as an "anonymous" sequence of bytes, such as files. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamBYOBReader) + */ +declare class ReadableStreamBYOBReader { + constructor(stream: ReadableStream); + get closed(): Promise; + cancel(reason?: any): Promise; + /** + * The **`read()`** method of the ReadableStreamBYOBReader interface is used to read data into a view on a user-supplied buffer from an associated readable byte stream. A request for data will be satisfied from the stream's internal queues if there is any data present. If the stream queues are empty, the request may be supplied as a zero-copy transfer from the underlying byte source. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamBYOBReader/read) + */ + read(view: T): Promise>; + /** + * The **`releaseLock()`** method of the ReadableStreamBYOBReader interface releases the reader's lock on the stream. After the lock is released, the reader is no longer active. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamBYOBReader/releaseLock) + */ + releaseLock(): void; + readAtLeast(minElements: number, view: T): Promise>; +} +interface ReadableStreamBYOBReaderReadableStreamBYOBReaderReadOptions { + min?: number; +} +interface ReadableStreamGetReaderOptions { + /** + * Creates a ReadableStreamBYOBReader and locks the stream to the new reader. + * + * This call behaves the same way as the no-argument variant, except that it only works on readable byte streams, i.e. streams which were constructed specifically with the ability to handle "bring your own buffer" reading. The returned BYOB reader provides the ability to directly read individual chunks from the stream via its read() method, into developer-supplied buffers, allowing more precise control over allocation. + */ + mode: "byob"; +} +/** + * The **`ReadableStreamBYOBRequest`** interface of the Streams API represents a "pull request" for data from an underlying source that will made as a zero-copy transfer to a consumer (bypassing the stream's internal queues). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamBYOBRequest) + */ +declare abstract class ReadableStreamBYOBRequest { + /** + * The **`view`** getter property of the ReadableStreamBYOBRequest interface returns the current view. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamBYOBRequest/view) + */ + get view(): Uint8Array | null; + /** + * The **`respond()`** method of the ReadableStreamBYOBRequest interface is used to signal to the associated readable byte stream that the specified number of bytes were written into the ReadableStreamBYOBRequest.view. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamBYOBRequest/respond) + */ + respond(bytesWritten: number): void; + /** + * The **`respondWithNewView()`** method of the ReadableStreamBYOBRequest interface specifies a new view that the consumer of the associated readable byte stream should write to instead of ReadableStreamBYOBRequest.view. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamBYOBRequest/respondWithNewView) + */ + respondWithNewView(view: ArrayBuffer | ArrayBufferView): void; + get atLeast(): number | null; +} +/** + * The **`ReadableStreamDefaultController`** interface of the Streams API represents a controller allowing control of a ReadableStream's state and internal queue. Default controllers are for streams that are not byte streams. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamDefaultController) + */ +declare abstract class ReadableStreamDefaultController { + /** + * The **`desiredSize`** read-only property of the ReadableStreamDefaultController interface returns the desired size required to fill the stream's internal queue. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamDefaultController/desiredSize) + */ + get desiredSize(): number | null; + /** + * The **`close()`** method of the ReadableStreamDefaultController interface closes the associated stream. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamDefaultController/close) + */ + close(): void; + /** + * The **`enqueue()`** method of the ReadableStreamDefaultController interface enqueues a given chunk in the associated stream. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamDefaultController/enqueue) + */ + enqueue(chunk?: R): void; + /** + * The **`error()`** method of the ReadableStreamDefaultController interface causes any future interactions with the associated stream to error. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamDefaultController/error) + */ + error(reason: any): void; +} +/** + * The **`ReadableByteStreamController`** interface of the Streams API represents a controller for a readable byte stream. It allows control of the state and internal queue of a ReadableStream with an underlying byte source, and enables efficient zero-copy transfer of data from the underlying source to a consumer when the stream's internal queue is empty. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableByteStreamController) + */ +declare abstract class ReadableByteStreamController { + /** + * The **`byobRequest`** read-only property of the ReadableByteStreamController interface returns the current BYOB request, or null if there are no pending requests. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableByteStreamController/byobRequest) + */ + get byobRequest(): ReadableStreamBYOBRequest | null; + /** + * The **`desiredSize`** read-only property of the ReadableByteStreamController interface returns the number of bytes required to fill the stream's internal queue to its "desired size". + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableByteStreamController/desiredSize) + */ + get desiredSize(): number | null; + /** + * The **`close()`** method of the ReadableByteStreamController interface closes the associated stream. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableByteStreamController/close) + */ + close(): void; + /** + * The **`enqueue()`** method of the ReadableByteStreamController interface enqueues a given chunk on the associated readable byte stream (the chunk is transferred into the stream's internal queues). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableByteStreamController/enqueue) + */ + enqueue(chunk: ArrayBuffer | ArrayBufferView): void; + /** + * The **`error()`** method of the ReadableByteStreamController interface causes any future interactions with the associated stream to error with the specified reason. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableByteStreamController/error) + */ + error(reason: any): void; +} +/** + * The **`WritableStreamDefaultController`** interface of the Streams API represents a controller allowing control of a WritableStream's state. When constructing a WritableStream, the underlying sink is given a corresponding WritableStreamDefaultController instance to manipulate. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WritableStreamDefaultController) + */ +declare abstract class WritableStreamDefaultController { + /** + * The read-only **`signal`** property of the WritableStreamDefaultController interface returns the AbortSignal associated with the controller. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WritableStreamDefaultController/signal) + */ + get signal(): AbortSignal; + /** + * The **`error()`** method of the WritableStreamDefaultController interface causes any future interactions with the associated stream to error. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WritableStreamDefaultController/error) + */ + error(reason?: any): void; +} +/** + * The **`TransformStreamDefaultController`** interface of the Streams API provides methods to manipulate the associated ReadableStream and WritableStream. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/TransformStreamDefaultController) + */ +declare abstract class TransformStreamDefaultController { + /** + * The **`desiredSize`** read-only property of the TransformStreamDefaultController interface returns the desired size to fill the queue of the associated ReadableStream. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/TransformStreamDefaultController/desiredSize) + */ + get desiredSize(): number | null; + /** + * The **`enqueue()`** method of the TransformStreamDefaultController interface enqueues the given chunk in the readable side of the stream. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/TransformStreamDefaultController/enqueue) + */ + enqueue(chunk?: O): void; + /** + * The **`error()`** method of the TransformStreamDefaultController interface errors both sides of the stream. Any further interactions with it will fail with the given error message, and any chunks in the queue will be discarded. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/TransformStreamDefaultController/error) + */ + error(reason: any): void; + /** + * The **`terminate()`** method of the TransformStreamDefaultController interface closes the readable side and errors the writable side of the stream. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/TransformStreamDefaultController/terminate) + */ + terminate(): void; +} +interface ReadableWritablePair { + readable: ReadableStream; + /** + * Provides a convenient, chainable way of piping this readable stream through a transform stream (or any other { writable, readable } pair). It simply pipes the stream into the writable side of the supplied pair, and returns the readable side for further use. + * + * Piping a stream will lock it for the duration of the pipe, preventing any other consumer from acquiring a reader. + */ + writable: WritableStream; +} +/** + * The **`WritableStream`** interface of the Streams API provides a standard abstraction for writing streaming data to a destination, known as a sink. This object comes with built-in backpressure and queuing. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WritableStream) + */ +declare class WritableStream { + constructor(underlyingSink?: UnderlyingSink, queuingStrategy?: QueuingStrategy); + /** + * The **`locked`** read-only property of the WritableStream interface returns a boolean indicating whether the WritableStream is locked to a writer. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WritableStream/locked) + */ + get locked(): boolean; + /** + * The **`abort()`** method of the WritableStream interface aborts the stream, signaling that the producer can no longer successfully write to the stream and it is to be immediately moved to an error state, with any queued writes discarded. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WritableStream/abort) + */ + abort(reason?: any): Promise; + /** + * The **`close()`** method of the WritableStream interface closes the associated stream. All chunks written before this method is called are sent before the returned promise is fulfilled. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WritableStream/close) + */ + close(): Promise; + /** + * The **`getWriter()`** method of the WritableStream interface returns a new instance of WritableStreamDefaultWriter and locks the stream to that instance. While the stream is locked, no other writer can be acquired until this one is released. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WritableStream/getWriter) + */ + getWriter(): WritableStreamDefaultWriter; +} +/** + * The **`WritableStreamDefaultWriter`** interface of the Streams API is the object returned by WritableStream.getWriter() and once created locks the writer to the WritableStream ensuring that no other streams can write to the underlying sink. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WritableStreamDefaultWriter) + */ +declare class WritableStreamDefaultWriter { + constructor(stream: WritableStream); + /** + * The **`closed`** read-only property of the WritableStreamDefaultWriter interface returns a Promise that fulfills if the stream becomes closed, or rejects if the stream errors or the writer's lock is released. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WritableStreamDefaultWriter/closed) + */ + get closed(): Promise; + /** + * The **`ready`** read-only property of the WritableStreamDefaultWriter interface returns a Promise that resolves when the desired size of the stream's internal queue transitions from non-positive to positive, signaling that it is no longer applying backpressure. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WritableStreamDefaultWriter/ready) + */ + get ready(): Promise; + /** + * The **`desiredSize`** read-only property of the WritableStreamDefaultWriter interface returns the desired size required to fill the stream's internal queue. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WritableStreamDefaultWriter/desiredSize) + */ + get desiredSize(): number | null; + /** + * The **`abort()`** method of the WritableStreamDefaultWriter interface aborts the stream, signaling that the producer can no longer successfully write to the stream and it is to be immediately moved to an error state, with any queued writes discarded. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WritableStreamDefaultWriter/abort) + */ + abort(reason?: any): Promise; + /** + * The **`close()`** method of the WritableStreamDefaultWriter interface closes the associated writable stream. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WritableStreamDefaultWriter/close) + */ + close(): Promise; + /** + * The **`write()`** method of the WritableStreamDefaultWriter interface writes a passed chunk of data to a WritableStream and its underlying sink, then returns a Promise that resolves to indicate the success or failure of the write operation. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WritableStreamDefaultWriter/write) + */ + write(chunk?: W): Promise; + /** + * The **`releaseLock()`** method of the WritableStreamDefaultWriter interface releases the writer's lock on the corresponding stream. After the lock is released, the writer is no longer active. If the associated stream is errored when the lock is released, the writer will appear errored in the same way from now on; otherwise, the writer will appear closed. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WritableStreamDefaultWriter/releaseLock) + */ + releaseLock(): void; +} +/** + * The **`TransformStream`** interface of the Streams API represents a concrete implementation of the pipe chain transform stream concept. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/TransformStream) + */ +declare class TransformStream { + constructor(transformer?: Transformer, writableStrategy?: QueuingStrategy, readableStrategy?: QueuingStrategy); + /** + * The **`readable`** read-only property of the TransformStream interface returns the ReadableStream instance controlled by this TransformStream. This stream emits the transformed output data. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/TransformStream/readable) + */ + get readable(): ReadableStream; + /** + * The **`writable`** read-only property of the TransformStream interface returns the WritableStream instance controlled by this TransformStream. This stream accepts input data that will be transformed and emitted to the readable stream. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/TransformStream/writable) + */ + get writable(): WritableStream; +} +declare class FixedLengthStream extends IdentityTransformStream { + constructor(expectedLength: number | bigint, queuingStrategy?: IdentityTransformStreamQueuingStrategy); +} +declare class IdentityTransformStream extends TransformStream { + constructor(queuingStrategy?: IdentityTransformStreamQueuingStrategy); +} +interface IdentityTransformStreamQueuingStrategy { + highWaterMark?: (number | bigint); +} +interface ReadableStreamValuesOptions { + preventCancel?: boolean; +} +/** + * The **`CompressionStream`** interface of the Compression Streams API compresses a stream of data. It implements the same shape as a TransformStream, allowing it to be used in ReadableStream.pipeThrough() and similar methods. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CompressionStream) + */ +declare class CompressionStream extends TransformStream { + constructor(format: "gzip" | "deflate" | "deflate-raw"); +} +/** + * The **`DecompressionStream`** interface of the Compression Streams API decompresses a stream of data. It implements the same shape as a TransformStream, allowing it to be used in ReadableStream.pipeThrough() and similar methods. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DecompressionStream) + */ +declare class DecompressionStream extends TransformStream { + constructor(format: "gzip" | "deflate" | "deflate-raw"); +} +/** + * The **`TextEncoderStream`** interface of the Encoding API converts a stream of strings into bytes in the UTF-8 encoding. It is the streaming equivalent of TextEncoder. It implements the same shape as a TransformStream, allowing it to be used in ReadableStream.pipeThrough() and similar methods. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/TextEncoderStream) + */ +declare class TextEncoderStream extends TransformStream { + constructor(); + get encoding(): string; +} +/** + * The **`TextDecoderStream`** interface of the Encoding API converts a stream of text in a binary encoding, such as UTF-8 etc., to a stream of strings. It is the streaming equivalent of TextDecoder. It implements the same shape as a TransformStream, allowing it to be used in ReadableStream.pipeThrough() and similar methods. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/TextDecoderStream) + */ +declare class TextDecoderStream extends TransformStream { + constructor(label?: string, options?: TextDecoderStreamTextDecoderStreamInit); + get encoding(): string; + get fatal(): boolean; + get ignoreBOM(): boolean; +} +interface TextDecoderStreamTextDecoderStreamInit { + fatal?: boolean; + ignoreBOM?: boolean; +} +/** + * The **`ByteLengthQueuingStrategy`** interface of the Streams API provides a built-in byte length queuing strategy that can be used when constructing streams. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ByteLengthQueuingStrategy) + */ +declare class ByteLengthQueuingStrategy implements QueuingStrategy { + constructor(init: QueuingStrategyInit); + /** + * The read-only **`ByteLengthQueuingStrategy.highWaterMark`** property returns the total number of bytes that can be contained in the internal queue before backpressure is applied. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ByteLengthQueuingStrategy/highWaterMark) + */ + get highWaterMark(): number; + /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ByteLengthQueuingStrategy/size) */ + get size(): (chunk?: any) => number; +} +/** + * The **`CountQueuingStrategy`** interface of the Streams API provides a built-in chunk counting queuing strategy that can be used when constructing streams. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CountQueuingStrategy) + */ +declare class CountQueuingStrategy implements QueuingStrategy { + constructor(init: QueuingStrategyInit); + /** + * The read-only **`CountQueuingStrategy.highWaterMark`** property returns the total number of chunks that can be contained in the internal queue before backpressure is applied. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CountQueuingStrategy/highWaterMark) + */ + get highWaterMark(): number; + /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/CountQueuingStrategy/size) */ + get size(): (chunk?: any) => number; +} +interface QueuingStrategyInit { + /** + * Creates a new ByteLengthQueuingStrategy with the provided high water mark. + * + * Note that the provided high water mark will not be validated ahead of time. Instead, if it is negative, NaN, or not a number, the resulting ByteLengthQueuingStrategy will cause the corresponding stream constructor to throw. + */ + highWaterMark: number; +} +interface TracePreviewInfo { + id: string; + slug: string; + name: string; +} +interface ScriptVersion { + id?: string; + tag?: string; + message?: string; +} +declare abstract class TailEvent extends ExtendableEvent { + readonly events: TraceItem[]; + readonly traces: TraceItem[]; +} +interface TraceItem { + readonly event: (TraceItemFetchEventInfo | TraceItemJsRpcEventInfo | TraceItemConnectEventInfo | TraceItemScheduledEventInfo | TraceItemAlarmEventInfo | TraceItemQueueEventInfo | TraceItemEmailEventInfo | TraceItemTailEventInfo | TraceItemCustomEventInfo | TraceItemHibernatableWebSocketEventInfo) | null; + readonly eventTimestamp: number | null; + readonly logs: TraceLog[]; + readonly exceptions: TraceException[]; + readonly diagnosticsChannelEvents: TraceDiagnosticChannelEvent[]; + readonly scriptName: string | null; + readonly entrypoint?: string; + readonly scriptVersion?: ScriptVersion; + readonly dispatchNamespace?: string; + readonly scriptTags?: string[]; + readonly tailAttributes?: Record; + readonly preview?: TracePreviewInfo; + readonly durableObjectId?: string; + readonly outcome: string; + readonly executionModel: string; + readonly truncated: boolean; + readonly cpuTime: number; + readonly wallTime: number; +} +interface TraceItemAlarmEventInfo { + readonly scheduledTime: Date; +} +interface TraceItemConnectEventInfo { +} +interface TraceItemCustomEventInfo { +} +interface TraceItemScheduledEventInfo { + readonly scheduledTime: number; + readonly cron: string; +} +interface TraceItemQueueEventInfo { + readonly queue: string; + readonly batchSize: number; +} +interface TraceItemEmailEventInfo { + readonly mailFrom: string; + readonly rcptTo: string; + readonly rawSize: number; +} +interface TraceItemTailEventInfo { + readonly consumedEvents: TraceItemTailEventInfoTailItem[]; +} +interface TraceItemTailEventInfoTailItem { + readonly scriptName: string | null; +} +interface TraceItemFetchEventInfo { + readonly response?: TraceItemFetchEventInfoResponse; + readonly request: TraceItemFetchEventInfoRequest; +} +interface TraceItemFetchEventInfoRequest { + readonly cf?: any; + readonly headers: Record; + readonly method: string; + readonly url: string; + getUnredacted(): TraceItemFetchEventInfoRequest; +} +interface TraceItemFetchEventInfoResponse { + readonly status: number; +} +interface TraceItemJsRpcEventInfo { + readonly rpcMethod: string; +} +interface TraceItemHibernatableWebSocketEventInfo { + readonly getWebSocketEvent: TraceItemHibernatableWebSocketEventInfoMessage | TraceItemHibernatableWebSocketEventInfoClose | TraceItemHibernatableWebSocketEventInfoError; +} +interface TraceItemHibernatableWebSocketEventInfoMessage { + readonly webSocketEventType: string; +} +interface TraceItemHibernatableWebSocketEventInfoClose { + readonly webSocketEventType: string; + readonly code: number; + readonly wasClean: boolean; +} +interface TraceItemHibernatableWebSocketEventInfoError { + readonly webSocketEventType: string; +} +interface TraceLog { + readonly timestamp: number; + readonly level: string; + readonly message: any; + readonly errorInfo?: (TraceLogErrorInfo | null)[]; +} +interface TraceLogErrorInfo { + name: string; + message: string; + stack?: string; +} +interface TraceException { + readonly timestamp: number; + readonly message: string; + readonly name: string; + readonly stack?: string; +} +interface TraceDiagnosticChannelEvent { + readonly timestamp: number; + readonly channel: string; + readonly message: any; +} +interface TraceMetrics { + readonly cpuTime: number; + readonly wallTime: number; +} +interface UnsafeTraceMetrics { + fromTrace(item: TraceItem): TraceMetrics; +} +/** + * The **`URL`** interface is used to parse, construct, normalize, and encode URLs. It works by providing properties which allow you to easily read and modify the components of a URL. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL) + */ +declare class URL { + constructor(url: string | URL, base?: string | URL); + /** + * The **`origin`** read-only property of the URL interface returns a string containing the Unicode serialization of the origin of the represented URL. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/origin) + */ + get origin(): string; + /** + * The **`href`** property of the URL interface is a string containing the whole URL. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/href) + */ + get href(): string; + /** + * The **`href`** property of the URL interface is a string containing the whole URL. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/href) + */ + set href(value: string); + /** + * The **`protocol`** property of the URL interface is a string containing the protocol or scheme of the URL, including the final ":". + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/protocol) + */ + get protocol(): string; + /** + * The **`protocol`** property of the URL interface is a string containing the protocol or scheme of the URL, including the final ":". + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/protocol) + */ + set protocol(value: string); + /** + * The **`username`** property of the URL interface is a string containing the username component of the URL. If the URL does not have a username, this property contains an empty string, "". + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/username) + */ + get username(): string; + /** + * The **`username`** property of the URL interface is a string containing the username component of the URL. If the URL does not have a username, this property contains an empty string, "". + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/username) + */ + set username(value: string); + /** + * The **`password`** property of the URL interface is a string containing the password component of the URL. If the URL does not have a password, this property contains an empty string, "". + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/password) + */ + get password(): string; + /** + * The **`password`** property of the URL interface is a string containing the password component of the URL. If the URL does not have a password, this property contains an empty string, "". + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/password) + */ + set password(value: string); + /** + * The **`host`** property of the URL interface is a string containing the host, which is the hostname, and then, if the port of the URL is nonempty, a ":", followed by the port of the URL. If the URL does not have a hostname, this property contains an empty string, "". + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/host) + */ + get host(): string; + /** + * The **`host`** property of the URL interface is a string containing the host, which is the hostname, and then, if the port of the URL is nonempty, a ":", followed by the port of the URL. If the URL does not have a hostname, this property contains an empty string, "". + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/host) + */ + set host(value: string); + /** + * The **`hostname`** property of the URL interface is a string containing either the domain name or IP address of the URL. If the URL does not have a hostname, this property contains an empty string, "". IPv4 and IPv6 addresses are normalized, such as stripping leading zeros, and domain names are converted to IDN. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/hostname) + */ + get hostname(): string; + /** + * The **`hostname`** property of the URL interface is a string containing either the domain name or IP address of the URL. If the URL does not have a hostname, this property contains an empty string, "". IPv4 and IPv6 addresses are normalized, such as stripping leading zeros, and domain names are converted to IDN. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/hostname) + */ + set hostname(value: string); + /** + * The **`port`** property of the URL interface is a string containing the port number of the URL. If the port is the default for the protocol (80 for ws: and http:, 443 for wss: and https:, and 21 for ftp:), this property contains an empty string, "". + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/port) + */ + get port(): string; + /** + * The **`port`** property of the URL interface is a string containing the port number of the URL. If the port is the default for the protocol (80 for ws: and http:, 443 for wss: and https:, and 21 for ftp:), this property contains an empty string, "". + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/port) + */ + set port(value: string); + /** + * The **`pathname`** property of the URL interface represents a location in a hierarchical structure. It is a string constructed from a list of path segments, each of which is prefixed by a / character. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/pathname) + */ + get pathname(): string; + /** + * The **`pathname`** property of the URL interface represents a location in a hierarchical structure. It is a string constructed from a list of path segments, each of which is prefixed by a / character. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/pathname) + */ + set pathname(value: string); + /** + * The **`search`** property of the URL interface is a search string, also called a query string, that is a string containing a "?" followed by the parameters of the URL. If the URL does not have a search query, this property contains an empty string, "". + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/search) + */ + get search(): string; + /** + * The **`search`** property of the URL interface is a search string, also called a query string, that is a string containing a "?" followed by the parameters of the URL. If the URL does not have a search query, this property contains an empty string, "". + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/search) + */ + set search(value: string); + /** + * The **`hash`** property of the URL interface is a string containing a "#" followed by the fragment identifier of the URL. If the URL does not have a fragment identifier, this property contains an empty string, "". + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/hash) + */ + get hash(): string; + /** + * The **`hash`** property of the URL interface is a string containing a "#" followed by the fragment identifier of the URL. If the URL does not have a fragment identifier, this property contains an empty string, "". + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/hash) + */ + set hash(value: string); + /** + * The **`searchParams`** read-only property of the URL interface returns a URLSearchParams object allowing access to the GET decoded query arguments contained in the URL. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/searchParams) + */ + get searchParams(): URLSearchParams; + /** + * The **`toJSON()`** method of the URL interface returns a string containing a serialized version of the URL, although in practice it seems to have the same effect as URL.toString(). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/toJSON) + */ + toJSON(): string; + /*function toString() { [native code] }*/ + toString(): string; + /** + * The **`URL.canParse()`** static method of the URL interface returns a boolean indicating whether or not an absolute URL, or a relative URL combined with a base URL, are parsable and valid. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/canParse_static) + */ + static canParse(url: string, base?: string): boolean; + /** + * The **`URL.parse()`** static method of the URL interface returns a newly created URL object representing the URL defined by the parameters. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/parse_static) + */ + static parse(url: string, base?: string): URL | null; + /** + * The **`createObjectURL()`** static method of the URL interface creates a string containing a blob URL pointing to the object given in the parameter. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/createObjectURL_static) + */ + static createObjectURL(object: File | Blob): string; + /** + * The **`revokeObjectURL()`** static method of the URL interface releases an existing object URL which was previously created by calling URL.createObjectURL(). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/revokeObjectURL_static) + */ + static revokeObjectURL(object_url: string): void; +} +/** + * The **`URLSearchParams`** interface defines utility methods to work with the query string of a URL. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URLSearchParams) + */ +declare class URLSearchParams { + constructor(init?: (Iterable> | Record | string)); + /** + * The **`size`** read-only property of the URLSearchParams interface indicates the total number of search parameter entries. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URLSearchParams/size) + */ + get size(): number; + /** + * The **`append()`** method of the URLSearchParams interface appends a specified key/value pair as a new search parameter. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URLSearchParams/append) + */ + append(name: string, value: string): void; + /** + * The **`delete()`** method of the URLSearchParams interface deletes specified parameters and their associated value(s) from the list of all search parameters. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URLSearchParams/delete) + */ + delete(name: string, value?: string): void; + /** + * The **`get()`** method of the URLSearchParams interface returns the first value associated to the given search parameter. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URLSearchParams/get) + */ + get(name: string): string | null; + /** + * The **`getAll()`** method of the URLSearchParams interface returns all the values associated with a given search parameter as an array. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URLSearchParams/getAll) + */ + getAll(name: string): string[]; + /** + * The **`has()`** method of the URLSearchParams interface returns a boolean value that indicates whether the specified parameter is in the search parameters. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URLSearchParams/has) + */ + has(name: string, value?: string): boolean; + /** + * The **`set()`** method of the URLSearchParams interface sets the value associated with a given search parameter to the given value. If there were several matching values, this method deletes the others. If the search parameter doesn't exist, this method creates it. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URLSearchParams/set) + */ + set(name: string, value: string): void; + /** + * The **`URLSearchParams.sort()`** method sorts all key/value pairs contained in this object in place and returns undefined. Key/value pairs are sorted by the values of the UTF-16 code units of the keys. This method uses a stable sorting algorithm (i.e., the relative order between key/value pairs with equal keys will be preserved). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URLSearchParams/sort) + */ + sort(): void; + entries(): IterableIterator<[ + key: string, + value: string + ]>; + keys(): IterableIterator; + values(): IterableIterator; + forEach(callback: (this: This, value: string, key: string, parent: URLSearchParams) => void, thisArg?: This): void; + /*function toString() { [native code] }*/ + toString(): string; + [Symbol.iterator](): IterableIterator<[ + key: string, + value: string + ]>; +} +/** + * The **`URLPattern`** interface of the URL Pattern API matches URLs or parts of URLs against a pattern. The pattern can contain capturing groups that extract parts of the matched URL. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URLPattern) + */ +declare class URLPattern { + constructor(input?: (string | URLPatternInit), baseURL?: (string | URLPatternOptions), patternOptions?: URLPatternOptions); + /** + * The **`protocol`** read-only property of the URLPattern interface is a string containing the pattern used to match the protocol part of a URL. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URLPattern/protocol) + */ + get protocol(): string; + /** + * The **`username`** read-only property of the URLPattern interface is a string containing the pattern used to match the username part of a URL. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URLPattern/username) + */ + get username(): string; + /** + * The **`password`** read-only property of the URLPattern interface is a string containing the pattern used to match the password part of a URL. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URLPattern/password) + */ + get password(): string; + /** + * The **`hostname`** read-only property of the URLPattern interface is a string containing the pattern used to match the hostname part of a URL. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URLPattern/hostname) + */ + get hostname(): string; + /** + * The **`port`** read-only property of the URLPattern interface is a string containing the pattern used to match the port part of a URL. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URLPattern/port) + */ + get port(): string; + /** + * The **`pathname`** read-only property of the URLPattern interface is a string containing the pattern used to match the pathname part of a URL. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URLPattern/pathname) + */ + get pathname(): string; + /** + * The **`search`** read-only property of the URLPattern interface is a string containing the pattern used to match the search part of a URL. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URLPattern/search) + */ + get search(): string; + /** + * The **`hash`** read-only property of the URLPattern interface is a string containing the pattern used to match the fragment part of a URL. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URLPattern/hash) + */ + get hash(): string; + /** + * The **`hasRegExpGroups`** read-only property of the URLPattern interface is a boolean indicating whether or not any of the URLPattern components contain regular expression capturing groups. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URLPattern/hasRegExpGroups) + */ + get hasRegExpGroups(): boolean; + /** + * The **`test()`** method of the URLPattern interface takes a URL string or object of URL parts, and returns a boolean indicating if the given input matches the current pattern. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URLPattern/test) + */ + test(input?: (string | URLPatternInit), baseURL?: string): boolean; + /** + * The **`exec()`** method of the URLPattern interface takes a URL or object of URL parts, and returns either an object containing the results of matching the URL to the pattern, or null if the URL does not match the pattern. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URLPattern/exec) + */ + exec(input?: (string | URLPatternInit), baseURL?: string): URLPatternResult | null; +} +interface URLPatternInit { + protocol?: string; + username?: string; + password?: string; + hostname?: string; + port?: string; + pathname?: string; + search?: string; + hash?: string; + baseURL?: string; +} +interface URLPatternComponentResult { + input: string; + groups: Record; +} +interface URLPatternResult { + inputs: (string | URLPatternInit)[]; + protocol: URLPatternComponentResult; + username: URLPatternComponentResult; + password: URLPatternComponentResult; + hostname: URLPatternComponentResult; + port: URLPatternComponentResult; + pathname: URLPatternComponentResult; + search: URLPatternComponentResult; + hash: URLPatternComponentResult; +} +interface URLPatternOptions { + ignoreCase?: boolean; +} +/** + * A **`CloseEvent`** is sent to clients using WebSockets when the connection is closed. This is delivered to the listener indicated by the WebSocket object's onclose attribute. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CloseEvent) + */ +declare class CloseEvent extends Event { + constructor(type: string, initializer?: CloseEventInit); + /** + * The **`code`** read-only property of the CloseEvent interface returns a WebSocket connection close code indicating the reason the connection was closed. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CloseEvent/code) + */ + readonly code: number; + /** + * The **`reason`** read-only property of the CloseEvent interface returns the WebSocket connection close reason the server gave for closing the connection; that is, a concise human-readable prose explanation for the closure. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CloseEvent/reason) + */ + readonly reason: string; + /** + * The **`wasClean`** read-only property of the CloseEvent interface returns true if the connection closed cleanly. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CloseEvent/wasClean) + */ + readonly wasClean: boolean; +} +interface CloseEventInit { + bubbles?: boolean; + cancelable?: boolean; + composed?: boolean; + code?: number; + reason?: string; + wasClean?: boolean; +} +type WebSocketEventMap = { + close: CloseEvent; + message: MessageEvent; + open: Event; + error: ErrorEvent; +}; +/** + * The **`WebSocket`** object provides the API for creating and managing a WebSocket connection to a server, as well as for sending and receiving data on the connection. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WebSocket) + */ +declare var WebSocket: { + prototype: WebSocket; + new (url: string, protocols?: (string[] | string)): WebSocket; + readonly READY_STATE_CONNECTING: number; + readonly CONNECTING: number; + readonly READY_STATE_OPEN: number; + readonly OPEN: number; + readonly READY_STATE_CLOSING: number; + readonly CLOSING: number; + readonly READY_STATE_CLOSED: number; + readonly CLOSED: number; +}; +/** + * The **`WebSocket`** object provides the API for creating and managing a WebSocket connection to a server, as well as for sending and receiving data on the connection. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WebSocket) + */ +interface WebSocket extends EventTarget { + accept(options?: WebSocketAcceptOptions): void; + /** + * The **`WebSocket.send()`** method enqueues the specified data to be transmitted to the server over the WebSocket connection, increasing the value of bufferedAmount by the number of bytes needed to contain the data. If the data can't be sent (for example, because it needs to be buffered but the buffer is full), the socket is closed automatically. The browser will throw an exception if you call send() when the connection is in the CONNECTING state. If you call send() when the connection is in the CLOSING or CLOSED states, the browser will silently discard the data. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WebSocket/send) + */ + send(message: (ArrayBuffer | ArrayBufferView) | string): void; + /** + * The **`WebSocket.close()`** method closes the WebSocket connection or connection attempt, if any. If the connection is already CLOSED, this method does nothing. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WebSocket/close) + */ + close(code?: number, reason?: string): void; + serializeAttachment(attachment: any): void; + deserializeAttachment(): any | null; + /** + * The **`WebSocket.readyState`** read-only property returns the current state of the WebSocket connection. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WebSocket/readyState) + */ + readyState: number; + /** + * The **`WebSocket.url`** read-only property returns the absolute URL of the WebSocket as resolved by the constructor. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WebSocket/url) + */ + url: string | null; + /** + * The **`WebSocket.protocol`** read-only property returns the name of the sub-protocol the server selected; this will be one of the strings specified in the protocols parameter when creating the WebSocket object, or the empty string if no connection is established. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WebSocket/protocol) + */ + protocol: string | null; + /** + * The **`WebSocket.extensions`** read-only property returns the extensions selected by the server. This is currently only the empty string or a list of extensions as negotiated by the connection. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WebSocket/extensions) + */ + extensions: string | null; + /** + * The **`WebSocket.binaryType`** property controls the type of binary data being received over the WebSocket connection. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WebSocket/binaryType) + */ + binaryType: "blob" | "arraybuffer"; +} +interface WebSocketAcceptOptions { + /** + * When set to `true`, receiving a server-initiated WebSocket Close frame will not + * automatically send a reciprocal Close frame, leaving the connection in a half-open + * state. This is useful for proxying scenarios where you need to coordinate closing + * both sides independently. Defaults to `false` when the + * `no_web_socket_half_open_by_default` compatibility flag is enabled. + */ + allowHalfOpen?: boolean; +} +declare const WebSocketPair: { + new (): { + 0: WebSocket; + 1: WebSocket; + }; +}; +interface SqlStorage { + exec>(query: string, ...bindings: any[]): SqlStorageCursor; + get databaseSize(): number; + Cursor: typeof SqlStorageCursor; + Statement: typeof SqlStorageStatement; +} +declare abstract class SqlStorageStatement { +} +type SqlStorageValue = ArrayBuffer | string | number | null; +declare abstract class SqlStorageCursor> { + next(): { + done?: false; + value: T; + } | { + done: true; + value?: never; + }; + toArray(): T[]; + one(): T; + raw(): IterableIterator; + columnNames: string[]; + get rowsRead(): number; + get rowsWritten(): number; + [Symbol.iterator](): IterableIterator; +} +interface Socket { + get readable(): ReadableStream; + get writable(): WritableStream; + get closed(): Promise; + get opened(): Promise; + get upgraded(): boolean; + get secureTransport(): "on" | "off" | "starttls"; + close(): Promise; + startTls(options?: TlsOptions): Socket; +} +interface SocketOptions { + secureTransport?: string; + allowHalfOpen: boolean; + highWaterMark?: (number | bigint); +} +interface SocketAddress { + hostname: string; + port: number; +} +interface TlsOptions { + expectedServerHostname?: string; +} +interface SocketInfo { + remoteAddress?: string; + localAddress?: string; +} +/** + * The **`EventSource`** interface is web content's interface to server-sent events. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventSource) + */ +declare class EventSource extends EventTarget { + constructor(url: string, init?: EventSourceEventSourceInit); + /** + * The **`close()`** method of the EventSource interface closes the connection, if one is made, and sets the EventSource.readyState attribute to 2 (closed). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventSource/close) + */ + close(): void; + /** + * The **`url`** read-only property of the EventSource interface returns a string representing the URL of the source. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventSource/url) + */ + get url(): string; + /** + * The **`withCredentials`** read-only property of the EventSource interface returns a boolean value indicating whether the EventSource object was instantiated with CORS credentials set. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventSource/withCredentials) + */ + get withCredentials(): boolean; + /** + * The **`readyState`** read-only property of the EventSource interface returns a number representing the state of the connection. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventSource/readyState) + */ + get readyState(): number; + /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventSource/open_event) */ + get onopen(): any | null; + /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventSource/open_event) */ + set onopen(value: any | null); + /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventSource/message_event) */ + get onmessage(): any | null; + /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventSource/message_event) */ + set onmessage(value: any | null); + /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventSource/error_event) */ + get onerror(): any | null; + /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventSource/error_event) */ + set onerror(value: any | null); + static readonly CONNECTING: number; + static readonly OPEN: number; + static readonly CLOSED: number; + static from(stream: ReadableStream): EventSource; +} +interface EventSourceEventSourceInit { + withCredentials?: boolean; + fetcher?: Fetcher; +} +interface ExecOutput { + readonly stdout: ArrayBuffer; + readonly stderr: ArrayBuffer; + readonly exitCode: number; +} +interface ContainerExecOptions { + cwd?: string; + env?: Record; + user?: string; + signal?: AbortSignal; + pty?: boolean | ContainerExecPtyOptions; + stdin?: ReadableStream | "pipe"; + stdout?: "pipe" | "ignore"; + stderr?: "pipe" | "ignore" | "combined"; +} +interface ContainerExecPtyOptions { + cols?: number; + rows?: number; +} +interface ExecProcess { + readonly stdin: WritableStream | null; + readonly stdout: ReadableStream | null; + readonly stderr: ReadableStream | null; + readonly pid: number; + readonly isPty: boolean; + readonly exitCode: Promise; + output(): Promise; + kill(signal?: number): void; + resize(cols: number, rows: number): void; +} +interface Container { + get running(): boolean; + get images(): Record; + start(options?: ContainerStartupOptions): void; + monitor(): Promise; + destroy(error?: any): Promise; + signal(signo: number): void; + getTcpPort(port: number): Fetcher; + setInactivityTimeout(durationMs: number | bigint): Promise; + interceptOutboundHttp(addr: string, binding: Fetcher): Promise; + interceptAllOutboundHttp(binding: Fetcher): Promise; + snapshotContainer(options?: ContainerSnapshotOptions): Promise; + interceptOutboundHttps(addr: string, binding: Fetcher): Promise; + exec(cmd: string[], options?: ContainerExecOptions): Promise; + inspect(): Promise; +} +interface ContainerDirectorySnapshot { + id: string; + size: number; + dir: string; + name?: string; +} +type ContainerDirectorySnapshotRestoreParams = { + snapshot: ContainerDirectorySnapshot; + mountPoint?: string; +} | { + snapshot?: undefined; + mountPoint: string; +}; +interface ContainerSnapshot { + id: string; + size: number; + name?: string; +} +interface ContainerSnapshotRestoreParams { + id: string; +} +interface ContainerSnapshotOptions { + name?: string; +} +type ContainerStartupOptions = { + entrypoint?: string[]; + enableInternet: boolean; + env?: Record; + instance?: "lite" | "standard-1" | "standard-2" | "standard-3" | "standard-4" | ContainerStartResources; + labels?: Record; + directorySnapshots?: ContainerDirectorySnapshotRestoreParams[]; +} & ({ + image: string; + containerSnapshot?: never; +} | { + image?: never; + containerSnapshot?: ContainerSnapshotRestoreParams; +}); +interface ContainerInfo { + labels: Record; + image: string; +} +interface ContainerStartResources { + vcpu: number; + memoryMib: number; + diskMb: number; +} +/** + * The **`MessagePort`** interface of the Channel Messaging API represents one of the two ports of a MessageChannel, allowing messages to be sent from one port and listening out for them arriving at the other. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/MessagePort) + */ +declare abstract class MessagePort extends EventTarget { + /** + * The **`postMessage()`** method of the MessagePort interface sends a message from the port, and optionally, transfers ownership of objects to other browsing contexts. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/MessagePort/postMessage) + */ + postMessage(data?: any, options?: (any[] | MessagePortPostMessageOptions)): void; + /** + * The **`close()`** method of the MessagePort interface disconnects the port, so it is no longer active. This stops the flow of messages to that port. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/MessagePort/close) + */ + close(): void; + /** + * The **`start()`** method of the MessagePort interface starts the sending of messages queued on the port. This method is only needed when using EventTarget.addEventListener; it is implied when using onmessage. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/MessagePort/start) + */ + start(): void; + get onmessage(): any | null; + set onmessage(value: any | null); +} +/** + * The **`MessageChannel`** interface of the Channel Messaging API allows us to create a new message channel and send data through it via its two MessagePort properties. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/MessageChannel) + */ +declare class MessageChannel { + constructor(); + /** + * The **`port1`** read-only property of the MessageChannel interface returns the first port of the message channel — the port attached to the context that originated the channel. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/MessageChannel/port1) + */ + readonly port1: MessagePort; + /** + * The **`port2`** read-only property of the MessageChannel interface returns the second port of the message channel — the port attached to the context at the other end of the channel, which the message is initially sent to. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/MessageChannel/port2) + */ + readonly port2: MessagePort; +} +interface MessagePortPostMessageOptions { + transfer?: any[]; +} +type LoopbackForExport Rpc.EntrypointBranded) | ExportedHandler | undefined = undefined> = T extends new (...args: any[]) => Rpc.WorkerEntrypointBranded ? LoopbackServiceStub> : T extends new (...args: any[]) => Rpc.DurableObjectBranded ? LoopbackDurableObjectClass> : T extends new (...args: any[]) => CloudflareWorkersModule.WorkflowEntrypoint ? Workflow : T extends ExportedHandler ? LoopbackServiceStub : undefined; +type LoopbackServiceStub = Fetcher & (T extends CloudflareWorkersModule.WorkerEntrypoint ? (opts: { + props?: Props; +}) => Fetcher : (opts: { + props?: any; +}) => Fetcher); +type LoopbackDurableObjectClass = DurableObjectClass & (T extends CloudflareWorkersModule.DurableObject ? (opts: { + props?: Props; +}) => DurableObjectClass : (opts: { + props?: any; +}) => DurableObjectClass); +interface LoopbackDurableObjectNamespace extends DurableObjectNamespace { +} +interface LoopbackColoLocalActorNamespace extends ColoLocalActorNamespace { +} +interface SyncKvStorage { + get(key: string): T | undefined; + list(options?: SyncKvListOptions): Iterable<[ + string, + T + ]>; + put(key: string, value: T): void; + delete(key: string): boolean; +} +interface SyncKvListOptions { + start?: string; + startAfter?: string; + end?: string; + prefix?: string; + reverse?: boolean; + limit?: number; +} +interface WorkerStub { + getEntrypoint(name?: string, options?: WorkerStubEntrypointOptions): Fetcher; + getDurableObjectClass(name?: string, options?: WorkerStubEntrypointOptions): DurableObjectClass; +} +interface WorkerStubEntrypointOptions { + props?: any; + limits?: workerdResourceLimits; +} +interface WorkerLoader { + get(name: string | null, getCode: () => WorkerLoaderWorkerCode | Promise): WorkerStub; + load(code: WorkerLoaderWorkerCode): WorkerStub; +} +interface WorkerLoaderModule { + js?: string; + cjs?: string; + text?: string; + data?: ArrayBuffer; + json?: any; + py?: string; + wasm?: ArrayBuffer | ArrayBufferView | WebAssembly.Module; +} +interface WorkerLoaderWorkerCode { + compatibilityDate: string; + compatibilityFlags?: string[]; + allowExperimental?: boolean; + limits?: workerdResourceLimits; + mainModule: string; + modules: Record; + env?: any; + globalOutbound?: (Fetcher | null); + tails?: Fetcher[]; + streamingTails?: Fetcher[]; +} +interface workerdResourceLimits { + cpuMs?: number; + subRequests?: number; +} +/** +* The Workers runtime supports a subset of the Performance API, used to measure timing and performance, +* as well as timing of subrequests and other operations. +* +* [Cloudflare Docs Reference](https://developers.cloudflare.com/workers/runtime-apis/performance/) +*/ +declare abstract class Performance { + /* [Cloudflare Docs Reference](https://developers.cloudflare.com/workers/runtime-apis/performance/#performancetimeorigin) */ + get timeOrigin(): number; + /* [Cloudflare Docs Reference](https://developers.cloudflare.com/workers/runtime-apis/performance/#performancenow) */ + now(): number; + /** + * The **`toJSON()`** method of the Performance interface is a serializer; it returns a JSON representation of the Performance object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Performance/toJSON) + */ + toJSON(): object; +} +interface Tracing { + enterSpan(name: string, callback: (span: Span, ...args: A) => T, ...args: A): T; + startActiveSpan(name: string, callback: (span: Span, ...args: A) => T, ...args: A): T; + startSpan(name: string): Span; + getActiveSpan(): Span | undefined; + Span: typeof Span; +} +declare abstract class Span { + get isTraced(): boolean; + setAttribute(key: string, value: boolean | number | string): this; + setAttributes(attributes: Record): this; + recordException(exception: string | { + code: string | number; + name?: string; + message?: string; + stack?: string; + } | { + code?: string | number; + name: string; + message?: string; + stack?: string; + } | { + code?: string | number; + name?: string; + message: string; + stack?: string; + }): void; + updateName(name: string): this; + setStatus(status: TracingSpanStatus): this; + end(): void; +} +type TracingSpanStatusCode = "unset" | "ok" | "error"; +interface TracingSpanStatus { + code: TracingSpanStatusCode; + message?: string; +} +/** + * Represents the identity of a user authenticated via Cloudflare Access. + * This matches the result of calling /cdn-cgi/access/get-identity. + * + * The exact structure of the returned object depends on the identity provider + * configuration for the Access application. The fields below represent commonly + * available properties, but additional provider-specific fields may be present. + */ +interface CloudflareAccessIdentity extends Record { + /** The user's email address, if available from the identity provider. */ + email?: string; + /** The user's display name. */ + name?: string; + /** The user's unique identifier. */ + user_uuid?: string; + /** The Cloudflare account ID. */ + account_id?: string; + /** Login timestamp (Unix epoch seconds). */ + iat?: number; + /** The user's IP address at authentication time. */ + ip?: string; + /** Authentication methods used (e.g., "pwd"). */ + amr?: string[]; + /** Identity provider information. */ + idp?: { + id: string; + type: string; + }; + /** Geographic information about where the user authenticated. */ + geo?: { + country: string; + }; + /** Group memberships from the identity provider. */ + groups?: Array<{ + id: string; + name: string; + email?: string; + }>; + /** Device posture check results, keyed by check ID. */ + devicePosture?: Record; + /** True if the user connected via Cloudflare WARP. */ + is_warp?: boolean; + /** True if the user is authenticated via Cloudflare Gateway. */ + is_gateway?: boolean; +} +// ============================================================================ +// Agent Memory +// +// Public type surface for user Workers binding to an Agent Memory namespace. +// ============================================================================ +/** Memory type — every memory is classified into exactly one. */ +type AgentMemoryMemoryType = "fact" | "event" | "instruction" | "task"; +/** Search intensity for recall. */ +type AgentMemoryThinkingLevel = "low" | "medium" | "high"; +/** Response verbosity for recall. */ +type AgentMemoryResponseLength = "short" | "medium" | "long"; +/** A conversation message passed to ingest(). */ +interface AgentMemoryMessage { + role: "system" | "user" | "assistant"; + content: string; + /** Optional message timestamp. */ + timestamp?: Date; +} +/** Raw memory content passed to remember(). */ +interface AgentMemoryIncomingMemory { + /** Raw memory content. The service classifies and summarizes automatically. */ + content: string; + /** Optional session identifier to associate with this memory. */ + sessionId?: string | null | undefined; +} +/** A stored memory returned from remember(), get(), and delete(). */ +interface AgentMemoryMemory { + /** Memory ID. */ + id: string; + /** Memory type. */ + type: AgentMemoryMemoryType; + /** Text summary. */ + summary: string; + /** Memory text. */ + content: string; + /** Session that created this memory. */ + sessionId: string | null; + /** Memory creation time. */ + createdAt: Date; + /** Memory last-update time. */ + updatedAt: Date; +} +/** Single entry in a list() response. Same shape as Memory minus full content. */ +type AgentMemoryMemoryListEntry = Omit; +/** A scored memory candidate in a recall result. */ +interface AgentMemoryScoredCandidate { + /** Candidate ID. */ + id: string; + /** Text summary. */ + summary: string; + /** Session that created this candidate, when known. */ + sessionId: string | null; + /** Relevance score (higher is better). Comparable only within a single query. */ + score: number; +} +/** Options for the ingest() method. */ +interface AgentMemoryIngestOptions { + /** Session identifier to associate with memories created during ingestion. */ + sessionId?: string | null | undefined; +} +/** Options for the getSummary() method. */ +interface AgentMemoryGetSummaryOptions { + /** Session identifier to retrieve session summary for. */ + sessionId?: string | null | undefined; +} +/** Response from the getSummary() method. */ +interface AgentMemoryGetSummaryResponse { + /** Markdown summary. */ + summary: string; +} +/** + * Options for the recall() method. + * + * `referenceDate` accepts a Date object, an ISO-8601 date string + * (YYYY-MM-DD), or a full ISO-8601 datetime string. When provided, this + * date is used as "today" for resolving relative time references + * ("how many days ago", "last week") instead of the server's wall-clock time. + */ +interface AgentMemoryRecallOptions { + /** Recall intensity: "low" (default), "medium", or "high". */ + thinkingLevel?: AgentMemoryThinkingLevel; + /** Response verbosity: "short", "medium" (default), or "long". */ + responseLength?: AgentMemoryResponseLength; + /** Temporal anchor for date arithmetic. */ + referenceDate?: Date | string; +} +/** Response from the recall() method. */ +interface AgentMemoryRecallResult { + /** Number of memories retrieved. */ + count: number; + /** LLM-generated answer synthesizing the matching memories. */ + answer: string; + /** Matching memories ranked by relevance. */ + candidates: AgentMemoryScoredCandidate[]; +} +/** + * Options for the list() method. + * + * `cursor` is the opaque continuation token returned by the previous page; + * pass it back unchanged to fetch the next page. `sessionId` and `type` + * are exact-match filters; combining them is allowed. + */ +interface AgentMemoryListMemoriesOptions { + /** Maximum number of memories to return. Default 20, max 500. */ + limit?: number; + /** Opaque cursor from a previous page. */ + cursor?: string; + /** Exact-match session filter. */ + sessionId?: string; + /** Exact-match memory-type filter. */ + type?: AgentMemoryMemoryType; +} +/** Response from the list() method. */ +interface AgentMemoryListMemoriesResult { + memories: AgentMemoryMemoryListEntry[]; + /** Continuation cursor; absent when this page exhausted the result set. */ + cursor?: string; +} +/** + * A single Agent Memory profile, scoped to a profile name. + * + * Returned by {@link AgentMemoryNamespace.getProfile}. + */ +declare abstract class AgentMemoryProfile { + /** + * Retrieve a memory by ID. + * + * @param memoryId - ULID of the memory to retrieve. + * @throws if the memory does not exist. + */ + get(memoryId: string): Promise; + /** + * Delete a memory by ID. + * + * Removes the memory and any source messages linked by the memory's + * source message IDs. + * + * @param memoryId - ULID of the memory to delete. + * @throws if the memory does not exist. + */ + delete(memoryId: string): Promise; + /** + * Store a memory in this profile. The content is automatically classified, + * summarized, and indexed. + * + * @param memory - Raw memory content to persist. + */ + remember(memory: AgentMemoryIncomingMemory): Promise; + /** + * Extract memories from a conversation. + * + * @param messages - Conversation messages to extract memories from. + * @param options - Optional ingest options. + */ + ingest(messages: Iterable, options?: AgentMemoryIngestOptions): Promise; + /** + * Get a profile summary. + * + * @param options - Optional getSummary options. + */ + getSummary(options?: AgentMemoryGetSummaryOptions): Promise; + /** + * Recall memories in this profile. + * + * @param query - Recall query matched against memory content and keywords. + * @param options - Optional recall parameters. + * @returns Matching memories with relevance scores and a synthesized answer. + */ + recall(query: string, options?: AgentMemoryRecallOptions): Promise; + /** + * List active memories in this profile. + * + * Returns a paginated, filterable view of stored memories. Superseded + * versions are excluded. Use the returned `cursor` (when present) to + * fetch the next page. + * + * @param options - Optional pagination and filter options. + */ + list(options?: AgentMemoryListMemoriesOptions): Promise; + /** + * Soft-delete every memory and message in this profile that is tagged + * with `sessionId`. + * + * Idempotent: deleting a sessionId that has no rows is a no-op. + * + * @param sessionId - Session to delete. + */ + deleteSession(sessionId: string): Promise; +} +/** + * Namespace-level Agent Memory binding. + * + * Used as the type of an `env.MEMORY`-style binding backed by the Agent + * Memory product. + * + * @example + * ```ts + * export default { + * async fetch(_request: Request, env: Env): Promise { + * const profile = await env.MEMORY.getProfile("wrangler-e2e"); + * const summary = await profile.getSummary(); + * return Response.json(summary); + * }, + * }; + * ``` + */ +declare abstract class AgentMemoryNamespace { + /** + * Get a memory profile by name. Profiles are isolated by namespace and + * addressed by a compound key (namespaceId:profileName). + * + * @param profileName - Profile name (validated against naming rules). + * @returns RPC target for interacting with the profile. + */ + getProfile(profileName: string): Promise; + /** + * Soft-delete a profile and schedule deferred purge. Marks all + * memories and messages as deleted. + * + * @param profileName - Name of the profile to delete. + */ + deleteProfile(profileName: string): Promise; +} +// ============ AI Search Error Interfaces ============ +interface AiSearchInternalError extends Error { +} +interface AiSearchNotFoundError extends Error { +} +// ============ AI Search Common Types ============ +/** A single message in a conversation-style search or chat request. */ +type AiSearchMessage = { + role: 'system' | 'developer' | 'user' | 'assistant' | 'tool'; + content: string | null; +}; +/** + * Common shape for `ai_search_options` used by both single-instance and multi-instance requests. + * Contains retrieval, query rewrite, reranking, and cache sub-options. + */ +type AiSearchOptions = { + retrieval?: { + /** Which retrieval backend to use. Defaults to the instance's configured index_method. */ + retrieval_type?: 'vector' | 'keyword' | 'hybrid'; + /** Fusion method for combining vector + keyword results. */ + fusion_method?: 'max' | 'rrf'; + /** How keyword terms are combined: "and" = all terms must match, "or" = any term matches. */ + keyword_match_mode?: 'and' | 'or'; + /** Minimum similarity score (0-1) for a result to be included. Default 0.4. */ + match_threshold?: number; + /** Maximum number of results to return (1-50). Default 10. */ + max_num_results?: number; + /** Vectorize metadata filters applied to the search. */ + filters?: VectorizeVectorMetadataFilter; + /** Number of surrounding chunks to include for context (0-3). Default 0. */ + context_expansion?: number; + /** If true, return only item metadata without chunk text. */ + metadata_only?: boolean; + /** If true (default), return empty results on retrieval failure instead of throwing. */ + return_on_failure?: boolean; + /** Boost results by metadata field values. Max 3 entries. */ + boost_by?: Array<{ + field: string; + direction?: 'asc' | 'desc' | 'exists' | 'not_exists'; + }>; + [key: string]: unknown; + }; + query_rewrite?: { + enabled?: boolean; + model?: string; + rewrite_prompt?: string; + [key: string]: unknown; + }; + reranking?: { + enabled?: boolean; + model?: string; + /** Match threshold (0-1, default 0.4) */ + match_threshold?: number; + [key: string]: unknown; + }; + cache?: { + enabled?: boolean; + cache_threshold?: 'super_strict_match' | 'close_enough' | 'flexible_friend' | 'anything_goes'; + }; + [key: string]: unknown; +}; +// ============ AI Search Request Types ============ +/** + * Request body for single-instance search. + * Exactly one of `query` or `messages` must be provided. + */ +type AiSearchSearchRequest = { + /** Simple query string. */ + query: string; + messages?: never; + ai_search_options?: AiSearchOptions; +} | { + query?: never; + /** Conversation-style input. At least one user message with non-empty content is required. */ + messages: AiSearchMessage[]; + ai_search_options?: AiSearchOptions; +}; +type AiSearchChatCompletionsRequest = { + messages: AiSearchMessage[]; + model?: string; + stream?: boolean; + ai_search_options?: AiSearchOptions; + [key: string]: unknown; +}; +// ============ AI Search Multi-Instance Types (Namespace-Scoped) ============ +/** `ai_search_options` shape for multi-instance requests — requires `instance_ids`. */ +type AiSearchMultiSearchOptions = AiSearchOptions & { + /** Instance IDs to search across (1-10). */ + instance_ids: string[]; +}; +/** + * Request for searching across multiple instances within a namespace. + * `ai_search_options` is required and must include `instance_ids`. + * Exactly one of `query` or `messages` must be provided. + */ +type AiSearchMultiSearchRequest = { + /** Simple query string. */ + query: string; + messages?: never; + ai_search_options: AiSearchMultiSearchOptions; +} | { + query?: never; + /** Conversation-style input. */ + messages: AiSearchMessage[]; + ai_search_options: AiSearchMultiSearchOptions; +}; +/** A search result chunk tagged with the instance it originated from. */ +type AiSearchMultiSearchChunk = AiSearchSearchResponse['chunks'][number] & { + instance_id: string; +}; +/** Describes a per-instance error during a multi-instance operation. */ +type AiSearchMultiSearchError = { + instance_id: string; + message: string; +}; +/** Response from a multi-instance search, with chunks tagged by instance and optional partial-failure errors. */ +type AiSearchMultiSearchResponse = { + search_query: string; + chunks: AiSearchMultiSearchChunk[]; + errors?: AiSearchMultiSearchError[]; +}; +/** Request for chat completions across multiple instances within a namespace. `ai_search_options` is required and must include `instance_ids`. */ +type AiSearchMultiChatCompletionsRequest = Omit & { + ai_search_options: AiSearchMultiSearchOptions; +}; +/** Response from multi-instance chat completions, with chunks tagged by instance and optional partial-failure errors. */ +type AiSearchMultiChatCompletionsResponse = Omit & { + chunks: AiSearchMultiSearchChunk[]; + errors?: AiSearchMultiSearchError[]; +}; +// ============ AI Search Response Types ============ +type AiSearchSearchResponse = { + search_query: string; + chunks: Array<{ + id: string; + type: string; + /** Match score (0-1) */ + score: number; + text: string; + item: { + timestamp?: number; + key: string; + metadata?: Record; + }; + scoring_details?: { + /** Keyword match score (0-1) */ + keyword_score?: number; + /** Vector similarity score (0-1) */ + vector_score?: number; + /** Keyword rank position */ + keyword_rank?: number; + /** Vector rank position */ + vector_rank?: number; + /** Reranking model score */ + reranking_score?: number; + /** Fusion method used to combine results */ + fusion_method?: 'rrf' | 'max'; + [key: string]: unknown; + }; + }>; +}; +type AiSearchChatCompletionsResponse = { + id?: string; + object?: string; + model?: string; + choices: Array<{ + index?: number; + message: { + role: 'system' | 'developer' | 'user' | 'assistant' | 'tool'; + content: string | null; + [key: string]: unknown; + }; + [key: string]: unknown; + }>; + chunks: AiSearchSearchResponse['chunks']; + [key: string]: unknown; +}; +type AiSearchStatsResponse = { + queued?: number; + running?: number; + completed?: number; + error?: number; + skipped?: number; + outdated?: number; + last_activity?: string; + /** Storage engine statistics. */ + engine?: { + vectorize?: { + vectorsCount: number; + dimensions: number; + }; + r2?: { + payloadSizeBytes: number; + metadataSizeBytes: number; + objectCount: number; + }; + }; +}; +// ============ AI Search Instance Info Types ============ +type AiSearchInstanceInfo = { + id: string; + type?: 'r2' | 'web-crawler' | string; + source?: string; + source_params?: unknown; + paused?: boolean; + status?: string; + namespace?: string; + created_at?: string; + modified_at?: string; + token_id?: string; + ai_gateway_id?: string; + rewrite_query?: boolean; + reranking?: boolean; + embedding_model?: string; + ai_search_model?: string; + rewrite_model?: string; + reranking_model?: string; + /** @deprecated Use index_method instead. */ + hybrid_search_enabled?: boolean; + /** Controls which storage backends are active. */ + index_method?: { + vector?: boolean; + keyword?: boolean; + }; + /** Fusion method for combining vector and keyword results. */ + fusion_method?: 'max' | 'rrf'; + indexing_options?: { + keyword_tokenizer?: 'porter' | 'trigram'; + } | null; + retrieval_options?: { + keyword_match_mode?: 'and' | 'or'; + boost_by?: Array<{ + field: string; + direction?: 'asc' | 'desc' | 'exists' | 'not_exists'; + }>; + } | null; + chunk?: boolean; + chunk_size?: number; + chunk_overlap?: number; + score_threshold?: number; + max_num_results?: number; + cache?: boolean; + cache_threshold?: 'super_strict_match' | 'close_enough' | 'flexible_friend' | 'anything_goes'; + custom_metadata?: Array<{ + field_name: string; + data_type: 'text' | 'number' | 'boolean' | 'datetime'; + }>; + /** Sync interval in seconds. */ + sync_interval?: 3600 | 7200 | 14400 | 21600 | 43200 | 86400; + metadata?: Record; + [key: string]: unknown; +}; +/** Pagination, search, and ordering parameters for listing instances within a namespace. */ +type AiSearchListInstancesParams = { + page?: number; + per_page?: number; + /** Search instances by ID. */ + search?: string; + /** Field to sort by. */ + order_by?: 'created_at'; + /** Sort direction. */ + order_by_direction?: 'asc' | 'desc'; +}; +type AiSearchListResponse = { + result: AiSearchInstanceInfo[]; + result_info?: { + count: number; + page: number; + per_page: number; + total_count: number; + }; +}; +// ============ AI Search Config Types ============ +type AiSearchConfig = { + /** Instance ID (1-32 chars, pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$) */ + id: string; + /** Instance type. Omit to create with built-in storage. */ + type?: 'r2' | 'web-crawler' | string; + /** Source URL (required for web-crawler type). */ + source?: string; + source_params?: unknown; + /** Token ID (UUID format) */ + token_id?: string; + ai_gateway_id?: string; + /** Enable query rewriting (default false) */ + rewrite_query?: boolean; + /** Enable reranking (default false) */ + reranking?: boolean; + embedding_model?: string; + ai_search_model?: string; + rewrite_model?: string; + reranking_model?: string; + /** @deprecated Use index_method instead. */ + hybrid_search_enabled?: boolean; + /** Controls which storage backends are used during indexing. Defaults to vector-only. */ + index_method?: { + vector?: boolean; + keyword?: boolean; + }; + /** Fusion method for combining vector and keyword results. "rrf" = reciprocal rank fusion (default), "max" = maximum score. */ + fusion_method?: 'max' | 'rrf'; + indexing_options?: { + keyword_tokenizer?: 'porter' | 'trigram'; + } | null; + retrieval_options?: { + keyword_match_mode?: 'and' | 'or'; + boost_by?: Array<{ + field: string; + direction?: 'asc' | 'desc' | 'exists' | 'not_exists'; + }>; + } | null; + chunk?: boolean; + chunk_size?: number; + chunk_overlap?: number; + /** Minimum similarity score (0-1) for a result to be included. */ + score_threshold?: number; + max_num_results?: number; + cache?: boolean; + /** Similarity threshold for cache hits. Stricter = fewer cache hits but higher relevance. */ + cache_threshold?: 'super_strict_match' | 'close_enough' | 'flexible_friend' | 'anything_goes'; + custom_metadata?: Array<{ + field_name: string; + data_type: 'text' | 'number' | 'boolean' | 'datetime'; + }>; + namespace?: string; + /** Sync interval in seconds. 3600=1h, 7200=2h, 14400=4h, 21600=6h, 43200=12h, 86400=24h. */ + sync_interval?: 3600 | 7200 | 14400 | 21600 | 43200 | 86400; + metadata?: Record; + [key: string]: unknown; +}; +// ============ AI Search Item Types ============ +type AiSearchItemInfo = { + id: string; + key: string; + status: 'completed' | 'error' | 'skipped' | 'queued' | 'running' | 'outdated'; + next_action?: 'INDEX' | 'DELETE' | null; + error?: string; + checksum?: string; + namespace?: string; + chunks_count?: number | null; + file_size?: number | null; + source_id?: string | null; + last_seen_at?: string; + created_at?: string; + metadata?: Record; + [key: string]: unknown; +}; +type AiSearchItemContentResult = { + body: ReadableStream; + contentType: string; + filename: string; + size: number; +}; +type AiSearchUploadItemOptions = { + metadata?: Record; +}; +type AiSearchListItemsParams = { + page?: number; + per_page?: number; + /** Search items by key name. */ + search?: string; + /** Sort order for results. */ + sort_by?: 'status' | 'modified_at'; + /** Filter items by processing status. */ + status?: 'queued' | 'running' | 'completed' | 'error' | 'skipped' | 'outdated'; + /** Filter items by source (e.g. "builtin" or "web-crawler:https://example.com"). */ + source?: string; + /** JSON-encoded Vectorize filter for metadata filtering. */ + metadata_filter?: string; + /** Filter items by their unique ID. Returns at most one item. */ + item_id?: string; + /** + * Filter items by their exact key (object key / filename). Keys are unique + * per source, so combine with `source` to disambiguate across data sources. + */ + key?: string; +}; +type AiSearchListItemsResponse = { + result: AiSearchItemInfo[]; + result_info?: { + count: number; + page: number; + per_page: number; + total_count: number; + }; +}; +// ============ AI Search Item Logs Types ============ +type AiSearchItemLogsParams = { + /** Maximum number of log entries to return (1-100, default 50). */ + limit?: number; + /** Opaque cursor for pagination. Pass the `cursor` value from a previous response. */ + cursor?: string; +}; +type AiSearchItemLog = { + timestamp: string; + action: string; + message: string; + fileKey?: string; + chunkCount?: number; + processingTimeMs?: number; + errorType?: string; +}; +/** Paginated response for item processing logs (cursor-based). */ +type AiSearchItemLogsResponse = { + result: AiSearchItemLog[]; + result_info: { + count: number; + per_page: number; + cursor: string | null; + truncated: boolean; + }; +}; +// ============ AI Search Item Chunks Types ============ +type AiSearchItemChunksParams = { + /** Maximum number of chunks to return (1-100, default 20). */ + limit?: number; + /** Offset into the chunks list (default 0). */ + offset?: number; +}; +/** A single indexed chunk belonging to an item, including its text content and byte range. */ +type AiSearchItemChunk = { + id: string; + text: string; + start_byte: number; + end_byte: number; + item?: { + timestamp?: number; + key: string; + metadata?: Record; + }; +}; +/** Paginated response for item chunks (offset-based). */ +type AiSearchItemChunksResponse = { + result: AiSearchItemChunk[]; + result_info: { + count: number; + total: number; + limit: number; + offset: number; + }; +}; +// ============ AI Search Job Types ============ +type AiSearchJobInfo = { + id: string; + source: 'user' | 'schedule'; + description?: string; + last_seen_at?: string; + started_at?: string; + ended_at?: string; + end_reason?: string; +}; +type AiSearchJobLog = { + id: number; + message: string; + message_type: number; + created_at: number; +}; +type AiSearchCreateJobParams = { + description?: string; +}; +type AiSearchListJobsParams = { + page?: number; + per_page?: number; +}; +type AiSearchListJobsResponse = { + result: AiSearchJobInfo[]; + result_info?: { + count: number; + page: number; + per_page: number; + total_count: number; + }; +}; +type AiSearchJobLogsParams = { + page?: number; + per_page?: number; +}; +type AiSearchJobLogsResponse = { + result: AiSearchJobLog[]; + result_info?: { + count: number; + page: number; + per_page: number; + total_count: number; + }; +}; +// ============ AI Search Sub-Service Classes ============ +/** + * Single item service for an AI Search instance. + * Provides info, download, sync, logs, and chunks operations on a specific item. + */ +declare abstract class AiSearchItem { + /** Get metadata about this item. */ + info(): Promise; + /** + * Download the item's content. + * @returns Object with body stream, content type, filename, and size. + */ + download(): Promise; + /** + * Trigger re-indexing of this item. + * @returns The updated item info. + */ + sync(): Promise; + /** + * Retrieve processing logs for this item (cursor-based pagination). + * @param params Optional pagination parameters (limit, cursor). + * @returns Paginated log entries for this item. + */ + logs(params?: AiSearchItemLogsParams): Promise; + /** + * List indexed chunks for this item (offset-based pagination). + * @param params Optional pagination parameters (limit, offset). + * @returns Paginated chunk entries for this item. + */ + chunks(params?: AiSearchItemChunksParams): Promise; +} +/** + * Items collection service for an AI Search instance. + * Provides list, upload, and access to individual items. + */ +declare abstract class AiSearchItems { + /** List items in this instance. */ + list(params?: AiSearchListItemsParams): Promise; + /** + * Upload a file as an item. Behaves as an upsert: if an item with the same + * filename already exists, it is overwritten and re-indexed. + * @param name Filename for the uploaded item. + * @param content File content as a ReadableStream, Blob, or string. + * @param options Optional metadata to attach to the item. + * @returns The created item info. + */ + upload(name: string, content: ReadableStream | Blob | string, options?: AiSearchUploadItemOptions): Promise; + /** + * Upload a file and poll until processing completes. + * Behaves as an upsert: if an item with the same filename already exists, + * it is overwritten and re-indexed. + * @param name Filename for the uploaded item. + * @param content File content as a ReadableStream, Blob, or string. + * @param options Optional metadata and polling configuration. + * @returns The item info after processing completes (or timeout). + */ + uploadAndPoll(name: string, content: ReadableStream | Blob | string, options?: AiSearchUploadItemOptions & { + /** Polling interval in milliseconds (default 1000). */ + pollIntervalMs?: number; + /** Maximum time to wait in milliseconds (default 30000). */ + timeoutMs?: number; + }): Promise; + /** + * Get an item by ID. + * @param itemId The item identifier. + * @returns Item service for info, download, sync, logs, and chunks operations. + */ + get(itemId: string): AiSearchItem; + /** + * Delete an item from the instance. + * @param itemId The item identifier. + */ + delete(itemId: string): Promise; +} +/** + * Single job service for an AI Search instance. + * Provides info, logs, and cancel operations for a specific job. + */ +declare abstract class AiSearchJob { + /** Get metadata about this job. */ + info(): Promise; + /** Get logs for this job. */ + logs(params?: AiSearchJobLogsParams): Promise; + /** + * Cancel a running job. + * @returns The updated job info. + * @throws AiSearchNotFoundError if the job does not exist. + */ + cancel(): Promise; +} +/** + * Jobs collection service for an AI Search instance. + * Provides list, create, and access to individual jobs. + */ +declare abstract class AiSearchJobs { + /** List jobs for this instance. */ + list(params?: AiSearchListJobsParams): Promise; + /** + * Create a new indexing job. + * @param params Optional job parameters. + * @returns The created job info. + */ + create(params?: AiSearchCreateJobParams): Promise; + /** + * Get a job by ID. + * @param jobId The job identifier. + * @returns Job service for info, logs, and cancel operations. + */ + get(jobId: string): AiSearchJob; +} +// ============ AI Search Binding Classes ============ +/** + * Instance-level AI Search service. + * + * Used as: + * - The return type of `AiSearchNamespace.get(name)` (namespace binding) + * - The type of `env.BLOG_SEARCH` (single instance binding via `ai_search`) + * + * Provides search, chat, update, stats, items, and jobs operations. + * + * @example + * ```ts + * // Via namespace binding + * const instance = env.AI_SEARCH.get("blog"); + * const results = await instance.search({ + * query: "How does caching work?", + * }); + * + * // Via single instance binding + * const results = await env.BLOG_SEARCH.search({ + * messages: [{ role: "user", content: "How does caching work?" }], + * }); + * ``` + */ +declare abstract class AiSearchInstance { + /** + * Search the AI Search instance for relevant chunks. + * @param params Search request with query or messages and optional AI search options. + * @returns Search response with matching chunks and search query. + */ + search(params: AiSearchSearchRequest): Promise; + /** + * Generate chat completions with AI Search context (streaming). + * @param params Chat completions request with stream: true. + * @returns ReadableStream of server-sent events. + */ + chatCompletions(params: AiSearchChatCompletionsRequest & { + stream: true; + }): Promise; + /** + * Generate chat completions with AI Search context. + * @param params Chat completions request. + * @returns Chat completion response with choices and RAG chunks. + */ + chatCompletions(params: AiSearchChatCompletionsRequest): Promise; + /** + * Update the instance configuration. + * @param config Partial configuration to update. + * @returns Updated instance info. + */ + update(config: Partial): Promise; + /** Get metadata about this instance. */ + info(): Promise; + /** + * Get instance statistics (item count, indexing status, etc.). + * @returns Statistics with counts per status, last activity time, and engine details. + */ + stats(): Promise; + /** Items collection — list, upload, and manage items in this instance. */ + get items(): AiSearchItems; + /** Jobs collection — list, create, and inspect indexing jobs. */ + get jobs(): AiSearchJobs; +} +/** + * Namespace-level AI Search service. + * + * Used as the type of `env.AI_SEARCH` (namespace binding via `ai_search_namespaces`). + * Scoped to a single namespace. Provides dynamic instance access, creation, deletion, + * and multi-instance search/chat operations. + * + * @example + * ```ts + * // Access an instance within the namespace + * const blog = env.AI_SEARCH.get("blog"); + * const results = await blog.search({ query: "How does caching work?" }); + * + * // List all instances in the namespace + * const instances = await env.AI_SEARCH.list(); + * + * // Create a new instance with built-in storage + * const tenant = await env.AI_SEARCH.create({ id: "tenant-123" }); + * + * // Upload items into the instance + * await tenant.items.upload("doc.pdf", fileContent); + * + * // Search across multiple instances + * const multi = await env.AI_SEARCH.search({ + * query: "caching", + * ai_search_options: { instance_ids: ["blog", "docs"] }, + * }); + * + * // Delete an instance + * await env.AI_SEARCH.delete("tenant-123"); + * ``` + */ +declare abstract class AiSearchNamespace { + /** + * Get an instance by name within the bound namespace. + * @param name Instance name. + * @returns Instance service for search, chat, update, stats, items, and jobs. + */ + get(name: string): AiSearchInstance; + /** + * List instances in the bound namespace. + * @param params Optional pagination, search, and ordering parameters. + * @returns Array of instance metadata with pagination info. + */ + list(params?: AiSearchListInstancesParams): Promise; + /** + * Create a new instance within the bound namespace. + * @param config Instance configuration. Only `id` is required — omit `type` and `source` to create with built-in storage. + * @returns Instance service for the newly created instance. + * + * @example + * ```ts + * // Create with built-in storage (upload items manually) + * const instance = await env.AI_SEARCH.create({ id: "my-search" }); + * + * // Create with web crawler source + * const instance = await env.AI_SEARCH.create({ + * id: "docs-search", + * type: "web-crawler", + * source: "https://developers.cloudflare.com", + * }); + * ``` + */ + create(config: AiSearchConfig): Promise; + /** + * Delete an instance from the bound namespace. + * @param name Instance name to delete. + */ + delete(name: string): Promise; + /** + * Search across multiple instances within the bound namespace. + * Fans out to the specified instance_ids and merges results. + * @param params Search request with required `ai_search_options.instance_ids`. + * @returns Search response with chunks tagged by instance_id and optional partial-failure errors. + */ + search(params: AiSearchMultiSearchRequest): Promise; + /** + * Generate chat completions across multiple instances within the bound namespace (streaming). + * Fans out to the specified instance_ids, merges context, and generates a response. + * @param params Chat completions request with stream: true and required `ai_search_options.instance_ids`. + * @returns ReadableStream of server-sent events. + */ + chatCompletions(params: AiSearchMultiChatCompletionsRequest & { + stream: true; + }): Promise; + /** + * Generate chat completions across multiple instances within the bound namespace. + * Fans out to the specified instance_ids, merges context, and generates a response. + * @param params Chat completions request with required `ai_search_options.instance_ids`. + * @returns Chat completion response with choices, chunks tagged by instance_id, and optional partial-failure errors. + */ + chatCompletions(params: AiSearchMultiChatCompletionsRequest): Promise; +} +type AiImageClassificationInput = { + image: number[]; +}; +type AiImageClassificationOutput = { + score?: number; + label?: string; +}[]; +declare abstract class BaseAiImageClassification { + inputs: AiImageClassificationInput; + postProcessedOutputs: AiImageClassificationOutput; +} +type AiImageToTextInput = { + image: number[]; + prompt?: string; + max_tokens?: number; + temperature?: number; + top_p?: number; + top_k?: number; + seed?: number; + repetition_penalty?: number; + frequency_penalty?: number; + presence_penalty?: number; + raw?: boolean; + messages?: RoleScopedChatInput[]; +}; +type AiImageToTextOutput = { + description: string; +}; +declare abstract class BaseAiImageToText { + inputs: AiImageToTextInput; + postProcessedOutputs: AiImageToTextOutput; +} +type AiImageTextToTextInput = { + image: string; + prompt?: string; + max_tokens?: number; + temperature?: number; + ignore_eos?: boolean; + top_p?: number; + top_k?: number; + seed?: number; + repetition_penalty?: number; + frequency_penalty?: number; + presence_penalty?: number; + raw?: boolean; + messages?: RoleScopedChatInput[]; +}; +type AiImageTextToTextOutput = { + description: string; +}; +declare abstract class BaseAiImageTextToText { + inputs: AiImageTextToTextInput; + postProcessedOutputs: AiImageTextToTextOutput; +} +type AiMultimodalEmbeddingsInput = { + image: string; + text: string[]; +}; +type AiIMultimodalEmbeddingsOutput = { + data: number[][]; + shape: number[]; +}; +declare abstract class BaseAiMultimodalEmbeddings { + inputs: AiImageTextToTextInput; + postProcessedOutputs: AiImageTextToTextOutput; +} +type AiObjectDetectionInput = { + image: number[]; +}; +type AiObjectDetectionOutput = { + score?: number; + label?: string; +}[]; +declare abstract class BaseAiObjectDetection { + inputs: AiObjectDetectionInput; + postProcessedOutputs: AiObjectDetectionOutput; +} +type AiSentenceSimilarityInput = { + source: string; + sentences: string[]; +}; +type AiSentenceSimilarityOutput = number[]; +declare abstract class BaseAiSentenceSimilarity { + inputs: AiSentenceSimilarityInput; + postProcessedOutputs: AiSentenceSimilarityOutput; +} +type AiAutomaticSpeechRecognitionInput = { + audio: number[]; +}; +type AiAutomaticSpeechRecognitionOutput = { + text?: string; + words?: { + word: string; + start: number; + end: number; + }[]; + vtt?: string; +}; +declare abstract class BaseAiAutomaticSpeechRecognition { + inputs: AiAutomaticSpeechRecognitionInput; + postProcessedOutputs: AiAutomaticSpeechRecognitionOutput; +} +type AiSummarizationInput = { + input_text: string; + max_length?: number; +}; +type AiSummarizationOutput = { + summary: string; +}; +declare abstract class BaseAiSummarization { + inputs: AiSummarizationInput; + postProcessedOutputs: AiSummarizationOutput; +} +type AiTextClassificationInput = { + text: string; +}; +type AiTextClassificationOutput = { + score?: number; + label?: string; +}[]; +declare abstract class BaseAiTextClassification { + inputs: AiTextClassificationInput; + postProcessedOutputs: AiTextClassificationOutput; +} +type AiTextEmbeddingsInput = { + text: string | string[]; +}; +type AiTextEmbeddingsOutput = { + shape: number[]; + data: number[][]; +}; +declare abstract class BaseAiTextEmbeddings { + inputs: AiTextEmbeddingsInput; + postProcessedOutputs: AiTextEmbeddingsOutput; +} +type RoleScopedChatInput = { + role: "user" | "assistant" | "system" | "tool" | (string & NonNullable); + content: string; + name?: string; +}; +type AiTextGenerationToolLegacyInput = { + name: string; + description: string; + parameters?: { + type: "object" | (string & NonNullable); + properties: { + [key: string]: { + type: string; + description?: string; + }; + }; + required: string[]; + }; +}; +type AiTextGenerationToolInput = { + type: "function" | (string & NonNullable); + function: { + name: string; + description: string; + parameters?: { + type: "object" | (string & NonNullable); + properties: { + [key: string]: { + type: string; + description?: string; + }; + }; + required: string[]; + }; + }; +}; +type AiTextGenerationFunctionsInput = { + name: string; + code: string; +}; +type AiTextGenerationResponseFormat = { + type: string; + json_schema?: any; +}; +type AiTextGenerationInput = { + prompt?: string; + raw?: boolean; + stream?: boolean; + max_tokens?: number; + temperature?: number; + top_p?: number; + top_k?: number; + seed?: number; + repetition_penalty?: number; + frequency_penalty?: number; + presence_penalty?: number; + messages?: RoleScopedChatInput[]; + response_format?: AiTextGenerationResponseFormat; + tools?: AiTextGenerationToolInput[] | AiTextGenerationToolLegacyInput[] | (object & NonNullable); + functions?: AiTextGenerationFunctionsInput[]; +}; +type AiTextGenerationToolLegacyOutput = { + name: string; + arguments: unknown; +}; +type AiTextGenerationToolOutput = { + id: string; + type: "function"; + function: { + name: string; + arguments: string; + }; +}; +type UsageTags = { + prompt_tokens: number; + completion_tokens: number; + total_tokens: number; +}; +type AiTextGenerationOutput = { + response?: string; + tool_calls?: AiTextGenerationToolLegacyOutput[] & AiTextGenerationToolOutput[]; + usage?: UsageTags; +}; +declare abstract class BaseAiTextGeneration { + inputs: AiTextGenerationInput; + postProcessedOutputs: AiTextGenerationOutput; +} +type AiTextToSpeechInput = { + prompt: string; + lang?: string; +}; +type AiTextToSpeechOutput = Uint8Array | { + audio: string; +}; +declare abstract class BaseAiTextToSpeech { + inputs: AiTextToSpeechInput; + postProcessedOutputs: AiTextToSpeechOutput; +} +type AiTextToImageInput = { + prompt: string; + negative_prompt?: string; + height?: number; + width?: number; + image?: number[]; + image_b64?: string; + mask?: number[]; + num_steps?: number; + strength?: number; + guidance?: number; + seed?: number; +}; +type AiTextToImageOutput = ReadableStream; +declare abstract class BaseAiTextToImage { + inputs: AiTextToImageInput; + postProcessedOutputs: AiTextToImageOutput; +} +type AiTranslationInput = { + text: string; + target_lang: string; + source_lang?: string; +}; +type AiTranslationOutput = { + translated_text?: string; +}; +declare abstract class BaseAiTranslation { + inputs: AiTranslationInput; + postProcessedOutputs: AiTranslationOutput; +} +/** + * Workers AI support for OpenAI's Chat Completions API + */ +type ChatCompletionContentPartText = { + type: "text"; + text: string; +}; +type ChatCompletionContentPartImage = { + type: "image_url"; + image_url: { + url: string; + detail?: "auto" | "low" | "high"; + }; +}; +type ChatCompletionContentPartInputAudio = { + type: "input_audio"; + input_audio: { + /** Base64 encoded audio data. */ + data: string; + format: "wav" | "mp3"; + }; +}; +type ChatCompletionContentPartFile = { + type: "file"; + file: { + /** Base64 encoded file data. */ + file_data?: string; + /** The ID of an uploaded file. */ + file_id?: string; + filename?: string; + }; +}; +type ChatCompletionContentPartRefusal = { + type: "refusal"; + refusal: string; +}; +type ChatCompletionContentPart = ChatCompletionContentPartText | ChatCompletionContentPartImage | ChatCompletionContentPartInputAudio | ChatCompletionContentPartFile; +type FunctionDefinition = { + name: string; + description?: string; + parameters?: Record; + strict?: boolean | null; +}; +type ChatCompletionFunctionTool = { + type: "function"; + function: FunctionDefinition; +}; +type ChatCompletionCustomToolGrammarFormat = { + type: "grammar"; + grammar: { + definition: string; + syntax: "lark" | "regex"; + }; +}; +type ChatCompletionCustomToolTextFormat = { + type: "text"; +}; +type ChatCompletionCustomToolFormat = ChatCompletionCustomToolTextFormat | ChatCompletionCustomToolGrammarFormat; +type ChatCompletionCustomTool = { + type: "custom"; + custom: { + name: string; + description?: string; + format?: ChatCompletionCustomToolFormat; + }; +}; +type ChatCompletionTool = ChatCompletionFunctionTool | ChatCompletionCustomTool; +type ChatCompletionMessageFunctionToolCall = { + id: string; + type: "function"; + function: { + name: string; + /** JSON-encoded arguments string. */ + arguments: string; + }; +}; +type ChatCompletionMessageCustomToolCall = { + id: string; + type: "custom"; + custom: { + name: string; + input: string; + }; +}; +type ChatCompletionMessageToolCall = ChatCompletionMessageFunctionToolCall | ChatCompletionMessageCustomToolCall; +type ChatCompletionToolChoiceFunction = { + type: "function"; + function: { + name: string; + }; +}; +type ChatCompletionToolChoiceCustom = { + type: "custom"; + custom: { + name: string; + }; +}; +type ChatCompletionToolChoiceAllowedTools = { + type: "allowed_tools"; + allowed_tools: { + mode: "auto" | "required"; + tools: Array>; + }; +}; +type ChatCompletionToolChoiceOption = "none" | "auto" | "required" | ChatCompletionToolChoiceFunction | ChatCompletionToolChoiceCustom | ChatCompletionToolChoiceAllowedTools; +type DeveloperMessage = { + role: "developer"; + content: string | Array<{ + type: "text"; + text: string; + }>; + name?: string; +}; +type SystemMessage = { + role: "system"; + content: string | Array<{ + type: "text"; + text: string; + }>; + name?: string; +}; +/** + * Permissive merged content part used inside UserMessage arrays. + * + * Cabidela has a limitation where anyOf/oneOf with enum-based discrimination + * inside nested array items does not correctly match different branches for + * different array elements, so the schema uses a single merged object. + */ +type UserMessageContentPart = { + type: "text" | "image_url" | "input_audio" | "file"; + text?: string; + image_url?: { + url?: string; + detail?: "auto" | "low" | "high"; + }; + input_audio?: { + data?: string; + format?: "wav" | "mp3"; + }; + file?: { + file_data?: string; + file_id?: string; + filename?: string; + }; +}; +type UserMessage = { + role: "user"; + content: string | Array; + name?: string; +}; +type AssistantMessageContentPart = { + type: "text" | "refusal"; + text?: string; + refusal?: string; +}; +type AssistantMessage = { + role: "assistant"; + content?: string | null | Array; + refusal?: string | null; + name?: string; + audio?: { + id: string; + }; + tool_calls?: Array; + function_call?: { + name: string; + arguments: string; + }; +}; +type ToolMessage = { + role: "tool"; + content: string | Array<{ + type: "text"; + text: string; + }>; + tool_call_id: string; +}; +type FunctionMessage = { + role: "function"; + content: string; + name: string; +}; +type ChatCompletionMessageParam = DeveloperMessage | SystemMessage | UserMessage | AssistantMessage | ToolMessage | FunctionMessage; +type ChatCompletionsResponseFormatText = { + type: "text"; +}; +type ChatCompletionsResponseFormatJSONObject = { + type: "json_object"; +}; +type ResponseFormatJSONSchema = { + type: "json_schema"; + json_schema: { + name: string; + description?: string; + schema?: Record; + strict?: boolean | null; + }; +}; +type ResponseFormat = ChatCompletionsResponseFormatText | ChatCompletionsResponseFormatJSONObject | ResponseFormatJSONSchema; +type ChatCompletionsStreamOptions = { + include_usage?: boolean; + include_obfuscation?: boolean; +}; +type PredictionContent = { + type: "content"; + content: string | Array<{ + type: "text"; + text: string; + }>; +}; +type AudioParams = { + voice: string | { + id: string; + }; + format: "wav" | "aac" | "mp3" | "flac" | "opus" | "pcm16"; +}; +type WebSearchUserLocation = { + type: "approximate"; + approximate: { + city?: string; + country?: string; + region?: string; + timezone?: string; + }; +}; +type WebSearchOptions = { + search_context_size?: "low" | "medium" | "high"; + user_location?: WebSearchUserLocation; +}; +// Source of truth for per-model reasoning types: each model's `reasoning_effort` metadata +// in Workers AI ConfigAPI (supported efforts, aliases, defaults, and whether reasoning can +// be turned off). The Workers AI SDK type generator (cloudflare/ai/sdk, +// apps/worker-constellation-entry/scripts/build-types) turns it into the per-model +// `inputs` types below; the developer docs model schemas come from the same metadata. +type ChatTemplateKwargs = { + /** Whether to enable reasoning. Support and defaults depend on the model. */ + enable_thinking?: boolean; + /** If false, preserves reasoning context between turns. */ + clear_thinking?: boolean; +}; +/** Shared optional properties used by both Prompt and Messages input branches. */ +type ChatCompletionsCommonOptions = { + model?: string; + audio?: AudioParams; + frequency_penalty?: number | null; + logit_bias?: Record | null; + logprobs?: boolean | null; + top_logprobs?: number | null; + max_tokens?: number | null; + max_completion_tokens?: number | null; + metadata?: Record | null; + modalities?: Array<"text" | "audio"> | null; + n?: number | null; + parallel_tool_calls?: boolean; + prediction?: PredictionContent; + presence_penalty?: number | null; + /** Reasoning effort. Supported levels depend on the model. */ + reasoning_effort?: "low" | "medium" | "high" | null; + chat_template_kwargs?: ChatTemplateKwargs; + response_format?: ResponseFormat; + seed?: number | null; + service_tier?: "auto" | "default" | "flex" | "scale" | "priority" | null; + stop?: string | Array | null; + store?: boolean | null; + stream?: boolean | null; + stream_options?: ChatCompletionsStreamOptions; + temperature?: number | null; + tool_choice?: ChatCompletionToolChoiceOption; + tools?: Array; + top_p?: number | null; + user?: string; + web_search_options?: WebSearchOptions; + function_call?: "none" | "auto" | { + name: string; + }; + functions?: Array; +}; +type PromptTokensDetails = { + cached_tokens?: number; + audio_tokens?: number; +}; +type CompletionTokensDetails = { + reasoning_tokens?: number; + audio_tokens?: number; + accepted_prediction_tokens?: number; + rejected_prediction_tokens?: number; +}; +type CompletionUsage = { + prompt_tokens: number; + completion_tokens: number; + total_tokens: number; + prompt_tokens_details?: PromptTokensDetails; + completion_tokens_details?: CompletionTokensDetails; +}; +type ChatCompletionTopLogprob = { + token: string; + logprob: number; + bytes: Array | null; +}; +type ChatCompletionTokenLogprob = { + token: string; + logprob: number; + bytes: Array | null; + top_logprobs: Array; +}; +type ChatCompletionAudio = { + id: string; + /** Base64 encoded audio bytes. */ + data: string; + expires_at: number; + transcript: string; +}; +type ChatCompletionUrlCitation = { + type: "url_citation"; + url_citation: { + url: string; + title: string; + start_index: number; + end_index: number; + }; +}; +type ChatCompletionResponseMessage = { + role: "assistant"; + content: string | null; + refusal: string | null; + annotations?: Array; + audio?: ChatCompletionAudio; + tool_calls?: Array; + function_call?: { + name: string; + arguments: string; + } | null; +}; +type ChatCompletionLogprobs = { + content: Array | null; + refusal?: Array | null; +}; +type ChatCompletionChoice = { + index: number; + message: ChatCompletionResponseMessage; + finish_reason: "stop" | "length" | "tool_calls" | "content_filter" | "function_call"; + logprobs: ChatCompletionLogprobs | null; +}; +type ChatCompletionsMessagesInput = { + messages: Array; +} & ChatCompletionsCommonOptions; +type ChatCompletionsOutput = { + id: string; + object: string; + created: number; + model: string; + choices: Array; + usage?: CompletionUsage; + system_fingerprint?: string | null; + service_tier?: "auto" | "default" | "flex" | "scale" | "priority" | null; +}; +/** + * Workers AI support for OpenAI's Responses API + * Reference: https://github.com/openai/openai-node/blob/master/src/resources/responses/responses.ts + * + * It's a stripped down version from its source. + * It currently supports basic function calling, json mode and accepts images as input. + * + * It does not include types for WebSearch, CodeInterpreter, FileInputs, MCP, CustomTools. + * We plan to add those incrementally as model + platform capabilities evolve. + */ +type ResponsesInput = { + background?: boolean | null; + conversation?: string | ResponseConversationParam | null; + include?: Array | null; + input?: string | ResponseInput; + instructions?: string | null; + max_output_tokens?: number | null; + parallel_tool_calls?: boolean | null; + previous_response_id?: string | null; + prompt_cache_key?: string; + reasoning?: Reasoning | null; + safety_identifier?: string; + service_tier?: "auto" | "default" | "flex" | "scale" | "priority" | null; + stream?: boolean | null; + stream_options?: StreamOptions | null; + temperature?: number | null; + text?: ResponseTextConfig; + tool_choice?: ToolChoiceOptions | ToolChoiceFunction; + tools?: Array; + top_p?: number | null; + truncation?: "auto" | "disabled" | null; +}; +type ResponsesOutput = { + id?: string; + created_at?: number; + output_text?: string; + error?: ResponseError | null; + incomplete_details?: ResponseIncompleteDetails | null; + instructions?: string | Array | null; + object?: "response"; + output?: Array; + parallel_tool_calls?: boolean; + temperature?: number | null; + tool_choice?: ToolChoiceOptions | ToolChoiceFunction; + tools?: Array; + top_p?: number | null; + max_output_tokens?: number | null; + previous_response_id?: string | null; + prompt?: ResponsePrompt | null; + reasoning?: Reasoning | null; + safety_identifier?: string; + service_tier?: "auto" | "default" | "flex" | "scale" | "priority" | null; + status?: ResponseStatus; + text?: ResponseTextConfig; + truncation?: "auto" | "disabled" | null; + usage?: ResponseUsage; +}; +type EasyInputMessage = { + content: string | ResponseInputMessageContentList; + role: "user" | "assistant" | "system" | "developer"; + type?: "message"; +}; +type ResponsesFunctionTool = { + name: string; + parameters: { + [key: string]: unknown; + } | null; + strict: boolean | null; + type: "function"; + description?: string | null; +}; +type ResponseIncompleteDetails = { + reason?: "max_output_tokens" | "content_filter"; +}; +type ResponsePrompt = { + id: string; + variables?: { + [key: string]: string | ResponseInputText | ResponseInputImage; + } | null; + version?: string | null; +}; +type Reasoning = { + effort?: ReasoningEffort | null; + generate_summary?: "auto" | "concise" | "detailed" | null; + summary?: "auto" | "concise" | "detailed" | null; +}; +type ResponseContent = ResponseInputText | ResponseInputImage | ResponseOutputText | ResponseOutputRefusal | ResponseContentReasoningText; +type ResponseContentReasoningText = { + text: string; + type: "reasoning_text"; +}; +type ResponseConversationParam = { + id: string; +}; +type ResponseCreatedEvent = { + response: Response; + sequence_number: number; + type: "response.created"; +}; +type ResponseCustomToolCallOutput = { + call_id: string; + output: string | Array; + type: "custom_tool_call_output"; + id?: string; +}; +type ResponseError = { + code: "server_error" | "rate_limit_exceeded" | "invalid_prompt" | "vector_store_timeout" | "invalid_image" | "invalid_image_format" | "invalid_base64_image" | "invalid_image_url" | "image_too_large" | "image_too_small" | "image_parse_error" | "image_content_policy_violation" | "invalid_image_mode" | "image_file_too_large" | "unsupported_image_media_type" | "empty_image_file" | "failed_to_download_image" | "image_file_not_found"; + message: string; +}; +type ResponseErrorEvent = { + code: string | null; + message: string; + param: string | null; + sequence_number: number; + type: "error"; +}; +type ResponseFailedEvent = { + response: Response; + sequence_number: number; + type: "response.failed"; +}; +type ResponseFormatText = { + type: "text"; +}; +type ResponseFormatJSONObject = { + type: "json_object"; +}; +type ResponseFormatTextConfig = ResponseFormatText | ResponseFormatTextJSONSchemaConfig | ResponseFormatJSONObject; +type ResponseFormatTextJSONSchemaConfig = { + name: string; + schema: { + [key: string]: unknown; + }; + type: "json_schema"; + description?: string; + strict?: boolean | null; +}; +type ResponseFunctionCallArgumentsDeltaEvent = { + delta: string; + item_id: string; + output_index: number; + sequence_number: number; + type: "response.function_call_arguments.delta"; +}; +type ResponseFunctionCallArgumentsDoneEvent = { + arguments: string; + item_id: string; + name: string; + output_index: number; + sequence_number: number; + type: "response.function_call_arguments.done"; +}; +type ResponseFunctionCallOutputItem = ResponseInputTextContent | ResponseInputImageContent; +type ResponseFunctionCallOutputItemList = Array; +type ResponseFunctionToolCall = { + arguments: string; + call_id: string; + name: string; + type: "function_call"; + id?: string; + status?: "in_progress" | "completed" | "incomplete"; +}; +interface ResponseFunctionToolCallItem extends ResponseFunctionToolCall { + id: string; +} +type ResponseFunctionToolCallOutputItem = { + id: string; + call_id: string; + output: string | Array; + type: "function_call_output"; + status?: "in_progress" | "completed" | "incomplete"; +}; +type ResponseIncludable = "message.input_image.image_url" | "message.output_text.logprobs"; +type ResponseIncompleteEvent = { + response: Response; + sequence_number: number; + type: "response.incomplete"; +}; +type ResponseInput = Array; +type ResponseInputContent = ResponseInputText | ResponseInputImage; +type ResponseInputImage = { + detail: "low" | "high" | "auto"; + type: "input_image"; + /** + * Base64 encoded image + */ + image_url?: string | null; +}; +type ResponseInputImageContent = { + type: "input_image"; + detail?: "low" | "high" | "auto" | null; + /** + * Base64 encoded image + */ + image_url?: string | null; +}; +type ResponseInputItem = EasyInputMessage | ResponseInputItemMessage | ResponseOutputMessage | ResponseFunctionToolCall | ResponseInputItemFunctionCallOutput | ResponseReasoningItem; +type ResponseInputItemFunctionCallOutput = { + call_id: string; + output: string | ResponseFunctionCallOutputItemList; + type: "function_call_output"; + id?: string | null; + status?: "in_progress" | "completed" | "incomplete" | null; +}; +type ResponseInputItemMessage = { + content: ResponseInputMessageContentList; + role: "user" | "system" | "developer"; + status?: "in_progress" | "completed" | "incomplete"; + type?: "message"; +}; +type ResponseInputMessageContentList = Array; +type ResponseInputMessageItem = { + id: string; + content: ResponseInputMessageContentList; + role: "user" | "system" | "developer"; + status?: "in_progress" | "completed" | "incomplete"; + type?: "message"; +}; +type ResponseInputText = { + text: string; + type: "input_text"; +}; +type ResponseInputTextContent = { + text: string; + type: "input_text"; +}; +type ResponseItem = ResponseInputMessageItem | ResponseOutputMessage | ResponseFunctionToolCallItem | ResponseFunctionToolCallOutputItem; +type ResponseOutputItem = ResponseOutputMessage | ResponseFunctionToolCall | ResponseReasoningItem; +type ResponseOutputItemAddedEvent = { + item: ResponseOutputItem; + output_index: number; + sequence_number: number; + type: "response.output_item.added"; +}; +type ResponseOutputItemDoneEvent = { + item: ResponseOutputItem; + output_index: number; + sequence_number: number; + type: "response.output_item.done"; +}; +type ResponseOutputMessage = { + id: string; + content: Array; + role: "assistant"; + status: "in_progress" | "completed" | "incomplete"; + type: "message"; +}; +type ResponseOutputRefusal = { + refusal: string; + type: "refusal"; +}; +type ResponseOutputText = { + text: string; + type: "output_text"; + logprobs?: Array; +}; +type ResponseReasoningItem = { + id: string; + summary: Array; + type: "reasoning"; + content?: Array; + encrypted_content?: string | null; + status?: "in_progress" | "completed" | "incomplete"; +}; +type ResponseReasoningSummaryItem = { + text: string; + type: "summary_text"; +}; +type ResponseReasoningContentItem = { + text: string; + type: "reasoning_text"; +}; +type ResponseReasoningTextDeltaEvent = { + content_index: number; + delta: string; + item_id: string; + output_index: number; + sequence_number: number; + type: "response.reasoning_text.delta"; +}; +type ResponseReasoningTextDoneEvent = { + content_index: number; + item_id: string; + output_index: number; + sequence_number: number; + text: string; + type: "response.reasoning_text.done"; +}; +type ResponseRefusalDeltaEvent = { + content_index: number; + delta: string; + item_id: string; + output_index: number; + sequence_number: number; + type: "response.refusal.delta"; +}; +type ResponseRefusalDoneEvent = { + content_index: number; + item_id: string; + output_index: number; + refusal: string; + sequence_number: number; + type: "response.refusal.done"; +}; +type ResponseStatus = "completed" | "failed" | "in_progress" | "cancelled" | "queued" | "incomplete"; +type ResponseStreamEvent = ResponseCompletedEvent | ResponseCreatedEvent | ResponseErrorEvent | ResponseFunctionCallArgumentsDeltaEvent | ResponseFunctionCallArgumentsDoneEvent | ResponseFailedEvent | ResponseIncompleteEvent | ResponseOutputItemAddedEvent | ResponseOutputItemDoneEvent | ResponseReasoningTextDeltaEvent | ResponseReasoningTextDoneEvent | ResponseRefusalDeltaEvent | ResponseRefusalDoneEvent | ResponseTextDeltaEvent | ResponseTextDoneEvent; +type ResponseCompletedEvent = { + response: Response; + sequence_number: number; + type: "response.completed"; +}; +type ResponseTextConfig = { + format?: ResponseFormatTextConfig; + verbosity?: "low" | "medium" | "high" | null; +}; +type ResponseTextDeltaEvent = { + content_index: number; + delta: string; + item_id: string; + logprobs: Array; + output_index: number; + sequence_number: number; + type: "response.output_text.delta"; +}; +type ResponseTextDoneEvent = { + content_index: number; + item_id: string; + logprobs: Array; + output_index: number; + sequence_number: number; + text: string; + type: "response.output_text.done"; +}; +type Logprob = { + token: string; + logprob: number; + top_logprobs?: Array; +}; +type TopLogprob = { + token?: string; + logprob?: number; +}; +type ResponseUsage = { + input_tokens: number; + output_tokens: number; + total_tokens: number; +}; +type Tool = ResponsesFunctionTool; +type ToolChoiceFunction = { + name: string; + type: "function"; +}; +type ToolChoiceOptions = "none"; +type ReasoningEffort = "minimal" | "low" | "medium" | "high" | null; +type StreamOptions = { + include_obfuscation?: boolean; +}; +/** Marks keys from T that aren't in U as optional never */ +type Without = { + [P in Exclude]?: never; +}; +/** Either T or U, but not both (mutually exclusive) */ +type XOR = (T & Without) | (U & Without); +type Ai_Cf_Baai_Bge_Base_En_V1_5_Input = { + text: string | string[]; + /** + * The pooling method used in the embedding process. `cls` pooling will generate more accurate embeddings on larger inputs - however, embeddings created with cls pooling are not compatible with embeddings generated with mean pooling. The default pooling method is `mean` in order for this to not be a breaking change, but we highly suggest using the new `cls` pooling for better accuracy. + */ + pooling?: "mean" | "cls"; +} | { + /** + * Batch of the embeddings requests to run using async-queue + */ + requests: { + text: string | string[]; + /** + * The pooling method used in the embedding process. `cls` pooling will generate more accurate embeddings on larger inputs - however, embeddings created with cls pooling are not compatible with embeddings generated with mean pooling. The default pooling method is `mean` in order for this to not be a breaking change, but we highly suggest using the new `cls` pooling for better accuracy. + */ + pooling?: "mean" | "cls"; + }[]; +}; +type Ai_Cf_Baai_Bge_Base_En_V1_5_Output = { + shape?: number[]; + /** + * Embeddings of the requested text values + */ + data?: number[][]; + /** + * The pooling method used in the embedding process. + */ + pooling?: "mean" | "cls"; +} | Ai_Cf_Baai_Bge_Base_En_V1_5_AsyncResponse; +interface Ai_Cf_Baai_Bge_Base_En_V1_5_AsyncResponse { + /** + * The async request id that can be used to obtain the results. + */ + request_id?: string; +} +declare abstract class Base_Ai_Cf_Baai_Bge_Base_En_V1_5 { + inputs: Ai_Cf_Baai_Bge_Base_En_V1_5_Input; + postProcessedOutputs: Ai_Cf_Baai_Bge_Base_En_V1_5_Output; +} +type Ai_Cf_Openai_Whisper_Input = string | { + /** + * An array of integers that represent the audio data constrained to 8-bit unsigned integer values + */ + audio: number[]; +}; +interface Ai_Cf_Openai_Whisper_Output { + /** + * The transcription + */ + text: string; + word_count?: number; + words?: { + word?: string; + /** + * The second this word begins in the recording + */ + start?: number; + /** + * The ending second when the word completes + */ + end?: number; + }[]; + vtt?: string; +} +declare abstract class Base_Ai_Cf_Openai_Whisper { + inputs: Ai_Cf_Openai_Whisper_Input; + postProcessedOutputs: Ai_Cf_Openai_Whisper_Output; +} +type Ai_Cf_Meta_M2M100_1_2B_Input = { + /** + * The text to be translated + */ + text: string; + /** + * The language code of the source text (e.g., 'en' for English). Defaults to 'en' if not specified + */ + source_lang?: string; + /** + * The language code to translate the text into (e.g., 'es' for Spanish) + */ + target_lang: string; +} | { + /** + * Batch of the embeddings requests to run using async-queue + */ + requests: { + /** + * The text to be translated + */ + text: string; + /** + * The language code of the source text (e.g., 'en' for English). Defaults to 'en' if not specified + */ + source_lang?: string; + /** + * The language code to translate the text into (e.g., 'es' for Spanish) + */ + target_lang: string; + }[]; +}; +type Ai_Cf_Meta_M2M100_1_2B_Output = { + /** + * The translated text in the target language + */ + translated_text?: string; +} | Ai_Cf_Meta_M2M100_1_2B_AsyncResponse; +interface Ai_Cf_Meta_M2M100_1_2B_AsyncResponse { + /** + * The async request id that can be used to obtain the results. + */ + request_id?: string; +} +declare abstract class Base_Ai_Cf_Meta_M2M100_1_2B { + inputs: Ai_Cf_Meta_M2M100_1_2B_Input; + postProcessedOutputs: Ai_Cf_Meta_M2M100_1_2B_Output; +} +type Ai_Cf_Baai_Bge_Small_En_V1_5_Input = { + text: string | string[]; + /** + * The pooling method used in the embedding process. `cls` pooling will generate more accurate embeddings on larger inputs - however, embeddings created with cls pooling are not compatible with embeddings generated with mean pooling. The default pooling method is `mean` in order for this to not be a breaking change, but we highly suggest using the new `cls` pooling for better accuracy. + */ + pooling?: "mean" | "cls"; +} | { + /** + * Batch of the embeddings requests to run using async-queue + */ + requests: { + text: string | string[]; + /** + * The pooling method used in the embedding process. `cls` pooling will generate more accurate embeddings on larger inputs - however, embeddings created with cls pooling are not compatible with embeddings generated with mean pooling. The default pooling method is `mean` in order for this to not be a breaking change, but we highly suggest using the new `cls` pooling for better accuracy. + */ + pooling?: "mean" | "cls"; + }[]; +}; +type Ai_Cf_Baai_Bge_Small_En_V1_5_Output = { + shape?: number[]; + /** + * Embeddings of the requested text values + */ + data?: number[][]; + /** + * The pooling method used in the embedding process. + */ + pooling?: "mean" | "cls"; +} | Ai_Cf_Baai_Bge_Small_En_V1_5_AsyncResponse; +interface Ai_Cf_Baai_Bge_Small_En_V1_5_AsyncResponse { + /** + * The async request id that can be used to obtain the results. + */ + request_id?: string; +} +declare abstract class Base_Ai_Cf_Baai_Bge_Small_En_V1_5 { + inputs: Ai_Cf_Baai_Bge_Small_En_V1_5_Input; + postProcessedOutputs: Ai_Cf_Baai_Bge_Small_En_V1_5_Output; +} +type Ai_Cf_Baai_Bge_Large_En_V1_5_Input = { + text: string | string[]; + /** + * The pooling method used in the embedding process. `cls` pooling will generate more accurate embeddings on larger inputs - however, embeddings created with cls pooling are not compatible with embeddings generated with mean pooling. The default pooling method is `mean` in order for this to not be a breaking change, but we highly suggest using the new `cls` pooling for better accuracy. + */ + pooling?: "mean" | "cls"; +} | { + /** + * Batch of the embeddings requests to run using async-queue + */ + requests: { + text: string | string[]; + /** + * The pooling method used in the embedding process. `cls` pooling will generate more accurate embeddings on larger inputs - however, embeddings created with cls pooling are not compatible with embeddings generated with mean pooling. The default pooling method is `mean` in order for this to not be a breaking change, but we highly suggest using the new `cls` pooling for better accuracy. + */ + pooling?: "mean" | "cls"; + }[]; +}; +type Ai_Cf_Baai_Bge_Large_En_V1_5_Output = { + shape?: number[]; + /** + * Embeddings of the requested text values + */ + data?: number[][]; + /** + * The pooling method used in the embedding process. + */ + pooling?: "mean" | "cls"; +} | Ai_Cf_Baai_Bge_Large_En_V1_5_AsyncResponse; +interface Ai_Cf_Baai_Bge_Large_En_V1_5_AsyncResponse { + /** + * The async request id that can be used to obtain the results. + */ + request_id?: string; +} +declare abstract class Base_Ai_Cf_Baai_Bge_Large_En_V1_5 { + inputs: Ai_Cf_Baai_Bge_Large_En_V1_5_Input; + postProcessedOutputs: Ai_Cf_Baai_Bge_Large_En_V1_5_Output; +} +type Ai_Cf_Unum_Uform_Gen2_Qwen_500M_Input = string | { + /** + * The input text prompt for the model to generate a response. + */ + prompt?: string; + /** + * If true, a chat template is not applied and you must adhere to the specific model's expected formatting. + */ + raw?: boolean; + /** + * Controls the creativity of the AI's responses by adjusting how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. + */ + top_p?: number; + /** + * Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. + */ + top_k?: number; + /** + * Random seed for reproducibility of the generation. + */ + seed?: number; + /** + * Penalty for repeated tokens; higher values discourage repetition. + */ + repetition_penalty?: number; + /** + * Decreases the likelihood of the model repeating the same lines verbatim. + */ + frequency_penalty?: number; + /** + * Increases the likelihood of the model introducing new topics. + */ + presence_penalty?: number; + image: number[] | (string & NonNullable); + /** + * The maximum number of tokens to generate in the response. + */ + max_tokens?: number; +}; +interface Ai_Cf_Unum_Uform_Gen2_Qwen_500M_Output { + description?: string; +} +declare abstract class Base_Ai_Cf_Unum_Uform_Gen2_Qwen_500M { + inputs: Ai_Cf_Unum_Uform_Gen2_Qwen_500M_Input; + postProcessedOutputs: Ai_Cf_Unum_Uform_Gen2_Qwen_500M_Output; +} +type Ai_Cf_Openai_Whisper_Tiny_En_Input = string | { + /** + * An array of integers that represent the audio data constrained to 8-bit unsigned integer values + */ + audio: number[]; +}; +interface Ai_Cf_Openai_Whisper_Tiny_En_Output { + /** + * The transcription + */ + text: string; + word_count?: number; + words?: { + word?: string; + /** + * The second this word begins in the recording + */ + start?: number; + /** + * The ending second when the word completes + */ + end?: number; + }[]; + vtt?: string; +} +declare abstract class Base_Ai_Cf_Openai_Whisper_Tiny_En { + inputs: Ai_Cf_Openai_Whisper_Tiny_En_Input; + postProcessedOutputs: Ai_Cf_Openai_Whisper_Tiny_En_Output; +} +interface Ai_Cf_Openai_Whisper_Large_V3_Turbo_Input { + audio: string | { + body?: object; + contentType?: string; + }; + /** + * Supported tasks are 'translate' or 'transcribe'. + */ + task?: string; + /** + * The language of the audio being transcribed or translated. + */ + language?: string; + /** + * Preprocess the audio with a voice activity detection model. + */ + vad_filter?: boolean; + /** + * A text prompt to help provide context to the model on the contents of the audio. + */ + initial_prompt?: string; + /** + * The prefix appended to the beginning of the output of the transcription and can guide the transcription result. + */ + prefix?: string; + /** + * The number of beams to use in beam search decoding. Higher values may improve accuracy at the cost of speed. + */ + beam_size?: number; + /** + * Whether to condition on previous text during transcription. Setting to false may help prevent hallucination loops. + */ + condition_on_previous_text?: boolean; + /** + * Threshold for detecting no-speech segments. Segments with no-speech probability above this value are skipped. + */ + no_speech_threshold?: number; + /** + * Threshold for filtering out segments with high compression ratio, which often indicate repetitive or hallucinated text. + */ + compression_ratio_threshold?: number; + /** + * Threshold for filtering out segments with low average log probability, indicating low confidence. + */ + log_prob_threshold?: number; + /** + * Optional threshold (in seconds) to skip silent periods that may cause hallucinations. + */ + hallucination_silence_threshold?: number; +} +interface Ai_Cf_Openai_Whisper_Large_V3_Turbo_Output { + transcription_info?: { + /** + * The language of the audio being transcribed or translated. + */ + language?: string; + /** + * The confidence level or probability of the detected language being accurate, represented as a decimal between 0 and 1. + */ + language_probability?: number; + /** + * The total duration of the original audio file, in seconds. + */ + duration?: number; + /** + * The duration of the audio after applying Voice Activity Detection (VAD) to remove silent or irrelevant sections, in seconds. + */ + duration_after_vad?: number; + }; + /** + * The complete transcription of the audio. + */ + text: string; + /** + * The total number of words in the transcription. + */ + word_count?: number; + segments?: { + /** + * The starting time of the segment within the audio, in seconds. + */ + start?: number; + /** + * The ending time of the segment within the audio, in seconds. + */ + end?: number; + /** + * The transcription of the segment. + */ + text?: string; + /** + * The temperature used in the decoding process, controlling randomness in predictions. Lower values result in more deterministic outputs. + */ + temperature?: number; + /** + * The average log probability of the predictions for the words in this segment, indicating overall confidence. + */ + avg_logprob?: number; + /** + * The compression ratio of the input to the output, measuring how much the text was compressed during the transcription process. + */ + compression_ratio?: number; + /** + * The probability that the segment contains no speech, represented as a decimal between 0 and 1. + */ + no_speech_prob?: number; + words?: { + /** + * The individual word transcribed from the audio. + */ + word?: string; + /** + * The starting time of the word within the audio, in seconds. + */ + start?: number; + /** + * The ending time of the word within the audio, in seconds. + */ + end?: number; + }[]; + }[]; + /** + * The transcription in WebVTT format, which includes timing and text information for use in subtitles. + */ + vtt?: string; +} +declare abstract class Base_Ai_Cf_Openai_Whisper_Large_V3_Turbo { + inputs: Ai_Cf_Openai_Whisper_Large_V3_Turbo_Input; + postProcessedOutputs: Ai_Cf_Openai_Whisper_Large_V3_Turbo_Output; +} +type Ai_Cf_Baai_Bge_M3_Input = Ai_Cf_Baai_Bge_M3_Input_QueryAnd_Contexts | Ai_Cf_Baai_Bge_M3_Input_Embedding | { + /** + * Batch of the embeddings requests to run using async-queue + */ + requests: (Ai_Cf_Baai_Bge_M3_Input_QueryAnd_Contexts_1 | Ai_Cf_Baai_Bge_M3_Input_Embedding_1)[]; +}; +interface Ai_Cf_Baai_Bge_M3_Input_QueryAnd_Contexts { + /** + * A query you wish to perform against the provided contexts. If no query is provided the model with respond with embeddings for contexts + */ + query?: string; + /** + * List of provided contexts. Note that the index in this array is important, as the response will refer to it. + */ + contexts: { + /** + * One of the provided context content + */ + text?: string; + }[]; + /** + * When provided with too long context should the model error out or truncate the context to fit? + */ + truncate_inputs?: boolean; +} +interface Ai_Cf_Baai_Bge_M3_Input_Embedding { + text: string | string[]; + /** + * When provided with too long context should the model error out or truncate the context to fit? + */ + truncate_inputs?: boolean; +} +interface Ai_Cf_Baai_Bge_M3_Input_QueryAnd_Contexts_1 { + /** + * A query you wish to perform against the provided contexts. If no query is provided the model with respond with embeddings for contexts + */ + query?: string; + /** + * List of provided contexts. Note that the index in this array is important, as the response will refer to it. + */ + contexts: { + /** + * One of the provided context content + */ + text?: string; + }[]; + /** + * When provided with too long context should the model error out or truncate the context to fit? + */ + truncate_inputs?: boolean; +} +interface Ai_Cf_Baai_Bge_M3_Input_Embedding_1 { + text: string | string[]; + /** + * When provided with too long context should the model error out or truncate the context to fit? + */ + truncate_inputs?: boolean; +} +type Ai_Cf_Baai_Bge_M3_Output = Ai_Cf_Baai_Bge_M3_Output_Query | Ai_Cf_Baai_Bge_M3_Output_EmbeddingFor_Contexts | Ai_Cf_Baai_Bge_M3_Output_Embedding | Ai_Cf_Baai_Bge_M3_AsyncResponse; +interface Ai_Cf_Baai_Bge_M3_Output_Query { + response?: { + /** + * Index of the context in the request + */ + id?: number; + /** + * Score of the context under the index. + */ + score?: number; + }[]; +} +interface Ai_Cf_Baai_Bge_M3_Output_EmbeddingFor_Contexts { + response?: number[][]; + shape?: number[]; + /** + * The pooling method used in the embedding process. + */ + pooling?: "mean" | "cls"; +} +interface Ai_Cf_Baai_Bge_M3_Output_Embedding { + shape?: number[]; + /** + * Embeddings of the requested text values + */ + data?: number[][]; + /** + * The pooling method used in the embedding process. + */ + pooling?: "mean" | "cls"; +} +interface Ai_Cf_Baai_Bge_M3_AsyncResponse { + /** + * The async request id that can be used to obtain the results. + */ + request_id?: string; +} +declare abstract class Base_Ai_Cf_Baai_Bge_M3 { + inputs: Ai_Cf_Baai_Bge_M3_Input; + postProcessedOutputs: Ai_Cf_Baai_Bge_M3_Output; +} +interface Ai_Cf_Black_Forest_Labs_Flux_1_Schnell_Input { + /** + * A text description of the image you want to generate. + */ + prompt: string; + /** + * The number of diffusion steps; higher values can improve quality but take longer. + */ + steps?: number; +} +interface Ai_Cf_Black_Forest_Labs_Flux_1_Schnell_Output { + /** + * The generated image in Base64 format. + */ + image?: string; +} +declare abstract class Base_Ai_Cf_Black_Forest_Labs_Flux_1_Schnell { + inputs: Ai_Cf_Black_Forest_Labs_Flux_1_Schnell_Input; + postProcessedOutputs: Ai_Cf_Black_Forest_Labs_Flux_1_Schnell_Output; +} +type Ai_Cf_Meta_Llama_3_2_11B_Vision_Instruct_Input = Ai_Cf_Meta_Llama_3_2_11B_Vision_Instruct_Prompt | Ai_Cf_Meta_Llama_3_2_11B_Vision_Instruct_Messages; +interface Ai_Cf_Meta_Llama_3_2_11B_Vision_Instruct_Prompt { + /** + * The input text prompt for the model to generate a response. + */ + prompt: string; + image?: number[] | (string & NonNullable); + /** + * If true, a chat template is not applied and you must adhere to the specific model's expected formatting. + */ + raw?: boolean; + /** + * If true, the response will be streamed back incrementally using SSE, Server Sent Events. + */ + stream?: boolean; + /** + * The maximum number of tokens to generate in the response. + */ + max_tokens?: number; + /** + * Controls the randomness of the output; higher values produce more random results. + */ + temperature?: number; + /** + * Adjusts the creativity of the AI's responses by controlling how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. + */ + top_p?: number; + /** + * Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. + */ + top_k?: number; + /** + * Random seed for reproducibility of the generation. + */ + seed?: number; + /** + * Penalty for repeated tokens; higher values discourage repetition. + */ + repetition_penalty?: number; + /** + * Decreases the likelihood of the model repeating the same lines verbatim. + */ + frequency_penalty?: number; + /** + * Increases the likelihood of the model introducing new topics. + */ + presence_penalty?: number; + /** + * Name of the LoRA (Low-Rank Adaptation) model to fine-tune the base model. + */ + lora?: string; +} +interface Ai_Cf_Meta_Llama_3_2_11B_Vision_Instruct_Messages { + /** + * An array of message objects representing the conversation history. + */ + messages: { + /** + * The role of the message sender (e.g., 'user', 'assistant', 'system', 'tool'). + */ + role?: string; + /** + * The tool call id. If you don't know what to put here you can fall back to 000000001 + */ + tool_call_id?: string; + content?: string | { + /** + * Type of the content provided + */ + type?: string; + text?: string; + image_url?: { + /** + * image uri with data (e.g. data:image/jpeg;base64,/9j/...). HTTP URL will not be accepted + */ + url?: string; + }; + }[] | { + /** + * Type of the content provided + */ + type?: string; + text?: string; + image_url?: { + /** + * image uri with data (e.g. data:image/jpeg;base64,/9j/...). HTTP URL will not be accepted + */ + url?: string; + }; + }; + }[]; + image?: number[] | (string & NonNullable); + functions?: { + name: string; + code: string; + }[]; + /** + * A list of tools available for the assistant to use. + */ + tools?: ({ + /** + * The name of the tool. More descriptive the better. + */ + name: string; + /** + * A brief description of what the tool does. + */ + description: string; + /** + * Schema defining the parameters accepted by the tool. + */ + parameters: { + /** + * The type of the parameters object (usually 'object'). + */ + type: string; + /** + * List of required parameter names. + */ + required?: string[]; + /** + * Definitions of each parameter. + */ + properties: { + [k: string]: { + /** + * The data type of the parameter. + */ + type: string; + /** + * A description of the expected parameter. + */ + description: string; + }; + }; + }; + } | { + /** + * Specifies the type of tool (e.g., 'function'). + */ + type: string; + /** + * Details of the function tool. + */ + function: { + /** + * The name of the function. + */ + name: string; + /** + * A brief description of what the function does. + */ + description: string; + /** + * Schema defining the parameters accepted by the function. + */ + parameters: { + /** + * The type of the parameters object (usually 'object'). + */ + type: string; + /** + * List of required parameter names. + */ + required?: string[]; + /** + * Definitions of each parameter. + */ + properties: { + [k: string]: { + /** + * The data type of the parameter. + */ + type: string; + /** + * A description of the expected parameter. + */ + description: string; + }; + }; + }; + }; + })[]; + /** + * If true, the response will be streamed back incrementally. + */ + stream?: boolean; + /** + * The maximum number of tokens to generate in the response. + */ + max_tokens?: number; + /** + * Controls the randomness of the output; higher values produce more random results. + */ + temperature?: number; + /** + * Controls the creativity of the AI's responses by adjusting how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. + */ + top_p?: number; + /** + * Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. + */ + top_k?: number; + /** + * Random seed for reproducibility of the generation. + */ + seed?: number; + /** + * Penalty for repeated tokens; higher values discourage repetition. + */ + repetition_penalty?: number; + /** + * Decreases the likelihood of the model repeating the same lines verbatim. + */ + frequency_penalty?: number; + /** + * Increases the likelihood of the model introducing new topics. + */ + presence_penalty?: number; +} +type Ai_Cf_Meta_Llama_3_2_11B_Vision_Instruct_Output = { + /** + * The generated text response from the model + */ + response?: string; + /** + * An array of tool calls requests made during the response generation + */ + tool_calls?: { + /** + * The arguments passed to be passed to the tool call request + */ + arguments?: object; + /** + * The name of the tool to be called + */ + name?: string; + }[]; +}; +declare abstract class Base_Ai_Cf_Meta_Llama_3_2_11B_Vision_Instruct { + inputs: Ai_Cf_Meta_Llama_3_2_11B_Vision_Instruct_Input; + postProcessedOutputs: Ai_Cf_Meta_Llama_3_2_11B_Vision_Instruct_Output; +} +type Ai_Cf_Meta_Llama_3_3_70B_Instruct_Fp8_Fast_Input = Ai_Cf_Meta_Llama_3_3_70B_Instruct_Fp8_Fast_Prompt | Ai_Cf_Meta_Llama_3_3_70B_Instruct_Fp8_Fast_Messages | Ai_Cf_Meta_Llama_3_3_70B_Instruct_Fp8_Fast_Async_Batch; +interface Ai_Cf_Meta_Llama_3_3_70B_Instruct_Fp8_Fast_Prompt { + /** + * The input text prompt for the model to generate a response. + */ + prompt: string; + /** + * Name of the LoRA (Low-Rank Adaptation) model to fine-tune the base model. + */ + lora?: string; + response_format?: Ai_Cf_Meta_Llama_3_3_70B_Instruct_Fp8_Fast_JSON_Mode; + /** + * If true, a chat template is not applied and you must adhere to the specific model's expected formatting. + */ + raw?: boolean; + /** + * If true, the response will be streamed back incrementally using SSE, Server Sent Events. + */ + stream?: boolean; + /** + * The maximum number of tokens to generate in the response. + */ + max_tokens?: number; + /** + * Controls the randomness of the output; higher values produce more random results. + */ + temperature?: number; + /** + * Adjusts the creativity of the AI's responses by controlling how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. + */ + top_p?: number; + /** + * Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. + */ + top_k?: number; + /** + * Random seed for reproducibility of the generation. + */ + seed?: number; + /** + * Penalty for repeated tokens; higher values discourage repetition. + */ + repetition_penalty?: number; + /** + * Decreases the likelihood of the model repeating the same lines verbatim. + */ + frequency_penalty?: number; + /** + * Increases the likelihood of the model introducing new topics. + */ + presence_penalty?: number; +} +interface Ai_Cf_Meta_Llama_3_3_70B_Instruct_Fp8_Fast_JSON_Mode { + type?: "json_object" | "json_schema"; + json_schema?: unknown; +} +interface Ai_Cf_Meta_Llama_3_3_70B_Instruct_Fp8_Fast_Messages { + /** + * An array of message objects representing the conversation history. + */ + messages: { + /** + * The role of the message sender (e.g., 'user', 'assistant', 'system', 'tool'). + */ + role: string; + content: string | { + /** + * Type of the content (text) + */ + type?: string; + /** + * Text content + */ + text?: string; + }[]; + }[]; + functions?: { + name: string; + code: string; + }[]; + /** + * A list of tools available for the assistant to use. + */ + tools?: ({ + /** + * The name of the tool. More descriptive the better. + */ + name: string; + /** + * A brief description of what the tool does. + */ + description: string; + /** + * Schema defining the parameters accepted by the tool. + */ + parameters: { + /** + * The type of the parameters object (usually 'object'). + */ + type: string; + /** + * List of required parameter names. + */ + required?: string[]; + /** + * Definitions of each parameter. + */ + properties: { + [k: string]: { + /** + * The data type of the parameter. + */ + type: string; + /** + * A description of the expected parameter. + */ + description: string; + }; + }; + }; + } | { + /** + * Specifies the type of tool (e.g., 'function'). + */ + type: string; + /** + * Details of the function tool. + */ + function: { + /** + * The name of the function. + */ + name: string; + /** + * A brief description of what the function does. + */ + description: string; + /** + * Schema defining the parameters accepted by the function. + */ + parameters: { + /** + * The type of the parameters object (usually 'object'). + */ + type: string; + /** + * List of required parameter names. + */ + required?: string[]; + /** + * Definitions of each parameter. + */ + properties: { + [k: string]: { + /** + * The data type of the parameter. + */ + type: string; + /** + * A description of the expected parameter. + */ + description: string; + }; + }; + }; + }; + })[]; + response_format?: Ai_Cf_Meta_Llama_3_3_70B_Instruct_Fp8_Fast_JSON_Mode_1; + /** + * If true, a chat template is not applied and you must adhere to the specific model's expected formatting. + */ + raw?: boolean; + /** + * If true, the response will be streamed back incrementally using SSE, Server Sent Events. + */ + stream?: boolean; + /** + * The maximum number of tokens to generate in the response. + */ + max_tokens?: number; + /** + * Controls the randomness of the output; higher values produce more random results. + */ + temperature?: number; + /** + * Adjusts the creativity of the AI's responses by controlling how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. + */ + top_p?: number; + /** + * Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. + */ + top_k?: number; + /** + * Random seed for reproducibility of the generation. + */ + seed?: number; + /** + * Penalty for repeated tokens; higher values discourage repetition. + */ + repetition_penalty?: number; + /** + * Decreases the likelihood of the model repeating the same lines verbatim. + */ + frequency_penalty?: number; + /** + * Increases the likelihood of the model introducing new topics. + */ + presence_penalty?: number; +} +interface Ai_Cf_Meta_Llama_3_3_70B_Instruct_Fp8_Fast_JSON_Mode_1 { + type?: "json_object" | "json_schema"; + json_schema?: unknown; +} +interface Ai_Cf_Meta_Llama_3_3_70B_Instruct_Fp8_Fast_Async_Batch { + requests?: { + /** + * User-supplied reference. This field will be present in the response as well it can be used to reference the request and response. It's NOT validated to be unique. + */ + external_reference?: string; + /** + * Prompt for the text generation model + */ + prompt?: string; + /** + * If true, the response will be streamed back incrementally using SSE, Server Sent Events. + */ + stream?: boolean; + /** + * The maximum number of tokens to generate in the response. + */ + max_tokens?: number; + /** + * Controls the randomness of the output; higher values produce more random results. + */ + temperature?: number; + /** + * Adjusts the creativity of the AI's responses by controlling how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. + */ + top_p?: number; + /** + * Random seed for reproducibility of the generation. + */ + seed?: number; + /** + * Penalty for repeated tokens; higher values discourage repetition. + */ + repetition_penalty?: number; + /** + * Decreases the likelihood of the model repeating the same lines verbatim. + */ + frequency_penalty?: number; + /** + * Increases the likelihood of the model introducing new topics. + */ + presence_penalty?: number; + response_format?: Ai_Cf_Meta_Llama_3_3_70B_Instruct_Fp8_Fast_JSON_Mode_2; + }[]; +} +interface Ai_Cf_Meta_Llama_3_3_70B_Instruct_Fp8_Fast_JSON_Mode_2 { + type?: "json_object" | "json_schema"; + json_schema?: unknown; +} +type Ai_Cf_Meta_Llama_3_3_70B_Instruct_Fp8_Fast_Output = { + /** + * The generated text response from the model + */ + response: string; + /** + * Usage statistics for the inference request + */ + usage?: { + /** + * Total number of tokens in input + */ + prompt_tokens?: number; + /** + * Total number of tokens in output + */ + completion_tokens?: number; + /** + * Total number of input and output tokens + */ + total_tokens?: number; + }; + /** + * An array of tool calls requests made during the response generation + */ + tool_calls?: { + /** + * The arguments passed to be passed to the tool call request + */ + arguments?: object; + /** + * The name of the tool to be called + */ + name?: string; + }[]; +} | string | Ai_Cf_Meta_Llama_3_3_70B_Instruct_Fp8_Fast_AsyncResponse; +interface Ai_Cf_Meta_Llama_3_3_70B_Instruct_Fp8_Fast_AsyncResponse { + /** + * The async request id that can be used to obtain the results. + */ + request_id?: string; +} +declare abstract class Base_Ai_Cf_Meta_Llama_3_3_70B_Instruct_Fp8_Fast { + inputs: Ai_Cf_Meta_Llama_3_3_70B_Instruct_Fp8_Fast_Input; + postProcessedOutputs: Ai_Cf_Meta_Llama_3_3_70B_Instruct_Fp8_Fast_Output; +} +interface Ai_Cf_Meta_Llama_Guard_3_8B_Input { + /** + * An array of message objects representing the conversation history. + */ + messages: { + /** + * The role of the message sender must alternate between 'user' and 'assistant'. + */ + role: "user" | "assistant"; + /** + * The content of the message as a string. + */ + content: string; + }[]; + /** + * The maximum number of tokens to generate in the response. + */ + max_tokens?: number; + /** + * Controls the randomness of the output; higher values produce more random results. + */ + temperature?: number; + /** + * Dictate the output format of the generated response. + */ + response_format?: { + /** + * Set to json_object to process and output generated text as JSON. + */ + type?: string; + }; +} +interface Ai_Cf_Meta_Llama_Guard_3_8B_Output { + response?: string | { + /** + * Whether the conversation is safe or not. + */ + safe?: boolean; + /** + * A list of what hazard categories predicted for the conversation, if the conversation is deemed unsafe. + */ + categories?: string[]; + }; + /** + * Usage statistics for the inference request + */ + usage?: { + /** + * Total number of tokens in input + */ + prompt_tokens?: number; + /** + * Total number of tokens in output + */ + completion_tokens?: number; + /** + * Total number of input and output tokens + */ + total_tokens?: number; + }; +} +declare abstract class Base_Ai_Cf_Meta_Llama_Guard_3_8B { + inputs: Ai_Cf_Meta_Llama_Guard_3_8B_Input; + postProcessedOutputs: Ai_Cf_Meta_Llama_Guard_3_8B_Output; +} +interface Ai_Cf_Baai_Bge_Reranker_Base_Input { + /** + * A query you wish to perform against the provided contexts. + */ + /** + * Number of returned results starting with the best score. + */ + top_k?: number; + /** + * List of provided contexts. Note that the index in this array is important, as the response will refer to it. + */ + contexts: { + /** + * One of the provided context content + */ + text?: string; + }[]; +} +interface Ai_Cf_Baai_Bge_Reranker_Base_Output { + response?: { + /** + * Index of the context in the request + */ + id?: number; + /** + * Score of the context under the index. + */ + score?: number; + }[]; +} +declare abstract class Base_Ai_Cf_Baai_Bge_Reranker_Base { + inputs: Ai_Cf_Baai_Bge_Reranker_Base_Input; + postProcessedOutputs: Ai_Cf_Baai_Bge_Reranker_Base_Output; +} +type Ai_Cf_Qwen_Qwen2_5_Coder_32B_Instruct_Input = Ai_Cf_Qwen_Qwen2_5_Coder_32B_Instruct_Prompt | Ai_Cf_Qwen_Qwen2_5_Coder_32B_Instruct_Messages; +interface Ai_Cf_Qwen_Qwen2_5_Coder_32B_Instruct_Prompt { + /** + * The input text prompt for the model to generate a response. + */ + prompt: string; + /** + * Name of the LoRA (Low-Rank Adaptation) model to fine-tune the base model. + */ + lora?: string; + response_format?: Ai_Cf_Qwen_Qwen2_5_Coder_32B_Instruct_JSON_Mode; + /** + * If true, a chat template is not applied and you must adhere to the specific model's expected formatting. + */ + raw?: boolean; + /** + * If true, the response will be streamed back incrementally using SSE, Server Sent Events. + */ + stream?: boolean; + /** + * The maximum number of tokens to generate in the response. + */ + max_tokens?: number; + /** + * Controls the randomness of the output; higher values produce more random results. + */ + temperature?: number; + /** + * Adjusts the creativity of the AI's responses by controlling how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. + */ + top_p?: number; + /** + * Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. + */ + top_k?: number; + /** + * Random seed for reproducibility of the generation. + */ + seed?: number; + /** + * Penalty for repeated tokens; higher values discourage repetition. + */ + repetition_penalty?: number; + /** + * Decreases the likelihood of the model repeating the same lines verbatim. + */ + frequency_penalty?: number; + /** + * Increases the likelihood of the model introducing new topics. + */ + presence_penalty?: number; +} +interface Ai_Cf_Qwen_Qwen2_5_Coder_32B_Instruct_JSON_Mode { + type?: "json_object" | "json_schema"; + json_schema?: unknown; +} +interface Ai_Cf_Qwen_Qwen2_5_Coder_32B_Instruct_Messages { + /** + * An array of message objects representing the conversation history. + */ + messages: { + /** + * The role of the message sender (e.g., 'user', 'assistant', 'system', 'tool'). + */ + role: string; + /** + * The content of the message as a string. + */ + content: string; + }[]; + functions?: { + name: string; + code: string; + }[]; + /** + * A list of tools available for the assistant to use. + */ + tools?: ({ + /** + * The name of the tool. More descriptive the better. + */ + name: string; + /** + * A brief description of what the tool does. + */ + description: string; + /** + * Schema defining the parameters accepted by the tool. + */ + parameters: { + /** + * The type of the parameters object (usually 'object'). + */ + type: string; + /** + * List of required parameter names. + */ + required?: string[]; + /** + * Definitions of each parameter. + */ + properties: { + [k: string]: { + /** + * The data type of the parameter. + */ + type: string; + /** + * A description of the expected parameter. + */ + description: string; + }; + }; + }; + } | { + /** + * Specifies the type of tool (e.g., 'function'). + */ + type: string; + /** + * Details of the function tool. + */ + function: { + /** + * The name of the function. + */ + name: string; + /** + * A brief description of what the function does. + */ + description: string; + /** + * Schema defining the parameters accepted by the function. + */ + parameters: { + /** + * The type of the parameters object (usually 'object'). + */ + type: string; + /** + * List of required parameter names. + */ + required?: string[]; + /** + * Definitions of each parameter. + */ + properties: { + [k: string]: { + /** + * The data type of the parameter. + */ + type: string; + /** + * A description of the expected parameter. + */ + description: string; + }; + }; + }; + }; + })[]; + response_format?: Ai_Cf_Qwen_Qwen2_5_Coder_32B_Instruct_JSON_Mode_1; + /** + * If true, a chat template is not applied and you must adhere to the specific model's expected formatting. + */ + raw?: boolean; + /** + * If true, the response will be streamed back incrementally using SSE, Server Sent Events. + */ + stream?: boolean; + /** + * The maximum number of tokens to generate in the response. + */ + max_tokens?: number; + /** + * Controls the randomness of the output; higher values produce more random results. + */ + temperature?: number; + /** + * Adjusts the creativity of the AI's responses by controlling how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. + */ + top_p?: number; + /** + * Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. + */ + top_k?: number; + /** + * Random seed for reproducibility of the generation. + */ + seed?: number; + /** + * Penalty for repeated tokens; higher values discourage repetition. + */ + repetition_penalty?: number; + /** + * Decreases the likelihood of the model repeating the same lines verbatim. + */ + frequency_penalty?: number; + /** + * Increases the likelihood of the model introducing new topics. + */ + presence_penalty?: number; +} +interface Ai_Cf_Qwen_Qwen2_5_Coder_32B_Instruct_JSON_Mode_1 { + type?: "json_object" | "json_schema"; + json_schema?: unknown; +} +type Ai_Cf_Qwen_Qwen2_5_Coder_32B_Instruct_Output = { + /** + * The generated text response from the model + */ + response: string; + /** + * Usage statistics for the inference request + */ + usage?: { + /** + * Total number of tokens in input + */ + prompt_tokens?: number; + /** + * Total number of tokens in output + */ + completion_tokens?: number; + /** + * Total number of input and output tokens + */ + total_tokens?: number; + }; + /** + * An array of tool calls requests made during the response generation + */ + tool_calls?: { + /** + * The arguments passed to be passed to the tool call request + */ + arguments?: object; + /** + * The name of the tool to be called + */ + name?: string; + }[]; +}; +declare abstract class Base_Ai_Cf_Qwen_Qwen2_5_Coder_32B_Instruct { + inputs: Ai_Cf_Qwen_Qwen2_5_Coder_32B_Instruct_Input; + postProcessedOutputs: Ai_Cf_Qwen_Qwen2_5_Coder_32B_Instruct_Output; +} +type Ai_Cf_Qwen_Qwq_32B_Input = Ai_Cf_Qwen_Qwq_32B_Prompt | Ai_Cf_Qwen_Qwq_32B_Messages; +interface Ai_Cf_Qwen_Qwq_32B_Prompt { + /** + * The input text prompt for the model to generate a response. + */ + prompt: string; + /** + * JSON schema that should be fulfilled for the response. + */ + guided_json?: object; + /** + * If true, a chat template is not applied and you must adhere to the specific model's expected formatting. + */ + raw?: boolean; + /** + * If true, the response will be streamed back incrementally using SSE, Server Sent Events. + */ + stream?: boolean; + /** + * The maximum number of tokens to generate in the response. + */ + max_tokens?: number; + /** + * Controls the randomness of the output; higher values produce more random results. + */ + temperature?: number; + /** + * Adjusts the creativity of the AI's responses by controlling how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. + */ + top_p?: number; + /** + * Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. + */ + top_k?: number; + /** + * Random seed for reproducibility of the generation. + */ + seed?: number; + /** + * Penalty for repeated tokens; higher values discourage repetition. + */ + repetition_penalty?: number; + /** + * Decreases the likelihood of the model repeating the same lines verbatim. + */ + frequency_penalty?: number; + /** + * Increases the likelihood of the model introducing new topics. + */ + presence_penalty?: number; +} +interface Ai_Cf_Qwen_Qwq_32B_Messages { + /** + * An array of message objects representing the conversation history. + */ + messages: { + /** + * The role of the message sender (e.g., 'user', 'assistant', 'system', 'tool'). + */ + role?: string; + /** + * The tool call id. If you don't know what to put here you can fall back to 000000001 + */ + tool_call_id?: string; + content?: string | { + /** + * Type of the content provided + */ + type?: string; + text?: string; + image_url?: { + /** + * image uri with data (e.g. data:image/jpeg;base64,/9j/...). HTTP URL will not be accepted + */ + url?: string; + }; + }[] | { + /** + * Type of the content provided + */ + type?: string; + text?: string; + image_url?: { + /** + * image uri with data (e.g. data:image/jpeg;base64,/9j/...). HTTP URL will not be accepted + */ + url?: string; + }; + }; + }[]; + functions?: { + name: string; + code: string; + }[]; + /** + * A list of tools available for the assistant to use. + */ + tools?: ({ + /** + * The name of the tool. More descriptive the better. + */ + name: string; + /** + * A brief description of what the tool does. + */ + description: string; + /** + * Schema defining the parameters accepted by the tool. + */ + parameters: { + /** + * The type of the parameters object (usually 'object'). + */ + type: string; + /** + * List of required parameter names. + */ + required?: string[]; + /** + * Definitions of each parameter. + */ + properties: { + [k: string]: { + /** + * The data type of the parameter. + */ + type: string; + /** + * A description of the expected parameter. + */ + description: string; + }; + }; + }; + } | { + /** + * Specifies the type of tool (e.g., 'function'). + */ + type: string; + /** + * Details of the function tool. + */ + function: { + /** + * The name of the function. + */ + name: string; + /** + * A brief description of what the function does. + */ + description: string; + /** + * Schema defining the parameters accepted by the function. + */ + parameters: { + /** + * The type of the parameters object (usually 'object'). + */ + type: string; + /** + * List of required parameter names. + */ + required?: string[]; + /** + * Definitions of each parameter. + */ + properties: { + [k: string]: { + /** + * The data type of the parameter. + */ + type: string; + /** + * A description of the expected parameter. + */ + description: string; + }; + }; + }; + }; + })[]; + /** + * JSON schema that should be fufilled for the response. + */ + guided_json?: object; + /** + * If true, a chat template is not applied and you must adhere to the specific model's expected formatting. + */ + raw?: boolean; + /** + * If true, the response will be streamed back incrementally using SSE, Server Sent Events. + */ + stream?: boolean; + /** + * The maximum number of tokens to generate in the response. + */ + max_tokens?: number; + /** + * Controls the randomness of the output; higher values produce more random results. + */ + temperature?: number; + /** + * Adjusts the creativity of the AI's responses by controlling how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. + */ + top_p?: number; + /** + * Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. + */ + top_k?: number; + /** + * Random seed for reproducibility of the generation. + */ + seed?: number; + /** + * Penalty for repeated tokens; higher values discourage repetition. + */ + repetition_penalty?: number; + /** + * Decreases the likelihood of the model repeating the same lines verbatim. + */ + frequency_penalty?: number; + /** + * Increases the likelihood of the model introducing new topics. + */ + presence_penalty?: number; +} +type Ai_Cf_Qwen_Qwq_32B_Output = { + /** + * The generated text response from the model + */ + response: string; + /** + * Usage statistics for the inference request + */ + usage?: { + /** + * Total number of tokens in input + */ + prompt_tokens?: number; + /** + * Total number of tokens in output + */ + completion_tokens?: number; + /** + * Total number of input and output tokens + */ + total_tokens?: number; + }; + /** + * An array of tool calls requests made during the response generation + */ + tool_calls?: { + /** + * The arguments passed to be passed to the tool call request + */ + arguments?: object; + /** + * The name of the tool to be called + */ + name?: string; + }[]; +}; +declare abstract class Base_Ai_Cf_Qwen_Qwq_32B { + inputs: Ai_Cf_Qwen_Qwq_32B_Input; + postProcessedOutputs: Ai_Cf_Qwen_Qwq_32B_Output; +} +type Ai_Cf_Mistralai_Mistral_Small_3_1_24B_Instruct_Input = Ai_Cf_Mistralai_Mistral_Small_3_1_24B_Instruct_Prompt | Ai_Cf_Mistralai_Mistral_Small_3_1_24B_Instruct_Messages; +interface Ai_Cf_Mistralai_Mistral_Small_3_1_24B_Instruct_Prompt { + /** + * The input text prompt for the model to generate a response. + */ + prompt: string; + /** + * JSON schema that should be fulfilled for the response. + */ + guided_json?: object; + /** + * If true, a chat template is not applied and you must adhere to the specific model's expected formatting. + */ + raw?: boolean; + /** + * If true, the response will be streamed back incrementally using SSE, Server Sent Events. + */ + stream?: boolean; + /** + * The maximum number of tokens to generate in the response. + */ + max_tokens?: number; + /** + * Controls the randomness of the output; higher values produce more random results. + */ + temperature?: number; + /** + * Adjusts the creativity of the AI's responses by controlling how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. + */ + top_p?: number; + /** + * Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. + */ + top_k?: number; + /** + * Random seed for reproducibility of the generation. + */ + seed?: number; + /** + * Penalty for repeated tokens; higher values discourage repetition. + */ + repetition_penalty?: number; + /** + * Decreases the likelihood of the model repeating the same lines verbatim. + */ + frequency_penalty?: number; + /** + * Increases the likelihood of the model introducing new topics. + */ + presence_penalty?: number; +} +interface Ai_Cf_Mistralai_Mistral_Small_3_1_24B_Instruct_Messages { + /** + * An array of message objects representing the conversation history. + */ + messages: { + /** + * The role of the message sender (e.g., 'user', 'assistant', 'system', 'tool'). + */ + role?: string; + /** + * The tool call id. Must be supplied for tool calls for Mistral-3. If you don't know what to put here you can fall back to 000000001 + */ + tool_call_id?: string; + content?: string | { + /** + * Type of the content provided + */ + type?: string; + text?: string; + image_url?: { + /** + * image uri with data (e.g. data:image/jpeg;base64,/9j/...). HTTP URL will not be accepted + */ + url?: string; + }; + }[] | { + /** + * Type of the content provided + */ + type?: string; + text?: string; + image_url?: { + /** + * image uri with data (e.g. data:image/jpeg;base64,/9j/...). HTTP URL will not be accepted + */ + url?: string; + }; + }; + }[]; + functions?: { + name: string; + code: string; + }[]; + /** + * A list of tools available for the assistant to use. + */ + tools?: ({ + /** + * The name of the tool. More descriptive the better. + */ + name: string; + /** + * A brief description of what the tool does. + */ + description: string; + /** + * Schema defining the parameters accepted by the tool. + */ + parameters: { + /** + * The type of the parameters object (usually 'object'). + */ + type: string; + /** + * List of required parameter names. + */ + required?: string[]; + /** + * Definitions of each parameter. + */ + properties: { + [k: string]: { + /** + * The data type of the parameter. + */ + type: string; + /** + * A description of the expected parameter. + */ + description: string; + }; + }; + }; + } | { + /** + * Specifies the type of tool (e.g., 'function'). + */ + type: string; + /** + * Details of the function tool. + */ + function: { + /** + * The name of the function. + */ + name: string; + /** + * A brief description of what the function does. + */ + description: string; + /** + * Schema defining the parameters accepted by the function. + */ + parameters: { + /** + * The type of the parameters object (usually 'object'). + */ + type: string; + /** + * List of required parameter names. + */ + required?: string[]; + /** + * Definitions of each parameter. + */ + properties: { + [k: string]: { + /** + * The data type of the parameter. + */ + type: string; + /** + * A description of the expected parameter. + */ + description: string; + }; + }; + }; + }; + })[]; + /** + * JSON schema that should be fufilled for the response. + */ + guided_json?: object; + /** + * If true, a chat template is not applied and you must adhere to the specific model's expected formatting. + */ + raw?: boolean; + /** + * If true, the response will be streamed back incrementally using SSE, Server Sent Events. + */ + stream?: boolean; + /** + * The maximum number of tokens to generate in the response. + */ + max_tokens?: number; + /** + * Controls the randomness of the output; higher values produce more random results. + */ + temperature?: number; + /** + * Adjusts the creativity of the AI's responses by controlling how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. + */ + top_p?: number; + /** + * Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. + */ + top_k?: number; + /** + * Random seed for reproducibility of the generation. + */ + seed?: number; + /** + * Penalty for repeated tokens; higher values discourage repetition. + */ + repetition_penalty?: number; + /** + * Decreases the likelihood of the model repeating the same lines verbatim. + */ + frequency_penalty?: number; + /** + * Increases the likelihood of the model introducing new topics. + */ + presence_penalty?: number; +} +type Ai_Cf_Mistralai_Mistral_Small_3_1_24B_Instruct_Output = { + /** + * The generated text response from the model + */ + response: string; + /** + * Usage statistics for the inference request + */ + usage?: { + /** + * Total number of tokens in input + */ + prompt_tokens?: number; + /** + * Total number of tokens in output + */ + completion_tokens?: number; + /** + * Total number of input and output tokens + */ + total_tokens?: number; + }; + /** + * An array of tool calls requests made during the response generation + */ + tool_calls?: { + /** + * The arguments passed to be passed to the tool call request + */ + arguments?: object; + /** + * The name of the tool to be called + */ + name?: string; + }[]; +}; +declare abstract class Base_Ai_Cf_Mistralai_Mistral_Small_3_1_24B_Instruct { + inputs: Ai_Cf_Mistralai_Mistral_Small_3_1_24B_Instruct_Input; + postProcessedOutputs: Ai_Cf_Mistralai_Mistral_Small_3_1_24B_Instruct_Output; +} +type Ai_Cf_Google_Gemma_3_12B_It_Input = Ai_Cf_Google_Gemma_3_12B_It_Prompt | Ai_Cf_Google_Gemma_3_12B_It_Messages; +interface Ai_Cf_Google_Gemma_3_12B_It_Prompt { + /** + * The input text prompt for the model to generate a response. + */ + prompt: string; + /** + * JSON schema that should be fufilled for the response. + */ + guided_json?: object; + /** + * If true, a chat template is not applied and you must adhere to the specific model's expected formatting. + */ + raw?: boolean; + /** + * If true, the response will be streamed back incrementally using SSE, Server Sent Events. + */ + stream?: boolean; + /** + * The maximum number of tokens to generate in the response. + */ + max_tokens?: number; + /** + * Controls the randomness of the output; higher values produce more random results. + */ + temperature?: number; + /** + * Adjusts the creativity of the AI's responses by controlling how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. + */ + top_p?: number; + /** + * Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. + */ + top_k?: number; + /** + * Random seed for reproducibility of the generation. + */ + seed?: number; + /** + * Penalty for repeated tokens; higher values discourage repetition. + */ + repetition_penalty?: number; + /** + * Decreases the likelihood of the model repeating the same lines verbatim. + */ + frequency_penalty?: number; + /** + * Increases the likelihood of the model introducing new topics. + */ + presence_penalty?: number; +} +interface Ai_Cf_Google_Gemma_3_12B_It_Messages { + /** + * An array of message objects representing the conversation history. + */ + messages: { + /** + * The role of the message sender (e.g., 'user', 'assistant', 'system', 'tool'). + */ + role?: string; + content?: string | { + /** + * Type of the content provided + */ + type?: string; + text?: string; + image_url?: { + /** + * image uri with data (e.g. data:image/jpeg;base64,/9j/...). HTTP URL will not be accepted + */ + url?: string; + }; + }[]; + }[]; + functions?: { + name: string; + code: string; + }[]; + /** + * A list of tools available for the assistant to use. + */ + tools?: ({ + /** + * The name of the tool. More descriptive the better. + */ + name: string; + /** + * A brief description of what the tool does. + */ + description: string; + /** + * Schema defining the parameters accepted by the tool. + */ + parameters: { + /** + * The type of the parameters object (usually 'object'). + */ + type: string; + /** + * List of required parameter names. + */ + required?: string[]; + /** + * Definitions of each parameter. + */ + properties: { + [k: string]: { + /** + * The data type of the parameter. + */ + type: string; + /** + * A description of the expected parameter. + */ + description: string; + }; + }; + }; + } | { + /** + * Specifies the type of tool (e.g., 'function'). + */ + type: string; + /** + * Details of the function tool. + */ + function: { + /** + * The name of the function. + */ + name: string; + /** + * A brief description of what the function does. + */ + description: string; + /** + * Schema defining the parameters accepted by the function. + */ + parameters: { + /** + * The type of the parameters object (usually 'object'). + */ + type: string; + /** + * List of required parameter names. + */ + required?: string[]; + /** + * Definitions of each parameter. + */ + properties: { + [k: string]: { + /** + * The data type of the parameter. + */ + type: string; + /** + * A description of the expected parameter. + */ + description: string; + }; + }; + }; + }; + })[]; + /** + * JSON schema that should be fufilled for the response. + */ + guided_json?: object; + /** + * If true, a chat template is not applied and you must adhere to the specific model's expected formatting. + */ + raw?: boolean; + /** + * If true, the response will be streamed back incrementally using SSE, Server Sent Events. + */ + stream?: boolean; + /** + * The maximum number of tokens to generate in the response. + */ + max_tokens?: number; + /** + * Controls the randomness of the output; higher values produce more random results. + */ + temperature?: number; + /** + * Adjusts the creativity of the AI's responses by controlling how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. + */ + top_p?: number; + /** + * Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. + */ + top_k?: number; + /** + * Random seed for reproducibility of the generation. + */ + seed?: number; + /** + * Penalty for repeated tokens; higher values discourage repetition. + */ + repetition_penalty?: number; + /** + * Decreases the likelihood of the model repeating the same lines verbatim. + */ + frequency_penalty?: number; + /** + * Increases the likelihood of the model introducing new topics. + */ + presence_penalty?: number; +} +type Ai_Cf_Google_Gemma_3_12B_It_Output = { + /** + * The generated text response from the model + */ + response: string; + /** + * Usage statistics for the inference request + */ + usage?: { + /** + * Total number of tokens in input + */ + prompt_tokens?: number; + /** + * Total number of tokens in output + */ + completion_tokens?: number; + /** + * Total number of input and output tokens + */ + total_tokens?: number; + }; + /** + * An array of tool calls requests made during the response generation + */ + tool_calls?: { + /** + * The arguments passed to be passed to the tool call request + */ + arguments?: object; + /** + * The name of the tool to be called + */ + name?: string; + }[]; +}; +declare abstract class Base_Ai_Cf_Google_Gemma_3_12B_It { + inputs: Ai_Cf_Google_Gemma_3_12B_It_Input; + postProcessedOutputs: Ai_Cf_Google_Gemma_3_12B_It_Output; +} +type Ai_Cf_Meta_Llama_4_Scout_17B_16E_Instruct_Input = Ai_Cf_Meta_Llama_4_Scout_17B_16E_Instruct_Prompt | Ai_Cf_Meta_Llama_4_Scout_17B_16E_Instruct_Messages | Ai_Cf_Meta_Llama_4_Scout_17B_16E_Instruct_Async_Batch; +interface Ai_Cf_Meta_Llama_4_Scout_17B_16E_Instruct_Prompt { + /** + * The input text prompt for the model to generate a response. + */ + prompt: string; + /** + * JSON schema that should be fulfilled for the response. + */ + guided_json?: object; + response_format?: Ai_Cf_Meta_Llama_4_Scout_17B_16E_Instruct_JSON_Mode; + /** + * If true, a chat template is not applied and you must adhere to the specific model's expected formatting. + */ + raw?: boolean; + /** + * If true, the response will be streamed back incrementally using SSE, Server Sent Events. + */ + stream?: boolean; + /** + * The maximum number of tokens to generate in the response. + */ + max_tokens?: number; + /** + * Controls the randomness of the output; higher values produce more random results. + */ + temperature?: number; + /** + * Adjusts the creativity of the AI's responses by controlling how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. + */ + top_p?: number; + /** + * Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. + */ + top_k?: number; + /** + * Random seed for reproducibility of the generation. + */ + seed?: number; + /** + * Penalty for repeated tokens; higher values discourage repetition. + */ + repetition_penalty?: number; + /** + * Decreases the likelihood of the model repeating the same lines verbatim. + */ + frequency_penalty?: number; + /** + * Increases the likelihood of the model introducing new topics. + */ + presence_penalty?: number; +} +interface Ai_Cf_Meta_Llama_4_Scout_17B_16E_Instruct_JSON_Mode { + type?: "json_object" | "json_schema"; + json_schema?: unknown; +} +interface Ai_Cf_Meta_Llama_4_Scout_17B_16E_Instruct_Messages { + /** + * An array of message objects representing the conversation history. + */ + messages: { + /** + * The role of the message sender (e.g., 'user', 'assistant', 'system', 'tool'). + */ + role?: string; + /** + * The tool call id. If you don't know what to put here you can fall back to 000000001 + */ + tool_call_id?: string; + content?: string | { + /** + * Type of the content provided + */ + type?: string; + text?: string; + image_url?: { + /** + * image uri with data (e.g. data:image/jpeg;base64,/9j/...). HTTP URL will not be accepted + */ + url?: string; + }; + }[] | { + /** + * Type of the content provided + */ + type?: string; + text?: string; + image_url?: { + /** + * image uri with data (e.g. data:image/jpeg;base64,/9j/...). HTTP URL will not be accepted + */ + url?: string; + }; + }; + }[]; + functions?: { + name: string; + code: string; + }[]; + /** + * A list of tools available for the assistant to use. + */ + tools?: ({ + /** + * The name of the tool. More descriptive the better. + */ + name: string; + /** + * A brief description of what the tool does. + */ + description: string; + /** + * Schema defining the parameters accepted by the tool. + */ + parameters: { + /** + * The type of the parameters object (usually 'object'). + */ + type: string; + /** + * List of required parameter names. + */ + required?: string[]; + /** + * Definitions of each parameter. + */ + properties: { + [k: string]: { + /** + * The data type of the parameter. + */ + type: string; + /** + * A description of the expected parameter. + */ + description: string; + }; + }; + }; + } | { + /** + * Specifies the type of tool (e.g., 'function'). + */ + type: string; + /** + * Details of the function tool. + */ + function: { + /** + * The name of the function. + */ + name: string; + /** + * A brief description of what the function does. + */ + description: string; + /** + * Schema defining the parameters accepted by the function. + */ + parameters: { + /** + * The type of the parameters object (usually 'object'). + */ + type: string; + /** + * List of required parameter names. + */ + required?: string[]; + /** + * Definitions of each parameter. + */ + properties: { + [k: string]: { + /** + * The data type of the parameter. + */ + type: string; + /** + * A description of the expected parameter. + */ + description: string; + }; + }; + }; + }; + })[]; + response_format?: Ai_Cf_Meta_Llama_4_Scout_17B_16E_Instruct_JSON_Mode; + /** + * JSON schema that should be fufilled for the response. + */ + guided_json?: object; + /** + * If true, a chat template is not applied and you must adhere to the specific model's expected formatting. + */ + raw?: boolean; + /** + * If true, the response will be streamed back incrementally using SSE, Server Sent Events. + */ + stream?: boolean; + /** + * The maximum number of tokens to generate in the response. + */ + max_tokens?: number; + /** + * Controls the randomness of the output; higher values produce more random results. + */ + temperature?: number; + /** + * Adjusts the creativity of the AI's responses by controlling how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. + */ + top_p?: number; + /** + * Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. + */ + top_k?: number; + /** + * Random seed for reproducibility of the generation. + */ + seed?: number; + /** + * Penalty for repeated tokens; higher values discourage repetition. + */ + repetition_penalty?: number; + /** + * Decreases the likelihood of the model repeating the same lines verbatim. + */ + frequency_penalty?: number; + /** + * Increases the likelihood of the model introducing new topics. + */ + presence_penalty?: number; +} +interface Ai_Cf_Meta_Llama_4_Scout_17B_16E_Instruct_Async_Batch { + requests: (Ai_Cf_Meta_Llama_4_Scout_17B_16E_Instruct_Prompt_Inner | Ai_Cf_Meta_Llama_4_Scout_17B_16E_Instruct_Messages_Inner)[]; +} +interface Ai_Cf_Meta_Llama_4_Scout_17B_16E_Instruct_Prompt_Inner { + /** + * The input text prompt for the model to generate a response. + */ + prompt: string; + /** + * JSON schema that should be fulfilled for the response. + */ + guided_json?: object; + response_format?: Ai_Cf_Meta_Llama_4_Scout_17B_16E_Instruct_JSON_Mode; + /** + * If true, a chat template is not applied and you must adhere to the specific model's expected formatting. + */ + raw?: boolean; + /** + * If true, the response will be streamed back incrementally using SSE, Server Sent Events. + */ + stream?: boolean; + /** + * The maximum number of tokens to generate in the response. + */ + max_tokens?: number; + /** + * Controls the randomness of the output; higher values produce more random results. + */ + temperature?: number; + /** + * Adjusts the creativity of the AI's responses by controlling how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. + */ + top_p?: number; + /** + * Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. + */ + top_k?: number; + /** + * Random seed for reproducibility of the generation. + */ + seed?: number; + /** + * Penalty for repeated tokens; higher values discourage repetition. + */ + repetition_penalty?: number; + /** + * Decreases the likelihood of the model repeating the same lines verbatim. + */ + frequency_penalty?: number; + /** + * Increases the likelihood of the model introducing new topics. + */ + presence_penalty?: number; +} +interface Ai_Cf_Meta_Llama_4_Scout_17B_16E_Instruct_Messages_Inner { + /** + * An array of message objects representing the conversation history. + */ + messages: { + /** + * The role of the message sender (e.g., 'user', 'assistant', 'system', 'tool'). + */ + role?: string; + /** + * The tool call id. If you don't know what to put here you can fall back to 000000001 + */ + tool_call_id?: string; + content?: string | { + /** + * Type of the content provided + */ + type?: string; + text?: string; + image_url?: { + /** + * image uri with data (e.g. data:image/jpeg;base64,/9j/...). HTTP URL will not be accepted + */ + url?: string; + }; + }[] | { + /** + * Type of the content provided + */ + type?: string; + text?: string; + image_url?: { + /** + * image uri with data (e.g. data:image/jpeg;base64,/9j/...). HTTP URL will not be accepted + */ + url?: string; + }; + }; + }[]; + functions?: { + name: string; + code: string; + }[]; + /** + * A list of tools available for the assistant to use. + */ + tools?: ({ + /** + * The name of the tool. More descriptive the better. + */ + name: string; + /** + * A brief description of what the tool does. + */ + description: string; + /** + * Schema defining the parameters accepted by the tool. + */ + parameters: { + /** + * The type of the parameters object (usually 'object'). + */ + type: string; + /** + * List of required parameter names. + */ + required?: string[]; + /** + * Definitions of each parameter. + */ + properties: { + [k: string]: { + /** + * The data type of the parameter. + */ + type: string; + /** + * A description of the expected parameter. + */ + description: string; + }; + }; + }; + } | { + /** + * Specifies the type of tool (e.g., 'function'). + */ + type: string; + /** + * Details of the function tool. + */ + function: { + /** + * The name of the function. + */ + name: string; + /** + * A brief description of what the function does. + */ + description: string; + /** + * Schema defining the parameters accepted by the function. + */ + parameters: { + /** + * The type of the parameters object (usually 'object'). + */ + type: string; + /** + * List of required parameter names. + */ + required?: string[]; + /** + * Definitions of each parameter. + */ + properties: { + [k: string]: { + /** + * The data type of the parameter. + */ + type: string; + /** + * A description of the expected parameter. + */ + description: string; + }; + }; + }; + }; + })[]; + response_format?: Ai_Cf_Meta_Llama_4_Scout_17B_16E_Instruct_JSON_Mode; + /** + * JSON schema that should be fufilled for the response. + */ + guided_json?: object; + /** + * If true, a chat template is not applied and you must adhere to the specific model's expected formatting. + */ + raw?: boolean; + /** + * If true, the response will be streamed back incrementally using SSE, Server Sent Events. + */ + stream?: boolean; + /** + * The maximum number of tokens to generate in the response. + */ + max_tokens?: number; + /** + * Controls the randomness of the output; higher values produce more random results. + */ + temperature?: number; + /** + * Adjusts the creativity of the AI's responses by controlling how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. + */ + top_p?: number; + /** + * Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. + */ + top_k?: number; + /** + * Random seed for reproducibility of the generation. + */ + seed?: number; + /** + * Penalty for repeated tokens; higher values discourage repetition. + */ + repetition_penalty?: number; + /** + * Decreases the likelihood of the model repeating the same lines verbatim. + */ + frequency_penalty?: number; + /** + * Increases the likelihood of the model introducing new topics. + */ + presence_penalty?: number; +} +type Ai_Cf_Meta_Llama_4_Scout_17B_16E_Instruct_Output = { + /** + * The generated text response from the model + */ + response: string; + /** + * Usage statistics for the inference request + */ + usage?: { + /** + * Total number of tokens in input + */ + prompt_tokens?: number; + /** + * Total number of tokens in output + */ + completion_tokens?: number; + /** + * Total number of input and output tokens + */ + total_tokens?: number; + }; + /** + * An array of tool calls requests made during the response generation + */ + tool_calls?: { + /** + * The tool call id. + */ + id?: string; + /** + * Specifies the type of tool (e.g., 'function'). + */ + type?: string; + /** + * Details of the function tool. + */ + function?: { + /** + * The name of the tool to be called + */ + name?: string; + /** + * The arguments passed to be passed to the tool call request + */ + arguments?: object; + }; + }[]; +}; +declare abstract class Base_Ai_Cf_Meta_Llama_4_Scout_17B_16E_Instruct { + inputs: Ai_Cf_Meta_Llama_4_Scout_17B_16E_Instruct_Input; + postProcessedOutputs: Ai_Cf_Meta_Llama_4_Scout_17B_16E_Instruct_Output; +} +type Ai_Cf_Qwen_Qwen3_30B_A3B_Fp8_Input = Ai_Cf_Qwen_Qwen3_30B_A3B_Fp8_Prompt | Ai_Cf_Qwen_Qwen3_30B_A3B_Fp8_Messages | Ai_Cf_Qwen_Qwen3_30B_A3B_Fp8_Async_Batch; +interface Ai_Cf_Qwen_Qwen3_30B_A3B_Fp8_Prompt { + /** + * The input text prompt for the model to generate a response. + */ + prompt: string; + /** + * Name of the LoRA (Low-Rank Adaptation) model to fine-tune the base model. + */ + lora?: string; + response_format?: Ai_Cf_Qwen_Qwen3_30B_A3B_Fp8_JSON_Mode; + /** + * If true, a chat template is not applied and you must adhere to the specific model's expected formatting. + */ + raw?: boolean; + /** + * If true, the response will be streamed back incrementally using SSE, Server Sent Events. + */ + stream?: boolean; + /** + * The maximum number of tokens to generate in the response. + */ + max_tokens?: number; + /** + * Controls the randomness of the output; higher values produce more random results. + */ + temperature?: number; + /** + * Adjusts the creativity of the AI's responses by controlling how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. + */ + top_p?: number; + /** + * Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. + */ + top_k?: number; + /** + * Random seed for reproducibility of the generation. + */ + seed?: number; + /** + * Penalty for repeated tokens; higher values discourage repetition. + */ + repetition_penalty?: number; + /** + * Decreases the likelihood of the model repeating the same lines verbatim. + */ + frequency_penalty?: number; + /** + * Increases the likelihood of the model introducing new topics. + */ + presence_penalty?: number; +} +interface Ai_Cf_Qwen_Qwen3_30B_A3B_Fp8_JSON_Mode { + type?: "json_object" | "json_schema"; + json_schema?: unknown; +} +interface Ai_Cf_Qwen_Qwen3_30B_A3B_Fp8_Messages { + /** + * An array of message objects representing the conversation history. + */ + messages: { + /** + * The role of the message sender (e.g., 'user', 'assistant', 'system', 'tool'). + */ + role: string; + content: string | { + /** + * Type of the content (text) + */ + type?: string; + /** + * Text content + */ + text?: string; + }[]; + }[]; + functions?: { + name: string; + code: string; + }[]; + /** + * A list of tools available for the assistant to use. + */ + tools?: ({ + /** + * The name of the tool. More descriptive the better. + */ + name: string; + /** + * A brief description of what the tool does. + */ + description: string; + /** + * Schema defining the parameters accepted by the tool. + */ + parameters: { + /** + * The type of the parameters object (usually 'object'). + */ + type: string; + /** + * List of required parameter names. + */ + required?: string[]; + /** + * Definitions of each parameter. + */ + properties: { + [k: string]: { + /** + * The data type of the parameter. + */ + type: string; + /** + * A description of the expected parameter. + */ + description: string; + }; + }; + }; + } | { + /** + * Specifies the type of tool (e.g., 'function'). + */ + type: string; + /** + * Details of the function tool. + */ + function: { + /** + * The name of the function. + */ + name: string; + /** + * A brief description of what the function does. + */ + description: string; + /** + * Schema defining the parameters accepted by the function. + */ + parameters: { + /** + * The type of the parameters object (usually 'object'). + */ + type: string; + /** + * List of required parameter names. + */ + required?: string[]; + /** + * Definitions of each parameter. + */ + properties: { + [k: string]: { + /** + * The data type of the parameter. + */ + type: string; + /** + * A description of the expected parameter. + */ + description: string; + }; + }; + }; + }; + })[]; + response_format?: Ai_Cf_Qwen_Qwen3_30B_A3B_Fp8_JSON_Mode_1; + /** + * If true, a chat template is not applied and you must adhere to the specific model's expected formatting. + */ + raw?: boolean; + /** + * If true, the response will be streamed back incrementally using SSE, Server Sent Events. + */ + stream?: boolean; + /** + * The maximum number of tokens to generate in the response. + */ + max_tokens?: number; + /** + * Controls the randomness of the output; higher values produce more random results. + */ + temperature?: number; + /** + * Adjusts the creativity of the AI's responses by controlling how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. + */ + top_p?: number; + /** + * Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. + */ + top_k?: number; + /** + * Random seed for reproducibility of the generation. + */ + seed?: number; + /** + * Penalty for repeated tokens; higher values discourage repetition. + */ + repetition_penalty?: number; + /** + * Decreases the likelihood of the model repeating the same lines verbatim. + */ + frequency_penalty?: number; + /** + * Increases the likelihood of the model introducing new topics. + */ + presence_penalty?: number; +} +interface Ai_Cf_Qwen_Qwen3_30B_A3B_Fp8_JSON_Mode_1 { + type?: "json_object" | "json_schema"; + json_schema?: unknown; +} +interface Ai_Cf_Qwen_Qwen3_30B_A3B_Fp8_Async_Batch { + requests: (Ai_Cf_Qwen_Qwen3_30B_A3B_Fp8_Prompt_1 | Ai_Cf_Qwen_Qwen3_30B_A3B_Fp8_Messages_1)[]; +} +interface Ai_Cf_Qwen_Qwen3_30B_A3B_Fp8_Prompt_1 { + /** + * The input text prompt for the model to generate a response. + */ + prompt: string; + /** + * Name of the LoRA (Low-Rank Adaptation) model to fine-tune the base model. + */ + lora?: string; + response_format?: Ai_Cf_Qwen_Qwen3_30B_A3B_Fp8_JSON_Mode_2; + /** + * If true, a chat template is not applied and you must adhere to the specific model's expected formatting. + */ + raw?: boolean; + /** + * If true, the response will be streamed back incrementally using SSE, Server Sent Events. + */ + stream?: boolean; + /** + * The maximum number of tokens to generate in the response. + */ + max_tokens?: number; + /** + * Controls the randomness of the output; higher values produce more random results. + */ + temperature?: number; + /** + * Adjusts the creativity of the AI's responses by controlling how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. + */ + top_p?: number; + /** + * Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. + */ + top_k?: number; + /** + * Random seed for reproducibility of the generation. + */ + seed?: number; + /** + * Penalty for repeated tokens; higher values discourage repetition. + */ + repetition_penalty?: number; + /** + * Decreases the likelihood of the model repeating the same lines verbatim. + */ + frequency_penalty?: number; + /** + * Increases the likelihood of the model introducing new topics. + */ + presence_penalty?: number; +} +interface Ai_Cf_Qwen_Qwen3_30B_A3B_Fp8_JSON_Mode_2 { + type?: "json_object" | "json_schema"; + json_schema?: unknown; +} +interface Ai_Cf_Qwen_Qwen3_30B_A3B_Fp8_Messages_1 { + /** + * An array of message objects representing the conversation history. + */ + messages: { + /** + * The role of the message sender (e.g., 'user', 'assistant', 'system', 'tool'). + */ + role: string; + content: string | { + /** + * Type of the content (text) + */ + type?: string; + /** + * Text content + */ + text?: string; + }[]; + }[]; + functions?: { + name: string; + code: string; + }[]; + /** + * A list of tools available for the assistant to use. + */ + tools?: ({ + /** + * The name of the tool. More descriptive the better. + */ + name: string; + /** + * A brief description of what the tool does. + */ + description: string; + /** + * Schema defining the parameters accepted by the tool. + */ + parameters: { + /** + * The type of the parameters object (usually 'object'). + */ + type: string; + /** + * List of required parameter names. + */ + required?: string[]; + /** + * Definitions of each parameter. + */ + properties: { + [k: string]: { + /** + * The data type of the parameter. + */ + type: string; + /** + * A description of the expected parameter. + */ + description: string; + }; + }; + }; + } | { + /** + * Specifies the type of tool (e.g., 'function'). + */ + type: string; + /** + * Details of the function tool. + */ + function: { + /** + * The name of the function. + */ + name: string; + /** + * A brief description of what the function does. + */ + description: string; + /** + * Schema defining the parameters accepted by the function. + */ + parameters: { + /** + * The type of the parameters object (usually 'object'). + */ + type: string; + /** + * List of required parameter names. + */ + required?: string[]; + /** + * Definitions of each parameter. + */ + properties: { + [k: string]: { + /** + * The data type of the parameter. + */ + type: string; + /** + * A description of the expected parameter. + */ + description: string; + }; + }; + }; + }; + })[]; + response_format?: Ai_Cf_Qwen_Qwen3_30B_A3B_Fp8_JSON_Mode_3; + /** + * If true, a chat template is not applied and you must adhere to the specific model's expected formatting. + */ + raw?: boolean; + /** + * If true, the response will be streamed back incrementally using SSE, Server Sent Events. + */ + stream?: boolean; + /** + * The maximum number of tokens to generate in the response. + */ + max_tokens?: number; + /** + * Controls the randomness of the output; higher values produce more random results. + */ + temperature?: number; + /** + * Adjusts the creativity of the AI's responses by controlling how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. + */ + top_p?: number; + /** + * Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. + */ + top_k?: number; + /** + * Random seed for reproducibility of the generation. + */ + seed?: number; + /** + * Penalty for repeated tokens; higher values discourage repetition. + */ + repetition_penalty?: number; + /** + * Decreases the likelihood of the model repeating the same lines verbatim. + */ + frequency_penalty?: number; + /** + * Increases the likelihood of the model introducing new topics. + */ + presence_penalty?: number; +} +interface Ai_Cf_Qwen_Qwen3_30B_A3B_Fp8_JSON_Mode_3 { + type?: "json_object" | "json_schema"; + json_schema?: unknown; +} +type Ai_Cf_Qwen_Qwen3_30B_A3B_Fp8_Output = Ai_Cf_Qwen_Qwen3_30B_A3B_Fp8_Chat_Completion_Response | Ai_Cf_Qwen_Qwen3_30B_A3B_Fp8_Text_Completion_Response | string | Ai_Cf_Qwen_Qwen3_30B_A3B_Fp8_AsyncResponse; +interface Ai_Cf_Qwen_Qwen3_30B_A3B_Fp8_Chat_Completion_Response { + /** + * Unique identifier for the completion + */ + id?: string; + /** + * Object type identifier + */ + object?: "chat.completion"; + /** + * Unix timestamp of when the completion was created + */ + created?: number; + /** + * Model used for the completion + */ + model?: string; + /** + * List of completion choices + */ + choices?: { + /** + * Index of the choice in the list + */ + index?: number; + /** + * The message generated by the model + */ + message?: { + /** + * Role of the message author + */ + role: string; + /** + * The content of the message + */ + content: string; + /** + * Internal reasoning content (if available) + */ + reasoning_content?: string; + /** + * Tool calls made by the assistant + */ + tool_calls?: { + /** + * Unique identifier for the tool call + */ + id: string; + /** + * Type of tool call + */ + type: "function"; + function: { + /** + * Name of the function to call + */ + name: string; + /** + * JSON string of arguments for the function + */ + arguments: string; + }; + }[]; + }; + /** + * Reason why the model stopped generating + */ + finish_reason?: string; + /** + * Stop reason (may be null) + */ + stop_reason?: string | null; + /** + * Log probabilities (if requested) + */ + logprobs?: {} | null; + }[]; + /** + * Usage statistics for the inference request + */ + usage?: { + /** + * Total number of tokens in input + */ + prompt_tokens?: number; + /** + * Total number of tokens in output + */ + completion_tokens?: number; + /** + * Total number of input and output tokens + */ + total_tokens?: number; + }; + /** + * Log probabilities for the prompt (if requested) + */ + prompt_logprobs?: {} | null; +} +interface Ai_Cf_Qwen_Qwen3_30B_A3B_Fp8_Text_Completion_Response { + /** + * Unique identifier for the completion + */ + id?: string; + /** + * Object type identifier + */ + object?: "text_completion"; + /** + * Unix timestamp of when the completion was created + */ + created?: number; + /** + * Model used for the completion + */ + model?: string; + /** + * List of completion choices + */ + choices?: { + /** + * Index of the choice in the list + */ + index: number; + /** + * The generated text completion + */ + text: string; + /** + * Reason why the model stopped generating + */ + finish_reason: string; + /** + * Stop reason (may be null) + */ + stop_reason?: string | null; + /** + * Log probabilities (if requested) + */ + logprobs?: {} | null; + /** + * Log probabilities for the prompt (if requested) + */ + prompt_logprobs?: {} | null; + }[]; + /** + * Usage statistics for the inference request + */ + usage?: { + /** + * Total number of tokens in input + */ + prompt_tokens?: number; + /** + * Total number of tokens in output + */ + completion_tokens?: number; + /** + * Total number of input and output tokens + */ + total_tokens?: number; + }; +} +interface Ai_Cf_Qwen_Qwen3_30B_A3B_Fp8_AsyncResponse { + /** + * The async request id that can be used to obtain the results. + */ + request_id?: string; +} +declare abstract class Base_Ai_Cf_Qwen_Qwen3_30B_A3B_Fp8 { + inputs: Ai_Cf_Qwen_Qwen3_30B_A3B_Fp8_Input; + postProcessedOutputs: Ai_Cf_Qwen_Qwen3_30B_A3B_Fp8_Output; +} +interface Ai_Cf_Deepgram_Nova_3_Input { + audio: { + body: object; + contentType: string; + }; + /** + * Sets how the model will interpret strings submitted to the custom_topic param. When strict, the model will only return topics submitted using the custom_topic param. When extended, the model will return its own detected topics in addition to those submitted using the custom_topic param. + */ + custom_topic_mode?: "extended" | "strict"; + /** + * Custom topics you want the model to detect within your input audio or text if present Submit up to 100 + */ + custom_topic?: string; + /** + * Sets how the model will interpret intents submitted to the custom_intent param. When strict, the model will only return intents submitted using the custom_intent param. When extended, the model will return its own detected intents in addition those submitted using the custom_intents param + */ + custom_intent_mode?: "extended" | "strict"; + /** + * Custom intents you want the model to detect within your input audio if present + */ + custom_intent?: string; + /** + * Identifies and extracts key entities from content in submitted audio + */ + detect_entities?: boolean; + /** + * Identifies the dominant language spoken in submitted audio + */ + detect_language?: boolean; + /** + * Recognize speaker changes. Each word in the transcript will be assigned a speaker number starting at 0 + */ + diarize?: boolean; + /** + * Identify and extract key entities from content in submitted audio + */ + dictation?: boolean; + /** + * Specify the expected encoding of your submitted audio + */ + encoding?: "linear16" | "flac" | "mulaw" | "amr-nb" | "amr-wb" | "opus" | "speex" | "g729"; + /** + * Arbitrary key-value pairs that are attached to the API response for usage in downstream processing + */ + extra?: string; + /** + * Filler Words can help transcribe interruptions in your audio, like 'uh' and 'um' + */ + filler_words?: boolean; + /** + * Key term prompting can boost or suppress specialized terminology and brands. + */ + keyterm?: string; + /** + * Keywords can boost or suppress specialized terminology and brands. + */ + keywords?: string; + /** + * The BCP-47 language tag that hints at the primary spoken language. Depending on the Model and API endpoint you choose only certain languages are available. + */ + language?: string; + /** + * Spoken measurements will be converted to their corresponding abbreviations. + */ + measurements?: boolean; + /** + * Opts out requests from the Deepgram Model Improvement Program. Refer to our Docs for pricing impacts before setting this to true. https://dpgr.am/deepgram-mip. + */ + mip_opt_out?: boolean; + /** + * Mode of operation for the model representing broad area of topic that will be talked about in the supplied audio + */ + mode?: "general" | "medical" | "finance"; + /** + * Transcribe each audio channel independently. + */ + multichannel?: boolean; + /** + * Numerals converts numbers from written format to numerical format. + */ + numerals?: boolean; + /** + * Splits audio into paragraphs to improve transcript readability. + */ + paragraphs?: boolean; + /** + * Profanity Filter looks for recognized profanity and converts it to the nearest recognized non-profane word or removes it from the transcript completely. + */ + profanity_filter?: boolean; + /** + * Add punctuation and capitalization to the transcript. + */ + punctuate?: boolean; + /** + * Redaction removes sensitive information from your transcripts. + */ + redact?: string; + /** + * Search for terms or phrases in submitted audio and replaces them. + */ + replace?: string; + /** + * Search for terms or phrases in submitted audio. + */ + search?: string; + /** + * Recognizes the sentiment throughout a transcript or text. + */ + sentiment?: boolean; + /** + * Apply formatting to transcript output. When set to true, additional formatting will be applied to transcripts to improve readability. + */ + smart_format?: boolean; + /** + * Detect topics throughout a transcript or text. + */ + topics?: boolean; + /** + * Segments speech into meaningful semantic units. + */ + utterances?: boolean; + /** + * Seconds to wait before detecting a pause between words in submitted audio. + */ + utt_split?: number; + /** + * The number of channels in the submitted audio + */ + channels?: number; + /** + * Specifies whether the streaming endpoint should provide ongoing transcription updates as more audio is received. When set to true, the endpoint sends continuous updates, meaning transcription results may evolve over time. Note: Supported only for webosockets. + */ + interim_results?: boolean; + /** + * Indicates how long model will wait to detect whether a speaker has finished speaking or pauses for a significant period of time. When set to a value, the streaming endpoint immediately finalizes the transcription for the processed time range and returns the transcript with a speech_final parameter set to true. Can also be set to false to disable endpointing + */ + endpointing?: string; + /** + * Indicates that speech has started. You'll begin receiving Speech Started messages upon speech starting. Note: Supported only for webosockets. + */ + vad_events?: boolean; + /** + * Indicates how long model will wait to send an UtteranceEnd message after a word has been transcribed. Use with interim_results. Note: Supported only for webosockets. + */ + utterance_end_ms?: boolean; +} +interface Ai_Cf_Deepgram_Nova_3_Output { + results?: { + channels?: { + alternatives?: { + confidence?: number; + transcript?: string; + words?: { + confidence?: number; + end?: number; + start?: number; + word?: string; + }[]; + }[]; + }[]; + summary?: { + result?: string; + short?: string; + }; + sentiments?: { + segments?: { + text?: string; + start_word?: number; + end_word?: number; + sentiment?: string; + sentiment_score?: number; + }[]; + average?: { + sentiment?: string; + sentiment_score?: number; + }; + }; + }; +} +declare abstract class Base_Ai_Cf_Deepgram_Nova_3 { + inputs: Ai_Cf_Deepgram_Nova_3_Input; + postProcessedOutputs: Ai_Cf_Deepgram_Nova_3_Output; +} +interface Ai_Cf_Qwen_Qwen3_Embedding_0_6B_Input { + queries?: string | string[]; + /** + * Optional instruction for the task + */ + instruction?: string; + documents?: string | string[]; + text?: string | string[]; +} +interface Ai_Cf_Qwen_Qwen3_Embedding_0_6B_Output { + data?: number[][]; + shape?: number[]; +} +declare abstract class Base_Ai_Cf_Qwen_Qwen3_Embedding_0_6B { + inputs: Ai_Cf_Qwen_Qwen3_Embedding_0_6B_Input; + postProcessedOutputs: Ai_Cf_Qwen_Qwen3_Embedding_0_6B_Output; +} +type Ai_Cf_Pipecat_Ai_Smart_Turn_V2_Input = { + /** + * readable stream with audio data and content-type specified for that data + */ + audio: { + body: object; + contentType: string; + }; + /** + * type of data PCM data that's sent to the inference server as raw array + */ + dtype?: "uint8" | "float32" | "float64"; +} | { + /** + * base64 encoded audio data + */ + audio: string; + /** + * type of data PCM data that's sent to the inference server as raw array + */ + dtype?: "uint8" | "float32" | "float64"; +}; +interface Ai_Cf_Pipecat_Ai_Smart_Turn_V2_Output { + /** + * if true, end-of-turn was detected + */ + is_complete?: boolean; + /** + * probability of the end-of-turn detection + */ + probability?: number; +} +declare abstract class Base_Ai_Cf_Pipecat_Ai_Smart_Turn_V2 { + inputs: Ai_Cf_Pipecat_Ai_Smart_Turn_V2_Input; + postProcessedOutputs: Ai_Cf_Pipecat_Ai_Smart_Turn_V2_Output; +} +declare abstract class Base_Ai_Cf_Openai_Gpt_Oss_120B { + inputs: XOR & { + reasoning?: (Omit & { + /** + * Reasoning effort. Supported levels: low, medium, high. Reasoning cannot be disabled. + * + * @default "medium" + */ + effort?: "low" | "medium" | "high" | null; + }) | null; + }, Omit & { + /** + * Reasoning effort. Supported levels: low, medium, high. Reasoning cannot be disabled. + * + * @default "medium" + */ + reasoning_effort?: "low" | "medium" | "high" | null; + chat_template_kwargs?: Omit & { + /** + * Reasoning is always enabled for this model and cannot be disabled. + * + * @default true + */ + enable_thinking?: true; + }; + }>; + postProcessedOutputs: XOR; +} +declare abstract class Base_Ai_Cf_Openai_Gpt_Oss_20B { + inputs: XOR & { + reasoning?: (Omit & { + /** + * Reasoning effort. Supported levels: low, medium, high. Reasoning cannot be disabled. + * + * @default "medium" + */ + effort?: "low" | "medium" | "high" | null; + }) | null; + }, Omit & { + /** + * Reasoning effort. Supported levels: low, medium, high. Reasoning cannot be disabled. + * + * @default "medium" + */ + reasoning_effort?: "low" | "medium" | "high" | null; + chat_template_kwargs?: Omit & { + /** + * Reasoning is always enabled for this model and cannot be disabled. + * + * @default true + */ + enable_thinking?: true; + }; + }>; + postProcessedOutputs: XOR; +} +interface Ai_Cf_Leonardo_Phoenix_1_0_Input { + /** + * A text description of the image you want to generate. + */ + prompt: string; + /** + * Controls how closely the generated image should adhere to the prompt; higher values make the image more aligned with the prompt + */ + guidance?: number; + /** + * Random seed for reproducibility of the image generation + */ + seed?: number; + /** + * The height of the generated image in pixels + */ + height?: number; + /** + * The width of the generated image in pixels + */ + width?: number; + /** + * The number of diffusion steps; higher values can improve quality but take longer + */ + num_steps?: number; + /** + * Specify what to exclude from the generated images + */ + negative_prompt?: string; +} +/** + * The generated image in JPEG format + */ +type Ai_Cf_Leonardo_Phoenix_1_0_Output = string; +declare abstract class Base_Ai_Cf_Leonardo_Phoenix_1_0 { + inputs: Ai_Cf_Leonardo_Phoenix_1_0_Input; + postProcessedOutputs: Ai_Cf_Leonardo_Phoenix_1_0_Output; +} +interface Ai_Cf_Leonardo_Lucid_Origin_Input { + /** + * A text description of the image you want to generate. + */ + prompt: string; + /** + * Controls how closely the generated image should adhere to the prompt; higher values make the image more aligned with the prompt + */ + guidance?: number; + /** + * Random seed for reproducibility of the image generation + */ + seed?: number; + /** + * The height of the generated image in pixels + */ + height?: number; + /** + * The width of the generated image in pixels + */ + width?: number; + /** + * The number of diffusion steps; higher values can improve quality but take longer + */ + num_steps?: number; + /** + * The number of diffusion steps; higher values can improve quality but take longer + */ + steps?: number; +} +interface Ai_Cf_Leonardo_Lucid_Origin_Output { + /** + * The generated image in Base64 format. + */ + image?: string; +} +declare abstract class Base_Ai_Cf_Leonardo_Lucid_Origin { + inputs: Ai_Cf_Leonardo_Lucid_Origin_Input; + postProcessedOutputs: Ai_Cf_Leonardo_Lucid_Origin_Output; +} +interface Ai_Cf_Deepgram_Aura_1_Input { + /** + * Speaker used to produce the audio. + */ + speaker?: "angus" | "asteria" | "arcas" | "orion" | "orpheus" | "athena" | "luna" | "zeus" | "perseus" | "helios" | "hera" | "stella"; + /** + * Encoding of the output audio. + */ + encoding?: "linear16" | "flac" | "mulaw" | "alaw" | "mp3" | "opus" | "aac"; + /** + * Container specifies the file format wrapper for the output audio. The available options depend on the encoding type.. + */ + container?: "none" | "wav" | "ogg"; + /** + * The text content to be converted to speech + */ + text: string; + /** + * Sample Rate specifies the sample rate for the output audio. Based on the encoding, different sample rates are supported. For some encodings, the sample rate is not configurable + */ + sample_rate?: number; + /** + * The bitrate of the audio in bits per second. Choose from predefined ranges or specific values based on the encoding type. + */ + bit_rate?: number; +} +/** + * The generated audio in MP3 format + */ +type Ai_Cf_Deepgram_Aura_1_Output = string; +declare abstract class Base_Ai_Cf_Deepgram_Aura_1 { + inputs: Ai_Cf_Deepgram_Aura_1_Input; + postProcessedOutputs: Ai_Cf_Deepgram_Aura_1_Output; +} +interface Ai_Cf_Ai4Bharat_Indictrans2_En_Indic_1B_Input { + /** + * Input text to translate. Can be a single string or a list of strings. + */ + text: string | string[]; + /** + * Target langauge to translate to + */ + target_language: "asm_Beng" | "awa_Deva" | "ben_Beng" | "bho_Deva" | "brx_Deva" | "doi_Deva" | "eng_Latn" | "gom_Deva" | "gon_Deva" | "guj_Gujr" | "hin_Deva" | "hne_Deva" | "kan_Knda" | "kas_Arab" | "kas_Deva" | "kha_Latn" | "lus_Latn" | "mag_Deva" | "mai_Deva" | "mal_Mlym" | "mar_Deva" | "mni_Beng" | "mni_Mtei" | "npi_Deva" | "ory_Orya" | "pan_Guru" | "san_Deva" | "sat_Olck" | "snd_Arab" | "snd_Deva" | "tam_Taml" | "tel_Telu" | "urd_Arab" | "unr_Deva"; +} +interface Ai_Cf_Ai4Bharat_Indictrans2_En_Indic_1B_Output { + /** + * Translated texts + */ + translations: string[]; +} +declare abstract class Base_Ai_Cf_Ai4Bharat_Indictrans2_En_Indic_1B { + inputs: Ai_Cf_Ai4Bharat_Indictrans2_En_Indic_1B_Input; + postProcessedOutputs: Ai_Cf_Ai4Bharat_Indictrans2_En_Indic_1B_Output; +} +type Ai_Cf_Aisingapore_Gemma_Sea_Lion_V4_27B_It_Input = Ai_Cf_Aisingapore_Gemma_Sea_Lion_V4_27B_It_Prompt | Ai_Cf_Aisingapore_Gemma_Sea_Lion_V4_27B_It_Messages | Ai_Cf_Aisingapore_Gemma_Sea_Lion_V4_27B_It_Async_Batch; +interface Ai_Cf_Aisingapore_Gemma_Sea_Lion_V4_27B_It_Prompt { + /** + * The input text prompt for the model to generate a response. + */ + prompt: string; + /** + * Name of the LoRA (Low-Rank Adaptation) model to fine-tune the base model. + */ + lora?: string; + response_format?: Ai_Cf_Aisingapore_Gemma_Sea_Lion_V4_27B_It_JSON_Mode; + /** + * If true, a chat template is not applied and you must adhere to the specific model's expected formatting. + */ + raw?: boolean; + /** + * If true, the response will be streamed back incrementally using SSE, Server Sent Events. + */ + stream?: boolean; + /** + * The maximum number of tokens to generate in the response. + */ + max_tokens?: number; + /** + * Controls the randomness of the output; higher values produce more random results. + */ + temperature?: number; + /** + * Adjusts the creativity of the AI's responses by controlling how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. + */ + top_p?: number; + /** + * Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. + */ + top_k?: number; + /** + * Random seed for reproducibility of the generation. + */ + seed?: number; + /** + * Penalty for repeated tokens; higher values discourage repetition. + */ + repetition_penalty?: number; + /** + * Decreases the likelihood of the model repeating the same lines verbatim. + */ + frequency_penalty?: number; + /** + * Increases the likelihood of the model introducing new topics. + */ + presence_penalty?: number; +} +interface Ai_Cf_Aisingapore_Gemma_Sea_Lion_V4_27B_It_JSON_Mode { + type?: "json_object" | "json_schema"; + json_schema?: unknown; +} +interface Ai_Cf_Aisingapore_Gemma_Sea_Lion_V4_27B_It_Messages { + /** + * An array of message objects representing the conversation history. + */ + messages: { + /** + * The role of the message sender (e.g., 'user', 'assistant', 'system', 'tool'). + */ + role: string; + content: string | { + /** + * Type of the content (text) + */ + type?: string; + /** + * Text content + */ + text?: string; + }[]; + }[]; + functions?: { + name: string; + code: string; + }[]; + /** + * A list of tools available for the assistant to use. + */ + tools?: ({ + /** + * The name of the tool. More descriptive the better. + */ + name: string; + /** + * A brief description of what the tool does. + */ + description: string; + /** + * Schema defining the parameters accepted by the tool. + */ + parameters: { + /** + * The type of the parameters object (usually 'object'). + */ + type: string; + /** + * List of required parameter names. + */ + required?: string[]; + /** + * Definitions of each parameter. + */ + properties: { + [k: string]: { + /** + * The data type of the parameter. + */ + type: string; + /** + * A description of the expected parameter. + */ + description: string; + }; + }; + }; + } | { + /** + * Specifies the type of tool (e.g., 'function'). + */ + type: string; + /** + * Details of the function tool. + */ + function: { + /** + * The name of the function. + */ + name: string; + /** + * A brief description of what the function does. + */ + description: string; + /** + * Schema defining the parameters accepted by the function. + */ + parameters: { + /** + * The type of the parameters object (usually 'object'). + */ + type: string; + /** + * List of required parameter names. + */ + required?: string[]; + /** + * Definitions of each parameter. + */ + properties: { + [k: string]: { + /** + * The data type of the parameter. + */ + type: string; + /** + * A description of the expected parameter. + */ + description: string; + }; + }; + }; + }; + })[]; + response_format?: Ai_Cf_Aisingapore_Gemma_Sea_Lion_V4_27B_It_JSON_Mode_1; + /** + * If true, a chat template is not applied and you must adhere to the specific model's expected formatting. + */ + raw?: boolean; + /** + * If true, the response will be streamed back incrementally using SSE, Server Sent Events. + */ + stream?: boolean; + /** + * The maximum number of tokens to generate in the response. + */ + max_tokens?: number; + /** + * Controls the randomness of the output; higher values produce more random results. + */ + temperature?: number; + /** + * Adjusts the creativity of the AI's responses by controlling how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. + */ + top_p?: number; + /** + * Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. + */ + top_k?: number; + /** + * Random seed for reproducibility of the generation. + */ + seed?: number; + /** + * Penalty for repeated tokens; higher values discourage repetition. + */ + repetition_penalty?: number; + /** + * Decreases the likelihood of the model repeating the same lines verbatim. + */ + frequency_penalty?: number; + /** + * Increases the likelihood of the model introducing new topics. + */ + presence_penalty?: number; +} +interface Ai_Cf_Aisingapore_Gemma_Sea_Lion_V4_27B_It_JSON_Mode_1 { + type?: "json_object" | "json_schema"; + json_schema?: unknown; +} +interface Ai_Cf_Aisingapore_Gemma_Sea_Lion_V4_27B_It_Async_Batch { + requests: (Ai_Cf_Aisingapore_Gemma_Sea_Lion_V4_27B_It_Prompt_1 | Ai_Cf_Aisingapore_Gemma_Sea_Lion_V4_27B_It_Messages_1)[]; +} +interface Ai_Cf_Aisingapore_Gemma_Sea_Lion_V4_27B_It_Prompt_1 { + /** + * The input text prompt for the model to generate a response. + */ + prompt: string; + /** + * Name of the LoRA (Low-Rank Adaptation) model to fine-tune the base model. + */ + lora?: string; + response_format?: Ai_Cf_Aisingapore_Gemma_Sea_Lion_V4_27B_It_JSON_Mode_2; + /** + * If true, a chat template is not applied and you must adhere to the specific model's expected formatting. + */ + raw?: boolean; + /** + * If true, the response will be streamed back incrementally using SSE, Server Sent Events. + */ + stream?: boolean; + /** + * The maximum number of tokens to generate in the response. + */ + max_tokens?: number; + /** + * Controls the randomness of the output; higher values produce more random results. + */ + temperature?: number; + /** + * Adjusts the creativity of the AI's responses by controlling how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. + */ + top_p?: number; + /** + * Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. + */ + top_k?: number; + /** + * Random seed for reproducibility of the generation. + */ + seed?: number; + /** + * Penalty for repeated tokens; higher values discourage repetition. + */ + repetition_penalty?: number; + /** + * Decreases the likelihood of the model repeating the same lines verbatim. + */ + frequency_penalty?: number; + /** + * Increases the likelihood of the model introducing new topics. + */ + presence_penalty?: number; +} +interface Ai_Cf_Aisingapore_Gemma_Sea_Lion_V4_27B_It_JSON_Mode_2 { + type?: "json_object" | "json_schema"; + json_schema?: unknown; +} +interface Ai_Cf_Aisingapore_Gemma_Sea_Lion_V4_27B_It_Messages_1 { + /** + * An array of message objects representing the conversation history. + */ + messages: { + /** + * The role of the message sender (e.g., 'user', 'assistant', 'system', 'tool'). + */ + role: string; + content: string | { + /** + * Type of the content (text) + */ + type?: string; + /** + * Text content + */ + text?: string; + }[]; + }[]; + functions?: { + name: string; + code: string; + }[]; + /** + * A list of tools available for the assistant to use. + */ + tools?: ({ + /** + * The name of the tool. More descriptive the better. + */ + name: string; + /** + * A brief description of what the tool does. + */ + description: string; + /** + * Schema defining the parameters accepted by the tool. + */ + parameters: { + /** + * The type of the parameters object (usually 'object'). + */ + type: string; + /** + * List of required parameter names. + */ + required?: string[]; + /** + * Definitions of each parameter. + */ + properties: { + [k: string]: { + /** + * The data type of the parameter. + */ + type: string; + /** + * A description of the expected parameter. + */ + description: string; + }; + }; + }; + } | { + /** + * Specifies the type of tool (e.g., 'function'). + */ + type: string; + /** + * Details of the function tool. + */ + function: { + /** + * The name of the function. + */ + name: string; + /** + * A brief description of what the function does. + */ + description: string; + /** + * Schema defining the parameters accepted by the function. + */ + parameters: { + /** + * The type of the parameters object (usually 'object'). + */ + type: string; + /** + * List of required parameter names. + */ + required?: string[]; + /** + * Definitions of each parameter. + */ + properties: { + [k: string]: { + /** + * The data type of the parameter. + */ + type: string; + /** + * A description of the expected parameter. + */ + description: string; + }; + }; + }; + }; + })[]; + response_format?: Ai_Cf_Aisingapore_Gemma_Sea_Lion_V4_27B_It_JSON_Mode_3; + /** + * If true, a chat template is not applied and you must adhere to the specific model's expected formatting. + */ + raw?: boolean; + /** + * If true, the response will be streamed back incrementally using SSE, Server Sent Events. + */ + stream?: boolean; + /** + * The maximum number of tokens to generate in the response. + */ + max_tokens?: number; + /** + * Controls the randomness of the output; higher values produce more random results. + */ + temperature?: number; + /** + * Adjusts the creativity of the AI's responses by controlling how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. + */ + top_p?: number; + /** + * Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. + */ + top_k?: number; + /** + * Random seed for reproducibility of the generation. + */ + seed?: number; + /** + * Penalty for repeated tokens; higher values discourage repetition. + */ + repetition_penalty?: number; + /** + * Decreases the likelihood of the model repeating the same lines verbatim. + */ + frequency_penalty?: number; + /** + * Increases the likelihood of the model introducing new topics. + */ + presence_penalty?: number; +} +interface Ai_Cf_Aisingapore_Gemma_Sea_Lion_V4_27B_It_JSON_Mode_3 { + type?: "json_object" | "json_schema"; + json_schema?: unknown; +} +type Ai_Cf_Aisingapore_Gemma_Sea_Lion_V4_27B_It_Output = Ai_Cf_Aisingapore_Gemma_Sea_Lion_V4_27B_It_Chat_Completion_Response | Ai_Cf_Aisingapore_Gemma_Sea_Lion_V4_27B_It_Text_Completion_Response | string | Ai_Cf_Aisingapore_Gemma_Sea_Lion_V4_27B_It_AsyncResponse; +interface Ai_Cf_Aisingapore_Gemma_Sea_Lion_V4_27B_It_Chat_Completion_Response { + /** + * Unique identifier for the completion + */ + id?: string; + /** + * Object type identifier + */ + object?: "chat.completion"; + /** + * Unix timestamp of when the completion was created + */ + created?: number; + /** + * Model used for the completion + */ + model?: string; + /** + * List of completion choices + */ + choices?: { + /** + * Index of the choice in the list + */ + index?: number; + /** + * The message generated by the model + */ + message?: { + /** + * Role of the message author + */ + role: string; + /** + * The content of the message + */ + content: string; + /** + * Internal reasoning content (if available) + */ + reasoning_content?: string; + /** + * Tool calls made by the assistant + */ + tool_calls?: { + /** + * Unique identifier for the tool call + */ + id: string; + /** + * Type of tool call + */ + type: "function"; + function: { + /** + * Name of the function to call + */ + name: string; + /** + * JSON string of arguments for the function + */ + arguments: string; + }; + }[]; + }; + /** + * Reason why the model stopped generating + */ + finish_reason?: string; + /** + * Stop reason (may be null) + */ + stop_reason?: string | null; + /** + * Log probabilities (if requested) + */ + logprobs?: {} | null; + }[]; + /** + * Usage statistics for the inference request + */ + usage?: { + /** + * Total number of tokens in input + */ + prompt_tokens?: number; + /** + * Total number of tokens in output + */ + completion_tokens?: number; + /** + * Total number of input and output tokens + */ + total_tokens?: number; + }; + /** + * Log probabilities for the prompt (if requested) + */ + prompt_logprobs?: {} | null; +} +interface Ai_Cf_Aisingapore_Gemma_Sea_Lion_V4_27B_It_Text_Completion_Response { + /** + * Unique identifier for the completion + */ + id?: string; + /** + * Object type identifier + */ + object?: "text_completion"; + /** + * Unix timestamp of when the completion was created + */ + created?: number; + /** + * Model used for the completion + */ + model?: string; + /** + * List of completion choices + */ + choices?: { + /** + * Index of the choice in the list + */ + index: number; + /** + * The generated text completion + */ + text: string; + /** + * Reason why the model stopped generating + */ + finish_reason: string; + /** + * Stop reason (may be null) + */ + stop_reason?: string | null; + /** + * Log probabilities (if requested) + */ + logprobs?: {} | null; + /** + * Log probabilities for the prompt (if requested) + */ + prompt_logprobs?: {} | null; + }[]; + /** + * Usage statistics for the inference request + */ + usage?: { + /** + * Total number of tokens in input + */ + prompt_tokens?: number; + /** + * Total number of tokens in output + */ + completion_tokens?: number; + /** + * Total number of input and output tokens + */ + total_tokens?: number; + }; +} +interface Ai_Cf_Aisingapore_Gemma_Sea_Lion_V4_27B_It_AsyncResponse { + /** + * The async request id that can be used to obtain the results. + */ + request_id?: string; +} +declare abstract class Base_Ai_Cf_Aisingapore_Gemma_Sea_Lion_V4_27B_It { + inputs: Ai_Cf_Aisingapore_Gemma_Sea_Lion_V4_27B_It_Input; + postProcessedOutputs: Ai_Cf_Aisingapore_Gemma_Sea_Lion_V4_27B_It_Output; +} +interface Ai_Cf_Pfnet_Plamo_Embedding_1B_Input { + /** + * Input text to embed. Can be a single string or a list of strings. + */ + text: string | string[]; +} +interface Ai_Cf_Pfnet_Plamo_Embedding_1B_Output { + /** + * Embedding vectors, where each vector is a list of floats. + */ + data: number[][]; + /** + * Shape of the embedding data as [number_of_embeddings, embedding_dimension]. + * + * @minItems 2 + * @maxItems 2 + */ + shape: [ + number, + number + ]; +} +declare abstract class Base_Ai_Cf_Pfnet_Plamo_Embedding_1B { + inputs: Ai_Cf_Pfnet_Plamo_Embedding_1B_Input; + postProcessedOutputs: Ai_Cf_Pfnet_Plamo_Embedding_1B_Output; +} +interface Ai_Cf_Deepgram_Flux_Input { + /** + * Encoding of the audio stream. Currently only supports raw signed little-endian 16-bit PCM. + */ + encoding: "linear16"; + /** + * Sample rate of the audio stream in Hz. + */ + sample_rate: string; + /** + * End-of-turn confidence required to fire an eager end-of-turn event. When set, enables EagerEndOfTurn and TurnResumed events. Valid Values 0.3 - 0.9. + */ + eager_eot_threshold?: string; + /** + * End-of-turn confidence required to finish a turn. Valid Values 0.5 - 0.9. + */ + eot_threshold?: string; + /** + * A turn will be finished when this much time has passed after speech, regardless of EOT confidence. + */ + eot_timeout_ms?: string; + /** + * Keyterm prompting can improve recognition of specialized terminology. Pass multiple keyterm query parameters to boost multiple keyterms. + */ + keyterm?: string; + /** + * Opts out requests from the Deepgram Model Improvement Program. Refer to Deepgram Docs for pricing impacts before setting this to true. https://dpgr.am/deepgram-mip + */ + mip_opt_out?: "true" | "false"; + /** + * Label your requests for the purpose of identification during usage reporting + */ + tag?: string; +} +/** + * Output will be returned as websocket messages. + */ +interface Ai_Cf_Deepgram_Flux_Output { + /** + * The unique identifier of the request (uuid) + */ + request_id?: string; + /** + * Starts at 0 and increments for each message the server sends to the client. + */ + sequence_id?: number; + /** + * The type of event being reported. + */ + event?: "Update" | "StartOfTurn" | "EagerEndOfTurn" | "TurnResumed" | "EndOfTurn"; + /** + * The index of the current turn + */ + turn_index?: number; + /** + * Start time in seconds of the audio range that was transcribed + */ + audio_window_start?: number; + /** + * End time in seconds of the audio range that was transcribed + */ + audio_window_end?: number; + /** + * Text that was said over the course of the current turn + */ + transcript?: string; + /** + * The words in the transcript + */ + words?: { + /** + * The individual punctuated, properly-cased word from the transcript + */ + word: string; + /** + * Confidence that this word was transcribed correctly + */ + confidence: number; + }[]; + /** + * Confidence that no more speech is coming in this turn + */ + end_of_turn_confidence?: number; +} +declare abstract class Base_Ai_Cf_Deepgram_Flux { + inputs: Ai_Cf_Deepgram_Flux_Input; + postProcessedOutputs: Ai_Cf_Deepgram_Flux_Output; +} +interface Ai_Cf_Deepgram_Aura_2_En_Input { + /** + * Speaker used to produce the audio. + */ + speaker?: "amalthea" | "andromeda" | "apollo" | "arcas" | "aries" | "asteria" | "athena" | "atlas" | "aurora" | "callista" | "cora" | "cordelia" | "delia" | "draco" | "electra" | "harmonia" | "helena" | "hera" | "hermes" | "hyperion" | "iris" | "janus" | "juno" | "jupiter" | "luna" | "mars" | "minerva" | "neptune" | "odysseus" | "ophelia" | "orion" | "orpheus" | "pandora" | "phoebe" | "pluto" | "saturn" | "thalia" | "theia" | "vesta" | "zeus"; + /** + * Encoding of the output audio. + */ + encoding?: "linear16" | "flac" | "mulaw" | "alaw" | "mp3" | "opus" | "aac"; + /** + * Container specifies the file format wrapper for the output audio. The available options depend on the encoding type.. + */ + container?: "none" | "wav" | "ogg"; + /** + * The text content to be converted to speech + */ + text: string; + /** + * Sample Rate specifies the sample rate for the output audio. Based on the encoding, different sample rates are supported. For some encodings, the sample rate is not configurable + */ + sample_rate?: number; + /** + * The bitrate of the audio in bits per second. Choose from predefined ranges or specific values based on the encoding type. + */ + bit_rate?: number; +} +/** + * The generated audio in MP3 format + */ +type Ai_Cf_Deepgram_Aura_2_En_Output = string; +declare abstract class Base_Ai_Cf_Deepgram_Aura_2_En { + inputs: Ai_Cf_Deepgram_Aura_2_En_Input; + postProcessedOutputs: Ai_Cf_Deepgram_Aura_2_En_Output; +} +interface Ai_Cf_Deepgram_Aura_2_Es_Input { + /** + * Speaker used to produce the audio. + */ + speaker?: "sirio" | "nestor" | "carina" | "celeste" | "alvaro" | "diana" | "aquila" | "selena" | "estrella" | "javier"; + /** + * Encoding of the output audio. + */ + encoding?: "linear16" | "flac" | "mulaw" | "alaw" | "mp3" | "opus" | "aac"; + /** + * Container specifies the file format wrapper for the output audio. The available options depend on the encoding type.. + */ + container?: "none" | "wav" | "ogg"; + /** + * The text content to be converted to speech + */ + text: string; + /** + * Sample Rate specifies the sample rate for the output audio. Based on the encoding, different sample rates are supported. For some encodings, the sample rate is not configurable + */ + sample_rate?: number; + /** + * The bitrate of the audio in bits per second. Choose from predefined ranges or specific values based on the encoding type. + */ + bit_rate?: number; +} +/** + * The generated audio in MP3 format + */ +type Ai_Cf_Deepgram_Aura_2_Es_Output = string; +declare abstract class Base_Ai_Cf_Deepgram_Aura_2_Es { + inputs: Ai_Cf_Deepgram_Aura_2_Es_Input; + postProcessedOutputs: Ai_Cf_Deepgram_Aura_2_Es_Output; +} +interface Ai_Cf_Black_Forest_Labs_Flux_2_Dev_Input { + multipart: { + body?: object; + contentType?: string; + }; +} +interface Ai_Cf_Black_Forest_Labs_Flux_2_Dev_Output { + /** + * Generated image as Base64 string. + */ + image?: string; +} +declare abstract class Base_Ai_Cf_Black_Forest_Labs_Flux_2_Dev { + inputs: Ai_Cf_Black_Forest_Labs_Flux_2_Dev_Input; + postProcessedOutputs: Ai_Cf_Black_Forest_Labs_Flux_2_Dev_Output; +} +interface Ai_Cf_Black_Forest_Labs_Flux_2_Klein_4B_Input { + multipart: { + body?: object; + contentType?: string; + }; +} +interface Ai_Cf_Black_Forest_Labs_Flux_2_Klein_4B_Output { + /** + * Generated image as Base64 string. + */ + image?: string; +} +declare abstract class Base_Ai_Cf_Black_Forest_Labs_Flux_2_Klein_4B { + inputs: Ai_Cf_Black_Forest_Labs_Flux_2_Klein_4B_Input; + postProcessedOutputs: Ai_Cf_Black_Forest_Labs_Flux_2_Klein_4B_Output; +} +interface Ai_Cf_Black_Forest_Labs_Flux_2_Klein_9B_Input { + multipart: { + body?: object; + contentType?: string; + }; +} +interface Ai_Cf_Black_Forest_Labs_Flux_2_Klein_9B_Output { + /** + * Generated image as Base64 string. + */ + image?: string; +} +declare abstract class Base_Ai_Cf_Black_Forest_Labs_Flux_2_Klein_9B { + inputs: Ai_Cf_Black_Forest_Labs_Flux_2_Klein_9B_Input; + postProcessedOutputs: Ai_Cf_Black_Forest_Labs_Flux_2_Klein_9B_Output; +} +declare abstract class Base_Ai_Cf_Zai_Org_Glm_4_7_Flash { + inputs: Omit & { + chat_template_kwargs?: Omit & { + /** + * Whether to enable reasoning for this model. This model has no reasoning effort levels. + * + * @default true + */ + enable_thinking?: boolean; + }; + }; + postProcessedOutputs: ChatCompletionsOutput; +} +declare abstract class Base_Ai_Cf_Moonshotai_Kimi_K2_5 { + inputs: ChatCompletionsInput; + postProcessedOutputs: ChatCompletionsOutput; +} +declare abstract class Base_Ai_Cf_Moonshotai_Kimi_K2_6 { + inputs: Omit & { + /** + * Reasoning effort. Supported levels: high, none. Compatibility aliases (accepted by the API, not by these types): low maps to high; medium maps to high; max maps to high. + * + * @default "high" + */ + reasoning_effort?: "high" | "none" | null; + chat_template_kwargs?: Omit & { + /** + * Whether to enable reasoning for this model. + * + * @default true + */ + enable_thinking?: boolean; + }; + }; + postProcessedOutputs: ChatCompletionsOutput; +} +type Ai_Cf_Nvidia_Nemotron_3_120B_A12B_Input = Omit & { + /** + * ID of the model to use (for example, '@cf/nvidia/nemotron-3-120b-a12b'). + */ + model?: ChatCompletionsInput["model"]; + /** + * The maximum number of tokens to generate. + */ + max_tokens?: ChatCompletionsInput["max_tokens"]; + /** + * Set of key-value pairs that can be attached to the object. + */ + metadata?: ChatCompletionsInput["metadata"]; + /** + * Output types requested from the model. + */ + modalities?: ChatCompletionsInput["modalities"]; + /** + * Nemotron chat-template controls for normal reasoning, low-effort reasoning, and non-reasoning responses. + */ + chat_template_kwargs?: { + /** + * Whether to enable reasoning. Reasoning is enabled by default. + */ + enable_thinking?: boolean; + /** + * When reasoning is enabled, use Nemotron's low-effort reasoning mode, which uses significantly fewer reasoning tokens. + */ + low_effort?: boolean; + /** + * For coding agent use, Nvidia suggests setting force_nonempty_content=true + */ + force_nonempty_content?: boolean; + }; + /** + * Whether to store the output for model distillation or evaluation. + * + * @default false + */ + store?: ChatCompletionsInput["store"]; +}; +declare abstract class Base_Ai_Cf_Nvidia_Nemotron_3_120B_A12B { + inputs: Ai_Cf_Nvidia_Nemotron_3_120B_A12B_Input; + postProcessedOutputs: ChatCompletionsOutput; +} +type Ai_Cf_Google_Gemma_4_26B_A4B_It_Input = Omit & { + chat_template_kwargs?: Omit & { + /** + * Whether to enable reasoning for this model. This model has no reasoning effort levels. + * + * @default true + */ + enable_thinking?: boolean; + }; +} & { + /** + * @default false + */ + skip_special_tokens?: boolean; +}; +declare abstract class Base_Ai_Cf_Google_Gemma_4_26B_A4B_It { + inputs: Ai_Cf_Google_Gemma_4_26B_A4B_It_Input; + postProcessedOutputs: ChatCompletionsOutput; +} +/** @deprecated Use Base_Ai_Cf_Google_Gemma_4_26B_A4B_It. */ +declare abstract class Base_Ai_Cf_Google_Gemma_4_26B_A4B_IT extends Base_Ai_Cf_Google_Gemma_4_26B_A4B_It { +} +type Ai_Cf_Nvidia_Nemotron_Speech_Streaming_En_0_6B_Input = { + /** + * readable stream with audio data and content-type specified for that data + */ + audio: { + body: object; + contentType: string; + }; +} | { + /** + * base64 encoded audio data + */ + audio: string; + encoding?: "wav" | "flac" | "ogg" | "linear16"; + sample_rate?: number; + channels?: number; +}; +interface Ai_Cf_Nvidia_Nemotron_Speech_Streaming_En_0_6B_Output { + text?: string; + duration?: number; +} +declare abstract class Base_Ai_Cf_Nvidia_Nemotron_Speech_Streaming_En_0_6B { + inputs: Ai_Cf_Nvidia_Nemotron_Speech_Streaming_En_0_6B_Input; + postProcessedOutputs: Ai_Cf_Nvidia_Nemotron_Speech_Streaming_En_0_6B_Output; +} +declare abstract class Base_Ai_Cf_Moonshotai_Kimi_K2_7_Code { + inputs: Omit & { + chat_template_kwargs?: Omit & { + /** + * Reasoning is always enabled for this model and cannot be disabled. This model has no reasoning effort levels. + * + * @default true + */ + enable_thinking?: true; + }; + }; + postProcessedOutputs: ChatCompletionsOutput; +} +declare abstract class Base_Ai_Cf_Zai_Org_Glm_5_2 { + inputs: Omit & { + /** + * Reasoning effort. Supported levels: max, high, none. Compatibility aliases (accepted by the API, not by these types): low maps to high; medium maps to high; xhigh maps to max; minimal maps to none. + * + * @default "max" + */ + reasoning_effort?: "max" | "high" | "none" | null; + chat_template_kwargs?: Omit & { + /** + * Whether to enable reasoning for this model. + * + * @default true + */ + enable_thinking?: boolean; + }; + }; + postProcessedOutputs: ChatCompletionsOutput; +} +interface Ai_Cf_Moondream_Moondream3_1_9B_A2B_Input { + /** + * Which Moondream skill to run. + */ + task?: "query" | "caption" | "point" | "detect"; + /** + * Input image as a public HTTPS URL or base64 data URI. Optional for `query`; required for `caption`, `point`, and `detect`. + */ + image?: string; + /** + * Question for the `query` task. + */ + question?: string; + /** + * Caption length for the `caption` task. + */ + caption_length?: "short" | "normal" | "long"; + /** + * Object phrase to locate for `point` and `detect` tasks (e.g. 'person wearing a red shirt'). + */ + target?: string; + /** + * Enable reasoning trace for the `query` task. + */ + reasoning?: boolean; + /** + * Sampling temperature. + */ + temperature?: number; + /** + * Top-p (nucleus) sampling. + */ + top_p?: number; + /** + * Max tokens to generate for `query` and `caption`. + */ + max_tokens?: number; + /** + * Max objects to return for `point` and `detect`. + */ + max_objects?: number; + /** + * Return incremental tokens for `query` and `caption`. `point` and `detect` do not support streaming. + */ + stream?: boolean; +} +interface Ai_Cf_Moondream_Moondream3_1_9B_A2B_Output { + /** + * Reason the generation finished. + */ + finish_reason: string; + metrics: { + /** + * Number of input tokens consumed. + */ + input_tokens: number; + /** + * Number of output tokens generated. + */ + output_tokens: number; + /** + * Prefill time in milliseconds. + */ + prefill_time_ms: number; + /** + * Decode time in milliseconds. + */ + decode_time_ms: number; + /** + * Time to first token in milliseconds. + */ + ttft_ms: number; + }; + /** + * Answer text for the `query` task. Null for other tasks. + */ + answer?: string; + /** + * Caption text for the `caption` task. Null for other tasks. + */ + caption?: string; + /** + * Located points for the `point` task. Null for other tasks. + */ + points?: { + /** + * X coordinate. + */ + x: number; + /** + * Y coordinate. + */ + y: number; + }[]; + /** + * Detected bounding boxes for the `detect` task. Null for other tasks. + */ + objects?: { + /** + * Minimum X coordinate. + */ + x_min: number; + /** + * Minimum Y coordinate. + */ + y_min: number; + /** + * Maximum X coordinate. + */ + x_max: number; + /** + * Maximum Y coordinate. + */ + y_max: number; + }[]; + /** + * Reasoning trace for the `query` task when reasoning=true. Null otherwise. + */ + reasoning?: { + /** + * Reasoning text. + */ + text: string; + /** + * Grounding information. + */ + grounding?: {}[]; + }; +} +declare abstract class Base_Ai_Cf_Moondream_Moondream3_1_9B_A2B { + inputs: Ai_Cf_Moondream_Moondream3_1_9B_A2B_Input; + postProcessedOutputs: Ai_Cf_Moondream_Moondream3_1_9B_A2B_Output; +} +declare abstract class Base_Ai_Cf_Deepseek_Ai_Deepseek_V4_Flash_0731 { + inputs: Omit & { + /** + * Reasoning effort. Supported levels: max, high, low, none. Compatibility aliases (accepted by the API, not by these types): minimal maps to low; medium maps to high; xhigh maps to high. + * + * @default "high" + */ + reasoning_effort?: "max" | "high" | "low" | "none" | null; + chat_template_kwargs?: Omit & { + /** + * Whether to enable reasoning for this model. + * + * @default true + */ + enable_thinking?: boolean; + }; + }; + postProcessedOutputs: ChatCompletionsOutput; +} +declare abstract class Base_Ai_Cf_Deepseek_Ai_Deepseek_V4_Pro_0813 { + inputs: Omit & { + /** + * Reasoning effort. Supported levels: max, high, low, none. Compatibility aliases (accepted by the API, not by these types): minimal maps to low; medium maps to high; xhigh maps to high. + * + * @default "high" + */ + reasoning_effort?: "max" | "high" | "low" | "none" | null; + chat_template_kwargs?: Omit & { + /** + * Whether to enable reasoning for this model. + * + * @default true + */ + enable_thinking?: boolean; + }; + }; + postProcessedOutputs: ChatCompletionsOutput; +} +declare abstract class Base_Ai_Cf_Qwen_Qwen3_8_27B { + inputs: Omit & { + /** + * Reasoning effort. Supported levels: low, medium, xhigh. + * + * @default "xhigh" + */ + reasoning_effort?: "low" | "medium" | "xhigh" | null; + chat_template_kwargs?: Omit & { + /** + * Whether to enable reasoning for this model. + * + * @default true + */ + enable_thinking?: boolean; + }; + }; + postProcessedOutputs: ChatCompletionsOutput; +} +declare abstract class Base_Ai_Cf_Zai_Org_Glm_5_3 { + inputs: Omit & { + /** + * Reasoning effort. Supported levels: max, high, low. Reasoning cannot be disabled. Compatibility aliases (accepted by the API, not by these types): none maps to max; minimal maps to max; medium maps to max; xhigh maps to max. + * + * @default "max" + */ + reasoning_effort?: "max" | "high" | "low" | null; + chat_template_kwargs?: Omit & { + /** + * Reasoning is always enabled for this model and cannot be disabled. + * + * @default true + */ + enable_thinking?: true; + }; + }; + postProcessedOutputs: ChatCompletionsOutput; +} +declare abstract class Base_Ai_Cf_Zai_Org_Glm_5_3_Flash { + inputs: Omit & { + /** + * Reasoning effort. Supported levels: max, high, low. Reasoning cannot be disabled. Compatibility aliases (accepted by the API, not by these types): none maps to max; minimal maps to max; medium maps to max; xhigh maps to max. + * + * @default "max" + */ + reasoning_effort?: "max" | "high" | "low" | null; + chat_template_kwargs?: Omit & { + /** + * Reasoning is always enabled for this model and cannot be disabled. + * + * @default true + */ + enable_thinking?: true; + }; + }; + postProcessedOutputs: ChatCompletionsOutput; +} +interface AiModels { + "@cf/huggingface/distilbert-sst-2-int8": BaseAiTextClassification; + "@cf/stabilityai/stable-diffusion-xl-base-1.0": BaseAiTextToImage; + "@cf/runwayml/stable-diffusion-v1-5-inpainting": BaseAiTextToImage; + "@cf/lykon/dreamshaper-8-lcm": BaseAiTextToImage; + "@cf/bytedance/stable-diffusion-xl-lightning": BaseAiTextToImage; + "@cf/myshell-ai/melotts": BaseAiTextToSpeech; + "@cf/google/embeddinggemma-300m": BaseAiTextEmbeddings; + "@cf/microsoft/resnet-50": BaseAiImageClassification; + "@cf/meta/llama-2-7b-chat-int8": BaseAiTextGeneration; + "@cf/mistral/mistral-7b-instruct-v0.1": BaseAiTextGeneration; + "@cf/meta/llama-2-7b-chat-fp16": BaseAiTextGeneration; + "@hf/thebloke/llama-2-13b-chat-awq": BaseAiTextGeneration; + "@hf/thebloke/mistral-7b-instruct-v0.1-awq": BaseAiTextGeneration; + "@hf/thebloke/zephyr-7b-beta-awq": BaseAiTextGeneration; + "@hf/thebloke/openhermes-2.5-mistral-7b-awq": BaseAiTextGeneration; + "@hf/thebloke/neural-chat-7b-v3-1-awq": BaseAiTextGeneration; + "@hf/thebloke/deepseek-coder-6.7b-base-awq": BaseAiTextGeneration; + "@hf/thebloke/deepseek-coder-6.7b-instruct-awq": BaseAiTextGeneration; + "@cf/deepseek-ai/deepseek-math-7b-instruct": BaseAiTextGeneration; + "@cf/defog/sqlcoder-7b-2": BaseAiTextGeneration; + "@cf/openchat/openchat-3.5-0106": BaseAiTextGeneration; + "@cf/tiiuae/falcon-7b-instruct": BaseAiTextGeneration; + "@cf/thebloke/discolm-german-7b-v1-awq": BaseAiTextGeneration; + "@cf/qwen/qwen1.5-0.5b-chat": BaseAiTextGeneration; + "@cf/qwen/qwen1.5-7b-chat-awq": BaseAiTextGeneration; + "@cf/qwen/qwen1.5-14b-chat-awq": BaseAiTextGeneration; + "@cf/tinyllama/tinyllama-1.1b-chat-v1.0": BaseAiTextGeneration; + "@cf/microsoft/phi-2": BaseAiTextGeneration; + "@cf/qwen/qwen1.5-1.8b-chat": BaseAiTextGeneration; + "@cf/mistral/mistral-7b-instruct-v0.2-lora": BaseAiTextGeneration; + "@hf/nousresearch/hermes-2-pro-mistral-7b": BaseAiTextGeneration; + "@hf/nexusflow/starling-lm-7b-beta": BaseAiTextGeneration; + "@hf/google/gemma-7b-it": BaseAiTextGeneration; + "@cf/meta-llama/llama-2-7b-chat-hf-lora": BaseAiTextGeneration; + "@cf/google/gemma-2b-it-lora": BaseAiTextGeneration; + "@cf/google/gemma-7b-it-lora": BaseAiTextGeneration; + "@hf/mistral/mistral-7b-instruct-v0.2": BaseAiTextGeneration; + "@cf/meta/llama-3-8b-instruct": BaseAiTextGeneration; + "@cf/fblgit/una-cybertron-7b-v2-bf16": BaseAiTextGeneration; + "@cf/meta/llama-3-8b-instruct-awq": BaseAiTextGeneration; + "@cf/meta/llama-3.1-8b-instruct-fp8": BaseAiTextGeneration; + "@cf/meta/llama-3.1-8b-instruct-awq": BaseAiTextGeneration; + "@cf/meta/llama-3.2-3b-instruct": BaseAiTextGeneration; + "@cf/meta/llama-3.2-1b-instruct": BaseAiTextGeneration; + "@cf/deepseek-ai/deepseek-r1-distill-qwen-32b": BaseAiTextGeneration; + "@cf/ibm-granite/granite-4.0-h-micro": BaseAiTextGeneration; + "@cf/facebook/bart-large-cnn": BaseAiSummarization; + "@cf/llava-hf/llava-1.5-7b-hf": BaseAiImageToText; + "@cf/baai/bge-base-en-v1.5": Base_Ai_Cf_Baai_Bge_Base_En_V1_5; + "@cf/openai/whisper": Base_Ai_Cf_Openai_Whisper; + "@cf/meta/m2m100-1.2b": Base_Ai_Cf_Meta_M2M100_1_2B; + "@cf/baai/bge-small-en-v1.5": Base_Ai_Cf_Baai_Bge_Small_En_V1_5; + "@cf/baai/bge-large-en-v1.5": Base_Ai_Cf_Baai_Bge_Large_En_V1_5; + "@cf/unum/uform-gen2-qwen-500m": Base_Ai_Cf_Unum_Uform_Gen2_Qwen_500M; + "@cf/openai/whisper-tiny-en": Base_Ai_Cf_Openai_Whisper_Tiny_En; + "@cf/openai/whisper-large-v3-turbo": Base_Ai_Cf_Openai_Whisper_Large_V3_Turbo; + "@cf/baai/bge-m3": Base_Ai_Cf_Baai_Bge_M3; + "@cf/black-forest-labs/flux-1-schnell": Base_Ai_Cf_Black_Forest_Labs_Flux_1_Schnell; + "@cf/meta/llama-3.2-11b-vision-instruct": Base_Ai_Cf_Meta_Llama_3_2_11B_Vision_Instruct; + "@cf/meta/llama-3.3-70b-instruct-fp8-fast": Base_Ai_Cf_Meta_Llama_3_3_70B_Instruct_Fp8_Fast; + "@cf/meta/llama-guard-3-8b": Base_Ai_Cf_Meta_Llama_Guard_3_8B; + "@cf/baai/bge-reranker-base": Base_Ai_Cf_Baai_Bge_Reranker_Base; + "@cf/qwen/qwen2.5-coder-32b-instruct": Base_Ai_Cf_Qwen_Qwen2_5_Coder_32B_Instruct; + "@cf/qwen/qwq-32b": Base_Ai_Cf_Qwen_Qwq_32B; + "@cf/mistralai/mistral-small-3.1-24b-instruct": Base_Ai_Cf_Mistralai_Mistral_Small_3_1_24B_Instruct; + "@cf/google/gemma-3-12b-it": Base_Ai_Cf_Google_Gemma_3_12B_It; + "@cf/meta/llama-4-scout-17b-16e-instruct": Base_Ai_Cf_Meta_Llama_4_Scout_17B_16E_Instruct; + "@cf/qwen/qwen3-30b-a3b-fp8": Base_Ai_Cf_Qwen_Qwen3_30B_A3B_Fp8; + "@cf/deepgram/nova-3": Base_Ai_Cf_Deepgram_Nova_3; + "@cf/qwen/qwen3-embedding-0.6b": Base_Ai_Cf_Qwen_Qwen3_Embedding_0_6B; + "@cf/pipecat-ai/smart-turn-v2": Base_Ai_Cf_Pipecat_Ai_Smart_Turn_V2; + "@cf/openai/gpt-oss-120b": Base_Ai_Cf_Openai_Gpt_Oss_120B; + "@cf/openai/gpt-oss-20b": Base_Ai_Cf_Openai_Gpt_Oss_20B; + "@cf/leonardo/phoenix-1.0": Base_Ai_Cf_Leonardo_Phoenix_1_0; + "@cf/leonardo/lucid-origin": Base_Ai_Cf_Leonardo_Lucid_Origin; + "@cf/deepgram/aura-1": Base_Ai_Cf_Deepgram_Aura_1; + "@cf/ai4bharat/indictrans2-en-indic-1B": Base_Ai_Cf_Ai4Bharat_Indictrans2_En_Indic_1B; + "@cf/aisingapore/gemma-sea-lion-v4-27b-it": Base_Ai_Cf_Aisingapore_Gemma_Sea_Lion_V4_27B_It; + "@cf/pfnet/plamo-embedding-1b": Base_Ai_Cf_Pfnet_Plamo_Embedding_1B; + "@cf/deepgram/flux": Base_Ai_Cf_Deepgram_Flux; + "@cf/deepgram/aura-2-en": Base_Ai_Cf_Deepgram_Aura_2_En; + "@cf/deepgram/aura-2-es": Base_Ai_Cf_Deepgram_Aura_2_Es; + "@cf/black-forest-labs/flux-2-dev": Base_Ai_Cf_Black_Forest_Labs_Flux_2_Dev; + "@cf/black-forest-labs/flux-2-klein-4b": Base_Ai_Cf_Black_Forest_Labs_Flux_2_Klein_4B; + "@cf/black-forest-labs/flux-2-klein-9b": Base_Ai_Cf_Black_Forest_Labs_Flux_2_Klein_9B; + "@cf/zai-org/glm-4.7-flash": Base_Ai_Cf_Zai_Org_Glm_4_7_Flash; + "@cf/moonshotai/kimi-k2.5": Base_Ai_Cf_Moonshotai_Kimi_K2_5; + "@cf/moonshotai/kimi-k2.6": Base_Ai_Cf_Moonshotai_Kimi_K2_6; + "@cf/nvidia/nemotron-3-120b-a12b": Base_Ai_Cf_Nvidia_Nemotron_3_120B_A12B; + "@cf/google/gemma-4-26b-a4b-it": Base_Ai_Cf_Google_Gemma_4_26B_A4B_It; + "@cf/nvidia/nemotron-speech-streaming-en-0.6b": Base_Ai_Cf_Nvidia_Nemotron_Speech_Streaming_En_0_6B; + "@cf/moonshotai/kimi-k2.7-code": Base_Ai_Cf_Moonshotai_Kimi_K2_7_Code; + "@cf/zai-org/glm-5.2": Base_Ai_Cf_Zai_Org_Glm_5_2; + "@cf/moondream/moondream3.1-9B-A2B": Base_Ai_Cf_Moondream_Moondream3_1_9B_A2B; + "@cf/deepseek-ai/deepseek-v4-flash-0731": Base_Ai_Cf_Deepseek_Ai_Deepseek_V4_Flash_0731; + "@cf/deepseek-ai/deepseek-v4-pro-0813": Base_Ai_Cf_Deepseek_Ai_Deepseek_V4_Pro_0813; + "@cf/qwen/qwen3.8-27b": Base_Ai_Cf_Qwen_Qwen3_8_27B; + "@cf/zai-org/glm-5.3": Base_Ai_Cf_Zai_Org_Glm_5_3; + "@cf/zai-org/glm-5.3-flash": Base_Ai_Cf_Zai_Org_Glm_5_3_Flash; +} +type AiOptions = { + /** + * Send requests as an asynchronous batch job, only works for supported models + * https://developers.cloudflare.com/workers-ai/features/batch-api + */ + queueRequest?: boolean; + /** + * Establish websocket connections, only works for supported models + */ + websocket?: boolean; + /** + * Tag your requests to group and view them in Cloudflare dashboard. + * + * Rules: + * Tags must only contain letters, numbers, and the symbols: : - . / @ + * Each tag can have maximum 50 characters. + * Maximum 5 tags are allowed each request. + * Duplicate tags will removed. + */ + tags?: string[]; + gateway?: GatewayOptions; + returnRawResponse?: boolean; + prefix?: string; + extraHeaders?: object; + signal?: AbortSignal; +}; +type AiModelsSearchParams = { + author?: string; + hide_experimental?: boolean; + page?: number; + per_page?: number; + search?: string; + source?: number; + task?: string; +}; +type AiModelsSearchObject = { + id: string; + source: number; + name: string; + description: string; + task: { + id: string; + name: string; + description: string; + }; + tags: string[]; + properties: { + property_id: string; + value: string; + }[]; +}; +type ChatCompletionsBase = ChatCompletionsMessagesInput; +type ChatCompletionsInput = ChatCompletionsMessagesInput; +interface InferenceUpstreamError extends Error { +} +interface AiInternalError extends Error { +} +type AiModelListType = Record; +type AiAsyncBatchResponse = { + request_id: string; +}; +type AiWebSearchRequest = { + /** AI Gateway configuration used for this request. */ + gatewayId: string; + /** Search query. */ + query: string; + /** Maximum number of results. Defaults to 10 and is capped at 20. */ + limit?: number; + /** Optional BYOK web-search provider configured on the gateway. */ + provider?: string; + /** Optional BYOK key alias. Defaults to `default`. */ + byokAlias?: string; +}; +declare abstract class Ai { + aiGatewayLogId: string | null; + gateway(gatewayId: string): AiGateway; + websearch(request: AiWebSearchRequest): Promise; + /** + * @deprecated Use the standalone `ai_search_namespaces` or `ai_search` Workers bindings instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + */ + aiSearch(): AiSearchNamespace; + /** + * @deprecated AutoRAG has been replaced by AI Search. + * Use the standalone `ai_search_namespaces` or `ai_search` Workers bindings instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + * + * @param autoragId Instance ID + */ + autorag(autoragId: string): AutoRAG; + // Batch request + run(model: Name, inputs: { + requests: AiModelList[Name]['inputs'][]; + }, options: AiOptions & { + queueRequest: true; + }): Promise; + // Raw response + run(model: Name, inputs: AiModelList[Name]['inputs'], options: AiOptions & { + returnRawResponse: true; + }): Promise; + // WebSocket + run(model: Name, inputs: AiModelList[Name]['inputs'], options: AiOptions & { + websocket: true; + }): Promise; + // Streaming + run(model: Name, inputs: AiModelList[Name]['inputs'] & { + stream: true; + }, options?: AiOptions): Promise; + // Normal (default) - known model + run(model: Name, inputs: AiModelList[Name]['inputs'], options?: AiOptions): Promise; + // Unknown model (fallback). + // + // The `Exclude<..., keyof AiModelList>` constraint forces TypeScript to + // route any model name that is a literal key of `AiModelList` to one of + // the known-model overloads above (so input/output mismatches surface as + // type errors rather than silently falling back to `Record`). + // Names that aren't in `AiModelList` — e.g. third-party gateway models + // like `"google/nano-banana"` — still hit this overload. + run(model: Model extends keyof AiModelList ? never : Model, inputs: Record, options?: AiOptions): Promise>; + models(params?: AiModelsSearchParams): Promise; + toMarkdown(): ToMarkdownService; + toMarkdown(files: MarkdownDocument[], options?: ConversionRequestOptions): Promise; + toMarkdown(files: MarkdownDocument, options?: ConversionRequestOptions): Promise; +} +type GatewayRetries = { + maxAttempts?: 1 | 2 | 3 | 4 | 5; + retryDelayMs?: number; + backoff?: 'constant' | 'linear' | 'exponential'; +}; +type GatewayOptions = { + id: string; + cacheKey?: string; + cacheTtl?: number; + skipCache?: boolean; + metadata?: Record; + collectLog?: boolean; + eventId?: string; + requestTimeoutMs?: number; + retries?: GatewayRetries; +}; +type UniversalGatewayOptions = Exclude & { + /** + ** @deprecated + */ + id?: string; +}; +type AiGatewayPatchLog = { + score?: number | null; + feedback?: -1 | 1 | null; + metadata?: Record | null; +}; +type AiGatewayLog = { + id: string; + provider: string; + model: string; + model_type?: string; + path: string; + duration: number; + request_type?: string; + request_content_type?: string; + status_code: number; + response_content_type?: string; + success: boolean; + cached: boolean; + tokens_in?: number; + tokens_out?: number; + metadata?: Record; + step?: number; + cost?: number; + custom_cost?: boolean; + request_size: number; + request_head?: string; + request_head_complete: boolean; + response_size: number; + response_head?: string; + response_head_complete: boolean; + created_at: Date; +}; +type AIGatewayProviders = 'workers-ai' | 'anthropic' | 'aws-bedrock' | 'azure-openai' | 'google-vertex-ai' | 'huggingface' | 'openai' | 'perplexity-ai' | 'replicate' | 'groq' | 'cohere' | 'google-ai-studio' | 'mistral' | 'grok' | 'openrouter' | 'deepseek' | 'cerebras' | 'cartesia' | 'elevenlabs' | 'adobe-firefly'; +type AIGatewayHeaders = { + 'cf-aig-metadata': Record | string; + 'cf-aig-custom-cost': { + per_token_in?: number; + per_token_out?: number; + } | { + total_cost?: number; + } | string; + 'cf-aig-cache-ttl': number | string; + 'cf-aig-skip-cache': boolean | string; + 'cf-aig-cache-key': string; + 'cf-aig-event-id': string; + 'cf-aig-request-timeout': number | string; + 'cf-aig-max-attempts': number | string; + 'cf-aig-retry-delay': number | string; + 'cf-aig-backoff': string; + 'cf-aig-collect-log': boolean | string; + Authorization: string; + 'Content-Type': string; + [key: string]: string | number | boolean | object; +}; +type AIGatewayUniversalRequest = { + provider: AIGatewayProviders | string; // eslint-disable-line + endpoint: string; + headers: Partial; + query: unknown; +}; +interface AiGatewayInternalError extends Error { +} +interface AiGatewayLogNotFound extends Error { +} +declare abstract class AiGateway { + patchLog(logId: string, data: AiGatewayPatchLog): Promise; + getLog(logId: string): Promise; + run(data: AIGatewayUniversalRequest | AIGatewayUniversalRequest[], options?: { + gateway?: UniversalGatewayOptions; + extraHeaders?: object; + signal?: AbortSignal; + }): Promise; + getUrl(provider?: AIGatewayProviders | string): Promise; // eslint-disable-line +} +/** A parameter accepted by an Analytics SQL query. */ +type AnalyticsSQLParameter = string | number | boolean | null; +/** An Analytics SQL query and its optional positional or named parameters. */ +interface AnalyticsSQLQuery { + query: string; + params?: readonly AnalyticsSQLParameter[] | Readonly>; +} +/** Execution statistics returned by Analytics SQL. */ +interface AnalyticsSQLStatistics { + elapsed_ms: number; + rows_read: number; + bytes_read: number; +} +/** The rows and execution statistics returned by an Analytics SQL query. */ +interface AnalyticsSQLResult = Record> { + data: T[]; + rows: number; + statistics: AnalyticsSQLStatistics; +} +/** An Analytics SQL binding. */ +interface AnalyticsSQLBinding { + query = Record>(request: AnalyticsSQLQuery): Promise>; +} +// Copyright (c) 2022-2025 Cloudflare, Inc. +// Licensed under the Apache 2.0 license found in the LICENSE file or at: +// https://opensource.org/licenses/Apache-2.0 +/** + * Artifacts — Git-compatible file storage on Cloudflare Workers. + * + * Provides programmatic access to create, manage, and fork repositories, + * and to issue and revoke scoped access tokens. + */ +/** Information about a repository. */ +interface ArtifactsRepoInfo { + /** Unique repository ID. */ + id: string; + /** Repository name. */ + name: string; + /** Repository description, or null if not set. */ + description: string | null; + /** Default branch name (e.g. "main"). */ + defaultBranch: string; + /** ISO 8601 creation timestamp. */ + createdAt: string; + /** ISO 8601 last-updated timestamp. */ + updatedAt: string; + /** ISO 8601 timestamp of the last push, or null if never pushed. */ + lastPushAt: string | null; + /** Fork source (e.g. "github:owner/repo", "artifacts:namespace/repo"), or null if not a fork. */ + source: string | null; + /** Whether the repository is read-only. */ + readOnly: boolean; + /** HTTPS git remote URL. */ + remote: string; +} +/** Result of creating a repository — includes the initial access token. */ +interface ArtifactsCreateRepoResult { + /** Unique repository ID. */ + id: string; + /** Repository name. */ + name: string; + /** Repository description, or null if not set. */ + description: string | null; + /** Default branch name. */ + defaultBranch: string; + /** HTTPS git remote URL. */ + remote: string; + /** Plaintext access token (only returned at creation time). */ + token: string; + /** ISO 8601 token expiry timestamp. */ + tokenExpiresAt: string; +} +/** Paginated list of repositories. */ +interface ArtifactsRepoListResult { + /** Repositories in this page (without the `remote` field). */ + repos: Omit[]; + /** Total number of repositories in the namespace. */ + total: number; + /** Cursor for the next page, if there are more results. */ + cursor?: string; +} +/** Result of creating an access token. */ +interface ArtifactsCreateTokenResult { + /** Unique token ID. */ + id: string; + /** Plaintext token (only returned at creation time). */ + plaintext: string; + /** Token scope: "read" or "write". */ + scope: 'read' | 'write'; + /** ISO 8601 token expiry timestamp. */ + expiresAt: string; +} +/** Token metadata (no plaintext). */ +interface ArtifactsTokenInfo { + /** Unique token ID. */ + id: string; + /** Token scope: "read" or "write". */ + scope: 'read' | 'write'; + /** Token state: "active", "expired", or "revoked". */ + state: 'active' | 'expired' | 'revoked'; + /** ISO 8601 creation timestamp. */ + createdAt: string; + /** ISO 8601 expiry timestamp. */ + expiresAt: string; +} +/** Paginated list of tokens for a repository. */ +interface ArtifactsTokenListResult { + /** Tokens in this page. */ + tokens: ArtifactsTokenInfo[]; + /** Total number of tokens for the repository. */ + total: number; +} +/** + * Handle for a single repository. Returned by Artifacts.get(). + * + * Methods may throw `ArtifactsError` with code `INTERNAL_ERROR` if an unexpected service error occurs. + */ +interface ArtifactsRepo extends ArtifactsRepoInfo { + /** + * Create an access token for this repo. + * @param scope Token scope: "write" (default) or "read". + * @param ttl Time-to-live in seconds (default 86400, min 60, max 31536000). + * @throws {ArtifactsError} with code `INVALID_TTL` if ttl is out of range. + */ + createToken(scope?: 'write' | 'read', ttl?: number): Promise; + /** List tokens for this repo (metadata only, no plaintext). */ + listTokens(): Promise; + /** + * Revoke a token by plaintext or ID. + * @param tokenOrId Plaintext token or token ID. + * @returns true if revoked, false if not found. + * @throws {ArtifactsError} with code `INVALID_INPUT` if tokenOrId is empty. + */ + revokeToken(tokenOrId: string): Promise; + // ── Fork ── + /** + * Fork this repo to a new repo. + * @param name Target repository name. + * @param opts Optional: description, readOnly flag, defaultBranchOnly (default true). + * @throws {ArtifactsError} with code `INVALID_REPO_NAME` if name is invalid. + * @throws {ArtifactsError} with code `ALREADY_EXISTS` if the target repo already exists. + * @throws {ArtifactsError} with code `FORK_IN_PROGRESS` if a fork is already running. + */ + fork(name: string, opts?: { + description?: string; + readOnly?: boolean; + defaultBranchOnly?: boolean; + }): Promise; +} +// ── Error types ────────────────────────────────────────────────────────────── +/** + * Error codes returned by Artifacts binding operations. + * + * Each code maps to a numeric code available on `ArtifactsError.numericCode`. + */ +type ArtifactsErrorCode = 'ALREADY_EXISTS' | 'NOT_FOUND' | 'IMPORT_IN_PROGRESS' | 'FORK_IN_PROGRESS' | 'INVALID_INPUT' | 'INVALID_REPO_NAME' | 'INVALID_TTL' | 'INVALID_URL' | 'REMOTE_AUTH_REQUIRED' | 'UPSTREAM_UNAVAILABLE' | 'MEMORY_LIMIT' | 'INTERNAL_ERROR'; +/** + * Error thrown by Artifacts binding operations. + * + * Uses a string `.code` discriminator following the Cloudflare platform + * convention (StreamError, ImagesError, etc.). The `.numericCode` matches + * the REST API `errors[].code` values. + */ +interface ArtifactsError extends Error { + readonly name: 'ArtifactsError'; + /** String error code for programmatic matching. */ + readonly code: ArtifactsErrorCode; + /** Numeric error code matching the REST API. */ + readonly numericCode: number; +} +// ── Binding ────────────────────────────────────────────────────────────────── +/** + * Artifacts binding — namespace-level operations. + * + * Methods may throw `ArtifactsError` with code `INTERNAL_ERROR` if an unexpected service error occurs. + */ +interface Artifacts { + /** + * Create a new repository with an initial access token. + * @param name Repository name (alphanumeric, dots, hyphens, underscores). + * @param opts Optional: readOnly flag, description, default branch name. + * @returns Repo metadata with initial token. + * @throws {ArtifactsError} with code `INVALID_REPO_NAME` if name is invalid. + * @throws {ArtifactsError} with code `ALREADY_EXISTS` if the repo already exists. + */ + create(name: string, opts?: { + readOnly?: boolean; + description?: string; + setDefaultBranch?: string; + }): Promise; + /** + * Get a handle to an existing repository. + * @param name Repository name. + * @returns Repo handle. + * @throws {ArtifactsError} with code `NOT_FOUND` if the repo does not exist. + * @throws {ArtifactsError} with code `IMPORT_IN_PROGRESS` if the repo is still importing. + * @throws {ArtifactsError} with code `FORK_IN_PROGRESS` if the repo is still forking. + */ + get(name: string): Promise; + /** + * Import a repository from an external git remote. + * @param params Source URL and optional branch/depth, plus target name and options. + * @returns Repo metadata with initial token. + * @throws {ArtifactsError} with code `INVALID_REPO_NAME` if the target name is invalid. + * @throws {ArtifactsError} with code `INVALID_INPUT` if the source URL is not valid HTTPS. + * @throws {ArtifactsError} with code `INVALID_URL` if the source URL does not point to a git repository. + * @throws {ArtifactsError} with code `REMOTE_AUTH_REQUIRED` if the remote requires authentication. + * @throws {ArtifactsError} with code `NOT_FOUND` if the remote repository does not exist. + * @throws {ArtifactsError} with code `UPSTREAM_UNAVAILABLE` if the remote cannot be reached. + * @throws {ArtifactsError} with code `MEMORY_LIMIT` if the import exceeds service memory limits. + * @throws {ArtifactsError} with code `ALREADY_EXISTS` if the target repo already exists. + */ + import(params: { + source: { + url: string; + branch?: string; + depth?: number; + }; + target: { + name: string; + opts?: { + description?: string; + readOnly?: boolean; + }; + }; + }): Promise; + /** + * List repositories with cursor-based pagination. + * @param opts Optional: limit (1–200, default 50), cursor for next page. + */ + list(opts?: { + limit?: number; + cursor?: string; + }): Promise; + /** + * Delete a repository and all associated tokens. + * @param name Repository name. + * @returns true if deleted, false if not found. + * @throws {ArtifactsError} with code `INVALID_REPO_NAME` if name is invalid. + */ + delete(name: string): Promise; +} +/** + * @deprecated Use the standalone AI Search Workers binding instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + */ +interface AutoRAGInternalError extends Error { +} +/** + * @deprecated Use the standalone AI Search Workers binding instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + */ +interface AutoRAGNotFoundError extends Error { +} +/** + * @deprecated Use the standalone AI Search Workers binding instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + */ +interface AutoRAGUnauthorizedError extends Error { +} +/** + * @deprecated Use the standalone AI Search Workers binding instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + */ +interface AutoRAGNameNotSetError extends Error { +} +type ComparisonFilter = { + key: string; + type: 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte'; + value: string | number | boolean; +}; +type CompoundFilter = { + type: 'and' | 'or'; + filters: ComparisonFilter[]; +}; +/** + * @deprecated Use the standalone AI Search Workers binding instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + */ +type AutoRagSearchRequest = { + query: string; + filters?: CompoundFilter | ComparisonFilter; + max_num_results?: number; + ranking_options?: { + ranker?: string; + score_threshold?: number; + }; + reranking?: { + enabled?: boolean; + model?: string; + }; + rewrite_query?: boolean; +}; +/** + * @deprecated Use the standalone AI Search Workers binding instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + */ +type AutoRagAiSearchRequest = AutoRagSearchRequest & { + stream?: boolean; + system_prompt?: string; +}; +/** + * @deprecated Use the standalone AI Search Workers binding instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + */ +type AutoRagAiSearchRequestStreaming = Omit & { + stream: true; +}; +/** + * @deprecated Use the standalone AI Search Workers binding instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + */ +type AutoRagSearchResponse = { + object: 'vector_store.search_results.page'; + search_query: string; + data: { + file_id: string; + filename: string; + score: number; + attributes: Record; + content: { + type: 'text'; + text: string; + }[]; + }[]; + has_more: boolean; + next_page: string | null; +}; +/** + * @deprecated Use the standalone AI Search Workers binding instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + */ +type AutoRagListResponse = { + id: string; + enable: boolean; + type: string; + source: string; + vectorize_name: string; + paused: boolean; + status: string; +}[]; +/** + * @deprecated Use the standalone AI Search Workers binding instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + */ +type AutoRagAiSearchResponse = AutoRagSearchResponse & { + response: string; +}; +/** + * @deprecated Use the standalone AI Search Workers binding instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + */ +declare abstract class AutoRAG { + /** + * @deprecated Use the standalone AI Search Workers binding instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + */ + list(): Promise; + /** + * @deprecated Use the standalone AI Search Workers binding instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + */ + search(params: AutoRagSearchRequest): Promise; + /** + * @deprecated Use the standalone AI Search Workers binding instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + */ + aiSearch(params: AutoRagAiSearchRequestStreaming): Promise; + /** + * @deprecated Use the standalone AI Search Workers binding instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + */ + aiSearch(params: AutoRagAiSearchRequest): Promise; + /** + * @deprecated Use the standalone AI Search Workers binding instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + */ + aiSearch(params: AutoRagAiSearchRequest): Promise; +} +type BrowserRunLifecycleEvent = 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2'; +type BrowserRunResourceType = 'document' | 'stylesheet' | 'image' | 'media' | 'font' | 'script' | 'texttrack' | 'xhr' | 'fetch' | 'prefetch' | 'eventsource' | 'websocket' | 'manifest' | 'signedexchange' | 'ping' | 'cspviolationreport' | 'preflight' | 'other'; +/** Options fields shared by all quick actions. */ +interface BrowserRunBaseOptions { + /** Adds ` + + diff --git a/apps/web/fixtures/ui.tsx b/apps/web/fixtures/ui.tsx new file mode 100644 index 0000000..6dba9b9 --- /dev/null +++ b/apps/web/fixtures/ui.tsx @@ -0,0 +1,213 @@ +// Test-only build entry; never linked or included in the production build. +import { createRoot } from 'react-dom/client'; +import { useLayoutEffect, useRef, useState, useSyncExternalStore } from 'react'; +import { QueryClient } from '@tanstack/react-query'; +import { ApiClientError } from '@hyperbug/api-client'; +import { BrowserAuth, takeCallback } from '../src/auth.ts'; +import { loadRuntimeConfig } from '../src/runtime-config.ts'; +import { useForm, fieldErrorText } from '../src/forms.ts'; +import { + ConfirmDialog, + ErrorSummary, + Field, + StateMessage, +} from '../src/components/ui.tsx'; + +const callback = takeCallback(); +const config = await loadRuntimeConfig(); +const queries = new QueryClient(); +const subscribeCache = (listener: () => void) => + queries.getQueryCache().subscribe(listener); +const privateCacheCount = () => + queries.getQueryCache().findAll({ queryKey: ['private'] }).length; +const auth = new BrowserAuth(config, queries); +if (callback) await auth.completeCallback(callback); + +function DraftForm() { + const summary = useRef(null); + const [attempts, setAttempts] = useState(0); + const [message, setMessage] = useState(''); + const validate = (value: string) => + value.trim().length < 3 ? 'Enter at least three characters.' : undefined; + const form = useForm({ + defaultValues: { title: '' }, + onSubmitInvalid: () => setAttempts((value) => value + 1), + onSubmit: async () => { + setMessage(''); + try { + if (auth.getSnapshot().account) + await auth.request('GET /api/v1/account'); + setMessage( + 'Validation complete. This fixture does not save product data.', + ); + } catch (error) { + setMessage( + error instanceof ApiClientError && error.status === 429 + ? 'Too many requests. Wait before trying again.' + : 'Access could not be checked.', + ); + } + }, + }); + useLayoutEffect(() => { + if (attempts > 0) summary.current?.focus(); + }, [attempts]); + return ( +
{ + event.preventDefault(); + void form.handleSubmit(); + }} + > + state.fieldMeta.title}> + {(meta) => ( + 0 && meta?.errors.length + ? [ + { + fieldId: 'fixture-title', + message: fieldErrorText(meta.errors), + }, + ] + : [] + } + /> + )} + + validate(value), + onSubmit: ({ value }) => validate(value), + onChange: ({ value, fieldApi }) => + fieldApi.state.meta.isBlurred || + fieldApi.form.state.submissionAttempts > 0 + ? validate(value) + : undefined, + }} + > + {(field) => ( + 0} + error={fieldErrorText(field.state.meta.errors)} + onBlur={field.handleBlur} + onChange={(event) => { + field.handleChange(event.target.value); + if (field.state.meta.isBlurred) void field.validate('blur'); + }} + /> + )} + + state.isSubmitting}> + {(submitting) => ( + + )} + + {message} +
+ ); +} + +function Fixture() { + const state = useSyncExternalStore(auth.subscribe, auth.getSnapshot); + const cacheCount = useSyncExternalStore(subscribeCache, privateCacheCount); + const [confirmed, setConfirmed] = useState(false); + return ( + <> + + Skip to content + +
+ +
+
+

UI acceptance fixture

+

Reusable primitives only; no product editing workflow.

+ {state.notice} +

+ {state.account + ? state.account.kind === 'staff' + ? 'Staff' + : 'Public user' + : 'Signed out'} +

+
+ + + +
+

Private cache entries: {cacheCount}

+
+

Field and dialog

+ + setConfirmed(true)} + > +

Cancel keeps this test draft.

+ + {confirmed ? 'Fixture action confirmed.' : ''} +
+
+

Application states

+ + +

Choose another filter.

+ + +

Ask an administrator for access.

+ + + Try again later. + +
+
+
+

Test fixture

+
+ + ); +} + +createRoot(document.getElementById('root')!).render(); diff --git a/apps/web/index.html b/apps/web/index.html new file mode 100644 index 0000000..c100b07 --- /dev/null +++ b/apps/web/index.html @@ -0,0 +1,22 @@ + + + + + + + + HyperBug + + + + +
+
+

HyperBug

+ Loading this instance… +
+
+ + + + diff --git a/apps/web/package.json b/apps/web/package.json new file mode 100644 index 0000000..b8f5a9b --- /dev/null +++ b/apps/web/package.json @@ -0,0 +1,41 @@ +{ + "name": "@hyperbug/web", + "version": "0.0.0", + "private": true, + "type": "module", + "scripts": { + "dev": "vite --host 127.0.0.1", + "build": "vite build && node scripts/prepare-deployment.ts", + "typecheck": "tsc --noEmit -p tsconfig.json", + "prepare:deployment": "node scripts/prepare-deployment.ts", + "serve": "node scripts/serve-static.ts", + "lint": "oxlint --config ../../.oxlintrc.json --deny-warnings src scripts fixtures vite.config.ts && node ../../tooling/check-boundaries.mjs", + "format": "oxfmt --write src scripts fixtures public index.html vite.config.ts package.json tsconfig.json components.json", + "format:check": "oxfmt --check src scripts fixtures public index.html vite.config.ts package.json tsconfig.json components.json" + }, + "dependencies": { + "@hyperbug/api-client": "workspace:*", + "@hyperbug/contracts": "workspace:*", + "@base-ui/react": "1.9.0", + "@tanstack/react-form": "1.33.5", + "@tanstack/react-query": "5.104.2", + "@tanstack/react-router": "1.170.42", + "clsx": "2.1.1", + "react": "19.3.0", + "react-dom": "19.3.0", + "tailwind-merge": "3.7.0" + }, + "devDependencies": { + "@tailwindcss/vite": "4.3.3", + "@types/react": "19.3.0", + "@types/react-dom": "19.3.0", + "@vitejs/plugin-react": "6.1.2", + "tailwindcss": "4.3.3", + "typescript": "7.0.2", + "vite": "8.3.4", + "@babel/core": "7.29.7", + "@types/babel__core": "7.20.5", + "@rolldown/plugin-babel": "0.2.4", + "babel-plugin-react-compiler": "1.0.0" + } +} diff --git a/apps/web/public/config.json b/apps/web/public/config.json new file mode 100644 index 0000000..4afbc8c --- /dev/null +++ b/apps/web/public/config.json @@ -0,0 +1,7 @@ +{ + "schemaVersion": 1, + "applicationName": "HyperBug", + "apiBaseUrl": "https://api.example.net", + "authBaseUrl": "https://auth.example.net", + "mediaOrigins": [] +} diff --git a/apps/web/public/favicon.svg b/apps/web/public/favicon.svg new file mode 100644 index 0000000..765152c --- /dev/null +++ b/apps/web/public/favicon.svg @@ -0,0 +1 @@ + diff --git a/apps/web/scripts/build-ui-fixture.ts b/apps/web/scripts/build-ui-fixture.ts new file mode 100644 index 0000000..a870218 --- /dev/null +++ b/apps/web/scripts/build-ui-fixture.ts @@ -0,0 +1,17 @@ +import { fileURLToPath } from 'node:url'; +import { resolve } from 'node:path'; +import { build } from 'vite'; +import config from '../vite.config.ts'; + +// Explicit separate test artifact; production build has only index.html. +const root = fileURLToPath(new URL('../', import.meta.url)); +await build({ + ...config, + root, + configFile: false, + build: { + ...config.build, + outDir: resolve(process.argv[2] ?? '/tmp/hyperbug-module11-ui'), + rolldownOptions: { input: resolve(root, 'fixtures/ui.html') }, + }, +}); diff --git a/apps/web/scripts/prepare-deployment.ts b/apps/web/scripts/prepare-deployment.ts new file mode 100644 index 0000000..084c06f --- /dev/null +++ b/apps/web/scripts/prepare-deployment.ts @@ -0,0 +1,110 @@ +import { readFile, writeFile } from 'node:fs/promises'; +import { resolve } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { + validateRuntimeConfig, + publicOrigin, + type RuntimeConfig, +} from '../src/runtime-config.ts'; +import { + reviewedPluginOrigins, + type ReviewedPluginOrigins, +} from '../src/plugins.ts'; + +export function deploymentPolicy( + config: RuntimeConfig, + plugins: readonly ReviewedPluginOrigins[] = reviewedPluginOrigins, +) { + const origins = (kind: 'connect' | 'images' | 'frames' | 'scripts') => + [ + ...new Set(plugins.flatMap((plugin) => plugin[kind].map(publicOrigin))), + ].sort(); + const csp = [ + "default-src 'none'", + `script-src 'self' ${origins('scripts').join(' ')}`.trim(), + "script-src-attr 'none'", + "style-src 'self'", + "style-src-attr 'none'", + `img-src 'self' data: blob: ${[...config.mediaOrigins, ...origins('images')].join(' ')}`.trim(), + "font-src 'self'", + `connect-src 'self' ${[...new Set([config.apiBaseUrl, config.authBaseUrl, ...config.mediaOrigins, ...(config.uploadOrigins ?? []), ...origins('connect')])].join(' ')}`, + "object-src 'none'", + "base-uri 'none'", + "frame-ancestors 'none'", + `form-action 'self' ${config.authBaseUrl}`, + `frame-src ${origins('frames').length ? origins('frames').join(' ') : "'none'"}`, + "manifest-src 'self'", + "worker-src 'self' blob:", + ].join('; '); + if (csp.length + ' Content-Security-Policy: '.length > 2000) + throw new Error('Deployment CSP exceeds the portable Pages header limit'); + return { + headers: { + 'Content-Security-Policy': csp, + 'X-Content-Type-Options': 'nosniff', + 'X-Frame-Options': 'DENY', + 'Referrer-Policy': 'strict-origin-when-cross-origin', + 'Permissions-Policy': 'camera=(), microphone=(), geolocation=()', + }, + cache: { + html: 'no-cache', + config: 'no-store', + assets: 'public, max-age=31536000, immutable', + other: 'no-cache', + }, + spaFallback: '/index.html', + }; +} + +export async function prepareDeployment( + directory: string, + configPath?: string, +) { + const config = validateRuntimeConfig( + JSON.parse( + await readFile(configPath ?? resolve(directory, 'config.json'), 'utf8'), + ), + ); + const policy = deploymentPolicy(config); + const lines = [ + '/*', + ...Object.entries(policy.headers).map( + ([key, value]) => ` ${key}: ${value}`, + ), + ` Cache-Control: ${policy.cache.html}`, + '/config.json', + ' ! Cache-Control', + ` Cache-Control: ${policy.cache.config}`, + '/assets/*', + ' ! Cache-Control', + ` Cache-Control: ${policy.cache.assets}`, + '', + ]; + // Host-neutral policy is canonical; _headers/_redirects are Pages adapters. + await writeFile( + resolve(directory, 'config.json'), + JSON.stringify(config, null, 2) + '\n', + ); + await writeFile( + resolve(directory, 'hosting.json'), + JSON.stringify(policy, null, 2) + '\n', + ); + await writeFile(resolve(directory, '_headers'), lines.join('\n')); + await writeFile(resolve(directory, '_redirects'), '/* /index.html 200\n'); + return policy; +} + +if ( + process.argv[1] && + resolve(process.argv[1]) === fileURLToPath(import.meta.url) +) { + const root = fileURLToPath(new URL('../dist', import.meta.url)); + const option = (name: string) => + process.argv + .find((x) => x.startsWith(`--${name}=`)) + ?.slice(name.length + 3); + await prepareDeployment(resolve(option('dir') ?? root), option('config')); + console.log( + 'Prepared public runtime configuration and static hosting policy.', + ); +} diff --git a/apps/web/scripts/serve-static.ts b/apps/web/scripts/serve-static.ts new file mode 100644 index 0000000..0704c77 --- /dev/null +++ b/apps/web/scripts/serve-static.ts @@ -0,0 +1,89 @@ +import { createServer } from 'node:http'; +import { readFile, stat } from 'node:fs/promises'; +import { extname, resolve, sep } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { prepareDeployment } from './prepare-deployment.ts'; + +// A portable static-host example only: no API routes, proxies, SSR or Functions. +const option = (name: string) => + process.argv.find((x) => x.startsWith(`--${name}=`))?.slice(name.length + 3); +const root = resolve( + option('dir') ?? fileURLToPath(new URL('../dist', import.meta.url)), +); +const port = Number(option('port') ?? 4173); +if (!Number.isInteger(port) || port < 1 || port > 65535) + throw new Error('Invalid static server port'); +const mime: Record = { + '.html': 'text/html; charset=utf-8', + '.js': 'text/javascript; charset=utf-8', + '.css': 'text/css; charset=utf-8', + '.json': 'application/json; charset=utf-8', + '.svg': 'image/svg+xml', +}; +await prepareDeployment(root); +const server = createServer(async (request, response) => { + try { + if (!['GET', 'HEAD'].includes(request.method ?? '')) { + response.writeHead(405, { Allow: 'GET, HEAD' }); + response.end(); + return; + } + const url = new URL(request.url ?? '/', 'http://localhost'); + const pathname = decodeURIComponent(url.pathname); + let file = resolve(root, '.' + pathname); + if ( + (file !== root && !file.startsWith(root + sep)) || + pathname.includes('\0') + ) { + response.writeHead(404); + response.end(); + return; + } + // Never serve host metadata or Vite's build manifest. + if ( + pathname.startsWith('/.') || + ['/_headers', '/_redirects', '/hosting.json'].includes(pathname) + ) { + response.writeHead(404); + response.end(); + return; + } + try { + if (!(await stat(file)).isFile()) throw new Error('not file'); + } catch { + if (extname(pathname)) { + response.writeHead(404); + response.end(); + return; + } + file = resolve(root, 'index.html'); + } + const policy = JSON.parse( + await readFile(resolve(root, 'hosting.json'), 'utf8'), + ) as Awaited>; + const cache = + pathname === '/config.json' + ? policy.cache.config + : pathname.startsWith('/assets/') + ? policy.cache.assets + : extname(file) === '.html' + ? policy.cache.html + : policy.cache.other; + const body = await readFile(file); + response.writeHead(200, { + ...policy.headers, + 'Cache-Control': cache, + 'Content-Type': mime[extname(file)] ?? 'application/octet-stream', + 'Content-Length': body.length, + }); + response.end(request.method === 'HEAD' ? undefined : body); + } catch { + response.writeHead(500, { 'Cache-Control': 'no-store' }); + response.end('Static host unavailable'); + } +}); +server.listen(port, '127.0.0.1', () => + console.log(`Static frontend: http://127.0.0.1:${port}`), +); +for (const signal of ['SIGTERM', 'SIGINT'] as const) + process.on(signal, () => server.close()); diff --git a/apps/web/src/app.tsx b/apps/web/src/app.tsx new file mode 100644 index 0000000..fe2ea74 --- /dev/null +++ b/apps/web/src/app.tsx @@ -0,0 +1,302 @@ +import { + StrictMode, + useLayoutEffect, + useRef, + useSyncExternalStore, +} from 'react'; +import { BrowserAuth } from './auth.ts'; +import { createApiClient } from '@hyperbug/api-client'; +import { createRoot } from 'react-dom/client'; +import { + QueryClient, + QueryClientProvider, + useQuery, +} from '@tanstack/react-query'; +import { + createRootRouteWithContext, + createRoute, + createRouter, + lazyRouteComponent, + Link, + Outlet, + useLocation, + RouterProvider, +} from '@tanstack/react-router'; +import { instanceQuery } from './capabilities.ts'; +import type { RuntimeConfig } from './runtime-config.ts'; +import { validateIssueSearch } from './product-state.ts'; +import { MinimumNotice } from './components/minimum-notice.tsx'; + +interface ApplicationContext { + config: RuntimeConfig; + instance: ReturnType; + auth: BrowserAuth; + publicClient: ReturnType; +} + +const rootRoute = createRootRouteWithContext()({ + component: ApplicationShell, + notFoundComponent: () => ( + <> +

Page not found

+

This address is not part of this instance.

+ Return to overview + + ), +}); +const overviewRoute = createRoute({ + getParentRoute: () => rootRoute, + path: '/', + component: lazyRouteComponent( + () => import('./routes/overview.tsx'), + 'Overview', + ), +}); +const instanceRoute = createRoute({ + getParentRoute: () => rootRoute, + path: '/instance', + validateSearch: ( + search: Record, + ): { section: 'capabilities' | 'limits' } => ({ + section: search.section === 'limits' ? 'limits' : 'capabilities', + }), + component: lazyRouteComponent( + () => import('./routes/instance.tsx'), + 'Instance', + ), +}); +const accountRoute = createRoute({ + getParentRoute: () => rootRoute, + path: '/account', + component: lazyRouteComponent( + () => import('./routes/account.tsx'), + 'Account', + ), +}); +export const projectRoute = createRoute({ + getParentRoute: () => rootRoute, + path: '/projects/$projectId', + validateSearch: validateIssueSearch, + component: lazyRouteComponent( + () => import('./routes/project.tsx'), + 'Project', + ), +}); +export const newIssueRoute = createRoute({ + getParentRoute: () => rootRoute, + path: '/projects/$projectId/new', + component: lazyRouteComponent( + () => import('./routes/new-issue.tsx'), + 'NewIssue', + ), +}); +export const issueRoute = createRoute({ + getParentRoute: () => rootRoute, + path: '/projects/$projectId/issues/$issueId/$number', + validateSearch: (raw: Record) => ({ + cursor: + typeof raw.cursor === 'string' && raw.cursor.length <= 2048 + ? raw.cursor + : '', + comment: + typeof raw.comment === 'string' && /^[0-9a-f-]{36}$/.test(raw.comment) + ? raw.comment + : '', + }), + component: lazyRouteComponent(() => import('./routes/issue.tsx'), 'Issue'), +}); +export const manageRoute = createRoute({ + getParentRoute: () => rootRoute, + path: '/projects/$projectId/manage', + validateSearch: (raw: Record) => ({ + auditAfter: + typeof raw.auditAfter === 'string' && raw.auditAfter.length <= 1024 + ? raw.auditAfter + : '', + }), + component: lazyRouteComponent(() => import('./routes/manage.tsx'), 'Manage'), +}); +const pluginsRoute = createRoute({ + getParentRoute: () => rootRoute, + path: '/plugins', + component: lazyRouteComponent( + () => import('./routes/plugins-admin.tsx'), + 'PluginsAdmin', + ), +}); + +function makeRouter(context: ApplicationContext) { + return createRouter({ + routeTree: rootRoute.addChildren([ + overviewRoute, + instanceRoute, + accountRoute, + projectRoute, + newIssueRoute, + issueRoute, + manageRoute, + pluginsRoute, + ]), + context, + defaultPreload: 'intent', + defaultPendingComponent: () => Loading page…, + defaultErrorComponent: () => ( + <> +

Page unavailable

+

Reload this page to try again.

+ + ), + }); +} +export type ApplicationRouter = ReturnType; +declare module '@tanstack/react-router' { + interface Register { + router: ApplicationRouter; + } +} + +export function useInstance() { + const { instance } = rootRoute.useRouteContext(); + return useQuery(instance); +} +export function usePublicConfig() { + return rootRoute.useRouteContext().config; +} +export function usePublicClient() { + return rootRoute.useRouteContext().publicClient; +} +export { instanceRoute }; +export function useAuth() { + const { auth } = rootRoute.useRouteContext(); + return { + auth, + state: useSyncExternalStore(auth.subscribe, auth.getSnapshot), + }; +} + +function ApplicationShell() { + const routePath = useLocation({ select: (current) => current.pathname }); + const config = usePublicConfig(); + const instance = useInstance(); + const { state } = useAuth(); + const previousEpoch = useRef(state.epoch); + useLayoutEffect(() => { + if (previousEpoch.current !== state.epoch) + document.getElementById('content')?.focus(); + previousEpoch.current = state.epoch; + }, [state.epoch]); + return ( + <> + + Skip to content + +
+ + + {config.applicationName} + + +
+
+ {instance.isPending ? ( + <> +

Connecting to this instance

+ Checking available capabilities… + + ) : instance.isError ? ( + <> +

This instance is unavailable

+

+ Its capabilities could not be verified. Try again or contact its + administrator. +

+ + + ) : ( + <> + {routePath !== '/account' && state.notice ? ( + {state.notice} + ) : null} + + + )} +
+
+ +

Powered by HyperBug · A shared place for feedback

+
+ + ); +} + +export async function startApplication( + container: HTMLElement, + config: RuntimeConfig, + callback: URLSearchParams | null, +) { + const queryClient = new QueryClient({ + defaultOptions: { queries: { retry: false }, mutations: { retry: false } }, + }); + const auth = new BrowserAuth(config, queryClient); + if (callback) await auth.completeCallback(callback); + const publicClient = createApiClient({ + baseUrl: config.apiBaseUrl, + maxRetries: 0, + }); + const router = makeRouter({ + config, + instance: instanceQuery(config), + auth, + publicClient, + }); + let previousPath = location.pathname; + router.subscribe('onRendered', ({ toLocation }) => { + const page = + toLocation.pathname === '/account' + ? 'Account' + : toLocation.pathname === '/instance' + ? 'Instance' + : toLocation.pathname.startsWith('/projects/') + ? 'Project' + : 'Overview'; + document.title = `${page} · ${config.applicationName}`; + if (previousPath !== toLocation.pathname) + document.getElementById('content')?.focus(); + previousPath = toLocation.pathname; + }); + createRoot(container).render( + + + + + , + ); +} diff --git a/apps/web/src/auth.ts b/apps/web/src/auth.ts new file mode 100644 index 0000000..d724f09 --- /dev/null +++ b/apps/web/src/auth.ts @@ -0,0 +1,467 @@ +import { + ApiClientError, + createApiClient, + type Operation, + type OperationTypes, + type RequestInput, +} from '@hyperbug/api-client'; +import type { QueryClient } from '@tanstack/react-query'; +import type { RuntimeConfig } from './runtime-config.ts'; + +// Register this public client and the exact /oauth/callback URI on the backend. +export const publicClientId = 'hyperbug-web'; +export const redirectAttemptKey = 'hyperbug.pkce.v1'; +const attemptLifetime = 5 * 60 * 1000; +const callbackPath = '/oauth/callback'; +const returnPaths = new Set(['/', '/instance', '/account']); +type Account = OperationTypes['GET /api/v1/account']['response']; +export interface AuthSnapshot { + readonly epoch: number; + readonly account: Account | null; + readonly notice: string; + readonly pending: boolean; +} +interface RedirectAttempt { + state: string; + verifier: string; + createdAt: number; + returnTo: string; + origin: string; + apiOrigin: string; + authOrigin: string; +} + +export function safeReturnRoute(value: string): string { + if (value.length > 512) return '/account'; + const url = new URL(value, location.origin); + if ( + !value.startsWith('/') || + value.startsWith('//') || + url.origin !== location.origin || + !returnPaths.has(url.pathname) || + url.hash || + (url.search && url.pathname !== '/instance') + ) + return '/account'; + if (url.pathname === '/instance') { + const section = url.searchParams.get('section'); + return section === 'limits' + ? '/instance?section=limits' + : '/instance?section=capabilities'; + } + return url.pathname; +} + +/** Capture once, then remove even invalid/error callbacks before any fetch. */ +export function takeCallback(): URLSearchParams | null { + if (location.pathname !== callbackPath) { + // Abandoned attempts are never used outside the callback. + try { + sessionStorage.removeItem(redirectAttemptKey); + } catch { + /* Browsing public pages does not require storage. */ + } + return null; + } + const parameters = new URLSearchParams(location.search); + history.replaceState(null, '', callbackPath); + return parameters; +} + +function randomValue() { + return btoa( + String.fromCharCode(...crypto.getRandomValues(new Uint8Array(32))), + ) + .replaceAll('+', '-') + .replaceAll('/', '_') + .replace(/=+$/, ''); +} + +function consumeAttempt(config: RuntimeConfig, parameters: URLSearchParams) { + const stored = sessionStorage.getItem(redirectAttemptKey); + sessionStorage.removeItem(redirectAttemptKey); + if (!stored || stored.length > 4096) throw new Error('INVALID_CALLBACK'); + const attempt = JSON.parse(stored) as RedirectAttempt; + const keys = [ + 'state', + 'verifier', + 'createdAt', + 'returnTo', + 'origin', + 'apiOrigin', + 'authOrigin', + ]; + if ( + Object.keys(attempt).length !== keys.length || + Object.keys(attempt).some((key) => !keys.includes(key)) || + !/^[A-Za-z0-9_-]{43}$/.test(attempt.state) || + !/^[A-Za-z0-9_-]{43}$/.test(attempt.verifier) || + !Number.isFinite(attempt.createdAt) || + Date.now() < attempt.createdAt || + Date.now() - attempt.createdAt > attemptLifetime || + attempt.origin !== location.origin || + attempt.apiOrigin !== config.apiBaseUrl || + attempt.authOrigin !== config.authBaseUrl || + typeof attempt.returnTo !== 'string' || + safeReturnRoute(attempt.returnTo) !== attempt.returnTo || + parameters.getAll('state').length !== 1 || + parameters.get('state') !== attempt.state || + [...parameters.keys()].some( + (key) => !['code', 'state', 'error', 'error_description'].includes(key), + ) || + parameters.has('error') || + parameters.getAll('code').length !== 1 || + !/^[A-Za-z0-9_.-]{1,256}$/.test(parameters.get('code') ?? '') + ) + throw new Error('INVALID_CALLBACK'); + return attempt; +} + +/** Credentials never enter snapshots, React, Query, URLs, logs or storage. */ +export class BrowserAuth { + #token: string | null = null; + #expiresAt = 0; + #timer: ReturnType | undefined; + #listeners = new Set<() => void>(); + #requests = new Set(); + #snapshot: AuthSnapshot = { + epoch: 0, + account: null, + notice: '', + pending: false, + }; + #client; + #authClient; + #channel: BroadcastChannel | undefined; + readonly config: RuntimeConfig; + private readonly queries: QueryClient; + + constructor(config: RuntimeConfig, queries: QueryClient) { + this.config = config; + this.queries = queries; + this.#client = createApiClient({ + baseUrl: config.apiBaseUrl, + getToken: () => this.#readToken(), + maxRetries: 0, + }); + this.#authClient = createApiClient({ + baseUrl: config.authBaseUrl, + maxRetries: 0, + maxResponseBytes: 16384, + }); + document.addEventListener('visibilitychange', () => { + if (document.visibilityState === 'visible') this.#readToken(); + }); + window.addEventListener('pageshow', (event) => { + if (event.persisted) + this.#invalidate( + 'Your session needs to be checked. Sign in to continue.', + ); + }); + if (typeof BroadcastChannel !== 'undefined') { + this.#channel = new BroadcastChannel( + `hyperbug.auth:${config.apiBaseUrl}`, + ); + this.#channel.onmessage = (event) => { + if (event.data === 'signed-out') + this.#invalidate('Signed out in another tab.'); + }; + } + } + subscribe = (listener: () => void) => { + this.#listeners.add(listener); + return () => { + this.#listeners.delete(listener); + }; + }; + getSnapshot = () => this.#snapshot; + + #publish(change: Partial) { + this.#snapshot = Object.freeze({ ...this.#snapshot, ...change }); + for (const listener of this.#listeners) listener(); + } + #invalidate(notice: string) { + this.#token = null; + this.#expiresAt = 0; + clearTimeout(this.#timer); + for (const request of this.#requests) request.abort(); + // Cancellation starts synchronously; clearing removes private queries AND mutations. + const instanceKey = ['instance', this.config.apiBaseUrl]; + const instance = this.queries.getQueryData(instanceKey); + void this.queries.cancelQueries(); + this.queries.clear(); + if (instance) this.queries.setQueryData(instanceKey, instance); + this.#publish({ + epoch: this.#snapshot.epoch + 1, + account: null, + notice, + pending: false, + }); + } + #readToken() { + if (this.#token && Date.now() >= this.#expiresAt) + this.#invalidate( + 'Your session expired. Sign in to continue. Unsaved changes were cleared.', + ); + return this.#token; + } + + async signIn(returnTo = '/account') { + this.#invalidate(''); + this.#publish({ pending: true }); + try { + const state = randomValue(), + verifier = randomValue(); + const digest = new Uint8Array( + await crypto.subtle.digest( + 'SHA-256', + new TextEncoder().encode(verifier), + ), + ); + const challenge = btoa(String.fromCharCode(...digest)) + .replaceAll('+', '-') + .replaceAll('/', '_') + .replace(/=+$/, ''); + const attempt: RedirectAttempt = { + state, + verifier, + createdAt: Date.now(), + returnTo: safeReturnRoute(returnTo), + origin: location.origin, + apiOrigin: this.config.apiBaseUrl, + authOrigin: this.config.authBaseUrl, + }; + sessionStorage.setItem(redirectAttemptKey, JSON.stringify(attempt)); + const url = new URL('/auth/authorize', this.config.authBaseUrl); + url.search = new URLSearchParams({ + response_type: 'code', + client_id: publicClientId, + redirect_uri: location.origin + callbackPath, + scope: 'public-api', + state, + code_challenge: challenge, + code_challenge_method: 'S256', + }).toString(); + location.assign(url.href); + } catch { + try { + sessionStorage.removeItem(redirectAttemptKey); + } catch { + /* Storage may be unavailable. */ + } + this.#publish({ + pending: false, + notice: 'Sign-in could not start. Check browser storage and try again.', + }); + } + } + + async completeCallback(parameters: URLSearchParams) { + this.#invalidate(''); + const epoch = this.#snapshot.epoch; + const controller = new AbortController(); + this.#requests.add(controller); + try { + const attempt = consumeAttempt(this.config, parameters); + const token = await this.#authClient.request('POST /auth/token', { + signal: controller.signal, + body: { + grant_type: 'authorization_code', + client_id: publicClientId, + redirect_uri: location.origin + callbackPath, + code: parameters.get('code')!, + code_verifier: attempt.verifier, + }, + }); + if (epoch !== this.#snapshot.epoch) + throw new ApiClientError(0, 'CANCELLED'); + if ( + token.tokenType !== 'Bearer' || + !/^at_[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(token.accessToken) || + !Number.isInteger(token.expiresIn) || + token.expiresIn < 1 || + token.expiresIn > 900 || + token.scope !== 'public-api' + ) + throw new Error('INVALID_TOKEN_RESPONSE'); + this.#token = token.accessToken; + this.#expiresAt = Date.now() + token.expiresIn * 1000; + this.#timer = setTimeout(() => this.#readToken(), token.expiresIn * 1000); + const account = await this.request('GET /api/v1/account'); + if ( + !account.principalId || + !account.identityId || + !['user', 'staff'].includes(account.kind) + ) + throw new Error('INVALID_ACCOUNT_RESPONSE'); + this.#publish({ account, notice: 'Signed in.' }); + history.replaceState(null, '', attempt.returnTo); + } catch { + if (epoch === this.#snapshot.epoch) + this.#invalidate( + 'Sign-in could not be verified. Start a new sign-in attempt.', + ); + history.replaceState(null, '', '/account'); + } finally { + this.#requests.delete(controller); + } + } + + async request( + operation: K, + ...args: {} extends RequestInput + ? [input?: RequestInput] + : [input: RequestInput] + ): Promise { + if (!this.#readToken()) + throw new ApiClientError(401, 'AUTHENTICATION_REQUIRED'); + const epoch = this.#snapshot.epoch; + const controller = new AbortController(); + this.#requests.add(controller); + const input = args[0]; + const abort = () => controller.abort(); + input?.signal?.addEventListener('abort', abort, { once: true }); + if (input?.signal?.aborted) controller.abort(); + try { + const request = this.#client.request as ( + op: K, + input: RequestInput, + ) => Promise; + const result = await request(operation, { + ...input, + signal: controller.signal, + } as RequestInput); + if (epoch !== this.#snapshot.epoch) + throw new ApiClientError(0, 'CANCELLED'); + return result; + } catch (error) { + if ( + epoch === this.#snapshot.epoch && + error instanceof ApiClientError && + [401, 403].includes(error.status) + ) + this.#invalidate( + error.status === 401 + ? 'Your session is no longer valid. Sign in to continue. Unsaved changes were cleared.' + : error.code === 'REAUTHENTICATION_REQUIRED' + ? 'A recent verified passkey sign-in is required. Password sign-in alone cannot confirm this sensitive action. Unsaved changes were cleared.' + : 'Permission denied. Cached data and unsaved changes were cleared.', + ); + throw error; + } finally { + input?.signal?.removeEventListener('abort', abort); + this.#requests.delete(controller); + } + } + + /** Fixed isolated-media path; never send the bearer to storage capabilities. */ + async downloadAttachment( + id: string, + origin: string, + signal: AbortSignal, + ): Promise<{ blob: Blob; imageType: string | null }> { + if ( + !/^[0-9a-f-]{36}$/.test(id) || + !this.config.mediaOrigins.includes(origin) + ) + throw new ApiClientError(0, 'INVALID_PARAMETERS'); + const epoch = this.#snapshot.epoch; + const token = this.#readToken(); + const controller = new AbortController(); + const abort = () => controller.abort(); + signal.addEventListener('abort', abort, { once: true }); + if (signal.aborted) controller.abort(); + this.#requests.add(controller); + const timer = setTimeout(abort, 60000); + try { + const response = await fetch(new URL(`/attachments/${id}`, origin), { + credentials: 'omit', + redirect: 'error', + cache: 'no-store', + referrerPolicy: 'no-referrer', + signal: controller.signal, + headers: token ? { authorization: `Bearer ${token}` } : {}, + }); + if (!response.ok) { + void response.body?.cancel(); + if ([401, 403].includes(response.status)) + this.#invalidate( + 'Attachment access changed. Sign in again to continue.', + ); + throw new ApiClientError(response.status, 'ATTACHMENT_UNAVAILABLE'); + } + if ( + !response.body || + response.headers.get('x-content-type-options') !== 'nosniff' || + !response.headers.get('content-disposition')?.startsWith('attachment') + ) { + void response.body?.cancel(); + throw new ApiClientError(0, 'INVALID_RESPONSE'); + } + const reader = response.body.getReader(); + const chunks: Uint8Array[] = []; + let length = 0; + try { + async function next(): Promise { + const { done, value } = await reader.read(); + if (done) return; + length += value.byteLength; + if (length > 33554432) + throw new ApiClientError(0, 'RESPONSE_TOO_LARGE'); + chunks.push(new Uint8Array(value)); + return next(); + } + await next(); + } finally { + void reader.cancel().catch(() => {}); + reader.releaseLock(); + } + if (epoch !== this.#snapshot.epoch || controller.signal.aborted) + throw new ApiClientError(0, 'CANCELLED'); + const type = response.headers.get('x-hyperbug-preview-type') ?? ''; + const imageType = [ + 'image/png', + 'image/jpeg', + 'image/gif', + 'image/webp', + ].includes(type) + ? type + : null; + return { + blob: new Blob(chunks, { type: 'application/octet-stream' }), + imageType, + }; + } catch (error) { + if (error instanceof ApiClientError) throw error; + throw new ApiClientError(0, 'ATTACHMENT_UNAVAILABLE'); + } finally { + clearTimeout(timer); + this.#requests.delete(controller); + signal.removeEventListener('abort', abort); + } + } + + async signOut() { + const token = this.#readToken(); + this.#invalidate( + 'Signed out of this app. The authorization service may still have a first-party session.', + ); + try { + sessionStorage.removeItem(redirectAttemptKey); + } catch { + /* Revocation must still run. */ + } + this.#channel?.postMessage('signed-out'); + if (!token) return; + try { + await this.#authClient.request('POST /auth/token/revoke', { + body: { token }, + }); + } catch { + this.#publish({ + notice: + 'Signed out locally. Server revocation could not be confirmed; the previous token expires within 15 minutes.', + }); + } + } +} diff --git a/apps/web/src/capabilities.ts b/apps/web/src/capabilities.ts new file mode 100644 index 0000000..0b0d7f9 --- /dev/null +++ b/apps/web/src/capabilities.ts @@ -0,0 +1,26 @@ +import instanceContract from 'virtual:hyperbug-instance-contract'; +import { createApiClient } from '@hyperbug/api-client'; +import { queryOptions } from '@tanstack/react-query'; +import type { RuntimeConfig } from './runtime-config.ts'; +import { validateInstanceDocument } from './capability-validation.ts'; + +export function instanceQuery(config: RuntimeConfig) { + const client = createApiClient({ + baseUrl: config.apiBaseUrl, + maxRetries: 0, + maxResponseBytes: 16384, + }); + return queryOptions({ + queryKey: ['instance', config.apiBaseUrl], + queryFn: async ({ signal }) => + validateInstanceDocument( + await client.request('GET /api/v1/instance', { signal }), + instanceContract, + ), + staleTime: 60000, + gcTime: 300000, + retry: false, + refetchOnWindowFocus: false, + refetchOnReconnect: false, + }); +} diff --git a/apps/web/src/capability-validation.ts b/apps/web/src/capability-validation.ts new file mode 100644 index 0000000..9e16f45 --- /dev/null +++ b/apps/web/src/capability-validation.ts @@ -0,0 +1,62 @@ +import type { InstanceDocument } from '@hyperbug/api-client'; + +// This bounded interpreter uses the exact public schema embedded at build time. +// No duplicate instance schema or TypeBox/server implementation ships to browsers. +function matches(schema: Record, value: unknown): boolean { + if ('const' in schema && value !== schema.const) return false; + if (Array.isArray(schema.anyOf)) + return schema.anyOf.some((item) => matches(item, value)); + if (schema.type === 'object') { + if (!value || typeof value !== 'object' || Array.isArray(value)) + return false; + const object = value as Record; + const properties = schema.properties as Record< + string, + Record + >; + const required = schema.required as string[]; + return ( + required.every((key) => Object.hasOwn(object, key)) && + Object.keys(object).every( + (key) => + properties[key] !== undefined && + matches(properties[key], object[key]), + ) + ); + } + if (schema.type === 'array') + return ( + Array.isArray(value) && + value.length <= Number(schema.maxItems ?? 100) && + (!schema.uniqueItems || new Set(value).size === value.length) && + value.every((item) => + matches(schema.items as Record, item), + ) + ); + if (schema.type === 'string') + return ( + typeof value === 'string' && + value.length >= Number(schema.minLength ?? 0) && + value.length <= Number(schema.maxLength ?? 2048) && + (typeof schema.pattern !== 'string' || + new RegExp(schema.pattern).test(value)) + ); + if (schema.type === 'boolean') return typeof value === 'boolean'; + if (schema.type === 'number') + return typeof value === 'number' && Number.isFinite(value); + if (schema.type === 'integer') + return ( + typeof value === 'number' && + Number.isSafeInteger(value) && + value >= Number(schema.minimum ?? Number.MIN_SAFE_INTEGER) && + value <= Number(schema.maximum ?? Number.MAX_SAFE_INTEGER) + ); + return false; +} +export function validateInstanceDocument( + value: unknown, + schema: Record, +): InstanceDocument { + if (!matches(schema, value)) throw new Error('INVALID_INSTANCE_DOCUMENT'); + return value as InstanceDocument; +} diff --git a/apps/web/src/components/attachment.tsx b/apps/web/src/components/attachment.tsx new file mode 100644 index 0000000..23b3ba4 --- /dev/null +++ b/apps/web/src/components/attachment.tsx @@ -0,0 +1,106 @@ +import { useEffect, useRef, useState } from 'react'; +import { useAuth, usePublicConfig } from '../app.tsx'; +import { productError } from '../product-state.ts'; +export function AttachmentReference({ + id, + label, +}: { + id: string; + label: string; +}) { + const { auth } = useAuth(); + const config = usePublicConfig(); + const [pending, setPending] = useState(false); + const [message, setMessage] = useState(''); + const [image, setImage] = useState(); + const urls = useRef(new Set()); + const controller = useRef(null); + useEffect(() => { + const owned = urls.current; + return () => { + controller.current?.abort(); + for (const url of owned) URL.revokeObjectURL(url); + owned.clear(); + }; + }, []); + if (!config.mediaOrigins[0]) + return ( + + Attachment {label || id}: downloads are unavailable until an isolated + media origin is configured. + + ); + async function load(preview: boolean) { + if (pending) return; + setPending(true); + setMessage(''); + const abort = new AbortController(); + controller.current = abort; + try { + const { blob, imageType } = await auth.downloadAttachment( + id, + config.mediaOrigins[0]!, + abort.signal, + ); + if (preview && (!imageType || blob.size > 8388608)) { + setMessage( + 'Only released raster images up to 8 MiB can be previewed. Download this file to open it.', + ); + return; + } + const url = URL.createObjectURL( + preview ? new Blob([blob], { type: imageType! }) : blob, + ); + urls.current.add(url); + if (preview) { + if (image) { + URL.revokeObjectURL(image); + urls.current.delete(image); + } + setImage(url); + } else { + const link = document.createElement('a'); + link.href = url; + link.download = + label.replace(/[\\/:*?"<>|]/g, '_').slice(0, 200) || + `attachment-${id}`; + link.click(); + setTimeout(() => { + URL.revokeObjectURL(url); + urls.current.delete(url); + }, 1000); + } + } catch (error) { + if (!abort.signal.aborted) setMessage(productError(error)); + } finally { + setPending(false); + } + } + return ( + + Attachment: {label || id} + + + + + {message} + {image ? {label} : null} + + ); +} diff --git a/apps/web/src/components/audit-browser.tsx b/apps/web/src/components/audit-browser.tsx new file mode 100644 index 0000000..2d7d6ef --- /dev/null +++ b/apps/web/src/components/audit-browser.tsx @@ -0,0 +1,62 @@ +import { Link } from '@tanstack/react-router'; +import { manageRoute } from '../app.tsx'; +import { useProductQuery } from '../product-api.ts'; +import { QueryStatus } from './product.tsx'; +export function AuditBrowser({ projectId }: { projectId: string }) { + const search = manageRoute.useSearch(); + const audit = useProductQuery('GET /api/v1/projects/{projectId}/audit', { + params: { projectId }, + query: { + limit: 20, + ...(search.auditAfter ? { after: search.auditAfter } : {}), + }, + }); + return ( +
+

Project audit trail

+

+ Administrator access only. This view omits metadata, secret values and + request identifiers. Each page is authorized against current + permissions. +

+ + {audit.data ? ( + <> +
    + {audit.data.items.map((event) => ( +
  1. + {' '} + · {event.action} · {event.result} +

    + Actor: {event.actorId ?? event.systemActor} · Target:{' '} + {event.targetId} +

    +
    2. + ))} +
+ {!audit.data.items.length ?

No project audit events.

: null} + + + ) : null} +
+ ); +} diff --git a/apps/web/src/components/command-form.tsx b/apps/web/src/components/command-form.tsx new file mode 100644 index 0000000..28d12b2 --- /dev/null +++ b/apps/web/src/components/command-form.tsx @@ -0,0 +1,168 @@ +import { useId, useRef, useState } from 'react'; +import { useForm } from '../forms.ts'; +import { ErrorSummary, ConfirmDialog } from './ui.tsx'; +import { productError } from '../product-state.ts'; + +export interface CommandField { + name: string; + label: string; + value?: string; + required?: boolean; + multiline?: boolean; + secret?: boolean; + inputType?: 'text' | 'date' | 'number'; + validate?: (value: string) => string | undefined; + maxLength?: number; + options?: readonly string[]; +} +export function CommandForm({ + label, + fields, + confirm = false, + onSave, +}: { + label: string; + fields: readonly CommandField[]; + confirm?: boolean; + onSave: (value: Record) => Promise; +}) { + const idPrefix = useId(); + const [errors, setErrors] = useState<{ fieldId: string; message: string }[]>( + [], + ); + const [message, setMessage] = useState(''); + const save = useRef(onSave); + const summary = useRef(null); + const form = useForm({ + defaultValues: Object.fromEntries( + fields.map((field) => [field.name, field.value ?? '']), + ), + onSubmit: async ({ value }) => { + const invalid = fields.flatMap((field) => { + const answer = value[field.name] ?? ''; + const validationMessage = + field.required && !answer.trim() + ? `Enter ${field.label.toLowerCase()}.` + : (field.validate?.(answer) ?? + (field.maxLength && [...answer].length > field.maxLength + ? `${field.label} is too long.` + : undefined)); + return validationMessage + ? [ + { + fieldId: `${idPrefix}-${field.name}`, + message: validationMessage, + }, + ] + : []; + }); + setErrors(invalid); + if (invalid.length) { + requestAnimationFrame(() => summary.current?.focus()); + return; + } + try { + await save.current(value); + setMessage('Changes saved.'); + for (const field of fields) + if (field.secret) form.setFieldValue(field.name, ''); + } catch (error) { + setMessage(productError(error)); + } + }, + }); + return ( +
{ + event.preventDefault(); + if (!confirm) void form.handleSubmit(); + }} + > + + {fields.map((definition) => ( + + {(field) => { + const id = `${idPrefix}-${definition.name}`; + const error = errors.find((entry) => entry.fieldId === id); + const common = { + id, + name: definition.name, + required: definition.required, + maxLength: definition.maxLength ?? 32768, + value: field.state.value ?? '', + 'aria-invalid': error ? (true as const) : undefined, + 'aria-describedby': error ? `${id}-error` : undefined, + onChange: (event: { target: { value: string } }) => { + field.handleChange(event.target.value); + setErrors((previous) => + previous.filter((entry) => entry.fieldId !== id), + ); + }, + onBlur: field.handleBlur, + }; + return ( +
+ + {definition.options ? ( + + ) : definition.multiline ? ( +