influship 0.2.0 → 0.3.2

package/src/core/pagination.ts

@@ -0,0 +1,232 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { InflushipError } from './error';
+import { FinalRequestOptions } from '../internal/request-options';
+import { defaultParseResponse } from '../internal/parse';
+import { type Influship } from '../client';
+import { APIPromise } from './api-promise';
+import { type APIResponseProps } from '../internal/parse';
+import { maybeObj } from '../internal/utils/values';
+
+export type PageRequestOptions = Pick<FinalRequestOptions, 'query' | 'headers' | 'body' | 'path' | 'method'>;
+
+export abstract class AbstractPage<Item> implements AsyncIterable<Item> {
+  #client: Influship;
+  protected options: FinalRequestOptions;
+
+  protected response: Response;
+  protected body: unknown;
+
+  constructor(client: Influship, response: Response, body: unknown, options: FinalRequestOptions) {
+    this.#client = client;
+    this.options = options;
+    this.response = response;
+    this.body = body;
+  }
+
+  abstract nextPageRequestOptions(): PageRequestOptions | null;
+
+  abstract getPaginatedItems(): Item[];
+
+  hasNextPage(): boolean {
+    const items = this.getPaginatedItems();
+    if (!items.length) return false;
+    return this.nextPageRequestOptions() != null;
+  }
+
+  async getNextPage(): Promise<this> {
+    const nextOptions = this.nextPageRequestOptions();
+    if (!nextOptions) {
+      throw new InflushipError(
+        'No next page expected; please check `.hasNextPage()` before calling `.getNextPage()`.',
+      );
+    }
+
+    return await this.#client.requestAPIList(this.constructor as any, nextOptions);
+  }
+
+  async *iterPages(): AsyncGenerator<this> {
+    let page: this = this;
+    yield page;
+    while (page.hasNextPage()) {
+      page = await page.getNextPage();
+      yield page;
+    }
+  }
+
+  async *[Symbol.asyncIterator](): AsyncGenerator<Item> {
+    for await (const page of this.iterPages()) {
+      for (const item of page.getPaginatedItems()) {
+        yield item;
+      }
+    }
+  }
+}
+
+/**
+ * This subclass of Promise will resolve to an instantiated Page once the request completes.
+ *
+ * It also implements AsyncIterable to allow auto-paginating iteration on an unawaited list call, eg:
+ *
+ *    for await (const item of client.items.list()) {
+ *      console.log(item)
+ *    }
+ */
+export class PagePromise<
+    PageClass extends AbstractPage<Item>,
+    Item = ReturnType<PageClass['getPaginatedItems']>[number],
+  >
+  extends APIPromise<PageClass>
+  implements AsyncIterable<Item>
+{
+  constructor(
+    client: Influship,
+    request: Promise<APIResponseProps>,
+    Page: new (...args: ConstructorParameters<typeof AbstractPage>) => PageClass,
+  ) {
+    super(
+      client,
+      request,
+      async (client, props) =>
+        new Page(client, props.response, await defaultParseResponse(client, props), props.options),
+    );
+  }
+
+  /**
+   * Allow auto-paginating iteration on an unawaited list call, eg:
+   *
+   *    for await (const item of client.items.list()) {
+   *      console.log(item)
+   *    }
+   */
+  async *[Symbol.asyncIterator](): AsyncGenerator<Item> {
+    const page = await this;
+    for await (const item of page) {
+      yield item;
+    }
+  }
+}
+
+export interface QueryCursorResponse<Item> {
+  next_cursor: string | null;
+
+  has_more: boolean;
+
+  data: Array<Item>;
+}
+
+export interface QueryCursorParams {
+  cursor?: string;
+
+  limit?: number;
+}
+
+export class QueryCursor<Item> extends AbstractPage<Item> implements QueryCursorResponse<Item> {
+  next_cursor: string | null;
+
+  has_more: boolean;
+
+  data: Array<Item>;
+
+  constructor(
+    client: Influship,
+    response: Response,
+    body: QueryCursorResponse<Item>,
+    options: FinalRequestOptions,
+  ) {
+    super(client, response, body, options);
+
+    this.next_cursor = body.next_cursor || null;
+    this.has_more = body.has_more || false;
+    this.data = body.data || [];
+  }
+
+  getPaginatedItems(): Item[] {
+    return this.data ?? [];
+  }
+
+  override hasNextPage(): boolean {
+    if (this.has_more === false) {
+      return false;
+    }
+
+    return super.hasNextPage();
+  }
+
+  nextPageRequestOptions(): PageRequestOptions | null {
+    const cursor = this.next_cursor;
+    if (!cursor) {
+      return null;
+    }
+
+    return {
+      ...this.options,
+      query: {
+        ...maybeObj(this.options.query),
+        cursor,
+      },
+    };
+  }
+}
+
+export interface BodyCursorResponse<Item> {
+  next_cursor: string | null;
+
+  has_more: boolean;
+
+  data: Array<Item>;
+}
+
+export interface BodyCursorParams {
+  cursor?: string;
+
+  limit?: number;
+}
+
+export class BodyCursor<Item> extends AbstractPage<Item> implements BodyCursorResponse<Item> {
+  next_cursor: string | null;
+
+  has_more: boolean;
+
+  data: Array<Item>;
+
+  constructor(
+    client: Influship,
+    response: Response,
+    body: BodyCursorResponse<Item>,
+    options: FinalRequestOptions,
+  ) {
+    super(client, response, body, options);
+
+    this.next_cursor = body.next_cursor || null;
+    this.has_more = body.has_more || false;
+    this.data = body.data || [];
+  }
+
+  getPaginatedItems(): Item[] {
+    return this.data ?? [];
+  }
+
+  override hasNextPage(): boolean {
+    if (this.has_more === false) {
+      return false;
+    }
+
+    return super.hasNextPage();
+  }
+
+  nextPageRequestOptions(): PageRequestOptions | null {
+    const cursor = this.next_cursor;
+    if (!cursor) {
+      return null;
+    }
+
+    return {
+      ...this.options,
+      body: {
+        ...maybeObj(this.options.body),
+        cursor,
+      },
+    };
+  }
+}

package/src/core/resource.ts

@@ -1,11 +1,11 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import type { InflushipAPI } from '../client';
+import type { Influship } from '../client';
 
 export abstract class APIResource {
-  protected _client: InflushipAPI;
+  protected _client: Influship;
 
-  constructor(client: InflushipAPI) {
+  constructor(client: Influship) {
     this._client = client;
   }
 }

package/src/index.ts

@@ -1,12 +1,13 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-export { InflushipAPI as default } from './client';
+export { Influship as default } from './client';
 
 export { type Uploadable, toFile } from './core/uploads';
 export { APIPromise } from './core/api-promise';
-export { InflushipAPI, type ClientOptions } from './client';
+export { Influship, type ClientOptions } from './client';
+export { PagePromise } from './core/pagination';
 export {
-  InflushipAPIError,
+  InflushipError,
   APIError,
   APIConnectionError,
   APIConnectionTimeoutError,

package/src/internal/parse.ts

@@ -1,7 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import type { FinalRequestOptions } from './request-options';
-import { type InflushipAPI } from '../client';
+import { type Influship } from '../client';
 import { formatRequestDetails, loggerFor } from './utils/log';
 
 export type APIResponseProps = {
@@ -13,7 +13,7 @@ export type APIResponseProps = {
   startTime: number;
 };
 
-export async function defaultParseResponse<T>(client: InflushipAPI, props: APIResponseProps): Promise<T> {
+export async function defaultParseResponse<T>(client: Influship, props: APIResponseProps): Promise<T> {
   const { response, requestLogID, retryOfRequestLogID, startTime } = props;
   const body = await (async () => {
     // fetch refuses to read the body when the status code is 204.
@@ -29,6 +29,12 @@ export async function defaultParseResponse<T>(client: InflushipAPI, props: APIRe
     const mediaType = contentType?.split(';')[0]?.trim();
     const isJSON = mediaType?.includes('application/json') || mediaType?.endsWith('+json');
     if (isJSON) {
+      const contentLength = response.headers.get('content-length');
+      if (contentLength === '0') {
+        // if there is no content we can't do anything
+        return undefined as T;
+      }
+
       const json = await response.json();
       return json as T;
     }

package/src/internal/shims.ts

@@ -16,7 +16,7 @@ export function getDefaultFetch(): Fetch {
   }
 
   throw new Error(
-    '`fetch` is not defined as a global; Either pass `fetch` to the client, `new InflushipAPI({ fetch })` or polyfill the global, `globalThis.fetch = fetch`',
+    '`fetch` is not defined as a global; Either pass `fetch` to the client, `new Influship({ fetch })` or polyfill the global, `globalThis.fetch = fetch`',
   );
 }
 

package/src/internal/uploads.ts

@@ -1,6 +1,6 @@
 import { type RequestOptions } from './request-options';
 import type { FilePropertyBag, Fetch } from './builtin-types';
-import type { InflushipAPI } from '../client';
+import type { Influship } from '../client';
 import { ReadableStreamFrom } from './shims';
 
 export type BlobPart = string | ArrayBuffer | ArrayBufferView | Blob | DataView;
@@ -74,7 +74,7 @@ export const isAsyncIterable = (value: any): value is AsyncIterable<any> =>
  */
 export const maybeMultipartFormRequestOptions = async (
   opts: RequestOptions,
-  fetch: InflushipAPI | Fetch,
+  fetch: Influship | Fetch,
 ): Promise<RequestOptions> => {
   if (!hasUploadableValue(opts.body)) return opts;
 
@@ -85,7 +85,7 @@ type MultipartFormRequestOptions = Omit<RequestOptions, 'body'> & { body: unknow
 
 export const multipartFormRequestOptions = async (
   opts: MultipartFormRequestOptions,
-  fetch: InflushipAPI | Fetch,
+  fetch: Influship | Fetch,
 ): Promise<RequestOptions> => {
   return { ...opts, body: await createForm(opts.body, fetch) };
 };
@@ -98,7 +98,7 @@ const supportsFormDataMap = /* @__PURE__ */ new WeakMap<Fetch, Promise<boolean>>
  * This function detects if the fetch function provided supports the global FormData object to avoid
  * confusing error messages later on.
  */
-function supportsFormData(fetchObject: InflushipAPI | Fetch): Promise<boolean> {
+function supportsFormData(fetchObject: Influship | Fetch): Promise<boolean> {
   const fetch: Fetch = typeof fetchObject === 'function' ? fetchObject : (fetchObject as any).fetch;
   const cached = supportsFormDataMap.get(fetch);
   if (cached) return cached;
@@ -124,7 +124,7 @@ function supportsFormData(fetchObject: InflushipAPI | Fetch): Promise<boolean> {
 
 export const createForm = async <T = Record<string, unknown>>(
   body: T | undefined,
-  fetch: InflushipAPI | Fetch,
+  fetch: Influship | Fetch,
 ): Promise<FormData> => {
   if (!(await supportsFormData(fetch))) {
     throw new TypeError(

package/src/internal/utils/base64.ts

@@ -1,6 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { InflushipAPIError } from '../../core/error';
+import { InflushipError } from '../../core/error';
 import { encodeUTF8 } from './bytes';
 
 export const toBase64 = (data: string | Uint8Array | null | undefined): string => {
@@ -18,7 +18,7 @@ export const toBase64 = (data: string | Uint8Array | null | undefined): string =
     return btoa(String.fromCharCode.apply(null, data as any));
   }
 
-  throw new InflushipAPIError('Cannot generate base64 string; Expected `Buffer` or `btoa` to be defined');
+  throw new InflushipError('Cannot generate base64 string; Expected `Buffer` or `btoa` to be defined');
 };
 
 export const fromBase64 = (str: string): Uint8Array => {
@@ -36,5 +36,5 @@ export const fromBase64 = (str: string): Uint8Array => {
     return buf;
   }
 
-  throw new InflushipAPIError('Cannot decode base64 string; Expected `Buffer` or `atob` to be defined');
+  throw new InflushipError('Cannot decode base64 string; Expected `Buffer` or `atob` to be defined');
 };

package/src/internal/utils/log.ts

@@ -1,7 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { hasOwn } from './values';
-import { type InflushipAPI } from '../../client';
+import { type Influship } from '../../client';
 import { RequestOptions } from '../request-options';
 
 type LogFn = (message: string, ...rest: unknown[]) => void;
@@ -24,7 +24,7 @@ const levelNumbers = {
 export const parseLogLevel = (
   maybeLevel: string | undefined,
   sourceName: string,
-  client: InflushipAPI,
+  client: Influship,
 ): LogLevel | undefined => {
   if (!maybeLevel) {
     return undefined;
@@ -60,7 +60,7 @@ const noopLogger = {
 
 let cachedLoggers = /* @__PURE__ */ new WeakMap<Logger, [LogLevel, Logger]>();
 
-export function loggerFor(client: InflushipAPI): Logger {
+export function loggerFor(client: Influship): Logger {
   const logger = client.logger;
   const logLevel = client.logLevel ?? 'off';
   if (!logger) {

package/src/internal/utils/path.ts

@@ -1,4 +1,4 @@
-import { InflushipAPIError } from '../../core/error';
+import { InflushipError } from '../../core/error';
 
 /**
  * Percent-encode everything that isn't safe to have in a path without encoding safe chars.
@@ -72,7 +72,7 @@ export const createPathTagFunction = (pathEncoder = encodeURIPath) =>
         return acc + spaces + arrows;
       }, '');
 
-      throw new InflushipAPIError(
+      throw new InflushipError(
         `Path parameters result in path with invalid segments:\n${invalidSegments
           .map((e) => e.error)
           .join('\n')}\n${path}\n${underline}`,

package/src/internal/utils/query.ts

@@ -0,0 +1,7 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import * as qs from '../qs/stringify';
+
+export function stringifyQuery(query: object | Record<string, unknown>) {
+  return qs.stringify(query, { arrayFormat: 'comma' });
+}

package/src/internal/utils/values.ts

@@ -1,6 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { InflushipAPIError } from '../../core/error';
+import { InflushipError } from '../../core/error';
 
 // https://url.spec.whatwg.org/#url-scheme-string
 const startsWithSchemeRegexp = /^[a-z][a-z0-9+.-]*:/i;
@@ -39,7 +39,7 @@ export function isObj(obj: unknown): obj is Record<string, unknown> {
 
 export const ensurePresent = <T>(value: T | null | undefined): T => {
   if (value == null) {
-    throw new InflushipAPIError(`Expected a value to be given but received ${value} instead.`);
+    throw new InflushipError(`Expected a value to be given but received ${value} instead.`);
   }
 
   return value;
@@ -47,10 +47,10 @@ export const ensurePresent = <T>(value: T | null | undefined): T => {
 
 export const validatePositiveInteger = (name: string, n: unknown): number => {
   if (typeof n !== 'number' || !Number.isInteger(n)) {
-    throw new InflushipAPIError(`${name} must be an integer`);
+    throw new InflushipError(`${name} must be an integer`);
   }
   if (n < 0) {
-    throw new InflushipAPIError(`${name} must be a positive integer`);
+    throw new InflushipError(`${name} must be a positive integer`);
   }
   return n;
 };
@@ -59,14 +59,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 InflushipAPIError(`Could not coerce ${value} (type: ${typeof value}) into a number`);
+  throw new InflushipError(`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 InflushipAPIError(`Could not coerce ${value} (type: ${typeof value}) into a number`);
+  throw new InflushipError(`Could not coerce ${value} (type: ${typeof value}) into a number`);
 };
 
 export const coerceBoolean = (value: unknown): boolean => {

package/src/internal/utils.ts

@@ -6,3 +6,4 @@ export * from './utils/env';
 export * from './utils/log';
 export * from './utils/uuid';
 export * from './utils/sleep';
+export * from './utils/query';

package/src/pagination.ts

@@ -0,0 +1,2 @@
+/** @deprecated Import from ./core/pagination instead */
+export * from './core/pagination';