modern-treasury 0.0.1 → 0.2.0

package/README.md

@@ -24,18 +24,17 @@ import ModernTreasury from 'modern-treasury';
 
 const modernTreasury = new ModernTreasury({
   apiKey: 'my api key', // defaults to process.env["MODERN_TREASURY_API_KEY"]
-  organizationId: 'my organization id',
+  organizationId: 'my-organization-ID',
 });
 
 async function main() {
-  const externalAccount = await modernTreasury.externalAccounts.create({
-    counterparty_id: '123',
-    name: 'my bank',
+  const counterparty = await modernTreasury.counterparties.create({
+    name: 'my first counterparty',
   });
 
-  console.log(externalAccount.id);
+  console.log(counterparty.id);
 }
-main();
+main().catch(console.error);
 ```
 
 ### Usage with TypeScript
@@ -48,17 +47,15 @@ import ModernTreasury from 'modern-treasury';
 
 const modernTreasury = new ModernTreasury({
   apiKey: 'my api key', // defaults to process.env["MODERN_TREASURY_API_KEY"]
-  organizationId: 'my organization id',
+  organizationId: 'my-organization-ID',
 });
 
 async function main() {
-  const params: ModernTreasury.ExternalAccountCreateParams = { counterparty_id: '123', name: 'my bank' };
+  const params: ModernTreasury.CounterpartyCreateParams = { name: 'my first counterparty' };
 
-  const externalAccount: ModernTreasury.ExternalAccount = await modernTreasury.externalAccounts.create(
-    params,
-  );
+  const counterparty: ModernTreasury.Counterparty = await modernTreasury.counterparties.create(params);
 }
-main();
+main().catch(console.error);
 ```
 
 Documentation for each method, request param, and response field are available in docstrings and will appear on hover in most modern editors.
@@ -82,7 +79,7 @@ async function main() {
       }
     });
 }
-main();
+main().catch(console.error);
 ```
 
 Error codes are as followed:
@@ -111,7 +108,7 @@ You can use the `maxRetries` option to configure or disable this:
 // Configure the default for all requests:
 const modernTreasury = new ModernTreasury({
   maxRetries: 0, // default is 2
-  organizationId: 'my organization id',
+  organizationId: 'my-organization-ID',
 });
 
 // Or, configure per-request:
@@ -129,7 +126,7 @@ Requests time out after 60 seconds by default. You can configure this with a `ti
 // Configure the default for all requests:
 const modernTreasury = new ModernTreasury({
   timeout: 20 * 1000, // 20 seconds (default is 60s)
-  organizationId: 'my organization id',
+  organizationId: 'my-organization-ID',
 });
 
 // Override per-request:
@@ -172,7 +169,7 @@ import HttpsProxyAgent from 'https-proxy-agent';
 // Configure the default for all requests:
 const modernTreasury = new ModernTreasury({
   httpAgent: new HttpsProxyAgent(process.env.PROXY_URL),
-  organizationId: 'my organization id',
+  organizationId: 'my-organization-ID',
 });
 
 // Override per-request:
@@ -188,7 +185,7 @@ This package is in beta. Its internals and interfaces are not stable
 and subject to change without a major semver bump;
 please reach out if you rely on any undocumented behavior.
 
-We are keen for your feedback; please email us at [dev-feedback@moderntreasury.com](mailto:dev-feedback@moderntreasury.com)
+We are keen for your feedback; please email us at [sdk-feedback@moderntreasury.com](mailto:sdk-feedback@moderntreasury.com)
 or open an issue with questions, bugs, or suggestions.
 
 ## Requirements

package/build

@@ -3,6 +3,8 @@ set -euo pipefail
 
 rm -rf dist/*
 
+yarn tsn check-version.ts
+
 tsc -p tsconfig.cjs.json
 
 tsc-alias -p tsconfig.cjs.json

package/check-version.ts

@@ -0,0 +1,22 @@
+import fs from 'fs';
+import { VERSION } from './version';
+
+const main = () => {
+  const pkg = JSON.parse(fs.readFileSync('package.json').toString()) as Record<string, unknown>;
+  const version = pkg['version'];
+  if (!version) throw 'The version property is not set in the package.json file';
+  if (typeof version !== 'string') {
+    throw `Unexpected type for the package.json version field; got ${typeof version}, expected string`;
+  }
+  if (version !== VERSION) {
+    throw (
+      `Version mismatch; package.json = ${version}, version.ts = ${VERSION}; ` +
+      `Please update the package.json version property or modify the VERSION variable in version.ts to ensure they match`
+    );
+  }
+  console.log(`Versions ${version} (package.json) and ${VERSION} (version.ts) match`);
+};
+
+if (require.main === module) {
+  main();
+}

package/core.ts

@@ -1,5 +1,4 @@
 import qs from 'qs';
-import pkgUp from 'pkg-up';
 
 import type { Agent } from 'http';
 import type NodeFetch from 'node-fetch';
@@ -8,9 +7,10 @@ import type KeepAliveAgent from 'agentkeepalive';
 import { AbortController } from 'abort-controller';
 import { FormData, File, Blob } from 'formdata-node';
 import { FormDataEncoder } from 'form-data-encoder';
-
 import { Readable } from 'stream';
 
+import { VERSION } from './version';
+
 const isNode = typeof process !== 'undefined';
 let nodeFetch: typeof NodeFetch | undefined = undefined;
 let getDefaultAgent = (_url: string): Agent | undefined => undefined;
@@ -29,6 +29,8 @@ if (isNode) {
 const DEFAULT_MAX_RETRIES = 2;
 const DEFAULT_TIMEOUT = 60 * 1000; // 60s
 
+type Fetch = (url: RequestInfo, init?: RequestInit) => Promise<Response>;
+
 export abstract class APIClient {
   apiKey: string | null;
   baseURL: string;
@@ -36,7 +38,7 @@ export abstract class APIClient {
   timeout: number;
   httpAgent: Agent | undefined;
 
-  private fetch: typeof NodeFetch;
+  private fetch: Fetch;
   protected idempotencyHeader?: string;
 
   constructor({
@@ -68,7 +70,7 @@ export abstract class APIClient {
         );
       }
       // For now, we just pretend that Fetch is the same type as NodeFetch.
-      this.fetch = fetch as unknown as typeof NodeFetch;
+      this.fetch = fetch as unknown as Fetch;
     }
   }
 
@@ -89,7 +91,7 @@ export abstract class APIClient {
       Accept: 'application/json',
       'Content-Type': 'application/json',
       'User-Agent': this.getUserAgent(),
-      'X-Stainless-Client-User-Agent': getPlatformPropertiesJSON(),
+      ...getPlatformHeaders(),
       ...this.authHeaders(),
     };
   }
@@ -241,9 +243,15 @@ export abstract class APIClient {
 
     const timeout = setTimeout(() => controller.abort(), ms);
 
-    return this.fetch(url, { signal: controller.signal as any, ...options }).finally(() => {
-      clearTimeout(timeout);
-    });
+    return this.getRequestClient()
+      .fetch(url, { signal: controller.signal as any, ...options })
+      .finally(() => {
+        clearTimeout(timeout);
+      });
+  }
+
+  protected getRequestClient(): RequestClient {
+    return { fetch: this.fetch };
   }
 
   private shouldRetry(response: Response): boolean {
@@ -312,8 +320,7 @@ export abstract class APIClient {
   }
 
   private getUserAgent(): string {
-    const packageVersion = getPackageVersion();
-    return `${this.constructor.name}/JS ${packageVersion}`;
+    return `${this.constructor.name}/JS ${VERSION}`;
   }
 
   private debug(action: string, ...args: any[]) {
@@ -438,7 +445,7 @@ export class PagePromise<
 }
 
 export const createResponseHeaders = (
-  headers: Awaited<ReturnType<typeof NodeFetch>>['headers'],
+  headers: Awaited<ReturnType<Fetch>>['headers'],
 ): Record<string, string> => {
   return new Proxy(Object.fromEntries(headers.entries()), {
     get(target, name) {
@@ -450,6 +457,7 @@ export const createResponseHeaders = (
 
 type HTTPMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
 
+export type RequestClient = { fetch: Fetch };
 export type Headers = Record<string, string | null | undefined>;
 export type KeysEnum<T> = { [P in keyof Required<T>]: true };
 
@@ -577,53 +585,98 @@ export class APIConnectionTimeoutError extends APIConnectionError {
   }
 }
 
-let _packageVersion: string;
-const getPackageVersion = (): string => {
-  try {
-    // eslint-disable-next-line @typescript-eslint/no-var-requires
-    return (_packageVersion ??= require(pkgUp.sync()!).version);
-  } catch (e) {
-    console.debug(`Ignoring error while determing package version ${e}`);
-    return (_packageVersion = 'unknown');
-  }
-};
-
 declare const Deno: any;
+type Arch = 'x32' | 'x64' | 'arm' | 'arm64' | `other:${string}` | 'unknown';
+type PlatformName =
+  | 'MacOS'
+  | 'Linux'
+  | 'Windows'
+  | 'FreeBSD'
+  | 'OpenBSD'
+  | 'iOS'
+  | 'Android'
+  | `Other:${string}`
+  | 'Unknown';
 type PlatformProperties = {
-  lang: 'js';
-  packageVersion: string;
-  os: string;
-  arch: string;
-  runtime: 'node' | 'deno';
-  runtimeVersion: string;
+  'X-Stainless-Lang': 'js';
+  'X-Stainless-Package-Version': string;
+  'X-Stainless-OS': PlatformName;
+  'X-Stainless-Arch': Arch;
+  'X-Stainless-Runtime': 'node' | 'deno' | 'unknown';
+  'X-Stainless-Runtime-Version': string;
 };
-const getPlatformProperties = (): PlatformProperties | void => {
+const getPlatformProperties = (): PlatformProperties => {
   if (typeof process !== 'undefined') {
     return {
-      lang: 'js',
-      packageVersion: getPackageVersion(),
-      os: process.platform,
-      arch: process.arch,
-      runtime: 'node',
-      runtimeVersion: process.version,
+      'X-Stainless-Lang': 'js',
+      'X-Stainless-Package-Version': VERSION,
+      'X-Stainless-OS': normalizePlatform(process.platform),
+      'X-Stainless-Arch': normalizeArch(process.arch),
+      'X-Stainless-Runtime': 'node',
+      'X-Stainless-Runtime-Version': process.version,
     };
   }
   if (typeof Deno !== 'undefined') {
     return {
-      lang: 'js',
-      packageVersion: getPackageVersion(),
-      os: Deno.build.os,
-      arch: Deno.build.arch,
-      runtime: 'deno',
-      runtimeVersion: Deno.version,
+      'X-Stainless-Lang': 'js',
+      'X-Stainless-Package-Version': VERSION,
+      'X-Stainless-OS': normalizePlatform(Deno.build.os),
+      'X-Stainless-Arch': normalizeArch(Deno.build.arch),
+      'X-Stainless-Runtime': 'deno',
+      'X-Stainless-Runtime-Version': Deno.version,
     };
   }
   // TODO add support for Cloudflare workers, browsers, etc.
+  return {
+    'X-Stainless-Lang': 'js',
+    'X-Stainless-Package-Version': VERSION,
+    'X-Stainless-OS': 'Unknown',
+    'X-Stainless-Arch': 'unknown',
+    'X-Stainless-Runtime': 'unknown',
+    'X-Stainless-Runtime-Version': 'unknown',
+  };
+};
+
+const normalizeArch = (arch: string): Arch => {
+  // Node docs:
+  // - https://nodejs.org/api/process.html#processarch
+  // Deno docs:
+  // - https://doc.deno.land/deno/stable/~/Deno.build
+  if (arch === 'x32') return 'x32';
+  if (arch === 'x86_64' || arch === 'x64') return 'x64';
+  if (arch === 'arm') return 'arm';
+  if (arch === 'aarch64' || arch === 'arm64') return 'arm64';
+  if (arch) return `other:${arch}`;
+  return 'unknown';
+};
+
+const normalizePlatform = (platform: string): PlatformName => {
+  // Node platforms:
+  // - https://nodejs.org/api/process.html#processplatform
+  // Deno platforms:
+  // - https://doc.deno.land/deno/stable/~/Deno.build
+  // - https://github.com/denoland/deno/issues/14799
+
+  platform = platform.toLowerCase();
+
+  // NOTE: this iOS check is untested and may not work
+  // Node does not work natively on IOS, there is a fork at
+  // https://github.com/nodejs-mobile/nodejs-mobile
+  // however it is unknown at the time of writing how to detect if it is running
+  if (platform.includes('ios')) return 'iOS';
+  if (platform === 'android') return 'Android';
+  if (platform === 'darwin') return 'MacOS';
+  if (platform === 'win32') return 'Windows';
+  if (platform === 'freebsd') return 'FreeBSD';
+  if (platform === 'openbsd') return 'OpenBSD';
+  if (platform === 'linux') return 'Linux';
+  if (platform) return `Other:${platform}`;
+  return 'Unknown';
 };
 
-let _platformPropertiesJSON: string;
-const getPlatformPropertiesJSON = () => {
-  return (_platformPropertiesJSON ??= JSON.stringify(getPlatformProperties())) || '';
+let _platformHeaders: PlatformProperties;
+const getPlatformHeaders = () => {
+  return (_platformHeaders ??= getPlatformProperties());
 };
 
 const safeJSON = (text: string) => {
@@ -657,35 +710,42 @@ const castToError = (err: any): Error => {
   return new Error(err);
 };
 
-const validateFormValue = (value: unknown): string | number | boolean | File | Blob => {
-  if (
-    typeof value === 'string' ||
-    typeof value === 'number' ||
-    typeof value === 'boolean' ||
-    value instanceof File ||
-    value instanceof Blob
-  ) {
-    return value;
-  }
+/**
+ * Returns a multipart/form-data request if any part of the given request body contains a File / Blob value.
+ * Otherwise returns the request as is.
+ */
+export const maybeMultipartFormRequestOptions = <T = Record<string, unknown>>(
+  opts: RequestOptions<T>,
+): RequestOptions<T | Readable> => {
+  // TODO: does this add unreasonable overhead in the case where we shouldn't use multipart/form-data?
+  const form = createForm(opts.body);
 
-  if (value == null) {
-    throw new TypeError(
-      `null is not a valid form data value, if you want to pass null then you need to use the string 'null'`,
-    );
+  for (const [_, entry] of form.entries()) {
+    const value = entry.valueOf();
+    if (value instanceof File || value instanceof Blob) {
+      return getMultipartRequestOptions(form, opts);
+    }
   }
 
-  throw new TypeError(
-    `Invalid value given to form, expected a string, number, boolean, File or Blob but got ${value} instead`,
-  );
+  return opts;
 };
 
 export const multipartFormRequestOptions = <T = Record<string, unknown>>(
   opts: RequestOptions<T>,
 ): RequestOptions<T | Readable> => {
+  return getMultipartRequestOptions(createForm(opts.body), opts);
+};
+
+const createForm = <T = Record<string, unknown>>(body: T | undefined): FormData => {
   const form = new FormData();
-  Object.entries(opts.body || {}).forEach(
-    ([key, value]) => value !== undefined && form.set(key, validateFormValue(value)),
-  );
+  Object.entries(body || {}).forEach(([key, value]) => addFormValue(form, key, value));
+  return form;
+};
+
+const getMultipartRequestOptions = <T = Record<string, unknown>>(
+  form: FormData,
+  opts: RequestOptions<T>,
+): RequestOptions<T | Readable> => {
   const encoder = new FormDataEncoder(form);
   return {
     ...opts,
@@ -694,6 +754,42 @@ export const multipartFormRequestOptions = <T = Record<string, unknown>>(
   };
 };
 
+const addFormValue = (form: FormData, key: string, value: unknown) => {
+  if (value == null) {
+    throw new TypeError(
+      `null is not a valid form data value, if you want to pass null then you need to use the string 'null'`,
+    );
+  }
+
+  // TODO: make nested formats configurable
+  if (
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    typeof value === 'boolean' ||
+    value instanceof File ||
+    value instanceof Blob
+  ) {
+    if (form.has(key)) {
+      throw new Error(
+        `Received multiple values for FormData with the same key: ${key}; This behaviour is not supported.`,
+      );
+    }
+    form.append(key, value);
+  } else if (Array.isArray(value)) {
+    value.forEach((entry) => {
+      addFormValue(form, key + '[]', entry);
+    });
+  } else if (typeof value === 'object') {
+    Object.entries(value).forEach(([name, prop]) => {
+      addFormValue(form, `${key}[${name}]`, prop);
+    });
+  } else {
+    throw new TypeError(
+      `Invalid value given to form, expected a string, number, boolean, object, Array, File or Blob but got ${value} instead`,
+    );
+  }
+};
+
 export const coerceInteger = (value: unknown): number => {
   if (typeof value === 'number') return Math.round(value);
   if (typeof value === 'string') return parseInt(value);

package/dist/cjs/check-version.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cjs/check-version.js

@@ -0,0 +1,28 @@
+'use strict';
+var __importDefault =
+  (this && this.__importDefault) ||
+  function (mod) {
+    return mod && mod.__esModule ? mod : { default: mod };
+  };
+Object.defineProperty(exports, '__esModule', { value: true });
+const fs_1 = __importDefault(require('fs'));
+const version_1 = require('./version');
+const main = () => {
+  const pkg = JSON.parse(fs_1.default.readFileSync('package.json').toString());
+  const version = pkg['version'];
+  if (!version) throw 'The version property is not set in the package.json file';
+  if (typeof version !== 'string') {
+    throw `Unexpected type for the package.json version field; got ${typeof version}, expected string`;
+  }
+  if (version !== version_1.VERSION) {
+    throw (
+      `Version mismatch; package.json = ${version}, version.ts = ${version_1.VERSION}; ` +
+      `Please update the package.json version property or modify the VERSION variable in version.ts to ensure they match`
+    );
+  }
+  console.log(`Versions ${version} (package.json) and ${version_1.VERSION} (version.ts) match`);
+};
+if (require.main === module) {
+  main();
+}
+//# sourceMappingURL=check-version.js.map

package/dist/cjs/check-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-version.js","sourceRoot":"","sources":["../../check-version.ts"],"names":[],"mappings":";;;;;AAAA,4CAAoB;AACpB,uCAAoC;AAEpC,MAAM,IAAI,GAAG,GAAG,EAAE;IAChB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAE,CAAC,YAAY,CAAC,cAAc,CAAC,CAAC,QAAQ,EAAE,CAA4B,CAAC;IAC9F,MAAM,OAAO,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC;IAC/B,IAAI,CAAC,OAAO;QAAE,MAAM,0DAA0D,CAAC;IAC/E,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE;QAC/B,MAAM,2DAA2D,OAAO,OAAO,mBAAmB,CAAC;KACpG;IACD,IAAI,OAAO,KAAK,iBAAO,EAAE;QACvB,MAAM,CACJ,oCAAoC,OAAO,kBAAkB,iBAAO,IAAI;YACxE,mHAAmH,CACpH,CAAC;KACH;IACD,OAAO,CAAC,GAAG,CAAC,YAAY,OAAO,uBAAuB,iBAAO,qBAAqB,CAAC,CAAC;AACtF,CAAC,CAAC;AAEF,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,EAAE;IAC3B,IAAI,EAAE,CAAC;CACR"}

package/dist/cjs/core.d.ts

@@ -2,9 +2,9 @@
 /// <reference types="node" />
 import qs from 'qs';
 import type { Agent } from 'http';
-import type NodeFetch from 'node-fetch';
 import type { RequestInfo, RequestInit, Response } from 'node-fetch';
 import { Readable } from 'stream';
+declare type Fetch = (url: RequestInfo, init?: RequestInit) => Promise<Response>;
 export declare abstract class APIClient {
   apiKey: string | null;
   baseURL: string;
@@ -67,6 +67,7 @@ export declare abstract class APIClient {
     { signal, ...options }: RequestInit | undefined,
     ms: number,
   ): Promise<Response>;
+  protected getRequestClient(): RequestClient;
   private shouldRetry;
   private retryRequest;
   private calculateRetryTimeoutSeconds;
@@ -125,9 +126,12 @@ export declare class PagePromise<
   [Symbol.asyncIterator](): AsyncGenerator<Awaited<Item>, void, unknown>;
 }
 export declare const createResponseHeaders: (
-  headers: Awaited<ReturnType<typeof NodeFetch>>['headers'],
+  headers: Awaited<ReturnType<Fetch>>['headers'],
 ) => Record<string, string>;
 declare type HTTPMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
+export declare type RequestClient = {
+  fetch: Fetch;
+};
 export declare type Headers = Record<string, string | null | undefined>;
 export declare type KeysEnum<T> = {
   [P in keyof Required<T>]: true;
@@ -144,7 +148,7 @@ export declare type RequestOptions<Req extends {} = Record<string, unknown> | Re
 };
 export declare const isRequestOptions: (
   obj: unknown,
-) => obj is RequestOptions<Readable | Record<string, unknown>>;
+) => obj is RequestOptions<Record<string, unknown> | Readable>;
 export declare type FinalRequestOptions<Req extends {} = Record<string, unknown> | Readable> =
   RequestOptions<Req> & {
     method: HTTPMethod;
@@ -200,6 +204,13 @@ export declare class APIConnectionError extends APIError {
 export declare class APIConnectionTimeoutError extends APIConnectionError {
   constructor();
 }
+/**
+ * Returns a multipart/form-data request if any part of the given request body contains a File / Blob value.
+ * Otherwise returns the request as is.
+ */
+export declare const maybeMultipartFormRequestOptions: <T = Record<string, unknown>>(
+  opts: RequestOptions<T>,
+) => RequestOptions<Readable | T>;
 export declare const multipartFormRequestOptions: <T = Record<string, unknown>>(
   opts: RequestOptions<T>,
 ) => RequestOptions<Readable | T>;