@stackable-labs/mcp-app-extension 0.7.3 → 0.8.0

package/dist/index.js

@@ -463,8 +463,8 @@ const result = await capabilities.data.query<Customer>({
 })
 \`\`\`
 
-## data.fetch \u2014 Direct HTTP from Sandbox
-Extension makes HTTP requests directly. Domain must be in \`allowedDomains\` in manifest.
+## data.fetch \u2014 HTTP Requests to External APIs
+Make HTTP requests to external APIs. Domain must be in \`allowedDomains\` in manifest. Requests are proxied through the Stackable platform server.
 - **Permission required:** \`data:fetch\`
 - **Usage:** \`capabilities.data.fetch(url: string, init?: FetchRequestInit): Promise<FetchResponse>\`
 - **FetchRequestInit:** \`{ method?: 'GET'|'POST'|'PUT'|'PATCH'|'DELETE', headers?: Record<string,string>, body?: unknown }\`
@@ -480,21 +480,52 @@ if (!result.ok) throw new Error(\`Request failed: \${result.status}\`)
 const data = result.data as MyType
 \`\`\`
 
+### Secret injection via \`{{settings.xxx}}\` placeholders
+For API keys and tokens stored as \`secret: true\` fields in \`settingsSchema\`, use template placeholders in header values. The proxy resolves them server-side \u2014 **the real secret never enters extension code**.
+
+\`\`\`tsx
+const result = await capabilities.data.fetch('https://api.example.com/orders', {
+  method: 'GET',
+  headers: {
+    'X-API-Key': '{{settings.apiKey}}',
+    'Authorization': 'Bearer {{settings.token}}',
+  },
+})
+\`\`\`
+
+- Placeholders are only allowed in **header values** (not URLs, header names, or body)
+- For \`required: true\` secret fields, the proxy returns 400 if the value is not configured
+- For optional secret fields, the entire header is omitted if the value is not configured
+- Declare secret fields in your \`manifest.json\` \`settingsSchema\` with \`"secret": true\`
+
 ## context.read \u2014 Read Host Context
-Read host-provided context (customer ID, email, etc.).
+Read host-provided context (customer ID, email, extension settings, etc.).
 - **Permission required:** \`context:read\`
 - **Usage:** \`capabilities.context.read(): Promise<ContextData>\`
-- **ContextData shape:** \`{ customerId?: string, customerEmail?: string, [key: string]: unknown }\`
-- **Convenience hook:** \`useContextData()\` returns \`ContextData & { loading: boolean }\`
+- **ContextData shape:** \`{ customerId?: string, customerEmail?: string, 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
-// Preferred: use the hook
-const { loading, customerId, customerEmail } = useContextData()
+// Read all context (customer + settings)
+const { loading, customerId, customerEmail, settings } = useContextData()
+
+// Read only extension settings (convenience)
+const settings = useSettings()
+const apiBaseUrl = settings.baseUrl as string
 
 // Alternative: use the capability directly
 const context = await capabilities.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.
+
+- **Secret fields are never included** in context \u2014 use \`{{settings.xxx}}\` placeholders in \`data.fetch\` headers instead
+- Settings propagate on **page load** \u2014 changes made in the admin dashboard take effect on the next page reload, not mid-session
+- No new permission needed \u2014 \`context:read\` is the only gate
+
 ## actions.toast \u2014 Show Toast Notifications
 Display a toast notification in the host UI.
 - **Permission required:** \`actions:toast\`
@@ -977,9 +1008,16 @@ const viewState = useStore(appStore, (s) => s.viewState)
 \`\`\`
 
 ## useContextData()
-Reads host-provided context. Returns \`{ loading, customerId, customerEmail, ... }\`.
+Reads host-provided context including extension settings. Returns \`{ loading, customerId, customerEmail, settings, ... }\`.
+\`\`\`tsx
+const { loading, customerId, customerEmail, settings } = useContextData()
+\`\`\`
+
+## useSettings()
+Convenience hook for reading extension settings. Returns non-secret settings scoped to this extension on this instance.
 \`\`\`tsx
-const { loading, customerId, customerEmail } = useContextData()
+const settings = useSettings()
+const apiBaseUrl = settings.baseUrl as string
 \`\`\`
 
 ## useSurfaceContext()
@@ -3254,8 +3292,11 @@ const capabilities = useCapabilities()
 const response = await capabilities.data.fetch('https://api.example.com/endpoint')
 `,
   "context.read": `
-const capabilities = useCapabilities()
-const ctx = await capabilities.context.read()
+// Read host context + extension settings
+const { customerId, settings } = useContextData()
+
+// Or use the convenience hook for settings only
+const settings = useSettings()
 `,
   "actions.toast": `
 const capabilities = useCapabilities()

package/dist/server.js

@@ -461,8 +461,8 @@ const result = await capabilities.data.query<Customer>({
 })
 \`\`\`
 
-## data.fetch \u2014 Direct HTTP from Sandbox
-Extension makes HTTP requests directly. Domain must be in \`allowedDomains\` in manifest.
+## data.fetch \u2014 HTTP Requests to External APIs
+Make HTTP requests to external APIs. Domain must be in \`allowedDomains\` in manifest. Requests are proxied through the Stackable platform server.
 - **Permission required:** \`data:fetch\`
 - **Usage:** \`capabilities.data.fetch(url: string, init?: FetchRequestInit): Promise<FetchResponse>\`
 - **FetchRequestInit:** \`{ method?: 'GET'|'POST'|'PUT'|'PATCH'|'DELETE', headers?: Record<string,string>, body?: unknown }\`
@@ -478,21 +478,52 @@ if (!result.ok) throw new Error(\`Request failed: \${result.status}\`)
 const data = result.data as MyType
 \`\`\`
 
+### Secret injection via \`{{settings.xxx}}\` placeholders
+For API keys and tokens stored as \`secret: true\` fields in \`settingsSchema\`, use template placeholders in header values. The proxy resolves them server-side \u2014 **the real secret never enters extension code**.
+
+\`\`\`tsx
+const result = await capabilities.data.fetch('https://api.example.com/orders', {
+  method: 'GET',
+  headers: {
+    'X-API-Key': '{{settings.apiKey}}',
+    'Authorization': 'Bearer {{settings.token}}',
+  },
+})
+\`\`\`
+
+- Placeholders are only allowed in **header values** (not URLs, header names, or body)
+- For \`required: true\` secret fields, the proxy returns 400 if the value is not configured
+- For optional secret fields, the entire header is omitted if the value is not configured
+- Declare secret fields in your \`manifest.json\` \`settingsSchema\` with \`"secret": true\`
+
 ## context.read \u2014 Read Host Context
-Read host-provided context (customer ID, email, etc.).
+Read host-provided context (customer ID, email, extension settings, etc.).
 - **Permission required:** \`context:read\`
 - **Usage:** \`capabilities.context.read(): Promise<ContextData>\`
-- **ContextData shape:** \`{ customerId?: string, customerEmail?: string, [key: string]: unknown }\`
-- **Convenience hook:** \`useContextData()\` returns \`ContextData & { loading: boolean }\`
+- **ContextData shape:** \`{ customerId?: string, customerEmail?: string, 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
-// Preferred: use the hook
-const { loading, customerId, customerEmail } = useContextData()
+// Read all context (customer + settings)
+const { loading, customerId, customerEmail, settings } = useContextData()
+
+// Read only extension settings (convenience)
+const settings = useSettings()
+const apiBaseUrl = settings.baseUrl as string
 
 // Alternative: use the capability directly
 const context = await capabilities.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.
+
+- **Secret fields are never included** in context \u2014 use \`{{settings.xxx}}\` placeholders in \`data.fetch\` headers instead
+- Settings propagate on **page load** \u2014 changes made in the admin dashboard take effect on the next page reload, not mid-session
+- No new permission needed \u2014 \`context:read\` is the only gate
+
 ## actions.toast \u2014 Show Toast Notifications
 Display a toast notification in the host UI.
 - **Permission required:** \`actions:toast\`
@@ -975,9 +1006,16 @@ const viewState = useStore(appStore, (s) => s.viewState)
 \`\`\`
 
 ## useContextData()
-Reads host-provided context. Returns \`{ loading, customerId, customerEmail, ... }\`.
+Reads host-provided context including extension settings. Returns \`{ loading, customerId, customerEmail, settings, ... }\`.
+\`\`\`tsx
+const { loading, customerId, customerEmail, settings } = useContextData()
+\`\`\`
+
+## useSettings()
+Convenience hook for reading extension settings. Returns non-secret settings scoped to this extension on this instance.
 \`\`\`tsx
-const { loading, customerId, customerEmail } = useContextData()
+const settings = useSettings()
+const apiBaseUrl = settings.baseUrl as string
 \`\`\`
 
 ## useSurfaceContext()
@@ -3252,8 +3290,11 @@ const capabilities = useCapabilities()
 const response = await capabilities.data.fetch('https://api.example.com/endpoint')
 `,
   "context.read": `
-const capabilities = useCapabilities()
-const ctx = await capabilities.context.read()
+// Read host context + extension settings
+const { customerId, settings } = useContextData()
+
+// Or use the convenience hook for settings only
+const settings = useSettings()
 `,
   "actions.toast": `
 const capabilities = useCapabilities()

package/package.json

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