imessage-sdk 0.1.0-beta.0 → 0.1.0

package/README.md

@@ -3,18 +3,19 @@
 A provider-neutral, type-safe TypeScript conversation layer for iMessage
 infrastructure.
 
-The normalized v0.1 client, Blooio v2 provider, and Photon Cloud provider are
-implemented.
+The normalized v0.1 client is implemented here. Blooio v2 and Photon Cloud are
+published as separate provider packages so applications install only the
+provider dependencies they use.
 
 The package is ESM-only and ships JavaScript plus TypeScript declarations.
 
 > This is a beta release. Install the prerelease with `pnpm add
-> imessage-sdk@beta` while the public API is being validated.
+imessage-sdk@beta` while the public API is being validated.
 
 ## Install
 
 ```bash
-pnpm add imessage-sdk@beta
+pnpm add imessage-sdk@beta @imessage-sdk/blooio@beta
 ```
 
 ## Creating a client
@@ -23,8 +24,8 @@ Provider factories consume provider configuration and return a complete,
 concrete provider:
 
 ```ts
-import { createIMessageClient } from "imessage-sdk";
-import { blooio } from "imessage-sdk/providers/blooio";
+import { blooio } from '@imessage-sdk/blooio';
+import { createIMessageClient } from 'imessage-sdk';
 
 const client = createIMessageClient({
   provider: blooio(),
@@ -39,7 +40,7 @@ when the application has multiple connections or sender lines:
 
 ```ts
 const namedClient = createIMessageClient({
-  connectionId: "main-line",
+  connectionId: 'main-line',
   provider: blooio(),
 });
 
@@ -74,8 +75,8 @@ client.providers.blooio.name;
 client.providers.photon;
 
 const sent = await client.messages.send({
-  to: { kind: "phone", value: "+15551234567" },
-  text: "Hello from imessage-sdk",
+  to: { kind: 'phone', value: '+15551234567' },
+  text: 'Hello from imessage-sdk',
 });
 
 sent.provider;
@@ -93,26 +94,26 @@ public URLs, while Photon uploads all three source types:
 
 ```ts
 await client.messages.send({
-  conversationId: "provider-conversation-id",
-  text: "Three attachments",
+  conversationId: 'provider-conversation-id',
+  text: 'Three attachments',
   attachments: [
     {
-      kind: "image",
+      kind: 'image',
       source: {
-        type: "url",
-        url: "https://example.com/photo.jpg",
+        type: 'url',
+        url: 'https://example.com/photo.jpg',
       },
-      contentType: "image/jpeg",
+      contentType: 'image/jpeg',
     },
     {
-      kind: "video",
-      source: { type: "url", url: "https://example.com/clip.mp4" },
-      filename: "clip.mp4",
+      kind: 'video',
+      source: { type: 'url', url: 'https://example.com/clip.mp4' },
+      filename: 'clip.mp4',
     },
     {
-      kind: "file",
-      source: { type: "url", url: "https://example.com/document.pdf" },
-      filename: "document.pdf",
+      kind: 'file',
+      source: { type: 'url', url: 'https://example.com/document.pdf' },
+      filename: 'document.pdf',
     },
   ],
 });
@@ -122,10 +123,10 @@ Replies use the provider-native message ID and optional message-part index:
 
 ```ts
 await client.messages.send({
-  conversationId: "provider-conversation-id",
-  text: "Replying in this thread",
+  conversationId: 'provider-conversation-id',
+  text: 'Replying in this thread',
   replyTo: {
-    messageId: "provider-message-id",
+    messageId: 'provider-message-id',
     partIndex: 0,
   },
 });
@@ -139,15 +140,15 @@ the exact same instance under its typed provider namespace:
 ```ts
 const provider = blooio();
 const client = createIMessageClient({
-  connectionId: "main-line",
+  connectionId: 'main-line',
   provider,
 });
 
 client.providers.blooio === provider; // true
 
 await client.providers.blooio.messages.send({
-  to: { kind: "phone", value: "+15551234567" },
-  text: "Send directly through Blooio",
+  to: { kind: 'phone', value: '+15551234567' },
+  text: 'Send directly through Blooio',
 });
 ```
 
@@ -155,8 +156,8 @@ The normalized top-level methods remain available:
 
 ```ts
 await client.messages.send({
-  to: { kind: "phone", value: "+15551234567" },
-  text: "Send through the normalized client",
+  to: { kind: 'phone', value: '+15551234567' },
+  text: 'Send through the normalized client',
 });
 ```
 
@@ -185,11 +186,11 @@ literal name, capability values, and complete concrete provider type.
 Conceptually, provider factories are structured like this:
 
 ```ts
-import { defineProvider } from "imessage-sdk";
+import { defineProvider } from 'imessage-sdk';
 
 function blooio(options = {}) {
   return defineProvider({
-    name: "blooio" as const,
+    name: 'blooio' as const,
     capabilities: BLOOIO_CAPABILITIES,
     messages: {
       async send(input) {
@@ -237,7 +238,7 @@ methods:
 
 ```ts
 const custom = defineProvider({
-  name: "my-provider" as const,
+  name: 'my-provider' as const,
   capabilities: MY_PROVIDER_CAPABILITIES,
   messages: {
     send: sendMessage,
@@ -255,9 +256,9 @@ customClient.provider;
 //           ^? "my-provider"
 
 // Required because this concrete provider defines it as required.
-await customClient.providers["my-provider"].messages.edit(
-  { conversationId: "conversation-id", messageId: "message-id" },
-  { text: "Corrected" },
+await customClient.providers['my-provider'].messages.edit(
+  { conversationId: 'conversation-id', messageId: 'message-id' },
+  { text: 'Corrected' },
 );
 ```
 
@@ -268,12 +269,12 @@ or sender lines, it creates multiple clients and selects one explicitly:
 
 ```ts
 const sales = createIMessageClient({
-  connectionId: "sales-line",
+  connectionId: 'sales-line',
   provider: blooio(salesOptions),
 });
 
 const support = createIMessageClient({
-  connectionId: "support-line",
+  connectionId: 'support-line',
   provider: photon(supportOptions),
 });
 ```
@@ -309,10 +310,10 @@ feature checks:
 if (client.capabilities.messages.edit) {
   await client.messages.edit(
     {
-      conversationId: "provider-conversation-id",
-      messageId: "provider-message-id",
+      conversationId: 'provider-conversation-id',
+      messageId: 'provider-message-id',
     },
-    { text: "Corrected" },
+    { text: 'Corrected' },
   );
 }
 ```
@@ -326,6 +327,10 @@ construction, while stream providers connect lazily when subscribed.
 `client.close()` is always available and idempotent. It is a no-op when the
 provider has no cleanup and releases resources for stream or local transports.
 
+All available normalized v0.1 operations are stable except webhook handling.
+`client.webhooks`, `ProviderWebhooks`, and webhook event normalization are
+marked experimental and may change incompatibly during the 0.1 release line.
+
 ## Blooio operations
 
 The v0.1 Blooio adapter supports text and public URL attachments, inline
@@ -340,15 +345,15 @@ const locator = {
 };
 
 await client.messages.get(locator);
-await client.reactions.add({ ...locator, reaction: "like" });
+await client.reactions.add({ ...locator, reaction: 'like' });
 await client.typing.start(sent.conversationId);
 await client.typing.stop(sent.conversationId);
 await client.conversations.markRead(sent.conversationId);
 ```
 
-Webhook handling verifies `X-Blooio-Signature` before parsing and returns an
-array because one provider delivery can represent zero, one, or multiple
-normalized events:
+Experimental webhook handling verifies `X-Blooio-Signature` before parsing and
+returns an array because one provider delivery can represent zero, one, or
+multiple normalized events:
 
 ```ts
 const events = await client.webhooks.handle(request);
@@ -367,7 +372,7 @@ export BLOOIO_TEST_IMAGE_URL="https://..."
 export BLOOIO_TEST_VIDEO_URL="https://..."
 export BLOOIO_TEST_FILE_URL="https://..."
 
-pnpm --filter imessage-sdk test:integration:blooio
+pnpm --filter @imessage-sdk/blooio test:integration
 ```
 
 It sends three messages and exercises lookup/status, reactions, typing, and
@@ -380,11 +385,11 @@ Photon authenticates with Spectrum Cloud lazily. A dedicated phone is optional
 when the project owns exactly one line and required when it owns multiple:
 
 ```ts
-import { createIMessageClient } from "imessage-sdk";
-import { photon } from "imessage-sdk/providers/photon";
+import { photon } from '@imessage-sdk/photon';
+import { createIMessageClient } from 'imessage-sdk';
 
 const client = createIMessageClient({
-  connectionId: "photon-main",
+  connectionId: 'photon-main',
   provider: photon(),
 });
 
@@ -407,7 +412,7 @@ Cursors are durable numeric event sequences represented as strings:
 
 ```ts
 for await (const event of client.providers.photon.events.subscribe({
-  cursor: "123",
+  cursor: '123',
 })) {
   console.log(event.providerEventId, event.type);
 }
@@ -430,7 +435,7 @@ export PHOTON_TEST_IMAGE_URL="https://..."
 export PHOTON_TEST_VIDEO_URL="https://..."
 export PHOTON_TEST_FILE_URL="https://..."
 
-pnpm --filter imessage-sdk test:integration:photon
+pnpm --filter @imessage-sdk/photon test:integration
 ```
 
 On Photon Free and Pro shared lines, add the recipient under the project's
@@ -444,7 +449,7 @@ persistent stream, run the command below and send an iMessage to the line
 within 60 seconds:
 
 ```bash
-pnpm --filter imessage-sdk test:integration:photon-stream
+pnpm --filter @imessage-sdk/photon test:integration:stream
 ```
 
 ## v0.1 beta boundary

package/dist/index.d.ts

@@ -1,5 +1,31 @@
-import { A as AnyIMessageProvider, S as SendMessageInput, a as SentMessage, M as MessageLocator, b as Message, E as EditMessageInput, O as OpenConversationInput, C as Conversation, c as AddReactionInput, R as RemoveReactionInput, I as IMessageEvent, d as SubscribeOptions } from './provider-CCW_6OWg.js';
-export { e as IMessageAddress, f as IMessageAddressKind, g as IMessageAttachment, h as IMessageAttachmentInput, i as IMessageAttachmentKind, j as IMessageAttachmentSource, k as IMessageCapabilities, l as IMessageDeletedEvent, m as IMessageDirection, n as IMessageEventBase, o as IMessageMessageEvent, p as IMessageProvider, q as IMessageProviderName, r as IMessageReaction, s as IMessageReactionEvent, t as IMessageService, u as IMessageStatus, v as IMessageTypingEvent, w as MessageReplyReference, N as NonEmptyReadonlyArray, P as ProviderConversation, x as ProviderConversations, y as ProviderEvent, z as ProviderEventBase, B as ProviderEvents, D as ProviderMessage, F as ProviderMessageDeletedEvent, G as ProviderMessageEvent, H as ProviderMessageEventType, J as ProviderMessages, K as ProviderReactionEvent, L as ProviderReactionEventType, Q as ProviderReactions, T as ProviderSentMessage, U as ProviderTyping, V as ProviderTypingEvent, W as ProviderTypingEventType, X as ProviderWebhooks, Y as defineProvider } from './provider-CCW_6OWg.js';
+/** Runtime feature declaration for one configured provider connection. */
+interface IMessageCapabilities {
+    readonly messages: {
+        readonly text: boolean;
+        readonly attachments: boolean;
+        readonly replies: boolean;
+        readonly get: boolean;
+        readonly edit: boolean;
+        readonly delete: boolean;
+    };
+    readonly conversations: {
+        readonly direct: boolean;
+        readonly groups: boolean;
+        readonly get: boolean;
+        readonly markRead: boolean;
+    };
+    readonly interactions: {
+        readonly reactions: boolean;
+        readonly typingStart: boolean;
+        readonly typingStop: boolean;
+        readonly readReceipts: boolean;
+    };
+    readonly events: {
+        /** @experimental Webhook normalization may change before a future stable release. */
+        readonly webhooks: boolean;
+        readonly stream: boolean;
+    };
+}
 
 /**
  * Creates a diagnostic fallback when a provider message omits its native
@@ -47,27 +73,269 @@ declare class AmbiguousDeliveryError extends IMessageSDKError {
 }
 declare class UnsupportedCapabilityError extends IMessageSDKError {
     readonly capability: string;
-    constructor(capability: string, options?: Pick<IMessageSDKErrorOptions, "provider" | "connectionId">);
+    constructor(capability: string, options?: Pick<IMessageSDKErrorOptions, 'provider' | 'connectionId'>);
 }
 declare class WebhookVerificationError extends IMessageSDKError {
-    constructor(options?: Pick<IMessageSDKErrorOptions, "provider" | "connectionId">);
+    constructor(options?: Pick<IMessageSDKErrorOptions, 'provider' | 'connectionId'>);
 }
 declare class ClientClosedError extends IMessageSDKError {
-    constructor(options?: Pick<IMessageSDKErrorOptions, "provider" | "connectionId">);
+    constructor(options?: Pick<IMessageSDKErrorOptions, 'provider' | 'connectionId'>);
+}
+
+/** Provider names stay literal through generics but are open to custom adapters. */
+type IMessageProviderName = string;
+type IMessageAddressKind = 'phone' | 'email';
+interface IMessageAddress {
+    readonly kind: IMessageAddressKind;
+    readonly value: string;
+}
+type NonEmptyReadonlyArray<T> = readonly [T, ...T[]];
+type IMessageAttachmentKind = 'image' | 'video' | 'file';
+type IMessageAttachmentSource = {
+    readonly type: 'url';
+    /** A URL that the selected provider can fetch. */
+    readonly url: string;
+} | {
+    readonly type: 'blob';
+    readonly data: Blob;
+} | {
+    readonly type: 'bytes';
+    readonly data: Uint8Array;
+};
+interface IMessageAttachmentInput {
+    readonly kind: IMessageAttachmentKind;
+    readonly source: IMessageAttachmentSource;
+    readonly filename?: string;
+    readonly contentType?: string;
+}
+interface IMessageAttachment {
+    readonly kind: IMessageAttachmentKind;
+    readonly id?: string;
+    readonly url?: string;
+    readonly filename?: string;
+    readonly contentType?: string;
+    readonly size?: number;
+    readonly raw: unknown;
+}
+interface MessageReplyReference {
+    /** Provider-native message identifier. */
+    readonly messageId: string;
+    readonly partIndex?: number;
+}
+/** Identifies a provider message within its native conversation. */
+interface MessageLocator {
+    readonly conversationId: string;
+    readonly messageId: string;
+}
+type SendDestination = {
+    readonly conversationId: string;
+    readonly to?: never;
+} | {
+    readonly conversationId?: never;
+    readonly to: IMessageAddress | NonEmptyReadonlyArray<IMessageAddress>;
+};
+type SendContent = {
+    readonly text: string;
+    readonly attachments?: readonly IMessageAttachmentInput[];
+} | {
+    readonly text?: string;
+    readonly attachments: NonEmptyReadonlyArray<IMessageAttachmentInput>;
+};
+type SendMessageInput = SendDestination & SendContent & {
+    readonly replyTo?: MessageReplyReference;
+    readonly idempotencyKey?: string;
+    readonly metadata?: Readonly<Record<string, string>>;
+};
+interface EditMessageInput {
+    readonly text: string;
+}
+type IMessageDirection = 'inbound' | 'outbound';
+type IMessageService = 'imessage' | 'sms' | 'rcs' | 'unknown';
+type IMessageStatus = 'pending' | 'accepted' | 'sent' | 'delivered' | 'read' | 'failed';
+/**
+ * A provider-normalized message before the client adds connection identity.
+ * Provider adapters return this shape.
+ */
+interface ProviderMessage {
+    readonly providerMessageId: string;
+    /** Opaque provider-native ID, scoped to one provider connection. */
+    readonly conversationId?: string;
+    readonly direction: IMessageDirection;
+    readonly sender: IMessageAddress;
+    readonly recipients: readonly IMessageAddress[];
+    readonly text: string;
+    readonly attachments: readonly IMessageAttachment[];
+    readonly replyTo?: MessageReplyReference;
+    readonly service: IMessageService;
+    readonly status: IMessageStatus;
+    readonly providerStatus?: string;
+    readonly createdAt: Date;
+    readonly sentAt?: Date;
+    readonly deliveredAt?: Date;
+    readonly readAt?: Date;
+    readonly raw: unknown;
+}
+type ProviderSentMessage = ProviderMessage & {
+    readonly direction: 'outbound';
+};
+/** A message returned by a client bound to one provider connection. */
+type Message<TProvider extends IMessageProviderName = IMessageProviderName, TConnectionId extends string = string> = Omit<ProviderMessage, 'conversationId'> & {
+    /** Equal to providerMessageId in v0.1. */
+    readonly id: string;
+    /** Provider-native when available; otherwise a non-routable imsg-sdk-v1 fallback. */
+    readonly conversationId: string;
+    readonly provider: TProvider;
+    readonly connectionId: TConnectionId;
+};
+type SentMessage<TProvider extends IMessageProviderName = IMessageProviderName, TConnectionId extends string = string> = Message<TProvider, TConnectionId> & {
+    readonly direction: 'outbound';
+};
+interface OpenConversationInput {
+    readonly participants: NonEmptyReadonlyArray<IMessageAddress>;
+}
+interface ProviderConversation {
+    /** Opaque provider-native ID, scoped to one provider connection. */
+    readonly providerConversationId: string;
+    readonly participants: readonly IMessageAddress[];
+    readonly createdAt?: Date;
+    readonly raw: unknown;
+}
+type Conversation<TProvider extends IMessageProviderName = IMessageProviderName, TConnectionId extends string = string> = ProviderConversation & {
+    /** Equal to providerConversationId in v0.1; scope with provider and connectionId. */
+    readonly id: string;
+    readonly provider: TProvider;
+    readonly connectionId: TConnectionId;
+};
+type IMessageReaction = 'love' | 'like' | 'dislike' | 'laugh' | 'emphasize' | 'question';
+interface AddReactionInput extends MessageLocator {
+    readonly reaction: IMessageReaction;
+    readonly partIndex?: number;
+}
+type RemoveReactionInput = AddReactionInput;
+interface SubscribeOptions {
+    readonly cursor?: string;
+    readonly signal?: AbortSignal;
+}
+
+interface ProviderEventBase<TType extends string> {
+    readonly id: string;
+    readonly providerEventId?: string;
+    readonly type: TType;
+    readonly timestamp: Date;
+    readonly raw: unknown;
+}
+type ProviderMessageEventType = 'message.received' | 'message.sent' | 'message.delivered' | 'message.read' | 'message.failed' | 'message.edited';
+interface ProviderMessageEvent<TType extends ProviderMessageEventType = ProviderMessageEventType> extends ProviderEventBase<TType> {
+    readonly message: ProviderMessage;
+}
+interface ProviderMessageDeletedEvent extends ProviderEventBase<'message.deleted'> {
+    readonly conversationId: string;
+    readonly messageId: string;
+}
+type ProviderReactionEventType = 'reaction.added' | 'reaction.removed';
+interface ProviderReactionEvent<TType extends ProviderReactionEventType = ProviderReactionEventType> extends ProviderEventBase<TType> {
+    readonly conversationId: string;
+    readonly messageId: string;
+    readonly actor: IMessageAddress;
+    readonly reaction: IMessageReaction;
+    readonly partIndex?: number;
+}
+type ProviderTypingEventType = 'typing.started' | 'typing.stopped';
+interface ProviderTypingEvent<TType extends ProviderTypingEventType = ProviderTypingEventType> extends ProviderEventBase<TType> {
+    readonly conversationId: string;
+    /** Some group transports do not identify which participant is typing. */
+    readonly actor?: IMessageAddress;
+}
+type ProviderEvent = ProviderMessageEvent | ProviderMessageDeletedEvent | ProviderReactionEvent | ProviderTypingEvent;
+interface IMessageEventBase<TProvider extends IMessageProviderName, TConnectionId extends string, TType extends string> extends ProviderEventBase<TType> {
+    readonly provider: TProvider;
+    readonly connectionId: TConnectionId;
+}
+interface IMessageMessageEvent<TProvider extends IMessageProviderName, TConnectionId extends string, TType extends ProviderMessageEventType = ProviderMessageEventType> extends IMessageEventBase<TProvider, TConnectionId, TType> {
+    readonly message: Message<TProvider, TConnectionId>;
+}
+interface IMessageDeletedEvent<TProvider extends IMessageProviderName, TConnectionId extends string> extends IMessageEventBase<TProvider, TConnectionId, 'message.deleted'> {
+    readonly conversationId: string;
+    readonly messageId: string;
+}
+interface IMessageReactionEvent<TProvider extends IMessageProviderName, TConnectionId extends string, TType extends ProviderReactionEventType = ProviderReactionEventType> extends IMessageEventBase<TProvider, TConnectionId, TType> {
+    readonly conversationId: string;
+    readonly messageId: string;
+    readonly actor: IMessageAddress;
+    readonly reaction: IMessageReaction;
+    readonly partIndex?: number;
+}
+interface IMessageTypingEvent<TProvider extends IMessageProviderName, TConnectionId extends string, TType extends ProviderTypingEventType = ProviderTypingEventType> extends IMessageEventBase<TProvider, TConnectionId, TType> {
+    readonly conversationId: string;
+    readonly actor?: IMessageAddress;
+}
+type IMessageEvent<TProvider extends IMessageProviderName = IMessageProviderName, TConnectionId extends string = string> = IMessageMessageEvent<TProvider, TConnectionId> | IMessageDeletedEvent<TProvider, TConnectionId> | IMessageReactionEvent<TProvider, TConnectionId> | IMessageTypingEvent<TProvider, TConnectionId>;
+
+interface ProviderMessages {
+    send(input: SendMessageInput): Promise<ProviderSentMessage>;
+    get?(message: MessageLocator): Promise<ProviderMessage | null>;
+    edit?(message: MessageLocator, input: EditMessageInput): Promise<ProviderMessage>;
+    delete?(message: MessageLocator): Promise<void>;
+}
+interface ProviderConversations {
+    open(input: OpenConversationInput): Promise<ProviderConversation>;
+    get?(conversationId: string): Promise<ProviderConversation | null>;
+    markRead?(conversationId: string): Promise<void>;
+}
+interface ProviderReactions {
+    add(input: AddReactionInput): Promise<void>;
+    remove(input: RemoveReactionInput): Promise<void>;
+}
+interface ProviderTyping {
+    start(conversationId: string): Promise<void>;
+    stop?(conversationId: string): Promise<void>;
+}
+/**
+ * Provider webhook verification and normalization contract.
+ *
+ * @experimental Webhook normalization may change before a future stable release.
+ */
+interface ProviderWebhooks {
+    verify(request: Request): Promise<boolean>;
+    parse(request: Request): Promise<readonly ProviderEvent[]>;
+}
+interface ProviderEvents {
+    subscribe(options?: SubscribeOptions): AsyncIterable<ProviderEvent>;
+}
+/**
+ * Contract implemented by a provider adapter.
+ *
+ * The complete adapter is exposed at `client.providers.<name>`, so
+ * provider-specific APIs should be defined directly on the concrete provider.
+ */
+interface IMessageProvider<TName extends IMessageProviderName = IMessageProviderName, TCapabilities extends IMessageCapabilities = IMessageCapabilities> {
+    readonly name: TName;
+    readonly capabilities: TCapabilities;
+    readonly messages: ProviderMessages;
+    readonly conversations: ProviderConversations;
+    readonly reactions?: ProviderReactions;
+    readonly typing?: ProviderTyping;
+    /** @experimental Webhook normalization may change before a future stable release. */
+    readonly webhooks?: ProviderWebhooks;
+    readonly events?: ProviderEvents;
+    close?(): Promise<void>;
 }
+type AnyIMessageProvider = IMessageProvider<IMessageProviderName, IMessageCapabilities>;
+/** Preserves the concrete name, capabilities, and methods of an adapter. */
+declare function defineProvider<const TProvider extends AnyIMessageProvider>(provider: TProvider): TProvider;
 
-type ProviderNameOf<TProvider extends AnyIMessageProvider> = TProvider["name"];
+type ProviderNameOf<TProvider extends AnyIMessageProvider> = TProvider['name'];
 declare const DEFAULT_CONNECTION_ID: "default";
 type ClientProvider<TProvider extends AnyIMessageProvider> = TProvider;
 type ClientProviders<TProvider extends AnyIMessageProvider> = {
-    readonly [TName in TProvider["name"]]: ClientProvider<Extract<TProvider, {
+    readonly [TName in TProvider['name']]: ClientProvider<Extract<TProvider, {
         readonly name: TName;
     }>>;
 };
 interface IMessageClient<TProvider extends AnyIMessageProvider = AnyIMessageProvider, TConnectionId extends string = string> {
     readonly provider: ProviderNameOf<TProvider>;
     readonly connectionId: TConnectionId;
-    readonly capabilities: TProvider["capabilities"];
+    readonly capabilities: TProvider['capabilities'];
     readonly providers: ClientProviders<TProvider>;
     readonly messages: {
         send(input: SendMessageInput): Promise<SentMessage<ProviderNameOf<TProvider>, TConnectionId>>;
@@ -88,6 +356,7 @@ interface IMessageClient<TProvider extends AnyIMessageProvider = AnyIMessageProv
         start(conversationId: string): Promise<void>;
         stop(conversationId: string): Promise<void>;
     };
+    /** @experimental Webhook normalization may change before a future stable release. */
     readonly webhooks: {
         handle(request: Request): Promise<readonly IMessageEvent<ProviderNameOf<TProvider>, TConnectionId>[]>;
     };
@@ -102,4 +371,4 @@ interface CreateIMessageClientOptions<TProvider extends AnyIMessageProvider, TCo
 }
 declare function createIMessageClient<const TProvider extends AnyIMessageProvider, const TConnectionId extends string = typeof DEFAULT_CONNECTION_ID>(options: CreateIMessageClientOptions<TProvider, TConnectionId>): IMessageClient<TProvider, TConnectionId>;
 
-export { AddReactionInput, AmbiguousDeliveryError, AnyIMessageProvider, AuthenticationError, ClientClosedError, type ClientProvider, type ClientProviders, ConflictError, Conversation, type CreateIMessageClientOptions, DEFAULT_CONNECTION_ID, EditMessageInput, type IMessageClient, IMessageEvent, IMessageSDKError, type IMessageSDKErrorOptions, Message, MessageLocator, NotFoundError, OpenConversationInput, ProviderUnavailableError, RateLimitError, RemoveReactionInput, SendMessageInput, SentMessage, SubscribeOptions, UnsupportedCapabilityError, ValidationError, WebhookVerificationError, createFallbackConversationId, createIMessageClient, isFallbackConversationId };
+export { type AddReactionInput, AmbiguousDeliveryError, type AnyIMessageProvider, AuthenticationError, ClientClosedError, type ClientProvider, type ClientProviders, ConflictError, type Conversation, type CreateIMessageClientOptions, DEFAULT_CONNECTION_ID, type EditMessageInput, type IMessageAddress, type IMessageAddressKind, type IMessageAttachment, type IMessageAttachmentInput, type IMessageAttachmentKind, type IMessageAttachmentSource, type IMessageCapabilities, type IMessageClient, type IMessageDeletedEvent, type IMessageDirection, type IMessageEvent, type IMessageEventBase, type IMessageMessageEvent, type IMessageProvider, type IMessageProviderName, type IMessageReaction, type IMessageReactionEvent, IMessageSDKError, type IMessageSDKErrorOptions, type IMessageService, type IMessageStatus, type IMessageTypingEvent, type Message, type MessageLocator, type MessageReplyReference, type NonEmptyReadonlyArray, NotFoundError, type OpenConversationInput, type ProviderConversation, type ProviderConversations, type ProviderEvent, type ProviderEventBase, type ProviderEvents, type ProviderMessage, type ProviderMessageDeletedEvent, type ProviderMessageEvent, type ProviderMessageEventType, type ProviderMessages, type ProviderReactionEvent, type ProviderReactionEventType, type ProviderReactions, type ProviderSentMessage, type ProviderTyping, type ProviderTypingEvent, type ProviderTypingEventType, ProviderUnavailableError, type ProviderWebhooks, RateLimitError, type RemoveReactionInput, type SendMessageInput, type SentMessage, type SubscribeOptions, UnsupportedCapabilityError, ValidationError, WebhookVerificationError, createFallbackConversationId, createIMessageClient, defineProvider, isFallbackConversationId };