@shardflux/sdk 0.6.2 → 0.7.0

package/dist/templates.d.ts

@@ -1,17 +1,57 @@
 /**
- * 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.
+ * Template registry, custom template builds (recipe v1 Dockerfiles and recipe v2, contracts §24.1), build uploads
+ * (§24.2), recipe export, version test instances, package search, 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 and template editor types 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 { components } from './generated/app-api.js';
-import type { ClientContext, Operation, Page, WaitOptions } from './client.js';
+import type { Caps, ClientContext, Operation, Page, WaitOptions } from './client.js';
+import type { YamlParser } from './template-file.js';
 import type { ToolName } from './tokens.js';
 import { Workspace } from './workspace.js';
 type S = components['schemas'];
+/** Recipe v2 (contracts §24.1): the `recipe` of a build, the export's `recipe` and the document of template.yaml. */
+export type TemplateRecipeV2 = S['TemplateRecipeV2'];
+/** One `build.files[]` entry: an upload (`upload: "sha256:<hex>"`), or in template.yaml a local path (`from`). */
+export type TemplateRecipeV2File = NonNullable<TemplateRecipeV2['build']['files']>[number];
+/** What a workspace of a version gets when it opens (§24.3): env, inputs, start commands, services, defaults. */
+export type TemplateSettings = S['TemplateSettings'];
+/** Settings as a recipe v2, a draft publish or save-as-template take them (omitted fields: empty, or carried forward). */
+export type TemplateSettingsInput = S['TemplateSettingsInput'];
+/** An open-time input: `text` (a value passed to open) or `secret` (a stored secret of the same name). */
+export type TemplateInput = S['TemplateInput'];
+/** A start command (§24.4): create, boot or resume. */
+export type TemplateStartCommand = S['TemplateStartCommand'];
+/** A process the guest keeps running (§24.4), ready before open() returns. */
+export type TemplateService = S['TemplateService'];
+/** The template's workspace network ceiling (§24.3). */
+export type TemplateEgressDefault = S['TemplateEgressDefault'];
+/** An uploaded file or folder (tar) of the organization (§24.2). */
+export type TemplateUpload = S['TemplateUpload'];
+export type TemplateUploadRequest = S['TemplateUploadRequest'];
+export type TemplateUploadResponse = S['TemplateUploadResponse'];
+/** The recipe and settings a version was built from (GET …/versions/{v}/recipe): ready to build again. */
+export type TemplateVersionRecipe = S['TemplateVersionRecipe'];
+export type TemplatePackage = S['TemplatePackage'];
+export type TemplatePackagePage = S['TemplatePackagePage'];
+export type TemplatePackageEcosystem = 'apt' | 'pip' | 'npm';
+/** The languages a base offers a recipe v2 (contracts §24.6 `GET …/template-languages`): the language table for its platform base. */
+export type TemplateLanguages = S['TemplateLanguages'];
+export type TemplateLanguage = TemplateLanguages['data'][number];
+export type CreateVersionTestInstanceBody = S['CreateVersionTestInstanceBody'];
+/** Platform templates: `os` (a bare operating system) or `stack`; organization templates are null. */
+export type TemplateCategory = 'os' | 'stack';
+/** The stored recipe v2 of a build (GET of one build): the build, the settings and the compiled steps. */
+export type TemplateBuildRecipeV2 = Extract<NonNullable<S['TemplateBuild']['recipe']>, {
+    schema: string;
+}>;
+/** Start commands and services of a workspace's version (§24.4); null when it has none. */
+export type WorkspaceStartup = S['WorkspaceStartup'];
 /** 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). */
@@ -124,6 +164,8 @@ export interface TemplateVersion {
         rootfs_sha256: string | null;
     } | null;
     defaults: TemplateDefaults;
+    /** What a workspace of this version gets when it opens (0.7.0; contracts §24.3). `defaults` equals `settings.defaults`. */
+    settings: TemplateSettings;
     /** The file list the tree and diff read (`loaded` when files() and diff() can answer). */
     files: TemplateFilesSummary;
     rootfs_bytes: number | null;
@@ -167,6 +209,8 @@ export interface TemplateSummary {
     draft: TemplateDraftSummary | null;
     /** Reserved (T2): always `pinned` in T1. */
     update_policy: 'pinned' | 'auto';
+    /** Platform templates: `os` or `stack` (0.7.0); organization templates: null. */
+    category: TemplateCategory | null;
 }
 export interface TemplateDetail extends TemplateSummary {
     plan: {
@@ -267,10 +311,12 @@ export interface TemplateBuild {
         builder_id: string | null;
         attempt: number;
     };
-    /** Recipe builds only, on create and get of one build. */
+    /** Recipe builds only, on create and get of one build: v1 `{dockerfile}`, or the stored recipe v2 (0.7.0). */
     recipe?: {
         dockerfile: string;
-    };
+    } | TemplateBuildRecipeV2;
+    /** Host names the builder refused during the build (0.7.0; at most 50): rebuild with them in `build.network.extra_hosts`. */
+    denied_hosts: string[];
     result: {
         artifact_sha256: string | null;
         scan: ({
@@ -334,12 +380,21 @@ export interface TemplateRecipe {
     };
 }
 export interface CreateTemplateBuildParams {
-    /** Organization template slug (created by the first build; platform slugs are refused). */
+    /** Organization template slug (created by the first build; platform slugs and the reserved `new`/`edit` are refused). */
     templateSlug: string;
     displayName?: string;
-    recipe: TemplateRecipe;
+    /**
+     * Recipe v1 (a Dockerfile) or recipe v2 (0.7.0; `schema: "shardflux.template-recipe.v2"`: languages, packages,
+     * uploaded files, steps, auto network and settings; contracts §24.1). Recipe v2 files reference uploads
+     * (`templates.uploads.put()`); `buildFromFile()` / `buildFromRecipe()` upload local `from` paths for you.
+     */
+    recipe: TemplateRecipe | TemplateRecipeV2;
     /** Publish the produced version as soon as it is registered (default true); false leaves it for the owner/admin publish route. */
     autoPublish?: boolean;
+    /** The version description (1..2000 characters; 0.7.0). */
+    description?: string;
+    /** Recipe v2 only (0.7.0): up to 200 absolute paths the credential scan may report without failing the build. */
+    acknowledgedScanFindings?: string[];
     /** Defaults to a random key so retries never create a second build. */
     idempotencyKey?: string;
 }
@@ -359,6 +414,8 @@ export interface WaitForBuildOptions {
     /** Ask the server to hold each poll until the build changes (`Prefer: wait`, contracts §3; default true). */
     serverWait?: boolean;
     signal?: AbortSignal;
+    /** Called with each build view the wait observes whose state or registration changed (0.7.0), the settled one included. */
+    onChange?: (build: TemplateBuild) => void;
 }
 /** Finished from the caller's point of view: failed/canceled/legacy succeeded, or published and its registration settled. */
 export declare function buildSettled(build: Pick<TemplateBuild, 'state' | 'registration'>): boolean;
@@ -382,6 +439,11 @@ export interface SaveAsTemplateParams {
     description?: string;
     /** Defaults of the new version (default: the source version's, else persistent). */
     defaults?: TemplateDefaultsInput;
+    /**
+     * Settings of the new version (0.7.0; contracts §24.3): each field given replaces that field of the source version's
+     * settings, each field left out is carried forward. `settings.defaults` together with `defaults` is 422 invalid_settings.
+     */
+    settings?: TemplateSettingsInput;
     /** A committed checkpoint of this workspace to save instead of its current state. */
     checkpointId?: string;
     /** Publish the produced version once registered (default true). */
@@ -420,6 +482,10 @@ export interface TemplateDiffParams {
 export interface CreateDraftParams {
     /** `<slug>@<version>`: a published, layered-capable version (default: the template's latest published version; required when it has none). */
     base?: string;
+    /** The template's name when this draft creates the template (0.7.0). */
+    displayName?: string;
+    /** Text inputs of the base version (0.7.0; `{NAME: value}`, as open() takes them). */
+    inputs?: Record<string, string>;
     caps?: {
         cpu_millis?: number;
         memory_mib?: number;
@@ -446,6 +512,8 @@ export interface OpenTestInstanceParams {
     };
     agentLabel?: string;
     tools?: ToolName[];
+    /** Text inputs (0.7.0; `{NAME: value}`, as open() takes them). */
+    inputs?: Record<string, string>;
     /** `false`: return at once. Default: wait until the test instance is ready. */
     wait?: false | WaitOptions;
     idempotencyKey?: string;
@@ -455,6 +523,8 @@ export interface PublishDraftParams {
     stateId?: string;
     description?: string;
     defaults?: TemplateDefaultsInput;
+    /** Settings of the new version (0.7.0): each field given replaces the draft base version's, the rest carries forward. */
+    settings?: TemplateSettingsInput;
     autoPublish?: boolean;
     acknowledgedScanFindings?: string[];
     idempotencyKey?: string;
@@ -521,7 +591,12 @@ export declare class TemplateDraftApi {
 export declare class TemplateBuildsApi {
     #private;
     constructor(ctx: () => ClientContext);
-    /** Queues a build (202). Poll with get()/waitForBuild(); `builder_availability` says whether a builder runs. */
+    /**
+     * Queues a build (202) of a recipe v1 (Dockerfile) or recipe v2 (0.7.0). Poll with get()/waitForBuild();
+     * `builder_availability` says whether a builder runs. A recipe v2 is validated at once: 422 validation_failed with
+     * details.reason (invalid_recipe, base_not_layered, language_unavailable, upload_missing, invalid_settings, ...) and
+     * details.field (the JSON path). A file entry still carrying `from` is 422 upload_required.
+     */
     create(organizationId: string, params: CreateTemplateBuildParams): Promise<TemplateBuild>;
     get(organizationId: string, buildId: string): Promise<TemplateBuild>;
     list(organizationId: string, params?: {
@@ -546,10 +621,244 @@ export declare class TemplateBuildsApi {
      */
     waitForBuild(organizationId: string, buildId: string, opts?: WaitForBuildOptions): Promise<TemplateBuild>;
 }
+/** Bytes to upload: in memory, a Blob (a File in browsers, fs.openAsBlob in Node) or a stream. */
+export type UploadData = Uint8Array | ArrayBuffer | Blob | ReadableStream<Uint8Array>;
+export interface PutUploadOptions {
+    /** `file` (copied to `to`) or `tar` (an uncompressed ustar/pax archive of a folder, extracted into `to`). */
+    kind: 'file' | 'tar';
+    /**
+     * The bytes' SHA-256 (lower-case hex) and size, when known. Required to send a stream without holding it in memory;
+     * otherwise the SDK reads the data once to hash it.
+     */
+    sha256?: string;
+    size?: number;
+    /** Use the organization form of the route (default: the API key's organization, the SDK form). */
+    organizationId?: string;
+    signal?: AbortSignal;
+}
+/** An upload the organization has: reference it in a recipe v2 file entry as `upload: ref`. */
+export interface TemplateUploadResult {
+    upload: TemplateUpload;
+    /** `sha256:<hex>`, the recipe's `upload` value. */
+    ref: string;
+    /** False when the organization already had these bytes (no PUT was sent). */
+    uploaded: boolean;
+}
+/** A presigned PUT the storage refused (the URL is a bearer credential and never part of the message). */
+export declare class TemplateUploadError extends Error {
+    /** HTTP status of the storage's answer (0: no answer, a network failure). */
+    readonly status: number;
+    /** The storage's error code: BadDigest (other bytes), SignatureDoesNotMatch (another length or header), ... */
+    readonly code: string | null;
+    readonly sha256: string;
+    constructor(sha256: string, status: number, code: string | null, detail?: string);
+}
+/**
+ * Build uploads (contracts §24.2): files and folders a recipe v2 copies into the template, stored once per
+ * organization and content (SHA-256). Needs build access (API keys with a tool permission). Uploads count toward the
+ * organization's template storage while they exist; one nothing references is deleted 7 days later.
+ */
+export declare class TemplateUploadsApi {
+    #private;
+    constructor(ctx: () => ClientContext);
+    /**
+     * POST …/template-uploads alone: `status` 200 (the organization has the bytes; `put` null) or 201 (`put`: the
+     * presigned PUT, valid 900 s). 422 upload_too_large (over 5 GiB), upload_digest_mismatch (the same SHA-256 with
+     * another size); 503 dependency_unavailable (uploads_not_configured).
+     */
+    request(meta: TemplateUploadRequest, opts?: {
+        organizationId?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        status: number;
+    } & TemplateUploadResponse>;
+    /**
+     * Uploads bytes unless the organization already has them, and returns the `sha256:<hex>` reference for a recipe v2
+     * file entry. The PUT carries exactly the presigned headers (the storage checks the SHA-256 and the length). A stream
+     * is sent as it is when `sha256` and `size` are given (it cannot be retried); otherwise it is read into memory first.
+     * Throws TemplateUploadError when the storage refuses the bytes.
+     */
+    put(data: UploadData, opts: PutUploadOptions): Promise<TemplateUploadResult>;
+    /**
+     * Node only: uploads a local file, or a folder packed as the reproducible tar (the same bytes as the Python SDK's
+     * for the same folder). `kind` omitted: a folder is `tar`, a file `file`; a file with kind `tar` is a prepared,
+     * uncompressed archive.
+     */
+    putPath(path: string, opts?: {
+        kind?: 'file' | 'tar';
+        organizationId?: string;
+        signal?: AbortSignal;
+    }): Promise<TemplateUploadResult & {
+        path: string;
+        kind: 'file' | 'tar';
+        size: number;
+        entries: number | null;
+    }>;
+}
+/** One distinct local `from` source of a template file (a path used by several entries is one row), uploaded or already there. */
+export interface LocalUpload {
+    /** `from` as written in the file (its first entry). */
+    from: string;
+    /** The resolved local path. */
+    path: string;
+    /** The destination of its first entry in the template. */
+    to: string;
+    kind: 'file' | 'tar';
+    sha256: string;
+    size: number;
+    /** Members of a packed folder; null for a file. */
+    entries: number | null;
+    /** False when the organization already had these bytes. */
+    uploaded: boolean;
+}
+export type BuildFromFileEvent = {
+    type: 'pack';
+    from: string;
+    path: string;
+    kind: 'file' | 'tar';
+    sha256: string;
+    size: number;
+    entries: number | null;
+    ms: number;
+} | {
+    type: 'upload';
+    from: string;
+    sha256: string;
+    size: number;
+    uploaded: boolean;
+    ms: number;
+} | {
+    type: 'build';
+    build: TemplateBuild;
+};
+export interface BuildFromRecipeOptions {
+    /** Organization template to build into (created by the first build). */
+    templateSlug: string;
+    /** Template name when this build creates the template. */
+    displayName?: string;
+    /** The version description. */
+    description?: string;
+    /** Publish the version once registered (API default true); false leaves it unpublished for test instances. */
+    autoPublish?: boolean;
+    /** Up to 200 absolute paths the credential scan may report without failing the build. */
+    acknowledgedScanFindings?: string[];
+    /** Default: the API key's organization (GET /v1/me). */
+    organizationId?: string;
+    /** Directory the `from` paths are relative to (buildFromFile: the template file's directory; default the process's). */
+    baseDir?: string;
+    /** Refuse every local path (the template file and each `from`) that resolves, after symlinks, outside this directory. */
+    root?: string;
+    /** Wait until the build settles (true: 30 minutes; or the wait's options). Default: return the queued build. */
+    wait?: boolean | WaitForBuildOptions;
+    /** Packing, each upload, the created build and each change while waiting. */
+    onProgress?: (event: BuildFromFileEvent) => void;
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+}
+export interface BuildFromFileOptions extends Omit<BuildFromRecipeOptions, 'baseDir'> {
+    /** YAML parser (default: the optional `yaml` package's parse). */
+    parseYaml?: YamlParser;
+}
+export interface BuildFromFileResult {
+    /** The created build, or the settled one with `wait`. */
+    build: TemplateBuild;
+    /** The recipe v2 as sent (every `from` replaced by its `upload`). */
+    recipe: TemplateRecipeV2;
+    uploads: LocalUpload[];
+}
+export declare class TemplateVersionsApi {
+    #private;
+    constructor(ctx: () => ClientContext);
+    /**
+     * The recipe and settings a version was built from, in request form (`recipe` null for versions saved from a
+     * workspace and platform versions). Building the recipe again (same base, uploads still present) gives the same
+     * recipe_sha256. Same visibility as the version.
+     */
+    recipe(slug: string, version: number, params?: {
+        owner?: TemplateOwner;
+        organizationId?: string;
+    }): Promise<TemplateVersionRecipe>;
+}
+export interface CreateVersionTestInstanceParams {
+    /** Workspace key (default sf:test:<slug>:<8 hex>); keys starting with `sf:` are reserved. */
+    key?: string;
+    caps?: Caps;
+    agentLabel?: string;
+    tools?: ToolName[];
+    /** The version's text inputs `{NAME: value}` (422 input_unknown, input_invalid, input_required). */
+    inputs?: Record<string, string>;
+    /** Browser/session principals only. */
+    projectId?: string;
+    /** `false`: return at once. Default: wait until the test instance is ready (its startup ran). */
+    wait?: false | WaitOptions;
+    organizationId?: string;
+    idempotencyKey?: string;
+}
+/**
+ * Test instances of a version (contracts §24.6): a session workspace on a registered version of the organization's
+ * template, published or not, so a build can be tried before it is published. Owners, admins and API keys with a
+ * tool permission (403 template_dev_mode_role otherwise).
+ */
+export declare class TemplateVersionTestInstancesApi {
+    #private;
+    constructor(ctx: () => ClientContext);
+    /** Opens one (202; waits until ready unless `wait: false`). It ends with close() or when idle. */
+    create(slug: string, version: number, params?: CreateVersionTestInstanceParams): Promise<Workspace>;
+}
+/** Package names for the editor's pickers (contracts §24.6): apt (a base's index), pip (names only) and npm. */
+export declare class TemplatePackagesApi {
+    #private;
+    constructor(ctx: () => ClientContext);
+    /**
+     * Searches an ecosystem (`query` 1..100 characters; `limit` 1..50, default 20). apt needs `base` (`<slug>@<version>`);
+     * a base without an index is 409 package_index_unavailable. pip returns names only (fetch one package for versions).
+     * 503 dependency_unavailable (package_search_unavailable, package_index_loading) and 429 are retryable.
+     */
+    search(ecosystem: TemplatePackageEcosystem, query: string, params?: {
+        base?: string;
+        limit?: number;
+        organizationId?: string;
+    }): Promise<TemplatePackagePage>;
+    /** One package: its latest version, summary and known versions (404 package_not_found). */
+    get(ecosystem: TemplatePackageEcosystem, name: string, params?: {
+        base?: string;
+        organizationId?: string;
+    }): Promise<TemplatePackage>;
+}
 export declare class TemplatesApi {
     #private;
     readonly builds: TemplateBuildsApi;
+    /** Build uploads (0.7.0): files and folders for recipe v2. */
+    readonly uploads: TemplateUploadsApi;
+    /** Recipe export of a version (0.7.0). */
+    readonly versions: TemplateVersionsApi;
+    /** Test instances of a registered version, published or not (0.7.0). */
+    readonly versionTestInstances: TemplateVersionTestInstancesApi;
+    /** Package search for recipes (0.7.0). */
+    readonly packages: TemplatePackagesApi;
     constructor(ctx: () => ClientContext);
+    /**
+     * The languages `base` (`<slug>@<version>`) offers a recipe v2's `build.languages` (0.7.0): the platform's table for
+     * the chain's platform base, in table order. `included`: the base already has that version (nothing is installed and
+     * no host is needed); a version the base has another version of is left out (a build would refuse it with
+     * language_conflict). `hosts` and `apt` are what the language adds to an `auto` build network. An unknown or
+     * archived base is 422 validation_failed with details.field `base`. Build access (API keys with a tool permission).
+     */
+    languages(base: string, params?: {
+        organizationId?: string;
+    }): Promise<TemplateLanguages>;
+    /**
+     * Node only: builds a template from template.yaml (or a .json file with the same document; contracts §24.1). The
+     * file is recipe v2; each `build.files[]` entry may name a local `from` path (relative to the file): folders are
+     * packed as the reproducible tar, files are sent as they are, both uploaded unless the organization already has
+     * them, and the build is created (and awaited with `wait`). YAML needs the optional `yaml` package or `parseYaml`.
+     */
+    buildFromFile(file: string, opts: BuildFromFileOptions): Promise<BuildFromFileResult>;
+    /**
+     * Builds a recipe v2 document whose file entries may name local `from` paths (Node only when one does): the same
+     * as buildFromFile() for a document already in memory, `from` relative to `baseDir`.
+     */
+    buildFromRecipe(recipe: TemplateRecipeV2 | Record<string, unknown>, opts: BuildFromRecipeOptions): Promise<BuildFromFileResult>;
     /** Templates the API key's organization can use (platform + its own), with the version `open` picks. */
     list(params?: {
         organizationId?: string;