@ninedeploy/sdk 0.10.5 → 0.16.0

package/src/resources/auth.ts

@@ -0,0 +1,357 @@
+// Client surface: auth, workspaces, users, scim, sso, accessGrants, access.
+// Split out of the former single-file SDK entry (src/index.ts); the public
+// surface is re-exported unchanged from there.
+import type {
+  ActiveSession,
+  ApiToken,
+  PasskeyCredential,
+  CreateApiTokenInput,
+  CreatedApiToken,
+  Login,
+  PasswordChange,
+  PasswordChangeResult,
+  PasswordReset,
+  PublicUser,
+  Refresh,
+  Register,
+  Session,
+  UserCreate,
+  WorkspaceEntry,
+  WorkspaceDetail,
+  WorkspaceCreateInput,
+  WorkspaceUpdateInput,
+  WorkspaceMemberEntry,
+  WorkspaceMemberInviteEntry,
+  WorkspaceMemberAddInput,
+  WorkspaceMemberRoleUpdateInput,
+  OidcPublicProvider,
+  WorkspaceInvitationEntry,
+  WorkspaceInvitationPublic,
+  WorkspaceRole,
+  OidcProviderEntry,
+  OidcProviderCreateInput,
+  OidcProviderUpdateInput,
+  AccessGrant,
+  AccessGrantCreate,
+  AccessGrantListQuery,
+  AccessGrantUpdate,
+  AccessMe,
+  ProjectAccessEntry,
+} from '@ninedeploy/schemas';
+import { apiGetUrl } from '../apiPath.js';
+import type { TokenIntrospection } from '../types.js';
+import type { Transport } from '../transport.js';
+
+export interface AuthApi {
+  auth: {
+    /** `setupTokenRequired` (0.16): the first-run bootstrap needs the installer's setup token. */
+    status: () => Promise<{ initialized: boolean; allowRegistration?: boolean; setupTokenRequired?: boolean }>;
+    /**
+     * Introspect the current bearer token. Returns the
+     * token's id (when opaque), name, scopes, expiry and
+     * the operator flag. Interactive sessions (JWT) report
+     * `scopes: ['session']`. The MCP server uses this to
+     * discover the token's authority before registering
+     * tools.
+     */
+    introspectToken: () => Promise<TokenIntrospection>;
+    setup: (input: Register) => Promise<Session>;
+    register: (input: Register) => Promise<Session>;
+    login: (input: Login) => Promise<Session>;
+    refresh: (input: Refresh) => Promise<Session>;
+    logout: () => Promise<{ ok: boolean }>;
+    /** Self-service password change; revokes other sessions, returns a fresh token pair
+     *  and (r603) how many passkeys still sign in to the account. */
+    changePassword: (input: PasswordChange) => Promise<PasswordChangeResult>;
+    /** Request a reset link (always 200 — no user enumeration). */
+    forgotPassword: (email: string) => Promise<{ ok: boolean }>;
+    /** Complete a reset with a single-use token; revokes all sessions. */
+    resetPasswordWithToken: (input: { token: string; newPassword: string }) => Promise<{ ok: boolean }>;
+    twoFactor: {
+      /**
+       * Generate a pending secret + otpauth URI (auth required). Since 0.10.36
+       * (r502) the server wants step-up proof: the current password, or a
+       * sign-in from the last 10 minutes (else 403 `reauth_required`).
+       */
+      setup: (input?: { password: string }) => Promise<{ secret: string; otpauthUri: string }>;
+      /** Turn 2FA on. `password` is the r502 step-up proof (see `setup`). */
+      enable: (code: string, password?: string) => Promise<{ ok: boolean; totpEnabled: boolean }>;
+      disable: (input: { password: string; code: string }) => Promise<{ ok: boolean; totpEnabled: boolean }>;
+    };
+    me: () => Promise<PublicUser>;
+    tokens: {
+      create: (input?: CreateApiTokenInput) => Promise<CreatedApiToken>;
+      list: () => Promise<ApiToken[]>;
+      remove: (id: number) => Promise<void>;
+    };
+    passkeys: {
+      /**
+       * Start a registration ceremony (returns JSON options for the browser
+       * API). Since 0.10.36 (r502) registration needs step-up proof: the
+       * current password, or a sign-in from the last 10 minutes (else 403
+       * `reauth_required`).
+       */
+      registerOptions: (input?: { password?: string }) => Promise<{ options: string }>;
+      /** Complete registration: verify the browser response, store the credential. */
+      registerVerify: (input: { name: string; response: unknown; password?: string }) => Promise<PasskeyCredential>;
+      list: () => Promise<PasskeyCredential[]>;
+      remove: (id: number) => Promise<void>;
+      /** Start a passwordless login ceremony (discoverable credentials). */
+      loginOptions: () => Promise<{ options: string }>;
+      /** Complete passkey login — returns a full session on success. */
+      loginVerify: (response: unknown) => Promise<Session>;
+    };
+    sessions: {
+      list: () => Promise<ActiveSession[]>;
+      revoke: (id: number) => Promise<{ ok: boolean }>;
+    };
+    oidc: {
+      publicProviders: () => Promise<OidcPublicProvider[]>;
+      link: (slug: string) => Promise<{ authUrl: string }>;
+      listProviders: () => Promise<OidcProviderEntry[]>;
+      list: () => Promise<OidcProviderEntry[]>;
+      createProvider: (input: OidcProviderCreateInput) => Promise<OidcProviderEntry>;
+      create: (input: OidcProviderCreateInput) => Promise<OidcProviderEntry>;
+      updateProvider: (id: number, input: OidcProviderUpdateInput) => Promise<OidcProviderEntry>;
+      update: (id: number, input: OidcProviderUpdateInput) => Promise<OidcProviderEntry>;
+      deleteProvider: (id: number) => Promise<{ ok: boolean }>;
+      delete: (id: number) => Promise<{ ok: boolean }>;
+      callback: (slug: string, payload: { code: string; state: string }) => Promise<Session>;
+    };
+  };
+  workspaces: {
+    list: () => Promise<WorkspaceEntry[]>;
+    get: (id: number) => Promise<WorkspaceDetail>;
+    create: (input: WorkspaceCreateInput) => Promise<WorkspaceEntry>;
+    update: (id: number, input: WorkspaceUpdateInput) => Promise<WorkspaceEntry>;
+    delete: (id: number) => Promise<{ ok: boolean }>;
+    /**
+     * Add a member by email. r604: only an instance operator gets a direct
+     * add (a `WorkspaceMemberEntry`) for a registered address; for everyone
+     * else the answer is always an invitation (`kind: 'invitation'`), so the
+     * response does not reveal whether the address has an account.
+     */
+    addMember: (id: number, input: WorkspaceMemberAddInput) => Promise<WorkspaceMemberEntry | WorkspaceMemberInviteEntry>;
+    /**
+     * Create a pending invitation for an email address that is not a member of
+     * the workspace yet (r604: registered or not).
+     * r334: the response is the invitation row only — the server does NOT
+     * return an `acceptUrl` here (the token travels in the `x-invitation-token`
+     * response header and in the invite email). `addMember` returns the accept
+     * link in its body for the same case.
+     */
+    inviteMember: (id: number, input: WorkspaceMemberAddInput) => Promise<WorkspaceInvitationEntry>;
+    listInvitations: (id: number) => Promise<WorkspaceInvitationEntry[]>;
+    revokeInvitation: (id: number, inviteId: number) => Promise<{ ok: boolean }>;
+    /** Look up a pending invitation by its public token (no auth required). */
+    previewInvitation: (token: string) => Promise<WorkspaceInvitationPublic>;
+    /** Accept an invitation as the currently authenticated user. */
+    acceptInvitation: (token: string) => Promise<{ ok: boolean; workspaceId: number; role: WorkspaceRole }>;
+    updateMemberRole: (id: number, memberId: number, input: WorkspaceMemberRoleUpdateInput) => Promise<WorkspaceMemberEntry>;
+    removeMember: (id: number, memberId: number) => Promise<{ ok: boolean }>;
+  };
+  users: {
+    list: () => Promise<PublicUser[]>;
+    /**
+     * Operator-only: create a user directly (no registration flow needed).
+     * The new account has no workspace memberships — an existing owner/admin
+     * must invite it into at least one workspace before it can act.
+     */
+    create: (input: UserCreate) => Promise<PublicUser>;
+    /**
+     * Operator-only: delete a user. The `users.role` column was removed when
+     * authorization became workspace-only; the legacy `setRole` is gone with
+     * it. Role changes go through `workspaces.updateMemberRole`.
+     * Workspaces the user owns are transferred, not deleted: to the caller,
+     * or to `opts.transferTo` (an existing, active user id).
+     */
+    remove: (id: number, opts?: { transferTo?: number }) => Promise<void>;
+    /** Operator reset of another user's password (revokes their sessions). */
+    resetPassword: (id: number, input: PasswordReset) => Promise<{ ok: boolean }>;
+    /** Mint a one-time reset link for a user (returned exactly once). */
+    resetLink: (id: number) => Promise<{ url: string; expiresAt: string }>;
+    /**
+     * Operator-only: grant or revoke the INSTANCE-operator flag.
+     *
+     * Not a workspace role — this is the flag that gates operator-only routes
+     * and the host-privilege boundary (PM2/compose deploys, lifecycle hooks,
+     * docker-socket templates). Creating a workspace does NOT confer it. The
+     * last remaining operator cannot be demoted.
+     */
+    setOperator: (id: number, isOperator: boolean) => Promise<{ ok: boolean; id: number; isOperator: boolean }>;
+  };
+  scim: {
+    /** SCIM 2.0 provisioning tokens (operator-managed). */
+    listTokens: () => Promise<Array<{ id: number; name: string; workspaceId: number; createdAt: string | null; lastUsedAt: string | null; revoked: boolean }>>;
+    /** The plaintext token is returned exactly once — only its sha256 persists. */
+    createToken: (input: { name: string; workspaceId: number }) => Promise<{ id: number; token: string }>;
+    revokeToken: (id: number) => Promise<{ ok: boolean }>;
+  };
+  sso: {
+    /** Every configured OIDC / SAML provider. G-22. */
+    listProviders: () => Promise<{
+      providers: Array<{ id: number; type: 'oidc' | 'saml'; name: string; createdAt: string }>;
+    }>;
+    /** Add a provider (OIDC issuer URL or SAML metadata URL lives in `config`). */
+    addProvider: (input: {
+      type: 'oidc' | 'saml';
+      name: string;
+      config: Record<string, unknown>;
+    }) => Promise<{ ok: boolean; id?: number; name?: string; type?: 'oidc' | 'saml'; error?: string }>;
+    /** Remove a provider by id. */
+    removeProvider: (id: number) => Promise<{ ok: boolean }>;
+  };
+  /** Project and environment access grants (0.15, raise-only). Workspace admin floor. */
+  accessGrants: {
+    list: (workspaceId: number, query?: Partial<AccessGrantListQuery>) => Promise<AccessGrant[]>;
+    create: (workspaceId: number, input: AccessGrantCreate) => Promise<AccessGrant>;
+    /**
+     * Change the role, suspend (`suspended: true`) or reinstate
+     * (`suspended: false`), or both. A grant the user's identity provider
+     * suspended cannot be reinstated here (409 `grant_suspended_by_idp`).
+     */
+    update: (workspaceId: number, grantId: number, input: AccessGrantUpdate) => Promise<AccessGrant>;
+    delete: (workspaceId: number, grantId: number) => Promise<{ ok: boolean }>;
+  };
+  access: {
+    /** The caller's own grants and the workspaces reached only through them. */
+    me: () => Promise<AccessMe>;
+    /** Who reaches a project and how (project admin). */
+    project: (projectId: number) => Promise<ProjectAccessEntry[]>;
+  };
+}
+
+export function authApi(t: Transport): AuthApi {
+  const { get, send, request } = t;
+  return {
+    auth: {
+      status: () => get<{ initialized: boolean; allowRegistration?: boolean; setupTokenRequired?: boolean }>('/v1/auth/status'),
+      introspectToken: () => get<TokenIntrospection>('/v1/auth/token'),
+      setup: (input) => send<Session>('POST', '/v1/setup', input),
+      register: (input) => send<Session>('POST', '/v1/auth/register', input),
+      login: (input) => send<Session>('POST', '/v1/auth/login', input),
+      refresh: (input) => send<Session>('POST', '/v1/auth/refresh', input),
+      /** Revoke this user's outstanding JWTs server-side (tokenVersion bump). */
+      logout: () => send<{ ok: boolean }>('POST', '/v1/auth/logout', {}),
+      changePassword: (input) => send<PasswordChangeResult>('POST', '/v1/auth/password', input),
+      forgotPassword: (email) => send<{ ok: boolean }>('POST', '/v1/auth/forgot-password', { email }),
+      resetPasswordWithToken: (input) => send<{ ok: boolean }>('POST', '/v1/auth/reset-password', input),
+      twoFactor: {
+        setup: (input?: { password: string }) => send<{ secret: string; otpauthUri: string }>('POST', '/v1/auth/2fa/setup', input ?? {}),
+        enable: (code, password) =>
+          send<{ ok: boolean; totpEnabled: boolean }>('POST', '/v1/auth/2fa/enable', password ? { code, password } : { code }),
+        disable: (input) => send<{ ok: boolean; totpEnabled: boolean }>('POST', '/v1/auth/2fa/disable', input),
+      },
+      me: () => get<PublicUser>('/v1/auth/me'),
+      tokens: {
+        create: (input) => send<CreatedApiToken>('POST', '/v1/auth/tokens', input ?? {}),
+        list: () => get<ApiToken[]>('/v1/auth/tokens'),
+        remove: async (id) => {
+          await request(`/v1/auth/tokens/${id}`, { method: 'DELETE' });
+        },
+      },
+      passkeys: {
+        registerOptions: (input) =>
+          send<{ options: string }>('POST', '/v1/auth/passkey/register/options', input?.password ? { password: input.password } : undefined),
+        registerVerify: (input) =>
+          send<PasskeyCredential>('POST', '/v1/auth/passkey/register/verify', {
+            name: input.name,
+            response: input.response as Record<string, unknown>,
+            ...(input.password ? { password: input.password } : {}),
+          }),
+        list: () => get<PasskeyCredential[]>('/v1/auth/passkey'),
+        remove: async (id) => {
+          await request(`/v1/auth/passkey/${id}`, { method: 'DELETE' });
+        },
+        loginOptions: () => send<{ options: string }>('POST', '/v1/auth/passkey/login/options'),
+        loginVerify: (response) =>
+          send<Session>('POST', '/v1/auth/passkey/login/verify', { response: response as Record<string, unknown> }),
+      },
+      sessions: {
+        list: () => get<ActiveSession[]>('/v1/auth/sessions'),
+        revoke: (id) => send<{ ok: boolean }>('DELETE', `/v1/auth/sessions/${id}`),
+      },
+      oidc: {
+        publicProviders: () => get<OidcPublicProvider[]>('/v1/auth/oidc/providers/public'),
+        link: (slug) => request<{ authUrl: string }>(`/v1/auth/oidc/${encodeURIComponent(slug)}/link`, { method: 'POST', credentials: 'include' }),
+        listProviders: () => get<OidcProviderEntry[]>('/v1/auth/oidc/providers'),
+        list: () => get<OidcProviderEntry[]>('/v1/auth/oidc/providers'),
+        createProvider: (input) => send<OidcProviderEntry>('POST', '/v1/auth/oidc/providers', input),
+        create: (input) => send<OidcProviderEntry>('POST', '/v1/auth/oidc/providers', input),
+        updateProvider: (id, input) => send<OidcProviderEntry>('PATCH', `/v1/auth/oidc/providers/${id}`, input),
+        update: (id, input) => send<OidcProviderEntry>('PATCH', `/v1/auth/oidc/providers/${id}`, input),
+        deleteProvider: (id) => send<{ ok: boolean }>('DELETE', `/v1/auth/oidc/providers/${id}`),
+        delete: (id) => send<{ ok: boolean }>('DELETE', `/v1/auth/oidc/providers/${id}`),
+        callback: (slug, payload) => send<Session>('POST', `/v1/auth/oidc/${slug}/callback`, payload),
+      },
+    },
+    workspaces: {
+      list: () => get<WorkspaceEntry[]>('/v1/workspaces'),
+      get: (id) => get<WorkspaceDetail>(`/v1/workspaces/${id}`),
+      create: (input) => send<WorkspaceEntry>('POST', '/v1/workspaces', input),
+      update: (id, input) => send<WorkspaceEntry>('PATCH', `/v1/workspaces/${id}`, input),
+      delete: (id) => send<{ ok: boolean }>('DELETE', `/v1/workspaces/${id}`),
+      addMember: (id, input) =>
+        send<WorkspaceMemberEntry | WorkspaceMemberInviteEntry>('POST', `/v1/workspaces/${id}/members`, input),
+      inviteMember: (id, input) =>
+        send<WorkspaceInvitationEntry>('POST', `/v1/workspaces/${id}/invitations`, input),
+      listInvitations: (id) => get<WorkspaceInvitationEntry[]>(`/v1/workspaces/${id}/invitations`),
+      revokeInvitation: (id, inviteId) =>
+        send<{ ok: boolean }>('DELETE', `/v1/workspaces/${id}/invitations/${inviteId}`),
+      previewInvitation: (token) => get<WorkspaceInvitationPublic>(`/v1/invitations/${token}`),
+      acceptInvitation: (token) =>
+        send<{ ok: boolean; workspaceId: number; role: WorkspaceRole }>(
+          'POST',
+          `/v1/invitations/${token}/accept`,
+        ),
+      updateMemberRole: (id, memberId, input) => send<WorkspaceMemberEntry>('PATCH', `/v1/workspaces/${id}/members/${memberId}`, input),
+      removeMember: (id, memberId) => send<{ ok: boolean }>('DELETE', `/v1/workspaces/${id}/members/${memberId}`),
+    },
+    users: {
+      list: () => get<PublicUser[]>('/v1/users'),
+      create: (input) => send<PublicUser>('POST', '/v1/users', input),
+      resetPassword: (id, input) => send<{ ok: boolean }>('PATCH', `/v1/users/${id}/password`, input),
+      resetLink: (id) => send<{ url: string; expiresAt: string }>('POST', `/v1/users/${id}/reset-link`),
+      setOperator: (id, isOperator) =>
+        send<{ ok: boolean; id: number; isOperator: boolean }>('PATCH', `/v1/users/${id}/operator`, { isOperator }),
+      remove: async (id, opts) => {
+        // r540: owned workspaces go to the caller unless `transferTo` names another user.
+        const q = opts?.transferTo != null ? `?transferTo=${encodeURIComponent(String(opts.transferTo))}` : '';
+        await request(`/v1/users/${id}${q}`, { method: 'DELETE' });
+      },
+    },
+    scim: {
+      listTokens: () =>
+        get<Array<{ id: number; name: string; workspaceId: number; createdAt: string | null; lastUsedAt: string | null; revoked: boolean }>>('/v1/scim/tokens'),
+      createToken: (input) =>
+        send<{ id: number; token: string }>('POST', '/v1/scim/tokens', input),
+      revokeToken: (id) => send<{ ok: boolean }>('DELETE', `/v1/scim/tokens/${id}`),
+    },
+    sso: {
+      listProviders: () => get<{
+        providers: Array<{ id: number; type: 'oidc' | 'saml'; name: string; createdAt: string }>;
+      }>('/v1/sso/providers'),
+      addProvider: (input) => send<{
+        ok: boolean;
+        id?: number;
+        name?: string;
+        type?: 'oidc' | 'saml';
+        error?: string;
+      }>('POST', '/v1/sso/providers', input),
+      removeProvider: (id) => send<{ ok: boolean }>('DELETE', `/v1/sso/providers/${id}`),
+    },
+    accessGrants: {
+      list: (workspaceId, query) =>
+        get<AccessGrant[]>(apiGetUrl(`/v1/workspaces/${workspaceId}/access-grants`, { ...query })),
+      create: (workspaceId, input) => send<AccessGrant>('POST', `/v1/workspaces/${workspaceId}/access-grants`, input),
+      update: (workspaceId, grantId, input) =>
+        send<AccessGrant>('PATCH', `/v1/workspaces/${workspaceId}/access-grants/${grantId}`, input),
+      delete: (workspaceId, grantId) =>
+        send<{ ok: boolean }>('DELETE', `/v1/workspaces/${workspaceId}/access-grants/${grantId}`),
+    },
+    access: {
+      me: () => get<AccessMe>('/v1/access/me'),
+      project: (projectId) => get<ProjectAccessEntry[]>(`/v1/projects/${projectId}/access`),
+    },
+  };
+}

package/src/resources/databases.ts

@@ -0,0 +1,227 @@
+// Client surface: databases, backups, backupDestinations, volumeBackups.
+// Split out of the former single-file SDK entry (src/index.ts); the public
+// surface is re-exported unchanged from there.
+import type {
+  CreateVolumeBackupInput,
+  Backup,
+  BackupPolicy,
+  BackupPolicyInput,
+  BackupWithDb,
+  CreateDatabaseInput,
+  ManagedDatabase,
+  DatabaseDetail,
+  SetLimitsInput,
+  PublicAccessPut,
+  PublicAccessStatus,
+  DatabaseImport,
+  DatabaseImportCreate,
+  BackupDestinationObject,
+} from '@ninedeploy/schemas';
+import type { ImportWaitOptions, ImportFileData, ImportFileOptions } from '../databaseImport.js';
+import type { BackupDrillResult, BackupDrillEntry, PgbouncerStatus, DatabaseCredentialsWithPublic } from '../types.js';
+import type { Transport } from '../transport.js';
+import { createImportHelpers } from '../databaseImport.js';
+
+export interface DatabasesApi {
+  databases: {
+    /** `query` is appended verbatim, e.g. `?projectId=3` (project scoping). */
+    list: (query?: string) => Promise<ManagedDatabase[]>;
+    create: (input: CreateDatabaseInput) => Promise<ManagedDatabase>;
+    get: (id: number) => Promise<DatabaseDetail>;
+    remove: (id: number, options?: { force?: boolean }) => Promise<void>;
+    restart: (id: number) => Promise<void>;
+    stop: (id: number) => Promise<void>;
+    start: (id: number) => Promise<void>;
+    logs: (id: number, lines?: number) => Promise<{ logs: string[] }>;
+    credentials: (id: number) => Promise<DatabaseCredentialsWithPublic>;
+    setLimits: (id: number, input: SetLimitsInput) => Promise<{ cpuShares: number | null; memLimitMb: number | null }>;
+    startStudio: (id: number, port?: number) => Promise<{ ok: boolean; port: number; url: string }>;
+    stopStudio: (id: number) => Promise<{ ok: boolean }>;
+    /**
+     * PgBouncer sidecar (G-32). Returns the current sidecar
+     * state — `enabled` + `running` + the URL the services
+     * should connect to. Use the same call after
+     * `enablePgbouncer` / `disablePgbouncer` for a fresh
+     * read (the route returns the post-mutation status).
+     */
+    pgbouncerStatus: (id: number) => Promise<PgbouncerStatus>;
+    /**
+     * Spin up the sidecar. `port` is optional — the row's
+     * existing `pgbouncerPort` (default 6432) is used
+     * when omitted. Only `engine='postgres'` is supported;
+     * the server returns 422 for any other engine.
+     */
+    enablePgbouncer: (id: number, input?: { port?: number }) => Promise<PgbouncerStatus>;
+    /** Stop + remove the sidecar and clear the row's flags. */
+    disablePgbouncer: (id: number) => Promise<PgbouncerStatus>;
+    /**
+     * Run an engine-specific smoke check against a backup
+     * file (pg_restore --list, redis-check-rdb, mysqldump
+     * header parse, ...). Returns the drill row with `status`
+     * of `passed` or `failed`; a failed drill is a real
+     * signal that the backup cannot be restored cleanly, not
+     * a warning. `unverifiable` (r356) means the check could
+     * not run at all. Requires the `member` role on the database.
+     */
+    drillBackup: (id: number, input: { backupId: number }) => Promise<BackupDrillResult>;
+    /** List the most recent drills for a database, newest first. */
+    drills: (id: number) => Promise<BackupDrillEntry[]>;
+    /**
+     * 0.14: public access through a per-database Traefik TCP sidecar. Reading
+     * needs `admin` on the database; `set` and `disable` are operator-only.
+     * Public access exposes the database's ROOT credentials.
+     */
+    publicAccess: {
+      get: (id: number) => Promise<PublicAccessStatus>;
+      /** Applies synchronously; answers the GET shape. */
+      set: (id: number, input: PublicAccessPut) => Promise<PublicAccessStatus>;
+      disable: (id: number) => Promise<{ ok: boolean }>;
+    };
+    /**
+     * 0.14: dump imports. Uploads are chunked at the server-advertised
+     * `chunkSize`; an S3 source (operator-only) downloads in the background
+     * (`uploading` → `pending`) and is then started like an upload.
+     */
+    imports: {
+      create: (id: number, input: DatabaseImportCreate) => Promise<DatabaseImport>;
+      /** Chunk `index` must be the next one (`receivedBytes / chunkSize`). */
+      uploadChunk: (id: number, importId: number, index: number, chunk: Uint8Array) => Promise<DatabaseImport>;
+      /** 202: the job runs in the background; poll `get` or use `wait`. */
+      start: (id: number, importId: number) => Promise<DatabaseImport>;
+      list: (id: number) => Promise<DatabaseImport[]>;
+      get: (id: number, importId: number) => Promise<DatabaseImport>;
+      /** Cancels an `uploading` or `pending` import. */
+      cancel: (id: number, importId: number) => Promise<DatabaseImport>;
+      /** Poll until the import finishes (or, with `until: 'uploaded'`, leaves `uploading`). */
+      wait: (id: number, importId: number, opts?: ImportWaitOptions) => Promise<DatabaseImport>;
+    };
+    /**
+     * 0.14: upload a dump in chunks (resuming from the server's
+     * `receivedBytes` when `resumeImportId` is given), start it, and
+     * optionally poll until it finishes.
+     */
+    importFile: (id: number, data: ImportFileData, opts?: ImportFileOptions) => Promise<DatabaseImport>;
+  };
+  backups: {
+    storage: (databaseId: number) => Promise<{ sizeBytes: number }>;
+    backupNow: (databaseId: number) => Promise<Backup>;
+    listForDb: (databaseId: number) => Promise<Backup[]>;
+    restore: (databaseId: number, backupId: number) => Promise<{ ok: boolean }>;
+    list: () => Promise<BackupWithDb[]>;
+    remove: (backupId: number) => Promise<void>;
+    downloadUrl: (backupId: number) => string;
+    /** 0.12: the database's backup schedule. `configured: false` = no policy
+     *  saved — the built-in daily run with 7 kept applies. */
+    getPolicy: (databaseId: number) => Promise<BackupPolicy>;
+    /** 0.12: save (replace) the database's backup schedule, retention and destination. */
+    setPolicy: (databaseId: number, input: BackupPolicyInput) => Promise<BackupPolicy>;
+  };
+  backupDestinations: {
+    list: () => Promise<Array<{ id: number; name: string; endpoint: string; region: string; bucket: string; prefix: string; active: boolean; createdAt: string }>>;
+    create: (input: { name: string; endpoint: string; region?: string; bucket: string; prefix?: string; accessKeyId: string; secretAccessKey: string }) => Promise<{ id: number }>;
+    update: (id: number, input: Partial<{ name: string; endpoint: string; region: string; bucket: string; prefix: string; active: boolean; accessKeyId: string; secretAccessKey: string }>) => Promise<{ ok: boolean }>;
+    remove: (id: number) => Promise<{ ok: boolean }>;
+    test: (id: number) => Promise<{ ok: boolean }>;
+    /** 0.14: list objects (operator-only); `prefix` defaults to the destination prefix. */
+    objects: (id: number, prefix?: string) => Promise<BackupDestinationObject[]>;
+  };
+  /** Per-volume backup history. The base URL is `/v1/volumes/:name/backups`;
+   *  restore + download go through the same path. The global `/v1/backups`
+   *  list/delete are exposed as `backups` below. */
+  volumeBackups: {
+    list: (volumeName: string) => Promise<Backup[]>;
+    create: (volumeName: string, input: CreateVolumeBackupInput) => Promise<Backup>;
+    restore: (volumeName: string, backupId: number) => Promise<{ ok: boolean }>;
+    downloadUrl: (volumeName: string, backupId: number) => string;
+  };
+}
+
+export function databasesApi(t: Transport): DatabasesApi {
+  const { get, send, request } = t;
+  const { importPath, getImport, uploadChunk, startImport, waitForImport, importFile } = createImportHelpers(t);
+  return {
+    databases: {
+      list: (query) => get<ManagedDatabase[]>(`/v1/databases${query ?? ''}`),
+      create: (input) => send<ManagedDatabase>('POST', '/v1/databases', input),
+      get: (id) => get<DatabaseDetail>(`/v1/databases/${id}`),
+      remove: async (id, opts) => {
+        await request(`/v1/databases/${id}${opts?.force ? '?force=true' : ''}`, { method: 'DELETE' });
+      },
+      restart: async (id) => {
+        await request(`/v1/databases/${id}/restart`, { method: 'POST' });
+      },
+      stop: async (id) => {
+        await request(`/v1/databases/${id}/stop`, { method: 'POST' });
+      },
+      start: async (id) => {
+        await request(`/v1/databases/${id}/start`, { method: 'POST' });
+      },
+      logs: (id, lines) => get<{ logs: string[] }>(`/v1/databases/${id}/logs${lines ? `?lines=${lines}` : ''}`),
+      credentials: (id) => get<DatabaseCredentialsWithPublic>(`/v1/databases/${id}/credentials`),
+      setLimits: (id, input) => send<{ cpuShares: number | null; cpuLimitMilli: number | null; memLimitMb: number | null }>('PATCH', `/v1/databases/${id}/limits`, input),
+      startStudio: (id, port) => send<{ ok: boolean; port: number; url: string }>('POST', `/v1/databases/${id}/studio`, { port }),
+      stopStudio: async (id) => {
+        await request(`/v1/databases/${id}/studio`, { method: 'DELETE' });
+        return { ok: true };
+      },
+      drillBackup: (id, input) =>
+        send<BackupDrillResult>('POST', `/v1/databases/${id}/backups/drill`, input),
+      drills: (id) => get<BackupDrillEntry[]>(`/v1/databases/${id}/drills`),
+      pgbouncerStatus: (id) => get<PgbouncerStatus>(`/v1/databases/${id}/pgbouncer`),
+      enablePgbouncer: (id, input) =>
+        send<PgbouncerStatus>('POST', `/v1/databases/${id}/pgbouncer/enable`, input ?? {}),
+      disablePgbouncer: (id) =>
+        send<PgbouncerStatus>('POST', `/v1/databases/${id}/pgbouncer/disable`, {}),
+      publicAccess: {
+        get: (id) => get<PublicAccessStatus>(`/v1/databases/${id}/public-access`),
+        set: (id, input) => send<PublicAccessStatus>('PUT', `/v1/databases/${id}/public-access`, input),
+        disable: (id) => send<{ ok: boolean }>('DELETE', `/v1/databases/${id}/public-access`),
+      },
+      imports: {
+        create: (id, input) => send<DatabaseImport>('POST', importPath(id), input),
+        uploadChunk,
+        start: startImport,
+        list: (id) => get<DatabaseImport[]>(importPath(id)),
+        get: getImport,
+        cancel: (id, importId) => send<DatabaseImport>('DELETE', importPath(id, importId)),
+        wait: waitForImport,
+      },
+      importFile,
+    },
+    backups: {
+      storage: (databaseId) => get<{ sizeBytes: number }>(`/v1/databases/${databaseId}/storage`),
+      backupNow: (databaseId) => send<Backup>('POST', `/v1/databases/${databaseId}/backups`),
+      listForDb: (databaseId) => get<Backup[]>(`/v1/databases/${databaseId}/backups`),
+      restore: (databaseId, backupId) => send<{ ok: boolean }>('POST', `/v1/databases/${databaseId}/backups/${backupId}/restore`),
+      list: () => get<BackupWithDb[]>('/v1/backups'),
+      remove: async (backupId) => {
+        await request(`/v1/backups/${backupId}`, { method: 'DELETE' });
+      },
+      downloadUrl: (backupId) => `/v1/backups/${backupId}/download`,
+      getPolicy: (databaseId) => get<BackupPolicy>(`/v1/databases/${databaseId}/backup-policy`),
+      setPolicy: (databaseId, input) => send<BackupPolicy>('PUT', `/v1/databases/${databaseId}/backup-policy`, input),
+    },
+    backupDestinations: {
+      list: () => get('/v1/backup-destinations'),
+      create: (input) => send<{ id: number }>('POST', '/v1/backup-destinations', input),
+      update: (id, input) => send<{ ok: boolean }>('PATCH', `/v1/backup-destinations/${id}`, input),
+      remove: (id) => send<{ ok: boolean }>('DELETE', `/v1/backup-destinations/${id}`),
+      test: (id) => send<{ ok: boolean }>('POST', `/v1/backup-destinations/${id}/test`),
+      objects: (id, prefix) =>
+        get<BackupDestinationObject[]>(
+          `/v1/backup-destinations/${id}/objects${prefix === undefined ? '' : `?prefix=${encodeURIComponent(prefix)}`}`,
+        ),
+    },
+    volumeBackups: {
+      // Path segments are user-visible names: encode them like the rest of
+      // the client does, or '?'/'#'/'%' in a volume name rewrite the URL.
+      list: (volumeName) => get<Backup[]>(`/v1/volumes/${encodeURIComponent(volumeName)}/backups`),
+      create: (volumeName, input) =>
+        send<Backup>('POST', `/v1/volumes/${encodeURIComponent(volumeName)}/backups`, input),
+      restore: (volumeName, backupId) =>
+        send<{ ok: boolean }>('POST', `/v1/volumes/${encodeURIComponent(volumeName)}/backups/${backupId}/restore`),
+      downloadUrl: (volumeName, backupId) =>
+        `/v1/volumes/${encodeURIComponent(volumeName)}/backups/${backupId}/download`,
+    },
+  };
+}