@enbox/agent 0.1.8 → 0.2.0

package/src/types/dwn.ts

@@ -11,7 +11,6 @@ import type {
   MessagesSubscribeReply,
   MessagesSyncMessage,
   MessagesSyncReply,
-  MessageSubscriptionHandler,
   ProtocolsConfigureMessage,
   ProtocolsConfigureOptions,
   ProtocolsQueryMessage,
@@ -28,9 +27,9 @@ import type {
   RecordsSubscribeMessage,
   RecordsSubscribeOptions,
   RecordsSubscribeReply,
-  RecordSubscriptionHandler,
   RecordsWriteMessage,
   RecordsWriteOptions,
+  SubscriptionListener,
 } from '@enbox/dwn-sdk-js';
 
 import type { MessagesSyncOptions } from '@enbox/dwn-sdk-js';
@@ -54,38 +53,37 @@ import {
  * Represents a Decentralized Web Node (DWN) service in a DID Document.
  *
  * A DWN DID service is a specialized type of DID service with the `type` set to
- * `DecentralizedWebNode`. It includes specific properties `enc` and `sig` that are used to identify
- * the public keys that can be used to interact with the DID Subject. The values of these properties
- * are strings or arrays of strings containing one or more verification method `id` values present in
- * the same DID document. If the `enc` and/or `sig` properties are an array of strings, an entity
- * interacting with the DID subject is expected to use the verification methods in the order they
- * are listed.
+ * `DecentralizedWebNode`. Encryption and signing keys are resolved from the DID document's
+ * verification methods, not from the service entry.
+ *
+ * The `enc` and `sig` properties are optional legacy fields that may be present on existing
+ * DID documents for backward compatibility. New implementations should resolve keys from the
+ * DID document's verification methods by purpose (`keyAgreement` for encryption,
+ * `authentication`/`assertionMethod` for signing).
  *
  * @example
  * ```ts
  * const service: DwnDidService = {
  *   id: 'did:example:123#dwn',
  *   type: 'DecentralizedWebNode',
- *   serviceEndpoint: 'https://enbox-dwn.fly.dev',
- *   enc: 'did:example:123#key-1',
- *   sig: 'did:example:123#key-2'
+ *   serviceEndpoint: 'https://enbox-dwn.fly.dev'
  * }
  * ```
  *
- * @see {@link https://identity.foundation/decentralized-web-node/spec/ | DIF Decentralized Web Node (DWN) Specification}
+ * @see {@link https://github.com/enboxorg/dwn-spec | Enbox DWN Specification}
  */
 export interface DwnDidService extends DidService {
   /**
-   * One or more verification method `id` values that can be used to encrypt information
-   * intended for the DID subject.
+   * @deprecated Optional legacy field. Resolve encryption keys from the DID document's
+   * `keyAgreement` verification methods instead.
    */
   enc?: string | string[];
 
   /**
-   * One or more verification method `id` values that will be used by the DID subject to sign data
-   * or by another entity to verify signatures created by the DID subject.
+   * @deprecated Optional legacy field. Resolve signing keys from the DID document's
+   * `authentication` or `assertionMethod` verification methods instead.
    */
-  sig: string | string[];
+  sig?: string | string[];
 }
 
 export enum DwnInterface {
@@ -158,8 +156,8 @@ export interface DwnMessageReply {
 }
 
 export interface MessageHandler {
-  [DwnInterface.MessagesSubscribe] : MessageSubscriptionHandler;
-  [DwnInterface.RecordsSubscribe] : RecordSubscriptionHandler;
+  [DwnInterface.MessagesSubscribe] : SubscriptionListener;
+  [DwnInterface.RecordsSubscribe] : SubscriptionListener;
 
   // define all of them individually as undefined
   [DwnInterface.MessagesRead] : undefined;
@@ -273,7 +271,6 @@ export type {
   DataEncodedRecordsWriteMessage as DwnDataEncodedRecordsWriteMessage,
   MessageSigner as DwnSigner,
   MessageSubscription as DwnMessageSubscription,
-  MessageSubscriptionHandler as DwnMessageSubscriptionHandler,
   MessagesPermissionScope as DwnMessagesPermissionScope,
   PaginationCursor as DwnPaginationCursor,
   PermissionConditions as DwnPermissionConditions,
@@ -283,6 +280,7 @@ export type {
   ProtocolDefinition as DwnProtocolDefinition,
   ProtocolPermissionScope as DwnProtocolPermissionScope,
   PublicKeyJwk as DwnPublicKeyJwk,
-  RecordSubscriptionHandler as DwnRecordSubscriptionHandler,
   RecordsPermissionScope as DwnRecordsPermissionScope,
+  SubscriptionListener as DwnSubscriptionListener,
+  SubscriptionMessage as DwnSubscriptionMessage,
 } from '@enbox/dwn-sdk-js';

package/src/types/sync.ts

@@ -11,13 +11,62 @@ export type SyncIdentityOptions = {
   /**
    * The protocols that should be synced for this identity, if an empty array is provided, all messages for all protocols will be synced.
    */
-  protocols: string[]
+  protocols: string[];
 };
+
+/**
+ * Connectivity state of the sync engine.
+ */
+export type SyncConnectivityState = 'online' | 'offline' | 'unknown';
+
+/**
+ * Describes the sync mode: `'poll'` for periodic SMT reconciliation,
+ * `'live'` for `MessagesSubscribe`-based real-time sync with SMT fallback.
+ */
+export type SyncMode = 'poll' | 'live';
+
+/**
+ * Parameters for {@link SyncEngine.startSync}.
+ */
+export type StartSyncParams = {
+  /**
+   * The sync mode to use. Default: `'poll'`.
+   *
+   * - `'live'`: Opens `MessagesSubscribe` WebSocket subscriptions to remote
+   *   DWNs for real-time pull, and listens to the local EventLog for immediate
+   *   push. Falls back to SMT reconciliation on cold start or long disconnect.
+   *   An infrequent SMT integrity check still runs at `interval`.
+   *
+   * - `'poll'`: Legacy mode. Performs a full SMT set-reconciliation sync on a
+   *   fixed interval. No WebSocket subscriptions are used.
+   */
+  mode?: SyncMode;
+
+  /**
+   * The interval at which the sync operation should be performed.
+   * Accepts any value recognised by `ms()`, e.g. `'30s'`, `'2m'`, `'10m'`.
+   *
+   * In `'live'` mode this controls the frequency of the SMT integrity check.
+   * In `'poll'` mode this controls the polling frequency.
+   *
+   * Default: `'2m'` (in poll mode), `'5m'` (in live mode).
+   */
+  interval?: string;
+};
+
 export interface SyncEngine {
   /**
    * The agent that the SyncEngine is attached to.
    */
   agent: Web5PlatformAgent;
+
+  /**
+   * Current connectivity state as observed by the sync engine.
+   * Updated when WebSocket subscriptions connect/disconnect or when the
+   * browser `online`/`offline` events fire.
+   */
+  readonly connectivityState: SyncConnectivityState;
+
   /**
    * Register an identity to be managed by the SyncEngine for syncing.
    * The options can define specific protocols that should only be synced, or a delegate DID that should be used to sign the sync messages.
@@ -43,11 +92,13 @@ export interface SyncEngine {
    */
   sync(direction?: 'push' | 'pull'): Promise<void>;
   /**
-   * Starts a periodic sync that runs at an interval. Subsequent calls to startSync will update the interval.
+   * Starts sync. In `'live'` mode opens real-time subscriptions with SMT
+   * fallback; in `'poll'` mode uses periodic SMT reconciliation.
    *
-   * @param params { interval: string } the interval at which the sync operation should be performed. ex: '30s', '1m', '10m'
+   * Subsequent calls update the mode/interval. Calling with a different mode
+   * tears down the previous mode's resources before starting the new one.
    */
-  startSync(params: { interval: string }): Promise<void>;
+  startSync(params: StartSyncParams): Promise<void>;
   /**
    * Stops the periodic sync operation, will complete the current sync operation if one is already in progress.
    *
@@ -55,4 +106,4 @@ export interface SyncEngine {
    * @throws {Error} if the sync operation fails to stop before the timeout.
    */
   stopSync(timeout?: number): Promise<void>;
-}
+}