unfazed 0.6.1 → 0.8.1

package/dist/unfazed.d.ts

@@ -1,5 +1,5 @@
 import { UnfazedClient, type ClientOptions, type RequestOptions } from "./client.js";
-import type { CreateDeploymentInput, DeploymentFieldsFragment, ListDeploymentsInput, RunFieldsFragment, RunStatus, ServiceMode, ServiceRuntime, SdkCreateWorkspaceMutation, SdkRunHarnessesQuery } from "./generated/graphql.js";
+import type { AppErrorGroupFieldsFragment, CreateDeploymentInput, DeploymentEventType, DeploymentFieldsFragment, FileCommitFieldsFragment, ListDeploymentsInput, RunFieldsFragment, RunStatus, ServiceMode, ServiceRuntime, SdkAppCommitQuery, SdkAppCommitsQuery, SdkAppErrorGroupQuery, SdkAppErrorsQuery, SdkCreateWorkspaceMutation, SdkDeleteAppMutation, SdkDeploymentEventsQuery, SdkEventTypesQuery, SdkPollEventsQuery, SdkRestoreVersionMutation, SdkRunHarnessesQuery, SdkWorkspaceLiveAppsQuery } from "./generated/graphql.js";
 import { type WaitOptions } from "./wait.js";
 /** A deployment as the workflow layer returns it. */
 export type Deployment = DeploymentFieldsFragment;
@@ -17,16 +17,58 @@ export type RunHarness = SdkRunHarnessesQuery["runHarnesses"][number];
  * a listed or a freshly created workspace under one type.
  */
 export type Workspace = SdkCreateWorkspaceMutation["createWorkspace"]["workspace"];
+/**
+ * An app a workspace serves right now, from {@link Unfazed.liveApps}: its
+ * alias, the deployment serving it, and the custom domains routing to it
+ * (listed for the app's owner only).
+ */
+export type LiveApp = NonNullable<SdkWorkspaceLiveAppsQuery["workspace"]>["liveApps"][number];
+/** What {@link Unfazed.deleteApp} removed, as the server reports it. */
+export type DeleteAppResult = SdkDeleteAppMutation["deleteApp"];
 /** Options for {@link Unfazed.deleteWorkspace}. */
-export type DeleteWorkspaceOptions = {
+export type DeleteWorkspaceOptions = ({
+    /**
+     * Omitted or `false`: delete the workspace only when it has no
+     * deployment records left. The server refuses otherwise, and deletes
+     * nothing.
+     */
+    withDeployments?: false;
+    /** Only with `withDeployments: true`. */
+    confirmAliases?: undefined;
+} | {
     /**
      * Also delete every deployment snapshotted from the workspace, stopping
-     * their service VMs. **Defaults to `true`** — see the method docs for why.
+     * its VMs. This takes EVERY app the workspace serves offline, so
+     * `confirmAliases` must name them.
      */
-    withDeployments?: boolean;
+    withDeployments: true;
+    /**
+     * Exactly the aliases of the apps the workspace serves
+     * ({@link Unfazed.liveApps}), in any order: every app this delete takes
+     * offline. `[]` when it serves none (only failed or retired records are
+     * left). A missing or extra alias makes the server refuse and delete
+     * nothing ({@link UnfazedUnconfirmedAppsError}). The SDK never fills
+     * this in for you.
+     */
+    confirmAliases: readonly string[];
+}) & {
     /** Resolve `false` instead of throwing when the workspace is not visible. */
     ignoreNotFound?: boolean;
 } & RequestOptions;
+/** The app {@link Unfazed.deleteApp} deletes. */
+export interface AppRef {
+    workspaceId: string;
+    /** The app's alias in that workspace. */
+    alias: string;
+}
+/** Options for {@link Unfazed.deleteApp}. */
+export type DeleteAppOptions = {
+    /**
+     * Resolve `null` instead of throwing when the app is not in the workspace
+     * (already deleted) or the workspace is not visible.
+     */
+    ignoreNotFound?: boolean;
+} & RequestOptions;
 /** Options for {@link Unfazed.deleteDeployment}. */
 export type DeleteDeploymentOptions = {
     /** Resolve `false` instead of throwing when the deployment is not visible. */
@@ -50,6 +92,239 @@ export interface EnvVar {
     masked: boolean;
     updatedAt: string;
 }
+/**
+ * The commit a write made on an app with platform git, exactly as MCP
+ * `write_workspace_files` reports it.
+ *
+ * The three states of a write: SAVED (the call returned: the app's files
+ * have it, and the next deploy uses it); COMMITTED (`committed && !waiting`:
+ * it is in the app's history, `listCommits`); DEPLOYED (a deploy of those
+ * files went READY: `deployService({ wait: true })`, or — only when
+ * `deploys` is true — the import of the branch head the write triggers).
+ *
+ * - `waiting: true` — saved, and the commit waits for the git server; it
+ *   lands in order. `sha` is null until then. Nothing to retry; await it with
+ *   {@link Unfazed.waitForCommit} (or `writeFiles(…, { waitForCommit: true })`).
+ * - `committed: false` — git already held exactly these files.
+ * - `conflicts` — a push changed the same paths meanwhile: the head (`sha`,
+ *   a merge) keeps the pushed version; yours is `writeSHA`.
+ * - `paused` — platform git is paused for recovery: saved, committed later.
+ */
+export type FileCommit = FileCommitFieldsFragment;
+/** One file's outcome in {@link Unfazed.writeFiles}, in the order given. */
+export interface FileWriteOutcome {
+    path: string;
+    ok: boolean;
+    /** Why this path was not written; null when it was. */
+    error: string | null;
+    /** The written file; null when it was not. */
+    file: WorkspaceFile | null;
+}
+/** What {@link Unfazed.writeFiles} wrote (MCP `write_workspace_files`' answer). */
+export interface WriteFilesResult {
+    workspaceId: string;
+    /** Every file's outcome, in the order of the map. */
+    files: FileWriteOutcome[];
+    written: number;
+    failed: number;
+    /** Bytes written (decoded). */
+    totalBytes: number;
+    /**
+     * The commit the call made on an app with platform git; null on any other
+     * app, and on a platform too old to report it. A map over one request's
+     * limits (100 files, 32 MiB) is several requests and several commits: this
+     * is the last, `commits` has them all.
+     */
+    commit: FileCommit | null;
+    /** One commit per request, in order. Usually exactly one. */
+    commits: FileCommit[];
+    /**
+     * With `waitForCommit`, when a commit was waiting: the branch head once
+     * every waiting write had landed (this write is in its history).
+     */
+    landed?: CommitsLanded;
+}
+/** A single-file write's answer: the file, and the commit it made. */
+export type WrittenFile = WorkspaceFile & {
+    commit: FileCommit | null;
+};
+/** What {@link Unfazed.waitForCommit} saw once no write was waiting. */
+export interface CommitsLanded {
+    branch: string;
+    /** The branch head: every write made before the wait is in its history. */
+    head: string | null;
+    /** How long the wait took, in ms. */
+    waitedMs: number;
+}
+/** One page of an app's platform git history ({@link Unfazed.listCommits}). */
+export type CommitPage = SdkAppCommitsQuery["appCommits"];
+/** One commit with its diff ({@link Unfazed.getCommit}). */
+export type CommitDetail = SdkAppCommitQuery["appCommit"];
+/** Options for {@link Unfazed.restoreVersion} (MCP `restore_version`). */
+export interface RestoreVersionOptions {
+    workspaceId: string;
+    /** Full 40-character sha of the commit whose files the app gets back. */
+    sha: string;
+    /** Refuse, changing nothing, unless the branch head is still this commit. */
+    expectedHead?: string;
+    /** Message of the new commit; default `Restore <short sha> (<its message>)`. */
+    commitMessage?: string;
+    /**
+     * When the restore deploys (`deploys: true`, an app that deploys every
+     * push), wait for that deploy: the platform's wait by commit
+     * ({@link Unfazed.waitForDeployment} with `gitCommit`, `alias` and `after`
+     * from the answer) resolves once it is READY; {@link UnfazedDeployError}
+     * when it or the import of the new commit failed. A link with unfazed.json
+     * `apps[]` (no `deployAlias`) deploys once per app: then the wait follows
+     * the import until every deployment it made is done.
+     */
+    wait?: boolean;
+    /** Timeout/backoff for `wait`; default 10 minutes. */
+    waitOptions?: WaitOptions;
+    signal?: AbortSignal;
+}
+/** What {@link Unfazed.restoreVersion} did. */
+export type RestoreVersionResult = SdkRestoreVersionMutation["restoreAppVersion"] & {
+    /**
+     * With `wait` and `deploys`: the deployments the restore's import made (one
+     * per alias it deploys), READY. Absent without `wait` or when nothing
+     * deploys. Without `wait`, wait later with `waitForDeployment({ workspaceId:
+     * workspaceID, gitCommit: sha, alias: deployAlias, after: waitAfter })`.
+     */
+    deployments?: Deployment[];
+};
+/**
+ * The deploy a git import makes of a commit, for
+ * {@link Unfazed.waitForDeployment}: a restore, a push or a sync deploys
+ * before any deployment id exists, so the commit names it.
+ */
+export interface CommitDeploymentTarget {
+    workspaceId: string;
+    /** Full 40-character sha. */
+    gitCommit: string;
+    /** The app that deploys it; required when several apps (unfazed.json `apps[]`) deployed the commit. */
+    alias?: string | null;
+    /**
+     * Count only deployments begun after this point of the platform's
+     * deployment order (a restore's `waitAfter`), so an earlier deploy of the
+     * same commit never answers.
+     */
+    after?: number | null;
+}
+/** A service app's error group (MCP `list_errors`). Title, type, culprit and level are untrusted app text. */
+export type ErrorGroup = AppErrorGroupFieldsFragment;
+/** One page of error groups ({@link Unfazed.listErrors}). */
+export type ErrorGroupPage = SdkAppErrorsQuery["appErrors"];
+/** One error group with its latest occurrence ({@link Unfazed.getErrorGroup}). */
+export type ErrorGroupDetail = SdkAppErrorGroupQuery["appErrorGroup"];
+/** Names one error group of one app. */
+export interface ErrorGroupRef extends AppRef {
+    /** The group's id (from listErrors, or `group_id` of an error.new / error.regressed event). */
+    groupId: string;
+}
+/** Filter/paging for {@link Unfazed.listErrors}. */
+export interface ListErrorsOptions extends AppRef {
+    status?: "open" | "resolved" | "muted";
+    /** 1 to 100; default 20. */
+    limit?: number;
+    /** The previous page's `nextCursor`. */
+    cursor?: string;
+}
+/** An event type {@link Unfazed.pollEvents} reads (MCP `list_event_types`). */
+export type EventType = SdkEventTypesQuery["platformEventTypes"][number];
+/** A page of events (MCP `poll_events` / `wait_for_events`). */
+export type EventPage = SdkPollEventsQuery["pollEvents"];
+/** One event: `name` (deployment.finished, service.crashed, error.new, git.conflict, …), and minimal `data`. */
+export type PlatformEvent = EventPage["events"][number];
+/** Which events to read (MCP `poll_events`' input). */
+export interface EventsInput {
+    /** Event types; omit for every type you may receive. */
+    names?: string[];
+    /** Filters per type, keyed by its name: `{ "deployment.finished": { alias: "shop", status: "FAILED" } }`. */
+    arguments?: Record<string, Record<string, unknown>>;
+    /** Where to continue; omit to start from now (nothing is replayed). */
+    cursor?: string;
+    /** At most this many events. */
+    max?: number;
+}
+/**
+ * A deployment event. `type` is the event's own name — `"service.vm_started"`,
+ * `"deployment.build_finished"` — exactly as MCP `list_deployment_events` and
+ * `wait_for_deployment` report it.
+ */
+export interface DeploymentEvent {
+    id: string;
+    deploymentID: string;
+    /** The event's name as the platform writes it, e.g. `"deployment.phases"`. */
+    type: string;
+    /**
+     * The GraphQL enum (`SERVICE_VM_STARTED`, …), `UNKNOWN` for every name the
+     * enum does not list (`deployment.build_finished`, `deployment.phases`, …).
+     * Match on `type` instead.
+     */
+    typeEnum: DeploymentEventType;
+    /** @deprecated Same as `type` (before 0.8.0 `type` was the enum). */
+    rawType: string;
+    severity: SdkDeploymentEventsQuery["deploymentEvents"][number]["severity"];
+    message: string;
+    vmID: string | null;
+    /** The event's fields; timing events carry their phases as `*_ms` strings. */
+    metadata: Record<string, string> | null;
+    /**
+     * What a timing event (`deployment.build_finished`, `deployment.phases`)
+     * measured, as the platform parsed it; null for any other event.
+     * {@link parseDeploymentTimings} prefers it to `metadata`.
+     */
+    timings: PlatformTimings | null;
+    createdAt: string;
+}
+/**
+ * A deploy's phases as the platform measured them: from `deployment.phases`
+ * (recorded when the deploy goes READY) and `deployment.build_finished`.
+ * Milliseconds.
+ */
+export interface PlatformTimings {
+    /** Deployment created → READY, on the platform's clock. Null until `deployment.phases` is recorded. */
+    totalMs: number | null;
+    /** The build, as the build VM's host measured it. */
+    buildMs: number | null;
+    /** Promotion: health probe and alias switch (and a worker's pickup and boot). */
+    promoteMs: number | null;
+    /**
+     * Every other measured phase by name: the build VM's (`vm_install`,
+     * `vm_build`, `vm_bundle`, `vm_collect`, `image`, `vm`, `return`,
+     * `extract`) and the promotion's (`admission`, `worker_pickup`, `boot`, …).
+     */
+    phases: Record<string, number>;
+    /** `local` or `worker`. */
+    buildMode: string | null;
+    artifactTransport: string | null;
+    buildMemoryMiB: number | null;
+}
+/** Wall time this client spent on a deploy with `wait: true`. Milliseconds. */
+export interface ClientTimings {
+    /** Sending createDeployment until its answer. */
+    createMs: number;
+    /** Its answer until the client saw the final status. */
+    waitMs: number;
+    /** `createMs + waitMs`: what the caller waited. Compare with `platform.totalMs`. */
+    totalMs: number;
+    /** Requests the wait made: one per server-side wait (up to 45 s each), or one per poll. */
+    waitRequests: number;
+    /** `"server"`: the platform's server-side wait; `"poll"`: polling (platforms without it). */
+    waitMode: "server" | "poll";
+}
+/** Both sides of a deploy's time ({@link DeployResult.timings}). */
+export interface DeployTimings {
+    client: ClientTimings;
+    /** Null when the platform recorded none (yet), or with `timings: false`. */
+    platform: PlatformTimings | null;
+}
+/** A deploy's answer: the deployment, and with `wait: true` its timings. */
+export type DeployResult = Deployment & {
+    /** With `wait: true`: the platform's phases and this client's wall time. */
+    timings?: DeployTimings;
+};
 /**
  * A file's contents for {@link Unfazed.writeFiles}.
  *
@@ -68,16 +343,31 @@ export type FileContent = string | {
 export type FilesMap = Record<string, FileContent>;
 export interface WriteFilesOptions {
     /**
-     * Max files per GraphQL request. Default 20.
-     *
-     * The batch is one document with N aliased root fields; too many at once
-     * makes a single oversized request whose failure is all-or-nothing to
-     * diagnose. Twenty keeps a typical app to one or two round trips.
+     * On an app with platform git: the message of the call's commit. Default
+     * names the files. Ignored on other apps.
+     */
+    commitMessage?: string;
+    /**
+     * When the commit waits for the git server (`commit.waiting`), resolve only
+     * once it landed ({@link Unfazed.waitForCommit}); `true` or the wait's
+     * options. The result's `landed` names the branch head then.
+     */
+    waitForCommit?: boolean | WaitOptions;
+    /**
+     * Resolve with the result even when some files failed, instead of throwing
+     * {@link UnfazedWriteError}. Read `failed` and `files[].error` then.
+     */
+    allowPartial?: boolean;
+    /**
+     * Max files per request. Default 100, the platform's per-call limit. A
+     * request is ONE commit on an app with platform git, so a map that needs
+     * several requests is several commits.
      */
     batchSize?: number;
     /**
-     * Max total payload bytes per request. Default 4 MiB. Whichever limit trips
-     * first closes the batch, so one large file cannot blow the request up.
+     * Max payload bytes per request (text, or base64 as sent). Default 32 MiB,
+     * the platform's per-call total. Whichever limit trips first closes a
+     * request; a single file over it is still sent, and refused on its own.
      */
     maxBatchBytes?: number;
     signal?: AbortSignal;
@@ -97,6 +387,12 @@ export interface DeployOptions {
     wait?: boolean;
     /** Backoff/timeout knobs used when `wait` is true. */
     waitOptions?: WaitOptions;
+    /**
+     * With `wait: true`, read the platform's phase timings once the deploy is
+     * READY (one more request) into `result.timings.platform`. Default true;
+     * `false` skips the read (`timings.platform` is null).
+     */
+    timings?: boolean;
     signal?: AbortSignal;
 }
 export interface DeployServiceOptions extends DeployOptions {
@@ -115,7 +411,14 @@ export interface DeployStaticOptions extends DeployOptions {
     spaMode?: boolean;
 }
 export interface DeployBoxOptions extends DeployOptions {
-    /** VM size. Omit for platform defaults (2048 MiB / 2 vCPU / 8 GiB disk). */
+    /**
+     * VM size. Omit a field for the platform default; the server's
+     * `BoxResourcesInput` is authoritative. Today: 4096 MiB RAM (min 512, max
+     * 16384), 4 vCPU (max 16) and a 32 GiB disk (max 128), unless the platform
+     * operator raised the box's limit; a node may clamp lower. `diskGiB` sizes
+     * the disk when it is first created; a later redeploy asking for more grows
+     * it before the box boots, and it never shrinks.
+     */
     resources?: {
         memMiB?: number;
         vcpus?: number;
@@ -319,33 +622,98 @@ export declare class Unfazed {
         updatedAt: string;
     }[]>;
     /**
-     * Deletes a workspace and everything anchored to it — deployments, env, and
-     * a BOX's persistent data disk. Not recoverable.
+     * Deletes a workspace — its files, env and secrets, and a BOX's persistent
+     * data disk — and, with `withDeployments`, every app it serves.
      *
-     * **The cascade is opt-out, not opt-in.** The server refuses to delete a
-     * workspace that has ANY deployment history — including FAILED records, and
-     * including deployments whose alias was long since taken over by something
-     * else — unless the mutation carries `withDeployments`. Since almost every
-     * workspace an agent creates gets deployed at least once, defaulting to
-     * `false` would make this method fail on nearly every real workspace, so it
-     * defaults to **`true`**: the behaviour this docstring has always promised.
-     *
-     * Pass `withDeployments: false` for the strict variant, which refuses rather
-     * than cascading and is the safer choice when you are deleting a workspace
-     * you did not create:
+     * A workspace can serve several apps (each `unfazed.json` `apps[]` entry, or
+     * several aliases deployed into it), so deleting one with its deployments is
+     * never implicit: **name exactly the apps it takes offline** in
+     * `confirmAliases`. The server compares them with the workspace's live apps
+     * and refuses, deleting nothing, on a missing or extra alias; the refusal
+     * ({@link UnfazedUnconfirmedAppsError}) lists every live app with its
+     * domains. The SDK never fills the list in: look it up deliberately with
+     * {@link liveApps} and decide. To delete one app and keep the rest, use
+     * {@link deleteApp}.
      *
      * ```ts
-     * await unfazed.deleteWorkspace(ws.id);                            // cascade
-     * await unfazed.deleteWorkspace(ws.id, { withDeployments: false }); // refuse if deployed
-     * await unfazed.deleteWorkspace(id, { ignoreNotFound: true });      // false, not a throw
+     * await unfazed.deleteWorkspace(ws.id);   // only when no deployment is left
+     * await unfazed.deleteWorkspace(ws.id, { withDeployments: true, confirmAliases: ["web", "api"] });
+     * await unfazed.deleteWorkspace(ws.id, { withDeployments: true, confirmAliases: [] }); // serves no app
+     * await unfazed.deleteWorkspace(id, { ignoreNotFound: true });   // false, not a throw
      * ```
      *
+     * Without `withDeployments` the server refuses while ANY deployment record
+     * is left — FAILED ones included — with `still has deployments; delete them
+     * first`. A workspace whose deploys all failed serves no app: delete it with
+     * `withDeployments: true, confirmAliases: []`.
+     *
+     * What is deleted disappears at once — gone from your views, its names and
+     * aliases free, its VMs stopped — but the platform keeps it for 30 days:
+     * within that time support (the platform operator) can restore it exactly
+     * as it was. You cannot restore it yourself; ask support. After 30 days it
+     * is erased for good.
+     *
      * With `ignoreNotFound` a workspace that is absent (or belongs to someone
      * else — the server returns one indistinguishable sentinel for both, on
      * purpose) resolves to `false` instead of throwing, which makes teardown in
      * a `finally` block idempotent.
      */
     deleteWorkspace(workspaceId: string, options?: DeleteWorkspaceOptions): Promise<boolean>;
+    /**
+     * The apps a workspace serves right now, by alias, with the deployment
+     * serving each and its custom domains: everything
+     * `deleteWorkspace(id, { withDeployments: true, … })` takes offline, and the
+     * exact list its `confirmAliases` must name.
+     *
+     * It is a lookup for you to read, not something to pipe into a delete
+     * unseen: check that the apps are the ones you mean to take down.
+     *
+     * ```ts
+     * const live = await unfazed.liveApps(ws.id);   // [{ alias: "web", deploymentID, domains: [] }, …]
+     * ```
+     *
+     * Throws {@link UnfazedNotFoundError} when the workspace is absent or not
+     * visible to this token.
+     */
+    liveApps(workspaceId: string, options?: RequestOptions): Promise<LiveApp[]>;
+    /**
+     * Deletes ONE app of a workspace and nothing else: every deployment of the
+     * alias there (live release, retained releases, failed and building
+     * attempts — its VM stops, its URL and custom domains stop serving), its App
+     * State, its app-scoped env and secrets, and its integration bindings. The
+     * workspace, its files and defaults, its other apps (`otherApps` in the
+     * result) and a box's data disk stay.
+     *
+     * ```ts
+     * const gone = await unfazed.deleteApp({ workspaceId: ws.id, alias: "docs" });
+     * gone.deployments;   // records deleted
+     * gone.otherApps;     // the workspace's apps still serving, untouched
+     * ```
+     *
+     * In a git-linked workspace pushes and syncs skip the alias while
+     * `unfazed.json` `apps[]` still declares it (`skippedOnSync: true`): remove
+     * it from `apps[]`, or bring it back with the GraphQL `syncRepo` mutation's
+     * `restoreApps` (through {@link client}). The server refuses while a git
+     * import of the workspace runs. Owner only.
+     *
+     * What is deleted disappears at once, but the platform keeps the app for 30
+     * days: within that time support (the platform operator) can restore it
+     * exactly as it was. You cannot restore it yourself; ask support. After 30
+     * days it is erased for good. A custom domain's record stays with the alias,
+     * so a restored app serves it again.
+     *
+     * A delete that stops part-way throws with the server's message, which says
+     * so; deleting again finishes it. With `ignoreNotFound`, an app that is not
+     * in the workspace (already deleted) or a workspace that is not visible
+     * resolves to `null` instead of throwing.
+     */
+    deleteApp(app: AppRef, options: DeleteAppOptions & {
+        ignoreNotFound: true;
+    }): Promise<DeleteAppResult | null>;
+    deleteApp(app: AppRef, options?: DeleteAppOptions & {
+        ignoreNotFound?: false;
+    }): Promise<DeleteAppResult>;
+    deleteApp(app: AppRef, options?: DeleteAppOptions): Promise<DeleteAppResult | null>;
     /**
      * Returns the workspace named `name`, creating it only if it does not exist.
      *
@@ -371,33 +739,58 @@ export declare class Unfazed {
         updatedAt: string;
     }>;
     /**
-     * Writes many files in as few requests as possible.
-     *
-     * The API is one-file-per-mutation, so writing a 12-file app naively costs 12
-     * round trips. This batches them into a single GraphQL document with one
-     * ALIASED root field per file (`f0: writeWorkspaceTextFile(...)`,
-     * `f1: ...`), which the server resolves in one request.
+     * Writes many files in ONE request — and, on an app with platform git, ONE
+     * commit — exactly as MCP `write_workspace_files` does.
      *
      * ```ts
-     * await unfazed.writeFiles(ws.id, {
+     * const out = await unfazed.writeFiles(ws.id, {
      *   "server.ts": serverCode,
-     *   "unfazed.json": JSON.stringify({ entry: "server.ts" }),
+     *   "package.json": JSON.stringify(pkg),
      *   "public/logo.png": { bytes: pngBytes },
-     * });
+     * }, { commitMessage: "Add the server" });
+     * out.commit;   // { sha, committed, waiting, conflicts, writeSHA, … } or null
      * ```
      *
-     * Batches are NOT atomic: GraphQL resolves each aliased field independently,
-     * so a partial failure leaves earlier writes committed. The thrown
-     * {@link UnfazedGraphQLError} carries `data` with whichever aliases
-     * succeeded, and `error.path` identifies the ones that did not.
+     * A call is not transactional: files are written in order, each atomically,
+     * and a file's failure does not undo the others. When any file fails this
+     * throws {@link UnfazedWriteError} (its `result` lists what was written and
+     * `failed` what was not; retry only those), unless `allowPartial`. A
+     * repeated path keeps its last content.
+     *
+     * On an app with platform git the commit is made before any file is
+     * written: if it fails, the request fails and nothing is written. `commit`
+     * may come back `waiting` — the files are saved and the commit lands in
+     * order; pass `waitForCommit: true` (or call {@link waitForCommit}) to
+     * resolve only once it has. See {@link FileCommit} for saved, committed and
+     * deployed.
+     *
+     * One request carries up to 100 files and 32 MiB; a bigger map is split
+     * into several requests, each its own commit (`commits`). On a platform
+     * older than the batch write the SDK falls back to one mutation per file
+     * (one commit each) and reports `commit: null`.
+     */
+    writeFiles(workspaceId: string, files: FilesMap, options?: WriteFilesOptions): Promise<WriteFilesResult>;
+    /**
+     * Writes one text file: {@link writeFiles} with one entry, so it is one
+     * commit with `commitMessage` on an app with platform git, and the answer
+     * carries that commit. Throws {@link UnfazedWriteError} when it is refused.
      */
-    writeFiles(workspaceId: string, files: FilesMap, options?: WriteFilesOptions): Promise<WorkspaceFile[]>;
-    /** Writes one text file. Prefer {@link writeFiles} for more than one. */
-    writeFile(workspaceId: string, path: string, text: string, options?: RequestOptions): Promise<WorkspaceFile>;
-    /** Writes one binary file. Accepts raw bytes or a base64 string. */
+    writeFile(workspaceId: string, path: string, text: string, options?: Omit<WriteFilesOptions, "allowPartial" | "batchSize" | "maxBatchBytes">): Promise<WrittenFile>;
+    /** Writes one binary file (raw bytes or base64), like {@link writeFile}. */
     writeBinaryFile(workspaceId: string, path: string, content: Uint8Array | ArrayBuffer | {
         base64: string;
-    }, options?: RequestOptions): Promise<WorkspaceFile>;
+    }, options?: Omit<WriteFilesOptions, "allowPartial" | "batchSize" | "maxBatchBytes">): Promise<WrittenFile>;
+    /**
+     * Waits until no file write of the app waits for its commit: platform git
+     * commits a write at once, but when the git server is slow the write is
+     * saved and its commit `waiting`, landing in order. Resolves with the
+     * branch head then — every write made before the call is in its history.
+     * An app without platform git resolves at once (`head: null`).
+     *
+     * Default timeout 2 minutes; throws {@link UnfazedTimeoutError} past it
+     * (the writes stay saved, and still land).
+     */
+    waitForCommit(workspaceId: string, waitOptions?: WaitOptions): Promise<CommitsLanded>;
     /** Lists workspace files (paginated). */
     listFiles(workspaceId: string, input?: {
         limit?: number;
@@ -453,9 +846,9 @@ export declare class Unfazed {
      * takes over the alias when it goes READY. Omitting `alias` lets the server
      * generate one, which means a different app on every call.
      */
-    deployService(options: DeployServiceOptions): Promise<Deployment>;
+    deployService(options: DeployServiceOptions): Promise<DeployResult>;
     /** Deploys the workspace as a STATIC site. */
-    deployStatic(options: DeployStaticOptions): Promise<Deployment>;
+    deployStatic(options: DeployStaticOptions): Promise<DeployResult>;
     /**
      * Deploys a BOX: a persistent always-on Linux VM with a data disk that
      * survives stops and redeploys. A dev machine, not an HTTP service. The
@@ -480,19 +873,46 @@ export declare class Unfazed {
      * await unfazed.deployBox({ workspaceId: ws.id, alias: "dev" });   // re-runnable
      * ```
      */
-    deployBox(options: DeployBoxOptions): Promise<Deployment>;
+    deployBox(options: DeployBoxOptions): Promise<DeployResult>;
     /** Escape hatch: deploy with a raw CreateDeploymentInput. */
-    deploy(input: CreateDeploymentInput, options?: Omit<DeployOptions, "workspaceId">): Promise<Deployment>;
+    deploy(input: CreateDeploymentInput, options?: Omit<DeployOptions, "workspaceId">): Promise<DeployResult>;
     /**
-     * Polls a deployment until it is READY, throwing on FAILED or timeout.
+     * Waits until a deployment is READY, throwing {@link UnfazedDeployError} on
+     * FAILED or timeout (default 10 minutes).
+     *
+     * It waits SERVER-SIDE (MCP `wait_for_deployment`): each request blocks on
+     * the control plane until the deployment leaves BUILDING — woken by the
+     * deploy pipeline itself — or 45 s pass, and comes back with the full
+     * deployment; so READY reaches you one round trip after it happens, not at
+     * the next poll. A NEW app that starts directly on its server is READY
+     * before it serves there; the wait covers that landing too. On a platform
+     * without the server-side wait, or when the platform refuses one because
+     * the account already holds its cap of waits in progress (16), it polls
+     * instead (`waitOptions.mode: "poll"` forces that), every 0.5 s backing
+     * off to 3 s by default.
      *
-     * BUILDING is the only non-terminal status; READY and FAILED are terminal.
-     * The poll query selects six fields rather than the full deployment, because
-     * this runs every few seconds for potentially minutes — then the READY
-     * deployment is re-read in full so callers get the same shape `deployService`
-     * returns without `wait`.
+     * Pass a {@link CommitDeploymentTarget} instead of an id to wait for the
+     * deploy a git import makes of a commit — a restore, a push or a sync
+     * deploys before any id exists. The wait covers the import too, and
+     * {@link UnfazedDeployError} carries the import's error when it failed on
+     * the commit.
+     *
+     * ```ts
+     * const back = await unfazed.restoreVersion({ workspaceId: ws.id, sha });
+     * await unfazed.waitForDeployment({
+     *   workspaceId: back.workspaceID, gitCommit: back.sha, alias: back.deployAlias, after: back.waitAfter,
+     * });
+     * ```
      */
-    waitForDeployment(deploymentId: string, waitOptions?: WaitOptions): Promise<Deployment>;
+    waitForDeployment(target: string | CommitDeploymentTarget, waitOptions?: WaitOptions): Promise<Deployment>;
+    /**
+     * The platform's measured phases of a deploy ({@link PlatformTimings}), as
+     * it parses them from all of the deployment's timing events
+     * (`Deployment.timings`). Null when it recorded none (a deploy that is
+     * still building, or one from before timings existed), or for a deployment
+     * you cannot see.
+     */
+    getDeploymentTimings(deploymentId: string, options?: RequestOptions): Promise<PlatformTimings | null>;
     /** Reads one deployment by id. Null when absent. */
     getDeployment(deploymentId: string, options?: RequestOptions): Promise<Deployment | null>;
     /** Reads the deployment currently serving an alias. Null when absent. */
@@ -566,17 +986,23 @@ export declare class Unfazed {
         stderrBytes: number;
         tailBytes: number;
     }>;
-    /** Deployment lifecycle events — build, boot, probe, cron, restarts. */
-    getEvents(deploymentId: string, limit?: number, options?: RequestOptions): Promise<{
-        id: string;
-        deploymentID: string;
-        type: import("./index.js").DeploymentEventType;
-        rawType: string;
-        severity: import("./index.js").DeploymentEventSeverity;
-        message: string;
-        vmID: string | null;
-        createdAt: string;
-    }[]>;
+    /**
+     * Deployment lifecycle events — build, boot, probe, cron, restarts — the
+     * most recent `limit` (default 20), oldest first.
+     *
+     * `type` is the event's own name, as MCP reports it:
+     * `"deployment.build_finished"`, `"deployment.phases"`,
+     * `"service.vm_started"`, `"service.crashed"`. (`typeEnum` keeps the GraphQL
+     * enum, which reads `UNKNOWN` for names it does not list.) Timing events
+     * carry their phases in `metadata`; {@link getDeploymentTimings} turns them
+     * into numbers.
+     *
+     * ```ts
+     * const events = await unfazed.getEvents(app.id, 50);
+     * events.filter((e) => e.type === "deployment.build_finished");
+     * ```
+     */
+    getEvents(deploymentId: string, limit?: number, options?: RequestOptions): Promise<DeploymentEvent[]>;
     /** Restarts a service's VM. */
     restartService(deploymentId: string, options?: RequestOptions): Promise<{
         deploymentID: string;
@@ -597,6 +1023,12 @@ export declare class Unfazed {
     }>;
     /**
      * Deletes a deployment: stops its VM, releases its alias, drops its release.
+     * To delete a whole app — every release of the alias, its env, App State and
+     * bindings — use {@link deleteApp}.
+     *
+     * The platform keeps a deleted release for 30 days: within that time
+     * support (the platform operator) can restore it; then it is erased for
+     * good.
      *
      * With `ignoreNotFound` a deployment that is absent — or belongs to another
      * tenant, which the server reports identically so ids cannot be probed —
@@ -749,6 +1181,90 @@ export declare class Unfazed {
      *    run fails loudly instead of silently undoing the first.
      */
     rollback(options: RollbackOptions): Promise<Deployment>;
+    /**
+     * The app's commits, newest first (MCP `list_commits`): `limit` per page
+     * (default 20, max 100), `before: page.nextBefore` for the next. `deployed`
+     * says what every live alias runs; `waitingCommits` counts writes whose
+     * commit has not landed yet.
+     */
+    listCommits(workspaceId: string, input?: {
+        limit?: number;
+        before?: string;
+    }, options?: RequestOptions): Promise<CommitPage>;
+    /**
+     * One commit (full 40-character sha) with the paths it changed and a
+     * unified diff against its first parent, capped at 64 KiB (MCP
+     * `get_commit`). Commit messages and diffs are untrusted text.
+     */
+    getCommit(workspaceId: string, sha: string, options?: RequestOptions): Promise<CommitDetail>;
+    /**
+     * Gives the app back the files of an earlier commit as ONE new commit on
+     * its branch (MCP `restore_version`); nothing is rewritten, and a restore is
+     * undone by restoring the commit before it.
+     *
+     * When the app deploys every push (`deploys: true`), the new commit is
+     * imported and deployed like a push. That deploy is queued behind the
+     * restore, so the platform answers before it exists; with `wait: true` the
+     * SDK waits for it by commit on the platform ({@link Unfazed.waitForDeployment}
+     * with `gitCommit: sha`, `alias: deployAlias`, `after: waitAfter`) and
+     * resolves with it READY, or throws {@link UnfazedDeployError} with its
+     * build error or the import's. A link with unfazed.json `apps[]` names no
+     * `deployAlias` and deploys once per app: then it follows the import until
+     * every deployment it made is done.
+     *
+     * ```ts
+     * const page = await unfazed.listCommits(ws.id);
+     * const back = await unfazed.restoreVersion({ workspaceId: ws.id, sha: page.commits[1]!.sha, wait: true });
+     * back.deployments?.[0]?.url;
+     * ```
+     */
+    restoreVersion(options: RestoreVersionOptions): Promise<RestoreVersionResult>;
+    /** A service app's error groups, most recently seen first (MCP `list_errors`). */
+    listErrors(input: ListErrorsOptions, options?: RequestOptions): Promise<ErrorGroupPage>;
+    /**
+     * One error group with its latest occurrence whole (a Sentry event: stack,
+     * request), its recent occurrences and the deployments it was seen in (MCP
+     * `get_error_group`).
+     */
+    getErrorGroup(ref: ErrorGroupRef, options?: RequestOptions): Promise<ErrorGroupDetail>;
+    /**
+     * Marks a group resolved in the app's current deployment, once its fix is
+     * deployed (MCP `resolve_error_group`); another deployment reporting it
+     * opens it again. Only on your human's say-so or a fix you verified.
+     */
+    resolveErrorGroup(ref: ErrorGroupRef, options?: RequestOptions): Promise<ErrorGroup>;
+    /** Mutes an expected group: still counted, never regresses or notifies (MCP `mute_error_group`). */
+    muteErrorGroup(ref: ErrorGroupRef, options?: RequestOptions): Promise<ErrorGroup>;
+    /** Opens a resolved or muted group again (MCP `reopen_error_group`). */
+    reopenErrorGroup(ref: ErrorGroupRef, options?: RequestOptions): Promise<ErrorGroup>;
+    /** The event types, with each one's filters and payload schema (MCP `list_event_types`). */
+    listEventTypes(options?: RequestOptions): Promise<EventType[]>;
+    /**
+     * Events since `cursor` (MCP `poll_events`). Omit `cursor` to start from now
+     * — nothing is replayed — and pass the returned `cursor` back: at once while
+     * `hasMore`, otherwise after `nextPollMs`, or to {@link waitForEvents}.
+     * `truncated` means events may be missing: re-read state.
+     */
+    pollEvents(input?: EventsInput, options?: RequestOptions): Promise<EventPage>;
+    /**
+     * {@link pollEvents} that waits server-side until an event arrives (MCP
+     * `wait_for_events`), for up to `timeoutMs` (default 45 s; longer waits are
+     * several server waits of up to 45 s, continuing from each cursor). A
+     * timeout is not an error: the page has `timedOut: true`, no events and a
+     * cursor to wait again with. The platform caps an account's waits in
+     * progress (16, deploy waits included); past it this throws an error that
+     * `isTooManyWaits` recognizes: poll then.
+     *
+     * ```ts
+     * let page = await unfazed.pollEvents({ names: ["deployment.finished"] });   // from now
+     * page = await unfazed.waitForEvents({ names: ["deployment.finished"], cursor: page.cursor, timeoutMs: 120_000 });
+     * ```
+     */
+    waitForEvents(input?: EventsInput & {
+        timeoutMs?: number;
+    }, options?: RequestOptions & {
+        now?: () => number;
+    }): Promise<EventPage>;
     /**
      * Starts an agent run.
      *
@@ -936,3 +1452,18 @@ export declare class Unfazed {
         truncated: boolean;
     }>;
 }
+/** An event {@link parseDeploymentTimings} reads: `timings` when the platform parsed it, else `metadata`. */
+export type TimingEvent = Pick<DeploymentEvent, "type" | "metadata"> & {
+    timings?: PlatformTimings | null;
+};
+/**
+ * A deploy's phases from its events, as the platform reads them: the latest
+ * `deployment.phases` (written when it went READY: build, promotion and its
+ * split, total) over the latest `deployment.build_finished` (the build VM's
+ * own phases). It prefers the `timings` the platform parsed into each event
+ * ({@link Unfazed.getEvents} reads them); events without them (an older
+ * platform, events built by hand) are parsed from their `*_ms` metadata the
+ * same way. Durations are whole, non-negative milliseconds: anything else is
+ * dropped, as the platform drops it. Null when neither event is there.
+ */
+export declare function parseDeploymentTimings(events: readonly TimingEvent[]): PlatformTimings | null;