qarpeo 0.0.0-alpha.10

package/dist/types.d.ts

@@ -0,0 +1,2750 @@
+export interface RateLimitConfig {
+    /**
+     * Max number of requests permitted within the time window.
+     *
+     * @default 100
+     */
+    limit?: number;
+    /**
+     * Period window in seconds: must be 10 or 60.
+     *
+     * @default 60
+     */
+    period?: 10 | 60;
+    /**
+     * Unique namespace ID grouping rate limit counters.
+     *
+     * @default 1001
+     */
+    namespaceId?: number;
+}
+export interface EmailOptions {
+    /**
+     * Default sender address or map of named sender presets.
+     *
+     * @example
+     *   // Single default address:
+     *   from: "MyApp <noreply@myapp.com>"
+     *
+     *   // Map of named presets:
+     *   from: {
+     *   default: "MyApp <noreply@myapp.com>",
+     *   support: "Support Team <support@myapp.com>",
+     *   billing: "Acme Invoicing <billing@myapp.com>",
+     *   }
+     */
+    from?: string | Record<string, string>;
+    /**
+     * Cloudflare send_email binding name override.
+     *
+     * @default "EMAIL"
+     */
+    binding?: string;
+}
+export interface AuthRedirectConfig {
+    /**
+     * Route to redirect after successful login.
+     *
+     * @default "/dashboard"
+     */
+    success?: string;
+    /**
+     * Route to redirect after logout.
+     *
+     * @default "/login"
+     */
+    logout?: string;
+    /**
+     * Route to redirect when an unauthenticated user accesses a protected route.
+     *
+     * @default "/login"
+     */
+    login?: string;
+}
+export interface AuthSessionConfig {
+    /**
+     * Session storage backend: sealed cookie or Cloudflare KV.
+     *
+     * @default "cookie"
+     */
+    backend?: "cookie" | "kv";
+    /**
+     * Session expiration maxAge in seconds.
+     *
+     * @default 604800 (7 days)
+     */
+    maxAge?: number;
+    /**
+     * Maximum concurrent sessions per user before LRU eviction.
+     *
+     * @default 5
+     */
+    maxSessionsPerUser?: number;
+    /**
+     * Throttled device tracking in D1.
+     *
+     * @default false
+     */
+    trackDevice?: boolean;
+}
+export interface AuthPasswordlessOtpConfig {
+    /** Enable 6-digit OTP codes */
+    enabled?: boolean;
+    /** Code TTL in seconds @default 300 */
+    ttl?: number;
+    /** Delivery channels @default ["email"] */
+    channels?: Array<"email" | "sms" | "whatsapp" | "telegram">;
+}
+export interface AuthPasswordlessMagicLinkConfig {
+    /** Enable email magic login links */
+    enabled?: boolean;
+    /** Link TTL in seconds @default 900 */
+    ttl?: number;
+}
+export interface AuthPasswordlessConfig {
+    otp?: boolean | AuthPasswordlessOtpConfig;
+    magicLink?: boolean | AuthPasswordlessMagicLinkConfig;
+}
+export interface AuthFieldDefinition {
+    type: "string" | "number" | "boolean" | "json";
+    default?: string | number | boolean;
+    enum?: readonly string[];
+    nullable?: boolean;
+}
+export interface AuthFieldsConfig {
+    extends?: Record<string, AuthFieldDefinition>;
+}
+export interface AuthOptions {
+    /** Route protection rules mapping path patterns to required role/permissions or boolean. */
+    rules?: Record<string, any>;
+    /**
+     * Base route prefix for auto-injected auth endpoints.
+     *
+     * @default "/api/auth"
+     */
+    prefix?: string;
+    /**
+     * Enabled OAuth providers (e.g. ['github', 'google', 'discord']). Auto-uses
+     * `NUXT_OAUTH_<PROVIDER>_CLIENT_ID` and `_CLIENT_SECRET`.
+     */
+    providers?: string[];
+    /**
+     * Automatic account linking for accounts sharing the same verified email address. Enforces
+     * dual-verified email check.
+     *
+     * @default true
+     */
+    linkAccounts?: boolean;
+    /** Redirect paths for auth flows. */
+    redirect?: AuthRedirectConfig;
+    /** Session storage configuration. */
+    session?: AuthSessionConfig;
+    /** Passwordless authentication (OTP / Magic Links). */
+    passwordless?: AuthPasswordlessConfig;
+    /** Declarative custom user fields (Tier 2). */
+    fields?: AuthFieldsConfig;
+    /**
+     * Enable Two-Factor Authentication (TOTP Authenticator Apps).
+     *
+     * @default false
+     */
+    twoFactor?: boolean;
+    /**
+     * Enable Multi-tenant Organizations & Teams.
+     *
+     * @default false
+     */
+    organizations?: boolean;
+    /**
+     * Enable Admin Impersonation.
+     *
+     * @default false
+     */
+    impersonation?: boolean;
+    /**
+     * Enable WebAuthn / Passkeys.
+     *
+     * @default false
+     */
+    webauthn?: boolean;
+    /**
+     * Alias for `webauthn`. Enable WebAuthn / Passkeys.
+     *
+     * @default false
+     */
+    webAuthn?: boolean;
+    /**
+     * Enable Personal Access Tokens (CLI keys).
+     *
+     * @default false
+     */
+    apiTokens?: boolean;
+    /**
+     * Enterprise: Cloudflare Turnstile bot and abuse protection.
+     */
+    turnstile?: boolean | AuthTurnstileConfig;
+    /**
+     * Enterprise: Mandatory Multi-Factor Authentication enforcement policies.
+     */
+    mfa?: AuthMfaConfig;
+    /**
+     * Enterprise: SAML 2.0 & Enterprise OIDC Single Sign-On (SSO).
+     *
+     * @default false
+     */
+    sso?: boolean | AuthSSOConfig;
+    /**
+     * Enterprise / GDPR: Self-serve account deletion settings.
+     */
+    accountDeletion?: boolean | AuthAccountDeletionConfig;
+}
+export interface AuthTurnstileConfig {
+    /** Turnstile secret key (or set NUXT_TURNSTILE_SECRET_KEY). */
+    secretKey?: string;
+    /** Turnstile public site key. */
+    siteKey?: string;
+    /** Automatic protection toggles for auth operations. */
+    protect?: {
+        login?: boolean;
+        register?: boolean;
+        otp?: boolean;
+        magicLink?: boolean;
+        accountDelete?: boolean;
+    };
+}
+export interface AuthMfaConfig {
+    /**
+     * Policy for MFA enforcement:
+     * - false / undefined: Optional MFA
+     * - true: Enforced for all authenticated users
+     * - "org": Enforced if user's current organization has mfaRequired set
+     * - "role": Enforced if user's role is in roles
+     */
+    enforce?: boolean | "org" | "role";
+    /** Roles that require MFA when enforce === "role" (default: ['admin', 'owner']) */
+    roles?: string[];
+    /** Redirect path when MFA is required but unverified (default: "/auth/2fa/verify") */
+    redirect?: string;
+}
+export interface AuthSSOConfig {
+    /** Enable Enterprise SSO endpoints & database tables. */
+    enabled?: boolean;
+    /** Default organization role for new users created via SSO (default: "member"). */
+    defaultRole?: string;
+    /** Allow automated self-registration for matching SSO domains (default: true). */
+    allowSelfRegistration?: boolean;
+}
+export interface AuthAccountDeletionConfig {
+    /** Allow users to delete their account self-serve (default: true). */
+    enabled?: boolean;
+    /** Require Cloudflare Turnstile verification token before deleting (default: false). */
+    requireTurnstile?: boolean;
+    /** Require explicit confirmation phrase (e.g. "DELETE") (default: false). */
+    requireConfirmationPhrase?: boolean;
+    /** Confirmation phrase string (default: "DELETE"). */
+    confirmationPhrase?: string;
+    /** Allow cascade deleting owned organizations if user is sole owner (default: false). */
+    allowOrgCascade?: boolean;
+}
+export interface QarpeoSSOConnection {
+    id: string;
+    organizationId?: string | null;
+    providerType: "saml" | "oidc";
+    name: string;
+    domain?: string | null;
+    clientId?: string | null;
+    clientSecret?: string | null;
+    issuer?: string | null;
+    ssoUrl: string;
+    tokenUrl?: string | null;
+    userinfoUrl?: string | null;
+    cert?: string | null;
+    enabled: boolean;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface DeleteAccountOptions {
+    confirm?: boolean;
+    phrase?: string;
+    turnstileToken?: string;
+    cascadeOrg?: boolean;
+}
+export interface StorageImagePreset {
+    width?: number;
+    height?: number;
+    quality?: number;
+    format?: "webp" | "avif" | "jpeg" | "png";
+    fit?: "cover" | "contain" | "scale-down" | "crop" | "pad";
+}
+export interface JobsOptions {
+    /**
+     * Cloudflare Queue binding name override.
+     *
+     * @default "QUEUE"
+     */
+    binding?: string;
+    /**
+     * Directory where background jobs are located.
+     *
+     * @default "server/jobs"
+     */
+    dir?: string;
+    /**
+     * Maximum retry attempts for failed jobs.
+     *
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * Maximum batch size delivered to consumer.
+     *
+     * @default 10
+     */
+    maxBatchSize?: number;
+    /**
+     * Maximum batch timeout in seconds before delivering.
+     *
+     * @default 5
+     */
+    maxBatchTimeout?: number;
+}
+export interface JobContext {
+    /** Unique message/job ID */
+    id: string;
+    /** Timestamp when the job was dispatched */
+    timestamp: Date;
+    /** Delivery attempt count (starts at 1) */
+    attempts: number;
+    /** Name of the job being executed */
+    jobName: string;
+    /** Manually request a retry for this message */
+    retry: () => void;
+    /** Manually acknowledge this message */
+    ack: () => void;
+}
+export type JobHandler<T = any> = (data: T, context: JobContext) => Promise<void> | void;
+export interface JobDefinitionOptions {
+    /** Override queue binding */
+    binding?: string;
+    /** Max retries before dead-letter */
+    maxRetries?: number;
+}
+export interface JobDefinition<T = any> {
+    name: string;
+    handler: JobHandler<T>;
+    options?: JobDefinitionOptions;
+}
+export interface AppRateLimitRule {
+    /** Max requests permitted in the time window */
+    max?: number;
+    /** Time window (e.g. '1m', '10s', '1h', or seconds) */
+    window?: string | number;
+    /** Optional custom identifier/key or grouping */
+    key?: string;
+}
+export interface RateLimitCheckResult {
+    /** Whether the request is permitted */
+    success: boolean;
+    /** Number of remaining requests permitted in the current window */
+    remaining: number;
+    /** Max limit for this window */
+    limit: number;
+    /** Seconds until the rate limit window resets */
+    reset: number;
+}
+export interface CheckRateLimitOptions extends AppRateLimitRule {
+    /** Optional custom identifier/key to rate limit against (defaults to client IP + route path) */
+    key?: string;
+    /** Storage backend override ('auto' | 'kv' | 'memory') */
+    backend?: "auto" | "kv" | "memory";
+    /** Custom binding name override */
+    binding?: string;
+    /** Custom error message when rate limit is exceeded */
+    message?: string;
+    /** Explicit event context */
+    event?: any;
+}
+export interface AppRateLimitOptions extends RateLimitConfig {
+    /** Whether edge rate limiting is enabled. */
+    enabled?: boolean;
+    /** Whether rate limiting applies globally to all routes not matched by `rules`. */
+    global?: boolean;
+    /**
+     * Max requests permitted within default window.
+     *
+     * @default 100
+     */
+    max?: number;
+    /**
+     * Default time window (e.g. '1m', '10s', '1h', or seconds).
+     *
+     * @default "1m"
+     */
+    window?: string | number;
+    /** IP whitelist that bypasses rate limiting. */
+    ipWhitelist?: string[];
+    /**
+     * Per-route rate limiting rules mapping path patterns to rules.
+     *
+     * @example
+     *   rules: {
+     *   '/api/auth/**': { max: 5, window: '1m' },
+     *   '/api/search': { max: 30, window: '1m' },
+     *   }
+     */
+    rules?: Record<string, AppRateLimitRule>;
+    /**
+     * Storage backend for rate limit counters.
+     *
+     * - 'auto': uses native Cloudflare RateLimiter binding if available, falls back to KV or memory
+     * - 'kv': Cloudflare KV
+     * - 'memory': in-memory sliding window
+     *
+     * @default "auto"
+     */
+    backend?: "auto" | "kv" | "memory";
+}
+export type AgentRole = "user" | "assistant" | "system" | "tool";
+export interface AgentMessage {
+    id?: string;
+    role: AgentRole;
+    content: string;
+    name?: string;
+    toolCalls?: Array<{
+        id: string;
+        name: string;
+        arguments: any;
+    }>;
+    toolCallId?: string;
+    createdAt?: number;
+}
+export interface AgentTool<TParams = any, TResult = any> {
+    name?: string;
+    description: string;
+    parameters?: Record<string, any>;
+    execute: (params: TParams, context?: any) => Promise<TResult> | TResult;
+}
+export interface AgentContext {
+    agentId: string;
+    agentName: string;
+    state: Record<string, any>;
+    setState: (state: Record<string, any>) => Promise<void>;
+    messages: AgentMessage[];
+    saveMessages: (messages: AgentMessage[]) => Promise<void>;
+    tools: Record<string, AgentTool>;
+    env: Record<string, any>;
+    setAlarm: (timestamp: number | Date) => Promise<void>;
+}
+export interface AgentDefinition {
+    name: string;
+    model?: string;
+    system?: string;
+    tools?: Record<string, AgentTool> | AgentTool[];
+    maxSteps?: number;
+    maxTokens?: number;
+    temperature?: number;
+    maxContextMessages?: number;
+    onMessage?: (message: AgentMessage, context: AgentContext) => Promise<string | void> | string | void;
+}
+export interface AgentsOptions {
+    /**
+     * Cloudflare Durable Object binding name for agents.
+     *
+     * @default "QARPEO_AGENT_DO"
+     */
+    binding?: string;
+    /**
+     * Directory where agent files are located.
+     *
+     * @default "server/agents"
+     */
+    dir?: string;
+    /**
+     * Default Workers AI model to use.
+     *
+     * @default "@cf/meta/llama-3.3-70b-instruct"
+     */
+    defaultModel?: string;
+    /**
+     * Base API route path for agents.
+     *
+     * @default "/api/agents"
+     */
+    path?: string;
+    /**
+     * Require active user session to access agent endpoints.
+     *
+     * @default false
+     */
+    requireAuth?: boolean;
+    /** Alias for `requireAuth`. */
+    auth?: boolean;
+    /**
+     * Maximum autonomous tool execution steps before stopping.
+     *
+     * @default 5
+     */
+    maxSteps?: number;
+    /**
+     * Maximum messages preserved in context history sliding window.
+     *
+     * @default 30
+     */
+    maxContextMessages?: number;
+}
+export type BotProvider = "telegram" | "slack" | "discord" | "github" | "whatsapp" | "generic";
+export interface BotMessageSender {
+    id: string;
+    name?: string;
+    username?: string;
+    avatarUrl?: string;
+}
+export interface BotMessage {
+    id: string;
+    text: string;
+    chatId: string;
+    channelId?: string;
+    sender?: BotMessageSender;
+    isCommand?: boolean;
+    command?: string;
+    args?: string[];
+    raw?: any;
+}
+export interface BotReplyOptions {
+    text: string;
+    parseMode?: "HTML" | "Markdown" | "MarkdownV2";
+    replyToMessageId?: string;
+    ephemeral?: boolean;
+    metadata?: Record<string, any>;
+    /**
+     * Enable or customize RFC 2369 / RFC 8058 List-Unsubscribe headers for this message.
+     * Set alse to disable for transactional emails (e.g. OTP, password reset).
+     */
+    unsubscribe?: boolean | {
+        url?: string;
+        email?: string;
+    };
+    /**
+     * Whether to check the suppression list before sending. Set alse to bypass
+     * suppression checks for critical security or transactional emails.
+     * @default true
+     */
+    suppression?: boolean;
+}
+export interface BotContext<TPayload = any> {
+    provider: BotProvider;
+    event: any;
+    rawBody: string;
+    payload: TPayload;
+    message?: BotMessage;
+    query: Record<string, any>;
+    headers: Record<string, string | undefined>;
+    reply: (textOrOptions: string | BotReplyOptions) => Promise<any>;
+    agent: (agentName: string, id?: string) => any;
+}
+export interface BotHandlerConfig<TPayload = any> {
+    /** The bot/webhook provider platform */
+    provider: BotProvider;
+    /**
+     * Secret or token used to verify incoming webhook signatures:
+     * - Telegram: secret_token configured in setWebhook
+     * - Slack: Signing Secret
+     * - Discord: Public Key (hex string)
+     * - GitHub: Webhook secret
+     * - WhatsApp: Meta App Secret
+     * - Generic: Secret token or HMAC secret
+     */
+    secret?: string;
+    /**
+     * Bot API token or credentials for sending replies:
+     * - Telegram: Bot Token from @BotFather (`TELEGRAM_BOT_TOKEN`)
+     * - Slack: Bot User OAuth Token `xoxb-...` (`SLACK_BOT_TOKEN`)
+     * - Discord: Bot Token (`DISCORD_BOT_TOKEN`)
+     * - WhatsApp: Meta System User Access Token (`WHATSAPP_ACCESS_TOKEN`)
+     */
+    botToken?: string;
+    /** Phone Number ID for WhatsApp Cloud API (falls back to `WHATSAPP_PHONE_NUMBER_ID`) */
+    phoneNumberId?: string;
+    /** Verify token for WhatsApp Cloud API GET challenge verification (falls back to `WHATSAPP_VERIFY_TOKEN`) */
+    verifyToken?: string;
+    /**
+     * Optional name of a Qarpeo agent to auto-wire. Incoming user messages are automatically sent
+     * to this agent and the agent's response is dispatched back to the chat platform.
+     */
+    agent?: string;
+    /**
+     * Custom session ID resolver for auto-wired agents. Defaults to `(msg) => msg.chatId`.
+     */
+    agentSessionId?: (message: BotMessage, event: any) => string;
+    /**
+     * Custom hook called whenever a text message is received.
+     */
+    onMessage?: (ctx: BotContext<TPayload>) => Promise<any> | any;
+    /**
+     * Custom hook called for any incoming platform event/action (e.g. Slack button clicks, GitHub push).
+     */
+    onEvent?: (eventName: string, ctx: BotContext<TPayload>) => Promise<any> | any;
+    /**
+     * Custom signature verification validator if you wish to override the default verification.
+     */
+    verifySignature?: (event: any, rawBody: string) => Promise<boolean> | boolean;
+}
+export interface ChunkOptions {
+    /** Maximum number of characters per chunk (default: 800) */
+    chunkSize?: number;
+    /** Number of characters of overlap between consecutive chunks (default: 100) */
+    chunkOverlap?: number;
+    /** Custom separator pattern or array of separators in priority order (default: ['\n\n', '\n', '. ', ' ']) */
+    separators?: string[];
+}
+export interface RAGDocument {
+    /** Unique document identifier */
+    id: string;
+    /** Full text content of the document */
+    text: string;
+    /** Optional metadata attached to every chunk of this document (e.g. title, url, author, category) */
+    metadata?: Record<string, any>;
+    /** Optional namespace within the Vectorize index */
+    namespace?: string;
+}
+export interface RAGChunk {
+    /** Unique chunk ID, e.g. `<docId>#chunk-<index>` */
+    id: string;
+    /** The text slice of this chunk */
+    text: string;
+    /** Parent document ID */
+    documentId: string;
+    /** 0-based index of the chunk */
+    chunkIndex: number;
+    /** Total number of chunks for this document */
+    totalChunks: number;
+    /** Merged document and chunk metadata */
+    metadata: Record<string, any>;
+}
+export interface RAGPipelineConfig {
+    /**
+     * Vectorize index binding name.
+     *
+     * @default "VECTORIZE"
+     */
+    binding?: string;
+    /**
+     * Workers AI binding name.
+     *
+     * @default "AI"
+     */
+    aiBinding?: string;
+    /**
+     * Embedding model to use.
+     *
+     * @default "@cf/baai/bge-base-en-v1.5"
+     */
+    embeddingModel?: string;
+    /**
+     * Generative LLM to use for answer generation.
+     *
+     * @default "@cf/meta/llama-3.3-70b-instruct"
+     */
+    llmModel?: string;
+    /** Default chunking parameters */
+    chunking?: ChunkOptions;
+    /** Default namespace for this pipeline */
+    namespace?: string;
+    /** Optional event context for binding resolution */
+    event?: any;
+}
+export interface RAGQueryOptions {
+    /** Maximum number of top matching chunks to retrieve (default: 5) */
+    topK?: number;
+    /** Minimum similarity score threshold (0.0 to 1.0) */
+    minScore?: number;
+    /** Metadata filter object */
+    filter?: Record<string, any>;
+    /** Namespace override */
+    namespace?: string;
+    /** Event context */
+    event?: any;
+}
+export interface RAGChunkMatch extends RAGChunk {
+    /** Similarity score (higher is more similar, typically 0.0 to 1.0) */
+    score: number;
+}
+export interface RAGContextResult {
+    /** Formatted markdown context string ready to inject into prompt */
+    contextText: string;
+    /** The matched chunks with scores and metadata */
+    matches: RAGChunkMatch[];
+}
+export interface RAGAnswerOptions extends RAGQueryOptions {
+    /** Custom system prompt instructions for answer generation */
+    system?: string;
+    /** Temperature for generation (default: 0.2) */
+    temperature?: number;
+    /** Maximum generation tokens */
+    maxTokens?: number;
+}
+export interface RAGAnswerResult {
+    /** Generated answer text */
+    answer: string;
+    /** Source chunks cited/used in answering */
+    sources: RAGChunkMatch[];
+    /** Query text */
+    query: string;
+}
+export interface RAGPipeline {
+    /** Splits raw text into overlapping contextual chunks */
+    chunkText(text: string, options?: ChunkOptions): string[];
+    /** Ingests and indexes a single document into Vectorize */
+    indexDocument(doc: RAGDocument, options?: {
+        chunking?: ChunkOptions;
+        event?: any;
+    }): Promise<{
+        chunksIndexed: number;
+        mutationId?: string;
+    }>;
+    /** Ingests and indexes multiple documents in batches */
+    indexDocuments(docs: RAGDocument[], options?: {
+        chunking?: ChunkOptions;
+        batchSize?: number;
+        event?: any;
+    }): Promise<{
+        totalIndexed: number;
+        totalChunks: number;
+    }>;
+    /** Deletes a document and all its chunks from the index */
+    deleteDocument(documentId: string, options?: {
+        maxChunks?: number;
+        event?: any;
+    }): Promise<void>;
+    /** Searches for most relevant chunks matching the query text */
+    query(queryText: string, options?: RAGQueryOptions): Promise<RAGChunkMatch[]>;
+    /** Retrieves matching chunks and formats them into an LLM context block */
+    retrieveContext(queryText: string, options?: RAGQueryOptions): Promise<RAGContextResult>;
+    /** Directly answers a user question using grounded RAG retrieval + LLM synthesis */
+    answer(queryText: string, options?: RAGAnswerOptions): Promise<RAGAnswerResult>;
+    /** Exports this pipeline as a typed tool for `defineAgent({ tools: { ... } })` */
+    asTool(options?: {
+        name?: string;
+        description?: string;
+        topK?: number;
+        minScore?: number;
+    }): AgentTool;
+}
+export interface AnalyticsOptions {
+    /**
+     * Cloudflare Analytics Engine binding name.
+     *
+     * @default "ANALYTICS"
+     */
+    binding?: string;
+    /**
+     * Cloudflare Analytics Engine dataset name (used in wrangler.json). Defaults to
+     * `<binding-lowercase>-prod` in production, `<binding-lowercase>-local-dev` in dev.
+     */
+    dataset?: string;
+    /**
+     * Cloudflare Account ID — required for the SQL API (read queries / dashboard). Falls back to
+     * `CLOUDFLARE_ACCOUNT_ID` environment variable.
+     */
+    accountId?: string;
+    /**
+     * Cloudflare API token with Analytics Engine read permissions. Falls back to
+     * `CLOUDFLARE_API_TOKEN` environment variable.
+     */
+    apiToken?: string;
+    /**
+     * Site identifier written to `indexes[0]` on every data point. Useful when a single AE dataset
+     * tracks multiple sites. Falls back to the request hostname.
+     */
+    siteId?: string;
+    /**
+     * Automatically track a pageview on every non-API SSR request via a server middleware.
+     *
+     * @default true
+     */
+    autoTrack?: boolean;
+    /**
+     * Base path for the analytics dashboard API routes.
+     *
+     * @default "/api/analytics"
+     */
+    path?: string;
+}
+/** Time range shorthand for dashboard queries. */
+export type AnalyticsRange = "1h" | "24h" | "7d" | "30d" | "90d";
+/** A single time-series bucket returned by AE SQL queries. */
+export interface AnalyticsTimeSeriesPoint {
+    date: string;
+    count: number;
+}
+/** Pageview summary returned by the dashboard API. */
+export interface PageviewSummary {
+    total: number;
+    series: AnalyticsTimeSeriesPoint[];
+}
+/** KPI summary returned by `/api/analytics/summary`. */
+export interface AnalyticsSummary {
+    pageviews: number;
+    visitors: number;
+    topPages: Array<{
+        path: string;
+        views: number;
+    }>;
+    topReferrers: Array<{
+        referrer: string;
+        count: number;
+    }>;
+    countries: Array<{
+        country: string;
+        count: number;
+    }>;
+    devices: {
+        mobile: number;
+        desktop: number;
+        bot: number;
+    };
+}
+/** Tracked event record returned by `/api/analytics/events`. */
+export interface AnalyticsEventRecord {
+    name: string;
+    count: number;
+    lastSeen: string;
+}
+export type DomainStatus = "pending" | "active" | "error" | "deleting";
+export type DomainSslStatus = "initializing" | "pending_validation" | "active" | "expired";
+export type DomainProviderType = "cloudflare" | "custom";
+export interface DomainVerificationRecord {
+    type: "cname" | "txt";
+    name: string;
+    value: string;
+    target?: string;
+}
+export interface CustomDomainRecord {
+    id: string;
+    tenantId: string;
+    domain: string;
+    status: DomainStatus;
+    sslStatus: DomainSslStatus;
+    verificationRecords?: DomainVerificationRecord[];
+    cnameTarget?: string;
+    cloudflareHostnameId?: string;
+    errorMessage?: string;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface TenantRecord {
+    id: string;
+    slug: string;
+    name: string;
+    plan?: string;
+    organizationId?: string;
+    customDomain?: string;
+    logoUrl?: string;
+    metadata?: Record<string, any>;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface MultitenantOptions {
+    /**
+     * Root / apex domain(s) for subdomain matching (e.g. "qarpeo.com" or ["qarpeo.com",
+     * "qarpeo.dev"]). Requests matching `<tenant>.<rootDomain>` will automatically resolve to that
+     * tenant slug.
+     */
+    rootDomains?: string | string[];
+    /**
+     * Enable Custom Domains with automated SSL and DNS verification via Cloudflare for SaaS.
+     *
+     * @default true
+     */
+    customDomains?: boolean;
+    /**
+     * Domain provider for custom hostnames and SSL certificate provisioning. Currently supports
+     * "cloudflare" (Cloudflare for SaaS Custom Hostnames API), with extensible architecture for other
+     * providers.
+     *
+     * @default "cloudflare"
+     */
+    provider?: DomainProviderType;
+    /**
+     * Cloudflare Zone ID for Custom Hostnames API. Falls back to `CLOUDFLARE_ZONE_ID` environment
+     * variable.
+     */
+    zoneId?: string;
+    /**
+     * Cloudflare API token with SSL and Custom Hostnames permissions. Falls back to
+     * `CLOUDFLARE_API_TOKEN` environment variable.
+     */
+    apiToken?: string;
+    /** CNAME fallback target that custom domains must point to (e.g. "cname.myapp.com"). */
+    cnameTarget?: string;
+    /**
+     * Reserved tenant slugs that cannot be registered or resolved as subdomains.
+     *
+     * @default ["admin", "api", "app", "auth", "cms", "dashboard", "mail", "static", "studio", "www"]
+     */
+    reservedSlugs?: string[];
+    /**
+     * Header name to check for tenant ID / slug override (useful for API and local dev testing).
+     *
+     * @default "x-tenant-id"
+     */
+    headerName?: string;
+    /**
+     * Base API path for tenant domain endpoints.
+     *
+     * @default "/api/tenants"
+     */
+    path?: string;
+    /**
+     * KV binding name used for high-speed edge domain-to-tenant lookup cache.
+     *
+     * @default "KV"
+     */
+    kvBinding?: string;
+}
+export interface StreamTextOptions {
+    model?: string;
+    prompt?: string;
+    messages?: AgentMessage[];
+    system?: string;
+    tools?: Record<string, AgentTool>;
+    maxSteps?: number;
+    maxTokens?: number;
+    temperature?: number;
+    binding?: string;
+    event?: any;
+}
+export interface GenerateImageOptions {
+    /** The text prompt describing the image to generate */
+    prompt: string;
+    /** Negative prompt describing what to avoid in the generation */
+    negativePrompt?: string;
+    /**
+     * The model to use.
+     *
+     * @default "@cf/black-forest-labs/flux-1-schnell"
+     * Other common options:
+     * - "@cf/stabilityai/stable-diffusion-xl-base-1.0"
+     * - "@cf/bytedance/stable-diffusion-xl-lightning"
+     * - "@cf/runwayml/stable-diffusion-v1-5"
+     */
+    model?: string;
+    /** Number of diffusion steps (schnell default: 4, sdxl default: 20) */
+    steps?: number;
+    /** Output image width (default: 1024 or 512 depending on model) */
+    width?: number;
+    /** Output image height (default: 1024 or 512 depending on model) */
+    height?: number;
+    /** Classifier-free guidance scale (for SDXL/SD1.5) */
+    guidance?: number;
+    /** Random seed for reproducible generation */
+    seed?: number;
+    /** Optional source image for image-to-image (img2img) tasks */
+    image?: Uint8Array | ArrayBuffer | Blob | Array<number> | string;
+    /** Strength / denoising factor for image-to-image (0.0 to 1.0) */
+    strength?: number;
+    /** Desired output format / MIME type */
+    format?: "png" | "jpeg" | "webp";
+    /** Binding name or override (defaults to "AI") */
+    binding?: string;
+    /** Event context for binding resolution */
+    event?: any;
+    /** Cloudflare AI Gateway options */
+    gateway?: {
+        id: string;
+        skipCache?: boolean;
+        cacheTtl?: number;
+    };
+}
+export interface GenerateImageResult {
+    /** Binary bytes of the generated image */
+    uint8Array: Uint8Array;
+    /** ArrayBuffer representation */
+    arrayBuffer: ArrayBuffer;
+    /** Base64 string without data prefix */
+    base64: string;
+    /** Ready-to-use data URL (e.g. data:image/png;base64,...) */
+    dataUrl: string;
+    /** MIME type (e.g. "image/png" or "image/jpeg") */
+    mimeType: string;
+    /** Width in pixels if specified/known */
+    width?: number;
+    /** Height in pixels if specified/known */
+    height?: number;
+    /** Returns a Web Standard Response with Content-Type and Cache-Control headers */
+    toResponse(headers?: HeadersInit): Response;
+    /**
+     * Persist this image directly to Qarpeo's R2 Blob storage.
+     *
+     * @param key Blob path/key to save to (e.g. "generated/avatar.png")
+     */
+    saveToBlob(key: string, options?: {
+        binding?: string;
+        event?: any;
+        contentType?: string;
+    }): Promise<any>;
+}
+export interface GenerateSpeechOptions {
+    /** The text script to convert into spoken audio */
+    text: string;
+    /**
+     * The TTS model to use.
+     *
+     * @default "@cf/meta/mms-tts-eng"
+     * Other common options:
+     * - "@cf/myshell-ai/melotts-english"
+     * - "@cf/meta/mms-tts-fra"
+     * - "@cf/meta/mms-tts-spa"
+     * - "@cf/meta/mms-tts-deu"
+     */
+    model?: string;
+    /** Language code (e.g. "en", "eng", "es", "fr", "de") */
+    lang?: string;
+    /** Voice name or preset (for models that support multiple voices) */
+    voice?: string;
+    /** Speech rate / speed multiplier (e.g. 1.0) */
+    speed?: number;
+    /** Binding name override */
+    binding?: string;
+    /** Event context */
+    event?: any;
+    /** Cloudflare AI Gateway options */
+    gateway?: {
+        id: string;
+        skipCache?: boolean;
+        cacheTtl?: number;
+    };
+}
+export interface GenerateSpeechResult {
+    /** Binary bytes of the generated audio */
+    uint8Array: Uint8Array;
+    /** ArrayBuffer representation */
+    arrayBuffer: ArrayBuffer;
+    /** Base64 string */
+    base64: string;
+    /** Ready-to-use data URL (e.g. data:audio/wav;base64,...) */
+    dataUrl: string;
+    /** Audio MIME type, e.g. "audio/wav" */
+    mimeType: string;
+    /** Returns a Web Standard Response with Content-Type header */
+    toResponse(headers?: HeadersInit): Response;
+    /** Persist directly to R2 Blob storage */
+    saveToBlob(key: string, options?: {
+        binding?: string;
+        event?: any;
+        contentType?: string;
+    }): Promise<any>;
+}
+export type TranscribeAudioInput = Uint8Array | ArrayBuffer | Blob | Array<number> | string;
+export interface TranscribeAudioOptions {
+    /** Audio data as Uint8Array, ArrayBuffer, Blob, number array, or Base64 string */
+    audio: TranscribeAudioInput;
+    /**
+     * The STT model to use.
+     *
+     * @default "@cf/openai/whisper"
+     * Other options:
+     * - "@cf/openai/whisper-tiny-en"
+     * - "@cf/openai/whisper-large-v3-turbo"
+     */
+    model?: string;
+    /** Language spoken in the audio (e.g. "en", "es", "fr", "de") */
+    language?: string;
+    /** Task: 'transcribe' (default) or 'translate' (translates spoken audio into English) */
+    task?: "transcribe" | "translate";
+    /** Whether to generate word-level timestamp intervals */
+    timestamps?: boolean;
+    /** Initial prompt / vocabulary hint to guide transcription accuracy */
+    prompt?: string;
+    /** Binding name override */
+    binding?: string;
+    /** Event context */
+    event?: any;
+    /** Cloudflare AI Gateway options */
+    gateway?: {
+        id: string;
+        skipCache?: boolean;
+        cacheTtl?: number;
+    };
+}
+export interface TranscribeAudioResult {
+    /** The transcribed text */
+    text: string;
+    /** Approximate or exact word count */
+    wordCount: number;
+    /** Word-level timestamps and tokens if returned by the model */
+    words?: Array<{
+        word: string;
+        start: number;
+        end: number;
+    }>;
+    /** WebVTT subtitles format if returned */
+    vtt?: string;
+    /** Language detected by the model if available */
+    language?: string;
+    /** Raw output object directly from Cloudflare Workers AI */
+    raw: any;
+}
+export type EmailTemplateName = "welcome" | "magic-link" | "otp" | "order-confirmation" | "invite" | "notification" | string;
+export interface MailTemplateOptions {
+    brandColor?: string;
+    logoUrl?: string;
+    companyName?: string;
+    supportEmail?: string;
+}
+export interface EmailTemplateResult {
+    subject?: string;
+    html: string;
+    text?: string;
+}
+export type EmailTemplateHandler<T = any> = (data: T, branding?: MailTemplateOptions) => EmailTemplateResult | Promise<EmailTemplateResult>;
+export interface MailTrackingOptions {
+    /**
+     * Track email open events via an invisible 1x1 tracking pixel.
+     *
+     * @default false
+     */
+    opens?: boolean;
+    /**
+     * Track link clicks by rewriting outgoing HTML links.
+     *
+     * @default false
+     */
+    clicks?: boolean;
+    /**
+     * Base URL used for tracking links and pixels (e.g. "https://myapp.com").
+     * Defaults to request host or site URL.
+     */
+    baseUrl?: string;
+}
+export type MailSuppressionReason = "bounce" | "complaint" | "unsubscribe" | "manual";
+export type MailSuppressionType = "hard_bounce" | "soft_bounce" | "spam_complaint" | "unsubscribe" | "manual";
+export interface MailSuppressionRecord {
+    id: string;
+    email: string;
+    reason: MailSuppressionReason;
+    type: MailSuppressionType;
+    source?: string;
+    metadata?: Record<string, any>;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface MailSuppressionOptions {
+    /**
+     * Automatically add emails to the suppression list upon hard bounce, spam complaints, or unsubscribes.
+     * @default true
+     */
+    autoSuppress?: boolean;
+    /**
+     * Enforce suppression checks prior to dispatching outgoing mail.
+     * Suppressed addresses are automatically filtered out to protect sender domain reputation.
+     * @default true
+     */
+    enforce?: boolean;
+    /**
+     * Number of consecutive soft bounces before an address is permanently suppressed.
+     * @default 3
+     */
+    softBounceThreshold?: number;
+}
+export interface MailUnsubscribeOptions {
+    /**
+     * Automatically generate and inject RFC 2369 & RFC 8058 compliant `List-Unsubscribe`
+     * and `List-Unsubscribe-Post: List-Unsubscribe=One-Click` headers.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Custom unsubscribe URL or base path (e.g. "https://myapp.com/api/mail/unsubscribe").
+     */
+    url?: string;
+    /**
+     * Mailto fallback address for List-Unsubscribe header (e.g. "unsubscribe@myapp.com").
+     */
+    email?: string;
+    /**
+     * Secret key used to sign HMAC tokens for unsubscribe links.
+     * Defaults to auth secret or session secret.
+     */
+    secret?: string;
+}
+export interface SendMailRequest {
+    to: string | string[];
+    from?: string;
+    /** Email subject line. Optional when provided by a template. */
+    subject?: string;
+    template?: EmailTemplateName;
+    data?: Record<string, any>;
+    html?: string;
+    text?: string;
+    /**
+     * Markdown body content. Automatically parsed into responsive, email-client-safe HTML.
+     */
+    markdown?: string;
+    replyTo?: string;
+    cc?: string | string[];
+    bcc?: string | string[];
+    headers?: Record<string, string>;
+    /**
+     * Queue this email for asynchronous background delivery via Cloudflare Queues.
+     */
+    queue?: boolean;
+    /**
+     * Enable open/click tracking for this specific message.
+     */
+    track?: boolean | {
+        opens?: boolean;
+        clicks?: boolean;
+    };
+    /**
+     * Arbitrary metadata associated with this message for tracking, analytics, and webhooks.
+     */
+    metadata?: Record<string, any>;
+    /**
+     * Enable or customize RFC 2369 / RFC 8058 List-Unsubscribe headers for this message.
+     * Set alse to disable for transactional emails (e.g. OTP, password reset).
+     */
+    unsubscribe?: boolean | {
+        url?: string;
+        email?: string;
+    };
+    /**
+     * Whether to check the suppression list before sending. Set alse to bypass
+     * suppression checks for critical security or transactional emails.
+     * @default true
+     */
+    suppression?: boolean;
+}
+export interface MailResult {
+    success: boolean;
+    messageId: string;
+    timestamp: number;
+    previewUrl?: string;
+    queued?: boolean;
+    /** Whether the send was skipped because all recipients are suppressed */
+    suppressed?: boolean;
+    /** List of recipient addresses that were suppressed and excluded from delivery */
+    suppressedRecipients?: string[];
+}
+export interface MailOptions {
+    /** Default sender address (e.g. "My App <noreply@myapp.com>"). */
+    from?: string;
+    /**
+     * Delivery provider.
+     *
+     * - 'cloudflare': Cloudflare send_email binding (default)
+     * - 'resend': Resend API
+     * - 'postmark': Postmark API
+     * - 'dev': In-memory dev mailbox intercept only
+     *
+     * @default "cloudflare"
+     */
+    provider?: "cloudflare" | "resend" | "postmark" | "dev";
+    /** API Key for external providers (Resend, Postmark). */
+    apiKey?: string;
+    /** Branding options applied to built-in email templates. */
+    branding?: MailTemplateOptions;
+    /**
+     * Enable in-browser Dev Mailbox preview during local development.
+     *
+     * @default true
+     */
+    devMailbox?: boolean;
+    /**
+     * Enable queue-backed background email delivery using Cloudflare Queues.
+     * When true, messages sent with sendMail are enqueued and delivered asynchronously
+     * with automatic retries and exponential backoff.
+     *
+     * @default false
+     */
+    queue?: boolean | string;
+    /**
+     * Configure open and click tracking.
+     */
+    tracking?: MailTrackingOptions;
+    /**
+     * Email suppression list configuration for managing bounces, spam complaints, and unsubscribes.
+     *
+     * @default true
+     */
+    suppression?: boolean | MailSuppressionOptions;
+    /**
+     * RFC 2369 & RFC 8058 compliant List-Unsubscribe and one-click unsubscribe configuration.
+     *
+     * @default true
+     */
+    unsubscribe?: boolean | MailUnsubscribeOptions;
+}
+export interface CacheOptions {
+    /**
+     * Cloudflare KV binding name override for cache storage.
+     *
+     * @default "CACHE"
+     */
+    binding?: string;
+    /**
+     * Key prefix for cache entries in KV.
+     *
+     * @default "nitro:cache:"
+     */
+    base?: string;
+    /**
+     * Default Time-To-Live for cached items when not explicitly specified. Accepts number (seconds)
+     * or human string (e.g. '1h', '30m', '1d').
+     *
+     * @default "1h"
+     */
+    defaultTtl?: string | number;
+    /**
+     * Automatically configure Stale-While-Revalidate (SWR) headers for cached responses.
+     *
+     * @default true
+     */
+    swr?: boolean;
+}
+export type BlobAccessTier = "public" | "unlisted" | "private";
+export interface SignedDownloadUrlOptions {
+    /** Expiration duration (e.g. '1h', '15m', '7d', or seconds) */
+    expiresIn?: string | number;
+    /** Force browser download attachment */
+    download?: boolean;
+    /** Custom download filename override */
+    filename?: string;
+}
+export interface StorageOptions {
+    /**
+     * Custom Cloudflare R2 binding name.
+     *
+     * @default "BLOB"
+     */
+    binding?: string;
+    /**
+     * Base route prefix for auto-injected storage endpoints.
+     *
+     * @default "/api/storage"
+     */
+    prefix?: string;
+    /**
+     * Custom public CDN domain or URL prefix (e.g. 'https://cdn.example.com'). If omitted, files are
+     * served through Qarpeo's edge handler.
+     */
+    cdnUrl?: string;
+    /**
+     * Maximum allowed file upload size. Accepts number (bytes) or human string (e.g. '10MB',
+     * '500KB').
+     *
+     * @default "20MB"
+     */
+    maxSize?: string | number;
+    /**
+     * Allowed MIME types for uploaded files (e.g. ['image/*', 'application/pdf']).
+     *
+     * @default ["*"]
+     */
+    allowedTypes?: string[];
+    /**
+     * Automatic directory scoping for multi-tenancy.
+     *
+     * - 'org': files stored under `org_${orgId}/`
+     * - 'user': files stored under `user_${userId}/`
+     * - 'public': files stored directly under root prefix
+     *
+     * @default "public"
+     */
+    scope?: "org" | "user" | "public";
+    /**
+     * Default access tier for newly uploaded files.
+     *
+     * - 'public': accessible to anyone
+     * - 'unlisted': accessible via token-signed URL only
+     * - 'private': guarded by session & authentication
+     *
+     * @default "public"
+     */
+    defaultAccess?: BlobAccessTier;
+    /**
+     * Whether unauthenticated callers are allowed to generate presigned upload tickets. Defaults to
+     * false (authentication required).
+     *
+     * @default false
+     */
+    allowAnonymousUploads?: boolean;
+    /** Cloudflare Image Resizing / optimization presets and settings. */
+    images?: {
+        /**
+         * Enable Cloudflare Image Resizing (/cdn-cgi/image/...) on served URLs.
+         *
+         * @default true
+         */
+        resizing?: boolean;
+        /**
+         * Named transformation presets.
+         *
+         * @example
+         *   presets: {
+         *   thumbnail: { width: 150, height: 150, format: "webp" },
+         *   banner: { width: 1200, height: 400, quality: 85 }
+         *   }
+         */
+        presets?: Record<string, StorageImagePreset>;
+    };
+}
+export type BlobOptions = StorageOptions;
+export type CMSFieldType = "string" | "text" | "number" | "boolean" | "image" | "date" | "tags" | "json" | "reference" | "blocks" | "component";
+/**
+ * Options for a `reference` field, which links an entry to an entry in another collection (or the
+ * same collection). References are stored inside the entry's `metadata_json`.
+ */
+export interface CMSReferenceFieldOptions {
+    /** Target collection ID that this field references. */
+    to: string;
+    /** Allow multiple references. When `true` the value is stored as an array. */
+    multiple?: boolean;
+    /** Optional filter restricting which target entries may be referenced. */
+    filter?: Record<string, unknown>;
+}
+/** Stored shape of a single reference value inside entry `metadata_json`. */
+export interface CMSReferenceValue {
+    id: string;
+    collectionId: string;
+    slug: string;
+    title: string;
+}
+export interface CMSBlockDefinition {
+    label?: string;
+    icon?: string;
+    description?: string;
+    fields: Record<string, CMSFieldDefinition>;
+}
+export interface CMSBlockData {
+    _id?: string;
+    _type: string;
+    [key: string]: any;
+}
+export interface CMSComponentDefinition {
+    name?: string;
+    label?: string;
+    icon?: string;
+    description?: string;
+    fields: Record<string, CMSFieldDefinition>;
+}
+export interface CMSComponentFieldOptions {
+    /** Registered component name (from cms.components) or inline component definition */
+    name?: string;
+    /** Inline field definitions if not referencing a named component */
+    fields?: Record<string, CMSFieldDefinition>;
+    /** Whether this component field is a repeatable list (array of component objects) */
+    repeatable?: boolean;
+    /** Maximum items allowed if repeatable */
+    max?: number;
+    /** Minimum items required if repeatable */
+    min?: number;
+}
+export interface CMSFieldDefinition {
+    type: CMSFieldType;
+    label?: string;
+    description?: string;
+    required?: boolean;
+    default?: any;
+    options?: Array<{
+        label: string;
+        value: string;
+    }>;
+    /** Reference-specific options. Only used when `type` is `"reference"`. */
+    reference?: CMSReferenceFieldOptions;
+    /** Block schemas allowed in dynamic zones / page builders. Only used when `type` is `"blocks"`. */
+    blocks?: Record<string, CMSBlockDefinition>;
+    /** Reusable component options. Only used when `type` is `"component"`. */
+    component?: string | CMSComponentFieldOptions;
+    /** Shorthand to make a component field a repeatable list */
+    repeatable?: boolean;
+}
+export interface CMSCollectionConfig {
+    name?: string;
+    description?: string;
+    order?: number;
+    fields?: Record<string, CMSFieldDefinition>;
+    /**
+     * Directory inside project where markdown files live for this collection. Default:
+     * `content/<collection>`
+     */
+    directory?: string;
+    /**
+     * Path pattern(s) to automatically match files into this collection. Supports globs: e.g.
+     * `"/docs/**"` or `["/docs/**", "/guides/**"]`.
+     */
+    path?: string | string[];
+    /**
+     * Collection type.
+     *
+     * - `"content"` (default) — flat key/value entries, slug-based lookup
+     * - `"page"` — hierarchical markdown pages with path-based routing, TOC, MDC directives, and
+     *   navigation tree
+     */
+    type?: "content" | "page";
+    /**
+     * Whether to include this collection in the navigation tree. Set `false` or `{ hidden: true }` to
+     * hide from navigation links.
+     *
+     * @default true
+     */
+    navigation?: boolean | {
+        hidden?: boolean;
+        title?: string;
+        icon?: string;
+    };
+    /**
+     * Hide this collection from navigation links.
+     *
+     * @default false
+     */
+    hidden?: boolean;
+    /**
+     * Editorial workflow mode for this collection.
+     *
+     * - `'db'` (default) — Dashboard edits are authoritative. D1 owns the content after initial
+     *   seeding.
+     * - `'file-lock'` — Read-only in CMS Admin. Content is managed via Git files/PRs only.
+     * - `'git-sync'` — Dashboard edits write back to Git (via disk in dev, GitHub API in production).
+     */
+    mode?: "db" | "file-lock" | "git-sync";
+    /** Git sync configuration for this collection when mode is 'git-sync'. */
+    github?: CMSGitHubConfig;
+    /** Outgoing webhooks triggered by changes in this collection. */
+    webhooks?: CMSWebhookConfig[];
+    /** Deploy trigger settings for this collection. */
+    deploy?: CMSDeployTriggerConfig;
+    /**
+     * Editorial approval workflow configuration. When enabled, content mutations require approval
+     * before being published.
+     *
+     * - `true`: Requires an admin or second editor to approve before publish.
+     * - `{ roles: [...], allowSelfApproval: false }`: Fine-grained approval policy.
+     */
+    approval?: boolean | CMSApprovalConfig;
+    /**
+     * Supported locales for localized content (e.g. ["en", "es", "fr", "de"]).
+     *
+     * @default ["en"]
+     */
+    locales?: string[];
+    /**
+     * Default fallback locale for content resolution.
+     *
+     * @default "en"
+     */
+    defaultLocale?: string;
+    /**
+     * Enable scheduled publishing for this collection.
+     *
+     * @default false
+     */
+    scheduledPublish?: boolean;
+    /**
+     * Whether this collection is a singleton (max 1 entry, e.g. site settings).
+     *
+     * @default false
+     */
+    singleton?: boolean;
+}
+export interface CMSApprovalConfig {
+    /**
+     * Roles authorized to approve and publish entries in this collection.
+     *
+     * @default ["admin"]
+     */
+    roles?: string[];
+    /**
+     * Whether the author of an entry is permitted to approve their own entry. When `false`, a
+     * different team member with an approver role must approve it.
+     *
+     * @default false
+     */
+    allowSelfApproval?: boolean;
+}
+export interface CMSGitHubConfig {
+    /**
+     * GitHub repository in "owner/repo" format. e.g. "qarpeo/qarpeo.com" Can also be inferred from
+     * process.env.GITHUB_REPOSITORY.
+     */
+    repo?: string;
+    /**
+     * Target branch for direct commits.
+     *
+     * @default "main"
+     */
+    branch?: string;
+    /**
+     * Whether to open a Pull Request instead of committing directly to the branch.
+     *
+     * @default false
+     */
+    pr?: boolean;
+    /**
+     * Base branch to open PR against if `pr: true`.
+     *
+     * @default "main"
+     */
+    prBase?: string;
+    /**
+     * Branch prefix when creating a branch for PR.
+     *
+     * @default "content/"
+     */
+    branchPrefix?: string;
+    /**
+     * Commit message template. Supports placeholders: `{collection}`, `{slug}`, `{action}` (create,
+     * update, delete)
+     *
+     * @default "content({collection}): {action} {slug}"
+     */
+    commitMessage?: string;
+    /**
+     * GitHub personal access token with contents:write permission. Falls back to
+     * `process.env.GITHUB_TOKEN` or `GH_TOKEN`.
+     */
+    token?: string;
+    /**
+     * Secret used to verify incoming GitHub webhook signatures (`X-Hub-Signature-256`).
+     * Falls back to `process.env.GITHUB_WEBHOOK_SECRET` or `cms.webhookSecret`.
+     */
+    webhookSecret?: string;
+}
+export interface CMSWebhookConfig {
+    /** Target endpoint URL to send HTTP POST request */
+    url: string;
+    /**
+     * Action events that trigger this webhook.
+     *
+     * @default ["publish", "unpublish"]
+     */
+    events?: Array<"create" | "update" | "delete" | "publish" | "unpublish">;
+    /** Optional secret for HMAC-SHA256 signature in `X-Qarpeo-Signature` header (`sha256=<hex>`). */
+    secret?: string;
+    /** Custom headers to include with the webhook POST request. */
+    headers?: Record<string, string>;
+}
+export interface CMSDeployTriggerConfig {
+    /**
+     * When to trigger a site redeployment.
+     *
+     * - `"on-publish"` (default) — Trigger whenever content is published or unpublished
+     * - `"manual"` — Only triggered when explicitly requested via CMS Admin or API
+     */
+    trigger?: "on-publish" | "manual";
+    /**
+     * HTTP deploy hook URL (e.g. Cloudflare Pages deploy hook, Vercel deploy hook, Netlify build
+     * hook).
+     */
+    hookUrl?: string;
+    /** Provider options (e.g. GitHub Actions workflow dispatch). */
+    github?: {
+        repo: string;
+        workflow: string;
+        ref?: string;
+        token?: string;
+    };
+}
+export interface CMSRevisionsConfig {
+    /**
+     * Maximum revisions to retain per entry before pruning.
+     *
+     * @default 10
+     */
+    max?: number;
+}
+export interface CMSOptions {
+    /**
+     * Mount the embedded edge CMS Admin.
+     *
+     * @default true
+     */
+    admin?: boolean;
+    /**
+     * Base route path for the CMS Admin.
+     *
+     * @default "/cms"
+     */
+    path?: string;
+    /**
+     * Base route path for public CMS API endpoints.
+     *
+     * @default "/api/cms"
+     */
+    apiPath?: string;
+    /**
+     * Root directory in project for file-based markdown/MDX content.
+     *
+     * @default "content"
+     */
+    contentDir?: string;
+    /**
+     * Shiki syntax highlighting shortcut.
+     *
+     * @default true
+     */
+    shiki?: boolean | CMSShikiPluginOptions;
+    /**
+     * Hybrid mode: automatically synchronize local content files into D1 on dev server start.
+     *
+     * @default true
+     */
+    hybrid?: boolean;
+    /**
+     * Roles allowed to access the CMS admin and mutate entries.
+     *
+     * @default ["admin", "editor"]
+     */
+    roles?: string[];
+    /**
+     * Revision history settings.
+     *
+     * @default { max: 10 }
+     */
+    revisions?: boolean | CMSRevisionsConfig;
+    /**
+     * Cache queries at the edge in KV.
+     *
+     * @default true
+     */
+    cache?: boolean;
+    /** Collections schema definitions. */
+    collections?: Record<string, CMSCollectionConfig>;
+    /**
+     * Globally registered reusable component definitions.
+     * Components can be referenced by name in collection fields using `type: \"component\"`\.
+     */
+    components?: Record<string, CMSComponentDefinition>;
+    /** Multi-source content aggregation sources (can also be defined via content _sources.yml files). */
+    sources?: CMSSourceConfig[];
+    /**
+     * Glob pattern(s) to exclude files or folders from CMS synchronization. e.g. `["**\/hosting\/**",
+     * "**\/dashboard\/**"]`
+     */
+    exclude?: string | string[];
+    /** Global GitHub repository configuration for CMS git-sync write-back. */
+    github?: CMSGitHubConfig;
+    /** Global deploy trigger configuration to rebuild static sites on content publish. */
+    deploy?: CMSDeployTriggerConfig;
+    /** Global outgoing webhook endpoints triggered on content mutations. */
+    webhooks?: CMSWebhookConfig[];
+    /**
+     * Secret used to authenticate incoming CMS webhooks (e.g. from GitHub, Cloudflare Queues, or CI/CD).
+     * Passed via `X-CMS-Secret`, `Authorization: Bearer <secret>`, or `X-Hub-Signature-256`.
+     */
+    webhookSecret?: string;
+    /** Global approval workflow default for collections. */
+    approval?: boolean | CMSApprovalConfig;
+    /**
+     * Supported locales for localized content (e.g. ["en", "es", "fr", "de"]).
+     *
+     * @default ["en"]
+     */
+    locales?: string[];
+    /**
+     * Default fallback locale for content resolution.
+     *
+     * @default "en"
+     */
+    defaultLocale?: string;
+    /**
+     * Global default for scheduled publishing.
+     *
+     * @default false
+     */
+    scheduledPublish?: boolean;
+    /**
+     * Markdown rendering plugins to enable.
+     *
+     * Each key enables (or configures) an optional comark plugin:
+     *
+     * - `shiki` — Syntax highlighting via Shiki. Enabled by default when the `cms` option is active.
+     * - `math` — KaTeX equation rendering (future).
+     * - `mermaid` — Mermaid diagram rendering (future).
+     *
+     * Pass `true`/`false` to enable/disable, or an options object to configure.
+     *
+     * @example
+     *   ;```ts
+     *   cms: {
+     *   plugins: {
+     *   shiki: { theme: 'github-dark' },
+     *   math: true,
+     *   }
+     *   }
+     *   ```
+     */
+    plugins?: CMSPluginOptions;
+}
+/**
+ * Config-driven plugin options for the CMS markdown renderer. Plugins are applied both server-side
+ * (pre-render to HTML) and client-side (live render via ContentRenderer).
+ */
+export interface CMSPluginOptions {
+    /**
+     * Shiki syntax highlighting. Pass `true` to enable with defaults, or an options object to
+     * customise.
+     *
+     * @default true (when cms is enabled)
+     */
+    shiki?: boolean | CMSShikiPluginOptions;
+    /**
+     * KaTeX math equation rendering.
+     *
+     * @default false
+     */
+    math?: boolean;
+    /**
+     * Mermaid diagram rendering.
+     *
+     * @default false
+     */
+    mermaid?: boolean;
+}
+/** Options for the Shiki syntax highlighting plugin. */
+export interface CMSShikiPluginOptions {
+    /**
+     * Light mode theme.
+     *
+     * @default "material-theme-lighter"
+     */
+    lightTheme?: string;
+    /**
+     * Dark mode theme.
+     *
+     * @default "material-theme-palenight"
+     */
+    darkTheme?: string;
+    /**
+     * Extra languages to support beyond the built-in defaults. Built-in defaults: vue, tsx, svelte,
+     * typescript, javascript, bash, json, yaml, astro.
+     */
+    langs?: string[];
+}
+export interface CMSSourceConfig {
+    /**
+     * Source location:
+     *
+     * - Local directory relative to the _sources.yml file: e.g. `../qarpeo/docs`
+     * - Remote GitHub repo: e.g. `github:qarpeo/qarpeo-blog/posts#main`
+     * - Remote tarball URL
+     */
+    from: string;
+    /**
+     * Content URL prefix.
+     *
+     * - Omitted / './' : relative to the directory containing this _sources.yml
+     * - '../sub' : relative, up one level
+     * - '/docs' : absolute from content root
+     */
+    prefix?: string;
+    /** Priority (higher wins). Default: 0. Local content/ files have implicit priority 10. */
+    priority?: number;
+    /** Order position in navigation relative to other sources (e.g. 1, 2, 3). */
+    order?: number;
+    /** Glob include pattern (default: all markdown files) */
+    include?: string;
+    /** Glob exclude pattern (e.g. "_drafts/*") */
+    exclude?: string;
+    /** Human-readable label for debugging / devtools display */
+    label?: string;
+}
+export interface CMSResolvedSource extends CMSSourceConfig {
+    /** Absolute resolved path on local disk (either resolved sibling or downloaded giget cache dir) */
+    resolvedDir: string;
+    /** Normalized absolute content route prefix (e.g. "/docs", "/templates") */
+    normalizedPrefix: string;
+    /** Source config file location where this was defined */
+    sourceConfigFile?: string;
+}
+export interface CMSHeadingLink {
+    id: string;
+    text: string;
+    depth: number;
+    children?: CMSHeadingLink[];
+}
+export interface CMSNavigationItem {
+    title: string;
+    path?: string;
+    to?: string;
+    icon?: string;
+    description?: string;
+    type?: string;
+    children?: CMSNavigationItem[];
+    locale?: string;
+    [key: string]: any;
+}
+export interface CMSNavigationOptions {
+    /**
+     * Maximum nesting depth to return. `1` = root level only (e.g. top-level sections for header
+     * menus).
+     */
+    levels?: number;
+    /**
+     * Scope navigation tree to a specific path prefix (e.g. `"/docs/cms"`). Useful for lazy-loading
+     * subtrees on demand.
+     */
+    path?: string;
+    /** Maximum number of items to return (at root or top-level list). */
+    limit?: number;
+    /** Number of items to skip (offset) for pagination. */
+    skip?: number;
+    /**
+     * Filter navigation items by editorial status.
+     *
+     * - `"published"` (default) — only published items
+     * - `"draft"` — only draft items
+     * - `"all"` — all items including drafts
+     *
+     * @default "published"
+     */
+    status?: "published" | "draft" | "all";
+    /**
+     * Filter navigation items by any frontmatter field value. First-class columns (`title`,
+     * `description`, `tags`, `path`, `slug`) are matched directly; all other fields are matched
+     * against the `metadata_json` blob stored alongside each entry.
+     *
+     * Values are compared with strict equality (`===`). `null` matches entries where the field is
+     * absent or explicitly `null`.
+     *
+     * @example
+     *   // Only show items tagged as tutorials in the "guides" category
+     *   queryCollectionNavigation("docs", { where: { category: "guides", featured: true } })
+     */
+    where?: Record<string, string | number | boolean | null>;
+    /** Optional locale filter (e.g. "en", "es") */
+    locale?: string;
+    /** When true, unwraps a single root collection node (e.g. /docs) */
+    unwrap?: boolean;
+}
+export interface CMSEntry {
+    id: string;
+    collectionId: string;
+    slug: string;
+    path?: string;
+    title: string;
+    description?: string | null;
+    coverImage?: string | null;
+    tags?: string | null;
+    order: number;
+    contentMd: string;
+    contentHtml: string;
+    body?: {
+        toc?: {
+            links: CMSHeadingLink[];
+        };
+        [key: string]: any;
+    };
+    toc?: {
+        links: CMSHeadingLink[];
+    };
+    navigation?: {
+        title?: string;
+        icon?: string;
+    };
+    metadata?: Record<string, unknown>;
+    metadataJson?: string;
+    status: CMSEntryStatus;
+    source: "file" | "db";
+    filePath?: string | null;
+    contentHash?: string | null;
+    authorId?: string | null;
+    publishedAt?: number | null;
+    tenantId?: string | null;
+    locale?: string;
+    version?: string;
+    createdAt: number;
+    updatedAt: number;
+}
+export type CMSEntryStatus = "draft" | "pending_review" | "scheduled" | "published" | "archived";
+/** A CMS collection record as stored in D1 (`_qarpeo_cms_collections`). */
+export interface CMSCollection {
+    id: string;
+    name: string;
+    description?: string | null;
+    schemaJson: string;
+    tenantId?: string | null;
+    /** Parsed field definitions (derived from schemaJson at runtime). */
+    fields?: Record<string, CMSFieldDefinition>;
+    /** 'config' = seeded from nuxt.config.ts; 'db' = created from CMS Admin. */
+    source: "config" | "db";
+    /** Order position in collection list / navigation tree. */
+    order?: number;
+    /** Whether this collection is a singleton (max 1 entry). */
+    singleton?: boolean;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface CMSPreviewTokenResult {
+    token: string;
+    expires: number;
+    /** Direct URL to preview the page with query parameters */
+    previewUrl: string;
+    /** One-click share URL that activates the preview cookie and redirects to the page */
+    shareUrl: string;
+}
+export interface CMSPreviewState {
+    isPreview: boolean;
+    token: string | null;
+    expires: string | null;
+    collection: string | null;
+    slug: string | null;
+}
+export interface CMSQueryOptions {
+    page?: number;
+    limit?: number;
+    sort?: string;
+    status?: CMSEntryStatus | "all";
+    tag?: string;
+    fields?: string;
+    /** Whether to allow fetching draft entries when preview mode or token is active */
+    preview?: boolean;
+    /** HMAC preview token for draft access */
+    previewToken?: string;
+    /** Preview token expiration timestamp */
+    previewExpires?: string | number;
+    /**
+     * Filter entries by custom metadata fields. Key-value pairs matching JSON properties in
+     * `metadataJson`.
+     */
+    where?: Record<string, unknown>;
+    /**
+     * Resolve reference fields into the full referenced entry. `true` populates every reference
+     * field; an array of field names populates only the listed fields. When omitted, reference fields
+     * are returned as lightweight `{ id, collectionId, slug, title }` objects.
+     */
+    populate?: boolean | string[];
+}
+export interface CMSCreateInput {
+    slug: string;
+    title: string;
+    description?: string;
+    coverImage?: string;
+    tags?: string;
+    order?: number;
+    contentMd: string;
+    metadata?: Record<string, unknown>;
+    status?: CMSEntryStatus;
+    authorId?: string;
+    publishedAt?: number | null;
+}
+export interface CMSUpdateInput {
+    slug?: string;
+    title?: string;
+    description?: string;
+    coverImage?: string;
+    tags?: string;
+    order?: number;
+    contentMd?: string;
+    metadata?: Record<string, unknown>;
+    status?: CMSEntryStatus;
+    authorId?: string;
+    publishedAt?: number | null;
+}
+export interface RealtimeOptions {
+    /**
+     * Base route path for WebSocket connections.
+     *
+     * @default "/api/realtime/ws"
+     */
+    path?: string;
+    /**
+     * Cloudflare Durable Object binding name.
+     *
+     * @default "QARPEO_ROOM_DO"
+     */
+    binding?: string;
+    /**
+     * Enable presence tracking (automatic join/leave events and active roster sync).
+     *
+     * @default true
+     */
+    presence?: boolean;
+    /**
+     * Require authenticated session to connect to rooms.
+     *
+     * @default false
+     */
+    requireAuth?: boolean;
+    /**
+     * Alias for `requireAuth`. Require authenticated session to connect to rooms.
+     *
+     * @default false
+     */
+    auth?: boolean;
+    /**
+     * Maximum concurrent WebSocket connections allowed per room.
+     *
+     * @default 100
+     */
+    maxConnectionsPerRoom?: number;
+    /**
+     * Maximum recent messages retained in the room's replay buffer in Durable Object storage.
+     *
+     * @default 50
+     */
+    historyLimit?: number;
+    /**
+     * Ping/heartbeat interval in milliseconds.
+     *
+     * @default 30000
+     */
+    heartbeatInterval?: number;
+    /** Alias for heartbeatInterval. */
+    heartbeat?: number;
+    /** Auto-reconnect enabled by default on client composable. */
+    reconnect?: boolean;
+    /** Replay unreceived messages automatically on reconnect using sequence numbers. @default true */
+    replayOnReconnect?: boolean;
+}
+export interface RealtimePeer {
+    id: string;
+    roomId: string;
+    ctx: {
+        user: RealtimeUser | Record<string, any> | null;
+        [key: string]: any;
+    };
+}
+export interface RealtimeHandlerOptions {
+    connect?(peer: RealtimePeer): void | Promise<void>;
+    disconnect?(peer: RealtimePeer): void | Promise<void>;
+    message?(peer: RealtimePeer, event: string, payload: any): void | Promise<void>;
+}
+export interface RealtimeHandlerRegistration {
+    pattern: string;
+    handlers: RealtimeHandlerOptions;
+}
+export interface RealtimeUser<TPresence = Record<string, any>> {
+    id: string;
+    name?: string | null;
+    avatar?: string | null;
+    metadata?: Record<string, unknown>;
+    presence?: TPresence;
+    joinedAt: number;
+    isAnonymous?: boolean;
+}
+export interface RealtimeMessage<T = unknown> {
+    type: "message" | "presence:sync" | "presence:join" | "presence:leave" | "presence:update" | "state:sync" | "state:set" | "state:patch" | "history:sync" | "ping" | "pong";
+    event?: string;
+    payload?: T;
+    sender?: string;
+    user?: RealtimeUser;
+    presence?: RealtimeUser[];
+    state?: Record<string, any>;
+    history?: RealtimeMessage[];
+    id?: string;
+    seq?: number;
+    replay?: boolean;
+    lastSeq?: number;
+    timestamp?: number;
+}
+export interface UsePresenceOptions<T extends Record<string, any> = Record<string, any>> {
+    /** Initial presence state */
+    initial?: T;
+    /** Minimum interval in milliseconds between broadcast updates (throttling). @default 50 */
+    throttle?: number;
+}
+export interface UsePresenceReturn<T extends Record<string, any> = Record<string, any>> {
+    /** My own current presence state */
+    myPresence: any;
+    /** Update my presence state (throttled) */
+    updatePresence: (partial: Partial<T>) => void;
+    /** Connected peers in the room with their presence data (excluding self) */
+    peers: any;
+    /** Total number of online peers including self */
+    onlineCount: any;
+    /** All connected users including self */
+    presence: any;
+    /** Helper to track and broadcast mouse/cursor coordinates on an element or window */
+    onCursorMove: (e: {
+        clientX: number;
+        clientY: number;
+    }) => void;
+}
+export interface UseRoomStateReturn<T extends Record<string, any> = Record<string, any>> {
+    /** Current synchronized room state */
+    state: any;
+    /** Replace entire room state */
+    setState: (newState: T) => void;
+    /** Merge partial update into room state */
+    patchState: (partial: Partial<T>) => void;
+    /** Whether initial state sync has completed */
+    synced: any;
+}
+export type PaymentProvider = "stripe" | "lemonsqueezy" | "polar" | "paddle";
+export type SubscriptionStatus = "active" | "trialing" | "past_due" | "canceled" | "unpaid" | "incomplete" | "paused";
+export interface PaymentPlanConfig {
+    name: string;
+    priceId: string;
+    features?: string[];
+    limits?: Record<string, number>;
+}
+export interface PaymentsOptions {
+    /**
+     * Payment provider backend.
+     *
+     * @default "stripe"
+     */
+    provider?: PaymentProvider;
+    /**
+     * Secret API key for provider. Defaults to process.env.STRIPE_SECRET_KEY, LEMONSQUEEZY_API_KEY,
+     * POLAR_ACCESS_TOKEN.
+     */
+    secretKey?: string;
+    /** Webhook signing secret. Defaults to process.env.STRIPE_WEBHOOK_SECRET, etc. */
+    webhookSecret?: string;
+    /**
+     * Base route prefix for payments endpoints.
+     *
+     * @default "/api/payments"
+     */
+    prefix?: string;
+    /** Default trial period in days for new subscriptions. */
+    trialDays?: number;
+    /** Default 3-letter currency code (e.g. 'usd', 'eur'). */
+    currency?: string;
+    /** Predefined plans mapping plan identifiers to price IDs and features. */
+    plans?: Record<string, PaymentPlanConfig>;
+    /**
+     * Default return URL after customer billing portal session completes.
+     *
+     * @default "/"
+     */
+    portalReturnUrl?: string;
+    /** Default redirect URLs for checkout sessions. */
+    checkoutUrls?: {
+        success?: string;
+        cancel?: string;
+    };
+    /** Paddle configuration options (environment, clientToken). */
+    paddle?: {
+        environment?: "sandbox" | "production";
+        clientToken?: string;
+    };
+}
+export interface QarpeoCustomer {
+    id: string;
+    userId: string;
+    orgId?: string | null;
+    provider: PaymentProvider;
+    customerId: string;
+    email: string;
+    name?: string | null;
+    metadataJson?: string | null;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface QarpeoSubscription {
+    id: string;
+    customerId: string;
+    userId: string;
+    orgId?: string | null;
+    provider: PaymentProvider;
+    subscriptionId: string;
+    planId: string;
+    priceId: string;
+    status: SubscriptionStatus;
+    quantity: number;
+    cancelAtPeriodEnd: boolean;
+    currentPeriodStart: number;
+    currentPeriodEnd: number;
+    trialEnd?: number | null;
+    canceledAt?: number | null;
+    metadata?: Record<string, any>;
+    metadataJson?: string | null;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface CreateCheckoutOptions {
+    planId?: string;
+    priceId?: string;
+    mode?: "subscription" | "payment" | "setup";
+    trialDays?: number;
+    currency?: string;
+    successUrl?: string;
+    cancelUrl?: string;
+    customerEmail?: string;
+    metadata?: Record<string, string>;
+}
+export interface QarpeoWebhookEvent {
+    id: string;
+    eventId: string;
+    provider: PaymentProvider;
+    eventType: string;
+    createdAt: number;
+}
+export interface MeterRecordOptions {
+    /** Optional user ID (defaults to current authenticated user) */
+    userId?: string;
+    /** Optional organization ID (defaults to current organization) */
+    orgId?: string;
+    /** Customer ID from payment provider */
+    customerId?: string;
+    /** Subscription ID from payment provider */
+    subscriptionId?: string;
+    /** Meter event or feature name (e.g. "api_requests", "tokens_generated", "storage_gb") */
+    eventName: string;
+    /** Quantity of units consumed (e.g. 100, 1) */
+    quantity: number;
+    /** Action: 'increment' (delta counter, default) or 'set' (absolute gauge) */
+    action?: "increment" | "set";
+    /** Timestamp of usage occurrence (defaults to now) */
+    timestamp?: number;
+    /** Custom metadata associated with this usage record */
+    metadata?: Record<string, any>;
+}
+export interface MeterUsageResult {
+    success: boolean;
+    id: string;
+    eventName: string;
+    quantity: number;
+    total?: number;
+    timestamp: number;
+}
+export interface UsageSummary {
+    eventName: string;
+    total: number;
+    count: number;
+    limit?: number;
+    remaining?: number;
+    periodStart?: number;
+    periodEnd?: number;
+    records?: Array<{
+        id: string;
+        quantity: number;
+        timestamp: number;
+        metadata?: Record<string, any>;
+    }>;
+}
+export interface DocsSearchSection {
+    /** Unique ID for search result item (e.g. "/docs/features/payments#paddle") */
+    id: string;
+    /** Canonical entry path */
+    path: string;
+    /** Section heading title (or page title if lead section) */
+    title: string;
+    /** Overall document page title */
+    pageTitle: string;
+    /** Breadcrumb hierarchy of titles */
+    titles: string[];
+    /** Clean highlighted text excerpt */
+    content: string;
+    /** Hash anchor for heading (e.g. "#webhooks") */
+    section?: string;
+    /** Locale of the document (e.g. "en", "es") */
+    locale?: string;
+    /** Heading level (1 for h1/title, 2 for h2, 3 for h3) */
+    level?: number;
+    /** Relevance match score */
+    score: number;
+}
+export interface DocsSearchResponse {
+    results: DocsSearchSection[];
+    total: number;
+    query: string;
+    /** Search execution engine used */
+    mode?: "fts" | "like";
+}
+export interface DocsSearchOptions {
+    q?: string;
+    locale?: string;
+    collection?: string;
+    limit?: number;
+    version?: string;
+    /** Search mode: 'fts' (default), 'like', or 'semantic' */
+    mode?: "fts" | "like" | "semantic";
+}
+export interface CMSLocaleConfig {
+    code: string;
+    name: string;
+    flag?: string;
+    dir?: "ltr" | "rtl";
+}
+export interface DocsVersionItem {
+    /** Version identifier (e.g. 'latest', 'v1', 'v2', 'next') */
+    id: string;
+    /** Display label in the version switcher (e.g. 'v2 (latest)', 'v1.x') */
+    label: string;
+    /** URL path prefix (e.g. '/docs', '/docs/v1') */
+    prefix: string;
+    /** Whether this is the active latest version */
+    isLatest?: boolean;
+    /** Whether this version is archived / deprecated */
+    isArchived?: boolean;
+}
+export interface SiteRobotsConfig {
+    /** Allow search engines to index the site. When false, generates Disallow: / on robots.txt and noindex meta. */
+    index?: boolean;
+    /** Paths to disallow in robots.txt. Defaults to ["/api/", "/devtools/", "/_qarpeo/"] */
+    disallow?: string[];
+    /** Paths to allow in robots.txt. Defaults to ["/"] */
+    allow?: string[];
+}
+export interface SiteSitemapUrl {
+    loc: string;
+    lastmod?: string;
+    changefreq?: "always" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "never";
+    priority?: number;
+}
+export interface SiteSitemapConfig {
+    /** Automatically generate /sitemap.xml. Defaults to true when site.url is provided. */
+    enabled?: boolean;
+    /** Paths to exclude from /sitemap.xml (supports wildcards, e.g. ["/api/**", "/_qarpeo/**"]) */
+    exclude?: string[];
+    /** Include published CMS entries from D1 database. Defaults to true. */
+    cms?: boolean;
+    /** Additional custom URLs to include in sitemap */
+    urls?: SiteSitemapUrl[];
+}
+export interface SiteFeedConfig {
+    /** Enabled by default when site.url is set. Set false to disable. */
+    enabled?: boolean;
+    /** CMS collection IDs/slugs to include in the global feed. Default: all published. */
+    collections?: string[];
+    /** Maximum entries per feed. Default: 50. */
+    maxItems?: number;
+    /** RSS TTL in minutes. Default: 60. */
+    ttl?: number;
+    /** Cache-Control max-age in seconds. Default: 3600. */
+    cacheMaxAge?: number;
+}
+export interface QarpeoSiteConfig {
+    /** Project/site name (used for Cloudflare Worker name, SEO, emails, branding) */
+    name?: string;
+    /** Canonical site URL (e.g. 'https://qarpeo.com') */
+    url?: string;
+    /** Site description */
+    description?: string;
+    /** Primary locale */
+    defaultLocale?: string;
+    /** Title template, e.g. "%s — %siteName" or "%s | %siteName". Default: "%s — %siteName" */
+    titleTemplate?: string;
+    /** Default separator between page title and site name. Default: "—" */
+    separator?: string;
+    /** Default OpenGraph / social share image URL (absolute or relative to site.url) */
+    image?: string;
+    /** Twitter/X creator or site handle (e.g. "@qarpeo") */
+    twitter?: string;
+    /** Canonical robots.txt rules */
+    robots?: boolean | SiteRobotsConfig;
+    /** Sitemap configuration */
+    sitemap?: boolean | SiteSitemapConfig;
+    /** RSS 2.0 / Atom 1.0 feed configuration */
+    feed?: boolean | SiteFeedConfig;
+    /** Auto-inject WebSite JSON-LD schema on root page. Default: true */
+    schemaOrg?: boolean;
+}
+/** Root configuration options for the Qarpeo Nuxt module (Strict Two-Tier Standard, Decision 22 & 23) */
+export interface QarpeoOptions {
+    /** Project & site metadata (name, url, SEO, branding) */
+    site?: QarpeoSiteConfig;
+    /** Native SEO engine configuration (alias for site config) */
+    seo?: boolean | QarpeoSiteConfig;
+    /** Project / Cloudflare Worker name override */
+    name?: string;
+    /**
+     * Use live Cloudflare remote bindings during `nuxt dev` instead of local Miniflare emulation.
+     *
+     * @default false
+     */
+    remote?: boolean;
+    /**
+     * Enable Cloudflare Workers AI integration for serverless LLMs, embeddings, and generative AI.
+     *
+     * @default false
+     */
+    ai?: boolean;
+    /**
+     * Enable Cloudflare Vectorize integration for vector embeddings and semantic search.
+     *
+     * @default false
+     */
+    vectorize?: boolean;
+    /**
+     * Enable Cloudflare Queues integration for asynchronous message queues and background jobs.
+     *
+     * @default false
+     */
+    queue?: boolean;
+    /**
+     * Enable Cloudflare Hyperdrive integration for pooled connections and query acceleration to
+     * external PostgreSQL/MySQL databases.
+     *
+     * @default false
+     */
+    hyperdrive?: boolean;
+    /**
+     * Enable Cloudflare Browser Rendering integration for headless Chromium web scraping, PDF
+     * generation, and automated screenshots.
+     *
+     * @default false
+     */
+    browser?: boolean;
+    /**
+     * Enable Cloudflare Durable Objects binding for stateful, low-latency coordination and presence.
+     *
+     * @default false
+     */
+    do?: boolean;
+    /**
+     * Cloudflare Cron Triggers configuration.
+     *
+     * @default false
+     */
+    cron?: boolean | Record<string, string[]>;
+    /**
+     * Enable Cloudflare Send Email integration for transactional emails.
+     *
+     * @default false
+     */
+    email?: boolean | EmailOptions;
+    /**
+     * Direct Cloudflare D1 SQL database binding.
+     *
+     * @default false
+     */
+    d1?: boolean;
+    /**
+     * Direct Cloudflare R2 Blob storage binding.
+     *
+     * @default false
+     */
+    r2?: boolean;
+    /**
+     * Enable Edge Database powered by Drizzle ORM on Cloudflare D1 (Tier 2). Auto-imports `db`,
+     * `useDrizzle()`, `schema`, and all Drizzle helpers.
+     *
+     * - `autoMigrate`: Automatically apply unapplied D1 migrations on `nuxt dev` startup (default:
+     *   true).
+     * - `migrateOnBuild`: Apply D1 migrations during `nuxt build`. Can be `true` (auto-detects remote
+     *   in CI / local otherwise), `"local"`, or `"remote"`. Also controllable via
+     *   `QARPEO_MIGRATE_ON_BUILD` env var (default: false).
+     *
+     * @default false
+     */
+    db?: boolean | {
+        autoMigrate?: boolean;
+        migrateOnBuild?: boolean | "local" | "remote";
+    };
+    /**
+     * Enable Cloudflare Key-Value (KV) storage. Auto-imports `kv` across server routes and handlers.
+     *
+     * @default false
+     */
+    kv?: boolean;
+    /**
+     * Enable Edge Cache Layer powered by Cloudflare KV (Tier 2). Mounts Nitro's `cache` storage
+     * driver to Cloudflare KV in production. Enables SWR routeRules and `purgeCache()`.
+     *
+     * @default false
+     */
+    cache?: boolean | CacheOptions;
+    /**
+     * Enable Cloudflare Edge Authentication powered by nuxt-auth-utils + D1 + KV (Tier 2).
+     *
+     * @default false
+     */
+    auth?: boolean | AuthOptions;
+    /**
+     * Enable Edge Blob / File System Layer powered by Cloudflare R2 (Tier 2).
+     *
+     * @default false
+     */
+    blob?: boolean | BlobOptions;
+    /**
+     * Alias for `blob` options (deprecated).
+     *
+     * @deprecated Use `blob` instead.
+     */
+    storage?: boolean | StorageOptions;
+    /**
+     * Enable Hybrid Edge Content Management System powered by D1 + R2 + Auth (Tier 2).
+     *
+     * @default false
+     */
+    cms?: boolean | CMSOptions;
+    /**
+     * Enable Realtime Layer powered by Cloudflare Durable Objects + KV (Tier 2).
+     *
+     * @default false
+     */
+    realtime?: boolean | RealtimeOptions;
+    /**
+     * Enable Edge Payments Layer powered by Stripe, Lemon Squeezy, or Polar (Tier 2).
+     *
+     * @default false
+     */
+    payments?: boolean | PaymentsOptions;
+    /**
+     * Enable Background Jobs Layer powered by Cloudflare Queues (Tier 2). Auto-scans `server/jobs/`
+     * and exposes `defineJob()` and `dispatchJob()`.
+     *
+     * @default false
+     */
+    jobs?: boolean | JobsOptions;
+    /**
+     * Enable Edge Rate Limiting powered by Cloudflare RateLimiter / KV (Tier 2). Exposes
+     * `assertRateLimit()`, `checkRateLimit()`, and per-route rate limiting.
+     *
+     * @default false
+     */
+    ratelimit?: boolean | AppRateLimitOptions;
+    /**
+     * Enable Stateful Edge Agents & AI Streaming Layer (Tier 2). Backed by Cloudflare Durable Objects
+     * (`QarpeoAgentDO`), Workers AI, and Vectorize. Exposes `defineAgent()`, `defineTool()`,
+     * `useChat()`, `streamText()`, and `useAgent()`.
+     *
+     * @default false
+     */
+    agents?: boolean | AgentsOptions;
+    /**
+     * Enable Transactional Email & Dev Mailbox Layer (Tier 2). Pre-built responsive HTML email
+     * templates, multi-provider delivery (Cloudflare, Resend, Postmark), and in-browser Dev Mailbox
+     * preview in development.
+     *
+     * @default false
+     */
+    mail?: boolean | MailOptions;
+    /**
+     * Enable Edge Analytics Dashboard (Tier 2). Privacy-first structured pageview tracking, custom
+     * business events, and a pre-built dashboard API backed by Cloudflare Analytics Engine.
+     *
+     * @default false
+     */
+    analytics?: boolean | AnalyticsOptions;
+    /**
+     * Enable Multi-Tenancy & Custom Domains Layer (Tier 2). Subdomain routing, custom domains via
+     * Cloudflare for SaaS, automated SSL, edge tenant resolution (`useTenant()`), and tenant data
+     * isolation.
+     *
+     * @default false
+     */
+    multitenant?: boolean | MultitenantOptions;
+    /**
+     * Enable Notifications Layer (Tier 2). Unified in-app feeds, realtime UI push via Durable
+     * Objects, browser Web Push (VAPID via Web Crypto), and email alerts.
+     *
+     * @default false
+     */
+    notifications?: boolean | NotificationsOptions;
+    /** Shorthand alias for notifications */
+    notify?: boolean | NotificationsOptions;
+    /**
+     * Configuration for Qarpeo DevTools (Dev-Only Management Console & DevTools panel).
+     *
+     * @default false
+     */
+    devtools?: boolean | DevtoolsOptions;
+}
+export type NotificationChannel = "in-app" | "push" | "email";
+export interface NotificationRecord {
+    id: string;
+    userId: string;
+    tenantId?: string;
+    title: string;
+    body?: string;
+    icon?: string;
+    actionUrl?: string;
+    channels: NotificationChannel[];
+    read: boolean;
+    readAt?: number;
+    createdAt: number;
+    metadata?: Record<string, any>;
+    /**
+     * Enable or customize RFC 2369 / RFC 8058 List-Unsubscribe headers for this message.
+     * Set alse to disable for transactional emails (e.g. OTP, password reset).
+     */
+    unsubscribe?: boolean | {
+        url?: string;
+        email?: string;
+    };
+    /**
+     * Whether to check the suppression list before sending. Set alse to bypass
+     * suppression checks for critical security or transactional emails.
+     * @default true
+     */
+    suppression?: boolean;
+}
+export interface PushSubscriptionKeys {
+    p256dh: string;
+    auth: string;
+}
+export interface PushSubscriptionRecord {
+    endpoint: string;
+    keys: PushSubscriptionKeys;
+}
+export interface SendNotificationRequest {
+    userId: string;
+    title: string;
+    body?: string;
+    icon?: string;
+    actionUrl?: string;
+    channels?: NotificationChannel[];
+    tenantId?: string;
+    metadata?: Record<string, any>;
+    emailOptions?: {
+        subject?: string;
+        from?: string;
+        template?: string;
+    };
+}
+export interface NotificationsVapidOptions {
+    publicKey: string;
+    privateKey: string;
+    subject?: string;
+}
+export interface NotificationsOptions {
+    /**
+     * Cloudflare D1 table name for notifications.
+     *
+     * @default "_qarpeo_notifications"
+     */
+    tableName?: string;
+    /**
+     * VAPID configuration for browser Web Push notifications.
+     * Can also be configured via NUXT_VAPID_PUBLIC_KEY, NUXT_VAPID_PRIVATE_KEY, NUXT_VAPID_SUBJECT.
+     */
+    vapid?: NotificationsVapidOptions;
+    /**
+     * Default notification channels when none specified.
+     *
+     * @default ["in-app"]
+     */
+    channels?: NotificationChannel[];
+}
+export interface DevtoolsOptions {
+    /**
+     * Whether Qarpeo DevTools is enabled in development.
+     *
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * IP addresses allowed to access Qarpeo DevTools endpoints in development.
+     *
+     * @default ["127.0.0.1", "::1", "localhost", "::ffff:127.0.0.1"]
+     */
+    allowedIps?: string[];
+    /**
+     * Allow access from any IP address (e.g. when binding to 0.0.0.0 for remote/mobile testing).
+     *
+     * @default false
+     */
+    allowAnyIp?: boolean;
+    /**
+     * Require an authentication token to access Qarpeo DevTools. Can also be provided via
+     * `QARPEO_DEVTOOLS_TOKEN` or `NUXT_DEVTOOLS_TOKEN` environment variables.
+     */
+    token?: string;
+    /**
+     * Whether authentication token is strictly required.
+     *
+     * @default false
+     */
+    requireAuth?: boolean;
+}
+import type { Nuxt } from "@nuxt/schema";
+export type ModuleOptions = QarpeoOptions;
+export * from "./runtime/types/durable-object";
+/** Type alias for the Nuxt instance, using official @nuxt/schema Nuxt interface. */
+export type NuxtInstance = Nuxt;