@surgeapi/node 0.25.7 → 0.27.0

package/src/resources/messages.ts

@@ -0,0 +1,269 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+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 });
+  }
+}
+
+/**
+ * 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';
+    }
+  }
+}
+
+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<MessageParamsWithConversation.Attachment>;
+
+    /**
+     * 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: Conversation.Contact;
+
+      /**
+       * 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 namespace Conversation {
+      /**
+       * Parameters for creating a contact
+       */
+      export interface Contact {
+        /**
+         * 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 };
+      }
+    }
+
+    /**
+     * Params for creating an attachment
+     */
+    export interface Attachment {
+      /**
+       * The URL of the attachment.
+       */
+      url: string;
+    }
+  }
+
+  export interface SimpleMessageParams {
+    /**
+     * The recipient's phone number in E.164 format. Cannot be used together with
+     * 'conversation'.
+     */
+    to: string;
+
+    attachments?: Array<SimpleMessageParams.Attachment>;
+
+    /**
+     * 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 namespace SimpleMessageParams {
+    /**
+     * Params for creating an attachment
+     */
+    export interface Attachment {
+      /**
+       * The URL of the attachment.
+       */
+      url: string;
+    }
+  }
+}
+
+export declare namespace Messages {
+  export { type Message as Message, type MessageCreateParams as MessageCreateParams };
+}

package/src/resources/phone-numbers.ts

@@ -0,0 +1,77 @@
+// 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';
+}
+
+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 };
+}

package/src/resources/users.ts

@@ -0,0 +1,172 @@
+// 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 Users extends APIResource {
+  /**
+   * Creates a new User object.
+   *
+   * @example
+   * ```ts
+   * const user = await client.users.create(
+   *   'acct_01j9a43avnfqzbjfch6pygv1td',
+   *   { first_name: 'Brian' },
+   * );
+   * ```
+   */
+  create(accountID: string, body: UserCreateParams, options?: RequestOptions): APIPromise<User> {
+    return this._client.post(path`/accounts/${accountID}/users`, { body, ...options });
+  }
+
+  /**
+   * Retrieves a User object.
+   *
+   * @example
+   * ```ts
+   * const user = await client.users.retrieve(
+   *   'usr_01j9dwavghe1ttppewekjjkfrx',
+   * );
+   * ```
+   */
+  retrieve(id: string, options?: RequestOptions): APIPromise<User> {
+    return this._client.get(path`/users/${id}`, options);
+  }
+
+  /**
+   * Updates an existing User object.
+   *
+   * @example
+   * ```ts
+   * const user = await client.users.update(
+   *   'usr_01j9dwavghe1ttppewekjjkfrx',
+   *   { first_name: 'Brian' },
+   * );
+   * ```
+   */
+  update(id: string, body: UserUpdateParams, options?: RequestOptions): APIPromise<User> {
+    return this._client.patch(path`/users/${id}`, { body, ...options });
+  }
+
+  /**
+   * Provides a mechanism for having Surge create a signed token for embeds instead
+   * of signing with your own signing key.
+   *
+   * @example
+   * ```ts
+   * const userTokenResponse = await client.users.createToken(
+   *   'usr_01jymgdfrpec2asc5m0z3a6fr9',
+   * );
+   * ```
+   */
+  createToken(
+    userID: string,
+    body: UserCreateTokenParams,
+    options?: RequestOptions,
+  ): APIPromise<UserTokenResponse> {
+    return this._client.post(path`/users/${userID}/tokens`, { body, ...options });
+  }
+}
+
+/**
+ * A user of the app
+ */
+export interface User {
+  /**
+   * The user's first name.
+   */
+  first_name: string;
+
+  /**
+   * Unique identifier for the object.
+   */
+  id?: string;
+
+  /**
+   * The user's last name.
+   */
+  last_name?: string;
+
+  /**
+   * Set of key-value pairs that will be stored with the object.
+   */
+  metadata?: { [key: string]: string };
+
+  /**
+   * URL of a photo to be used as the user's avatar.
+   */
+  photo_url?: string;
+}
+
+/**
+ * Response when token has been created successfully
+ */
+export interface UserTokenResponse {
+  /**
+   * The created token.
+   */
+  token?: string;
+}
+
+export interface UserCreateParams {
+  /**
+   * The user's first name.
+   */
+  first_name: string;
+
+  /**
+   * The user's last name.
+   */
+  last_name?: string;
+
+  /**
+   * Set of key-value pairs that will be stored with the object.
+   */
+  metadata?: { [key: string]: string };
+
+  /**
+   * URL of a photo to be used as the user's avatar.
+   */
+  photo_url?: string;
+}
+
+export interface UserUpdateParams {
+  /**
+   * The user's first name.
+   */
+  first_name: string;
+
+  /**
+   * The user's last name.
+   */
+  last_name?: string;
+
+  /**
+   * Set of key-value pairs that will be stored with the object.
+   */
+  metadata?: { [key: string]: string };
+
+  /**
+   * URL of a photo to be used as the user's avatar.
+   */
+  photo_url?: string;
+}
+
+export interface UserCreateTokenParams {
+  /**
+   * For how many seconds the token should be accepted. Defaults to 15 minutes.
+   */
+  duration_seconds?: number;
+}
+
+export declare namespace Users {
+  export {
+    type User as User,
+    type UserTokenResponse as UserTokenResponse,
+    type UserCreateParams as UserCreateParams,
+    type UserUpdateParams as UserUpdateParams,
+    type UserCreateTokenParams as UserCreateTokenParams,
+  };
+}

package/src/resources/verifications.ts

@@ -0,0 +1,100 @@
+// 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 Verifications extends APIResource {
+  /**
+   * Creates a new Verification and sends the code to the given phone number.
+   *
+   * @example
+   * ```ts
+   * const verification = await client.verifications.create({
+   *   phone_number: '+18015551234',
+   * });
+   * ```
+   */
+  create(body: VerificationCreateParams, options?: RequestOptions): APIPromise<Verification> {
+    return this._client.post('/verifications', { body, ...options });
+  }
+
+  /**
+   * Checks the code against a verification.
+   *
+   * @example
+   * ```ts
+   * const verificationCheck = await client.verifications.check(
+   *   'vfn_01jayh15c2f2xamftg0xpyq1nj',
+   *   { code: '123456' },
+   * );
+   * ```
+   */
+  check(id: string, body: VerificationCheckParams, options?: RequestOptions): APIPromise<VerificationCheck> {
+    return this._client.post(path`/verifications/${id}/checks`, { body, ...options });
+  }
+}
+
+/**
+ * A phone number verification
+ */
+export interface Verification {
+  /**
+   * Unique identifier for the object.
+   */
+  id: string;
+
+  /**
+   * The number of times the code has been attempted.
+   */
+  attempt_count: number;
+
+  /**
+   * The phone number being verified. In E.164 format.
+   */
+  phone_number: string;
+
+  /**
+   * The current status of the verification.
+   */
+  status: 'pending' | 'verified' | 'exhausted' | 'expired';
+}
+
+/**
+ * The result of checking a Verification code
+ */
+export interface VerificationCheck {
+  /**
+   * The result of the code check.
+   */
+  result?: 'ok' | 'incorrect' | 'exhausted' | 'expired' | 'already_verified';
+
+  /**
+   * A phone number verification
+   */
+  verification?: Verification;
+}
+
+export interface VerificationCreateParams {
+  /**
+   * The phone number to be verified. In E.164 format.
+   */
+  phone_number: string;
+}
+
+export interface VerificationCheckParams {
+  /**
+   * The Verification code that was received.
+   */
+  code: string;
+}
+
+export declare namespace Verifications {
+  export {
+    type Verification as Verification,
+    type VerificationCheck as VerificationCheck,
+    type VerificationCreateParams as VerificationCreateParams,
+    type VerificationCheckParams as VerificationCheckParams,
+  };
+}