@cadenya/cadenya 0.134.0 → 1.0.0

package/src/resources/widgets.ts

@@ -1,317 +1,223 @@
-// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+// Generated by redwood. Do not edit by hand.
 
-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';
+import { HttpClient, RequestOptions, APIPromise, pathSegment, snapshotParams } from '../core/http.js';
+import { Page } from '../core/pagination.js';
+import type { CreateResourceMetadata, ListWidgetsResponse, UpdateResourceMetadata, Widget, WidgetSpec } from '../types.js';
 
-/**
- * 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 {
+export interface WidgetListParams {
   /**
-   * 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.
+   * Workspace ID.
+   * 
+   * Defaults to the client-level `workspaceId` option or the CADENYA_WORKSPACE_ID environment variable.
    */
-  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 });
-  }
-
+  workspaceId?: string;
   /**
-   * Retrieves a widget by ID
+   * Maximum number of results to return.
    */
-  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);
-  }
-
+  limit?: number;
   /**
-   * 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.
+   * Pagination cursor from previous response.
    */
-  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 });
-  }
-
+  cursor?: string;
   /**
-   * Lists all widgets in a workspace
+   * Filter to widgets bound to a specific agent. Accepts the canonical
+   *  `agent_…` form or the `external_id:<value>` form.
    */
-  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,
-    });
-  }
-
+  agentId?: string;
   /**
-   * Deletes a widget. Its hostname stops serving and all of its sessions are
-   * revoked.
+   * 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).
    */
-  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]),
-    });
-  }
-
+  labels?: string;
   /**
-   * 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.
+   * Sort order for results (asc or desc by creation time).
    */
-  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 });
-  }
-
+  sortOrder?: string;
   /**
-   * Transitions an archived widget back to STATE_ACTIVE so its hostname serves
-   * traffic again. Sessions revoked by archival stay revoked; mint new ones.
+   * When true, the `info` field on each returned widget is populated.
+   *  Requests with this flag count more against your rate limit.
    */
-  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,
-    });
-  }
+  includeInfo?: boolean;
 }
 
-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.
-   */
+export interface WidgetCreateParams {
+  metadata: CreateResourceMetadata;
   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.
+   * Workspace ID.
+   * 
+   * Defaults to the client-level `workspaceId` option or the CADENYA_WORKSPACE_ID environment variable.
    */
-  variationId?: string;
+  workspaceId?: string;
 }
 
-export interface WidgetCreateParams {
+export interface WidgetRetrieveParams {
   /**
-   * Path param: Workspace ID.
+   * Workspace ID.
+   * 
+   * Defaults to the client-level `workspaceId` option or the CADENYA_WORKSPACE_ID environment variable.
    */
   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 {
+export interface WidgetDeleteParams {
   /**
    * Workspace ID.
+   * 
+   * Defaults to the client-level `workspaceId` option or the CADENYA_WORKSPACE_ID environment variable.
    */
   workspaceId?: string;
 }
 
 export interface WidgetUpdateParams {
   /**
-   * Path param: Workspace ID.
+   * Workspace ID.
+   * 
+   * Defaults to the client-level `workspaceId` option or the CADENYA_WORKSPACE_ID environment variable.
    */
   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.
-   */
+  metadata?: UpdateResourceMetadata;
   spec?: WidgetSpec;
-
   /**
-   * Body param: Fields to update.
+   * Fields to update.
    */
   updateMask?: string;
 }
 
-export interface WidgetListParams extends CursorPaginationParams {
+export interface WidgetArchiveParams {
   /**
-   * Path param: Workspace ID.
+   * Workspace ID.
+   * 
+   * Defaults to the client-level `workspaceId` option or the CADENYA_WORKSPACE_ID environment variable.
    */
   workspaceId?: string;
+}
 
+export interface WidgetUnarchiveParams {
   /**
-   * Query param: Filter to widgets bound to a specific agent. Accepts the canonical
-   * `agent_…` form or the `external_id:<value>` form.
+   * Workspace ID.
+   * 
+   * Defaults to the client-level `workspaceId` option or the CADENYA_WORKSPACE_ID environment variable.
    */
-  agentId?: string;
+  workspaceId?: string;
+}
+
+export class Widgets {
+  constructor(private readonly _client: HttpClient) {}
+
+  /**
+   * List widgets
+   * 
+   * @example
+   * ```ts
+   * const page = await client.widgets.list();
+   * for await (const item of page) {
+   *   // auto-fetches every page
+   * }
+   * ```
+   */
+  async list(params?: WidgetListParams, options?: RequestOptions): Promise<Page<Widget>> {
+    const workspaceId = String(params?.workspaceId ?? this._client.defaults['workspaceId'] ?? '').trim() || undefined;
+    if (workspaceId === undefined) throw new Error("Missing 'workspaceId': pass it in params, set it on the client, or set the CADENYA_WORKSPACE_ID environment variable.");
+    const _base = snapshotParams(params);
+    const response = await this._client.request<ListWidgetsResponse>({ method: 'GET', path: `/v1/workspaces/${pathSegment('workspaceId', workspaceId)}/widgets`, query: { limit: params?.limit, cursor: params?.cursor, agentId: params?.agentId, labels: params?.labels, sortOrder: params?.sortOrder, includeInfo: params?.includeInfo } }, options);
+    return new Page(response.items ?? [], response.pagination?.nextCursor, (cursor) => this.list({ ..._base, cursor: cursor }, options));
+  }
 
   /**
-   * Query param: When true, the `info` field on each returned widget is populated.
-   * Requests with this flag count more against your rate limit.
+   * Create a new widget
+   * 
+   * @example
+   * ```ts
+   * const widget = await client.widgets.create({ metadata: { name: 'sample' }, spec: { agentId: 'sample' } });
+   * ```
    */
-  includeInfo?: boolean;
+  create(params: WidgetCreateParams, options?: RequestOptions): APIPromise<Widget> {
+    return this._client.requestAPI<Widget>(() => {
+      const workspaceId = String(params.workspaceId ?? this._client.defaults['workspaceId'] ?? '').trim() || undefined;
+      if (workspaceId === undefined) throw new Error("Missing 'workspaceId': pass it in params, set it on the client, or set the CADENYA_WORKSPACE_ID environment variable.");
+      return { method: 'POST', path: `/v1/workspaces/${pathSegment('workspaceId', workspaceId)}/widgets`, body: { metadata: params.metadata, spec: params.spec } };
+    }, options);
+  }
 
   /**
-   * 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).
+   * Get a widget by ID
+   * 
+   * @example
+   * ```ts
+   * const widget = await client.widgets.retrieve('_123');
+   * ```
    */
-  labels?: string;
+  retrieve(id: string, params?: WidgetRetrieveParams, options?: RequestOptions): APIPromise<Widget> {
+    return this._client.requestAPI<Widget>(() => {
+      const workspaceId = String(params?.workspaceId ?? this._client.defaults['workspaceId'] ?? '').trim() || undefined;
+      if (workspaceId === undefined) throw new Error("Missing 'workspaceId': pass it in params, set it on the client, or set the CADENYA_WORKSPACE_ID environment variable.");
+      return { method: 'GET', path: `/v1/workspaces/${pathSegment('workspaceId', workspaceId)}/widgets/${pathSegment('id', id)}` };
+    }, options);
+  }
 
   /**
-   * Query param: Sort order for results (asc or desc by creation time).
+   * Delete a widget
+   * 
+   * @example
+   * ```ts
+   * await client.widgets.delete('_123');
+   * ```
    */
-  sortOrder?: string;
-}
+  delete(id: string, params?: WidgetDeleteParams, options?: RequestOptions): APIPromise<void> {
+    return this._client.requestAPI<void>(() => {
+      const workspaceId = String(params?.workspaceId ?? this._client.defaults['workspaceId'] ?? '').trim() || undefined;
+      if (workspaceId === undefined) throw new Error("Missing 'workspaceId': pass it in params, set it on the client, or set the CADENYA_WORKSPACE_ID environment variable.");
+      return { method: 'DELETE', path: `/v1/workspaces/${pathSegment('workspaceId', workspaceId)}/widgets/${pathSegment('id', id)}`, void: true };
+    }, options);
+  }
 
-export interface WidgetDeleteParams {
   /**
-   * Workspace ID.
+   * Update a widget
+   * 
+   * @example
+   * ```ts
+   * const widget = await client.widgets.update('_123');
+   * ```
    */
-  workspaceId?: string;
-}
+  update(id: string, params?: WidgetUpdateParams, options?: RequestOptions): APIPromise<Widget> {
+    return this._client.requestAPI<Widget>(() => {
+      const workspaceId = String(params?.workspaceId ?? this._client.defaults['workspaceId'] ?? '').trim() || undefined;
+      if (workspaceId === undefined) throw new Error("Missing 'workspaceId': pass it in params, set it on the client, or set the CADENYA_WORKSPACE_ID environment variable.");
+      return { method: 'PATCH', path: `/v1/workspaces/${pathSegment('workspaceId', workspaceId)}/widgets/${pathSegment('id', id)}`, body: { metadata: params?.metadata, spec: params?.spec, updateMask: params?.updateMask } };
+    }, options);
+  }
 
-export interface WidgetArchiveParams {
   /**
-   * Workspace ID.
+   * Archive a widget
+   * 
+   * @example
+   * ```ts
+   * const widget = await client.widgets.archive('_123');
+   * ```
    */
-  workspaceId?: string;
-}
+  archive(id: string, params?: WidgetArchiveParams, options?: RequestOptions): APIPromise<Widget> {
+    return this._client.requestAPI<Widget>(() => {
+      const workspaceId = String(params?.workspaceId ?? this._client.defaults['workspaceId'] ?? '').trim() || undefined;
+      if (workspaceId === undefined) throw new Error("Missing 'workspaceId': pass it in params, set it on the client, or set the CADENYA_WORKSPACE_ID environment variable.");
+      return { method: 'POST', path: `/v1/workspaces/${pathSegment('workspaceId', workspaceId)}/widgets/${pathSegment('id', id)}:archive` };
+    }, options);
+  }
 
-export interface WidgetUnarchiveParams {
   /**
-   * Workspace ID.
+   * Unarchive a widget
+   * 
+   * @example
+   * ```ts
+   * const widget = await client.widgets.unarchive('_123');
+   * ```
    */
-  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,
-  };
+  unarchive(id: string, params?: WidgetUnarchiveParams, options?: RequestOptions): APIPromise<Widget> {
+    return this._client.requestAPI<Widget>(() => {
+      const workspaceId = String(params?.workspaceId ?? this._client.defaults['workspaceId'] ?? '').trim() || undefined;
+      if (workspaceId === undefined) throw new Error("Missing 'workspaceId': pass it in params, set it on the client, or set the CADENYA_WORKSPACE_ID environment variable.");
+      return { method: 'POST', path: `/v1/workspaces/${pathSegment('workspaceId', workspaceId)}/widgets/${pathSegment('id', id)}:unarchive` };
+    }, options);
+  }
 }