sendblue 2.1.0 → 3.3.1

package/src/client.ts

@@ -11,6 +11,7 @@ import type { APIResponseProps } from './internal/parse';
 import { getPlatformHeaders } from './internal/detect-platform';
 import * as Shims from './internal/shims';
 import * as Opts from './internal/request-options';
+import { stringifyQuery } from './internal/utils/query';
 import { VERSION } from './version';
 import * as Errors from './core/error';
 import * as Uploads from './core/uploads';
@@ -51,6 +52,7 @@ import {
   ContactCreateParams,
   ContactCreateResponse,
   ContactDeleteResponse,
+  ContactListParams,
   ContactListResponse,
   ContactRetrieveResponse,
   ContactUpdateParams,
@@ -279,21 +281,8 @@ export class SendblueAPI {
   /**
    * Basic re-implementation of `qs.stringify` for primitive types.
    */
-  protected stringifyQuery(query: Record<string, unknown>): string {
-    return Object.entries(query)
-      .filter(([_, value]) => typeof value !== 'undefined')
-      .map(([key, value]) => {
-        if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
-          return `${encodeURIComponent(key)}=${encodeURIComponent(value)}`;
-        }
-        if (value === null) {
-          return `${encodeURIComponent(key)}=`;
-        }
-        throw new Errors.SendblueAPIError(
-          `Cannot stringify type ${typeof value}; Expected string, number, boolean, or null. If you need to pass nested query parameters, you can manually encode them, e.g. { query: { 'foo[key1]': value1, 'foo[key2]': value2 } }, and please open a GitHub issue requesting better support for your use case.`,
-        );
-      })
-      .join('&');
+  protected stringifyQuery(query: object | Record<string, unknown>): string {
+    return stringifyQuery(query);
   }
 
   private getUserAgent(): string {
@@ -325,12 +314,13 @@ export class SendblueAPI {
       : new URL(baseURL + (baseURL.endsWith('/') && path.startsWith('/') ? path.slice(1) : path));
 
     const defaultQuery = this.defaultQuery();
-    if (!isEmptyObj(defaultQuery)) {
-      query = { ...defaultQuery, ...query };
+    const pathQuery = Object.fromEntries(url.searchParams);
+    if (!isEmptyObj(defaultQuery) || !isEmptyObj(pathQuery)) {
+      query = { ...pathQuery, ...defaultQuery, ...query };
     }
 
     if (typeof query === 'object' && query && !Array.isArray(query)) {
-      url.search = this.stringifyQuery(query as Record<string, unknown>);
+      url.search = this.stringifyQuery(query);
     }
 
     return url.toString();
@@ -514,7 +504,7 @@ export class SendblueAPI {
       loggerFor(this).info(`${responseInfo} - ${retryMessage}`);
 
       const errText = await response.text().catch((err: any) => castToError(err).message);
-      const errJSON = safeJSON(errText);
+      const errJSON = safeJSON(errText) as any;
       const errMessage = errJSON ? undefined : errText;
 
       loggerFor(this).debug(
@@ -555,9 +545,10 @@ export class SendblueAPI {
     controller: AbortController,
   ): Promise<Response> {
     const { signal, method, ...options } = init || {};
-    if (signal) signal.addEventListener('abort', () => controller.abort());
+    const abort = this._makeAbort(controller);
+    if (signal) signal.addEventListener('abort', abort, { once: true });
 
-    const timeout = setTimeout(() => controller.abort(), ms);
+    const timeout = setTimeout(abort, ms);
 
     const isReadableBody =
       ((globalThis as any).ReadableStream && options.body instanceof (globalThis as any).ReadableStream) ||
@@ -634,9 +625,9 @@ export class SendblueAPI {
       }
     }
 
-    // If the API asks us to wait a certain amount of time (and it's a reasonable amount),
-    // just do what it says, but otherwise calculate a default
-    if (!(timeoutMillis && 0 <= timeoutMillis && timeoutMillis < 60 * 1000)) {
+    // If the API asks us to wait a certain amount of time, just do what it
+    // says, but otherwise calculate a default
+    if (timeoutMillis === undefined) {
       const maxRetries = options.maxRetries ?? this.maxRetries;
       timeoutMillis = this.calculateDefaultRetryTimeoutMillis(retriesRemaining, maxRetries);
     }
@@ -724,6 +715,12 @@ export class SendblueAPI {
     return headers.values;
   }
 
+  private _makeAbort(controller: AbortController) {
+    // note: we can't just inline this method inside `fetchWithTimeout()` because then the closure
+    //       would capture all request options, and cause a memory leak.
+    return () => controller.abort();
+  }
+
   private buildBody({ options: { body, headers: rawHeaders } }: { options: FinalRequestOptions }): {
     bodyHeaders: HeadersLike;
     body: BodyInit | undefined;
@@ -756,6 +753,14 @@ export class SendblueAPI {
         (Symbol.iterator in body && 'next' in body && typeof body.next === 'function'))
     ) {
       return { bodyHeaders: undefined, body: Shims.ReadableStreamFrom(body as AsyncIterable<Uint8Array>) };
+    } else if (
+      typeof body === 'object' &&
+      headers.values.get('content-type') === 'application/x-www-form-urlencoded'
+    ) {
+      return {
+        bodyHeaders: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: this.stringifyQuery(body),
+      };
     } else {
       return this.#encoder({ body, headers });
     }
@@ -780,12 +785,33 @@ export class SendblueAPI {
 
   static toFile = Uploads.toFile;
 
+  /**
+   * Operations for sending and managing messages
+   */
   messages: API.Messages = new API.Messages(this);
+  /**
+   * Operations for group messaging (beta)
+   */
   groups: API.Groups = new API.Groups(this);
+  /**
+   * Operations for uploading and managing media files
+   */
   mediaObjects: API.MediaObjects = new API.MediaObjects(this);
+  /**
+   * Operations for looking up service availability for phone numbers
+   */
   lookups: API.Lookups = new API.Lookups(this);
+  /**
+   * Operations for sending and managing messages
+   */
   typingIndicators: API.TypingIndicators = new API.TypingIndicators(this);
+  /**
+   * Operations for managing contacts
+   */
   contacts: API.Contacts = new API.Contacts(this);
+  /**
+   * Operations for managing webhook subscriptions
+   */
   webhooks: API.Webhooks = new API.Webhooks(this);
 }
 
@@ -848,6 +874,7 @@ export declare namespace SendblueAPI {
     type ContactVerifyResponse as ContactVerifyResponse,
     type ContactCreateParams as ContactCreateParams,
     type ContactUpdateParams as ContactUpdateParams,
+    type ContactListParams as ContactListParams,
     type ContactVerifyParams as ContactVerifyParams,
   };
 

package/src/internal/parse.ts

@@ -29,6 +29,12 @@ export async function defaultParseResponse<T>(client: SendblueAPI, props: APIRes
     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/internal/utils/query.ts

@@ -0,0 +1,23 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { SendblueAPIError } from '../../core/error';
+
+/**
+ * Basic re-implementation of `qs.stringify` for primitive types.
+ */
+export function stringifyQuery(query: object | Record<string, unknown>) {
+  return Object.entries(query)
+    .filter(([_, value]) => typeof value !== 'undefined')
+    .map(([key, value]) => {
+      if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+        return `${encodeURIComponent(key)}=${encodeURIComponent(value)}`;
+      }
+      if (value === null) {
+        return `${encodeURIComponent(key)}=`;
+      }
+      throw new SendblueAPIError(
+        `Cannot stringify type ${typeof value}; Expected string, number, boolean, or null. If you need to pass nested query parameters, you can manually encode them, e.g. { query: { 'foo[key1]': value1, 'foo[key2]': value2 } }, and please open a GitHub issue requesting better support for your use case.`,
+      );
+    })
+    .join('&');
+}

package/src/internal/utils.ts

@@ -6,3 +6,4 @@ export * from './utils/env';
 export * from './utils/log';
 export * from './utils/uuid';
 export * from './utils/sleep';
+export * from './utils/query';

package/src/resources/contacts/bulk.ts

@@ -5,6 +5,9 @@ import * as ContactsAPI from './contacts';
 import { APIPromise } from '../../core/api-promise';
 import { RequestOptions } from '../../internal/request-options';
 
+/**
+ * Operations for managing contacts
+ */
 export class Bulk extends APIResource {
   /**
    * Create multiple contacts in bulk
@@ -56,13 +59,31 @@ export interface BulkCreateParams {
 
 export namespace BulkCreateParams {
   export interface Contact {
+    /**
+     * Phone number in E.164 format
+     */
     phone: string;
 
-    company?: string;
+    /**
+     * Company name
+     */
+    company_name?: string;
 
-    firstName?: string;
+    /**
+     * Custom key-value pairs. Keys are human-readable labels; new labels are
+     * auto-created.
+     */
+    custom_variables?: { [key: string]: string };
 
-    lastName?: string;
+    /**
+     * Contact's first name
+     */
+    first_name?: string;
+
+    /**
+     * Contact's last name
+     */
+    last_name?: string;
 
     tags?: Array<string>;
   }

package/src/resources/contacts/contacts.ts

@@ -7,6 +7,9 @@ import { APIPromise } from '../../core/api-promise';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
+/**
+ * Operations for managing contacts
+ */
 export class Contacts extends APIResource {
   bulk: BulkAPI.Bulk = new BulkAPI.Bulk(this._client);
 
@@ -62,8 +65,11 @@ export class Contacts extends APIResource {
    * const contacts = await client.contacts.list();
    * ```
    */
-  list(options?: RequestOptions): APIPromise<ContactListResponse> {
-    return this._client.get('/api/v2/contacts', options);
+  list(
+    query: ContactListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ContactListResponse> {
+    return this._client.get('/api/v2/contacts', { query, ...options });
   }
 
   /**
@@ -109,27 +115,32 @@ export interface Contact {
   /**
    * Email of assigned user
    */
-  assignedToEmail?: string;
+  assigned_to_email?: string;
 
   /**
    * Company name
    */
-  companyName?: string;
+  company_name?: string;
 
   /**
    * When the contact was created
    */
   created_at?: string;
 
+  /**
+   * Custom key-value pairs stored on the contact. Keys are human-readable labels.
+   */
+  custom_variables?: { [key: string]: string };
+
   /**
    * First name
    */
-  firstName?: string;
+  first_name?: string;
 
   /**
    * Last name
    */
-  lastName?: string;
+  last_name?: string;
 
   /**
    * Phone number in E.164 format
@@ -139,12 +150,17 @@ export interface Contact {
   /**
    * Associated Sendblue phone number
    */
-  sendblueNumber?: string;
+  sendblue_number?: string;
 
   /**
    * Tags associated with the contact
    */
   tags?: Array<string>;
+
+  /**
+   * Whether the contact is verified
+   */
+  verified?: boolean;
 }
 
 export interface ContactCreateResponse {
@@ -184,57 +200,63 @@ export interface ContactVerifyResponse {
 
 export interface ContactCreateParams {
   /**
-   * Contact's phone number in E.164 format
+   * Contact's phone number in E.164 format (preferred)
    */
   number: string;
 
   /**
-   * Email of assigned user
+   * Email of assigned user (preferred)
    */
   assigned_to_email?: string;
 
   /**
-   * Email of assigned user (alternative)
+   * @deprecated Email of assigned user (deprecated, use assigned_to_email)
    */
   assignedToEmail?: string;
 
   /**
-   * Contact's first name
+   * Custom key-value pairs. Keys are human-readable labels; new labels are
+   * auto-created.
+   */
+  custom_variables?: { [key: string]: string };
+
+  /**
+   * Contact's first name (preferred)
    */
   first_name?: string;
 
   /**
-   * Contact's first name (alternative)
+   * @deprecated Contact's first name (deprecated, use first_name)
    */
   firstName?: string;
 
   /**
-   * Contact's last name
+   * Contact's last name (preferred)
    */
   last_name?: string;
 
   /**
-   * Contact's last name (alternative)
+   * @deprecated Contact's last name (deprecated, use last_name)
    */
   lastName?: string;
 
   /**
-   * Contact's phone number (alternative)
+   * @deprecated Contact's phone number (deprecated, use number)
    */
   phone_number?: string;
 
   /**
-   * Contact's phone number (alternative)
+   * @deprecated Contact's phone number (deprecated, use number)
    */
   phoneNumber?: string;
 
   /**
-   * Associated Sendblue phone number
+   * Associated Sendblue phone number to send with (preferred)
    */
   sendblue_number?: string;
 
   /**
-   * Associated Sendblue phone number (alternative)
+   * @deprecated Associated Sendblue phone number (deprecated, use sendblue_number)
    */
   sendblueNumber?: string;
 
@@ -250,19 +272,96 @@ export interface ContactCreateParams {
 }
 
 export interface ContactUpdateParams {
+  /**
+   * Email of assigned user (preferred)
+   */
+  assigned_to_email?: string;
+
+  /**
+   * @deprecated Deprecated, use assigned_to_email
+   */
   assignedToEmail?: string;
 
+  /**
+   * Company name (preferred)
+   */
+  company_name?: string;
+
+  /**
+   * @deprecated Deprecated, use company_name
+   */
   companyName?: string;
 
+  /**
+   * Custom key-value pairs. Merged with existing variables (not replaced).
+   */
+  custom_variables?: { [key: string]: string };
+
+  /**
+   * Contact's first name (preferred)
+   */
+  first_name?: string;
+
+  /**
+   * @deprecated Deprecated, use first_name
+   */
   firstName?: string;
 
+  /**
+   * Contact's last name (preferred)
+   */
+  last_name?: string;
+
+  /**
+   * @deprecated Deprecated, use last_name
+   */
   lastName?: string;
 
+  /**
+   * Associated Sendblue phone number (preferred)
+   */
+  sendblue_number?: string;
+
+  /**
+   * @deprecated Deprecated, use sendblue_number
+   */
   sendblueNumber?: string;
 
   tags?: Array<string>;
 }
 
+export interface ContactListParams {
+  /**
+   * Filter by contact ID
+   */
+  cid?: string;
+
+  /**
+   * Maximum number of contacts to return
+   */
+  limit?: number;
+
+  /**
+   * Number of contacts to skip
+   */
+  offset?: number;
+
+  /**
+   * Field to sort by
+   */
+  order_by?: string;
+
+  /**
+   * Sort direction
+   */
+  order_direction?: 'asc' | 'desc';
+
+  /**
+   * Filter by phone number
+   */
+  phone_number?: string;
+}
+
 export interface ContactVerifyParams {
   /**
    * Phone number to verify
@@ -284,6 +383,7 @@ export declare namespace Contacts {
     type ContactVerifyResponse as ContactVerifyResponse,
     type ContactCreateParams as ContactCreateParams,
     type ContactUpdateParams as ContactUpdateParams,
+    type ContactListParams as ContactListParams,
     type ContactVerifyParams as ContactVerifyParams,
   };
 

package/src/resources/contacts/index.ts

@@ -19,5 +19,6 @@ export {
   type ContactVerifyResponse,
   type ContactCreateParams,
   type ContactUpdateParams,
+  type ContactListParams,
   type ContactVerifyParams,
 } from './contacts';

package/src/resources/groups.ts

@@ -5,6 +5,9 @@ import * as MessagesAPI from './messages';
 import { APIPromise } from '../core/api-promise';
 import { RequestOptions } from '../internal/request-options';
 
+/**
+ * Operations for group messaging (beta)
+ */
 export class Groups extends APIResource {
   /**
    * Add or manage participants in a group chat (beta feature)

package/src/resources/index.ts

@@ -12,6 +12,7 @@ export {
   type ContactVerifyResponse,
   type ContactCreateParams,
   type ContactUpdateParams,
+  type ContactListParams,
   type ContactVerifyParams,
 } from './contacts/contacts';
 export {

package/src/resources/lookups.ts

@@ -4,6 +4,9 @@ import { APIResource } from '../core/resource';
 import { APIPromise } from '../core/api-promise';
 import { RequestOptions } from '../internal/request-options';
 
+/**
+ * Operations for looking up service availability for phone numbers
+ */
 export class Lookups extends APIResource {
   /**
    * Determine if a phone number supports iMessage or SMS. Useful for checking if a

package/src/resources/media-objects.ts

@@ -4,6 +4,9 @@ import { APIResource } from '../core/resource';
 import { APIPromise } from '../core/api-promise';
 import { RequestOptions } from '../internal/request-options';
 
+/**
+ * Operations for uploading and managing media files
+ */
 export class MediaObjects extends APIResource {
   /**
    * Upload a media file to Sendblue's CDN for use in messages

package/src/resources/messages.ts

@@ -5,6 +5,9 @@ import { APIPromise } from '../core/api-promise';
 import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
 
+/**
+ * Operations for sending and managing messages
+ */
 export class Messages extends APIResource {
   /**
    * Retrieve details of a specific message by its ID
@@ -24,6 +27,22 @@ export class Messages extends APIResource {
    * Retrieve a list of messages for the authenticated account with comprehensive
    * filtering capabilities. Rate limited to 100 requests per 10 seconds per account.
    *
+   * ## Common Use Cases
+   *
+   * **Polling for inbound messages (no webhooks):**
+   *
+   * ```
+   * GET /api/v2/messages?is_outbound=false&sendblue_number=+16292925296&order_by=createdAt&order_direction=desc&limit=50
+   * ```
+   *
+   * Track processed message IDs to avoid duplicates.
+   *
+   * **Get conversation with a specific contact:**
+   *
+   * ```
+   * GET /api/v2/messages?number=+15551234567&order_by=createdAt&order_direction=desc
+   * ```
+   *
    * @example
    * ```ts
    * const messages = await client.messages.list();
@@ -129,7 +148,7 @@ export interface MessageContent {
     | 'loud'
     | 'slam';
 
-  status?: 'QUEUED' | 'SENT' | 'DELIVERED' | 'READ' | 'ERROR' | 'RECEIVED';
+  status?: 'QUEUED' | 'SENT' | 'DELIVERED' | 'ERROR' | 'RECEIVED';
 
   /**
    * Recipient phone number
@@ -211,7 +230,7 @@ export interface MessageResponse {
     | 'loud'
     | 'slam';
 
-  status?: 'QUEUED' | 'SENT' | 'DELIVERED' | 'READ' | 'ERROR';
+  status?: 'QUEUED' | 'SENT' | 'DELIVERED' | 'ERROR';
 }
 
 export interface MessageRetrieveResponse {
@@ -337,7 +356,10 @@ export namespace MessageRetrieveResponse {
      */
     sendblue_number?: string | null;
 
-    service?: 'iMessage' | 'SMS';
+    /**
+     * The messaging service used
+     */
+    service?: 'iMessage' | 'SMS' | 'RCS';
 
     status?:
       | 'REGISTERED'
@@ -488,7 +510,10 @@ export namespace MessageListResponse {
      */
     sendblue_number?: string | null;
 
-    service?: 'iMessage' | 'SMS';
+    /**
+     * The messaging service used
+     */
+    service?: 'iMessage' | 'SMS' | 'RCS';
 
     status?:
       | 'REGISTERED'
@@ -563,7 +588,14 @@ export interface MessageListParams {
   group_id?: string;
 
   /**
-   * Filter by message direction
+   * Filter by message direction. Use `false` to get inbound messages (messages sent
+   * TO your Sendblue number).
+   *
+   * **To get inbound messages for polling:** Use `is_outbound=false` combined with
+   * `sendblue_number` or `to_number` set to your Sendblue phone number.
+   *
+   * Note: Do NOT use `message_type=inbound` - that parameter only accepts `message`
+   * or `group` values.
    */
   is_outbound?: 'true' | 'false';
 
@@ -573,10 +605,18 @@ export interface MessageListParams {
   limit?: number;
 
   /**
-   * Filter by message type
+   * Filter by message type (1:1 vs group chat). Only accepts `message` or `group`.
+   *
+   * **Common mistake:** This is NOT for filtering inbound vs outbound messages. Use
+   * `is_outbound` parameter instead.
    */
   message_type?: 'message' | 'group';
 
+  /**
+   * Filter by any phone number (from or to)
+   */
+  number?: string;
+
   /**
    * Number of messages to skip
    */
@@ -592,6 +632,11 @@ export interface MessageListParams {
    */
   order_direction?: 'asc' | 'desc';
 
+  /**
+   * Filter by Sendblue phone number
+   */
+  sendblue_number?: string;
+
   /**
    * Filter messages sent after this date (ISO 8601 format)
    */
@@ -605,7 +650,7 @@ export interface MessageListParams {
   /**
    * Filter by service type
    */
-  service?: 'iMessage' | 'SMS';
+  service?: 'iMessage' | 'SMS' | 'RCS';
 
   /**
    * Filter by message status