@cadenya/cadenya 0.129.0 → 0.131.0

package/src/resources/widgets.ts

@@ -0,0 +1,317 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import * as AccountAPI from './account';
+import * as Shared from './shared';
+import { APIPromise } from '../core/api-promise';
+import { CursorPagination, type CursorPaginationParams, PagePromise } from '../core/pagination';
+import { buildHeaders } from '../internal/headers';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+/**
+ * Manage embeddable chat widgets. A widget binds an agent to a globally
+ *  unique hostname with a per-widget origin allowlist; browsers reach it with
+ *  session tokens minted via WidgetSessionService.
+ */
+export class Widgets extends APIResource {
+  /**
+   * Creates a widget bound to an agent. The widget's DNS label and hostname are
+   * generated by the server and returned in `info`. The hostname may take up to a
+   * minute to become reachable while the edge propagates.
+   */
+  create(params: WidgetCreateParams, options?: RequestOptions): APIPromise<Widget> {
+    const { workspaceId = this._client.workspaceID, ...body } = params;
+    return this._client.post(path`/v1/workspaces/${workspaceId}/widgets`, { body, ...options });
+  }
+
+  /**
+   * Retrieves a widget by ID
+   */
+  retrieve(
+    id: string,
+    params: WidgetRetrieveParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<Widget> {
+    const { workspaceId = this._client.workspaceID } = params ?? {};
+    return this._client.get(path`/v1/workspaces/${workspaceId}/widgets/${id}`, options);
+  }
+
+  /**
+   * Updates a widget's metadata or spec. The DNS label is immutable and cannot be
+   * updated. Re-pointing the agent affects new sessions only; in-flight
+   * conversations finish against the agent they started with.
+   */
+  update(id: string, params: WidgetUpdateParams, options?: RequestOptions): APIPromise<Widget> {
+    const { workspaceId = this._client.workspaceID, ...body } = params;
+    return this._client.patch(path`/v1/workspaces/${workspaceId}/widgets/${id}`, { body, ...options });
+  }
+
+  /**
+   * Lists all widgets in a workspace
+   */
+  list(
+    params: WidgetListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<WidgetsCursorPagination, Widget> {
+    const { workspaceId = this._client.workspaceID, ...query } = params ?? {};
+    return this._client.getAPIList(path`/v1/workspaces/${workspaceId}/widgets`, CursorPagination<Widget>, {
+      query,
+      ...options,
+    });
+  }
+
+  /**
+   * Deletes a widget. Its hostname stops serving and all of its sessions are
+   * revoked.
+   */
+  delete(
+    id: string,
+    params: WidgetDeleteParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<void> {
+    const { workspaceId = this._client.workspaceID } = params ?? {};
+    return this._client.delete(path`/v1/workspaces/${workspaceId}/widgets/${id}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
+  /**
+   * Transitions a widget to STATE_ARCHIVED. The hostname stops serving at the edge,
+   * existing sessions are revoked, and no new sessions can be minted. Reversible via
+   * :unarchive.
+   */
+  archive(id: string, params: WidgetArchiveParams, options?: RequestOptions): APIPromise<Widget> {
+    const { workspaceId = this._client.workspaceID, ...body } = params;
+    return this._client.post(path`/v1/workspaces/${workspaceId}/widgets/${id}:archive`, { body, ...options });
+  }
+
+  /**
+   * Transitions an archived widget back to STATE_ACTIVE so its hostname serves
+   * traffic again. Sessions revoked by archival stay revoked; mint new ones.
+   */
+  unarchive(id: string, params: WidgetUnarchiveParams, options?: RequestOptions): APIPromise<Widget> {
+    const { workspaceId = this._client.workspaceID, ...body } = params;
+    return this._client.post(path`/v1/workspaces/${workspaceId}/widgets/${id}:unarchive`, {
+      body,
+      ...options,
+    });
+  }
+}
+
+export type WidgetsCursorPagination = CursorPagination<Widget>;
+
+/**
+ * Widget is an embeddable chat surface bound to a single agent. Each widget owns a
+ * globally unique, immutable DNS label under the widgets domain (e.g.
+ * "k7m2xq9fp4wn.widgets.cadenya.com"): one widget = one hostname = one origin
+ * allowlist = one agent binding. Browsers talk to the widget host with session
+ * bearer tokens minted server-side via WidgetSessionService.
+ */
+export interface Widget {
+  /**
+   * Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
+   */
+  metadata: Shared.ResourceMetadata;
+
+  /**
+   * WidgetSpec is the user-provided configuration for a widget.
+   */
+  spec: WidgetSpec;
+
+  /**
+   * The current lifecycle state of the widget. Output only. Widgets are created
+   * STATE_ACTIVE; use the :archive and :unarchive actions to transition between
+   * states.
+   */
+  state: 'STATE_UNSPECIFIED' | 'STATE_ACTIVE' | 'STATE_ARCHIVED';
+
+  /**
+   * WidgetInfo provides read-only server-derived data about a widget.
+   */
+  info?: WidgetInfo;
+}
+
+/**
+ * WidgetInfo provides read-only server-derived data about a widget.
+ */
+export interface WidgetInfo {
+  /**
+   * BareMetadata contains the minimal metadata for a resource: the ID and an
+   * optional human-readable name. These are used for reference fields where the full
+   * metadata (account scoping, timestamps, labels, external IDs) is not needed —
+   * e.g., the tool references inside an agent variation spec or the tools assigned
+   * to an objective. Both fields are server-populated; clients provide IDs through
+   * sibling fields rather than by constructing a BareMetadata themselves.
+   */
+  agent?: Shared.BareMetadata;
+
+  /**
+   * A profile identifies a user or non-human principal (such as an API key) at the
+   * account level. Profiles are account-scoped and can be granted access to multiple
+   * workspaces.
+   */
+  createdBy?: AccountAPI.Profile;
+
+  /**
+   * The widget's DNS label — the single hostname label under the widgets domain.
+   * Server-generated at creation, globally unique, immutable, and deliberately
+   * unrelated to the widget's id.
+   */
+  dnsLabel?: string;
+
+  /**
+   * The full hostname browsers talk to. Authoritative — clients must use this value
+   * rather than constructing the hostname themselves.
+   */
+  host?: string;
+}
+
+/**
+ * WidgetSpec is the user-provided configuration for a widget.
+ */
+export interface WidgetSpec {
+  /**
+   * Agent this widget is bound to. Accepts the canonical `agent_…` form or the
+   * `external_id:<value>` form. Sessions copy the agent at mint: re-pointing a
+   * widget's agent affects new sessions only.
+   */
+  agentId: string;
+
+  /**
+   * Web origins allowed to embed and use this widget, enforced at the edge on every
+   * browser request. Exact origins only (scheme + host + optional port), no paths,
+   * no wildcard subdomains.
+   */
+  originAllowlist?: Array<string>;
+
+  /**
+   * Optional explicit variation pin. Must belong to the widget's agent. When set,
+   * every objective created through the widget runs this variation — bypassing the
+   * agent's variation_selection_mode (staged rollout: pin in production, follow in
+   * staging, promote by clearing). When unset, the agent's selection mode chooses
+   * per conversation.
+   */
+  variationId?: string;
+}
+
+export interface WidgetCreateParams {
+  /**
+   * Path param: Workspace ID.
+   */
+  workspaceId?: string;
+
+  /**
+   * Body param: CreateResourceMetadata contains the user-provided fields for
+   * creating a workspace-scoped resource. Read-only fields (id, account_id,
+   * workspace_id, profile_id, created_at) are excluded since they are set by the
+   * server.
+   */
+  metadata: Shared.CreateResourceMetadata;
+
+  /**
+   * Body param: WidgetSpec is the user-provided configuration for a widget.
+   */
+  spec: WidgetSpec;
+}
+
+export interface WidgetRetrieveParams {
+  /**
+   * Workspace ID.
+   */
+  workspaceId?: string;
+}
+
+export interface WidgetUpdateParams {
+  /**
+   * Path param: Workspace ID.
+   */
+  workspaceId?: string;
+
+  /**
+   * Body param: UpdateResourceMetadata contains the user-provided fields for
+   * updating a workspace-scoped resource. Read-only fields (id, account_id,
+   * workspace_id, profile_id, created_at) are excluded since they are set by the
+   * server.
+   */
+  metadata?: Shared.UpdateResourceMetadata;
+
+  /**
+   * Body param: WidgetSpec is the user-provided configuration for a widget.
+   */
+  spec?: WidgetSpec;
+
+  /**
+   * Body param: Fields to update.
+   */
+  updateMask?: string;
+}
+
+export interface WidgetListParams extends CursorPaginationParams {
+  /**
+   * Path param: Workspace ID.
+   */
+  workspaceId?: string;
+
+  /**
+   * Query param: Filter to widgets bound to a specific agent. Accepts the canonical
+   * `agent_…` form or the `external_id:<value>` form.
+   */
+  agentId?: string;
+
+  /**
+   * Query param: When true, the `info` field on each returned widget is populated.
+   * Requests with this flag count more against your rate limit.
+   */
+  includeInfo?: boolean;
+
+  /**
+   * Query param: Filters by metadata labels. Comma-separated key=value pairs, e.g.
+   * "env=prod,team=ai". A resource matches only if every pair matches exactly (AND
+   * semantics).
+   */
+  labels?: string;
+
+  /**
+   * Query param: Sort order for results (asc or desc by creation time).
+   */
+  sortOrder?: string;
+}
+
+export interface WidgetDeleteParams {
+  /**
+   * Workspace ID.
+   */
+  workspaceId?: string;
+}
+
+export interface WidgetArchiveParams {
+  /**
+   * Workspace ID.
+   */
+  workspaceId?: string;
+}
+
+export interface WidgetUnarchiveParams {
+  /**
+   * Workspace ID.
+   */
+  workspaceId?: string;
+}
+
+export declare namespace Widgets {
+  export {
+    type Widget as Widget,
+    type WidgetInfo as WidgetInfo,
+    type WidgetSpec as WidgetSpec,
+    type WidgetsCursorPagination as WidgetsCursorPagination,
+    type WidgetCreateParams as WidgetCreateParams,
+    type WidgetRetrieveParams as WidgetRetrieveParams,
+    type WidgetUpdateParams as WidgetUpdateParams,
+    type WidgetListParams as WidgetListParams,
+    type WidgetDeleteParams as WidgetDeleteParams,
+    type WidgetArchiveParams as WidgetArchiveParams,
+    type WidgetUnarchiveParams as WidgetUnarchiveParams,
+  };
+}

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.129.0'; // x-release-please-version
+export const VERSION = '0.131.0'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.129.0";
+export declare const VERSION = "0.131.0";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.129.0";
+export declare const VERSION = "0.131.0";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.129.0'; // x-release-please-version
+exports.VERSION = '0.131.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '0.129.0'; // x-release-please-version
+export const VERSION = '0.131.0'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map