@vibiz/sdk 0.0.0-stage → 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,751 @@
+import type { ActionUsage, AdminMetrics, AiJob, AiModelInfo, AiProviderKey, AiProviderKeyInput, AiProviderKeyList, AiSettings, AnalyticsPeriod, AnalyticsReport, ApiKey, AppKeyInfo, AuthEnvironment, AuthProviderId, AuthProviderInput, AuthSettings, AuthSettingsPatch, Billing, BillingCharge, BillingCheckout, BillingEntry, BillingEntryKind, BillingList, BillingUpdate, ChatChunk, ChatCompletion, ChatRequest, Checkout, CheckoutInput, Company, CompanyAddressFields, CompanyCatalog, CompanyDraft, CompanyEnvironment, CompanyLink, Connector, ConnectorApproval, ConnectorCall, ConnectorCallInput, ConnectorCheck, ConnectorEnvironment, ConnectorImport, ConnectorInput, ConnectorPatch, ConnectorResponse, DashboardLink, DeployFile, Deployment, DevEnvironment, EnvTargetInfo, HostKind, ImageRequest, ImageResult, KeyAccess, LedgerEntry, MetricsReport, Operation, Payment, PaymentPrice, PaymentPriceInput, PaymentProduct, PaymentSubscription, PaymentsAccount, PaymentsEnvironment, PaymentsList, PaymentsSimulation, Project, ReplayDetail, ReplayInsights, ReplayListOptions, ReplayPeriod, ReplayStatus, ReplaySummary, Resource, ResourceType, SendEmailInput, SendEmailOutput, SocialAccount, SocialAccountAnalytics, SocialAdCampaign, SocialAdChange, SocialAdChangeInput, SocialConnectLink, SocialEnvironment, SocialMedia, SocialOverview, SocialPost, SocialPostAnalytics, SocialPostInput, SpeechRequest, Transcription, UsageOptions, UsagePeriod, UsageReport, WebhookDelivery, WebhookEventType, Withdrawal } from './types.js';
+export declare class VibizApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details?: unknown | undefined;
+    constructor(status: number, code: string, message: string, details?: unknown | undefined);
+}
+export interface VibizOptions {
+    apiKey: string;
+    /** Required: the Vibiz API base URL. */
+    baseUrl: string;
+    fetch?: typeof fetch;
+    /**
+     * Your own end user, sent as `X-Vibiz-User` on every call so spend shows per
+     * end user (and per-end-user AI budgets apply). A stable pseudonymous id,
+     * not an email.
+     */
+    user?: string;
+}
+/**
+ * The typed client for the Vibiz Stack API. Used by the CLI, by Principia's
+ * gateway tools and by anyone building on the API.
+ */
+export declare class Vibiz {
+    private readonly options;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options: VibizOptions);
+    private send;
+    private fail;
+    /** A raw response (audio, a stream), failing like `request` on an error status. */
+    private stream;
+    private request;
+    private postAction;
+    readonly projects: {
+        create: (input: {
+            name: string;
+            slug?: string;
+            resources?: ResourceType[];
+        }, opts?: {
+            idempotencyKey?: string;
+        }) => Promise<{
+            project: Project;
+            operations: Operation[];
+        }>;
+        list: () => Promise<Project[]>;
+        get: (id: string) => Promise<Project>;
+        delete: (id: string) => Promise<{
+            project: Project;
+            operations: Operation[];
+        }>;
+        /** Undo a delete within 7 days: data was kept, the site is provisioned again. */
+        restore: (id: string) => Promise<{
+            project: Project;
+            operations: Operation[];
+        }>;
+        addResource: (id: string, type: ResourceType) => Promise<{
+            resource: Resource;
+            operations: Operation[];
+        }>;
+        /** Change a resource's settings (merged), e.g. `('replay', { sample_rate: 0.1 })`. */
+        configureResource: (id: string, type: ResourceType, config: Record<string, unknown>) => Promise<Resource>;
+        /** Run a project-scoped action, such as `email.send`. */
+        runAction: <O = unknown>(id: string, name: string, input: unknown, opts?: {
+            idempotencyKey?: string;
+        }) => Promise<{
+            output: O;
+            cost_micro_usd: number | null;
+            usage: ActionUsage | null;
+        }>;
+        /** The production env. Owner keys only: an agent key gets `forbidden` (use `dev`). */
+        env: (id: string) => Promise<Record<string, string>>;
+        /** The production env's variable names, without values. Any key. */
+        envNames: (id: string) => Promise<string[]>;
+        /**
+         * The development environment: its own database branch (schema, no
+         * production rows), its own sign-in and AI key. What agents and laptops use.
+         */
+        dev: {
+            get: (id: string) => Promise<DevEnvironment>;
+            start: (id: string) => Promise<DevEnvironment>;
+            env: (id: string) => Promise<Record<string, string>>;
+            remove: (id: string) => Promise<{
+                status: string;
+            }>;
+            /** Start it if needed and wait until ready, then return its env. */
+            ensure: (id: string, opts?: {
+                timeoutMs?: number;
+                intervalMs?: number;
+            }) => Promise<Record<string, string>>;
+        };
+        /** The app key (`vz_app_…`), per environment. The secret itself only ever travels in the env. */
+        appKeys: {
+            list: (id: string) => Promise<AppKeyInfo[]>;
+            /** Production's needs an owner key. The old key works for `grace_seconds` (default 3600). */
+            rotate: (id: string, opts?: {
+                environment?: "production" | "development";
+                grace_seconds?: number;
+            }) => Promise<AppKeyInfo>;
+        };
+        /** Hosts outside Vibiz that receive the env server to server. Connecting needs an owner key. */
+        hosts: {
+            list: (id: string) => Promise<EnvTargetInfo[]>;
+            add: (id: string, input: {
+                /** `vercel`, `netlify`, `render`, `railway`, `fly`, `heroku`, `cloudflare-workers`, `cloudflare-pages`, `github-actions`. */
+                kind: string;
+                token: string;
+                /** The host's fields (see `hostKinds()`): `{ project }`, `{ site }`, `{ service }`, `{ app }`, `{ repo }`… */
+                config?: Record<string, string>;
+                project?: string;
+                team_id?: string;
+                environments?: Array<"production" | "development">;
+            }) => Promise<EnvTargetInfo>;
+            sync: (id: string) => Promise<EnvTargetInfo[]>;
+            remove: (id: string, targetId: string, opts?: {
+                keepValues?: boolean;
+            }) => Promise<EnvTargetInfo>;
+        };
+        /**
+         * The app's own database. `production` needs an owner key (it holds the
+         * app's users' data); agents read `development`, the default for them.
+         */
+        database: {
+            tables: (id: string, env?: "production" | "development") => Promise<{
+                environment: string;
+                tables: Array<Record<string, unknown>>;
+            }>;
+            /** Read-only: one SELECT / WITH / EXPLAIN / SHOW statement, 5 s, 500 rows. */
+            query: (id: string, sql: string, env?: "production" | "development") => Promise<{
+                columns: string[];
+                rows: Record<string, unknown>[];
+                row_count: number;
+                truncated: boolean;
+            }>;
+        };
+        /**
+         * How people sign in to the app (docs/SIGN-IN.md). `production` needs an
+         * owner key; agents work on `development`, the default for them.
+         */
+        auth: {
+            get: (id: string, env?: AuthEnvironment) => Promise<AuthSettings>;
+            update: (id: string, patch: AuthSettingsPatch, env?: AuthEnvironment) => Promise<AuthSettings>;
+            /** Turn a social provider on, with shared keys or the customer's own OAuth app. */
+            setProvider: (id: string, provider: AuthProviderId, input: AuthProviderInput, env?: AuthEnvironment) => Promise<AuthSettings>;
+            removeProvider: (id: string, provider: AuthProviderId, env?: AuthEnvironment) => Promise<AuthSettings>;
+            /** Owner only: a test message through the SMTP sender already set. */
+            testEmail: (id: string, to: string, env?: AuthEnvironment) => Promise<{
+                success: boolean;
+                error_message?: string;
+            }>;
+        };
+        /**
+         * The business behind the project (docs/COMPANY.md). `env` defaults like
+         * the API: production for owners, development for agents. Production
+         * submit, signing, actions and documents need an owner key.
+         */
+        company: {
+            get: (id: string, env?: CompanyEnvironment) => Promise<Company>;
+            /** Create or replace the draft. */
+            draft: (id: string, draft: CompanyDraft, env?: CompanyEnvironment) => Promise<Company>;
+            /** Change part of the draft: top-level keys replace, `null` clears one. */
+            update: (id: string, patch: Partial<CompanyDraft>, env?: CompanyEnvironment) => Promise<Company>;
+            remove: (id: string, env?: CompanyEnvironment) => Promise<{
+                object: "company";
+                id: string;
+                deleted: true;
+            }>;
+            /**
+             * Production files for real and charges the price: an owner key, `confirm: true`,
+             * and the `quote.total_cents` and `updated_at` of the draft that was reviewed
+             * (a draft or price changed since is refused with a 409, not filed).
+             */
+            submit: (id: string, input: {
+                accept_terms: true;
+                confirm?: boolean;
+                expected_total_cents?: number;
+                expected_updated_at?: string;
+            }, env?: CompanyEnvironment) => Promise<Company>;
+            /**
+             * Pay a live filing by card instead of from the balance (owner keys): the same
+             * body as `submit`; it is filed when the payment arrives (docs/BILLING.md "Company").
+             */
+            checkout: (id: string, input: {
+                accept_terms: true;
+                confirm: true;
+                expected_total_cents: number;
+                expected_updated_at: string;
+            }) => Promise<BillingCheckout>;
+            /** A fresh signing link; show it to the signer right away, it voids the previous one. */
+            sign: (id: string, document: "ss4" | "form_8821", env?: CompanyEnvironment) => Promise<CompanyLink & {
+                object: "company_signature";
+                document: string;
+            }>;
+            /** Answer a required action: new names, or the founder's own US address. */
+            resolve: (id: string, actionId: string, input: {
+                names: Array<{
+                    name: string;
+                    ending?: string;
+                }>;
+            } | {
+                address: CompanyAddressFields;
+            }, env?: CompanyEnvironment) => Promise<Company>;
+            /** A short-lived download link. */
+            document: (id: string, documentId: string, env?: CompanyEnvironment) => Promise<CompanyLink & {
+                object: "company_document_link";
+                id: string;
+                name: string;
+            }>;
+            refresh: (id: string, env?: CompanyEnvironment) => Promise<Company>;
+            /** Development only: complete formation or the EIN at the sandbox. */
+            simulate: (id: string, step: "formation" | "ein") => Promise<Company>;
+        };
+        /**
+         * Social (docs/SOCIAL.md): the project's own social and ad accounts. `env`
+         * defaults like the API: production for owners, development (a sandbox:
+         * nothing is posted or spent) for agents. On production an agent's posts
+         * and ad changes wait for the owner (`pending_approval`); an owner sends
+         * `confirm: true`.
+         */
+        social: {
+            get: (id: string, env?: SocialEnvironment) => Promise<SocialOverview>;
+            accounts: (id: string, opts?: {
+                env?: SocialEnvironment;
+                kind?: "social" | "ads";
+                platform?: string;
+            }) => Promise<{
+                object: "list";
+                data: SocialAccount[];
+                has_more: boolean;
+            }>;
+            /** A link (1 h) for the owner to open and sign in to the platform. */
+            connect: (id: string, platform: string, opts?: {
+                ads?: boolean;
+                env?: SocialEnvironment;
+            }) => Promise<SocialConnectLink>;
+            refreshAccounts: (id: string, env?: SocialEnvironment) => Promise<{
+                object: "list";
+                data: SocialAccount[];
+            }>;
+            disconnect: (id: string, accountId: string, env?: SocialEnvironment) => Promise<SocialAccount>;
+            accountAnalytics: (id: string, accountId: string, opts?: {
+                env?: SocialEnvironment;
+                from?: string;
+                to?: string;
+            }) => Promise<SocialAccountAnalytics>;
+            /** Upload a file (bytes and their content type) → a URL to post with. */
+            upload: (id: string, file: {
+                bytes: Uint8Array;
+                contentType: string;
+                filename?: string;
+            }, env?: SocialEnvironment) => Promise<SocialMedia>;
+            posts: (id: string, opts?: {
+                env?: SocialEnvironment;
+                status?: string;
+                account?: string;
+                platform?: string;
+                from?: string;
+                to?: string;
+                cursor?: string;
+                limit?: number;
+            }) => Promise<{
+                object: "list";
+                data: SocialPost[];
+                has_more: boolean;
+                next_cursor: string | null;
+            }>;
+            post: (id: string, postId: string, env?: SocialEnvironment) => Promise<SocialPost>;
+            create: (id: string, input: SocialPostInput, env?: SocialEnvironment) => Promise<SocialPost>;
+            publish: (id: string, postId: string, input?: {
+                schedule_at?: string | null;
+                timezone?: string | null;
+                confirm?: boolean;
+            }, env?: SocialEnvironment) => Promise<SocialPost>;
+            approve: (id: string, postId: string, input?: {
+                schedule_at?: string | null;
+            }, env?: SocialEnvironment) => Promise<SocialPost>;
+            reject: (id: string, postId: string, env?: SocialEnvironment) => Promise<SocialPost>;
+            retry: (id: string, postId: string, input?: {
+                confirm?: boolean;
+            }, env?: SocialEnvironment) => Promise<SocialPost>;
+            refresh: (id: string, postId: string, env?: SocialEnvironment) => Promise<SocialPost>;
+            /** Cancel a draft, a waiting or a scheduled post. */
+            cancel: (id: string, postId: string, env?: SocialEnvironment) => Promise<SocialPost>;
+            postAnalytics: (id: string, postId: string, env?: SocialEnvironment) => Promise<SocialPostAnalytics>;
+            campaigns: (id: string, opts?: {
+                env?: SocialEnvironment;
+                account?: string;
+                ad_account?: string;
+                from?: string;
+                to?: string;
+            }) => Promise<{
+                object: "list";
+                data: SocialAdCampaign[];
+            }>;
+            adChanges: (id: string, opts?: {
+                env?: SocialEnvironment;
+                status?: string;
+            }) => Promise<{
+                object: "list";
+                data: SocialAdChange[];
+            }>;
+            adChange: (id: string, input: SocialAdChangeInput, env?: SocialEnvironment) => Promise<SocialAdChange>;
+            approveAdChange: (id: string, changeId: string, env?: SocialEnvironment) => Promise<SocialAdChange>;
+            rejectAdChange: (id: string, changeId: string, env?: SocialEnvironment) => Promise<SocialAdChange>;
+        };
+        /**
+         * Payments (docs/PAYMENTS.md): Vibiz is the merchant, so an app sells from
+         * its first call. `env` defaults like the API: production for owners,
+         * development for agents. On production, refunds, cancels, withdrawing,
+         * payout setup and webhook settings need an owner key.
+         */
+        payments: {
+            get: (id: string, env?: PaymentsEnvironment) => Promise<PaymentsAccount>;
+            update: (id: string, patch: {
+                statement_descriptor_suffix?: string | null;
+                webhook_url?: string | null;
+                webhook_events?: WebhookEventType[];
+            }, env?: PaymentsEnvironment) => Promise<PaymentsAccount>;
+            /** A new signing secret, shown once (also put in the app's env as VIBIZ_WEBHOOK_SECRET). */
+            rotateWebhookSecret: (id: string, env?: PaymentsEnvironment) => Promise<{
+                object: "webhook_secret";
+                secret: string;
+            }>;
+            deliveries: (id: string, env?: PaymentsEnvironment) => Promise<PaymentsList<WebhookDelivery>>;
+            products: {
+                list: (id: string, env?: PaymentsEnvironment) => Promise<PaymentsList<PaymentProduct>>;
+                create: (id: string, input: {
+                    name: string;
+                    description?: string;
+                    price?: PaymentPriceInput;
+                }, env?: PaymentsEnvironment) => Promise<PaymentProduct>;
+                get: (id: string, productId: string, env?: PaymentsEnvironment) => Promise<PaymentProduct>;
+                update: (id: string, productId: string, patch: {
+                    name?: string;
+                    description?: string | null;
+                    active?: boolean;
+                }, env?: PaymentsEnvironment) => Promise<PaymentProduct>;
+                /** Archive: kept on record, no longer sold. */
+                remove: (id: string, productId: string, env?: PaymentsEnvironment) => Promise<PaymentProduct>;
+                addPrice: (id: string, productId: string, price: PaymentPriceInput, env?: PaymentsEnvironment) => Promise<PaymentPrice>;
+                updatePrice: (id: string, priceId: string, patch: {
+                    active?: boolean;
+                    lookup_key?: string | null;
+                }, env?: PaymentsEnvironment) => Promise<PaymentPrice>;
+            };
+            checkout: (id: string, input: CheckoutInput, env?: PaymentsEnvironment) => Promise<Checkout>;
+            list: (id: string, opts?: {
+                env?: PaymentsEnvironment;
+                cursor?: string;
+                limit?: number;
+                user?: string;
+            }) => Promise<PaymentsList<Payment>>;
+            payment: (id: string, paymentId: string, env?: PaymentsEnvironment) => Promise<Payment>;
+            /** The balance (available + pending) must cover it: `409 insufficient_balance` otherwise. */
+            refund: (id: string, paymentId: string, input?: {
+                amount_cents?: number;
+                reason?: "requested_by_customer" | "duplicate" | "fraudulent";
+            }, env?: PaymentsEnvironment) => Promise<Payment>;
+            subscriptions: (id: string, opts?: {
+                env?: PaymentsEnvironment;
+                user?: string;
+                status?: string;
+            }) => Promise<PaymentsList<PaymentSubscription>>;
+            cancel: (id: string, subscriptionId: string, opts?: {
+                at_period_end?: boolean;
+            }, env?: PaymentsEnvironment) => Promise<PaymentSubscription>;
+            ledger: (id: string, opts?: {
+                env?: PaymentsEnvironment;
+                cursor?: string;
+                limit?: number;
+            }) => Promise<PaymentsList<LedgerEntry>>;
+            /** For the embedded verification, bank and payout UI (Connect.js). Short-lived. */
+            payoutsSession: (id: string, input?: {
+                country?: string;
+            }, env?: PaymentsEnvironment) => Promise<{
+                object: "payouts_session";
+                client_secret: string;
+                publishable_key: string | null;
+                expires_at: string;
+            }>;
+            /** Default: everything available. */
+            withdraw: (id: string, input?: {
+                amount_cents?: number;
+            }, env?: PaymentsEnvironment) => Promise<Withdrawal>;
+            withdrawals: (id: string, env?: PaymentsEnvironment) => Promise<PaymentsList<Withdrawal>>;
+            refresh: (id: string, env?: PaymentsEnvironment) => Promise<PaymentsAccount>;
+            /** Development only: a real test-mode payment, dispute or refund, or release the hold. */
+            simulate: (id: string, input: PaymentsSimulation) => Promise<PaymentsAccount | Payment>;
+        };
+        /**
+         * Custom connectors (docs/CONNECTORS.md): any HTTP API from one manifest,
+         * called through Vibiz, which holds the key. `env` defaults like the API:
+         * production for owners, development for agents. Production keys, and
+         * approving an agent's dangerous call, need an owner key.
+         */
+        connectors: {
+            list: (id: string) => Promise<Connector[]>;
+            get: (id: string, name: string) => Promise<Connector>;
+            /** From a manifest, a short form (`operations: ["GET /posts/{id}"]`) or an import's draft. */
+            create: (id: string, manifest: ConnectorInput | ConnectorImport["manifest"]) => Promise<Connector>;
+            /** Preview an OpenAPI 3 spec (url or the document): nothing is saved. */
+            import: (id: string, input: {
+                url?: string;
+                spec?: unknown;
+                name?: string;
+                base_url?: string;
+                enable?: string[];
+            }) => Promise<ConnectorImport>;
+            update: (id: string, name: string, patch: ConnectorPatch) => Promise<Connector>;
+            delete: (id: string, name: string) => Promise<Connector>;
+            /** Set values (`null` removes). Production: owner keys. Values are never read back. */
+            setSecrets: (id: string, name: string, values: Record<string, string | null>, env?: ConnectorEnvironment) => Promise<Connector>;
+            check: (id: string, name: string, env?: ConnectorEnvironment) => Promise<ConnectorCheck>;
+            /** One operation. A dangerous one (or a production write) by an agent key answers 403 approval_required. */
+            call: <T = unknown>(id: string, name: string, input: ConnectorCallInput, opts?: {
+                env?: ConnectorEnvironment;
+                idempotencyKey?: string;
+            }) => Promise<ConnectorResponse<T>>;
+            calls: (id: string, name: string, opts?: {
+                env?: ConnectorEnvironment;
+                limit?: number;
+                cursor?: string;
+            }) => Promise<PaymentsList<ConnectorCall>>;
+            approvals: (id: string, opts?: {
+                status?: ConnectorApproval["status"];
+            }) => Promise<ConnectorApproval[]>;
+            approval: (id: string, approvalId: string) => Promise<ConnectorApproval>;
+            /** Owner keys. */
+            approve: (id: string, approvalId: string) => Promise<ConnectorApproval>;
+            /** Owner keys. */
+            deny: (id: string, approvalId: string) => Promise<ConnectorApproval>;
+        };
+        /** Where the app also runs outside Vibiz hosting. Adding and removing need an owner key. */
+        domains: {
+            list: (id: string) => Promise<string[]>;
+            add: (id: string, domain: string) => Promise<string[]>;
+            remove: (id: string, domain: string) => Promise<string[]>;
+        };
+        /** Poll until every resource is ready, or throw on the first failure. */
+        waitUntilReady: (id: string, opts?: {
+            timeoutMs?: number;
+            intervalMs?: number;
+        }) => Promise<Project>;
+    };
+    readonly files: {
+        missing: (shas: string[]) => Promise<string[]>;
+        upload: (sha: string, bytes: Uint8Array) => Promise<void>;
+    };
+    readonly deployments: {
+        create: (projectId: string, input: {
+            files: DeployFile[];
+            target?: "preview" | "production";
+        }, opts?: {
+            idempotencyKey?: string;
+        }) => Promise<{
+            deployment: Deployment;
+            operation: Operation;
+        }>;
+        list: (projectId: string) => Promise<Deployment[]>;
+        get: (id: string) => Promise<Deployment>;
+        promote: (id: string) => Promise<{
+            deployment: Deployment;
+            operation: Operation | null;
+            instant: boolean;
+        }>;
+        waitUntilDone: (id: string, opts?: {
+            timeoutMs?: number;
+            intervalMs?: number;
+        }) => Promise<Deployment>;
+    };
+    readonly analytics: {
+        /** Visitors, pageviews, top pages, sources, countries, events and a timeseries. */
+        get: (projectId: string, opts?: {
+            period?: AnalyticsPeriod;
+        }) => Promise<AnalyticsReport>;
+    };
+    /** Session replay. Start from `insights`; open single sessions with `get`. */
+    readonly replays: {
+        /** Rule-based findings over recorded sessions: what broke and where people got stuck. */
+        insights: (projectId: string, opts?: {
+            period?: ReplayPeriod;
+        }) => Promise<ReplayInsights>;
+        /** Recorded sessions, most worth watching first. */
+        list: (projectId: string, opts?: ReplayListOptions) => Promise<{
+            data: ReplaySummary[];
+            has_more: boolean;
+            next_offset: number | null;
+            replay_status: ReplayStatus;
+            /** The same list in the web console. */
+            console_url?: string;
+        }>;
+        /** Metadata, signals, completeness and the timeline of notable moments. */
+        get: (id: string) => Promise<ReplayDetail>;
+        /** The raw rrweb events (masked at the source). Pages with `from_seq` / `max_chunks`. */
+        events: (id: string, opts?: {
+            from_seq?: number;
+            max_chunks?: number;
+            time?: "browser" | "server";
+        }) => Promise<{
+            replay_id: string;
+            events: unknown[];
+            next_seq: number | null;
+        }>;
+        /** A link to the hosted player for a person, valid for `expires_in` seconds (default 1 h, max 24 h). */
+        share: (id: string, opts?: {
+            expires_in?: number;
+        }) => Promise<{
+            replay_id: string;
+            url: string;
+            expires_at: string;
+        }>;
+        delete: (id: string) => Promise<void>;
+    };
+    readonly operations: {
+        get: (id: string) => Promise<Operation>;
+    };
+    readonly actions: {
+        run: <O = unknown>(name: string, input: unknown) => Promise<{
+            output: O;
+            cost_micro_usd: number | null;
+        }>;
+    };
+    readonly email: {
+        /** Send from the project's address (`info@<slug>.vibiz.app` by default). */
+        send: (projectId: string, input: SendEmailInput, opts?: {
+            idempotencyKey?: string;
+        }) => Promise<{
+            output: SendEmailOutput;
+            cost_micro_usd: number | null;
+            usage: ActionUsage | null;
+        }>;
+    };
+    /**
+     * The AI gateway: chat, images, speech and transcription, metered against
+     * the account's (or the project's) spend. Works with the account key or a
+     * project AI key (`VIBIZ_AI_API_KEY`). OpenAI's SDK works too: point it at
+     * `<api>/v1/ai`.
+     */
+    readonly ai: {
+        /** One completion. `model` defaults to `vibiz/fast`. */
+        chat: (input: ChatRequest, opts?: {
+            idempotencyKey?: string;
+        }) => Promise<ChatCompletion>;
+        /** A streamed completion, chunk by chunk. Breaking out of the loop stops the model. */
+        chatStream: (input: ChatRequest) => AsyncIterable<ChatChunk>;
+        embed: (input: {
+            input: string | string[];
+            model?: string;
+            dimensions?: number;
+        }) => Promise<{
+            data: Array<{
+                index: number;
+                embedding: number[];
+            }>;
+            cost_micro_usd: number;
+        }>;
+        image: (input: ImageRequest, opts?: {
+            idempotencyKey?: string;
+        }) => Promise<ImageResult>;
+        /** Text to speech: the audio bytes (mp3 by default). */
+        speech: (input: SpeechRequest) => Promise<Uint8Array>;
+        /** Speech to text. */
+        transcribe: (input: {
+            file: Blob | Uint8Array;
+            filename?: string;
+            model?: string;
+            language?: string;
+        }) => Promise<Transcription>;
+        /**
+         * The Vibiz models and the lab models, with prices. `all` adds every
+         * language model you can call by id; `q` searches id, name and maker.
+         */
+        models: (opts?: {
+            all?: boolean;
+            q?: string;
+        }) => Promise<AiModelInfo[]>;
+        jobs: {
+            create: (input: {
+                type: "image" | "video";
+                model?: string;
+                input: {
+                    prompt: string;
+                    n?: number;
+                    size?: string;
+                    aspect_ratio?: "16:9" | "9:16" | "1:1";
+                };
+            }, opts?: {
+                idempotencyKey?: string;
+            }) => Promise<AiJob>;
+            get: (id: string) => Promise<AiJob>;
+            cancel: (id: string) => Promise<AiJob>;
+            wait: (id: string, opts?: {
+                timeoutMs?: number;
+                intervalMs?: number;
+            }) => Promise<AiJob>;
+        };
+    };
+    /** A project's AI key and settings (the `ai` resource). Account key only. */
+    readonly projectAi: {
+        get: (projectId: string) => Promise<AiSettings>;
+        update: (projectId: string, patch: Partial<AiSettings["settings"]>) => Promise<AiSettings>;
+        /** A new key; the old one keeps working for `graceSeconds` (default 3600). */
+        rotateKey: (projectId: string, opts?: {
+            graceSeconds?: number;
+        }) => Promise<AiSettings & {
+            api_key: string;
+        }>;
+        revokeKey: (projectId: string) => Promise<AiSettings>;
+    };
+    /**
+     * Your own AI provider keys (docs/AI.md "Your own keys"): calls they can
+     * serve run only on them (never falling back to Vibiz) and cost 0 here.
+     * Pass `projectId` for a project's override. Setting and removing need an
+     * owner key. Secrets are write-only: no method returns one.
+     */
+    readonly aiKeys: {
+        list: (opts?: {
+            projectId?: string;
+        }) => Promise<AiProviderKeyList>;
+        get: (provider: "google", opts?: {
+            projectId?: string;
+        }) => Promise<AiProviderKey>;
+        /** Checked with a cheap call to the provider first; refused with the reason if it fails. */
+        set: (provider: "google", input: AiProviderKeyInput, opts?: {
+            projectId?: string;
+        }) => Promise<AiProviderKey>;
+        /** Which capabilities the key serves; the rest runs on Vibiz. */
+        update: (provider: "google", patch: {
+            use_for: AiProviderKey["use_for"] & {};
+        }, opts?: {
+            projectId?: string;
+        }) => Promise<AiProviderKey>;
+        test: (provider: "google", opts?: {
+            projectId?: string;
+        }) => Promise<AiProviderKey>;
+        remove: (provider: "google", opts?: {
+            projectId?: string;
+        }) => Promise<AiProviderKey>;
+    };
+    /** What the account used, what it cost, and how close it is to its limits. */
+    readonly usage: {
+        get: (opts?: UsageOptions) => Promise<UsageReport>;
+        project: (projectId: string, opts?: UsageOptions) => Promise<UsageReport>;
+    };
+    /**
+     * The account's own credits (docs/BILLING.md): the balance, the card,
+     * auto-recharge and history. A top-up is a hosted page a person pays on.
+     */
+    readonly billing: {
+        get: () => Promise<Billing>;
+        /** Owner keys: auto-recharge and the daily safety cap. */
+        update: (input: BillingUpdate) => Promise<Billing>;
+        /** A payment page for `amount_cents` (500–100000); hand its `url` to a person. */
+        checkout: (input: {
+            amount_cents: number;
+            save_card?: boolean;
+        }) => Promise<BillingCheckout>;
+        checkoutStatus: (id: string) => Promise<BillingCheckout>;
+        /** Owner keys: a page to save or replace the card. */
+        saveCard: () => Promise<BillingCheckout>;
+        removeCard: () => Promise<Billing>;
+        ledger: (opts?: {
+            kind?: BillingEntryKind[];
+            cursor?: string;
+            limit?: number;
+        }) => Promise<BillingList<BillingEntry>>;
+        charges: (opts?: {
+            status?: string;
+            cursor?: string;
+            limit?: number;
+        }) => Promise<BillingList<BillingCharge>>;
+    };
+    /** Request counts, error rate and latency by capability. */
+    readonly metrics: {
+        get: (opts?: {
+            period?: UsagePeriod;
+        }) => Promise<MetricsReport>;
+    };
+    /** Named keys, one per teammate or agent, so spend shows per person. */
+    readonly apiKeys: {
+        list: () => Promise<ApiKey[]>;
+        /** The secret is returned once, here. */
+        /** `agent` by default: builds and runs, never reads production secrets. Needs an owner key. */
+        create: (name: string, opts?: {
+            access?: KeyAccess;
+        }) => Promise<ApiKey & {
+            secret: string;
+        }>;
+        revoke: (id: string) => Promise<ApiKey>;
+    };
+    /** A short-lived link to the hosted usage dashboard (admin scope needs an admin key). */
+    readonly dashboard: {
+        link: (opts?: {
+            scope?: "tenant" | "admin";
+            expires_in?: number;
+            period?: UsagePeriod;
+        }) => Promise<DashboardLink>;
+    };
+    /** The platform view. Admin keys only. */
+    readonly admin: {
+        metrics: (opts?: {
+            period?: UsagePeriod;
+        }) => Promise<AdminMetrics>;
+        usage: (opts?: UsageOptions & {
+            tenant?: string;
+            provider?: string;
+        }) => Promise<UsageReport>;
+        tenantUsage: (tenantId: string, opts?: UsageOptions) => Promise<UsageReport>;
+    };
+    /** Company formation: what can be formed where, fees, industries, the disclaimer. */
+    readonly company: {
+        catalog: (env?: CompanyEnvironment) => Promise<CompanyCatalog>;
+    };
+    /** The hosts Vibiz can connect to, and the fields each asks for. */
+    hostKinds(): Promise<HostKind[]>;
+    capabilities(): Promise<{
+        resources: ResourceType[];
+        actions: string[];
+        services: string[];
+    }>;
+    /** The account and key this client acts as. */
+    whoami(): Promise<WhoAmI>;
+    /** Revoke the key this client uses (`vibiz logout` for a key made by a browser login). */
+    logout(): Promise<{
+        object: "api_key";
+        id: string;
+        revoked: true;
+    }>;
+}
+export interface WhoAmI {
+    object: 'whoami';
+    account: {
+        id: string;
+        name: string;
+    };
+    key: {
+        id: string;
+        name: string;
+        prefix: string;
+        kind: 'key' | 'console';
+        access: 'owner' | 'agent';
+        created_at: string;
+    };
+    role: 'tenant' | 'admin';
+}
+/**
+ * Header values must be Latin-1, so an id outside printable ASCII (`用户-7`,
+ * Arabic, emoji) is sent as `b64u:` + base64url of its UTF-8. The API decodes
+ * both forms.
+ */
+export declare function endUserHeader(user: string): string;