@shardflux/sdk 0.5.0 → 0.6.1

package/dist/templates.d.ts

@@ -1,12 +1,47 @@
 /**
- * Template registry and custom template builds over the application API (/v1).
- * Types are written by hand.
+ * Template registry, custom template builds, the version file tree and diff, and template dev mode (drafts and test
+ * instances) over the application API (/v1). Registry and build types are written by hand and checked against the
+ * generated contract in type-checks.ts; the Templates v2 types (contracts §19) alias the generated schemas.
  *
  * Publishing/archiving an organization template version is a browser-only
  * owner/admin action (it changes what `open` resolves for every project), so
  * it is not exposed here.
  */
-import type { ClientContext, Page } from './client.js';
+import type { components } from './generated/app-api.js';
+import type { ClientContext, Operation, Page, WaitOptions } from './client.js';
+import type { ToolName } from './tokens.js';
+import { Workspace } from './workspace.js';
+type S = components['schemas'];
+/** Manifest v2 `defaults` of a version (contracts §19.7). */
+export type TemplateDefaults = S['TemplateDefaults'];
+/** How a version was produced: a recipe build, a saved workspace (or draft publish), or git (reserved). */
+export type TemplateSource = S['TemplateSource'];
+/** The version's file list state (the tree and diff routes read it). */
+export type TemplateFilesSummary = S['TemplateFilesSummary'];
+/** Storage of a template version (contracts §19.13). */
+export type TemplateStorage = S['TemplateStorage'];
+export type TemplateStorageWarning = S['TemplateStorageWarning'];
+/** Template storage of an organization (counts toward retained_state_gib). */
+export type OrgTemplateStorage = S['OrgTemplateStorage'];
+/** One inode path of a template version (contracts §19.10). */
+export type TemplateFileEntry = S['TemplateFileEntry'];
+/** One directory level of a version's tree (keyset-paginated). */
+export type TemplateFilePage = S['TemplateFilePage'];
+/** One path of a version diff: added | removed | changed | type_changed | metadata. */
+export type TemplateDiffEntry = S['TemplateDiffEntry'];
+export type TemplateDiffChange = TemplateDiffEntry['change'];
+/** One page of a version diff; the first page (no cursor) carries `summary`. */
+export type TemplateDiffPage = S['TemplateDiffPage'];
+/** The live draft of an organization template (contracts §19.9). */
+export type TemplateDraft = S['TemplateDraft'];
+/** A disk-only capture of the draft (a test instance or a publish starts from one). */
+export type DraftState = S['DraftState'];
+export type CreateDraftBody = S['CreateDraftBody'];
+export type CreateTestInstanceBody = S['CreateTestInstanceBody'];
+export type PublishDraftBody = S['PublishDraftBody'];
+export type SaveAsTemplateBody = S['SaveAsTemplateBody'];
+/** Defaults of a version produced by save-as-template or a draft publish (omitted fields: persistent, platform idle timeout, no limits). */
+export type TemplateDefaultsInput = NonNullable<SaveAsTemplateBody['defaults']>;
 export type TemplateOwner = 'platform' | 'organization';
 export type TemplateVersionState = 'unpublished' | 'published' | 'archived';
 export type CeilingSource = 'template' | 'user' | 'plan';
@@ -76,6 +111,42 @@ export interface TemplateVersion {
     }>;
     build_id: string | null;
     publishable: boolean;
+    /** `shardflux.template.v1` or `shardflux.template.v2` (Templates v2). */
+    manifest_schema: string | null;
+    /** Layouts a new workspace of this version may use (a manifest without the field: legacy only). */
+    disk_layouts: Array<'legacy' | 'layered'>;
+    source: TemplateSource | null;
+    /** The platform base (or parent) the version was built on. */
+    base: {
+        name: string;
+        version: string;
+        manifest_sha256: string | null;
+        rootfs_sha256: string | null;
+    } | null;
+    defaults: TemplateDefaults;
+    /** The file list the tree and diff read (`loaded` when files() and diff() can answer). */
+    files: TemplateFilesSummary;
+    rootfs_bytes: number | null;
+    /** The org layers of this version's chain, bottom to top (empty for images). */
+    chain: Array<{
+        layer_id: string;
+        bytes: number;
+        introduced_in_version: number | null;
+    }>;
+    storage: TemplateStorage;
+}
+/** Summary of an organization template's live draft on the template view (null when none). */
+export interface TemplateDraftSummary {
+    workspace_id: string;
+    workspace_key: string;
+    observed_state: string;
+    base_version: {
+        id: string;
+        template_id: string;
+        slug: string;
+        version: number;
+    };
+    created_at: string;
 }
 export interface TemplateSummary {
     id: string;
@@ -86,7 +157,16 @@ export interface TemplateSummary {
     created_at: string;
     archived_at: string | null;
     shadowed_by_organization_template: boolean;
+    /** Mutable template-level defaults (contracts §20.5, §20.7): the size of a start without caps.memory_mib, and the idle policy of a workspace that sets none. */
+    defaults: {
+        memory_mib: number | null;
+        idle_policy: string | null;
+    };
     open_version: TemplateVersion | null;
+    /** The live draft (organization templates in dev mode), or null. */
+    draft: TemplateDraftSummary | null;
+    /** Reserved (T2): always `pinned` in T1. */
+    update_policy: 'pinned' | 'auto';
 }
 export interface TemplateDetail extends TemplateSummary {
     plan: {
@@ -179,14 +259,15 @@ export interface TemplateBuild {
         mode: 'none' | 'egress_allowlist';
         allow_hosts: string[];
     };
+    /** recipe_schema/recipe_sha256 are null for workspace-source builds (save-as-template, draft publish). */
     provenance: {
-        recipe_schema: string;
-        recipe_sha256: string;
+        recipe_schema: string | null;
+        recipe_sha256: string | null;
         base_artifact_sha256: string;
         builder_id: string | null;
         attempt: number;
     };
-    /** Present on create and get of one build. */
+    /** Recipe builds only, on create and get of one build. */
     recipe?: {
         dockerfile: string;
     };
@@ -220,6 +301,20 @@ export interface TemplateBuild {
     };
     publishable: boolean;
     builder_availability: BuilderAvailability;
+    /** `recipe` (Dockerfile dialect) or `workspace` (save-as-template, draft publish; contracts §19.8). */
+    source_kind: 'recipe' | 'workspace';
+    source_workspace_id: string | null;
+    /** The captured checkpoint (null until the capture operation succeeded). */
+    source_checkpoint_id: string | null;
+    /** sf-scrub.v1 report of a workspace build: {policy, removed_count, removed_bytes, removed_paths, emptied, reimposed}. */
+    scrub_result: Record<string, unknown> | null;
+    /** The produced file list: {key, size, sha256, content_sha256, entries, total_file_bytes}. */
+    files: Record<string, unknown> | null;
+    produced_layer_id: string | null;
+    /** The base chain already had 4 org layers and was squashed into the produced one. */
+    squashed: boolean | null;
+    /** Organization bytes of the produced chain (limit: the plan's template_org_bytes_max). */
+    org_bytes: number | null;
 }
 export interface TemplateRecipe {
     /** `<template slug>@<version>`, referenced in the Dockerfile as `FROM shardflux-base`. */
@@ -258,8 +353,11 @@ export interface TemplateBuildLogUrl {
 }
 export interface WaitForBuildOptions {
     timeoutMs?: number;
+    /** Backoff used when the server does not hold the poll (default 1 s doubling to 10 s). */
     pollIntervalMs?: number;
     maxPollIntervalMs?: number;
+    /** Ask the server to hold each poll until the build changes (`Prefer: wait`, contracts §3; default true). */
+    serverWait?: boolean;
     signal?: AbortSignal;
 }
 /** Finished from the caller's point of view: failed/canceled/legacy succeeded, or published and its registration settled. */
@@ -269,6 +367,157 @@ export declare class TemplateBuildTimeoutError extends Error {
     readonly build: TemplateBuild;
     constructor(build: TemplateBuild, waitedMs: number);
 }
+/** operation: the capture (layer_snapshot) of a running workspace, null otherwise. build: poll it until registration.state is registered. */
+export interface SaveAsTemplateResponse {
+    operation: Operation | null;
+    build: TemplateBuild;
+}
+/** Save-as-template (contracts §19.8): everything in the workspace, minus the sf-scrub.v1 list, becomes one new org layer. */
+export interface SaveAsTemplateParams {
+    /** Organization template to save into (created when absent; platform slugs are refused with platform_template_slug). */
+    templateSlug: string;
+    /** Template name when this save creates the template. */
+    displayName?: string;
+    /** The version description (default: the source version's). */
+    description?: string;
+    /** Defaults of the new version (default: the source version's, else persistent). */
+    defaults?: TemplateDefaultsInput;
+    /** A committed checkpoint of this workspace to save instead of its current state. */
+    checkpointId?: string;
+    /** Publish the produced version once registered (default true). */
+    autoPublish?: boolean;
+    /** Up to 200 absolute paths the credential scan may report without failing the build. */
+    acknowledgedScanFindings?: string[];
+    /** Defaults to a random key so retries never start a second save. */
+    idempotencyKey?: string;
+}
+/** The JSON body of save-as-template (and, without template_slug/display_name/checkpoint_id, of a draft publish). */
+export declare function saveAsTemplateBody(params: SaveAsTemplateParams): SaveAsTemplateBody;
+export interface TemplateFilesParams {
+    /** Directory to list (absolute, normalized; default `/`). */
+    path?: string;
+    /** 1..1000 (default 200). */
+    limit?: number;
+    cursor?: string;
+    /** Pick the platform template even when an organization template shadows its slug. */
+    owner?: TemplateOwner;
+    /** Use the organization form of the route (default: the API key's organization). */
+    organizationId?: string;
+}
+export interface TemplateDiffParams {
+    /** A version number of this template, or `base` (the `to` version's build base, possibly a platform version). */
+    from: number | 'base';
+    to: number;
+    /** Only paths starting with this (absolute) prefix. */
+    pathPrefix?: string;
+    change?: TemplateDiffChange;
+    /** 1..1000. */
+    limit?: number;
+    cursor?: string;
+    owner?: TemplateOwner;
+    organizationId?: string;
+}
+export interface CreateDraftParams {
+    /** `<slug>@<version>`: a published, layered-capable version (default: the template's latest published version; required when it has none). */
+    base?: string;
+    caps?: {
+        cpu_millis?: number;
+        memory_mib?: number;
+        disk_gib?: number;
+    };
+    /** Browser/session principals only; API keys use their own project. */
+    projectId?: string;
+    /** Attribution label for tool tokens obtained through the returned workspace object. */
+    agentLabel?: string;
+    tools?: ToolName[];
+    /** `false`: return at once (possibly not ready). Default: wait until the draft is ready. */
+    wait?: false | WaitOptions;
+    idempotencyKey?: string;
+}
+export interface OpenTestInstanceParams {
+    /** A draft state (states()). Omitted: a fresh capture of the running draft (its current checkpoint when suspended). */
+    stateId?: string;
+    /** Workspace key (default sf:test:<slug>:<8 hex>); keys starting with `sf:` are reserved. */
+    key?: string;
+    caps?: {
+        cpu_millis?: number;
+        memory_mib?: number;
+        disk_gib?: number;
+    };
+    agentLabel?: string;
+    tools?: ToolName[];
+    /** `false`: return at once. Default: wait until the test instance is ready. */
+    wait?: false | WaitOptions;
+    idempotencyKey?: string;
+}
+export interface PublishDraftParams {
+    /** A draft state to publish (default: the draft's current state; a fresh capture when running). */
+    stateId?: string;
+    description?: string;
+    defaults?: TemplateDefaultsInput;
+    autoPublish?: boolean;
+    acknowledgedScanFindings?: string[];
+    idempotencyKey?: string;
+}
+/** The draft's workspace (a Workspace handle), the draft view and the open operation (null when it was already ready). */
+export interface DraftOpened {
+    workspace: Workspace;
+    draft: TemplateDraft;
+    operation: Operation | null;
+}
+/**
+ * Template dev mode for one organization template (contracts §19.9): the single live draft (a layered, persistent
+ * workspace on the draft base), its captured states, disposable test instances (session workspaces on a copy of a
+ * state) and publishing the draft as the next version. Mutations need build access (owners/admins, API keys with a
+ * tool permission); others get 403 forbidden with details.reason template_dev_mode_role.
+ */
+export declare class TemplateDraftApi {
+    #private;
+    readonly slug: string;
+    constructor(ctx: () => ClientContext, slug: string, organizationId?: string);
+    /**
+     * Opens the template's draft on `base` (202; waits until ready unless `wait: false`). 409 template_not_layered (the
+     * base is not layered-capable, or layered opens are off), 409 draft_exists (details.workspace_id).
+     */
+    create(params?: CreateDraftParams): Promise<DraftOpened>;
+    /** The draft (404 not_found with details.reason draft_not_found when the template has none). */
+    get(): Promise<TemplateDraft>;
+    /** Like get() but null when the template has no draft. */
+    find(): Promise<TemplateDraft | null>;
+    /** Deletes the draft (operation `delete`, input.reason draft_discarded) and ends its live test instances. */
+    discard(opts?: {
+        idempotencyKey?: string;
+    }): Promise<Operation>;
+    /** Captures a draft state (`layer_snapshot`; its result carries checkpoint_id). A suspended draft is 409 workspace_not_running. */
+    captureState(opts?: {
+        label?: string;
+        idempotencyKey?: string;
+    }): Promise<Operation>;
+    /** The draft's states, newest first. */
+    states(params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<Page<DraftState>>;
+    statesAll(params?: {
+        limit?: number;
+    }): AsyncGenerator<DraftState>;
+    /**
+     * Opens a test instance: a session workspace on the draft base whose layer is a copy of the state (its writes never
+     * reach the draft). It ends on close(), idle or a draft discard. Waits until ready unless `wait: false`.
+     */
+    openTestInstance(params?: OpenTestInstanceParams): Promise<Workspace>;
+    /** The draft's live test instances (`includeEnded` adds ended ones: tombstones with ended_reason). */
+    testInstances(params?: {
+        limit?: number;
+        cursor?: string;
+        includeEnded?: boolean;
+    }): Promise<Page<Workspace>>;
+    /**
+     * Publishes the draft as the template's next version (save-as-template from the draft). 409 draft_stale (details
+     * latest_version, draft_base_version) or build_in_progress. Poll the returned build (templates.builds.waitForBuild).
+     */
+    publish(params?: PublishDraftParams): Promise<SaveAsTemplateResponse>;
+}
 export declare class TemplateBuildsApi {
     #private;
     constructor(ctx: () => ClientContext);
@@ -290,7 +539,8 @@ export declare class TemplateBuildsApi {
     cancel(organizationId: string, buildId: string): Promise<TemplateBuild>;
     builderAvailability(organizationId: string): Promise<BuilderAvailability>;
     /**
-     * Polls until the build is settled and returns it: failed | canceled, or published with its registration
+     * Waits until the build is settled (each poll asks the server to hold it until the build changes, `Prefer: wait`,
+     * falling back to backoff polling on servers that do not wait) and returns it: failed | canceled, or published with its registration
      * `registered` (the version exists; `template_version`) or `failed`. Legacy builds end `succeeded`.
      * Throws TemplateBuildTimeoutError at the deadline (default 30 min); the build continues.
      */
@@ -325,4 +575,26 @@ export declare class TemplatesApi {
         includeArchived?: boolean;
         owner?: TemplateOwner;
     }): Promise<TemplateDetail | null>;
+    /**
+     * One directory level of a version's file tree (contracts §19.10), sorted by name bytes. 409 conflict with
+     * details.reason file_list_unavailable (no file list) or file_list_indexing (retryable); 404 path_not_found or
+     * version_not_found; 422 invalid_path. File contents are not served: open a draft or test instance for that.
+     */
+    files(slug: string, version: number, params?: TemplateFilesParams): Promise<TemplateFilePage>;
+    /** Every entry of one directory, following next_cursor. */
+    filesAll(slug: string, version: number, params?: Omit<TemplateFilesParams, 'cursor'>): AsyncGenerator<TemplateFileEntry>;
+    /** One entry of a version's file tree (404 path_not_found). */
+    fileEntry(slug: string, version: number, path: string, params?: {
+        owner?: TemplateOwner;
+        organizationId?: string;
+    }): Promise<TemplateFileEntry>;
+    /** One page of the diff between two versions (keyset-paginated by path; the first page carries `summary`). */
+    diff(slug: string, params: TemplateDiffParams): Promise<TemplateDiffPage>;
+    /** Every diff entry, following next_cursor. */
+    diffAll(slug: string, params: Omit<TemplateDiffParams, 'cursor'>): AsyncGenerator<TemplateDiffEntry>;
+    /** Dev mode of one organization template: its draft, states, test instances and publish (contracts §19.9). */
+    draft(slug: string, params?: {
+        organizationId?: string;
+    }): TemplateDraftApi;
 }
+export {};

package/dist/templates.js

@@ -1,5 +1,6 @@
 import { ShardfluxApiError } from "./errors.js";
-import { randomId } from "./http.js";
+import { pollWithWait, randomId } from "./http.js";
+import { Workspace } from "./workspace.js";
 const TERMINAL = new Set(['succeeded', 'failed', 'canceled']);
 /** Finished from the caller's point of view: failed/canceled/legacy succeeded, or published and its registration settled. */
 export function buildSettled(build) {
@@ -17,6 +18,164 @@ export class TemplateBuildTimeoutError extends Error {
     }
 }
 const enc = encodeURIComponent;
+/** Where a template route lives: the SDK form `/v1/templates/{slug}` or the organization form (both take API keys). */
+function templatePath(slug, organizationId) {
+    return organizationId === undefined ? `/v1/templates/${enc(slug)}` : `/v1/organizations/${enc(organizationId)}/templates/${enc(slug)}`;
+}
+/** The JSON body of save-as-template (and, without template_slug/display_name/checkpoint_id, of a draft publish). */
+export function saveAsTemplateBody(params) {
+    const body = { template_slug: params.templateSlug };
+    if (params.displayName !== undefined)
+        body.display_name = params.displayName;
+    if (params.description !== undefined)
+        body.description = params.description;
+    if (params.defaults !== undefined)
+        body.defaults = params.defaults;
+    if (params.checkpointId !== undefined)
+        body.checkpoint_id = params.checkpointId;
+    if (params.autoPublish !== undefined)
+        body.auto_publish = params.autoPublish;
+    if (params.acknowledgedScanFindings !== undefined)
+        body.acknowledged_scan_findings = params.acknowledgedScanFindings;
+    return body;
+}
+/**
+ * Template dev mode for one organization template (contracts §19.9): the single live draft (a layered, persistent
+ * workspace on the draft base), its captured states, disposable test instances (session workspaces on a copy of a
+ * state) and publishing the draft as the next version. Mutations need build access (owners/admins, API keys with a
+ * tool permission); others get 403 forbidden with details.reason template_dev_mode_role.
+ */
+export class TemplateDraftApi {
+    slug;
+    #ctx;
+    #org;
+    constructor(ctx, slug, organizationId) {
+        this.#ctx = ctx;
+        this.slug = slug;
+        this.#org = organizationId;
+    }
+    #path(suffix = '') {
+        return `${templatePath(this.slug, this.#org)}/draft${suffix}`;
+    }
+    async #opened(res, p) {
+        const ctx = this.#ctx();
+        const wrap = { agentLabel: p.agentLabel, tools: p.tools };
+        if (res.status === 200 || p.wait === false || res.body.operation === null) {
+            return { workspace: new Workspace(ctx, res.body.workspace, { ...wrap, token: res.body.tool_token }), operation: res.body.operation };
+        }
+        const operation = await ctx.workspaces.waitForOperation(res.body.operation.id, p.wait ?? {});
+        const view = await ctx.http.json('GET', `/v1/workspaces/${enc(res.body.workspace.id)}`, {}, ctx.authorization);
+        return { workspace: new Workspace(ctx, view, wrap), operation };
+    }
+    /**
+     * Opens the template's draft on `base` (202; waits until ready unless `wait: false`). 409 template_not_layered (the
+     * base is not layered-capable, or layered opens are off), 409 draft_exists (details.workspace_id).
+     */
+    async create(params = {}) {
+        const body = {};
+        if (params.base !== undefined)
+            body.base = params.base;
+        if (params.caps !== undefined)
+            body.caps = params.caps;
+        if (params.projectId !== undefined)
+            body.project_id = params.projectId;
+        if (params.agentLabel !== undefined)
+            body.agent_label = params.agentLabel;
+        if (params.tools !== undefined)
+            body.tools = params.tools;
+        const ctx = this.#ctx();
+        const res = await ctx.http.jsonWithStatus('POST', this.#path(), { json: body, idempotencyKey: params.idempotencyKey ?? randomId('draft-') }, ctx.authorization);
+        const { workspace, operation } = await this.#opened(res, params);
+        return { workspace, draft: { ...res.body.draft, workspace: workspace.data }, operation };
+    }
+    /** The draft (404 not_found with details.reason draft_not_found when the template has none). */
+    get() {
+        const ctx = this.#ctx();
+        return ctx.http.json('GET', this.#path(), {}, ctx.authorization);
+    }
+    /** Like get() but null when the template has no draft. */
+    async find() {
+        try {
+            return await this.get();
+        }
+        catch (err) {
+            if (err instanceof ShardfluxApiError && err.status === 404 && err.details?.reason === 'draft_not_found')
+                return null;
+            throw err;
+        }
+    }
+    /** Deletes the draft (operation `delete`, input.reason draft_discarded) and ends its live test instances. */
+    async discard(opts = {}) {
+        const ctx = this.#ctx();
+        const out = await ctx.http.json('DELETE', this.#path(), { idempotencyKey: opts.idempotencyKey ?? randomId('op-') }, ctx.authorization);
+        return out.operation;
+    }
+    /** Captures a draft state (`layer_snapshot`; its result carries checkpoint_id). A suspended draft is 409 workspace_not_running. */
+    async captureState(opts = {}) {
+        const ctx = this.#ctx();
+        const out = await ctx.http.json('POST', this.#path('/states'), { json: opts.label === undefined ? {} : { label: opts.label }, idempotencyKey: opts.idempotencyKey ?? randomId('op-') }, ctx.authorization);
+        return out.operation;
+    }
+    /** The draft's states, newest first. */
+    async states(params = {}) {
+        const ctx = this.#ctx();
+        const page = await ctx.http.json('GET', this.#path('/states'), { query: { limit: params.limit, cursor: params.cursor } }, ctx.authorization);
+        return { data: page.data, nextCursor: page.next_cursor };
+    }
+    async *statesAll(params = {}) {
+        let cursor;
+        do {
+            const page = await this.states({ ...params, ...(cursor === undefined ? {} : { cursor }) });
+            yield* page.data;
+            cursor = page.nextCursor ?? undefined;
+        } while (cursor !== undefined);
+    }
+    /**
+     * Opens a test instance: a session workspace on the draft base whose layer is a copy of the state (its writes never
+     * reach the draft). It ends on close(), idle or a draft discard. Waits until ready unless `wait: false`.
+     */
+    async openTestInstance(params = {}) {
+        const body = {};
+        if (params.stateId !== undefined)
+            body.state_id = params.stateId;
+        if (params.key !== undefined)
+            body.key = params.key;
+        if (params.caps !== undefined)
+            body.caps = params.caps;
+        if (params.agentLabel !== undefined)
+            body.agent_label = params.agentLabel;
+        if (params.tools !== undefined)
+            body.tools = params.tools;
+        const ctx = this.#ctx();
+        const res = await ctx.http.jsonWithStatus('POST', this.#path('/test-instances'), { json: body, idempotencyKey: params.idempotencyKey ?? randomId('test-') }, ctx.authorization);
+        return (await this.#opened(res, params)).workspace;
+    }
+    /** The draft's live test instances (`includeEnded` adds ended ones: tombstones with ended_reason). */
+    async testInstances(params = {}) {
+        const ctx = this.#ctx();
+        const page = await ctx.http.json('GET', this.#path('/test-instances'), { query: { limit: params.limit, cursor: params.cursor, include_ended: params.includeEnded } }, ctx.authorization);
+        return { data: page.data.map((v) => new Workspace(ctx, v)), nextCursor: page.next_cursor };
+    }
+    /**
+     * Publishes the draft as the template's next version (save-as-template from the draft). 409 draft_stale (details
+     * latest_version, draft_base_version) or build_in_progress. Poll the returned build (templates.builds.waitForBuild).
+     */
+    publish(params = {}) {
+        const body = {};
+        if (params.stateId !== undefined)
+            body.state_id = params.stateId;
+        if (params.description !== undefined)
+            body.description = params.description;
+        if (params.defaults !== undefined)
+            body.defaults = params.defaults;
+        if (params.autoPublish !== undefined)
+            body.auto_publish = params.autoPublish;
+        if (params.acknowledgedScanFindings !== undefined)
+            body.acknowledged_scan_findings = params.acknowledgedScanFindings;
+        const ctx = this.#ctx();
+        return ctx.http.json('POST', this.#path('/publish'), { json: body, idempotencyKey: params.idempotencyKey ?? randomId('publish-') }, ctx.authorization);
+    }
+}
 export class TemplateBuildsApi {
     #ctx;
     constructor(ctx) {
@@ -53,23 +212,35 @@ export class TemplateBuildsApi {
         return this.#ctx().http.json('GET', `/v1/organizations/${enc(organizationId)}/template-builder-availability`, {}, this.#ctx().authorization);
     }
     /**
-     * Polls until the build is settled and returns it: failed | canceled, or published with its registration
+     * Waits until the build is settled (each poll asks the server to hold it until the build changes, `Prefer: wait`,
+     * falling back to backoff polling on servers that do not wait) and returns it: failed | canceled, or published with its registration
      * `registered` (the version exists; `template_version`) or `failed`. Legacy builds end `succeeded`.
      * Throws TemplateBuildTimeoutError at the deadline (default 30 min); the build continues.
      */
     async waitForBuild(organizationId, buildId, opts = {}) {
-        const { sleep } = this.#ctx();
+        const { sleep, http, authorization } = this.#ctx();
         const timeoutMs = opts.timeoutMs ?? 1_800_000;
         const maxInterval = opts.maxPollIntervalMs ?? 10_000;
         let interval = opts.pollIntervalMs ?? 1_000;
         const started = Date.now();
+        let lastKey = null;
         for (;;) {
-            const build = await this.get(organizationId, buildId);
+            if (opts.signal?.aborted)
+                throw opts.signal.reason instanceof Error ? opts.signal.reason : new Error('aborted');
+            const waitS = opts.serverWait === false ? 0 : (timeoutMs - (Date.now() - started)) / 1000;
+            const t0 = Date.now();
+            const { body: build, applied } = await pollWithWait(http, `/v1/organizations/${enc(organizationId)}/template-builds/${enc(buildId)}`, authorization, waitS, opts.signal);
             if (buildSettled(build))
                 return build;
             const waited = Date.now() - started;
             if (waited >= timeoutMs)
                 throw new TemplateBuildTimeoutError(build, waited);
+            // Held by the server (or a change): poll again at once; a quick unchanged answer falls through to the backoff.
+            const key = `${build.state}/${build.registration.state}`;
+            const changed = key !== lastKey;
+            lastKey = key;
+            if (applied && (changed || Date.now() - t0 >= 1_000))
+                continue;
             await sleep(Math.max(10, Math.min(interval, timeoutMs - waited)));
             if (opts.signal?.aborted)
                 throw opts.signal.reason instanceof Error ? opts.signal.reason : new Error('aborted');
@@ -114,4 +285,45 @@ export class TemplatesApi {
             throw err;
         }
     }
+    /**
+     * One directory level of a version's file tree (contracts §19.10), sorted by name bytes. 409 conflict with
+     * details.reason file_list_unavailable (no file list) or file_list_indexing (retryable); 404 path_not_found or
+     * version_not_found; 422 invalid_path. File contents are not served: open a draft or test instance for that.
+     */
+    async files(slug, version, params = {}) {
+        const ctx = this.#ctx();
+        return ctx.http.json('GET', `${templatePath(slug, params.organizationId)}/versions/${enc(String(version))}/files`, { query: { path: params.path, limit: params.limit, cursor: params.cursor, owner: params.owner } }, ctx.authorization);
+    }
+    /** Every entry of one directory, following next_cursor. */
+    async *filesAll(slug, version, params = {}) {
+        let cursor;
+        do {
+            const page = await this.files(slug, version, { limit: 1000, ...params, ...(cursor === undefined ? {} : { cursor }) });
+            yield* page.data;
+            cursor = page.next_cursor ?? undefined;
+        } while (cursor !== undefined);
+    }
+    /** One entry of a version's file tree (404 path_not_found). */
+    fileEntry(slug, version, path, params = {}) {
+        const ctx = this.#ctx();
+        return ctx.http.json('GET', `${templatePath(slug, params.organizationId)}/versions/${enc(String(version))}/files/entry`, { query: { path, owner: params.owner } }, ctx.authorization);
+    }
+    /** One page of the diff between two versions (keyset-paginated by path; the first page carries `summary`). */
+    diff(slug, params) {
+        const ctx = this.#ctx();
+        return ctx.http.json('GET', `${templatePath(slug, params.organizationId)}/diff`, { query: { from: String(params.from), to: params.to, path_prefix: params.pathPrefix, change: params.change, limit: params.limit, cursor: params.cursor, owner: params.owner } }, ctx.authorization);
+    }
+    /** Every diff entry, following next_cursor. */
+    async *diffAll(slug, params) {
+        let cursor;
+        do {
+            const page = await this.diff(slug, { limit: 1000, ...params, ...(cursor === undefined ? {} : { cursor }) });
+            yield* page.data;
+            cursor = page.next_cursor ?? undefined;
+        } while (cursor !== undefined);
+    }
+    /** Dev mode of one organization template: its draft, states, test instances and publish (contracts §19.9). */
+    draft(slug, params = {}) {
+        return new TemplateDraftApi(this.#ctx, slug, params.organizationId);
+    }
 }

package/dist/tokens.d.ts

@@ -8,6 +8,7 @@
  */
 import type { components } from './generated/app-api.js';
 import type { HttpClient } from './http.js';
+import type { ProgressListener } from './progress.js';
 export type ToolToken = components['schemas']['ToolToken'];
 export type ToolName = ToolToken['tools'][number];
 export interface ToolTokenOptions {
@@ -28,8 +29,12 @@ export declare class ToolTokenManager {
     /** Accepts a token obtained elsewhere (e.g. the one returned by a 200 open). */
     seed(token: ToolToken): void;
     get current(): ToolToken | undefined;
-    get(): Promise<ToolToken>;
-    /** Forces a new token (single-flight). */
-    refresh(): Promise<ToolToken>;
+    /**
+     * The current token, or a new one when there is none or it expires within the skew. A fetch is a traced `token` call:
+     * `onProgress` sees it (phase `request` with the reason `initial`, `expiring` or `invalidated`) and its timing.
+     */
+    get(onProgress?: ProgressListener): Promise<ToolToken>;
+    /** Forces a new token (single-flight: concurrent callers share one request, and the first caller's trace). */
+    refresh(onProgress?: ProgressListener, reason?: string): Promise<ToolToken>;
     invalidate(): void;
 }