@zavudev/sdk 0.5.0 → 0.7.0

package/src/client.ts

@@ -13,15 +13,17 @@ import * as Shims from './internal/shims';
 import * as Opts from './internal/request-options';
 import { VERSION } from './version';
 import * as Errors from './core/error';
+import * as Pagination from './core/pagination';
+import { AbstractPage, type CursorParams, CursorResponse } from './core/pagination';
 import * as Uploads from './core/uploads';
 import * as API from './resources/index';
 import { APIPromise } from './core/api-promise';
 import {
   Contact,
   ContactListParams,
-  ContactListResponse,
   ContactUpdateParams,
   Contacts,
+  ContactsCursor,
 } from './resources/contacts';
 import {
   Introspect,
@@ -34,28 +36,28 @@ import {
   Message,
   MessageContent,
   MessageListParams,
-  MessageListResponse,
   MessageReactParams,
   MessageResponse,
   MessageSendParams,
   MessageStatus,
   MessageType,
   Messages,
+  MessagesCursor,
 } from './resources/messages';
 import {
   Sender,
   SenderCreateParams,
   SenderListParams,
-  SenderListResponse,
   SenderUpdateParams,
   Senders,
+  SendersCursor,
 } from './resources/senders';
 import {
   Template,
   TemplateCreateParams,
   TemplateListParams,
-  TemplateListResponse,
   Templates,
+  TemplatesCursor,
   WhatsappCategory,
 } from './resources/templates';
 import { type Fetch } from './internal/builtin-types';
@@ -523,6 +525,25 @@ export class Zavudev {
     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 Zavudev, request, Page);
+  }
+
   async fetchWithTimeout(
     url: RequestInfo,
     init: RequestInit | undefined,
@@ -771,6 +792,9 @@ Zavudev.Introspect = Introspect;
 export declare namespace Zavudev {
   export type RequestOptions = Opts.RequestOptions;
 
+  export import Cursor = Pagination.Cursor;
+  export { type CursorParams as CursorParams, type CursorResponse as CursorResponse };
+
   export {
     Messages as Messages,
     type Channel as Channel,
@@ -779,7 +803,7 @@ export declare namespace Zavudev {
     type MessageResponse as MessageResponse,
     type MessageStatus as MessageStatus,
     type MessageType as MessageType,
-    type MessageListResponse as MessageListResponse,
+    type MessagesCursor as MessagesCursor,
     type MessageListParams as MessageListParams,
     type MessageReactParams as MessageReactParams,
     type MessageSendParams as MessageSendParams,
@@ -789,7 +813,7 @@ export declare namespace Zavudev {
     Templates as Templates,
     type Template as Template,
     type WhatsappCategory as WhatsappCategory,
-    type TemplateListResponse as TemplateListResponse,
+    type TemplatesCursor as TemplatesCursor,
     type TemplateCreateParams as TemplateCreateParams,
     type TemplateListParams as TemplateListParams,
   };
@@ -797,7 +821,7 @@ export declare namespace Zavudev {
   export {
     Senders as Senders,
     type Sender as Sender,
-    type SenderListResponse as SenderListResponse,
+    type SendersCursor as SendersCursor,
     type SenderCreateParams as SenderCreateParams,
     type SenderUpdateParams as SenderUpdateParams,
     type SenderListParams as SenderListParams,
@@ -806,7 +830,7 @@ export declare namespace Zavudev {
   export {
     Contacts as Contacts,
     type Contact as Contact,
-    type ContactListResponse as ContactListResponse,
+    type ContactsCursor as ContactsCursor,
     type ContactUpdateParams as ContactUpdateParams,
     type ContactListParams as ContactListParams,
   };

package/src/core/pagination.ts

@@ -0,0 +1,152 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { ZavudevError } from './error';
+import { FinalRequestOptions } from '../internal/request-options';
+import { defaultParseResponse } from '../internal/parse';
+import { type Zavudev } 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: Zavudev;
+  protected options: FinalRequestOptions;
+
+  protected response: Response;
+  protected body: unknown;
+
+  constructor(client: Zavudev, 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 ZavudevError(
+        '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: Zavudev,
+    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 CursorResponse<Item> {
+  items: Array<Item>;
+
+  nextCursor: string;
+}
+
+export interface CursorParams {
+  cursor?: string;
+
+  limit?: number;
+}
+
+export class Cursor<Item> extends AbstractPage<Item> implements CursorResponse<Item> {
+  items: Array<Item>;
+
+  nextCursor: string;
+
+  constructor(client: Zavudev, response: Response, body: CursorResponse<Item>, options: FinalRequestOptions) {
+    super(client, response, body, options);
+
+    this.items = body.items || [];
+    this.nextCursor = body.nextCursor || '';
+  }
+
+  getPaginatedItems(): Item[] {
+    return this.items ?? [];
+  }
+
+  nextPageRequestOptions(): PageRequestOptions | null {
+    const cursor = this.nextCursor;
+    if (!cursor) {
+      return null;
+    }
+
+    return {
+      ...this.options,
+      query: {
+        ...maybeObj(this.options.query),
+        cursor,
+      },
+    };
+  }
+}

package/src/index.ts

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

package/src/pagination.ts

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

package/src/resources/contacts.ts

@@ -2,6 +2,7 @@
 
 import { APIResource } from '../core/resource';
 import { APIPromise } from '../core/api-promise';
+import { Cursor, type CursorParams, PagePromise } from '../core/pagination';
 import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
 
@@ -26,8 +27,8 @@ export class Contacts extends APIResource {
   list(
     query: ContactListParams | null | undefined = {},
     options?: RequestOptions,
-  ): APIPromise<ContactListResponse> {
-    return this._client.get('/v1/contacts', { query, ...options });
+  ): PagePromise<ContactsCursor, Contact> {
+    return this._client.getAPIList('/v1/contacts', Cursor<Contact>, { query, ...options });
   }
 
   /**
@@ -38,6 +39,8 @@ export class Contacts extends APIResource {
   }
 }
 
+export type ContactsCursor = Cursor<Contact>;
+
 export interface Contact {
   id: string;
 
@@ -70,12 +73,6 @@ export interface Contact {
   verified?: boolean;
 }
 
-export interface ContactListResponse {
-  items: Array<Contact>;
-
-  nextCursor?: string | null;
-}
-
 export interface ContactUpdateParams {
   /**
    * Preferred channel for this contact. Set to null to clear.
@@ -85,18 +82,14 @@ export interface ContactUpdateParams {
   metadata?: { [key: string]: string };
 }
 
-export interface ContactListParams {
-  cursor?: string;
-
-  limit?: number;
-
+export interface ContactListParams extends CursorParams {
   phoneNumber?: string;
 }
 
 export declare namespace Contacts {
   export {
     type Contact as Contact,
-    type ContactListResponse as ContactListResponse,
+    type ContactsCursor as ContactsCursor,
     type ContactUpdateParams as ContactUpdateParams,
     type ContactListParams as ContactListParams,
   };

package/src/resources/index.ts

@@ -3,9 +3,9 @@
 export {
   Contacts,
   type Contact,
-  type ContactListResponse,
   type ContactUpdateParams,
   type ContactListParams,
+  type ContactsCursor,
 } from './contacts';
 export {
   Introspect,
@@ -21,24 +21,24 @@ export {
   type MessageResponse,
   type MessageStatus,
   type MessageType,
-  type MessageListResponse,
   type MessageListParams,
   type MessageReactParams,
   type MessageSendParams,
+  type MessagesCursor,
 } from './messages';
 export {
   Senders,
   type Sender,
-  type SenderListResponse,
   type SenderCreateParams,
   type SenderUpdateParams,
   type SenderListParams,
+  type SendersCursor,
 } from './senders';
 export {
   Templates,
   type Template,
   type WhatsappCategory,
-  type TemplateListResponse,
   type TemplateCreateParams,
   type TemplateListParams,
+  type TemplatesCursor,
 } from './templates';

package/src/resources/messages.ts

@@ -2,6 +2,7 @@
 
 import { APIResource } from '../core/resource';
 import { APIPromise } from '../core/api-promise';
+import { Cursor, type CursorParams, PagePromise } from '../core/pagination';
 import { buildHeaders } from '../internal/headers';
 import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
@@ -26,14 +27,17 @@ export class Messages extends APIResource {
    *
    * @example
    * ```ts
-   * const messages = await client.messages.list();
+   * // Automatically fetches more pages as needed.
+   * for await (const message of client.messages.list()) {
+   *   // ...
+   * }
    * ```
    */
   list(
     query: MessageListParams | null | undefined = {},
     options?: RequestOptions,
-  ): APIPromise<MessageListResponse> {
-    return this._client.get('/v1/messages', { query, ...options });
+  ): PagePromise<MessagesCursor, Message> {
+    return this._client.getAPIList('/v1/messages', Cursor<Message>, { query, ...options });
   }
 
   /**
@@ -99,6 +103,8 @@ export class Messages extends APIResource {
   }
 }
 
+export type MessagesCursor = Cursor<Message>;
+
 /**
  * Delivery channel. Use 'auto' for intelligent routing.
  */
@@ -129,14 +135,19 @@ export interface Message {
   content?: MessageContent;
 
   /**
-   * Cost of the message in USD.
+   * MAU cost in USD (charged for first contact of the month).
    */
   cost?: number | null;
 
   /**
-   * Provider that charged for the message (e.g., 'telnyx').
+   * Provider cost in USD (Telnyx, SES, etc.).
    */
-  costProvider?: string | null;
+  costProvider?: number | null;
+
+  /**
+   * Total cost in USD (MAU + provider cost).
+   */
+  costTotal?: number | null;
 
   errorCode?: string | null;
 
@@ -299,22 +310,12 @@ export type MessageType =
   | 'reaction'
   | 'template';
 
-export interface MessageListResponse {
-  items: Array<Message>;
-
-  nextCursor?: string | null;
-}
-
-export interface MessageListParams {
+export interface MessageListParams extends CursorParams {
   /**
    * Delivery channel. Use 'auto' for intelligent routing.
    */
   channel?: Channel;
 
-  cursor?: string;
-
-  limit?: number;
-
   status?: MessageStatus;
 
   to?: string;
@@ -403,7 +404,7 @@ export declare namespace Messages {
     type MessageResponse as MessageResponse,
     type MessageStatus as MessageStatus,
     type MessageType as MessageType,
-    type MessageListResponse as MessageListResponse,
+    type MessagesCursor as MessagesCursor,
     type MessageListParams as MessageListParams,
     type MessageReactParams as MessageReactParams,
     type MessageSendParams as MessageSendParams,

package/src/resources/senders.ts

@@ -2,6 +2,7 @@
 
 import { APIResource } from '../core/resource';
 import { APIPromise } from '../core/api-promise';
+import { Cursor, type CursorParams, PagePromise } from '../core/pagination';
 import { buildHeaders } from '../internal/headers';
 import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
@@ -34,8 +35,8 @@ export class Senders extends APIResource {
   list(
     query: SenderListParams | null | undefined = {},
     options?: RequestOptions,
-  ): APIPromise<SenderListResponse> {
-    return this._client.get('/v1/senders', { query, ...options });
+  ): PagePromise<SendersCursor, Sender> {
+    return this._client.getAPIList('/v1/senders', Cursor<Sender>, { query, ...options });
   }
 
   /**
@@ -49,6 +50,8 @@ export class Senders extends APIResource {
   }
 }
 
+export type SendersCursor = Cursor<Sender>;
+
 export interface Sender {
   id: string;
 
@@ -69,12 +72,6 @@ export interface Sender {
   updatedAt?: string;
 }
 
-export interface SenderListResponse {
-  items: Array<Sender>;
-
-  nextCursor?: string | null;
-}
-
 export interface SenderCreateParams {
   name: string;
 
@@ -89,16 +86,12 @@ export interface SenderUpdateParams {
   setAsDefault?: boolean;
 }
 
-export interface SenderListParams {
-  cursor?: string;
-
-  limit?: number;
-}
+export interface SenderListParams extends CursorParams {}
 
 export declare namespace Senders {
   export {
     type Sender as Sender,
-    type SenderListResponse as SenderListResponse,
+    type SendersCursor as SendersCursor,
     type SenderCreateParams as SenderCreateParams,
     type SenderUpdateParams as SenderUpdateParams,
     type SenderListParams as SenderListParams,

package/src/resources/templates.ts

@@ -2,6 +2,7 @@
 
 import { APIResource } from '../core/resource';
 import { APIPromise } from '../core/api-promise';
+import { Cursor, type CursorParams, PagePromise } from '../core/pagination';
 import { buildHeaders } from '../internal/headers';
 import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
@@ -45,14 +46,17 @@ export class Templates extends APIResource {
    *
    * @example
    * ```ts
-   * const templates = await client.templates.list();
+   * // Automatically fetches more pages as needed.
+   * for await (const template of client.templates.list()) {
+   *   // ...
+   * }
    * ```
    */
   list(
     query: TemplateListParams | null | undefined = {},
     options?: RequestOptions,
-  ): APIPromise<TemplateListResponse> {
-    return this._client.get('/v1/templates', { query, ...options });
+  ): PagePromise<TemplatesCursor, Template> {
+    return this._client.getAPIList('/v1/templates', Cursor<Template>, { query, ...options });
   }
 
   /**
@@ -71,6 +75,8 @@ export class Templates extends APIResource {
   }
 }
 
+export type TemplatesCursor = Cursor<Template>;
+
 export interface Template {
   id: string;
 
@@ -168,12 +174,6 @@ export namespace Template {
  */
 export type WhatsappCategory = 'UTILITY' | 'MARKETING' | 'AUTHENTICATION';
 
-export interface TemplateListResponse {
-  items: Array<Template>;
-
-  nextCursor?: string | null;
-}
-
 export interface TemplateCreateParams {
   body: string;
 
@@ -189,17 +189,13 @@ export interface TemplateCreateParams {
   whatsappCategory?: WhatsappCategory;
 }
 
-export interface TemplateListParams {
-  cursor?: string;
-
-  limit?: number;
-}
+export interface TemplateListParams extends CursorParams {}
 
 export declare namespace Templates {
   export {
     type Template as Template,
     type WhatsappCategory as WhatsappCategory,
-    type TemplateListResponse as TemplateListResponse,
+    type TemplatesCursor as TemplatesCursor,
     type TemplateCreateParams as TemplateCreateParams,
     type TemplateListParams as TemplateListParams,
   };

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.5.0'; // x-release-please-version
+export const VERSION = '0.7.0'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.5.0";
+export declare const VERSION = "0.7.0";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.5.0";
+export declare const VERSION = "0.7.0";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.5.0'; // x-release-please-version
+exports.VERSION = '0.7.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '0.5.0'; // x-release-please-version
+export const VERSION = '0.7.0'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map