automated.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 { RequestOptions } from '../../internal/request-options';
import { path } from '../../internal/utils/path';

export class Automated extends APIResource {
  /**
   * Enqueue an automated job.
   *
   * `data_sync_all`: Enqueue a job to re-sync all data for a connection.
   * `data_sync_all` has a concurrency limit of 1 job at a time per connection. This
   * means that if this endpoint is called while a job is already in progress for
   * this connection, Finch will return the `job_id` of the job that is currently in
   * progress. Finch allows a fixed window rate limit of 1 forced refresh per hour
   * per connection.
   *
   * `w4_form_employee_sync`: Enqueues a job for sync W-4 data for a particular
   * individual, identified by `individual_id`. This feature is currently in beta.
   *
   * This endpoint is available for _Scale_ tier customers as an add-on. To request
   * access to this endpoint, please contact your Finch account manager.
   */
  create(body: AutomatedCreateParams, options?: RequestOptions): APIPromise<AutomatedCreateResponse> {
    return this._client.post('/jobs/automated', { body, ...options, __security: { bearerAuth: true } });
  }

  /**
   * Get an automated job by `job_id`.
   */
  retrieve(jobID: string, options?: RequestOptions): APIPromise<AutomatedAsyncJob> {
    return this._client.get(path`/jobs/automated/${jobID}`, { ...options, __security: { bearerAuth: true } });
  }

  /**
   * Get all automated jobs. Automated jobs are completed by a machine. By default,
   * jobs are sorted in descending order by submission time. For scheduled jobs such
   * as data syncs, only the next scheduled job is shown.
   */
  list(
    query: AutomatedListParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<AutomatedListResponse> {
    return this._client.get('/jobs/automated', { query, ...options, __security: { bearerAuth: true } });
  }
}

export interface AutomatedAsyncJob {
  /**
   * The datetime the job completed.
   */
  completed_at: string | null;

  /**
   * The datetime when the job was created. for scheduled jobs, this will be the
   * initial connection time. For ad-hoc jobs, this will be the time the creation
   * request was received.
   */
  created_at: string;

  /**
   * The id of the job that has been created.
   */
  job_id: string;

  /**
   * The url that can be used to retrieve the job status
   */
  job_url: string;

  /**
   * The input parameters for the job.
   */
  params: AutomatedAsyncJob.Params | null;

  /**
   * The datetime a job is scheduled to be run. For scheduled jobs, this datetime can
   * be in the future if the job has not yet been enqueued. For ad-hoc jobs, this
   * field will be null.
   */
  scheduled_at: string | null;

  /**
   * The datetime a job entered into the job queue.
   */
  started_at: string | null;

  status: 'pending' | 'in_progress' | 'complete' | 'error' | 'reauth_error' | 'permissions_error';

  /**
   * The type of automated job
   */
  type: 'data_sync_all' | 'w4_form_employee_sync';
}

export namespace AutomatedAsyncJob {
  /**
   * The input parameters for the job.
   */
  export interface Params {
    /**
     * The ID of the individual that the job was completed for.
     */
    individual_id?: string;
  }
}

export interface AutomatedCreateResponse {
  /**
   * The number of allowed refreshes per hour (per hour, fixed window)
   */
  allowed_refreshes: number;

  /**
   * The number of remaining refreshes available (per hour, fixed window)
   */
  remaining_refreshes: number;

  /**
   * The id of the job that has been created.
   */
  job_id?: string;

  /**
   * The url that can be used to retrieve the job status
   */
  job_url?: string;

  /**
   * ISO 8601 timestamp indicating when to retry the request
   */
  retry_at?: string;
}

export interface AutomatedListResponse {
  data: Array<AutomatedAsyncJob>;

  meta: AutomatedListResponse.Meta;
}

export namespace AutomatedListResponse {
  export interface Meta {
    /**
     * Information about remaining quotas for this connection. Only applicable for
     * customers opted in to use Finch's Data Sync Refresh endpoint
     * (`POST /jobs/automated`). Please contact a Finch representative for more
     * details.
     */
    quotas?: Meta.Quotas;
  }

  export namespace Meta {
    /**
     * Information about remaining quotas for this connection. Only applicable for
     * customers opted in to use Finch's Data Sync Refresh endpoint
     * (`POST /jobs/automated`). Please contact a Finch representative for more
     * details.
     */
    export interface Quotas {
      data_sync_all?: Quotas.DataSyncAll;
    }

    export namespace Quotas {
      export interface DataSyncAll {
        allowed_refreshes?: number;

        remaining_refreshes?: number;
      }
    }
  }
}

export type AutomatedCreateParams =
  | AutomatedCreateParams.DataSyncAll
  | AutomatedCreateParams.W4FormEmployeeSync;

export declare namespace AutomatedCreateParams {
  export interface DataSyncAll {
    /**
     * The type of job to start.
     */
    type: 'data_sync_all';
  }

  export interface W4FormEmployeeSync {
    params: W4FormEmployeeSync.Params;

    /**
     * The type of job to start.
     */
    type: 'w4_form_employee_sync';
  }

  export namespace W4FormEmployeeSync {
    export interface Params {
      /**
       * The unique ID of the individual for W-4 data sync.
       */
      individual_id: string;
    }
  }
}

export interface AutomatedListParams {
  /**
   * Number of items to return
   */
  limit?: number;

  /**
   * Index to start from (defaults to 0)
   */
  offset?: number;
}

export declare namespace Automated {
  export {
    type AutomatedAsyncJob as AutomatedAsyncJob,
    type AutomatedCreateResponse as AutomatedCreateResponse,
    type AutomatedListResponse as AutomatedListResponse,
    type AutomatedCreateParams as AutomatedCreateParams,
    type AutomatedListParams as AutomatedListParams,
  };
}