@adonis-agora/collaboration 0.1.1

package/dist/src/types.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Tipos centrais da lib de colaboração.
+ *
+ * A abstração é document-first: um `CollabDocument` é identificado por nome
+ * (`researches/<id>/writing`, por exemplo) e o driver escolhido decide como
+ * sincronizar (Yjs/Hocuspocus ou Automerge). Tudo que depende do motor fica
+ * atrás das interfaces — o app consome apenas `CollaborationManager`.
+ */
+/** Motor CRDT subjacente. */
+export type CollaborationEngine = 'yjs' | 'automerge';
+/**
+ * Âncora de um comentário — genérica por tipo de conteúdo.
+ * A lib persiste a âncora + lifecycle; quem sabe interpretá-la é o resolver
+ * registrado pelo app (texto → offsets, canvas → shapeId, mídia → timestamp).
+ */
+export type CommentAnchor = {
+    kind: 'text-range';
+    start: number;
+    end: number;
+    selectedText: string;
+} | {
+    kind: 'canvas-object';
+    shapeId: string;
+    relativeX: number;
+    relativeY: number;
+} | {
+    kind: 'timestamp';
+    at: number;
+    end?: number;
+};
+/** Comentário persistido pela lib (thread + resolved + autor). */
+export interface CollabComment {
+    id: string;
+    documentName: string;
+    /** Espaço do documento onde a âncora vive ('text', 'canvas', ...). */
+    space: string;
+    anchor: CommentAnchor;
+    body: string;
+    userId: string;
+    authorName?: string | null;
+    resolvedAt: string | null;
+    createdAt: string;
+    updatedAt: string | null;
+}
+/** Payload de autenticação anexado à conexão WebSocket. */
+export interface CollabConnectionContext {
+    /** Id do usuário autenticado (o provider valida antes do handshake). */
+    userId: string;
+    /** Metadados livres (nome, avatar) pra presença. */
+    user?: {
+        name?: string;
+        avatarUrl?: string | null;
+    };
+}
+/** Resultado da autorização de leitura/escrita de um documento. */
+export interface CollabPermission {
+    canRead: boolean;
+    /** Escrever no conteúdo do documento (editor central). */
+    canWrite: boolean;
+    /** Comentar (annotations laterais — não muda o texto). */
+    canComment: boolean;
+}
+/** Documento colaborativo carregado pelo driver. */
+export interface LoadedCollabDocument {
+    /** Estado binário completo pra enviar a um cliente novo (update merge). */
+    state: Uint8Array;
+    /** Vetor de estado pra sync diferencial (Yjs: state vector; Automerge: heads). */
+    vector: Uint8Array;
+}
+/** Uma versão registrada no histórico do documento. */
+export interface CollabVersion {
+    /** Referência opaca pro driver (snapshot Yjs / hash Automerge). */
+    id: string;
+    createdAt: string;
+    createdBy: string | null;
+    label: string | null;
+    /** Número sequencial amigável (1, 2, 3…). */
+    seq: number;
+}
+/** Estatísticas de diff entre duas versões. */
+export interface CollabDiffSummary {
+    added: number;
+    removed: number;
+}
+/**
+ * Persistência de documentos + versões + comentários. O app hospedeiro
+ * implementa isso (banco, S3…) e a lib só conhece a interface.
+ */
+export interface CollaborationStorage {
+    loadDocument(docName: string): Promise<{
+        state: Uint8Array;
+    } | null>;
+    saveDocument(docName: string, state: Uint8Array, meta?: Record<string, unknown>): Promise<void>;
+    listVersions(docName: string): Promise<CollabVersion[]>;
+    saveVersion(docName: string, version: CollabVersion, snapshot: Uint8Array): Promise<void>;
+    loadVersionSnapshot(docName: string, versionId: string): Promise<Uint8Array | null>;
+    /** Comentários de um documento (por espaço). */
+    listComments(docName: string, space?: string): Promise<CollabComment[]>;
+    saveComment(docName: string, comment: CollabComment): Promise<void>;
+    deleteComment(docName: string, commentId: string): Promise<void>;
+}
+/** Configuração do manager. */
+export interface CollaborationConfig {
+    engine: CollaborationEngine;
+    /** Omitido = in-memory (só dev). O stub de config publica um default. */
+    storage?: CollaborationStorage;
+    /**
+     * Autorização por documento. Chamada no handshake (onAuthenticate) e a cada
+     * mudança de permissão relevante — retorna false pra derrubar a conexão.
+     */
+    authorize: (ctx: CollabConnectionContext, docName: string) => Promise<CollabPermission>;
+    /** Redis pra presença cross-instance (opcional em dev single-instance). */
+    redis?: {
+        url: string;
+    };
+    /** Porta/path do WS quando embutido no server HTTP do Adonis. */
+    path?: string;
+    /** Debounce de persistência em ms (default 2000). */
+    debounce?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,6BAA6B;AAC7B,MAAM,MAAM,mBAAmB,GAAG,KAAK,GAAG,WAAW,CAAA;AAErD;;;;GAIG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GACxE;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAChF;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAEnD,kEAAkE;AAClE,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,YAAY,EAAE,MAAM,CAAA;IACpB,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,aAAa,CAAA;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CACzB;AAED,2DAA2D;AAC3D,MAAM,WAAW,uBAAuB;IACtC,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CACrD;AAED,mEAAmE;AACnE,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,0DAA0D;IAC1D,QAAQ,EAAE,OAAO,CAAC;IAClB,0DAA0D;IAC1D,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,oDAAoD;AACpD,MAAM,WAAW,oBAAoB;IACnC,2EAA2E;IAC3E,KAAK,EAAE,UAAU,CAAC;IAClB,kFAAkF;IAClF,MAAM,EAAE,UAAU,CAAC;CACpB;AAED,uDAAuD;AACvD,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,6CAA6C;IAC7C,GAAG,EAAE,MAAM,CAAC;CACb;AAED,+CAA+C;AAC/C,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,UAAU,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IACrE,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChG,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IACxD,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1F,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IACpF,gDAAgD;IAChD,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IACxE,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClE;AAED,+BAA+B;AAC/B,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,mBAAmB,CAAC;IAC5B,yEAAyE;IACzE,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAC/B;;;OAGG;IACH,SAAS,EAAE,CAAC,GAAG,EAAE,uBAAuB,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACxF,2EAA2E;IAC3E,KAAK,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACxB,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/dist/src/types.js

@@ -0,0 +1,11 @@
+/**
+ * Tipos centrais da lib de colaboração.
+ *
+ * A abstração é document-first: um `CollabDocument` é identificado por nome
+ * (`researches/<id>/writing`, por exemplo) e o driver escolhido decide como
+ * sincronizar (Yjs/Hocuspocus ou Automerge). Tudo que depende do motor fica
+ * atrás das interfaces — o app consome apenas `CollaborationManager`.
+ */
+;
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA4BF,CAAC"}

package/dist/src/versioning.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Metadados de versões compartilhados entre drivers — mesma semântica de
+ * histórico pro Automerge (nativo) e pro Yjs (snapshots).
+ */
+import type { CollabVersion } from './types.js';
+/** Próximo número sequencial a partir das versões existentes. */
+export declare function seqVersions(existing: CollabVersion[]): number;
+export declare function createVersionMetadata(createdBy: string | null, label: string | null, seq: number): CollabVersion;
+//# sourceMappingURL=versioning.d.ts.map

package/dist/src/versioning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"versioning.d.ts","sourceRoot":"","sources":["../../src/versioning.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,iEAAiE;AACjE,wBAAgB,WAAW,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,MAAM,CAE7D;AAED,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,GAAG,EAAE,MAAM,GACV,aAAa,CAQf"}

package/dist/src/versioning.js

@@ -0,0 +1,19 @@
+/**
+ * Metadados de versões compartilhados entre drivers — mesma semântica de
+ * histórico pro Automerge (nativo) e pro Yjs (snapshots).
+ */
+import { randomUUID } from 'node:crypto';
+/** Próximo número sequencial a partir das versões existentes. */
+export function seqVersions(existing) {
+    return existing.reduce((max, version) => Math.max(max, version.seq), 0) + 1;
+}
+export function createVersionMetadata(createdBy, label, seq) {
+    return {
+        id: randomUUID(),
+        createdAt: new Date().toISOString(),
+        createdBy,
+        label,
+        seq,
+    };
+}
+//# sourceMappingURL=versioning.js.map

package/dist/src/versioning.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"versioning.js","sourceRoot":"","sources":["../../src/versioning.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,iEAAiE;AACjE,MAAM,UAAU,WAAW,CAAC,QAAyB;IACnD,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;AAC9E,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,SAAwB,EACxB,KAAoB,EACpB,GAAW;IAEX,OAAO;QACL,EAAE,EAAE,UAAU,EAAE;QAChB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,SAAS;QACT,KAAK;QACL,GAAG;KACJ,CAAC;AACJ,CAAC"}

package/dist/stubs/config/collaboration.stub

@@ -0,0 +1,39 @@
+{{{
+  exports({ to: app.configPath('collaboration.ts') })
+}}}
+import { defineConfig } from '@adonis-agora/collaboration'
+
+/**
+ * Configuration for @adonis-agora/collaboration.
+ *
+ * The engine picks the CRDT backend: 'yjs' (Hocuspocus sync server, default)
+ * or 'automerge' (native history). Documents are identified by name — e.g.
+ * `researches/<id>/writing` — and resolved by your `authorize` callback.
+ */
+export default defineConfig({
+  engine: 'yjs',
+
+  /** WebSocket upgrade path on the Adonis HTTP server. */
+  path: '/collaboration',
+
+  /** Redis connection for cross-instance presence (omit for single-instance dev). */
+  // redisUrl: env.get('REDIS_URL'),
+
+  /** Persist debounce in ms (onStoreDocument). */
+  debounce: 2000,
+
+  /**
+   * Authorization per document. Return canRead/canWrite/canComment; the
+   * driver drops the connection when canRead is false.
+   */
+  async authorize(_ctx, _docName) {
+    throw new Error('Configure authorize() in config/collaboration.ts')
+  },
+
+  /**
+   * Storage backend for document states and versions. The default persists
+   * to disk (.collab-data) — swap for a Lucid/S3-backed implementation in
+   * production.
+   */
+  storage: undefined,
+})

package/dist/stubs/main.d.ts

@@ -0,0 +1,3 @@
+/** Absolute path to the published stubs directory (`dist/stubs/main.js`). */
+export declare const stubsRoot: string;
+//# sourceMappingURL=main.d.ts.map

package/dist/stubs/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../stubs/main.ts"],"names":[],"mappings":"AAEA,6EAA6E;AAC7E,eAAO,MAAM,SAAS,QAAgD,CAAC"}

package/dist/stubs/main.js

@@ -0,0 +1,4 @@
+import { fileURLToPath } from 'node:url';
+
+/** Absolute path to the published stubs directory (`dist/stubs/main.js`). */
+export const stubsRoot = fileURLToPath(new URL('./', import.meta.url));

package/dist/stubs/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../stubs/main.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,6EAA6E;AAC7E,MAAM,CAAC,MAAM,SAAS,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,124 @@
+{
+  "name": "@adonis-agora/collaboration",
+  "version": "0.1.1",
+  "description": "Collaborative editing (CRDT) for AdonisJS 7 — Yjs (Hocuspocus) and Automerge drivers, Redis-backed presence, unified version control. Part of the Agora ecosystem.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DavideCarvalho/adonis-agora-collaboration.git",
+    "directory": "packages/adonis"
+  },
+  "author": "Davi Carvalho <davi@goflip.ai>",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js",
+      "default": "./dist/src/index.js"
+    },
+    "./types": {
+      "types": "./dist/src/types.d.ts",
+      "import": "./dist/src/types.js",
+      "default": "./dist/src/types.js"
+    },
+    "./drivers/yjs": {
+      "types": "./dist/src/drivers/yjs/yjs_driver.d.ts",
+      "import": "./dist/src/drivers/yjs/yjs_driver.js",
+      "default": "./dist/src/drivers/yjs/yjs_driver.js"
+    },
+    "./drivers/automerge": {
+      "types": "./dist/src/drivers/automerge/automerge_driver.d.ts",
+      "import": "./dist/src/drivers/automerge/automerge_driver.js",
+      "default": "./dist/src/drivers/automerge/automerge_driver.js"
+    },
+    "./storage/file_system": {
+      "types": "./dist/src/storage/file_system_storage.d.ts",
+      "import": "./dist/src/storage/file_system_storage.js",
+      "default": "./dist/src/storage/file_system_storage.js"
+    },
+    "./storage/lucid": {
+      "types": "./dist/src/storage/lucid_storage.d.ts",
+      "import": "./dist/src/storage/lucid_storage.js",
+      "default": "./dist/src/storage/lucid_storage.js"
+    },
+    "./services/main": {
+      "types": "./dist/src/services/main.d.ts",
+      "import": "./dist/src/services/main.js",
+      "default": "./dist/src/services/main.js"
+    },
+    "./collaboration_provider": {
+      "types": "./dist/providers/collaboration_provider.d.ts",
+      "import": "./dist/providers/collaboration_provider.js",
+      "default": "./dist/providers/collaboration_provider.js"
+    },
+    "./configure": {
+      "types": "./dist/configure.d.ts",
+      "import": "./dist/configure.js",
+      "default": "./dist/configure.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "pnpm run clean && tsc -p tsconfig.build.json && pnpm run copy:stubs",
+    "check:dist": "node ../../scripts/assert-build-output.mjs dist src/index.js",
+    "clean": "rm -rf dist",
+    "copy:stubs": "mkdir -p dist/stubs/config && cp stubs/main.ts dist/stubs/main.js && cp stubs/config/collaboration.stub dist/stubs/config/collaboration.stub",
+    "prepack": "pnpm run check:dist",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@automerge/automerge": "^3.4.1",
+    "@hocuspocus/server": "^4.6.0",
+    "@hocuspocus/transformer": "^4.6.0",
+    "ioredis": "^5.11.1",
+    "ws": "^8.18.0",
+    "y-protocols": "^1.0.7",
+    "yjs": "^13.6.27"
+  },
+  "peerDependencies": {
+    "@adonisjs/core": "^7.3.0",
+    "@adonisjs/lucid": "^22.4.0"
+  },
+  "peerDependenciesMeta": {
+    "@adonisjs/core": {
+      "optional": true
+    },
+    "@adonisjs/lucid": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@adonisjs/assembler": "8.5.0",
+    "@adonisjs/core": "7.5.0",
+    "@adonisjs/lucid": "22.4.2",
+    "@swc/core": "1.15.47",
+    "@types/node": "22.20.1",
+    "@types/ws": "8.18.1",
+    "typescript": "5.9.3",
+    "unplugin-swc": "1.5.11",
+    "vitest": "3.2.7"
+  },
+  "engines": {
+    "node": ">=20.6.0"
+  },
+  "keywords": [
+    "adonisjs",
+    "adonis",
+    "crdt",
+    "yjs",
+    "automerge",
+    "collaboration",
+    "websocket",
+    "realtime",
+    "agora"
+  ]
+}