@stackable-labs/mcp-app-extension 1.7.1 → 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()
@@ -2271,7 +2276,7 @@ Every domain your extension calls must be listed in \`allowedDomains\`:
 - The framework will reject requests to unlisted domains
 - Add each subdomain separately when listing exact hosts (e.g., \`api.example.com\` and \`cdn.example.com\`)
 
-### Wildcards
+#### Wildcard Domains
 
 **Prefer exact hostnames where possible.** Use \`*.example.com\` only when you
 need to match any subdomain \u2014 for example, tenant-per-subdomain platforms
@@ -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
@@ -4115,7 +4120,7 @@ var SKILLS = [
   },
   {
     id: "capabilities",
-    description: "Extension capabilities: data.query, data.fetch, context.read, actions.toast, actions.invoke. Use when wiring up host-mediated APIs or direct HTTP requests.",
+    description: "Extension capabilities: data.query, data.fetch, context.read, actions.toast, actions.invoke. Use when wiring up platform-mediated APIs or direct HTTP requests.",
     type: "knowledge",
     content: () => generateCapabilities()
   },
@@ -4166,7 +4171,7 @@ var SKILLS = [
   },
   {
     id: "external-apis",
-    description: "Direct HTTP requests via data.fetch, allowedDomains configuration, and API wrapper patterns. Use when connecting an extension to external APIs.",
+    description: "Direct HTTP requests via data.fetch \u2014 allowed domains (including wildcard subdomains like *.myshopify.com), allowedDomains configuration, API wrapper patterns, and data.fetch vs data.query. Use when connecting an extension to external APIs or configuring allowedDomains.",
     type: "knowledge",
     content: () => generateExternalApis()
   },
@@ -4178,7 +4183,7 @@ var SKILLS = [
   },
   {
     id: "styling-and-theming",
-    description: "Host theme inheritance, className usage, layout components, and CSS constraints. Use when styling extension UI or working with the host theme.",
+    description: "Extension theming and styling - tailwind className usage, layout components, and CSS constraints. Use when styling extension UI or working with the host theme.",
     type: "knowledge",
     content: () => generateStylingAndTheming()
   },
@@ -4268,7 +4273,7 @@ var SKILLS = [
   },
   {
     id: "add-capability",
-    description: "Wire up a new capability (data.fetch, data.query, context.read, actions.toast, actions.invoke) in this extension. Use when adding a new host-mediated API.",
+    description: "Wire up a new capability (data.fetch, data.query, context.read, actions.toast, actions.invoke) in this extension. Use when adding a new platform-mediated API.",
     type: "action",
     content: () => generateAddCapabilityCommand()
   },

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()
@@ -2264,7 +2269,7 @@ Every domain your extension calls must be listed in \`allowedDomains\`:
 - The framework will reject requests to unlisted domains
 - Add each subdomain separately when listing exact hosts (e.g., \`api.example.com\` and \`cdn.example.com\`)
 
-### Wildcards
+#### Wildcard Domains
 
 **Prefer exact hostnames where possible.** Use \`*.example.com\` only when you
 need to match any subdomain \u2014 for example, tenant-per-subdomain platforms
@@ -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
@@ -4108,7 +4113,7 @@ var SKILLS = [
   },
   {
     id: "capabilities",
-    description: "Extension capabilities: data.query, data.fetch, context.read, actions.toast, actions.invoke. Use when wiring up host-mediated APIs or direct HTTP requests.",
+    description: "Extension capabilities: data.query, data.fetch, context.read, actions.toast, actions.invoke. Use when wiring up platform-mediated APIs or direct HTTP requests.",
     type: "knowledge",
     content: () => generateCapabilities()
   },
@@ -4159,7 +4164,7 @@ var SKILLS = [
   },
   {
     id: "external-apis",
-    description: "Direct HTTP requests via data.fetch, allowedDomains configuration, and API wrapper patterns. Use when connecting an extension to external APIs.",
+    description: "Direct HTTP requests via data.fetch \u2014 allowed domains (including wildcard subdomains like *.myshopify.com), allowedDomains configuration, API wrapper patterns, and data.fetch vs data.query. Use when connecting an extension to external APIs or configuring allowedDomains.",
     type: "knowledge",
     content: () => generateExternalApis()
   },
@@ -4171,7 +4176,7 @@ var SKILLS = [
   },
   {
     id: "styling-and-theming",
-    description: "Host theme inheritance, className usage, layout components, and CSS constraints. Use when styling extension UI or working with the host theme.",
+    description: "Extension theming and styling - tailwind className usage, layout components, and CSS constraints. Use when styling extension UI or working with the host theme.",
     type: "knowledge",
     content: () => generateStylingAndTheming()
   },
@@ -4261,7 +4266,7 @@ var SKILLS = [
   },
   {
     id: "add-capability",
-    description: "Wire up a new capability (data.fetch, data.query, context.read, actions.toast, actions.invoke) in this extension. Use when adding a new host-mediated API.",
+    description: "Wire up a new capability (data.fetch, data.query, context.read, actions.toast, actions.invoke) in this extension. Use when adding a new platform-mediated API.",
     type: "action",
     content: () => generateAddCapabilityCommand()
   },

package/package.json

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