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

package/dist/index.js

@@ -43,12 +43,13 @@ export const appStore = createStore<AppState>({
   {
     path: "surfaces/Content.tsx",
     title: "Content Surface with Loading State",
-    code: `import { ui, useStore, useContextData, Surface } from '@stackable-labs/sdk-extension-react'
+    code: `import { ui, useStore, useContextData, useSettings, Surface } from '@stackable-labs/sdk-extension-react'
 import { appStore } from '../store'
 
 export function Content() {
   const viewState = useStore(appStore, (s) => s.viewState)
   const { loading } = useContextData()
+  const settings = useSettings() // Non-secret settings from settingsSchema
 
   if (loading) {
     return (
@@ -143,19 +144,33 @@ export function createApi(query: QueryFn) {
 }
 
 // \u2500\u2500 data.fetch wrapper \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+//
+// For API keys and secrets, use {{settings.xxx}} placeholders in headers.
+// The proxy resolves them server-side \u2014 the real secret never enters extension code.
+// Declare secret fields in manifest.json settingsSchema with "secret": true.
 
 const API_BASE_URL = import.meta.env.VITE_API_BASE_URL as string
 
 export function createFetchApi(fetch: FetchFn) {
   return {
     async getItems(): Promise<unknown[]> {
-      const result = await fetch(\`\${API_BASE_URL}/items\`, { method: 'GET' })
+      const result = await fetch(\`\${API_BASE_URL}/items\`, {
+        method: 'GET',
+        headers: {
+          'X-API-Key': '{{settings.apiKey}}',
+        },
+      })
       if (!result.ok) throw new Error(\`getItems failed: \${result.status}\`)
       return result.data as unknown[]
     },
 
     async getItem(itemId: string): Promise<unknown> {
-      const result = await fetch(\`\${API_BASE_URL}/items/\${itemId}\`, { method: 'GET' })
+      const result = await fetch(\`\${API_BASE_URL}/items/\${itemId}\`, {
+        method: 'GET',
+        headers: {
+          'X-API-Key': '{{settings.apiKey}}',
+        },
+      })
       if (!result.ok) throw new Error(\`getItem failed: \${result.status}\`)
       return result.data as unknown
     },
@@ -182,12 +197,13 @@ export const appStore = createStore<AppState>({
   {
     path: "surfaces/Content.tsx",
     title: "Current Content Surface",
-    code: `import { ui, useStore, useContextData, Surface } from '@stackable-labs/sdk-extension-react'
+    code: `import { ui, useStore, useContextData, useSettings, Surface } from '@stackable-labs/sdk-extension-react'
 import { appStore } from '../store'
 
 export function Content() {
   const viewState = useStore(appStore, (s) => s.viewState)
   const { loading } = useContextData()
+  const settings = useSettings() // Non-secret settings from settingsSchema
 
   if (loading) {
     return (
@@ -251,19 +267,33 @@ export function createApi(query: QueryFn) {
 }
 
 // \u2500\u2500 data.fetch wrapper \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+//
+// For API keys and secrets, use {{settings.xxx}} placeholders in headers.
+// The proxy resolves them server-side \u2014 the real secret never enters extension code.
+// Declare secret fields in manifest.json settingsSchema with "secret": true.
 
 const API_BASE_URL = import.meta.env.VITE_API_BASE_URL as string
 
 export function createFetchApi(fetch: FetchFn) {
   return {
     async getItems(): Promise<unknown[]> {
-      const result = await fetch(\`\${API_BASE_URL}/items\`, { method: 'GET' })
+      const result = await fetch(\`\${API_BASE_URL}/items\`, {
+        method: 'GET',
+        headers: {
+          'X-API-Key': '{{settings.apiKey}}',
+        },
+      })
       if (!result.ok) throw new Error(\`getItems failed: \${result.status}\`)
       return result.data as unknown[]
     },
 
     async getItem(itemId: string): Promise<unknown> {
-      const result = await fetch(\`\${API_BASE_URL}/items/\${itemId}\`, { method: 'GET' })
+      const result = await fetch(\`\${API_BASE_URL}/items/\${itemId}\`, {
+        method: 'GET',
+        headers: {
+          'X-API-Key': '{{settings.apiKey}}',
+        },
+      })
       if (!result.ok) throw new Error(\`getItem failed: \${result.status}\`)
       return result.data as unknown
     },
@@ -463,8 +493,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 +510,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 +1038,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 +3322,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()
@@ -3641,8 +3712,11 @@ var CAPABILITY_SNIPPETS2 = {
 const result = await capabilities.data.query({ path: '/your-endpoint', method: 'GET' })`,
   "data.fetch": `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()`,
+  "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()
 capabilities.actions.toast({ type: 'success', message: 'Done!' })`,
   "actions.invoke": `const capabilities = useCapabilities()

package/dist/server.js

@@ -41,12 +41,13 @@ export const appStore = createStore<AppState>({
   {
     path: "surfaces/Content.tsx",
     title: "Content Surface with Loading State",
-    code: `import { ui, useStore, useContextData, Surface } from '@stackable-labs/sdk-extension-react'
+    code: `import { ui, useStore, useContextData, useSettings, Surface } from '@stackable-labs/sdk-extension-react'
 import { appStore } from '../store'
 
 export function Content() {
   const viewState = useStore(appStore, (s) => s.viewState)
   const { loading } = useContextData()
+  const settings = useSettings() // Non-secret settings from settingsSchema
 
   if (loading) {
     return (
@@ -141,19 +142,33 @@ export function createApi(query: QueryFn) {
 }
 
 // \u2500\u2500 data.fetch wrapper \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+//
+// For API keys and secrets, use {{settings.xxx}} placeholders in headers.
+// The proxy resolves them server-side \u2014 the real secret never enters extension code.
+// Declare secret fields in manifest.json settingsSchema with "secret": true.
 
 const API_BASE_URL = import.meta.env.VITE_API_BASE_URL as string
 
 export function createFetchApi(fetch: FetchFn) {
   return {
     async getItems(): Promise<unknown[]> {
-      const result = await fetch(\`\${API_BASE_URL}/items\`, { method: 'GET' })
+      const result = await fetch(\`\${API_BASE_URL}/items\`, {
+        method: 'GET',
+        headers: {
+          'X-API-Key': '{{settings.apiKey}}',
+        },
+      })
       if (!result.ok) throw new Error(\`getItems failed: \${result.status}\`)
       return result.data as unknown[]
     },
 
     async getItem(itemId: string): Promise<unknown> {
-      const result = await fetch(\`\${API_BASE_URL}/items/\${itemId}\`, { method: 'GET' })
+      const result = await fetch(\`\${API_BASE_URL}/items/\${itemId}\`, {
+        method: 'GET',
+        headers: {
+          'X-API-Key': '{{settings.apiKey}}',
+        },
+      })
       if (!result.ok) throw new Error(\`getItem failed: \${result.status}\`)
       return result.data as unknown
     },
@@ -180,12 +195,13 @@ export const appStore = createStore<AppState>({
   {
     path: "surfaces/Content.tsx",
     title: "Current Content Surface",
-    code: `import { ui, useStore, useContextData, Surface } from '@stackable-labs/sdk-extension-react'
+    code: `import { ui, useStore, useContextData, useSettings, Surface } from '@stackable-labs/sdk-extension-react'
 import { appStore } from '../store'
 
 export function Content() {
   const viewState = useStore(appStore, (s) => s.viewState)
   const { loading } = useContextData()
+  const settings = useSettings() // Non-secret settings from settingsSchema
 
   if (loading) {
     return (
@@ -249,19 +265,33 @@ export function createApi(query: QueryFn) {
 }
 
 // \u2500\u2500 data.fetch wrapper \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+//
+// For API keys and secrets, use {{settings.xxx}} placeholders in headers.
+// The proxy resolves them server-side \u2014 the real secret never enters extension code.
+// Declare secret fields in manifest.json settingsSchema with "secret": true.
 
 const API_BASE_URL = import.meta.env.VITE_API_BASE_URL as string
 
 export function createFetchApi(fetch: FetchFn) {
   return {
     async getItems(): Promise<unknown[]> {
-      const result = await fetch(\`\${API_BASE_URL}/items\`, { method: 'GET' })
+      const result = await fetch(\`\${API_BASE_URL}/items\`, {
+        method: 'GET',
+        headers: {
+          'X-API-Key': '{{settings.apiKey}}',
+        },
+      })
       if (!result.ok) throw new Error(\`getItems failed: \${result.status}\`)
       return result.data as unknown[]
     },
 
     async getItem(itemId: string): Promise<unknown> {
-      const result = await fetch(\`\${API_BASE_URL}/items/\${itemId}\`, { method: 'GET' })
+      const result = await fetch(\`\${API_BASE_URL}/items/\${itemId}\`, {
+        method: 'GET',
+        headers: {
+          'X-API-Key': '{{settings.apiKey}}',
+        },
+      })
       if (!result.ok) throw new Error(\`getItem failed: \${result.status}\`)
       return result.data as unknown
     },
@@ -461,8 +491,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 +508,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 +1036,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 +3320,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()
@@ -3639,8 +3710,11 @@ var CAPABILITY_SNIPPETS2 = {
 const result = await capabilities.data.query({ path: '/your-endpoint', method: 'GET' })`,
   "data.fetch": `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()`,
+  "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()
 capabilities.actions.toast({ type: 'success', message: 'Done!' })`,
   "actions.invoke": `const capabilities = useCapabilities()

package/package.json

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