(\n \n )}\n renderInstalledIntegrations={() => No installed integrations
}\n renderIntegrationDetails={(id) => Details for {id}
}\n />\n)\n```\n\n---\n\n## API reference\n\n### `useIntegrationHub(options)`\n\nHook that fetches the integration catalog and bot state, and provides mutation functions.\n\n**Options:**\n\n| Param | Type | Description |\n|---|---|---|\n| `client` | `Client` | A configured `@botpress/client` instance |\n| `workspaceId` | `string` | Workspace ID |\n| `botId` | `string` | Bot ID |\n| `categoryResolver?` | `(integration) => string \\| null` | Override default category mapping |\n| `enabled?` | `boolean` | Disable fetching (default `true`) |\n\n**Returns:**\n\n| Field | Type | Description |\n|---|---|---|\n| `integrations` | `BotpressIntegrationHubItem[]` | All public + private integrations with `installed`/`enabled`/`hasUpdate` computed |\n| `installedIntegrations` | `BotpressIntegrationHubItem[]` | Only integrations installed on the bot |\n| `isLoading` | `boolean` | Initial load in progress |\n| `error` | `Error \\| null` | Fetch error |\n| `install(id)` | `(id: string) => Promise` | Install integration on the bot |\n| `uninstall(id)` | `(id: string) => Promise` | Remove integration from the bot |\n| `enable(id)` | `(id: string) => Promise` | Enable installed integration |\n| `disable(id)` | `(id: string) => Promise` | Disable installed integration |\n| `upgrade(id)` | `(id: string) => Promise` | Upgrade integration to latest version |\n| `refresh()` | `() => void` | Re-fetch all data |\n| `isInstalling` | `boolean` | Install mutation in progress |\n| `isUninstalling` | `boolean` | Uninstall mutation in progress |\n| `isEnabling` | `boolean` | Enable mutation in progress |\n| `isDisabling` | `boolean` | Disable mutation in progress |\n| `isUpgrading` | `boolean` | Upgrade mutation in progress |\n\n### `useIntegrationDetails(options)`\n\nHook that fetches a single integration's full definition, bot-installed state, and capabilities.\n\n**Options:**\n\n| Param | Type | Description |\n|---|---|---|\n| `client` | `Client` | A configured `@botpress/client` instance |\n| `workspaceId` | `string` | Workspace ID |\n| `botId` | `string` | Bot ID |\n| `integrationId` | `string \\| null` | Integration to load (null = disabled) |\n| `enabled?` | `boolean` | Disable fetching (default `true`) |\n\n**Returns:**\n\n| Field | Type | Description |\n|---|---|---|\n| `definition` | `Integration \\| null` | Full integration definition (actions, events, channels, config schema) |\n| `installedState` | `BotpressInstalledIntegration \\| null` | Bot's installed state (enabled, config, webhookUrl) or null if not installed |\n| `capabilities.actionCards` | `IntegrationCapabilityCardItem[]` | Action cards ready for `IntegrationCapabilitiesCards` |\n| `capabilities.eventCards` | `IntegrationCapabilityCardItem[]` | Event cards |\n| `capabilities.channelCards` | `IntegrationCapabilityCardItem[]` | Channel cards |\n| `connectionMethods` | `IntegrationConnectionMethodOption[]` | Available connection methods (OAuth, named configs, sandbox) |\n| `selectedConnectionMethod` | `string \\| null` | Currently active connection method |\n| `isLoading` | `boolean` | Fetch in progress |\n| `error` | `Error \\| null` | Fetch error |\n| `saveConfig(config)` | `(config: Record) => Promise` | Save integration configuration |\n| `toggleEnabled()` | `() => Promise` | Toggle enabled/disabled state |\n| `setConnectionMethod(method)` | `(method: string \\| null) => Promise` | Switch connection method |\n| `refresh()` | `() => void` | Re-fetch details |\n| `isSavingConfig` | `boolean` | Config save in progress |\n| `isTogglingEnabled` | `boolean` | Toggle mutation in progress |\n| `isSettingConnectionMethod` | `boolean` | Connection method mutation in progress |\n\n### `BotpressIntegrationHub` (composed screen)\n\nDrop-in component that wires `useIntegrationHub` + `useIntegrationDetails` + all UI components. Manages view/search/selection/tab state internally.\n\n**Required props:** `client`, `workspaceId`, `botId`\n\n**Optional overrides:**\n\n| Prop | Type | Description |\n|---|---|---|\n| `initialView` | `'hub' \\| 'installed'` | Starting view (default `'hub'`) |\n| `categories` | `IntegrationHubCategory[]` | Override default categories |\n| `bannerSlides` | `IntegrationHubBannerSlide[]` | Override promotional banner content |\n| `bannerIconUrl` | `string` | Banner image URL |\n| `filterMenuLabels` | `Partial` | Override filter menu text |\n| `categoryResolver` | `(integration) => string \\| null` | Custom category mapping |\n| `disableInstallation` | `boolean` | Hide install buttons |\n| `hasWriteAccess` | `boolean` | Disable mutation buttons when false |\n| `noResultsDocumentationLink` | `{ href, label? }` | Link shown in empty search results |\n| `oauthTemplateData` | `Record` | Extra payload merged into `client.runVrl` when generating OAuth authorization URLs. If `env` is omitted, the runtime infers `production` for `*.cloud` API URLs and `preview` otherwise. |\n\n**Render slots (for things the package cannot own):**\n\n| Slot | Props you receive | Purpose |\n|---|---|---|\n| `renderConfigurationForm` | `{ definition, installedState, selectedConnectionMethod, onSave, isSaving }` | Override the default Static ZUI configuration form renderer. |\n| `renderConnectionsContent` | `{ definition, installedState, connectionMethods, selectedConnectionMethod, onConnectionMethodChange }` | Override the default runtime connection UI (OAuth/manual flows). |\n| `renderDetailPanel` | `{ definition, selectedCard, onClose }` | Render the side panel when a capability card is selected (e.g. schema viewer). |\n\n**Callbacks:**\n\n| Callback | Type | When it fires |\n|---|---|---|\n| `onInstall` | `(integration) => void` | After successful install |\n| `onUninstall` | `(integration) => void` | After successful uninstall |\n| `onEnable` | `(integration) => void` | After successful enable |\n| `onDisable` | `(integration) => void` | After successful disable |\n| `onUpgrade` | `(integration) => void` | After successful upgrade |\n| `onError` | `(error: Error) => void` | On any mutation error |\n\n### Mapper functions\n\nPure functions (no React) exported from `@bpinternal/integration-hub/runtime`:\n\n| Function | Description |\n|---|---|\n| `toHubItem({ summary, installedByName, categoryResolver? })` | Convert a `@botpress/client` integration summary + bot state into an `IntegrationHubItem` |\n| `toInstalledItem({ installedIntegration, summary?, categoryResolver? })` | Convert a bot's installed integration entry into an `IntegrationHubItem` |\n| `toCapabilityCards(definition)` | Extract actions, events, and channels from a full integration definition into card arrays |\n| `toConnectionMethods(definition)` | Extract available connection methods (OAuth, named configs, sandbox) from a definition |\n| `getInstalledIntegrations(botIntegrations)` | Convert the raw `bot.integrations` map into a typed array |\n| `findInstalledIntegration({ installedIntegrations, integrationId, integrationName? })` | Find a specific installed integration by ID or name |\n| `filterAndSortIntegrations({ integrations, searchTerm, visibility?, verification?, sortMethod? })` | Filter and sort hub items by search, visibility, verification status, and sort method |\n| `resolveCategory(integration, categoryResolver?)` | Resolve an integration's category with optional custom resolver |\n| `isOfficialWorkspace(handle)` | Check if a workspace handle is the official Botpress workspace |\n| `dedupeById(items)` | Remove duplicate items by ID |\n\n---\n\n## What this package does NOT include\n\nThese are the consumer's responsibility:\n\n| Thing | Why | What to do |\n|---|---|---|\n| **Auth / session** | Every app handles auth differently | Create your own `@botpress/client` instance with your token and pass it to hooks |\n| **Custom OAuth UX** | The package includes a default OAuth flow, but app-specific redirects and UX can vary | Use `oauthTemplateData` or override with `renderConnectionsContent` / `IntegrationOAuthButton` |\n| **Custom config form behavior** | The package ships a Static ZUI default renderer, but apps may need custom controls/validation/UX | Provide `renderConfigurationForm` only when overriding the default |\n| **Routing / URL sync** | Too framework-specific (React Router, TanStack Router, Next.js) | Manage `selectedIntegrationId` and `view` state yourself and map to your router |\n| **Toast notifications** | Every app has its own toast system | Use `onInstall`, `onUninstall`, `onError` callbacks to trigger your toasts |\n| **Analytics / tracking** | App-specific telemetry | Use mutation callbacks (`onInstall`, `onUninstall`, `onEnable`, `onDisable`, `onUpgrade`) and your own UI-level tracking hooks |\n| **Feature flags** | App-specific gating | Pass `disableInstallation` or `hasWriteAccess` booleans |\n\n---\n\n## Customizing defaults\n\nThe package ships with generic defaults. Override them for your product:\n\n- `bannerSlides` — promotional banner content (pass your own slides or an empty array to hide)\n- `categories` — integration categories with icons (defaults to 13 common categories)\n- `filterMenuLabels` — deep-merge with defaults to change labels like `{ verification: { official: 'Made by Botpress' } }`\n- `noResultsDocumentationLink` — link shown when search has no results\n- `formatGithubLabel` on `IntegrationSetupMetadataBar` — custom GitHub URL display formatting\n- `categoryResolver` — function to override how integrations are assigned to categories\n\n---\n\n## UI components\n\nAll exported from `@bpinternal/integration-hub`:\n\n| Component | Purpose |\n|---|---|\n| `IntegrationHubBody` | Full hub page: category sidebar, search, banner carousel, responsive card grid, installed list, detail pane routing |\n| `IntegrationHubFilterMenu` | Dropdown filter menu (visibility, verification, sort) with active filter pills |\n| `IntegrationGridCard` | Integration card with icon, name, description, author, badges |\n| `IntegrationInstalledList` | Sorted/filtered list of installed integrations with enabled/disabled status |\n| `IntegrationDetailsLayout` | Detail page shell: back button, header, Install/Uninstall/Enable/Disable/Upgrade buttons, side panel slot |\n| `IntegrationSetupWizardLayout` | Setup wizard: \"setup mode\" numbered steps and \"configured mode\" tabs |\n| `IntegrationSetupMetadataBar` | Version, GitHub link, About button row |\n| `IntegrationConnectionMethodSelector` | Dropdown to pick connection method (OAuth, named config, sandbox) |\n| `IntegrationWebhookUrlField` | Read-only webhook URL with copy button and tooltip |\n| `IntegrationConfigurationSection` | Configuration wrapper with title, webhook field, blocked state, and children slot |\n| `IntegrationCapabilitiesCards` | Action/event/channel capability card grid with selection state |\n\n---\n\n## Styling requirements\n\n### 1. Import package CSS\n\nThe package ships precompiled component styles in `theme.css`. Import it once in your app entrypoint:\n\n```ts\nimport '@bpinternal/integration-hub/theme.css'\n```\n\nYou do not need to add `@bpinternal/integration-hub` to Tailwind content globs for runtime styles.\nTailwind scanning of package source is only useful when developing against unpublished local source.\n\n### 2. CSS custom properties\n\nComponents use Radix-style color tokens. Either use `@radix-ui/themes` or define these variables:\n\n```css\n:root {\n --gray-1: #ffffff;\n --gray-2: #f8f9fa;\n --gray-3: #f1f3f5;\n --gray-5: #e1e5ea;\n --gray-6: #d0d7de;\n --gray-7: #bfc8d3;\n --gray-8: #9aa4b2;\n --gray-9: #7a8594;\n --gray-10: #6b7280;\n --gray-11: #4b5563;\n --gray-12: #111827;\n\n --gray-a2: rgba(17, 24, 39, 0.04);\n --gray-a3: rgba(17, 24, 39, 0.07);\n --gray-a4: rgba(17, 24, 39, 0.1);\n --gray-a5: rgba(17, 24, 39, 0.14);\n --gray-a6: rgba(17, 24, 39, 0.2);\n --gray-a8: rgba(17, 24, 39, 0.4);\n\n --blue-a2: rgba(37, 99, 235, 0.12);\n --blue-8: #3b82f6;\n --blue-11: #1d4ed8;\n\n --grass-3: #ecfdf3;\n --grass-5: #a7f3d0;\n --grass-10: #16a34a;\n\n --accent-9: #0ea5e9;\n --accent-11: #0284c7;\n}\n```\n\n### 3. Container queries\n\n`IntegrationHubBody` uses native CSS container queries for responsive grids.\nIf you rebuild package styles from source in a Tailwind v3 app, add:\n\n```js\nimport containerQueries from '@tailwindcss/container-queries'\nexport default { plugins: [containerQueries] }\n```\n\n---\n\n## Build\n\n```bash\npnpm --filter @bpinternal/integration-hub build\npnpm --filter @bpinternal/integration-hub type-check\n```\n\n## Publish\n\n```bash\npnpm --filter @bpinternal/integration-hub exec npm version patch\npnpm --filter @bpinternal/integration-hub exec npm publish --access public\n```\n\n`prepack` runs `clean && build` automatically before publish.\n\n**Note:** Depending on options passed to the botpress client (x-multiple-integrations = true), the integrations from Botpress Cloud are keyed by their ALIAS, not their ID. For edits that intend to use the integration ID, make sure to explicitly use the .id parameter.","readmeFilename":"README.md"}