@cadenya/cadenya 0.129.0 → 0.131.0

package/src/client.ts

@@ -88,6 +88,38 @@ import {
   Uploads as UploadsAPIUploads,
 } from './resources/uploads';
 import { UnsafeUnwrapWebhookEvent, UnwrapWebhookEvent, Webhooks } from './resources/webhooks';
+import {
+  SubjectAssertion,
+  SubjectReference,
+  TenantAssertion,
+  TenantReference,
+  WidgetSession,
+  WidgetSessionCreateParams,
+  WidgetSessionDeleteParams,
+  WidgetSessionDeleteTenantParams,
+  WidgetSessionDeleteTenantResponse,
+  WidgetSessionInfo,
+  WidgetSessionListParams,
+  WidgetSessionRetrieveParams,
+  WidgetSessionRevokeParams,
+  WidgetSessionSpec,
+  WidgetSessions,
+  WidgetSessionsCursorPagination,
+} from './resources/widget-sessions';
+import {
+  Widget,
+  WidgetArchiveParams,
+  WidgetCreateParams,
+  WidgetDeleteParams,
+  WidgetInfo,
+  WidgetListParams,
+  WidgetRetrieveParams,
+  WidgetSpec,
+  WidgetUnarchiveParams,
+  WidgetUpdateParams,
+  Widgets,
+  WidgetsCursorPagination,
+} from './resources/widgets';
 import {
   WorkspaceSecret,
   WorkspaceSecretCreateParams,
@@ -1102,6 +1134,19 @@ export class Cadenya {
    */
   workspaceAdmin: API.WorkspaceAdmin = new API.WorkspaceAdmin(this);
   webhooks: API.Webhooks = new API.Webhooks(this);
+  /**
+   * 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.
+   */
+  widgets: API.Widgets = new API.Widgets(this);
+  /**
+   * Mint and manage widget sessions. Session creation is server-to-server only:
+   *  the customer's backend authenticates its visitor, asserts tenant/subject
+   *  context, attaches any per-visitor secrets, and receives a short-lived
+   *  bearer token the browser uses against the widget host.
+   */
+  widgetSessions: API.WidgetSessions = new API.WidgetSessions(this);
 }
 
 Cadenya.AIProviderKeys = AIProviderKeys;
@@ -1120,6 +1165,8 @@ Cadenya.WorkspaceSecrets = WorkspaceSecrets;
 Cadenya.Workspaces = Workspaces;
 Cadenya.WorkspaceAdmin = WorkspaceAdmin;
 Cadenya.Webhooks = Webhooks;
+Cadenya.Widgets = Widgets;
+Cadenya.WidgetSessions = WidgetSessions;
 
 export declare namespace Cadenya {
   export type RequestOptions = Opts.RequestOptions;
@@ -1393,6 +1440,40 @@ export declare namespace Cadenya {
     type UnwrapWebhookEvent as UnwrapWebhookEvent,
   };
 
+  export {
+    Widgets as Widgets,
+    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,
+  };
+
+  export {
+    WidgetSessions as WidgetSessions,
+    type SubjectAssertion as SubjectAssertion,
+    type SubjectReference as SubjectReference,
+    type TenantAssertion as TenantAssertion,
+    type TenantReference as TenantReference,
+    type WidgetSession as WidgetSession,
+    type WidgetSessionInfo as WidgetSessionInfo,
+    type WidgetSessionSpec as WidgetSessionSpec,
+    type WidgetSessionDeleteTenantResponse as WidgetSessionDeleteTenantResponse,
+    type WidgetSessionsCursorPagination as WidgetSessionsCursorPagination,
+    type WidgetSessionCreateParams as WidgetSessionCreateParams,
+    type WidgetSessionRetrieveParams as WidgetSessionRetrieveParams,
+    type WidgetSessionListParams as WidgetSessionListParams,
+    type WidgetSessionDeleteParams as WidgetSessionDeleteParams,
+    type WidgetSessionDeleteTenantParams as WidgetSessionDeleteTenantParams,
+    type WidgetSessionRevokeParams as WidgetSessionRevokeParams,
+  };
+
   export type AccountResourceMetadata = API.AccountResourceMetadata;
   export type BareMetadata = API.BareMetadata;
   export type CreateOperationMetadata = API.CreateOperationMetadata;

package/src/resources/api-keys.ts

@@ -160,10 +160,11 @@ export interface APIKeySpec {
    * Scopes granted to this key. Each entry is a colon-separated resource:verb string
    * (e.g. "objectives:manage").
    *
-   * Resources: agents, objectives, tools, memory, api_keys, workspaces, secrets,
-   * account. Verbs: read and manage, where manage implies read — a stored scope set
-   * is normalized to drop "x:read" when "x:manage" is present. The secrets and
-   * account resources support only manage. "\*" is an explicit full-access grant.
+   * Resources: agents, objectives, tools, memory, api_keys, workspaces, widgets,
+   * widget_sessions, secrets, account. Verbs: read and manage, where manage implies
+   * read — a stored scope set is normalized to drop "x:read" when "x:manage" is
+   * present. The secrets and account resources support only manage. "\*" is an
+   * explicit full-access grant.
    *
    * Scopes are deny-by-default: a key with an empty list can call only scope-free
    * endpoints. Full access is always an explicit "\*" grant.

package/src/resources/index.ts

@@ -217,6 +217,38 @@ export {
   type UploadRetrieveParams,
 } from './uploads';
 export { Webhooks, type UnsafeUnwrapWebhookEvent, type UnwrapWebhookEvent } from './webhooks';
+export {
+  WidgetSessions,
+  type SubjectAssertion,
+  type SubjectReference,
+  type TenantAssertion,
+  type TenantReference,
+  type WidgetSession,
+  type WidgetSessionInfo,
+  type WidgetSessionSpec,
+  type WidgetSessionDeleteTenantResponse,
+  type WidgetSessionCreateParams,
+  type WidgetSessionRetrieveParams,
+  type WidgetSessionListParams,
+  type WidgetSessionDeleteParams,
+  type WidgetSessionDeleteTenantParams,
+  type WidgetSessionRevokeParams,
+  type WidgetSessionsCursorPagination,
+} from './widget-sessions';
+export {
+  Widgets,
+  type Widget,
+  type WidgetInfo,
+  type WidgetSpec,
+  type WidgetCreateParams,
+  type WidgetRetrieveParams,
+  type WidgetUpdateParams,
+  type WidgetListParams,
+  type WidgetDeleteParams,
+  type WidgetArchiveParams,
+  type WidgetUnarchiveParams,
+  type WidgetsCursorPagination,
+} from './widgets';
 export {
   WorkspaceAdmin,
   type WorkspaceMember,

package/src/resources/objectives/objectives.ts

@@ -4,6 +4,7 @@ import { APIResource } from '../../core/resource';
 import * as ObjectivesAPI from './objectives';
 import * as AccountAPI from '../account';
 import * as Shared from '../shared';
+import * as WidgetSessionsAPI from '../widget-sessions';
 import * as AgentsAPI from '../agents/agents';
 import * as SchedulesAPI from '../agents/schedules';
 import * as VariationsAPI from '../agents/variations';
@@ -587,6 +588,12 @@ export interface Objective {
    */
   parentObjectiveId?: string;
 
+  /**
+   * Parameters forced onto this objective's tool calls, as provided at creation. See
+   * CreateObjectiveRequest.pinned_parameters for semantics.
+   */
+  pinnedParameters?: { [key: string]: string };
+
   /**
    * Secrets that can be used in the headers for tool calls using the secret
    * interpolation format.
@@ -1131,6 +1138,28 @@ export interface ObjectiveInfo {
    * Total number of tool calls made during execution
    */
   totalToolCalls: number;
+
+  /**
+   * SubjectReference is the read-only echo of a resource's subject association,
+   * carrying both Cadenya's canonical id and the customer's own key.
+   */
+  subject?: WidgetSessionsAPI.SubjectReference;
+
+  /**
+   * TenantReference is the read-only echo of a resource's tenant association,
+   * carrying both Cadenya's canonical id and the customer's own key.
+   */
+  tenant?: WidgetSessionsAPI.TenantReference;
+
+  /**
+   * 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.
+   */
+  widget?: Shared.BareMetadata;
 }
 
 export interface ObjectiveSecret {
@@ -1351,12 +1380,37 @@ export interface ObjectiveCreateParams {
    */
   metadata?: Shared.CreateOperationMetadata;
 
+  /**
+   * Body param: Parameters forced onto this objective's tool calls. A pinned
+   * parameter is an overlay on a tool's JSON schema: the parameter is removed from
+   * what the LLM sees, and its value is always overwritten server-side with the
+   * pinned value — the model cannot choose a different value for it.
+   */
+  pinnedParameters?: { [key: string]: string };
+
   /**
    * Body param: Secrets that can be used in the headers for tool calls using the
    * secret interpolation format.
    */
   secrets?: Array<ObjectiveCreateParams.Secret>;
 
+  /**
+   * Body param: SubjectAssertion identifies a person within a tenant in the
+   * customer's own namespace — typically their user id. Asserting a subject upserts
+   * the subject record under the asserted tenant and associates the created resource
+   * with it. A subject assertion is only valid alongside a tenant assertion: subject
+   * identifiers are scoped to their tenant.
+   */
+  subject?: WidgetSessionsAPI.SubjectAssertion;
+
+  /**
+   * Body param: TenantAssertion identifies a tenant in the customer's own namespace
+   * — their org, company, or team identifier for an end user. Asserting a tenant
+   * upserts the tenant record in the workspace (keyed on `id` as the tenant's
+   * external_id) and associates the created resource with it.
+   */
+  tenant?: WidgetSessionsAPI.TenantAssertion;
+
   /**
    * Body param: Optional explicit variation selection. Overrides the agent's
    * variation_selection_mode.
@@ -1443,6 +1497,30 @@ export interface ObjectiveListParams extends CursorPaginationParams {
     | 'STATE_CANCELLED'
     | 'STATE_FINALIZED'
     | 'STATE_TIMED_OUT';
+
+  /**
+   * Query param: Filter to objectives associated with a subject. Accepts the
+   * canonical `subj_…` form or the `external_id:<value>` form; the external_id form
+   * is scoped within a tenant and requires `tenant_id` to also be set.
+   */
+  subjectId?: string;
+
+  /**
+   * Query param: Filter to objectives associated with a tenant. Accepts the
+   * canonical `tenant_…` form or the `external_id:<value>` form.
+   */
+  tenantId?: string;
+
+  /**
+   * Query param: Filter to objectives whose conversation ran through a widget.
+   * Accepts the canonical `wgt_…` form or the `external_id:<value>` form.
+   */
+  widgetId?: string;
+
+  /**
+   * Query param: Filter to objectives created by a specific widget session.
+   */
+  widgetSessionId?: string;
 }
 
 export interface ObjectiveCancelParams {