diff --git a/client/pages/docs/DocsIntegrations.tsx b/client/pages/docs/DocsIntegrations.tsx new file mode 100644 index 00000000..08b52bec --- /dev/null +++ b/client/pages/docs/DocsIntegrations.tsx @@ -0,0 +1,263 @@ +import { Link } from "react-router-dom"; +import { + Card, + CardContent, + CardDescription, + CardHeader, + CardTitle, +} from "@/components/ui/card"; +import { Badge } from "@/components/ui/badge"; +import { + Table, + TableBody, + TableCell, + TableHead, + TableHeader, + TableRow, + TableCaption, +} from "@/components/ui/table"; +import { Button } from "@/components/ui/button"; +import { + Puzzle, + Server, + Brush, + Shield, + RefreshCw, + ArrowRight, + Link as LinkIcon, + Palette, + AlertTriangle, + FileText, +} from "lucide-react"; + +const embedSettings = [ + { + name: "buttonSize", + description: "Controls the floating launcher dimensions in pixels.", + defaultValue: "60", + }, + { + name: "buttonPosition", + description: "Places the launcher in one of four corners (e.g. bottom-right).", + defaultValue: "bottom-right", + }, + { + name: "buttonOffset", + description: "Fine-tunes horizontal/vertical offsets from the viewport edge.", + defaultValue: "{ x: 32, y: 32 }", + }, + { + name: "iframeWidth", + description: "Maximum width of the opened assistant panel.", + defaultValue: "448", + }, + { + name: "iframeHeight", + description: "Viewport height percentage for the assistant panel.", + defaultValue: "85vh", + }, + { + name: "tooltipText", + description: "Copy shown when hovering the launcher button.", + defaultValue: "Need a hand?\\nAeThex Copilot is live.", + }, +]; + +const troubleshooting = [ + { + title: "Failed to fetch status", + detail: + "If the HelloSkip API cannot be reached, the embed skips initialization. Verify outbound network access or retry when the environment regains connectivity.", + }, + { + title: "Agent inactive", + detail: + "Status responses containing `active: false` mean the agent is disabled. Update the agent inside HelloSkip or switch the data-agent-id.", + }, + { + title: "Styling conflicts", + detail: + "AeThex injects a dedicated theme stylesheet. Ensure no additional overrides remove the `.skip-agent-*` classes or the gradient tokens defined in `global.css`.", + }, +]; + +export default function DocsIntegrations() { + return ( +
+
+ + + Integrations + +

Embedding partner services in 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. +

+
+ +
+ + + + + Runtime flow + + + +

+ The HelloSkip agent is lazily loaded at runtime from main.tsx using a + guarded fetch. Before executing the external runtime, AeThex performs a status preflight against + /api/agent/status. If the agent is unavailable, initialization is skipped to + prevent console noise. +

+

+ On success, the script injects HelloSkip's global object and immediately 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. +

+ + + + + + + + Theming hook + + + +

+ 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. +

+

+ 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. +

+ + +
+ +
+
+ +

Configuration options

+
+ + + + + + Property + Purpose + Default + + + + {embedSettings.map((setting) => ( + + {setting.name} + {setting.description} + {setting.defaultValue} + + ))} + + + Update values inside SKIP_AGENT_EMBED_OPTIONS in + client/main.tsx. + +
+ + +
+ +
+ + + + + Best practices + + + +
    +
  • Keep the preflight status check in place for stability in staging or offline previews.
    • +
  • Regenerate the blob URL after each successful load to avoid memory leaks.
    • +
  • Wrap additional embeds in the same helper to maintain a single initialization flag.
    • +
+ + + + + + + + Updating the agent + + + +

+ To switch agents, update SKIP_AGENT_ID. If the HelloSkip host changes, + adjust SKIP_AGENT_SRC—the origin is derived automatically for status checks. +

+

+ For full replacements, swap the fetch target to your new integration and continue calling the same + embedSkipAgent helper to retain theme and lifecycle management. +

+ + +
+ +
+
+ +

Troubleshooting

+
+
+ {troubleshooting.map((issue) => ( + + + {issue.title} + + + + {issue.detail} + + + + ))} +
+
+ +
+
+
+

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. +

+
+
+ + +
+
+
+
+ ); +}