@mobilerun/sdk 5.4.0 → 5.6.0

package/src/resources/mailboxes/mailboxes.ts

@@ -2,6 +2,13 @@
 
 import { APIResource } from '../../core/resource';
 import * as Shared from '../shared';
+import * as ConnectionsAPI from './connections';
+import {
+  ConnectionCreateParams,
+  ConnectionCreateResponse,
+  ConnectionRetrieveResponse,
+  Connections,
+} from './connections';
 import * as MessagesAPI from './messages';
 import {
   MessageListParams,
@@ -15,25 +22,25 @@ import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
 export class Mailboxes extends APIResource {
+  connections: ConnectionsAPI.Connections = new ConnectionsAPI.Connections(this._client);
   messages: MessagesAPI.Messages = new MessagesAPI.Messages(this._client);
 
   /**
-   * Reserves a permanently-allocated, individually-rented mailbox and starts an
-   * Autumn rental checkout. An optional localPart selects the full address local
-   * part; omitting it keeps the default random, non-guessable mx\_-prefixed address.
-   * The address is withheld until the first payment is confirmed. Idempotent on
-   * (owner, clientRequestId): same key + payload replays (200); a conflicting or
-   * already-held local part returns 409. 201 when the checkout URL is already
-   * persisted, otherwise 202 (poll GET for the URL).
+   * Creates a mailbox on the default domain or a connected custom domain. An
+   * optional `localPart` selects the address. Replaying the same Idempotency-Key
+   * (or, during migration, the deprecated `clientRequestId` body field) and payload
+   * returns the original mailbox. Poll the mailbox when a 202 response does not yet
+   * include a checkout URL.
    *
    * @example
    * ```ts
-   * const mailbox = await client.mailboxes.create({
-   *   clientRequestId: 'x',
-   * });
+   * const mailbox = await client.mailboxes.create();
    * ```
    */
-  create(body: MailboxCreateParams, options?: RequestOptions): APIPromise<MailboxCreateResponse> {
+  create(
+    body: MailboxCreateParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<MailboxCreateResponse> {
     return this._client.post('/mailboxes', { body, ...options });
   }
 
@@ -86,10 +93,9 @@ export class Mailboxes extends APIResource {
   }
 
   /**
-   * For paid rent, schedules end-of-cycle cancellation. For an included generation,
-   * archives immediately and releases its package seat. This never deletes the
-   * mailbox, its address, or its messages — the address is permanently reserved.
-   * Idempotent.
+   * Cancels a pending mailbox or schedules an active paid mailbox for cancellation.
+   * Existing addresses and messages are retained. Repeating the request is safe. An
+   * external inbox (Gmail) cannot be cancelled here; disconnect the link instead.
    *
    * @example
    * ```ts
@@ -103,8 +109,7 @@ export class Mailboxes extends APIResource {
   }
 
   /**
-   * Returns the authoritative number of package-funded mailbox claims currently
-   * available after local reservations.
+   * Returns the number of mailboxes currently available through included capacity.
    *
    * @example
    * ```ts
@@ -116,9 +121,22 @@ export class Mailboxes extends APIResource {
   }
 
   /**
-   * Returns the highest-confidence, most recent OTP for the mailbox, restricted to
-   * messages of completed/active paid intervals. Does not wait server-side (SDKs
-   * poll). 200 with the best code, 204 when none matches.
+   * Removes only this mailbox link. The agent Composio connection stays in place.
+   *
+   * @example
+   * ```ts
+   * const response = await client.mailboxes.disconnect(
+   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   * );
+   * ```
+   */
+  disconnect(mailboxID: string, options?: RequestOptions): APIPromise<MailboxDisconnectResponse> {
+    return this._client.post(path`/mailboxes/${mailboxID}/disconnect`, options);
+  }
+
+  /**
+   * Returns the most likely recent OTP for the mailbox. Returns 204 when no matching
+   * code is available.
    *
    * @example
    * ```ts
@@ -136,8 +154,8 @@ export class Mailboxes extends APIResource {
   }
 
   /**
-   * Starts a new generation on an archived mailbox, reusing the same permanent
-   * address. Uses included capacity first unless paid rent is requested.
+   * Restarts an archived mailbox with the same address. Uses included capacity when
+   * available unless paid service is requested.
    *
    * @example
    * ```ts
@@ -155,8 +173,8 @@ export class Mailboxes extends APIResource {
   }
 
   /**
-   * Retracts a scheduled end-of-cycle cancellation for the current generation. Only
-   * valid while cancellation is pending.
+   * Withdraws a scheduled cancellation. Only available while cancellation is
+   * pending.
    *
    * @example
    * ```ts
@@ -180,7 +198,7 @@ export namespace MailboxCreateResponse {
 
     address: string | null;
 
-    billingMode: 'rent' | 'included';
+    billingMode: 'rent' | 'included' | 'domain' | 'external';
 
     cancelAtPeriodEnd: boolean;
 
@@ -192,17 +210,24 @@ export namespace MailboxCreateResponse {
 
     currentPeriodEnd: string | null;
 
+    domainId: string | null;
+
     inboundMessages: Data.InboundMessages;
 
     label: string | null;
 
+    provider: 'matix' | 'gmail';
+
     status:
       | 'provisioning'
       | 'awaiting_payment'
       | 'active'
       | 'cancel_scheduled'
       | 'archived'
-      | 'billing_error';
+      | 'billing_error'
+      | 'pending_connection'
+      | 'connection_expired'
+      | 'connection_removed';
   }
 
   export namespace Data {
@@ -228,7 +253,7 @@ export namespace MailboxRetrieveResponse {
 
     address: string | null;
 
-    billingMode: 'rent' | 'included';
+    billingMode: 'rent' | 'included' | 'domain' | 'external';
 
     cancelAtPeriodEnd: boolean;
 
@@ -240,17 +265,24 @@ export namespace MailboxRetrieveResponse {
 
     currentPeriodEnd: string | null;
 
+    domainId: string | null;
+
     inboundMessages: Data.InboundMessages;
 
     label: string | null;
 
+    provider: 'matix' | 'gmail';
+
     status:
       | 'provisioning'
       | 'awaiting_payment'
       | 'active'
       | 'cancel_scheduled'
       | 'archived'
-      | 'billing_error';
+      | 'billing_error'
+      | 'pending_connection'
+      | 'connection_expired'
+      | 'connection_removed';
   }
 
   export namespace Data {
@@ -276,7 +308,7 @@ export namespace MailboxUpdateResponse {
 
     address: string | null;
 
-    billingMode: 'rent' | 'included';
+    billingMode: 'rent' | 'included' | 'domain' | 'external';
 
     cancelAtPeriodEnd: boolean;
 
@@ -288,17 +320,24 @@ export namespace MailboxUpdateResponse {
 
     currentPeriodEnd: string | null;
 
+    domainId: string | null;
+
     inboundMessages: Data.InboundMessages;
 
     label: string | null;
 
+    provider: 'matix' | 'gmail';
+
     status:
       | 'provisioning'
       | 'awaiting_payment'
       | 'active'
       | 'cancel_scheduled'
       | 'archived'
-      | 'billing_error';
+      | 'billing_error'
+      | 'pending_connection'
+      | 'connection_expired'
+      | 'connection_removed';
   }
 
   export namespace Data {
@@ -326,7 +365,7 @@ export namespace MailboxListResponse {
 
     address: string | null;
 
-    billingMode: 'rent' | 'included';
+    billingMode: 'rent' | 'included' | 'domain' | 'external';
 
     cancelAtPeriodEnd: boolean;
 
@@ -338,17 +377,24 @@ export namespace MailboxListResponse {
 
     currentPeriodEnd: string | null;
 
+    domainId: string | null;
+
     inboundMessages: Item.InboundMessages;
 
     label: string | null;
 
+    provider: 'matix' | 'gmail';
+
     status:
       | 'provisioning'
       | 'awaiting_payment'
       | 'active'
       | 'cancel_scheduled'
       | 'archived'
-      | 'billing_error';
+      | 'billing_error'
+      | 'pending_connection'
+      | 'connection_expired'
+      | 'connection_removed';
   }
 
   export namespace Item {
@@ -374,7 +420,7 @@ export namespace MailboxDeleteResponse {
 
     address: string | null;
 
-    billingMode: 'rent' | 'included';
+    billingMode: 'rent' | 'included' | 'domain' | 'external';
 
     cancelAtPeriodEnd: boolean;
 
@@ -386,17 +432,24 @@ export namespace MailboxDeleteResponse {
 
     currentPeriodEnd: string | null;
 
+    domainId: string | null;
+
     inboundMessages: Data.InboundMessages;
 
     label: string | null;
 
+    provider: 'matix' | 'gmail';
+
     status:
       | 'provisioning'
       | 'awaiting_payment'
       | 'active'
       | 'cancel_scheduled'
       | 'archived'
-      | 'billing_error';
+      | 'billing_error'
+      | 'pending_connection'
+      | 'connection_expired'
+      | 'connection_removed';
   }
 
   export namespace Data {
@@ -418,7 +471,68 @@ export interface MailboxCapacityResponse {
 
 export namespace MailboxCapacityResponse {
   export interface Data {
+    included: number;
+
     includedRemaining: number;
+
+    remaining: number;
+
+    status: 'available' | 'exhausted' | 'not_included';
+  }
+}
+
+export interface MailboxDisconnectResponse {
+  data: MailboxDisconnectResponse.Data;
+}
+
+export namespace MailboxDisconnectResponse {
+  export interface Data {
+    id: string;
+
+    address: string | null;
+
+    billingMode: 'rent' | 'included' | 'domain' | 'external';
+
+    cancelAtPeriodEnd: boolean;
+
+    checkoutExpiresAt: string | null;
+
+    checkoutUrl: string | null;
+
+    createdAt: string;
+
+    currentPeriodEnd: string | null;
+
+    domainId: string | null;
+
+    inboundMessages: Data.InboundMessages;
+
+    label: string | null;
+
+    provider: 'matix' | 'gmail';
+
+    status:
+      | 'provisioning'
+      | 'awaiting_payment'
+      | 'active'
+      | 'cancel_scheduled'
+      | 'archived'
+      | 'billing_error'
+      | 'pending_connection'
+      | 'connection_expired'
+      | 'connection_removed';
+  }
+
+  export namespace Data {
+    export interface InboundMessages {
+      exhausted: boolean;
+
+      included: number;
+
+      resetsAt: string | null;
+
+      used: number;
+    }
   }
 }
 
@@ -429,7 +543,7 @@ export interface MailboxOtpResponse {
 export namespace MailboxOtpResponse {
   export interface Data {
     /**
-     * String to preserve leading zeros
+     * OTP code as text to preserve leading zeros.
      */
     code: string;
 
@@ -455,7 +569,7 @@ export namespace MailboxRestartResponse {
 
     address: string | null;
 
-    billingMode: 'rent' | 'included';
+    billingMode: 'rent' | 'included' | 'domain' | 'external';
 
     cancelAtPeriodEnd: boolean;
 
@@ -467,17 +581,24 @@ export namespace MailboxRestartResponse {
 
     currentPeriodEnd: string | null;
 
+    domainId: string | null;
+
     inboundMessages: Data.InboundMessages;
 
     label: string | null;
 
+    provider: 'matix' | 'gmail';
+
     status:
       | 'provisioning'
       | 'awaiting_payment'
       | 'active'
       | 'cancel_scheduled'
       | 'archived'
-      | 'billing_error';
+      | 'billing_error'
+      | 'pending_connection'
+      | 'connection_expired'
+      | 'connection_removed';
   }
 
   export namespace Data {
@@ -503,7 +624,7 @@ export namespace MailboxUncancelResponse {
 
     address: string | null;
 
-    billingMode: 'rent' | 'included';
+    billingMode: 'rent' | 'included' | 'domain' | 'external';
 
     cancelAtPeriodEnd: boolean;
 
@@ -515,17 +636,24 @@ export namespace MailboxUncancelResponse {
 
     currentPeriodEnd: string | null;
 
+    domainId: string | null;
+
     inboundMessages: Data.InboundMessages;
 
     label: string | null;
 
+    provider: 'matix' | 'gmail';
+
     status:
       | 'provisioning'
       | 'awaiting_payment'
       | 'active'
       | 'cancel_scheduled'
       | 'archived'
-      | 'billing_error';
+      | 'billing_error'
+      | 'pending_connection'
+      | 'connection_expired'
+      | 'connection_removed';
   }
 
   export namespace Data {
@@ -542,20 +670,23 @@ export namespace MailboxUncancelResponse {
 }
 
 export interface MailboxCreateParams {
-  clientRequestId: string;
+  /**
+   * included uses package capacity when available and otherwise starts paid
+   * checkout; included_only fails without creating a paid reservation when no
+   * included slot remains; rent always starts paid checkout.
+   */
+  billingPreference?: 'included' | 'included_only' | 'rent';
 
   /**
-   * Funding preference. Omit or use included for included-first activation; rent
-   * always preserves package capacity and starts paid checkout.
+   * Optional active custom mailbox domain owned by the caller. Omit to use the
+   * system domain.
    */
-  billingPreference?: 'included' | 'rent';
+  domainId?: string;
 
   label?: string;
 
   /**
-   * Optional full mailbox local part (the address before "@"). Trimmed and
-   * lowercased before validation. Omit for a random, non-guessable mx\_-prefixed
-   * address.
+   * Optional mailbox name before the "@". Omit to generate a random address.
    */
   localPart?: string;
 }
@@ -582,12 +713,14 @@ export interface MailboxOtpParams {
 
 export interface MailboxRestartParams {
   /**
-   * Funding preference. Omit or use included for included-first activation; rent
-   * always preserves package capacity and starts paid checkout.
+   * included uses package capacity when available and otherwise starts paid
+   * checkout; included_only fails without creating a paid reservation when no
+   * included slot remains; rent always starts paid checkout.
    */
-  billingPreference?: 'included' | 'rent';
+  billingPreference?: 'included' | 'included_only' | 'rent';
 }
 
+Mailboxes.Connections = Connections;
 Mailboxes.Messages = Messages;
 
 export declare namespace Mailboxes {
@@ -598,6 +731,7 @@ export declare namespace Mailboxes {
     type MailboxListResponse as MailboxListResponse,
     type MailboxDeleteResponse as MailboxDeleteResponse,
     type MailboxCapacityResponse as MailboxCapacityResponse,
+    type MailboxDisconnectResponse as MailboxDisconnectResponse,
     type MailboxOtpResponse as MailboxOtpResponse,
     type MailboxRestartResponse as MailboxRestartResponse,
     type MailboxUncancelResponse as MailboxUncancelResponse,
@@ -608,6 +742,13 @@ export declare namespace Mailboxes {
     type MailboxRestartParams as MailboxRestartParams,
   };
 
+  export {
+    Connections as Connections,
+    type ConnectionCreateResponse as ConnectionCreateResponse,
+    type ConnectionRetrieveResponse as ConnectionRetrieveResponse,
+    type ConnectionCreateParams as ConnectionCreateParams,
+  };
+
   export {
     Messages as Messages,
     type MessageRetrieveResponse as MessageRetrieveResponse,

package/src/resources/mailboxes/messages.ts

@@ -27,8 +27,8 @@ export class Messages extends APIResource {
   }
 
   /**
-   * Lists messages for a mailbox with keyset pagination and time/sender/hasOtp
-   * filters for polling.
+   * Lists mailbox messages with cursor pagination and optional time, sender, and OTP
+   * filters.
    *
    * @example
    * ```ts

package/src/resources/messages/conversations.ts

@@ -6,17 +6,8 @@ import { RequestOptions } from '../../internal/request-options';
 
 export class Conversations extends APIResource {
   /**
-   * Lists the caller's own SMS conversations, one row per thread. Each row includes
-   * the most recent message in the thread, its unread inbound count, and the eSIMs
-   * it was seen through. Optional `esimId` or `numberId` narrows to threads on one
-   * eSIM or number.
-   *
-   * Cursor-paginated via `limit` (default 20, max 100) and
-   * `cursorLastOccurredAt`/`cursorLastMessageId` (both required together, taken from
-   * a previous page's `nextCursor`). Pagination follows each thread's most recent
-   * activity rather than a fixed snapshot, so a thread with new activity can move
-   * ahead of an in-progress page fetch. Clients that need a stable ordering should
-   * snapshot their own view.
+   * Lists SMS conversations by recent activity. Use both cursor fields from
+   * `nextCursor` to fetch the next page.
    */
   list(
     query: ConversationListParams | null | undefined = {},
@@ -26,10 +17,8 @@ export class Conversations extends APIResource {
   }
 
   /**
-   * Marks the caller's own inbound messages in a conversation thread as read, up to
-   * and including the given `(upToOccurredAt, upToMessageId)` cursor — typically a
-   * conversation row's `lastMessage`. Idempotent: repeating the call with the same
-   * cursor updates 0 rows. Returns the number of rows updated.
+   * Marks inbound messages in a conversation as read through the supplied cursor.
+   * Repeating the request is safe.
    */
   markRead(
     body: ConversationMarkReadParams,

package/src/resources/messages/index.ts

@@ -7,4 +7,9 @@ export {
   type ConversationListParams,
   type ConversationMarkReadParams,
 } from './conversations';
-export { Messages, type MessageListResponse, type MessageListParams } from './messages';
+export {
+  Messages,
+  type MessageRetrieveResponse,
+  type MessageListResponse,
+  type MessageListParams,
+} from './messages';

package/src/resources/messages/messages.ts

@@ -12,15 +12,23 @@ import {
 } from './conversations';
 import { APIPromise } from '../../core/api-promise';
 import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
 
 export class Messages extends APIResource {
   conversations: ConversationsAPI.Conversations = new ConversationsAPI.Conversations(this._client);
 
   /**
-   * Lists the caller's own SMS messages, newest first. Supports filtering by
-   * direction, esimId, numberId, status, peerNumber (substring search, min 3
-   * characters), and peerKey (exact thread match). Each row includes its canonical
-   * thread key (`peerKey`).
+   * Returns one message. For an outbound message that is not yet final, the status
+   * may be refreshed once (at most every 30 s) before it is returned; a failed
+   * refresh returns the stored message.
+   */
+  retrieve(id: string, options?: RequestOptions): APIPromise<MessageRetrieveResponse> {
+    return this._client.get(path`/numbers/messages/${id}`, options);
+  }
+
+  /**
+   * Lists SMS messages newest first, with filters for direction, eSIM, phone number,
+   * status, and conversation.
    */
   list(
     query: MessageListParams | null | undefined = {},
@@ -30,6 +38,46 @@ export class Messages extends APIResource {
   }
 }
 
+export interface MessageRetrieveResponse {
+  data: MessageRetrieveResponse.Data;
+}
+
+export namespace MessageRetrieveResponse {
+  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;
+
+    providerCode: string | null;
+
+    status:
+      | 'received'
+      | 'queued'
+      | 'claimed'
+      | 'sending'
+      | 'sent'
+      | 'sent_unconfirmed'
+      | 'delivered'
+      | 'failed';
+  }
+}
+
 export interface MessageListResponse {
   items: Array<MessageListResponse.Item>;
 
@@ -102,7 +150,11 @@ export interface MessageListParams {
 Messages.Conversations = Conversations;
 
 export declare namespace Messages {
-  export { type MessageListResponse as MessageListResponse, type MessageListParams as MessageListParams };
+  export {
+    type MessageRetrieveResponse as MessageRetrieveResponse,
+    type MessageListResponse as MessageListResponse,
+    type MessageListParams as MessageListParams,
+  };
 
   export {
     Conversations as Conversations,