// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import { APIResource } from '../core/resource';
import { APIPromise } from '../core/api-promise';
import { RequestOptions } from '../internal/request-options';
import { path } from '../internal/utils/path';

/**
 * Authentication configuration management
 */
export class AuthConfigs extends APIResource {
  /**
   * Creates a new auth config for a toolkit, allowing you to use your own OAuth
   * credentials or API keys instead of Composio-managed authentication. This is
   * required when you want to use custom OAuth apps (bring your own client
   * ID/secret) or configure specific authentication parameters for a toolkit.
   *
   * @example
   * ```ts
   * const authConfig = await client.authConfigs.create({
   *   toolkit: { slug: 'slug' },
   * });
   * ```
   */
  create(body: AuthConfigCreateParams, options?: RequestOptions): APIPromise<AuthConfigCreateResponse> {
    return this._client.post('/api/v3.1/auth_configs', { body, ...options });
  }

  /**
   * Retrieves detailed information about a specific authentication configuration
   * using its unique identifier.
   *
   * @example
   * ```ts
   * const authConfig = await client.authConfigs.retrieve(
   *   'nanoid',
   * );
   * ```
   */
  retrieve(nanoid: string, options?: RequestOptions): APIPromise<AuthConfigRetrieveResponse> {
    return this._client.get(path`/api/v3.1/auth_configs/${nanoid}`, options);
  }

  /**
   * Modifies an existing authentication configuration with new credentials or other
   * settings. Only specified fields will be updated.
   *
   * @example
   * ```ts
   * const authConfig = await client.authConfigs.update(
   *   'nanoid',
   *   { type: 'custom' },
   * );
   * ```
   */
  update(nanoid: string, body: AuthConfigUpdateParams, options?: RequestOptions): APIPromise<unknown> {
    return this._client.patch(path`/api/v3.1/auth_configs/${nanoid}`, { body, ...options });
  }

  /**
   * Retrieves all auth configs for your project. Auth configs define how users
   * authenticate with external services (OAuth, API keys, etc.). Use filters to find
   * configs for specific toolkits or to distinguish between Composio-managed and
   * custom configurations.
   *
   * @example
   * ```ts
   * const authConfigs = await client.authConfigs.list();
   * ```
   */
  list(
    query: AuthConfigListParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<AuthConfigListResponse> {
    return this._client.get('/api/v3.1/auth_configs', { query, ...options });
  }

  /**
   * Soft-deletes an authentication configuration by marking it as deleted in the
   * database. This operation cannot be undone. Pass `?revoke_on_delete=true` to also
   * revoke the upstream credentials of every connection using this auth config via a
   * background job.
   *
   * @example
   * ```ts
   * const authConfig = await client.authConfigs.delete(
   *   'nanoid',
   * );
   * ```
   */
  delete(
    nanoid: string,
    params: AuthConfigDeleteParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<AuthConfigDeleteResponse> {
    const { revoke_on_delete } = params ?? {};
    return this._client.delete(path`/api/v3.1/auth_configs/${nanoid}`, {
      query: { revoke_on_delete },
      ...options,
    });
  }

  /**
   * Updates the status of an authentication configuration to either enabled or
   * disabled. Disabled configurations cannot be used for new connections.
   *
   * @example
   * ```ts
   * const response = await client.authConfigs.updateStatus(
   *   'ENABLED',
   *   { nanoid: 'nanoid' },
   * );
   * ```
   */
  updateStatus(
    status: 'ENABLED' | 'DISABLED',
    params: AuthConfigUpdateStatusParams,
    options?: RequestOptions,
  ): APIPromise<unknown> {
    const { nanoid } = params;
    return this._client.patch(path`/api/v3.1/auth_configs/${nanoid}/${status}`, options);
  }
}

export interface AuthConfigCreateResponse {
  auth_config: AuthConfigCreateResponse.AuthConfig;

  toolkit: AuthConfigCreateResponse.Toolkit;
}

export namespace AuthConfigCreateResponse {
  export interface AuthConfig {
    /**
     * The auth config id of the toolkit (must be a valid auth config id)
     */
    id: string;

    /**
     * The authentication mode of the toolkit
     */
    auth_scheme: string;

    /**
     * Whether the auth config is managed by Composio
     */
    is_composio_managed: boolean;

    /**
     * The tools that the user can use with the auth config
     */
    restrict_to_following_tools?: Array<string>;
  }

  export interface Toolkit {
    /**
     * The unique key of the toolkit
     */
    slug: string;
  }
}

export interface AuthConfigRetrieveResponse {
  /**
   * The unique ID of the authentication configuration
   */
  id: string;

  /**
   * The display name of the authentication configuration
   */
  name: string;

  /**
   * The number of active connections using this auth config
   */
  no_of_connections: number;

  /**
   * Current status of the authentication configuration
   */
  status: 'ENABLED' | 'DISABLED';

  tool_access_config: AuthConfigRetrieveResponse.ToolAccessConfig;

  /**
   * Information about the associated integration
   */
  toolkit: AuthConfigRetrieveResponse.Toolkit;

  /**
   * The type of the authentication configuration (custom or default)
   */
  type: 'default' | 'custom';

  /**
   * @deprecated The UUID of the authentication configuration (for backward
   * compatibility)
   */
  uuid: string;

  /**
   * The authentication scheme used (e.g., OAuth2, API Key, etc.)
   */
  auth_scheme?:
    | 'OAUTH2'
    | 'OAUTH1'
    | 'API_KEY'
    | 'BASIC'
    | 'BILLCOM_AUTH'
    | 'BEARER_TOKEN'
    | 'GOOGLE_SERVICE_ACCOUNT'
    | 'NO_AUTH'
    | 'BASIC_WITH_JWT'
    | 'CALCOM_AUTH'
    | 'SERVICE_ACCOUNT'
    | 'SAML'
    | 'DCR_OAUTH'
    | 'S2S_OAUTH2';

  /**
   * ISO 8601 date-time when the auth config was created
   */
  created_at?: string;

  /**
   * The identifier of the user who created the auth config
   */
  created_by?: string;

  /**
   * The authentication credentials (tokens, keys, etc.) - may be partially hidden
   * for security
   */
  credentials?: { [key: string]: unknown };

  /**
   * Fields expected during connection initialization
   */
  expected_input_fields?: Array<unknown>;

  /**
   * Whether this authentication configuration is managed by Composio or the user
   */
  is_composio_managed?: boolean;

  /**
   * Whether this auth config is enabled for tool router
   */
  is_enabled_for_tool_router?: boolean;

  /**
   * ISO 8601 date-time when the auth config was last updated
   */
  last_updated_at?: string;

  proxy_config?: AuthConfigRetrieveResponse.ProxyConfig | null;

  /**
   * @deprecated Use tool_access_config instead. This field will be deprecated in the
   * future.
   */
  restrict_to_following_tools?: Array<string>;

  /**
   * [EXPERIMENTAL] Shared credentials that will be inherited by all connected
   * accounts using this auth config
   */
  shared_credentials?: { [key: string]: unknown };
}

export namespace AuthConfigRetrieveResponse {
  export interface ToolAccessConfig {
    /**
     * The actions that the user can perform on the auth config. If passed, this will
     * update the actions that the user can perform on the auth config.
     */
    tools_available_for_execution?: Array<string>;

    /**
     * Tools used to generate the minimum required scopes for the auth config (only
     * valid for OAuth). If passed, this will update the scopes.
     */
    tools_for_connected_account_creation?: Array<string>;
  }

  /**
   * Information about the associated integration
   */
  export interface Toolkit {
    /**
     * The URL to the integration app's logo image
     */
    logo: string;

    /**
     * The unique identifier of the integration app
     */
    slug: string;

    /**
     * URL to a guide page with authentication setup instructions
     */
    auth_guide_url?: string | null;

    /**
     * URL to a page where users can obtain or configure credentials
     */
    auth_hint_url?: string | null;
  }

  export interface ProxyConfig {
    /**
     * The url of the auth proxy
     */
    proxy_url: string;

    /**
     * The auth key for the auth proxy
     */
    proxy_auth_key?: string;
  }
}

export type AuthConfigUpdateResponse = unknown;

export interface AuthConfigListResponse {
  current_page: number;

  items: Array<AuthConfigListResponse.Item>;

  total_items: number;

  total_pages: number;

  next_cursor?: string | null;
}

export namespace AuthConfigListResponse {
  export interface Item {
    /**
     * The unique ID of the authentication configuration
     */
    id: string;

    /**
     * The display name of the authentication configuration
     */
    name: string;

    /**
     * The number of active connections using this auth config
     */
    no_of_connections: number;

    /**
     * Current status of the authentication configuration
     */
    status: 'ENABLED' | 'DISABLED';

    tool_access_config: Item.ToolAccessConfig;

    /**
     * Information about the associated integration
     */
    toolkit: Item.Toolkit;

    /**
     * The type of the authentication configuration (custom or default)
     */
    type: 'default' | 'custom';

    /**
     * @deprecated The UUID of the authentication configuration (for backward
     * compatibility)
     */
    uuid: string;

    /**
     * The authentication scheme used (e.g., OAuth2, API Key, etc.)
     */
    auth_scheme?:
      | 'OAUTH2'
      | 'OAUTH1'
      | 'API_KEY'
      | 'BASIC'
      | 'BILLCOM_AUTH'
      | 'BEARER_TOKEN'
      | 'GOOGLE_SERVICE_ACCOUNT'
      | 'NO_AUTH'
      | 'BASIC_WITH_JWT'
      | 'CALCOM_AUTH'
      | 'SERVICE_ACCOUNT'
      | 'SAML'
      | 'DCR_OAUTH'
      | 'S2S_OAUTH2';

    /**
     * ISO 8601 date-time when the auth config was created
     */
    created_at?: string;

    /**
     * The identifier of the user who created the auth config
     */
    created_by?: string;

    /**
     * The authentication credentials (tokens, keys, etc.) - may be partially hidden
     * for security
     */
    credentials?: { [key: string]: unknown };

    /**
     * Fields expected during connection initialization
     */
    expected_input_fields?: Array<unknown>;

    /**
     * Whether this authentication configuration is managed by Composio or the user
     */
    is_composio_managed?: boolean;

    /**
     * Whether this auth config is enabled for tool router
     */
    is_enabled_for_tool_router?: boolean;

    /**
     * ISO 8601 date-time when the auth config was last updated
     */
    last_updated_at?: string;

    proxy_config?: Item.ProxyConfig | null;

    /**
     * @deprecated Use tool_access_config instead. This field will be deprecated in the
     * future.
     */
    restrict_to_following_tools?: Array<string>;

    /**
     * [EXPERIMENTAL] Shared credentials that will be inherited by all connected
     * accounts using this auth config
     */
    shared_credentials?: { [key: string]: unknown };
  }

  export namespace Item {
    export interface ToolAccessConfig {
      /**
       * The actions that the user can perform on the auth config. If passed, this will
       * update the actions that the user can perform on the auth config.
       */
      tools_available_for_execution?: Array<string>;

      /**
       * Tools used to generate the minimum required scopes for the auth config (only
       * valid for OAuth). If passed, this will update the scopes.
       */
      tools_for_connected_account_creation?: Array<string>;
    }

    /**
     * Information about the associated integration
     */
    export interface Toolkit {
      /**
       * The URL to the integration app's logo image
       */
      logo: string;

      /**
       * The unique identifier of the integration app
       */
      slug: string;

      /**
       * URL to a guide page with authentication setup instructions
       */
      auth_guide_url?: string | null;

      /**
       * URL to a page where users can obtain or configure credentials
       */
      auth_hint_url?: string | null;
    }

    export interface ProxyConfig {
      /**
       * The url of the auth proxy
       */
      proxy_url: string;

      /**
       * The auth key for the auth proxy
       */
      proxy_auth_key?: string;
    }
  }
}

export interface AuthConfigDeleteResponse {
  /**
   * Identifier of the background revoke job started for this delete. Present only
   * when `revoke_on_delete=true`. Track the job and its per-connection results from
   * the Composio dashboard — a programmatic endpoint to poll this job is not yet
   * generally available.
   */
  revoke_job_id?: string;
}

export type AuthConfigUpdateStatusResponse = unknown;

export interface AuthConfigCreateParams {
  toolkit: AuthConfigCreateParams.Toolkit;

  auth_config?: AuthConfigCreateParams.UnionMember0 | AuthConfigCreateParams.UnionMember1;
}

export namespace AuthConfigCreateParams {
  export interface Toolkit {
    /**
     * Toolkit slug to create auth config for
     */
    slug: string;
  }

  export interface UnionMember0 {
    type: 'use_composio_managed_auth';

    credentials?: UnionMember0.Credentials;

    /**
     * Whether this auth config is enabled for tool router
     */
    is_enabled_for_tool_router?: boolean;

    /**
     * The name of the integration
     */
    name?: string;

    /**
     * @deprecated Use tool_access_config instead. This field will be deprecated in the
     * future.
     */
    restrict_to_following_tools?: Array<string>;

    /**
     * [EXPERIMENTAL] Shared credentials that will be inherited by all connected
     * accounts using this auth config
     */
    shared_credentials?: { [key: string]: unknown };

    tool_access_config?: UnionMember0.ToolAccessConfig;
  }

  export namespace UnionMember0 {
    export interface Credentials {
      /**
       * OAuth scopes requested for the managed auth config.
       */
      scopes?: string | Array<string>;

      /**
       * OAuth user-token scopes requested for the managed auth config. This is primarily
       * used by Slack OAuth v2.
       */
      user_scopes?: string | Array<string>;
    }

    export interface ToolAccessConfig {
      /**
       * Tools used to generate the minimum required scopes for the auth config (only
       * valid for OAuth). If passed, this will update the scopes.
       */
      tools_for_connected_account_creation?: Array<string>;
    }
  }

  export interface UnionMember1 {
    authScheme:
      | 'OAUTH2'
      | 'OAUTH1'
      | 'API_KEY'
      | 'BASIC'
      | 'BILLCOM_AUTH'
      | 'BEARER_TOKEN'
      | 'GOOGLE_SERVICE_ACCOUNT'
      | 'NO_AUTH'
      | 'BASIC_WITH_JWT'
      | 'CALCOM_AUTH'
      | 'SERVICE_ACCOUNT'
      | 'SAML'
      | 'DCR_OAUTH'
      | 'S2S_OAUTH2';

    type: 'use_custom_auth';

    credentials?: UnionMember1.Credentials;

    /**
     * Whether this auth config is enabled for tool router
     */
    is_enabled_for_tool_router?: boolean;

    /**
     * The name of the integration
     */
    name?: string;

    proxy_config?: UnionMember1.ProxyConfig | null;

    /**
     * @deprecated Use tool_access_config instead. This field will be deprecated in the
     * future.
     */
    restrict_to_following_tools?: Array<string>;

    /**
     * [EXPERIMENTAL] Shared credentials that will be inherited by all connected
     * accounts using this auth config
     */
    shared_credentials?: { [key: string]: unknown };

    tool_access_config?: UnionMember1.ToolAccessConfig;
  }

  export namespace UnionMember1 {
    export interface Credentials {
      /**
       * OAuth scopes requested for the custom auth config.
       */
      scopes?: string | Array<string>;

      /**
       * OAuth user-token scopes requested for the custom auth config. This is primarily
       * used by Slack OAuth v2.
       */
      user_scopes?: string | Array<string>;
    }

    export interface ProxyConfig {
      /**
       * The url of the auth proxy
       */
      proxy_url: string;

      /**
       * The auth key for the auth proxy
       */
      proxy_auth_key?: string;
    }

    export interface ToolAccessConfig {
      /**
       * Tools used to generate the minimum required scopes for the auth config (only
       * valid for OAuth). If passed, this will update the scopes.
       */
      tools_for_connected_account_creation?: Array<string>;
    }
  }
}

export type AuthConfigUpdateParams = AuthConfigUpdateParams.Variant0 | AuthConfigUpdateParams.Variant1;

export declare namespace AuthConfigUpdateParams {
  export interface Variant0 {
    type: 'custom';

    credentials?: Variant0.Credentials;

    /**
     * Whether this auth config is enabled for tool router
     */
    is_enabled_for_tool_router?: boolean;

    /**
     * The display name of the authentication configuration
     */
    name?: string;

    proxy_config?: Variant0.ProxyConfig | null;

    /**
     * @deprecated Use tool_access_config instead. This field will be deprecated in the
     * future.
     */
    restrict_to_following_tools?: Array<string>;

    /**
     * Shared credentials inherited by all connected accounts using this auth config.
     * Secret values are redacted in responses, so provide the real values when
     * updating; omit this field to leave them unchanged.
     */
    shared_credentials?: { [key: string]: unknown };

    tool_access_config?: Variant0.ToolAccessConfig;
  }

  export namespace Variant0 {
    export interface Credentials {
      /**
       * OAuth scopes requested for the auth config.
       */
      scopes?: string | Array<string>;

      /**
       * OAuth user-token scopes requested for the auth config. This is primarily used by
       * Slack OAuth v2.
       */
      user_scopes?: string | Array<string>;
    }

    export interface ProxyConfig {
      /**
       * The url of the auth proxy
       */
      proxy_url: string;

      /**
       * The auth key for the auth proxy
       */
      proxy_auth_key?: string;
    }

    export interface ToolAccessConfig {
      /**
       * The actions that the user can perform on the auth config. If passed, this will
       * update the actions that the user can perform on the auth config.
       */
      tools_available_for_execution?: Array<string>;

      /**
       * Tools used to generate the minimum required scopes for the auth config (only
       * valid for OAuth). If passed, this will update the scopes.
       */
      tools_for_connected_account_creation?: Array<string>;
    }
  }

  export interface Variant1 {
    type: 'default';

    /**
     * Whether this auth config is enabled for tool router
     */
    is_enabled_for_tool_router?: boolean;

    /**
     * The display name of the authentication configuration
     */
    name?: string;

    /**
     * @deprecated Use tool_access_config instead. This field will be deprecated in the
     * future.
     */
    restrict_to_following_tools?: Array<string>;

    /**
     * OAuth scopes requested for the auth config.
     */
    scopes?: string | Array<string>;

    /**
     * Shared credentials inherited by all connected accounts using this auth config.
     * Secret values are redacted in responses, so provide the real values when
     * updating; omit this field to leave them unchanged.
     */
    shared_credentials?: { [key: string]: unknown };

    tool_access_config?: Variant1.ToolAccessConfig;

    /**
     * OAuth user-token scopes requested for the auth config. This is primarily used by
     * Slack OAuth v2.
     */
    user_scopes?: string | Array<string>;
  }

  export namespace Variant1 {
    export interface ToolAccessConfig {
      /**
       * The actions that the user can perform on the auth config. If passed, this will
       * update the actions that the user can perform on the auth config.
       */
      tools_available_for_execution?: Array<string>;

      /**
       * Tools used to generate the minimum required scopes for the auth config (only
       * valid for OAuth). If passed, this will update the scopes.
       */
      tools_for_connected_account_creation?: Array<string>;
    }
  }
}

export interface AuthConfigListParams {
  /**
   * Cursor for pagination. The cursor is a base64 encoded string of the page and
   * limit. The page is the page number and the limit is the number of items per
   * page. The cursor is used to paginate through the items. The cursor is not
   * required for the first page.
   */
  cursor?: string;

  /**
   * @deprecated The app id to filter by
   */
  deprecated_app_id?: string;

  /**
   * @deprecated DEPRECATED: This parameter will be removed in a future version.
   */
  deprecated_status?: string;

  /**
   * Whether to filter by composio managed auth configs
   */
  is_composio_managed?: string | boolean;

  /**
   * Number of items per page, max allowed is 1000
   */
  limit?: number | null;

  /**
   * Search auth configs by name or id
   */
  search?: string;

  /**
   * Show disabled auth configs
   */
  show_disabled?: boolean | null;

  /**
   * Comma-separated list of toolkit slugs to filter auth configs by
   */
  toolkit_slug?: string;
}

export interface AuthConfigDeleteParams {
  /**
   * When `true`, the delete also starts a background job that revokes the upstream
   * credentials of every connected account in scope, and the response carries a
   * `revoke_job_id`. Defaults to `false`. Revocation is irreversible — recovering a
   * deleted entity does not restore working credentials.
   */
  revoke_on_delete?: boolean | null;
}

export interface AuthConfigUpdateStatusParams {
  /**
   * The unique identifier of the authentication configuration to update
   */
  nanoid: string;
}

export declare namespace AuthConfigs {
  export {
    type AuthConfigCreateResponse as AuthConfigCreateResponse,
    type AuthConfigRetrieveResponse as AuthConfigRetrieveResponse,
    type AuthConfigUpdateResponse as AuthConfigUpdateResponse,
    type AuthConfigListResponse as AuthConfigListResponse,
    type AuthConfigDeleteResponse as AuthConfigDeleteResponse,
    type AuthConfigUpdateStatusResponse as AuthConfigUpdateStatusResponse,
    type AuthConfigCreateParams as AuthConfigCreateParams,
    type AuthConfigUpdateParams as AuthConfigUpdateParams,
    type AuthConfigListParams as AuthConfigListParams,
    type AuthConfigDeleteParams as AuthConfigDeleteParams,
    type AuthConfigUpdateStatusParams as AuthConfigUpdateStatusParams,
  };
}