Node.js V4→V5 API Migration Guide

I need help migrating a Ditto Node.js application from v4 to v5. Focus on these critical changes:

INITIALIZATION:
Replace `new Ditto(identity, path)` with `await Ditto.open(config)` using async/await.
- Create a `DittoConfig` with `databaseID` and a connect mode object
- `{ type: 'onlinePlayground', appID, token }` → `new DittoConfig(databaseID, { mode: 'server', url: 'https://<databaseID>.cloud.ditto.live' })`
- `{ type: 'onlineWithAuthentication', appID, authHandler }` → `new DittoConfig(databaseID, { mode: 'server', url })` + `auth.setExpirationHandler()`
- `{ type: 'offlinePlayground', appID }` → `new DittoConfig(databaseID, { mode: 'smallPeersOnly' })`
- `{ type: 'sharedKey', appID, sharedKey }` → `new DittoConfig(databaseID, { mode: 'smallPeersOnly', privateKey: sharedKey })`
- `{ type: 'manual', certificate }` → **No replacement** — removed in v5
- The Ditto constructor is now private. You MUST use `Ditto.open(config)` (async) or `Ditto.openSync(config)` (sync).
- Remove `disableSyncWithV3()` calls — v3 protocol is fully dropped in v5
- Remove `updateTransportConfig` workaround patterns for adding websocket URLs — `DittoConfig` handles the server URL directly. Note: `updateTransportConfig()` itself still exists in v5 for advanced transport configuration
- Remove `ditto.store.execute("ALTER SYSTEM SET DQL_STRICT_MODE = false")` — v5 defaults to `false`
- IMPORTANT: If your v4 app used the default (strict=true), set `DQL_STRICT_MODE=true` BEFORE starting sync to maintain v4 behavior

SYNC:
The sync API moved from top-level Ditto methods to the `ditto.sync` sub-object.
- `ditto.startSync()` → `ditto.sync.start()`
- `ditto.stopSync()` → `ditto.sync.stop()`
- `ditto.isSyncActive` → `ditto.sync.isActive`

AUTHENTICATION:
The `AuthenticationHandler` callback interface is removed. Replace with `setExpirationHandler` + `login()`.
- Set `await ditto.auth.setExpirationHandler(async (ditto, timeUntilExpiration) => { ... })` after Ditto.open()
- Handler signature: `(ditto: Ditto, timeUntilExpiration: number) => Promise<any> | any`
- Inside the handler, call `await ditto.auth.login(token, provider)` which returns `{ clientInfo, error }`
- Use `Authenticator.DEVELOPMENT_PROVIDER` for playground/dev tokens
- The handler is called for both initial auth and token refresh — check `timeUntilExpiration`
- `auth.loginWithToken(token, provider)` → removed, use `auth.login(token, provider)` instead
- `auth.loginWithUsernameAndPassword(u, p, provider)` → removed, use `auth.login(token, provider)` instead
- New: `auth.observeStatus(callback)` lets you observe auth status changes

OBSERVERS:
The `registerObserver` API is callback-based with simplified generic type parameters.
- `StoreObserver<T, U>` → `StoreObserver` (single type param `<T>` optional)
- `observer.cancel()` is unchanged
- `StoreObserver.liveQueryID` property is removed
- IMPORTANT: Parameter order changed — `registerObserver(query, handler, queryArguments?)` — handler comes BEFORE args

COLLECTION API → DQL:
The entire Collection/Document API is removed. Replace all collection operations with DQL via `store.execute()`.
- `store.collection(name)` → removed. Use `store.execute('SELECT * FROM <name>')`
- `store.collections()` → removed
- `store.collectionNames()` → removed, no replacement
- `collection.findAll().exec()` → `store.execute('SELECT * FROM <name>')`
- `collection.find(query).exec()` → `store.execute('SELECT * FROM <name> WHERE ...')`
- `collection.findByID(id).exec()` → `store.execute('SELECT * FROM <name> WHERE _id = :id', { id })`
- `collection.upsert(value)` → `store.execute('INSERT INTO <name> DOCUMENTS (:doc)', { doc: value })`
- `collection.findByID(id).update(fn)` → `store.execute('UPDATE <name> SET ... WHERE _id = :id', { id })`
- `collection.findByID(id).remove()` → `store.execute('DELETE FROM <name> WHERE _id = :id', { id })`
- `collection.findByID(id).evict()` → `store.execute('EVICT FROM <name> WHERE _id = :id', { id })`
- Always use parameterized queries with `:paramName` — NEVER use string interpolation

LIVE QUERIES → STORE OBSERVERS:
- `collection.findAll().observeLocal(handler)` → `store.registerObserver('SELECT * FROM <name>', handler)`
- `liveQuery.stop()` → `observer.cancel()`
- The `LiveQuery` class, `LiveQueryEvent` type, and the entire callback shape are different:
  - v4 handler: `(docs, event) => { ... }` where docs is an array of Document objects
  - v5 handler: `(result) => { ... }` where result is a QueryResult with `.items` property containing plain objects

SUBSCRIPTIONS:
- `collection.findAll().subscribe()` → `sync.registerSubscription('SELECT * FROM <name>')`
- `Subscription` class → replaced by `SyncSubscription`
- `SyncSubscription<T>` generics removed → plain `SyncSubscription`
- `syncSubscription.queryArgumentsCBOR` → renamed to `syncSubscription.queryArgumentsCBORData`

TRANSACTIONS:
- `store.write(callback)` → `store.transaction(scope, options?)`
- v4: `txn.scoped('name').upsert(value)` → v5: `txn.execute('INSERT INTO <name> DOCUMENTS (:doc)', { doc: value })`
- `WriteTransaction` / `WriteTransactionCollection` / `WriteTransactionResult` classes are all removed

PRESENCE:
- `peer.peerKeyString` → `peer.peerKey` (peerKey is now a string directly, not Uint8Array)
- `peer.peerKey` (was Uint8Array) → `peer.peerKey` (now string)
- `peer.address` → removed (Address type removed entirely)
- `peer.isConnectedToDittoCloud` → `peer.isConnectedToDittoServer`
- `peer.isCompatible` → new optional boolean property
- `connection.peerKeyString1` / `peerKeyString2` → `connection.peer1` / `connection.peer2` (now strings)
- `connection.approximateDistanceInMeters` → removed
- `connectionRequest.peerKeyString` → `connectionRequest.peerKey`
- `ditto.observePeers(callback)` → `ditto.presence.observe(callback)`
- `Address` type / `addressToString()` → removed
- `PresenceManager` class → removed

ATTACHMENTS:
- `AttachmentToken` class → replaced by plain objects `{ id: string, len: number | bigint, metadata }`
- `TypedAttachmentToken` → renamed to `TypedAttachmentTokenV1` (marked `@internal`)
- `Attachment.len` type: `number | BigInt` → `number | bigint` (lowercase)
- `fetchAttachment(AttachmentToken, handler)` → `fetchAttachment({ id, len, metadata }, handler)` (plain object only)
- `AttachmentFetcher.attachment` promise: v4 could resolve to `null` on deletion → v5 rejects with `DittoError` instead

DITTO CLASS:
- `new Ditto(identity, path)` → `await Ditto.open(config)` or `Ditto.openSync(config)` (constructor private)
- `ditto.appID` → `ditto.config.databaseID`
- `ditto.identity` → `ditto.config`
- `ditto.path` / `ditto.persistenceDirectory` → `ditto.absolutePersistenceDirectory`
- `ditto.siteID` → removed
- `ditto.sdkVersion` → use `Ditto.VERSION` (static property)
- `ditto.runGarbageCollection()` → removed (automatic in v5)
- `ditto.disableSyncWithV3()` → removed (v3 protocol dropped)
- `ditto.observePeers(callback)` → `ditto.presence.observe(callback)`

LOGGER:
- `Logger.setLogFile(path)` → removed
- `Logger.setLogFileURL(url)` → removed
- `Logger.emojiLogLevelHeadingsEnabled` → removed
- `Logger.exportToFile(path)` — still available
- `Logger.enabled` / `Logger.minimumLogLevel` / `Logger.setCustomLogCallback()` — still available

ERRORS:
- `DittoError(code, message, context)` → `DittoError(code, message)` — context parameter removed
- `DittoError.context` property → removed
- Error code `'sdk/unsupported'` → `'unsupported'`
- Error code `'internal/unknown-error'` → `'unknown'`

TRANSPORT CONFIG:
- `TransportConfigListenHTTP.staticContentPath` → removed
- Default `websocketSync` changed from `true` to `false` — explicitly set `true` if your app needs it

TYPES:
- `BigInt` → `bigint` (lowercase) across the entire SDK
- `QueryResult.mutatedDocumentIDs()` → removed, use `QueryResult.mutatedDocumentIDsV2()` which returns `any[]`
- `StoreObserver<T, U>` → `StoreObserver` (no generics)
- `SyncSubscription<T>` → `SyncSubscription` (no generics)

REMOVED CLASSES (no replacement):
- `Document` / `MutableDocument` — DQL returns plain objects
- `DocumentID` / `DocumentPath` / `MutableDocumentPath`
- `Counter` / `Register` CRDT types
- `Collection` / `PendingCursorOperation` / `PendingIDSpecificOperation` / `PendingCollectionsOperation`
- `LiveQuery` / `LiveQueryEvent`
- `WriteTransaction` / `WriteTransactionCollection` / `WriteTransactionResult`
- `UpdateResult` / `UpdateResultsMap`
- `PresenceManager`

NEW APIs:
- `Ditto.open(config): Promise<Ditto>` — async factory
- `Ditto.openSync(config): Ditto` — sync factory
- `DittoConfig(id, connect, persistenceDir?)` — replaces Identity system
- `DittoConfig.DEFAULT_DATABASE_ID` / `.default` / `.copy()`
- `DittoConfigConnectServer` — `{ mode: 'server', url: string }`
- `DittoConfigConnectSmallPeersOnly` — `{ mode: 'smallPeersOnly', privateKey?: string }`
- `auth.login(token, provider): Promise<LoginResult>` — returns `{ clientInfo, error }`
- `Authenticator.DEVELOPMENT_PROVIDER` — static constant for dev provider
- `auth.observeStatus(callback): Observer` — observe auth changes
- `store.transaction(scope, options?)` — DQL-based transaction
- `store.registerObserverWithSignalNext(query, handler, args?)` — back-pressure control
- `StoreObserver.queryArgumentsCBORData` / `.queryArgumentsJSONString` — introspection
- `SyncSubscription.queryArgumentsCBORData` / `.queryArgumentsJSONString` — introspection
- `Peer.isCompatible` — optional peer compatibility flag
- `Peer.isConnectedToDittoServer` — replaces `isConnectedToDittoCloud`

BEFORE (v4):
```typescript
import { Ditto } from '@dittolive/ditto'

await init();

const ditto = new Ditto(
  {
    type: 'onlinePlayground',
    appID: 'your-app-id',
    token: 'your-token',
    customAuthURL: 'https://your-server.ditto.live',
  },
  '/data/ditto'
)

ditto.updateTransportConfig((config) => {
  config.connect.websocketURLs.add('wss://...')
})
ditto.disableSyncWithV3()
await ditto.store.execute("ALTER SYSTEM SET DQL_STRICT_MODE = false")
ditto.startSync()

// Presence
ditto.observePeers((peers) => {
  peers.forEach((peer) => {
    console.log(peer.peerKeyString, peer.isConnectedToDittoCloud)
  })
})

// Cleanup
ditto.stopSync()
await ditto.close()
```

AFTER (v5):
```typescript
import { Ditto, DittoConfig, Authenticator } from '@dittolive/ditto'

const databaseID = 'your-database-id'
const config = new DittoConfig(databaseID, {
  mode: 'server',
  url: 'https://your-server.ditto.live',
})

const ditto = await Ditto.open(config)

await ditto.auth.setExpirationHandler(async (ditto, timeUntilExpiration) => {
  try {
    const result = await ditto.auth.login('your-token', Authenticator.DEVELOPMENT_PROVIDER)
    if (result.error) {
      console.error(`Auth failed: ${result.error}, time until expiration: ${timeUntilExpiration}`)
    }
  } catch (error) {
    console.error(`Auth exception: ${error}`)
  }
})

// If maintaining v4 behavior, set strict mode BEFORE starting sync
// await ditto.store.execute("ALTER SYSTEM SET DQL_STRICT_MODE = true")

ditto.sync.start()

// Store observer (replaces live query)
const observer = ditto.store.registerObserver('SELECT * FROM cars', (result) => {
  updateUI(result.items)
})

// Sync subscription (replaces collection subscription)
const subscription = ditto.sync.registerSubscription('SELECT * FROM cars')

// Presence
ditto.presence.observe((graph) => {
  const allPeers = [graph.localPeer, ...graph.remotePeers]
  allPeers.forEach((peer) => {
    console.log(peer.peerKey, peer.isConnectedToDittoServer)
  })
})

// Cleanup
subscription.cancel()
ditto.sync.stop()
await ditto.close()
```

CHECKLIST:
- Replace `new Ditto(identity, path)` with `await Ditto.open(new DittoConfig(...))`
- Add `await` for initialization — `Ditto.open()` is async
- Create `DittoConfig` with `databaseID` and connect mode (`server` or `smallPeersOnly`)
- Set `DQL_STRICT_MODE=true` BEFORE `sync.start()` if maintaining v4 strict behavior
- Set up `auth.setExpirationHandler()` and use `auth.login()` for authentication
- Replace `ditto.startSync()` / `stopSync()` with `ditto.sync.start()` / `stop()`
- Replace `ditto.isSyncActive` with `ditto.sync.isActive`
- Replace all `store.collection('x')` calls with `store.execute()` DQL queries
- Use parameterized DQL queries (`:paramName`) — never string interpolation
- Replace `collection.upsert()` with `INSERT INTO ... DOCUMENTS (:doc)`
- Replace `collection.findByID(id).update()` with `UPDATE ... SET ... WHERE _id = :id`
- Replace `collection.findByID(id).remove()` with `DELETE FROM ... WHERE _id = :id`
- Replace `collection.findAll().observeLocal(handler)` with `store.registerObserver(query, handler)`
- Note: v5 registerObserver parameter order is (query, handler, args?) — handler before args
- Replace `liveQuery.stop()` with `observer.cancel()`
- Replace `collection.findAll().subscribe()` with `sync.registerSubscription(query)`
- Replace `store.write()` with `store.transaction()`
- Replace `auth.loginWithToken()` with `auth.login()`
- Remove `AuthenticationHandler` interface usage
- Remove `disableSyncWithV3()` calls
- Remove `updateTransportConfig` workaround patterns for websocket URLs (method still exists for advanced use)
- Update `peer.peerKeyString` → `peer.peerKey`
- Update `peer.isConnectedToDittoCloud` → `peer.isConnectedToDittoServer`
- Update `connection.peerKeyString1`/`peerKeyString2` → `connection.peer1`/`peer2`
- Update `connectionRequest.peerKeyString` → `connectionRequest.peerKey`
- Replace `ditto.observePeers()` with `ditto.presence.observe()`
- Update `AttachmentToken` class usage to plain `{ id, len, metadata }` objects
- Update `BigInt` type annotations to lowercase `bigint`
- Remove `Logger.setLogFile()` / `Logger.emojiLogLevelHeadingsEnabled` calls
- Remove `DittoError.context` usage
- Set `websocketSync = true` explicitly if your app relied on the v4 default of `true`
- Remove generic type parameters from `StoreObserver<T, U>` and `SyncSubscription<T>`

Work through the codebase systematically. Show me each file's changes.