@stackable-labs/mcp-app-extension 1.29.0 → 2.0.0

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { IDENTITY_EVENT, ACTIVITY_EVENT, SURFACE_TARGET, TEMPLATE_FLAVORS, PERMISSIONS, CAPABILITY_PERMISSION_MAP, EVENT_HOOK_PERMISSION_MAP, ALLOWED_ICONS, UI_TAGS, UI_TAG_CATEGORIES, UI_TAG_ATTRIBUTES, tagToComponentName } from '@stackable-labs/sdk-extension-contracts';
+import { IDENTITY_EVENT, ACTIVITY_EVENT, SURFACE_TARGET, TEMPLATE_FLAVORS, MESSAGING_ACTION_EXAMPLES, PERMISSIONS, CAPABILITY_PERMISSION_MAP, HOOK_PERMISSION_MAP, ALLOWED_ICONS, UI_TAGS, UI_TAG_CATEGORIES, UI_TAG_ATTRIBUTES, tagToComponentName, EVENT_HOOK_PERMISSION_MAP, MESSAGING_SEND_EXAMPLES } from '@stackable-labs/sdk-extension-contracts';
 import { validatePatternFormat } from '@stackable-labs/lib-contracts';
 import fs4, { readFile, mkdir, writeFile, constants } from 'fs/promises';
 import path, { join } from 'path';
@@ -348,6 +348,11 @@ var CORE_CONTENT = `# Extension SDK \u2014 Editorial Notes
 - Always check the \`loading\` flag before using context values
 - Context is only available when the host provides it (e.g., when viewing a ticket)
 
+### \`messaging.send\` resolves to null without throwing
+- The host silently handles \`no_conversation\` / \`reauth_required\` / \`forbidden\` \u2014 \`send()\` returns null and \`error\` stays unset on these codes
+- These are operational/admin concerns (no active conversation, instance disconnected from messaging, permission revoked) \u2014 surfaced to admins via dashboard remediation UI, not user-actionable from the extension
+- Actionable codes (\`invalid_message\`, \`rate_limited\`, \`upstream_error\`) DO populate \`error\` and throw \u2014 handle in UI
+
 ## Best Practices
 
 ### Performance
@@ -506,7 +511,12 @@ useExtendIdentity((claims) => ({
   external_id: \`custom_\${claims.external_id}\`,   // standard claim override (exempt)
   loyalty_tier: 'bronze',                           // custom \u2014 sync, known at login
   verified: false,                                  // custom \u2014 default; updated async post-verification
-}))`
+}))`,
+  "messaging.send": `import { useMessaging } from '@stackable-labs/sdk-extension-react'
+
+// manifest.json: { "permissions": ["messaging:send"] }
+const [send, { enabled, loading, error }] = useMessaging()
+await send({ kind: 'text', body: 'Hello from the extension' })`
 };
 var HOOK_SNIPPETS_MEMOIZED = {
   "events:messaging": `import { useCallback } from 'react'
@@ -541,7 +551,7 @@ var generateCapabilities = () => {
   const fm = frontmatter({
     root: false,
     targets: ["*"],
-    description: "Extension capabilities: data.query, data.fetch, context.read, actions.toast, actions.invoke, identity.extend, events:identity, events:messaging, events:activity",
+    description: "Extension capabilities: data.query, data.fetch, context.read, actions.toast, actions.invoke, identity.extend, messaging.send, events:identity, events:messaging, events:activity",
     globs: ["packages/extension/src/**/*.tsx", "packages/extension/src/**/*.ts"]
   });
   return `${fm}
@@ -798,7 +808,7 @@ await capabilities.identity.extend({
 // \u2192 identity:refresh broadcast to all extensions with events:identity
 \`\`\`
 
-Per-extension calls are serialized to prevent concurrent Zendesk \`loginUser\` callbacks from orphaning each other (empirically verified in the loginUser re-auth spike).
+Per-extension calls are serialized to prevent concurrent \`loginUser\` callbacks from orphaning each other.
 
 ### Consuming enriched state from another extension
 
@@ -831,6 +841,122 @@ The publisher-side bundle scan validates your declaration at submission time:
 | \`identityClaims_reserved_key\` | error | Collides with a reserved JWT / Zendesk claim |
 | \`identityClaims_standard_key\` | warning | Redundant \u2014 standard claims (\`external_id\`, \`email\`, \`name\`) are exempt |
 | \`identityClaims_too_many\` | error | More than 20 entries |
+
+## messaging.send \u2014 Send Messages to Conversations
+
+Post a message into the **active conversation** bound to the current Instance. The host attributes each message to the extension via the per-Instance author label set by the admin (see "Author label" below). Two complementary APIs:
+
+1. **\`useMessaging()\`** \u2014 React hook returning tuple \`[send, { enabled, loading, error, data }]\` \u2014 lets callers rename \`send\` per-instance when used multiple times in one component. Preferred for UI components; narrows the error surface to actionable codes only. Use \`enabled\` to pre-empt the silent \`no_conversation\` case **without** declaring \`context:read\`.
+2. **\`messagingSendCapability(payload)\`** / **\`capabilities.messaging.send(payload)\`** \u2014 imperative; useful outside React render. Exposes the full wire-level error taxonomy.
+
+### Manifest contract
+
+\`\`\`json
+{
+  "permissions": ["messaging:send"]
+}
+\`\`\`
+
+- **\`messaging:send\` permission** \u2014 without it the host gate rejects the call before any network request.
+
+### Author label (host-resolved, per-Instance)
+
+Extensions do **not** set the author label. The host resolves it from:
+1. \`instance.config.settings.messagingDisplayName\` \u2014 admin sets via the dashboard Instance form (visible only after OAuth completes; gated on \`messagingAppId\` being populated)
+2. **Fallback**: \`extension.manifest.name\` \u2014 used when admin hasn't set a label
+
+This prevents impersonation (extension A can't author as extension B) and gives admins per-deployment branding control.
+
+### Runtime requirements
+
+1. **Instance connected to a messaging provider** \u2014 bearer token stored, ready to post
+2. **An active conversation** when \`send()\` is called (else host-handled \`no_conversation\` \u2014 \`send()\` returns \`null\`)
+3. **Instance not disconnected** from the messaging provider (else host-handled \`reauth_required\` \u2014 admin reconnect surfaced in dashboard)
+
+### Payload \u2014 discriminated by \`kind\`
+
+Four kinds:
+
+| kind | Required fields | Optional |
+|---|---|---|
+| \`'text'\` | \`body: string\` | \`actions?: MessageItemAction[]\`, \`metadata?\`, \`htmlText?\`, \`markdownText?\`, \`disableUserInput?\` |
+| \`'image'\` | \`url: string\`, \`altText: string\` | \`body?\`, \`actions?\`, \`metadata?\` |
+| \`'file'\` | \`url: string\`, \`altText: string\` | \`body?\`, \`metadata?\` (no \`actions\` \u2014 file kind doesn't accept item-level actions) |
+| \`'carousel'\` | \`items: [MessageItem, ...MessageItem[]]\` (1\u201310 items, each with \`title\`, \`description?\`, \`imageUrl?\`, \`actions?\`) | \`displaySettings?: { imageAspectRatio?: 'square' \\| 'horizontal' }\` |
+
+**Action types** (per-item or per-message): \`reply\` (quick-reply button \u2014 emits postback to \`useMessagingEvent\`), \`link\` (opens URL), \`postback\` (custom payload to your handler), \`locationRequest\` (asks user for location).
+
+### Hook usage
+
+\`\`\`tsx
+import { useMessaging } from '@stackable-labs/sdk-extension-react'
+
+const [send, { enabled, loading, error }] = useMessaging()
+
+const onApprove = async () => {
+  try {
+    await send({
+      kind: 'text',
+      body: 'Order approved \u2713',
+      actions: [{ type: 'reply', label: 'Got it', payload: 'ACK' }],
+    })
+  } catch {
+    // error holds the typed SendMessageActionableErrorCode
+  }
+}
+
+return (
+  <button disabled={!enabled || loading} onClick={onApprove}>
+    {error === 'rate_limited' ? 'Slow down\u2026' : 'Approve'}
+  </button>
+)
+\`\`\`
+
+The \`enabled\` flag is a permission-free, host-pushed signal \u2014 \`true\` whenever an active conversation exists. Wiring buttons to \`disabled={!enabled || loading}\` pre-empts the silent \`no_conversation\` case without forcing the extension to declare \`context:read\`. If the extension already has \`context:read\` for other reasons, \`useContextData().messaging?.conversationId\` is an equivalent gate.
+
+### Imperative usage
+
+\`\`\`tsx
+const capabilities = useCapabilities()
+const result = await capabilities.messaging.send({ kind: 'text', body: 'Hello' })
+// result is either { messageId, receivedAt } OR { error: SendMessageErrorCode }
+\`\`\`
+
+### Typed error codes \u2014 split by who acts
+
+The wire taxonomy has 6 codes. The hook (\`useMessaging\`) narrows them into two groups:
+
+**Actionable (extension catches + renders UI)** \u2014 \`send()\` throws and \`state.error\` is populated:
+
+| Code | When |
+| --- | --- |
+| \`invalid_message\` | Payload failed validation (e.g. empty \`body\` for text, carousel >10 items, list kind sent) |
+| \`rate_limited\` | Upstream rate limit hit \u2014 back off + retry |
+| \`upstream_error\` | Provider returned 5xx \u2014 transient; retry with backoff |
+
+**Host-handled (extension ignores)** \u2014 \`send()\` resolves to \`null\`, \`state.error\` stays \`null\`, SDK logs a breadcrumb:
+
+| Code | What the framework does |
+| --- | --- |
+| \`no_conversation\` | \`console.info\` \u2014 pre-empt via the \`enabled\` flag from \`useMessaging()\` (no permission needed) |
+| \`reauth_required\` | \`console.warn\` \u2014 admin sees a "Reconnect" CTA in the dashboard (server flips \`messagingDisconnected: true\`) |
+| \`forbidden\` | \`console.warn\` \u2014 should not reach in production with correct manifest |
+
+The imperative \`messagingSendCapability\` path returns the full taxonomy without the actionable/host-handled split \u2014 useful when you need every code (e.g. dynamic dispatch).
+
+### Defense-in-depth gates
+
+Three gates fire in series, surfacing the same \`forbidden\` error if any blocks:
+
+1. **Embeddable host gate** (\`CapabilityRPCHandler\`) \u2014 checks \`sandbox.manifest.permissions.includes('messaging:send')\` before the call leaves the sandbox.
+2. **Backend handler gate** \u2014 checks \`claims.permissions?.includes('messaging:send')\` on the proxy-token JWT.
+3. **Server-side instance check** \u2014 \`instance.config.messagingDisconnected\` short-circuits with \`reauth_required\` before any upstream call.
+
+### Receiving replies \u2014 pair with \`events:messaging\`
+
+\`reply\` and \`postback\` action clicks fire on extensions with the \`events:messaging\` permission via \`useMessagingEvent\` \u2014 see the \`events:messaging\` section above.
+
+> **Note:** the postback \`payload\` field is currently not surfaced by the Web Widget (only the button text \`actionName\`). Until that gap is closed, design action labels to be self-describing or pair sends with a follow-up \`data.fetch\` lookup.
 `;
 };
 
@@ -1192,6 +1318,39 @@ export function Content(): React.ReactElement {
       <ui.Text className="text-xs">{lastEvent ?? 'No activity yet'}</ui.Text>
     </Surface>
   )
+}`,
+  "messaging.send": `import { useMessaging, Surface, ui } from '@stackable-labs/sdk-extension-react'
+
+// Requires 'messaging:send' permission. send() throws on actionable errors
+// (state.error holds the typed code); resolves to null on host-handled cases.
+export function Content(): React.ReactElement {
+  const [send, { enabled, loading, error }] = useMessaging()
+
+  const onSayHello = async () => {
+    try {
+      await send({
+        kind: 'text',
+        body: 'Hello from the extension',
+        actions: [
+          { type: 'reply', label: 'Sounds good', payload: 'ACK' },
+          { type: 'reply', label: 'Maybe later', payload: 'DEFER' },
+        ],
+      })
+    } catch {
+      // error holds the typed SendMessageActionableErrorCode
+    }
+  }
+
+  return (
+    <Surface id="slot.content">
+      <ui.Stack direction="column" gap="2" className="p-3">
+        <ui.Button onClick={onSayHello} disabled={!enabled || loading}>Say hello</ui.Button>
+        {(error === 'rate_limited') && <ui.Alert variant="warning">Slow down \u2014 sent too many.</ui.Alert>}
+        {(error === 'upstream_error') && <ui.Alert variant="error">Send failed \u2014 please try again.</ui.Alert>}
+        {(error === 'invalid_message') && <ui.Alert variant="error">Send failed \u2014 message format invalid.</ui.Alert>}
+      </ui.Stack>
+    </Surface>
+  )
 }`
 };
 
@@ -1221,10 +1380,6 @@ Bootstrap the extension runtime. Call once in \`src/index.tsx\`.
 ${EXAMPLE_SNIPPETS.bootstrap}
 \`\`\`
 
-## Surface component
-Wraps content for a target slot. The \`id\` must match a target in \`manifest.json\`.
-- \`<Surface id="slot.content">...</Surface>\`
-
 ## useCapabilities()
 Returns the capabilities object for calling host-mediated APIs.
 \`\`\`tsx
@@ -1235,6 +1390,7 @@ const capabilities = useCapabilities()
 // capabilities.actions.toast(payload)
 // capabilities.actions.invoke(action, payload?) \u2014 actions: newConversation, setConversationTags, setConversationFields, open, close, show, hide
 // capabilities.identity.extend(patch) \u2014 push enrichment claims to user.metadata + JWT custom_claims (imperative; for handler-style at login, use useExtendIdentity hook). Each patch key MUST be declared in manifest.identityClaims or the host filter drops it.
+// capabilities.messaging.send(payload) \u2014 post a message into the active conversation bound to this Instance. Prefer the useMessaging hook instead. Requires messaging:send permission. Author label is admin-set per-Instance (instance.config.settings.messagingDisplayName) with extension.manifest.name fallback.
 \`\`\`
 
 ## useStore(store, selector?)
@@ -1243,6 +1399,17 @@ Subscribe to a shared store. Re-renders when the selected state changes.
 const viewState = useStore(appStore, (s) => s.viewState)
 \`\`\`
 
+## createStore(initialState)
+Create a shared store for cross-surface state coordination.
+\`\`\`tsx
+const appStore = createStore<AppState>({ viewState: { type: 'menu' } })
+\`\`\`
+
+**Store\\<T\\> interface**
+- \`get(): T\` \u2014 read current state
+- \`set(partial: Partial<T>): void\` \u2014 merge partial state update
+- \`subscribe(listener: (state: T) => void): () => void\` \u2014 subscribe, returns unsubscribe fn
+
 ## useContextData()
 Reads host-provided context including extension settings. Returns \`{ loading, customerId, customerEmail, messaging, settings, ... }\`. \`messaging.conversationId\` is the active Messaging conversation ID (or \`null\` until one exists).
 \`\`\`tsx
@@ -1269,26 +1436,48 @@ Returns extension-level context.
 const { extensionId } = useExtension()
 \`\`\`
 
-## createStore(initialState)
-Create a shared store for cross-surface state coordination.
+## useEvent(eventType, handler)
+Generic cross-domain event hook (should not be used unless absolutely required). Subscribe to any event using fully-qualified event types.
+- \`eventType: EventType\` \u2014 fully-qualified (e.g., \`'activity:product_view'\`, \`'identity:login'\`, \`'messaging:postback'\`)
+- Domain wildcard (e.g., \`'activity'\`) receives all events in that domain
+- \`handler: (event: BaseEvent) => void\`
+
 \`\`\`tsx
-const appStore = createStore<AppState>({ viewState: { type: 'menu' } })
+useEvent('activity', (event) => {
+  console.log('Activity:', event.data)
+})
 \`\`\`
 
-### Store\\<T\\> interface
-- \`get(): T\` \u2014 read current state
-- \`set(partial: Partial<T>): void\` \u2014 merge partial state update
-- \`subscribe(listener: (state: T) => void): () => void\` \u2014 subscribe, returns unsubscribe fn
+## useMessaging()
+Send messages into the active conversation bound to this Instance. Wraps the \`messaging.send\` capability with React state, tracking \`enabled\` / \`loading\` / \`error\` / \`data\`. Returns a tuple \`[send, state]\` so callers can rename \`send\` when the hook is used multiple times in one component. Requires \`messaging:send\` permission. The author label rendered above outbound messages is set per-Instance by the admin (Instance settings \`messagingDisplayName\`); falls back to \`extension.manifest.name\` when blank.
 
-## useIdentityEvent(eventType, handler)
-Subscribe to identity events pushed from the host via the framework. Requires \`events:identity\` permission and matching entries in manifest \`events\` array.
-- \`eventType: ${identityEventTypes}\`
-- \`handler: (event: IdentityEvent) => void\`
-- \`IdentityEvent: { eventName: IdentityEventType, data: { state: IdentityState, timestamp: string } }\`
-- \`IdentityState: { authenticated: boolean, user: UserIdentity | null, expiresAt?: string }\`
+- **Returns:** \`readonly [send, { enabled, loading, error, data }]\`
+- **\`send(payload: SendMessagePayload): Promise<SendMessageResponse | null>\`** \u2014 returns the response on success; throws on **actionable** errors; resolves to \`null\` on host-handled errors (SDK logs a breadcrumb, host surfaces remediation)
+- **\`enabled: boolean\`** \u2014 advisory; \`true\` when an active conversation exists. Permission-free (no \`context:read\` needed). Wire to button \`disabled\` to pre-empt the silent \`no_conversation\` case. Starts \`false\`; flips reactively via host-pushed availability events.
+- **\`loading: boolean\`** \u2014 true while a call is in flight (matches \`useContextData\`'s \`loading\` for SDK-wide consistency)
+- **\`data: SendMessageResponse | null\`** \u2014 \`{ messageId, receivedAt }\` from last successful send
+- **\`error: SendMessageActionableErrorCode | null\`** \u2014 one of \`invalid_message\` / \`rate_limited\` / \`upstream_error\` after a failed send. Host-handled codes (\`no_conversation\` / \`reauth_required\` / \`forbidden\`) never surface here.
+
+Payload is discriminated by \`kind\`: \`'text'\` / \`'image'\` / \`'file'\` / \`'carousel'\`. See the \`messaging.send\` capability section for the full payload table + action types.
 
 \`\`\`tsx
-${stripImports(HOOK_SNIPPETS["events:identity"])}
+import { useMessaging } from '@stackable-labs/sdk-extension-react'
+
+const [send, { enabled, loading, error }] = useMessaging()
+
+const onApprove = async () => {
+  try {
+    await send({ kind: 'text', body: 'Approved \u2713' })
+  } catch {
+    // error holds the typed SendMessageActionableErrorCode
+  }
+}
+
+return (
+  <button disabled={!enabled || loading} onClick={onApprove}>
+    Approve
+  </button>
+)
 \`\`\`
 
 ## useMessagingEvent(eventType, handler)
@@ -1319,16 +1508,15 @@ Subscribe to activity events pushed from the host via the framework. Requires \`
 ${stripImports(HOOK_SNIPPETS["events:activity"])}
 \`\`\`
 
-## useEvent(eventType, handler)
-Generic cross-domain event hook (should not be used unless absolutely required). Subscribe to any event using fully-qualified event types.
-- \`eventType: EventType\` \u2014 fully-qualified (e.g., \`'activity:product_view'\`, \`'identity:login'\`, \`'messaging:postback'\`)
-- Domain wildcard (e.g., \`'activity'\`) receives all events in that domain
-- \`handler: (event: BaseEvent) => void\`
+## useIdentityEvent(eventType, handler)
+Subscribe to identity events pushed from the host via the framework. Requires \`events:identity\` permission and matching entries in manifest \`events\` array.
+- \`eventType: ${identityEventTypes}\`
+- \`handler: (event: IdentityEvent) => void\`
+- \`IdentityEvent: { eventName: IdentityEventType, data: { state: IdentityState, timestamp: string } }\`
+- \`IdentityState: { authenticated: boolean, user: UserIdentity | null, expiresAt?: string }\`
 
 \`\`\`tsx
-useEvent('activity', (event) => {
-  console.log('Activity:', event.data)
-})
+${stripImports(HOOK_SNIPPETS["events:identity"])}
 \`\`\`
 
 ## useExtendIdentity(handler)
@@ -1345,7 +1533,7 @@ With \`useCallback\` (for memoized handlers):
 ${HOOK_SNIPPETS_MEMOIZED["identity.extend"]}
 \`\`\`
 
-## Identity via context.read()
+**Identity via context.read()**
 Identity state is available in the \`context.read()\` response as an \`identity\` field. Requires \`context:read\` permission (no separate identity permission needed).
 \`\`\`tsx
 const context = await capabilities.context.read()
@@ -3612,6 +3800,27 @@ updating custom fields.
 \`\`\`tsx
 ${EXAMPLE_SNIPPETS["actions.invoke"]}
 \`\`\`
+
+## messaging.send \u2014 Sending Messages to Conversations
+
+Post a message into the active conversation bound to this Instance via the
+\`useMessaging\` React hook. Returns the response on happy path and throws on
+**actionable** errors \u2014 inspect \`error\` for one of the typed
+\`SendMessageActionableErrorCode\` values (\`invalid_message\`, \`rate_limited\`,
+\`upstream_error\`). Host-handled cases (\`no_conversation\`, \`reauth_required\`,
+\`forbidden\`) resolve to \`null\` without throwing; the SDK logs a breadcrumb
+and the host surfaces remediation to admins (e.g. dashboard reconnect UI) \u2014
+extensions don't catch them.
+
+**Permission:** \`messaging:send\`. The author label rendered above outbound
+messages is set **per-Instance by the admin** via the Instance settings field
+\`messagingDisplayName\` (visible on the dashboard once OAuth completes);
+falls back to \`extension.manifest.name\` when blank. Extensions do not set or
+think about the author identity.
+
+\`\`\`tsx
+${EXAMPLE_SNIPPETS["messaging.send"]}
+\`\`\`
 `;
 };
 var generateCookbookStructural = () => {
@@ -3695,6 +3904,108 @@ ${EXAMPLE_SNIPPETS.surfaceContext}
 \`\`\`
 `;
 };
+var renderPayload = (kind) => JSON.stringify(MESSAGING_SEND_EXAMPLES[kind], null, 2);
+var renderAction = (type) => JSON.stringify(MESSAGING_ACTION_EXAMPLES[type], null, 2);
+var ACTION_DESCRIPTIONS = {
+  reply: "Inserts a visible user-reply bubble carrying `payload` back into the conversation, as if the user typed it. **Mutually exclusive** \u2014 a `reply` action cannot share an `actions[]` array with any other action type; the host validates and surfaces `invalid_message` if mixed.",
+  link: "Opens `url` in a new tab/window. No bubble inserted. Freely mixable with other non-reply actions.",
+  postback: "Fires a server-side `conversation:postback` webhook to the Stackable backend carrying the full `payload` + any `metadata`. NO visible bubble. Extensions with the `events:messaging` permission receive postback events via `useMessagingEvent` \u2014 see the **Events & Identity** cookbook.",
+  locationRequest: "Prompts the user to share device location. Response arrives as a separate `location`-type message inbound to the conversation. Freely mixable."
+};
+var actionTypeSections = Object.keys(MESSAGING_ACTION_EXAMPLES).map((type) => `### type: '${type}'
+
+${ACTION_DESCRIPTIONS[type]}
+
+\`\`\`tsx
+${renderAction(type)}
+\`\`\``).join("\n\n");
+var generateCookbookMessaging = () => {
+  const fm = frontmatter({
+    root: false,
+    targets: ["*"],
+    description: "Cookbook: example payloads per-kind for the messaging.send capability + action type shapes",
+    globs: ["packages/extension/src/**/*.tsx", "packages/extension/src/**/*.ts"]
+  });
+  return `${fm}
+
+# Messaging Examples
+
+Example payloads for the \`messaging.send\` capability \u2014 one per supported message
+kind, plus the action types you can attach to messages. Each payload is the
+exact shape the \`useMessaging\` hook accepts; copy and adapt as needed.
+
+**Permission:** \`messaging:send\` in your \`manifest.json\`. The author label
+above outbound messages is set **per-Instance by the admin** via the Instance
+settings field \`messagingDisplayName\`; falls back to \`extension.manifest.name\`
+when blank. Extensions do not set or think about the author identity.
+
+---
+
+## kind: 'text' \u2014 Plain text + reply actions
+
+Plain conversational message. Optional \`actions\` array attaches quick-reply
+buttons, links, postbacks, or location requests.
+
+\`\`\`tsx
+const [send] = useMessaging()
+
+await send(${renderPayload("text")})
+\`\`\`
+
+## kind: 'image' \u2014 Embedded image + optional caption
+
+Product photos, screenshots, visual help. \`url\` must respond with a
+\`Content-Type: image/*\` header (Sunco enforces; redirecting URLs like
+\`picsum.photos\` will fail). \`altText\` is optional \u2014 defaults to filename.
+Optional \`body\` renders a caption alongside the image.
+
+\`\`\`tsx
+const [send] = useMessaging()
+
+await send(${renderPayload("image")})
+\`\`\`
+
+## kind: 'file' \u2014 Embedded file attachment
+
+Return labels, receipts, NDAs, warranty paperwork. Sunco's \`fileMessage\`
+schema does NOT support \`actions\` \u2014 file messages can only carry an
+optional text caption.
+
+\`\`\`tsx
+const [send] = useMessaging()
+
+await send(${renderPayload("file")})
+\`\`\`
+
+## kind: 'carousel' \u2014 Horizontally scrolling cards
+
+The conversational-commerce primitive: product recommendations, size/color
+pickers, search results with images, multi-option selection.
+
+- 1\u201310 items, each with required \`title\` + required \`actions\` (1\u20133 per item)
+- Item actions are a subset: \`link\` + \`postback\` only (no \`reply\`, no
+  \`locationRequest\` \u2014 Sunco rejects those at the item level)
+- Carousel messages have NO message-level \`actions\` field \u2014 actions live
+  per-card
+- Use a separate \`text\` message before the carousel if you need an intro
+
+\`\`\`tsx
+const [send] = useMessaging()
+
+await send(${renderPayload("carousel")})
+\`\`\`
+
+---
+
+## Action types
+
+Attach to message-level \`actions\` (text / image) or item-level \`actions\`
+(carousel). All actions share \`label\` + optional \`metadata\` (primitives only,
+\u22644KB total).
+
+${actionTypeSections}
+`;
+};
 var identityEventTypes2 = Object.values(IDENTITY_EVENT).map((e) => `\`${e}\``).join(", ");
 var activityEventTypes2 = Object.values(ACTIVITY_EVENT).map((e) => `\`${e}\``).join(", ");
 var generateCookbookEvents = () => {
@@ -3716,7 +4027,7 @@ supports both a login-time hook (\`useExtendIdentity\`) and an imperative post-l
 
 ## Messaging Events
 
-Subscribe to postback button clicks from the Zendesk messaging widget.
+Subscribe to postback button clicks from the Messaging widget.
 The \`actionName\` is the button's display text, not a programmatic identifier.
 
 **Permission:** \`events:messaging\`
@@ -3853,7 +4164,7 @@ alongside existing surfaces.
 Add the target to the \`targets\` array in \`packages/extension/public/manifest.json\`.
 Also add any required permissions based on the target-permission mapping:
 - \`slot.header\` \u2192 \`context:read\`
-- \`slot.content\` \u2192 \`context:read\`, \`data:query\`, \`actions:toast\`, \`actions:invoke\`
+- \`slot.content\` \u2192 \`context:read\`, \`data:query\`, \`actions:toast\`, \`actions:invoke\`, \`messaging:send\`
 - \`slot.footer\` \u2192 (none)
 - \`slot.footer-links\` \u2192 (none)
 
@@ -3929,6 +4240,18 @@ await capabilities.identity.extend({ verified: true })
 useIdentityEvent('refresh', (event) => {
   console.log('verified =>', event.data.state.user?.metadata?.verified)
 })
+`,
+  "messaging.send": `${HOOK_SNIPPETS["messaging.send"]}
+
+// Actionable errors throw + populate state.error: 'invalid_message' (bad payload),
+// 'rate_limited' (slow down), 'upstream_error' (transient \u2014 retry). Branch in
+// catch / on state.error to show UX.
+// Host-handled cases ('no_conversation' / 'reauth_required' / 'forbidden')
+// resolve to null without throwing; the SDK logs a breadcrumb and the host
+// surfaces remediation to admins (e.g. dashboard Reconnect UI). Extensions
+// can pre-empt 'no_conversation' via the 'enabled' flag from useMessaging()
+// (permission-free) \u2014 wire to button disabled={!enabled || loading}.
+if (error === 'rate_limited') { /* show "slow down" UI */ }
 `
 };
 var EVENT_SNIPPETS = {
@@ -4006,7 +4329,7 @@ export function Content(): React.ReactElement {
 // ../../sdk/extension/ai-docs/src/commands/add-capability.ts
 var generateAddCapabilityCommand = () => {
   const fm = frontmatter({
-    description: "Wire up a new capability (data.fetch, data.query, context.read, actions.toast, actions.invoke, identity.extend, events:identity, events:messaging, events:activity) in this extension",
+    description: "Wire up a new capability (data.fetch, data.query, context.read, actions.toast, actions.invoke, messaging.send, identity.extend, events:identity, events:messaging, events:activity) in this extension",
     targets: ["*"]
   });
   return `${fm}
@@ -4022,6 +4345,7 @@ Ask which capability to add. Valid capabilities:
 - \`context.read\` \u2014 read host-provided context (customerId, customerEmail, messaging.conversationId, etc.)
 - \`actions.toast\` \u2014 show toast notifications (success, error, info, warning)
 - \`actions.invoke\` \u2014 invoke host actions (e.g., open new conversation)
+- \`messaging.send\` \u2014 send messages into the active conversation bound to this Instance (text/image/file/carousel + reply/link/postback actions)
 - \`identity.extend\` \u2014 enrich identity JWT claims before signing
 - \`events:identity\` \u2014 subscribe to identity events (login, logout, refresh, expired)
 - \`events:messaging\` \u2014 subscribe to messaging events (postback button clicks)
@@ -4034,6 +4358,7 @@ Add the corresponding permission to \`packages/extension/public/manifest.json\`:
 - \`context.read\` \u2192 \`"context:read"\`
 - \`actions.toast\` \u2192 \`"actions:toast"\`
 - \`actions.invoke\` \u2192 \`"actions:invoke"\`
+- \`messaging.send\` \u2192 \`"messaging:send"\`
 - \`identity.extend\` \u2192 \`"identity:extend"\`
 - \`events:identity\` \u2192 \`"events:identity"\` (also add entries to \`events\` array, e.g. \`["identity:login", "identity:logout"]\`)
 - \`events:messaging\` \u2192 \`"events:messaging"\` (also add entries to \`events\` array, e.g. \`["messaging:postback:Buy Now"]\`)
@@ -4076,12 +4401,15 @@ const capabilities = useCapabilities()
 // actions.invoke: capabilities.actions.invoke('newConversation', { tags: ['order'], fields: [{ id: 'field_id', value: 'val' }] })
 \`\`\`
 
-### Special handling (events + identity.extend):
+### Special handling (events + identity.extend + messaging.send):
 
 #### For events \u2014 ALWAYS use dedicated hooks (INSTEAD of useCapabilities direct):
 Events are subscribed via \`useIdentityEvent\` / \`useMessagingEvent\` / \`useActivityEvent\` \u2014 never use \`capabilities.events.*\` directly (events are not part of the \`capabilities\` object).
 
-#### For identity.extend \u2014 choose the CORRECT option:
+#### For messaging.send \u2014 ALWAYS use the \`useMessaging\` hook:
+\`useMessaging\` returns a \`[send, { enabled, loading, error }]\` tuple. The \`send\` function is the imperative call wrapped with React state + typed errors. ALWAYS use the hook \u2014 do NOT call \`capabilities.messaging.send(...)\` directly from \`useCapabilities()\`. The hook is the canonical pattern: state management (\`enabled\`/\`loading\`) + typed errors (\`error\`) + correct payload shape (\`{ kind, body }\` with the \`kind\` discriminator). Wire send buttons to \`disabled={!enabled || loading}\` \u2014 the \`enabled\` flag pre-empts the silent \`no_conversation\` case without declaring \`context:read\`. See the snippet below for the full error-handling surface (actionable codes vs. host-handled codes).
+
+#### For identity.extend \u2014 CHOOSE the correct option:
 - **\`useExtendIdentity(handler)\`** \u2014 synchronous hook, fires only once at initial login. ALWAYS use for known-at-login enrichment.
 - **\`capabilities.identity.extend(patch)\`** \u2014 imperative call via \`useCapabilities()\`, fires post-login (after async verification, webhook callbacks, user-triggered flows). Re-signs the JWT and broadcasts \`identity:refresh\`.
 
@@ -4100,6 +4428,11 @@ ${HOOK_SNIPPETS["events:messaging"]}
 ${HOOK_SNIPPETS["events:activity"]}
 \`\`\`
 
+\`\`\`tsx
+// messaging.send \u2014 use useMessaging hook (returns [send, { enabled, loading, error }] tuple)
+${HOOK_SNIPPETS["messaging.send"]}
+\`\`\`
+
 \`\`\`tsx
 // identity.extend \u2014 login-time useExtendIdentity hook OR post-login imperative capabilities.identity.extend
 ${CAPABILITY_SNIPPETS["identity.extend"]}
@@ -4111,6 +4444,7 @@ ${CAPABILITY_SNIPPETS["identity.extend"]}
 - For data/context/actions: confirm accessed via \`useCapabilities()\` hook
 - For events: confirm using \`useIdentityEvent\`, \`useMessagingEvent\`, or \`useActivityEvent\` hooks
 - For identity.extend: confirm using \`useExtendIdentity\` hook (login-time) and/or \`capabilities.identity.extend(patch)\` (imperative post-login)
+- For messaging.send: confirm using \`useMessaging\` hook
 `;
 };
 
@@ -4582,6 +4916,13 @@ var SKILLS = [
     scopes: ["docs"],
     content: () => generateCookbookEvents()
   },
+  {
+    id: "cookbook-messaging",
+    description: "Cookbook: per-kind example payloads (text / image / file / carousel) and action types (reply / link / postback / locationRequest) for the messaging.send capability. Use when wiring the useMessaging hook or composing outbound conversation messages.",
+    type: "knowledge",
+    scopes: ["docs"],
+    content: () => generateCookbookMessaging()
+  },
   {
     id: "marketplace-listing",
     description: "Marketplace listing reference: the listing fields (icon, screenshots, description, categories), Public vs Protected visibility, and the two-stage review process (bundle scan + security review + approval). Use when publishing a deployed extension to the marketplace.",
@@ -5051,6 +5392,39 @@ export function Content() {
       <ui.Text className="text-xs">{lastEvent ?? 'No activity yet'}</ui.Text>
     </Surface>
   )
+}`,
+  "messaging.send": `import { useMessaging, Surface, ui } from '@stackable-labs/sdk-extension-react'
+
+// Requires 'messaging:send' permission. send() throws on actionable errors
+// (state.error holds the typed code); resolves to null on host-handled cases.
+export function Content() {
+  const [send, { enabled, loading, error }] = useMessaging()
+
+  const onSayHello = async () => {
+    try {
+      await send({
+        kind: 'text',
+        body: 'Hello from the extension',
+        actions: [
+          { type: 'reply', label: 'Sounds good', payload: 'ACK' },
+          { type: 'reply', label: 'Maybe later', payload: 'DEFER' },
+        ],
+      })
+    } catch {
+      // error holds the typed SendMessageActionableErrorCode
+    }
+  }
+
+  return (
+    <Surface id="slot.content">
+      <ui.Stack direction="column" gap="2" className="p-3">
+        <ui.Button onClick={onSayHello} disabled={!enabled || loading}>Say hello</ui.Button>
+        {(error === 'rate_limited') && <ui.Alert variant="warning">Slow down \u2014 sent too many.</ui.Alert>}
+        {(error === 'upstream_error') && <ui.Alert variant="error">Send failed \u2014 please try again.</ui.Alert>}
+        {(error === 'invalid_message') && <ui.Alert variant="error">Send failed \u2014 message format invalid.</ui.Alert>}
+      </ui.Stack>
+    </Surface>
+  )
 }`
 };
 
@@ -5142,7 +5516,22 @@ await capabilities.identity.extend({ verified: true })
 // Consumer side \u2014 same or sibling extension reacts via identity:refresh
 useIdentityEvent('refresh', (event) => {
   console.log('verified =>', event.data.state.user?.metadata?.verified)
-})`
+})`,
+  "messaging.send": `import { useMessaging } from '@stackable-labs/sdk-extension-react'
+
+// manifest.json: { "permissions": ["messaging:send"] }
+const [send, { enabled, loading, error }] = useMessaging()
+await send({ kind: 'text', body: 'Hello from the extension' })
+
+// Actionable errors throw + populate state.error: 'invalid_message' (bad payload),
+// 'rate_limited' (slow down), 'upstream_error' (transient \u2014 retry). Branch in
+// catch / on state.error to show UX.
+// Host-handled cases ('no_conversation' / 'reauth_required' / 'forbidden')
+// resolve to null without throwing; the SDK logs a breadcrumb and the host
+// surfaces remediation to admins (e.g. dashboard Reconnect UI). Extensions
+// can pre-empt 'no_conversation' via the 'enabled' flag from useMessaging()
+// (permission-free) \u2014 wire to button disabled={!enabled || loading}.
+if (error === 'rate_limited') { /* show "slow down" UI */ }`
 };
 var EVENT_SNIPPETS2 = {
   "events:identity": `import { useIdentityEvent, Surface, ui } from '@stackable-labs/sdk-extension-react'
@@ -5518,7 +5907,7 @@ ${errors.map((e) => `- ${e}`).join("\n")}`);
         usedPermissions.add(permission);
       }
     }
-    for (const [hook, permission] of Object.entries(EVENT_HOOK_PERMISSION_MAP)) {
+    for (const [hook, permission] of Object.entries(HOOK_PERMISSION_MAP)) {
       if (allSource.includes(hook)) {
         usedPermissions.add(permission);
       }