increase 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## [0.5.0](https://github.com/Increase/increase-node/compare/v0.4.0...v0.5.0) (2023-06-29)
+
+
+### ⚠ BREAKING CHANGES
+
+* **api:** remove many enum members from document category ([#27](https://github.com/Increase/increase-node/issues/27))
+* **types:** singularize array item types ([#25](https://github.com/Increase/increase-node/issues/25))
+
+### Features
+
+* **api/types:** mark more check transfer intention properties as nullable ([#26](https://github.com/Increase/increase-node/issues/26)) ([324580e](https://github.com/Increase/increase-node/commit/324580e75db774e8ca3c6561e288c217915b7722))
+* support ESM and web platform runtimes; easier file uploads ([#28](https://github.com/Increase/increase-node/issues/28)) ([1d53a8d](https://github.com/Increase/increase-node/commit/1d53a8dd26cfa10c36a1813a9e8d5a78697439e4))
+* **types:** export nested types through the root client export ([#23](https://github.com/Increase/increase-node/issues/23)) ([c68b1ae](https://github.com/Increase/increase-node/commit/c68b1ae49b52828121c5042303d74dc10f2960fc))
+
+
+### Bug Fixes
+
+* **form-data:** strip out undefined properties ([#21](https://github.com/Increase/increase-node/issues/21)) ([dd73783](https://github.com/Increase/increase-node/commit/dd73783b3541ff86ac53e22f397d53a87872f925))
+
+
+### Refactors
+
+* **api:** remove `other` from reason enum ([#24](https://github.com/Increase/increase-node/issues/24)) ([5d7206a](https://github.com/Increase/increase-node/commit/5d7206a911039f9f2b8c8f40db589777afbad113))
+* **api:** remove many enum members from document category ([#27](https://github.com/Increase/increase-node/issues/27)) ([ddcd780](https://github.com/Increase/increase-node/commit/ddcd7807953bc64a4e9f055bb9cd1a671554eaa5))
+* **types:** singularize array item types ([#25](https://github.com/Increase/increase-node/issues/25)) ([bb00a48](https://github.com/Increase/increase-node/commit/bb00a48c7c6aee72593c9e79decc9a4127873587))
+
+
+### Styles
+
+* minor reordering of types and properties ([#29](https://github.com/Increase/increase-node/issues/29)) ([0e6dbc5](https://github.com/Increase/increase-node/commit/0e6dbc537b6a5ff9464de3f3ce2c164f00b79680))
+
+
+### Chores
+
+* speed up build script slightly ([#30](https://github.com/Increase/increase-node/issues/30)) ([b8ad73c](https://github.com/Increase/increase-node/commit/b8ad73c54aacb5a582826a4d8cfb594f3e1450ee))
+
+
+### Documentation
+
+* rearrange sections in api.md ([#31](https://github.com/Increase/increase-node/issues/31)) ([a8859f4](https://github.com/Increase/increase-node/commit/a8859f4fcca63820dc3568f7fd9c5a8c5b79c445))
+
 ## [0.4.0](https://github.com/Increase/increase-node/compare/v0.3.0...v0.4.0) (2023-06-19)
 
 

package/README.md

@@ -61,17 +61,32 @@ Documentation for each method, request param, and response field are available i
 
 ## File Uploads
 
-Request parameters that correspond to file uploads can be passed as either a `FormData.Blob` or a `FormData.File` instance.
+Request parameters that correspond to file uploads can be passed in many different forms:
 
-We provide a `fileFromPath` helper function to easily create `FormData.File` instances from a given class.
+- `File` (or an object with the same structure)
+- a `fetch` `Response` (or an object with the same structure)
+- an `fs.ReadStream`
+- the return value of our `toFile` helper
 
 ```ts
-import Increase, { fileFromPath } from 'increase';
+import fs from 'fs';
+import fetch from 'node-fetch';
+import Increase, { toFile } from 'increase';
 
 const increase = new Increase();
 
-const file = await fileFromPath('my/file.txt');
-await increase.files.create({ file: file, purpose: 'other' });
+// If you have access to Node `fs` we recommend using `fs.createReadStream()`:
+await increase.files.create({ file: fs.createReadStream('my/file.txt'), purpose: 'other' });
+
+// Or if you have the web `File` API you can pass a `File` instance:
+await increase.files.create({ file: new File(['my bytes'], 'file.txt'), purpose: 'other' });
+
+// You can also pass a `fetch` `Response`:
+await increase.files.create({ file: await fetch('https://somesite/file.txt'), purpose: 'other' });
+
+// Finally, if none of the above are convenient, you can use our `toFile` helper:
+await increase.files.create({ file: await toFile(Buffer.from('my bytes'), 'file.txt'), purpose: 'other' });
+await increase.files.create({ file: await toFile(new Uint8Array([0, 1, 2]), 'file.txt'), purpose: 'other' });
 ```
 
 ## Handling errors

package/_shims/agent.node.ts

@@ -0,0 +1,20 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ */
+
+import KeepAliveAgent from 'agentkeepalive';
+import type { Agent } from 'node:http';
+import { AbortController as AbortControllerPolyfill } from 'abort-controller';
+
+const defaultHttpAgent: Agent = new KeepAliveAgent({ keepAlive: true, timeout: 5 * 60 * 1000 });
+const defaultHttpsAgent: Agent = new KeepAliveAgent.HttpsAgent({ keepAlive: true, timeout: 5 * 60 * 1000 });
+
+// Polyfill global object if needed.
+if (typeof AbortController === 'undefined') {
+  AbortController = AbortControllerPolyfill as any as typeof AbortController;
+}
+
+export const getDefaultAgent = (url: string): Agent | undefined => {
+  if (defaultHttpsAgent && url.startsWith('https')) return defaultHttpsAgent;
+  return defaultHttpAgent;
+};

package/_shims/agent.ts

@@ -0,0 +1,12 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ *
+ * This is a stub for non-node environments.
+ * In node environments, it gets replaced agent.node.ts by the package export map
+ */
+
+import type { Agent } from 'node:http';
+
+export const getDefaultAgent = (url: string): Agent | undefined => {
+  return undefined;
+};

package/_shims/fetch.node.ts

@@ -0,0 +1,11 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ */
+
+import fetch, { Request, Response, Headers } from 'node-fetch';
+import type { RequestInfo, RequestInit, BodyInit } from 'node-fetch';
+
+export { fetch, Request, Response, Headers };
+export type { RequestInfo, RequestInit, BodyInit };
+
+export const isPolyfilled = true;

package/_shims/fetch.ts

@@ -0,0 +1,32 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ */
+
+import type * as nf from 'node-fetch';
+
+const _fetch: typeof nf.default =
+  // @ts-ignore
+  fetch as any;
+type _fetch = typeof nf.default;
+const _Request: typeof nf.Request =
+  // @ts-ignore
+  Request as any;
+type _Request = nf.Request;
+const _Response: typeof nf.Response =
+  // @ts-ignore
+  Response as any;
+type _Response = nf.Response;
+const _Headers: typeof nf.Headers =
+  // @ts-ignore
+  Headers as any;
+type _Headers = nf.Headers;
+
+export const isPolyfilled = false;
+
+export { _fetch as fetch, _Request as Request, _Response as Response, _Headers as Headers };
+
+type _RequestInfo = nf.RequestInfo;
+type _RequestInit = nf.RequestInit;
+type _BodyInit = nf.BodyInit;
+
+export type { _RequestInit as RequestInit, _RequestInfo as RequestInfo, _BodyInit as BodyInit };

package/_shims/fileFromPath.node.ts

@@ -0,0 +1,30 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ */
+
+import type { FilePropertyBag } from 'formdata-node';
+import { fileFromPath as _fileFromPath } from 'formdata-node/file-from-path';
+import type { File } from './formdata.node';
+
+export type FileFromPathOptions = Omit<FilePropertyBag, 'lastModified'>;
+
+let warned = false;
+
+/**
+ * @deprecated use fs.createReadStream('./my/file.txt') instead
+ */
+export async function fileFromPath(path: string): Promise<File>;
+export async function fileFromPath(path: string, filename?: string): Promise<File>;
+export async function fileFromPath(path: string, options?: FileFromPathOptions): Promise<File>;
+export async function fileFromPath(
+  path: string,
+  filename?: string,
+  options?: FileFromPathOptions,
+): Promise<File>;
+export async function fileFromPath(path: string, ...args: any[]): Promise<File> {
+  if (!warned) {
+    console.warn(`fileFromPath is deprecated; use fs.createReadStream(${JSON.stringify(path)}) instead`);
+    warned = true;
+  }
+  return await _fileFromPath(path, ...args);
+}

package/_shims/fileFromPath.ts

@@ -0,0 +1,30 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ *
+ * This is a stub that gets replaced by fileFromPath.node.js for node environments
+ * in the package export map
+ */
+
+import type { FilePropertyBag } from 'formdata-node';
+import type { File } from './formdata';
+
+export type FileFromPathOptions = Omit<FilePropertyBag, 'lastModified'>;
+
+/**
+ * This is a stub for non-node environments that just throws an error.
+ * In node environments, this module will be replaced by util/node/fileFromPath by the
+ * package import map.
+ */
+export async function fileFromPath(path: string): Promise<File>;
+export async function fileFromPath(path: string, filename?: string): Promise<File>;
+export async function fileFromPath(path: string, options?: FileFromPathOptions): Promise<File>;
+export async function fileFromPath(
+  path: string,
+  filename?: string,
+  options?: FileFromPathOptions,
+): Promise<File>;
+export async function fileFromPath(): Promise<File> {
+  throw new Error(
+    'The `fileFromPath` function is only supported in Node. See the README for more details: https://www.github.com/increase/increase-node#file-uploads',
+  );
+}

package/_shims/formdata.node.ts

@@ -0,0 +1,9 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ */
+
+import { FormData, File, Blob } from 'formdata-node';
+
+export { FormData, File, Blob };
+
+export const isPolyfilled = true;

package/_shims/formdata.ts

@@ -0,0 +1,22 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ */
+
+import type * as fd from 'formdata-node';
+
+const _FormData: typeof fd.FormData =
+  // @ts-ignore
+  FormData as any;
+type _FormData = fd.FormData;
+const _File: typeof fd.File =
+  // @ts-ignore
+  File as any;
+type _File = fd.File;
+const _Blob: typeof fd.Blob =
+  // @ts-ignore
+  Blob as any;
+type _Blob = fd.Blob;
+
+export const isPolyfilled = false;
+
+export { _FormData as FormData, _File as File, _Blob as Blob };

package/_shims/getMultipartRequestOptions.node.ts

@@ -0,0 +1,24 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ */
+
+import { FormData } from './formdata.node';
+import type { RequestOptions } from '../core';
+import { Readable } from 'node:stream';
+import { FormDataEncoder } from 'form-data-encoder';
+
+export async function getMultipartRequestOptions<T extends {} = Record<string, unknown>>(
+  form: FormData,
+  opts: RequestOptions<T>,
+): Promise<RequestOptions<T>> {
+  const encoder = new FormDataEncoder(form);
+  const readable = Readable.from(encoder);
+  const body = { __multipartBody__: readable };
+  const headers = {
+    ...opts.headers,
+    ...encoder.headers,
+    'Content-Length': encoder.contentLength,
+  };
+
+  return { ...opts, body: body as any, headers };
+}

package/_shims/getMultipartRequestOptions.ts

@@ -0,0 +1,13 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ */
+
+import { FormData } from './formdata';
+import type { RequestOptions } from '../core';
+
+export async function getMultipartRequestOptions<T extends {} = Record<string, unknown>>(
+  form: FormData,
+  opts: RequestOptions<T>,
+): Promise<RequestOptions<T>> {
+  return { ...opts, body: { __multipartBody__: form } as any };
+}

package/_shims/newFileArgs.ts

@@ -0,0 +1,94 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ */
+
+import { type BlobPart, type Uploadable, isResponseLike, isBlobLike } from './uploadable';
+
+export type ToFileInput = Uploadable | Exclude<BlobPart, string> | AsyncIterable<BlobPart>;
+
+export type FilePropertyBag = {
+  type?: string;
+  lastModified?: number;
+};
+
+export async function newFileArgs(
+  value: ToFileInput,
+  name?: string | null,
+  options: FilePropertyBag = {},
+): Promise<{
+  bits: BlobPart[];
+  name: string;
+  options: FilePropertyBag;
+}> {
+  if (isResponseLike(value)) {
+    const blob = await value.blob();
+    name ||= new URL(value.url).pathname.split(/[\\/]/).pop() ?? 'unknown_file';
+
+    return { bits: [blob as any], name, options };
+  }
+
+  const bits = await getBytes(value);
+
+  name ||= getName(value) ?? 'unknown_file';
+
+  if (!options.type) {
+    const type = (bits[0] as any)?.type;
+    if (typeof type === 'string') {
+      options = { ...options, type };
+    }
+  }
+
+  return { bits, name, options };
+}
+
+async function getBytes(value: ToFileInput): Promise<Array<BlobPart>> {
+  if (value instanceof Promise) return getBytes(await (value as any));
+
+  let parts: Array<BlobPart> = [];
+  if (
+    typeof value === 'string' ||
+    ArrayBuffer.isView(value) || // includes Uint8Array, Buffer, etc.
+    value instanceof ArrayBuffer
+  ) {
+    parts.push(value);
+  } else if (isBlobLike(value)) {
+    parts.push(await value.arrayBuffer());
+  } else if (
+    isAsyncIterableIterator(value) // includes Readable, ReadableStream, etc.
+  ) {
+    for await (const chunk of value) {
+      parts.push(chunk as BlobPart); // TODO, consider validating?
+    }
+  } else {
+    throw new Error(
+      `Unexpected data type: ${typeof value}; constructor: ${
+        value?.constructor?.name
+      }; props: ${propsForError(value)}`,
+    );
+  }
+
+  return parts;
+}
+
+function propsForError(value: any): string {
+  const props = Object.getOwnPropertyNames(value);
+  return `[${props.map((p) => `"${p}"`).join(', ')}]`;
+}
+
+function getName(value: any): string | undefined {
+  return (
+    getStringFromMaybeBuffer(value.name) ||
+    getStringFromMaybeBuffer(value.filename) ||
+    // For fs.ReadStream
+    getStringFromMaybeBuffer(value.path)?.split(/[\\/]/).pop()
+  );
+}
+
+const getStringFromMaybeBuffer = (x: string | Buffer | unknown): string | undefined => {
+  if (typeof x === 'string') return x;
+  if (typeof Buffer !== 'undefined' && x instanceof Buffer) return String(x);
+  return undefined;
+};
+
+const isAsyncIterableIterator = (value: any): value is AsyncIterableIterator<unknown> =>
+  value != null && typeof value === 'object' && typeof value[Symbol.asyncIterator] === 'function';

package/_shims/toFile.node.ts

@@ -0,0 +1,25 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ */
+
+import { File } from 'formdata-node';
+import { type ToFileInput, newFileArgs, type FilePropertyBag } from './newFileArgs';
+import type { Uploadable, BlobPart, FileLike } from './uploadable.node'; // eslint-disable-line
+
+/**
+ * Helper for creating a {@link File} to pass to an SDK upload method from a variety of different data formats
+ * @param bits the raw content of the file.  Can be an {@link Uploadable}, {@link BlobPart}, or {@link AsyncIterable} of {@link BlobPart}s
+ * @param name the name of the file. If omitted, toFile will try to determine a file name from bits if possible
+ * @param {Object=} options additional properties
+ * @param {string=} options.type the MIME type of the content
+ * @param {number=} options.lastModified the last modified timestamp
+ * @returns a {@link File} with the given properties
+ */
+export async function toFile(
+  bits: ToFileInput,
+  name?: string | null | undefined,
+  options: FilePropertyBag | undefined = {},
+): Promise<FileLike> {
+  const args = await newFileArgs(bits, name, options);
+  return new File(args.bits, args.name, args.options);
+}

package/_shims/toFile.ts

@@ -0,0 +1,26 @@
+/// <reference lib="dom" />;
+
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ */
+
+import { type ToFileInput, newFileArgs, type FilePropertyBag } from './newFileArgs';
+import type { FileLike, Uploadable } from './uploadable'; // eslint-disable-line
+
+/**
+ * Helper for creating a {@link File} to pass to an SDK upload method from a variety of different data formats
+ * @param bits the raw content of the file.  Can be an {@link Uploadable}, {@link BlobPart}, or {@link AsyncIterable} of {@link BlobPart}s
+ * @param {string=} name the name of the file. If omitted, toFile will try to determine a file name from bits if possible
+ * @param {Object=} options additional properties
+ * @param {string=} options.type the MIME type of the content
+ * @param {number=} options.lastModified the last modified timestamp
+ * @returns a {@link File} with the given properties
+ */
+export async function toFile(
+  bits: ToFileInput,
+  name?: string | null | undefined,
+  options: FilePropertyBag | undefined = {},
+): Promise<FileLike> {
+  const args = await newFileArgs(bits, name, options);
+  return new File(args.bits as BlobPart[], args.name, args.options);
+}

package/_shims/uploadable.node.ts

@@ -0,0 +1,21 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ */
+
+import { ReadStream } from 'node:fs';
+import {
+  BlobPart,
+  Uploadable,
+  BlobLike,
+  FileLike,
+  ResponseLike,
+  isBlobLike,
+  isFileLike,
+  isResponseLike,
+} from './uploadable';
+
+export { BlobPart, BlobLike, FileLike, ResponseLike, isBlobLike, Uploadable };
+
+export const isUploadable = (value: any): value is Uploadable => {
+  return isFileLike(value) || isResponseLike(value) || value instanceof ReadStream;
+};

package/_shims/uploadable.ts

@@ -0,0 +1,82 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ */
+
+import type * as fs from 'node:fs';
+import type { toFile } from 'increase/_shims/toFile'; // eslint-disable-line
+
+export type BlobPart = string | ArrayBuffer | ArrayBufferView | BlobLike | Uint8Array | DataView;
+
+/**
+ * Typically, this is a native "File" class.
+ *
+ * We provide the {@link toFile} utility to convert a variety of objects
+ * into the File class.
+ *
+ * For convenience, you can also pass a fetch Response
+ * or, on Node, the result of {@link fs.createReadStream}('./myfile').
+ */
+export type Uploadable = FileLike | ResponseLike | fs.ReadStream;
+
+/**
+ * Intended to match web.Blob, node.Blob, node-fetch.Blob, etc.
+ */
+export interface BlobLike {
+  /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/size) */
+  readonly size: number;
+  /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/type) */
+  readonly type: string;
+  /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/text) */
+  text(): Promise<string>;
+  /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/slice) */
+  slice(start?: number, end?: number): BlobLike;
+  // unfortunately @types/node-fetch@^2.6.4 doesn't type the arrayBuffer method
+}
+
+/**
+ * Intended to match web.File, node.File, node-fetch.File, etc.
+ */
+export interface FileLike extends BlobLike {
+  /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/File/lastModified) */
+  readonly lastModified: number;
+  /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/File/name) */
+  readonly name: string;
+}
+
+/**
+ * Intended to match web.Response, node.Response, node-fetch.Response, etc.
+ */
+export interface ResponseLike {
+  url: string;
+  blob(): Promise<BlobLike>;
+}
+
+export const isResponseLike = (value: any): value is ResponseLike =>
+  value != null &&
+  typeof value === 'object' &&
+  typeof value.url === 'string' &&
+  typeof value.blob === 'function';
+
+export const isFileLike = (value: any): value is FileLike =>
+  value != null &&
+  typeof value === 'object' &&
+  typeof value.name === 'string' &&
+  typeof value.lastModified === 'number' &&
+  isBlobLike(value);
+
+/**
+ * The BlobLike type omits arrayBuffer() because @types/node-fetch@^2.6.4 lacks it; but this check
+ * adds the arrayBuffer() method type because it is available and used at runtime
+ */
+export const isBlobLike = (value: any): value is BlobLike & { arrayBuffer(): Promise<ArrayBuffer> } =>
+  value != null &&
+  typeof value === 'object' &&
+  typeof value.size === 'number' &&
+  typeof value.type === 'string' &&
+  typeof value.text === 'function' &&
+  typeof value.slice === 'function' &&
+  typeof value.arrayBuffer === 'function';
+
+export const isUploadable = (value: any): value is Uploadable => {
+  return isFileLike(value) || isResponseLike(value);
+};