@synteq/cli 0.2.0 → 1.1.2

package/dist/api/client.js

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
 import { ApiError, AuthExpiredError, NetworkError } from "./errors.js";
-export const CLI_VERSION = "0.2.0";
+export const CLI_VERSION = "1.1.2";
 let insecureTlsWarned = false;
 function isLocalOrPrivateHost(hostname) {
     const h = hostname.toLowerCase().replace(/^\[/, "").replace(/\]$/, "");
@@ -38,6 +39,86 @@ function warnInsecureTls(baseUrl) {
     insecureTlsWarned = true;
     process.stderr.write(`WARNING: TLS certificate verification disabled for ${baseUrl} — credentials may be exposed.\n`);
 }
+/** A list route's rows whether the portal answers a bare array (the shape
+ *  these routes had through 2026-10-08) or the paginated
+ *  `{items, total, page, per_page, pages}` envelope the apps / functions
+ *  lists moved to (portal 1a57feba0). The CLI never names a page, so the
+ *  first page is the list it asked for; a shape that is neither is an empty
+ *  list rather than a `.find is not a function` crash mid-deploy. */
+/** The widest page the paginated list routes allow (`page_params(max_per_page=200)`),
+ *  asked for on every list the CLI reads whole — a 50-row default page would
+ *  silently drop the 51st app or release that the pre-page routes returned.
+ *  An older portal that still answers a bare array ignores the query. */
+const PAGE_MAX = "per_page=200";
+/** The numeric twin of PAGE_MAX for the routes that take `query:` params. */
+export const LIST_PAGE_MAX = 200;
+/** /tickets caps per_page at 100 and 422s on a larger value (never clamps). */
+export const TICKET_PAGE_MAX = 100;
+export function listItems(r) {
+    if (Array.isArray(r))
+        return r;
+    if (r && Array.isArray(r.items))
+        return r.items;
+    return [];
+}
+/** 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 function asPage(r) {
+    if (Array.isArray(r))
+        return { items: r, total: r.length, page: 1, per_page: r.length, pages: 1 };
+    const items = listItems(r);
+    const total = typeof r?.total === "number" ? r.total : items.length;
+    const page = typeof r?.page === "number" && r.page > 0 ? r.page : 1;
+    const per_page = typeof r?.per_page === "number" && r.per_page > 0 ? r.per_page : items.length;
+    const pages = typeof r?.pages === "number" && r.pages > 0 ? r.pages : 1;
+    return { items, total, page, per_page, pages };
+}
+/**
+ * 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 async function pageThrough(fetchPage, stop) {
+    const out = [];
+    let pageNo = 1;
+    for (;;) {
+        const page = await fetchPage(pageNo);
+        out.push(...page.items);
+        if (page.items.length === 0 || stop?.(page))
+            break;
+        // `pages` is the server's count; a bare-array portal reports 1. A page
+        // that came back short of `per_page` is also the last one.
+        if (page.page >= page.pages || page.items.length < page.per_page)
+            break;
+        pageNo = page.page + 1;
+    }
+    return out;
+}
+/** A /resources/block_volume row in the CLI's StorageVolume shape (the
+ *  GET /storage list this replaced). */
+function storageVolumeFromRow(r) {
+    return {
+        id: r.id,
+        name: r.name,
+        size_gb: r.size_gb,
+        status: r.status,
+        is_attached: r.status === "attached",
+        disk_slot: r.disk_slot,
+        monthly_price: r.monthly_price != null ? Number(r.monthly_price) : null,
+        attached_resource_id: r.resource_id,
+        attached_resource_hostname: r.attached_resource_hostname,
+        project_id: r.project_id,
+        project_name: r.project_name,
+        // BlockVolumeOut carries location_name only; nothing in the CLI
+        // consumes StorageVolume.location_id.
+        location_id: null,
+        location_name: r.location_name,
+        created_at: r.created_at,
+    };
+}
 export class ApiClient {
     opts;
     constructor(opts) {
@@ -46,11 +127,26 @@ export class ApiClient {
     get fetchImpl() {
         return (this.opts.fetchImpl ?? globalThis.fetch);
     }
-    async makeInit(method, headers, body) {
+    /** 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". */
+    refreshing = null;
+    /** 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() {
+        return Boolean(this.opts.insecure);
+    }
+    async makeInit(method, headers, body, rawBody) {
         const init = {
             method,
             headers,
-            body: body ? JSON.stringify(body) : undefined,
+            body: rawBody ??
+                (body instanceof FormData ? body : body ? JSON.stringify(body) : undefined),
         };
         if (this.opts.insecure) {
             warnInsecureTls(this.opts.baseUrl);
@@ -70,18 +166,71 @@ export class ApiClient {
             headers[k] = v;
         });
         opts.onResponse?.(res.status, headers);
-        const text = res.status === 204 ? "" : await res.text();
+        let text;
+        try {
+            text = res.status === 204 ? "" : await res.text();
+        }
+        catch (e) {
+            // A body that dies mid-stream is a retryable network fault (exit 3), not
+            // the raw TypeError it surfaces as — the same wrap `parseResponse` has.
+            throw new NetworkError(e, res.url || undefined);
+        }
         const parsed = text ? safeJson(text) : undefined;
         const body = parsed === null && text ? undefined : parsed;
         if (!res.ok)
             throw buildApiError(res, body ?? {});
         return { status: res.status, headers, body, text };
     }
+    /**
+     * 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.
+     */
+    async uploadMultipart(path, file, field = "file") {
+        const bytes = await readFile(file.path);
+        const form = new FormData();
+        form.append(field, new Blob([bytes], { type: file.contentType }), file.filename);
+        return this.request("POST", path, { formData: form });
+    }
+    /**
+     * 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.
+     */
+    async download(path) {
+        const res = await this.dispatch("GET", path, {});
+        if (!res.ok) {
+            let text;
+            try {
+                text = res.status === 204 ? "" : await res.text();
+            }
+            catch (e) {
+                throw new NetworkError(e, res.url || undefined);
+            }
+            throw buildApiError(res, text ? (safeJson(text) ?? {}) : {});
+        }
+        let bytes;
+        try {
+            // Reading the attachment bytes can drop mid-stream too — a network
+            // fault (exit 3), not the raw TypeError it would otherwise surface as.
+            bytes = Buffer.from(await res.arrayBuffer());
+        }
+        catch (e) {
+            throw new NetworkError(e, res.url || undefined);
+        }
+        return {
+            bytes,
+            contentType: res.headers.get("content-type"),
+            filename: filenameFromContentDisposition(res.headers.get("content-disposition")),
+        };
+    }
     async dispatch(method, path, opts) {
         const auth = opts.auth ?? true;
+        const payload = opts.formData ?? opts.body;
         const headers = {
-            "Content-Type": "application/json",
             "User-Agent": `synteq-cli/${CLI_VERSION} node/${process.version}`,
+            // Let fetch set the multipart Content-Type (with boundary) for uploads.
+            ...(opts.formData ? {} : { "Content-Type": "application/json" }),
             ...(opts.headers ?? {}),
         };
         let refreshable = null;
@@ -112,7 +261,7 @@ export class ApiClient {
         const url = this.buildUrl(path, opts.query);
         let res;
         try {
-            res = await this.fetchImpl(url, await this.makeInit(method, headers, opts.body));
+            res = await this.fetchImpl(url, await this.makeInit(method, headers, payload, opts.rawBody));
         }
         catch (e) {
             throw new NetworkError(e, url);
@@ -123,12 +272,12 @@ export class ApiClient {
                 : "Stored API token rejected. Re-run `synteq login --with-token` with a valid key, or `synteq logout` to clear it.");
         }
         if (res.status === 401 && refreshable) {
-            const refreshed = await this.tryRefresh(refreshable);
+            const refreshed = await this.refreshTokens(refreshable);
             if (!refreshed)
                 throw new AuthExpiredError();
             headers["Authorization"] = `Bearer ${refreshed.access_token}`;
             try {
-                res = await this.fetchImpl(url, await this.makeInit(method, headers, opts.body));
+                res = await this.fetchImpl(url, await this.makeInit(method, headers, payload, opts.rawBody));
             }
             catch (e) {
                 throw new NetworkError(e, url);
@@ -138,6 +287,28 @@ export class ApiClient {
         }
         return res;
     }
+    /**
+     * 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.
+     */
+    refreshTokens(used) {
+        if (!this.refreshing) {
+            this.refreshing = (async () => {
+                const stored = await this.opts.tokens.read();
+                if (stored && stored.kind !== "api_key" && stored.access_token !== used.access_token) {
+                    return stored;
+                }
+                return this.tryRefresh(used);
+            })().finally(() => {
+                this.refreshing = null;
+            });
+        }
+        return this.refreshing;
+    }
     async tryRefresh(current) {
         let res;
         try {
@@ -188,11 +359,32 @@ export class ApiClient {
     async parseResponse(res) {
         if (res.status === 204)
             return undefined;
-        const text = await res.text();
+        // `fetch()` resolving only means the headers arrived — the body can still
+        // die mid-stream (a socket reset, a load balancer cycling). `dispatch`
+        // wraps the fetch call as a NetworkError but not this read, so an
+        // interrupted body surfaced as a raw `TypeError: terminated`: fatal to a
+        // long `deploy`/`function deploy` poll instead of the retryable network
+        // fault it is (`pollBuild`/`waitFor` keep polling through NetworkError).
+        let text;
+        try {
+            text = await res.text();
+        }
+        catch (e) {
+            throw new NetworkError(e, res.url || undefined);
+        }
         const body = text ? safeJson(text) : {};
-        if (res.ok)
-            return body;
-        throw buildApiError(res, body);
+        if (!res.ok)
+            throw buildApiError(res, body);
+        // A 2xx whose body is not JSON never came from the API (a proxy's HTML
+        // error page, a captive portal). Surfacing it as a network fault — exit
+        // 3, safe to retry — beats handing the caller `null` to read `.items`
+        // off. A literal `null` body is what a None-returning route answers and
+        // stays as-is.
+        if (body === null && text.trim() !== "null") {
+            const contentType = res.headers.get("content-type") ?? "no content-type";
+            throw new NetworkError(new Error(`non-JSON response (HTTP ${res.status}, ${contentType})`), res.url || undefined);
+        }
+        return body;
     }
     auth = {
         deviceCode: (client_id = "synteq-cli", scope = "cli") => this.request("POST", "/auth/device/code", {
@@ -211,6 +403,14 @@ export class ApiClient {
         whoami: () => this.request("GET", "/auth/me"),
         apiKeyWhoami: () => this.request("GET", "/organization/api-keys/whoami"),
         teams: () => this.request("GET", "/account/teams"),
+        /**
+         * 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: () => this.request("POST", "/auth/ws-ticket", { body: {} }),
     };
     projects = {
         list: () => this.request("GET", "/account/projects"),
@@ -221,51 +421,46 @@ export class ApiClient {
         remove: (keyId) => this.request("DELETE", `/account/ssh-keys/${keyId}`),
     };
     virtualized = {
-        list: (projectId) => this.request("GET", "/resources", {
+        /** GET /resources (50/200): `q` matches hostname / id / IP / location,
+         *  `kind` narrows to one virtualized kind server-side. */
+        listPage: (projectId, query = {}) => this.request("GET", "/resources", {
+            query: { per_page: LIST_PAGE_MAX, ...query },
             headers: projectId ? { "X-Project-Id": projectId } : undefined,
-        }),
+        }).then(asPage),
+        list: (projectId, query) => this.virtualized.listPage(projectId, query).then((p) => p.items),
         get: (resourceId) => this.request("GET", `/resources/${resourceId}`),
         stats: (resourceId, timeframe = "hour") => this.request("GET", `/virtualized/${resourceId}/stats`, { query: { timeframe } }),
         rrd: (resourceId, timeframe = "hour") => this.request("GET", `/virtualized/${resourceId}/rrd`, { query: { timeframe } }),
         bandwidth: (resourceId) => this.request("GET", `/virtualized/${resourceId}/bandwidth`),
     };
     transit = {
-        list: (projectId) => this.request("GET", "/transit/services", {
+        list: (projectId) => this.request("GET", `/transit/services?${PAGE_MAX}`, {
             headers: projectId ? { "X-Project-Id": projectId } : undefined,
-        }),
+        }).then(listItems),
     };
     storage = {
         // GET /storage was deleted (/resources unification) — volumes now come
         // from the generic kind-scoped list. Adapt rows back to the CLI's
         // StorageVolume shape at this single call site. No projectId → list the
         // whole team (?team=true), matching the old endpoint's breadth.
-        list: async (projectId) => {
-            const rows = await this.request("GET", "/resources/block_volume", projectId
-                ? { headers: { "X-Project-Id": projectId } }
-                : { query: { team: "true" } });
-            return rows
-                // Parity with the old /storage list: cancelled volumes are dead
-                // rows kept for audit, not customer-visible storage.
-                .filter((r) => r.status !== "cancelled")
-                .map((r) => ({
-                id: r.id,
-                name: r.name,
-                size_gb: r.size_gb,
-                status: r.status,
-                is_attached: r.status === "attached",
-                disk_slot: r.disk_slot,
-                monthly_price: r.monthly_price != null ? Number(r.monthly_price) : null,
-                attached_resource_id: r.resource_id,
-                attached_resource_hostname: r.attached_resource_hostname,
-                project_id: r.project_id,
-                project_name: r.project_name,
-                // BlockVolumeOut carries location_name only; nothing in the CLI
-                // consumes StorageVolume.location_id.
-                location_id: null,
-                location_name: r.location_name,
-                created_at: r.created_at,
+        /** GET /resources/block_volume (50/200): `q` matches name / id /
+         *  attached VM hostname. */
+        listPage: async (projectId, query = {}) => {
+            const page = asPage(await this.request("GET", "/resources/block_volume", {
+                query: { per_page: LIST_PAGE_MAX, ...query, ...(projectId ? {} : { team: "true" }) },
+                headers: projectId ? { "X-Project-Id": projectId } : undefined,
             }));
+            // Parity with the old /storage list: cancelled volumes are dead
+            // rows kept for audit, not customer-visible storage. They still
+            // count in the server's `total`, so take them off it too.
+            const live = page.items.filter((r) => r.status !== "cancelled");
+            return {
+                ...page,
+                total: Math.max(live.length, page.total - (page.items.length - live.length)),
+                items: live.map(storageVolumeFromRow),
+            };
         },
+        list: (projectId, query) => this.storage.listPage(projectId, query).then((p) => p.items),
         catalog: () => this.request("GET", "/public/storage/catalog", { auth: false }),
         // POST /block-volumes was deleted (/resources unification) — standalone
         // volume creation now rides the generic /orders surface
@@ -327,6 +522,10 @@ export class ApiClient {
     };
     payments = {
         methods: () => this.request("GET", "/payments/methods"),
+        /** 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) => this.request("GET", `/payments/touchpoints/${encodeURIComponent(touchpoint)}/payment-methods`),
         topup: (body) => this.request("POST", "/payments/credits/topup", { body }),
         setDefaultMethod: (methodId) => this.request("POST", `/payments/methods/${methodId}/set-default`),
         deleteMethod: (methodId) => this.request("DELETE", `/payments/methods/${methodId}`),
@@ -350,6 +549,7 @@ export class ApiClient {
         list: (resourceId) => this.request("GET", `/virtualized/${resourceId}/addons`),
         pending: (resourceId) => this.request("GET", `/virtualized/${resourceId}/pending-addons`),
         attach: (resourceId, body) => this.request("POST", `/virtualized/${resourceId}/addons`, { body }),
+        quote: (resourceId, body) => this.request("POST", `/virtualized/${resourceId}/addons/quote`, { body }),
     };
     projectActivity = {
         list: (projectId, limit = 25, offset = 0) => this.request("GET", `/projects/${projectId}/activity`, {
@@ -361,6 +561,9 @@ export class ApiClient {
         // Single-spec fit at one location — returns {available, reason?, max_fittable?}.
         // The backend defaults `kind` to "vps"; pass explicitly when probing a VDS /
         // GPU Cloud / Instant Metal custom spec so the right node pool is used.
+        // `max_fittable` is entitlement-clamped server-side: null whenever the
+        // caller's entitled quantity fits (always, for anon calls) — treat it as
+        // advisory, never as an inventory count.
         validate: (body) => this.request("POST", "/public/order/validate", { body, auth: false }),
         // Customer order surface is /orders + /orders/batch + /orders/{id}
         // (kind-dispatched, spec/payment wrapper, N-independent-specs batch,
@@ -386,6 +589,69 @@ export class ApiClient {
             const out = await this.request("GET", `/orders/${orderId}`);
             return genericOrderOutToStatusOut(out);
         },
+        // Price a {kind, spec} without creating an order — used by the
+        // vps/order, storage/order and baremetal/order wizards to show a
+        // tax-inclusive total before the "Submit order?" confirm. Read-only,
+        // rate-limited server-side. Callers MUST wrap this in try/catch and
+        // fall back to the net estimate — a preview failure (Numeral outage,
+        // rate limit) must never block ordering.
+        preview: (body) => this.request("POST", "/orders/preview", { body }),
+        /** 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, payment) => this.request("POST", "/orders", { body: { kind: "app", spec, payment } }),
+    };
+    // ── Bare metal (ILA-managed physical servers) ─────────────────────────
+    // Separate resource family from /resources + /virtualized (Instant Metal
+    // is a whole-node VM; this is a physical box). List/detail/invoices live
+    // on /baremetal/*; lifecycle (power/jobs/install-password/reinstall) on
+    // the same prefix via baremetal_ila.py — ILA-backed, no Proxmox involved.
+    baremetal = {
+        /** GET /baremetal (50/200): `q` matches hostname / reference / primary
+         *  IP / id. */
+        listPage: (query = {}) => this.request("GET", "/baremetal", {
+            query: { per_page: LIST_PAGE_MAX, ...query },
+        }).then(asPage),
+        list: (query) => this.baremetal.listPage(query).then((p) => p.items),
+        get: (serviceId) => this.request("GET", `/baremetal/${serviceId}`),
+        invoices: (serviceId) => this.request("GET", `/baremetal/${serviceId}/invoices`),
+        // Dedicated routes, NOT the generic /resources/{id}/activity or
+        // /virtualized/{id}/bandwidth — those resolve via get_owned_resource_any
+        // (virtualized/block_volume only) and would 404 a baremetal service id.
+        // See backend/app/routers/customer/resource_activity.py's
+        // list_baremetal_activity and bandwidth.py's baremetal_bandwidth.
+        activity: (serviceId, limit = 25, offset = 0) => this.request("GET", `/baremetal/${serviceId}/activity`, {
+            query: { limit, offset },
+        }),
+        bandwidth: (serviceId) => this.request("GET", `/baremetal/${serviceId}/bandwidth`),
+        powerState: (serviceId) => this.request("GET", `/baremetal/${serviceId}/power`),
+        power: (serviceId, action) => this.request("POST", `/baremetal/${serviceId}/power`, {
+            body: { action },
+        }),
+        installProfiles: (serviceId) => this.request("GET", `/baremetal/${serviceId}/install-profiles`),
+        jobs: (serviceId) => this.request("GET", `/baremetal/${serviceId}/jobs`),
+        jobEvents: (serviceId, jobId) => this.request("GET", `/baremetal/${serviceId}/jobs/${jobId}/events`),
+        cancelJob: (serviceId, jobId) => this.request("POST", `/baremetal/${serviceId}/jobs/${jobId}/cancel`),
+        reinstall: (serviceId, body) => this.request("POST", `/baremetal/${serviceId}/reinstall`, { body }),
+        installPasswordStatus: (serviceId) => this.request("GET", `/baremetal/${serviceId}/install-password`),
+        revealInstallPassword: (serviceId) => this.request("POST", `/baremetal/${serviceId}/install-password/reveal`),
+        // Public catalog — unauthenticated, groups sellable offerings by
+        // location. The common case is an empty list (build-to-order product);
+        // `baremetal order` uses this to decide whether there's a self-serve
+        // path at all before touching /orders.
+        catalog: () => this.request("GET", "/public/baremetal/catalog", { auth: false }),
+        installProfilesForOffering: (offeringId) => this.request("GET", `/public/baremetal/offerings/${offeringId}/install-profiles`, { auth: false }),
+        // POST /orders {kind:"baremetal", spec:{...}} — adapt to the same
+        // generic /orders wrapper the virtualized/storage adapters use above,
+        // so order.ts keeps a flat BaremetalOrderSpec + payment pair.
+        order: async (spec, payment, projectId) => {
+            const specBody = { ...spec };
+            const out = await this.request("POST", "/orders", {
+                body: { kind: "baremetal", spec: specBody, payment },
+                headers: projectId ? { "X-Project-Id": projectId } : undefined,
+            });
+            return genericCreateOutToOrderResult(out);
+        },
     };
     teams = {
         details: (teamId) => this.request("GET", `/account/teams/${teamId}/details`),
@@ -393,15 +659,238 @@ export class ApiClient {
     };
     tickets = {
         departments: () => this.request("GET", "/tickets/departments"),
-        list: () => this.request("GET", "/tickets"),
+        /** 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 = {}) => this.request("GET", "/tickets", {
+            query: { per_page: TICKET_PAGE_MAX, ...query },
+        }).then(asPage),
+        list: (query) => this.tickets.listPage(query).then((p) => p.items),
         get: (ticketId) => this.request("GET", `/tickets/${ticketId}`),
         messages: (ticketId) => this.request("GET", `/tickets/${ticketId}/messages`),
         create: (body) => this.request("POST", "/tickets", { body }),
         reply: (ticketId, body) => this.request("POST", `/tickets/${ticketId}/messages`, { body }),
+        uploadAttachment: (ticketId, messageId, file) => this.uploadMultipart(`/tickets/${ticketId}/messages/${messageId}/attachments`, file),
+        downloadAttachment: (ticketId, messageId, attachmentId) => this.download(`/tickets/${ticketId}/messages/${messageId}/attachments/${attachmentId}`),
         setStatus: (ticketId, status) => this.request("PATCH", `/tickets/${ticketId}/status`, {
             body: { status },
         }),
     };
+    /**
+     * 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: () => this.request("GET", "/apps-plans"),
+        /** 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: () => this.request("GET", "/apps/locations"),
+        /** GET /apps (50/200): `q` matches name / slug / hostname. */
+        listPage: (projectId, query = {}) => this.request("GET", "/apps", {
+            query: { per_page: LIST_PAGE_MAX, ...query },
+            headers: projectId ? { "X-Project-Id": projectId } : undefined,
+        }).then(asPage),
+        list: (projectId, query) => this.apps.listPage(projectId, query).then((p) => p.items),
+        get: (appId) => this.request("GET", `/apps/${appId}`),
+        /** Apps deploying from a GitHub repo, across every team the user is in. */
+        findByRepo: (repo) => this.request("GET", `/apps/by-repo?repo=${encodeURIComponent(repo)}`),
+        checkName: (slug) => this.request("POST", "/apps/check-name", { body: { slug } }),
+        create: (body, projectId) => this.request("POST", "/apps", {
+            body,
+            headers: projectId ? { "X-Project-Id": projectId } : undefined,
+        }),
+        deploy: (appId, body) => this.request("POST", `/apps/${appId}/deploys`, { body }),
+        /** 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, tarball) => this.request("POST", `/apps/${appId}/deploys/source`, {
+            rawBody: tarball,
+            headers: { "Content-Type": "application/gzip" },
+        }),
+        /** 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, body) => this.request("POST", `/apps/${appId}/deploys/source/upload-url`, { body }),
+        /** Trigger the build from an object already PUT to the URL
+         *  `sourceUploadUrl` minted — the counterpart to `deploySource` for the
+         *  direct-upload path. */
+        deploySourceObject: (appId, objectKey) => this.request("POST", `/apps/${appId}/deploys/source`, {
+            body: { sourceObjectKey: objectKey },
+        }),
+        builds: (appId) => this.request("GET", `/apps/${appId}/builds?${PAGE_MAX}`).then(listItems),
+        /** GET /apps/{id}/releases (50/200), ordered by number desc. */
+        releasesPage: (appId, query = {}) => this.request("GET", `/apps/${appId}/releases`, {
+            query: { per_page: LIST_PAGE_MAX, ...query },
+        }).then(asPage),
+        releases: (appId) => this.apps.releasesPage(appId).then((p) => p.items),
+        env: (appId) => this.request("GET", `/apps/${appId}/env`),
+        setEnv: (appId, body) => this.request("PUT", `/apps/${appId}/env`, { body }),
+        /** "Roll out now": push the saved env and redeploy the current release. */
+        rolloutEnv: (appId) => this.request("POST", `/apps/${appId}/env/rollout`, { body: {} }),
+        /** GitHub push-to-deploy link. GET returns null when nothing is linked. */
+        githubLink: (appId) => this.request("GET", `/apps/${appId}/github/link`),
+        linkGithub: (appId, body) => this.request("POST", `/apps/${appId}/github/link`, { body }),
+        unlinkGithub: (appId) => this.request("DELETE", `/apps/${appId}/github/link`),
+        // --- env: reveal + delete (set/list are above) ---
+        revealEnv: (appId, key) => this.request("POST", `/apps/${appId}/env/${encodeURIComponent(key)}/reveal`),
+        deleteEnv: (appId, key) => this.request("DELETE", `/apps/${appId}/env/${encodeURIComponent(key)}`),
+        // --- deploy history detail ---
+        buildDetail: (appId, buildId) => this.request("GET", `/apps/${appId}/builds/${buildId}`),
+        // --- logs: bounded history/search (live tail is the WS in logs.ts) ---
+        /** `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, opts = {}) => {
+            const q = new URLSearchParams();
+            if (opts.from)
+                q.set("from", opts.from);
+            else if (opts.since)
+                q.set("since", opts.since);
+            if (opts.until)
+                q.set("until", opts.until);
+            if (opts.container)
+                q.set("container", opts.container);
+            if (opts.search)
+                q.set("search", opts.search);
+            if (opts.limit != null)
+                q.set("limit", String(opts.limit));
+            const qs = q.toString();
+            return this.request("GET", `/apps/${appId}/logs/history${qs ? `?${qs}` : ""}`);
+        },
+        // --- metrics: usage series + live current + plan envelope ---
+        /** `range` (15m/1h/6h/24h/72h/168h) shapes the series; `since`+`until`
+         *  (ISO, together) pick an explicit window instead. */
+        usage: (appId, opts = {}) => {
+            const q = new URLSearchParams();
+            if (opts.range)
+                q.set("range", opts.range);
+            if (opts.since)
+                q.set("since", opts.since);
+            if (opts.until)
+                q.set("until", opts.until);
+            const qs = q.toString();
+            return this.request("GET", `/apps/${appId}/usage${qs ? `?${qs}` : ""}`);
+        },
+        // --- rollback: re-deploy an earlier release's image (mints a new release) ---
+        rollback: (appId, toRelease) => this.request("POST", `/apps/${appId}/rollback`, { body: { toRelease } }),
+        // --- health ---
+        health: (appId) => this.request("GET", `/apps/${appId}/health-check`),
+        // --- domains (add/list/verify are all that exist server-side; delete added) ---
+        domains: (appId) => this.request("GET", `/apps/${appId}/domains`),
+        // The body key is `domain` (DomainAddIn) — it was `hostname`, which the
+        // API rejected with a 422 on every `app domain add`. `acceptFee` answers
+        // the 402 a priced tier returns for the first custom domain.
+        addDomain: (appId, domain, opts = {}) => this.request("POST", `/apps/${appId}/domains`, {
+            body: { domain, acceptFee: opts.acceptFee ?? false },
+        }),
+        verifyDomain: (appId, domainId) => this.request("POST", `/apps/${appId}/domains/${domainId}/verify`),
+        removeDomain: (appId, domainId) => this.request("DELETE", `/apps/${appId}/domains/${domainId}`),
+        // --- plan: preview + apply change ---
+        planPreview: (appId, planTier, schedule = "now") => this.request("GET", `/apps/${appId}/plan/preview?planTier=${encodeURIComponent(planTier)}&schedule=${schedule}`),
+        changePlan: (appId, body) => this.request("PATCH", `/apps/${appId}/plan`, { body }),
+        // --- settings: read + patch ---
+        settings: (appId) => this.request("GET", `/apps/${appId}/settings`),
+        patchSettings: (appId, body) => this.request("PATCH", `/apps/${appId}/settings`, { body }),
+    };
+    /**
+     * 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: () => this.request("GET", "/functions-plans").then((r) => r.plans),
+        locations: () => this.request("GET", "/functions-locations"),
+        /** 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, query = {}) => this.request("GET", "/functions", {
+            query: { per_page: LIST_PAGE_MAX, ...query },
+            headers: projectId ? { "X-Project-Id": projectId } : undefined,
+        }).then(asPage),
+        list: (projectId, query) => this.functions.listPage(projectId, query).then((p) => p.items),
+        get: (fnId) => this.request("GET", `/functions/${fnId}`),
+        checkName: (name) => this.request("POST", "/functions/check-name", { body: { name } }),
+        create: (body, projectId) => this.request("POST", "/functions", {
+            body,
+            headers: projectId ? { "X-Project-Id": projectId } : undefined,
+        }),
+        update: (fnId, body) => this.request("PATCH", `/functions/${fnId}`, { body }),
+        // Step-up gated: the customer's current password rides in the body.
+        delete: (fnId, passwordChallenge) => this.request("DELETE", `/functions/${fnId}`, { body: { password_challenge: passwordChallenge } }),
+        /** 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, files) => this.request("POST", `/functions/${fnId}/deploys/source`, { body: { files } }),
+        /** The same endpoint's tarball shape: no 32-file editor limit, only the
+         *  function's source caps. */
+        deployTarball: (fnId, tarball) => this.request("POST", `/functions/${fnId}/deploys/source`, {
+            body: { sourceB64: Buffer.from(tarball).toString("base64") },
+        }),
+        /** 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, imageRef) => this.request("POST", `/functions/${fnId}/deploys`, { body: { imageRef } }),
+        source: (fnId) => this.request("GET", `/functions/${fnId}/source`),
+        builds: (fnId) => this.request("GET", `/functions/${fnId}/builds?${PAGE_MAX}`).then(listItems),
+        build: (fnId, buildId) => this.request("GET", `/functions/${fnId}/builds/${buildId}`),
+        /** GET /functions/{id}/releases (50/200), ordered by number desc. */
+        releasesPage: (fnId, query = {}) => this.request("GET", `/functions/${fnId}/releases`, {
+            query: { per_page: LIST_PAGE_MAX, ...query },
+        }).then(asPage),
+        releases: (fnId) => this.functions.releasesPage(fnId).then((p) => p.items),
+        rollback: (fnId, toRelease) => this.request("POST", `/functions/${fnId}/rollback`, { body: { toRelease } }),
+        /** Per-invocation records, newest first. `before` is the opaque cursor
+         *  from the previous page's `nextBefore`. */
+        runs: (fnId, opts = {}) => {
+            const qs = new URLSearchParams();
+            if (opts.limit != null)
+                qs.set("limit", String(opts.limit));
+            if (opts.before)
+                qs.set("before", opts.before);
+            if (opts.status)
+                qs.set("status", opts.status);
+            if (opts.release != null)
+                qs.set("release", String(opts.release));
+            if (opts.q)
+                qs.set("q", opts.q);
+            const q = qs.toString();
+            return this.request("GET", `/functions/${fnId}/runs${q ? `?${q}` : ""}`);
+        },
+        env: (fnId) => this.request("GET", `/functions/${fnId}/env`),
+        setEnv: (fnId, body) => this.request("PUT", `/functions/${fnId}/env`, { body }),
+        /** "Roll out now": push the saved env and redeploy the current release. */
+        rolloutEnv: (fnId) => this.request("POST", `/functions/${fnId}/env/rollout`, { body: {} }),
+        deleteEnv: (fnId, key) => this.request("DELETE", `/functions/${fnId}/env/${encodeURIComponent(key)}`),
+        revealEnv: (fnId, key) => this.request("POST", `/functions/${fnId}/env/${encodeURIComponent(key)}/reveal`),
+        // --- cron triggers ---
+        cronTriggers: (fnId) => this.request("GET", `/functions/${fnId}/triggers/cron`),
+        createCronTrigger: (fnId, body) => this.request("POST", `/functions/${fnId}/triggers/cron`, { body }),
+        updateCronTrigger: (fnId, triggerId, body) => this.request("PATCH", `/functions/${fnId}/triggers/cron/${triggerId}`, { body }),
+        deleteCronTrigger: (fnId, triggerId) => this.request("DELETE", `/functions/${fnId}/triggers/cron/${triggerId}`),
+        runCronTrigger: (fnId, triggerId) => this.request("POST", `/functions/${fnId}/triggers/cron/${triggerId}/run`),
+        // --- run credits (the Billing tab's buy panel + auto-reload) ---
+        billing: (fnId) => this.request("GET", `/functions/${fnId}/billing`),
+        setCreditAutoReload: (fnId, body) => this.request("PUT", `/functions/${fnId}/credits/auto-reload`, { body }),
+        /** No per-function quote route exists: price from the billing view's
+         *  `creditRateUsd` (an estimate; tax lands on the invoice). */
+        purchaseCredits: (fnId, body) => this.request("POST", `/functions/${fnId}/credits/purchase`, { body }),
+        teamBilling: () => this.request("GET", "/functions-team-billing"),
+        setTeamCreditAutoReload: (body) => this.request("PUT", "/functions-team-credits/auto-reload", { body }),
+        quoteTeamCredits: (body) => this.request("POST", "/functions-team-credits/quote", { body }),
+        purchaseTeamCredits: (body) => this.request("POST", "/functions-team-credits/purchase", { body }),
+    };
 }
 /** Old `VirtualizedOrderIn.payment_kind` ("method"/"bitpay") + a `payment_method_id`
  *  that may or may not be set collapses two customer intents ("charge this
@@ -409,12 +898,19 @@ export class ApiClient {
  *  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. */
-function virtualizedOrderInToGenericSpecs(body) {
+// Exported so vps/order.ts's wizard can build the same {kind, spec} shape
+// for a POST /orders/preview call before the confirm prompt, without
+// duplicating the plan/tier/custom-spec branching here.
+export function virtualizedOrderInToGenericSpecs(body) {
     const sharedSpec = {
         project_id: body.project_id,
         location_id: body.location_id,
         image_id: body.image_id,
     };
+    // billing_cycle must ride inside each spec — the generic /orders body has no
+    // top-level cycle field. Dropping it here silently bills monthly (CLI-C1).
+    if (body.billing_cycle)
+        sharedSpec.billing_cycle = body.billing_cycle;
     if (body.plan_id) {
         sharedSpec.plan_id = body.plan_id;
     }
@@ -488,6 +984,23 @@ function safeJson(s) {
         return null;
     }
 }
+// Pull a suggested filename out of a Content-Disposition header. The RFC 5987
+// `filename*=UTF-8''…` form (percent-encoded) wins over a plain `filename=`.
+function filenameFromContentDisposition(value) {
+    if (!value)
+        return null;
+    const star = /filename\*=(?:UTF-8'')?([^;]+)/i.exec(value);
+    if (star) {
+        try {
+            return decodeURIComponent(star[1].trim().replace(/^"|"$/g, ""));
+        }
+        catch {
+            // Malformed encoding — fall back to the plain filename= form below.
+        }
+    }
+    const plain = /filename="?([^";]+)"?/i.exec(value);
+    return plain ? plain[1].trim() : null;
+}
 function buildApiError(res, body) {
     const requestId = res.headers.get("x-request-id") ?? undefined;
     const d = body?.detail;
@@ -525,7 +1038,9 @@ function buildApiError(res, body) {
             bmsg ??
                 (body && typeof body === "object" && Object.keys(body).length
                     ? JSON.stringify(body)
-                    : `HTTP ${res.status}`);
+                    : res.status === 413
+                        ? "Upload rejected as too large before it reached the API (HTTP 413). Exclude build output (.next, dist, node_modules) or check your plan's source cap with `synteq apps plans`."
+                        : `HTTP ${res.status}`);
     }
     const code = typeof d === "object" && d ? d.error ?? "error" : "error";
     return new ApiError(res.status, code, detail, requestId);