@idapt/browser-app-sdk 0.1.0

package/dist/data-Chus9wn2.d.cts

@@ -0,0 +1,1714 @@
+import { z } from 'zod';
+
+/**
+ * Typed fetch wrapper used by every API-calling module.
+ *
+ * Responsibilities:
+ *   - Build the URL (base + path + query) safely
+ *   - Serialise JSON bodies or pass through `BodyInit` (multipart)
+ *   - Attach the bearer token
+ *   - Honour AbortSignal
+ *   - Parse JSON responses (respecting Content-Type)
+ *   - Map non-2xx responses to the typed error hierarchy
+ *
+ * Everything else in the SDK calls through this single surface so behaviours
+ * (retries, 401 handling, etc.) can be evolved in one place.
+ */
+/**
+ * Query params.
+ *
+ * Typed as `object` rather than `Record<string, unknown>` because named
+ * interfaces (e.g. `ListAgentsQuery`) don't satisfy `Record`'s implicit
+ * index signature — a known TS papercut. Any typed object satisfies
+ * `object`, so call sites don't need casts. `buildQuery` reads the value
+ * via `Object.entries` and skips non-primitives.
+ */
+type QueryInput = object;
+interface HttpRequest {
+    method: "GET" | "POST" | "PATCH" | "DELETE" | "PUT";
+    path: string;
+    query?: QueryInput;
+    headers?: Record<string, string>;
+    body?: unknown;
+    bodyRaw?: BodyInit;
+    signal?: AbortSignal;
+    /**
+     * Response decoding mode. Exactly one of these is honoured:
+     *   - `expectBlob: true`  → return `res.blob()` (binary)
+     *   - `expectJson: false` → return `res.text()` (raw string)
+     *   - otherwise            → parse JSON when Content-Type says so,
+     *                            fall back to text
+     */
+    expectJson?: boolean;
+    expectBlob?: boolean;
+}
+/**
+ * How the SDK proves identity on every request:
+ *
+ *   - `"bearer"` (default) — send `Authorization: Bearer <key>`. Used by
+ *     library mode (explicit `uk_`/`pk_`/`ap_` key) and any caller holding a
+ *     raw key.
+ *   - `"cookie"` — send `credentials: "include"` and NO `Authorization`
+ *     header. Used by the hosted cookie-bootstrap flow: the raw `ap_` key
+ *     lives only in the httpOnly `__Secure-idapt_app_key` cookie planted on the
+ *     app subdomain, so the SDK never sees it — the browser attaches it
+ *     automatically. `key` is unused (and typically empty) in this mode.
+ *
+ * A third, derived strategy exists when {@link HttpContext.getToken} is set
+ * (cookie-mode v1 surfaces): a **minted bearer**. The provider lazily mints an
+ * `idapt-api`-audience JWT from the app cookie (via `/api/browser-app/token`),
+ * the request sends it as `Authorization: Bearer <jwt>` with NO ambient cookie,
+ * and a 401 triggers a single re-mint-and-retry (via {@link HttpContext.onUnauthorized}).
+ */
+type AuthMode$1 = "bearer" | "cookie";
+interface HttpContext {
+    apiUrl: string;
+    key: string;
+    /**
+     * Auth transport. Defaults to `"bearer"` when omitted (back-compat). In
+     * `"cookie"` mode the httpOnly app-key cookie carries auth instead — the
+     * request is sent with `credentials: "include"` and no bearer header.
+     *
+     * Ignored when {@link getToken} is set: a minted-bearer context always
+     * attaches the provider's JWT and never sends ambient cookies.
+     */
+    auth?: AuthMode$1;
+    /**
+     * Dynamic bearer provider (cookie-mode v1 surfaces). When present it
+     * supersedes both `key` and `auth`: every request awaits it for the
+     * `Authorization` bearer and omits `credentials: "include"`. Implementations
+     * cache the minted token and re-mint on expiry; {@link onUnauthorized} lets
+     * the request layer force a re-mint when the server still rejects (401).
+     */
+    getToken?: () => Promise<string>;
+    /**
+     * Called once on a 401 from a {@link getToken}-backed request so the provider
+     * can invalidate its cached token; the request is then retried a single time
+     * with a freshly-minted bearer. No-op / absent ⇒ no retry.
+     */
+    onUnauthorized?: () => void;
+    /**
+     * Default headers applied to every request through this context (e.g. a
+     * `User-Agent` advertising the caller). Per-request `req.headers` win on key
+     * collision; the `Authorization` header is still owned by the auth strategy
+     * above (don't set it here). Lets a transport thread one static header set
+     * through the context instead of re-specifying it per call. Optional.
+     */
+    headers?: Record<string, string>;
+    /** Custom fetch — used in tests and for polyfills. */
+    fetch?: typeof fetch;
+}
+declare function request<T = unknown>(ctx: HttpContext, req: HttpRequest): Promise<T>;
+declare function requestRaw(ctx: HttpContext, req: HttpRequest): Promise<Response>;
+declare function buildUrl(apiUrl: string, path: string, query?: QueryInput): string;
+
+declare const userResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    slug: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    created_at: z.ZodString;
+}, z.core.$strip>;
+type UserResponse = z.infer<typeof userResponseSchema>;
+declare const settingsResponseSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    slug: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    is_public: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    is_auto_compact_enabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    consent_analytics: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    consent_marketing: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    consent_decided_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    locale: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    icon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    display_image: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    github_username: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+type SettingsResponse = z.infer<typeof settingsResponseSchema>;
+declare const subscriptionResponseSchema: z.ZodObject<{
+    plan: z.ZodString;
+    is_paid: z.ZodBoolean;
+    balance: z.ZodNumber;
+    auto_reload_enabled: z.ZodBoolean;
+    auto_reload_amount_cents: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    auto_reload_threshold_cents: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    monthly_limit_usd: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$strip>;
+type SubscriptionResponse = z.infer<typeof subscriptionResponseSchema>;
+declare const sharedWithMeItemResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    resource_type: z.ZodEnum<{
+        file: "file";
+        agent: "agent";
+        workspace: "workspace";
+        chat: "chat";
+    }>;
+    name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    owner_slug: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    owner_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    icon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    extension: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    mime_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    permission: z.ZodEnum<{
+        read: "read";
+        write: "write";
+        admin: "admin";
+    }>;
+    shared_by_actor_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    workspace_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    shared_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    via_public: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type SharedWithMeItemResponse = z.infer<typeof sharedWithMeItemResponseSchema>;
+
+declare const blobObjectResponseSchema: z.ZodObject<{
+    namespace: z.ZodString;
+    key: z.ZodString;
+    content_type: z.ZodString;
+    size: z.ZodNumber;
+    etag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    sha256: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    public: z.ZodBoolean;
+    resource_id: z.ZodString;
+    updated_at: z.ZodString;
+}, z.core.$strip>;
+type BlobObjectResponse = z.infer<typeof blobObjectResponseSchema>;
+
+/** `execution_run` record — `transformExecutionRun` output, snake_case. */
+declare const executionRunResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    backend: z.ZodString;
+    mode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    status: z.ZodString;
+    workspace_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    file_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    file_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    runtime: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    exit_code: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    stdout: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    stderr: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    duration_ms: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    timed_out: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    timeout_seconds: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    trigger_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    error_message: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    created_at: z.ZodString;
+    started_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    completed_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    output_files: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        file_id: z.ZodString;
+        path: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+type ExecutionRunResponse = z.infer<typeof executionRunResponseSchema>;
+
+declare const computerResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    icon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    type: z.ZodEnum<{
+        remote: "remote";
+        managed: "managed";
+    }>;
+    hostname: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    port: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    logging_level: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        standard: "standard";
+        full: "full";
+        minimal: "minimal";
+    }>>>;
+    workspace_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    state: z.ZodNullable<z.ZodEnum<{
+        unprovisioned: "unprovisioned";
+        provisioning: "provisioning";
+        running: "running";
+        hibernating: "hibernating";
+        hibernated: "hibernated";
+        waking: "waking";
+        stopping: "stopping";
+        stopped: "stopped";
+        terminating: "terminating";
+        terminated: "terminated";
+    }>>;
+    archived_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, z.core.$strip>;
+type ComputerResponse = z.infer<typeof computerResponseSchema>;
+declare const computerUserResponseSchema: z.ZodObject<{
+    username: z.ZodString;
+    uid: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    groups: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    shell: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    home: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    has_credential: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type ComputerUserResponse = z.infer<typeof computerUserResponseSchema>;
+declare const computerEnvVarResponseSchema: z.ZodObject<{
+    name: z.ZodString;
+    username: z.ZodString;
+    file_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    created_at: z.ZodString;
+}, z.core.$strip>;
+type ComputerEnvVarResponse = z.infer<typeof computerEnvVarResponseSchema>;
+declare const computerPortResponseSchema: z.ZodObject<{
+    port: z.ZodNumber;
+    protocol: z.ZodString;
+    process: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    hidden: z.ZodOptional<z.ZodBoolean>;
+    display_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    icon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+type ComputerPortResponse = z.infer<typeof computerPortResponseSchema>;
+
+declare const agentResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    icon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    system_prompt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    workspace_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    permissions: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>>;
+    compaction_preset: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        minimal: "minimal";
+        normal: "normal";
+        detailed: "detailed";
+    }>>>;
+    compaction_summary_percent: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    compaction_summary_max_tokens: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    compaction_preserved_percent: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    compaction_preserved_max_tokens: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    compaction_msg_percent: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    compaction_msg_max_tokens: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    compaction_trigger_type: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        percent: "percent";
+        tokens: "tokens";
+    }>>>;
+    compaction_trigger_value: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    source_template_resource_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    memory_folder: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    default_model_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    default_reasoning_effort: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    default_auto_cost_level: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    default_cost_budget_limit_usd: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    is_trashed: z.ZodOptional<z.ZodBoolean>;
+    trashed_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    archived_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, z.core.$strip>;
+type AgentResponse = z.infer<typeof agentResponseSchema>;
+declare const chatResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    icon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    agent_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    workspace_id: z.ZodString;
+    default_model: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    is_trashed: z.ZodOptional<z.ZodBoolean>;
+    archived_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, z.core.$strip>;
+type ChatResponse = z.infer<typeof chatResponseSchema>;
+declare const messageResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    role: z.ZodEnum<{
+        user: "user";
+        assistant: "assistant";
+        tool: "tool";
+    }>;
+    content: z.ZodString;
+    model_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    created_at: z.ZodString;
+}, z.core.$strip>;
+type MessageResponse = z.infer<typeof messageResponseSchema>;
+declare const workspaceResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    slug: z.ZodString;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    icon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    is_personal: z.ZodBoolean;
+    public_access: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    archived_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, z.core.$strip>;
+type WorkspaceResponse = z.infer<typeof workspaceResponseSchema>;
+declare const workspaceMemberResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    actor_id: z.ZodString;
+    slug: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    display_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    display_image: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    role: z.ZodEnum<{
+        custom: "custom";
+        admin: "admin";
+        owner: "owner";
+        editor: "editor";
+        viewer: "viewer";
+    }>;
+    created_at: z.ZodString;
+}, z.core.$strip>;
+type WorkspaceMemberResponse = z.infer<typeof workspaceMemberResponseSchema>;
+declare const triggerResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    enabled: z.ZodBoolean;
+    workspace_id: z.ZodString;
+    trigger_type: z.ZodString;
+    action_type: z.ZodString;
+    cron_expression: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    cron_timezone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    agent_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    prompt_template: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    initial_context: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    model: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    reasoning_level: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    auto_cost_level: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    cost_budget_limit_usd: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    web_search_enabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    memory_enabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    subagent_enabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    delegate_mode: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    auto_compact_enabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    compaction_preset: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    pasted_texts: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodUnknown>>>;
+    active_skills: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    file_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    runtime: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    timeout_seconds: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    env: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodString>>>;
+    working_dir_folder_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    next_run_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    last_fired_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    archived_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, z.core.$strip>;
+type TriggerResponse = z.infer<typeof triggerResponseSchema>;
+/** Trigger + its one-time plaintext webhook secret (create / rotate-secret). */
+declare const triggerWithSecretResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    enabled: z.ZodBoolean;
+    workspace_id: z.ZodString;
+    trigger_type: z.ZodString;
+    action_type: z.ZodString;
+    cron_expression: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    cron_timezone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    agent_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    prompt_template: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    initial_context: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    model: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    reasoning_level: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    auto_cost_level: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    cost_budget_limit_usd: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    web_search_enabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    memory_enabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    subagent_enabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    delegate_mode: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    auto_compact_enabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    compaction_preset: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    pasted_texts: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodUnknown>>>;
+    active_skills: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    file_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    runtime: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    timeout_seconds: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    env: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodString>>>;
+    working_dir_folder_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    next_run_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    last_fired_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    archived_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+    secret: z.ZodString;
+}, z.core.$strip>;
+type TriggerWithSecretResponse = z.infer<typeof triggerWithSecretResponseSchema>;
+declare const triggerRunResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    trigger_id: z.ZodString;
+    success: z.ZodBoolean;
+    error: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    chat_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    execution_run_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    fired_at: z.ZodString;
+}, z.core.$strip>;
+type TriggerRunResponse = z.infer<typeof triggerRunResponseSchema>;
+declare const triggerCostStatsResponseSchema: z.ZodObject<{
+    runs_with_cost: z.ZodNumber;
+    total_cost_usd: z.ZodNumber;
+    today_cost_usd: z.ZodNumber;
+    this_month_cost_usd: z.ZodNumber;
+    last24h_cost_usd: z.ZodNumber;
+    last7d_cost_usd: z.ZodNumber;
+    first_fired_at: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+type TriggerCostStatsResponse = z.infer<typeof triggerCostStatsResponseSchema>;
+declare const notificationResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodString;
+    subtype: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    title: z.ZodString;
+    message: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    data: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    group_key: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    workspace_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    sender_kind: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    sender_actor_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    sender_agent_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    audience: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>>;
+    is_read: z.ZodBoolean;
+    read_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    archived_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    created_at: z.ZodString;
+}, z.core.$strip>;
+type NotificationResponse = z.infer<typeof notificationResponseSchema>;
+declare const notificationConfigResponseSchema: z.ZodObject<{
+    toasts_enabled: z.ZodOptional<z.ZodBoolean>;
+    sound_enabled: z.ZodOptional<z.ZodBoolean>;
+    quiet_hours_enabled: z.ZodOptional<z.ZodBoolean>;
+    quiet_hours_start: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    quiet_hours_end: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    quiet_hours_timezone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    digest_frequency: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    nudge_shown_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$catchall<z.ZodUnknown>>;
+type NotificationConfigResponse = z.infer<typeof notificationConfigResponseSchema>;
+declare const notificationPreferenceResponseSchema: z.ZodObject<{
+    type: z.ZodString;
+    subtype: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    channel: z.ZodEnum<{
+        email: "email";
+        in_app: "in_app";
+        web_push: "web_push";
+    }>;
+    enabled: z.ZodBoolean;
+    is_default: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type NotificationPreferenceResponse = z.infer<typeof notificationPreferenceResponseSchema>;
+declare const shareResponseSchema: z.ZodObject<{
+    resource_type: z.ZodEnum<{
+        file: "file";
+        agent: "agent";
+        workspace: "workspace";
+        chat: "chat";
+    }>;
+    resource_id: z.ZodString;
+    grantee_actor_id: z.ZodString;
+    permission: z.ZodEnum<{
+        read: "read";
+        write: "write";
+        admin: "admin";
+    }>;
+    shared_by_actor_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    shared_at: z.ZodString;
+}, z.core.$strip>;
+type ShareResponse = z.infer<typeof shareResponseSchema>;
+
+declare const datastoreEntryResponseSchema: z.ZodObject<{
+    namespace: z.ZodString;
+    key: z.ZodString;
+    value: z.ZodNullable<z.ZodUnknown>;
+    size: z.ZodNumber;
+    expires_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    updated_at: z.ZodString;
+}, z.core.$strip>;
+type DatastoreEntryResponse = z.infer<typeof datastoreEntryResponseSchema>;
+
+/**
+ * A file resource (`transformFile` → snake_case). `id` is the resourceId.
+ * Nullable-and-optional (`.nullish()`) where the SDK marks the field optional,
+ * so `z.infer<typeof fileResponseSchema>` is wire-identical to the SDK `File`
+ * type it now sources (a present `null` always validates).
+ */
+declare const fileResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    mime_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    file_size: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    version: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    content_hash: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    parent_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    workspace_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    lock_expires_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    is_locked: z.ZodOptional<z.ZodBoolean>;
+    lock_reason: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    created_at: z.ZodOptional<z.ZodString>;
+    updated_at: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type FileResponse = z.infer<typeof fileResponseSchema>;
+/** Stripped record from a multipart upload (`transformFileUpload`) — no timestamps. */
+declare const fileUploadResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    mime_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    file_size: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$strip>;
+type FileUploadResponse = z.infer<typeof fileUploadResponseSchema>;
+
+/**
+ * A hub/store item from `GET /hub/search` (snake_case wire). `id` is the item's
+ * resourceId (non-null). The catalog has heterogeneous payloads per type
+ * (skills carry version/license, agents carry icons/prompts, computer templates
+ * carry sizing), so the common fields are typed and the rest stays open via
+ * `.catchall`. Component id `StoreItem` (the SDK `StoreItem` type infers this).
+ */
+declare const storeItemResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    display_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    icon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    display_image: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    license: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    author_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    author_slug: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    source: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    external_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    install_count: z.ZodOptional<z.ZodNumber>;
+    popularity: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    preview: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    metadata: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    created_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    updated_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$catchall<z.ZodUnknown>>;
+type StoreItemResponse = z.infer<typeof storeItemResponseSchema>;
+
+declare const apiKeyResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    prefix: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    key_preview: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    permissions: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        resource: z.ZodString;
+        scope: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        access: z.ZodOptional<z.ZodEnum<{
+            read: "read";
+            write: "write";
+            admin: "admin";
+        }>>;
+    }, z.core.$strip>>>>;
+    enabled: z.ZodBoolean;
+    expires_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    last_used_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    created_at: z.ZodString;
+    key: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type ApiKeyResponse = z.infer<typeof apiKeyResponseSchema>;
+
+/** Secret metadata — never carries the plaintext value. */
+declare const secretResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    workspace_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    value_preview: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    expires_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    last_used_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, z.core.$strip>;
+type SecretResponse = z.infer<typeof secretResponseSchema>;
+/** Reveal response — the metadata PLUS the decrypted plaintext value. */
+declare const secretWithValueResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    workspace_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    value_preview: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    expires_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    last_used_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+    value: z.ZodString;
+}, z.core.$strip>;
+type SecretWithValueResponse = z.infer<typeof secretWithValueResponseSchema>;
+
+declare const tableCollectionResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    icon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    schema: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        fields: z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            name: z.ZodString;
+            type: z.ZodString;
+            options: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+            required: z.ZodOptional<z.ZodBoolean>;
+            default: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    workspace_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, z.core.$strip>;
+type TableCollectionResponse = z.infer<typeof tableCollectionResponseSchema>;
+declare const tableRecordResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    collection_id: z.ZodString;
+    values: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, z.core.$strip>;
+type TableRecordResponse = z.infer<typeof tableRecordResponseSchema>;
+
+/**
+ * Public type surface for @idapt/sdk.
+ *
+ * Types are hand-written against the **actual** v1 response shapes. When the
+ * v1 API changes, update this file and the unit tests — the tests exercise
+ * every wire format through mocked fetch responses.
+ *
+ * ## Envelope conventions (verified against lib/api/v1/response.ts)
+ *
+ *   Single:   { data: T }
+ *   List:     { data: T[], pagination: { has_more, next_cursor } }
+ *   Deleted:  { deleted: true, id }
+ *   Error:    { error: { type, message, code? } }
+ *
+ * Pagination lives in a nested object so the envelope can grow without a
+ * breaking change — do NOT flatten `has_more` up. Paging is cursor-based
+ * (`limit` capped at 100, opaque `cursor` token) — there is no offset and
+ * no total count (Stripe/OpenAI-style).
+ *
+ * The error envelope splits the old flat `code` into `type` (the coarse
+ * category clients branch on) + an optional finer `code` sub-code — see
+ * `errors.ts` for the typed hierarchy that wraps it.
+ */
+
+/**
+ * Pagination metadata on every list envelope. Cursor-based: callers page
+ * with `limit` (max 100) + an opaque `cursor`. `has_more` flags whether
+ * another page exists; `next_cursor` is the token to pass as the next
+ * request's `?cursor=` (it is `null` when `has_more` is false).
+ *
+ * The cursor is OPAQUE — echo `next_cursor` back as `cursor`, never parse
+ * it. Bounded lists (static catalogs, workspace members, …) still carry a
+ * `pagination` block, but their `next_cursor` is always `null`. There is
+ * no total count (Stripe/OpenAI-style).
+ */
+interface Pagination {
+    has_more: boolean;
+    /** Opaque token for the next page, or `null` when `has_more` is false. */
+    next_cursor: string | null;
+}
+interface ListEnvelope<T> {
+    data: T[];
+    pagination: Pagination;
+}
+interface SingleEnvelope<T> {
+    data: T;
+}
+interface DeletedResponse {
+    deleted: true;
+    id: string;
+}
+/**
+ * A file resource as returned by the v1 API (`GET /files/:id`, lists).
+ *
+ * Field names follow the API's snake_case convention. Many columns are
+ * nullable on the server — tolerate that in consumer code. `id` is the
+ * file's resourceId — there is no separate `resource_id` field.
+ */
+type File = FileResponse;
+type FileList = ListEnvelope<File>;
+/**
+ * Stripped-down file record returned by `POST /files` (multipart upload).
+ * No timestamps. `id` is the file's resourceId.
+ */
+type FileUploadResult = FileUploadResponse;
+/** Current-user payload from `GET /me`. */
+/** Current-user payload from `GET /me`. Sourced from the account v1 contract. */
+type User = UserResponse;
+/** `GET /me/usage?view=summary`. */
+interface UsageSummary {
+    storage: {
+        used_bytes: number;
+        capacity_bytes: number;
+        snapshot_bytes: number;
+    };
+}
+/**
+ * `GET /me/usage?view=history` entry — one metered LLM / image / audio
+ * call. There is no `id` on the wire: usage rows are an append-only log,
+ * keyed by `(actor, created_at)`, not addressable resources.
+ */
+interface UsageRecord {
+    call_type: string;
+    model_id?: string | null;
+    /** Workspace the call was billed against. Null for non-workspace calls. */
+    workspace_id?: string | null;
+    input_tokens?: number | null;
+    output_tokens?: number | null;
+    /** Reasoning/thinking tokens, when the model reports them separately. */
+    reasoning_tokens?: number | null;
+    /** Prompt tokens served from the provider's cache. */
+    cached_tokens?: number | null;
+    cost_usd?: number | null;
+    /** Wall-clock duration of the call. */
+    duration_seconds?: number | null;
+    /** Provider finish reason (`stop`, `length`, `tool_calls`, …). */
+    finish_reason?: string | null;
+    /** True when the call was cancelled before completion. */
+    cancelled?: boolean | null;
+    created_at: string;
+    [k: string]: unknown;
+}
+/** Agent resource. Sourced from the crud v1 contract. */
+type Agent = AgentResponse;
+/** Chat resource. Sourced from the crud v1 contract. */
+type Chat = ChatResponse;
+/** Chat message. Sourced from the crud v1 contract. */
+type Message = MessageResponse;
+/**
+ * Per-call-type cost + token breakdown inside `ChatCost.by_call_type`.
+ * Each key (`chat`, `image`, `web_search`, …) maps to one of these.
+ */
+interface ChatCostByCallType {
+    cost_usd: number;
+    count: number;
+    input_tokens: number;
+    output_tokens: number;
+    cached_tokens: number;
+    input_cost_usd: number;
+    output_cost_usd: number;
+    cached_cost_usd: number;
+}
+interface ChatCost {
+    total_cost_usd: number;
+    total_input_tokens: number;
+    total_output_tokens: number;
+    total_cached_tokens: number;
+    by_call_type?: Record<string, ChatCostByCallType> | null;
+    cost_budget_limit_usd?: number | null;
+    cost_budget_mode?: string | null;
+    cost_budget_spent_usd?: number | null;
+}
+interface MessageCostEntry {
+    cost_usd: number;
+    input_tokens: number;
+    output_tokens: number;
+    cached_tokens: number;
+    call_type: string;
+    is_estimated: boolean;
+    duration_seconds: number;
+}
+interface RunCostMetrics {
+    total_cost_usd: number;
+    total_input_tokens: number;
+    total_output_tokens: number;
+    total_cached_tokens: number;
+    duration_seconds: number;
+    state: string;
+}
+interface MessageCosts {
+    by_message: Record<string, MessageCostEntry[]>;
+    by_run: Record<string, RunCostMetrics>;
+}
+interface ChatStopResult extends Chat {
+    run_active: boolean;
+}
+/** Lifecycle state of an agent run row (`GET /chats/:id/runs`). */
+type AgentRunState = "generating" | "streaming" | "completed" | "failed" | "stopped" | "paused";
+interface AgentRun {
+    id: string;
+    state: AgentRunState;
+    model_id?: string | null;
+    total_input_tokens?: number | null;
+    total_output_tokens?: number | null;
+    total_cost_usd?: number | null;
+    duration_seconds?: number | null;
+    error?: string | null;
+    created_at: string;
+    completed_at?: string | null;
+}
+/**
+ * Response shape of `POST /chats/:id/messages` (201, a `oneOf`).
+ *  - completed: `{ status, chat_id, model_id, user_message_id, message }`
+ *  - pending:   `{ status, pending_token, chat_id }`
+ *
+ * `pending_token` is an opaque workflow handle (NOT a resourceId).
+ */
+type SendMessageResult = {
+    status: "completed";
+    chat_id: string;
+    model_id: string | null;
+    user_message_id: string;
+    message: Message;
+} | {
+    status: "pending";
+    pending_token: string;
+    chat_id: string;
+};
+/**
+ * Lifecycle status of an execution run. `interrupted` lands when a run is
+ * cancelled via `POST /code-runs/:id/interrupt`.
+ */
+type ExecutionRunStatus = "pending" | "running" | "completed" | "failed" | "timed_out" | "interrupted";
+/** Where an execution run executes — sandboxed Lambda or a paired computer. */
+type ExecutionBackend = "computer" | "lambda";
+/**
+ * An execution-run row. Returned by `POST /code-runs`, `POST /files/:id/run`,
+ * `GET /code-runs` and `GET /code-runs/:id` — code execution always yields
+ * this single shape (there is no separate stripped run-summary type).
+ */
+type ExecutionRun = ExecutionRunResponse;
+type TriggerType = "webhook" | "schedule" | "manual" | string;
+type TriggerActionType = "run_code" | "run_chat" | string;
+/**
+ * A trigger resource. This is a flat object — every scheduling field
+ * and every action field lives directly on the row, with no nested
+ * `trigger_config` / `action_config` objects.
+ *
+ * `agent_id`, `file_id` and `working_dir_folder_id` are resourceIds.
+ */
+/** A trigger resource (flat). Sourced from the crud v1 contract. */
+type Trigger = TriggerResponse;
+/**
+ * A trigger plus its one-time webhook `secret`. Returned by
+ * `POST /v1/triggers` (webhook creation) and `POST /v1/triggers/:id/rotate-secret`.
+ * The plaintext `secret` is only ever echoed on these two responses.
+ */
+/** Trigger + one-time webhook secret. Sourced from the crud v1 contract. */
+type TriggerWithSecret = TriggerWithSecretResponse;
+/** A trigger run record. Sourced from the crud v1 contract. */
+type TriggerRun = TriggerRunResponse;
+/** Trigger cost aggregates. Sourced from the crud v1 contract. */
+type TriggerCostStats = TriggerCostStatsResponse;
+/**
+ * Create-trigger request body — flat, mirrors the `Trigger` shape. The
+ * required fields depend on `trigger_type` / `action_type` (a schedule
+ * trigger needs `cron_expression`; a `run_code` action needs `file_id`;
+ * a `run_chat` action needs `prompt_template` or `agent_id`). The server
+ * validates the combination.
+ */
+interface CreateTriggerInput {
+    name: string;
+    description?: string;
+    enabled?: boolean;
+    trigger_type: TriggerType;
+    action_type: TriggerActionType;
+    cron_expression?: string;
+    cron_timezone?: string;
+    agent_id?: string;
+    prompt_template?: string;
+    initial_context?: string;
+    model?: string;
+    reasoning_level?: number;
+    auto_cost_level?: number;
+    cost_budget_limit_usd?: number;
+    web_search_enabled?: boolean;
+    memory_enabled?: boolean;
+    subagent_enabled?: boolean;
+    delegate_mode?: boolean;
+    auto_compact_enabled?: boolean;
+    compaction_preset?: string;
+    pasted_texts?: unknown[];
+    active_skills?: string[];
+    file_id?: string;
+    runtime?: string;
+    timeout_seconds?: number;
+    env?: Record<string, string>;
+    working_dir_folder_id?: string;
+}
+/** Update-trigger request body — every create field plus `agent_id` is patchable. */
+type UpdateTriggerInput = Partial<CreateTriggerInput>;
+/**
+ * Modality bucket a model belongs to. Every model row across `/v1/models`,
+ * `/v1/audio/models` and `/v1/images/models` carries this discriminant.
+ */
+type ModelModality = "chat" | "audio" | "image";
+/**
+ * Fields shared by every model row regardless of modality. Modality-specific
+ * shapes (`LLMModel`, `AudioModel`, `ImageModel`) extend this.
+ *
+ * Every model row carries `pricing` and `capabilities` as nested
+ * objects. `pricing` is always the user-facing (post-markup) price.
+ */
+interface ModelBase {
+    id: string;
+    /** Human-readable label. */
+    display_name: string;
+    provider: string;
+    modality: ModelModality;
+}
+/** Chat-model pricing block — null when the model is free / unpriced. */
+interface LLMModelPricing {
+    input_per_million: number;
+    output_per_million: number;
+}
+/** Chat-model capability block (always an object, never an array). */
+interface LLMModelCapabilities {
+    context_length: number;
+    max_output_tokens: number;
+    image_input: boolean;
+}
+/** A chat/LLM model from `GET /v1/models` (`modality: "chat"`). */
+interface LLMModel extends ModelBase {
+    modality: "chat";
+    pricing: LLMModelPricing | null;
+    capabilities: LLMModelCapabilities;
+}
+type ProviderEndpointKind = "openai" | "anthropic" | "openai_compatible";
+type ProviderEndpointProviderKey = "openai" | "anthropic" | "openrouter" | "gemini" | "xai" | "deepseek" | "replicate" | "minimax" | "custom_openai_compatible" | "ollama";
+type ProviderEndpointConnectionType = "managed" | "custom" | "local";
+type ProviderEndpointModality = "text-completion" | "image-generation" | "speech-synthesis" | "speech-recognition" | "embedding";
+type ProviderEndpointTransport = "public_https" | "daemon";
+type ProviderEndpointRuntime = "ollama";
+type ProviderEndpointProtocol = "openai_compatible";
+type ProviderEndpointVisibility = "private" | "marketplace";
+interface ProviderEndpointModelMapping {
+    /** Idapt/OpenRouter-style model id, for example `openai/gpt-5.4`. */
+    model_id: string;
+    /** Upstream API model id sent to the provider. */
+    api_model_id: string;
+}
+/**
+ * A saved BYOK or daemon-local provider endpoint. Provider secrets are
+ * write-only: reads expose only `api_key_preview`.
+ */
+interface ProviderEndpoint {
+    id: string;
+    kind: ProviderEndpointKind;
+    provider_key: ProviderEndpointProviderKey;
+    connection_type: ProviderEndpointConnectionType;
+    display_name: string;
+    transport: ProviderEndpointTransport;
+    runtime: ProviderEndpointRuntime | null;
+    protocol: ProviderEndpointProtocol | null;
+    computer_id: string | null;
+    local_base_url: string | null;
+    visibility: ProviderEndpointVisibility;
+    base_url: string | null;
+    api_key_preview: string;
+    enabled: boolean;
+    default_for_kind: boolean;
+    default_modalities: ProviderEndpointModality[];
+    supported_modalities: ProviderEndpointModality[];
+    model_mappings: ProviderEndpointModelMapping[];
+    last_verified_at: string | null;
+    last_used_at: string | null;
+    last_error_at: string | null;
+    last_error_code: string | null;
+    last_error_message: string | null;
+    created_at: string;
+    updated_at: string;
+}
+interface ManagedProviderPreset {
+    provider_key: ProviderEndpointProviderKey;
+    connection_type: ProviderEndpointConnectionType;
+    label: string;
+    description: string;
+    supported_modalities: ProviderEndpointModality[];
+    requires_api_key: boolean;
+}
+interface ProviderEndpointTestResult {
+    ok: boolean;
+    message: string;
+    status?: number;
+}
+/** One routable serving provider in the catalog. */
+interface AiGatewayProvider {
+    slug: string;
+    name: string;
+    has_direct_connector: boolean;
+}
+/** One usage-breakdown row (model view carries `model_id`; provider view carries `provider_*`). */
+interface AiGatewayUsageRow {
+    model_id?: string | null;
+    provider_slug?: string | null;
+    provider_name?: string | null;
+    cost_usd: number;
+    input_tokens: number;
+    output_tokens: number;
+    calls: number;
+}
+/** Image-model pricing block — flat per-image price (post-markup). */
+interface ImageModelPricing {
+    per_image: number;
+}
+/** An image model from `GET /v1/images/models` (`modality: "image"`). */
+interface ImageModel extends ModelBase {
+    modality: "image";
+    provider_display_name?: string | null;
+    provider_slug?: string | null;
+    /** Post-markup pricing. */
+    pricing: ImageModelPricing;
+    /** Capability block — always an object. */
+    capabilities: Record<string, unknown>;
+    paid: boolean;
+    /** Minimum tier required to use a paid model. */
+    required_tier?: string | null;
+    /** True when the caller's tier is below `required_tier`. */
+    locked?: boolean;
+    speed?: string | null;
+    is_new?: boolean;
+}
+interface ImageGenerationResult {
+    path: string;
+    file_id: string;
+    url: string;
+    raw_url?: string | null;
+    model: string;
+    cost_usd?: number | null;
+}
+/** Audio (TTS) model pricing block — price per 1,000 characters (post-markup). */
+interface AudioModelPricing {
+    per_thousand_chars: number;
+}
+/** Audio (TTS) model capability block (always an object). */
+interface AudioModelCapabilities {
+    max_chars: number;
+}
+/**
+ * A text-to-speech model from `GET /v1/audio/models` (`modality: "audio"`).
+ * Pricing and capabilities are nested objects.
+ */
+interface AudioModel extends ModelBase {
+    modality: "audio";
+    provider_display_name?: string | null;
+    provider_slug?: string | null;
+    pricing: AudioModelPricing;
+    capabilities: AudioModelCapabilities;
+    speed?: string | null;
+    paid: boolean;
+    is_new?: boolean;
+}
+/** Perceived gender of a TTS voice. */
+type TtsVoiceGender = "male" | "female" | "neutral";
+/**
+ * A selectable TTS voice from `GET /v1/audio/voices`. The wire field is
+ * `display_name` (was `name`); `gender` is a non-null enum.
+ */
+interface TtsVoice {
+    id: string;
+    display_name: string;
+    gender: TtsVoiceGender;
+    language?: string | null;
+    provider?: string | null;
+    preview_url?: string | null;
+}
+interface SpeechResult {
+    path: string;
+    file_id: string;
+    url: string;
+    raw_url?: string | null;
+    model: string;
+    voice_id?: string | null;
+    cost_usd?: number | null;
+    char_count: number;
+}
+interface TranscriptionResult {
+    text: string;
+    /**
+     * Present only for the JSON / reference form (`file_id` / `path` / `url`),
+     * which persists the transcript as a `.txt` Drive file. The multipart
+     * `file`-upload form (OpenAI-compatible) returns only `text`.
+     */
+    file_id?: string | null;
+    path?: string | null;
+}
+type SpeechStreamEvent = {
+    type: "chunk";
+    audio: string;
+} | {
+    type: "done";
+    total_bytes?: number;
+    duration_ms?: number;
+    char_count?: number;
+    cached?: boolean;
+} | {
+    type: "error";
+    status?: number;
+    retry_after?: number;
+};
+type TranscriptionStreamEvent = {
+    type: "partial";
+    text: string;
+} | {
+    type: "final";
+    text: string;
+} | {
+    type: "error";
+    status?: number;
+    retry_after?: number;
+};
+/** Workspace resource. Sourced from the crud v1 contract. */
+type Workspace = WorkspaceResponse;
+type WorkspaceMemberRole = "owner" | "admin" | "editor" | "viewer" | "custom";
+/** A workspace member. Sourced from the crud v1 contract. */
+type WorkspaceMember = WorkspaceMemberResponse;
+/** Whether a computer is a self-managed remote box or an idapt-provisioned VM. */
+type ComputerType = "remote" | "managed";
+/** Per-computer daemon logging verbosity. */
+type ComputerLoggingLevel = "minimal" | "standard" | "full";
+/**
+ * Managed-computer lifecycle state. `state` is `null` for `remote` computers
+ * (their reachability is not modelled as a lifecycle).
+ */
+type ComputerState = "unprovisioned" | "provisioning" | "running" | "hibernating" | "hibernated" | "waking" | "stopping" | "stopped" | "terminating" | "terminated";
+/**
+ * Computer record. Self-managed (`type: "remote"`) computers are paired
+ * through the local daemon; idapt-provisioned (`type: "managed"`) computers
+ * expose the full lifecycle `state`.
+ */
+/** Computer record. Sourced from the computers v1 contract. */
+type Computer = ComputerResponse;
+/** One Unix user on a computer, returned by `listUsers`. */
+/** One Unix user on a computer. Sourced from the computers v1 contract. */
+type ComputerUser = ComputerUserResponse;
+/**
+ * Env-var binding row — one credential file mounted as `${name}=$(<...)`
+ * on a user. A binding is addressed by its env-var `name`; there is no
+ * standalone UUID `id`. The bound credential is referenced by `file_id`.
+ */
+/** Env-var binding row. Sourced from the computers v1 contract. */
+type ComputerEnvVar = ComputerEnvVarResponse;
+/** Auto-discovered listening port on a cloud computer. */
+/** Auto-discovered listening port. Sourced from the computers v1 contract. */
+type ComputerPort = ComputerPortResponse;
+/**
+ * `exec` result — single-shot daemon command output. `success` reflects
+ * whether the command exited 0 within its timeout.
+ */
+interface ComputerExecResult {
+    success: boolean;
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    durationMs: number;
+    timedOut: boolean;
+}
+/**
+ * Daemon server info returned inside `test-connection` — a structured
+ * object.
+ */
+interface ComputerServerInfo {
+    version: string;
+    uptime_seconds: number;
+}
+/**
+ * One re-attachable tmux window on the `idapt` session. A tmux window
+ * has no `pid` — it is not a single process.
+ */
+interface TmuxWindow {
+    name: string;
+    active: boolean;
+}
+/** SFTP listing entry as returned by `op: "list"`. */
+interface SftpEntry {
+    name: string;
+    type: "file" | "dir" | "symlink" | string;
+    size?: number | null;
+    mode?: string | null;
+    mtime?: string | null;
+}
+/**
+ * A credential row exposed via `/api/v1/api-keys`. The plaintext `key` is
+ * only present on the create response — there is no way to retrieve it
+ * after that (the server only stores the hash).
+ */
+/** An API key credential row. Sourced from the keys v1 contract. */
+type ApiKey = ApiKeyResponse;
+type NotificationSenderKind = "user" | "agent" | "system" | string;
+/** A notification row. Sourced from the crud v1 contract. */
+type Notification = NotificationResponse;
+/** Per-user toast/sound/quiet-hours/digest config. Sourced from the crud v1 contract. */
+type NotificationConfig = NotificationConfigResponse;
+/** One (type, subtype?, channel) preference row. Sourced from the crud v1 contract. */
+type NotificationPreference = NotificationPreferenceResponse;
+/**
+ * A workspace secret. Stored server-side as a `.credential` file in the
+ * workspace's `.secrets/` folder; the public API masks that detail. The
+ * plaintext `value` is only echoed on the create response (so the caller
+ * can audit what was stored), never on subsequent reads.
+ */
+/** A workspace secret (metadata only — never the plaintext value). */
+type Secret = SecretResponse;
+/** A secret plus its decrypted value — only returned by `reveal`. */
+type SecretWithValue = SecretWithValueResponse;
+/** Datastore (KV) entry. */
+type DatastoreEntry = DatastoreEntryResponse;
+/** Blobs (object storage) object metadata. */
+type BlobObject = BlobObjectResponse;
+/** Idapt Tables — a collection (schema + metadata). */
+type TableCollection = TableCollectionResponse;
+/** Idapt Tables — a record (JSON document). */
+type TableRecord = TableRecordResponse;
+/**
+ * A workspace invitation. The v1 contract keys invitations by `invitee_slug`
+ * — there is no standalone `id` field on the wire. `DELETE` takes the slug
+ * as a query param.
+ */
+interface WorkspaceInvitation {
+    status: "pending" | "accepted" | "declined" | "expired" | string;
+    invitee_slug?: string | null;
+    invitee_display_name?: string | null;
+    inviter_slug?: string | null;
+    inviter_display_name?: string | null;
+    role?: string | null;
+    expires_at?: string | null;
+    created_at: string;
+    responded_at?: string | null;
+}
+/**
+ * Account-level preferences exposed on the v1 surface — the exact set
+ * returned by `GET /v1/settings` and `PATCH /v1/settings`.
+ *
+ * `transformSettings` on the server picks ONLY these v1-stable fields and
+ * deep-snake-cases them. UI-only state (sidebar collapsed groups, modal
+ * counters, theme) is deliberately omitted from the public contract.
+ */
+/** Account preferences from `GET/PATCH /settings`. Sourced from the v1 contract. */
+type Settings = SettingsResponse;
+/**
+ * Account tier. Idapt is pay-as-you-go — there are no subscription plans /
+ * tiers. `"paid"` means the caller has funded real credits (a persistent
+ * credit balance); everyone else is `"free"`.
+ */
+type SubscriptionPlan = "free" | "paid" | string;
+/**
+ * Current account/credit view from `GET /subscription`. Sourced from the v1
+ * contract. Carries the account tier (`plan` / `is_paid`), the credit `balance`
+ * (USD), and the auto top-up settings. There are no subscription periods,
+ * trial / cancel timestamps, or scheduled-downgrade fields — those concepts no
+ * longer exist. Anonymous / unauthenticated callers get the `free` view.
+ *
+ * Stripe correlation ids are excluded at the route boundary — never visible.
+ */
+type Subscription = SubscriptionResponse;
+type ShareResourceType = "chat" | "agent" | "file" | "workspace";
+type SharePermission = "read" | "write" | "admin";
+/**
+ * A share row. The v1 contract identifies a share by its
+ * `(resource_type, resource_id, grantee_actor_id)` triple — there is no
+ * standalone `id` field on the wire.
+ *
+ * The provenance fields are `shared_at` / `shared_by_actor_id`.
+ */
+/** A share grant. Sourced from the crud v1 contract. */
+type Share = ShareResponse;
+/**
+ * Payload of `DELETE /v1/shares` — the unshare echoes back the triple it
+ * removed (no envelope `id`).
+ */
+interface ShareDeletedResult {
+    deleted: true;
+    resource_type: ShareResourceType;
+    resource_id: string;
+    grantee_actor_id: string;
+}
+/** One row in `GET /v1/shared-with-me`. The id IS the shared resource's id. */
+/** One `GET /v1/shared-with-me` row. Sourced from the account v1 contract. */
+type SharedWithMeItem = SharedWithMeItemResponse;
+type StoreItemType = "skill" | "agent" | "computer" | "computer-template" | "workspace" | string;
+/**
+ * A single hub/store item. The catalog has heterogeneous payloads per
+ * type (skills carry `version`/`license`, agents carry icons/prompts,
+ * computer templates carry sizing) so we type the common fields and
+ * leave the rest open.
+ */
+/** A hub/store item. Sourced from the hub v1 contract. */
+type StoreItem = StoreItemResponse;
+/**
+ * Returned by `POST /v1/store/:id/install`. Open shape per template type.
+ * `id` is always present (the installed resource's resourceId).
+ */
+interface StoreInstallResult {
+    /** The installed resource's resourceId — always present. */
+    id: string;
+    installed: boolean;
+    /** When the install lands as files in a workspace, the parent folder id. */
+    folder_id?: string | null;
+    /** When the install creates an agent, the new agent id. */
+    agent_id?: string | null;
+    /** Echoed back so callers can chain on the installed surface. */
+    resource_type?: StoreItemType;
+    resource_id?: string;
+    [k: string]: unknown;
+}
+/**
+ * Response shape of `POST /chats/:id/messages/:message_id/reprompt`.
+ *  - `wait=true` (default): returns `{ status: "completed", ..., message? }`
+ *  - `wait=false` or timeout: returns `{ status: "pending", ... }`
+ *
+ * The async status is `"pending"`. `reprompted_message_id` echoes the
+ * user message the reprompt targets.
+ */
+type RepromptResult = {
+    status: "completed";
+    chat_id: string;
+    reprompted_message_id: string;
+    model_id: string | null;
+    /** The new assistant sibling. Null when we couldn't locate it post-run. */
+    message: Message | null;
+} | {
+    status: "pending";
+    chat_id: string;
+    reprompted_message_id: string;
+};
+interface SearchResult {
+    id: string;
+    source?: string | null;
+    source_id?: string | null;
+    resource_id?: string | null;
+    title?: string | null;
+    content?: string | null;
+    score?: number | null;
+    is_folder?: boolean;
+    mime_type?: string | null;
+    extension?: string | null;
+    parent_name?: string | null;
+    icon?: string | null;
+    chat_title?: string | null;
+    message_type?: "user" | "assistant" | null;
+    agent_name?: string | null;
+    workspace_resource_id?: string | null;
+    workspace_name?: string | null;
+    profile_slug?: string | null;
+    display_image?: string | null;
+    updated_at?: string | null;
+    computer_name?: string | null;
+    computer_hostname?: string | null;
+    [k: string]: unknown;
+}
+interface WebSearchHit {
+    title: string;
+    url: string;
+    text?: string;
+    published_date?: string | null;
+    author?: string | null;
+}
+interface WebSearchResponse {
+    query: string;
+    results: WebSearchHit[];
+}
+/** Permission descriptor — server-side `Permission` mirror. */
+interface Permission {
+    resource: string;
+    scope?: string | null;
+    access?: "read" | "write" | "admin";
+}
+/**
+ * Which backing the client is wired against. Always `"remote"` — the client
+ * talks to the Idapt backend, either via the cookie/bootstrap flow (hosted on
+ * an app subdomain) or library mode with an explicit `key`. Browser apps are
+ * **npm-only**: there is no off-Idapt local mode.
+ */
+type RuntimeMode = "remote";
+interface ClientMeta {
+    appId: string;
+    apiUrl: string;
+    appFolderId: string;
+    dataFolderId: string;
+    /** Which backing the client is wired against (always `"remote"`). */
+    mode: RuntimeMode;
+}
+/**
+ * How the client authenticates each request:
+ *
+ *   - `"bearer"` — send the raw `key` as `Authorization: Bearer`. Library mode
+ *     (explicit key) and any credential carrying a raw key.
+ *   - `"cookie"` — the httpOnly `__Secure-idapt_app_key` cookie carries auth;
+ *     there is no raw `key`. Hosted cookie-bootstrap flow. Requests go out
+ *     with `credentials: "include"` and no bearer header.
+ */
+type AuthMode = "bearer" | "cookie";
+/**
+ * The credential the client was constructed from.
+ *
+ * Two shapes (both `"remote"` — there is no off-Idapt local mode):
+ *   - **library bearer** — `{ key, apiUrl, mode: "remote", auth: "bearer" }`.
+ *   - **cookie bootstrap** — `{ key: null, apiUrl, mode: "remote",
+ *     auth: "cookie", appResourceId }`. The DB-first hosted flow: the raw
+ *     `ap_` key lives only in the httpOnly cookie, so `key` is `null` and auth
+ *     rides the cookie. `appResourceId` scopes the data KV (`RemoteDataStore`).
+ *
+ * `appFolderId` / `dataFolderId` are legacy Drive-folder ids — kept for the
+ * `ClientMeta` surface. DB-first cookie boots no longer carry them (there is no
+ * Drive folder); they default to `""`.
+ */
+interface StoredCredential {
+    /** The `ap_` / `uk_` bearer, or `null` in cookie mode (cookie carries auth). */
+    key: string | null;
+    /** API origin. */
+    apiUrl: string;
+    appResourceId?: string;
+    appFolderId: string;
+    dataFolderId: string;
+    /** Always `"remote"`; defaults to `"remote"` when omitted. */
+    mode?: RuntimeMode;
+    /**
+     * Auth transport. Defaults to `"bearer"`. Set to `"cookie"` for the hosted
+     * bootstrap flow (no raw key — the httpOnly cookie carries auth).
+     */
+    auth?: AuthMode;
+}
+interface CallOptions {
+    signal?: AbortSignal;
+}
+interface WriteOptions extends CallOptions {
+    expectedUpdatedAt?: string;
+}
+interface ConnectOptions {
+    apiUrl?: string;
+    browserAppDomain?: string;
+    /**
+     * Explicit bearer (`uk_` / `pk_` / `ap_`) for **library mode**. When set,
+     * the SDK skips the cookie bootstrap and connects directly to `apiUrl` with
+     * this key as the Bearer token. Requires `apiUrl`.
+     */
+    key?: string;
+    debug?: boolean;
+    fetch?: typeof fetch;
+    location?: Pick<Location, "hostname" | "pathname" | "origin" | "href" | "search">;
+}
+type EscalateRequest = Permission | Permission[];
+
+/**
+ * AppFolder — read-only access to the app's own code/bundle.
+ *
+ * Browser apps can list and read files from their own bundle to inspect their
+ * manifest, bundled assets, etc. They cannot write here — that would be the
+ * equivalent of a mobile app self-modifying its IPA bundle at runtime.
+ *
+ * `AppFolder` delegates every read to a {@link BundleReader}. The only
+ * implementation is {@link RemoteBundleReader}, which reads the app's Drive
+ * code folder through the same `/api/v1/drive/files/*` endpoints every other
+ * file surface uses (id-addressed). The `BundleReader` seam is kept so the
+ * accessor stays trivially testable with an injected reader.
+ */
+
+/**
+ * The minimal read surface `AppFolder` needs. {@link RemoteBundleReader}
+ * implements it; the interface is kept as a seam so tests can inject a fake
+ * reader without an HTTP context. `id` arguments are Drive file ids.
+ */
+interface BundleReader {
+    /** The bundle/code-folder id. */
+    readonly id?: string;
+    /** List the bundle root. */
+    list(opts?: CallOptions): Promise<File[]>;
+    /** List a specific subfolder. */
+    listFolder(parentId: string, opts?: CallOptions): Promise<File[]>;
+    /** Read text by Drive file id. */
+    read(id: string, opts?: CallOptions): Promise<string>;
+    /** Read + parse JSON. */
+    readJSON<T = unknown>(id: string, opts?: CallOptions): Promise<T>;
+    /** Read raw bytes as a Blob, preserving Content-Type. */
+    readBlob(id: string, opts?: CallOptions): Promise<Blob>;
+}
+/**
+ * Remote `BundleReader` — the historical Drive-backed behaviour, talking to
+ * `/api/v1/drive/files/*` scoped to the app's code folder.
+ */
+declare class RemoteBundleReader implements BundleReader {
+    private readonly ctx;
+    readonly id: string;
+    constructor(ctx: HttpContext, id: string);
+    list(opts?: CallOptions): Promise<File[]>;
+    listFolder(parentId: string, opts?: CallOptions): Promise<File[]>;
+    read(fileId: string, opts?: CallOptions): Promise<string>;
+    readJSON<T = unknown>(fileId: string, opts?: CallOptions): Promise<T>;
+    readBlob(fileId: string, opts?: CallOptions): Promise<Blob>;
+}
+declare class AppFolder {
+    private readonly reader;
+    /**
+     * Two construction shapes:
+     *
+     *   - `new AppFolder(ctx, folderId)` — builds a {@link RemoteBundleReader}
+     *     internally. The normal path.
+     *   - `new AppFolder(reader)` — inject any {@link BundleReader} (e.g. a fake
+     *     in tests).
+     */
+    constructor(ctxOrReader: HttpContext | BundleReader, folderId?: string);
+    /** The code folder's id. */
+    get id(): string;
+    /** List files in the app folder. */
+    list(opts?: CallOptions): Promise<File[]>;
+    /** List a specific subfolder of the app folder. */
+    listFolder(parentId: string, opts?: CallOptions): Promise<File[]>;
+    /**
+     * Read a file's text content (by Drive file id). UTF-8 decoded; use
+     * `readBlob` for binary.
+     */
+    read(fileId: string, opts?: CallOptions): Promise<string>;
+    /** Read + parse JSON in one call. */
+    readJSON<T = unknown>(fileId: string, opts?: CallOptions): Promise<T>;
+    /** Read a file's raw bytes as a Blob. Preserves the server's MIME type. */
+    readBlob(fileId: string, opts?: CallOptions): Promise<Blob>;
+}
+
+/**
+ * DataFolder — read-write access to the app's **per-(user × app) data store**.
+ *
+ * This is where browser apps persist per-user state (preferences, history,
+ * caches). `DataFolder` delegates every operation to a {@link DataStore}; the
+ * only implementation is {@link RemoteDataStore} (`./data-remote.ts`), which
+ * backs onto the dedicated app-data KV at `/api/browser-app/data/{appResId}/{key}`
+ * (DB-first — NOT Drive). Each entry is scoped to the app's principal → blast
+ * radius is exactly this app's own sandbox. The KV is a **flat key/value
+ * namespace**: the key doubles as the file id AND name (there are no folders).
+ * The `DataStore` interface is kept as a testing seam.
+ *
+ * Three layers are exposed:
+ *
+ *   **Name-based** (ergonomic, the 95% case):
+ *     set/get/has/remove/setJSON/getJSON — keyed by name (== the KV key).
+ *
+ *   **key-based** (raw, for apps that want full control):
+ *     list/read/write/delete/readJSON/writeJSON + upload (the key is the id).
+ *
+ *   **Subfolders** (`createFolder`/`move`/`listFolder`): the flat KV has no
+ *     folder analogue and throws a typed `InvalidRequestError`.
+ */
+
+/** Upload input at the store layer (already resolved against the data folder). */
+interface DataStoreUploadInput {
+    file: Blob | globalThis.File;
+    name?: string;
+    /** Resolved parent; the store defaults a missing value to its root. */
+    parent_id?: string;
+    skip_if_exists?: boolean;
+}
+/** Create-folder input at the store layer. */
+interface DataStoreCreateFolderInput {
+    name: string;
+    parent_id?: string;
+    icon?: string;
+}
+/**
+ * The read-write surface `DataFolder` needs. {@link RemoteDataStore} implements
+ * it; the interface is kept as a seam so tests can inject a fake store. Methods
+ * mirror the v1 Drive operations the name-cache / OCC logic composes.
+ */
+interface DataStore {
+    /** The data store's id (the app resource id). */
+    readonly id: string;
+    /** API origin. */
+    readonly apiUrl?: string | null;
+    list(opts?: CallOptions): Promise<File[]>;
+    listFolder(parentId: string, opts?: CallOptions): Promise<File[]>;
+    getMetadata(fileId: string, opts?: CallOptions): Promise<File>;
+    read(fileId: string, opts?: CallOptions): Promise<string>;
+    readBlob(fileId: string, opts?: CallOptions): Promise<Blob>;
+    write(fileId: string, content: string, opts?: WriteOptions): Promise<File>;
+    delete(fileId: string, opts?: CallOptions): Promise<DeletedResponse>;
+    upload(input: DataStoreUploadInput, opts?: CallOptions): Promise<FileUploadResult>;
+    createFolder(input: DataStoreCreateFolderInput, opts?: CallOptions): Promise<File>;
+    move(fileId: string, parentId: string | null, opts?: CallOptions): Promise<File>;
+}
+interface DataUploadInput {
+    file: Blob | globalThis.File;
+    /** Override the name stored in the database. */
+    name?: string;
+    /** Subfolder within the data folder; defaults to the data folder root. */
+    parent_id?: string;
+    skip_if_exists?: boolean;
+}
+interface DataCreateFolderInput {
+    name: string;
+    /** Nest under another folder inside the data folder. Defaults to data root. */
+    parent_id?: string;
+    icon?: string;
+}
+declare class DataFolder {
+    /** name (lowercased) → fileId, populated lazily by list() / set(). */
+    private readonly nameCache;
+    private nameCacheLoaded;
+    private readonly store;
+    /**
+     * Two construction shapes:
+     *
+     *   - `new DataFolder(ctx, appResourceId)` — builds a {@link RemoteDataStore}
+     *     internally, scoped by the app's RESOURCE id (the `{appResId}` segment of
+     *     the KV path), NOT a Drive folder id. The normal path.
+     *   - `new DataFolder(store)` — inject any {@link DataStore} (e.g. a fake in
+     *     tests).
+     */
+    constructor(ctxOrStore: HttpContext | DataStore, appResourceId?: string);
+    /** The data folder's id — useful for passing to other SDK calls. */
+    get id(): string;
+    /** List every file in the data folder (top level only, excluding subfolders' contents). */
+    list(opts?: CallOptions): Promise<File[]>;
+    /** List a specific subfolder within the data folder. */
+    listFolder(parentId: string, opts?: CallOptions): Promise<File[]>;
+    /** Read a file's raw text content by id. UTF-8 decoded. */
+    read(fileId: string, opts?: CallOptions): Promise<string>;
+    /** Read and parse as JSON. */
+    readJSON<T = unknown>(fileId: string, opts?: CallOptions): Promise<T>;
+    /** Read raw bytes as a Blob. Use for binary files stored in data folder. */
+    readBlob(fileId: string, opts?: CallOptions): Promise<Blob>;
+    /** PATCH content on an existing file id (optimistic concurrency via opts). */
+    write(fileId: string, content: string, opts?: WriteOptions): Promise<File>;
+    /** Stringify and PATCH. */
+    writeJSON<T>(fileId: string, data: T, opts?: WriteOptions): Promise<File>;
+    /** Move the file to trash. */
+    delete(fileId: string, opts?: CallOptions): Promise<void>;
+    /**
+     * Multipart upload a Blob or File into the data folder (or a subfolder of
+     * it). Returns the upload record. Use this for binary data; for text/JSON
+     * prefer the name-based `set()` / `setJSON()`.
+     */
+    upload(input: DataUploadInput, opts?: CallOptions): Promise<FileUploadResult>;
+    /**
+     * Create (or get) a subfolder inside the data folder. Returns the folder
+     * record — store the `id` to use as `parent_id` for nested uploads /
+     * `createFolder` calls. Idempotent by name at the given parent.
+     */
+    createFolder(input: DataCreateFolderInput, opts?: CallOptions): Promise<File>;
+    /**
+     * Move a file or subfolder within the data folder. Pass the data folder's
+     * own id (or omit `parentId`) to move it back to the data-folder root.
+     */
+    move(fileId: string, parentId?: string | null, opts?: CallOptions): Promise<File>;
+    /**
+     * Upsert a file by name. Creates it on first call, PATCHes it on
+     * subsequent calls. Returns the resolved file metadata.
+     */
+    set(name: string, content: string, opts?: WriteOptions): Promise<File>;
+    /** Stringify-and-upsert. */
+    setJSON<T>(name: string, data: T, opts?: WriteOptions): Promise<File>;
+    /**
+     * Read a file by name. Returns `null` if the file doesn't exist (rather
+     * than throwing) — this is the common "first-run preferences" case.
+     */
+    get(name: string, opts?: CallOptions): Promise<string | null>;
+    /** Read + parse JSON, or null if the file doesn't exist. */
+    getJSON<T = unknown>(name: string, opts?: CallOptions): Promise<T | null>;
+    /** Does a file with this name exist? */
+    has(name: string, opts?: CallOptions): Promise<boolean>;
+    /**
+     * Delete a file by name. Returns `true` if something was deleted, `false`
+     * if the file didn't exist.
+     */
+    remove(name: string, opts?: CallOptions): Promise<boolean>;
+    /**
+     * Find the file id for a given name, or null. Populates the name→id cache
+     * on first call.
+     */
+    resolve(name: string, opts?: CallOptions): Promise<File | null>;
+    /** Drop the name→id cache. Next call will re-list. */
+    invalidate(): void;
+    /**
+     * Create a new file at the data-folder root via multipart upload. The
+     * `skip_if_exists` flag hedges against concurrent creates; if another tab
+     * wins the race, we re-list and PATCH instead.
+     */
+    private createByName;
+    private rebuildNameCache;
+}
+
+export { type LLMModelPricing as $, type AiGatewayProvider as A, type BlobObject as B, type CallOptions as C, type DataStore as D, type ComputerServerInfo as E, type File as F, type ComputerState as G, type HttpContext as H, type ComputerType as I, type ComputerUser as J, type CreateTriggerInput as K, type DataCreateFolderInput as L, DataFolder as M, type DataUploadInput as N, type DatastoreEntry as O, type EscalateRequest as P, type ExecutionBackend as Q, type ExecutionRun as R, type ExecutionRunStatus as S, type FileList as T, type HttpRequest as U, type ImageGenerationResult as V, type WriteOptions as W, type ImageModel as X, type ImageModelPricing as Y, type LLMModel as Z, type LLMModelCapabilities as _, type AiGatewayUsageRow as a, type UsageRecord as a$, type ListEnvelope as a0, type ManagedProviderPreset as a1, type Message as a2, type MessageCostEntry as a3, type MessageCosts as a4, type ModelBase as a5, type ModelModality as a6, type Notification as a7, type NotificationConfig as a8, type NotificationPreference as a9, type ShareDeletedResult as aA, type SharePermission as aB, type ShareResourceType as aC, type SharedWithMeItem as aD, type SingleEnvelope as aE, type SpeechResult as aF, type SpeechStreamEvent as aG, type StoreInstallResult as aH, type StoreItem as aI, type StoreItemType as aJ, type StoredCredential as aK, type Subscription as aL, type SubscriptionPlan as aM, type TableCollection as aN, type TableRecord as aO, type TmuxWindow as aP, type TranscriptionResult as aQ, type TranscriptionStreamEvent as aR, type Trigger as aS, type TriggerActionType as aT, type TriggerCostStats as aU, type TriggerRun as aV, type TriggerType as aW, type TriggerWithSecret as aX, type TtsVoice as aY, type TtsVoiceGender as aZ, type UpdateTriggerInput as a_, type NotificationSenderKind as aa, type Pagination as ab, type Permission as ac, type ProviderEndpoint as ad, type ProviderEndpointConnectionType as ae, type ProviderEndpointKind as af, type ProviderEndpointModality as ag, type ProviderEndpointModelMapping as ah, type ProviderEndpointProtocol as ai, type ProviderEndpointProviderKey as aj, type ProviderEndpointRuntime as ak, type ProviderEndpointTestResult as al, type ProviderEndpointTransport as am, type ProviderEndpointVisibility as an, type QueryInput as ao, RemoteBundleReader as ap, type RepromptResult as aq, type RunCostMetrics as ar, type RuntimeMode as as, type SearchResult as at, type Secret as au, type SecretWithValue as av, type SendMessageResult as aw, type Settings as ax, type SftpEntry as ay, type Share as az, type DeletedResponse as b, type UsageSummary as b0, type User as b1, type WebSearchHit as b2, type WebSearchResponse as b3, type Workspace as b4, type WorkspaceInvitation as b5, type WorkspaceMember as b6, type WorkspaceMemberRole as b7, buildUrl as b8, request as b9, requestRaw as ba, type DataStoreUploadInput as c, type FileUploadResult as d, type DataStoreCreateFolderInput as e, type ConnectOptions as f, type Agent as g, type AgentRun as h, type AgentRunState as i, type ApiKey as j, AppFolder as k, type AudioModel as l, type AudioModelCapabilities as m, type AudioModelPricing as n, type AuthMode as o, type BundleReader as p, type Chat as q, type ChatCost as r, type ChatCostByCallType as s, type ChatStopResult as t, type ClientMeta as u, type Computer as v, type ComputerEnvVar as w, type ComputerExecResult as x, type ComputerLoggingLevel as y, type ComputerPort as z };