@12-apps/mcp 1.0.0 → 1.3.0

package/src/react/ai-landing.tsx

@@ -0,0 +1,125 @@
+"use client";
+
+import BoltOutlinedIcon from "@mui/icons-material/BoltOutlined";
+import LanguageOutlinedIcon from "@mui/icons-material/LanguageOutlined";
+import LockOpenOutlinedIcon from "@mui/icons-material/LockOpenOutlined";
+import VerifiedUserOutlinedIcon from "@mui/icons-material/VerifiedUserOutlined";
+
+import { Button } from "@12-apps/ui/form/Button";
+import { Box } from "@12-apps/ui/mui/Box";
+import { Stack } from "@12-apps/ui/mui/Stack";
+import { Text } from "@12-apps/ui/typography/Text";
+
+import { AI_CAPABILITIES, AI_PERMISSION_MODEL, type AiCapability } from "../guide";
+import { AiCapabilities } from "./ai-capabilities";
+import { FeatureBadge, type FeatureBadgeItem } from "./feature-badge";
+
+const FEATURES: FeatureBadgeItem[] = [
+  { icon: <LockOpenOutlinedIcon />, label: "Usa o seu próprio login", caption: "Sem chaves ou credenciais extras" },
+  { icon: <BoltOutlinedIcon />, label: "Sem instalar nada", caption: "Conecta em poucos minutos" },
+  { icon: <VerifiedUserOutlinedIcon />, label: "Só o que você pode", caption: "As suas permissões, nada além" },
+  { icon: <LanguageOutlinedIcon />, label: "Navegador ou app", caption: "Claude, ChatGPT, Codex" },
+];
+
+/** The single-column marketing hero: eyebrow + headline + description + CTA. */
+function Hero({ onStart }: { onStart: () => void }): React.JSX.Element {
+  return (
+    <Stack spacing={2.5} sx={{ maxWidth: 680 }}>
+      <Box
+        sx={{
+          color: "primary.main",
+          fontSize: 12,
+          fontWeight: 700,
+          letterSpacing: 1.2,
+          textTransform: "uppercase",
+        }}
+      >
+        Integração com IA
+      </Box>
+      <Text variant="heading" size="xl" weight="bold" as="h1">
+        Conecte{" "}
+        <Box component="span" sx={{ color: "primary.main" }}>
+          assistentes de IA
+        </Box>{" "}
+        à sua loja
+      </Text>
+      <Text variant="body" color="secondary" as="p">
+        Deixe o Claude, o ChatGPT e outros assistentes responderem sobre o seu cardápio, estoque e
+        pedidos — e executarem ações por você, direto na conversa. Com segurança e sem instalar
+        nada.
+      </Text>
+      <Box sx={{ pt: 1 }}>
+        <Button onClick={onStart} data-testid="ai-landing-start">
+          Ver como conectar
+        </Button>
+      </Box>
+    </Stack>
+  );
+}
+
+/**
+ * Homepage-style marketing landing for the AI integration (shown before the
+ * owner starts): a hero, the permission reassurance, a trust/feature strip, and
+ * the capability highlights. `onStart` begins the guided flow. `permissionModel`
+ * and `capabilities` default to the shared copy; apps can override.
+ */
+export function AiLanding({
+  onStart,
+  permissionModel = AI_PERMISSION_MODEL,
+  capabilities = AI_CAPABILITIES,
+}: {
+  onStart: () => void;
+  permissionModel?: string;
+  capabilities?: readonly AiCapability[];
+}): React.JSX.Element {
+  return (
+    <Stack spacing={6} data-testid="ai-landing">
+      <Hero onStart={onStart} />
+
+      <Stack
+        direction="row"
+        spacing={1.5}
+        alignItems="flex-start"
+        data-testid="ai-permission-callout"
+        sx={{
+          p: 2,
+          borderRadius: 2,
+          bgcolor: "action.hover",
+          border: 1,
+          borderColor: "divider",
+        }}
+      >
+        <VerifiedUserOutlinedIcon sx={{ color: "success.main", mt: 0.25 }} />
+        <Text variant="body" as="p">
+          {permissionModel}
+        </Text>
+      </Stack>
+
+      <Box
+        sx={{
+          p: { xs: 2.5, md: 3 },
+          borderRadius: 3,
+          bgcolor: "action.hover",
+          border: 1,
+          borderColor: "divider",
+        }}
+      >
+        <Box
+          sx={{
+            display: "grid",
+            gap: 3,
+            gridTemplateColumns: { xs: "1fr", sm: "1fr 1fr", md: "repeat(4, 1fr)" },
+          }}
+        >
+          {FEATURES.map((f) => (
+            <FeatureBadge key={f.label} icon={f.icon} label={f.label} caption={f.caption} />
+          ))}
+        </Box>
+      </Box>
+
+      <Box>
+        <AiCapabilities capabilities={capabilities} />
+      </Box>
+    </Stack>
+  );
+}

package/src/react/ai-onboarding.tsx

@@ -0,0 +1,147 @@
+"use client";
+
+import {
+  GuidedSection,
+  OnboardingProvider,
+  useOnboarding,
+  type OnboardingStateSnapshot,
+  type OnboardingStore,
+} from "@12-apps/onboarding";
+
+import {
+  AI_CAPABILITIES,
+  AI_CONNECT_PROMPT,
+  AI_HOST_GUIDES,
+  AI_PERMISSION_MODEL,
+  type AiCapability,
+  type AiHostGuide,
+} from "../guide";
+import { AiLanding } from "./ai-landing";
+import {
+  buildFlowSteps,
+  connectedSummary,
+  connectedTitle,
+  StatusBoard,
+  type AiConnection,
+} from "./ai-steps";
+
+export type { AiConnection } from "./ai-steps";
+
+const DEFAULT_FEATURE_KEY = "ai_integration";
+
+/** Props for the reusable AI-connect onboarding flow. */
+export interface AiIntegrationOnboardingProps {
+  /** Persistence seam — the app wires this to its own backend (server actions). */
+  store: OnboardingStore;
+  /** The MCP endpoint URL to paste (derived by the app from its public origin). */
+  endpointUrl: string;
+  /** The owner's saved progress (null → first run / landing). */
+  initialState: OnboardingStateSnapshot | null;
+  /** The live MCP connections (one per connected assistant; empty when none). */
+  connections: readonly AiConnection[];
+  /** Onboarding feature key (persistence namespace). @default "ai_integration" */
+  featureKey?: string;
+  /** Show the dev-only "reset onboarding" button. @default false */
+  devReset?: boolean;
+  /** Assistants offered in the flow. @default the shared AI_HOST_GUIDES */
+  hosts?: readonly AiHostGuide[];
+  /** Capability cards on the landing. @default the shared AI_CAPABILITIES */
+  capabilities?: readonly AiCapability[];
+  /** Permission reassurance copy on the landing. @default AI_PERMISSION_MODEL */
+  permissionModel?: string;
+  /** Message pasted into the assistant on the Conectar step. @default AI_CONNECT_PROMPT */
+  connectPrompt?: string;
+  /**
+   * Re-check the live connection on the verify step's "Testar conexão" button —
+   * apps pass a router refresh (e.g. Next's `router.refresh`). @default a full
+   * `window.location.reload()`.
+   */
+  onRetest?: () => void;
+}
+
+/** Resolved (defaults-applied) props threaded to the in-provider flow body. */
+interface FlowProps {
+  endpointUrl: string;
+  connections: readonly AiConnection[];
+  hosts: readonly AiHostGuide[];
+  capabilities: readonly AiCapability[];
+  permissionModel: string;
+  connectPrompt: string;
+  onRetest: () => void;
+  devReset: boolean;
+}
+
+/**
+ * The flow body — inside the OnboardingProvider so it can read the selected host
+ * and pick the path. A host with a published `pluginUrl` gets the simplified
+ * Escolher → Instalar → Confirmar flow (no URL to copy); otherwise the full
+ * Escolher → Copiar URL → Configurar → Conectar → Confirmar flow.
+ */
+function AiOnboardingFlow(props: FlowProps): React.JSX.Element {
+  const { endpointUrl, connections, hosts, capabilities, permissionModel, connectPrompt, onRetest, devReset } =
+    props;
+  const { state } = useOnboarding();
+  const selectedHost = hosts.find((h) => h.id === state.data.selectedHost) ?? hosts[0]!;
+
+  const steps = buildFlowSteps({ host: selectedHost, hosts, endpointUrl, connectPrompt, connections, onRetest });
+  const connectedHostId = (state.data.connectedHost ?? state.data.selectedHost) as string | undefined;
+
+  return (
+    <GuidedSection
+      steps={steps}
+      title="Conecte assistentes de IA à sua loja"
+      startLabel="Ver como conectar"
+      renderLanding={(start) => (
+        <AiLanding onStart={start} permissionModel={permissionModel} capabilities={capabilities} />
+      )}
+      configuredTitle={connectedTitle(connections, hosts, connectedHostId)}
+      configuredSummary={connectedSummary(connections)}
+      editLabel="Conectar IA"
+      completedContent={(nav) => <StatusBoard nav={nav} connections={connections} hosts={hosts} />}
+      devReset={devReset}
+      dataTestId="ai-onboarding"
+    />
+  );
+}
+
+/**
+ * URL-free, persisted onboarding for the AI/MCP integration — a five-step wizard
+ * (pick an assistant, copy the store URL, configure the connector, connect, then
+ * verify) whose position + chosen assistant are saved via `@12-apps/onboarding`, so
+ * a refresh resumes exactly where the owner left off. The live MCP connection
+ * signal drives the verify step and the completed status board.
+ *
+ * App-agnostic: the app supplies the persistence `store`, the `endpointUrl`, and
+ * the live `connections` (one per connected assistant); content (hosts,
+ * capabilities, copy) defaults to the shared guide but can be overridden per app.
+ */
+export function AiIntegrationOnboarding({
+  store,
+  endpointUrl,
+  initialState,
+  connections,
+  featureKey = DEFAULT_FEATURE_KEY,
+  devReset = false,
+  hosts = AI_HOST_GUIDES,
+  capabilities = AI_CAPABILITIES,
+  permissionModel = AI_PERMISSION_MODEL,
+  connectPrompt = AI_CONNECT_PROMPT,
+  onRetest = () => {
+    if (typeof window !== "undefined") window.location.reload();
+  },
+}: AiIntegrationOnboardingProps): React.JSX.Element {
+  return (
+    <OnboardingProvider featureKey={featureKey} store={store} initialState={initialState}>
+      <AiOnboardingFlow
+        endpointUrl={endpointUrl}
+        connections={connections}
+        hosts={hosts}
+        capabilities={capabilities}
+        permissionModel={permissionModel}
+        connectPrompt={connectPrompt}
+        onRetest={onRetest}
+        devReset={devReset}
+      />
+    </OnboardingProvider>
+  );
+}

package/src/react/ai-status-board.tsx

@@ -0,0 +1,124 @@
+"use client";
+
+import AddLinkOutlinedIcon from "@mui/icons-material/AddLinkOutlined";
+import CheckCircleIcon from "@mui/icons-material/CheckCircle";
+
+import { Button } from "@12-apps/ui/form/Button";
+import { Box } from "@12-apps/ui/mui/Box";
+import { Stack } from "@12-apps/ui/mui/Stack";
+import { Text } from "@12-apps/ui/typography/Text";
+
+import type { AiHostGuide } from "../guide";
+import { HostBrandAvatar } from "./ai-icons";
+
+/** One assistant's connection state. */
+export interface HostStatus {
+  host: AiHostGuide;
+  connected: boolean;
+  /** Freeform activity line for a connected host (e.g. "ativo há 3 min"). */
+  detail?: string;
+}
+
+/** A single green (connected) / red (to connect) status box for one assistant. */
+function StatusBox({
+  status,
+  onConnect,
+}: {
+  status: HostStatus;
+  onConnect: (hostId: string) => void;
+}): React.JSX.Element {
+  const { host, connected, detail } = status;
+  return (
+    <Box
+      data-testid={`ai-status-${host.id}`}
+      data-connected={connected}
+      sx={{
+        display: "flex",
+        alignItems: "center",
+        gap: 1.5,
+        p: 2,
+        borderRadius: 3,
+        border: 1,
+        borderColor: connected ? "success.main" : "error.main",
+        bgcolor: "background.paper",
+      }}
+    >
+      <HostBrandAvatar brand={host.brand} size={36} />
+      <Box sx={{ minWidth: 0, flexGrow: 1 }}>
+        <Stack direction="row" spacing={0.75} alignItems="center">
+          <Text variant="body" weight="bold" as="span">
+            {host.label}
+          </Text>
+          {connected ? <CheckCircleIcon sx={{ fontSize: 18, color: "success.main" }} /> : null}
+        </Stack>
+        <Text variant="caption" as="p" color="secondary">
+          {connected ? (detail ?? "Conectado") : "Ainda não conectado"}
+        </Text>
+      </Box>
+      {connected ? (
+        <Box
+          sx={{
+            px: 1,
+            py: 0.25,
+            borderRadius: 999,
+            bgcolor: "success.main",
+            color: "success.contrastText",
+          }}
+        >
+          <Text variant="caption" weight="bold" as="span">
+            Conectado
+          </Text>
+        </Box>
+      ) : (
+        <Button
+          variant="outline"
+          size="sm"
+          onClick={() => onConnect(host.id)}
+          data-testid={`ai-status-connect-${host.id}`}
+        >
+          <AddLinkOutlinedIcon sx={{ fontSize: 16, mr: 0.5 }} />
+          Conectar
+        </Button>
+      )}
+    </Box>
+  );
+}
+
+/**
+ * The completed-state status board for the AI integration: every assistant as a
+ * box — green when connected, red when still to connect (with a "Conectar"
+ * button that re-enters the guided flow for that host). Each connection is
+ * attributed to its provider (derived from the OAuth client + confirmed by
+ * `announceAiConnection`), so several assistants can show connected at once.
+ */
+export function AiStatusBoard({
+  statuses,
+  onConnect,
+}: {
+  statuses: readonly HostStatus[];
+  onConnect: (hostId: string) => void;
+}): React.JSX.Element {
+  return (
+    <Stack spacing={2} data-testid="ai-status-board">
+      <Box>
+        <Text variant="heading" size="sm" as="h2">
+          Assistentes conectados
+        </Text>
+        <Text variant="caption" as="p" color="secondary">
+          Em verde os que já operam a sua loja; em vermelho os que faltam conectar.
+        </Text>
+      </Box>
+      <Box
+        sx={{
+          display: "grid",
+          gap: 2,
+          gridTemplateColumns: { xs: "1fr", sm: "1fr 1fr" },
+        }}
+      >
+        {statuses.map((status) => (
+          <StatusBox key={status.host.id} status={status} onConnect={onConnect} />
+        ))}
+      </Box>
+    </Stack>
+  );
+}

package/src/react/ai-steps.tsx

@@ -0,0 +1,167 @@
+"use client";
+
+import { type GuidedNav, type GuidedStep } from "@12-apps/onboarding";
+
+import { providerForHostId, type AiHostGuide } from "../guide";
+import { activeAgo, resolveHost, type AiConnection } from "./ai-connection-utils";
+import {
+  ConfigureStageStep,
+  ConfigureStep,
+  ConfirmStep,
+  ConnectStep,
+  CopyUrlStep,
+  InstallStep,
+} from "./ai-flow-steps";
+import { AiStatusBoard, type HostStatus } from "./ai-status-board";
+import { HostSelectStep } from "./host-select-step";
+
+export type { AiConnection } from "./ai-connection-utils";
+export { connectedSummary, connectedTitle } from "./ai-connection-utils";
+
+/** The completed status board: green for each connected host, red for the rest. */
+export function StatusBoard({
+  nav,
+  connections,
+  hosts,
+}: {
+  nav: GuidedNav;
+  connections: readonly AiConnection[];
+  hosts: readonly AiHostGuide[];
+}): React.JSX.Element {
+  const legacyHostId = (nav.data.connectedHost ?? nav.data.selectedHost) as string | undefined;
+
+  const statuses: HostStatus[] = hosts.map((host) => {
+    const provider = providerForHostId(host.id);
+    // Prefer a provider-attributed connection; fall back to a legacy null-host
+    // connection only for the host the owner completed the flow with.
+    const connection =
+      (provider ? connections.find((c) => c.host === provider) : undefined) ??
+      (host.id === legacyHostId ? connections.find((c) => c.host === null) : undefined) ??
+      null;
+    return {
+      host,
+      connected: connection !== null,
+      detail: connection ? activeAgo(connection.lastActiveAt) : undefined,
+    };
+  });
+
+  return (
+    <AiStatusBoard
+      statuses={statuses}
+      onConnect={(hostId) =>
+        nav.goTo(hosts.find((h) => h.id === hostId)?.pluginUrl ? "install" : "copy", {
+          selectedHost: hostId,
+        })
+      }
+    />
+  );
+}
+
+/** The first step (host picker) — picking a card advances to the right path. */
+function selectStep(hosts: readonly AiHostGuide[]): GuidedStep {
+  return {
+    id: "select",
+    label: "Escolher",
+    render: (nav: GuidedNav) => (
+      <HostSelectStep
+        hosts={hosts}
+        selectedId={(nav.data.selectedHost as string | undefined) ?? null}
+        onSelect={(hostId) =>
+          nav.goTo(hosts.find((h) => h.id === hostId)?.pluginUrl ? "install" : "copy", {
+            selectedHost: hostId,
+          })
+        }
+      />
+    ),
+  };
+}
+
+/** The Copiar-URL step, shared by every manual flow. */
+function copyStep(endpointUrl: string): GuidedStep {
+  return {
+    id: "copy",
+    label: "Copiar URL",
+    render: (nav: GuidedNav) => <CopyUrlStep nav={nav} endpointUrl={endpointUrl} />,
+  };
+}
+
+/**
+ * The middle steps for the full manual flow. A host with `configureStages`
+ * (e.g. ChatGPT) gets one step per stage — each with its own deep link — after
+ * Copiar URL; otherwise the default copy → configure → connect split.
+ */
+function manualMiddle(
+  host: AiHostGuide,
+  hosts: readonly AiHostGuide[],
+  endpointUrl: string,
+  connectPrompt: string,
+): GuidedStep[] {
+  if (host.configureStages && host.configureStages.length > 0) {
+    return [
+      copyStep(endpointUrl),
+      ...host.configureStages.map((stage) => ({
+        id: stage.id,
+        label: stage.label,
+        render: (nav: GuidedNav) => (
+          <ConfigureStageStep nav={nav} host={resolveHost(hosts, nav.data.selectedHost)} stage={stage} />
+        ),
+      })),
+    ];
+  }
+  return [
+    copyStep(endpointUrl),
+    {
+      id: "configure",
+      label: "Configurar",
+      render: (nav: GuidedNav) => <ConfigureStep nav={nav} host={resolveHost(hosts, nav.data.selectedHost)} />,
+    },
+    {
+      id: "connect",
+      label: "Conectar",
+      render: (nav: GuidedNav) => (
+        <ConnectStep nav={nav} host={resolveHost(hosts, nav.data.selectedHost)} connectPrompt={connectPrompt} />
+      ),
+    },
+  ];
+}
+
+/** The single middle step for the simplified plugin flow: install. */
+function simpleMiddle(hosts: readonly AiHostGuide[], connectPrompt: string): GuidedStep[] {
+  return [
+    {
+      id: "install",
+      label: "Instalar",
+      render: (nav: GuidedNav) => (
+        <InstallStep nav={nav} host={resolveHost(hosts, nav.data.selectedHost)} connectPrompt={connectPrompt} />
+      ),
+    },
+  ];
+}
+
+/**
+ * Build the wizard's steps for the selected host's path: the simplified
+ * `install` flow when the host has a published `pluginUrl`, the per-stage flow
+ * when it declares `configureStages`, otherwise the full copy → configure →
+ * connect flow. `select` and `confirm` bookend all of them.
+ */
+export function buildFlowSteps(opts: {
+  host: AiHostGuide;
+  hosts: readonly AiHostGuide[];
+  endpointUrl: string;
+  connectPrompt: string;
+  connections: readonly AiConnection[];
+  onRetest: () => void;
+}): GuidedStep[] {
+  const { host, hosts, endpointUrl, connectPrompt, connections, onRetest } = opts;
+  const middle = host.pluginUrl
+    ? simpleMiddle(hosts, connectPrompt)
+    : manualMiddle(host, hosts, endpointUrl, connectPrompt);
+  const confirm: GuidedStep = {
+    id: "confirm",
+    label: "Confirmar",
+    render: (nav: GuidedNav) => (
+      <ConfirmStep nav={nav} connections={connections} hosts={hosts} onRetest={onRetest} />
+    ),
+  };
+  return [selectStep(hosts), ...middle, confirm];
+}

package/src/react/feature-badge.tsx

@@ -0,0 +1,46 @@
+import { Box } from "@12-apps/ui/mui/Box";
+import { Stack } from "@12-apps/ui/mui/Stack";
+import { Text } from "@12-apps/ui/typography/Text";
+
+/** One entry of a landing's trust/feature strip. */
+export interface FeatureBadgeItem {
+  icon: React.ReactNode;
+  label: string;
+  caption: string;
+}
+
+/**
+ * One item of an onboarding landing's trust/feature strip: a paper icon tile
+ * (primary-coloured glyph) with a two-line label + caption.
+ */
+export function FeatureBadge({ icon, label, caption }: FeatureBadgeItem): React.JSX.Element {
+  return (
+    <Stack direction="row" spacing={1.5} alignItems="flex-start">
+      <Box
+        sx={{
+          width: 36,
+          height: 36,
+          borderRadius: 2,
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          bgcolor: "background.paper",
+          color: "primary.main",
+          border: 1,
+          borderColor: "divider",
+          flexShrink: 0,
+        }}
+      >
+        {icon}
+      </Box>
+      <Box>
+        <Text variant="body" size="sm" weight="bold" as="p">
+          {label}
+        </Text>
+        <Text variant="caption" color="secondary" as="p">
+          {caption}
+        </Text>
+      </Box>
+    </Stack>
+  );
+}