postgrid-node 0.1.0-alpha.1

package/src/error.ts

@@ -0,0 +1,130 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { castToError, Headers } from './core';
+
+export class PostGridError extends Error {}
+
+export class APIError<
+  TStatus extends number | undefined = number | undefined,
+  THeaders extends Headers | undefined = Headers | undefined,
+  TError extends Object | undefined = Object | undefined,
+> extends PostGridError {
+  /** HTTP status for the response that caused the error */
+  readonly status: TStatus;
+  /** HTTP headers for the response that caused the error */
+  readonly headers: THeaders;
+  /** JSON body of the response that caused the error */
+  readonly error: TError;
+
+  constructor(status: TStatus, error: TError, message: string | undefined, headers: THeaders) {
+    super(`${APIError.makeMessage(status, error, message)}`);
+    this.status = status;
+    this.headers = headers;
+    this.error = error;
+  }
+
+  private static makeMessage(status: number | undefined, error: any, message: string | undefined) {
+    const msg =
+      error?.message ?
+        typeof error.message === 'string' ?
+          error.message
+        : JSON.stringify(error.message)
+      : error ? JSON.stringify(error)
+      : message;
+
+    if (status && msg) {
+      return `${status} ${msg}`;
+    }
+    if (status) {
+      return `${status} status code (no body)`;
+    }
+    if (msg) {
+      return msg;
+    }
+    return '(no status code or body)';
+  }
+
+  static generate(
+    status: number | undefined,
+    errorResponse: Object | undefined,
+    message: string | undefined,
+    headers: Headers | undefined,
+  ): APIError {
+    if (!status || !headers) {
+      return new APIConnectionError({ message, cause: castToError(errorResponse) });
+    }
+
+    const error = errorResponse as Record<string, any>;
+
+    if (status === 400) {
+      return new BadRequestError(status, error, message, headers);
+    }
+
+    if (status === 401) {
+      return new AuthenticationError(status, error, message, headers);
+    }
+
+    if (status === 403) {
+      return new PermissionDeniedError(status, error, message, headers);
+    }
+
+    if (status === 404) {
+      return new NotFoundError(status, error, message, headers);
+    }
+
+    if (status === 409) {
+      return new ConflictError(status, error, message, headers);
+    }
+
+    if (status === 422) {
+      return new UnprocessableEntityError(status, error, message, headers);
+    }
+
+    if (status === 429) {
+      return new RateLimitError(status, error, message, headers);
+    }
+
+    if (status >= 500) {
+      return new InternalServerError(status, error, message, headers);
+    }
+
+    return new APIError(status, error, message, headers);
+  }
+}
+
+export class APIUserAbortError extends APIError<undefined, undefined, undefined> {
+  constructor({ message }: { message?: string } = {}) {
+    super(undefined, undefined, message || 'Request was aborted.', undefined);
+  }
+}
+
+export class APIConnectionError extends APIError<undefined, undefined, undefined> {
+  constructor({ message, cause }: { message?: string | undefined; cause?: Error | undefined }) {
+    super(undefined, undefined, message || 'Connection error.', undefined);
+    // in some environments the 'cause' property is already declared
+    // @ts-ignore
+    if (cause) this.cause = cause;
+  }
+}
+
+export class APIConnectionTimeoutError extends APIConnectionError {
+  constructor({ message }: { message?: string } = {}) {
+    super({ message: message ?? 'Request timed out.' });
+  }
+}
+
+export class BadRequestError extends APIError<400, Headers> {}
+
+export class AuthenticationError extends APIError<401, Headers> {}
+
+export class PermissionDeniedError extends APIError<403, Headers> {}
+
+export class NotFoundError extends APIError<404, Headers> {}
+
+export class ConflictError extends APIError<409, Headers> {}
+
+export class UnprocessableEntityError extends APIError<422, Headers> {}
+
+export class RateLimitError extends APIError<429, Headers> {}
+
+export class InternalServerError extends APIError<number, Headers> {}

package/src/index.ts

@@ -0,0 +1,428 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { type Agent } from './_shims/index';
+import * as Core from './core';
+import * as Errors from './error';
+import * as Pagination from './pagination';
+import { type ListParams, ListResponse } from './pagination';
+import * as Uploads from './uploads';
+import * as API from './resources/index';
+import {
+  BankAccount,
+  BankAccountCreateParams,
+  BankAccountDeleteResponse,
+  BankAccountList,
+  BankAccountListParams,
+  BankAccounts,
+  BankAccountsList,
+} from './resources/bank-accounts';
+import {
+  BoxCancelResponse,
+  BoxCreateParams,
+  BoxCreateResponse,
+  BoxListParams,
+  BoxListResponse,
+  BoxListResponsesList,
+  BoxRetrieveResponse,
+  Boxes,
+} from './resources/boxes';
+import {
+  CampaignCreateParams,
+  CampaignCreateResponse,
+  CampaignDeleteResponse,
+  CampaignListParams,
+  CampaignListResponse,
+  CampaignListResponsesList,
+  CampaignRetrieveResponse,
+  CampaignSendParams,
+  CampaignSendResponse,
+  CampaignUpdateParams,
+  CampaignUpdateResponse,
+  Campaigns,
+} from './resources/campaigns';
+import {
+  Contact,
+  ContactCreateParams,
+  ContactDeleteResponse,
+  ContactListParams,
+  Contacts,
+  ContactsList,
+} from './resources/contacts';
+import {
+  Letter,
+  LetterCreateParams,
+  LetterList,
+  LetterListParams,
+  LetterURLResponse,
+  Letters,
+  LettersList,
+} from './resources/letters';
+import {
+  Postcard,
+  PostcardCreateParams,
+  PostcardList,
+  PostcardListParams,
+  PostcardURLResponse,
+  Postcards,
+  PostcardsList,
+} from './resources/postcards';
+import {
+  SelfMailerCancelResponse,
+  SelfMailerCreateParams,
+  SelfMailerCreateResponse,
+  SelfMailerListParams,
+  SelfMailerListResponse,
+  SelfMailerListResponsesList,
+  SelfMailerRetrieveResponse,
+  SelfMailers,
+} from './resources/self-mailers';
+import {
+  Template,
+  TemplateCreateParams,
+  TemplateDeleteResponse,
+  TemplateList,
+  TemplateListParams,
+  TemplateUpdateParams,
+  Templates,
+  TemplatesList,
+} from './resources/templates';
+import {
+  Cheque,
+  ChequeCreateParams,
+  ChequeList,
+  ChequeListParams,
+  Cheques,
+  ChequesList,
+} from './resources/cheques/cheques';
+import {
+  ReportCreateParams,
+  ReportCreateResponse,
+  ReportDeleteResponse,
+  ReportListParams,
+  ReportListResponse,
+  ReportListResponsesList,
+  ReportRetrieveResponse,
+  ReportUpdateParams,
+  ReportUpdateResponse,
+  Reports,
+} from './resources/reports/reports';
+
+export interface ClientOptions {
+  /**
+   * Defaults to process.env['POSTGRID_API_KEY'].
+   */
+  apiKey?: string | undefined;
+
+  /**
+   * Override the default base URL for the API, e.g., "https://api.example.com/v2/"
+   *
+   * Defaults to process.env['POSTGRID_BASE_URL'].
+   */
+  baseURL?: string | null | undefined;
+
+  /**
+   * The maximum amount of time (in milliseconds) that the client should wait for a response
+   * from the server before timing out a single request.
+   *
+   * Note that request timeouts are retried by default, so in a worst-case scenario you may wait
+   * much longer than this timeout before the promise succeeds or fails.
+   */
+  timeout?: number | undefined;
+
+  /**
+   * An HTTP agent used to manage HTTP(S) connections.
+   *
+   * If not provided, an agent will be constructed by default in the Node.js environment,
+   * otherwise no agent is used.
+   */
+  httpAgent?: Agent | undefined;
+
+  /**
+   * Specify a custom `fetch` function implementation.
+   *
+   * If not provided, we use `node-fetch` on Node.js and otherwise expect that `fetch` is
+   * defined globally.
+   */
+  fetch?: Core.Fetch | undefined;
+
+  /**
+   * The maximum number of times that the client will retry a request in case of a
+   * temporary failure, like a network error or a 5XX error from the server.
+   *
+   * @default 2
+   */
+  maxRetries?: number | undefined;
+
+  /**
+   * Default headers to include with every request to the API.
+   *
+   * These can be removed in individual requests by explicitly setting the
+   * header to `undefined` or `null` in request options.
+   */
+  defaultHeaders?: Core.Headers | undefined;
+
+  /**
+   * Default query parameters to include with every request to the API.
+   *
+   * These can be removed in individual requests by explicitly setting the
+   * param to `undefined` in request options.
+   */
+  defaultQuery?: Core.DefaultQuery | undefined;
+}
+
+/**
+ * API Client for interfacing with the PostGrid API.
+ */
+export class PostGrid extends Core.APIClient {
+  apiKey: string;
+
+  private _options: ClientOptions;
+
+  /**
+   * API Client for interfacing with the PostGrid API.
+   *
+   * @param {string | undefined} [opts.apiKey=process.env['POSTGRID_API_KEY'] ?? undefined]
+   * @param {string} [opts.baseURL=process.env['POSTGRID_BASE_URL'] ?? https://api.postgrid.com/print-mail/v1] - 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 {number} [opts.httpAgent] - An HTTP agent used to manage HTTP(s) connections.
+   * @param {Core.Fetch} [opts.fetch] - Specify a custom `fetch` function implementation.
+   * @param {number} [opts.maxRetries=2] - The maximum number of times the client will retry a request.
+   * @param {Core.Headers} opts.defaultHeaders - Default headers to include with every request to the API.
+   * @param {Core.DefaultQuery} opts.defaultQuery - Default query parameters to include with every request to the API.
+   */
+  constructor({
+    baseURL = Core.readEnv('POSTGRID_BASE_URL'),
+    apiKey = Core.readEnv('POSTGRID_API_KEY'),
+    ...opts
+  }: ClientOptions = {}) {
+    if (apiKey === undefined) {
+      throw new Errors.PostGridError(
+        "The POSTGRID_API_KEY environment variable is missing or empty; either provide it, or instantiate the PostGrid client with an apiKey option, like new PostGrid({ apiKey: 'My API Key' }).",
+      );
+    }
+
+    const options: ClientOptions = {
+      apiKey,
+      ...opts,
+      baseURL: baseURL || `https://api.postgrid.com/print-mail/v1`,
+    };
+
+    super({
+      baseURL: options.baseURL!,
+      timeout: options.timeout ?? 60000 /* 1 minute */,
+      httpAgent: options.httpAgent,
+      maxRetries: options.maxRetries,
+      fetch: options.fetch,
+    });
+
+    this._options = options;
+    this.idempotencyHeader = 'Idempotency-Key';
+
+    this.apiKey = apiKey;
+  }
+
+  contacts: API.Contacts = new API.Contacts(this);
+  templates: API.Templates = new API.Templates(this);
+  bankAccounts: API.BankAccounts = new API.BankAccounts(this);
+  cheques: API.Cheques = new API.Cheques(this);
+  letters: API.Letters = new API.Letters(this);
+  postcards: API.Postcards = new API.Postcards(this);
+  boxes: API.Boxes = new API.Boxes(this);
+  campaigns: API.Campaigns = new API.Campaigns(this);
+  reports: API.Reports = new API.Reports(this);
+  selfMailers: API.SelfMailers = new API.SelfMailers(this);
+
+  protected override defaultQuery(): Core.DefaultQuery | undefined {
+    return this._options.defaultQuery;
+  }
+
+  protected override defaultHeaders(opts: Core.FinalRequestOptions): Core.Headers {
+    return {
+      ...super.defaultHeaders(opts),
+      ...this._options.defaultHeaders,
+    };
+  }
+
+  protected override authHeaders(opts: Core.FinalRequestOptions): Core.Headers {
+    return { 'X-API-Key': this.apiKey };
+  }
+
+  static PostGrid = this;
+  static DEFAULT_TIMEOUT = 60000; // 1 minute
+
+  static PostGridError = Errors.PostGridError;
+  static APIError = Errors.APIError;
+  static APIConnectionError = Errors.APIConnectionError;
+  static APIConnectionTimeoutError = Errors.APIConnectionTimeoutError;
+  static APIUserAbortError = Errors.APIUserAbortError;
+  static NotFoundError = Errors.NotFoundError;
+  static ConflictError = Errors.ConflictError;
+  static RateLimitError = Errors.RateLimitError;
+  static BadRequestError = Errors.BadRequestError;
+  static AuthenticationError = Errors.AuthenticationError;
+  static InternalServerError = Errors.InternalServerError;
+  static PermissionDeniedError = Errors.PermissionDeniedError;
+  static UnprocessableEntityError = Errors.UnprocessableEntityError;
+
+  static toFile = Uploads.toFile;
+  static fileFromPath = Uploads.fileFromPath;
+}
+
+PostGrid.Contacts = Contacts;
+PostGrid.ContactsList = ContactsList;
+PostGrid.Templates = Templates;
+PostGrid.TemplatesList = TemplatesList;
+PostGrid.BankAccounts = BankAccounts;
+PostGrid.BankAccountsList = BankAccountsList;
+PostGrid.Cheques = Cheques;
+PostGrid.ChequesList = ChequesList;
+PostGrid.Letters = Letters;
+PostGrid.LettersList = LettersList;
+PostGrid.Postcards = Postcards;
+PostGrid.PostcardsList = PostcardsList;
+PostGrid.Boxes = Boxes;
+PostGrid.BoxListResponsesList = BoxListResponsesList;
+PostGrid.Campaigns = Campaigns;
+PostGrid.CampaignListResponsesList = CampaignListResponsesList;
+PostGrid.Reports = Reports;
+PostGrid.ReportListResponsesList = ReportListResponsesList;
+PostGrid.SelfMailers = SelfMailers;
+PostGrid.SelfMailerListResponsesList = SelfMailerListResponsesList;
+export declare namespace PostGrid {
+  export type RequestOptions = Core.RequestOptions;
+
+  export import List = Pagination.List;
+  export { type ListParams as ListParams, type ListResponse as ListResponse };
+
+  export {
+    Contacts as Contacts,
+    type Contact as Contact,
+    type ContactDeleteResponse as ContactDeleteResponse,
+    ContactsList as ContactsList,
+    type ContactCreateParams as ContactCreateParams,
+    type ContactListParams as ContactListParams,
+  };
+
+  export {
+    Templates as Templates,
+    type Template as Template,
+    type TemplateList as TemplateList,
+    type TemplateDeleteResponse as TemplateDeleteResponse,
+    TemplatesList as TemplatesList,
+    type TemplateCreateParams as TemplateCreateParams,
+    type TemplateUpdateParams as TemplateUpdateParams,
+    type TemplateListParams as TemplateListParams,
+  };
+
+  export {
+    BankAccounts as BankAccounts,
+    type BankAccount as BankAccount,
+    type BankAccountList as BankAccountList,
+    type BankAccountDeleteResponse as BankAccountDeleteResponse,
+    BankAccountsList as BankAccountsList,
+    type BankAccountCreateParams as BankAccountCreateParams,
+    type BankAccountListParams as BankAccountListParams,
+  };
+
+  export {
+    Cheques as Cheques,
+    type Cheque as Cheque,
+    type ChequeList as ChequeList,
+    ChequesList as ChequesList,
+    type ChequeCreateParams as ChequeCreateParams,
+    type ChequeListParams as ChequeListParams,
+  };
+
+  export {
+    Letters as Letters,
+    type Letter as Letter,
+    type LetterList as LetterList,
+    type LetterURLResponse as LetterURLResponse,
+    LettersList as LettersList,
+    type LetterCreateParams as LetterCreateParams,
+    type LetterListParams as LetterListParams,
+  };
+
+  export {
+    Postcards as Postcards,
+    type Postcard as Postcard,
+    type PostcardList as PostcardList,
+    type PostcardURLResponse as PostcardURLResponse,
+    PostcardsList as PostcardsList,
+    type PostcardCreateParams as PostcardCreateParams,
+    type PostcardListParams as PostcardListParams,
+  };
+
+  export {
+    Boxes as Boxes,
+    type BoxCreateResponse as BoxCreateResponse,
+    type BoxRetrieveResponse as BoxRetrieveResponse,
+    type BoxListResponse as BoxListResponse,
+    type BoxCancelResponse as BoxCancelResponse,
+    BoxListResponsesList as BoxListResponsesList,
+    type BoxCreateParams as BoxCreateParams,
+    type BoxListParams as BoxListParams,
+  };
+
+  export {
+    Campaigns as Campaigns,
+    type CampaignCreateResponse as CampaignCreateResponse,
+    type CampaignRetrieveResponse as CampaignRetrieveResponse,
+    type CampaignUpdateResponse as CampaignUpdateResponse,
+    type CampaignListResponse as CampaignListResponse,
+    type CampaignDeleteResponse as CampaignDeleteResponse,
+    type CampaignSendResponse as CampaignSendResponse,
+    CampaignListResponsesList as CampaignListResponsesList,
+    type CampaignCreateParams as CampaignCreateParams,
+    type CampaignUpdateParams as CampaignUpdateParams,
+    type CampaignListParams as CampaignListParams,
+    type CampaignSendParams as CampaignSendParams,
+  };
+
+  export {
+    Reports as Reports,
+    type ReportCreateResponse as ReportCreateResponse,
+    type ReportRetrieveResponse as ReportRetrieveResponse,
+    type ReportUpdateResponse as ReportUpdateResponse,
+    type ReportListResponse as ReportListResponse,
+    type ReportDeleteResponse as ReportDeleteResponse,
+    ReportListResponsesList as ReportListResponsesList,
+    type ReportCreateParams as ReportCreateParams,
+    type ReportUpdateParams as ReportUpdateParams,
+    type ReportListParams as ReportListParams,
+  };
+
+  export {
+    SelfMailers as SelfMailers,
+    type SelfMailerCreateResponse as SelfMailerCreateResponse,
+    type SelfMailerRetrieveResponse as SelfMailerRetrieveResponse,
+    type SelfMailerListResponse as SelfMailerListResponse,
+    type SelfMailerCancelResponse as SelfMailerCancelResponse,
+    SelfMailerListResponsesList as SelfMailerListResponsesList,
+    type SelfMailerCreateParams as SelfMailerCreateParams,
+    type SelfMailerListParams as SelfMailerListParams,
+  };
+
+  export type Cancellation = API.Cancellation;
+  export type ContactCreateWithCompanyName = API.ContactCreateWithCompanyName;
+  export type ContactCreateWithFirstName = API.ContactCreateWithFirstName;
+}
+
+export { toFile, fileFromPath } from './uploads';
+export {
+  PostGridError,
+  APIError,
+  APIConnectionError,
+  APIConnectionTimeoutError,
+  APIUserAbortError,
+  NotFoundError,
+  ConflictError,
+  RateLimitError,
+  BadRequestError,
+  AuthenticationError,
+  InternalServerError,
+  PermissionDeniedError,
+  UnprocessableEntityError,
+} from './error';
+
+export default PostGrid;

package/src/lib/.keep

@@ -0,0 +1,4 @@
+File generated from our OpenAPI spec by Stainless.
+
+This directory can be used to store custom files to expand the SDK.
+It is ignored by Stainless code generation and its content (other than this keep file) won't be touched.

package/src/pagination.ts

@@ -0,0 +1,69 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { AbstractPage, Response, APIClient, FinalRequestOptions, PageInfo } from './core';
+
+export interface ListResponse<Item> {
+  data: Array<Item>;
+
+  totalCount: number;
+}
+
+export interface ListParams {
+  /**
+   * The number of elements to skip.
+   */
+  skip?: number;
+
+  /**
+   * The maximum number of elements to fetch.
+   */
+  limit?: number;
+}
+
+export class List<Item> extends AbstractPage<Item> implements ListResponse<Item> {
+  data: Array<Item>;
+
+  totalCount: number;
+
+  constructor(client: APIClient, response: Response, body: ListResponse<Item>, options: FinalRequestOptions) {
+    super(client, response, body, options);
+
+    this.data = body.data || [];
+    this.totalCount = body.totalCount || 0;
+  }
+
+  getPaginatedItems(): Item[] {
+    return this.data ?? [];
+  }
+
+  // @deprecated Please use `nextPageInfo()` instead
+  nextPageParams(): Partial<ListParams> | null {
+    const info = this.nextPageInfo();
+    if (!info) return null;
+    if ('params' in info) return info.params;
+    const params = Object.fromEntries(info.url.searchParams);
+    if (!Object.keys(params).length) return null;
+    return params;
+  }
+
+  nextPageInfo(): PageInfo | null {
+    const offset = (this.options.query as ListParams).skip ?? 0;
+    if (!offset) {
+      return null;
+    }
+
+    const length = this.getPaginatedItems().length;
+    const currentCount = offset + length;
+
+    const totalCount = this.totalCount;
+    if (!totalCount) {
+      return null;
+    }
+
+    if (currentCount < totalCount) {
+      return { params: { skip: currentCount } };
+    }
+
+    return null;
+  }
+}

package/src/resource.ts

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