@w6w/sdk 0.3.0 → 0.4.0

package/dist/src/console/vault.js

@@ -0,0 +1,164 @@
+/**
+ * `client.console.vault.*` — the write-only secret store (list, get, create,
+ * update, delete, seal), relocated from the studio's own API client.
+ *
+ * **Studio-internal, not the published partner contract.** This namespace
+ * lives under the `console` subpath export (`@w6w/sdk/console`), excluded from
+ * `endpoints.json` and from the root barrel (`mod.ts`) — see `docs/console.md`
+ * and HITL-1 in this task's contract. `@w6w/sdk`'s instance-state mechanism
+ * pin still applies here exactly as it does to every other namespace
+ * (`docs/implementation.md` §MECHANISM PIN — instance state, never globals):
+ * this class holds no state of its own beyond the injected host, so two
+ * clients in one process never share a credential.
+ *
+ * **Write-only, no-plaintext-in-responses is the invariant this whole domain
+ * rests on** (`packages/server/packages/api/admin/vault.ts:1-21`'s own header
+ * comment: "plaintext values NEVER appear in a response"). `list`/`get` never
+ * carry `value` — by the server's wire contract itself, not by client
+ * discipline — which is why {@linkcode VaultSecretSummary} has no `value`
+ * field. `create`/`update` forward `value` verbatim to *write* it, and it is
+ * simply never echoed back. `seal` is the one deliberate exception, and even
+ * there it never returns the plaintext: it answers with a ciphertext envelope
+ * (`SecretValue`) — an encrypt-only oracle with no matching decrypt route, so
+ * an authed caller learns nothing they didn't already provide.
+ *
+ * Six methods relocate from the studio's own `// Vault` comment block
+ * (`packages/studio/src/api/client.ts:257-278` on the current merged tree) —
+ * field-for-field, not redesigned.
+ *
+ * `value` is opaque — forwarded verbatim on `create`/`update`/`seal`, never
+ * inspected, logged, or transformed. This is a security-adjacent discipline,
+ * not a style note: the whole point of this field is a caller-opaque secret
+ * payload.
+ *
+ * None of these methods take a `project` scoping parameter — vault secrets
+ * are subject-scoped like `vars`, not project-scoped — so `VaultHost` needs
+ * only the transport, mirroring `VarsHost`/`ConnectionsHost`, not
+ * `DocumentsHost`.
+ *
+ * @module
+ */
+import { path } from "../http.js";
+import { unwrap } from "../types.js";
+/**
+ * The `console.vault` namespace on a `W6wClient`.
+ *
+ * @example
+ * ```ts
+ * const secrets = await client.console.vault.list();
+ * const created = await client.console.vault.create({ name: "openai_key", value: "sk-…" });
+ * await client.console.vault.update(created.id, { description: "Prod key" });
+ * const sealed = await client.console.vault.seal("sk-live-…");
+ * await client.console.vault.delete(created.id);
+ * ```
+ */
+export class VaultApi {
+    #host;
+    /**
+     * @param host - The client this namespace issues requests through.
+     */
+    constructor(host) {
+        this.#host = host;
+    }
+    /**
+     * List the account's vault secrets.
+     *
+     * @returns The secrets, unwrapped from the `secrets` envelope. Never
+     * carries `value`.
+     */
+    async list() {
+        const res = await this.#host.request({ method: "GET", path: "/vault" });
+        return unwrap(res, "secrets");
+    }
+    /**
+     * Fetch one secret's metadata.
+     *
+     * **Zero studio callers today** — built for SDK completeness only. No 404
+     * special-casing — propagates as `ApiError` like every other "get" in this
+     * package except `console.schedules.get`, which has its own documented,
+     * unrelated exception.
+     *
+     * @param id - The `sec_…` id.
+     * @returns The secret, unwrapped from the `secret` envelope. Never carries `value`.
+     * @throws {ApiError} `404 unknown_secret` when there is no such id.
+     */
+    async get(id) {
+        const res = await this.#host.request({ method: "GET", path: path `/vault/${id}` });
+        return unwrap(res, "secret");
+    }
+    /**
+     * Create a secret.
+     *
+     * `value` is opaque — forwarded verbatim, never inspected, logged, or
+     * transformed.
+     *
+     * @param body - `name` (unique, matches `^[a-z_][a-z0-9_]*$`), `value` (the
+     * plaintext to store), and an optional `description`.
+     * @returns The created secret, unwrapped from the `secret` envelope (the
+     * server answers `201`). Never carries `value`.
+     * @throws {ApiError} `400 invalid_name`/`invalid_value`/`invalid_description`; `409 secret_exists`.
+     */
+    async create(body) {
+        const res = await this.#host.request({ method: "POST", path: "/vault", body });
+        return unwrap(res, "secret");
+    }
+    /**
+     * Update a secret: replace its value and/or its description.
+     *
+     * `value` is opaque — forwarded verbatim, never inspected, logged, or
+     * transformed, same discipline as {@linkcode create}.
+     *
+     * @param id - The `sec_…` id.
+     * @param body - `value` and/or `description`, forwarded verbatim.
+     * @returns The updated secret, unwrapped from the `secret` envelope. Never carries `value`.
+     * @throws {ApiError} `400 invalid_value`/`invalid_description`; `404 unknown_secret`.
+     */
+    async update(id, body) {
+        const res = await this.#host.request({
+            method: "PATCH",
+            path: path `/vault/${id}`,
+            body,
+        });
+        return unwrap(res, "secret");
+    }
+    /**
+     * Delete a secret.
+     *
+     * Returns nothing: the server's `{ok: true}` carries no information a
+     * caller can use, mirroring `console.projects.delete`/
+     * `console.schedules.delete`/`console.connections.delete` in this same
+     * package (NOT `console.apps.delete`, which is the one documented
+     * exception) — vault delete has no such value to preserve.
+     *
+     * @param id - The `sec_…` id.
+     * @throws {ApiError} `404 unknown_secret` when there is no such id.
+     */
+    async delete(id) {
+        await this.#host.request({ method: "DELETE", path: path `/vault/${id}` });
+    }
+    /**
+     * Encrypt an ad-hoc secret value into an at-rest ciphertext envelope,
+     * without storing it.
+     *
+     * **An encrypt-only oracle — there is no matching decrypt route.** The
+     * server's own header comment states the security property directly: "an
+     * authed caller learns nothing they didn't provide." `value` is opaque —
+     * forwarded verbatim, never inspected, logged, or transformed. **No
+     * envelope key to peel on the request side** — the body IS `{ value }` —
+     * but the *response* IS enveloped under `sealed`, unlike `console.
+     * connections.test`'s/`console.reliability.list`'s whole-body responses.
+     *
+     * @param value - The plaintext to seal. Never logged, never echoed back.
+     * @returns The ciphertext envelope, unwrapped from the `sealed` envelope.
+     * @throws {ApiError} `400 invalid_value` when `value` is empty.
+     */
+    async seal(value) {
+        const res = await this.#host.request({
+            method: "POST",
+            path: "/vault/seal",
+            body: { value },
+        });
+        return unwrap(res, "sealed");
+    }
+}
+//# sourceMappingURL=vault.js.map

package/dist/src/console/vault.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault.js","sourceRoot":"","sources":["../../../src/console/vault.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAqB,IAAI,EAAuB,MAAM,YAAY,CAAC;AAC1E,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAkDrC;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,QAAQ;IACV,KAAK,CAAY;IAE1B;;OAEG;IACH,YAAY,IAAe;QACzB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,IAAI;QACR,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;QACjF,OAAO,MAAM,CAAuB,GAAG,EAAE,SAAS,CAAC,CAAC;IACtD,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,GAAG,CAAC,EAAU;QAClB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,CAAA,UAAU,EAAE,EAAE,EAAE,CAAC,CAAC;QAC3F,OAAO,MAAM,CAAqB,GAAG,EAAE,QAAQ,CAAC,CAAC;IACnD,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,MAAM,CACV,IAA2D;QAE3D,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QACxF,OAAO,MAAM,CAAqB,GAAG,EAAE,QAAQ,CAAC,CAAC;IACnD,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,MAAM,CACV,EAAU,EACV,IAA8C;QAE9C,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU;YAC5C,MAAM,EAAE,OAAO;YACf,IAAI,EAAE,IAAI,CAAA,UAAU,EAAE,EAAE;YACxB,IAAI;SACL,CAAC,CAAC;QACH,OAAO,MAAM,CAAqB,GAAG,EAAE,QAAQ,CAAC,CAAC;IACnD,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,MAAM,CAAC,EAAU;QACrB,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAA,UAAU,EAAE,EAAE,EAAE,CAAC,CAAC;IACpF,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,IAAI,CAAC,KAAa;QACtB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU;YAC5C,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,aAAa;YACnB,IAAI,EAAE,EAAE,KAAK,EAAE;SAChB,CAAC,CAAC;QACH,OAAO,MAAM,CAAc,GAAG,EAAE,QAAQ,CAAC,CAAC;IAC5C,CAAC;CACF"}

package/dist/src/console/workflows.d.ts

@@ -0,0 +1,243 @@
+/**
+ * `client.console.workflows.*` — the workflow definition/lifecycle and run
+ * surface (`get`, `upsert`, `archive`, `delete`, `listRuns`, `getRun`),
+ * relocated from the studio's own API client.
+ *
+ * **Studio-internal, not the published partner contract.** This namespace
+ * lives under the `console` subpath export (`@w6w/sdk/console`), excluded from
+ * `endpoints.json` and from the root barrel (`mod.ts`) — see `docs/console.md`
+ * and HITL-1 in this task's contract. `@w6w/sdk`'s instance-state mechanism
+ * pin still applies here exactly as it does to every other namespace
+ * (`docs/implementation.md` §MECHANISM PIN — instance state, never globals):
+ * this class holds no state of its own beyond the injected host, so two
+ * clients in one process never share a credential.
+ *
+ * **Console placement is the same precedent as `console.connections`'s
+ * `HITL-10`, not a fresh judgment call — see `HITL.md` and `plan.md`'s SP2.3
+ * section for the full investigation.** `endpoints.json`'s `outOfScope` array
+ * names "all write operations on connections and workflows" together, with the
+ * identical "in this version" framing HITL-10 already resolved for
+ * connections. The server routes here (`admin/workflows.ts`) are, like
+ * connections, plain stateless handlers over an already-resolved request
+ * body/precondition header — no interactive flow the SDK method itself would
+ * need to conduct. Console placement is safe for studio's own use; it does not
+ * by itself justify promotion to the partner surface (cli/python lockstep; no
+ * documented partner story exists yet either) — that promotion, if it ever
+ * happens, is a dedicated future project.
+ *
+ * **`list` and `run` are NOT part of this domain.** Both already exist on the
+ * BASE namespace (`client.workflows.list()`/`client.workflows.run()`,
+ * `../workflows.ts`) and studio reuses them verbatim — adding a duplicate
+ * `list`/`run` under `console.workflows` would give a caller two ways to reach
+ * the same route, exactly the anti-duplication defect this project's own
+ * rules flag. **No poll loop lives here either**: `../workflows.ts`'s own
+ * module doc pins "no client-side polling" for the whole package, and
+ * `getRun` below is deliberately a single request with no retry — the caller
+ * (studio's `lib/workflow-poll.ts`) owns the loop.
+ *
+ * Five of six methods relocate from the studio's `// Workflows` comment block
+ * (`packages/studio/src/api/client.ts:254-331`): `getWorkflow`→`get`,
+ * `createWorkflow`→`upsert`, `archiveWorkflow`→`archive`,
+ * `deleteWorkflow`→`delete`, `listRuns`→`listRuns`. `getRun` is genuinely NEW
+ * here — `client.ts`'s own `getRun` method is dead code today (zero callers),
+ * but this task gives it a real consumer: `runWorkflow`'s poll loop, ported
+ * into studio's `lib/workflow-poll.ts`, calls it.
+ *
+ * None of the six methods take a client-side default-project fallback — they
+ * are addressed by `wf_…`/`run_…` id (plus an optional explicit `?project=`
+ * on `upsert`), so `WorkflowsHost` needs only the transport, mirroring
+ * `SchedulesHost`/`ProjectsHost`, not the BASE `WorkflowsHost` (`../workflows.ts`),
+ * which additionally reads `config.project` as `list()`'s default.
+ *
+ * @module
+ */
+import { type HttpResponse, type RequestOptions } from "../http.ts";
+import { type RunStatus, type StepError } from "../types.ts";
+/**
+ * The slice of `W6wClient` this namespace needs: the transport, and nothing
+ * else. Structural rather than a concrete client type, so the namespace stays
+ * independently constructible in a test and this module never imports the
+ * client back — mirrors `SchedulesHost` in `./schedules.ts`.
+ */
+export interface WorkflowsHost {
+    /** Perform one request. */
+    request<T>(options: RequestOptions): Promise<HttpResponse<T>>;
+}
+/**
+ * A workflow run's full state, as `GET /runs/:id` returns it.
+ *
+ * Field-for-field, relocated from `packages/studio/src/api/types.ts:84-102`,
+ * with ONE deliberate deviation from studio's local shape: `error` and `steps`
+ * stay OPAQUE (`unknown`/`Record<string, unknown>`), matching this package's
+ * own documented philosophy for `RunResult` (`../types.ts` — "a client that
+ * modelled their internals would be wrong for someone"). Studio's local type
+ * typed `error` as a structured `{code,message,…}` and `steps` as
+ * `Record<string, StepExecution>`; that richer typing does not carry over
+ * here, on purpose, for consistency with every other run-shaped type in this
+ * package.
+ *
+ * Defined LOCALLY in this file, not in the shared `../types.ts`: it is
+ * consumed only by console methods, never by base `run()`/`list()`, mirroring
+ * where `Schedule`/`Project` live (inside their own `console/*.ts` files).
+ */
+export interface RunState {
+    /** Server-issued run handle, `run_…`. */
+    runId: string;
+    /** The workflow this run belongs to. */
+    workflowId: string;
+    /** Where the run has got to. */
+    status: RunStatus;
+    /** Variables the run was started with. Opaque pass-through. */
+    variables: Record<string, unknown>;
+    /** Per-step state, keyed by step id. Opaque pass-through. */
+    steps: Record<string, unknown>;
+    /** The run's output when it finished; absent while it is still going. */
+    output?: unknown;
+    /** The run-level error when it failed; absent otherwise. Data, never a raised exception. Opaque pass-through. */
+    error?: unknown;
+    /** Per-step failures, when the server reports them. */
+    stepErrors?: StepError[];
+}
+/**
+ * One row of `listRuns`'s result — a run's summary, not its full state.
+ *
+ * Field-for-field, relocated from `packages/studio/src/api/types.ts:84-102`
+ * (the summary subset). Defined LOCALLY, same reasoning as {@linkcode RunState}.
+ */
+export interface RunSummary {
+    /** Server-issued run handle, `run_…`. */
+    runId: string;
+    /** Where the run has got to. */
+    status: RunStatus;
+    /** What triggered this run, e.g. `"manual"`, `"schedule"`, `"webhook"`. */
+    trigger: string;
+    /** ISO-8601 timestamp. */
+    startedAt: string;
+    /** ISO-8601 timestamp, or `null` while the run is still going. */
+    finishedAt: string | null;
+}
+/**
+ * The `console.workflows` namespace on a `W6wClient`.
+ *
+ * @example
+ * ```ts
+ * const { workflow, updatedAt } = await client.console.workflows.get("wf_1");
+ * const saved = await client.console.workflows.upsert(workflow, { ifUnmodifiedSince: updatedAt });
+ * const runs = await client.console.workflows.listRuns("wf_1");
+ * const run = await client.console.workflows.getRun(runs[0].runId);
+ * await client.console.workflows.archive("wf_1");
+ * await client.console.workflows.delete("wf_1");
+ * ```
+ */
+export declare class WorkflowsApi {
+    #private;
+    /**
+     * @param host - The client this namespace issues requests through.
+     */
+    constructor(host: WorkflowsHost);
+    /**
+     * Fetch one workflow's stored definition.
+     *
+     * `workflow` is the merged definition (the stored definition overlaid with
+     * `status` and `tags`) — an arbitrary JSON object, never a fixed shape, kept
+     * as `Record<string, unknown>` exactly as `client.ts` typed it. `updatedAt`
+     * is TOP-LEVEL, never inside `workflow` — it is the optimistic-concurrency
+     * token a save echoes back via {@linkcode upsert}'s `ifUnmodifiedSince`.
+     *
+     * No 404 special-casing — propagates as `ApiError` like every other "get" in
+     * this package except `console.schedules.get`'s documented, unrelated
+     * exception.
+     *
+     * @param id - The `wf_…` id.
+     * @returns The whole response body — no envelope key to peel.
+     * @throws {ApiError} `404 unknown_workflow` when there is no such id.
+     */
+    get(id: string): Promise<{
+        workflow: Record<string, unknown>;
+        sourceRef: string | null;
+        updatedAt: string;
+    }>;
+    /**
+     * Register (create or overwrite) a workflow definition.
+     *
+     * `definition` is the whole definition, sent verbatim as the request body —
+     * not wrapped in an envelope key. `options.ifUnmodifiedSince` is the
+     * optional optimistic-concurrency precondition: pass the exact `updatedAt`
+     * this client last saw (from {@linkcode get}, or a prior `upsert`'s own
+     * `updatedAt`) and the server rejects the write with `409 workflow_stale` if
+     * the stored row has moved on since. Omitted, the save is last-write-wins
+     * and the header is never sent at all — never as an empty or `"null"`
+     * string, mirroring the server's own conditional exactly
+     * (`admin/workflows.ts`).
+     *
+     * @param definition - The whole workflow definition, forwarded verbatim.
+     * @param options - `project` scopes the write; `ifUnmodifiedSince` is the concurrency precondition.
+     * @returns The new/updated workflow's id and name, whether a schedule was (re)applied, and the new `updatedAt`.
+     * @throws {ApiError} `400 invalid_workflow`/`invalid_body`/`invalid_precondition`.
+     * @throws {ApiError} `409 workflow_conflict` — another `(tenant,subject)` owns this id. NOT recoverable by reloading.
+     * @throws {ApiError} `409 workflow_stale` — the precondition didn't match the stored `updatedAt`. IS recoverable by reloading and re-saving.
+     */
+    upsert(definition: unknown, options?: {
+        project?: string;
+        ifUnmodifiedSince?: string | null;
+    }): Promise<{
+        workflow: {
+            id: string;
+            name: string;
+        };
+        scheduled: boolean;
+        updatedAt: string;
+    }>;
+    /**
+     * Archive a workflow. One-way — no unarchive route exists anywhere on this
+     * domain.
+     *
+     * Idempotent: archiving an already-archived workflow re-returns it
+     * unchanged rather than erroring.
+     *
+     * @param id - The `wf_…` id.
+     * @returns The archived workflow — no envelope key to peel.
+     * @throws {ApiError} `404 unknown_workflow` when there is no such id.
+     */
+    archive(id: string): Promise<{
+        workflow: Record<string, unknown>;
+    }>;
+    /**
+     * Delete a workflow. Cascade-deletes its runs/schedules/subscriptions
+     * server-side; nothing for the caller to do about that.
+     *
+     * The server requires archive-then-delete — deleting a workflow whose status
+     * isn't `"archived"` yet answers `409 workflow_not_archived`, which this
+     * method does NOT catch. That is a real signal the caller must handle;
+     * enforcing archive-then-delete is not this method's job.
+     *
+     * Returns nothing: the server's `{ok: true}` carries no information a
+     * caller can use.
+     *
+     * @param id - The `wf_…` id.
+     * @throws {ApiError} `404 unknown_workflow` when there is no such id.
+     * @throws {ApiError} `409 workflow_not_archived` when the workflow exists but is not archived yet.
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * List a workflow's runs.
+     *
+     * @param id - The `wf_…` id.
+     * @returns The runs, unwrapped from the `runs` envelope.
+     * @throws {ApiError} `404 unknown_workflow` — an ownership gate: the workflow must belong to the caller.
+     */
+    listRuns(id: string): Promise<RunSummary[]>;
+    /**
+     * Fetch one run's full state.
+     *
+     * **One request, one answer — no polling, no `wait`, no retry.** The caller
+     * (studio's `lib/workflow-poll.ts`) owns the loop; see this module's header
+     * and `../workflows.ts`'s own "no client-side polling" pin.
+     *
+     * @param runId - The `run_…` id.
+     * @returns The run, unwrapped from the `run` envelope.
+     * @throws {ApiError} `404 unknown_run` — covers both "no such run" and "not your workflow"; the caller cannot and does not need to distinguish them.
+     */
+    getRun(runId: string): Promise<RunState>;
+}
+//# sourceMappingURL=workflows.d.ts.map

package/dist/src/console/workflows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflows.d.ts","sourceRoot":"","sources":["../../../src/console/workflows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAQ,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAC1E,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,SAAS,EAAU,MAAM,aAAa,CAAC;AAKrE;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,2BAA2B;IAC3B,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;CAC/D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,QAAQ;IACvB,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,MAAM,EAAE,SAAS,CAAC;IAClB,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,yEAAyE;IACzE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,iHAAiH;IACjH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,uDAAuD;IACvD,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,MAAM,EAAE,SAAS,CAAC;IAClB,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,YAAY;;IAGvB;;OAEG;gBACS,IAAI,EAAE,aAAa;IAI/B;;;;;;;;;;;;;;;;OAgBG;IACG,GAAG,CACP,EAAE,EAAE,MAAM,GACT,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAU9F;;;;;;;;;;;;;;;;;;;OAmBG;IACG,MAAM,CACV,UAAU,EAAE,OAAO,EACnB,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAChE,OAAO,CAAC;QAAE,QAAQ,EAAE;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC;QAAC,SAAS,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAe7F;;;;;;;;;;OAUG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;IAQzE;;;;;;;;;;;;;;;OAeG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvC;;;;;;OAMG;IACG,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAQjD;;;;;;;;;;OAUG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;CAO/C"}

package/dist/src/console/workflows.js

@@ -0,0 +1,205 @@
+/**
+ * `client.console.workflows.*` — the workflow definition/lifecycle and run
+ * surface (`get`, `upsert`, `archive`, `delete`, `listRuns`, `getRun`),
+ * relocated from the studio's own API client.
+ *
+ * **Studio-internal, not the published partner contract.** This namespace
+ * lives under the `console` subpath export (`@w6w/sdk/console`), excluded from
+ * `endpoints.json` and from the root barrel (`mod.ts`) — see `docs/console.md`
+ * and HITL-1 in this task's contract. `@w6w/sdk`'s instance-state mechanism
+ * pin still applies here exactly as it does to every other namespace
+ * (`docs/implementation.md` §MECHANISM PIN — instance state, never globals):
+ * this class holds no state of its own beyond the injected host, so two
+ * clients in one process never share a credential.
+ *
+ * **Console placement is the same precedent as `console.connections`'s
+ * `HITL-10`, not a fresh judgment call — see `HITL.md` and `plan.md`'s SP2.3
+ * section for the full investigation.** `endpoints.json`'s `outOfScope` array
+ * names "all write operations on connections and workflows" together, with the
+ * identical "in this version" framing HITL-10 already resolved for
+ * connections. The server routes here (`admin/workflows.ts`) are, like
+ * connections, plain stateless handlers over an already-resolved request
+ * body/precondition header — no interactive flow the SDK method itself would
+ * need to conduct. Console placement is safe for studio's own use; it does not
+ * by itself justify promotion to the partner surface (cli/python lockstep; no
+ * documented partner story exists yet either) — that promotion, if it ever
+ * happens, is a dedicated future project.
+ *
+ * **`list` and `run` are NOT part of this domain.** Both already exist on the
+ * BASE namespace (`client.workflows.list()`/`client.workflows.run()`,
+ * `../workflows.ts`) and studio reuses them verbatim — adding a duplicate
+ * `list`/`run` under `console.workflows` would give a caller two ways to reach
+ * the same route, exactly the anti-duplication defect this project's own
+ * rules flag. **No poll loop lives here either**: `../workflows.ts`'s own
+ * module doc pins "no client-side polling" for the whole package, and
+ * `getRun` below is deliberately a single request with no retry — the caller
+ * (studio's `lib/workflow-poll.ts`) owns the loop.
+ *
+ * Five of six methods relocate from the studio's `// Workflows` comment block
+ * (`packages/studio/src/api/client.ts:254-331`): `getWorkflow`→`get`,
+ * `createWorkflow`→`upsert`, `archiveWorkflow`→`archive`,
+ * `deleteWorkflow`→`delete`, `listRuns`→`listRuns`. `getRun` is genuinely NEW
+ * here — `client.ts`'s own `getRun` method is dead code today (zero callers),
+ * but this task gives it a real consumer: `runWorkflow`'s poll loop, ported
+ * into studio's `lib/workflow-poll.ts`, calls it.
+ *
+ * None of the six methods take a client-side default-project fallback — they
+ * are addressed by `wf_…`/`run_…` id (plus an optional explicit `?project=`
+ * on `upsert`), so `WorkflowsHost` needs only the transport, mirroring
+ * `SchedulesHost`/`ProjectsHost`, not the BASE `WorkflowsHost` (`../workflows.ts`),
+ * which additionally reads `config.project` as `list()`'s default.
+ *
+ * @module
+ */
+import { path } from "../http.js";
+import { unwrap } from "../types.js";
+/** The precondition header `upsert` sends when `ifUnmodifiedSince` is given. */
+const PRECONDITION_HEADER = "x-w6w-if-unmodified-since";
+/**
+ * The `console.workflows` namespace on a `W6wClient`.
+ *
+ * @example
+ * ```ts
+ * const { workflow, updatedAt } = await client.console.workflows.get("wf_1");
+ * const saved = await client.console.workflows.upsert(workflow, { ifUnmodifiedSince: updatedAt });
+ * const runs = await client.console.workflows.listRuns("wf_1");
+ * const run = await client.console.workflows.getRun(runs[0].runId);
+ * await client.console.workflows.archive("wf_1");
+ * await client.console.workflows.delete("wf_1");
+ * ```
+ */
+export class WorkflowsApi {
+    #host;
+    /**
+     * @param host - The client this namespace issues requests through.
+     */
+    constructor(host) {
+        this.#host = host;
+    }
+    /**
+     * Fetch one workflow's stored definition.
+     *
+     * `workflow` is the merged definition (the stored definition overlaid with
+     * `status` and `tags`) — an arbitrary JSON object, never a fixed shape, kept
+     * as `Record<string, unknown>` exactly as `client.ts` typed it. `updatedAt`
+     * is TOP-LEVEL, never inside `workflow` — it is the optimistic-concurrency
+     * token a save echoes back via {@linkcode upsert}'s `ifUnmodifiedSince`.
+     *
+     * No 404 special-casing — propagates as `ApiError` like every other "get" in
+     * this package except `console.schedules.get`'s documented, unrelated
+     * exception.
+     *
+     * @param id - The `wf_…` id.
+     * @returns The whole response body — no envelope key to peel.
+     * @throws {ApiError} `404 unknown_workflow` when there is no such id.
+     */
+    async get(id) {
+        const res = await this.#host.request({
+            method: "GET",
+            path: path `/workflows/${id}`,
+        });
+        return res.body;
+    }
+    /**
+     * Register (create or overwrite) a workflow definition.
+     *
+     * `definition` is the whole definition, sent verbatim as the request body —
+     * not wrapped in an envelope key. `options.ifUnmodifiedSince` is the
+     * optional optimistic-concurrency precondition: pass the exact `updatedAt`
+     * this client last saw (from {@linkcode get}, or a prior `upsert`'s own
+     * `updatedAt`) and the server rejects the write with `409 workflow_stale` if
+     * the stored row has moved on since. Omitted, the save is last-write-wins
+     * and the header is never sent at all — never as an empty or `"null"`
+     * string, mirroring the server's own conditional exactly
+     * (`admin/workflows.ts`).
+     *
+     * @param definition - The whole workflow definition, forwarded verbatim.
+     * @param options - `project` scopes the write; `ifUnmodifiedSince` is the concurrency precondition.
+     * @returns The new/updated workflow's id and name, whether a schedule was (re)applied, and the new `updatedAt`.
+     * @throws {ApiError} `400 invalid_workflow`/`invalid_body`/`invalid_precondition`.
+     * @throws {ApiError} `409 workflow_conflict` — another `(tenant,subject)` owns this id. NOT recoverable by reloading.
+     * @throws {ApiError} `409 workflow_stale` — the precondition didn't match the stored `updatedAt`. IS recoverable by reloading and re-saving.
+     */
+    async upsert(definition, options) {
+        const res = await this.#host.request({
+            method: "POST",
+            path: "/workflows",
+            query: { project: options?.project },
+            body: definition,
+            ...(options?.ifUnmodifiedSince
+                ? { headers: { [PRECONDITION_HEADER]: options.ifUnmodifiedSince } }
+                : {}),
+        });
+        return res.body;
+    }
+    /**
+     * Archive a workflow. One-way — no unarchive route exists anywhere on this
+     * domain.
+     *
+     * Idempotent: archiving an already-archived workflow re-returns it
+     * unchanged rather than erroring.
+     *
+     * @param id - The `wf_…` id.
+     * @returns The archived workflow — no envelope key to peel.
+     * @throws {ApiError} `404 unknown_workflow` when there is no such id.
+     */
+    async archive(id) {
+        const res = await this.#host.request({
+            method: "POST",
+            path: path `/workflows/${id}/archive`,
+        });
+        return res.body;
+    }
+    /**
+     * Delete a workflow. Cascade-deletes its runs/schedules/subscriptions
+     * server-side; nothing for the caller to do about that.
+     *
+     * The server requires archive-then-delete — deleting a workflow whose status
+     * isn't `"archived"` yet answers `409 workflow_not_archived`, which this
+     * method does NOT catch. That is a real signal the caller must handle;
+     * enforcing archive-then-delete is not this method's job.
+     *
+     * Returns nothing: the server's `{ok: true}` carries no information a
+     * caller can use.
+     *
+     * @param id - The `wf_…` id.
+     * @throws {ApiError} `404 unknown_workflow` when there is no such id.
+     * @throws {ApiError} `409 workflow_not_archived` when the workflow exists but is not archived yet.
+     */
+    async delete(id) {
+        await this.#host.request({ method: "DELETE", path: path `/workflows/${id}` });
+    }
+    /**
+     * List a workflow's runs.
+     *
+     * @param id - The `wf_…` id.
+     * @returns The runs, unwrapped from the `runs` envelope.
+     * @throws {ApiError} `404 unknown_workflow` — an ownership gate: the workflow must belong to the caller.
+     */
+    async listRuns(id) {
+        const res = await this.#host.request({
+            method: "GET",
+            path: path `/workflows/${id}/runs`,
+        });
+        return unwrap(res, "runs");
+    }
+    /**
+     * Fetch one run's full state.
+     *
+     * **One request, one answer — no polling, no `wait`, no retry.** The caller
+     * (studio's `lib/workflow-poll.ts`) owns the loop; see this module's header
+     * and `../workflows.ts`'s own "no client-side polling" pin.
+     *
+     * @param runId - The `run_…` id.
+     * @returns The run, unwrapped from the `run` envelope.
+     * @throws {ApiError} `404 unknown_run` — covers both "no such run" and "not your workflow"; the caller cannot and does not need to distinguish them.
+     */
+    async getRun(runId) {
+        const res = await this.#host.request({
+            method: "GET",
+            path: path `/runs/${runId}`,
+        });
+        return unwrap(res, "run");
+    }
+}
+//# sourceMappingURL=workflows.js.map

package/dist/src/console/workflows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflows.js","sourceRoot":"","sources":["../../../src/console/workflows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH,OAAO,EAAqB,IAAI,EAAuB,MAAM,YAAY,CAAC;AAC1E,OAAO,EAAkC,MAAM,EAAE,MAAM,aAAa,CAAC;AAErE,gFAAgF;AAChF,MAAM,mBAAmB,GAAG,2BAA2B,CAAC;AAoExD;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,YAAY;IACd,KAAK,CAAgB;IAE9B;;OAEG;IACH,YAAY,IAAmB;QAC7B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,CAAC,GAAG,CACP,EAAU;QAEV,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAElC;YACA,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,IAAI,CAAA,cAAc,EAAE,EAAE;SAC7B,CAAC,CAAC;QACH,OAAO,GAAG,CAAC,IAAI,CAAC;IAClB,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,KAAK,CAAC,MAAM,CACV,UAAmB,EACnB,OAAiE;QAEjE,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAElC;YACA,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,YAAY;YAClB,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE;YACpC,IAAI,EAAE,UAAU;YAChB,GAAG,CAAC,OAAO,EAAE,iBAAiB;gBAC5B,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC,iBAAiB,EAAE,EAAE;gBACnE,CAAC,CAAC,EAAE,CAAC;SACR,CAAC,CAAC;QACH,OAAO,GAAG,CAAC,IAAI,CAAC;IAClB,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,OAAO,CAAC,EAAU;QACtB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAwC;YAC1E,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,IAAI,CAAA,cAAc,EAAE,UAAU;SACrC,CAAC,CAAC;QACH,OAAO,GAAG,CAAC,IAAI,CAAC;IAClB,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,MAAM,CAAC,EAAU;QACrB,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAA,cAAc,EAAE,EAAE,EAAE,CAAC,CAAC;IACxF,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,QAAQ,CAAC,EAAU;QACvB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU;YAC5C,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,IAAI,CAAA,cAAc,EAAE,OAAO;SAClC,CAAC,CAAC;QACH,OAAO,MAAM,CAAe,GAAG,EAAE,MAAM,CAAC,CAAC;IAC3C,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,MAAM,CAAC,KAAa;QACxB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU;YAC5C,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,IAAI,CAAA,SAAS,KAAK,EAAE;SAC3B,CAAC,CAAC;QACH,OAAO,MAAM,CAAW,GAAG,EAAE,KAAK,CAAC,CAAC;IACtC,CAAC;CACF"}