@univerjs-pro/collaboration-comment-endpoint 1.0.0-beta.2

package/README.md

@@ -0,0 +1,65 @@
+# @univerjs-pro/collaboration-comment-endpoint
+
+English | [简体中文](./README.zh-CN.md)
+
+A Univer Thread Comment HTTP and realtime Endpoint for `@univerjs-pro/collaboration-comment-service`.
+
+It handles Univer Comment protocol requests with the Comment Service API and publishes `comment_update` to online members through the main Collaboration Endpoint's Unit rooms.
+
+```text
+HTTP Comment request
+→ Transport authentication middleware
+→ UniverCommentEndpoint
+→ Comment Service middleware
+→ Comment Database Adapter
+
+Comment commit succeeds
+→ main UniverCollabEndpoint Unit room
+→ comment_update
+```
+
+## Installation and registration
+
+```bash
+pnpm add \
+  @univerjs-pro/collaboration-comment-service \
+  @univerjs-pro/collaboration-comment-endpoint \
+  @univerjs-pro/collaboration-endpoint \
+  @univerjs-pro/collaboration-transport-node
+```
+
+```ts
+const collabEndpoint = new UniverCollabEndpoint(collabService);
+const commentEndpoint = new UniverCommentEndpoint({
+  service: commentService,
+  roomHost: collabEndpoint,
+  protocolBasePath: '/universer-api',
+});
+
+transport.use(authenticationMiddleware);
+transport.register(commentEndpoint);
+transport.register(collabEndpoint);
+```
+
+Registration order is authentication → Comment Endpoint → main Collaboration Endpoint. `roomHost` lets Comment realtime delivery reuse Sessions and Unit rooms already established by the main Endpoint.
+
+## HTTP and realtime updates
+
+The table uses the default `protocolBasePath=/universer-api`:
+
+| Method | Path | Service action | Session requirement |
+| --- | --- | --- | --- |
+| `GET/POST` | `/universer-api/comment/unit/:unitID/list` | `listComments` | No online Session required |
+| `POST` | `/universer-api/comment/unit/:unitID/add` | `addComment` | User and `memberId` must match a joined Session |
+| `POST` | `/universer-api/comment/unit/:unitID/reply` | `replyComment` | Same as above |
+| `POST` | `/universer-api/comment/unit/:unitID/edit` | `editComment` | Same as above |
+| `POST` | `/universer-api/comment/unit/:unitID/solved` | `setThreadSolved` | Must associate the current user with a joined Session |
+| `POST` | `/universer-api/comment/unit/:unitID/delete` | `deleteComment` | User and `memberId` must match a joined Session |
+
+Every route calls Comment Service with `ctx.userID/customData` set by Transport middleware for the current HTTP request. List is a regular HTTP read. Writes additionally associate an online Session so the submitter can be excluded from realtime broadcasts. Comment ACL remains controlled by Comment Service middleware.
+
+After Comment Service commits successfully, Endpoint sends `comment_update` to other online members of the Unit. If the application calls Comment Service directly and its `memberID` resolves to an online Session, that Session is treated as the initiator and does not receive its own broadcast. If it cannot be resolved, the update is broadcast to all currently online members. The HTTP response does not depend on realtime delivery succeeding.
+
+Endpoint handles protocol errors and realtime updates but does not define Comment ACL. Install permissions in Comment Service. Realtime broadcasts currently cover only one main Endpoint process. Send failure does not roll back committed Comments; clients recover by listing again.
+
+Transport disposes registered Endpoints. Comment Endpoint does not own Comment Service or the main Endpoint.

package/README.zh-CN.md

@@ -0,0 +1,75 @@
+# @univerjs-pro/collaboration-comment-endpoint
+
+[English](./README.md) | [简体中文](./README.zh-CN.md)
+
+面向 `@univerjs-pro/collaboration-comment-service` 的 Univer Thread Comment HTTP 和
+实时 Endpoint。
+
+它使用 Comment Service API 处理 Univer Comment 协议请求，并通过主协同 Endpoint 的 Unit
+房间向在线成员发布 `comment_update`。
+
+```text
+HTTP Comment 请求
+→ Transport authentication middleware
+→ UniverCommentEndpoint
+→ Comment Service middleware
+→ Comment Database Adapter
+
+Comment 提交成功
+→ 主 UniverCollabEndpoint 的 Unit room
+→ comment_update
+```
+
+## 安装与注册
+
+```bash
+pnpm add \
+  @univerjs-pro/collaboration-comment-service \
+  @univerjs-pro/collaboration-comment-endpoint \
+  @univerjs-pro/collaboration-endpoint \
+  @univerjs-pro/collaboration-transport-node
+```
+
+```ts
+const collabEndpoint = new UniverCollabEndpoint(collabService);
+const commentEndpoint = new UniverCommentEndpoint({
+  service: commentService,
+  roomHost: collabEndpoint,
+  protocolBasePath: '/universer-api',
+});
+
+transport.use(authenticationMiddleware);
+transport.register(commentEndpoint);
+transport.register(collabEndpoint);
+```
+
+注册顺序是认证 → Comment Endpoint → 主协同 Endpoint。`roomHost` 让 Comment 实时投递
+复用主 Endpoint 已建立的 Session 和 Unit room。
+
+## HTTP 与实时更新
+
+下表使用默认 `protocolBasePath=/universer-api`：
+
+| Method | Path | Service action | Session 要求 |
+| --- | --- | --- | --- |
+| `GET/POST` | `/universer-api/comment/unit/:unitID/list` | `listComments` | 不要求在线 Session |
+| `POST` | `/universer-api/comment/unit/:unitID/add` | `addComment` | 用户和 `memberId` 必须对应已 JOIN 的 Session |
+| `POST` | `/universer-api/comment/unit/:unitID/reply` | `replyComment` | 同上 |
+| `POST` | `/universer-api/comment/unit/:unitID/edit` | `editComment` | 同上 |
+| `POST` | `/universer-api/comment/unit/:unitID/solved` | `setThreadSolved` | 必须能关联当前用户已 JOIN 的 Session |
+| `POST` | `/universer-api/comment/unit/:unitID/delete` | `deleteComment` | 用户和 `memberId` 必须对应已 JOIN 的 Session |
+
+所有路由都使用当前 HTTP 请求由 Transport middleware 设置的 `ctx.userID/customData` 调用
+Comment Service。list 是普通 HTTP 读取；写操作额外关联在线 Session，以便把提交者从实时
+广播中排除。Comment ACL 仍由 Comment Service middleware 控制。
+
+Comment Service 提交成功后，Endpoint 会向同一 Unit 的其他在线成员发送
+`comment_update`。如果应用直接调用 Comment Service，并传入的 `memberID` 能找到在线
+Session，该 Session 会被视为发起方而不接收自己的广播；找不到时则向当前全部在线成员
+广播。HTTP 返回结果本身不依赖实时发送成功。
+
+Endpoint 只负责协议错误处理和实时更新，不定义 Comment ACL；权限必须安装在 Comment
+Service。当前实时广播只覆盖单个主 Endpoint 进程，发送失败不回滚已提交的
+Comment，客户端通过重新 list 恢复。
+
+Transport 释放已注册 Endpoint；Comment Endpoint 不拥有 Comment Service 或主 Endpoint。

package/dist/index.cjs

@@ -0,0 +1 @@
+Object['defineProperty'](exports,Symbol['toStringTag'],{'value':'Module'});let e=require('@univerjs-pro/collaboration-service'),t=require('@univerjs-pro/collaboration-transport-node'),n=require('@univerjs/protocol');var r={'code':n['ErrorCode']['OK'],'message':''},i=class{['_service'];['_roomHost'];['_protocolBasePath'];['_subscription'];['_calls']=new Set();['_disposed']=!0x1;['_disposePromise'];constructor(_0x1dd9ce){if(!_0x1dd9ce?.['service'])throw TypeError('UniverCommentEndpoint\x20requires\x20a\x20service');if(!_0x1dd9ce?.['roomHost'])throw TypeError('UniverCommentEndpoint\x20requires\x20a\x20roomHost');this['_service']=_0x1dd9ce['service'],this['_roomHost']=_0x1dd9ce['roomHost'],this['_protocolBasePath']=p(_0x1dd9ce['protocolBasePath']??'/universer-api'),this['_subscription']=this['_service']['on']('commentCommitted',_0x4fd8a5=>this['_track'](this['_publish'](_0x4fd8a5)));}['handleHttp'](_0x48f612,_0x41aea4){return this['_disposed']?_0x41aea4():this['_track'](this['_handleHttp'](_0x48f612,_0x41aea4));}['dispose'](){return this['_disposePromise']?this['_disposePromise']:(this['_disposed']=!0x0,this['_subscription']['dispose'](),this['_disposePromise']=Promise['allSettled']([...this['_calls']])['then'](()=>void 0x0),this['_disposePromise']);}['_track'](_0x4fe641){return this['_calls']['add'](_0x4fe641),_0x4fe641['finally'](()=>this['_calls']['delete'](_0x4fe641))['catch'](()=>void 0x0),_0x4fe641;}async['_handleHttp'](_0x3e087d,_0xff7928){let _0x4c6c74,_0xbbf0ce;try{_0xbbf0ce=new URL(_0x3e087d['incomingMessage']['url']??'/','http://localhost'),_0x4c6c74=a(_0x3e087d['incomingMessage']['method'],_0xbbf0ce['pathname'],this['_protocolBasePath']);}catch(_0x4db46b){m(_0x3e087d['response'],_0x4db46b,'unknown');return;}if(!_0x4c6c74)return _0xff7928();try{if(!_0x3e087d['userID'])throw new e['CollabError']('UNAUTHENTICATED','HTTP\x20user\x20is\x20not\x20authenticated');if(_0x4c6c74['action']==='list'){let _0x256b33=o(_0x3e087d['incomingMessage']['method']==='GET'?{'unitId':_0x4c6c74['unitID'],'threadId':_0xbbf0ce['searchParams']['getAll']('threadId')}:await _0x3e087d['readJson'](),_0x4c6c74['unitID']),_0x32675c=await this['_service']['listComments']({'unitID':_0x4c6c74['unitID'],'threadIDs':_0x256b33['threadId']},{'userID':_0x3e087d['userID'],'customData':_0x3e087d['customData']});g(_0x3e087d['response'],0xc8,{'error':r,..._0x32675c});return;}let _0x211d4e=s(await _0x3e087d['readJson']());if(c(_0x211d4e['unitId'],'unitId')!==_0x4c6c74['unitID'])throw f('Route\x20and\x20body\x20unitId\x20must\x20match');let _0x1f6c15=c(_0x211d4e['memberId'],'memberId'),_0x3c722c=this['_resolveWriteSession'](_0x4c6c74['action'],_0x4c6c74['unitID'],_0x1f6c15,_0x3e087d['userID']),_0x248151={'userID':_0x3e087d['userID'],'memberID':_0x3c722c['memberID'],'customData':_0x3e087d['customData']};switch(_0x4c6c74['action']){case'add':{let _0x576e72=await this['_service']['addComment']({'unitID':_0x4c6c74['unitID'],'content':c(_0x211d4e['content'],'content'),'mentions':u(_0x211d4e['mention'],'mention')},_0x248151);g(_0x3e087d['response'],0xc8,{'error':r,'comment':_0x576e72});return;}case'reply':{let _0x268b21=await this['_service']['replyComment']({'unitID':_0x4c6c74['unitID'],'threadID':c(_0x211d4e['threadId'],'threadId'),'content':c(_0x211d4e['content'],'content'),'mentions':u(_0x211d4e['mention'],'mention')},_0x248151);g(_0x3e087d['response'],0xc8,{'error':r,'reply':_0x268b21});return;}case'solved':{let _0x20ab1b=d(_0x211d4e['solved']);await this['_service']['setThreadSolved']({'unitID':_0x4c6c74['unitID'],'threadID':c(_0x211d4e['threadId'],'threadId'),'solved':_0x20ab1b},_0x248151),g(_0x3e087d['response'],0xc8,{'error':r});return;}case'edit':await this['_service']['editComment']({'unitID':_0x4c6c74['unitID'],'threadID':c(_0x211d4e['threadId'],'threadId'),'replyID':c(_0x211d4e['replyId'],'replyId'),'content':c(_0x211d4e['content'],'content'),'mentions':u(_0x211d4e['mention'],'mention')},_0x248151),g(_0x3e087d['response'],0xc8,{'error':r});return;case'delete':await this['_service']['deleteComment']({'unitID':_0x4c6c74['unitID'],'threadID':c(_0x211d4e['threadId'],'threadId'),...l(_0x211d4e['replyId'],'replyId')},_0x248151),g(_0x3e087d['response'],0xc8,{'error':r});return;}}catch(_0x2adde){m(_0x3e087d['response'],_0x2adde,_0x4c6c74['action']);}}['_resolveWriteSession'](_0x3e2344,_0x489c26,_0x553fbf,_0x49d488){let _0x2dd650=this['_roomHost']['findJoinedSession']({'unitID':_0x489c26,'memberID':_0x553fbf,'authenticatedUserID':_0x49d488});if(_0x2dd650)return _0x2dd650;if(_0x3e2344==='solved'&&_0x553fbf===_0x49d488){let _0x21a90c=this['_roomHost']['findJoinedSessionByUser']({'unitID':_0x489c26,'authenticatedUserID':_0x49d488});if(_0x21a90c)return _0x21a90c;}throw new e['CollabError']('PERMISSION_DENIED','Comment\x20member\x20is\x20not\x20an\x20authenticated\x20joined\x20Session');}async['_publish'](_0x3ba264){try{await this['_roomHost']['publishTrustedUnitEvent']({'unitID':_0x3ba264['update']['unitId'],'memberID':_0x3ba264['memberID'],'eventID':'comment_update','data':{'commentUpdateEvent':_0x3ba264['update']}});}catch{}}};function a(_0xe191b5,_0x220342,_0x3d98bd){let _0x203a53=_0x3d98bd+'/comment/unit/';if(!_0x220342['startsWith'](_0x203a53))return null;let _0x53717f=_0x220342['slice'](_0x203a53['length'])['split']('/');if(_0x53717f['length']!==0x2||!_0x53717f[0x0]||!_0x53717f[0x1])return null;let _0x39e533=_0x53717f[0x1];if(!['add','list','reply','solved','edit','delete']['includes'](_0x39e533)||_0x39e533==='list'&&_0xe191b5!=='GET'&&_0xe191b5!=='POST'||_0x39e533!=='list'&&_0xe191b5!=='POST')return null;let _0x1bdb39;try{_0x1bdb39=decodeURIComponent(_0x53717f[0x0]);}catch{throw f('Route\x20contains\x20invalid\x20encoding');}if(!_0x1bdb39||_0x1bdb39['includes']('/'))throw f('Invalid\x20route\x20unitId');return{'action':_0x39e533,'unitID':_0x1bdb39};}function o(_0x455adb,_0x716547){let _0x4a0f2b=s(_0x455adb),_0x531fa8=c(_0x4a0f2b['unitId'],'unitId');if(_0x531fa8!==_0x716547)throw f('Route\x20and\x20body\x20unitId\x20must\x20match');return{'unitId':_0x531fa8,'threadId':u(_0x4a0f2b['threadId'],'threadId')};}function s(_0x24fdba){if(!_0x24fdba||typeof _0x24fdba!='object'||Array['isArray'](_0x24fdba))throw f('Request\x20body\x20must\x20be\x20an\x20object');return _0x24fdba;}function c(_0x1d97a1,_0x2ea6fb){if(typeof _0x1d97a1!='string'||_0x1d97a1['length']===0x0)throw f(_0x2ea6fb+'\x20must\x20be\x20a\x20non-empty\x20string');return _0x1d97a1;}function l(_0x2eb881,_0x5a17ba){return _0x2eb881==null||_0x2eb881===''?{}:{'replyID':c(_0x2eb881,_0x5a17ba)};}function u(_0x21c7ac,_0x2e7896){if(!Array['isArray'](_0x21c7ac)||_0x21c7ac['some'](_0x677f7f=>typeof _0x677f7f!='string'||_0x677f7f['length']===0x0))throw f(_0x2e7896+'\x20must\x20be\x20an\x20array\x20of\x20non-empty\x20strings');return[..._0x21c7ac];}function d(_0x23e9cb){if(_0x23e9cb!==n['CommentSolvedStatus']['OpenOrReOpen']&&_0x23e9cb!==n['CommentSolvedStatus']['Solved'])throw f('solved\x20must\x20be\x20OpenOrReOpen\x20or\x20Solved');return _0x23e9cb;}function f(_0x4e2550){return new e['CollabError']('INVALID_REQUEST',_0x4e2550);}function p(_0x1b4243){if(!_0x1b4243['startsWith']('/')||_0x1b4243==='/'||_0x1b4243['endsWith']('/')||_0x1b4243['includes']('//'))throw TypeError('protocolBasePath\x20must\x20be\x20an\x20absolute\x20path\x20without\x20a\x20trailing\x20slash');return _0x1b4243;}function m(_0x3cb73a,_0x29c176,_0x5e4842){let _0x2819a9=h(_0x29c176),_0x2e2749=_0x5e4842==='list'?{'comments':{},'users':{}}:_0x5e4842==='add'?{'comment':void 0x0}:_0x5e4842==='reply'?{'reply':void 0x0}:{};g(_0x3cb73a,_0x2819a9['status'],{'error':_0x2819a9['error'],..._0x2e2749});}function h(_0x3df552){if(_0x3df552 instanceof t['NodeTransportError'])return _0x3df552['code']==='REQUEST_BODY_TOO_LARGE'?{'status':0x19d,'error':{'code':n['ErrorCode']['INVALID_ARGUMENT'],'message':_0x3df552['message']}}:_0x3df552['code']==='INVALID_JSON'||_0x3df552['code']==='REQUEST_ABORTED'?{'status':0x190,'error':{'code':n['ErrorCode']['INVALID_ARGUMENT'],'message':_0x3df552['message']}}:{'status':0x1f7,'error':{'code':n['ErrorCode']['INTERNAL_ERROR'],'message':_0x3df552['message']}};if(!(_0x3df552 instanceof e['CollabError']))return{'status':0x1f4,'error':{'code':n['ErrorCode']['INTERNAL_ERROR'],'message':'Internal\x20error'}};let [_0x1c943a,_0x5d4268]=((()=>{switch(_0x3df552['code']){case'INVALID_REQUEST':return[0x190,n['ErrorCode']['INVALID_ARGUMENT']];case'UNAUTHENTICATED':return[0x191,n['ErrorCode']['UNAUTHENTICATED']];case'PERMISSION_DENIED':return[0x193,n['ErrorCode']['PERMISSION_DENIED']];case'UNIT_NOT_FOUND':return[0x194,n['ErrorCode']['NOT_FOUND']];case'ADAPTER_FAILURE':return[0x1f7,n['ErrorCode']['INTERNAL_ERROR']];default:return[0x1f4,n['ErrorCode']['INTERNAL_ERROR']];}})());return{'status':_0x1c943a,'error':{'code':_0x5d4268,'message':_0x3df552['message']}};}function g(_0x27f845,_0x17accd,_0x534187){_0x27f845['writableEnded']||(_0x27f845['statusCode']=_0x17accd,_0x27f845['setHeader']('content-type','application/json;\x20charset=utf-8'),_0x27f845['end'](JSON['stringify'](_0x534187)));}exports['UniverCommentEndpoint']=i;

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+import { IUniverCommentService } from "@univerjs-pro/collaboration-comment-service";
+import { ITrustedUnitRoomHost } from "@univerjs-pro/collaboration-endpoint";
+import { NodeHttpTransportContext, NodeTransportEndpoint, NodeTransportNext } from "@univerjs-pro/collaboration-transport-node";
+
+//#region src/endpoint.d.ts
+interface UniverCommentEndpointOptions {
+  readonly service: IUniverCommentService;
+  readonly roomHost: ITrustedUnitRoomHost;
+  readonly protocolBasePath?: string;
+}
+declare class UniverCommentEndpoint implements NodeTransportEndpoint {
+  private readonly _service;
+  private readonly _roomHost;
+  private readonly _protocolBasePath;
+  private readonly _subscription;
+  private readonly _calls;
+  private _disposed;
+  private _disposePromise;
+  constructor(options: UniverCommentEndpointOptions);
+  handleHttp(context: NodeHttpTransportContext, next: NodeTransportNext): Promise<void>;
+  dispose(): Promise<void>;
+  private _track;
+  private _handleHttp;
+  private _resolveWriteSession;
+  private _publish;
+}
+//#endregion
+export { UniverCommentEndpoint, type UniverCommentEndpointOptions };

package/dist/index.mjs

@@ -0,0 +1 @@
+const _0x2f73c5=_0x5d58;(function(_0x259a81,_0x499a35){const _0x27b5f2=_0x5d58,_0x809e67=_0x259a81();while(!![]){try{const _0x3d443f=-parseInt(_0x27b5f2(0x196))/0x1*(-parseInt(_0x27b5f2(0x192))/0x2)+parseInt(_0x27b5f2(0x190))/0x3*(-parseInt(_0x27b5f2(0x197))/0x4)+parseInt(_0x27b5f2(0x18d))/0x5*(parseInt(_0x27b5f2(0x18c))/0x6)+-parseInt(_0x27b5f2(0x195))/0x7+-parseInt(_0x27b5f2(0x18f))/0x8*(-parseInt(_0x27b5f2(0x194))/0x9)+-parseInt(_0x27b5f2(0x191))/0xa+parseInt(_0x27b5f2(0x193))/0xb;if(_0x3d443f===_0x499a35)break;else _0x809e67['push'](_0x809e67['shift']());}catch(_0x57c7d4){_0x809e67['push'](_0x809e67['shift']());}}}(_0x1794,0x22d6b));import _0x4130e3 from'./index.cjs';const facadeExport0=_0x4130e3[_0x2f73c5(0x18e)];function _0x5d58(_0x2fb667,_0xa9d7d){_0x2fb667=_0x2fb667-0x18c;const _0x179493=_0x1794();let _0x5d58f7=_0x179493[_0x2fb667];return _0x5d58f7;}function _0x1794(){const _0x2bae30=['2841260UKsXoJ','412570ZSgvBM','4927439AhBlUq','279EzuLTD','1279194teLlhv','1XKtjTb','4myrChg','6PNJyNt','646755aARPCu','UniverCommentEndpoint','12448wZRCoX','666762TthDBI'];_0x1794=function(){return _0x2bae30;};return _0x1794();}export{facadeExport0 as UniverCommentEndpoint};

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@univerjs-pro/collaboration-comment-endpoint",
+  "type": "module",
+  "version": "1.0.0-beta.2",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@univerjs-pro/collaboration-comment-service": "1.0.0-beta.2",
+    "@univerjs-pro/collaboration-endpoint": "1.0.0-beta.2",
+    "@univerjs-pro/collaboration-service": "1.0.0-beta.2",
+    "@univerjs-pro/collaboration-transport-node": "1.0.0-beta.2",
+    "@univerjs/protocol": "1.0.0-beta.2"
+  }
+}