@composio/client 0.1.0-alpha.10 → 0.1.0-alpha.12

package/src/resources/migration.ts

@@ -6,7 +6,9 @@ import { RequestOptions } from '../internal/request-options';
 
 export class Migration extends APIResource {
   /**
-   * Convert a legacy UUID to its corresponding NanoId for migration purposes
+   * Convert a legacy UUID to its corresponding NanoId for migration purposes. This
+   * endpoint facilitates the transition from UUID-based identifiers to the more
+   * compact NanoId format used in the v3 API.
    */
   retrieveNanoid(
     query: MigrationRetrieveNanoidParams,
@@ -18,14 +20,21 @@ export class Migration extends APIResource {
 
 export interface MigrationRetrieveNanoidResponse {
   /**
-   * The NanoId corresponding to the provided UUID.
+   * The NanoId corresponding to the provided UUID. This is the new identifier that
+   * should be used in place of the legacy UUID.
    */
   nanoid: string;
 }
 
 export interface MigrationRetrieveNanoidParams {
+  /**
+   * The type of resource that the UUID belongs to
+   */
   type: 'CONNECTED_ACCOUNT' | 'AUTH_CONFIG' | 'TRIGGER_INSTANCE';
 
+  /**
+   * The legacy UUID that needs to be converted to a NanoId
+   */
   uuid: string;
 }
 

package/src/resources/org/api-key.ts

@@ -6,7 +6,14 @@ import { RequestOptions } from '../../internal/request-options';
 
 export class APIKey extends APIResource {
   /**
-   * Retrieve the API key for the current organization (admin only)
+   * Retrieve the API key for the current organization. This endpoint is restricted
+   * to organization administrators only. The returned API key can be used for
+   * authenticating organization-level API requests.
+   *
+   * @example
+   * ```ts
+   * const apiKey = await client.org.apiKey.retrieve();
+   * ```
    */
   retrieve(options?: RequestOptions): APIPromise<APIKeyRetrieveResponse> {
     return this._client.get('/api/v3/org/api_key', options);
@@ -14,7 +21,13 @@ export class APIKey extends APIResource {
 
   /**
    * Generate a new API key for the organization, invalidating the previous one
-   * (admin only)
+   * (admin only). This operation cannot be undone and will immediately invalidate
+   * the previous API key.
+   *
+   * @example
+   * ```ts
+   * const response = await client.org.apiKey.regenerate();
+   * ```
    */
   regenerate(options?: RequestOptions): APIPromise<APIKeyRegenerateResponse> {
     return this._client.post('/api/v3/org/api_key/regenerate', options);
@@ -22,10 +35,18 @@ export class APIKey extends APIResource {
 }
 
 export interface APIKeyRetrieveResponse {
+  /**
+   * The API key for the organization that can be used for authentication. Format:
+   * org_xxx
+   */
   org_api_key: string;
 }
 
 export interface APIKeyRegenerateResponse {
+  /**
+   * The newly generated API key for the organization that can be used for
+   * authentication. Format: org_xxx
+   */
   org_api_key: string;
 }
 

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

@@ -6,6 +6,21 @@ import { RequestOptions } from '../../../internal/request-options';
 import { path } from '../../../internal/utils/path';
 
 export class APIKeys extends APIResource {
+  /**
+   * Creates a new API key for the specified project. API keys are used for
+   * authenticating requests to the API. This endpoint generates a new key with the
+   * provided name and returns the complete key details including the actual key
+   * value. Note that the full API key value is only returned once at creation time
+   * and cannot be retrieved later, so it should be securely stored immediately.
+   *
+   * @example
+   * ```ts
+   * const apiKey = await client.org.project.apiKeys.create(
+   *   'proj_abc123xyz456',
+   *   { name: 'Production API Key' },
+   * );
+   * ```
+   */
   create(
     projectID: string,
     body: APIKeyCreateParams,
@@ -14,50 +29,107 @@ export class APIKeys extends APIResource {
     return this._client.post(path`/api/v3/org/project/${projectID}/api_keys/create`, { body, ...options });
   }
 
+  /**
+   * Retrieves all API keys associated with the specified project. This endpoint
+   * returns details about each API key including its name, creation date, and last
+   * used information. Use this endpoint to audit which keys exist for a project or
+   * to manage key rotation policies.
+   *
+   * @example
+   * ```ts
+   * const apiKeys = await client.org.project.apiKeys.list(
+   *   'proj_abc123xyz456',
+   * );
+   * ```
+   */
   list(projectID: string, options?: RequestOptions): APIPromise<APIKeyListResponse> {
     return this._client.get(path`/api/v3/org/project/${projectID}/api_keys/list`, options);
   }
 
+  /**
+   * Permanently deletes an API key from the specified project. Once deleted, the API
+   * key can no longer be used for authentication and any services using it will need
+   * to be updated with a new key. This operation cannot be undone, so it should be
+   * used with caution.
+   *
+   * @example
+   * ```ts
+   * const apiKey = await client.org.project.apiKeys.delete(
+   *   '01H4DKRF5SMP7NQCA3BWT0JYB6',
+   *   { projectId: 'proj_abc123xyz456' },
+   * );
+   * ```
+   */
   delete(id: string, params: APIKeyDeleteParams, options?: RequestOptions): APIPromise<APIKeyDeleteResponse> {
     const { projectId } = params;
     return this._client.delete(path`/api/v3/org/project/${projectId}/api_keys/remove/${id}`, options);
   }
 
+  /**
+   * Retrieves an existing API key for the project or creates a new one if none
+   * exists. This endpoint is useful for ensuring a project always has at least one
+   * API key without the risk of creating duplicates. If an API key already exists,
+   * it returns the existing key. If no API keys exist for the project, it creates a
+   * new one with an automatically generated name.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.org.project.apiKeys.createAPIKey(
+   *     'proj_abc123xyz456',
+   *   );
+   * ```
+   */
   createAPIKey(projectID: string, options?: RequestOptions): APIPromise<APIKeyCreateAPIKeyResponse> {
     return this._client.post(path`/api/v3/org/project/${projectID}/api_keys/create-api-key`, options);
   }
 }
 
+/**
+ * API key object containing the key details
+ */
 export interface APIKeyCreateResponse {
   /**
-   * API key ID
+   * Database record identifier for the API key
    */
   id: string;
 
   /**
-   * Creation timestamp
+   * UTC timestamp indicating when the API key was created
+   */
+  created_at: string;
+
+  /**
+   * @deprecated UTC timestamp indicating when the API key was created. DEPRECATED:
+   * Use created_at instead.
    */
   createdAt: string;
 
   /**
-   * API key value
+   * The API key string value that should be included in API requests. This value is
+   * only shown once at creation time.
    */
   key: string;
 
   /**
-   * API key name
+   * Descriptive name assigned to help identify the key's purpose
    */
   name: string;
 
   /**
-   * Last used timestamp
+   * UTC timestamp indicating when the API key was last used for authentication. Will
+   * be null for newly created keys.
    */
-  lastUsed?: string;
+  last_used_at?: string;
 }
 
+/**
+ * Response containing the list of API keys for a project
+ */
 export interface APIKeyListResponse {
   /**
-   * List of API keys
+   * List of all API keys for the specified project, including their properties and
+   * usage information
    */
   items: Array<APIKeyListResponse.Item>;
 }
@@ -65,81 +137,104 @@ export interface APIKeyListResponse {
 export namespace APIKeyListResponse {
   export interface Item {
     /**
-     * API key ID
+     * Unique identifier for the API key record
      */
     id: string;
 
     /**
-     * Creation timestamp
+     * UTC timestamp indicating when the API key was created
      */
     created_at: string;
 
     /**
-     * API key value
+     * The API key string that should be included in API requests for authentication
      */
     key: string;
 
     /**
-     * API key name
+     * Descriptive name assigned to the API key for identification purposes
      */
     name: string;
 
     /**
-     * Last used timestamp
+     * UTC timestamp indicating when the API key was last used for authentication. Will
+     * be null if the key has never been used.
      */
     last_used?: string;
   }
 }
 
+/**
+ * Response indicating the status of the API key deletion operation
+ */
 export interface APIKeyDeleteResponse {
   /**
-   * Status message
+   * Status message providing details about the deletion operation
    */
   message: string;
 
   /**
-   * Whether the operation was successful
+   * Boolean flag indicating if the deletion operation was successful
    */
   success: boolean;
 }
 
+/**
+ * API key object containing the key details
+ */
 export interface APIKeyCreateAPIKeyResponse {
   /**
-   * API key ID
+   * Database record identifier for the API key
    */
   id: string;
 
   /**
-   * Creation timestamp
+   * UTC timestamp indicating when the API key was created
+   */
+  created_at: string;
+
+  /**
+   * @deprecated UTC timestamp indicating when the API key was created. Use
+   * created_at instead.
    */
   createdAt: string;
 
   /**
-   * API key value
+   * The API key string value that should be included in API requests. This value is
+   * only shown once.
    */
   key: string;
 
   /**
-   * API key name
+   * @deprecated UTC timestamp indicating when the API key was created. Use
+   * last_used_at instead.
+   */
+  lastUsedAt: string;
+
+  /**
+   * Name assigned to help identify the key's purpose. For auto-generated keys, this
+   * will be a random name.
    */
   name: string;
 
   /**
-   * Last used timestamp
+   * UTC timestamp indicating when the API key was last used for authentication. Will
+   * be null for newly created keys.
    */
-  lastUsed?: string;
+  last_used_at?: string;
 }
 
 export interface APIKeyCreateParams {
   /**
-   * API key name
+   * A user-friendly name to identify the API key's purpose (e.g., "Production
+   * Server", "Test Environment")
    */
   name: string;
 }
 
 export interface APIKeyDeleteParams {
   /**
-   * Project ID
+   * The project Nano ID that owns the API key to be deleted
    */
   projectId: string;
 }

package/src/resources/org/project/project.ts

@@ -34,128 +34,300 @@ export class Project extends APIResource {
   trigger: TriggerAPI.Trigger = new TriggerAPI.Trigger(this._client);
 
   /**
-   * Create a new project within the organization with the specified name
+   * Creates a new project within the authenticated user's organization using the
+   * specified name. Projects are isolated environments within your organization,
+   * each with their own API keys, webhook configurations, and resources. Use this
+   * endpoint to create additional projects for different environments (e.g.,
+   * development, staging, production) or for separate applications.
+   *
+   * @example
+   * ```ts
+   * const project = await client.org.project.create({
+   *   name: 'my-production-api',
+   * });
+   * ```
    */
   create(body: ProjectCreateParams, options?: RequestOptions): APIPromise<ProjectCreateResponse> {
     return this._client.post('/api/v3/org/project/new', { body, ...options });
   }
 
   /**
-   * Retrieve detailed information about a specific project using its ID
+   * Retrieves detailed information about a specific project using its unique
+   * identifier. This endpoint provides complete project configuration including
+   * webhook URLs, creation and update timestamps, and webhook secrets. Use this
+   * endpoint to inspect project settings or verify project configuration.
+   *
+   * @example
+   * ```ts
+   * const project = await client.org.project.retrieve(
+   *   'proj_abc123xyz456',
+   * );
+   * ```
    */
   retrieve(projectID: string, options?: RequestOptions): APIPromise<ProjectRetrieveResponse> {
     return this._client.get(path`/api/v3/org/project/${projectID}`, options);
   }
 
   /**
-   * Retrieve a list of all projects within the current organization
+   * Retrieves all projects belonging to the authenticated user's organization.
+   * Projects are returned in descending order of creation date (newest first). This
+   * endpoint is useful for displaying project selection in dashboards or for
+   * integrations that need to list all available projects.
+   *
+   * @example
+   * ```ts
+   * const projects = await client.org.project.list();
+   * ```
    */
   list(options?: RequestOptions): APIPromise<ProjectListResponse> {
     return this._client.get('/api/v3/org/project/list', options);
   }
 
+  /**
+   * Soft-deletes a project within the organization by its unique identifier. When a
+   * project is deleted, it is marked as deleted but not immediately removed from the
+   * database. This operation affects all resources associated with the project
+   * including API keys, webhook configurations, and connected services. This action
+   * cannot be undone through the API.
+   *
+   * @example
+   * ```ts
+   * const project = await client.org.project.delete(
+   *   'proj_abc123xyz456',
+   * );
+   * ```
+   */
   delete(projectID: string, options?: RequestOptions): APIPromise<ProjectDeleteResponse> {
     return this._client.delete(path`/api/v3/org/project/delete/${projectID}`, options);
   }
 }
 
 export interface ProjectCreateResponse {
+  /**
+   * Unique identifier for the project
+   */
   id: string;
 
+  /**
+   * ISO timestamp when the project was created
+   */
   created_at: string;
 
+  /**
+   * Whether this project has been soft-deleted
+   */
   deleted: boolean;
 
+  /**
+   * Email address associated with the project
+   */
   email: string;
 
+  /**
+   * URL where event webhook notifications will be sent (can be null)
+   */
   event_webhook_url: string | null;
 
+  /**
+   * Name of the project
+   */
   name: string;
 
+  /**
+   * Identifier of the organization that owns this project
+   */
   org_id: string;
 
+  /**
+   * ISO timestamp when the project was last updated
+   */
   updated_at: string;
 
+  /**
+   * Secret key used to sign webhook payloads for verification
+   */
   webhook_secret: string | null;
 
+  /**
+   * URL where webhook events will be sent (can be null)
+   */
   webhook_url: string | null;
 
+  /**
+   * Indicates if the webhook configuration is using the new format
+   */
   is_new_webhook?: boolean;
 
+  /**
+   * ISO timestamp when the project last subscribed to updates
+   */
   last_subscribed_at?: string | null;
 
+  /**
+   * Whether triggers are enabled for this project
+   */
   triggers_enabled?: boolean;
 }
 
 export interface ProjectRetrieveResponse {
+  /**
+   * Unique identifier for the project
+   */
   id: string;
 
+  /**
+   * ISO timestamp when the project was created
+   */
   created_at: string;
 
+  /**
+   * Whether this project has been soft-deleted
+   */
   deleted: boolean;
 
+  /**
+   * Email address associated with the project
+   */
   email: string;
 
+  /**
+   * URL where event webhook notifications will be sent (can be null)
+   */
   event_webhook_url: string | null;
 
+  /**
+   * Name of the project
+   */
   name: string;
 
+  /**
+   * Identifier of the organization that owns this project
+   */
   org_id: string;
 
+  /**
+   * ISO timestamp when the project was last updated
+   */
   updated_at: string;
 
+  /**
+   * Secret key used to sign webhook payloads for verification
+   */
   webhook_secret: string | null;
 
+  /**
+   * URL where webhook events will be sent (can be null)
+   */
   webhook_url: string | null;
 
+  /**
+   * Indicates if the webhook configuration is using the new format
+   */
   is_new_webhook?: boolean;
 
+  /**
+   * ISO timestamp when the project last subscribed to updates
+   */
   last_subscribed_at?: string | null;
 
+  /**
+   * Whether triggers are enabled for this project
+   */
   triggers_enabled?: boolean;
 }
 
+/**
+ * Response containing a list of projects
+ */
 export interface ProjectListResponse {
+  /**
+   * Array of projects belonging to the organization
+   */
   data: Array<ProjectListResponse.Data>;
 }
 
 export namespace ProjectListResponse {
   export interface Data {
+    /**
+     * Unique identifier for the project
+     */
     id: string;
 
+    /**
+     * ISO timestamp when the project was created
+     */
     created_at: string;
 
+    /**
+     * Whether this project has been soft-deleted
+     */
     deleted: boolean;
 
+    /**
+     * Email address associated with the project
+     */
     email: string;
 
+    /**
+     * URL where event webhook notifications will be sent (can be null)
+     */
     event_webhook_url: string | null;
 
+    /**
+     * Name of the project
+     */
     name: string;
 
+    /**
+     * Identifier of the organization that owns this project
+     */
     org_id: string;
 
+    /**
+     * ISO timestamp when the project was last updated
+     */
     updated_at: string;
 
+    /**
+     * Secret key used to sign webhook payloads for verification
+     */
     webhook_secret: string | null;
 
+    /**
+     * URL where webhook events will be sent (can be null)
+     */
     webhook_url: string | null;
 
+    /**
+     * Indicates if the webhook configuration is using the new format
+     */
     is_new_webhook?: boolean;
 
+    /**
+     * ISO timestamp when the project last subscribed to updates
+     */
     last_subscribed_at?: string | null;
 
+    /**
+     * Whether triggers are enabled for this project
+     */
     triggers_enabled?: boolean;
   }
 }
 
+/**
+ * Response indicating the result of a project deletion operation
+ */
 export interface ProjectDeleteResponse {
+  /**
+   * Status of the delete operation
+   */
   status: string;
 }
 
 export interface ProjectCreateParams {
   /**
-   * Name of the project
+   * A unique name for your project that follows the required format rules
    */
   name: string;
 }