@cadenya/cadenya 1.3.1 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cadenya/cadenya",
-  "version": "1.3.1",
+  "version": "1.5.0",
   "description": "The official TypeScript SDK for the Cadenya API",
   "license": "Apache-2.0",
   "type": "module",

package/src/client.ts

@@ -35,7 +35,7 @@ export interface ClientOptions {
    * Defaults to 60000; a non-finite or <= 0 value disables the deadline.
    */
   timeout?: number;
-  /** Headers sent with every request. */
+  /** Additional request headers. Browsers supply their own User-Agent by default. */
   defaultHeaders?: Record<string, string>;
   /** Custom fetch implementation. */
   fetch?: typeof fetch;
@@ -85,7 +85,7 @@ export class Cadenya {
       authHeader: () => ({ Authorization: `Bearer ${apiKey}` }),
       maxRetries: options.maxRetries ?? 0,
       timeout: options.timeout,
-      defaultHeaders: { 'User-Agent': 'cadenya-typescript/1.3.0 (api 1.0)', ...options.defaultHeaders },
+      defaultHeaders: { ...nodeUserAgent('cadenya-typescript/1.5.0 (api 1.0)'), ...options.defaultHeaders },
       fetch: options.fetch,
       logger: options.logger,
       logLevel: options.logLevel,
@@ -112,6 +112,14 @@ export class Cadenya {
   }
 }
 
+// Browser-authored User-Agent headers require CORS permission. Only Node-compatible
+// runtimes receive the SDK default; browsers and workers use their native header.
+function nodeUserAgent(value: string): Record<string, string> {
+  const nodeVersion = (globalThis as { process?: { versions?: { node?: string } } })
+    .process?.versions?.node;
+  return nodeVersion ? { 'User-Agent': value } : {};
+}
+
 function readEnv(name: string): string | undefined {
   const env = (globalThis as { process?: { env?: Record<string, string | undefined> } })
     .process?.env;

package/src/resources/widget-sessions.ts

@@ -141,7 +141,7 @@ export class WidgetSessions {
    * 
    * @example
    * ```ts
-   * const widgetSession = await client.widgetSessions.create({ spec: { widgetId: 'sample' } });
+   * const widgetSession = await client.widgetSessions.create({ spec: { subject: { id: 'sample' }, tenant: { id: 'sample' }, widgetId: 'sample' } });
    * ```
    */
   create(params: WidgetSessionCreateParams, options?: RequestOptions): APIPromise<WidgetSession> {

package/src/types.ts

@@ -2499,6 +2499,10 @@ export interface ObjectiveError {
 }
 
 export interface ObjectiveEvent {
+  /**
+   * Durable events use objevt_ IDs, the only IDs accepted as reconnect
+   *  cursors. Live-only heartbeats use hb_ IDs and have no SSE id: field.
+   */
   metadata: OperationMetadata;
   data: ObjectiveEventData;
   contextWindowId: string;
@@ -2538,7 +2542,8 @@ export type ObjectiveEventData =
   | ObjectiveEventData_Notice
   | ObjectiveEventData_TimedOut
   | ObjectiveEventData_Reasoning
-  | ObjectiveEventData_StateChanged;
+  | ObjectiveEventData_StateChanged
+  | ObjectiveEventData_Heartbeat;
 
 export interface ObjectiveEventInfo {
   objective?: OperationMetadata;
@@ -2596,6 +2601,15 @@ export interface ObjectiveFinalized {
   output?: Record<string, unknown>;
 }
 
+/**
+ * ObjectiveHeartbeat reports recent execution liveness. It is transient:
+ *  delivered only on live streams, never stored in event history or delivered
+ *  to webhooks. Its hb_ event ID is not a reconnect cursor. Heartbeats do not
+ *  change objective state or promise progress from the model.
+ */
+export interface ObjectiveHeartbeat {
+}
+
 /**
  * ObjectiveInfo provides read-only aggregated statistics about an objective's execution
  */
@@ -3502,6 +3516,10 @@ export interface SetToolCallContentRequest_TextBlock {
   text: string;
 }
 
+export type StatusDetails =
+  | WidgetSessionErrorInfo
+  | GoogleProtobufAny;
+
 /**
  * The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).
  */
@@ -3517,7 +3535,7 @@ export interface Status {
   /**
    * A list of messages that carry the error details.  There is a common set of message types for APIs to use.
    */
-  details?: Array<GoogleProtobufAny>;
+  details?: Array<StatusDetails>;
 }
 
 export interface SubAgentSpawned {
@@ -4860,7 +4878,7 @@ export type WebhookDeliveryDataStatus = 'WEBHOOK_DELIVERY_STATUS_UNSPECIFIED' |
 /**
  * The type of objective event that triggered this webhook delivery
  */
-export type WebhookDeliveryDataEventType = 'OBJECTIVE_EVENT_TYPE_UNSPECIFIED' | 'OBJECTIVE_EVENT_TYPE_USER_MESSAGE' | 'OBJECTIVE_EVENT_TYPE_TOOL_APPROVAL_REQUESTED' | 'OBJECTIVE_EVENT_TYPE_TOOL_APPROVED' | 'OBJECTIVE_EVENT_TYPE_TOOL_DENIED' | 'OBJECTIVE_EVENT_TYPE_TOOL_CALLED' | 'OBJECTIVE_EVENT_TYPE_ERROR' | 'OBJECTIVE_EVENT_TYPE_ASSISTANT_MESSAGE' | 'OBJECTIVE_EVENT_TYPE_TOOL_RESULT' | 'OBJECTIVE_EVENT_TYPE_TOOL_ERROR' | 'OBJECTIVE_EVENT_TYPE_CONTEXT_WINDOW_COMPACTED' | 'OBJECTIVE_EVENT_TYPE_MEMORY_READ' | 'OBJECTIVE_EVENT_TYPE_CANCELLED' | 'OBJECTIVE_EVENT_TYPE_SUB_AGENT_SPAWNED' | 'OBJECTIVE_EVENT_TYPE_SUB_AGENT_UPDATED' | 'OBJECTIVE_EVENT_TYPE_FINALIZED' | 'OBJECTIVE_EVENT_TYPE_NOTICE' | 'OBJECTIVE_EVENT_TYPE_TIMED_OUT' | 'OBJECTIVE_EVENT_TYPE_REASONING' | 'OBJECTIVE_EVENT_TYPE_STATE_CHANGED';
+export type WebhookDeliveryDataEventType = 'OBJECTIVE_EVENT_TYPE_UNSPECIFIED' | 'OBJECTIVE_EVENT_TYPE_USER_MESSAGE' | 'OBJECTIVE_EVENT_TYPE_TOOL_APPROVAL_REQUESTED' | 'OBJECTIVE_EVENT_TYPE_TOOL_APPROVED' | 'OBJECTIVE_EVENT_TYPE_TOOL_DENIED' | 'OBJECTIVE_EVENT_TYPE_TOOL_CALLED' | 'OBJECTIVE_EVENT_TYPE_ERROR' | 'OBJECTIVE_EVENT_TYPE_ASSISTANT_MESSAGE' | 'OBJECTIVE_EVENT_TYPE_TOOL_RESULT' | 'OBJECTIVE_EVENT_TYPE_TOOL_ERROR' | 'OBJECTIVE_EVENT_TYPE_CONTEXT_WINDOW_COMPACTED' | 'OBJECTIVE_EVENT_TYPE_MEMORY_READ' | 'OBJECTIVE_EVENT_TYPE_CANCELLED' | 'OBJECTIVE_EVENT_TYPE_SUB_AGENT_SPAWNED' | 'OBJECTIVE_EVENT_TYPE_SUB_AGENT_UPDATED' | 'OBJECTIVE_EVENT_TYPE_FINALIZED' | 'OBJECTIVE_EVENT_TYPE_NOTICE' | 'OBJECTIVE_EVENT_TYPE_TIMED_OUT' | 'OBJECTIVE_EVENT_TYPE_REASONING' | 'OBJECTIVE_EVENT_TYPE_STATE_CHANGED' | 'OBJECTIVE_EVENT_TYPE_HEARTBEAT';
 
 export interface WebhookDeliveryData {
   /**
@@ -4956,8 +4974,9 @@ export type WidgetSessionState = 'STATE_UNSPECIFIED' | 'STATE_ACTIVE' | 'STATE_E
  *  a widget, minted server-to-server by the customer's backend. The session
  *  carries all customer-asserted context — tenant, subject, labels, secrets —
  *  and every conversation (objective) created through the widget inherits it.
- *  The bearer token returned at mint is short-lived and refreshed at the
- *  widget host; the session row is what makes revocation possible.
+ *  The browser renews short-lived bearer tokens at the widget host with
+ *  RenewWidgetSession, authenticated by its existing token. Renewal preserves
+ *  this bounded grant and does not extend its hard expiry.
  */
 export interface WidgetSession {
   metadata: OperationMetadata;
@@ -4974,6 +4993,45 @@ export interface WidgetSession {
    *  headers server-side — never returned by any API.
    */
   secrets: Array<WidgetSession_Secret>;
+  /**
+   * Present only on creation. The same envelope is returned by
+   *  RenewWidgetSession on the widget host. Omitted on reads, lists, and revocation.
+   *  Existing spec.token/spec.token_expires_at and info.host remain populated
+   *  on creation for v1 compatibility and agree with these credentials.
+   */
+  credentials?: WidgetSessionCredentials;
+}
+
+/**
+ * WidgetSessionCredentials is the only credential envelope the customer's
+ *  backend forwards to the browser. Never log or persist its token. Responses
+ *  containing credentials use Cache-Control: no-store. Both initial and later
+ *  issuance use the same schema; no refresh token or management key is included.
+ */
+export interface WidgetSessionCredentials {
+  /**
+   * Canonical wsess_ identifier. Ordinary renewal cannot change the session.
+   */
+  sessionId: string;
+  /**
+   * Authoritative hostname, without a scheme or path. Use HTTPS with this
+   *  host; never construct it or accept a host change during renewal.
+   */
+  host: string;
+  /**
+   * Short-lived bearer credential for the widget host only.
+   */
+  token: string;
+  /**
+   * Exact token expiry, at most 15 minutes after issuance and never later
+   *  than session_expires_at. Equals JWT exp without the 60-second validation
+   *  tolerance added. Renew proactively before this timestamp.
+   */
+  tokenExpiresAt: string;
+  /**
+   * Immutable hard session expiry. Issuance never extends this deadline.
+   */
+  sessionExpiresAt: string;
 }
 
 /**
@@ -5010,7 +5068,7 @@ export interface WidgetSessionInfo {
   messageCount: number;
   /**
    * When the session last created a conversation, sent a message, or
-   *  refreshed a token.
+   *  received a newly issued token.
    */
   lastActiveAt?: string;
 }
@@ -5025,18 +5083,19 @@ export interface WidgetSessionSpec {
    */
   widgetId: string;
   /**
-   * Optional tenant assertion — the customer's org/company identifier for the
-   *  visitor. Upserts the tenant record in the workspace and tags the session
-   *  and every conversation it creates. Conversation listing at the widget
-   *  host is scoped to this tenant.
+   * Required tenant assertion — the customer's organization identifier.
+   *  Upserts the tenant record in the workspace. Every conversation created
+   *  through this session inherits the tenant and subject identity.
    */
-  tenant?: TenantAssertion;
+  tenant: TenantAssertion;
   /**
-   * Optional subject assertion — the visitor within the tenant (e.g. their
-   *  user id in the customer's namespace). Requires `tenant`; a subject
-   *  asserted without a tenant is rejected with InvalidArgument.
+   * Required subject assertion — the visitor's ID within the tenant.
+   *  Sessions with the same tenant and subject share conversation history on
+   *  the same widget and agent, subject to the current session's permissions.
+   *  A static ID deliberately shares that history; use a distinct ID per
+   *  visitor when their conversations should be separate.
    */
-  subject?: SubjectAssertion;
+  subject: SubjectAssertion;
   /**
    * Hard session expiry. Tokens never outlive it; after it passes the session
    *  transitions to STATE_EXPIRED. Defaults to a server-chosen horizon when
@@ -5044,14 +5103,14 @@ export interface WidgetSessionSpec {
    */
   expiresAt?: string;
   /**
-   * The session bearer token. Returned only on creation — subsequent reads
-   *  omit it. The token is short-lived; the widget refreshes it at the widget
-   *  host without involving the customer's backend.
+   * Legacy creation-only alias of credentials.token; omitted on reads.
+   *  Supported throughout v1. New clients should consume credentials.
+   *  The browser obtains replacements with RenewWidgetSession at the widget host.
    */
   token: string;
   /**
-   * Expiry of the token returned in `token`. Distinct from `expires_at`,
-   *  which bounds the session itself.
+   * Legacy creation-only alias of credentials.token_expires_at, supported
+   *  throughout v1. Distinct from expires_at, which bounds the session itself.
    */
   tokenExpiresAt?: string;
   /**
@@ -5559,6 +5618,11 @@ export interface ObjectiveEventData_StateChanged {
   stateChanged: ObjectiveStateChanged;
 }
 
+export interface ObjectiveEventData_Heartbeat {
+  type: 'heartbeat';
+  heartbeat: ObjectiveHeartbeat;
+}
+
 export interface CallableTool_Tool {
   type: 'tool';
   tool: ResourceMetadata;
@@ -5816,13 +5880,31 @@ export interface ModelSpec_Capability_Caching {
   caching: Capability_Caching;
 }
 
+/**
+ * TOKEN_EXPIRED identifies access-token expiry beyond the 60-second clock-skew tolerance. That token cannot renew; use already-installed newer credentials or require explicit app reauthentication. SESSION_* reasons are terminal. Never infer renewability from HTTP status alone.
+ */
+export type WidgetSessionErrorReason = 'TOKEN_EXPIRED' | 'SESSION_REVOKED' | 'SESSION_EXPIRED' | 'SESSION_EXHAUSTED';
+
+/**
+ * google.rpc.ErrorInfo detail for widget lifecycle failures. Match both domain and reason; ignore unknown reasons rather than renewing automatically.
+ */
+export interface WidgetSessionErrorInfo {
+  '@type': 'type.googleapis.com/google.rpc.ErrorInfo';
+  domain: 'api.cadenya.com';
+  reason: WidgetSessionErrorReason;
+  /**
+   * Optional non-sensitive context. Never contains tokens or secrets.
+   */
+  metadata?: Record<string, string>;
+}
+
 export type AgentServiceListAgentsState = 'STATE_UNSPECIFIED' | 'STATE_DRAFT' | 'STATE_PUBLISHED' | 'STATE_ARCHIVED';
 
 export type AgentServiceListAgentsVariationSelectionMode = 'VARIATION_SELECTION_MODE_UNSPECIFIED' | 'VARIATION_SELECTION_MODE_RANDOM' | 'VARIATION_SELECTION_MODE_WEIGHTED';
 
 export type AgentServiceListAgentFeedbackSentiment = 'FEEDBACK_SENTIMENT_UNSPECIFIED' | 'FEEDBACK_SENTIMENT_POSITIVE' | 'FEEDBACK_SENTIMENT_NEGATIVE';
 
-export type AgentServiceListAgentWebhookDeliveriesEventType = 'OBJECTIVE_EVENT_TYPE_UNSPECIFIED' | 'OBJECTIVE_EVENT_TYPE_USER_MESSAGE' | 'OBJECTIVE_EVENT_TYPE_TOOL_APPROVAL_REQUESTED' | 'OBJECTIVE_EVENT_TYPE_TOOL_APPROVED' | 'OBJECTIVE_EVENT_TYPE_TOOL_DENIED' | 'OBJECTIVE_EVENT_TYPE_TOOL_CALLED' | 'OBJECTIVE_EVENT_TYPE_ERROR' | 'OBJECTIVE_EVENT_TYPE_ASSISTANT_MESSAGE' | 'OBJECTIVE_EVENT_TYPE_TOOL_RESULT' | 'OBJECTIVE_EVENT_TYPE_TOOL_ERROR' | 'OBJECTIVE_EVENT_TYPE_CONTEXT_WINDOW_COMPACTED' | 'OBJECTIVE_EVENT_TYPE_MEMORY_READ' | 'OBJECTIVE_EVENT_TYPE_CANCELLED' | 'OBJECTIVE_EVENT_TYPE_SUB_AGENT_SPAWNED' | 'OBJECTIVE_EVENT_TYPE_SUB_AGENT_UPDATED' | 'OBJECTIVE_EVENT_TYPE_FINALIZED' | 'OBJECTIVE_EVENT_TYPE_NOTICE' | 'OBJECTIVE_EVENT_TYPE_TIMED_OUT' | 'OBJECTIVE_EVENT_TYPE_REASONING' | 'OBJECTIVE_EVENT_TYPE_STATE_CHANGED';
+export type AgentServiceListAgentWebhookDeliveriesEventType = 'OBJECTIVE_EVENT_TYPE_UNSPECIFIED' | 'OBJECTIVE_EVENT_TYPE_USER_MESSAGE' | 'OBJECTIVE_EVENT_TYPE_TOOL_APPROVAL_REQUESTED' | 'OBJECTIVE_EVENT_TYPE_TOOL_APPROVED' | 'OBJECTIVE_EVENT_TYPE_TOOL_DENIED' | 'OBJECTIVE_EVENT_TYPE_TOOL_CALLED' | 'OBJECTIVE_EVENT_TYPE_ERROR' | 'OBJECTIVE_EVENT_TYPE_ASSISTANT_MESSAGE' | 'OBJECTIVE_EVENT_TYPE_TOOL_RESULT' | 'OBJECTIVE_EVENT_TYPE_TOOL_ERROR' | 'OBJECTIVE_EVENT_TYPE_CONTEXT_WINDOW_COMPACTED' | 'OBJECTIVE_EVENT_TYPE_MEMORY_READ' | 'OBJECTIVE_EVENT_TYPE_CANCELLED' | 'OBJECTIVE_EVENT_TYPE_SUB_AGENT_SPAWNED' | 'OBJECTIVE_EVENT_TYPE_SUB_AGENT_UPDATED' | 'OBJECTIVE_EVENT_TYPE_FINALIZED' | 'OBJECTIVE_EVENT_TYPE_NOTICE' | 'OBJECTIVE_EVENT_TYPE_TIMED_OUT' | 'OBJECTIVE_EVENT_TYPE_REASONING' | 'OBJECTIVE_EVENT_TYPE_STATE_CHANGED' | 'OBJECTIVE_EVENT_TYPE_HEARTBEAT';
 
 export type MemoryServiceListMemoryLayersType = 'MEMORY_LAYER_TYPE_UNSPECIFIED' | 'MEMORY_LAYER_TYPE_EPISODIC' | 'MEMORY_LAYER_TYPE_SKILLS';
 
@@ -5898,18 +5980,19 @@ export interface WidgetSessionSpecParam {
    */
   widgetId: string;
   /**
-   * Optional tenant assertion — the customer's org/company identifier for the
-   *  visitor. Upserts the tenant record in the workspace and tags the session
-   *  and every conversation it creates. Conversation listing at the widget
-   *  host is scoped to this tenant.
+   * Required tenant assertion — the customer's organization identifier.
+   *  Upserts the tenant record in the workspace. Every conversation created
+   *  through this session inherits the tenant and subject identity.
    */
-  tenant?: TenantAssertion;
+  tenant: TenantAssertion;
   /**
-   * Optional subject assertion — the visitor within the tenant (e.g. their
-   *  user id in the customer's namespace). Requires `tenant`; a subject
-   *  asserted without a tenant is rejected with InvalidArgument.
+   * Required subject assertion — the visitor's ID within the tenant.
+   *  Sessions with the same tenant and subject share conversation history on
+   *  the same widget and agent, subject to the current session's permissions.
+   *  A static ID deliberately shares that history; use a distinct ID per
+   *  visitor when their conversations should be separate.
    */
-  subject?: SubjectAssertion;
+  subject: SubjectAssertion;
   /**
    * Hard session expiry. Tokens never outlive it; after it passes the session
    *  transitions to STATE_EXPIRED. Defaults to a server-chosen horizon when