@relaymessenger/sdk 0.3.6-staging.3 → 0.3.6-staging.30

package/dist/types.d.ts

@@ -11,24 +11,22 @@ export interface CallContact {
     handle: string;
     kind: "user" | "agent";
 }
+export type CallTerminalStatus = "completed" | "no-answer" | "canceled" | "busy" | "failed";
 export interface Call {
     id: UUID;
     chat_id: UUID;
     from: CallContact;
     to: [CallContact];
-    mode: "audio";
-    status: "ringing" | "connecting" | "active" | "ended";
+    /** `ringing` and `in-progress` are live. Terminal states set `ended_at`. */
+    status: "ringing" | "in-progress" | CallTerminalStatus;
     revision: number;
     created_at: string;
     ringing_at: string;
     answered_at: string | null;
-    connected_at: string | null;
     ended_at: string | null;
-    end_reason: "completed" | "declined" | "canceled" | "no_answer" | "disconnected" | "failed" | null;
 }
 export interface CallCreateParams {
     to: [string];
-    mode: "audio";
 }
 export interface CallCreateOptions extends RequestOptions {
     /** Reuse this key and request after an uncertain response. */
@@ -45,49 +43,291 @@ export interface CallListResponse {
 export interface CallResponse {
     call: Call;
 }
-export interface CallAudioFormat {
-    encoding: "pcm_s16le";
-    sample_rate: 48000;
-    channels: 2;
+/** A participant's published local track, named on the SFU. */
+export type CallRoomTrackName = "audio" | "video";
+export interface CallRoomParticipant {
+    contact_id: UUID;
+    kind: "user" | "agent";
+    attached: boolean;
+    track: "audio" | null;
+    muted: boolean;
+    connected: boolean;
+    /** Camera sending, from this participant's `userUpdate`. */
+    video?: boolean;
+    /** Tracks this participant has published: `[]` before its first offer, then `["audio"]` or `["audio", "video"]`. */
+    tracks?: CallRoomTrackName[];
+    /**
+     * The other participant's tracks this participant is receiving now: its
+     * pull answer is applied and it sent `connected` for it. Reset on restart.
+     */
+    receiving?: CallRoomTrackName[];
 }
-export type CallConnectionCreateParams = {
-    transport: "websocket";
-} | {
-    transport: "webrtc";
+export interface CallRoomJoinFrame {
+    type: "join";
+}
+export interface CallRoomPublishOfferFrame {
+    type: "offer";
     session_description: {
         type: "offer";
         sdp: string;
     };
+    /** One or two tracks, `audio` first, no duplicate names. */
     tracks: [{
         mid: string;
-        name: "microphone";
+        name: "audio";
+    }] | [{
+        mid: string;
+        name: "audio";
+    }, {
+        mid: string;
+        name: "video";
+    }] | [{
+        mid: string;
+        name: "video";
     }];
-};
-export interface CallWebSocketConnection {
-    id: UUID;
-    call_id: UUID;
-    transport: "websocket";
-    url: string;
-    /** Ephemeral Relay grant, supplied as the media WebSocket bearer token. */
-    token: string;
-    expires_at: string;
-    audio_format: CallAudioFormat;
+    /** The previous session is dead: publish on a brand-new session from a new peer connection. */
+    restart?: boolean;
 }
-export interface CallWebRTCConnection {
-    id: UUID;
-    call_id: UUID;
-    transport: "webrtc";
+export interface CallRoomAnswerFrame {
+    type: "answer";
     session_description: {
         type: "answer";
         sdp: string;
     };
 }
-export interface CallConnectionResponse {
-    connection: CallWebSocketConnection | CallWebRTCConnection;
+export interface CallRoomConnectedFrame {
+    type: "connected";
+}
+export interface CallRoomUserUpdateFrame {
+    type: "userUpdate";
+    muted: boolean;
+    /** Camera sending. Omitted keeps the last value. */
+    video?: boolean;
+}
+export interface CallRoomEndFrame {
+    type: "end";
+}
+export interface CallRoomHeartbeatFrame {
+    type: "heartbeat";
+}
+export type CallRoomClientFrame = CallRoomJoinFrame | CallRoomPublishOfferFrame | CallRoomAnswerFrame | CallRoomConnectedFrame | CallRoomUserUpdateFrame | CallRoomEndFrame | CallRoomHeartbeatFrame;
+export interface CallRoomStateFrame {
+    type: "roomState";
+    call: Call;
+    participants: [CallRoomParticipant, CallRoomParticipant];
+}
+export interface CallRoomServerAnswerFrame {
+    type: "answer";
+    session_description: {
+        type: "answer";
+        sdp: string;
+    };
 }
+export interface CallRoomSubscriptionOfferFrame {
+    type: "offer";
+    session_description: {
+        type: "offer";
+        sdp: string;
+    };
+    /** The other participant's track this renegotiation pulls. */
+    track: CallRoomTrackName;
+}
+export interface CallRoomEndedFrame {
+    type: "ended";
+    reason: CallTerminalStatus;
+}
+export type CallRoomErrorCode = "invalid_frame" | "not_allowed" | "media_unavailable";
+export interface CallRoomErrorFrame {
+    type: "error";
+    code: CallRoomErrorCode;
+    message: string;
+}
+/** Standard `RTCIceServer`: STUN or TURN URLs, with credentials on TURN servers. */
+export interface CallRoomIceServer {
+    urls: string[];
+    username?: string;
+    credential?: string;
+}
+/**
+ * STUN and TURN servers for this participant's peer connection, sent after
+ * every accepted `join` and before the first `roomState` (Orange Meets shape:
+ * Cloudflare TURN credentials minted by the server).
+ */
+export interface CallRoomIceServersFrame {
+    type: "iceServers";
+    ice_servers: CallRoomIceServer[];
+}
+export type CallRoomServerFrame = CallRoomIceServersFrame | CallRoomStateFrame | CallRoomServerAnswerFrame | CallRoomSubscriptionOfferFrame | CallRoomEndedFrame | CallRoomErrorFrame;
 export type CallWebhookEvent = RelayWebhookEnvelope<CallResponse, "call.created" | "call.updated" | "call.ended">;
+/** Subscription mode only. One coupon or one promotion code from your connected Stripe account, never both. */
+export interface PaymentDiscount {
+    /** The id of a coupon on your connected Stripe account. */
+    coupon?: string;
+    /** The id of a promotion code (`promo_...`), not the code a customer types. */
+    promotion_code?: string;
+    /** Your own name for the discount, stored and returned with the request. */
+    label?: string;
+}
+/**
+ * `POST /v1/payment_requests`. Payment mode needs `amount` and `currency`;
+ * subscription mode needs `price_id` and takes the currency from the price.
+ */
+export interface PaymentRequestCreateParams {
+    /** Payment mode: what to charge, in the currency's minor units. */
+    amount?: number;
+    /** Payment mode: a 3-letter ISO 4217 code, returned lowercase. */
+    currency?: string;
+    /** The card's title line and the checkout's product name. Trimmed; 1 to 32 characters. */
+    description: string;
+    category: PaymentCategory;
+    /** Up to 49 keys of your own; keys starting with `relay_` are reserved. */
+    metadata?: Record<string, string>;
+    /** Defaults to `payment`. */
+    mode?: PaymentMode;
+    /** Subscription mode: an active recurring Price on your connected Stripe account. */
+    price_id?: string;
+    /** Subscription mode: units of the price. Defaults to 1. */
+    quantity?: number;
+    /** An existing Customer on your connected Stripe account (`cus_...`). */
+    customer_id?: string;
+    discount?: PaymentDiscount;
+    /** Optional HTTPS product picture; Relay copies it into its own image store. */
+    image_url?: string;
+}
+export interface PaymentRequestCreateOptions extends RequestOptions {
+    /** Reusing a key with the same body returns the first request (200); with a different body, 409. */
+    idempotencyKey?: string;
+}
+/** The ids of the Stripe objects on your connected account. */
+export interface PaymentRequestStripe {
+    /** The one PaymentIntent the person pays (`pi_...`). */
+    payment_intent_id: string;
+    customer_id?: string;
+    /** Subscription mode (`sub_...`). */
+    subscription_id?: string;
+}
+export interface PaymentRequest {
+    id: UUID;
+    object: "payment_request";
+    status: PaymentStatus;
+    mode: PaymentMode;
+    /** What the person is charged at checkout, in minor units. */
+    amount: number;
+    /** Relay's 5% fee in minor units. */
+    application_fee_amount: number;
+    currency: string;
+    description: string;
+    category: PaymentCategory;
+    /** Relay's pay page for this request. Send it back unchanged in a `payment` part. */
+    checkout_url: string;
+    /** 23 hours after creation; the request then moves to `expired`. */
+    expires_at: string;
+    metadata: Record<string, string>;
+    image_url?: string;
+    price_id?: string;
+    quantity?: number;
+    interval?: PaymentRecurring["interval"];
+    interval_count?: number;
+    discount?: PaymentDiscount;
+    stripe: PaymentRequestStripe;
+    /** Absent until the request succeeds. */
+    paid_at?: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface PaymentRequestListParams {
+    cursor?: string;
+    /** 1 to 100; defaults to 20. */
+    limit?: number;
+    status?: PaymentStatus;
+}
+export interface PaymentRequestListResponse {
+    payment_requests: PaymentRequest[];
+    next_cursor: string | null;
+}
+/** `POST /v1/chats/{chatId}/location/request` answers with this once the request is in the chat. */
+export interface LocationRequestResponse {
+    success: true;
+    message: "Location request sent";
+}
+/** One person sharing their location with your agent, as a GeoJSON Feature (RFC 7946). */
+export interface LocationFeature {
+    type: "Feature";
+    geometry: {
+        type: "Point";
+        /** `[longitude, latitude]`, longitude first. */
+        coordinates: [number, number];
+    };
+    properties: {
+        /** Handle of the person sharing. */
+        handle: string;
+        /** When this position arrived. */
+        updated_at: string;
+    };
+}
+/**
+ * `GET /v1/chats/{chatId}/location`: one Feature per person sharing with your
+ * agent in the chat; `features` is empty when nobody is sharing.
+ */
+export interface GetChatLocationResponse {
+    success: true;
+    data: {
+        type: "FeatureCollection";
+        features: LocationFeature[];
+    };
+}
+/** `location.sharing.started`: a person started sharing their location with your agent. */
+export interface LocationSharingStartedEvent {
+    /** Handle of the person who started sharing. */
+    shared_by: string;
+    /** Handle of your agent. */
+    shared_with: string;
+    chat_id: UUID;
+    began_at: string;
+    /** When the share ends by itself; null when it has no end. */
+    ends_at: string | null;
+}
+/** `location.sharing.stopped`: the person stopped sharing, or the share reached its end. */
+export interface LocationSharingStoppedEvent {
+    /** Handle of the person who stopped sharing. */
+    shared_by: string;
+    /** Handle of your agent. */
+    shared_with: string;
+    chat_id: UUID;
+    began_at: string;
+    /** When the share ended. Equals the share's `ends_at` when it ran out. */
+    ended_at: string;
+}
+export type LocationSharingStartedWebhookEvent = RelayWebhookEnvelope<LocationSharingStartedEvent, "location.sharing.started">;
+export type LocationSharingStoppedWebhookEvent = RelayWebhookEnvelope<LocationSharingStoppedEvent, "location.sharing.stopped">;
+export type PaymentWebhookEvent = RelayWebhookEnvelope<PaymentRequest, "payment.succeeded" | "payment.canceled" | "payment.expired">;
 export type DeliveryStatus = "sent" | "delivered" | "read";
 export type ReactionType = "love" | "like" | "dislike" | "laugh" | "emphasize" | "question" | "custom";
+export interface ChatActivity {
+    id: UUID;
+    text: string;
+    emoji: string | null;
+    updated_at: string;
+    expires_at: string;
+}
+export interface ChatActivityResponse {
+    chat_id: UUID;
+    agent_id: UUID;
+    version: string;
+    activity: ChatActivity | null;
+}
+export interface ChatSetActivityParams {
+    /** 1–21 visible characters, at most 1024 UTF-8 bytes. */
+    text: string;
+    /** One Unicode emoji, or null. */
+    emoji?: string | null;
+    /** Omit to start/replace; supply the current ID to refresh/update. */
+    activity_id?: UUID;
+}
+export interface ChatClearActivityParams {
+    /** Clear only this task. A stale or missing activity is a successful no-op. */
+    activity_id?: UUID;
+}
 interface ChatHandleBase {
     id: UUID;
     handle: string;
@@ -97,10 +337,12 @@ interface ChatHandleBase {
     is_me?: boolean | null;
     display_name: string | null;
     image_url: string | null;
-    about: string | null;
+    subtitle: string | null;
     verified: boolean;
     /** True when the caller holds this Handle as a Contact. */
     is_contact: boolean;
+    activity_version?: string;
+    activity?: ChatActivity | null;
 }
 export interface UserChatHandle extends ChatHandleBase {
     kind: "user";
@@ -130,32 +372,346 @@ export interface LinkPart {
     type: "link";
     value: string;
 }
-/** One button in a `buttons`. Exactly one of `id` or `url`. */
+/**
+ * One button in a `buttons`. A tap on a plain button sends its `label` back
+ * as the person's next message: one `text` part whose value is the label,
+ * with `reply_to` naming the `buttons` part. A `url` button opens the page
+ * in the app and sends nothing.
+ */
 export interface ButtonItem {
-    /** Callback button: the tap arrives as a `button_reply` carrying this id. */
-    id?: string;
-    /** Link button: the tap opens this HTTPS URL and sends nothing. */
+    /** Link button: the tap opens this HTTPS URL instead of sending the label. */
     url?: string;
+    /** The button's visible text, 1 to 80 characters, and what a tap sends. */
     label: string;
 }
 /**
  * Agent-only: a vertical stack of 1 to 5 text-only buttons under the message.
- * Only button_reply may target this part; ordinary replies and reactions may not.
+ * At most one per message. The only reply it accepts is a tap; reactions may
+ * not target it.
  */
 export interface ButtonsPart {
     type: "buttons";
     items: ButtonItem[];
 }
+/** Stable machine value and independently editable visible label. */
+export interface SelectionOption {
+    /** Unique case-sensitive ASCII token, 1–100 characters. Never derived from label. */
+    value: string;
+    /** Trimmed visible label, 1–80 characters. */
+    label: string;
+}
+/** Agent-only, 1–25 options; requires nonblank text and cannot mix with buttons. */
+export interface SelectionPart {
+    type: "selection";
+    /** The text is the prompt's title; the person checks any number of options and submits them once, and checking sends nothing. */
+    options: SelectionOption[];
+}
+export interface SelectionPartResponse extends SelectionPart {
+    /** Durable response state for this viewer across devices. Existing Chat rules allow at most one human user; only that user can respond, once; reopening an answered selection shows what they chose without letting them change it. */
+    readonly has_responded: boolean;
+    /** The values the authenticated viewer chose, in source-option order, identical on every one of that user's devices; null until the viewer answers, when the answer Message no longer exists, and always for an agent viewer. */
+    readonly selected_values: string[] | null;
+    reactions: null;
+}
+/**
+ * User-only metadata after canonical text (literal '• ' + each source
+ * label, joined with '\n'), with explicit reply_to. Exact legacy comma-joined
+ * labels are accepted by the server only for compatibility, never parsed for IDs.
+ */
+export interface SelectionResponsePart {
+    type: "selection_response";
+    /**
+     * Unique known values, nonempty and in source-option order, authoritative with
+     * reply_to. New preceding text is literal '• ' + each source label joined with
+     * '\n'. The server accepts exact legacy comma-joined labels for compatibility
+     * only, never arbitrary label parsing. iOS may draw a checkmark in place of
+     * each bullet and repeat the prompt's title, as presentation only; portable
+     * text remains bullets.
+     */
+    selected_values: string[];
+}
+/** Metadata only: contributes no visible fallback text. */
+export interface SelectionResponsePartResponse extends SelectionResponsePart {
+}
+/** What is being paid for (PayPal Orders v2 `items[].category`); App Store rules decide where each is payable. */
+export type PaymentCategory = "physical_goods" | "digital_goods" | "donation";
+/** A payment request's lifecycle. It leaves `requested` exactly once, only on Stripe's word or your cancel. */
+export type PaymentStatus = "requested" | "succeeded" | "canceled" | "expired";
+/** `payment` collects one charge; `subscription` starts a Stripe subscription from a recurring price. */
+export type PaymentMode = "payment" | "subscription";
+/** A subscription's renewal cadence, read from its Stripe Price. */
+export interface PaymentRecurring {
+    interval: "day" | "week" | "month" | "year";
+    /** Intervals per renewal (3 with `month` is quarterly). */
+    interval_count: number;
+}
+/**
+ * A request to pay, drawn as a card. `checkout_url` is the only field: pass
+ * back exactly what `paymentRequests.create` returned. The card's amount and
+ * title are read from that request, never from the message. Sent only by the
+ * agent that created the request, while it is `requested`; it must be the only
+ * part of its message.
+ */
+export interface PaymentPart {
+    type: "payment";
+    /** At most 2048 characters. */
+    checkout_url: string;
+}
+/** A payment card as every reader sees it, read from the payment request. `status` changes in place. */
+export interface PaymentPartResponse {
+    type: "payment";
+    payment_request_id: UUID;
+    checkout_url: string;
+    /** Minor units. For a subscription, what the first period costs. */
+    amount: number;
+    currency: string;
+    /** The card's title line. */
+    description: string;
+    category: PaymentCategory;
+    mode: PaymentMode;
+    recurring?: PaymentRecurring;
+    /** The request's product picture, when it has one. */
+    image_url?: string;
+    status: PaymentStatus;
+    /** Only a person can react to a payment. */
+    reactions: Reaction[] | null;
+}
+/**
+ * The payer's receipt: Relay adds one message from the person who paid, a
+ * reply to the `payment` card, when a request succeeds. It arrives as
+ * `message.received`. Only Relay writes this part.
+ */
+export interface PaymentReceiptPartResponse {
+    type: "payment_receipt";
+    payment_request_id: UUID;
+    description: string;
+    /** What was paid, in minor units. For a subscription, what the first period cost. */
+    amount: number;
+    currency: string;
+    mode: PaymentMode;
+    recurring?: PaymentRecurring;
+    reactions: Reaction[] | null;
+}
+/**
+ * An agent's request for the person's location, sent with
+ * `chats.location.request`. It cannot be sent as a message part. A client that
+ * does not draw it shows the Message's text, "<agent display name> requested
+ * your location".
+ */
+export interface LocationRequestPartResponse {
+    type: "location_request";
+    reactions: Reaction[] | null;
+}
+/**
+ * A person's location share, the card the person's app draws. It carries the
+ * share's state, never its position: read the position with
+ * `chats.location.retrieve`. It cannot be sent as a message part. A share whose
+ * `ends_at` has passed reads as `ended` with `ended_at` equal to `ends_at`.
+ */
+export interface LocationPartResponse {
+    type: "location";
+    state: "live" | "ended";
+    began_at: string | null;
+    /** When the share ends by itself; null when it has no end. */
+    ends_at: string | null;
+    ended_at: string | null;
+    reactions: Reaction[] | null;
+}
+/**
+ * A place sent once: a person's current location, a dropped pin, or a place an
+ * agent names (Relay-Server contract `PlacePart`; WhatsApp Cloud API's location
+ * fields). `name` and `address` are 1 to 256 characters after trimming.
+ */
+export interface PlacePart {
+    type: "place";
+    /** Latitude in degrees (WGS 84), -90 to 90. */
+    latitude: number;
+    /** Longitude in degrees (WGS 84), -180 to 180. */
+    longitude: number;
+    name?: string;
+    address?: string;
+}
+/** A place as its sender sent it; `name` and `address` are absent when left out. */
+export interface PlacePartResponse extends PlacePart {
+    reactions: Reaction[] | null;
+}
 /**
- * A user's tap on a `buttons` item. Must be the only part, and
- * `reply_to` must name the message and part index of the `buttons`.
+ * A2UI v0.9.1 (https://a2ui.org), the messages a card is made of. The shapes
+ * are A2UI's own JSON schemas (`specification/v0_9_1/json/*.json` in
+ * google/A2UI): `server_to_client.json` for what an agent sends to draw a
+ * card, `client_to_server.json` for a tap (`action`) and an `error`. The
+ * version enum is A2UI's (`v0.9` or `v0.9.1`); Relay's contract names v0.9.1.
  */
-export interface ButtonReplyPart {
-    type: "button_reply";
+export type A2uiVersion = "v0.9" | "v0.9.1";
+/**
+ * One component of a surface: `id`, the catalog's `component` name, and that
+ * component's own properties, for example
+ * `{ id: "title", component: "Text", text: "Lakers win tonight?" }`. The
+ * catalog named by `createSurface.catalogId` defines them: Relay refuses a
+ * component, property or value that catalog does not define.
+ */
+export interface A2uiComponent {
     id: string;
-    label: string;
+    component: string;
+    [property: string]: unknown;
+}
+/** A2UI `createSurface`: starts a surface drawn by the Message that carries it. */
+export interface A2uiCreateSurfaceMessage {
+    version: A2uiVersion;
+    createSurface: {
+        surfaceId: string;
+        /** A catalog Relay draws; see `A2uiClientCapabilities`. */
+        catalogId: string;
+        /** Theme values the catalog defines, for example `{ primaryColor: "#FF0000" }`. */
+        theme?: Record<string, unknown>;
+        /** When true, every tap on the surface carries the surface's data model in `metadata.a2uiClientDataModel`. */
+        sendDataModel?: boolean;
+    };
+}
+/** A2UI `updateComponents`: adds or replaces components by `id`. A surface's first update holds the component with the id `root`. */
+export interface A2uiUpdateComponentsMessage {
+    version: A2uiVersion;
+    updateComponents: {
+        surfaceId: string;
+        components: A2uiComponent[];
+    };
 }
-export type MessagePart = TextPart | MediaPart | LinkPart | ButtonsPart | ButtonReplyPart;
+/**
+ * A2UI `updateDataModel`: replaces (or creates) the value at `path`, a JSON
+ * Pointer; no `path`, or `/`, is the whole data model. No `value` removes the
+ * key at `path`.
+ */
+export interface A2uiUpdateDataModelMessage {
+    version: A2uiVersion;
+    updateDataModel: {
+        surfaceId: string;
+        path?: string;
+        value?: unknown;
+    };
+}
+/** A2UI `deleteSurface`: removes the surface for everyone. */
+export interface A2uiDeleteSurfaceMessage {
+    version: A2uiVersion;
+    deleteSurface: {
+        surfaceId: string;
+    };
+}
+/** What an agent sends to draw, change or remove a card (A2UI `server_to_client.json`). */
+export type A2uiServerToClientMessage = A2uiCreateSurfaceMessage | A2uiUpdateComponentsMessage | A2uiUpdateDataModelMessage | A2uiDeleteSurfaceMessage;
+/** The body of an A2UI `action` message: a tap on a Button. */
+export interface A2uiAction {
+    /** The Button's `action.event.name`. */
+    name: string;
+    surfaceId: string;
+    /** The `id` of the Button that was tapped. */
+    sourceComponentId: string;
+    /** ISO 8601 time of the tap. */
+    timestamp: string;
+    /** The Button's `action.event.context`, with every data binding resolved. */
+    context: Record<string, unknown>;
+}
+/** A2UI `action`: a person (or an agent) tapped a Button on a surface. */
+export interface A2uiActionMessage {
+    version: A2uiVersion;
+    action: A2uiAction;
+}
+/** A2UI's validation error: `path` is a JSON Pointer to the field that failed. */
+export interface A2uiValidationError {
+    code: "VALIDATION_FAILED";
+    surfaceId: string;
+    path: string;
+    message: string;
+}
+/** A2UI's generic error: any other `code`. */
+export interface A2uiGenericError {
+    code: string;
+    surfaceId: string;
+    message: string;
+    [property: string]: unknown;
+}
+/** A2UI `error`: a renderer (or an agent) reports that it could not use a message. */
+export interface A2uiErrorMessage {
+    version: A2uiVersion;
+    error: A2uiValidationError | A2uiGenericError;
+}
+/**
+ * A2UI's `error` message in its validation format, as Relay writes it for a
+ * message it did not apply. `surfaceId` is empty when the message named none;
+ * `path` points inside the failing message's body, as in A2UI's own example
+ * `/components/0/text`, and is empty when the whole message is at fault.
+ */
+export interface A2uiValidationErrorMessage {
+    version: "v0.9.1";
+    error: A2uiValidationError;
+}
+/** One A2UI message of a send that Relay did not apply, where it sits in the request, and A2UI's `error` message for it. */
+export interface A2uiFailure {
+    /** The data part's index in `parts`; null when the fault is in `metadata.a2uiClientDataModel`. */
+    part_index: number | null;
+    /** The message's index in that part's `data`; null when the part itself, or the metadata, is at fault. */
+    data_index: number | null;
+    a2ui_message: A2uiValidationErrorMessage;
+}
+/** What a renderer sends back (A2UI `client_to_server.json`). */
+export type A2uiClientToServerMessage = A2uiActionMessage | A2uiErrorMessage;
+/** Any A2UI v0.9.1 message a data part may carry. */
+export type A2uiMessage = A2uiServerToClientMessage | A2uiClientToServerMessage;
+/**
+ * A data part holding A2UI v0.9.1 messages, in order: Relay's REST shape of
+ * A2A's DataPart. A Message may carry any number of data parts beside its
+ * other parts. Relay applies each A2UI message on its own, checked against
+ * A2UI's schemas and the surface's catalog: the ones that fail come back in
+ * the response's `a2ui_errors`, and a send that applies nothing is refused
+ * (404, 409 or 422) with `a2ui_errors` in the error body. Only an agent sends
+ * `createSurface`, `updateComponents`, `updateDataModel` and `deleteSurface`;
+ * a send that only changes an earlier card adds no Message and returns that
+ * card. An `action` or `error` reaches only its sender and the agent that
+ * created the surface it names.
+ */
+export interface DataPart {
+    type: "data";
+    media_type: "application/a2ui+json";
+    data: A2uiMessage[];
+}
+/**
+ * A data part as a reader receives it: the `action` and `error` messages it
+ * carried, as sent, when the reader sent them or created the surface they
+ * name; then, for each surface it created, every A2UI message accepted for
+ * that surface since, in order. Replay the list to draw the card.
+ */
+export interface DataPartResponse extends DataPart {
+    reactions: Reaction[] | null;
+}
+/** A2UI's `a2uiClientDataModel` (`client_data_model.json`): each surface's data model, by surface id. */
+export interface A2uiClientDataModel {
+    version: A2uiVersion;
+    surfaces: Record<string, Record<string, unknown>>;
+}
+/**
+ * A2UI's `a2uiClientCapabilities` (`client_capabilities.json`, keyed by the
+ * protocol family `v0.9`): the catalogs Relay's app draws, in order of
+ * preference. Relay's catalog (`RELAY_A2UI_CATALOG_ID`) is every basic catalog
+ * component and function plus `PaymentRequest`.
+ */
+export interface A2uiClientCapabilities {
+    "v0.9": {
+        supportedCatalogIds: string[];
+        inlineCatalogs?: Array<Record<string, unknown>>;
+    };
+}
+/**
+ * A2A Message metadata. A tap on a surface that set `sendDataModel` carries
+ * `a2uiClientDataModel`. Each surface's data model reaches only the sender and
+ * the agent that created that surface, unchanged.
+ */
+export interface MessageMetadata {
+    a2uiClientDataModel?: A2uiClientDataModel;
+}
+/** The metadata on every `message.received`: the reader's A2UI catalogs, and the sender's data model for the surfaces this agent created, when it sent one. */
+export interface MessageReceivedMetadata extends MessageMetadata {
+    a2uiClientCapabilities: A2uiClientCapabilities;
+}
+export type MessagePart = TextPart | MediaPart | LinkPart | ButtonsPart | SelectionPart | SelectionResponsePart | PaymentPart | DataPart | PlacePart;
 export interface TextPartResponse extends TextPart {
     mentions?: Array<{
         id: string;
@@ -187,9 +743,6 @@ export interface LinkPartResponse extends LinkPart {
 export interface ButtonsPartResponse extends ButtonsPart {
     reactions: Reaction[] | null;
 }
-export interface ButtonReplyPartResponse extends ButtonReplyPart {
-    reactions: Reaction[] | null;
-}
 export interface SystemEventParty {
     id: UUID;
     handle: string;
@@ -200,7 +753,16 @@ export interface TypingIndicatorWebhookData {
     chat_id: UUID;
     contact: TypingContact;
 }
-export type SystemEventType = "chat_created" | "participant_added" | "participant_removed" | "group_name_updated" | "group_icon_updated" | "contact_card_shared";
+export type SystemEventType = "chat_created" | "participant_added" | "participant_removed" | "group_name_updated" | "group_icon_updated" | "contact_card_shared" | "call";
+export interface CallMarker {
+    id: UUID;
+    status: Call["status"];
+    answered_at: string | null;
+    ended_at: string | null;
+    from: CallContact;
+    to: [CallContact];
+    duration_seconds: number | null;
+}
 export interface SystemEvent {
     type: SystemEventType;
     actor: SystemEventParty;
@@ -208,15 +770,17 @@ export interface SystemEvent {
     value: string | null;
     icon_attachment_id: UUID | null;
     contact_card: ContactCardItem | null;
+    call: CallMarker | null;
 }
 export interface SystemPartResponse {
     type: "system";
     value: string;
     reactions: null;
 }
-export type MessagePartResponse = TextPartResponse | MediaPartResponse | LinkPartResponse | ButtonsPartResponse | ButtonReplyPartResponse | SystemPartResponse;
-/** Ordinary replies target text, media, link, or button_reply, never buttons or system.
- * A button_reply instead targets the originating buttons part. */
+export type MessagePartResponse = TextPartResponse | MediaPartResponse | LinkPartResponse | ButtonsPartResponse | SelectionPartResponse | SelectionResponsePartResponse | PaymentPartResponse | PaymentReceiptPartResponse | DataPartResponse | LocationRequestPartResponse | LocationPartResponse | PlacePartResponse | SystemPartResponse;
+/** Ordinary replies target text, media, or link, never system. A buttons part
+ * accepts only a tap: one text part equal to one of its plain labels. A selection
+ * requires explicit part_index and exactly text then selection_response metadata. */
 export interface ReplyTo {
     message_id: UUID;
     part_index?: number;
@@ -224,6 +788,11 @@ export interface ReplyTo {
 export interface MessageContent {
     parts: MessagePart[];
     reply_to?: ReplyTo;
+    /**
+     * A2A Message metadata. A tap (an A2UI `action`) on a surface that set
+     * `sendDataModel` must carry `a2uiClientDataModel`.
+     */
+    metadata?: MessageMetadata;
     idempotency_key?: string;
     /**
      * Send the Message with no banner and no sound on the recipient's device.
@@ -234,7 +803,7 @@ export interface MessageContent {
 }
 /**
  * The Message a send returns. A send never produces a system Message, so its
- * parts are only text, media, link, buttons or button_reply, and it carries no `system_event`.
+ * parts exclude system parts, and it carries no `system_event`.
  * `is_system_message` is on the wire and is always `false` here; the contract's
  * `SentMessage` does not declare it yet.
  * Read paths (`chats.messages.list`, `messages.listMessagesThread`) return
@@ -242,7 +811,8 @@ export interface MessageContent {
  */
 export interface SentMessage {
     id: UUID;
-    parts: Array<TextPartResponse | MediaPartResponse | LinkPartResponse | ButtonsPartResponse | ButtonReplyPartResponse>;
+    parts: Array<TextPartResponse | MediaPartResponse | LinkPartResponse | ButtonsPartResponse | SelectionPartResponse | SelectionResponsePartResponse | PaymentPartResponse | PaymentReceiptPartResponse | DataPartResponse | LocationRequestPartResponse | LocationPartResponse | PlacePartResponse>;
+    metadata?: MessageMetadata;
     created_at: string;
     sent_at: string | null;
     delivered_at?: string | null;
@@ -263,6 +833,7 @@ export interface Message {
     from_handle?: ChatHandle | null;
     parts?: MessagePartResponse[] | null;
     reply_to?: ReplyTo | null;
+    metadata?: MessageMetadata;
     is_system_message: boolean;
     system_event?: SystemEvent | null;
     is_from_me: boolean;
@@ -313,6 +884,11 @@ export interface ChatCreateParams {
     message: MessageContent;
 }
 export interface ChatCreateResponse {
+    /**
+     * The A2UI messages of the send that were not applied, each with its place
+     * in the request and A2UI's `error` message for it. The rest was applied.
+     */
+    a2ui_errors?: A2uiFailure[];
     chat: Pick<Chat, "id" | "display_name" | "is_group" | "handles"> & {
         message: SentMessage;
     };
@@ -353,6 +929,11 @@ export interface MessageSendParams {
     message: MessageContent;
 }
 export interface MessageSendResponse {
+    /**
+     * The A2UI messages of the send that were not applied, each with its place
+     * in the request and A2UI's `error` message for it. The rest was applied.
+     */
+    a2ui_errors?: A2uiFailure[];
     chat_id: UUID;
     message: SentMessage;
 }
@@ -362,6 +943,11 @@ export interface MessageCreateParams {
     "Idempotency-Key"?: string;
 }
 export interface MessageCreateResponse {
+    /**
+     * The A2UI messages of the send that were not applied, each with its place
+     * in the request and A2UI's `error` message for it. The rest was applied.
+     */
+    a2ui_errors?: A2uiFailure[];
     from: string;
     chat_id: UUID;
     created_new_chat: boolean;
@@ -380,7 +966,11 @@ export interface MessageListParams {
     order?: "asc" | "desc";
 }
 export type MessageThreadParams = MessageListParams;
-/** Target text, media, link, or button_reply; buttons and system cannot receive reactions. */
+/**
+ * Target text, media, link, or payment; buttons, selection, selection_response
+ * and system cannot receive reactions. Only a person can react to a payment;
+ * an agent reacting to one gets a 403.
+ */
 export interface MessageAddReactionParams {
     operation: "add" | "remove";
     type: ReactionType;
@@ -487,12 +1077,88 @@ export interface WebhookSubscriptionUpdateParams {
 export interface WebhookSubscriptionListResponse {
     subscriptions: WebhookSubscription[];
 }
+/** Where the directory files the agent. */
+export type AgentCategory = "productivity" | "business" | "finance" | "shopping" | "travel" | "health-fitness" | "lifestyle" | "social" | "education" | "entertainment" | "utilities" | "developer-tools";
+/**
+ * `public` agents are listed in the directory and found by task; `unlisted`
+ * agents answer by handle only.
+ */
+export type AgentVisibility = "public" | "unlisted";
+/** One thing the agent does, in the A2A AgentSkill shape. */
+export interface AgentSkill {
+    id: string;
+    name: string;
+    description: string;
+    tags: string[];
+    examples: string[];
+}
+export interface ContactLookup {
+    id: UUID;
+    handle: string;
+    display_name: string;
+    kind: "user" | "agent";
+    image_url: string | null;
+    image_color: string | null;
+    verified: boolean;
+    /** The agent's name. Agents only. */
+    name?: string;
+    /** The one line under the agent's name. Agents only. */
+    subtitle?: string | null;
+    /** The agent's paragraph. Agents only. */
+    description?: string | null;
+    /** Where the directory files the agent. Agents only. */
+    category?: AgentCategory | null;
+    /** What the agent does, at most ten skills. Agents only. */
+    skills?: AgentSkill[];
+    /** Whether the agent is listed in the directory. Agents only. */
+    visibility?: AgentVisibility;
+    /**
+     * Who made the agent: its organization, by the name the organization gave
+     * in the Relay Console. Null when the organization has not given a name.
+     * Agents only.
+     */
+    creator?: AgentCreator | null;
+}
+/** The organization that made an agent. */
+export interface AgentCreator {
+    kind: "organization";
+    name: string;
+    /** The maker's Relay Handle. Null until Relay stores one. */
+    handle: string | null;
+}
+/**
+ * Look up one contact by Relay Handle, or find public agents by task. Send
+ * exactly one of the two.
+ */
+export type ContactLookupParams = 
+/** Relay Handle, trimmed and lowercased by the Server before validation. */
+{
+    handle: string;
+}
+/** What you need done, in plain words; at most 200 characters. */
+ | {
+    task: string;
+};
+/**
+ * A handle lookup answers with one `contact`; a task search answers with
+ * `contacts`, verified agents first and at most twenty, empty when nothing
+ * matches.
+ */
+export type ContactLookupResponse = {
+    contact: ContactLookup;
+} | {
+    contacts: ContactLookup[];
+};
 export interface ContactCardItem {
+    /** Detailed agent description, up to 2000 characters. Public agents cannot clear it. */
+    description?: string | null;
     handle: string;
     first_name: string;
     last_name: string | null;
     image_url: string | null;
     is_active: boolean;
+    /** Whether Relay has verified this agent. Always false for a user. */
+    is_verified?: boolean;
     kind: "user" | "agent";
 }
 export interface ContactCardCreateParams {
@@ -512,8 +1178,10 @@ export interface ContactCardRetrieveResponse {
     contact_cards: ContactCardItem[];
 }
 export interface ContactCardUpdateParams {
-    /** Server contract 3097dda: trimmed about text, 1 to 60 characters. */
-    about?: string;
+    /** Detailed agent description, up to 2000 characters. Public agents cannot clear it. */
+    description?: string | null;
+    /** The one line under the name, 1 to 60 characters. */
+    subtitle?: string;
     handle: string;
     first_name?: string;
     last_name?: string | null;
@@ -609,6 +1277,13 @@ export interface MessageWebhookData {
      */
     silent?: boolean;
     reply_to?: ReplyTo | null;
+    /**
+     * A2A Message metadata. Every `message.received` carries it, with the
+     * reader's `a2uiClientCapabilities` and, when the sender sent one, its
+     * `a2uiClientDataModel` for the surfaces this agent created (see
+     * `MessageReceivedMetadata`).
+     */
+    metadata?: Partial<MessageReceivedMetadata>;
 }
 /**
  * `message.failed`. Relay commits a Message before it answers, so a Message
@@ -658,8 +1333,8 @@ export type ContactAddedWebhookEvent = ContactAddedWebhook;
 export type ContactRemovedWebhookEvent = ContactRemovedWebhook;
 type MessageWebhookEventType = "message.sent" | "message.received" | "message.read" | "message.delivered";
 type TypingIndicatorWebhookEventType = "chat.typing_indicator.started" | "chat.typing_indicator.stopped";
-type OtherWebhookEventType = Exclude<WebhookEventType, MessageWebhookEventType | TypingIndicatorWebhookEventType | "contact.added" | "contact.removed" | "message.failed" | "call.created" | "call.updated" | "call.ended">;
-export type RelayWebhookEvent = RelayWebhookEnvelope<MessageWebhookData, MessageWebhookEventType> | RelayWebhookEnvelope<TypingIndicatorWebhookData, TypingIndicatorWebhookEventType> | MessageFailedWebhook | ContactAddedWebhookEvent | ContactRemovedWebhookEvent | CallWebhookEvent | RelayWebhookEnvelope<Record<string, unknown>, OtherWebhookEventType>;
+type OtherWebhookEventType = Exclude<WebhookEventType, MessageWebhookEventType | TypingIndicatorWebhookEventType | "contact.added" | "contact.removed" | "message.failed" | "call.created" | "call.updated" | "call.ended" | "payment.succeeded" | "payment.canceled" | "payment.expired" | "location.sharing.started" | "location.sharing.stopped">;
+export type RelayWebhookEvent = RelayWebhookEnvelope<MessageWebhookData, MessageWebhookEventType> | RelayWebhookEnvelope<TypingIndicatorWebhookData, TypingIndicatorWebhookEventType> | MessageFailedWebhook | ContactAddedWebhookEvent | ContactRemovedWebhookEvent | CallWebhookEvent | PaymentWebhookEvent | LocationSharingStartedWebhookEvent | LocationSharingStoppedWebhookEvent | RelayWebhookEnvelope<Record<string, unknown>, OtherWebhookEventType>;
 /** Existing Relay avatar gradient pairs, ordered top then base. */
 export type AgentImageGradient = readonly ["EC8A3C", "C85F1C"] | readonly ["E0567A", "AD2A52"] | readonly ["D05FC6", "93217E"] | readonly ["8F6CF2", "5F38CF"] | readonly ["5B9BFA", "0B52C0"] | readonly ["2596A6", "116A79"] | readonly ["2FA46A", "137347"];
 export interface AgentImageBackground {