@layers/amba 0.1.1

package/dist/api-client.d.ts

@@ -0,0 +1,671 @@
+import type { ApiResponse, ApiListResponse } from './_internal/shared.js';
+export declare class ApiClientError extends Error {
+    readonly statusCode: number;
+    readonly errorCode?: string | undefined;
+    constructor(message: string, statusCode: number, errorCode?: string | undefined);
+}
+/**
+ * Generic typed GET against the admin API. Wraps `request` so callers
+ * outside this module (e.g. the codegen-engine adapter in
+ * `commands/types.ts`) don't need to reach into the private helper.
+ *
+ * Path is relative to `/admin` — leading slash required (`/projects/X`).
+ */
+export declare function adminGet<T>(path: string): Promise<{
+    data: T;
+}>;
+export interface ProjectSummary {
+    id: string;
+    name: string;
+    platform: string;
+    environment?: string;
+    bundle_id?: string | null;
+    status?: string;
+    created_at?: string;
+}
+export declare function listProjects(): Promise<ApiListResponse<ProjectSummary>>;
+export declare function createProject(input: {
+    name: string;
+    bundle_id?: string;
+    platform?: string;
+    /**
+     * Project environment. `'development'` flags the row as the developer's
+     * personal dev project — used by `amba init` for the dev-project
+     * bootstrap. Defaults to `'production'` when omitted.
+     */
+    environment?: 'development' | 'production';
+}): Promise<ApiResponse<{
+    id: string;
+    name: string;
+    platform: string;
+    environment?: string;
+}>>;
+export declare function getProject(projectId: string): Promise<ApiResponse<{
+    id: string;
+    name: string;
+    platform: string;
+    environment: string;
+    bundle_id: string | null;
+    created_at: string;
+}>>;
+export declare function deleteProject(projectId: string): Promise<ApiResponse<{
+    id: string;
+    deleted: boolean;
+}>>;
+export declare function reprovisionProject(projectId: string): Promise<ApiResponse<{
+    workflowId?: string;
+    status?: string;
+    message?: string;
+}>>;
+export declare function getProvisioningStatus(projectId: string): Promise<ApiResponse<{
+    projectId: string;
+    status: string;
+    workflowId?: string | null;
+    errorMessage?: string | null;
+}>>;
+export declare function createApiKey(projectId: string, keyType: 'client' | 'server', environment: 'development' | 'production'): Promise<ApiResponse<{
+    id: string;
+    key: string;
+    key_prefix: string;
+    key_type: string;
+    environment: string;
+}>>;
+export declare function sendTestPush(projectId: string, input: {
+    title: string;
+    body: string;
+    data?: Record<string, unknown>;
+}): Promise<ApiResponse<{
+    sent: number;
+    message: string;
+}>>;
+export declare function listConfig(projectId: string): Promise<ApiListResponse<{
+    key: string;
+    value: unknown;
+    value_type: string;
+    description: string | null;
+}>>;
+export declare function setConfig(projectId: string, input: {
+    key: string;
+    value: unknown;
+    value_type?: string;
+    description?: string;
+}): Promise<ApiResponse<{
+    key: string;
+    value: unknown;
+    value_type: string;
+}>>;
+export interface IntegrationSummary {
+    provider: string;
+    status?: string;
+    enabled?: boolean;
+    last_verified_at?: string | null;
+    [key: string]: unknown;
+}
+export declare function listIntegrations(projectId: string): Promise<ApiListResponse<IntegrationSummary>>;
+export interface AdminUserSummary {
+    id: string;
+    email?: string | null;
+    is_anonymous?: boolean;
+    created_at?: string;
+    [key: string]: unknown;
+}
+export declare function listUsers(projectId: string, query?: {
+    limit?: number;
+}): Promise<ApiListResponse<AdminUserSummary>>;
+export declare function getUserEvents(projectId: string, userId: string, query?: {
+    limit?: number;
+    since?: string;
+    cursor?: string;
+}): Promise<ApiListResponse<{
+    id?: string;
+    event_name: string;
+    user_id: string;
+    properties?: Record<string, unknown>;
+    created_at: string;
+}>>;
+export interface AdminEventRow {
+    id: string;
+    app_user_id: string;
+    event_name: string;
+    properties: Record<string, unknown>;
+    occurred_at: string;
+}
+export interface AdminEventsPage {
+    data: AdminEventRow[];
+    next_cursor: string | null;
+}
+/**
+ * Fetch a page of project-wide engagement events. Most-recent-first; when
+ * `next_cursor` is non-null the caller should pass it back as `cursor` to
+ * continue paging.
+ */
+export declare function listProjectEvents(projectId: string, query?: {
+    since?: string;
+    until?: string;
+    eventName?: string;
+    userId?: string;
+    limit?: number;
+    cursor?: string;
+}): Promise<AdminEventsPage>;
+export interface EventsCountBucket {
+    key: string;
+    count: number;
+}
+export interface EventsCountResponse {
+    data: {
+        total: number;
+        buckets?: EventsCountBucket[];
+    };
+}
+/**
+ * Aggregate event counts in a time range. `groupBy` of `event_name` returns
+ * the per-event-name bucket list ordered by count desc.
+ */
+export declare function getEventsCount(projectId: string, query: {
+    since: string;
+    until?: string;
+    eventName?: string;
+    groupBy?: 'day' | 'event_name';
+}): Promise<EventsCountResponse>;
+/**
+ * Stream `/users/export` as line-delimited text. Yields chunks as the
+ * server emits them. The endpoint always emits CSV (or NDJSON) so we don't
+ * try to parse — callers either tee to disk or split lines themselves.
+ */
+export declare function streamUsersExport(projectId: string, query?: {
+    format?: 'csv' | 'ndjson';
+    since?: string;
+}): Promise<Response>;
+export declare function listSegments(projectId: string): Promise<ApiListResponse<{
+    id: string;
+    name: string;
+    is_active?: boolean;
+}>>;
+export declare function createSegment(projectId: string, input: {
+    name: string;
+    description?: string;
+    rules?: unknown;
+    is_active?: boolean;
+}): Promise<ApiResponse<{
+    id: string;
+    name: string;
+}>>;
+export declare function listAchievements(projectId: string): Promise<ApiListResponse<{
+    id: string;
+    name: string;
+}>>;
+export declare function createAchievement(projectId: string, input: {
+    code: string;
+    name: string;
+    description?: string;
+    criteria?: unknown;
+    reward?: unknown;
+}): Promise<ApiResponse<{
+    id: string;
+    name: string;
+}>>;
+export declare function listContentLibraries(projectId: string): Promise<ApiListResponse<{
+    id: string;
+    slug: string;
+    name: string;
+}>>;
+export declare function createContentLibrary(projectId: string, input: {
+    slug: string;
+    name: string;
+    description?: string;
+}): Promise<ApiResponse<{
+    id: string;
+    slug: string;
+}>>;
+export declare function addContentItems(projectId: string, libraryId: string, input: {
+    items: Array<{
+        key: string;
+        content: unknown;
+        locale?: string;
+    }>;
+}): Promise<ApiResponse<{
+    added: number;
+}>>;
+export declare function listXpRules(projectId: string): Promise<ApiListResponse<{
+    id: string;
+    event_name: string;
+    amount: number;
+}>>;
+export declare function createXpRule(projectId: string, input: {
+    event_name: string;
+    amount: number;
+    description?: string;
+}): Promise<ApiResponse<{
+    id: string;
+    event_name: string;
+    amount: number;
+}>>;
+export interface FunctionDeploymentRow {
+    id: string;
+    project_id: string;
+    name: string;
+    version: number;
+    cf_script_name: string;
+    cf_dispatch_namespace: string;
+    bundle_sha: string;
+    status: 'active' | 'superseded' | 'disabled';
+    created_at: string;
+}
+export declare function recordFunctionDeployment(projectId: string, input: {
+    name: string;
+    cf_script_name: string;
+    cf_dispatch_namespace: string;
+    bundle_sha: string;
+    /**
+     * Optional declarative rate-limit. The CLI passes a validated
+     * `RateLimitConfig` here; the server persists it on the deployment
+     * row. Omitting (or sending `null`) = no rate limit.
+     */
+    rate_limit?: {
+        window: string;
+        max: number;
+        key: 'user_id' | 'ip';
+    } | null;
+}): Promise<ApiResponse<FunctionDeploymentRow>>;
+export interface DeployFunctionResult {
+    data: FunctionDeploymentRow;
+    /** `https://<project_slug>.fn.amba.host/<name>` — the live invocation URL. */
+    fn_url: string;
+}
+export declare function deployFunctionViaApi(projectId: string, input: {
+    /** Function name (matches `/^[a-z][a-z0-9_-]*$/`). */
+    name: string;
+    /** Bundled JS — single-file ESM entry. Server-enforced 10 MB cap. */
+    bundleCode: string;
+    /** Optional rate-limit. Validated server-side too. */
+    rate_limit?: {
+        window: string;
+        max: number;
+        key: 'user_id' | 'ip';
+    } | null;
+}): Promise<DeployFunctionResult>;
+export declare function listFunctionDeployments(projectId: string, options?: {
+    activeOnly?: boolean;
+}): Promise<ApiListResponse<FunctionDeploymentRow>>;
+export interface FunctionDeployContext {
+    /** Dispatch namespace for the script PUT (e.g. `amba_tenant_functions`). */
+    dispatch_namespace: string;
+    /** Project slug for `https://{slug}.fn.amba.host/{name}` URL rendering. */
+    project_slug: string;
+    /**
+     * R2 bucket name for the project — shared default OR dedicated tier
+     * NULL when storage isn't yet provisioned for the project; deploy
+     * step skips the storage binding in that case.
+     */
+    r2_bucket_name: string | null;
+    /**
+     * Cloudflare Hyperdrive config id. NULL until storage provisioning
+     * completes; deploy step skips the Hyperdrive binding when null and
+     * `ctx.collections` returns `tenant_unavailable` until the column is
+     * populated.
+     */
+    cf_hyperdrive_config_id: string | null;
+}
+export declare function getFunctionDispatchNamespace(projectId: string): Promise<ApiResponse<FunctionDeployContext>>;
+export interface InternalCredentialsResponse {
+    internal_token: string;
+    header_signing_secret: string;
+    /** First 4 chars of the random portion — for log correlation, not auth. */
+    internal_token_fingerprint: string;
+    /** Same shape as above — for log correlation. */
+    header_signing_secret_fingerprint: string;
+}
+export declare function fetchInternalCredentials(projectId: string): Promise<ApiResponse<InternalCredentialsResponse>>;
+export declare function disableFunctionDeployment(projectId: string, deploymentId: string): Promise<ApiResponse<{
+    id: string;
+    status: string;
+}>>;
+export declare function scheduleFunction(projectId: string, input: {
+    name: string;
+    cron: string;
+    timezone?: string;
+}): Promise<ApiResponse<{
+    schedule_id: string;
+}>>;
+export interface FunctionLogEvent {
+    /** Logpush row — see `r2-log-reader.ts:LogpushTraceEvent`. Field-shape stable. */
+    Event?: {
+        Timestamp?: string;
+    };
+    ScriptName?: string;
+    Outcome?: string;
+    Logs?: Array<{
+        Level?: string;
+        Message?: unknown[];
+        TimestampMs?: number;
+    }>;
+    Exceptions?: Array<{
+        Name?: string;
+        Message?: string;
+        TimestampMs?: number;
+    }>;
+    EventTimestampMs?: number;
+}
+export interface FunctionLogsResponse {
+    events: FunctionLogEvent[];
+    truncated: boolean;
+    since: string;
+    until: string;
+}
+export declare function getFunctionLogs(projectId: string, functionName: string, options?: {
+    since?: string;
+    until?: string;
+    limit?: number;
+}): Promise<ApiResponse<FunctionLogsResponse>>;
+export interface QueueBinding {
+    queue_name: string;
+    function_name: string;
+    status: 'active' | 'paused';
+    created_at: string;
+    updated_at: string;
+}
+export declare function upsertQueueBinding(projectId: string, input: {
+    queue_name: string;
+    function_name: string;
+    status?: 'active' | 'paused';
+}): Promise<ApiResponse<QueueBinding & {
+    id: string;
+}>>;
+export declare function listQueueBindings(projectId: string): Promise<ApiListResponse<QueueBinding>>;
+export declare function deleteQueueBinding(projectId: string, queueName: string): Promise<ApiResponse<{
+    queue_name: string;
+    deleted: boolean;
+}>>;
+export interface SecretSyncPendingRow {
+    id: string;
+    project_id: string;
+    function_name: string | null;
+    secret_name: string;
+    expected_version: number;
+    status: 'pending' | 'syncing' | 'sync_failed_retrying' | 'synced';
+    last_error: string | null;
+    attempts: number;
+    created_at: string;
+    updated_at: string;
+}
+export declare function registerSecretSync(projectId: string, input: {
+    function_name: string;
+    secret_name: string;
+    expected_version: number;
+}): Promise<ApiResponse<SecretSyncPendingRow>>;
+export declare function listSecretSyncStatus(projectId: string): Promise<ApiListResponse<SecretSyncPendingRow>>;
+export interface SetSecretResultRow {
+    /** Secret name as set by the customer. */
+    name: string;
+    /** Function name the secret binds to. */
+    function: string;
+    /** Secret store version number (1, 2, 3, ...). */
+    version: number;
+    /** Backend version resource path — exposed for ops debugging. */
+    version_path: string;
+    /** `'pending'` until the secret sync completes. */
+    sync_status: 'pending' | 'syncing' | 'sync_failed_retrying' | 'synced';
+    created_at: string;
+}
+export declare function setSecretViaApi(projectId: string, input: {
+    /** Uppercase identifier (`/^[A-Z][A-Z0-9_]{0,62}$/`). */
+    name: string;
+    /** Plaintext secret value. <=64KiB. */
+    value: string;
+    /** Function name the secret binds to. v1 has no project-wide secrets. */
+    function: string;
+}): Promise<ApiResponse<SetSecretResultRow>>;
+export interface ListSecretsRow {
+    /** Function name the secret binds to. */
+    function: string;
+    /** Secret name. */
+    name: string;
+    /** Latest secret-store version number. */
+    version: number;
+    sync_status: 'pending' | 'syncing' | 'sync_failed_retrying' | 'synced';
+    attempts: number;
+    last_error: string | null;
+    updated_at: string;
+}
+export declare function listSecretsViaApi(projectId: string): Promise<ApiListResponse<ListSecretsRow>>;
+export declare function deleteSecretViaApi(projectId: string, name: string, options: {
+    function: string;
+}): Promise<ApiResponse<{
+    name: string;
+    function: string;
+    deleted: true;
+}>>;
+/** Closed set of column types the server accepts. */
+export type CollectionColumnType = 'uuid' | 'text' | 'integer' | 'bigint' | 'numeric' | 'boolean' | 'timestamptz' | 'date' | 'jsonb' | 'vector';
+export interface CollectionColumn {
+    name: string;
+    type: CollectionColumnType;
+    nullable?: boolean;
+    references?: {
+        table: string;
+        column?: string;
+        onDelete?: 'CASCADE' | 'RESTRICT' | 'SET NULL' | 'NO ACTION';
+    };
+    /**
+     * Required when `type === 'vector'`. The pgvector dimension
+     * (`vector(N)`). Common values: 384, 768, 1536, 3072.
+     */
+    dimension?: number;
+}
+export interface CollectionIndex {
+    /** Optional explicit name; auto-derived from column list if omitted. */
+    name?: string;
+    /** Each entry is `<col>` or `<col> asc|desc`. Direction is parsed by the DDL emit. */
+    columns: string[];
+    unique?: boolean;
+}
+export interface CollectionDefinition {
+    name: string;
+    columns: CollectionColumn[];
+    indexes?: CollectionIndex[];
+}
+/** Create-collection response from `POST /admin/projects/:p/collections`. */
+export interface CreateCollectionResult {
+    name: string;
+    version: number;
+    workflow_id: string;
+    run_id: string;
+    status: 'applied';
+}
+export declare function createCollection(projectId: string, input: CollectionDefinition): Promise<ApiResponse<CreateCollectionResult>>;
+export interface CollectionListItem {
+    name: string;
+    created_at: string;
+}
+export declare function listCollections(projectId: string, options?: {
+    limit?: number;
+    offset?: number;
+}): Promise<ApiListResponse<CollectionListItem>>;
+export interface CollectionDescribeResult {
+    name: string;
+    columns: CollectionColumn[];
+    indexes: CollectionIndex[];
+    latest_migration: {
+        version: number;
+        applied_at: string;
+    } | null;
+}
+export declare function describeCollection(projectId: string, name: string): Promise<ApiResponse<CollectionDescribeResult>>;
+/**
+ * Single-op PATCH per data's contract — one of `add_column`, `add_index`,
+ * or `drop_column` per call. The saga writes one registry row per intent
+ * so the operator audit trail stays one-to-one with developer actions.
+ *
+ * `drop_column` requires a `?confirm=<column-name>` query param to guard
+ * against typos — same accident-protection pattern as `dropCollection`.
+ */
+export type AlterCollectionPatch = {
+    add_column: CollectionColumn;
+} | {
+    add_index: CollectionIndex;
+} | {
+    drop_column: string;
+};
+export interface AlterCollectionResult {
+    name: string;
+    version: number;
+    workflow_id: string;
+    run_id: string;
+    status: 'applied';
+}
+export declare function alterCollection(projectId: string, name: string, patch: AlterCollectionPatch, options?: {
+    confirm?: string;
+}): Promise<ApiResponse<AlterCollectionResult>>;
+/**
+ * Drop a collection. Requires `confirm` matching the collection name —
+ * data's safety guard against typos. CLI surfaces this as `--confirm <name>`.
+ */
+export declare function dropCollection(projectId: string, name: string, confirm: string): Promise<ApiResponse<{
+    name: string;
+    deleted: boolean;
+    version: number;
+}>>;
+export type AiProviderName = 'anthropic' | 'openai';
+export interface AiProviderRow {
+    name: AiProviderName;
+    /** Canonical secret name in the secret store. NULL only mid-rotation. */
+    api_key_secret_name: string | null;
+    /** Preview cue printed to the CLI on register; NOT a real partial key. */
+    api_key_preview?: string;
+    created_at?: string;
+    updated_at?: string;
+}
+export declare function registerAiProvider(projectId: string, input: {
+    name: AiProviderName;
+    api_key: string;
+}): Promise<ApiResponse<AiProviderRow>>;
+export declare function listAiProviders(projectId: string): Promise<ApiListResponse<AiProviderRow>>;
+export declare function deleteAiProvider(projectId: string, name: AiProviderName): Promise<ApiResponse<{
+    name: AiProviderName;
+    deleted: true;
+}>>;
+export interface SiteRow {
+    id: string;
+    project_id: string;
+    name: string;
+    cf_pages_project_name: string;
+    status: 'active' | 'disabled' | 'archived';
+    created_at: string;
+    updated_at: string;
+}
+export interface SiteDomainRow {
+    id: string;
+    site_id: string;
+    hostname: string;
+    cf_hostname_id: string | null;
+    cert_status: 'pending_validation' | 'pending_issuance' | 'pending_deployment' | 'active' | 'error';
+    created_at: string;
+    updated_at: string;
+}
+export declare function createSite(projectId: string, input: {
+    name: string;
+}): Promise<ApiResponse<SiteRow>>;
+export declare function listSites(projectId: string): Promise<ApiListResponse<SiteRow>>;
+export declare function describeSite(projectId: string, name: string): Promise<ApiResponse<SiteRow & {
+    domains: SiteDomainRow[];
+}>>;
+export interface DeploySiteResult {
+    /** Deployment uuid. */
+    deployment_id: string;
+    site_name: string;
+    branch: string;
+    /** Customer-facing canonical URL (`https://{slug}-{site}.app.amba.host`). */
+    url: string;
+    /** Underlying CDN preview URL — exposed for ops. */
+    preview_url: string;
+    deployed_at: string;
+    status: 'queued' | 'building' | 'success' | 'failure';
+}
+export declare function deploySiteViaApi(projectId: string, siteName: string, body: FormData): Promise<ApiResponse<DeploySiteResult>>;
+export declare function updateSite(projectId: string, name: string, patch: {
+    status: 'active' | 'disabled';
+}): Promise<ApiResponse<SiteRow>>;
+export declare function archiveSite(projectId: string, name: string, confirm: string): Promise<ApiResponse<SiteRow>>;
+/** Cascade summary returned by site/function delete proxies. */
+export interface DeleteCascadeSummary {
+    domains_removed?: number;
+    cf_pages_project_deleted?: boolean;
+    cf_dispatch_script_deleted?: boolean;
+    function_deployments_marked_disabled?: number;
+}
+/**
+ * Add a custom domain to a site. The server-side proxy registers the
+ * custom hostname, persists the resulting `cf_hostname_id`, and returns
+ * the CNAME target the customer should point their DNS at.
+ */
+export declare function addSiteDomainViaApi(projectId: string, siteName: string, hostname: string): Promise<ApiResponse<{
+    hostname: string;
+    cf_hostname_id: string;
+    cert_status: SiteDomainRow["cert_status"];
+    dns_target: string;
+    created_at: string;
+}>>;
+/**
+ * Remove a custom domain from a site. Idempotent — re-running on an
+ * already-removed hostname returns 200 with `deleted: true`. Backend
+ * 404s are treated as success at the proxy layer.
+ */
+export declare function removeSiteDomainViaApi(projectId: string, siteName: string, hostname: string): Promise<ApiResponse<{
+    hostname: string;
+    deleted: true;
+}>>;
+/**
+ * Roll a live CF Pages deployment back to a prior `deployment_id`. CF's
+ * rollback creates a NEW deployment that serves the prior bundle (git-
+ * revert semantics, not git-reset), so the response shape mirrors
+ * `DeploySiteResult` and the new `deployment_id` is what's now live.
+ */
+export declare function rollbackSiteViaApi(projectId: string, siteName: string, deploymentId: string): Promise<ApiResponse<DeploySiteResult>>;
+/**
+ * Delete a site entirely. Cascade: removes attached custom hostnames,
+ * tears down the CDN project, and soft-deletes the site row. Partial
+ * failures surface as `503 CASCADE_PARTIAL_FAILURE` with the `cascade`
+ * field telling the CLI which steps completed.
+ */
+export declare function deleteSiteViaApi(projectId: string, siteName: string, options: {
+    confirm: string;
+}): Promise<ApiResponse<{
+    name: string;
+    deleted: true;
+    cascade: DeleteCascadeSummary;
+}>>;
+/**
+ * Delete a function entirely. Cascade: removes the deployed script
+ * (backend 404 treated as success), then marks every historical
+ * deployment row as `status='disabled'` to keep history intact for
+ * audit. Customer Workers stop responding immediately on cascade
+ * step 1.
+ */
+export declare function deleteFunctionViaApi(projectId: string, functionName: string, options: {
+    confirm: string;
+}): Promise<ApiResponse<{
+    name: string;
+    deleted: true;
+    cascade: DeleteCascadeSummary;
+}>>;
+export declare function attachSiteDomain(projectId: string, siteName: string, input: {
+    hostname: string;
+    cf_hostname_id?: string;
+}): Promise<ApiResponse<SiteDomainRow>>;
+export declare function listSiteDomains(projectId: string, siteName: string): Promise<ApiListResponse<SiteDomainRow>>;
+export declare function updateSiteDomain(projectId: string, siteName: string, hostname: string, patch: {
+    cert_status: SiteDomainRow['cert_status'];
+    cf_hostname_id?: string;
+}): Promise<ApiResponse<SiteDomainRow>>;
+export declare function detachSiteDomain(projectId: string, siteName: string, hostname: string): Promise<ApiResponse<{
+    deleted: boolean;
+}>>;
+export declare function validateApiKey(apiKey: string): Promise<{
+    valid: false;
+    error: string;
+} | {
+    project_id: string;
+    environment: string;
+    valid: true;
+    error?: undefined;
+}>;