@tryfinch/finch-api 5.14.2 → 5.15.0

package/src/_shims/registry.ts

@@ -13,7 +13,7 @@ export interface Shims {
   Blob: any;
   File: any;
   ReadableStream: any;
-  getMultipartRequestOptions: <T extends {} = Record<string, unknown>>(
+  getMultipartRequestOptions: <T = Record<string, unknown>>(
     form: Shims['FormData'],
     opts: RequestOptions<T>,
   ) => Promise<RequestOptions<T>>;

package/src/_shims/web-runtime.ts

@@ -84,7 +84,7 @@ export function getRuntime({ manuallyImported }: { manuallyImported?: boolean }
           }
         }
       ),
-    getMultipartRequestOptions: async <T extends {} = Record<string, unknown>>(
+    getMultipartRequestOptions: async <T = Record<string, unknown>>(
       // @ts-ignore
       form: FormData,
       opts: RequestOptions<T>,

package/src/core.ts

@@ -208,27 +208,27 @@ export abstract class APIClient {
     return `stainless-node-retry-${uuid4()}`;
   }
 
-  get<Req extends {}, Rsp>(path: string, opts?: PromiseOrValue<RequestOptions<Req>>): APIPromise<Rsp> {
+  get<Req, Rsp>(path: string, opts?: PromiseOrValue<RequestOptions<Req>>): APIPromise<Rsp> {
     return this.methodRequest('get', path, opts);
   }
 
-  post<Req extends {}, Rsp>(path: string, opts?: PromiseOrValue<RequestOptions<Req>>): APIPromise<Rsp> {
+  post<Req, Rsp>(path: string, opts?: PromiseOrValue<RequestOptions<Req>>): APIPromise<Rsp> {
     return this.methodRequest('post', path, opts);
   }
 
-  patch<Req extends {}, Rsp>(path: string, opts?: PromiseOrValue<RequestOptions<Req>>): APIPromise<Rsp> {
+  patch<Req, Rsp>(path: string, opts?: PromiseOrValue<RequestOptions<Req>>): APIPromise<Rsp> {
     return this.methodRequest('patch', path, opts);
   }
 
-  put<Req extends {}, Rsp>(path: string, opts?: PromiseOrValue<RequestOptions<Req>>): APIPromise<Rsp> {
+  put<Req, Rsp>(path: string, opts?: PromiseOrValue<RequestOptions<Req>>): APIPromise<Rsp> {
     return this.methodRequest('put', path, opts);
   }
 
-  delete<Req extends {}, Rsp>(path: string, opts?: PromiseOrValue<RequestOptions<Req>>): APIPromise<Rsp> {
+  delete<Req, Rsp>(path: string, opts?: PromiseOrValue<RequestOptions<Req>>): APIPromise<Rsp> {
     return this.methodRequest('delete', path, opts);
   }
 
-  private methodRequest<Req extends {}, Rsp>(
+  private methodRequest<Req, Rsp>(
     method: HTTPMethod,
     path: string,
     opts?: PromiseOrValue<RequestOptions<Req>>,
@@ -260,9 +260,7 @@ export abstract class APIClient {
     return null;
   }
 
-  buildRequest<Req extends {}>(
-    options: FinalRequestOptions<Req>,
-  ): { req: RequestInit; url: string; timeout: number } {
+  buildRequest<Req>(options: FinalRequestOptions<Req>): { req: RequestInit; url: string; timeout: number } {
     const { method, path, query, headers: headers = {} } = options;
 
     const body =
@@ -292,18 +290,7 @@ export abstract class APIClient {
       headers[this.idempotencyHeader] = options.idempotencyKey;
     }
 
-    const reqHeaders: Record<string, string> = {
-      ...(contentLength && { 'Content-Length': contentLength }),
-      ...this.defaultHeaders(options),
-      ...headers,
-    };
-    // let builtin fetch set the Content-Type for multipart bodies
-    if (isMultipartBody(options.body) && shimsKind !== 'node') {
-      delete reqHeaders['Content-Type'];
-    }
-
-    // Strip any headers being explicitly omitted with null
-    Object.keys(reqHeaders).forEach((key) => reqHeaders[key] === null && delete reqHeaders[key]);
+    const reqHeaders = this.buildHeaders({ options, headers, contentLength });
 
     const req: RequestInit = {
       method,
@@ -315,9 +302,35 @@ export abstract class APIClient {
       signal: options.signal ?? null,
     };
 
+    return { req, url, timeout };
+  }
+
+  private buildHeaders({
+    options,
+    headers,
+    contentLength,
+  }: {
+    options: FinalRequestOptions;
+    headers: Record<string, string | null | undefined>;
+    contentLength: string | null | undefined;
+  }): Record<string, string> {
+    const reqHeaders: Record<string, string> = {};
+    if (contentLength) {
+      reqHeaders['content-length'] = contentLength;
+    }
+
+    const defaultHeaders = this.defaultHeaders(options);
+    applyHeadersMut(reqHeaders, defaultHeaders);
+    applyHeadersMut(reqHeaders, headers);
+
+    // let builtin fetch set the Content-Type for multipart bodies
+    if (isMultipartBody(options.body) && shimsKind !== 'node') {
+      delete reqHeaders['content-type'];
+    }
+
     this.validateHeaders(reqHeaders, headers);
 
-    return { req, url, timeout };
+    return reqHeaders;
   }
 
   /**
@@ -349,15 +362,15 @@ export abstract class APIClient {
     return APIError.generate(status, error, message, headers);
   }
 
-  request<Req extends {}, Rsp>(
+  request<Req, Rsp>(
     options: PromiseOrValue<FinalRequestOptions<Req>>,
     remainingRetries: number | null = null,
   ): APIPromise<Rsp> {
     return new APIPromise(this.makeRequest(options, remainingRetries));
   }
 
-  private async makeRequest(
-    optionsInput: PromiseOrValue<FinalRequestOptions>,
+  private async makeRequest<Req>(
+    optionsInput: PromiseOrValue<FinalRequestOptions<Req>>,
     retriesRemaining: number | null,
   ): Promise<APIResponseProps> {
     const options = await optionsInput;
@@ -419,7 +432,7 @@ export abstract class APIClient {
     return new PagePromise<PageClass, Item>(this, request, Page);
   }
 
-  buildURL<Req extends Record<string, unknown>>(path: string, query: Req | null | undefined): string {
+  buildURL<Req>(path: string, query: Req | null | undefined): string {
     const url =
       isAbsoluteURL(path) ?
         new URL(path)
@@ -593,7 +606,7 @@ export abstract class AbstractPage<Item> implements AsyncIterable<Item> {
       );
     }
     const nextOptions = { ...this.options };
-    if ('params' in nextInfo) {
+    if ('params' in nextInfo && typeof nextOptions.query === 'object') {
       nextOptions.query = { ...nextOptions.query, ...nextInfo.params };
     } else if ('url' in nextInfo) {
       const params = [...Object.entries(nextOptions.query || {}), ...nextInfo.url.searchParams.entries()];
@@ -691,7 +704,7 @@ export type Headers = Record<string, string | null | undefined>;
 export type DefaultQuery = Record<string, string | undefined>;
 export type KeysEnum<T> = { [P in keyof Required<T>]: true };
 
-export type RequestOptions<Req extends {} = Record<string, unknown> | Readable> = {
+export type RequestOptions<Req = unknown | Record<string, unknown> | Readable> = {
   method?: HTTPMethod;
   path?: string;
   query?: Req | undefined;
@@ -728,7 +741,7 @@ const requestOptionsKeys: KeysEnum<RequestOptions> = {
   __binaryResponse: true,
 };
 
-export const isRequestOptions = (obj: unknown): obj is RequestOptions<Record<string, unknown> | Readable> => {
+export const isRequestOptions = (obj: unknown): obj is RequestOptions => {
   return (
     typeof obj === 'object' &&
     obj !== null &&
@@ -737,7 +750,7 @@ export const isRequestOptions = (obj: unknown): obj is RequestOptions<Record<str
   );
 };
 
-export type FinalRequestOptions<Req extends {} = Record<string, unknown> | Readable> = RequestOptions<Req> & {
+export type FinalRequestOptions<Req = unknown | Record<string, unknown> | Readable> = RequestOptions<Req> & {
   method: HTTPMethod;
   path: string;
 };
@@ -1004,6 +1017,28 @@ export function hasOwn(obj: Object, key: string): boolean {
   return Object.prototype.hasOwnProperty.call(obj, key);
 }
 
+/**
+ * Copies headers from "newHeaders" onto "targetHeaders",
+ * using lower-case for all properties,
+ * ignoring any keys with undefined values,
+ * and deleting any keys with null values.
+ */
+function applyHeadersMut(targetHeaders: Headers, newHeaders: Headers): void {
+  for (const k in newHeaders) {
+    if (!hasOwn(newHeaders, k)) continue;
+    const lowerKey = k.toLowerCase();
+    if (!lowerKey) continue;
+
+    const val = newHeaders[k];
+
+    if (val === null) {
+      delete targetHeaders[lowerKey];
+    } else if (val !== undefined) {
+      targetHeaders[lowerKey] = val;
+    }
+  }
+}
+
 export function debug(action: string, ...args: any[]) {
   if (typeof process !== 'undefined' && process.env['DEBUG'] === 'true') {
     console.log(`Finch:DEBUG:${action}`, ...args);

package/src/index.ts

@@ -138,12 +138,15 @@ export class Finch extends Core.APIClient {
     this.webhookSecret = webhookSecret;
   }
 
+  accessTokens: API.AccessTokens = new API.AccessTokens(this);
   hris: API.HRIS = new API.HRIS(this);
   providers: API.Providers = new API.Providers(this);
   account: API.Account = new API.Account(this);
   webhooks: API.Webhooks = new API.Webhooks(this);
   requestForwarding: API.RequestForwarding = new API.RequestForwarding(this);
   jobs: API.Jobs = new API.Jobs(this);
+  auth: API.Auth = new API.Auth(this);
+  sandbox: API.Sandbox = new API.Sandbox(this);
 
   /**
    * Returns an access token for the Finch API given an authorization code. An
@@ -196,6 +199,14 @@ export class Finch extends Core.APIClient {
     return url.toString();
   }
 
+  /**
+   * Returns a copy of the current Finch client with the given access token for
+   * authentication.
+   */
+  withAccessToken(accessToken: string): Finch {
+    return new Finch({ ...this._options, accessToken });
+  }
+
   protected override defaultQuery(): Core.DefaultQuery | undefined {
     return this._options.defaultQuery;
   }
@@ -209,10 +220,10 @@ export class Finch extends Core.APIClient {
   }
 
   protected override validateHeaders(headers: Core.Headers, customHeaders: Core.Headers) {
-    if (this.accessToken && headers['Authorization']) {
+    if (this.accessToken && headers['authorization']) {
       return;
     }
-    if (customHeaders['Authorization'] === null) {
+    if (customHeaders['authorization'] === null) {
       return;
     }
 
@@ -285,6 +296,10 @@ export namespace Finch {
   export import PageParams = Pagination.PageParams;
   export import PageResponse = Pagination.PageResponse;
 
+  export import AccessTokens = API.AccessTokens;
+  export import CreateAccessTokenResponse = API.CreateAccessTokenResponse;
+  export import AccessTokenCreateParams = API.AccessTokenCreateParams;
+
   export import HRIS = API.HRIS;
   export import Income = API.Income;
   export import Location = API.Location;
@@ -306,6 +321,12 @@ export namespace Finch {
 
   export import Jobs = API.Jobs;
 
+  export import Auth = API.Auth;
+  export import AuthCreateTokenParams = API.AuthCreateTokenParams;
+
+  export import Sandbox = API.Sandbox;
+
+  export import IntrospectResponseConnectionStatus = API.IntrospectResponseConnectionStatus;
   export import OperationSupport = API.OperationSupport;
   export import OperationSupportMatrix = API.OperationSupportMatrix;
   export import Paging = API.Paging;

package/src/lib/.keep

@@ -0,0 +1,4 @@
+File generated from our OpenAPI spec by Stainless.
+
+This directory can be used to store custom files to expand the SDK.
+It is ignored by Stainless code generation and its content (other than this keep file) won't be touched.

package/src/resources/access-tokens.ts

@@ -0,0 +1,36 @@
+// File generated from our OpenAPI spec by Stainless.
+
+import * as Core from "../core";
+import { APIResource } from "../resource";
+import * as AccessTokensAPI from "./access-tokens";
+
+export class AccessTokens extends APIResource {
+  /**
+   * Exchange the authorization code for an access token
+   */
+  create(
+    body: AccessTokenCreateParams,
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<CreateAccessTokenResponse> {
+    return this._client.post('/auth/token', { body, ...options });
+  }
+}
+
+export interface CreateAccessTokenResponse {
+  access_token: string;
+}
+
+export interface AccessTokenCreateParams {
+  client_id: string;
+
+  client_secret: string;
+
+  code: string;
+
+  redirect_uri: string;
+}
+
+export namespace AccessTokens {
+  export import CreateAccessTokenResponse = AccessTokensAPI.CreateAccessTokenResponse;
+  export import AccessTokenCreateParams = AccessTokensAPI.AccessTokenCreateParams;
+}

package/src/resources/account.ts

@@ -3,6 +3,7 @@
 import * as Core from "../core";
 import { APIResource } from "../resource";
 import * as AccountAPI from "./account";
+import * as Shared from "./shared";
 
 export class Account extends APIResource {
   /**
@@ -35,6 +36,8 @@ export interface Introspection {
    */
   account_id: string;
 
+  authentication_methods: Introspection.AuthenticationMethods;
+
   /**
    * The client id of the application associated with the `access_token`.
    */
@@ -82,6 +85,22 @@ export interface Introspection {
   username: string;
 }
 
+export namespace Introspection {
+  export interface AuthenticationMethods {
+    connection_status?: AuthenticationMethods.ConnectionStatus;
+
+    type?: string;
+  }
+
+  export namespace AuthenticationMethods {
+    export interface ConnectionStatus {
+      message?: string;
+
+      status?: Shared.IntrospectResponseConnectionStatus;
+    }
+  }
+}
+
 export namespace Account {
   export import DisconnectResponse = AccountAPI.DisconnectResponse;
   export import Introspection = AccountAPI.Introspection;

package/src/resources/auth.ts

@@ -0,0 +1,32 @@
+// File generated from our OpenAPI spec by Stainless.
+
+import * as Core from "../core";
+import { APIResource } from "../resource";
+import * as AuthAPI from "./auth";
+import * as AccessTokensAPI from "./access-tokens";
+
+export class Auth extends APIResource {
+  /**
+   * Exchange the authorization code for an access token
+   */
+  createToken(
+    body: AuthCreateTokenParams,
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<AccessTokensAPI.CreateAccessTokenResponse> {
+    return this._client.post('/auth/token', { body, ...options });
+  }
+}
+
+export interface AuthCreateTokenParams {
+  client_id: string;
+
+  client_secret: string;
+
+  code: string;
+
+  redirect_uri: string;
+}
+
+export namespace Auth {
+  export import AuthCreateTokenParams = AuthAPI.AuthCreateTokenParams;
+}

package/src/resources/index.ts

@@ -1,6 +1,8 @@
 // File generated from our OpenAPI spec by Stainless.
 
 export * from './shared';
+export { AuthCreateTokenParams, Auth } from './auth';
+export { CreateAccessTokenResponse, AccessTokenCreateParams, AccessTokens } from './access-tokens';
 export { DisconnectResponse, Introspection, Account } from './account';
 export { Income, Location, Money, HRIS } from './hris/hris';
 export { Jobs } from './jobs/jobs';
@@ -10,4 +12,5 @@ export {
   RequestForwardingForwardParams,
   RequestForwarding,
 } from './request-forwarding';
+export { Sandbox } from './sandbox/sandbox';
 export { Webhooks } from './webhooks';

package/src/resources/sandbox/company.ts

@@ -0,0 +1,252 @@
+// File generated from our OpenAPI spec by Stainless.
+
+import * as Core from "../../core";
+import { APIResource } from "../../resource";
+import * as CompanyAPI from "./company";
+import * as HRISAPI from "../hris/hris";
+
+export class Company extends APIResource {
+  /**
+   * Update a sandbox company's data
+   */
+  update(body: CompanyUpdateParams, options?: Core.RequestOptions): Core.APIPromise<CompanyUpdateResponse> {
+    return this._client.put('/sandbox/company', { body, ...options });
+  }
+}
+
+export interface CompanyUpdateResponse {
+  /**
+   * An array of bank account objects associated with the payroll/HRIS system.
+   */
+  accounts: Array<CompanyUpdateResponse.Account> | null;
+
+  /**
+   * The array of company departments.
+   */
+  departments: Array<CompanyUpdateResponse.Department | null> | null;
+
+  /**
+   * The employer identification number.
+   */
+  ein: string | null;
+
+  /**
+   * The entity type object.
+   */
+  entity: CompanyUpdateResponse.Entity | null;
+
+  /**
+   * The legal name of the company.
+   */
+  legal_name: string | null;
+
+  locations: Array<HRISAPI.Location | null> | null;
+
+  /**
+   * The email of the main administrator on the account.
+   */
+  primary_email: string | null;
+
+  /**
+   * The phone number of the main administrator on the account. Format: `XXXXXXXXXX`
+   */
+  primary_phone_number: string | null;
+}
+
+export namespace CompanyUpdateResponse {
+  export interface Account {
+    /**
+     * The name of the bank associated in the payroll/HRIS system.
+     */
+    account_name?: string | null;
+
+    /**
+     * 10-12 digit number to specify the bank account
+     */
+    account_number?: string | null;
+
+    /**
+     * The type of bank account.
+     */
+    account_type?: 'checking' | 'savings' | null;
+
+    /**
+     * Name of the banking institution.
+     */
+    institution_name?: string | null;
+
+    /**
+     * A nine-digit code that's based on the U.S. Bank location where your account was
+     * opened.
+     */
+    routing_number?: string | null;
+  }
+
+  export interface Department {
+    /**
+     * The department name.
+     */
+    name?: string | null;
+
+    /**
+     * The parent department, if present.
+     */
+    parent?: Department.Parent | null;
+  }
+
+  export namespace Department {
+    /**
+     * The parent department, if present.
+     */
+    export interface Parent {
+      /**
+       * The parent department's name.
+       */
+      name?: string | null;
+    }
+  }
+
+  /**
+   * The entity type object.
+   */
+  export interface Entity {
+    /**
+     * The tax payer subtype of the company.
+     */
+    subtype?: 's_corporation' | 'c_corporation' | 'b_corporation' | null;
+
+    /**
+     * The tax payer type of the company.
+     */
+    type?:
+      | 'llc'
+      | 'lp'
+      | 'corporation'
+      | 'sole_proprietor'
+      | 'non_profit'
+      | 'partnership'
+      | 'cooperative'
+      | null;
+  }
+}
+
+export interface CompanyUpdateParams {
+  /**
+   * An array of bank account objects associated with the payroll/HRIS system.
+   */
+  accounts: Array<CompanyUpdateParams.Account> | null;
+
+  /**
+   * The array of company departments.
+   */
+  departments: Array<CompanyUpdateParams.Department | null> | null;
+
+  /**
+   * The employer identification number.
+   */
+  ein: string | null;
+
+  /**
+   * The entity type object.
+   */
+  entity: CompanyUpdateParams.Entity | null;
+
+  /**
+   * The legal name of the company.
+   */
+  legal_name: string | null;
+
+  locations: Array<HRISAPI.Location | null> | null;
+
+  /**
+   * The email of the main administrator on the account.
+   */
+  primary_email: string | null;
+
+  /**
+   * The phone number of the main administrator on the account. Format: `XXXXXXXXXX`
+   */
+  primary_phone_number: string | null;
+}
+
+export namespace CompanyUpdateParams {
+  export interface Account {
+    /**
+     * The name of the bank associated in the payroll/HRIS system.
+     */
+    account_name?: string | null;
+
+    /**
+     * 10-12 digit number to specify the bank account
+     */
+    account_number?: string | null;
+
+    /**
+     * The type of bank account.
+     */
+    account_type?: 'checking' | 'savings' | null;
+
+    /**
+     * Name of the banking institution.
+     */
+    institution_name?: string | null;
+
+    /**
+     * A nine-digit code that's based on the U.S. Bank location where your account was
+     * opened.
+     */
+    routing_number?: string | null;
+  }
+
+  export interface Department {
+    /**
+     * The department name.
+     */
+    name?: string | null;
+
+    /**
+     * The parent department, if present.
+     */
+    parent?: Department.Parent | null;
+  }
+
+  export namespace Department {
+    /**
+     * The parent department, if present.
+     */
+    export interface Parent {
+      /**
+       * The parent department's name.
+       */
+      name?: string | null;
+    }
+  }
+
+  /**
+   * The entity type object.
+   */
+  export interface Entity {
+    /**
+     * The tax payer subtype of the company.
+     */
+    subtype?: 's_corporation' | 'c_corporation' | 'b_corporation' | null;
+
+    /**
+     * The tax payer type of the company.
+     */
+    type?:
+      | 'llc'
+      | 'lp'
+      | 'corporation'
+      | 'sole_proprietor'
+      | 'non_profit'
+      | 'partnership'
+      | 'cooperative'
+      | null;
+  }
+}
+
+export namespace Company {
+  export import CompanyUpdateResponse = CompanyAPI.CompanyUpdateResponse;
+  export import CompanyUpdateParams = CompanyAPI.CompanyUpdateParams;
+}