@ripperts/poco-agent-embed 0.1.0

package/README.md

@@ -0,0 +1,123 @@
+# Poco Agent Embed
+
+将 Poco Agent 的对话、历史消息和产物预览嵌入第三方系统。SDK 不依赖 Vue 或 React，支持 ESM、CommonJS 和浏览器 Script 标签接入。
+
+## 安装
+
+```bash
+pnpm add @ripperts/poco-agent-embed
+```
+
+SDK 需要在浏览器环境中挂载。第三方系统必须通过 `getAccessToken` 返回当前用户有效的 Poco 登录 token。
+
+## Vue 2
+
+```vue
+<template>
+  <div ref="agentChat" style="height: 640px"></div>
+</template>
+
+<script>
+import { mountAgentEmbed } from "@ripperts/poco-agent-embed";
+
+export default {
+  props: {
+    getAccessToken: {
+      type: Function,
+      required: true,
+    },
+  },
+  data() {
+    return {
+      agentEmbedController: null,
+    };
+  },
+  mounted() {
+    this.agentEmbedController = mountAgentEmbed({
+      baseUrl: "https://poco.example.com",
+      agentId: "<agent-id>",
+      target: this.$refs.agentChat,
+      getAccessToken: () => this.getAccessToken(),
+    });
+  },
+  beforeDestroy() {
+    if (this.agentEmbedController) {
+      this.agentEmbedController.destroy();
+    }
+  },
+};
+</script>
+```
+
+## Vue 3
+
+```vue
+<template>
+  <div ref="agentChat" style="height: 640px"></div>
+</template>
+
+<script setup>
+import { onBeforeUnmount, onMounted, ref } from "vue";
+import { mountAgentEmbed } from "@ripperts/poco-agent-embed";
+
+const props = defineProps({
+  getAccessToken: {
+    type: Function,
+    required: true,
+  },
+});
+const agentChat = ref(null);
+let agentEmbedController;
+
+onMounted(() => {
+  agentEmbedController = mountAgentEmbed({
+    baseUrl: "https://poco.example.com",
+    agentId: "<agent-id>",
+    target: agentChat.value,
+    getAccessToken: () => props.getAccessToken(),
+  });
+});
+
+onBeforeUnmount(() => {
+  if (agentEmbedController) {
+    agentEmbedController.destroy();
+  }
+});
+</script>
+```
+
+## React
+
+```tsx
+import { useEffect, useRef } from "react";
+import { mountAgentEmbed } from "@ripperts/poco-agent-embed";
+
+interface AgentChatProps {
+  getAccessToken: () => string | Promise<string>;
+}
+
+export function AgentChat({ getAccessToken }: AgentChatProps) {
+  const targetRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!targetRef.current) return;
+
+    const controller = mountAgentEmbed({
+      baseUrl: "https://poco.example.com",
+      agentId: "<agent-id>",
+      target: targetRef.current,
+      getAccessToken,
+    });
+
+    return () => controller.destroy();
+  }, [getAccessToken]);
+
+  return <div ref={targetRef} style={{ height: 640 }} />;
+}
+```
+
+## 浏览器支持
+
+支持现代 Chrome、Edge、Firefox 和 Safari。Vue 2 项目可以正常接入，但不支持 Internet Explorer 11。
+
+完整参数和安全配置请参阅 [Agent 外部嵌入文档](https://ai-agent.fsxgt.cn/docs/external-integration/agent-embed)。

package/index.d.ts

@@ -0,0 +1,45 @@
+export type AgentEmbedTheme = "light" | "dark" | "system";
+export type AgentEmbedPosition =
+  | "bottom-right"
+  | "bottom-left"
+  | "top-right"
+  | "top-left";
+
+export interface AgentEmbedOptions {
+  agentId: string;
+  getAccessToken: () => string | Promise<string>;
+  baseUrl?: string;
+  target?: string | HTMLElement;
+  language?: string;
+  theme?: AgentEmbedTheme;
+  position?: AgentEmbedPosition;
+  defaultOpen?: boolean;
+  draggable?: boolean;
+  zIndex?: number;
+  openIcon?: string | Node | (() => Node);
+  closeIcon?: string | Node | (() => Node);
+  ariaLabel?: string;
+  onError?: (error: Error) => void;
+}
+
+export interface AgentEmbedController {
+  open(): void;
+  close(): void;
+  toggle(): void;
+  destroy(): void;
+  isOpen(): boolean;
+  iframe: HTMLIFrameElement;
+}
+
+export function mountAgentEmbed(
+  options: AgentEmbedOptions,
+): AgentEmbedController;
+
+export const mount: typeof mountAgentEmbed;
+
+declare const PocoAgentEmbed: {
+  mount: typeof mountAgentEmbed;
+  mountAgentEmbed: typeof mountAgentEmbed;
+};
+
+export default PocoAgentEmbed;

package/index.js

@@ -0,0 +1,422 @@
+(function (root, factory) {
+  var api = factory(
+    typeof document !== "undefined" ? document.currentScript : null,
+  );
+  if (typeof module === "object" && module.exports) {
+    module.exports = api;
+  }
+  if (root) {
+    root.PocoAgentEmbed = api;
+  }
+})(
+  typeof globalThis !== "undefined" ? globalThis : this,
+  function (sourceScript) {
+    "use strict";
+
+    var DEFAULT_Z_INDEX = 2147483000;
+    var MESSAGE_READY = "poco-agent-embed:ready";
+    var MESSAGE_REQUEST_AUTH = "poco-agent-embed:request-auth";
+    var MESSAGE_AUTHENTICATE = "poco-agent-embed:authenticate";
+    var MESSAGE_ERROR = "poco-agent-embed:error";
+
+    function trimTrailingSlash(value) {
+      return String(value || "").replace(/\/+$/, "");
+    }
+
+    function inferBaseUrl() {
+      if (!sourceScript || !sourceScript.src) return "";
+      try {
+        return new URL(sourceScript.src, document.baseURI).origin;
+      } catch {
+        return "";
+      }
+    }
+
+    function createChannel() {
+      if (
+        globalThis.crypto &&
+        typeof globalThis.crypto.randomUUID === "function"
+      ) {
+        return globalThis.crypto.randomUUID();
+      }
+      return "poco-" + Date.now() + "-" + Math.random().toString(36).slice(2);
+    }
+
+    function resolveTarget(target) {
+      if (!target) return null;
+      if (typeof target === "string") return document.querySelector(target);
+      return target instanceof HTMLElement ? target : null;
+    }
+
+    function createDefaultIcon(isClose) {
+      var span = document.createElement("span");
+      span.setAttribute("aria-hidden", "true");
+      span.style.cssText =
+        "display:flex;align-items:center;justify-content:center;width:22px;height:22px";
+      span.textContent = isClose ? "×" : "✦";
+      span.style.fontSize = isClose ? "26px" : "20px";
+      span.style.lineHeight = "1";
+      return span;
+    }
+
+    function createIcon(value, isClose) {
+      if (typeof value === "function") {
+        var generated = value();
+        if (generated instanceof Node) return generated;
+      }
+      if (value instanceof Node) return value.cloneNode(true);
+      if (typeof value === "string" && value.trim()) {
+        var image = document.createElement("img");
+        image.src = value.trim();
+        image.alt = "";
+        image.style.cssText =
+          "display:block;width:22px;height:22px;object-fit:contain";
+        return image;
+      }
+      return createDefaultIcon(isClose);
+    }
+
+    function mountAgentEmbed(options) {
+      if (!options || typeof options !== "object") {
+        throw new TypeError("Poco Agent embed options are required");
+      }
+      var agentId = String(options.agentId || "").trim();
+      if (!agentId) throw new TypeError("agentId is required");
+      if (typeof options.getAccessToken !== "function") {
+        throw new TypeError("getAccessToken must be a function");
+      }
+
+      var baseUrl = trimTrailingSlash(options.baseUrl || inferBaseUrl());
+      if (!baseUrl) {
+        throw new TypeError(
+          "baseUrl is required when the SDK URL cannot be inferred",
+        );
+      }
+      var pocoOrigin = new URL(baseUrl).origin;
+      var target = resolveTarget(options.target);
+      if (options.target && !target)
+        throw new TypeError("target was not found");
+      var channel = createChannel();
+      var requestedLanguage = String(
+        options.language || document.documentElement.lang || "zh",
+      )
+        .trim()
+        .toLowerCase()
+        .split("-")[0];
+      var language = ["en", "zh"].includes(requestedLanguage)
+        ? requestedLanguage
+        : "en";
+      var theme = ["light", "dark", "system"].includes(options.theme)
+        ? options.theme
+        : "system";
+      var query = new URLSearchParams({ channel: channel, theme: theme });
+      var iframe = document.createElement("iframe");
+      iframe.src =
+        baseUrl +
+        "/" +
+        encodeURIComponent(language || "zh") +
+        "/embed/agents/" +
+        encodeURIComponent(agentId) +
+        "?" +
+        query.toString();
+      iframe.title = options.ariaLabel || "AI Agent";
+      iframe.setAttribute(
+        "sandbox",
+        "allow-downloads allow-forms allow-popups allow-same-origin allow-scripts",
+      );
+      iframe.setAttribute("allow", "clipboard-write");
+      iframe.style.cssText =
+        "display:block;width:100%;height:100%;border:0;background:transparent";
+
+      var destroyed = false;
+      var opened = Boolean(target || options.defaultOpen);
+      var container = document.createElement("div");
+      var button = null;
+      var updateViewportPosition = null;
+      var openIcon = createIcon(options.openIcon, false);
+      var closeIcon = createIcon(options.closeIcon, true);
+
+      if (target) {
+        container.style.cssText =
+          "position:relative;width:100%;height:100%;overflow:hidden";
+        container.appendChild(iframe);
+        target.appendChild(container);
+      } else {
+        container.style.cssText = [
+          "position:fixed",
+          "width:min(420px,calc(100vw - 24px))",
+          "height:min(720px,calc(100dvh - 96px))",
+          "min-height:min(360px,calc(100dvh - 96px))",
+          "overflow:hidden",
+          "border:1px solid color-mix(in srgb,CanvasText 25%,transparent)",
+          "border-radius:16px",
+          "background:Canvas",
+          "box-shadow:0 20px 60px color-mix(in srgb,CanvasText 20%,transparent)",
+          "transition:opacity .18s ease,transform .18s ease,visibility .18s ease",
+          "transform-origin:bottom right",
+          "z-index:" + String(options.zIndex || DEFAULT_Z_INDEX),
+        ].join(";");
+        container.appendChild(iframe);
+
+        button = document.createElement("button");
+        button.type = "button";
+        button.setAttribute("aria-label", options.ariaLabel || "Open AI Agent");
+        button.style.cssText = [
+          "position:fixed",
+          "display:flex",
+          "align-items:center",
+          "justify-content:center",
+          "width:52px",
+          "height:52px",
+          "padding:0",
+          "border:0",
+          "border-radius:999px",
+          "background:var(--poco-agent-embed-button-background,CanvasText)",
+          "color:var(--poco-agent-embed-button-foreground,Canvas)",
+          "box-shadow:0 10px 30px color-mix(in srgb,CanvasText 25%,transparent)",
+          "cursor:pointer",
+          "touch-action:none",
+          "z-index:" + String((options.zIndex || DEFAULT_Z_INDEX) + 1),
+        ].join(";");
+
+        var position = options.position || "bottom-right";
+        var vertical = position.indexOf("top") === 0 ? "top" : "bottom";
+        var horizontal = position.indexOf("left") > -1 ? "left" : "right";
+        button.style[vertical] = "20px";
+        button.style[horizontal] = "20px";
+        container.style[vertical] = "84px";
+        container.style[horizontal] = "20px";
+        container.style.transformOrigin = vertical + " " + horizontal;
+
+        function renderButtonIcon() {
+          button.replaceChildren(opened ? closeIcon : openIcon);
+          button.setAttribute("aria-expanded", opened ? "true" : "false");
+        }
+
+        function renderOpenState() {
+          container.style.opacity = opened ? "1" : "0";
+          container.style.visibility = opened ? "visible" : "hidden";
+          container.style.pointerEvents = opened ? "auto" : "none";
+          container.style.transform = opened ? "scale(1)" : "scale(.96)";
+          renderButtonIcon();
+        }
+
+        function anchorContainerToButton() {
+          var rect = button.getBoundingClientRect();
+          var useLeft = rect.left + rect.width / 2 < window.innerWidth / 2;
+          var popupWidth = Math.min(420, Math.max(0, window.innerWidth - 24));
+          var preferredLeft = useLeft ? rect.left : rect.right - popupWidth;
+          var popupLeft = Math.max(
+            8,
+            Math.min(window.innerWidth - popupWidth - 8, preferredLeft),
+          );
+          var availableAbove = Math.max(0, rect.top - 20);
+          var availableBelow = Math.max(
+            0,
+            window.innerHeight - rect.bottom - 20,
+          );
+          var useTop = availableBelow >= availableAbove;
+          var availableHeight = useTop ? availableBelow : availableAbove;
+          var popupHeight = Math.max(0, Math.min(720, availableHeight));
+          container.style.left = popupLeft + "px";
+          container.style.right = "auto";
+          container.style.top = useTop ? rect.bottom + 12 + "px" : "auto";
+          container.style.bottom = useTop
+            ? "auto"
+            : Math.max(8, window.innerHeight - rect.top + 12) + "px";
+          container.style.height = popupHeight + "px";
+          container.style.minHeight = Math.min(360, popupHeight) + "px";
+          container.style.transformOrigin =
+            (useTop ? "top" : "bottom") + " " + (useLeft ? "left" : "right");
+        }
+
+        updateViewportPosition = function () {
+          if (destroyed) return;
+          dragState = null;
+          var rect = button.getBoundingClientRect();
+          var left = Math.max(
+            8,
+            Math.min(window.innerWidth - rect.width - 8, rect.left),
+          );
+          var top = Math.max(
+            8,
+            Math.min(window.innerHeight - rect.height - 8, rect.top),
+          );
+          button.style.left = left + "px";
+          button.style.top = top + "px";
+          button.style.right = "auto";
+          button.style.bottom = "auto";
+          anchorContainerToButton();
+        };
+
+        var dragState = null;
+        var suppressClickUntil = 0;
+        button.addEventListener("pointerdown", function (event) {
+          if (options.draggable === false) return;
+          var rect = button.getBoundingClientRect();
+          dragState = {
+            pointerId: event.pointerId,
+            startX: event.clientX,
+            startY: event.clientY,
+            left: rect.left,
+            top: rect.top,
+            moved: false,
+          };
+          button.setPointerCapture(event.pointerId);
+        });
+        button.addEventListener("pointermove", function (event) {
+          if (!dragState || dragState.pointerId !== event.pointerId) return;
+          var deltaX = event.clientX - dragState.startX;
+          var deltaY = event.clientY - dragState.startY;
+          if (Math.abs(deltaX) + Math.abs(deltaY) > 4) dragState.moved = true;
+          if (!dragState.moved) return;
+          var left = Math.max(
+            8,
+            Math.min(window.innerWidth - 60, dragState.left + deltaX),
+          );
+          var top = Math.max(
+            8,
+            Math.min(window.innerHeight - 60, dragState.top + deltaY),
+          );
+          button.style.left = left + "px";
+          button.style.top = top + "px";
+          button.style.right = "auto";
+          button.style.bottom = "auto";
+        });
+        button.addEventListener("pointerup", function (event) {
+          if (!dragState || dragState.pointerId !== event.pointerId) return;
+          var moved = dragState.moved;
+          dragState = null;
+          button.releasePointerCapture(event.pointerId);
+          if (moved) {
+            suppressClickUntil = Date.now() + 100;
+            anchorContainerToButton();
+          }
+        });
+        button.addEventListener("pointercancel", function () {
+          dragState = null;
+        });
+        button.addEventListener("click", function () {
+          if (Date.now() < suppressClickUntil) return;
+          opened = !opened;
+          renderOpenState();
+        });
+
+        document.body.appendChild(container);
+        document.body.appendChild(button);
+        window.addEventListener("resize", updateViewportPosition);
+        window.addEventListener("orientationchange", updateViewportPosition);
+        if (window.visualViewport) {
+          window.visualViewport.addEventListener(
+            "resize",
+            updateViewportPosition,
+          );
+        }
+        updateViewportPosition();
+        renderOpenState();
+      }
+
+      async function authenticate() {
+        try {
+          var token = await options.getAccessToken();
+          token = String(token || "").trim();
+          if (!token) throw new Error("getAccessToken returned an empty token");
+          if (destroyed || !iframe.contentWindow) return;
+          iframe.contentWindow.postMessage(
+            {
+              type: MESSAGE_AUTHENTICATE,
+              channel: channel,
+              accessToken: token,
+            },
+            pocoOrigin,
+          );
+        } catch (error) {
+          var normalized =
+            error instanceof Error ? error : new Error(String(error));
+          if (typeof options.onError === "function")
+            options.onError(normalized);
+        }
+      }
+
+      function handleMessage(event) {
+        if (destroyed || event.source !== iframe.contentWindow) return;
+        if (
+          event.origin !== pocoOrigin ||
+          !event.data ||
+          typeof event.data !== "object"
+        )
+          return;
+        if (event.data.channel !== channel) return;
+        if (
+          event.data.type === MESSAGE_READY ||
+          event.data.type === MESSAGE_REQUEST_AUTH
+        ) {
+          authenticate();
+        } else if (
+          event.data.type === MESSAGE_ERROR &&
+          typeof options.onError === "function"
+        ) {
+          options.onError(
+            new Error(String(event.data.message || "Agent embed failed")),
+          );
+        }
+      }
+
+      window.addEventListener("message", handleMessage);
+
+      function setOpened(next) {
+        if (destroyed || target) return;
+        opened = next;
+        container.style.opacity = opened ? "1" : "0";
+        container.style.visibility = opened ? "visible" : "hidden";
+        container.style.pointerEvents = opened ? "auto" : "none";
+        container.style.transform = opened ? "scale(1)" : "scale(.96)";
+        if (button) {
+          button.replaceChildren(opened ? closeIcon : openIcon);
+          button.setAttribute("aria-expanded", opened ? "true" : "false");
+        }
+      }
+
+      return {
+        iframe: iframe,
+        open: function () {
+          setOpened(true);
+        },
+        close: function () {
+          setOpened(false);
+        },
+        toggle: function () {
+          setOpened(!opened);
+        },
+        isOpen: function () {
+          return target ? true : opened;
+        },
+        destroy: function () {
+          if (destroyed) return;
+          destroyed = true;
+          window.removeEventListener("message", handleMessage);
+          if (updateViewportPosition) {
+            window.removeEventListener("resize", updateViewportPosition);
+            window.removeEventListener(
+              "orientationchange",
+              updateViewportPosition,
+            );
+            if (window.visualViewport) {
+              window.visualViewport.removeEventListener(
+                "resize",
+                updateViewportPosition,
+              );
+            }
+          }
+          container.remove();
+          if (button) button.remove();
+        },
+      };
+    }
+
+    return {
+      mount: mountAgentEmbed,
+      mountAgentEmbed: mountAgentEmbed,
+    };
+  },
+);

package/index.mjs

@@ -0,0 +1,6 @@
+import PocoAgentEmbed from "./index.js";
+
+const { mount, mountAgentEmbed } = PocoAgentEmbed;
+
+export { mount, mountAgentEmbed };
+export default PocoAgentEmbed;

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@ripperts/poco-agent-embed",
+  "version": "0.1.0",
+  "description": "Zero-dependency SDK for embedding a Poco Agent conversation",
+  "main": "index.js",
+  "module": "index.mjs",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.mjs",
+      "require": "./index.js",
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.mjs",
+    "index.d.ts",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RipperTs/poco-ai-agent.git",
+    "directory": "frontend/packages/agent-embed"
+  },
+  "homepage": "https://github.com/RipperTs/poco-ai-agent#readme",
+  "bugs": {
+    "url": "https://github.com/RipperTs/poco-ai-agent/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT",
+  "sideEffects": false
+}