@w6w/sdk 0.3.0 → 0.5.0

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

@@ -0,0 +1,199 @@
+/**
+ * `client.console.subscriptions.*` — (trigger → workflow) bindings, 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.
+ *
+ * Seven methods, relocated from `packages/studio/src/api/client.ts:253-286`'s
+ * single `// Subscriptions` comment block — field-for-field, not redesigned:
+ * `listSubscriptions` → `list`, `listSubscriptionsForWorkflow` →
+ * `listForWorkflow`, `getSubscription` → `get`, `createSubscription` →
+ * `create`, `deleteSubscription` → `delete`, `listSubscriptionEvents` →
+ * `listEvents`, `requeueTriggerEvent` → `requeueEvent`.
+ *
+ * **Four of these seven have zero callers anywhere in studio or `@w6w/ui`**
+ * (`listForWorkflow`, `get`, `listEvents`, `requeueEvent`) — HITL-4's pinned
+ * default, re-confirmed this pass. They are still built to full type
+ * fidelity (real implementation, JSDoc, `@throws`) for SDK/wrapper coverage;
+ * only the test bar for them is deliberately lighter, mirroring
+ * `console.apps`'s/`console.functions`' identical treatment of their own
+ * zero-caller methods.
+ *
+ * **`webhookUrl` is a real server-side field this module deliberately does
+ * NOT model.** For a subscription whose `appId === "@w6w/webhook"`, the
+ * server enriches the response with a `webhookUrl` field computed from a
+ * config value genuinely distinct from studio's own `apiBaseUrl()`
+ * (`internal-triggers.ts:123-127`, `config.ts:27,259`). Studio's current
+ * `Subscription` type never modeled this and no in-boundary code reads it
+ * (`SubscriptionsPage.tsx` computes its own webhook URL client-side
+ * independently) — this is a deliberate, verified omission, not an
+ * oversight: whatever extra field the server sends is silently ignored,
+ * exactly as today.
+ *
+ * Subscriptions are account-level, never scoped by `project` — so
+ * `SubscriptionsHost` needs only the transport, mirroring `VarsHost`/
+ * `ProjectsHost`, not `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 `VarsHost` in `../vars.ts`.
+ */
+export interface SubscriptionsHost {
+    /** Perform one request. */
+    request<T>(options: RequestOptions): Promise<HttpResponse<T>>;
+}
+/**
+ * A (trigger → workflow) binding. Field-for-field per
+ * `packages/studio/src/api/types.ts:72-83` — this module does not redesign
+ * the shape, only gives it a second home. Deliberately does NOT carry
+ * `webhookUrl` — see this module's header.
+ */
+export interface Subscription {
+    id: string;
+    appId: string;
+    triggerKey: string;
+    connectionId: string | null;
+    workflowId: string;
+    params: Record<string, unknown>;
+    state: Record<string, unknown>;
+    enabled: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * The body of `create`, forwarded verbatim as the whole POST body.
+ * Field-for-field per `packages/studio/src/api/client.ts:267-271`.
+ */
+export interface SubscriptionCreateInput {
+    workflowId: string;
+    connectionId?: string | null;
+    params?: Record<string, unknown>;
+}
+/** The lifecycle a delivered trigger event can be in. */
+export type TriggerEventStatus = "received" | "dispatching" | "dispatched" | "failed";
+/**
+ * Metadata-only view of a delivered trigger event. Field-for-field per
+ * `packages/studio/src/api/types.ts:85-96`.
+ */
+export interface TriggerEventSummary {
+    id: string;
+    subscriptionId: string;
+    status: TriggerEventStatus;
+    attempts: number;
+    receivedAt: string;
+    dispatchedAt: string | null;
+    runId: string | null;
+}
+/**
+ * The `console.subscriptions` namespace on a `W6WClient`.
+ *
+ * @example
+ * ```ts
+ * const subs = await client.console.subscriptions.list();
+ * const sub = await client.console.subscriptions.create("app_x", "new-message", {
+ *   workflowId: "wf_1",
+ * });
+ * await client.console.subscriptions.delete(sub.id);
+ * ```
+ */
+export declare class SubscriptionsApi {
+    #private;
+    /**
+     * @param host - The client this namespace issues requests through.
+     */
+    constructor(host: SubscriptionsHost);
+    /**
+     * List every subscription the caller can see.
+     *
+     * @returns The subscriptions, unwrapped from the `subscriptions` envelope.
+     * @throws {ApiError} On any non-2xx.
+     */
+    list(): Promise<Subscription[]>;
+    /**
+     * List the subscriptions bound to one workflow.
+     *
+     * **Dead code (HITL-4)** — zero call sites anywhere in studio or
+     * `@w6w/ui`. Built for SDK completeness only; see this module's header.
+     *
+     * @param workflowId - The `wf_…` id.
+     * @returns The subscriptions, unwrapped from the `subscriptions` envelope.
+     * @throws {ApiError} On any non-2xx.
+     */
+    listForWorkflow(workflowId: string): Promise<Subscription[]>;
+    /**
+     * Fetch one subscription.
+     *
+     * **Dead code (HITL-4)** — zero call sites anywhere in studio or
+     * `@w6w/ui`. Built for SDK completeness only; see this module's header.
+     * Unlike `console.schedules.get`, this method throws `ApiError` on a 404
+     * rather than resolving `null` — there is no precedent on this domain to
+     * preserve, and this package's default `get` behavior is to throw.
+     *
+     * @param id - The `sub_…` id.
+     * @returns The subscription, unwrapped from the `subscription` envelope.
+     * @throws {ApiError} `404 unknown_subscription` when there is no such id.
+     */
+    get(id: string): Promise<Subscription>;
+    /**
+     * Bind a trigger to a workflow.
+     *
+     * @param appId - The app declaring the trigger.
+     * @param triggerKey - The trigger's key, as declared by the app's manifest.
+     * @param input - The subscription to create; forwarded verbatim as the whole body.
+     * @returns The created subscription, unwrapped from the `subscription` envelope (the server answers `201`).
+     * @throws {ApiError} `404 unknown_trigger`/`unknown_workflow` on a bad app/trigger/workflow id.
+     */
+    create(appId: string, triggerKey: string, input: SubscriptionCreateInput): Promise<Subscription>;
+    /**
+     * Remove a subscription.
+     *
+     * Returns nothing: the server's `{ok: true}` carries no information a
+     * caller can use, mirroring `projects.delete`/`schedules.delete`'s
+     * established discard-to-void convention (not `apps.delete`'s
+     * informative-`{removed: number}` exception).
+     *
+     * @param id - The `sub_…` id.
+     * @throws {ApiError} `404 unknown_subscription` when there is no such id.
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * List a subscription's delivered trigger events, newest first.
+     *
+     * **Dead code (HITL-4)** — zero call sites anywhere in studio or
+     * `@w6w/ui`. Built for SDK completeness only; see this module's header. No
+     * `limit` parameter is exposed — the server applies its own default of 50
+     * (`trigger-manager.ts:109`) and no studio caller ever sent one.
+     *
+     * @param id - The `sub_…` id.
+     * @returns The events, unwrapped from the `events` envelope.
+     * @throws {ApiError} On any non-2xx.
+     */
+    listEvents(id: string): Promise<TriggerEventSummary[]>;
+    /**
+     * Re-queue a `failed`-status trigger event for another delivery attempt —
+     * a dead-letter re-dispatch.
+     *
+     * **Dead code (HITL-4)** — zero call sites anywhere in studio or
+     * `@w6w/ui`. Built for SDK completeness only; see this module's header.
+     * Returns nothing: the server's `{ok: true}` carries no information a
+     * caller can use, mirroring `projects.delete`/`schedules.delete`'s
+     * established discard-to-void convention.
+     *
+     * @param eventId - The trigger event's id.
+     * @throws {ApiError} `404 requeue_failed` when the event doesn't exist or isn't in `failed` status.
+     */
+    requeueEvent(eventId: string): Promise<void>;
+}
+//# sourceMappingURL=subscriptions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"subscriptions.d.ts","sourceRoot":"","sources":["../../../src/console/subscriptions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAQ,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAG1E;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,2BAA2B;IAC3B,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;CAC/D;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,yDAAyD;AACzD,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,aAAa,GAAG,YAAY,GAAG,QAAQ,CAAC;AAEtF;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,gBAAgB;;IAG3B;;OAEG;gBACS,IAAI,EAAE,iBAAiB;IAInC;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IAQrC;;;;;;;;;OASG;IACG,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAQlE;;;;;;;;;;;;OAYG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAQ5C;;;;;;;;OAQG;IACG,MAAM,CACV,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,uBAAuB,GAC7B,OAAO,CAAC,YAAY,CAAC;IASxB;;;;;;;;;;OAUG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOvC;;;;;;;;;;;OAWG;IACG,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAQ5D;;;;;;;;;;;;OAYG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAMnD"}

package/dist/src/console/subscriptions.js

@@ -0,0 +1,191 @@
+/**
+ * `client.console.subscriptions.*` — (trigger → workflow) bindings, 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.
+ *
+ * Seven methods, relocated from `packages/studio/src/api/client.ts:253-286`'s
+ * single `// Subscriptions` comment block — field-for-field, not redesigned:
+ * `listSubscriptions` → `list`, `listSubscriptionsForWorkflow` →
+ * `listForWorkflow`, `getSubscription` → `get`, `createSubscription` →
+ * `create`, `deleteSubscription` → `delete`, `listSubscriptionEvents` →
+ * `listEvents`, `requeueTriggerEvent` → `requeueEvent`.
+ *
+ * **Four of these seven have zero callers anywhere in studio or `@w6w/ui`**
+ * (`listForWorkflow`, `get`, `listEvents`, `requeueEvent`) — HITL-4's pinned
+ * default, re-confirmed this pass. They are still built to full type
+ * fidelity (real implementation, JSDoc, `@throws`) for SDK/wrapper coverage;
+ * only the test bar for them is deliberately lighter, mirroring
+ * `console.apps`'s/`console.functions`' identical treatment of their own
+ * zero-caller methods.
+ *
+ * **`webhookUrl` is a real server-side field this module deliberately does
+ * NOT model.** For a subscription whose `appId === "@w6w/webhook"`, the
+ * server enriches the response with a `webhookUrl` field computed from a
+ * config value genuinely distinct from studio's own `apiBaseUrl()`
+ * (`internal-triggers.ts:123-127`, `config.ts:27,259`). Studio's current
+ * `Subscription` type never modeled this and no in-boundary code reads it
+ * (`SubscriptionsPage.tsx` computes its own webhook URL client-side
+ * independently) — this is a deliberate, verified omission, not an
+ * oversight: whatever extra field the server sends is silently ignored,
+ * exactly as today.
+ *
+ * Subscriptions are account-level, never scoped by `project` — so
+ * `SubscriptionsHost` needs only the transport, mirroring `VarsHost`/
+ * `ProjectsHost`, not `DocumentsHost`.
+ *
+ * @module
+ */
+import { path } from "../http.js";
+import { unwrap } from "../types.js";
+/**
+ * The `console.subscriptions` namespace on a `W6WClient`.
+ *
+ * @example
+ * ```ts
+ * const subs = await client.console.subscriptions.list();
+ * const sub = await client.console.subscriptions.create("app_x", "new-message", {
+ *   workflowId: "wf_1",
+ * });
+ * await client.console.subscriptions.delete(sub.id);
+ * ```
+ */
+export class SubscriptionsApi {
+    #host;
+    /**
+     * @param host - The client this namespace issues requests through.
+     */
+    constructor(host) {
+        this.#host = host;
+    }
+    /**
+     * List every subscription the caller can see.
+     *
+     * @returns The subscriptions, unwrapped from the `subscriptions` envelope.
+     * @throws {ApiError} On any non-2xx.
+     */
+    async list() {
+        const res = await this.#host.request({
+            method: "GET",
+            path: "/subscriptions",
+        });
+        return unwrap(res, "subscriptions");
+    }
+    /**
+     * List the subscriptions bound to one workflow.
+     *
+     * **Dead code (HITL-4)** — zero call sites anywhere in studio or
+     * `@w6w/ui`. Built for SDK completeness only; see this module's header.
+     *
+     * @param workflowId - The `wf_…` id.
+     * @returns The subscriptions, unwrapped from the `subscriptions` envelope.
+     * @throws {ApiError} On any non-2xx.
+     */
+    async listForWorkflow(workflowId) {
+        const res = await this.#host.request({
+            method: "GET",
+            path: path `/workflows/${workflowId}/subscriptions`,
+        });
+        return unwrap(res, "subscriptions");
+    }
+    /**
+     * Fetch one subscription.
+     *
+     * **Dead code (HITL-4)** — zero call sites anywhere in studio or
+     * `@w6w/ui`. Built for SDK completeness only; see this module's header.
+     * Unlike `console.schedules.get`, this method throws `ApiError` on a 404
+     * rather than resolving `null` — there is no precedent on this domain to
+     * preserve, and this package's default `get` behavior is to throw.
+     *
+     * @param id - The `sub_…` id.
+     * @returns The subscription, unwrapped from the `subscription` envelope.
+     * @throws {ApiError} `404 unknown_subscription` when there is no such id.
+     */
+    async get(id) {
+        const res = await this.#host.request({
+            method: "GET",
+            path: path `/subscriptions/${id}`,
+        });
+        return unwrap(res, "subscription");
+    }
+    /**
+     * Bind a trigger to a workflow.
+     *
+     * @param appId - The app declaring the trigger.
+     * @param triggerKey - The trigger's key, as declared by the app's manifest.
+     * @param input - The subscription to create; forwarded verbatim as the whole body.
+     * @returns The created subscription, unwrapped from the `subscription` envelope (the server answers `201`).
+     * @throws {ApiError} `404 unknown_trigger`/`unknown_workflow` on a bad app/trigger/workflow id.
+     */
+    async create(appId, triggerKey, input) {
+        const res = await this.#host.request({
+            method: "POST",
+            path: path `/apps/${appId}/triggers/${triggerKey}/subscriptions`,
+            body: input,
+        });
+        return unwrap(res, "subscription");
+    }
+    /**
+     * Remove a subscription.
+     *
+     * Returns nothing: the server's `{ok: true}` carries no information a
+     * caller can use, mirroring `projects.delete`/`schedules.delete`'s
+     * established discard-to-void convention (not `apps.delete`'s
+     * informative-`{removed: number}` exception).
+     *
+     * @param id - The `sub_…` id.
+     * @throws {ApiError} `404 unknown_subscription` when there is no such id.
+     */
+    async delete(id) {
+        await this.#host.request({
+            method: "DELETE",
+            path: path `/subscriptions/${id}`,
+        });
+    }
+    /**
+     * List a subscription's delivered trigger events, newest first.
+     *
+     * **Dead code (HITL-4)** — zero call sites anywhere in studio or
+     * `@w6w/ui`. Built for SDK completeness only; see this module's header. No
+     * `limit` parameter is exposed — the server applies its own default of 50
+     * (`trigger-manager.ts:109`) and no studio caller ever sent one.
+     *
+     * @param id - The `sub_…` id.
+     * @returns The events, unwrapped from the `events` envelope.
+     * @throws {ApiError} On any non-2xx.
+     */
+    async listEvents(id) {
+        const res = await this.#host.request({
+            method: "GET",
+            path: path `/subscriptions/${id}/events`,
+        });
+        return unwrap(res, "events");
+    }
+    /**
+     * Re-queue a `failed`-status trigger event for another delivery attempt —
+     * a dead-letter re-dispatch.
+     *
+     * **Dead code (HITL-4)** — zero call sites anywhere in studio or
+     * `@w6w/ui`. Built for SDK completeness only; see this module's header.
+     * Returns nothing: the server's `{ok: true}` carries no information a
+     * caller can use, mirroring `projects.delete`/`schedules.delete`'s
+     * established discard-to-void convention.
+     *
+     * @param eventId - The trigger event's id.
+     * @throws {ApiError} `404 requeue_failed` when the event doesn't exist or isn't in `failed` status.
+     */
+    async requeueEvent(eventId) {
+        await this.#host.request({
+            method: "POST",
+            path: path `/trigger-events/${eventId}/requeue`,
+        });
+    }
+}
+//# sourceMappingURL=subscriptions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"subscriptions.js","sourceRoot":"","sources":["../../../src/console/subscriptions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,EAAqB,IAAI,EAAuB,MAAM,YAAY,CAAC;AAC1E,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AA2DrC;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,gBAAgB;IAClB,KAAK,CAAoB;IAElC;;OAEG;IACH,YAAY,IAAuB;QACjC,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;YAC5C,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,gBAAgB;SACvB,CAAC,CAAC;QACH,OAAO,MAAM,CAAiB,GAAG,EAAE,eAAe,CAAC,CAAC;IACtD,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,eAAe,CAAC,UAAkB;QACtC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU;YAC5C,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,IAAI,CAAA,cAAc,UAAU,gBAAgB;SACnD,CAAC,CAAC;QACH,OAAO,MAAM,CAAiB,GAAG,EAAE,eAAe,CAAC,CAAC;IACtD,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,GAAG,CAAC,EAAU;QAClB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU;YAC5C,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,IAAI,CAAA,kBAAkB,EAAE,EAAE;SACjC,CAAC,CAAC;QACH,OAAO,MAAM,CAAe,GAAG,EAAE,cAAc,CAAC,CAAC;IACnD,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,MAAM,CACV,KAAa,EACb,UAAkB,EAClB,KAA8B;QAE9B,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU;YAC5C,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,IAAI,CAAA,SAAS,KAAK,aAAa,UAAU,gBAAgB;YAC/D,IAAI,EAAE,KAAK;SACZ,CAAC,CAAC;QACH,OAAO,MAAM,CAAe,GAAG,EAAE,cAAc,CAAC,CAAC;IACnD,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,MAAM,CAAC,EAAU;QACrB,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU;YAChC,MAAM,EAAE,QAAQ;YAChB,IAAI,EAAE,IAAI,CAAA,kBAAkB,EAAE,EAAE;SACjC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,UAAU,CAAC,EAAU;QACzB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU;YAC5C,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,IAAI,CAAA,kBAAkB,EAAE,SAAS;SACxC,CAAC,CAAC;QACH,OAAO,MAAM,CAAwB,GAAG,EAAE,QAAQ,CAAC,CAAC;IACtD,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,YAAY,CAAC,OAAe;QAChC,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU;YAChC,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,IAAI,CAAA,mBAAmB,OAAO,UAAU;SAC/C,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/src/console/tenant-oauth-apps.d.ts

@@ -0,0 +1,188 @@
+/**
+ * `client.console.tenantOAuthApps.*` — a tenant administrator's own OAuth
+ * client overrides (list, upsert, remove) for the apps their tenant connects
+ * to.
+ *
+ * **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`.
+ * `@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.
+ *
+ * **The tenant is never a parameter here.** These three routes are scoped by
+ * the caller's own credential (the tenant claim on the bearer) plus a
+ * server-side tenant-admin check — unlike the operator family
+ * (`GET/PUT/DELETE /tenants/:id/oauth-app…`, `api/admin/tenants.ts:307-309`),
+ * which takes the tenant in the path and requires an operator. A `tenant`
+ * argument on any method below would be a tenant-selection affordance the
+ * server does not offer, so there is none.
+ *
+ * **Nothing here can read a client secret back.** {@linkcode
+ * TenantOAuthAppSummary} carries `hasClientSecret: boolean` and no secret
+ * field, mirroring the server's own summary projection
+ * (`packages/server/packages/db/repos/tenant_oauth_app.ts:26-37`, whose
+ * decrypting sibling `TenantOAuthApp` is entitled to exactly one caller in the
+ * BLL). That makes "no method on this namespace can ever resolve a stored
+ * secret" a compile-time fact rather than a runtime convention.
+ *
+ * **Response shapes are flat, no envelope key to peel with `unwrap()`** —
+ * mirroring `console/auth.ts:29-32` for this whole family. `list` returns the
+ * whole body deliberately, because `callbackUrl` rides beside `configs` and an
+ * `unwrap(res, "configs")` would silently drop it; `put` reaches one level in
+ * for `body.config`, which is the shape the server answers with (W4).
+ *
+ * **Wire shapes are planner pins, not reverse-engineered from a merged route.**
+ * `plan-B.md` § WIRE PINS W3–W5 fix `GET /tenant/oauth-apps`,
+ * `PUT /tenant/oauth-app/:app/:authKey` and
+ * `DELETE /tenant/oauth-app/:app/:authKey`; the tenant-scoped handlers are
+ * added by a sibling node on the server, against the same pins. The domain
+ * rules those handlers enforce already exist and are readable today in
+ * `packages/server/packages/bll/tenant-oauth-app.ts` — in particular
+ * `effectiveRow` (`:281-296`), which is what makes {@linkcode
+ * SetTenantOAuthAppInput}'s omission rule load-bearing rather than cosmetic.
+ * See {@linkcode SetTenantOAuthAppInput}.
+ *
+ * @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 `AuthHost` in `./auth.ts`.
+ */
+export interface TenantOAuthAppsHost {
+    /** Perform one request. */
+    request<T>(options: RequestOptions): Promise<HttpResponse<T>>;
+}
+/**
+ * One tenant OAuth client override, as the tenant-scoped routes project it
+ * (W3/W4). A summary only: it names whether a secret is stored, never the
+ * secret — the server's own summary row has no `clientSecret` column on it
+ * either (`db/repos/tenant_oauth_app.ts:26-37`).
+ */
+export interface TenantOAuthAppSummary {
+    /** The app this override applies to. */
+    appId: string;
+    /** The app manifest's `oauth2` auth method key. */
+    authKey: string;
+    /** The tenant's OAuth client id, or `null` when never set / cleared. */
+    clientId: string | null;
+    /**
+     * The redirect URI registered with the provider, as stored **server-side**.
+     * Read-only here: it is derived by the server, never sent by this client —
+     * {@linkcode SetTenantOAuthAppInput} carries no `redirectUri` key.
+     */
+    redirectUri: string | null;
+    /** Provider-specific extras (scopes, audience, …). `{}` when none. */
+    extra: Record<string, unknown>;
+    /** Whether a client secret is stored. **Never the secret itself.** */
+    hasClientSecret: boolean;
+    /** Whether the override is switched off (the host's own client is used instead). */
+    disabled: boolean;
+}
+/** `GET /tenant/oauth-apps` → 200 (W3). */
+export interface TenantOAuthAppsResponse {
+    /** Every override this tenant has, in the server's order. */
+    configs: TenantOAuthAppSummary[];
+    /** This host's OAuth callback, derived SERVER-SIDE. Display it; never assemble it. */
+    callbackUrl: string;
+}
+/**
+ * The body `put` sends (W4) — **built by OMISSION, key by key.**
+ *
+ * Every field is optional and every one of them means "set this field to this
+ * value", including `null`, which means "clear it". Absence means "leave
+ * whatever is stored alone": the server merges the request over the stored row
+ * (`bll/tenant-oauth-app.ts:281-296`'s `effectiveRow`, which tests each field
+ * with `!== undefined`), so a key that is not sent is a key that is not
+ * touched.
+ *
+ * **Sending a key you did not mean to set is destructive, and one of them is
+ * destructive SILENTLY.** `hasClientSecret` is computed as
+ * `input.clientSecret !== null` (`:291-293`), so an empty-string
+ * `clientSecret: ""` satisfies the enabled-override invariant at `:332` and the
+ * stored ciphertext is overwritten with an empty secret — no error anywhere.
+ * The neighbouring fields fail loudly instead (`clientId: ""` at `:324`,
+ * `redirectUri` at `:313-322`). That asymmetry is the entire reason this type
+ * has no required field and this module builds the body key by key: omit what
+ * the user did not touch, never send `""`.
+ *
+ * **No `redirectUri` and no `force`.** Neither exists on this surface — the
+ * callback URL is derived server-side (W3's `callbackUrl`) and the operator's
+ * `?force` affordance is not offered to a tenant admin (W4). A field the SDK
+ * declares is a field a form will fill, so neither is declared, and
+ * {@linkcode toSetBody} additionally refuses to forward either at runtime.
+ */
+export interface SetTenantOAuthAppInput {
+    /** The OAuth client id. `null` clears it. */
+    clientId?: string | null;
+    /**
+     * The OAuth client secret, write-only. `null` clears it. Sending `""` IS
+     * carried to the wire and IS destructive (silently overwrites the stored
+     * secret) — omit this key instead of sending `""` when not changing it.
+     */
+    clientSecret?: string | null;
+    /** Provider-specific extras. `null` clears them to `{}`. */
+    extra?: Record<string, unknown> | null;
+    /** Whether to switch the override off. */
+    disabled?: boolean;
+}
+/**
+ * The `console.tenantOAuthApps` namespace on a `W6WClient` — the caller's own
+ * tenant, never a tenant of its choosing.
+ *
+ * @example
+ * ```ts
+ * const { configs, callbackUrl } = await client.console.tenantOAuthApps.list();
+ * // Register `callbackUrl` with the provider — never assemble it client-side.
+ * await client.console.tenantOAuthApps.put("sendgrid", "oauth2", { clientId: "abc" });
+ * await client.console.tenantOAuthApps.remove("sendgrid", "oauth2");
+ * ```
+ */
+export declare class TenantOAuthAppsApi {
+    #private;
+    /**
+     * @param host - The client this namespace issues requests through.
+     */
+    constructor(host: TenantOAuthAppsHost);
+    /**
+     * List the caller's tenant's OAuth overrides, plus this host's callback URL.
+     *
+     * Returns the body VERBATIM rather than unwrapping `configs`: `callbackUrl`
+     * rides beside it and is the one value a caller cannot compute for itself.
+     *
+     * @returns Every override for this tenant, and the server-derived callback URL.
+     * @throws {ApiError} `403` when the caller does not administer its tenant.
+     */
+    list(): Promise<TenantOAuthAppsResponse>;
+    /**
+     * Create or update one override, sending **only the fields `input` sets**.
+     *
+     * @param appId - The app id.
+     * @param authKey - The app manifest's `oauth2` auth method key.
+     * @param input - The fields to set; an omitted field is left untouched server-side.
+     * @returns The stored summary (the server answers `201 { config }`). Never carries a secret.
+     * @throws {ApiError} `403` when the caller does not administer its tenant;
+     * `404 unknown_app` when the app does not exist or does not support a tenant
+     * OAuth client; `400 invalid_config`/`invalid_redirect_uri` when the merged
+     * row would be an enabled override missing a required field.
+     */
+    put(appId: string, authKey: string, input: SetTenantOAuthAppInput): Promise<TenantOAuthAppSummary>;
+    /**
+     * Remove one override; the tenant falls back to the host's own OAuth client.
+     *
+     * Resolves `void`, discarding the server's uninformative `{ok: true}` —
+     * mirroring `projects.delete`/`schedules.delete`, not `apps.delete` (which
+     * keeps a genuinely informative count).
+     *
+     * @param appId - The app id.
+     * @param authKey - The app manifest's `oauth2` auth method key.
+     * @throws {ApiError} `403` when the caller does not administer its tenant;
+     * `404 unknown_tenant_oauth_app` when there is no override to remove.
+     */
+    remove(appId: string, authKey: string): Promise<void>;
+}
+//# sourceMappingURL=tenant-oauth-apps.d.ts.map

package/dist/src/console/tenant-oauth-apps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-oauth-apps.d.ts","sourceRoot":"","sources":["../../../src/console/tenant-oauth-apps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAQ,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAE1E;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,2BAA2B;IAC3B,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;CAC/D;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB;;;;OAIG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,sEAAsE;IACtE,eAAe,EAAE,OAAO,CAAC;IACzB,oFAAoF;IACpF,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,2CAA2C;AAC3C,MAAM,WAAW,uBAAuB;IACtC,6DAA6D;IAC7D,OAAO,EAAE,qBAAqB,EAAE,CAAC;IACjC,sFAAsF;IACtF,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,sBAAsB;IACrC,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACvC,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AA0BD;;;;;;;;;;;GAWG;AACH,qBAAa,kBAAkB;;IAG7B;;OAEG;gBACS,IAAI,EAAE,mBAAmB;IAIrC;;;;;;;;OAQG;IACG,IAAI,IAAI,OAAO,CAAC,uBAAuB,CAAC;IAQ9C;;;;;;;;;;;OAWG;IACG,GAAG,CACP,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,sBAAsB,GAC5B,OAAO,CAAC,qBAAqB,CAAC;IASjC;;;;;;;;;;;OAWG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAM5D"}