@ripperts/poco-agent-embed 0.1.2 → 0.1.4

package/README.md

@@ -5,119 +5,107 @@
 ## 安装
 
 ```bash
-pnpm add @ripperts/poco-agent-embed
+npm install @ripperts/poco-agent-embed
 ```
 
-SDK 需要在浏览器环境中挂载。第三方系统必须通过 `getAccessToken` 返回当前用户有效的 Poco 登录 token。
+## 接入步骤
 
-## Vue 2
+1. 在 Poco 的场景专家中开放外部嵌入，并把宿主页面的 origin 加入允许来源。
+2. 在宿主系统后端调用 `POST https://poco.example.com/openapi/v1/auth/token`，为当前登录用户换取 Poco 登录 Token，再通过自己的接口（下文示例为 `/api/poco/token`）返回给前端。
+3. 在前端挂载对话窗口，`getAccessToken` 调用上一步的接口。
 
-```vue
-<template>
-  <div ref="agentChat" style="height: 640px"></div>
-</template>
-
-<script>
-import { mountAgentEmbed } from "@ripperts/poco-agent-embed";
+`https://poco.example.com` 替换为你在浏览器中打开 Poco 的地址，Token 接口和 SDK 使用同一个地址。下文示例共用这个函数：
 
-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>
+```js
+async function getAccessToken() {
+  const response = await fetch("/api/poco/token");
+  const data = await response.json();
+  return data.access_token;
+}
 ```
 
 ## Vue 3
 
 ```vue
 <template>
-  <div ref="agentChat" style="height: 640px"></div>
+  <div ref="container" 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;
+const container = ref(null);
+let widget = null;
 
 onMounted(() => {
-  agentEmbedController = mountAgentEmbed({
+  widget = mountAgentEmbed({
     baseUrl: "https://poco.example.com",
     agentId: "<agent-id>",
-    target: agentChat.value,
-    getAccessToken: () => props.getAccessToken(),
+    target: container.value,
+    getAccessToken,
   });
 });
 
 onBeforeUnmount(() => {
-  if (agentEmbedController) {
-    agentEmbedController.destroy();
-  }
+  if (widget) widget.destroy();
 });
 </script>
 ```
 
+## Vue 2
+
+```vue
+<template>
+  <div ref="container" style="height: 640px"></div>
+</template>
+
+<script>
+import { mountAgentEmbed } from "@ripperts/poco-agent-embed";
+
+export default {
+  mounted() {
+    this.widget = mountAgentEmbed({
+      baseUrl: "https://poco.example.com",
+      agentId: "<agent-id>",
+      target: this.$refs.container,
+      getAccessToken,
+    });
+  },
+  beforeDestroy() {
+    if (this.widget) this.widget.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);
+export function AgentChat() {
+  const containerRef = useRef(null);
 
   useEffect(() => {
-    if (!targetRef.current) return;
-
-    const controller = mountAgentEmbed({
+    const widget = mountAgentEmbed({
       baseUrl: "https://poco.example.com",
       agentId: "<agent-id>",
-      target: targetRef.current,
+      target: containerRef.current,
       getAccessToken,
     });
+    return () => widget.destroy();
+  }, []);
 
-    return () => controller.destroy();
-  }, [getAccessToken]);
-
-  return <div ref={targetRef} style={{ height: 640 }} />;
+  return <div ref={containerRef} style={{ height: 640 }} />;
 }
 ```
 
+传入 `target` 时对话窗口填满该容器，容器需要有明确高度；不传 `target` 则在页面右下角显示悬浮按钮。
+
 ## 浏览器支持
 
 支持现代 Chrome、Edge、Firefox 和 Safari。Vue 2 项目可以正常接入，但不支持 Internet Explorer 11。
 
-完整参数和安全配置请参阅 [Agent 外部嵌入文档](https://ai-agent.fsxgt.cn/docs/external-integration/agent-embed)。
+完整参数和安全配置请参阅 [Agent 外部嵌入文档](https://ai-agent.fsxgt.cn/docs/getting-started/agent-embed)。

package/index.js

@@ -18,6 +18,7 @@
     var MESSAGE_REQUEST_AUTH = "poco-agent-embed:request-auth";
     var MESSAGE_AUTHENTICATE = "poco-agent-embed:authenticate";
     var MESSAGE_ERROR = "poco-agent-embed:error";
+    var MESSAGE_DRAG = "poco-agent-embed:drag";
 
     function trimTrailingSlash(value) {
       return String(value || "").replace(/\/+$/, "");
@@ -114,6 +115,7 @@
         ? options.theme
         : "system";
       var query = new URLSearchParams({ channel: channel, theme: theme });
+      if (!target && options.draggable !== false) query.set("draggable", "1");
       var iframe = document.createElement("iframe");
       iframe.src =
         baseUrl +
@@ -137,6 +139,7 @@
       var container = document.createElement("div");
       var button = null;
       var updateViewportPosition = null;
+      var handleFrameDrag = null;
       var openIcon = createIcon(options.openIcon, false);
       var closeIcon = createIcon(options.closeIcon, true);
 
@@ -165,8 +168,6 @@
         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",
@@ -201,10 +202,15 @@
         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";
+        var verticalOffset = vertical === "bottom" ? 100 : 20;
+        var popupAvailableHeight =
+          "calc(100dvh - " + (verticalOffset + 76) + "px)";
+        button.style[vertical] = verticalOffset + "px";
         button.style[horizontal] = "20px";
-        container.style[vertical] = "84px";
+        container.style[vertical] = verticalOffset + 64 + "px";
         container.style[horizontal] = "20px";
+        container.style.height = "min(720px," + popupAvailableHeight + ")";
+        container.style.minHeight = "min(360px," + popupAvailableHeight + ")";
         container.style.transformOrigin = vertical + " " + horizontal;
 
         function anchorContainerToButton() {
@@ -255,6 +261,52 @@
           anchorContainerToButton();
         };
 
+        var frameDrag = null;
+        handleFrameDrag = function (data) {
+          if (data.phase === "start") {
+            var buttonRect = button.getBoundingClientRect();
+            var containerRect = container.getBoundingClientRect();
+            frameDrag = {
+              buttonLeft: buttonRect.left,
+              buttonTop: buttonRect.top,
+              containerLeft: containerRect.left,
+              containerTop: containerRect.top,
+              minX: 8 - Math.min(buttonRect.left, containerRect.left),
+              maxX:
+                window.innerWidth -
+                8 -
+                Math.max(buttonRect.right, containerRect.right),
+              minY: 8 - Math.min(buttonRect.top, containerRect.top),
+              maxY:
+                window.innerHeight -
+                8 -
+                Math.max(buttonRect.bottom, containerRect.bottom),
+            };
+            container.style.height = containerRect.height + "px";
+            container.style.minHeight = containerRect.height + "px";
+            return;
+          }
+          if (!frameDrag) return;
+          if (data.phase === "move") {
+            var offsetX = Math.max(
+              frameDrag.minX,
+              Math.min(frameDrag.maxX, data.dx),
+            );
+            var offsetY = Math.max(
+              frameDrag.minY,
+              Math.min(frameDrag.maxY, data.dy),
+            );
+            button.style.left = frameDrag.buttonLeft + offsetX + "px";
+            button.style.top = frameDrag.buttonTop + offsetY + "px";
+            container.style.left = frameDrag.containerLeft + offsetX + "px";
+            container.style.top = frameDrag.containerTop + offsetY + "px";
+            container.style.bottom = "auto";
+            return;
+          }
+          frameDrag = null;
+          anchorContainerToButton();
+        };
+
         var dragState = null;
         var suppressClickUntil = 0;
         button.addEventListener("pointerdown", function (event) {
@@ -358,6 +410,15 @@
           event.data.type === MESSAGE_REQUEST_AUTH
         ) {
           authenticate();
+        } else if (
+          event.data.type === MESSAGE_DRAG &&
+          handleFrameDrag &&
+          options.draggable !== false &&
+          ["start", "move", "end"].includes(event.data.phase) &&
+          Number.isFinite(event.data.dx) &&
+          Number.isFinite(event.data.dy)
+        ) {
+          handleFrameDrag(event.data);
         } else if (
           event.data.type === MESSAGE_ERROR &&
           typeof options.onError === "function"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ripperts/poco-agent-embed",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Zero-dependency SDK for embedding a Poco Agent conversation",
   "main": "index.js",
   "module": "index.mjs",