@w6w/sdk 0.3.0 → 0.5.0

package/dist/src/console/dashboard.js

@@ -0,0 +1,59 @@
+/**
+ * `client.console.dashboard.*` — the account-scoped dashboard rollup,
+ * 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.
+ *
+ * One operation: `stats`, `GET /dashboard/stats`. AUTHENTICATED — the account
+ * is derived server-side from the principal (`admin/dashboard.ts:44-96`), so
+ * this uses the default, unconditional `requireAuth` (HITL-9); the client
+ * never sends an account. Unlike `client.documents.*` and `client.vars.*`,
+ * the response carries **no envelope key** — the `DashboardStats`-shaped
+ * object IS the top-level response body (`admin/dashboard.ts:90-95`, which
+ * answers `c.json({range, headline, series, recent})`), so `stats` returns
+ * `res.body` directly and never calls this package's `unwrap()` helper.
+ *
+ * @module
+ */
+/**
+ * The `console.dashboard` namespace on a `W6WClient`.
+ *
+ * @example
+ * ```ts
+ * const rollup = await client.console.dashboard.stats({ bucket: "week" });
+ * ```
+ */
+export class DashboardApi {
+    #host;
+    /**
+     * @param host - The client this namespace issues requests through.
+     */
+    constructor(host) {
+        this.#host = host;
+    }
+    /**
+     * Fetch the account-scoped dashboard rollup.
+     *
+     * @param params - Optional `from`/`to`/`bucket`; each is forwarded as a
+     * query parameter when given, and omitted from the query string entirely
+     * when not (the server applies its own defaults).
+     * @returns The rollup, exactly as the server sent it — no envelope key to peel.
+     * @throws {ApiError} On any non-2xx.
+     */
+    async stats(params = {}) {
+        const res = await this.#host.request({
+            method: "GET",
+            path: "/dashboard/stats",
+            query: { from: params.from, to: params.to, bucket: params.bucket },
+        });
+        return res.body;
+    }
+}
+//# sourceMappingURL=dashboard.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard.js","sourceRoot":"","sources":["../../../src/console/dashboard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AA6CH;;;;;;;GAOG;AACH,MAAM,OAAO,YAAY;IACd,KAAK,CAAgB;IAE9B;;OAEG;IACH,YAAY,IAAmB;QAC7B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,KAAK,CAAC,SAA+B,EAAE;QAC3C,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAiB;YACnD,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,kBAAkB;YACxB,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;SACnE,CAAC,CAAC;QACH,OAAO,GAAG,CAAC,IAAI,CAAC;IAClB,CAAC;CACF"}

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

@@ -0,0 +1,264 @@
+/**
+ * `client.console.endpoints.*` — the named, stable callable-entry-point
+ * surface (`list`/`get`/`upsert`/`invoke`), 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.
+ *
+ * **`invoke`'s wire path is a PINNED mechanism, not a choice — read this
+ * before touching `invoke` below.** {@linkcode EndpointsApi.invoke} MUST call
+ * `POST /endpoints/:id/invoke` directly. It must NEVER be implemented by
+ * delegating to `client.run()`/`runUrn()`/`POST /run`, even though that
+ * dispatcher can also resolve an `ep_…` URN. Verified directly against the
+ * server: `packages/server/packages/bll/resolve-run.ts`'s `ep_` arm
+ * (`:198-207`) delegates to `InvokeEndpointService.invoke()` but then
+ * **remaps** the action-kind result's field from `output` to `value`
+ * (`return { kind: "action", value: result.output };`) to match `run()`'s own
+ * `ActionRunEnvelope` shape. The dedicated `/endpoints/:id/invoke` route
+ * (`packages/server/packages/api/admin/endpoints.ts:319-360`) does NOT do
+ * this remap — it returns `InvokeEndpointResult` VERBATIM (`{kind:"action",
+ * output}` for an action target). Studio's `EndpointsPage.tsx` renders the
+ * raw envelope it gets back directly (`JSON.stringify(result, null, 2)`), so
+ * this field name is user-visible. Routing `invoke` through `/run` instead of
+ * the dedicated route would silently rename `output` to `value` and break
+ * that page — a "simplification" that looks harmless and is not.
+ *
+ * Four methods relocate from the studio's `// Endpoints` comment block
+ * (`packages/studio/src/api/client.ts:281-314`): `listEndpoints`→`list`,
+ * `getEndpoint`→`get`, `saveEndpoint`→`upsert`, `invokeEndpoint`→`invoke`.
+ *
+ * None of the four methods take a client-side default-project fallback or a
+ * `?project=` scoping parameter — neither is reachable via any HTTP route on
+ * this domain — so `EndpointsHost` needs only the transport, mirroring
+ * `WorkflowsHost`/`SchedulesHost`, not the base `DocumentsHost`.
+ *
+ * @module
+ */
+import { type HttpResponse, type RequestOptions } from "../http.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 `WorkflowsHost` in `./workflows.ts`.
+ */
+export interface EndpointsHost {
+    /** Perform one request. */
+    request<T>(options: RequestOptions): Promise<HttpResponse<T>>;
+}
+/** What an Endpoint dispatches to, when the target is a Function or Workflow. */
+export type Callable = {
+    kind: "function";
+    function: string;
+} | {
+    kind: "workflow";
+    workflow: string;
+};
+/** What an Endpoint dispatches to, when the target is a direct app Action. */
+export interface ActionTarget {
+    kind: "action";
+    uses: {
+        app: string;
+        action: string;
+        connection?: string | null;
+    };
+    with?: Record<string, unknown>;
+}
+/** The full discriminated union of what an Endpoint may dispatch to. */
+export type EndpointTarget = Callable | ActionTarget;
+/** The inbound auth mode an Endpoint's public exposure enforces. */
+export type EndpointAuthMode = "platform" | "none" | "basic" | "header" | "jwt";
+/**
+ * An Endpoint's inbound security policy. Secret-carrying fields
+ * (`basicPassword`, `headerValue`, `jwtSecret`) come back from a `GET` masked
+ * with {@linkcode SECRET_MASK}, never as plaintext or ciphertext — sending the
+ * mask back on `upsert` preserves whatever is already stored.
+ */
+export interface EndpointSecurity {
+    auth: EndpointAuthMode;
+    basicUser?: string;
+    basicPassword?: string;
+    headerName?: string;
+    headerValue?: string;
+    jwtSecret?: string;
+}
+/**
+ * The placeholder a `GET` returns in place of a configured secret, and which
+ * an `upsert` may send back to mean "keep what is stored". Relocated
+ * verbatim from `admin/endpoints.ts`'s own exported constant — same value,
+ * same meaning.
+ */
+export declare const SECRET_MASK = "__stored__";
+/** How an Endpoint may additionally be reachable, declaratively. */
+export interface Exposure {
+    http?: {
+        method?: "POST" | "GET";
+        path?: string;
+        auth?: "none" | "token" | "tenant";
+    };
+    security?: EndpointSecurity;
+}
+/** One declared input an Endpoint accepts. */
+export interface EndpointInput {
+    key: string;
+    label: string;
+    type: string;
+    required?: boolean;
+    default?: unknown;
+    hint?: string;
+}
+/**
+ * An Endpoint definition — a named, stable callable entry point that
+ * dispatches to exactly one target: an app Action, a Function, or a Workflow
+ * (`rfcs/endpoint.md`). Callers bind to the Endpoint id; the target beneath
+ * it can change without breaking them.
+ *
+ * `key` is **immutable after first save** — it is a public URL segment. A
+ * save that changes `key` on an already-stored Endpoint answers `409
+ * key_immutable`; a first save with a malformed `key` answers `400
+ * invalid_endpoint`.
+ */
+export interface EndpointDef {
+    manifestVersion: string;
+    id: string;
+    key: string;
+    displayName?: string;
+    description?: string;
+    target: EndpointTarget;
+    input?: EndpointInput[];
+    exposure?: Exposure;
+}
+/**
+ * One row of `list`'s result — an Endpoint's summary, not its full
+ * definition. Each row already carries its own `invokeUrl`, merged in
+ * server-side.
+ */
+export interface EndpointSummary {
+    id: string;
+    key: string;
+    displayName: string;
+    description: string;
+    updatedAt: string;
+    invokeUrl: string;
+}
+/**
+ * What {@linkcode EndpointsApi.invoke} resolves to — the discriminated result
+ * of dispatching one Endpoint, returned VERBATIM from the dedicated invoke
+ * route. `output` (action/function) and `runId` (workflow) are the server's
+ * own field names — never renamed, never normalised, per this module's
+ * header pin.
+ */
+export type EndpointInvokeResult = {
+    kind: "action";
+    output: unknown;
+} | {
+    kind: "function";
+    output: unknown;
+} | {
+    kind: "workflow";
+    runId: string;
+};
+/**
+ * The `console.endpoints` namespace on a `W6WClient`.
+ *
+ * @example
+ * ```ts
+ * const endpoints = await client.console.endpoints.list();
+ * const { endpoint, invokeUrl } = await client.console.endpoints.get(endpoints[0].id);
+ * const result = await client.console.endpoints.invoke(endpoint.id, { to: "a@b.com" });
+ * ```
+ */
+export declare class EndpointsApi {
+    #private;
+    /**
+     * @param host - The client this namespace issues requests through.
+     */
+    constructor(host: EndpointsHost);
+    /**
+     * List the caller's Endpoint definitions.
+     *
+     * @returns The Endpoints, unwrapped from the `endpoints` envelope; each row
+     * carries its own `invokeUrl`/`invokeUrlByKey`, preserved untouched.
+     */
+    list(): Promise<EndpointSummary[]>;
+    /**
+     * Fetch one Endpoint's stored definition plus its callable URL(s). Any
+     * configured secret comes back masked with {@linkcode SECRET_MASK}, never
+     * as plaintext or ciphertext.
+     *
+     * **Returns the response body VERBATIM — a three-key top-level shape, NOT
+     * merged.** `invokeUrl`/`invokeUrlByKey` are never spliced into `endpoint`;
+     * this mirrors `console.workflows.get`'s "no envelope key to peel, multiple
+     * top-level siblings" precedent, deliberately NOT
+     * `console.functions.get`'s merge — these are two different,
+     * individually-verified, individually-pinned shapes. `invokeUrl` is ALWAYS
+     * present; `invokeUrlByKey` is present only when the owning account has a
+     * slug — genuinely absent from the body otherwise, never an
+     * `undefined`-valued key.
+     *
+     * No 404 special-casing — propagates as `ApiError` like every other "get"
+     * in this package except `console.schedules.get`'s documented exception.
+     *
+     * @param id - The `ep_…` id.
+     * @returns The whole response body — no envelope key to peel.
+     * @throws {ApiError} `404 unknown_endpoint` when there is no such id.
+     */
+    get(id: string): Promise<{
+        endpoint: EndpointDef;
+        invokeUrl: string;
+        invokeUrlByKey?: string;
+    }>;
+    /**
+     * Register (create or overwrite) an Endpoint definition.
+     *
+     * `definition` is the whole definition, sent verbatim as the request body —
+     * not wrapped in an envelope key. **Returns the response body VERBATIM**,
+     * same three-key shape as {@linkcode get} — no merge, no `unwrap()`.
+     *
+     * None of the four error codes below need special client-side handling —
+     * they propagate as an ordinary `ApiError` with the server's own
+     * `.message`, exactly like every other write in this package; this method
+     * does not branch on any of them.
+     *
+     * @param definition - The whole Endpoint definition, forwarded verbatim.
+     * @returns The new/updated Endpoint's id and key, plus its callable URL(s).
+     * @throws {ApiError} `400 invalid_endpoint` — structurally invalid body, or (first save only) a malformed `key`.
+     * @throws {ApiError} `409 key_immutable` — `key` differs from the already-stored row's `key`.
+     * @throws {ApiError} `409 endpoint_conflict` — another `(tenant,subject)` owns this id.
+     * @throws {ApiError} `409 endpoint_key_conflict` — another Endpoint already holds this `key`.
+     */
+    upsert(definition: EndpointDef): Promise<{
+        endpoint: {
+            id: string;
+            key: string;
+        };
+        invokeUrl: string;
+        invokeUrlByKey?: string;
+    }>;
+    /**
+     * Invoke an Endpoint: dispatches to its configured target (an app Action, a
+     * Function, or a Workflow) and returns the discriminated result.
+     *
+     * **Calls the DEDICATED `POST /endpoints/:id/invoke` route directly — see
+     * this module's header for why it must NEVER delegate to `client.run()`/
+     * `runUrn()`/`POST /run` instead.** The response body is returned
+     * VERBATIM, field names untouched: an `action`/`function` target answers
+     * `200` with `{kind, output}`; a `workflow` target answers `202` with
+     * `{kind:"workflow", runId}` — both are success on this API, mirroring
+     * `console.workflows`'s/base `run()`'s own "202 is success" convention.
+     *
+     * @param id - The `ep_…` id.
+     * @param input - The Endpoint's declared inputs, forwarded verbatim as `{input}`.
+     * @returns The discriminated dispatch result, unmodified from the wire.
+     * @throws {ApiError} `404 unknown_endpoint` / `404 unknown_function` / `404 unknown_workflow`.
+     * @throws {ApiError} `422 function_incomplete` — the target Function is not runnable.
+     */
+    invoke(id: string, input: Record<string, unknown>): Promise<EndpointInvokeResult>;
+}
+//# sourceMappingURL=endpoints.d.ts.map

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

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

package/dist/src/console/endpoints.js

@@ -0,0 +1,164 @@
+/**
+ * `client.console.endpoints.*` — the named, stable callable-entry-point
+ * surface (`list`/`get`/`upsert`/`invoke`), 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.
+ *
+ * **`invoke`'s wire path is a PINNED mechanism, not a choice — read this
+ * before touching `invoke` below.** {@linkcode EndpointsApi.invoke} MUST call
+ * `POST /endpoints/:id/invoke` directly. It must NEVER be implemented by
+ * delegating to `client.run()`/`runUrn()`/`POST /run`, even though that
+ * dispatcher can also resolve an `ep_…` URN. Verified directly against the
+ * server: `packages/server/packages/bll/resolve-run.ts`'s `ep_` arm
+ * (`:198-207`) delegates to `InvokeEndpointService.invoke()` but then
+ * **remaps** the action-kind result's field from `output` to `value`
+ * (`return { kind: "action", value: result.output };`) to match `run()`'s own
+ * `ActionRunEnvelope` shape. The dedicated `/endpoints/:id/invoke` route
+ * (`packages/server/packages/api/admin/endpoints.ts:319-360`) does NOT do
+ * this remap — it returns `InvokeEndpointResult` VERBATIM (`{kind:"action",
+ * output}` for an action target). Studio's `EndpointsPage.tsx` renders the
+ * raw envelope it gets back directly (`JSON.stringify(result, null, 2)`), so
+ * this field name is user-visible. Routing `invoke` through `/run` instead of
+ * the dedicated route would silently rename `output` to `value` and break
+ * that page — a "simplification" that looks harmless and is not.
+ *
+ * Four methods relocate from the studio's `// Endpoints` comment block
+ * (`packages/studio/src/api/client.ts:281-314`): `listEndpoints`→`list`,
+ * `getEndpoint`→`get`, `saveEndpoint`→`upsert`, `invokeEndpoint`→`invoke`.
+ *
+ * None of the four methods take a client-side default-project fallback or a
+ * `?project=` scoping parameter — neither is reachable via any HTTP route on
+ * this domain — so `EndpointsHost` needs only the transport, mirroring
+ * `WorkflowsHost`/`SchedulesHost`, not the base `DocumentsHost`.
+ *
+ * @module
+ */
+import { path } from "../http.js";
+import { unwrap } from "../types.js";
+/**
+ * The placeholder a `GET` returns in place of a configured secret, and which
+ * an `upsert` may send back to mean "keep what is stored". Relocated
+ * verbatim from `admin/endpoints.ts`'s own exported constant — same value,
+ * same meaning.
+ */
+export const SECRET_MASK = "__stored__";
+/**
+ * The `console.endpoints` namespace on a `W6WClient`.
+ *
+ * @example
+ * ```ts
+ * const endpoints = await client.console.endpoints.list();
+ * const { endpoint, invokeUrl } = await client.console.endpoints.get(endpoints[0].id);
+ * const result = await client.console.endpoints.invoke(endpoint.id, { to: "a@b.com" });
+ * ```
+ */
+export class EndpointsApi {
+    #host;
+    /**
+     * @param host - The client this namespace issues requests through.
+     */
+    constructor(host) {
+        this.#host = host;
+    }
+    /**
+     * List the caller's Endpoint definitions.
+     *
+     * @returns The Endpoints, unwrapped from the `endpoints` envelope; each row
+     * carries its own `invokeUrl`/`invokeUrlByKey`, preserved untouched.
+     */
+    async list() {
+        const res = await this.#host.request({ method: "GET", path: "/endpoints" });
+        return unwrap(res, "endpoints");
+    }
+    /**
+     * Fetch one Endpoint's stored definition plus its callable URL(s). Any
+     * configured secret comes back masked with {@linkcode SECRET_MASK}, never
+     * as plaintext or ciphertext.
+     *
+     * **Returns the response body VERBATIM — a three-key top-level shape, NOT
+     * merged.** `invokeUrl`/`invokeUrlByKey` are never spliced into `endpoint`;
+     * this mirrors `console.workflows.get`'s "no envelope key to peel, multiple
+     * top-level siblings" precedent, deliberately NOT
+     * `console.functions.get`'s merge — these are two different,
+     * individually-verified, individually-pinned shapes. `invokeUrl` is ALWAYS
+     * present; `invokeUrlByKey` is present only when the owning account has a
+     * slug — genuinely absent from the body otherwise, never an
+     * `undefined`-valued key.
+     *
+     * No 404 special-casing — propagates as `ApiError` like every other "get"
+     * in this package except `console.schedules.get`'s documented exception.
+     *
+     * @param id - The `ep_…` id.
+     * @returns The whole response body — no envelope key to peel.
+     * @throws {ApiError} `404 unknown_endpoint` when there is no such id.
+     */
+    async get(id) {
+        const res = await this.#host.request({
+            method: "GET",
+            path: path `/endpoints/${id}`,
+        });
+        return res.body;
+    }
+    /**
+     * Register (create or overwrite) an Endpoint definition.
+     *
+     * `definition` is the whole definition, sent verbatim as the request body —
+     * not wrapped in an envelope key. **Returns the response body VERBATIM**,
+     * same three-key shape as {@linkcode get} — no merge, no `unwrap()`.
+     *
+     * None of the four error codes below need special client-side handling —
+     * they propagate as an ordinary `ApiError` with the server's own
+     * `.message`, exactly like every other write in this package; this method
+     * does not branch on any of them.
+     *
+     * @param definition - The whole Endpoint definition, forwarded verbatim.
+     * @returns The new/updated Endpoint's id and key, plus its callable URL(s).
+     * @throws {ApiError} `400 invalid_endpoint` — structurally invalid body, or (first save only) a malformed `key`.
+     * @throws {ApiError} `409 key_immutable` — `key` differs from the already-stored row's `key`.
+     * @throws {ApiError} `409 endpoint_conflict` — another `(tenant,subject)` owns this id.
+     * @throws {ApiError} `409 endpoint_key_conflict` — another Endpoint already holds this `key`.
+     */
+    async upsert(definition) {
+        const res = await this.#host.request({
+            method: "POST",
+            path: "/endpoints",
+            body: definition,
+        });
+        return res.body;
+    }
+    /**
+     * Invoke an Endpoint: dispatches to its configured target (an app Action, a
+     * Function, or a Workflow) and returns the discriminated result.
+     *
+     * **Calls the DEDICATED `POST /endpoints/:id/invoke` route directly — see
+     * this module's header for why it must NEVER delegate to `client.run()`/
+     * `runUrn()`/`POST /run` instead.** The response body is returned
+     * VERBATIM, field names untouched: an `action`/`function` target answers
+     * `200` with `{kind, output}`; a `workflow` target answers `202` with
+     * `{kind:"workflow", runId}` — both are success on this API, mirroring
+     * `console.workflows`'s/base `run()`'s own "202 is success" convention.
+     *
+     * @param id - The `ep_…` id.
+     * @param input - The Endpoint's declared inputs, forwarded verbatim as `{input}`.
+     * @returns The discriminated dispatch result, unmodified from the wire.
+     * @throws {ApiError} `404 unknown_endpoint` / `404 unknown_function` / `404 unknown_workflow`.
+     * @throws {ApiError} `422 function_incomplete` — the target Function is not runnable.
+     */
+    async invoke(id, input) {
+        const res = await this.#host.request({
+            method: "POST",
+            path: path `/endpoints/${id}/invoke`,
+            body: { input },
+        });
+        return res.body;
+    }
+}
+//# sourceMappingURL=endpoints.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"endpoints.js","sourceRoot":"","sources":["../../../src/console/endpoints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,EAAqB,IAAI,EAAuB,MAAM,YAAY,CAAC;AAC1E,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AA8CrC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,YAAY,CAAC;AAkExC;;;;;;;;;GASG;AACH,MAAM,OAAO,YAAY;IACd,KAAK,CAAgB;IAE9B;;OAEG;IACH,YAAY,IAAmB;QAC7B,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,YAAY,EAAE,CAAC,CAAC;QACrF,OAAO,MAAM,CAAoB,GAAG,EAAE,WAAW,CAAC,CAAC;IACrD,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;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;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK,CAAC,MAAM,CACV,UAAuB;QAIvB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAElC;YACA,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,YAAY;YAClB,IAAI,EAAE,UAAU;SACjB,CAAC,CAAC;QACH,OAAO,GAAG,CAAC,IAAI,CAAC;IAClB,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,CAAC,MAAM,CAAC,EAAU,EAAE,KAA8B;QACrD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAuB;YACzD,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,IAAI,CAAA,cAAc,EAAE,SAAS;YACnC,IAAI,EAAE,EAAE,KAAK,EAAE;SAChB,CAAC,CAAC;QACH,OAAO,GAAG,CAAC,IAAI,CAAC;IAClB,CAAC;CACF"}

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

@@ -0,0 +1,165 @@
+/**
+ * `client.console.functions.*` — the canonical, vendor-stable Function
+ * definition surface (`list`/`get`/`upsert`), 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.
+ *
+ * **`invoke` is deliberately NOT modeled here.** The base
+ * `client.run({urn, payload})` (already-published surface,
+ * `endpoints.json`-named, exported from the root `mod.ts`) dispatches a
+ * `fn_…` URN through the exact same `InvokeFunctionService` the dedicated
+ * `/functions/:id/invoke` route uses, returning `{kind:"function", output}` —
+ * field-for-field identical to what the dedicated route returns. Adding a
+ * duplicate `console.functions.invoke` would give a caller two ways to reach
+ * the same route, the anti-duplication defect this project's own rules flag
+ * — mirrors `console.workflows`'s established precedent of NOT re-wrapping
+ * base `list`/`run`. Studio composes `client.run()` + `isFunctionRun` itself;
+ * no invoke method lives here, and none should be added later without
+ * re-litigating this reasoning.
+ *
+ * Three methods relocate from the studio's `// Functions` comment block
+ * (`packages/studio/src/api/client.ts:255-268`): `listFunctions`→`list`,
+ * `getFunction`→`get`, `saveFunction`→`upsert`.
+ *
+ * None of the three methods take a client-side default-project fallback or a
+ * `?project=` scoping parameter — neither is reachable via either HTTP route
+ * — so `FunctionsHost` needs only the transport, mirroring
+ * `WorkflowsHost`/`SchedulesHost`, not the base `DocumentsHost`.
+ *
+ * @module
+ */
+import { type HttpResponse, type RequestOptions } from "../http.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 `WorkflowsHost` in `./workflows.ts`.
+ */
+export interface FunctionsHost {
+    /** Perform one request. */
+    request<T>(options: RequestOptions): Promise<HttpResponse<T>>;
+}
+/** One declared input a Function accepts. */
+export interface FunctionInput {
+    key: string;
+    label: string;
+    type: "string" | "text" | "number" | "boolean" | "json" | "secret" | string;
+    required?: boolean;
+    default?: unknown;
+    hint?: string;
+}
+/** One declared field of a Function's output shape. */
+export interface FunctionOutputField {
+    key: string;
+    type: "string" | "number" | "boolean" | "object" | "array" | string;
+    label?: string;
+}
+/** What a Function is bound to: one app Action, plus the mapping around it. */
+export interface FunctionImpl {
+    uses: {
+        app: string;
+        action: string;
+        connection?: string | null;
+    };
+    with?: Record<string, unknown>;
+    outputMap?: Record<string, unknown>;
+}
+/**
+ * A Function definition — a canonical, vendor-stable interface bound to one
+ * swappable app Action (`rfcs/function.md`). Callers bind to `inputs`/
+ * `output`; a vendor swap rewrites only `impl.uses`, so no caller breaks.
+ *
+ * `valid` is **server-computed**, spliced in by {@linkcode FunctionsApi.get}
+ * — see that method's doc. It is never sent by a caller on `upsert`.
+ */
+export interface FunctionDef {
+    manifestVersion: string;
+    id: string;
+    key: string;
+    displayName?: string;
+    description?: string;
+    inputs: FunctionInput[];
+    output?: FunctionOutputField[];
+    impl: FunctionImpl;
+    /** Server-computed, spliced in by `console.functions.get` — see above. Read-only. */
+    valid: boolean;
+}
+/** One row of `list`'s result — a Function's summary, not its full definition. */
+export interface FunctionSummary {
+    id: string;
+    key: string;
+    displayName: string;
+    description: string;
+    updatedAt: string;
+    valid: boolean;
+}
+/**
+ * The `console.functions` namespace on a `W6WClient`.
+ *
+ * @example
+ * ```ts
+ * const fns = await client.console.functions.list();
+ * const fn = await client.console.functions.get(fns[0].id);
+ * await client.console.functions.upsert({ ...fn, description: "Send an email" });
+ * ```
+ */
+export declare class FunctionsApi {
+    #private;
+    /**
+     * @param host - The client this namespace issues requests through.
+     */
+    constructor(host: FunctionsHost);
+    /**
+     * List the caller's Function definitions.
+     *
+     * Each row already carries `valid` — server-computed
+     * (`db/repos/functions.ts`'s `list()`) — same as {@linkcode get}'s splice,
+     * but here it arrives already flat on the summary row, nothing to merge.
+     *
+     * @returns The Functions, unwrapped from the `functions` envelope.
+     */
+    list(): Promise<FunctionSummary[]>;
+    /**
+     * Fetch one Function's stored definition.
+     *
+     * **`valid` is a TOP-LEVEL SIBLING of `function` on the wire, never spliced
+     * into the stored definition itself** (`admin/functions.ts:82-93`) — but
+     * this method DOES splice it into its own return value, for caller
+     * convenience: `{...body.function, valid: body.valid}`. This is a
+     * deliberate, behavior-preserving relocation of studio's own current
+     * `getFunction` (`client.ts:259-262`), not a redesign — a raw
+     * `{function, valid}` return would be a regression.
+     *
+     * No 404 special-casing — propagates as `ApiError` like every other "get"
+     * in this package except `console.schedules.get`'s documented exception.
+     *
+     * @param id - The `fn_…` id.
+     * @returns The Function definition with `valid` merged in at the top level.
+     * @throws {ApiError} `404 unknown_function` when there is no such id.
+     */
+    get(id: string): Promise<FunctionDef>;
+    /**
+     * Register (create or overwrite) a Function definition.
+     *
+     * `definition` is the whole definition, sent verbatim as the request body —
+     * not wrapped in an envelope key.
+     *
+     * @param definition - The whole Function definition, forwarded verbatim.
+     * @returns The new/updated Function's id and key.
+     * @throws {ApiError} `400 invalid_function` — structurally invalid body.
+     * @throws {ApiError} `409 function_conflict` — another `(tenant,subject)` owns this id.
+     */
+    upsert(definition: FunctionDef): Promise<{
+        id: string;
+        key: string;
+    }>;
+}
+//# sourceMappingURL=functions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"functions.d.ts","sourceRoot":"","sources":["../../../src/console/functions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAQ,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAG1E;;;;;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,6CAA6C;AAC7C,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC5E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,uDAAuD;AACvD,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;IACpE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,MAAM,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAC/B,IAAI,EAAE,YAAY,CAAC;IACnB,qFAAqF;IACrF,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,kFAAkF;AAClF,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;;GASG;AACH,qBAAa,YAAY;;IAGvB;;OAEG;gBACS,IAAI,EAAE,aAAa;IAI/B;;;;;;;;OAQG;IACG,IAAI,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IAKxC;;;;;;;;;;;;;;;;;OAiBG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAQ3C;;;;;;;;;;OAUG;IACG,MAAM,CAAC,UAAU,EAAE,WAAW,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CAQ5E"}