From 80ca82dbb2965172eafec349e8b86290ba3035ed Mon Sep 17 00:00:00 2001 From: "Builder.io" Date: Tue, 14 Oct 2025 01:45:39 +0000 Subject: [PATCH] Rewrite integrations documentation cgen-f8836ef5cc4e42d9bfc7677ccb1cc314 --- client/pages/docs/DocsIntegrations.tsx | 117 ++++++++++++------------- 1 file changed, 56 insertions(+), 61 deletions(-) diff --git a/client/pages/docs/DocsIntegrations.tsx b/client/pages/docs/DocsIntegrations.tsx index d2c2f9d4..da347260 100644 --- a/client/pages/docs/DocsIntegrations.tsx +++ b/client/pages/docs/DocsIntegrations.tsx @@ -30,54 +30,54 @@ import { FileText, } from "lucide-react"; -const embedSettings = [ +const connectorFields = [ { - name: "buttonSize", - description: "Controls the floating launcher dimensions in pixels.", - defaultValue: "60", + name: "key", + description: "Unique identifier referenced across dashboards, APIs, and audit logs.", + defaultValue: '"analytics-segment"', }, { - name: "buttonPosition", - description: "Places the launcher in one of four corners (e.g. bottom-right).", - defaultValue: "bottom-right", + name: "category", + description: "Integration taxonomy aligned with AeThex surfaces (analytics, identity, commerce, ops).", + defaultValue: '"analytics"', }, { - name: "buttonOffset", - description: "Fine-tunes horizontal/vertical offsets from the viewport edge.", - defaultValue: "{ x: 32, y: 32 }", + name: "capabilities", + description: "Feature flags that unlock widgets, automation hooks, and data pipelines.", + defaultValue: "['metrics', 'webhooks']", }, { - name: "iframeWidth", - description: "Maximum width of the opened assistant panel.", - defaultValue: "448", + name: "connectionMode", + description: "Determines how credentials are managed (oauth, apiKey, managedVault).", + defaultValue: '"oauth"', }, { - name: "iframeHeight", - description: "Viewport height percentage for the assistant panel.", - defaultValue: "85vh", + name: "webhookEndpoint", + description: "Optional callback URL for outbound events delivered by AeThex.", + defaultValue: '"https://app.example.com/aethex/webhooks"', }, { - name: "tooltipText", - description: "Copy shown when hovering the launcher button.", - defaultValue: "Need a hand?\\nAeThex Copilot is live.", + name: "uiEmbeds", + description: "Declarative config describing dashboard cards, modals, or launchers this integration renders.", + defaultValue: "[{ surface: 'dashboard', placement: 'sidebar' }]", }, ]; const troubleshooting = [ { - title: "Failed to fetch status", + title: "OAuth handshake fails", detail: - "If the HelloSkip API cannot be reached, the embed skips initialization. Verify outbound network access or retry when the environment regains connectivity.", + "Confirm the integration's redirect URI matches the value registered in the partner console. AeThex surfaces expose the required callback under Settings → Integrations.", }, { - title: "Agent inactive", + title: "Webhook retries exhausted", detail: - "Status responses containing `active: false` mean the agent is disabled. Update the agent inside HelloSkip or switch the data-agent-id.", + "Inspect delivery attempts in the Integrations dashboard. Update retry policies or verify your endpoint responds with a 2xx status within 10 seconds.", }, { - title: "Styling conflicts", + title: "Embedded widget styling", detail: - "AeThex injects a dedicated theme stylesheet. Ensure no additional overrides remove the `.skip-agent-*` classes or the gradient tokens defined in `global.css`.", + "Override component tokens through the integration theme utilities or wrap the widget in a container that inherits AeThex gradient variables.", }, ]; @@ -89,12 +89,11 @@ export default function DocsIntegrations() { Integrations -

Embedding partner services in AeThex

+

Connecting partner services to AeThex

- AeThex supports secure, theme-aware embeds for third-party agents and tools. This guide covers the - HelloSkip support assistant that ships with the platform and outlines patterns you can reuse for future - integrations. The router-aware SkipAgentController keeps the - experience out of the documentation space while still making it available across the rest of the site. + AeThex Integrations wrap third-party analytics, identity, payments, and live-ops tooling behind a consistent + runtime, security model, and visual system. Use this guide to register new connectors, surface partner UI in + product flows, and automate data exchange without hand-rolled plumbing.

@@ -108,15 +107,14 @@ export default function DocsIntegrations() {

- The HelloSkip agent utilities live in lib/skip-agent.ts. They lazily fetch the - runtime once and gate initialization behind a guarded status check at - /api/agent/status. If the endpoint is unreachable or reports an inactive agent, - the embed is skipped to avoid client-side errors. + Integration manifests are stored in the AeThex Integrations service and synced across the dashboard and + runtime. Client components resolve connector metadata through the shared API helpers, ensuring credentials + and capability flags stay consistent with server state.

- When healthy, the loader injects HelloSkip's global object and calls - window.SkipAgent.embed with AeThex-specific sizing, copy, and z-index values. - A companion stylesheet applies the gradient, border, and focus treatments to match the site aesthetic. + During hydration the runtime mounts partner SDKs behind AeThex loaders, applying sandboxed execution where + required. Use lifecycle hooks to emit analytics, hydrate widgets with scoped credentials, and gate access + through the same role-based policies used elsewhere in the platform.

@@ -130,14 +128,13 @@ export default function DocsIntegrations() {

- AeThex provides a handcrafted theme in SKIP_AGENT_THEME. It uses the gradient - palette defined in global.css to restyle the floating launcher, tooltip, and - assistant container. + Use the integration theming utilities to adapt partner widgets to AeThex gradients, typography, and focus + states. Tokens flow through CSS variables defined in global.css, so embeds stay + visually aligned with dashboards and consumer apps.

- Add additional overrides by extending the same template literal and keeping selectors scoped to - .skip-agent-*. The embed only injects the style block once via the - createSkipAgentTheme helper. + Extend styling with scoped class names or CSS variables exported by the partner SDK. When shipping multiple + widgets, prefer design tokens over hard-coded overrides to keep dark-mode and accessibility tweaks in sync.

@@ -159,17 +156,16 @@ export default function DocsIntegrations() { - {embedSettings.map((setting) => ( - - {setting.name} - {setting.description} - {setting.defaultValue} + {connectorFields.map((field) => ( + + {field.name} + {field.description} + {field.defaultValue} ))} - Update values inside SKIP_AGENT_EMBED_OPTIONS in - client/lib/skip-agent.ts. + Manage manifests in the Integrations dashboard or via the Admin API to keep environments in sync. @@ -186,10 +182,9 @@ export default function DocsIntegrations() {
    -
  • Keep the preflight status check in place for stability in staging or offline previews.
    • -
  • Reuse the router gating pattern in SkipAgentController for embeds that should - disappear on specific routes.
    • -
  • Wrap additional embeds in the same helper to maintain a single initialization flag.
    • +
  • Store credentials in AeThex-managed vaults and rotate them from the dashboard rather than hard-coding.
    • +
  • Limit embed rendering to audiences that have access to the underlying data to avoid leaking partner UI.
    • +
  • Log integration events through the shared telemetry helpers so support can trace partner-side failures.
 @@ -198,17 +193,17 @@ export default function DocsIntegrations() { - Updating the agent + Lifecycle management

- To switch agents, update SKIP_AGENT_ID. If the HelloSkip host changes, - adjust SKIP_AGENT_SRC—the origin is derived automatically for status checks. + Promote integration changes through staging first. AeThex snapshots connector manifests per environment so + you can test credentials, capability flags, and UI placements without impacting production users.

- For full replacements, swap the fetch target to your new integration and continue calling the same - embedSkipAgent helper to retain theme and lifecycle management. + When partners publish SDK updates, pin versions in your manifest, document the change log, and coordinate + rollout windows with stakeholders subscribing to the integration.

@@ -240,8 +235,8 @@ export default function DocsIntegrations() {

Further reading

- Manage integration documentation centrally in Builder CMS or export static knowledge base pages. Use the - same theming primitives to embed other providers consistently across the platform. + Manage integration documentation centrally in Builder CMS or export static guides for partner teams. Keep + manifests, onboarding playbooks, and support runbooks together so each connector has a clear owner.