@stackable-labs/mcp-app-extension 1.8.0 → 1.9.0

package/dist/index.js

@@ -579,17 +579,18 @@ const result = await capabilities.data.fetch('https://api.example.com/orders', {
 > See [Instance Settings](./instance-settings) for the full schema-declaration + storage-mode story, including which field types accept \`secret: true\`.
 
 ## context.read \u2014 Read Platform Context
-Read framework-provided context (customer ID, email, extension settings, etc.).
+Read framework-provided context (customer ID, email, messaging conversation, extension settings, etc.).
 - **Permission required:** \`context:read\`
 - **Usage:** \`capabilities.context.read(): Promise<ContextData>\`
-- **ContextData shape:** \`{ customerId?: string, customerEmail?: string, settings?: Record<string, unknown>, [key: string]: unknown }\`
+- **ContextData shape:** \`{ customerId?: string, customerEmail?: string, messaging?: { conversationId?: string | null, appId?: string | null }, settings?: Record<string, unknown>, [key: string]: unknown }\`
 - **Convenience hooks:**
   - \`useContextData()\` returns \`ContextData & { loading: boolean }\`
   - \`useSettings()\` returns \`Record<string, unknown>\` \u2014 shorthand for \`contextData.settings ?? {}\`
 
 \`\`\`tsx
-// Read all context (customer + settings)
-const { loading, customerId, customerEmail, settings } = useContextData()
+// Read all context (customer + messaging + settings)
+const { loading, customerId, customerEmail, messaging, settings } = useContextData()
+const conversationId = messaging?.conversationId
 
 // Read only extension settings (convenience)
 const settings = useSettings()
@@ -599,6 +600,9 @@ const apiBaseUrl = settings.baseUrl as string
 const context = await capabilities.context.read()
 \`\`\`
 
+### Messaging context
+\`messaging.conversationId\` is the active Messaging conversation ID, or \`null\` until the widget has an open conversation. Use this when you need the ID for an API call from a non-event surface. If you're already reacting to a postback button click, prefer reading \`event.data.conversationId\` from \`useMessagingEvent\` \u2014 it doesn't require \`context:read\`.
+
 ### Extension settings in context
 Non-secret settings declared in \`settingsSchema\` are automatically available via \`contextData.settings\`. Values are scoped to the calling extension on the current instance \u2014 an extension never sees other extensions' settings.
 
@@ -621,7 +625,7 @@ Trigger framework-defined actions (e.g., open a new conversation, set conversati
 - **Permission required:** \`actions:invoke\`
 - **Usage:** \`capabilities.actions.invoke<T>(action: string, payload?: Record<string, unknown>): Promise<T>\`
 - **Available actions:**
-  - \`'newConversation'\` \u2014 start a new Zendesk conversation (optionally with tags/fields)
+  - \`'newConversation'\` \u2014 start a new Messaging conversation (optionally with tags/fields)
   - \`'setConversationTags'\` \u2014 set tags on the current/next conversation
   - \`'setConversationFields'\` \u2014 set custom fields on the current/next conversation
   - \`'open'\` / \`'close'\` / \`'show'\` / \`'hide'\` \u2014 control the Zendesk messenger widget
@@ -1088,9 +1092,10 @@ const viewState = useStore(appStore, (s) => s.viewState)
 \`\`\`
 
 ## useContextData()
-Reads host-provided context including extension settings. Returns \`{ loading, customerId, customerEmail, settings, ... }\`.
+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
-const { loading, customerId, customerEmail, settings } = useContextData()
+const { loading, customerId, customerEmail, messaging, settings } = useContextData()
+const conversationId = messaging?.conversationId
 \`\`\`
 
 ## useSettings()
@@ -3696,7 +3701,7 @@ Wire up a new capability in this extension. Follow these steps exactly:
 Ask which capability to add. Valid capabilities:
 - \`data.query\` \u2014 host-mediated data requests (action name + params \u2192 host returns data)
 - \`data.fetch\` \u2014 direct HTTP requests from the sandbox (requires allowedDomains)
-- \`context.read\` \u2014 read host-provided context (customerId, customerEmail, etc.)
+- \`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)
 - \`extend:identity\` \u2014 enrich identity JWT claims before signing

package/dist/server.js

@@ -572,17 +572,18 @@ const result = await capabilities.data.fetch('https://api.example.com/orders', {
 > See [Instance Settings](./instance-settings) for the full schema-declaration + storage-mode story, including which field types accept \`secret: true\`.
 
 ## context.read \u2014 Read Platform Context
-Read framework-provided context (customer ID, email, extension settings, etc.).
+Read framework-provided context (customer ID, email, messaging conversation, extension settings, etc.).
 - **Permission required:** \`context:read\`
 - **Usage:** \`capabilities.context.read(): Promise<ContextData>\`
-- **ContextData shape:** \`{ customerId?: string, customerEmail?: string, settings?: Record<string, unknown>, [key: string]: unknown }\`
+- **ContextData shape:** \`{ customerId?: string, customerEmail?: string, messaging?: { conversationId?: string | null, appId?: string | null }, settings?: Record<string, unknown>, [key: string]: unknown }\`
 - **Convenience hooks:**
   - \`useContextData()\` returns \`ContextData & { loading: boolean }\`
   - \`useSettings()\` returns \`Record<string, unknown>\` \u2014 shorthand for \`contextData.settings ?? {}\`
 
 \`\`\`tsx
-// Read all context (customer + settings)
-const { loading, customerId, customerEmail, settings } = useContextData()
+// Read all context (customer + messaging + settings)
+const { loading, customerId, customerEmail, messaging, settings } = useContextData()
+const conversationId = messaging?.conversationId
 
 // Read only extension settings (convenience)
 const settings = useSettings()
@@ -592,6 +593,9 @@ const apiBaseUrl = settings.baseUrl as string
 const context = await capabilities.context.read()
 \`\`\`
 
+### Messaging context
+\`messaging.conversationId\` is the active Messaging conversation ID, or \`null\` until the widget has an open conversation. Use this when you need the ID for an API call from a non-event surface. If you're already reacting to a postback button click, prefer reading \`event.data.conversationId\` from \`useMessagingEvent\` \u2014 it doesn't require \`context:read\`.
+
 ### Extension settings in context
 Non-secret settings declared in \`settingsSchema\` are automatically available via \`contextData.settings\`. Values are scoped to the calling extension on the current instance \u2014 an extension never sees other extensions' settings.
 
@@ -614,7 +618,7 @@ Trigger framework-defined actions (e.g., open a new conversation, set conversati
 - **Permission required:** \`actions:invoke\`
 - **Usage:** \`capabilities.actions.invoke<T>(action: string, payload?: Record<string, unknown>): Promise<T>\`
 - **Available actions:**
-  - \`'newConversation'\` \u2014 start a new Zendesk conversation (optionally with tags/fields)
+  - \`'newConversation'\` \u2014 start a new Messaging conversation (optionally with tags/fields)
   - \`'setConversationTags'\` \u2014 set tags on the current/next conversation
   - \`'setConversationFields'\` \u2014 set custom fields on the current/next conversation
   - \`'open'\` / \`'close'\` / \`'show'\` / \`'hide'\` \u2014 control the Zendesk messenger widget
@@ -1081,9 +1085,10 @@ const viewState = useStore(appStore, (s) => s.viewState)
 \`\`\`
 
 ## useContextData()
-Reads host-provided context including extension settings. Returns \`{ loading, customerId, customerEmail, settings, ... }\`.
+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
-const { loading, customerId, customerEmail, settings } = useContextData()
+const { loading, customerId, customerEmail, messaging, settings } = useContextData()
+const conversationId = messaging?.conversationId
 \`\`\`
 
 ## useSettings()
@@ -3689,7 +3694,7 @@ Wire up a new capability in this extension. Follow these steps exactly:
 Ask which capability to add. Valid capabilities:
 - \`data.query\` \u2014 host-mediated data requests (action name + params \u2192 host returns data)
 - \`data.fetch\` \u2014 direct HTTP requests from the sandbox (requires allowedDomains)
-- \`context.read\` \u2014 read host-provided context (customerId, customerEmail, etc.)
+- \`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)
 - \`extend:identity\` \u2014 enrich identity JWT claims before signing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackable-labs/mcp-app-extension",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "type": "module",
   "bin": {
     "mcp-app-extension": "./dist/index.js"