@synteq/cli 0.1.6 → 1.1.1

package/bin/run.js

@@ -1,9 +1,68 @@
 #!/usr/bin/env node
 import { execute } from "@oclif/core";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
 
-// Bare `synteq` on a TTY → launch the interactive app.
-// Same call when piped (or with args) falls through to oclif as normal.
+// bin/ is a sibling of dist/ under cli/. package.json's oclif.commands /
+// oclif.helpClass already point at ./dist/*, so dist/ existing is already a
+// hard requirement for this CLI to run at all — importing the shim from
+// dist/ here doesn't add a new constraint. The dev path (bin/dev.js,
+// ts-node against src/) is separate and unaffected.
+import { checkOutdatedFromCacheForBin } from "../dist/version-check-bin.js";
+
+function isApiKeyMode() {
+  const envToken = (process.env.SYNTEQ_API_TOKEN ?? "").trim();
+  if (envToken) return true;
+  // TokenStore (src/auth/tokens.ts) prefers the OS keychain and only
+  // falls back to a file on disk when the keychain write fails (e.g. no
+  // keychain daemon on Linux/CI). So this file-backed check is
+  // best-effort: it catches the fallback case but can't see a
+  // keychain-stored api_key. That's fine — this bin-level short-circuit
+  // exists mainly for the env-var path; the keychain-backed case is
+  // still caught by the guard inside src/commands/tui/index.ts, which
+  // runs after oclif boots and can read the real TokenStore.
+  const cfgDir = process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+  const tokensPath = join(cfgDir, "synteq", "tokens.json");
+  if (!existsSync(tokensPath)) return false;
+  try {
+    const parsed = JSON.parse(readFileSync(tokensPath, "utf8"));
+    return parsed?.kind === "api_key";
+  } catch {
+    return false;
+  }
+}
+
+// Version check FIRST — before the bare-TTY api-key short-circuit and
+// before `tui` gets pushed onto argv. An outdated bare `synteq` invocation
+// (TTY or not, api-key mode or not) must exit 4, not silently proceed.
+// (F3 — the old ordering let a bare-TTY api-key invocation call
+// process.exit(0) before this ran, swallowing the version check entirely.)
+//
+// Unconditional (not just bare-TTY) — scripted/CI invocations also need to
+// fail fast on outdated, before oclif spins up. Cache-only, no network.
+// checkOutdatedFromCacheForBin already skips SYNTEQ_SKIP_VERSION_CHECK=1
+// and exempt commands (login/logout/settings*, colon or space form) so a
+// locked-out user can still recover.
+{
+  const outdatedMsg = checkOutdatedFromCacheForBin(process.argv);
+  if (outdatedMsg) {
+    process.stderr.write(outdatedMsg + "\n");
+    process.exit(4);
+  }
+}
+
+// Bare `synteq` on a TTY → launch the interactive app, unless the caller
+// is in API-key mode, in which case the TUI has no meaningful state to
+// show and we exit 0 with a hint.
 if (process.argv.length === 2 && process.stdout.isTTY) {
+  if (isApiKeyMode()) {
+    process.stderr.write(
+      "The interactive TUI requires a user session — API keys are for scripted commands only.\n" +
+      "Run 'synteq login' for a session, or 'synteq --help' to see commands this key can call.\n",
+    );
+    process.exit(0);
+  }
   process.argv.push("tui");
 }
 

package/dist/api/client.d.ts

@@ -1,13 +1,52 @@
 import type { TokenStore } from "../auth/tokens.js";
-import type { Project, Resource, WhoAmI, Team, TokenPair, DeviceCodeOut, TransitService, StorageVolume, CreditEntry, BalanceOut, CreditTopupIn, CreditTopupOut, PaymentMethod, ReinstallIn, HypervisorTask, BootOrderOut, ActivityList, OrderCatalog, VirtualizedOrderIn, OrderResultOut, StorageCatalog, BlockVolumeCreateIn, BlockVolumeCreateOut, AttachOut, DetachOut, TeamInviteIn, OrgDetails, SSHKey, ApiKeyWhoami, ResourceOrderStatusOut, ReinstallStatusOut, ResourceAddon, PendingResourceAddon, AddonAttachIn, AddonAttachOut, ResourceResizeIn, ResourceResizeQuoteOut, ResourceResizeOut, ConsoleTokenOut, BlockVolumeResizeQuoteIn, BlockVolumeResizeQuoteOut, BlockVolumeResizeIn, BlockVolumeResizeOut, BandwidthSummary, SetDefaultMethodOut, TicketDepartment, TicketListItem, Ticket, TicketMessage, TicketCreateIn, TicketMessageIn, TicketStatus } from "./types.js";
-export declare const CLI_VERSION = "0.1.6";
+import type { Project, Resource, WhoAmI, Team, TokenPair, DeviceCodeOut, TransitService, StorageVolume, CreditEntry, BalanceOut, CreditTopupIn, CreditTopupOut, PaymentMethod, PaymentMethodEligibility, ReinstallIn, HypervisorTask, BootOrderOut, ActivityList, OrderCatalog, VirtualizedOrderIn, OrderResultOut, PreviewOrderOut, StorageCatalog, BlockVolumeCreateIn, BlockVolumeCreateOut, AttachOut, DetachOut, TeamInviteIn, OrgDetails, SSHKey, ApiKeyWhoami, ResourceOrderStatusOut, ReinstallStatusOut, ResourceAddon, PendingResourceAddon, AddonAttachIn, AddonAttachOut, AddonQuoteIn, AddonQuoteOut, ResourceResizeIn, ResourceResizeQuoteOut, ResourceResizeOut, ConsoleTokenOut, BlockVolumeResizeQuoteIn, BlockVolumeResizeQuoteOut, BlockVolumeResizeIn, BlockVolumeResizeOut, BandwidthSummary, SetDefaultMethodOut, TicketDepartment, TicketListItem, Ticket, TicketMessage, TicketAttachment, TicketCreateIn, TicketMessageIn, TicketStatus, BaremetalService, BaremetalInvoice, BaremetalPowerState, BaremetalPowerAction, BaremetalJobResult, BaremetalInstallProfile, BaremetalJob, BaremetalJobEvent, BaremetalInstallPasswordStatus, BaremetalInstallPasswordOut, BaremetalReinstallIn, BaremetalCatalogOut, BaremetalOrderSpec, App, AppCreateIn, AppNameCheck, AppPlan, AppLocation, Build, BuildDetail, SourceUploadUrlOut, LogHistory, AppUsage, AppHealth, AppDomain, PlanChangePreview, PlanChange, AppSettings, AppSettingsPatch, Release, EnvVar, EnvVarSetIn, DeployIn, GithubLink, GithubLinkIn, WsTicket, Fn, FnCreateIn, FnPlan, FnLocation, FnNameCheck, FnSourceFile, FnSource, FnBuild, FnRelease, FnRollbackOut, FnRunListOut, FnEnvVar, FnEnvVarSetIn, FnEnvReveal, FnCronTrigger, FnCronTriggerCreateIn, FnCronTriggerUpdateIn, FnUpdateIn, FnBilling, FnTeamBilling, FnAutoReloadIn, FnAutoReloadState, FnCreditsPurchaseIn, FnCreditsQuote, FnCreditsPurchaseOut, AppByRepo } from "./types.js";
+export declare const CLI_VERSION = "1.1.1";
 type FetchLike = (input: string, init: Record<string, unknown>) => Promise<Response>;
 interface RequestOpts {
     body?: unknown;
+    formData?: FormData;
+    /** Raw bytes to send verbatim (skips JSON serialization). Sets no default
+     *  Content-Type — pass one in `headers`. Used for tarball uploads. */
+    rawBody?: Uint8Array;
     query?: Record<string, string | number | undefined>;
     headers?: Record<string, string>;
     auth?: boolean;
 }
+/** The numeric twin of PAGE_MAX for the routes that take `query:` params. */
+export declare const LIST_PAGE_MAX = 200;
+/** /tickets caps per_page at 100 and 422s on a larger value (never clamps). */
+export declare const TICKET_PAGE_MAX = 100;
+export declare function listItems<T>(r: T[] | {
+    items?: T[] | null;
+} | null | undefined): T[];
+/** One page of a paginated list route (portal #419): the rows, how many
+ *  rows match in total, and where this page sits. */
+export interface Page<T> {
+    items: T[];
+    total: number;
+    page: number;
+    per_page: number;
+    pages: number;
+}
+/** Normalise a list response to a `Page` whether the portal answered the
+ *  `{items,total,page,per_page,pages}` envelope or (an older portal) a bare
+ *  array — a bare array is the whole list, so it is one page of itself. */
+export declare function asPage<T>(r: T[] | Partial<Page<T>> | null | undefined): Page<T>;
+/** Query params the paginated list routes share. `q` is a server-side
+ *  search (what it matches differs per route — see each `listPage`). */
+export interface ListQuery {
+    q?: string;
+    page?: number;
+    per_page?: number;
+}
+/**
+ * Walk a paginated route from page 1 until the last page, an empty page, or
+ * `stop(page)` says the caller has what it came for. THE one paging loop in
+ * the CLI: the name resolvers (an id prefix `q=` cannot search, a ticket #
+ * whose `q=` page is still full, a release number past the first 200) all
+ * go through here rather than each carrying its own `while` loop.
+ */
+export declare function pageThrough<T>(fetchPage: (page: number) => Promise<Page<T>>, stop?: (page: Page<T>) => boolean): Promise<T[]>;
 export declare class ApiClient {
     private opts;
     constructor(opts: {
@@ -19,6 +58,18 @@ export declare class ApiClient {
         apiToken?: string;
     });
     private get fetchImpl();
+    /** The token refresh in flight, if any. Requests that 401 together (a
+     *  `Promise.all` of list calls on an expired access token) coalesce onto
+     *  it: a refresh token is single-use, so a second POST /auth/refresh with
+     *  the same one is refused and would turn a recoverable expiry into a
+     *  spurious "session expired". */
+    private refreshing;
+    /** Whether this client was configured to skip TLS verification
+     *  (--insecure / SYNTEQ_INSECURE_TLS). Read by the direct-upload PUT
+     *  (apps-support/deploy.ts's uploadSource), which goes over node:http(s)
+     *  rather than through dispatch()/makeInit() and needs to honour the same
+     *  setting for local-dev self-signed certs. */
+    get insecureTls(): boolean;
     private makeInit;
     request<T>(method: string, path: string, opts?: RequestOpts): Promise<T>;
     rawRequest(method: string, path: string, opts?: RequestOpts & {
@@ -29,7 +80,36 @@ export declare class ApiClient {
         body: unknown;
         text: string;
     }>;
+    /**
+     * POST a single file as multipart/form-data. Reuses request()/dispatch() for
+     * auth and error handling; the FormData body makes fetch pick the boundary
+     * and Content-Type, so it bypasses the JSON envelope applied by default.
+     */
+    uploadMultipart<T>(path: string, file: {
+        path: string;
+        filename: string;
+        contentType: string;
+    }, field?: string): Promise<T>;
+    /**
+     * GET a binary resource (e.g. a ticket attachment). Unlike request(), this
+     * reads the raw bytes instead of JSON-decoding, and returns the server's
+     * Content-Type and suggested filename from the response headers.
+     */
+    download(path: string): Promise<{
+        bytes: Buffer;
+        contentType: string | null;
+        filename: string | null;
+    }>;
     private dispatch;
+    /**
+     * Single-flight wrapper around `tryRefresh`. `used` is the pair the 401'd
+     * request was sent with. One refresh runs at a time; everyone who 401s
+     * while it is in flight gets its result. A request that 401s AFTER a
+     * refresh already finished (it was sent with the old access token, the
+     * store now holds the new pair) takes the stored pair as-is rather than
+     * spending a refresh token that no longer exists.
+     */
+    private refreshTokens;
     private tryRefresh;
     private buildUrl;
     private parseResponse;
@@ -38,6 +118,7 @@ export declare class ApiClient {
         deviceToken: (device_code: string, client_id?: string) => Promise<TokenPair>;
         minCliVersion: () => Promise<{
             min_cli_version: string;
+            deprecated_message: string | null;
         }>;
         logout: (refresh_token: string) => Promise<{
             message: string;
@@ -45,6 +126,14 @@ export declare class ApiClient {
         whoami: () => Promise<WhoAmI>;
         apiKeyWhoami: () => Promise<ApiKeyWhoami>;
         teams: () => Promise<Team[]>;
+        /**
+         * Mint a single-use, 60s WebSocket ticket. Browsers can't attach the
+         * session cookie to a `ws://` handshake; the CLI carries a bearer token
+         * but the log WS reuses the same ticket contract for parity, so we fetch
+         * a throwaway ticket and pass it as `?token=` on the ws URL. The ticket
+         * is consumed exactly once server-side.
+         */
+        wsTicket: () => Promise<WsTicket>;
     };
     projects: {
         list: () => Promise<Project[]>;
@@ -58,7 +147,14 @@ export declare class ApiClient {
         remove: (keyId: string) => Promise<void>;
     };
     virtualized: {
-        list: (projectId?: string) => Promise<Resource[]>;
+        /** GET /resources (50/200): `q` matches hostname / id / IP / location,
+         *  `kind` narrows to one virtualized kind server-side. */
+        listPage: (projectId?: string, query?: ListQuery & {
+            kind?: string;
+        }) => Promise<Page<Resource>>;
+        list: (projectId?: string, query?: ListQuery & {
+            kind?: string;
+        }) => Promise<Resource[]>;
         get: (resourceId: string) => Promise<Resource>;
         stats: (resourceId: string, timeframe?: "hour" | "day" | "week" | "month" | "year") => Promise<Record<string, unknown> | Record<string, unknown>[]>;
         rrd: (resourceId: string, timeframe?: "hour" | "day" | "week" | "month" | "year") => Promise<{
@@ -76,7 +172,10 @@ export declare class ApiClient {
         list: (projectId?: string) => Promise<TransitService[]>;
     };
     storage: {
-        list: (projectId?: string) => Promise<StorageVolume[]>;
+        /** GET /resources/block_volume (50/200): `q` matches name / id /
+         *  attached VM hostname. */
+        listPage: (projectId?: string, query?: ListQuery) => Promise<Page<StorageVolume>>;
+        list: (projectId?: string, query?: ListQuery) => Promise<StorageVolume[]>;
         catalog: () => Promise<StorageCatalog>;
         order: (body: BlockVolumeCreateIn, projectId?: string) => Promise<BlockVolumeCreateOut>;
         attach: (volumeId: string, resourceId: string) => Promise<AttachOut>;
@@ -100,6 +199,10 @@ export declare class ApiClient {
     };
     payments: {
         methods: () => Promise<PaymentMethod[]>;
+        /** Every active team method annotated with whether THIS touchpoint may
+         *  charge it (the backend owns the allowlist; the web's pickers read the
+         *  same route). */
+        methodsForTouchpoint: (touchpoint: string) => Promise<PaymentMethodEligibility[]>;
         topup: (body: CreditTopupIn) => Promise<CreditTopupOut>;
         setDefaultMethod: (methodId: string) => Promise<SetDefaultMethodOut>;
         deleteMethod: (methodId: string) => Promise<void>;
@@ -120,6 +223,7 @@ export declare class ApiClient {
         list: (resourceId: string) => Promise<ResourceAddon[]>;
         pending: (resourceId: string) => Promise<PendingResourceAddon[]>;
         attach: (resourceId: string, body: AddonAttachIn) => Promise<AddonAttachOut>;
+        quote: (resourceId: string, body: AddonQuoteIn) => Promise<AddonQuoteOut>;
     };
     projectActivity: {
         list: (projectId: string, limit?: number, offset?: number) => Promise<ActivityList>;
@@ -140,6 +244,45 @@ export declare class ApiClient {
         }>;
         create: (body: VirtualizedOrderIn) => Promise<OrderResultOut>;
         status: (orderId: string) => Promise<ResourceOrderStatusOut>;
+        preview: (body: {
+            kind: "virtualized" | "block_volume" | "baremetal" | "addon" | "resize" | "app";
+            spec: Record<string, unknown>;
+            quantity?: number;
+        }) => Promise<PreviewOrderOut>;
+        /** A paid app is an ORDER: the first month is invoiced and charged, and
+         *  provisioning runs off the settled order (the web's NewAppPayModal
+         *  does the same). POST /apps only creates free-tier apps. */
+        createApp: (spec: AppOrderSpec, payment: GenericPaymentIn) => Promise<GenericCreateOrderOut>;
+    };
+    baremetal: {
+        /** GET /baremetal (50/200): `q` matches hostname / reference / primary
+         *  IP / id. */
+        listPage: (query?: ListQuery) => Promise<Page<BaremetalService>>;
+        list: (query?: ListQuery) => Promise<BaremetalService[]>;
+        get: (serviceId: string) => Promise<BaremetalService>;
+        invoices: (serviceId: string) => Promise<BaremetalInvoice[]>;
+        activity: (serviceId: string, limit?: number, offset?: number) => Promise<ActivityList>;
+        bandwidth: (serviceId: string) => Promise<BandwidthSummary>;
+        powerState: (serviceId: string) => Promise<BaremetalPowerState>;
+        power: (serviceId: string, action: BaremetalPowerAction) => Promise<BaremetalJobResult>;
+        installProfiles: (serviceId: string) => Promise<{
+            profiles: BaremetalInstallProfile[];
+        }>;
+        jobs: (serviceId: string) => Promise<{
+            jobs: BaremetalJob[];
+        }>;
+        jobEvents: (serviceId: string, jobId: string) => Promise<{
+            events: BaremetalJobEvent[];
+        }>;
+        cancelJob: (serviceId: string, jobId: string) => Promise<BaremetalJobResult>;
+        reinstall: (serviceId: string, body: BaremetalReinstallIn) => Promise<BaremetalJobResult>;
+        installPasswordStatus: (serviceId: string) => Promise<BaremetalInstallPasswordStatus>;
+        revealInstallPassword: (serviceId: string) => Promise<BaremetalInstallPasswordOut>;
+        catalog: () => Promise<BaremetalCatalogOut>;
+        installProfilesForOffering: (offeringId: string) => Promise<{
+            profiles: BaremetalInstallProfile[];
+        }>;
+        order: (spec: BaremetalOrderSpec, payment: GenericPaymentIn, projectId?: string) => Promise<OrderResultOut>;
     };
     teams: {
         details: (teamId: string) => Promise<OrgDetails>;
@@ -147,12 +290,227 @@ export declare class ApiClient {
     };
     tickets: {
         departments: () => Promise<TicketDepartment[]>;
-        list: () => Promise<TicketListItem[]>;
+        /** GET /tickets (25/100): `q` matches `display_id == int(q)` OR a
+         *  subject / body substring (so a `#` lookup still exact-matches
+         *  client-side); `status` filters server-side. Its cap is 100, not
+         *  200 — a larger per_page is a 422, never clamped. */
+        listPage: (query?: ListQuery & {
+            status?: TicketStatus;
+        }) => Promise<Page<TicketListItem>>;
+        list: (query?: ListQuery & {
+            status?: TicketStatus;
+        }) => Promise<TicketListItem[]>;
         get: (ticketId: string) => Promise<Ticket>;
         messages: (ticketId: string) => Promise<TicketMessage[]>;
         create: (body: TicketCreateIn) => Promise<Ticket>;
         reply: (ticketId: string, body: TicketMessageIn) => Promise<TicketMessage>;
+        uploadAttachment: (ticketId: string, messageId: string, file: {
+            path: string;
+            filename: string;
+            contentType: string;
+        }) => Promise<TicketAttachment>;
+        downloadAttachment: (ticketId: string, messageId: string, attachmentId: string) => Promise<{
+            bytes: Buffer;
+            contentType: string | null;
+            filename: string | null;
+        }>;
         setStatus: (ticketId: string, status: TicketStatus) => Promise<Ticket>;
     };
+    /**
+     * Managed containers (apps). Like `vps`, list/create are scoped to the
+     * active project by the `X-Project-Id` header, not a query param — the
+     * backend resolves the active project from it (falling back to the team's
+     * first project when unset). Responses are camelCase (`_CamelOut`).
+     */
+    apps: {
+        plans: () => Promise<AppPlan[]>;
+        /** Placeable clusters for this environment — what the web onboarding's
+         *  location picker reads, so the CLI never offers a location that has
+         *  no cluster behind it. */
+        locations: () => Promise<AppLocation[]>;
+        /** GET /apps (50/200): `q` matches name / slug / hostname. */
+        listPage: (projectId?: string, query?: ListQuery) => Promise<Page<App>>;
+        list: (projectId?: string, query?: ListQuery) => Promise<App[]>;
+        get: (appId: string) => Promise<App>;
+        /** Apps deploying from a GitHub repo, across every team the user is in. */
+        findByRepo: (repo: string) => Promise<AppByRepo[]>;
+        checkName: (slug: string) => Promise<AppNameCheck>;
+        create: (body: AppCreateIn, projectId?: string) => Promise<App>;
+        deploy: (appId: string, body: DeployIn) => Promise<Build>;
+        /** Deploy from a local source tarball (gzipped tar as the raw body). The
+         *  portal stores it + the cluster builds it — no external URL needed.
+         *  Fallback path (loads the whole tarball into memory) — kept for
+         *  clusters that don't support direct upload; use `uploadSource()`
+         *  (apps-support/deploy.ts) for the streamed path, which tries this
+         *  automatically when direct upload isn't available and the pack fits
+         *  the proxy's body-size limit. */
+        deploySource: (appId: string, tarball: Uint8Array) => Promise<Build>;
+        /** Mint a presigned PUT for the object store, so the CLI can upload the
+         *  (possibly ~1 GB) source tarball directly instead of through the API —
+         *  the proxy in front of the API rejects bodies over 100 MB. A used or
+         *  expired URL must not be reused: call this again for every retry, with
+         *  `replaces` set to the previous attempt's `objectKey` so the API frees
+         *  that attempt's pending-upload slot (an older API 422s the field). */
+        sourceUploadUrl: (appId: string, body: {
+            sizeBytes: number;
+            sha256: string;
+            replaces?: string;
+        }) => Promise<SourceUploadUrlOut>;
+        /** Trigger the build from an object already PUT to the URL
+         *  `sourceUploadUrl` minted — the counterpart to `deploySource` for the
+         *  direct-upload path. */
+        deploySourceObject: (appId: string, objectKey: string) => Promise<Build>;
+        builds: (appId: string) => Promise<Build[]>;
+        /** GET /apps/{id}/releases (50/200), ordered by number desc. */
+        releasesPage: (appId: string, query?: ListQuery) => Promise<Page<Release>>;
+        releases: (appId: string) => Promise<Release[]>;
+        env: (appId: string) => Promise<EnvVar[]>;
+        setEnv: (appId: string, body: EnvVarSetIn) => Promise<EnvVar>;
+        /** "Roll out now": push the saved env and redeploy the current release. */
+        rolloutEnv: (appId: string) => Promise<void>;
+        /** GitHub push-to-deploy link. GET returns null when nothing is linked. */
+        githubLink: (appId: string) => Promise<GithubLink | null>;
+        linkGithub: (appId: string, body: GithubLinkIn) => Promise<GithubLink>;
+        unlinkGithub: (appId: string) => Promise<void>;
+        revealEnv: (appId: string, key: string) => Promise<{
+            key: string;
+            value: string;
+        }>;
+        deleteEnv: (appId: string, key: string) => Promise<void>;
+        buildDetail: (appId: string, buildId: string) => Promise<BuildDetail>;
+        /** `since` is a relative window (15m … 4320h). `from` / `until` (ISO
+         *  instants) name an absolute timeframe instead — `from` replaces
+         *  `since`, `until` bounds the top (2026-09-12). */
+        logHistory: (appId: string, opts?: {
+            since?: string;
+            from?: string;
+            until?: string;
+            container?: string;
+            search?: string;
+            limit?: number;
+        }) => Promise<LogHistory>;
+        /** `range` (15m/1h/6h/24h/72h/168h) shapes the series; `since`+`until`
+         *  (ISO, together) pick an explicit window instead. */
+        usage: (appId: string, opts?: {
+            range?: string;
+            since?: string;
+            until?: string;
+        }) => Promise<AppUsage>;
+        rollback: (appId: string, toRelease: number) => Promise<Build>;
+        health: (appId: string) => Promise<AppHealth>;
+        domains: (appId: string) => Promise<AppDomain[]>;
+        addDomain: (appId: string, domain: string, opts?: {
+            acceptFee?: boolean;
+        }) => Promise<AppDomain>;
+        verifyDomain: (appId: string, domainId: string) => Promise<AppDomain>;
+        removeDomain: (appId: string, domainId: string) => Promise<void>;
+        planPreview: (appId: string, planTier: string, schedule?: string) => Promise<PlanChangePreview>;
+        changePlan: (appId: string, body: {
+            planTier: string;
+            schedule?: string;
+        }) => Promise<PlanChange>;
+        settings: (appId: string) => Promise<AppSettings>;
+        patchSettings: (appId: string, body: AppSettingsPatch) => Promise<AppSettings>;
+    };
+    /**
+     * Functions (serverless). Same shape discipline as `apps` above, against
+     * portal/backend/app/routers/functions*.py. Project scoping rides the
+     * X-Project-Id header exactly as apps does. Nothing here names a build
+     * frontend: how a function builds is decided server-side from the bundle
+     * and the function's runtime, never by the caller.
+     */
+    functions: {
+        plans: () => Promise<FnPlan[]>;
+        locations: () => Promise<FnLocation[]>;
+        /** GET /functions (100/200): `q` matches name / slug / hostname. Until
+         *  #419 this read the 100-row default page and unwrapped it by hand,
+         *  so the 101st function was invisible to every resolver. */
+        listPage: (projectId?: string, query?: ListQuery) => Promise<Page<Fn>>;
+        list: (projectId?: string, query?: ListQuery) => Promise<Fn[]>;
+        get: (fnId: string) => Promise<Fn>;
+        checkName: (name: string) => Promise<FnNameCheck>;
+        create: (body: FnCreateIn, projectId?: string) => Promise<Fn>;
+        update: (fnId: string, body: FnUpdateIn) => Promise<Fn>;
+        delete: (fnId: string, passwordChallenge: string) => Promise<void>;
+        /** Deploy pasted files. The backend tars them, keeps them on the build row
+         *  (so `source` can reopen them) and picks the build path itself. */
+        deployFiles: (fnId: string, files: FnSourceFile[]) => Promise<FnBuild>;
+        /** The same endpoint's tarball shape: no 32-file editor limit, only the
+         *  function's source caps. */
+        deployTarball: (fnId: string, tarball: Uint8Array) => Promise<FnBuild>;
+        /** Deploy a pre-built image: the apps `deploy --image` route, function-owned
+         *  (POST /functions/{id}/deploys — a pull Build; the status cron mints the
+         *  release off the build's own digest). */
+        deployImage: (fnId: string, imageRef: string) => Promise<FnBuild>;
+        source: (fnId: string) => Promise<FnSource>;
+        builds: (fnId: string) => Promise<FnBuild[]>;
+        build: (fnId: string, buildId: string) => Promise<FnBuild>;
+        /** GET /functions/{id}/releases (50/200), ordered by number desc. */
+        releasesPage: (fnId: string, query?: ListQuery) => Promise<Page<FnRelease>>;
+        releases: (fnId: string) => Promise<FnRelease[]>;
+        rollback: (fnId: string, toRelease: number) => Promise<FnRollbackOut>;
+        /** Per-invocation records, newest first. `before` is the opaque cursor
+         *  from the previous page's `nextBefore`. */
+        runs: (fnId: string, opts?: {
+            limit?: number;
+            before?: string;
+            status?: string;
+            release?: number;
+            q?: string;
+        }) => Promise<FnRunListOut>;
+        env: (fnId: string) => Promise<FnEnvVar[]>;
+        setEnv: (fnId: string, body: FnEnvVarSetIn) => Promise<FnEnvVar>;
+        /** "Roll out now": push the saved env and redeploy the current release. */
+        rolloutEnv: (fnId: string) => Promise<void>;
+        deleteEnv: (fnId: string, key: string) => Promise<void>;
+        revealEnv: (fnId: string, key: string) => Promise<FnEnvReveal>;
+        cronTriggers: (fnId: string) => Promise<FnCronTrigger[]>;
+        createCronTrigger: (fnId: string, body: FnCronTriggerCreateIn) => Promise<FnCronTrigger>;
+        updateCronTrigger: (fnId: string, triggerId: string, body: FnCronTriggerUpdateIn) => Promise<FnCronTrigger>;
+        deleteCronTrigger: (fnId: string, triggerId: string) => Promise<void>;
+        runCronTrigger: (fnId: string, triggerId: string) => Promise<FnCronTrigger>;
+        billing: (fnId: string) => Promise<FnBilling>;
+        setCreditAutoReload: (fnId: string, body: FnAutoReloadIn) => Promise<FnAutoReloadState>;
+        /** No per-function quote route exists: price from the billing view's
+         *  `creditRateUsd` (an estimate; tax lands on the invoice). */
+        purchaseCredits: (fnId: string, body: FnCreditsPurchaseIn) => Promise<FnCreditsPurchaseOut>;
+        teamBilling: () => Promise<FnTeamBilling>;
+        setTeamCreditAutoReload: (body: FnAutoReloadIn) => Promise<FnAutoReloadState>;
+        quoteTeamCredits: (body: FnCreditsPurchaseIn) => Promise<FnCreditsQuote>;
+        purchaseTeamCredits: (body: FnCreditsPurchaseIn) => Promise<FnCreditsPurchaseOut>;
+    };
+}
+type GenericPaymentMethod = "saved" | "bitpay" | "credit_only" | "invoice_only";
+/** POST /orders kind=app spec — what AppProvider.validate_spec reads. */
+export interface AppOrderSpec {
+    slug: string;
+    plan_tier: string;
+    region: string;
+    project_id?: string;
+}
+export interface GenericPaymentIn {
+    method: GenericPaymentMethod;
+    payment_method_id?: string;
+    apply_credits?: boolean;
+    bitpay_redirect_url?: string;
+}
+interface GenericCreateOrderOut {
+    order_id: string;
+    status: string;
+    invoice_id?: string | null;
+    checkout_url?: string | null;
+    charge_id?: string | null;
+    provider?: string | null;
+    credits_applied?: string | null;
 }
+/** Old `VirtualizedOrderIn.payment_kind` ("method"/"bitpay") + a `payment_method_id`
+ *  that may or may not be set collapses two customer intents ("charge this
+ *  saved method" vs "pay from credit balance, no method") into one literal.
+ *  The new `GenericPaymentIn.method` enum keeps them distinct — split here
+ *  so callers (order.ts, pickPayment) don't need to know about the new
+ *  vocabulary at all. */
+export declare function virtualizedOrderInToGenericSpecs(body: VirtualizedOrderIn): {
+    specs: Record<string, unknown>[];
+    payment: GenericPaymentIn;
+};
 export {};