@surgeapi/node 0.34.0 → 0.36.0

package/src/core/pagination.ts

@@ -0,0 +1,176 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { SurgeError } from './error';
+import { FinalRequestOptions } from '../internal/request-options';
+import { defaultParseResponse } from '../internal/parse';
+import { type Surge } 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: Surge;
+  protected options: FinalRequestOptions;
+
+  protected response: Response;
+  protected body: unknown;
+
+  constructor(client: Surge, 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 SurgeError(
+        '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: Surge,
+    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> {
+  data: Array<Item>;
+
+  pagination: CursorResponse.Pagination;
+}
+
+export namespace CursorResponse {
+  export interface Pagination {
+    next_cursor?: string;
+
+    previous_cursor?: string;
+  }
+}
+
+export interface CursorParams {
+  after?: string;
+
+  before?: string;
+}
+
+export class Cursor<Item> extends AbstractPage<Item> implements CursorResponse<Item> {
+  data: Array<Item>;
+
+  pagination: CursorResponse.Pagination;
+
+  constructor(client: Surge, response: Response, body: CursorResponse<Item>, options: FinalRequestOptions) {
+    super(client, response, body, options);
+
+    this.data = body.data || [];
+    this.pagination = body.pagination || {};
+  }
+
+  getPaginatedItems(): Item[] {
+    return this.data ?? [];
+  }
+
+  nextPageRequestOptions(): PageRequestOptions | null {
+    if ((this.options.query as Record<string, unknown>)?.['before']) {
+      // in reverse
+      const previous_cursor = this.pagination?.previous_cursor;
+      if (!previous_cursor) {
+        return null;
+      }
+
+      return {
+        ...this.options,
+        query: {
+          ...maybeObj(this.options.query),
+          before: previous_cursor,
+        },
+      };
+    }
+
+    const cursor = this.pagination?.next_cursor;
+    if (!cursor) {
+      return null;
+    }
+
+    return {
+      ...this.options,
+      query: {
+        ...maybeObj(this.options.query),
+        after: cursor,
+      },
+    };
+  }
+}

package/src/index.ts

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

package/src/internal/parse.ts

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

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

package/src/resources/blasts.ts

@@ -35,7 +35,7 @@ export interface Blast {
   /**
    * The message body.
    */
-  body?: string;
+  body?: string | null;
 
   /**
    * Optional name for the blast.
@@ -63,10 +63,10 @@ export interface BlastCreateParams {
   /**
    * The message body.
    */
-  body?: string;
+  body?: string | null;
 
   /**
-   * @deprecated Deprecated. Use `to` instead.
+   * @deprecated Use `to` to specify recipients instead.
    */
   contacts?: Array<string>;
 
@@ -83,7 +83,7 @@ export interface BlastCreateParams {
   name?: string;
 
   /**
-   * @deprecated Deprecated. Use `to` instead.
+   * @deprecated Use `to` to specify recipients instead.
    */
   segments?: Array<string>;
 

package/src/resources/campaigns.ts

@@ -37,6 +37,20 @@ export class Campaigns extends APIResource {
   create(accountID: string, body: CampaignCreateParams, options?: RequestOptions): APIPromise<Campaign> {
     return this._client.post(path`/accounts/${accountID}/campaigns`, { body, ...options });
   }
+
+  /**
+   * Retrieves a Campaign object.
+   *
+   * @example
+   * ```ts
+   * const campaign = await client.campaigns.retrieve(
+   *   'cpn_01k0qczvhbet4azgn5xm2ccfst',
+   * );
+   * ```
+   */
+  retrieve(id: string, options?: RequestOptions): APIPromise<Campaign> {
+    return this._client.get(path`/campaigns/${id}`, options);
+  }
 }
 
 /**
@@ -94,6 +108,11 @@ export interface Campaign {
    */
   privacy_policy_url: string;
 
+  /**
+   * The current status of the campaign.
+   */
+  status: 'active' | 'canceled' | 'created' | 'deactivated' | 'in_review' | 'pending' | 'rejected';
+
   /**
    * A list containing 1-5 types of messages that will be sent with this campaign.
    *

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';
 
@@ -50,8 +51,34 @@ export class Contacts extends APIResource {
   update(id: string, body: ContactUpdateParams, options?: RequestOptions): APIPromise<Contact> {
     return this._client.patch(path`/contacts/${id}`, { body, ...options });
   }
+
+  /**
+   * List all contacts for an account with cursor-based pagination.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const contact of client.contacts.list(
+   *   'acct_01j9a43avnfqzbjfch6pygv1td',
+   * )) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    accountID: string,
+    query: ContactListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<ContactsCursor, Contact> {
+    return this._client.getAPIList(path`/accounts/${accountID}/contacts`, Cursor<Contact>, {
+      query,
+      ...options,
+    });
+  }
 }
 
+export type ContactsCursor = Cursor<Contact>;
+
 /**
  * A contact who has consented to receive messages
  */
@@ -141,10 +168,14 @@ export interface ContactUpdateParams {
   metadata?: { [key: string]: string };
 }
 
+export interface ContactListParams extends CursorParams {}
+
 export declare namespace Contacts {
   export {
     type Contact as Contact,
+    type ContactsCursor as ContactsCursor,
     type ContactCreateParams as ContactCreateParams,
     type ContactUpdateParams as ContactUpdateParams,
+    type ContactListParams as ContactListParams,
   };
 }

package/src/resources/index.ts

@@ -12,9 +12,29 @@ export {
 } from './accounts';
 export { Blasts, type Blast, type BlastCreateParams } from './blasts';
 export { Campaigns, type Campaign, type CampaignCreateParams } from './campaigns';
-export { Contacts, type Contact, type ContactCreateParams, type ContactUpdateParams } from './contacts';
-export { Messages, type Message, type MessageCreateParams } from './messages';
-export { PhoneNumbers, type PhoneNumber, type PhoneNumberPurchaseParams } from './phone-numbers';
+export {
+  Contacts,
+  type Contact,
+  type ContactCreateParams,
+  type ContactUpdateParams,
+  type ContactListParams,
+  type ContactsCursor,
+} from './contacts';
+export {
+  Messages,
+  type Message,
+  type MessageCreateParams,
+  type MessageListParams,
+  type MessagesCursor,
+} from './messages';
+export {
+  PhoneNumbers,
+  type PhoneNumber,
+  type PhoneNumberListParams,
+  type PhoneNumberPurchaseParams,
+  type PhoneNumbersCursor,
+} from './phone-numbers';
+export { Recordings, type RecordingGetFileResponse } from './recordings';
 export {
   Users,
   type User,
@@ -42,5 +62,7 @@ export {
   type MessageFailedWebhookEvent,
   type MessageReceivedWebhookEvent,
   type MessageSentWebhookEvent,
+  type RecordingCompletedWebhookEvent,
+  type VoicemailReceivedWebhookEvent,
   type UnwrapWebhookEvent,
 } from './webhooks';

package/src/resources/messages.ts

@@ -3,6 +3,7 @@
 import { APIResource } from '../core/resource';
 import * as ContactsAPI from './contacts';
 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';
 
@@ -63,8 +64,34 @@ export class Messages extends APIResource {
   retrieve(id: string, options?: RequestOptions): APIPromise<Message> {
     return this._client.get(path`/messages/${id}`, options);
   }
+
+  /**
+   * List all messages for an account with cursor-based pagination.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const message of client.messages.list(
+   *   'acct_01j9a43avnfqzbjfch6pygv1td',
+   * )) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    accountID: string,
+    query: MessageListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<MessagesCursor, Message> {
+    return this._client.getAPIList(path`/accounts/${accountID}/messages`, Cursor<Message>, {
+      query,
+      ...options,
+    });
+  }
 }
 
+export type MessagesCursor = Cursor<Message>;
+
 /**
  * A Message is a communication sent to a Contact.
  */
@@ -80,12 +107,12 @@ export interface Message {
    * The ID of the blast this message belongs to, if any. This can be used to
    * attribute messages back to a specific blast.
    */
-  blast_id?: string;
+  blast_id?: string | null;
 
   /**
    * The message body.
    */
-  body?: string;
+  body?: string | null;
 
   /**
    * A conversation with a Contact
@@ -299,6 +326,13 @@ export declare namespace MessageCreateParams {
   }
 }
 
+export interface MessageListParams extends CursorParams {}
+
 export declare namespace Messages {
-  export { type Message as Message, type MessageCreateParams as MessageCreateParams };
+  export {
+    type Message as Message,
+    type MessagesCursor as MessagesCursor,
+    type MessageCreateParams as MessageCreateParams,
+    type MessageListParams as MessageListParams,
+  };
 }

package/src/resources/phone-numbers.ts

@@ -2,10 +2,35 @@
 
 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';
 
 export class PhoneNumbers extends APIResource {
+  /**
+   * List all phone numbers for an account with cursor-based pagination.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const phoneNumber of client.phoneNumbers.list(
+   *   'acct_01j9a43avnfqzbjfch6pygv1td',
+   * )) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    accountID: string,
+    query: PhoneNumberListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<PhoneNumbersCursor, PhoneNumber> {
+    return this._client.getAPIList(path`/accounts/${accountID}/phone_numbers`, Cursor<PhoneNumber>, {
+      query,
+      ...options,
+    });
+  }
+
   /**
    * Purchase a new phone number for the account. You can specify search criteria or
    * let the system select a random number.
@@ -26,6 +51,8 @@ export class PhoneNumbers extends APIResource {
   }
 }
 
+export type PhoneNumbersCursor = Cursor<PhoneNumber>;
+
 /**
  * A phone number that can be used to send and receive messages and calls
  */
@@ -46,6 +73,8 @@ export interface PhoneNumber {
   type: 'local' | 'short_code' | 'toll_free';
 }
 
+export interface PhoneNumberListParams extends CursorParams {}
+
 export interface PhoneNumberPurchaseParams {
   /**
    * The desired area code for this phone number. If provided without type, the type
@@ -73,5 +102,10 @@ export interface PhoneNumberPurchaseParams {
 }
 
 export declare namespace PhoneNumbers {
-  export { type PhoneNumber as PhoneNumber, type PhoneNumberPurchaseParams as PhoneNumberPurchaseParams };
+  export {
+    type PhoneNumber as PhoneNumber,
+    type PhoneNumbersCursor as PhoneNumbersCursor,
+    type PhoneNumberListParams as PhoneNumberListParams,
+    type PhoneNumberPurchaseParams as PhoneNumberPurchaseParams,
+  };
 }

package/src/resources/recordings.ts

@@ -0,0 +1,38 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import * as Shared from './shared';
+import { APIPromise } from '../core/api-promise';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+export class Recordings extends APIResource {
+  /**
+   * Redirects to a signed URL where the recording audio file can be downloaded. URL
+   * is short-lived, so redirect should be followed immediately.
+   *
+   * @example
+   * ```ts
+   * const response = await client.recordings.getFile(
+   *   'rec_01kfyc9dgdec1avkgs7tng8htg',
+   * );
+   * ```
+   */
+  getFile(recordingID: string, options?: RequestOptions): APIPromise<RecordingGetFileResponse> {
+    return this._client.get(path`/recordings/${recordingID}/file`, options);
+  }
+}
+
+/**
+ * An error response
+ */
+export interface RecordingGetFileResponse {
+  /**
+   * An error response
+   */
+  error: Shared.Error;
+}
+
+export declare namespace Recordings {
+  export { type RecordingGetFileResponse as RecordingGetFileResponse };
+}