@automerge/automerge-repo 1.0.0-alpha.2 → 1.0.0-alpha.4

package/src/DocHandle.ts

@@ -1,6 +1,6 @@
-import * as A from "@automerge/automerge"
+import * as A from "@automerge/automerge/next"
 import debug from "debug"
-import EventEmitter from "eventemitter3"
+import { EventEmitter } from "eventemitter3"
 import {
   assign,
   BaseActionObject,
@@ -17,8 +17,9 @@ import { waitFor } from "xstate/lib/waitFor.js"
 import { headsAreSame } from "./helpers/headsAreSame.js"
 import { pause } from "./helpers/pause.js"
 import { TimeoutError, withTimeout } from "./helpers/withTimeout.js"
-import type { ChannelId, DocumentId, PeerId, AutomergeUrl } from "./types.js"
+import type { DocumentId, PeerId, AutomergeUrl } from "./types.js"
 import { stringifyAutomergeUrl } from "./DocUrl.js"
+import { encode } from "./helpers/cbor.js"
 
 /** DocHandle is a wrapper around a single Automerge document that lets us listen for changes. */
 export class DocHandle<T> //
@@ -42,7 +43,12 @@ export class DocHandle<T> //
     this.#log = debug(`automerge-repo:dochandle:${this.documentId.slice(0, 5)}`)
 
     // initial doc
-    const doc = A.init<T>()
+    let doc = A.init<T>()
+
+    // Make an empty change so that we have something to save to disk
+    if (isNew) {
+      doc = A.emptyChange(doc, {})
+    }
 
     /**
      * Internally we use a state machine to orchestrate document loading and/or syncing, in order to
@@ -81,6 +87,8 @@ export class DocHandle<T> //
                 UPDATE: { actions: "onUpdate", target: READY },
                 // REQUEST is called by the Repo if the document is not found in storage
                 REQUEST: { target: REQUESTING },
+                // AWAIT_NETWORK is called by the repo if the document is not found in storage but the network is not yet ready
+                AWAIT_NETWORK: { target: AWAITING_NETWORK },
                 DELETE: { actions: "onDelete", target: DELETED },
               },
               after: [
@@ -90,8 +98,17 @@ export class DocHandle<T> //
                 },
               ],
             },
+            awaitingNetwork: {
+              on: {
+                NETWORK_READY: { target: REQUESTING },
+              }
+            },
             requesting: {
               on: {
+                MARK_UNAVAILABLE: {
+                  target: UNAVAILABLE,
+                  actions: "onUnavailable",
+                },
                 // UPDATE is called by the Repo when we receive changes from the network
                 UPDATE: { actions: "onUpdate" },
                 // REQUEST_COMPLETE is called from `onUpdate` when the doc has been fully loaded from the network
@@ -118,6 +135,14 @@ export class DocHandle<T> //
             deleted: {
               type: "final",
             },
+            unavailable: {
+              on: {
+                UPDATE: { actions: "onUpdate" },
+                // REQUEST_COMPLETE is called from `onUpdate` when the doc has been fully loaded from the network
+                REQUEST_COMPLETE: { target: READY },
+                DELETE: { actions: "onDelete", target: DELETED },
+              },
+            },
           },
         },
 
@@ -136,6 +161,12 @@ export class DocHandle<T> //
               this.emit("delete", { handle: this })
               return { doc: undefined }
             }),
+            onUnavailable: assign(context => {
+              const { doc } = context
+
+              this.emit("unavailable", { handle: this })
+              return { doc }
+            }),
           },
         }
       )
@@ -144,9 +175,12 @@ export class DocHandle<T> //
         const oldDoc = history?.context?.doc
         const newDoc = context.doc
 
-        console.log(`${event} → ${state}`, newDoc)
+        this.#log(`${history?.value}: ${event.type} → ${state}`, newDoc)
 
-        const docChanged = newDoc && oldDoc && !headsAreSame(A.getHeads(newDoc), A.getHeads(oldDoc))
+        const docChanged =
+          newDoc &&
+          oldDoc &&
+          !headsAreSame(A.getHeads(newDoc), A.getHeads(oldDoc))
         if (docChanged) {
           this.emit("heads-changed", { handle: this, doc: newDoc })
 
@@ -210,6 +244,7 @@ export class DocHandle<T> //
    * @returns true if the document has been marked as deleted
    */
   isDeleted = () => this.inState([HandleState.DELETED])
+  isUnavailable = () => this.inState([HandleState.UNAVAILABLE])
   inState = (states: HandleState[]) =>
     states.some(this.#machine?.getSnapshot().matches)
 
@@ -234,7 +269,9 @@ export class DocHandle<T> //
    *
    * @param {awaitStates=[READY]} optional states to wait for, such as "LOADING". mostly for internal use.
    */
-  async doc(awaitStates: HandleState[] = [READY]): Promise<A.Doc<T>> {
+  async doc(
+    awaitStates: HandleState[] = [READY, UNAVAILABLE]
+  ): Promise<A.Doc<T> | undefined> {
     await pause() // yield one tick because reasons
     try {
       // wait for the document to enter one of the desired states
@@ -245,7 +282,7 @@ export class DocHandle<T> //
       else throw error
     }
     // Return the document
-    return this.#doc
+    return !this.isUnavailable() ? this.#doc : undefined
   }
 
   /**
@@ -308,15 +345,40 @@ export class DocHandle<T> //
     })
   }
 
+  unavailable() {
+    this.#machine.send(MARK_UNAVAILABLE)
+  }
+
   /** `request` is called by the repo when the document is not found in storage */
   request() {
     if (this.#state === LOADING) this.#machine.send(REQUEST)
   }
 
+  awaitNetwork() {
+    if (this.#state === LOADING) this.#machine.send(AWAIT_NETWORK)
+  }
+
+  networkReady() {
+    if (this.#state === AWAITING_NETWORK) this.#machine.send(NETWORK_READY)
+  }
+
   /** `delete` is called by the repo when the document is deleted */
   delete() {
     this.#machine.send(DELETE)
   }
+
+  /** `broadcast` sends an arbitrary ephemeral message out to all reachable peers who would receive sync messages from you
+   * it has no guarantee of delivery, and is not persisted to the underlying automerge doc in any way.
+   * messages will have a sending PeerId but this is *not* a useful user identifier.
+   * a user could have multiple tabs open and would appear as multiple PeerIds.
+   * every message source must have a unique PeerId.
+   */
+  broadcast(message: any) {
+    this.emit("ephemeral-message-outbound", {
+      handle: this,
+      data: encode(message),
+    })
+  }
 }
 
 // WRAPPER CLASS TYPES
@@ -328,7 +390,7 @@ interface DocHandleOptions {
 
 export interface DocHandleMessagePayload {
   destinationId: PeerId
-  channelId: ChannelId
+  documentId: DocumentId
   data: Uint8Array
 }
 
@@ -348,10 +410,26 @@ export interface DocHandleChangePayload<T> {
   patchInfo: A.PatchInfo<T>
 }
 
+export interface DocHandleEphemeralMessagePayload {
+  handle: DocHandle<any>
+  senderId: PeerId
+  message: unknown
+}
+
+export interface DocHandleOutboundEphemeralMessagePayload {
+  handle: DocHandle<any>
+  data: Uint8Array
+}
+
 export interface DocHandleEvents<T> {
   "heads-changed": (payload: DocHandleEncodedChangePayload<T>) => void
   change: (payload: DocHandleChangePayload<T>) => void
   delete: (payload: DocHandleDeletePayload<T>) => void
+  unavailable: (payload: DocHandleDeletePayload<T>) => void
+  "ephemeral-message": (payload: DocHandleEphemeralMessagePayload) => void
+  "ephemeral-message-outbound": (
+    payload: DocHandleOutboundEphemeralMessagePayload
+  ) => void
 }
 
 // STATE MACHINE TYPES
@@ -361,10 +439,12 @@ export interface DocHandleEvents<T> {
 export const HandleState = {
   IDLE: "idle",
   LOADING: "loading",
+  AWAITING_NETWORK: "awaitingNetwork",
   REQUESTING: "requesting",
   READY: "ready",
   FAILED: "failed",
   DELETED: "deleted",
+  UNAVAILABLE: "unavailable",
 } as const
 export type HandleState = (typeof HandleState)[keyof typeof HandleState]
 
@@ -389,9 +469,12 @@ export const Event = {
   FIND: "FIND",
   REQUEST: "REQUEST",
   REQUEST_COMPLETE: "REQUEST_COMPLETE",
+  AWAIT_NETWORK: "AWAIT_NETWORK",
+  NETWORK_READY: "NETWORK_READY",
   UPDATE: "UPDATE",
   TIMEOUT: "TIMEOUT",
   DELETE: "DELETE",
+  MARK_UNAVAILABLE: "MARK_UNAVAILABLE",
 } as const
 type Event = (typeof Event)[keyof typeof Event]
 
@@ -405,6 +488,9 @@ type UpdateEvent<T> = {
   payload: { callback: (doc: A.Doc<T>) => A.Doc<T> }
 }
 type TimeoutEvent = { type: typeof TIMEOUT }
+type MarkUnavailableEvent = { type: typeof MARK_UNAVAILABLE }
+type AwaitNetworkEvent = { type: typeof AWAIT_NETWORK }
+type NetworkReadyEvent = { type: typeof NETWORK_READY }
 
 type DocHandleEvent<T> =
   | CreateEvent
@@ -414,6 +500,9 @@ type DocHandleEvent<T> =
   | UpdateEvent<T>
   | TimeoutEvent
   | DeleteEvent
+  | MarkUnavailableEvent
+  | AwaitNetworkEvent 
+  | NetworkReadyEvent
 
 type DocHandleXstateMachine<T> = Interpreter<
   DocHandleContext<T>,
@@ -432,7 +521,25 @@ type DocHandleXstateMachine<T> = Interpreter<
 >
 
 // CONSTANTS
-
-export const { IDLE, LOADING, REQUESTING, READY, FAILED, DELETED } = HandleState
-const { CREATE, FIND, REQUEST, UPDATE, TIMEOUT, DELETE, REQUEST_COMPLETE } =
-  Event
+export const {
+  IDLE,
+  LOADING,
+  AWAITING_NETWORK,
+  REQUESTING,
+  READY,
+  FAILED,
+  DELETED,
+  UNAVAILABLE,
+} = HandleState
+const {
+  CREATE,
+  FIND,
+  REQUEST,
+  UPDATE,
+  TIMEOUT,
+  DELETE,
+  REQUEST_COMPLETE,
+  MARK_UNAVAILABLE,
+  AWAIT_NETWORK,
+  NETWORK_READY
+} = Event

package/src/DocUrl.ts

@@ -2,7 +2,7 @@ import {
   type AutomergeUrl,
   type BinaryDocumentId,
   type DocumentId,
-} from "./types"
+} from "./types.js"
 import { v4 as uuid } from "uuid"
 import bs58check from "bs58check"
 
@@ -12,12 +12,12 @@ export const urlPrefix = "automerge:"
  * given an Automerge URL, return a decoded DocumentId (and the encoded DocumentId)
  *
  * @param url
- * @returns { documentId: Uint8Array(16), encodedDocumentId: bs58check.encode(documentId) }
+ * @returns { binaryDocumentId: BinaryDocumentId, documentId: DocumentId }
  */
 export const parseAutomergeUrl = (url: AutomergeUrl) => {
-  const { binaryDocumentId: binaryDocumentId, encodedDocumentId } = parts(url)
+  const { binaryDocumentId, documentId } = parts(url)
   if (!binaryDocumentId) throw new Error("Invalid document URL: " + url)
-  return { binaryDocumentId, encodedDocumentId }
+  return { binaryDocumentId, documentId }
 }
 
 interface StringifyAutomergeUrlOptions {
@@ -28,7 +28,7 @@ interface StringifyAutomergeUrlOptions {
  * Given a documentId in either canonical form, return an Automerge URL
  * Throws on invalid input.
  * Note: this is an object because we anticipate adding fields in the future.
- * @param { documentId: EncodedDocumentId | DocumentId }
+ * @param { documentId: BinaryDocumentId | DocumentId }
  * @returns AutomergeUrl
  */
 export const stringifyAutomergeUrl = ({
@@ -79,12 +79,12 @@ export const binaryToDocumentId = (docId: BinaryDocumentId): DocumentId =>
  * eventually this could include things like heads, so we use this structure
  * we return both a binary & string-encoded version of the document ID
  * @param str
- * @returns { binaryDocumentId, encodedDocumentId }
+ * @returns { binaryDocumentId, documentId }
  */
 const parts = (str: string) => {
   const regex = new RegExp(`^${urlPrefix}(\\w+)$`)
-  const [m, docMatch] = str.match(regex) || []
-  const encodedDocumentId = docMatch as DocumentId
-  const binaryDocumentId = documentIdToBinary(encodedDocumentId)
-  return { binaryDocumentId, encodedDocumentId }
+  const [_, docMatch] = str.match(regex) || []
+  const documentId = docMatch as DocumentId
+  const binaryDocumentId = documentIdToBinary(documentId)
+  return { binaryDocumentId, documentId }
 }

package/src/EphemeralData.ts

@@ -1,46 +1,16 @@
-import { decode, encode } from "cbor-x"
-import EventEmitter from "eventemitter3"
-import { ChannelId, PeerId } from "./index.js"
-import { MessagePayload } from "./network/NetworkAdapter.js"
-
-/**
- * EphemeralData provides a mechanism to broadcast short-lived data — cursor positions, presence,
- * heartbeats, etc. — that is useful in the moment but not worth persisting.
- */
-export class EphemeralData extends EventEmitter<EphemeralDataMessageEvents> {
-  /** Broadcast an ephemeral message */
-  broadcast(channelId: ChannelId, message: unknown) {
-    const messageBytes = encode(message)
-
-    this.emit("message", {
-      targetId: "*" as PeerId, // TODO: we don't really need a targetId for broadcast
-      channelId: ("m/" + channelId) as ChannelId,
-      message: messageBytes,
-      broadcast: true,
-    })
-  }
-
-  /** Receive an ephemeral message */
-  receive(senderId: PeerId, grossChannelId: ChannelId, message: Uint8Array) {
-    const data = decode(message)
-    const channelId = grossChannelId.slice(2) as ChannelId
-    this.emit("data", {
-      peerId: senderId,
-      channelId,
-      data,
-    })
-  }
-}
+import { DocumentId, PeerId } from "./index.js"
+import { EphemeralMessageContents } from "./network/messages.js"
 
 // types
+export type SessionId = string & { __SessionId: false }
 
 export interface EphemeralDataPayload {
-  channelId: ChannelId
+  documentId: DocumentId
   peerId: PeerId
-  data: { peerId: PeerId; channelId: ChannelId; data: unknown }
+  data: { peerId: PeerId; documentId: DocumentId; data: unknown }
 }
 
 export type EphemeralDataMessageEvents = {
-  message: (event: MessagePayload) => void
+  message: (event: EphemeralMessageContents) => void
   data: (event: EphemeralDataPayload) => void
 }

package/src/Repo.ts

@@ -1,5 +1,5 @@
+import debug from "debug"
 import { DocCollection } from "./DocCollection.js"
-import { EphemeralData } from "./EphemeralData.js"
 import { NetworkAdapter } from "./network/NetworkAdapter.js"
 import { NetworkSubsystem } from "./network/NetworkSubsystem.js"
 import { StorageAdapter } from "./storage/StorageAdapter.js"
@@ -7,15 +7,12 @@ import { StorageSubsystem } from "./storage/StorageSubsystem.js"
 import { CollectionSynchronizer } from "./synchronizer/CollectionSynchronizer.js"
 import { DocumentId, PeerId } from "./types.js"
 
-import debug from "debug"
-
 /** A Repo is a DocCollection with networking, syncing, and storage capabilities. */
 export class Repo extends DocCollection {
   #log: debug.Debugger
 
   networkSubsystem: NetworkSubsystem
   storageSubsystem?: StorageSubsystem
-  ephemeralData: EphemeralData
 
   constructor({ storage, network, peerId, sharePolicy }: RepoConfig) {
     super()
@@ -26,58 +23,75 @@ export class Repo extends DocCollection {
 
     // The `document` event is fired by the DocCollection any time we create a new document or look
     // up a document by ID. We listen for it in order to wire up storage and network synchronization.
-    this.on("document", async ({ handle }) => {
+    this.on("document", async ({ handle, isNew }) => {
       if (storageSubsystem) {
         // Save when the document changes
         handle.on("heads-changed", async ({ handle, doc }) => {
           await storageSubsystem.saveDoc(handle.documentId, doc)
         })
 
-        // Try to load from disk
-        const loadedDoc = await storageSubsystem.loadDoc(handle.documentId)
-        if (loadedDoc) {
-          handle.update(() => loadedDoc)
+        if (isNew) {
+          // this is a new document, immediately save it
+          await storageSubsystem.saveDoc(handle.documentId, handle.docSync()!)
+        } else {
+          // Try to load from disk
+          const loadedDoc = await storageSubsystem.loadDoc(handle.documentId)
+          if (loadedDoc) {
+            handle.update(() => loadedDoc)
+          }
         }
       }
 
-      handle.request()
+      handle.on("unavailable", () => {
+        this.#log("document unavailable", { documentId: handle.documentId })
+        this.emit("unavailable-document", {
+          documentId: handle.documentId,
+        })
+      })
+
+      if (this.networkSubsystem.isReady()) {
+        handle.request()
+      } else {
+        handle.awaitNetwork()
+        this.networkSubsystem.whenReady().then(() => {
+          handle.networkReady()
+        }).catch(err => {
+          this.#log("error waiting for network", { err })
+        })
+      }
 
       // Register the document with the synchronizer. This advertises our interest in the document.
       synchronizer.addDocument(handle.documentId)
     })
 
-    this.on("delete-document", ({ encodedDocumentId }) => {
+    this.on("delete-document", ({ documentId }) => {
       // TODO Pass the delete on to the network
       // synchronizer.removeDocument(documentId)
 
       if (storageSubsystem) {
-        storageSubsystem.remove(encodedDocumentId)
+        storageSubsystem.remove(documentId).catch(err => {
+          this.#log("error deleting document", { documentId, err })
+        })
       }
     })
 
     // SYNCHRONIZER
     // The synchronizer uses the network subsystem to keep documents in sync with peers.
-
     const synchronizer = new CollectionSynchronizer(this)
 
     // When the synchronizer emits sync messages, send them to peers
-    synchronizer.on(
-      "message",
-      ({ targetId, channelId, message, broadcast }) => {
-        this.#log(`sending sync message to ${targetId}`)
-        networkSubsystem.sendMessage(targetId, channelId, message, broadcast)
-      }
-    )
+    synchronizer.on("message", message => {
+      this.#log(`sending sync message to ${message.targetId}`)
+      networkSubsystem.send(message)
+    })
 
     // STORAGE
     // The storage subsystem has access to some form of persistence, and deals with save and loading documents.
-
     const storageSubsystem = storage ? new StorageSubsystem(storage) : undefined
     this.storageSubsystem = storageSubsystem
 
     // NETWORK
     // The network subsystem deals with sending and receiving messages to and from peers.
-
     const networkSubsystem = new NetworkSubsystem(network, peerId)
     this.networkSubsystem = networkSubsystem
 
@@ -94,40 +108,8 @@ export class Repo extends DocCollection {
 
     // Handle incoming messages
     networkSubsystem.on("message", async msg => {
-      const { senderId, channelId, message } = msg
-
-      // TODO: this demands a more principled way of associating channels with recipients
-
-      // Ephemeral channel ids start with "m/"
-      if (channelId.startsWith("m/")) {
-        // Ephemeral message
-        this.#log(`receiving ephemeral message from ${senderId}`)
-        ephemeralData.receive(senderId, channelId, message)
-      } else {
-        // Sync message
-        this.#log(`receiving sync message from ${senderId}`)
-        await synchronizer.receiveSyncMessage(senderId, channelId, message)
-      }
+      await synchronizer.receiveMessage(msg)
     })
-
-    // We establish a special channel for sync messages
-    networkSubsystem.join()
-
-    // EPHEMERAL DATA
-    // The ephemeral data subsystem uses the network to send and receive messages that are not
-    // persisted to storage, e.g. cursor position, presence, etc.
-
-    const ephemeralData = new EphemeralData()
-    this.ephemeralData = ephemeralData
-
-    // Send ephemeral messages to peers
-    ephemeralData.on(
-      "message",
-      ({ targetId, channelId, message, broadcast }) => {
-        this.#log(`sending ephemeral message to ${targetId}`)
-        networkSubsystem.sendMessage(targetId, channelId, message, broadcast)
-      }
-    )
   }
 }
 

package/src/helpers/cbor.ts

@@ -0,0 +1,10 @@
+import { Encoder, decode as cborXdecode } from "cbor-x";
+
+export function encode(obj: any): Buffer {
+  let encoder = new Encoder({tagUint8Array: false})
+  return encoder.encode(obj)
+}
+
+export function decode(buf: Buffer | Uint8Array): any {
+  return cborXdecode(buf)
+}

package/src/helpers/eventPromise.ts

@@ -1,4 +1,4 @@
-import EventEmitter from "eventemitter3"
+import { EventEmitter } from "eventemitter3"
 
 /** Returns a promise that resolves when the given event is emitted on the given emitter. */
 export const eventPromise = (emitter: EventEmitter, event: string) =>

package/src/helpers/headsAreSame.ts

@@ -1,4 +1,4 @@
-import {Heads} from "@automerge/automerge"
+import {Heads} from "@automerge/automerge/next"
 import { arraysAreEqual } from "./arraysAreEqual.js"
 
 export const headsAreSame = (a: Heads, b: Heads) => {

package/src/helpers/tests/network-adapter-tests.ts

@@ -1,7 +1,8 @@
-import { PeerId, Repo, type NetworkAdapter, ChannelId } from "../../index.js"
+import { PeerId, Repo, type NetworkAdapter, DocumentId } from "../../index.js"
 import { eventPromise, eventPromises } from "../eventPromise.js"
 import { assert } from "chai"
 import { describe, it } from "mocha"
+import { pause } from "../pause.js"
 
 /**
  * Runs a series of tests against a set of three peers, each represented by one or more instantiated
@@ -46,7 +47,7 @@ export function runAdapterTests(_setup: SetupFn, title?: string): void {
 
         // Bob receives the change
         await eventPromise(bobHandle, "change")
-        assert.equal((await bobHandle.doc()).foo, "bar")
+        assert.equal((await bobHandle.doc())?.foo, "bar")
 
         // Bob changes the document
         bobHandle.change(d => {
@@ -55,7 +56,7 @@ export function runAdapterTests(_setup: SetupFn, title?: string): void {
 
         // Alice receives the change
         await eventPromise(aliceHandle, "change")
-        assert.equal((await aliceHandle.doc()).foo, "baz")
+        assert.equal((await aliceHandle.doc())?.foo, "baz")
       }
 
       // Run the test in both directions, in case they're different types of adapters
@@ -97,8 +98,8 @@ export function runAdapterTests(_setup: SetupFn, title?: string): void {
 
       // Bob and Charlie receive the change
       await eventPromises([bobHandle, charlieHandle], "change")
-      assert.equal((await bobHandle.doc()).foo, "bar")
-      assert.equal((await charlieHandle.doc()).foo, "bar")
+      assert.equal((await bobHandle.doc())?.foo, "bar")
+      assert.equal((await charlieHandle.doc())?.foo, "bar")
 
       // Charlie changes the document
       charlieHandle.change(d => {
@@ -107,15 +108,13 @@ export function runAdapterTests(_setup: SetupFn, title?: string): void {
 
       // Alice and Bob receive the change
       await eventPromises([aliceHandle, bobHandle], "change")
-      assert.equal((await bobHandle.doc()).foo, "baz")
-      assert.equal((await charlieHandle.doc()).foo, "baz")
+      assert.equal((await bobHandle.doc())?.foo, "baz")
+      assert.equal((await charlieHandle.doc())?.foo, "baz")
 
       teardown()
     })
 
-    // TODO: with BroadcastChannel, this test never ends, because it goes into an infinite loop,
-    // because the network has cycles (see #92)
-    it.skip("can broadcast a message", async () => {
+    it("can broadcast a message", async () => {
       const { adapters, teardown } = await setup()
       const [a, b, c] = adapters
 
@@ -128,13 +127,18 @@ export function runAdapterTests(_setup: SetupFn, title?: string): void {
         "peer"
       )
 
-      const channelId = "broadcast" as ChannelId
+      const aliceHandle = aliceRepo.create<TestDoc>()
+      const charlieHandle = charlieRepo.find(aliceHandle.url)
+
+      // pause to give charlie a chance to let alice know it wants the doc
+      await pause(100)
+
       const alicePresenceData = { presence: "alice" }
+      aliceHandle.broadcast(alicePresenceData)
 
-      aliceRepo.ephemeralData.broadcast(channelId, alicePresenceData)
-      const { data } = await eventPromise(charlieRepo.ephemeralData, "data")
+      const { message } = await eventPromise(charlieHandle, "ephemeral-message")
 
-      assert.deepStrictEqual(data, alicePresenceData)
+      assert.deepStrictEqual(message, alicePresenceData)
       teardown()
     })
   })

package/src/index.ts

@@ -3,12 +3,22 @@ export { DocHandle, HandleState } from "./DocHandle.js"
 export type { DocHandleChangePayload } from "./DocHandle.js"
 export { NetworkAdapter } from "./network/NetworkAdapter.js"
 export type {
-  InboundMessagePayload,
-  MessagePayload,
   OpenPayload,
   PeerCandidatePayload,
   PeerDisconnectedPayload,
 } from "./network/NetworkAdapter.js"
+
+// This is a bit confusing right now, but:
+// Message is the type for messages used outside of the network adapters
+// there are some extra internal network adapter-only messages on NetworkAdapterMessage
+// and Message is (as of this writing) a union type for EphmeralMessage and SyncMessage
+export type {
+  Message,
+  NetworkAdapterMessage,
+  EphemeralMessage,
+  SyncMessage,
+} from "./network/messages.js"
+
 export { NetworkSubsystem } from "./network/NetworkSubsystem.js"
 export { Repo, type SharePolicy } from "./Repo.js"
 export { StorageAdapter, type StorageKey } from "./storage/StorageAdapter.js"
@@ -20,3 +30,5 @@ export {
   stringifyAutomergeUrl as generateAutomergeUrl,
 } from "./DocUrl.js"
 export * from "./types.js"
+
+export * as cbor from "./helpers/cbor.js"