postgrid-node 0.4.2 → 0.6.1

package/resources/print-mail/virtual-mailboxes/virtual-mailboxes.js

@@ -0,0 +1,92 @@
+"use strict";
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VirtualMailboxes = void 0;
+const tslib_1 = require("../../../internal/tslib.js");
+const resource_1 = require("../../../core/resource.js");
+const ItemsAPI = tslib_1.__importStar(require("./items.js"));
+const items_1 = require("./items.js");
+const pagination_1 = require("../../../core/pagination.js");
+const path_1 = require("../../../internal/utils/path.js");
+/**
+ *  Virtual mailboxes let you receive, scan, and forward your physical mail
+ *  without needing a traditional physical mailbox. Each mailbox is fully
+ *  digital, giving you a unique ID, status, and a set of capabilities such as
+ *  forwarding mail to another address or viewing envelope scans. This allows you
+ *  to manage physical correspondence entirely online.
+ *
+ *  You can request access to this feature by reaching out to
+ *  support@postgrid.com
+ */
+class VirtualMailboxes extends resource_1.APIResource {
+    constructor() {
+        super(...arguments);
+        this.items = new ItemsAPI.Items(this._client);
+    }
+    /**
+     * Creates a new virtual mailbox. In live mode, the virtual mailbox will be pending
+     * assignment and cannot be used until it has been assigned and activated by our
+     * team. You will be notified via email once the virtual mailbox has been
+     * activated. In test mode, the virtual mailbox will be activated immediately upon
+     * creation.
+     *
+     * @example
+     * ```ts
+     * const virtualMailbox =
+     *   await client.printMail.virtualMailboxes.create({
+     *     countryCode: 'US',
+     *     capabilities: {
+     *       envelopeScans: true,
+     *       forwardMailTo: 'contact_pxd7wnnD1xY6H6etKNvjb4',
+     *     },
+     *   });
+     * ```
+     */
+    create(body, options) {
+        return this._client.post('/print-mail/v1/virtual_mailboxes', { body, ...options });
+    }
+    /**
+     * Retrieve Virtual Mailbox
+     *
+     * @example
+     * ```ts
+     * const virtualMailbox =
+     *   await client.printMail.virtualMailboxes.retrieve('id');
+     * ```
+     */
+    retrieve(id, options) {
+        return this._client.get((0, path_1.path) `/print-mail/v1/virtual_mailboxes/${id}`, options);
+    }
+    /**
+     * Lists virtual mailboxes. You can use the `skip`, `limit`, and `search` query
+     * parameters to refine the list.
+     *
+     * @example
+     * ```ts
+     * // Automatically fetches more pages as needed.
+     * for await (const virtualMailboxListResponse of client.printMail.virtualMailboxes.list()) {
+     *   // ...
+     * }
+     * ```
+     */
+    list(query = {}, options) {
+        return this._client.getAPIList('/print-mail/v1/virtual_mailboxes', (pagination_1.SkipLimit), { query, ...options });
+    }
+    /**
+     * Retrieves the physical address of the virtual mailbox.
+     *
+     * @example
+     * ```ts
+     * const response =
+     *   await client.printMail.virtualMailboxes.retrieveAddress(
+     *     'id',
+     *   );
+     * ```
+     */
+    retrieveAddress(id, options) {
+        return this._client.get((0, path_1.path) `/print-mail/v1/virtual_mailboxes/${id}/address`, options);
+    }
+}
+exports.VirtualMailboxes = VirtualMailboxes;
+VirtualMailboxes.Items = items_1.Items;
+//# sourceMappingURL=virtual-mailboxes.js.map

package/resources/print-mail/virtual-mailboxes/virtual-mailboxes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual-mailboxes.js","sourceRoot":"","sources":["../../../src/resources/print-mail/virtual-mailboxes/virtual-mailboxes.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;;AAEtF,wDAAqD;AAErD,6DAAoC;AACpC,sCASiB;AAEjB,4DAAwF;AAExF,0DAAoD;AAEpD;;;;;;;;;GASG;AACH,MAAa,gBAAiB,SAAQ,sBAAW;IAAjD;;QACE,UAAK,GAAmB,IAAI,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IA8E3D,CAAC;IA5EC;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CACJ,IAAgC,EAChC,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,kCAAkC,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACrF,CAAC;IAED;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAU,EAAE,OAAwB;QAC3C,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,oCAAoC,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;IACjF,CAAC;IAED;;;;;;;;;;;OAWG;IACH,IAAI,CACF,QAAqD,EAAE,EACvD,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAC5B,kCAAkC,EAClC,CAAA,sBAAqC,CAAA,EACrC,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CACtB,CAAC;IACJ,CAAC;IAED;;;;;;;;;;OAUG;IACH,eAAe,CAAC,EAAU,EAAE,OAAwB;QAClD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,oCAAoC,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;IACzF,CAAC;CACF;AA/ED,4CA+EC;AA6SD,gBAAgB,CAAC,KAAK,GAAG,aAAK,CAAC"}

package/resources/print-mail/virtual-mailboxes/virtual-mailboxes.mjs

@@ -0,0 +1,87 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+import { APIResource } from "../../../core/resource.mjs";
+import * as ItemsAPI from "./items.mjs";
+import { Items, } from "./items.mjs";
+import { SkipLimit } from "../../../core/pagination.mjs";
+import { path } from "../../../internal/utils/path.mjs";
+/**
+ *  Virtual mailboxes let you receive, scan, and forward your physical mail
+ *  without needing a traditional physical mailbox. Each mailbox is fully
+ *  digital, giving you a unique ID, status, and a set of capabilities such as
+ *  forwarding mail to another address or viewing envelope scans. This allows you
+ *  to manage physical correspondence entirely online.
+ *
+ *  You can request access to this feature by reaching out to
+ *  support@postgrid.com
+ */
+export class VirtualMailboxes extends APIResource {
+    constructor() {
+        super(...arguments);
+        this.items = new ItemsAPI.Items(this._client);
+    }
+    /**
+     * Creates a new virtual mailbox. In live mode, the virtual mailbox will be pending
+     * assignment and cannot be used until it has been assigned and activated by our
+     * team. You will be notified via email once the virtual mailbox has been
+     * activated. In test mode, the virtual mailbox will be activated immediately upon
+     * creation.
+     *
+     * @example
+     * ```ts
+     * const virtualMailbox =
+     *   await client.printMail.virtualMailboxes.create({
+     *     countryCode: 'US',
+     *     capabilities: {
+     *       envelopeScans: true,
+     *       forwardMailTo: 'contact_pxd7wnnD1xY6H6etKNvjb4',
+     *     },
+     *   });
+     * ```
+     */
+    create(body, options) {
+        return this._client.post('/print-mail/v1/virtual_mailboxes', { body, ...options });
+    }
+    /**
+     * Retrieve Virtual Mailbox
+     *
+     * @example
+     * ```ts
+     * const virtualMailbox =
+     *   await client.printMail.virtualMailboxes.retrieve('id');
+     * ```
+     */
+    retrieve(id, options) {
+        return this._client.get(path `/print-mail/v1/virtual_mailboxes/${id}`, options);
+    }
+    /**
+     * Lists virtual mailboxes. You can use the `skip`, `limit`, and `search` query
+     * parameters to refine the list.
+     *
+     * @example
+     * ```ts
+     * // Automatically fetches more pages as needed.
+     * for await (const virtualMailboxListResponse of client.printMail.virtualMailboxes.list()) {
+     *   // ...
+     * }
+     * ```
+     */
+    list(query = {}, options) {
+        return this._client.getAPIList('/print-mail/v1/virtual_mailboxes', (SkipLimit), { query, ...options });
+    }
+    /**
+     * Retrieves the physical address of the virtual mailbox.
+     *
+     * @example
+     * ```ts
+     * const response =
+     *   await client.printMail.virtualMailboxes.retrieveAddress(
+     *     'id',
+     *   );
+     * ```
+     */
+    retrieveAddress(id, options) {
+        return this._client.get(path `/print-mail/v1/virtual_mailboxes/${id}/address`, options);
+    }
+}
+VirtualMailboxes.Items = Items;
+//# sourceMappingURL=virtual-mailboxes.mjs.map

package/resources/print-mail/virtual-mailboxes/virtual-mailboxes.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual-mailboxes.mjs","sourceRoot":"","sources":["../../../src/resources/print-mail/virtual-mailboxes/virtual-mailboxes.ts"],"names":[],"mappings":"AAAA,sFAAsF;OAE/E,EAAE,WAAW,EAAE;OAEf,KAAK,QAAQ;OACb,EAQL,KAAK,GACN;OAEM,EAAe,SAAS,EAAwB;OAEhD,EAAE,IAAI,EAAE;AAEf;;;;;;;;;GASG;AACH,MAAM,OAAO,gBAAiB,SAAQ,WAAW;IAAjD;;QACE,UAAK,GAAmB,IAAI,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IA8E3D,CAAC;IA5EC;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CACJ,IAAgC,EAChC,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,kCAAkC,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACrF,CAAC;IAED;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAU,EAAE,OAAwB;QAC3C,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,oCAAoC,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;IACjF,CAAC;IAED;;;;;;;;;;;OAWG;IACH,IAAI,CACF,QAAqD,EAAE,EACvD,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAC5B,kCAAkC,EAClC,CAAA,SAAqC,CAAA,EACrC,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CACtB,CAAC;IACJ,CAAC;IAED;;;;;;;;;;OAUG;IACH,eAAe,CAAC,EAAU,EAAE,OAAwB;QAClD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,oCAAoC,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;IACzF,CAAC;CACF;AA6SD,gBAAgB,CAAC,KAAK,GAAG,KAAK,CAAC"}

package/resources/print-mail/virtual-mailboxes.d.mts

@@ -0,0 +1,2 @@
+export * from "./virtual-mailboxes/index.mjs";
+//# sourceMappingURL=virtual-mailboxes.d.mts.map

package/resources/print-mail/virtual-mailboxes.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual-mailboxes.d.mts","sourceRoot":"","sources":["../../src/resources/print-mail/virtual-mailboxes.ts"],"names":[],"mappings":""}

package/resources/print-mail/virtual-mailboxes.d.ts

@@ -0,0 +1,2 @@
+export * from "./virtual-mailboxes/index.js";
+//# sourceMappingURL=virtual-mailboxes.d.ts.map

package/resources/print-mail/virtual-mailboxes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual-mailboxes.d.ts","sourceRoot":"","sources":["../../src/resources/print-mail/virtual-mailboxes.ts"],"names":[],"mappings":""}

package/resources/print-mail/{order-profiles.js → virtual-mailboxes.js}

@@ -2,5 +2,5 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("../../internal/tslib.js");
-tslib_1.__exportStar(require("./order-profiles/index.js"), exports);
-//# sourceMappingURL=order-profiles.js.map
+tslib_1.__exportStar(require("./virtual-mailboxes/index.js"), exports);
+//# sourceMappingURL=virtual-mailboxes.js.map

package/resources/print-mail/virtual-mailboxes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual-mailboxes.js","sourceRoot":"","sources":["../../src/resources/print-mail/virtual-mailboxes.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;AAEtF,uEAA0C"}

package/resources/print-mail/virtual-mailboxes.mjs

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+export * from "./virtual-mailboxes/index.mjs";
+//# sourceMappingURL=virtual-mailboxes.mjs.map

package/resources/print-mail/virtual-mailboxes.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual-mailboxes.mjs","sourceRoot":"","sources":["../../src/resources/print-mail/virtual-mailboxes.ts"],"names":[],"mappings":"AAAA,sFAAsF"}

package/src/client.ts

@@ -11,7 +11,7 @@ import type { APIResponseProps } from './internal/parse';
 import { getPlatformHeaders } from './internal/detect-platform';
 import * as Shims from './internal/shims';
 import * as Opts from './internal/request-options';
-import * as qs from './internal/qs';
+import { stringifyQuery } from './internal/utils/query';
 import { VERSION } from './version';
 import * as Errors from './core/error';
 import * as Pagination from './core/pagination';
@@ -21,6 +21,21 @@ import * as API from './resources/index';
 import { APIPromise } from './core/api-promise';
 import {
   AddressVerification,
+  AddressVerificationAutocompleteParams,
+  AddressVerificationAutocompleteResponse,
+  AddressVerificationBatchVerificationParams,
+  AddressVerificationBatchVerificationResponse,
+  AddressVerificationGetAutocompletePreviewsParams,
+  AddressVerificationGetAutocompletePreviewsResponse,
+  AddressVerificationGetLookupInfoResponse,
+  AddressVerificationLookupCityOrStateFromPostalOrZipCodeParams,
+  AddressVerificationLookupCityOrStateFromPostalOrZipCodeResponse,
+  AddressVerificationLookupZipCodeFromCityOrStateParams,
+  AddressVerificationLookupZipCodeFromCityOrStateResponse,
+  AddressVerificationParseAnAddressParams,
+  AddressVerificationParseAnAddressResponse,
+  AddressVerificationSuggestAddressesParams,
+  AddressVerificationSuggestAddressesResponse,
   AddressVerificationVerifyParams,
   AddressVerificationVerifyResponse,
   Errors as AddressVerificationAPIErrors,
@@ -28,14 +43,18 @@ import {
 } from './resources/address-verification';
 import {
   IntlAddressVerification,
+  IntlAddressVerificationAutocompleteParams,
+  IntlAddressVerificationAutocompleteResponse,
+  IntlAddressVerificationBatchVerificationParams,
+  IntlAddressVerificationBatchVerificationResponse,
+  IntlAddressVerificationGetAutocompleteAdvancedPreviewsParams,
+  IntlAddressVerificationGetAutocompleteAdvancedPreviewsResponse,
+  IntlAddressVerificationGetAutocompletePreviewsParams,
+  IntlAddressVerificationGetAutocompletePreviewsResponse,
   IntlAddressVerificationVerifyParams,
   IntlAddressVerificationVerifyResponse,
 } from './resources/intl-address-verification';
-import {
-  ContactCreateWithCompanyName,
-  ContactCreateWithFirstName,
-  PrintMail,
-} from './resources/print-mail/print-mail';
+import { 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';
@@ -63,7 +82,7 @@ export interface ClientOptions {
   /**
    * Override the default base URL for the API, e.g., "https://api.example.com/v2/"
    *
-   * Defaults to process.env['POST_GRID_BASE_URL'].
+   * Defaults to process.env['POSTGRID_BASE_URL'].
    */
   baseURL?: string | null | undefined;
 
@@ -117,7 +136,7 @@ export interface ClientOptions {
   /**
    * Set the log level.
    *
-   * Defaults to process.env['POST_GRID_LOG'] or 'warn' if it isn't set.
+   * Defaults to process.env['POSTGRID_LOG'] or 'warn' if it isn't set.
    */
   logLevel?: LogLevel | undefined;
 
@@ -130,7 +149,7 @@ export interface ClientOptions {
 }
 
 /**
- * API Client for interfacing with the Post Grid API.
+ * API Client for interfacing with the PostGrid API.
  */
 export class PostGrid {
   addressVerificationAPIKey: string | null;
@@ -139,7 +158,7 @@ export class PostGrid {
   baseURL: string;
   maxRetries: number;
   timeout: number;
-  logger: Logger | undefined;
+  logger: Logger;
   logLevel: LogLevel | undefined;
   fetchOptions: MergedRequestInit | undefined;
 
@@ -149,11 +168,11 @@ export class PostGrid {
   private _options: ClientOptions;
 
   /**
-   * API Client for interfacing with the Post Grid API.
+   * API Client for interfacing with the PostGrid API.
    *
    * @param {string | null | undefined} [opts.addressVerificationAPIKey=process.env['POSTGRID_ADDRESS_VERIFICATION_API_KEY'] ?? null]
    * @param {string | null | undefined} [opts.printMailAPIKey=process.env['POSTGRID_PRINT_MAIL_API_KEY'] ?? null]
-   * @param {string} [opts.baseURL=process.env['POST_GRID_BASE_URL'] ?? https://api.postgrid.com] - Override the default base URL for the API.
+   * @param {string} [opts.baseURL=process.env['POSTGRID_BASE_URL'] ?? https://api.postgrid.com] - Override the default base URL for the API.
    * @param {number} [opts.timeout=1 minute] - The maximum amount of time (in milliseconds) the client will wait for a response before timing out.
    * @param {MergedRequestInit} [opts.fetchOptions] - Additional `RequestInit` options to be passed to `fetch` calls.
    * @param {Fetch} [opts.fetch] - Specify a custom `fetch` function implementation.
@@ -162,7 +181,7 @@ export class PostGrid {
    * @param {Record<string, string | undefined>} opts.defaultQuery - Default query parameters to include with every request to the API.
    */
   constructor({
-    baseURL = readEnv('POST_GRID_BASE_URL'),
+    baseURL = readEnv('POSTGRID_BASE_URL'),
     addressVerificationAPIKey = readEnv('POSTGRID_ADDRESS_VERIFICATION_API_KEY') ?? null,
     printMailAPIKey = readEnv('POSTGRID_PRINT_MAIL_API_KEY') ?? null,
     ...opts
@@ -182,13 +201,25 @@ export class PostGrid {
     this.logLevel = defaultLogLevel;
     this.logLevel =
       parseLogLevel(options.logLevel, 'ClientOptions.logLevel', this) ??
-      parseLogLevel(readEnv('POST_GRID_LOG'), "process.env['POST_GRID_LOG']", this) ??
+      parseLogLevel(readEnv('POSTGRID_LOG'), "process.env['POSTGRID_LOG']", this) ??
       defaultLogLevel;
     this.fetchOptions = options.fetchOptions;
     this.maxRetries = options.maxRetries ?? 2;
     this.fetch = options.fetch ?? Shims.getDefaultFetch();
     this.#encoder = Opts.FallbackEncoder;
 
+    const customHeadersEnv = readEnv('POSTGRID_CUSTOM_HEADERS');
+    if (customHeadersEnv) {
+      const parsed: Record<string, string> = {};
+      for (const line of customHeadersEnv.split('\n')) {
+        const colon = line.indexOf(':');
+        if (colon >= 0) {
+          parsed[line.substring(0, colon).trim()] = line.substring(colon + 1).trim();
+        }
+      }
+      options.defaultHeaders = { ...parsed, ...options.defaultHeaders };
+    }
+
     this._options = options;
 
     this.addressVerificationAPIKey = addressVerificationAPIKey;
@@ -269,8 +300,11 @@ export class PostGrid {
     return buildHeaders([{ 'X-API-Key': this.printMailAPIKey }]);
   }
 
-  protected stringifyQuery(query: Record<string, unknown>): string {
-    return qs.stringify(query, { arrayFormat: 'comma' });
+  /**
+   * Basic re-implementation of `qs.stringify` for primitive types.
+   */
+  protected stringifyQuery(query: object | Record<string, unknown>): string {
+    return stringifyQuery(query);
   }
 
   private getUserAgent(): string {
@@ -302,12 +336,13 @@ export class PostGrid {
       : new URL(baseURL + (baseURL.endsWith('/') && path.startsWith('/') ? path.slice(1) : path));
 
     const defaultQuery = this.defaultQuery();
-    if (!isEmptyObj(defaultQuery)) {
-      query = { ...defaultQuery, ...query };
+    const pathQuery = Object.fromEntries(url.searchParams);
+    if (!isEmptyObj(defaultQuery) || !isEmptyObj(pathQuery)) {
+      query = { ...pathQuery, ...defaultQuery, ...query };
     }
 
     if (typeof query === 'object' && query && !Array.isArray(query)) {
-      url.search = this.stringifyQuery(query as Record<string, unknown>);
+      url.search = this.stringifyQuery(query);
     }
 
     return url.toString();
@@ -503,7 +538,7 @@ export class PostGrid {
       loggerFor(this).info(`${responseInfo} - ${retryMessage}`);
 
       const errText = await response.text().catch((err: any) => castToError(err).message);
-      const errJSON = safeJSON(errText);
+      const errJSON = safeJSON(errText) as any;
       const errMessage = errJSON ? undefined : errText;
 
       loggerFor(this).debug(
@@ -540,9 +575,14 @@ export class PostGrid {
   getAPIList<Item, PageClass extends Pagination.AbstractPage<Item> = Pagination.AbstractPage<Item>>(
     path: string,
     Page: new (...args: any[]) => PageClass,
-    opts?: RequestOptions,
+    opts?: PromiseOrValue<RequestOptions>,
   ): Pagination.PagePromise<PageClass, Item> {
-    return this.requestAPIList(Page, { method: 'get', path, ...opts });
+    return this.requestAPIList(
+      Page,
+      opts && 'then' in opts ?
+        opts.then((opts) => ({ method: 'get', path, ...opts }))
+      : { method: 'get', path, ...opts },
+    );
   }
 
   requestAPIList<
@@ -550,7 +590,7 @@ export class PostGrid {
     PageClass extends Pagination.AbstractPage<Item> = Pagination.AbstractPage<Item>,
   >(
     Page: new (...args: ConstructorParameters<typeof Pagination.AbstractPage>) => PageClass,
-    options: FinalRequestOptions,
+    options: PromiseOrValue<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);
@@ -563,9 +603,10 @@ export class PostGrid {
     controller: AbortController,
   ): Promise<Response> {
     const { signal, method, ...options } = init || {};
-    if (signal) signal.addEventListener('abort', () => controller.abort());
+    const abort = this._makeAbort(controller);
+    if (signal) signal.addEventListener('abort', abort, { once: true });
 
-    const timeout = setTimeout(() => controller.abort(), ms);
+    const timeout = setTimeout(abort, ms);
 
     const isReadableBody =
       ((globalThis as any).ReadableStream && options.body instanceof (globalThis as any).ReadableStream) ||
@@ -642,9 +683,9 @@ export class PostGrid {
       }
     }
 
-    // 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 && 0 <= timeoutMillis && timeoutMillis < 60 * 1000)) {
+    // If the API asks us to wait a certain amount of time, just do what it
+    // says, but otherwise calculate a default
+    if (timeoutMillis === undefined) {
       const maxRetries = options.maxRetries ?? this.maxRetries;
       timeoutMillis = this.calculateDefaultRetryTimeoutMillis(retriesRemaining, maxRetries);
     }
@@ -732,6 +773,12 @@ export class PostGrid {
     return headers.values;
   }
 
+  private _makeAbort(controller: AbortController) {
+    // note: we can't just inline this method inside `fetchWithTimeout()` because then the closure
+    //       would capture all request options, and cause a memory leak.
+    return () => controller.abort();
+  }
+
   private buildBody({ options: { body, headers: rawHeaders } }: { options: FinalRequestOptions }): {
     bodyHeaders: HeadersLike;
     body: BodyInit | undefined;
@@ -764,6 +811,14 @@ export class PostGrid {
         (Symbol.iterator in body && 'next' in body && typeof body.next === 'function'))
     ) {
       return { bodyHeaders: undefined, body: Shims.ReadableStreamFrom(body as AsyncIterable<Uint8Array>) };
+    } else if (
+      typeof body === 'object' &&
+      headers.values.get('content-type') === 'application/x-www-form-urlencoded'
+    ) {
+      return {
+        bodyHeaders: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: this.stringifyQuery(body),
+      };
     } else {
       return this.#encoder({ body, headers });
     }
@@ -788,7 +843,23 @@ export class PostGrid {
 
   static toFile = Uploads.toFile;
 
+  /**
+   *  Standard Address Verification API.
+   *
+   *  Provides endpoints to verify and standardize addresses across US and Canada,
+   *  supporting both structured and freeform inputs.
+   *
+   *  Note that this uses a different set of lookups than our international API.
+   *
+   */
   addressVerification: API.AddressVerification = new API.AddressVerification(this);
+  /**
+   *  International Address Verification API.
+   *
+   *  Provides endpoints to verify and standardize international addresses,
+   *  supporting both structured and freeform inputs.
+   *
+   */
   intlAddressVerification: API.IntlAddressVerification = new API.IntlAddressVerification(this);
   printMail: API.PrintMail = new API.PrintMail(this);
 }
@@ -807,19 +878,38 @@ export declare namespace PostGrid {
     AddressVerification as AddressVerification,
     type AddressVerificationAPIErrors as Errors,
     type Status as Status,
+    type AddressVerificationAutocompleteResponse as AddressVerificationAutocompleteResponse,
+    type AddressVerificationBatchVerificationResponse as AddressVerificationBatchVerificationResponse,
+    type AddressVerificationGetAutocompletePreviewsResponse as AddressVerificationGetAutocompletePreviewsResponse,
+    type AddressVerificationGetLookupInfoResponse as AddressVerificationGetLookupInfoResponse,
+    type AddressVerificationLookupCityOrStateFromPostalOrZipCodeResponse as AddressVerificationLookupCityOrStateFromPostalOrZipCodeResponse,
+    type AddressVerificationLookupZipCodeFromCityOrStateResponse as AddressVerificationLookupZipCodeFromCityOrStateResponse,
+    type AddressVerificationParseAnAddressResponse as AddressVerificationParseAnAddressResponse,
+    type AddressVerificationSuggestAddressesResponse as AddressVerificationSuggestAddressesResponse,
     type AddressVerificationVerifyResponse as AddressVerificationVerifyResponse,
+    type AddressVerificationAutocompleteParams as AddressVerificationAutocompleteParams,
+    type AddressVerificationBatchVerificationParams as AddressVerificationBatchVerificationParams,
+    type AddressVerificationGetAutocompletePreviewsParams as AddressVerificationGetAutocompletePreviewsParams,
+    type AddressVerificationLookupCityOrStateFromPostalOrZipCodeParams as AddressVerificationLookupCityOrStateFromPostalOrZipCodeParams,
+    type AddressVerificationLookupZipCodeFromCityOrStateParams as AddressVerificationLookupZipCodeFromCityOrStateParams,
+    type AddressVerificationParseAnAddressParams as AddressVerificationParseAnAddressParams,
+    type AddressVerificationSuggestAddressesParams as AddressVerificationSuggestAddressesParams,
     type AddressVerificationVerifyParams as AddressVerificationVerifyParams,
   };
 
   export {
     IntlAddressVerification as IntlAddressVerification,
+    type IntlAddressVerificationAutocompleteResponse as IntlAddressVerificationAutocompleteResponse,
+    type IntlAddressVerificationBatchVerificationResponse as IntlAddressVerificationBatchVerificationResponse,
+    type IntlAddressVerificationGetAutocompleteAdvancedPreviewsResponse as IntlAddressVerificationGetAutocompleteAdvancedPreviewsResponse,
+    type IntlAddressVerificationGetAutocompletePreviewsResponse as IntlAddressVerificationGetAutocompletePreviewsResponse,
     type IntlAddressVerificationVerifyResponse as IntlAddressVerificationVerifyResponse,
+    type IntlAddressVerificationAutocompleteParams as IntlAddressVerificationAutocompleteParams,
+    type IntlAddressVerificationBatchVerificationParams as IntlAddressVerificationBatchVerificationParams,
+    type IntlAddressVerificationGetAutocompleteAdvancedPreviewsParams as IntlAddressVerificationGetAutocompleteAdvancedPreviewsParams,
+    type IntlAddressVerificationGetAutocompletePreviewsParams as IntlAddressVerificationGetAutocompletePreviewsParams,
     type IntlAddressVerificationVerifyParams as IntlAddressVerificationVerifyParams,
   };
 
-  export {
-    PrintMail as PrintMail,
-    type ContactCreateWithCompanyName as ContactCreateWithCompanyName,
-    type ContactCreateWithFirstName as ContactCreateWithFirstName,
-  };
+  export { PrintMail as PrintMail };
 }

package/src/internal/parse.ts

@@ -29,6 +29,12 @@ export async function defaultParseResponse<T>(client: PostGrid, props: APIRespon
     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/types.ts

@@ -40,7 +40,6 @@ type OverloadedParameters<T> =
   : T extends (...args: infer A) => unknown ? A
   : never;
 
-/* eslint-disable */
 /**
  * These imports attempt to get types from a parent package's dependencies.
  * Unresolved bare specifiers can trigger [automatic type acquisition][1] in some projects, which
@@ -63,19 +62,18 @@ type OverloadedParameters<T> =
  *
  * [1]: https://www.typescriptlang.org/tsconfig/#typeAcquisition
  */
-/** @ts-ignore For users with \@types/node */
+/** @ts-ignore For users with \@types/node */ /* prettier-ignore */
 type UndiciTypesRequestInit = NotAny<import('../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../../../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../../../../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../../../../../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../../../../../../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../../../node_modules/undici-types/index.d.ts').RequestInit>;
-/** @ts-ignore For users with undici */
+/** @ts-ignore For users with undici */ /* prettier-ignore */
 type UndiciRequestInit = NotAny<import('../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../../../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../../../../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../../../../../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../../../../../../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../../../node_modules/undici/index.d.ts').RequestInit>;
-/** @ts-ignore For users with \@types/bun */
+/** @ts-ignore For users with \@types/bun */ /* prettier-ignore */
 type BunRequestInit = globalThis.FetchRequestInit;
-/** @ts-ignore For users with node-fetch@2 */
+/** @ts-ignore For users with node-fetch@2 */ /* prettier-ignore */
 type NodeFetch2RequestInit = NotAny<import('../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../../../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../../../../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../../../../../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../../../../../../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../../../node_modules/@types/node-fetch/index.d.ts').RequestInit>;
-/** @ts-ignore For users with node-fetch@3, doesn't need file extension because types are at ./@types/index.d.ts */
+/** @ts-ignore For users with node-fetch@3, doesn't need file extension because types are at ./@types/index.d.ts */ /* prettier-ignore */
 type NodeFetch3RequestInit =  NotAny<import('../node_modules/node-fetch').RequestInit> | NotAny<import('../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../../../../../node_modules/node-fetch').RequestInit>;
-/** @ts-ignore For users who use Deno */
+/** @ts-ignore For users who use Deno */ /* prettier-ignore */
 type FetchRequestInit = NonNullable<OverloadedParameters<typeof fetch>[1]>;
-/* eslint-enable */
 
 type RequestInits =
   | NotAny<UndiciTypesRequestInit>

package/src/internal/utils/env.ts

@@ -9,10 +9,10 @@
  */
 export const readEnv = (env: string): string | undefined => {
   if (typeof (globalThis as any).process !== 'undefined') {
-    return (globalThis as any).process.env?.[env]?.trim() ?? undefined;
+    return (globalThis as any).process.env?.[env]?.trim() || undefined;
   }
   if (typeof (globalThis as any).Deno !== 'undefined') {
-    return (globalThis as any).Deno.env?.get?.(env)?.trim();
+    return (globalThis as any).Deno.env?.get?.(env)?.trim() || undefined;
   }
   return undefined;
 };

package/src/internal/utils/log.ts

@@ -106,8 +106,9 @@ export const formatRequestDetails = (details: {
         ([name, value]) => [
           name,
           (
-            name.toLowerCase() === 'x-api-key' ||
             name.toLowerCase() === 'authorization' ||
+            name.toLowerCase() === 'api-key' ||
+            name.toLowerCase() === 'x-api-key' ||
             name.toLowerCase() === 'cookie' ||
             name.toLowerCase() === 'set-cookie'
           ) ?

package/src/internal/utils/query.ts

@@ -0,0 +1,23 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { PostGridError } from '../../core/error';
+
+/**
+ * Basic re-implementation of `qs.stringify` for primitive types.
+ */
+export function stringifyQuery(query: object | Record<string, unknown>) {
+  return Object.entries(query)
+    .filter(([_, value]) => typeof value !== 'undefined')
+    .map(([key, value]) => {
+      if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+        return `${encodeURIComponent(key)}=${encodeURIComponent(value)}`;
+      }
+      if (value === null) {
+        return `${encodeURIComponent(key)}=`;
+      }
+      throw new PostGridError(
+        `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.`,
+      );
+    })
+    .join('&');
+}