@feathersdev/automerge 0.11.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# [0.11.0](https://github.com/feathersdev/app/compare/v0.10.1...v0.11.0) (2025-05-25)
+
+
+### Features
+
+* Basic Automerge feature integration ([#275](https://github.com/feathersdev/app/issues/275)) ([3ccc80c](https://github.com/feathersdev/app/commit/3ccc80cdd02db52fc32d7e1566b844ef211c2c0f))

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Feathers Cloud Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# @feathersdev/automerge
+
+Feathers local-first data synchronization using Automerge.

package/esm/index.d.ts

@@ -0,0 +1,32 @@
+import type { AnyDocumentId, StorageAdapterInterface } from '@automerge/automerge-repo';
+import type { FeathersAuthClient } from '@feathersdev/auth';
+import { Repo } from '@automerge/automerge-repo';
+export * from '@automerge/automerge-repo';
+export interface AutomergeClientOptions {
+    storage: StorageAdapterInterface;
+    syncUrl: string;
+}
+export declare const syncUrl = "https://sync.feathers.dev";
+export declare class AutomergeClient {
+    client: FeathersAuthClient;
+    options: AutomergeClientOptions;
+    private repo?;
+    constructor(client: FeathersAuthClient, options: AutomergeClientOptions);
+    private getDocFromToken;
+    connect(): Promise<Repo>;
+    /**
+     * Retrieve an Automerge document handle. Will use the auth application
+     * document if no id is passed.
+     *
+     * @param _id The Automerge document id or nothing when using the application document
+     * @returns The document handle
+     */
+    find<T = unknown>(_id?: AnyDocumentId): Promise<import("@automerge/automerge-repo").DocHandle<T>>;
+}
+/**
+ * Create an Automerge client for Feathers
+ *
+ * @param client The feathers auth client
+ * @returns A new Automerge client instance
+ */
+export declare function createAutomerge(client: FeathersAuthClient, options?: Partial<AutomergeClientOptions>): AutomergeClient;

package/esm/index.js

@@ -0,0 +1,58 @@
+import { Repo } from '@automerge/automerge-repo';
+import { BrowserWebSocketClientAdapter } from '@automerge/automerge-repo-network-websocket';
+import { IndexedDBStorageAdapter } from '@automerge/automerge-repo-storage-indexeddb';
+import { verifyToken } from '@feathersdev/auth/internals';
+export * from '@automerge/automerge-repo';
+export const syncUrl = 'https://sync.feathers.dev';
+export class AutomergeClient {
+    constructor(client, options) {
+        this.client = client;
+        this.options = options;
+    }
+    async getDocFromToken() {
+        const getAccessToken = await this.client.getAccessToken();
+        const { payload } = await verifyToken(getAccessToken);
+        return payload.doc;
+    }
+    async connect() {
+        if (!this.repo) {
+            const { syncUrl, storage } = this.options;
+            const token = await this.client.getAccessToken();
+            const wsUrl = `${syncUrl}?authorization=${token}`;
+            this.repo = new Repo({
+                network: [new BrowserWebSocketClientAdapter(wsUrl)],
+                storage,
+            });
+        }
+        return this.repo;
+    }
+    /**
+     * Retrieve an Automerge document handle. Will use the auth application
+     * document if no id is passed.
+     *
+     * @param _id The Automerge document id or nothing when using the application document
+     * @returns The document handle
+     */
+    async find(_id) {
+        const id = _id ?? (await this.getDocFromToken());
+        if (!id) {
+            throw new Error('Invalid document id');
+        }
+        const repo = await this.connect();
+        return repo.find(id);
+    }
+}
+/**
+ * Create an Automerge client for Feathers
+ *
+ * @param client The feathers auth client
+ * @returns A new Automerge client instance
+ */
+export function createAutomerge(client, options) {
+    const storage = options?.storage ?? new IndexedDBStorageAdapter();
+    return new AutomergeClient(client, {
+        storage,
+        syncUrl,
+        ...options,
+    });
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@feathersdev/automerge",
+  "type": "module",
+  "version": "0.11.0",
+  "description": "Feathers local-first data synchronization using Automerge",
+  "author": {
+    "name": "Feathers Cloud Inc.",
+    "email": "hello@feathers.dev",
+    "url": "https://feathers.dev"
+  },
+  "contributors": [],
+  "license": "MIT",
+  "homepage": "https://feathers.dev",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/feathersdev/app.git",
+    "directory": "packages/automerge"
+  },
+  "keywords": [
+    "feathersdev"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./esm/index.js",
+  "files": [
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "esm/**",
+    "lib/**",
+    "src/**"
+  ],
+  "engines": {
+    "node": ">= 18"
+  },
+  "scripts": {
+    "prepublish": "pnpm compile",
+    "compile": "shx rm -rf esm/ && npx tsc --outDir esm/"
+  },
+  "directories": {
+    "lib": "lib"
+  },
+  "dependencies": {
+    "@automerge/automerge-repo": "^1.2.1",
+    "@automerge/automerge-repo-network-websocket": "^1.2.1",
+    "@automerge/automerge-repo-storage-indexeddb": "^1.2.1",
+    "@feathersdev/auth": "^0.11.0"
+  },
+  "devDependencies": {
+    "@vitest/browser": "^3.1.2"
+  },
+  "gitHead": "c39ce0034f664037faf0e4be4ca209309835bfa4"
+}

package/src/index.ts

@@ -0,0 +1,80 @@
+import type { AnyDocumentId, StorageAdapterInterface } from '@automerge/automerge-repo'
+import type { FeathersAuthClient } from '@feathersdev/auth'
+import { Repo } from '@automerge/automerge-repo'
+import { BrowserWebSocketClientAdapter } from '@automerge/automerge-repo-network-websocket'
+import { IndexedDBStorageAdapter } from '@automerge/automerge-repo-storage-indexeddb'
+import { verifyToken } from '@feathersdev/auth/internals'
+
+export * from '@automerge/automerge-repo'
+
+export interface AutomergeClientOptions {
+  storage: StorageAdapterInterface
+  syncUrl: string
+}
+
+export const syncUrl = 'https://sync.feathers.dev'
+
+export class AutomergeClient {
+  private repo?: Repo
+
+  constructor(
+    public client: FeathersAuthClient,
+    public options: AutomergeClientOptions,
+  ) {}
+
+  private async getDocFromToken() {
+    const getAccessToken = await this.client.getAccessToken()
+    const { payload } = await verifyToken<{ doc?: string }>(getAccessToken)
+    return payload.doc
+  }
+
+  async connect() {
+    if (!this.repo) {
+      const { syncUrl, storage } = this.options
+      const token = await this.client.getAccessToken()
+      const wsUrl = `${syncUrl}?authorization=${token}`
+
+      this.repo = new Repo({
+        network: [new BrowserWebSocketClientAdapter(wsUrl)],
+        storage,
+      })
+    }
+
+    return this.repo
+  }
+
+  /**
+   * Retrieve an Automerge document handle. Will use the auth application
+   * document if no id is passed.
+   *
+   * @param _id The Automerge document id or nothing when using the application document
+   * @returns The document handle
+   */
+  async find<T = unknown>(_id?: AnyDocumentId) {
+    const id = _id ?? (await this.getDocFromToken())
+
+    if (!id) {
+      throw new Error('Invalid document id')
+    }
+
+    const repo = await this.connect()
+
+    return repo.find<T>(id as AnyDocumentId)
+  }
+}
+
+/**
+ * Create an Automerge client for Feathers
+ *
+ * @param client The feathers auth client
+ * @returns A new Automerge client instance
+ */
+export function createAutomerge(client: FeathersAuthClient, options?: Partial<AutomergeClientOptions>) {
+  const storage = options?.storage ?? new IndexedDBStorageAdapter()
+
+  return new AutomergeClient(client, {
+    storage,
+    syncUrl,
+    ...options,
+  })
+}