// 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 { PagePromise, V4PagePaginationArray, type V4PagePaginationArrayParams } from '../../core/pagination';
import { RequestOptions } from '../../internal/request-options';
import { path } from '../../internal/utils/path';

export class BaseRecipients extends APIResource {
  static override readonly _key: readonly ['resourceSharing', 'recipients'] = Object.freeze([
    'resourceSharing',
    'recipients',
  ] as const);

  /**
   * Adds a single recipient to an account-targeted resource share, granting them
   * access to the shared resources. The recipient account must belong to the same
   * organization as the share owner.
   *
   * To replace the entire recipient list in one call, use
   * `PUT /accounts/{account_id}/shares/{share_id}/recipients` instead.
   *
   * @example
   * ```ts
   * const recipient =
   *   await client.resourceSharing.recipients.create(
   *     '3fd85f74b32742f1bff64a85009dda07',
   *     { path_account_id: '023e105f4ecef8ad9ca31a8372d0c353' },
   *   );
   * ```
   */
  create(
    shareID: string,
    params: RecipientCreateParams,
    options?: RequestOptions,
  ): APIPromise<RecipientCreateResponse> {
    const { path_account_id, ...body } = params;
    return (
      this._client.post(path`/accounts/${path_account_id}/shares/${shareID}/recipients`, {
        body,
        ...options,
      }) as APIPromise<{ result: RecipientCreateResponse }>
    )._thenUnwrap((obj) => obj.result);
  }

  /**
   * List share recipients by share ID. Returns **all** recipients regardless of
   * their `association_status` (associating, associated, disassociating,
   * disassociated). Callers that want only "active" recipients must filter
   * client-side on the `association_status` field.
   *
   * @example
   * ```ts
   * // Automatically fetches more pages as needed.
   * for await (const recipientListResponse of client.resourceSharing.recipients.list(
   *   '3fd85f74b32742f1bff64a85009dda07',
   *   { account_id: '023e105f4ecef8ad9ca31a8372d0c353' },
   * )) {
   *   // ...
   * }
   * ```
   */
  list(
    shareID: string,
    params: RecipientListParams,
    options?: RequestOptions,
  ): PagePromise<RecipientListResponsesV4PagePaginationArray, RecipientListResponse> {
    const { account_id, ...query } = params;
    return this._client.getAPIList(
      path`/accounts/${account_id}/shares/${shareID}/recipients`,
      V4PagePaginationArray<RecipientListResponse>,
      { query, ...options },
    );
  }

  /**
   * Performs a **soft delete**: sets the recipient's `desired_association_status` to
   * `disassociated`, which signals the background reconciliation workflow (Temporal)
   * to remove the shared resources from the recipient account. The recipient record
   * remains in the database for audit purposes and is still returned by
   * `GET /accounts/{account_id}/shares/{share_id}/recipients` with its updated
   * status.
   *
   * Resource access is not fully removed until the workflow completes and
   * `current_association_status` transitions to `disassociated`. The recipient
   * record itself is never physically deleted.
   *
   * @example
   * ```ts
   * const recipient =
   *   await client.resourceSharing.recipients.delete(
   *     '3fd85f74b32742f1bff64a85009dda07',
   *     {
   *       account_id: '023e105f4ecef8ad9ca31a8372d0c353',
   *       share_id: '3fd85f74b32742f1bff64a85009dda07',
   *     },
   *   );
   * ```
   */
  delete(
    recipientID: string,
    params: RecipientDeleteParams,
    options?: RequestOptions,
  ): APIPromise<RecipientDeleteResponse> {
    const { account_id, share_id } = params;
    return (
      this._client.delete(
        path`/accounts/${account_id}/shares/${share_id}/recipients/${recipientID}`,
        options,
      ) as APIPromise<{ result: RecipientDeleteResponse }>
    )._thenUnwrap((obj) => obj.result);
  }

  /**
   * Get share recipient by ID.
   *
   * @example
   * ```ts
   * const recipient =
   *   await client.resourceSharing.recipients.get(
   *     '3fd85f74b32742f1bff64a85009dda07',
   *     {
   *       account_id: '023e105f4ecef8ad9ca31a8372d0c353',
   *       share_id: '3fd85f74b32742f1bff64a85009dda07',
   *     },
   *   );
   * ```
   */
  get(
    recipientID: string,
    params: RecipientGetParams,
    options?: RequestOptions,
  ): APIPromise<RecipientGetResponse> {
    const { account_id, share_id, ...query } = params;
    return (
      this._client.get(path`/accounts/${account_id}/shares/${share_id}/recipients/${recipientID}`, {
        query,
        ...options,
      }) as APIPromise<{ result: RecipientGetResponse }>
    )._thenUnwrap((obj) => obj.result);
  }
}
export class Recipients extends BaseRecipients {}

export type RecipientListResponsesV4PagePaginationArray = V4PagePaginationArray<RecipientListResponse>;

/**
 * A recipient of a share. The `association_status` field tracks the lifecycle of
 * the shared resources in the recipient account. All recipients are returned by
 * the list endpoint regardless of status; filter client-side if only active
 * recipients are needed.
 */
export interface RecipientCreateResponse {
  /**
   * Share Recipient identifier tag.
   */
  id: string;

  /**
   * Account identifier.
   */
  account_id: string;

  /**
   * The current state of the recipient relative to the share. The
   * `desired_association_status` (not exposed in the response) tracks the target
   * state set by the API; the background reconciliation workflow drives
   * `current_association_status` toward it.
   *
   * - `associating` — The recipient was recently added; the workflow is pushing
   *   shared resources into the recipient account.
   * - `associated` — Shared resources have been successfully applied to the
   *   recipient account.
   * - `disassociating` — The recipient was removed (via DELETE or PUT replacement);
   *   the workflow is removing shared resources from the recipient account.
   * - `disassociated` — Shared resources have been removed from the recipient
   *   account. The recipient record remains in the database.
   */
  association_status: 'associating' | 'associated' | 'disassociating' | 'disassociated';

  /**
   * When the share was created.
   */
  created: string;

  /**
   * When the share was modified.
   */
  modified: string;

  resources?: Array<RecipientCreateResponse.Resource>;
}

export namespace RecipientCreateResponse {
  export interface Resource {
    /**
     * Share Recipient error message.
     */
    error: string;

    /**
     * Share Resource identifier.
     */
    resource_id: string;

    /**
     * Resource Version.
     */
    resource_version: number;

    /**
     * Whether the error is terminal or will be continually retried.
     */
    terminal: boolean;
  }
}

/**
 * A recipient of a share. The `association_status` field tracks the lifecycle of
 * the shared resources in the recipient account. All recipients are returned by
 * the list endpoint regardless of status; filter client-side if only active
 * recipients are needed.
 */
export interface RecipientListResponse {
  /**
   * Share Recipient identifier tag.
   */
  id: string;

  /**
   * Account identifier.
   */
  account_id: string;

  /**
   * The current state of the recipient relative to the share. The
   * `desired_association_status` (not exposed in the response) tracks the target
   * state set by the API; the background reconciliation workflow drives
   * `current_association_status` toward it.
   *
   * - `associating` — The recipient was recently added; the workflow is pushing
   *   shared resources into the recipient account.
   * - `associated` — Shared resources have been successfully applied to the
   *   recipient account.
   * - `disassociating` — The recipient was removed (via DELETE or PUT replacement);
   *   the workflow is removing shared resources from the recipient account.
   * - `disassociated` — Shared resources have been removed from the recipient
   *   account. The recipient record remains in the database.
   */
  association_status: 'associating' | 'associated' | 'disassociating' | 'disassociated';

  /**
   * When the share was created.
   */
  created: string;

  /**
   * When the share was modified.
   */
  modified: string;

  resources?: Array<RecipientListResponse.Resource>;
}

export namespace RecipientListResponse {
  export interface Resource {
    /**
     * Share Recipient error message.
     */
    error: string;

    /**
     * Share Resource identifier.
     */
    resource_id: string;

    /**
     * Resource Version.
     */
    resource_version: number;

    /**
     * Whether the error is terminal or will be continually retried.
     */
    terminal: boolean;
  }
}

/**
 * A recipient of a share. The `association_status` field tracks the lifecycle of
 * the shared resources in the recipient account. All recipients are returned by
 * the list endpoint regardless of status; filter client-side if only active
 * recipients are needed.
 */
export interface RecipientDeleteResponse {
  /**
   * Share Recipient identifier tag.
   */
  id: string;

  /**
   * Account identifier.
   */
  account_id: string;

  /**
   * The current state of the recipient relative to the share. The
   * `desired_association_status` (not exposed in the response) tracks the target
   * state set by the API; the background reconciliation workflow drives
   * `current_association_status` toward it.
   *
   * - `associating` — The recipient was recently added; the workflow is pushing
   *   shared resources into the recipient account.
   * - `associated` — Shared resources have been successfully applied to the
   *   recipient account.
   * - `disassociating` — The recipient was removed (via DELETE or PUT replacement);
   *   the workflow is removing shared resources from the recipient account.
   * - `disassociated` — Shared resources have been removed from the recipient
   *   account. The recipient record remains in the database.
   */
  association_status: 'associating' | 'associated' | 'disassociating' | 'disassociated';

  /**
   * When the share was created.
   */
  created: string;

  /**
   * When the share was modified.
   */
  modified: string;

  resources?: Array<RecipientDeleteResponse.Resource>;
}

export namespace RecipientDeleteResponse {
  export interface Resource {
    /**
     * Share Recipient error message.
     */
    error: string;

    /**
     * Share Resource identifier.
     */
    resource_id: string;

    /**
     * Resource Version.
     */
    resource_version: number;

    /**
     * Whether the error is terminal or will be continually retried.
     */
    terminal: boolean;
  }
}

/**
 * A recipient of a share. The `association_status` field tracks the lifecycle of
 * the shared resources in the recipient account. All recipients are returned by
 * the list endpoint regardless of status; filter client-side if only active
 * recipients are needed.
 */
export interface RecipientGetResponse {
  /**
   * Share Recipient identifier tag.
   */
  id: string;

  /**
   * Account identifier.
   */
  account_id: string;

  /**
   * The current state of the recipient relative to the share. The
   * `desired_association_status` (not exposed in the response) tracks the target
   * state set by the API; the background reconciliation workflow drives
   * `current_association_status` toward it.
   *
   * - `associating` — The recipient was recently added; the workflow is pushing
   *   shared resources into the recipient account.
   * - `associated` — Shared resources have been successfully applied to the
   *   recipient account.
   * - `disassociating` — The recipient was removed (via DELETE or PUT replacement);
   *   the workflow is removing shared resources from the recipient account.
   * - `disassociated` — Shared resources have been removed from the recipient
   *   account. The recipient record remains in the database.
   */
  association_status: 'associating' | 'associated' | 'disassociating' | 'disassociated';

  /**
   * When the share was created.
   */
  created: string;

  /**
   * When the share was modified.
   */
  modified: string;

  resources?: Array<RecipientGetResponse.Resource>;
}

export namespace RecipientGetResponse {
  export interface Resource {
    /**
     * Share Recipient error message.
     */
    error: string;

    /**
     * Share Resource identifier.
     */
    resource_id: string;

    /**
     * Resource Version.
     */
    resource_version: number;

    /**
     * Whether the error is terminal or will be continually retried.
     */
    terminal: boolean;
  }
}

export interface RecipientCreateParams {
  /**
   * Path param: Account identifier.
   */
  path_account_id: string;

  /**
   * @deprecated This field has been renamed to `recipient_account_id`. Both names
   * are accepted during the deprecation period.
   */
  body_account_id?: string;

  /**
   * Body param: Organization identifier.
   */
  organization_id?: string;

  /**
   * Body param: The account that will receive the share.
   */
  recipient_account_id?: string;
}

export interface RecipientListParams extends V4PagePaginationArrayParams {
  /**
   * Path param: Account identifier.
   */
  account_id: string;

  /**
   * Query param: Include resources in the response.
   */
  include_resources?: boolean;
}

export interface RecipientDeleteParams {
  /**
   * Account identifier.
   */
  account_id: string;

  /**
   * Share identifier tag.
   */
  share_id: string;
}

export interface RecipientGetParams {
  /**
   * Path param: Account identifier.
   */
  account_id: string;

  /**
   * Path param: Share identifier tag.
   */
  share_id: string;

  /**
   * Query param: Include resources in the response.
   */
  include_resources?: boolean;
}

export declare namespace Recipients {
  export {
    type RecipientCreateResponse as RecipientCreateResponse,
    type RecipientListResponse as RecipientListResponse,
    type RecipientDeleteResponse as RecipientDeleteResponse,
    type RecipientGetResponse as RecipientGetResponse,
    type RecipientListResponsesV4PagePaginationArray as RecipientListResponsesV4PagePaginationArray,
    type RecipientCreateParams as RecipientCreateParams,
    type RecipientListParams as RecipientListParams,
    type RecipientDeleteParams as RecipientDeleteParams,
    type RecipientGetParams as RecipientGetParams,
  };
}