postgrid-node 0.3.0 → 0.4.0

package/src/client.ts

@@ -14,6 +14,8 @@ import * as Opts from './internal/request-options';
 import * as qs from './internal/qs';
 import { VERSION } from './version';
 import * as Errors from './core/error';
+import * as Pagination from './core/pagination';
+import { AbstractPage, type SkipLimitParams, SkipLimitResponse } from './core/pagination';
 import * as Uploads from './core/uploads';
 import * as API from './resources/index';
 import { APIPromise } from './core/api-promise';
@@ -29,7 +31,11 @@ import {
   IntlAddressVerificationVerifyParams,
   IntlAddressVerificationVerifyResponse,
 } from './resources/intl-address-verification';
-import { PrintMail } from './resources/print-mail/print-mail';
+import {
+  ContactCreateWithCompanyName,
+  ContactCreateWithFirstName,
+  PrintMail,
+} from './resources/print-mail/print-mail';
 import { type Fetch } from './internal/builtin-types';
 import { HeadersLike, NullableHeaders, buildHeaders } from './internal/headers';
 import { FinalRequestOptions, RequestOptions } from './internal/request-options';
@@ -531,6 +537,25 @@ export class PostGrid {
     return { response, options, controller, requestLogID, retryOfRequestLogID, startTime };
   }
 
+  getAPIList<Item, PageClass extends Pagination.AbstractPage<Item> = Pagination.AbstractPage<Item>>(
+    path: string,
+    Page: new (...args: any[]) => PageClass,
+    opts?: RequestOptions,
+  ): Pagination.PagePromise<PageClass, Item> {
+    return this.requestAPIList(Page, { method: 'get', path, ...opts });
+  }
+
+  requestAPIList<
+    Item = unknown,
+    PageClass extends Pagination.AbstractPage<Item> = Pagination.AbstractPage<Item>,
+  >(
+    Page: new (...args: ConstructorParameters<typeof Pagination.AbstractPage>) => PageClass,
+    options: FinalRequestOptions,
+  ): Pagination.PagePromise<PageClass, Item> {
+    const request = this.makeRequest(options, null, undefined);
+    return new Pagination.PagePromise<PageClass, Item>(this as any as PostGrid, request, Page);
+  }
+
   async fetchWithTimeout(
     url: RequestInfo,
     init: RequestInit | undefined,
@@ -775,6 +800,9 @@ PostGrid.PrintMail = PrintMail;
 export declare namespace PostGrid {
   export type RequestOptions = Opts.RequestOptions;
 
+  export import SkipLimit = Pagination.SkipLimit;
+  export { type SkipLimitParams as SkipLimitParams, type SkipLimitResponse as SkipLimitResponse };
+
   export {
     AddressVerification as AddressVerification,
     type AddressVerificationAPIErrors as Errors,
@@ -789,5 +817,9 @@ export declare namespace PostGrid {
     type IntlAddressVerificationVerifyParams as IntlAddressVerificationVerifyParams,
   };
 
-  export { PrintMail as PrintMail };
+  export {
+    PrintMail as PrintMail,
+    type ContactCreateWithCompanyName as ContactCreateWithCompanyName,
+    type ContactCreateWithFirstName as ContactCreateWithFirstName,
+  };
 }

package/src/core/pagination.ts

@@ -0,0 +1,171 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { PostGridError } from './error';
+import { FinalRequestOptions } from '../internal/request-options';
+import { defaultParseResponse } from '../internal/parse';
+import { type PostGrid } 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: PostGrid;
+  protected options: FinalRequestOptions;
+
+  protected response: Response;
+  protected body: unknown;
+
+  constructor(client: PostGrid, 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 PostGridError(
+        '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: PostGrid,
+    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 SkipLimitResponse<Item> {
+  data: Array<Item>;
+
+  totalCount: number;
+}
+
+export interface SkipLimitParams {
+  /**
+   * The number of elements to skip.
+   */
+  skip?: number;
+
+  /**
+   * The maximum number of elements to fetch.
+   */
+  limit?: number;
+}
+
+export class SkipLimit<Item> extends AbstractPage<Item> implements SkipLimitResponse<Item> {
+  data: Array<Item>;
+
+  totalCount: number;
+
+  constructor(
+    client: PostGrid,
+    response: Response,
+    body: SkipLimitResponse<Item>,
+    options: FinalRequestOptions,
+  ) {
+    super(client, response, body, options);
+
+    this.data = body.data || [];
+    this.totalCount = body.totalCount || 0;
+  }
+
+  getPaginatedItems(): Item[] {
+    return this.data ?? [];
+  }
+
+  nextPageRequestOptions(): PageRequestOptions | null {
+    const offset = (this.options.query as SkipLimitParams).skip ?? 0;
+    const length = this.getPaginatedItems().length;
+    const currentCount = offset + length;
+
+    const totalCount = this.totalCount;
+    if (!totalCount) {
+      return null;
+    }
+
+    if (currentCount < totalCount) {
+      return {
+        ...this.options,
+        query: {
+          ...maybeObj(this.options.query),
+          skip: currentCount,
+        },
+      };
+    }
+
+    return null;
+  }
+}

package/src/index.ts

@@ -5,6 +5,7 @@ export { PostGrid as default } from './client';
 export { type Uploadable, toFile } from './core/uploads';
 export { APIPromise } from './core/api-promise';
 export { PostGrid, type ClientOptions } from './client';
+export { PagePromise } from './core/pagination';
 export {
   PostGridError,
   APIError,

package/src/pagination.ts

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

package/src/resources/index.ts

@@ -12,4 +12,8 @@ export {
   type IntlAddressVerificationVerifyResponse,
   type IntlAddressVerificationVerifyParams,
 } from './intl-address-verification';
-export { PrintMail } from './print-mail/print-mail';
+export {
+  PrintMail,
+  type ContactCreateWithCompanyName,
+  type ContactCreateWithFirstName,
+} from './print-mail/print-mail';

package/src/resources/print-mail/bank-accounts.ts

@@ -2,6 +2,7 @@
 
 import { APIResource } from '../../core/resource';
 import { APIPromise } from '../../core/api-promise';
+import { PagePromise, SkipLimit, type SkipLimitParams } from '../../core/pagination';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
@@ -51,15 +52,20 @@ export class BankAccounts extends APIResource {
    *
    * @example
    * ```ts
-   * const bankAccounts =
-   *   await client.printMail.bankAccounts.list();
+   * // Automatically fetches more pages as needed.
+   * for await (const bankAccount of client.printMail.bankAccounts.list()) {
+   *   // ...
+   * }
    * ```
    */
   list(
     query: BankAccountListParams | null | undefined = {},
     options?: RequestOptions,
-  ): APIPromise<BankAccountListResponse> {
-    return this._client.get('/print-mail/v1/bank_accounts', { query, ...options });
+  ): PagePromise<BankAccountsSkipLimit, BankAccount> {
+    return this._client.getAPIList('/print-mail/v1/bank_accounts', SkipLimit<BankAccount>, {
+      query,
+      ...options,
+    });
   }
 
   /**
@@ -76,6 +82,8 @@ export class BankAccounts extends APIResource {
   }
 }
 
+export type BankAccountsSkipLimit = SkipLimit<BankAccount>;
+
 export interface BankAccount {
   /**
    * A unique ID prefixed with bank*account*
@@ -178,18 +186,6 @@ export interface BankAccount {
  */
 export type BankAccountCountryCode = 'CA' | 'US';
 
-export interface BankAccountListResponse {
-  data: Array<BankAccount>;
-
-  limit: number;
-
-  object: 'list';
-
-  skip: number;
-
-  totalCount: number;
-}
-
 export interface BankAccountDeleteResponse {
   /**
    * A unique ID prefixed with bank*account*
@@ -405,9 +401,7 @@ export declare namespace BankAccountCreateParams {
   }
 }
 
-export interface BankAccountListParams {
-  limit?: number;
-
+export interface BankAccountListParams extends SkipLimitParams {
   /**
    * You can supply any string to help narrow down the list of resources. For
    * example, if you pass `"New York"` (quoted), it will return resources that have
@@ -416,16 +410,14 @@ export interface BankAccountListParams {
    * more details.
    */
   search?: string;
-
-  skip?: number;
 }
 
 export declare namespace BankAccounts {
   export {
     type BankAccount as BankAccount,
     type BankAccountCountryCode as BankAccountCountryCode,
-    type BankAccountListResponse as BankAccountListResponse,
     type BankAccountDeleteResponse as BankAccountDeleteResponse,
+    type BankAccountsSkipLimit as BankAccountsSkipLimit,
     type BankAccountCreateParams as BankAccountCreateParams,
     type BankAccountListParams as BankAccountListParams,
   };