files.ts

// 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 { Page, type PageParams, PagePromise } from '../core/pagination';
import { type Uploadable } from '../core/uploads';
import { RequestOptions } from '../internal/request-options';
import { multipartFormRequestOptions } from '../internal/uploads';
import { path } from '../internal/utils/path';

export class Files extends APIResource {
  /**
   * To upload a file to Increase, you'll need to send a request of Content-Type
   * `multipart/form-data`. The request should contain the file you would like to
   * upload, as well as the parameters for creating a file.
   *
   * @example
   * ```ts
   * const file = await client.files.create({
   *   file: fs.createReadStream('path/to/file'),
   *   purpose: 'check_image_front',
   * });
   * ```
   */
  create(body: FileCreateParams, options?: RequestOptions): APIPromise<File> {
    return this._client.post('/files', multipartFormRequestOptions({ body, ...options }, this._client));
  }

  /**
   * Retrieve a File
   *
   * @example
   * ```ts
   * const file = await client.files.retrieve(
   *   'file_makxrc67oh9l6sg7w9yc',
   * );
   * ```
   */
  retrieve(fileID: string, options?: RequestOptions): APIPromise<File> {
    return this._client.get(path`/files/${fileID}`, options);
  }

  /**
   * List Files
   *
   * @example
   * ```ts
   * // Automatically fetches more pages as needed.
   * for await (const file of client.files.list()) {
   *   // ...
   * }
   * ```
   */
  list(
    query: FileListParams | null | undefined = {},
    options?: RequestOptions,
  ): PagePromise<FilesPage, File> {
    return this._client.getAPIList('/files', Page<File>, { query, ...options });
  }
}

export type FilesPage = Page<File>;

/**
 * Files are objects that represent a file hosted on Increase's servers. The file
 * may have been uploaded by you (for example, when uploading a check image) or it
 * may have been created by Increase (for example, an autogenerated statement PDF).
 * If you need to download a File, create a File Link.
 */
export interface File {
  /**
   * The File's identifier.
   */
  id: string;

  /**
   * The time the File was created.
   */
  created_at: string;

  /**
   * A description of the File.
   */
  description: string | null;

  /**
   * Whether the File was generated by Increase or by you and sent to Increase.
   *
   * - `to_increase` - This File was sent by you to Increase.
   * - `from_increase` - This File was generated by Increase.
   */
  direction: 'to_increase' | 'from_increase';

  /**
   * The filename that was provided upon upload or generated by Increase.
   */
  filename: string | null;

  /**
   * The idempotency key you chose for this object. This value is unique across
   * Increase and is used to ensure that a request is only processed once. Learn more
   * about [idempotency](https://increase.com/documentation/idempotency-keys).
   */
  idempotency_key: string | null;

  /**
   * The MIME type of the file.
   */
  mime_type: string;

  /**
   * What the File will be used for. We may add additional possible values for this
   * enum over time; your application should be able to handle such additions
   * gracefully.
   *
   * - `card_dispute_attachment` - A file to be attached to a Card Dispute.
   * - `check_image_front` - An image of the front of a check, used for check
   *   deposits.
   * - `check_image_back` - An image of the back of a check, used for check deposits.
   * - `processed_check_image_front` - An image of the front of a deposited check
   *   after processing by Increase and submission to the Federal Reserve.
   * - `processed_check_image_back` - An image of the back of a deposited check after
   *   processing by Increase and submission to the Federal Reserve.
   * - `mailed_check_image` - An image of a check that was mailed to a recipient.
   * - `check_attachment` - A document to be printed on an additional page and mailed
   *   with a check that you've requested Increase print. This must be a PDF whose
   *   pages are all US letter size and all have the same orientation.
   * - `check_voucher_image` - An image to be used as the check voucher image, which
   *   is printed in the middle of the trifold area of a check. This must be a
   *   2550x1100 pixel PNG.
   * - `check_signature` - A signature image to be printed on a check. This must be a
   *   1320x120 pixel PNG.
   * - `inbound_mail_item` - A scanned mail item sent to Increase.
   * - `form_1099_int` - IRS Form 1099-INT.
   * - `form_1099_misc` - IRS Form 1099-MISC.
   * - `form_ss_4` - IRS Form SS-4.
   * - `identity_document` - An image of a government-issued ID.
   * - `increase_statement` - A statement generated by Increase.
   * - `loan_application_supplemental_document` - A supplemental document for a Loan
   *   Application.
   * - `other` - A file purpose not covered by any of the other cases.
   * - `trust_formation_document` - A legal document forming a trust.
   * - `digital_wallet_artwork` - A card image to be rendered inside digital wallet
   *   apps. This must be a 1536x969 pixel PNG.
   * - `digital_wallet_app_icon` - An icon for you app to be rendered inside digital
   *   wallet apps. This must be a 100x100 pixel PNG.
   * - `physical_card_front` - A card image to be printed on the front of a physical
   *   card. This must be a 2100x1344 pixel PNG with no other color but black.
   * - `physical_card_back` - The image to be printed on the back of a physical card.
   * - `physical_card_carrier` - An image representing the entirety of the carrier
   *   used for a physical card. This must be a 2550x3300 pixel PNG with no other
   *   color but black.
   * - `document_request` - A document requested by Increase.
   * - `entity_supplemental_document` - A supplemental document associated an an
   *   Entity.
   * - `export` - The results of an Export you requested via the dashboard or API.
   * - `fee_statement` - A fee statement.
   * - `unusual_activity_report_attachment` - An attachment to an Unusual Activity
   *   Report.
   * - `deposit_account_control_agreement` - A document granting another entity
   *   access to the funds into your account.
   * - `proof_of_authorization_request_submission` - A file containing additional
   *   evidence for a Proof of Authorization Request Submission.
   * - `account_verification_letter` - An account verification letter.
   * - `funding_instructions` - Funding instructions.
   * - `hold_harmless_letter` - A Hold Harmless Letter.
   */
  purpose:
    | 'card_dispute_attachment'
    | 'check_image_front'
    | 'check_image_back'
    | 'processed_check_image_front'
    | 'processed_check_image_back'
    | 'mailed_check_image'
    | 'check_attachment'
    | 'check_voucher_image'
    | 'check_signature'
    | 'inbound_mail_item'
    | 'form_1099_int'
    | 'form_1099_misc'
    | 'form_ss_4'
    | 'identity_document'
    | 'increase_statement'
    | 'loan_application_supplemental_document'
    | 'other'
    | 'trust_formation_document'
    | 'digital_wallet_artwork'
    | 'digital_wallet_app_icon'
    | 'physical_card_front'
    | 'physical_card_back'
    | 'physical_card_carrier'
    | 'document_request'
    | 'entity_supplemental_document'
    | 'export'
    | 'fee_statement'
    | 'unusual_activity_report_attachment'
    | 'deposit_account_control_agreement'
    | 'proof_of_authorization_request_submission'
    | 'account_verification_letter'
    | 'funding_instructions'
    | 'hold_harmless_letter';

  /**
   * A constant representing the object's type. For this resource it will always be
   * `file`.
   */
  type: 'file';

  [k: string]: unknown;
}

export interface FileCreateParams {
  /**
   * The file contents. This should follow the specifications of
   * [RFC 7578](https://datatracker.ietf.org/doc/html/rfc7578) which defines file
   * transfers for the multipart/form-data protocol.
   */
  file: Uploadable;

  /**
   * What the File will be used for in Increase's systems.
   *
   * - `card_dispute_attachment` - A file to be attached to a Card Dispute.
   * - `check_image_front` - An image of the front of a check, used for check
   *   deposits.
   * - `check_image_back` - An image of the back of a check, used for check deposits.
   * - `mailed_check_image` - An image of a check that was mailed to a recipient.
   * - `check_attachment` - A document to be printed on an additional page and mailed
   *   with a check that you've requested Increase print. This must be a PDF whose
   *   pages are all US letter size and all have the same orientation.
   * - `check_voucher_image` - An image to be used as the check voucher image, which
   *   is printed in the middle of the trifold area of a check. This must be a
   *   2550x1100 pixel PNG.
   * - `check_signature` - A signature image to be printed on a check. This must be a
   *   1320x120 pixel PNG.
   * - `form_ss_4` - IRS Form SS-4.
   * - `identity_document` - An image of a government-issued ID.
   * - `loan_application_supplemental_document` - A supplemental document for a Loan
   *   Application.
   * - `other` - A file purpose not covered by any of the other cases.
   * - `trust_formation_document` - A legal document forming a trust.
   * - `digital_wallet_artwork` - A card image to be rendered inside digital wallet
   *   apps. This must be a 1536x969 pixel PNG.
   * - `digital_wallet_app_icon` - An icon for you app to be rendered inside digital
   *   wallet apps. This must be a 100x100 pixel PNG.
   * - `physical_card_front` - A card image to be printed on the front of a physical
   *   card. This must be a 2100x1344 pixel PNG with no other color but black.
   * - `physical_card_carrier` - An image representing the entirety of the carrier
   *   used for a physical card. This must be a 2550x3300 pixel PNG with no other
   *   color but black.
   * - `document_request` - A document requested by Increase.
   * - `entity_supplemental_document` - A supplemental document associated an an
   *   Entity.
   * - `unusual_activity_report_attachment` - An attachment to an Unusual Activity
   *   Report.
   * - `proof_of_authorization_request_submission` - A file containing additional
   *   evidence for a Proof of Authorization Request Submission.
   */
  purpose:
    | 'card_dispute_attachment'
    | 'check_image_front'
    | 'check_image_back'
    | 'mailed_check_image'
    | 'check_attachment'
    | 'check_voucher_image'
    | 'check_signature'
    | 'form_ss_4'
    | 'identity_document'
    | 'loan_application_supplemental_document'
    | 'other'
    | 'trust_formation_document'
    | 'digital_wallet_artwork'
    | 'digital_wallet_app_icon'
    | 'physical_card_front'
    | 'physical_card_carrier'
    | 'document_request'
    | 'entity_supplemental_document'
    | 'unusual_activity_report_attachment'
    | 'proof_of_authorization_request_submission';

  /**
   * The description you choose to give the File.
   */
  description?: string;

  [k: string]: unknown;
}

export interface FileListParams extends PageParams {
  created_at?: FileListParams.CreatedAt;

  /**
   * Filter records to the one with the specified `idempotency_key` you chose for
   * that object. This value is unique across Increase and is used to ensure that a
   * request is only processed once. Learn more about
   * [idempotency](https://increase.com/documentation/idempotency-keys).
   */
  idempotency_key?: string;

  purpose?: FileListParams.Purpose;
}

export namespace FileListParams {
  export interface CreatedAt {
    /**
     * Return results after this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)
     * timestamp.
     */
    after?: string;

    /**
     * Return results before this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)
     * timestamp.
     */
    before?: string;

    /**
     * Return results on or after this
     * [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.
     */
    on_or_after?: string;

    /**
     * Return results on or before this
     * [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.
     */
    on_or_before?: string;
  }

  export interface Purpose {
    /**
     * Filter Files for those with the specified purpose or purposes. For GET requests,
     * this should be encoded as a comma-delimited string, such as `?in=one,two,three`.
     */
    in?: Array<
      | 'card_dispute_attachment'
      | 'check_image_front'
      | 'check_image_back'
      | 'processed_check_image_front'
      | 'processed_check_image_back'
      | 'mailed_check_image'
      | 'check_attachment'
      | 'check_voucher_image'
      | 'check_signature'
      | 'inbound_mail_item'
      | 'form_1099_int'
      | 'form_1099_misc'
      | 'form_ss_4'
      | 'identity_document'
      | 'increase_statement'
      | 'loan_application_supplemental_document'
      | 'other'
      | 'trust_formation_document'
      | 'digital_wallet_artwork'
      | 'digital_wallet_app_icon'
      | 'physical_card_front'
      | 'physical_card_back'
      | 'physical_card_carrier'
      | 'document_request'
      | 'entity_supplemental_document'
      | 'export'
      | 'fee_statement'
      | 'unusual_activity_report_attachment'
      | 'deposit_account_control_agreement'
      | 'proof_of_authorization_request_submission'
      | 'account_verification_letter'
      | 'funding_instructions'
      | 'hold_harmless_letter'
    >;
  }
}

export declare namespace Files {
  export {
    type File as File,
    type FilesPage as FilesPage,
    type FileCreateParams as FileCreateParams,
    type FileListParams as FileListParams,
  };
}