@w6w/sdk 0.1.0

package/dist/src/types.d.ts

@@ -0,0 +1,362 @@
+/**
+ * Wire types, transcribed — plus the one envelope reader every operation uses.
+ *
+ * The shapes below are **transcribed** from `docs/implementation.md` §5 (which
+ * reads them off the studio's API types), not imported or vendored from it: this
+ * package publishes to npm and JSR and cannot depend on a private workspace
+ * source. Field names are the wire's, verbatim — no camel/snake drift, no
+ * renaming, no "nicer" aliases. A client that quietly renames a wire field makes
+ * every error message and every documentation example wrong.
+ *
+ * Unknown fields are **tolerated, never rejected**: these are `interface`s, so a
+ * field the server adds tomorrow simply arrives and is ignored by an older
+ * client. Nothing here validates a response against a closed schema.
+ *
+ * Every exported member carries an explicit type — JSR publishes this file as
+ * TypeScript source and rejects inferred public types ("no slow types",
+ * `docs/implementation.md` §1).
+ *
+ * @module
+ */
+import type { HttpResponse } from "./http.ts";
+/**
+ * A document's format hint.
+ *
+ * A **hint only**: it does not gate the content, which the server stores
+ * verbatim and never parses. Defaults to `"text"` server-side when a create
+ * omits it.
+ */
+export type DocFormat = "text" | "markdown" | "yaml" | "html" | "json";
+/**
+ * A document — a keyed blob of text in a project's document store.
+ *
+ * `id` is the server-issued `doc_…` handle used for update and delete; `key` is
+ * the human-chosen name used at create time (and by `documents.getByKey`).
+ * `key` is **immutable** — it is not in any patch body
+ * (`docs/implementation.md` §7).
+ *
+ * Timestamps are ISO-8601 **strings**, exactly as they arrive. They are not
+ * parsed into `Date`: date parsing is a policy that would have to be identical
+ * in three languages and reversible for round-trips, so the wrappers adopt it
+ * together or not at all.
+ */
+export interface Doc {
+    /** Server-issued id, `doc_…`. Addresses update and delete. */
+    id: string;
+    /** Caller-chosen key: non-empty, ≤128 characters, unique per scope + project. */
+    key: string;
+    /** Raw text. Stored verbatim and never parsed by the server. */
+    content: string;
+    /** Format hint. */
+    format: DocFormat;
+    /** Free-text description; `""` when unset. */
+    description: string;
+    /** ISO-8601 timestamp. */
+    createdAt: string;
+    /** ISO-8601 timestamp. */
+    updatedAt: string;
+}
+/** A variable's declared type. `value` is validated against it **server-side**. */
+export type VarType = "string" | "number" | "boolean" | "json";
+/**
+ * A typed variable, scoped by tenant/subject.
+ *
+ * `value` is **`unknown`** on purpose: it is whatever the declared
+ * {@linkcode VarType} allows, including an arbitrary JSON document, and a
+ * wrapper that modelled its internals would be wrong for someone. Narrow it at
+ * the call site after checking `type`.
+ */
+export interface Var {
+    /** Server-issued id, `var_…`. Addresses update and delete. */
+    id: string;
+    /** Caller-chosen name, matching `^[a-z_][a-z0-9_]*$`. Immutable. */
+    name: string;
+    /** Declared type. */
+    type: VarType;
+    /** The value, opaque pass-through. */
+    value: unknown;
+    /** Free-text description; `""` when unset. */
+    description: string;
+    /** ISO-8601 timestamp. */
+    createdAt: string;
+    /** ISO-8601 timestamp. */
+    updatedAt: string;
+}
+/**
+ * Who the caller is, plus the versions of the components that answered.
+ *
+ * The body is **flat**: the identity fields sit at the top level, with no
+ * wrapping object around them. That is the contract, not an accident of this
+ * transcription — `client.me()` calls `/auth/me`, the server's real identity
+ * handler, whose live consumer is the studio, so a nested envelope would break
+ * that consumer (`docs/endpoints.md` §1, D15). Nothing in this file unwraps a
+ * `me` response, because there is nothing to unwrap.
+ *
+ * The four identity fields mirror the server's principal.
+ */
+export interface Me {
+    /** Tenant the caller belongs to. */
+    tenant: string;
+    /** The authenticated subject (a user or a machine principal). */
+    subject: string;
+    /** Account the caller is acting in. */
+    account: string;
+    /** The caller's role within that account. */
+    role: string;
+    /**
+     * Component versions, e.g. `{composition: "server@1a2b3c4 …", wrapper: "0.1.0"}`.
+     *
+     * **Optional and open.** It may be absent entirely (an older server), and it
+     * may carry keys this release has never heard of — so it is typed as a string
+     * map and never as a closed record: adding a key server-side must not break an
+     * installed client. `wrapper` is filled in by this package from its own
+     * `VERSION` (`src/me.ts`); the server cannot know it.
+     */
+    versions?: Record<string, string>;
+}
+/**
+ * Lifecycle state of a connection.
+ *
+ * A closed union because it is the server's own enum and a caller switches on
+ * it; unknown *fields* are tolerated everywhere in this file, but a new state
+ * would be a server change that the wrapper version-bumps with.
+ */
+export type ConnectionState = "pending" | "connected" | "needs_refresh" | "broken" | "revoked";
+/**
+ * A connection, as the list route projects it.
+ *
+ * **Two fields the stored record has are deliberately absent here**: the secret
+ * material and its last-refresh timestamp are redacted server-side and never
+ * reach a client. Declaring them would promise a caller a field that can never
+ * arrive — and would invite exactly the code path (`if (c.…)`) that this
+ * omission makes impossible to write (`docs/endpoints.md` §2).
+ *
+ * Timestamps are ISO-8601 strings, exactly as they arrive; `lastTestOk` and
+ * `lastTestedAt` are `null` until the connection has been tested once.
+ */
+export interface ConnectionSummary {
+    /** Server-issued id, `conn_…`. This is the handle a URN addresses. */
+    id: string;
+    /** The app this connection authenticates against, e.g. `"sendgrid"`. */
+    appId: string;
+    /** Which of the app's auth methods this connection uses. */
+    authKey: string;
+    /** The subject that owns the connection. */
+    owner: string;
+    /** Human-chosen label. */
+    displayName: string;
+    /** Lifecycle state. */
+    state: ConnectionState;
+    /** Non-secret profile data the app captured at connect time; opaque pass-through. */
+    profile: Record<string, unknown>;
+    /** Result of the last connection test; `null` when it has never been tested. */
+    lastTestOk: boolean | null;
+    /** ISO-8601 timestamp of the last test, or `null`. */
+    lastTestedAt: string | null;
+    /** ISO-8601 timestamp. */
+    createdAt: string;
+    /** ISO-8601 timestamp. */
+    updatedAt: string;
+}
+/** Lifecycle state of a workflow: an editable draft, or a published live one. */
+export type WorkflowStatus = "draft" | "active";
+/**
+ * A workflow definition, as the list route projects it.
+ *
+ * `name` is the stable slug the workflow was registered under; `displayName` is
+ * the label a human reads. Both are present on the wire and neither is derived
+ * from the other, so both are kept.
+ */
+export interface WorkflowSummary {
+    /** Server-issued id, `wf_…`. This is the handle a URN addresses. */
+    id: string;
+    /** Stable slug, e.g. `"welcome-email"`. */
+    name: string;
+    /** Human-readable label. */
+    displayName: string;
+    /** Free-text description; `""` when unset. */
+    description: string;
+    /** Lifecycle state. */
+    status: WorkflowStatus;
+    /** Free-form labels. */
+    tags: string[];
+    /** Total number of runs this workflow has accumulated. */
+    runCount: number;
+    /** ISO-8601 timestamp. */
+    updatedAt: string;
+}
+/**
+ * Lifecycle state of a run.
+ *
+ * `queued` and `running` are in-flight; `succeeded`, `failed` and `canceled`
+ * are terminal (see {@linkcode isTerminalRunStatus}). **`failed` is a status,
+ * not an error**: a run that failed comes back as a normal `200` carrying this
+ * value, and no operation in this package raises on it
+ * (`docs/implementation.md` §4).
+ */
+export type RunStatus = "queued" | "running" | "succeeded" | "failed" | "canceled";
+/** One step's failure inside a run. `error` is opaque pass-through. */
+export interface StepError {
+    /** Id of the step that failed. */
+    stepId: string;
+    /** Whatever the step reported; shape belongs to the app, not to this client. */
+    error: unknown;
+}
+/**
+ * A workflow run: the handle, its state, and the result when it has one.
+ *
+ * A `202` body carries only `runId` + `status` — the run is queued or still
+ * going — while a `200` additionally carries `output`, `error` and `steps`.
+ * The optional fields are optional for exactly that reason.
+ *
+ * `output`, `error` and the values in `steps` are **opaque pass-through**
+ * (`unknown`): they come from user workflows and vendor apps, and a client that
+ * modelled their internals would be wrong for someone. `steps` is a map **keyed
+ * by step id**, not an array (`docs/implementation.md` §5).
+ */
+export interface RunResult {
+    /** Server-issued run handle, `run_…`. Present on every response, queued included. */
+    runId: string;
+    /** Where the run has got to. */
+    status: RunStatus;
+    /** 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. */
+    error?: unknown;
+    /** Per-step state, keyed by step id. `{}` when the server sent none. */
+    steps: Record<string, unknown>;
+    /** Per-step failures, when the server reports them. */
+    stepErrors?: StepError[];
+}
+/** `run` resolved a `conn_…` URN and executed an app action. HTTP `200`. */
+export interface ActionRunEnvelope {
+    kind: "action";
+    /** The action's return value. Opaque pass-through. */
+    value: unknown;
+}
+/** `run` resolved a `fn_…` / `ep_…` URN and executed it. HTTP `200`. */
+export interface FunctionRunEnvelope {
+    kind: "function";
+    /** The function's output. Opaque pass-through. */
+    output: unknown;
+}
+/**
+ * `run` resolved a `wf_…` URN and enqueued a workflow run. HTTP `202`.
+ *
+ * `202` is **success**: the run is queued, and `runId` is how the caller follows
+ * it. There is no `?wait=` on this operation — use `workflows.run` for that (D4).
+ */
+export interface WorkflowRunEnvelope {
+    kind: "workflow";
+    /** Server-issued run handle. */
+    runId: string;
+    /** Where the run has got to; `"queued"` immediately after dispatch. */
+    status: RunStatus;
+}
+/**
+ * A `kind` this release has never heard of, handed back verbatim.
+ *
+ * The server may grow a fourth `kind` before the wrappers do — a purely
+ * additive change on the one operation whose entire job is dispatch. This arm
+ * is what keeps that additive change from becoming a hard breakage for every
+ * user of an installed version: the parsed body is returned as it arrived,
+ * `kind` and all sibling fields intact, and nothing raises
+ * (`docs/implementation.md` §5).
+ */
+export type UnknownRunEnvelope = {
+    kind: string;
+} & Record<string, unknown>;
+/**
+ * What `client.run()` returns: three known arms plus an open one.
+ *
+ * `value` (action) and `output` (function) are **deliberately different names**
+ * for the two synchronous arms and are never normalised into one field — the
+ * discrimination is the point (D3).
+ *
+ * **The union is open, and narrowing on `kind` alone does not work.** Because
+ * the fourth arm admits any `kind: string`, a bare `env.kind === "workflow"`
+ * check leaves `env.status` typed `unknown` under `--strict`, not `RunStatus`.
+ * That is a property of the open union, not a bug in it: closing the union would
+ * make an unknown `kind` unrepresentable and the pinned "return the raw
+ * envelope" behaviour un-typeable. Use the guards below, which narrow properly:
+ *
+ * @example
+ * ```ts
+ * const env = await client.run({ urn: "wf_01HQ" });
+ * if (isActionRun(env)) console.log(env.value);
+ * else if (isFunctionRun(env)) console.log(env.output);
+ * else if (isWorkflowRun(env)) console.log(env.runId, env.status);
+ * else console.log("a kind this SDK version does not know:", env.kind, env);
+ * ```
+ */
+export type RunEnvelope = ActionRunEnvelope | FunctionRunEnvelope | WorkflowRunEnvelope | UnknownRunEnvelope;
+/**
+ * Is this the `action` arm? Narrows to {@linkcode ActionRunEnvelope}, so
+ * `env.value` is reachable and typed inside the branch.
+ *
+ * @param env - Any envelope `run` returned.
+ * @returns `true` when `kind` is `"action"`.
+ */
+export declare function isActionRun(env: RunEnvelope): env is ActionRunEnvelope;
+/**
+ * Is this the `function` arm? Narrows to {@linkcode FunctionRunEnvelope}, so
+ * `env.output` is reachable and typed inside the branch.
+ *
+ * @param env - Any envelope `run` returned.
+ * @returns `true` when `kind` is `"function"`.
+ */
+export declare function isFunctionRun(env: RunEnvelope): env is FunctionRunEnvelope;
+/**
+ * Is this the `workflow` arm? Narrows to {@linkcode WorkflowRunEnvelope}, so
+ * `env.runId` and `env.status` are reachable and typed inside the branch.
+ *
+ * @param env - Any envelope `run` returned.
+ * @returns `true` when `kind` is `"workflow"`.
+ */
+export declare function isWorkflowRun(env: RunEnvelope): env is WorkflowRunEnvelope;
+/**
+ * Has a run reached a state it will not leave?
+ *
+ * Exported because it is the same question `workflows.run`'s `terminal` flag
+ * answers, and a caller polling a `202` handle on its own schedule needs it
+ * too. It reads the **run's** status rather than an HTTP code: a `202` can carry
+ * `queued` or `running`, and the answer is about the run, not the transport.
+ *
+ * @param status - A run status.
+ * @returns `true` for `succeeded`, `failed` and `canceled`.
+ */
+export declare function isTerminalRunStatus(status: RunStatus): boolean;
+/**
+ * Read one payload out of the server's envelope, or fail loudly.
+ *
+ * The server wraps every asset body under a key — `{documents: […]}`,
+ * `{document: …}`, `{vars: […]}`, `{var: …}` — and the wrapper's contract is to
+ * hand the caller the payload, never the wrapper (`docs/implementation.md` §6).
+ *
+ * A `2xx` body **missing** that key is a `bad_response`-class bug and raises,
+ * rather than returning `undefined`. That is the pinned behaviour, and the
+ * reason is worth keeping next to the code: three wrappers each returning a
+ * silent `undefined` here would turn a server regression into a `TypeError`
+ * thrown somewhere in the caller's code, minutes later, with nothing pointing
+ * back at the response that caused it.
+ *
+ * This is the *only* place an operation module inspects a body's shape. It is
+ * not schema validation: extra keys are ignored, and the payload itself is cast,
+ * never checked.
+ *
+ * A key present but carrying **`null`** counts as missing, for exactly the same
+ * reason: `{"document": null}` resolved `documents.get()` to `null` typed `Doc`
+ * (measured), which is precisely the deferred `TypeError` in the caller that the
+ * paragraph above says this function exists to prevent. The check is therefore
+ * `!= null`, not `!== undefined`. The python lane stops the same body one level
+ * further in (`unwrap_object`); what both lanes agree on is that it raises
+ * `bad_response` with the status still in hand, rather than reaching the caller.
+ *
+ * @param res - The response returned by the transport.
+ * @param key - The envelope key to read, e.g. `"document"`, `"vars"`.
+ * @returns The unwrapped payload.
+ * @throws {ApiError} `bad_response` when the body is not an object, or lacks the
+ * key, or the key is `null`.
+ */
+export declare function unwrap<T>(res: HttpResponse<unknown>, key: string): T;
+//# sourceMappingURL=types.d.ts.map

package/dist/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/dist/src/types.js

@@ -0,0 +1,109 @@
+/**
+ * Wire types, transcribed — plus the one envelope reader every operation uses.
+ *
+ * The shapes below are **transcribed** from `docs/implementation.md` §5 (which
+ * reads them off the studio's API types), not imported or vendored from it: this
+ * package publishes to npm and JSR and cannot depend on a private workspace
+ * source. Field names are the wire's, verbatim — no camel/snake drift, no
+ * renaming, no "nicer" aliases. A client that quietly renames a wire field makes
+ * every error message and every documentation example wrong.
+ *
+ * Unknown fields are **tolerated, never rejected**: these are `interface`s, so a
+ * field the server adds tomorrow simply arrives and is ignored by an older
+ * client. Nothing here validates a response against a closed schema.
+ *
+ * Every exported member carries an explicit type — JSR publishes this file as
+ * TypeScript source and rejects inferred public types ("no slow types",
+ * `docs/implementation.md` §1).
+ *
+ * @module
+ */
+import { ApiError } from "./errors.js";
+/**
+ * Is this the `action` arm? Narrows to {@linkcode ActionRunEnvelope}, so
+ * `env.value` is reachable and typed inside the branch.
+ *
+ * @param env - Any envelope `run` returned.
+ * @returns `true` when `kind` is `"action"`.
+ */
+export function isActionRun(env) {
+    return env.kind === "action";
+}
+/**
+ * Is this the `function` arm? Narrows to {@linkcode FunctionRunEnvelope}, so
+ * `env.output` is reachable and typed inside the branch.
+ *
+ * @param env - Any envelope `run` returned.
+ * @returns `true` when `kind` is `"function"`.
+ */
+export function isFunctionRun(env) {
+    return env.kind === "function";
+}
+/**
+ * Is this the `workflow` arm? Narrows to {@linkcode WorkflowRunEnvelope}, so
+ * `env.runId` and `env.status` are reachable and typed inside the branch.
+ *
+ * @param env - Any envelope `run` returned.
+ * @returns `true` when `kind` is `"workflow"`.
+ */
+export function isWorkflowRun(env) {
+    return env.kind === "workflow";
+}
+/**
+ * Has a run reached a state it will not leave?
+ *
+ * Exported because it is the same question `workflows.run`'s `terminal` flag
+ * answers, and a caller polling a `202` handle on its own schedule needs it
+ * too. It reads the **run's** status rather than an HTTP code: a `202` can carry
+ * `queued` or `running`, and the answer is about the run, not the transport.
+ *
+ * @param status - A run status.
+ * @returns `true` for `succeeded`, `failed` and `canceled`.
+ */
+export function isTerminalRunStatus(status) {
+    return status === "succeeded" || status === "failed" || status === "canceled";
+}
+/**
+ * Read one payload out of the server's envelope, or fail loudly.
+ *
+ * The server wraps every asset body under a key — `{documents: […]}`,
+ * `{document: …}`, `{vars: […]}`, `{var: …}` — and the wrapper's contract is to
+ * hand the caller the payload, never the wrapper (`docs/implementation.md` §6).
+ *
+ * A `2xx` body **missing** that key is a `bad_response`-class bug and raises,
+ * rather than returning `undefined`. That is the pinned behaviour, and the
+ * reason is worth keeping next to the code: three wrappers each returning a
+ * silent `undefined` here would turn a server regression into a `TypeError`
+ * thrown somewhere in the caller's code, minutes later, with nothing pointing
+ * back at the response that caused it.
+ *
+ * This is the *only* place an operation module inspects a body's shape. It is
+ * not schema validation: extra keys are ignored, and the payload itself is cast,
+ * never checked.
+ *
+ * A key present but carrying **`null`** counts as missing, for exactly the same
+ * reason: `{"document": null}` resolved `documents.get()` to `null` typed `Doc`
+ * (measured), which is precisely the deferred `TypeError` in the caller that the
+ * paragraph above says this function exists to prevent. The check is therefore
+ * `!= null`, not `!== undefined`. The python lane stops the same body one level
+ * further in (`unwrap_object`); what both lanes agree on is that it raises
+ * `bad_response` with the status still in hand, rather than reaching the caller.
+ *
+ * @param res - The response returned by the transport.
+ * @param key - The envelope key to read, e.g. `"document"`, `"vars"`.
+ * @returns The unwrapped payload.
+ * @throws {ApiError} `bad_response` when the body is not an object, or lacks the
+ * key, or the key is `null`.
+ */
+export function unwrap(res, key) {
+    const body = res.body;
+    if (typeof body === "object" && body !== null) {
+        const value = body[key];
+        // Both arms are load-bearing: absent AND null are "the server did not send
+        // what it promised", and only one of them used to be caught.
+        if (value !== undefined && value !== null)
+            return value;
+    }
+    throw new ApiError(res.status, "bad_response", `Server returned a ${res.status} with no "${key}" in the response body.`, body);
+}
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAqSvC;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,GAAgB;IAC1C,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC;AAC/B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,GAAgB;IAC5C,OAAO,GAAG,CAAC,IAAI,KAAK,UAAU,CAAC;AACjC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,GAAgB;IAC5C,OAAO,GAAG,CAAC,IAAI,KAAK,UAAU,CAAC;AACjC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAiB;IACnD,OAAO,MAAM,KAAK,WAAW,IAAI,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,UAAU,CAAC;AAChF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,MAAM,CAAI,GAA0B,EAAE,GAAW;IAC/D,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;IACtB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAC9C,MAAM,KAAK,GAAI,IAAgC,CAAC,GAAG,CAAC,CAAC;QACrD,2EAA2E;QAC3E,6DAA6D;QAC7D,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,KAAU,CAAC;IAC/D,CAAC;IACD,MAAM,IAAI,QAAQ,CAChB,GAAG,CAAC,MAAM,EACV,cAAc,EACd,qBAAqB,GAAG,CAAC,MAAM,aAAa,GAAG,yBAAyB,EACxE,IAAI,CACL,CAAC;AACJ,CAAC"}

package/dist/src/vars.d.ts

@@ -0,0 +1,149 @@
+/**
+ * `client.vars.*` — typed variables, addressed the way the server addresses
+ * them.
+ *
+ * Six operations, one HTTP call each. **Create by `name`, read by id or by
+ * name, update and delete by id** (`docs/implementation.md` §7, D6 amended by
+ * D12). No client-side list-then-filter: `getByName` targets a real route,
+ * `GET /vars/by-name/{name}` (verified live 2026-07-28).
+ *
+ * **There is no scoping query parameter on any variable operation, and this
+ * module cannot invent one.** Variables are scoped by tenant/subject only; the
+ * server's `vars` routes read no such parameter and the table has no column for
+ * it, while every document route does — so the two asset surfaces are
+ * deliberately asymmetric (`docs/implementation.md` §7, and `src/documents.ts`
+ * for the other half). The asymmetry is enforced structurally rather than by
+ * discipline: {@linkcode VarsHost} exposes the transport and **not** the
+ * client's resolved configuration, so nothing in this file can reach a default
+ * scope to send even by accident. Adding the parameter later, once the server
+ * honours it, is purely additive; adding it now would be an argument the server
+ * ignores — a lie that typechecks.
+ *
+ * @module
+ */
+import { type HttpResponse, type RequestOptions } from "./http.ts";
+import { type Var, type VarType } 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.
+ */
+export interface VarsHost {
+    /** Perform one request. */
+    request<T>(options: RequestOptions): Promise<HttpResponse<T>>;
+}
+/**
+ * The body of `vars.create`.
+ *
+ * Addressed by `name`, because that is how the server addresses a create (D6).
+ */
+export interface VarCreateInput {
+    /** Must match `^[a-z_][a-z0-9_]*$` (`400 invalid_name`); unique (`409 var_exists`). */
+    name: string;
+    /** The declared type. */
+    type: VarType;
+    /** The value, validated server-side against `type` (`400 invalid_value`). */
+    value: unknown;
+    /** Free text. */
+    description?: string;
+}
+/**
+ * The body of `vars.update`. Every field is optional; an omitted field is left
+ * alone.
+ *
+ * **`name` is deliberately absent.** The server's PATCH body has no `name` and
+ * the name is immutable, so there is no field here to put one in — the type is
+ * what enforces it, not a comment.
+ *
+ * A `value` sent **without** a `type` is validated against the variable's
+ * existing type.
+ */
+export interface VarPatch {
+    /** Replacement type. */
+    type?: VarType;
+    /** Replacement value. */
+    value?: unknown;
+    /** Replacement description. */
+    description?: string;
+}
+/**
+ * The `vars` namespace on a `W6wClient`.
+ *
+ * @example
+ * ```ts
+ * const v = await client.vars.create({ name: "sender_email", type: "string", value: "a@b.c" });
+ * await client.vars.update(v.id, { value: "c@d.e" });
+ * await client.vars.delete(v.id);
+ * ```
+ */
+export declare class VarsApi {
+    #private;
+    /**
+     * @param host - The client this namespace issues requests through.
+     */
+    constructor(host: VarsHost);
+    /**
+     * List the caller's variables.
+     *
+     * @returns The variables, unwrapped from the `vars` envelope.
+     * @throws {ApiError} On any non-2xx.
+     */
+    list(): Promise<Var[]>;
+    /**
+     * Fetch one variable by its server-issued id.
+     *
+     * @param id - The `var_…` id.
+     * @returns The variable.
+     * @throws {ApiError} `404 unknown_var` when there is no such id.
+     */
+    get(id: string): Promise<Var>;
+    /**
+     * Fetch one variable by the `name` its author chose.
+     *
+     * The name is percent-encoded at interpolation by the `path` tag. The server's
+     * own rule (`^[a-z_][a-z0-9_]*$`) contains nothing that needs encoding — but
+     * that rule is the *server's* to enforce, and this method encodes rather than
+     * validates: a name the server accepts is sent as-is (encoded), and a name it
+     * rejects comes back as `400 invalid_name` from the one place that owns the
+     * rule, instead of as a client-side error that would go stale the moment the
+     * rule changed.
+     *
+     * @param name - The variable name, sent encoded and otherwise untouched.
+     * @returns The variable.
+     * @throws {ApiError} `404 unknown_var` when there is no such name.
+     */
+    getByName(name: string): Promise<Var>;
+    /**
+     * Create a typed variable under a caller-chosen name.
+     *
+     * @param input - `name`, `type` and `value` are required.
+     * @returns The created variable (the server answers `201`).
+     * @throws {ApiError} `409 var_exists` on a duplicate name — the code reaches the caller intact.
+     */
+    create(input: VarCreateInput): Promise<Var>;
+    /**
+     * Patch a variable's type, value or description.
+     *
+     * Addressed by id, never by name, and the name itself cannot be changed.
+     *
+     * @param id - The `var_…` id.
+     * @param patch - The fields to change; omitted fields are left alone.
+     * @returns The updated variable.
+     * @throws {ApiError} `404 unknown_var` when there is no such id.
+     */
+    update(id: string, patch: VarPatch): Promise<Var>;
+    /**
+     * Delete a variable.
+     *
+     * Returns nothing: the server's `{ok: true}` carries no information a caller
+     * can use. Deleting an unknown id is `404 unknown_var`, **not** a silent
+     * success — the delete is not idempotent and this method does not pretend
+     * otherwise.
+     *
+     * @param id - The `var_…` id.
+     * @throws {ApiError} `404 unknown_var` when there is no such id.
+     */
+    delete(id: string): Promise<void>;
+}
+//# sourceMappingURL=vars.d.ts.map

package/dist/src/vars.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vars.d.ts","sourceRoot":"","sources":["../../src/vars.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAQ,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AACzE,OAAO,EAAU,KAAK,GAAG,EAAE,KAAK,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,2BAA2B;IAC3B,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;CAC/D;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,uFAAuF;IACvF,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,IAAI,EAAE,OAAO,CAAC;IACd,6EAA6E;IAC7E,KAAK,EAAE,OAAO,CAAC;IACf,iBAAiB;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,QAAQ;IACvB,wBAAwB;IACxB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,yBAAyB;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,+BAA+B;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,qBAAa,OAAO;;IAGlB;;OAEG;gBACS,IAAI,EAAE,QAAQ;IAI1B;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAK5B;;;;;;OAMG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAOnC;;;;;;;;;;;;;;OAcG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAQ3C;;;;;;OAMG;IACG,MAAM,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC;IAiBjD;;;;;;;;;OASG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC;IAavD;;;;;;;;;;OAUG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGxC"}