@tryfinch/finch-api 5.2.0 → 5.4.0

package/src/core.ts

@@ -1,5 +1,11 @@
 import { VERSION } from './version';
-import { APIError, APIConnectionError, APIConnectionTimeoutError, APIUserAbortError } from './error';
+import {
+  FinchError,
+  APIError,
+  APIConnectionError,
+  APIConnectionTimeoutError,
+  APIUserAbortError,
+} from './error';
 import {
   kind as shimsKind,
   type Readable,
@@ -433,7 +439,7 @@ export abstract class APIClient {
         if (value === null) {
           return `${encodeURIComponent(key)}=`;
         }
-        throw new Error(
+        throw new FinchError(
           `Cannot stringify type ${typeof value}; Expected string, number, boolean, or null. If you need to pass nested query parameters, you can manually encode them, e.g. { query: { 'foo[key1]': value1, 'foo[key2]': value2 } }, and please open a GitHub issue requesting better support for your use case.`,
         );
       })
@@ -496,32 +502,37 @@ export abstract class APIClient {
     retriesRemaining -= 1;
 
     // About the Retry-After header: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After
-    //
-    // TODO: we may want to handle the case where the header is using the http-date syntax: "Retry-After: <http-date>".
-    // See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After#syntax for details.
-    const retryAfter = parseInt(responseHeaders?.['retry-after'] || '');
+    let timeoutMillis: number | undefined;
+    const retryAfterHeader = responseHeaders?.['retry-after'];
+    if (retryAfterHeader) {
+      const timeoutSeconds = parseInt(retryAfterHeader);
+      if (!Number.isNaN(timeoutSeconds)) {
+        timeoutMillis = timeoutSeconds * 1000;
+      } else {
+        timeoutMillis = Date.parse(retryAfterHeader) - Date.now();
+      }
+    }
 
-    const maxRetries = options.maxRetries ?? this.maxRetries;
-    const timeout = this.calculateRetryTimeoutSeconds(retriesRemaining, retryAfter, maxRetries) * 1000;
-    await sleep(timeout);
+    // If the API asks us to wait a certain amount of time (and it's a reasonable amount),
+    // just do what it says, but otherwise calculate a default
+    if (
+      !timeoutMillis ||
+      !Number.isInteger(timeoutMillis) ||
+      timeoutMillis <= 0 ||
+      timeoutMillis > 60 * 1000
+    ) {
+      const maxRetries = options.maxRetries ?? this.maxRetries;
+      timeoutMillis = this.calculateDefaultRetryTimeoutMillis(retriesRemaining, maxRetries);
+    }
+    await sleep(timeoutMillis);
 
     return this.makeRequest(options, retriesRemaining);
   }
 
-  private calculateRetryTimeoutSeconds(
-    retriesRemaining: number,
-    retryAfter: number,
-    maxRetries: number,
-  ): number {
+  private calculateDefaultRetryTimeoutMillis(retriesRemaining: number, maxRetries: number): number {
     const initialRetryDelay = 0.5;
     const maxRetryDelay = 2;
 
-    // If the API asks us to wait a certain amount of time (and it's a reasonable amount),
-    // just do what it says.
-    if (Number.isInteger(retryAfter) && retryAfter <= 60) {
-      return retryAfter;
-    }
-
     const numRetries = maxRetries - retriesRemaining;
 
     // Apply exponential backoff, but not more than the max.
@@ -530,7 +541,7 @@ export abstract class APIClient {
     // Apply some jitter, plus-or-minus half a second.
     const jitter = Math.random() - 0.5;
 
-    return sleepSeconds + jitter;
+    return (sleepSeconds + jitter) * 1000;
   }
 
   private getUserAgent(): string {
@@ -592,7 +603,7 @@ export abstract class AbstractPage<Item> implements AsyncIterable<Item> {
   async getNextPage(): Promise<this> {
     const nextInfo = this.nextPageInfo();
     if (!nextInfo) {
-      throw new Error(
+      throw new FinchError(
         'No next page expected; please check `.hasNextPage()` before calling `.getNextPage()`.',
       );
     }
@@ -918,10 +929,10 @@ export const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve
 
 const validatePositiveInteger = (name: string, n: unknown): number => {
   if (typeof n !== 'number' || !Number.isInteger(n)) {
-    throw new Error(`${name} must be an integer`);
+    throw new FinchError(`${name} must be an integer`);
   }
   if (n < 0) {
-    throw new Error(`${name} must be a positive integer`);
+    throw new FinchError(`${name} must be a positive integer`);
   }
   return n;
 };
@@ -932,7 +943,7 @@ export const castToError = (err: any): Error => {
 };
 
 export const ensurePresent = <T>(value: T | null | undefined): T => {
-  if (value == null) throw new Error(`Expected a value to be given but received ${value} instead.`);
+  if (value == null) throw new FinchError(`Expected a value to be given but received ${value} instead.`);
   return value;
 };
 
@@ -955,14 +966,14 @@ export const coerceInteger = (value: unknown): number => {
   if (typeof value === 'number') return Math.round(value);
   if (typeof value === 'string') return parseInt(value, 10);
 
-  throw new Error(`Could not coerce ${value} (type: ${typeof value}) into a number`);
+  throw new FinchError(`Could not coerce ${value} (type: ${typeof value}) into a number`);
 };
 
 export const coerceFloat = (value: unknown): number => {
   if (typeof value === 'number') return value;
   if (typeof value === 'string') return parseFloat(value);
 
-  throw new Error(`Could not coerce ${value} (type: ${typeof value}) into a number`);
+  throw new FinchError(`Could not coerce ${value} (type: ${typeof value}) into a number`);
 };
 
 export const coerceBoolean = (value: unknown): boolean => {
@@ -1066,5 +1077,5 @@ export const toBase64 = (str: string | null | undefined): string => {
     return btoa(str);
   }
 
-  throw new Error('Cannot generate b64 string; Expected `Buffer` or `btoa` to be defined');
+  throw new FinchError('Cannot generate b64 string; Expected `Buffer` or `btoa` to be defined');
 };

package/src/error.ts

@@ -2,7 +2,9 @@
 
 import { castToError, Headers } from './core';
 
-export class APIError extends Error {
+export class FinchError extends Error {}
+
+export class APIError extends FinchError {
   readonly status: number | undefined;
   readonly headers: Headers | undefined;
   readonly error: Object | undefined;

package/src/index.ts

@@ -133,6 +133,7 @@ export class Finch extends Core.APIClient {
   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);
 
   /**
    * Returns an access token for the Finch API given an authorization code. An
@@ -220,6 +221,7 @@ export class Finch extends Core.APIClient {
 
   static Finch = this;
 
+  static FinchError = Errors.FinchError;
   static APIError = Errors.APIError;
   static APIConnectionError = Errors.APIConnectionError;
   static APIConnectionTimeoutError = Errors.APIConnectionTimeoutError;
@@ -235,6 +237,7 @@ export class Finch extends Core.APIClient {
 }
 
 export const {
+  FinchError,
   APIError,
   APIConnectionError,
   APIConnectionTimeoutError,
@@ -284,6 +287,10 @@ export namespace Finch {
   export import Introspection = API.Introspection;
 
   export import Webhooks = API.Webhooks;
+
+  export import RequestForwarding = API.RequestForwarding;
+  export import RequestForwardingForwardResponse = API.RequestForwardingForwardResponse;
+  export import RequestForwardingForwardParams = API.RequestForwardingForwardParams;
 }
 
 export default Finch;

package/src/resources/hris/employments.ts

@@ -98,6 +98,11 @@ export interface EmploymentData {
    */
   pay_group_ids?: Array<string> | null;
 
+  /**
+   * The source system's unique employment identifier for this individual
+   */
+  source_id?: string | null;
+
   start_date?: string | null;
 
   /**

package/src/resources/hris/hris.ts

@@ -98,7 +98,7 @@ export interface Money {
   /**
    * Amount for money object (in cents)
    */
-  amount?: number;
+  amount?: number | null;
 
   currency?: string;
 }

package/src/resources/index.ts

@@ -1,7 +1,11 @@
 // File generated from our OpenAPI spec by Stainless.
 
-export {} from './top-level';
 export { DisconnectResponse, Introspection, Account } from './account';
 export { Income, Location, Money, Paging, HRIS } from './hris/hris';
 export { Provider, ProvidersSinglePage, Providers } from './providers';
+export {
+  RequestForwardingForwardResponse,
+  RequestForwardingForwardParams,
+  RequestForwarding,
+} from './request-forwarding';
 export { Webhooks } from './webhooks';

package/src/resources/request-forwarding.ts

@@ -0,0 +1,121 @@
+// File generated from our OpenAPI spec by Stainless.
+
+import * as Core from "../ch/finch-api/core";
+import { APIResource } from "../ch/finch-api/resource";
+import * as API from './index';
+
+export class RequestForwarding extends APIResource {
+  /**
+   * The Forward API allows you to make direct requests to an employment system.
+   */
+  forward(
+    body: RequestForwardingForwardParams,
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<RequestForwardingForwardResponse> {
+    return this.post('/forward', { body, ...options });
+  }
+}
+
+export interface RequestForwardingForwardResponse {
+  /**
+   * A string representation of the HTTP response body of the forwarded request’s
+   * response received from the underlying integration’s API. This field may be null
+   * in the case where the upstream system’s response is empty.
+   */
+  data: string | null;
+
+  /**
+   * The HTTP headers of the forwarded request’s response, exactly as received from
+   * the underlying integration’s API.
+   */
+  headers: unknown | null;
+
+  /**
+   * An object containing details of your original forwarded request, for your ease
+   * of reference.
+   */
+  request: RequestForwardingForwardResponse.Request;
+
+  /**
+   * The HTTP status code of the forwarded request’s response, exactly received from
+   * the underlying integration’s API. This value will be returned as an integer.
+   */
+  statusCode: number;
+}
+
+export namespace RequestForwardingForwardResponse {
+  /**
+   * An object containing details of your original forwarded request, for your ease
+   * of reference.
+   */
+  export interface Request {
+    /**
+     * The body that was specified for the forwarded request. If a value was not
+     * specified in the original request, this value will be returned as null ;
+     * otherwise, this value will always be returned as a string.
+     */
+    data: string | null;
+
+    /**
+     * The specified HTTP headers that were included in the forwarded request. If no
+     * headers were specified, this will be returned as `null`.
+     */
+    headers: unknown | null;
+
+    /**
+     * The HTTP method that was specified for the forwarded request. Valid values
+     * include: `GET`, `POST`, `PUT` , `DELETE`, and `PATCH`.
+     */
+    method: string;
+
+    /**
+     * The query parameters that were included in the forwarded request. If no query
+     * parameters were specified, this will be returned as `null`.
+     */
+    params: unknown | null;
+
+    /**
+     * The URL route path that was specified for the forwarded request.
+     */
+    route: string;
+  }
+}
+
+export interface RequestForwardingForwardParams {
+  /**
+   * The HTTP method for the forwarded request. Valid values include: `GET`, `POST`,
+   * `PUT`, `DELETE`, and `PATCH`.
+   */
+  method: string;
+
+  /**
+   * The URL route path for the forwarded request. This value must begin with a
+   * forward-slash ( / ) and may only contain alphanumeric characters, hyphens, and
+   * underscores.
+   */
+  route: string;
+
+  /**
+   * The body for the forwarded request. This value must be specified as either a
+   * string or a valid JSON object.
+   */
+  data?: string | null;
+
+  /**
+   * The HTTP headers to include on the forwarded request. This value must be
+   * specified as an object of key-value pairs. Example:
+   * `{"Content-Type": "application/xml", "X-API-Version": "v1" }`
+   */
+  headers?: unknown | null;
+
+  /**
+   * The query parameters for the forwarded request. This value must be specified as
+   * a valid JSON object rather than a query string.
+   */
+  params?: unknown | null;
+}
+
+export namespace RequestForwarding {
+  export import RequestForwardingForwardResponse = API.RequestForwardingForwardResponse;
+  export import RequestForwardingForwardParams = API.RequestForwardingForwardParams;
+}

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '5.2.0'; // x-release-please-version
+export const VERSION = '5.4.0'; // x-release-please-version

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "5.2.0";
+export declare const VERSION = "5.4.0";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '5.2.0'; // x-release-please-version
+exports.VERSION = '5.4.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '5.2.0'; // x-release-please-version
+export const VERSION = '5.4.0'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map