@cadenya/cadenya 0.67.0 → 0.69.0

package/src/resources/agents/variations.ts

@@ -9,6 +9,9 @@ import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
+/**
+ * Manage variations of an agent and their tool, sub-agent, and memory layer assignments.
+ */
 export class Variations extends APIResource {
   /**
    * Creates a new variation for an agent
@@ -189,9 +192,9 @@ export interface AgentVariationInfo {
   assignments?: Array<VariationAssignment>;
 
   /**
-   * Profile represents a human user at the account level. Profiles are
-   * account-scoped resources that can be associated with multiple workspaces through
-   * the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS).
+   * 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;
 
@@ -402,15 +405,14 @@ export interface CompactionConfigToolResultClearingStrategy {
 }
 
 /**
- * VariationAssignment is a read-only reference to a single tool, tool set, or
- * sub-agent attached to a variation. Clients read the full set of assignments via
+ * A read-only reference to a single tool, tool set, or sub-agent attached to a
+ * variation. Read the full set of assignments via
  * `AgentVariationInfo.assignments`; mutations go through the dedicated add/remove
- * assignment endpoints under
- * /v1/agents/{agent_id}/variations/{variation_id}/assignments.
+ * assignment endpoints.
  *
- * The `id` identifies the assignment row itself (not the referenced resource) and
- * is the handle used to remove the assignment. It is returned by the add endpoint
- * and present on every entry in AgentVariationInfo.assignments.
+ * The `id` identifies the assignment itself (not the referenced resource) and is
+ * the handle used to remove the assignment. It is returned by the add endpoint and
+ * present on every entry in `AgentVariationInfo.assignments`.
  */
 export interface VariationAssignment {
   id?: string;
@@ -483,7 +485,7 @@ export interface VariationMemoryLayerAssignment {
 
 export interface VariationCreateParams {
   /**
-   * Path param: Workspace ID (from path).
+   * Path param: Workspace ID.
    */
   workspaceId: string;
 
@@ -504,26 +506,26 @@ export interface VariationCreateParams {
 
 export interface VariationRetrieveParams {
   /**
-   * Workspace ID (from path).
+   * Workspace ID.
    */
   workspaceId: string;
 
   /**
-   * Agent ID (from path). Accepts canonical agent\_… form or external_id:<value>
-   * form (see common.proto "Path-parameter ID resolution").
+   * Agent ID. Accepts the canonical `agent_…` form or the `external_id:<value>`
+   * form.
    */
   agentId: string;
 }
 
 export interface VariationUpdateParams {
   /**
-   * Path param: Workspace ID (from path).
+   * Path param: Workspace ID.
    */
   workspaceId: string;
 
   /**
-   * Path param: Agent ID (from path). Accepts canonical agent\_… form or
-   * external_id:<value> form (see common.proto "Path-parameter ID resolution").
+   * Path param: Agent ID. Accepts the canonical `agent_…` form or the
+   * `external_id:<value>` form.
    */
   agentId: string;
 
@@ -549,7 +551,7 @@ export interface VariationUpdateParams {
 
 export interface VariationListParams extends CursorPaginationParams {
   /**
-   * Path param: Workspace ID (from path).
+   * Path param: Workspace ID.
    */
   workspaceId: string;
 
@@ -559,7 +561,8 @@ export interface VariationListParams extends CursorPaginationParams {
   bundleKey?: string;
 
   /**
-   * Query param: When set to true you may use more of your alloted API rate-limit
+   * Query param: When true, the `info` field on each returned variation is
+   * populated. Requests with this flag count more against your rate limit.
    */
   includeInfo?: boolean;
 
@@ -571,26 +574,26 @@ export interface VariationListParams extends CursorPaginationParams {
 
 export interface VariationDeleteParams {
   /**
-   * Workspace ID (from path).
+   * Workspace ID.
    */
   workspaceId: string;
 
   /**
-   * Agent ID (from path). Accepts canonical agent\_… form or external_id:<value>
-   * form (see common.proto "Path-parameter ID resolution").
+   * Agent ID. Accepts the canonical `agent_…` form or the `external_id:<value>`
+   * form.
    */
   agentId: string;
 }
 
 export interface VariationAddAssignmentParams {
   /**
-   * Path param: Workspace ID (from path).
+   * Path param: Workspace ID.
    */
   workspaceId: string;
 
   /**
-   * Path param: Agent ID (from path). Accepts canonical agent\_… form or
-   * external_id:<value> form (see common.proto "Path-parameter ID resolution").
+   * Path param: Agent ID. Accepts the canonical `agent_…` form or the
+   * `external_id:<value>` form.
    */
   agentId: string;
 
@@ -612,19 +615,19 @@ export interface VariationAddAssignmentParams {
 
 export interface VariationAddMemoryLayerParams {
   /**
-   * Path param: Workspace ID (from path).
+   * Path param: Workspace ID.
    */
   workspaceId: string;
 
   /**
-   * Path param: Agent ID (from path). Accepts canonical agent\_… form or
-   * external_id:<value> form (see common.proto "Path-parameter ID resolution").
+   * Path param: Agent ID. Accepts the canonical `agent_…` form or the
+   * `external_id:<value>` form.
    */
   agentId: string;
 
   /**
-   * Body param: Layer to attach. Accepts canonical memlyr\_… form or
-   * external_id:<value> form (see common.proto "Path-parameter ID resolution").
+   * Body param: Layer to attach. Accepts the canonical `memlyr_…` form or the
+   * `external_id:<value>` form.
    */
   memoryLayerId?: string;
 
@@ -637,57 +640,57 @@ export interface VariationAddMemoryLayerParams {
 
 export interface VariationRemoveAssignmentParams {
   /**
-   * Workspace ID (from path).
+   * Workspace ID.
    */
   workspaceId: string;
 
   /**
-   * Agent ID (from path). Accepts canonical agent\_… form or external_id:<value>
-   * form (see common.proto "Path-parameter ID resolution").
+   * Agent ID. Accepts the canonical `agent_…` form or the `external_id:<value>`
+   * form.
    */
   agentId: string;
 
   /**
-   * Variation ID (from path). Accepts canonical av\_… form or external_id:<value>
-   * form (see common.proto "Path-parameter ID resolution").
+   * Variation ID. Accepts the canonical `av_…` form or the `external_id:<value>`
+   * form.
    */
   variationId: string;
 }
 
 export interface VariationRemoveMemoryLayerParams {
   /**
-   * Workspace ID (from path).
+   * Workspace ID.
    */
   workspaceId: string;
 
   /**
-   * Agent ID (from path). Accepts canonical agent\_… form or external_id:<value>
-   * form (see common.proto "Path-parameter ID resolution").
+   * Agent ID. Accepts the canonical `agent_…` form or the `external_id:<value>`
+   * form.
    */
   agentId: string;
 
   /**
-   * Variation ID (from path). Accepts canonical av\_… form or external_id:<value>
-   * form (see common.proto "Path-parameter ID resolution").
+   * Variation ID. Accepts the canonical `av_…` form or the `external_id:<value>`
+   * form.
    */
   variationId: string;
 }
 
 export interface VariationUpdateMemoryLayerParams {
   /**
-   * Path param: Workspace ID (from path).
+   * Path param: Workspace ID.
    */
   workspaceId: string;
 
   /**
-   * Path param: Agent ID (from path). Accepts canonical agent\_… form or
-   * external_id:<value> form (see common.proto "Path-parameter ID resolution").
+   * Path param: Agent ID. Accepts the canonical `agent_…` form or the
+   * `external_id:<value>` form.
    */
   agentId: string;
 
   /**
-   * Path param: Variation ID (from path). Accepts canonical av\_… form or
-   * external_id:<value> form (see common.proto "Path-parameter ID resolution").
+   * Path param: Variation ID. Accepts the canonical `av_…` form or the
+   * `external_id:<value>` form.
    */
   variationId: string;
 

package/src/resources/agents/webhook-deliveries.ts

@@ -7,12 +7,7 @@ import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
 /**
- * AgentService manages AI agents at the WORKSPACE level.
- *  Agents are workspace-scoped resources that define AI behavior and tool access.
- *  All operations are implicitly scoped to the workspace determined by the JWT token.
- *
- *  Authentication: Bearer token (JWT)
- *  Scope: Workspace-level operations
+ * Manage AI agents within a workspace. Agents define AI behavior and tool access.
  */
 export class WebhookDeliveries extends APIResource {
   /**
@@ -36,7 +31,7 @@ export type WebhookDeliveriesCursorPagination = CursorPagination<WebhookDelivery
 
 export interface WebhookDelivery {
   /**
-   * Webhook delivery data
+   * Webhook delivery details.
    */
   data: WebhookDeliveryData;
 
@@ -75,7 +70,7 @@ export interface WebhookDeliveryData {
     | 'OBJECTIVE_EVENT_TYPE_CANCELLED';
 
   /**
-   * Response details (no response_body to avoid storing large payloads)
+   * Response details. The response body is not retained.
    */
   httpStatusCode: number;
 
@@ -116,7 +111,7 @@ export interface WebhookDeliveryData {
 
 export interface WebhookDeliveryListParams extends CursorPaginationParams {
   /**
-   * Path param: Workspace ID (from path).
+   * Path param: Workspace ID.
    */
   workspaceId: string;
 

package/src/resources/api-keys/access.ts

@@ -0,0 +1,79 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as WorkspacesAPI from '../workspaces';
+import { WorkspacesCursorPagination } from '../workspaces';
+import * as APIKeysAPI from './api-keys';
+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';
+
+/**
+ * Issue, rotate, and revoke API keys for the account, and grant or revoke
+ *  each key's access to individual workspaces.
+ */
+export class Access extends APIResource {
+  /**
+   * Lists the workspaces this API key has access to. Cursor-paginated.
+   */
+  list(
+    id: string,
+    query: AccessListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<WorkspacesCursorPagination, WorkspacesAPI.Workspace> {
+    return this._client.getAPIList(
+      path`/v1/account/api_keys/${id}/workspaces`,
+      CursorPagination<WorkspacesAPI.Workspace>,
+      { query, ...options },
+    );
+  }
+
+  /**
+   * Grants this API key access to the specified workspace. Idempotent — adding an
+   * already-associated workspace is a no-op. Returns the updated API key with
+   * refreshed workspace preview and total.
+   */
+  add(id: string, body: AccessAddParams, options?: RequestOptions): APIPromise<APIKeysAPI.APIKey> {
+    return this._client.post(path`/v1/account/api_keys/${id}/workspaces`, { body, ...options });
+  }
+
+  /**
+   * Revokes this API key's access to the specified workspace. Idempotent. A key may
+   * have zero workspaces and remains valid.
+   */
+  remove(workspaceID: string, params: AccessRemoveParams, options?: RequestOptions): APIPromise<void> {
+    const { id } = params;
+    return this._client.delete(path`/v1/account/api_keys/${id}/workspaces/${workspaceID}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+export interface AccessListParams extends CursorPaginationParams {}
+
+export interface AccessAddParams {
+  /**
+   * The workspace to grant access to.
+   */
+  workspaceId?: string;
+}
+
+export interface AccessRemoveParams {
+  /**
+   * The API key losing workspace access (path).
+   */
+  id: string;
+}
+
+export declare namespace Access {
+  export {
+    type AccessListParams as AccessListParams,
+    type AccessAddParams as AccessAddParams,
+    type AccessRemoveParams as AccessRemoveParams,
+  };
+}
+
+export { type WorkspacesCursorPagination };

package/src/resources/api-keys/api-keys.ts

@@ -0,0 +1,282 @@
+// 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 * as AccessAPI from './access';
+import { Access, AccessAddParams, AccessListParams, AccessRemoveParams } from './access';
+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';
+
+/**
+ * Issue, rotate, and revoke API keys for the account, and grant or revoke
+ *  each key's access to individual workspaces.
+ */
+export class APIKeys extends APIResource {
+  access: AccessAPI.Access = new AccessAPI.Access(this._client);
+
+  /**
+   * Creates a new API key on the account. Optionally grants the key access to one or
+   * more workspaces via initial_workspace_ids.
+   */
+  create(body: APIKeyCreateParams, options?: RequestOptions): APIPromise<APIKey> {
+    return this._client.post('/v1/account/api_keys', { body, ...options });
+  }
+
+  /**
+   * Retrieves an API key by ID.
+   */
+  retrieve(id: string, options?: RequestOptions): APIPromise<APIKey> {
+    return this._client.get(path`/v1/account/api_keys/${id}`, options);
+  }
+
+  /**
+   * Updates an API key.
+   */
+  update(id: string, body: APIKeyUpdateParams, options?: RequestOptions): APIPromise<APIKey> {
+    return this._client.patch(path`/v1/account/api_keys/${id}`, { body, ...options });
+  }
+
+  /**
+   * Lists all API keys on the account.
+   */
+  list(
+    query: APIKeyListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<APIKeysCursorPagination, APIKey> {
+    return this._client.getAPIList('/v1/account/api_keys', CursorPagination<APIKey>, { query, ...options });
+  }
+
+  /**
+   * Deletes an API key.
+   */
+  delete(id: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/v1/account/api_keys/${id}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
+  /**
+   * Rotates an API key and returns a new token. All previous tokens for this key are
+   * invalidated.
+   */
+  rotate(id: string, options?: RequestOptions): APIPromise<APIKey> {
+    return this._client.put(path`/v1/account/api_keys/${id}/rotate`, options);
+  }
+}
+
+export type APIKeysCursorPagination = CursorPagination<APIKey>;
+
+/**
+ * An API key for the account. Use workspace-association RPCs to grant the key
+ * access to specific workspaces; a key with zero workspaces is valid but cannot
+ * access workspace-scoped resources.
+ */
+export interface APIKey {
+  /**
+   * AccountResourceMetadata is used to represent a resource that is associated to an
+   * account but not to a workspace.
+   */
+  metadata: Shared.AccountResourceMetadata;
+
+  /**
+   * Configuration for an API key.
+   */
+  spec: APIKeySpec;
+
+  info?: APIKeyInfo;
+}
+
+export interface APIKeyInfo {
+  /**
+   * 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;
+
+  /**
+   * Up to a small number of workspaces this key has access to, intended for display
+   * ("Workspace 1, Workspace 2, and 4 more"). Use ListAPIKeyWorkspaces for the full
+   * paginated list.
+   */
+  workspacesPreview?: Array<Shared.BareMetadata>;
+
+  /**
+   * Total number of workspaces this key has access to.
+   */
+  workspacesTotal?: number;
+}
+
+/**
+ * Configuration for an API key.
+ */
+export interface APIKeySpec {
+  /**
+   * The bearer token used to authenticate as this API key. Returned only on creation
+   * and rotation; subsequent reads omit this field.
+   */
+  token?: string;
+
+  /**
+   * Free-form description of what this API key is used for.
+   */
+  description?: string;
+
+  /**
+   * Permissions granted to this key. Each entry is a colon-separated verb:resource
+   * string (e.g. "manage:agents"). Currently has no enforced effect; reserved for
+   * future fine-grained authorization.
+   */
+  permissions?: Array<string>;
+
+  /**
+   * True when this key is managed by the system (e.g. the auto-provisioned global
+   * account key). System keys cannot be deleted but can be rotated.
+   */
+  system?: boolean;
+}
+
+export interface APIKeyCreateParams {
+  /**
+   * CreateAccountResourceMetadata contains the user-provided fields for creating an
+   * account-scoped resource. Read-only fields (id, account_id, profile_id) are
+   * excluded since they are set by the server.
+   */
+  metadata: APIKeyCreateParams.Metadata;
+
+  /**
+   * Configuration for an API key.
+   */
+  spec: APIKeySpec;
+
+  /**
+   * Workspaces this API key will have access to on creation. Optional — a key can be
+   * created with no workspace access and granted later via AddAPIKeyWorkspace.
+   */
+  initialWorkspaceIds?: Array<string>;
+}
+
+export namespace APIKeyCreateParams {
+  /**
+   * CreateAccountResourceMetadata contains the user-provided fields for creating an
+   * account-scoped resource. Read-only fields (id, account_id, profile_id) are
+   * excluded since they are set by the server.
+   */
+  export interface Metadata {
+    /**
+     * Human-readable name for the resource (e.g., "Production API Key", "Staging
+     * Workspace")
+     */
+    name: string;
+
+    /**
+     * External ID for the resource (e.g., a workflow ID from an external system)
+     */
+    externalId?: string;
+
+    /**
+     * Arbitrary key-value pairs for categorization and filtering Examples:
+     * {"environment": "production", "team": "platform", "version": "v2"}
+     */
+    labels?: { [key: string]: string };
+  }
+}
+
+export interface APIKeyUpdateParams {
+  /**
+   * UpdateAccountResourceMetadata contains the user-provided fields for updating an
+   * account-scoped resource. Read-only fields (id, account_id, profile_id) are
+   * excluded since they are set by the server.
+   */
+  metadata?: APIKeyUpdateParams.Metadata;
+
+  /**
+   * Configuration for an API key.
+   */
+  spec?: APIKeySpec;
+
+  /**
+   * Fields to update.
+   */
+  updateMask?: string;
+}
+
+export namespace APIKeyUpdateParams {
+  /**
+   * UpdateAccountResourceMetadata contains the user-provided fields for updating an
+   * account-scoped resource. Read-only fields (id, account_id, profile_id) are
+   * excluded since they are set by the server.
+   */
+  export interface Metadata {
+    /**
+     * Human-readable name for the resource (e.g., "Production API Key", "Staging
+     * Workspace")
+     */
+    name: string;
+
+    /**
+     * External ID for the resource (e.g., a workflow ID from an external system)
+     */
+    externalId?: string;
+
+    /**
+     * Arbitrary key-value pairs for categorization and filtering Examples:
+     * {"environment": "production", "team": "platform", "version": "v2"}
+     */
+    labels?: { [key: string]: string };
+  }
+}
+
+export interface APIKeyListParams extends CursorPaginationParams {
+  /**
+   * Filter by bundle_key — return only resources owned by this bundle.
+   */
+  bundleKey?: string;
+
+  /**
+   * When true, included info fields are populated. Requests with this flag count
+   * more against your rate limit.
+   */
+  includeInfo?: boolean;
+
+  /**
+   * Filter by ID prefix.
+   */
+  prefix?: string;
+
+  /**
+   * Free-form search query.
+   */
+  query?: string;
+
+  /**
+   * Sort order for results (asc or desc by creation time).
+   */
+  sortOrder?: string;
+}
+
+APIKeys.Access = Access;
+
+export declare namespace APIKeys {
+  export {
+    type APIKey as APIKey,
+    type APIKeyInfo as APIKeyInfo,
+    type APIKeySpec as APIKeySpec,
+    type APIKeysCursorPagination as APIKeysCursorPagination,
+    type APIKeyCreateParams as APIKeyCreateParams,
+    type APIKeyUpdateParams as APIKeyUpdateParams,
+    type APIKeyListParams as APIKeyListParams,
+  };
+
+  export {
+    Access as Access,
+    type AccessListParams as AccessListParams,
+    type AccessAddParams as AccessAddParams,
+    type AccessRemoveParams as AccessRemoveParams,
+  };
+}

package/src/resources/api-keys/index.ts

@@ -0,0 +1,13 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  APIKeys,
+  type APIKey,
+  type APIKeyInfo,
+  type APIKeySpec,
+  type APIKeyCreateParams,
+  type APIKeyUpdateParams,
+  type APIKeyListParams,
+  type APIKeysCursorPagination,
+} from './api-keys';
+export { Access, type AccessListParams, type AccessAddParams, type AccessRemoveParams } from './access';