sendblue 3.10.1 → 3.12.0

package/src/internal/decoders/line.ts

@@ -0,0 +1,135 @@
+import { concatBytes, decodeUTF8, encodeUTF8 } from '../utils/bytes';
+
+export type Bytes = string | ArrayBuffer | Uint8Array | null | undefined;
+
+/**
+ * A re-implementation of httpx's `LineDecoder` in Python that handles incrementally
+ * reading lines from text.
+ *
+ * https://github.com/encode/httpx/blob/920333ea98118e9cf617f246905d7b202510941c/httpx/_decoders.py#L258
+ */
+export class LineDecoder {
+  // prettier-ignore
+  static NEWLINE_CHARS = new Set(['\n', '\r']);
+  static NEWLINE_REGEXP = /\r\n|[\n\r]/g;
+
+  #buffer: Uint8Array;
+  #carriageReturnIndex: number | null;
+
+  constructor() {
+    this.#buffer = new Uint8Array();
+    this.#carriageReturnIndex = null;
+  }
+
+  decode(chunk: Bytes): string[] {
+    if (chunk == null) {
+      return [];
+    }
+
+    const binaryChunk =
+      chunk instanceof ArrayBuffer ? new Uint8Array(chunk)
+      : typeof chunk === 'string' ? encodeUTF8(chunk)
+      : chunk;
+
+    this.#buffer = concatBytes([this.#buffer, binaryChunk]);
+
+    const lines: string[] = [];
+    let patternIndex;
+    while ((patternIndex = findNewlineIndex(this.#buffer, this.#carriageReturnIndex)) != null) {
+      if (patternIndex.carriage && this.#carriageReturnIndex == null) {
+        // skip until we either get a corresponding `\n`, a new `\r` or nothing
+        this.#carriageReturnIndex = patternIndex.index;
+        continue;
+      }
+
+      // we got double \r or \rtext\n
+      if (
+        this.#carriageReturnIndex != null &&
+        (patternIndex.index !== this.#carriageReturnIndex + 1 || patternIndex.carriage)
+      ) {
+        lines.push(decodeUTF8(this.#buffer.subarray(0, this.#carriageReturnIndex - 1)));
+        this.#buffer = this.#buffer.subarray(this.#carriageReturnIndex);
+        this.#carriageReturnIndex = null;
+        continue;
+      }
+
+      const endIndex =
+        this.#carriageReturnIndex !== null ? patternIndex.preceding - 1 : patternIndex.preceding;
+
+      const line = decodeUTF8(this.#buffer.subarray(0, endIndex));
+      lines.push(line);
+
+      this.#buffer = this.#buffer.subarray(patternIndex.index);
+      this.#carriageReturnIndex = null;
+    }
+
+    return lines;
+  }
+
+  flush(): string[] {
+    if (!this.#buffer.length) {
+      return [];
+    }
+    return this.decode('\n');
+  }
+}
+
+/**
+ * This function searches the buffer for the end patterns, (\r or \n)
+ * and returns an object with the index preceding the matched newline and the
+ * index after the newline char. `null` is returned if no new line is found.
+ *
+ * ```ts
+ * findNewLineIndex('abc\ndef') -> { preceding: 2, index: 3 }
+ * ```
+ */
+function findNewlineIndex(
+  buffer: Uint8Array,
+  startIndex: number | null,
+): { preceding: number; index: number; carriage: boolean } | null {
+  const newline = 0x0a; // \n
+  const carriage = 0x0d; // \r
+
+  for (let i = startIndex ?? 0; i < buffer.length; i++) {
+    if (buffer[i] === newline) {
+      return { preceding: i, index: i + 1, carriage: false };
+    }
+
+    if (buffer[i] === carriage) {
+      return { preceding: i, index: i + 1, carriage: true };
+    }
+  }
+
+  return null;
+}
+
+export function findDoubleNewlineIndex(buffer: Uint8Array): number {
+  // This function searches the buffer for the end patterns (\r\r, \n\n, \r\n\r\n)
+  // and returns the index right after the first occurrence of any pattern,
+  // or -1 if none of the patterns are found.
+  const newline = 0x0a; // \n
+  const carriage = 0x0d; // \r
+
+  for (let i = 0; i < buffer.length - 1; i++) {
+    if (buffer[i] === newline && buffer[i + 1] === newline) {
+      // \n\n
+      return i + 2;
+    }
+    if (buffer[i] === carriage && buffer[i + 1] === carriage) {
+      // \r\r
+      return i + 2;
+    }
+    if (
+      buffer[i] === carriage &&
+      buffer[i + 1] === newline &&
+      i + 3 < buffer.length &&
+      buffer[i + 2] === carriage &&
+      buffer[i + 3] === newline
+    ) {
+      // \r\n\r\n
+      return i + 4;
+    }
+  }
+
+  return -1;
+}

package/src/internal/parse.ts

@@ -1,6 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import type { FinalRequestOptions } from './request-options';
+import { Stream } from '../core/streaming';
 import { type SendblueAPI } from '../client';
 import { formatRequestDetails, loggerFor } from './utils/log';
 
@@ -16,6 +17,19 @@ export type APIResponseProps = {
 export async function defaultParseResponse<T>(client: SendblueAPI, props: APIResponseProps): Promise<T> {
   const { response, requestLogID, retryOfRequestLogID, startTime } = props;
   const body = await (async () => {
+    if (props.options.stream) {
+      loggerFor(client).debug('response', response.status, response.url, response.headers, response.body);
+
+      // Note: there is an invariant here that isn't represented in the type system
+      // that if you set `stream: true` the response type must also be `Stream<T>`
+
+      if (props.options.__streamClass) {
+        return props.options.__streamClass.fromSSEResponse(response, props.controller, client) as any;
+      }
+
+      return Stream.fromSSEResponse(response, props.controller, client) as any;
+    }
+
     // fetch refuses to read the body when the status code is 204.
     if (response.status === 204) {
       return null as T;

package/src/internal/request-options.ts

@@ -3,6 +3,7 @@
 import { NullableHeaders } from './headers';
 
 import type { BodyInit } from './builtin-types';
+import { Stream } from '../core/streaming';
 import type { HTTPMethod, MergedRequestInit } from './types';
 import { type HeadersLike } from './headers';
 
@@ -76,6 +77,7 @@ export type RequestOptions = {
   defaultBaseURL?: string | undefined;
 
   __binaryResponse?: boolean | undefined;
+  __streamClass?: typeof Stream;
 };
 
 export type EncodedContent = { bodyHeaders: HeadersLike; body: BodyInit };

package/src/resources/auth/auth.ts

@@ -0,0 +1,19 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as TokensAPI from './tokens';
+import { TokenCreateParams, TokenCreateResponse, Tokens } from './tokens';
+
+export class Auth extends APIResource {
+  tokens: TokensAPI.Tokens = new TokensAPI.Tokens(this._client);
+}
+
+Auth.Tokens = Tokens;
+
+export declare namespace Auth {
+  export {
+    Tokens as Tokens,
+    type TokenCreateResponse as TokenCreateResponse,
+    type TokenCreateParams as TokenCreateParams,
+  };
+}

package/src/resources/auth/index.ts

@@ -0,0 +1,4 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export { Auth } from './auth';
+export { Tokens, type TokenCreateResponse, type TokenCreateParams } from './tokens';

package/src/resources/auth/tokens.ts

@@ -0,0 +1,101 @@
+// 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 { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+/**
+ * Operations for minting and revoking temporary account API tokens
+ */
+export class Tokens extends APIResource {
+  /**
+   * Creates a short-lived bearer token for the authenticated account. This endpoint
+   * must be called with live account API keys; temporary bearer tokens and test API
+   * keys cannot mint additional tokens.
+   *
+   * When `phone_number` or `phone_numbers` is supplied, the token is scoped to those
+   * Sendblue phone numbers. When no phone selector is supplied, the token is an
+   * account-scoped temporary token.
+   *
+   * The plaintext token is returned only once.
+   *
+   * @example
+   * ```ts
+   * const token = await client.auth.tokens.create();
+   * ```
+   */
+  create(
+    body: TokenCreateParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<TokenCreateResponse> {
+    return this._client.post('/v3/auth/tokens', { body, ...options });
+  }
+
+  /**
+   * Revokes a temporary bearer token owned by the authenticated account. This
+   * endpoint must be called with live account API keys; temporary bearer tokens and
+   * test API keys cannot revoke tokens.
+   *
+   * @example
+   * ```ts
+   * await client.auth.tokens.revoke(
+   *   '11111111-1111-4111-8111-111111111111',
+   * );
+   * ```
+   */
+  revoke(tokenID: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/v3/auth/tokens/${tokenID}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+export interface TokenCreateResponse {
+  /**
+   * Plaintext temporary bearer token. Store it securely; it is returned only once.
+   */
+  token: string;
+
+  /**
+   * ISO timestamp when the token expires.
+   */
+  expires_at: string;
+
+  /**
+   * Phone-number scope for this token. Empty means the token is account-scoped.
+   */
+  phone_numbers: Array<string>;
+
+  /**
+   * Token identifier used for revocation.
+   */
+  token_id: string;
+
+  token_type: 'Bearer';
+}
+
+export interface TokenCreateParams {
+  /**
+   * Token lifetime in seconds. Defaults to 900 seconds when omitted.
+   */
+  expires_in_seconds?: number;
+
+  /**
+   * Single Sendblue phone number to scope the token to. Cannot be combined with
+   * `phone_numbers`.
+   */
+  phone_number?: string;
+
+  /**
+   * Sendblue phone numbers to scope the token to. Cannot be combined with
+   * `phone_number`.
+   */
+  phone_numbers?: Array<string>;
+}
+
+export declare namespace Tokens {
+  export { type TokenCreateResponse as TokenCreateResponse, type TokenCreateParams as TokenCreateParams };
+}

package/src/resources/auth.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './auth/index';

package/src/resources/contacts/contacts.ts

@@ -140,6 +140,11 @@ export interface Contact {
    */
   company_name?: string;
 
+  /**
+   * Immutable contact identity (included by list responses for event recovery)
+   */
+  contact_id?: string;
+
   /**
    * When the contact was created
    */
@@ -384,6 +389,11 @@ export interface ContactListParams {
    */
   cid?: string;
 
+  /**
+   * Filter contacts created at or after this ISO 8601 timestamp (event recovery)
+   */
+  created_at_gte?: string;
+
   /**
    * Maximum number of contacts to return. Defaults to 100, capped at 1000.
    */

package/src/resources/events.ts

@@ -0,0 +1,75 @@
+// 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 { Stream } from '../core/streaming';
+import { buildHeaders } from '../internal/headers';
+import { RequestOptions } from '../internal/request-options';
+
+/**
+ * Authenticated live account events and recovery contracts
+ */
+export class Events extends APIResource {
+  /**
+   * Opens an authenticated Server-Sent Events stream scoped exclusively to the
+   * account resolved by the supplied credentials. The stream is live and
+   * intentionally not a durable replay log. It sends a heartbeat every 15 seconds
+   * and rotates after at most 15 minutes. A temporary-token stream closes no later
+   * than that token's `expires_at`; clients should reconnect and repair gaps via:
+   *
+   * - `GET /api/v2/messages?updated_at_gte=...&order_by=updated_at&order_direction=asc`
+   * - `GET /api/v2/contacts?created_at_gte=...&order_by=created_at&order_direction=asc`
+   * - `GET /api/v2/lines/state`
+   * - `GET /api/v2/verify/verifications?updated_at_gte=...`
+   *
+   * Each event contains a stable `id`, a `type`, `occurred_at`, and a minimal `data`
+   * object. Consumers must deduplicate by ID. Typing indicators are ephemeral and
+   * cannot be recovered.
+   */
+  stream(
+    query: EventStreamParams | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<Stream<AccountEvent>> {
+    return this._client.get('/api/v2/events', {
+      query,
+      ...options,
+      headers: buildHeaders([{ Accept: 'text/event-stream' }, options?.headers]),
+      stream: true,
+    }) as APIPromise<Stream<AccountEvent>>;
+  }
+}
+
+export interface AccountEvent {
+  id: string;
+
+  data: { [key: string]: unknown };
+
+  occurred_at: string;
+
+  type:
+    | 'message.received'
+    | 'message.created'
+    | 'message.updated'
+    | 'typing.changed'
+    | 'line.assigned'
+    | 'line.unassigned'
+    | 'line.status.changed'
+    | 'line.blocked'
+    | 'contact.created'
+    | 'verification.approved'
+    | 'verification.expired'
+    | 'verification.canceled';
+
+  version: 1;
+}
+
+export interface EventStreamParams {
+  /**
+   * Optional comma-separated allowlist of event types
+   */
+  types?: string;
+}
+
+export declare namespace Events {
+  export { type AccountEvent as AccountEvent, type EventStreamParams as EventStreamParams };
+}

package/src/resources/groups.ts

@@ -95,6 +95,12 @@ export interface GroupSendMessageParams {
    */
   numbers?: Array<string>;
 
+  /**
+   * Immediate parent of an iMessage inline reply. The target must belong to the same
+   * account, conversation, and sending line.
+   */
+  reply_to?: GroupSendMessageParams.ReplyTo;
+
   /**
    * Optional. Identifies the seat (user) sending the group message so it is
    * attributed to a specific rep. Accepts either the seat UUID or the Firebase Auth
@@ -104,6 +110,28 @@ export interface GroupSendMessageParams {
   seat_id?: string;
 }
 
+export namespace GroupSendMessageParams {
+  /**
+   * Immediate parent of an iMessage inline reply. The target must belong to the same
+   * account, conversation, and sending line.
+   */
+  export interface ReplyTo {
+    /**
+     * Public handle of the immediate parent message
+     */
+    message_handle: string;
+
+    /**
+     * Advanced override for a known part of a multipart target. Omit this in normal
+     * reply requests and never guess it; requests default to 0. When replying to an
+     * attachment represented by its own webhook, use that webhook's `message_handle`
+     * and omit `part_index` so Sendblue can use the stored authoritative part.
+     * Responses omit it when no authoritative immediate-parent part is available.
+     */
+    part_index?: number;
+  }
+}
+
 export declare namespace Groups {
   export {
     type GroupModifyResponse as GroupModifyResponse,

package/src/resources/index.ts

@@ -1,5 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+export { Auth } from './auth/auth';
 export {
   Contacts,
   type Contact,
@@ -17,13 +18,23 @@ export {
   type ContactOptOutParams,
   type ContactVerifyParams,
 } from './contacts/contacts';
+export { Events, type AccountEvent, type EventStreamParams } from './events';
 export {
   Groups,
   type GroupModifyResponse,
   type GroupModifyParams,
   type GroupSendMessageParams,
 } from './groups';
-export { Lines } from './lines/lines';
+export { Lines, type LineState, type LineGetStateResponse } from './lines/lines';
+export {
+  Location,
+  type LocationRetrieveResponse,
+  type LocationListResponse,
+  type LocationWatchResponse,
+  type LocationRetrieveParams,
+  type LocationListParams,
+  type LocationWatchParams,
+} from './location';
 export { Lookups, type LookupLookupNumberResponse, type LookupLookupNumberParams } from './lookups';
 export { MediaObjects, type MediaObjectUploadResponse, type MediaObjectUploadParams } from './media-objects';
 export {
@@ -35,7 +46,13 @@ export {
   type MessageListParams,
   type MessageGetStatusParams,
   type MessageSendParams,
+  type MessageUpdateAppCardParams,
 } from './messages';
+export {
+  RequestLocation,
+  type RequestLocationCreateResponse,
+  type RequestLocationCreateParams,
+} from './request-location';
 export { SendCarousel, type SendCarouselSendResponse, type SendCarouselSendParams } from './send-carousel';
 export {
   TypingIndicators,
@@ -43,6 +60,14 @@ export {
   type TypingIndicatorSendParams,
 } from './typing-indicators';
 export { V2 } from './v2/v2';
+export {
+  VerifiedContacts,
+  type VerifiedContactCreateResponse,
+  type VerifiedContactRetrieveResponse,
+  type VerifiedContactListResponse,
+  type VerifiedContactCreateParams,
+} from './verified-contacts';
+export { Verify } from './verify/verify';
 export {
   Webhooks,
   type WebhookConfiguration,

package/src/resources/lines/call-forwarding.ts

@@ -5,6 +5,9 @@ import { APIPromise } from '../../core/api-promise';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
+/**
+ * Sendblue line configuration and health state
+ */
 export class CallForwarding extends APIResource {
   /**
    * Returns the current call forwarding number for a dedicated phone line.

package/src/resources/lines/index.ts

@@ -7,4 +7,4 @@ export {
   type CallForwardingDeleteResponse,
   type CallForwardingUpdateParams,
 } from './call-forwarding';
-export { Lines } from './lines';
+export { Lines, type LineState, type LineGetStateResponse } from './lines';

package/src/resources/lines/lines.ts

@@ -9,14 +9,58 @@ import {
   CallForwardingUpdateParams,
   CallForwardingUpdateResponse,
 } from './call-forwarding';
+import { APIPromise } from '../../core/api-promise';
+import { RequestOptions } from '../../internal/request-options';
 
+/**
+ * Sendblue line configuration and health state
+ */
 export class Lines extends APIResource {
   callForwarding: CallForwardingAPI.CallForwarding = new CallForwardingAPI.CallForwarding(this._client);
+
+  /**
+   * Returns the authenticated account's current line membership and latest persisted
+   * health transition.
+   *
+   * @example
+   * ```ts
+   * const response = await client.lines.getState();
+   * ```
+   */
+  getState(options?: RequestOptions): APIPromise<LineGetStateResponse> {
+    return this._client.get('/api/v2/lines/state', options);
+  }
+}
+
+export interface LineState {
+  assignment: 'assigned' | 'shared' | 'grace_period';
+
+  sendblue_number: string | null;
+
+  status: 'ONLINE' | 'OFFLINE' | 'DEGRADED' | 'UNKNOWN';
+
+  worker_id: string;
+
+  degraded_since?: string | null;
+
+  effective_until?: string | null;
+
+  status_changed_at?: string | null;
+}
+
+export interface LineGetStateResponse {
+  data: Array<LineState>;
+
+  snapshot_at: string;
+
+  status: 'OK';
 }
 
 Lines.CallForwarding = CallForwarding;
 
 export declare namespace Lines {
+  export { type LineState as LineState, type LineGetStateResponse as LineGetStateResponse };
+
   export {
     CallForwarding as CallForwarding,
     type CallForwardingRetrieveResponse as CallForwardingRetrieveResponse,