@surgeapi/node 0.25.6 → 0.26.0

package/src/resources/contacts.ts

@@ -0,0 +1,181 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+export class Contacts extends APIResource {
+  /**
+   * Creates a new Contact object.
+   *
+   * @example
+   * ```ts
+   * const contact = await client.contacts.create(
+   *   'acct_01j9a43avnfqzbjfch6pygv1td',
+   *   { phone_number: '+18015551234' },
+   * );
+   * ```
+   */
+  create(accountID: string, body: ContactCreateParams, options?: RequestOptions): APIPromise<Contact> {
+    return this._client.post(path`/accounts/${accountID}/contacts`, { body, ...options });
+  }
+
+  /**
+   * Retrieves a Contact object.
+   *
+   * @example
+   * ```ts
+   * const contact = await client.contacts.retrieve(
+   *   'ctc_01j9dy8mdzfn3r0e8x1tbdrdrf',
+   * );
+   * ```
+   */
+  retrieve(id: string, options?: RequestOptions): APIPromise<Contact> {
+    return this._client.get(path`/contacts/${id}`, options);
+  }
+
+  /**
+   * Updates the specified contact by setting the values of the parameters passed.
+   * Any parameters not provided will be left unchanged.
+   *
+   * @example
+   * ```ts
+   * const contact = await client.contacts.update(
+   *   'ctc_01j9dy8mdzfn3r0e8x1tbdrdrf',
+   *   { phone_number: '+18015551234' },
+   * );
+   * ```
+   */
+  update(id: string, body: ContactUpdateParams, options?: RequestOptions): APIPromise<Contact> {
+    return this._client.patch(path`/contacts/${id}`, { body, ...options });
+  }
+}
+
+/**
+ * A contact who has consented to receive messages
+ */
+export interface Contact {
+  /**
+   * Unique identifier for the object.
+   */
+  id: string;
+
+  /**
+   * The contact's phone number in E.164 format.
+   */
+  phone_number: string;
+
+  /**
+   * The contact's email address.
+   */
+  email?: string;
+
+  /**
+   * The contact's first name.
+   */
+  first_name?: string;
+
+  /**
+   * The contact's last name.
+   */
+  last_name?: string;
+
+  /**
+   * Set of key-value pairs that will be stored with the object.
+   */
+  metadata?: { [key: string]: string };
+}
+
+/**
+ * Parameters for creating a contact
+ */
+export interface ContactParams {
+  /**
+   * The contact's phone number in E.164 format.
+   */
+  phone_number: string;
+
+  /**
+   * The contact's email address.
+   */
+  email?: string;
+
+  /**
+   * The contact's first name.
+   */
+  first_name?: string;
+
+  /**
+   * The contact's last name.
+   */
+  last_name?: string;
+
+  /**
+   * Set of key-value pairs that will be stored with the object.
+   */
+  metadata?: { [key: string]: string };
+}
+
+export interface ContactCreateParams {
+  /**
+   * The contact's phone number in E.164 format.
+   */
+  phone_number: string;
+
+  /**
+   * The contact's email address.
+   */
+  email?: string;
+
+  /**
+   * The contact's first name.
+   */
+  first_name?: string;
+
+  /**
+   * The contact's last name.
+   */
+  last_name?: string;
+
+  /**
+   * Set of key-value pairs that will be stored with the object.
+   */
+  metadata?: { [key: string]: string };
+}
+
+export interface ContactUpdateParams {
+  /**
+   * The contact's phone number in E.164 format.
+   */
+  phone_number: string;
+
+  /**
+   * The contact's email address.
+   */
+  email?: string;
+
+  /**
+   * The contact's first name.
+   */
+  first_name?: string;
+
+  /**
+   * The contact's last name.
+   */
+  last_name?: string;
+
+  /**
+   * Set of key-value pairs that will be stored with the object.
+   */
+  metadata?: { [key: string]: string };
+}
+
+export declare namespace Contacts {
+  export {
+    type Contact as Contact,
+    type ContactParams as ContactParams,
+    type ContactCreateParams as ContactCreateParams,
+    type ContactUpdateParams as ContactUpdateParams,
+  };
+}

package/src/resources/index.ts

@@ -0,0 +1,60 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './shared';
+export {
+  Accounts,
+  type Account,
+  type AccountParams,
+  type AccountStatus,
+  type AccountUpdateParams,
+  type Organization,
+  type OrganizationParams,
+  type AccountCreateParams,
+  type AccountRetrieveStatusParams,
+} from './accounts';
+export { Blasts, type Blast, type BlastParams, type BlastCreateParams } from './blasts';
+export { Campaigns, type Campaign, type CampaignParams, type CampaignCreateParams } from './campaigns';
+export {
+  Contacts,
+  type Contact,
+  type ContactParams,
+  type ContactCreateParams,
+  type ContactUpdateParams,
+} from './contacts';
+export {
+  Messages,
+  type AttachmentParams,
+  type Message,
+  type MessageParams,
+  type MessageCreateParams,
+} from './messages';
+export { PhoneNumbers, type PhoneNumber, type PhoneNumberPurchaseParams } from './phone-numbers';
+export {
+  Users,
+  type User,
+  type UserParams,
+  type UserTokenParams,
+  type UserTokenResponse,
+  type UserCreateParams,
+  type UserUpdateParams,
+  type UserCreateTokenParams,
+} from './users';
+export {
+  Verifications,
+  type Verification,
+  type VerificationCheck,
+  type VerificationCheckParams,
+  type VerificationParams,
+  type VerificationCreateParams,
+} from './verifications';
+export {
+  Webhooks,
+  type CallEndedWebhookEvent,
+  type CampaignApprovedWebhookEvent,
+  type ConversationCreatedWebhookEvent,
+  type MessageDeliveredWebhookEvent,
+  type MessageFailedWebhookEvent,
+  type MessageReceivedWebhookEvent,
+  type MessageSentWebhookEvent,
+  type UnwrapWebhookEvent,
+} from './webhooks';

package/src/resources/messages.ts

@@ -0,0 +1,314 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import * as MessagesAPI from './messages';
+import * as ContactsAPI from './contacts';
+import { APIPromise } from '../core/api-promise';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+export class Messages extends APIResource {
+  /**
+   * Creates and enqueues a new message to be sent.
+   *
+   * Messages are always sent asynchronously. When you hit this endpoint, the message
+   * will be created within Surge's system and enqueued for sending, and then the id
+   * for the new message will be returned. When the message is actually sent, a
+   * `message.sent` webhook event will be triggered and sent to any webhook endpoints
+   * that you have subscribed to this event type. Then a `message.delivered` webhook
+   * event will be triggered when the carrier sends us a delivery receipt.
+   *
+   * By default all messages will be sent immediately. If you would like to schedule
+   * sending for some time up to 60 days in the future, you can do that by providing
+   * a value for the `send_at` field. This should be formatted as an ISO8601 datetime
+   * like `2028-10-14T18:06:00Z`.
+   *
+   * You must include either a `body` or `attachments` field (or both) in the request
+   * body. The `body` field should contain the text of the message you want to send,
+   * and the `attachments` field should be an array of objects with a `url` field
+   * pointing to the file you want to attach. Surge will download these files and
+   * send them as attachments in the message.
+   *
+   * You can provide either a `conversation` object or a `to` field to specify the
+   * intended recipient of the message, but an error will be returned if both fields
+   * are provided. Similarly the `from` field cannot be used together with the
+   * `conversation` field, and `conversation.phone_number` should be specified
+   * instead.
+   *
+   * @example
+   * ```ts
+   * const message = await client.messages.create(
+   *   'acct_01j9a43avnfqzbjfch6pygv1td',
+   *   {
+   *     conversation: {
+   *       contact: { phone_number: '+18015551234' },
+   *     },
+   *   },
+   * );
+   * ```
+   */
+  create(accountID: string, body: MessageCreateParams, options?: RequestOptions): APIPromise<Message> {
+    return this._client.post(path`/accounts/${accountID}/messages`, { body, ...options });
+  }
+}
+
+/**
+ * Params for creating an attachment
+ */
+export interface AttachmentParams {
+  /**
+   * The URL of the attachment.
+   */
+  url: string;
+}
+
+/**
+ * A Message is a communication sent to a Contact.
+ */
+export interface Message {
+  /**
+   * Unique identifier for the object.
+   */
+  id?: string;
+
+  attachments?: Array<Message.Attachment>;
+
+  /**
+   * The message body.
+   */
+  body?: string;
+
+  /**
+   * A conversation with a Contact
+   */
+  conversation?: Message.Conversation;
+}
+
+export namespace Message {
+  /**
+   * An Attachment is a file that can be sent with a message.
+   */
+  export interface Attachment {
+    /**
+     * Unique identifier for the object.
+     */
+    id?: string;
+
+    /**
+     * The type of attachment.
+     */
+    type?: string;
+
+    /**
+     * The URL of the attachment.
+     */
+    url?: string;
+  }
+
+  /**
+   * A conversation with a Contact
+   */
+  export interface Conversation {
+    /**
+     * Unique identifier for the object.
+     */
+    id: string;
+
+    /**
+     * A contact who has consented to receive messages
+     */
+    contact: ContactsAPI.Contact;
+
+    /**
+     * This is the phone number tied to the Surge account.
+     */
+    phone_number?: Conversation.PhoneNumber;
+  }
+
+  export namespace Conversation {
+    /**
+     * This is the phone number tied to the Surge account.
+     */
+    export interface PhoneNumber {
+      /**
+       * Unique identifier for the phone number
+       */
+      id: string;
+
+      /**
+       * The canonical format of the phone number.
+       */
+      number: string;
+
+      /**
+       * Whether the phone number is local, toll-free, or short code
+       */
+      type: 'local' | 'toll_free' | 'short_code' | 'demo';
+    }
+  }
+}
+
+/**
+ * Payload for creating a message. Either an attachment or the body must be given.
+ * You can specify the recipient either using the 'conversation' parameter or the
+ * 'to'/'from' parameters, but not both.
+ */
+export type MessageParams = MessageParams.MessageParamsWithConversation | MessageParams.SimpleMessageParams;
+
+export namespace MessageParams {
+  /**
+   * Create a message while including parameters for the conversation in which the
+   * message should be sent.
+   */
+  export interface MessageParamsWithConversation {
+    /**
+     * Params for selecting or creating a new conversation. Either the id or the
+     * Contact must be given.
+     */
+    conversation: MessageParamsWithConversation.Conversation;
+
+    attachments?: Array<MessagesAPI.AttachmentParams>;
+
+    /**
+     * The message body.
+     */
+    body?: string;
+
+    /**
+     * An optional datetime for scheduling message up to a couple of months in the
+     * future.
+     */
+    send_at?: string;
+  }
+
+  export namespace MessageParamsWithConversation {
+    /**
+     * Params for selecting or creating a new conversation. Either the id or the
+     * Contact must be given.
+     */
+    export interface Conversation {
+      /**
+       * Parameters for creating a contact
+       */
+      contact: ContactsAPI.ContactParams;
+
+      /**
+       * The phone number from which to send the message. This can be either the phone
+       * number in E.164 format or a Surge phone number id.
+       */
+      phone_number?: string;
+    }
+  }
+
+  /**
+   * Create a basic message by specifying just the to/from phone numbers.
+   */
+  export interface SimpleMessageParams {
+    /**
+     * The recipient's phone number in E.164 format. Cannot be used together with
+     * 'conversation'.
+     */
+    to: string;
+
+    attachments?: Array<MessagesAPI.AttachmentParams>;
+
+    /**
+     * The message body.
+     */
+    body?: string;
+
+    /**
+     * The sender's phone number in E.164 format or phone number ID. If omitted, uses
+     * the account's default phone number. Cannot be used together with 'conversation'.
+     */
+    from?: string;
+
+    /**
+     * An optional datetime for scheduling message up to a couple of months in the
+     * future.
+     */
+    send_at?: string;
+  }
+}
+
+export type MessageCreateParams =
+  | MessageCreateParams.MessageParamsWithConversation
+  | MessageCreateParams.SimpleMessageParams;
+
+export declare namespace MessageCreateParams {
+  export interface MessageParamsWithConversation {
+    /**
+     * Params for selecting or creating a new conversation. Either the id or the
+     * Contact must be given.
+     */
+    conversation: MessageParamsWithConversation.Conversation;
+
+    attachments?: Array<AttachmentParams>;
+
+    /**
+     * The message body.
+     */
+    body?: string;
+
+    /**
+     * An optional datetime for scheduling message up to a couple of months in the
+     * future.
+     */
+    send_at?: string;
+  }
+
+  export namespace MessageParamsWithConversation {
+    /**
+     * Params for selecting or creating a new conversation. Either the id or the
+     * Contact must be given.
+     */
+    export interface Conversation {
+      /**
+       * Parameters for creating a contact
+       */
+      contact: ContactsAPI.ContactParams;
+
+      /**
+       * The phone number from which to send the message. This can be either the phone
+       * number in E.164 format or a Surge phone number id.
+       */
+      phone_number?: string;
+    }
+  }
+
+  export interface SimpleMessageParams {
+    /**
+     * The recipient's phone number in E.164 format. Cannot be used together with
+     * 'conversation'.
+     */
+    to: string;
+
+    attachments?: Array<AttachmentParams>;
+
+    /**
+     * The message body.
+     */
+    body?: string;
+
+    /**
+     * The sender's phone number in E.164 format or phone number ID. If omitted, uses
+     * the account's default phone number. Cannot be used together with 'conversation'.
+     */
+    from?: string;
+
+    /**
+     * An optional datetime for scheduling message up to a couple of months in the
+     * future.
+     */
+    send_at?: string;
+  }
+}
+
+export declare namespace Messages {
+  export {
+    type AttachmentParams as AttachmentParams,
+    type Message as Message,
+    type MessageParams as MessageParams,
+    type MessageCreateParams as MessageCreateParams,
+  };
+}

package/src/resources/phone-numbers.ts

@@ -0,0 +1,111 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+export class PhoneNumbers extends APIResource {
+  /**
+   * Purchase a new phone number for the account. You can specify search criteria or
+   * let the system select a random number.
+   *
+   * @example
+   * ```ts
+   * const phoneNumber = await client.phoneNumbers.purchase(
+   *   'acct_01j9a43avnfqzbjfch6pygv1td',
+   * );
+   * ```
+   */
+  purchase(
+    accountID: string,
+    body: PhoneNumberPurchaseParams,
+    options?: RequestOptions,
+  ): APIPromise<PhoneNumber> {
+    return this._client.post(path`/accounts/${accountID}/phone_numbers`, { body, ...options });
+  }
+}
+
+/**
+ * A phone number that can be used to send and receive messages and calls
+ */
+export interface PhoneNumber {
+  /**
+   * Unique identifier for the phone number
+   */
+  id: string;
+
+  /**
+   * The phone number in E.164 format
+   */
+  number: string;
+
+  /**
+   * Whether the phone number is local, toll-free, or short code
+   */
+  type: 'local' | 'toll_free';
+}
+
+/**
+ * Parameters for purchasing a new phone number. The system will automatically
+ * infer the type in certain cases:
+ *
+ * - If only area_code is provided, type is inferred from the area code
+ * - If only latitude/longitude are provided, type is inferred as 'local'
+ * - Otherwise, type must be explicitly specified
+ */
+export interface PhoneNumberPurchaseParams {
+  /**
+   * The desired area code for this phone number. If provided without type, the type
+   * will be inferred.
+   */
+  area_code?: string;
+
+  /**
+   * Latitude to search for nearby phone numbers. Must be used with longitude. If
+   * provided without type, type will be inferred as 'local'.
+   */
+  latitude?: number;
+
+  /**
+   * Longitude to search for nearby phone numbers. Must be used with latitude. If
+   * provided without type, type will be inferred as 'local'.
+   */
+  longitude?: number;
+
+  /**
+   * Whether the phone number is local or toll-free. Can be omitted if area_code or
+   * latitude/longitude are provided.
+   */
+  type?: 'local' | 'toll_free';
+}
+
+export interface PhoneNumberPurchaseParams {
+  /**
+   * The desired area code for this phone number. If provided without type, the type
+   * will be inferred.
+   */
+  area_code?: string;
+
+  /**
+   * Latitude to search for nearby phone numbers. Must be used with longitude. If
+   * provided without type, type will be inferred as 'local'.
+   */
+  latitude?: number;
+
+  /**
+   * Longitude to search for nearby phone numbers. Must be used with latitude. If
+   * provided without type, type will be inferred as 'local'.
+   */
+  longitude?: number;
+
+  /**
+   * Whether the phone number is local or toll-free. Can be omitted if area_code or
+   * latitude/longitude are provided.
+   */
+  type?: 'local' | 'toll_free';
+}
+
+export declare namespace PhoneNumbers {
+  export { type PhoneNumber as PhoneNumber, type PhoneNumberPurchaseParams as PhoneNumberPurchaseParams };
+}

package/src/resources/shared.ts

@@ -0,0 +1,21 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+/**
+ * An error response
+ */
+export interface Error {
+  /**
+   * A human-readable error message.
+   */
+  message: string;
+
+  /**
+   * A unique error code.
+   */
+  type: string;
+
+  /**
+   * Additional details about the error.
+   */
+  detail?: { [key: string]: unknown };
+}