@mobilerun/sdk 5.4.0 → 5.6.0

package/src/resources/notifications.ts

@@ -5,6 +5,27 @@ import { APIPromise } from '../core/api-promise';
 import { RequestOptions } from '../internal/request-options';
 
 export class Notifications extends APIResource {
+  /**
+   * Replaces your muted event types with a server-computed preset: `recommended`
+   * mutes the mobilerun-default noisy lifecycle/progress events, `failures` mutes
+   * everything except failures/timeouts/invalid runs, and `everything` unmutes all.
+   * The response returns the muted types that were actually stored.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.notifications.applyPreferencesPreset({
+   *     preset: 'recommended',
+   *   });
+   * ```
+   */
+  applyPreferencesPreset(
+    body: NotificationApplyPreferencesPresetParams,
+    options?: RequestOptions,
+  ): APIPromise<NotificationApplyPreferencesPresetResponse> {
+    return this._client.post('/notifications/preferences/apply-preset', { body, ...options });
+  }
+
   /**
    * Returns the catalog of notifiable event types grouped by source category. Each
    * event lists its type identifier, label, and description, which can be referenced
@@ -58,6 +79,16 @@ export class Notifications extends APIResource {
   }
 }
 
+export interface NotificationApplyPreferencesPresetResponse {
+  data: NotificationApplyPreferencesPresetResponse.Data;
+}
+
+export namespace NotificationApplyPreferencesPresetResponse {
+  export interface Data {
+    mutedTypes: Array<string>;
+  }
+}
+
 export interface NotificationCatalogResponse {
   data: Array<NotificationCatalogResponse.Data>;
 }
@@ -104,15 +135,21 @@ export namespace NotificationUpdatePreferencesResponse {
   }
 }
 
+export interface NotificationApplyPreferencesPresetParams {
+  preset: 'recommended' | 'failures' | 'everything';
+}
+
 export interface NotificationUpdatePreferencesParams {
   mutedTypes: Array<string>;
 }
 
 export declare namespace Notifications {
   export {
+    type NotificationApplyPreferencesPresetResponse as NotificationApplyPreferencesPresetResponse,
     type NotificationCatalogResponse as NotificationCatalogResponse,
     type NotificationGetPreferencesResponse as NotificationGetPreferencesResponse,
     type NotificationUpdatePreferencesResponse as NotificationUpdatePreferencesResponse,
+    type NotificationApplyPreferencesPresetParams as NotificationApplyPreferencesPresetParams,
     type NotificationUpdatePreferencesParams as NotificationUpdatePreferencesParams,
   };
 }

package/src/resources/numbers/index.ts

@@ -1,6 +1,12 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-export { Messages, type MessageListResponse, type MessageListParams } from './messages';
+export {
+  Messages,
+  type MessageListResponse,
+  type MessageSendResponse,
+  type MessageListParams,
+  type MessageSendParams,
+} from './messages';
 export {
   Numbers,
   type NumberCreateResponse,
@@ -8,9 +14,11 @@ export {
   type NumberUpdateResponse,
   type NumberListResponse,
   type NumberDeleteResponse,
+  type NumberCapacityResponse,
   type NumberCountriesResponse,
   type NumberPurposesResponse,
   type NumberCreateParams,
   type NumberUpdateParams,
   type NumberListParams,
+  type NumberCapacityParams,
 } from './numbers';

package/src/resources/numbers/messages.ts

@@ -26,6 +26,28 @@ export class Messages extends APIResource {
   ): APIPromise<MessageListResponse> {
     return this._client.get(path`/numbers/phones/${id}/messages`, { query, ...options });
   }
+
+  /**
+   * Queues an SMS from one of the caller's numbers that can send. Same idempotency
+   * contract as the eSIM send: replaying an Idempotency-Key with the same payload
+   * returns the original message, reusing it with a different payload returns 422.
+   * 409 capability_unavailable: this number cannot send right now. 422
+   * invalid_recipient / unsupported_destination / body_too_long: the recipient or
+   * text does not fit the number. 429 daily_limit_reached: the rolling 24 h limit
+   * for the account is used up; 429 rate_limited: too many sends in a short window.
+   * 403 send_disabled: self-service SMS send is switched off.
+   *
+   * @example
+   * ```ts
+   * const response = await client.numbers.messages.send(
+   *   '550e8400-e29b-41d4-a716-446655440000',
+   *   { body: 'x', to: '+15551230001' },
+   * );
+   * ```
+   */
+  send(id: string, body: MessageSendParams, options?: RequestOptions): APIPromise<MessageSendResponse> {
+    return this._client.post(path`/numbers/phones/${id}/messages`, { body, ...options });
+  }
 }
 
 export interface MessageListResponse {
@@ -68,6 +90,44 @@ export namespace MessageListResponse {
   }
 }
 
+export interface MessageSendResponse {
+  data: MessageSendResponse.Data;
+}
+
+export namespace MessageSendResponse {
+  export interface Data {
+    id: string;
+
+    body: string | null;
+
+    createdAt: string;
+
+    deliveryStatus: string | null;
+
+    detectedSender: string | null;
+
+    direction: 'inbound' | 'outbound';
+
+    esimId: string | null;
+
+    occurredAt: string;
+
+    peerKey: string | null;
+
+    peerNumber: string | null;
+
+    status:
+      | 'received'
+      | 'queued'
+      | 'claimed'
+      | 'sending'
+      | 'sent'
+      | 'sent_unconfirmed'
+      | 'delivered'
+      | 'failed';
+  }
+}
+
 export interface MessageListParams {
   direction?: 'all' | 'inbound' | 'outbound';
 
@@ -78,6 +138,37 @@ export interface MessageListParams {
   since?: string;
 }
 
+export interface MessageSendParams {
+  /**
+   * SMS body text, up to 1600 characters (rejected with 400 beyond that, before
+   * hashing). A number's own limit may be lower and is answered 422 body_too_long.
+   */
+  body: string;
+
+  /**
+   * Recipient phone number, as E.164 or a US 10/11-digit number. Destinations the
+   * number cannot send to are rejected with 422 unsupported_destination, non-numbers
+   * with 422 invalid_recipient.
+   */
+  to: string;
+
+  /**
+   * @deprecated Deprecated: use the Idempotency-Key header instead. Optional
+   * idempotency key. Replaying the same key and payload returns the original send.
+   */
+  clientRequestId?: string;
+
+  /**
+   * Request a delivery report. Defaults to false.
+   */
+  deliveryReport?: boolean;
+}
+
 export declare namespace Messages {
-  export { type MessageListResponse as MessageListResponse, type MessageListParams as MessageListParams };
+  export {
+    type MessageListResponse as MessageListResponse,
+    type MessageSendResponse as MessageSendResponse,
+    type MessageListParams as MessageListParams,
+    type MessageSendParams as MessageSendParams,
+  };
 }

package/src/resources/numbers/numbers.ts

@@ -3,9 +3,14 @@
 import { APIResource } from '../../core/resource';
 import * as Shared from '../shared';
 import * as MessagesAPI from './messages';
-import { MessageListParams, MessageListResponse, Messages } from './messages';
+import {
+  MessageListParams,
+  MessageListResponse,
+  MessageSendParams,
+  MessageSendResponse,
+  Messages,
+} from './messages';
 import { APIPromise } from '../../core/api-promise';
-import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
@@ -13,9 +18,8 @@ export class Numbers extends APIResource {
   messages: MessagesAPI.Messages = new MessagesAPI.Messages(this._client);
 
   /**
-   * Starts a Mobilerun Phone purchase for the authenticated owner. Accepted requests
-   * always return the same asynchronous envelope; poll GET /numbers/phones/{id} for
-   * its business state. `purpose` and `country` are mutually exclusive.
+   * Starts a phone-number purchase. Poll the returned phone number for status
+   * updates. `purpose` and `country` cannot be combined.
    *
    * @example
    * ```ts
@@ -23,18 +27,10 @@ export class Numbers extends APIResource {
    * ```
    */
   create(
-    params: NumberCreateParams | null | undefined = {},
+    body: NumberCreateParams | null | undefined = {},
     options?: RequestOptions,
   ): APIPromise<NumberCreateResponse> {
-    const { 'Idempotency-Key': idempotencyKey, ...body } = params ?? {};
-    return this._client.post('/numbers/phones', {
-      body,
-      ...options,
-      headers: buildHeaders([
-        { ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined) },
-        options?.headers,
-      ]),
-    });
+    return this._client.post('/numbers/phones', { body, ...options });
   }
 
   /**
@@ -52,11 +48,8 @@ export class Numbers extends APIResource {
   }
 
   /**
-   * Updates the phone number's user-defined display label. Omitting `label` leaves
-   * it unchanged; setting it to null or an empty string clears it. The label is
-   * capped at 100 characters, is display-only, and never affects routing. It also
-   * seeds the billing entity name when set at purchase time; a later change here
-   * does not rename the already-created billing entity.
+   * Updates the display label. Omitting `label` leaves it unchanged; null or an
+   * empty string clears it.
    *
    * @example
    * ```ts
@@ -74,8 +67,7 @@ export class Numbers extends APIResource {
   }
 
   /**
-   * Lists phone numbers owned by the authenticated user — both BYO (`user`) and
-   * provisioned (`mobilerun`) numbers.
+   * Lists the caller's phone numbers.
    *
    * @example
    * ```ts
@@ -90,23 +82,9 @@ export class Numbers extends APIResource {
   }
 
   /**
-   * Cancels a Mobilerun Phone. The outcome depends on the number's current state:
-   *
-   * - If the number is still awaiting payment and no payment for it is currently
-   *   being processed, the checkout is closed immediately and the number is retired.
-   * - If the number is on the standard paid plan and already paid and in service,
-   *   cancellation is scheduled for the end of the current billing period rather
-   *   than taking effect immediately. The number stays usable through the period
-   *   already paid for, with no partial refund. Calling this again while a
-   *   cancellation is already scheduled is a no-op that returns the same result. The
-   *   response's `state` reflects this as `cancel_scheduled` with
-   *   `cancelAtPeriodEnd: true`; `currentPeriodEnd` is populated once billing
-   *   confirms the cancellation.
-   *
-   * Any other state (already refunding, a permanent billing failure, a payment
-   * currently being processed, an included-plan number, or a non-hosted/BYO number)
-   * returns 409 `not_cancellable`. Returns 404 if the number doesn't exist or isn't
-   * owned by the caller.
+   * Cancels a pending purchase or schedules cancellation of an active paid phone
+   * number. Repeating a scheduled cancellation is safe. Returns 409 when
+   * cancellation is not available.
    *
    * @example
    * ```ts
@@ -120,8 +98,22 @@ export class Numbers extends APIResource {
   }
 
   /**
-   * Lists the countries currently offered for a dedicated Mobilerun Phone, with live
-   * stock status. Pass `country` as the `country` field on POST /numbers/phones.
+   * Returns included phone capacity for a country. Creating a phone is
+   * authoritative.
+   *
+   * @example
+   * ```ts
+   * const response = await client.numbers.capacity({
+   *   country: 'de',
+   * });
+   * ```
+   */
+  capacity(query: NumberCapacityParams, options?: RequestOptions): APIPromise<NumberCapacityResponse> {
+    return this._client.get('/numbers/phones/capacity', { query, ...options });
+  }
+
+  /**
+   * Lists available countries and current phone-number availability.
    *
    * @example
    * ```ts
@@ -167,10 +159,21 @@ export namespace NumberRetrieveResponse {
   export interface Data {
     id: string;
 
+    /**
+     * Actions currently available for this phone number.
+     */
+    actions: Data.Actions;
+
     cancelAtPeriodEnd: boolean;
 
+    /**
+     * @deprecated Deprecated: use `actions.cancel`
+     */
     cancellable: boolean;
 
+    /**
+     * @deprecated Deprecated: use `actions.send`
+     */
     canSend: boolean;
 
     capabilities: Array<'sms' | 'voice'> | null;
@@ -193,6 +196,26 @@ export namespace NumberRetrieveResponse {
 
     updatedAt: string | null;
   }
+
+  export namespace Data {
+    /**
+     * Actions currently available for this phone number.
+     */
+    export interface Actions {
+      /**
+       * True when DELETE /numbers/phones/{id} would currently succeed.
+       */
+      cancel: boolean;
+
+      /**
+       * True when this number passes the send gate of POST
+       * /numbers/phones/{id}/messages: self-service sending is switched on and the
+       * number is active and able to send SMS. Daily and burst limits and recipient/body
+       * checks still apply; the send endpoint stays the final judge.
+       */
+      send: boolean;
+    }
+  }
 }
 
 export interface NumberUpdateResponse {
@@ -203,10 +226,21 @@ export namespace NumberUpdateResponse {
   export interface Data {
     id: string;
 
+    /**
+     * Actions currently available for this phone number.
+     */
+    actions: Data.Actions;
+
     cancelAtPeriodEnd: boolean;
 
+    /**
+     * @deprecated Deprecated: use `actions.cancel`
+     */
     cancellable: boolean;
 
+    /**
+     * @deprecated Deprecated: use `actions.send`
+     */
     canSend: boolean;
 
     capabilities: Array<'sms' | 'voice'> | null;
@@ -229,6 +263,26 @@ export namespace NumberUpdateResponse {
 
     updatedAt: string | null;
   }
+
+  export namespace Data {
+    /**
+     * Actions currently available for this phone number.
+     */
+    export interface Actions {
+      /**
+       * True when DELETE /numbers/phones/{id} would currently succeed.
+       */
+      cancel: boolean;
+
+      /**
+       * True when this number passes the send gate of POST
+       * /numbers/phones/{id}/messages: self-service sending is switched on and the
+       * number is active and able to send SMS. Daily and burst limits and recipient/body
+       * checks still apply; the send endpoint stays the final judge.
+       */
+      send: boolean;
+    }
+  }
 }
 
 export interface NumberListResponse {
@@ -241,10 +295,21 @@ export namespace NumberListResponse {
   export interface Item {
     id: string;
 
+    /**
+     * Actions currently available for this phone number.
+     */
+    actions: Item.Actions;
+
     cancelAtPeriodEnd: boolean;
 
+    /**
+     * @deprecated Deprecated: use `actions.cancel`
+     */
     cancellable: boolean;
 
+    /**
+     * @deprecated Deprecated: use `actions.send`
+     */
     canSend: boolean;
 
     capabilities: Array<'sms' | 'voice'> | null;
@@ -267,6 +332,26 @@ export namespace NumberListResponse {
 
     updatedAt: string | null;
   }
+
+  export namespace Item {
+    /**
+     * Actions currently available for this phone number.
+     */
+    export interface Actions {
+      /**
+       * True when DELETE /numbers/phones/{id} would currently succeed.
+       */
+      cancel: boolean;
+
+      /**
+       * True when this number passes the send gate of POST
+       * /numbers/phones/{id}/messages: self-service sending is switched on and the
+       * number is active and able to send SMS. Daily and burst limits and recipient/body
+       * checks still apply; the send endpoint stays the final judge.
+       */
+      send: boolean;
+    }
+  }
 }
 
 export interface NumberDeleteResponse {
@@ -277,10 +362,21 @@ export namespace NumberDeleteResponse {
   export interface Data {
     id: string;
 
+    /**
+     * Actions currently available for this phone number.
+     */
+    actions: Data.Actions;
+
     cancelAtPeriodEnd: boolean;
 
+    /**
+     * @deprecated Deprecated: use `actions.cancel`
+     */
     cancellable: boolean;
 
+    /**
+     * @deprecated Deprecated: use `actions.send`
+     */
     canSend: boolean;
 
     capabilities: Array<'sms' | 'voice'> | null;
@@ -303,6 +399,46 @@ export namespace NumberDeleteResponse {
 
     updatedAt: string | null;
   }
+
+  export namespace Data {
+    /**
+     * Actions currently available for this phone number.
+     */
+    export interface Actions {
+      /**
+       * True when DELETE /numbers/phones/{id} would currently succeed.
+       */
+      cancel: boolean;
+
+      /**
+       * True when this number passes the send gate of POST
+       * /numbers/phones/{id}/messages: self-service sending is switched on and the
+       * number is active and able to send SMS. Daily and burst limits and recipient/body
+       * checks still apply; the send endpoint stays the final judge.
+       */
+      send: boolean;
+    }
+  }
+}
+
+export interface NumberCapacityResponse {
+  data: NumberCapacityResponse.Data;
+}
+
+export namespace NumberCapacityResponse {
+  export interface Data {
+    included: number;
+
+    /**
+     * @deprecated Deprecated — always equal to `remaining`. Migrate to `remaining`;
+     * this field will be removed in a future revision.
+     */
+    includedRemaining: number;
+
+    remaining: number;
+
+    status: 'available' | 'exhausted' | 'not_included';
+  }
 }
 
 export interface NumberCountriesResponse {
@@ -347,33 +483,28 @@ export namespace NumberPurposesResponse {
 
 export interface NumberCreateParams {
   /**
-   * Body param: Prefer a free package seat ('included', default) or force the paid
-   * checkout ('rent')
+   * Use included capacity when available, require included capacity without paid
+   * fallback (included_only), or start a paid checkout (rent).
    */
-  billingPreference?: 'included' | 'rent';
+  billingPreference?: 'included' | 'included_only' | 'rent';
 
   /**
-   * Body param: Optional ISO 3166-1 alpha-2 country code from GET
-   * /numbers/countries. Cannot be combined with `purpose`.
+   * Optional ISO 3166-1 alpha-2 country code from GET /numbers/phones/countries.
+   * Cannot be combined with `purpose`.
    */
   country?: string;
 
   /**
-   * Body param: User-defined display label — NFC-normalized, up to 100 GRAPHEMES
-   * (not UTF-16 code units; an emoji/flag may span several). Display-only, never
-   * used for routing. Also seeds the billing entity name at purchase.
+   * User-defined display label — NFC-normalized, up to 100 GRAPHEMES (not UTF-16
+   * code units; an emoji/flag may span several). Display-only, never used for
+   * routing. Also seeds the billing entity name at purchase.
    */
   label?: string | null;
 
   /**
-   * Body param: Optional Mobilerun Phone purpose slug from GET /numbers/purposes.
+   * Optional purpose from GET /numbers/phones/purposes.
    */
   purpose?: string;
-
-  /**
-   * Header param: Optional request idempotency key.
-   */
-  'Idempotency-Key'?: string;
 }
 
 export interface NumberUpdateParams {
@@ -391,6 +522,13 @@ export interface NumberListParams {
   pageSize?: number;
 }
 
+export interface NumberCapacityParams {
+  /**
+   * ISO 3166-1 alpha-2 country code from GET /numbers/phones/countries.
+   */
+  country: string;
+}
+
 Numbers.Messages = Messages;
 
 export declare namespace Numbers {
@@ -400,16 +538,20 @@ export declare namespace Numbers {
     type NumberUpdateResponse as NumberUpdateResponse,
     type NumberListResponse as NumberListResponse,
     type NumberDeleteResponse as NumberDeleteResponse,
+    type NumberCapacityResponse as NumberCapacityResponse,
     type NumberCountriesResponse as NumberCountriesResponse,
     type NumberPurposesResponse as NumberPurposesResponse,
     type NumberCreateParams as NumberCreateParams,
     type NumberUpdateParams as NumberUpdateParams,
     type NumberListParams as NumberListParams,
+    type NumberCapacityParams as NumberCapacityParams,
   };
 
   export {
     Messages as Messages,
     type MessageListResponse as MessageListResponse,
+    type MessageSendResponse as MessageSendResponse,
     type MessageListParams as MessageListParams,
+    type MessageSendParams as MessageSendParams,
   };
 }