@enbox/agent 0.5.16 → 0.6.0

package/src/types/sync.ts

@@ -196,13 +196,20 @@ export type ReplicationLinkState = {
  * Result of a batch push operation. Replaces the previous throw-on-first-failure
  * pattern so callers can advance the push replication checkpoint incrementally.
  */
+/** A permanently failed push entry with diagnostic info. */
+export type PermanentPushFailure = {
+  cid : string;
+  statusCode : number;
+  detail : string;
+};
+
 export type PushResult = {
   /** messageCids that were accepted (202/204/409 — idempotent success). */
   succeeded: string[];
   /** messageCids that failed with a transient error (5xx, network) — worth retrying. */
   failed: string[];
-  /** messageCids that failed permanently (400/401/403) — will never succeed, do NOT retry. */
-  permanentlyFailed: string[];
+  /** Messages that failed permanently (400/401/403) — will never succeed, do NOT retry. */
+  permanentlyFailed: PermanentPushFailure[];
 };
 
 /**
@@ -257,6 +264,52 @@ export type SyncEvent =
 
 export type SyncEventListener = (event: SyncEvent) => void;
 
+// ---------------------------------------------------------------------------
+// Dead letter tracking
+// ---------------------------------------------------------------------------
+
+/** Category of sync failure for dead letter entries. */
+export type DeadLetterCategory = 'push-permanent' | 'push-exhausted' | 'pull-processing' | 'closure';
+
+/** A message that permanently failed to sync. */
+export type DeadLetterEntry = {
+  /** The message CID that failed. */
+  messageCid: string;
+  /** The tenant DID the message belongs to. */
+  tenantDid: string;
+  /** The remote DWN endpoint involved (for push failures). */
+  remoteEndpoint?: string;
+  /** The protocol URI, if applicable. */
+  protocol?: string;
+  /** What kind of failure occurred. */
+  category: DeadLetterCategory;
+  /** Machine-readable error code (e.g., HTTP status or ClosureFailureCode). */
+  errorCode?: string;
+  /** Human-readable error detail. */
+  errorDetail: string;
+  /** ISO-8601 timestamp of when the failure was recorded. */
+  failedAt: string;
+};
+
+/**
+ * Sync health summary returned by `getSyncHealth()`.
+ *
+ * `failedMessageCount` reflects messages that are currently failing — entries
+ * are auto-cleared when the same CID later succeeds via push or pull, so the
+ * count decreases as the engine self-heals through reconciliation and repair.
+ */
+export type SyncHealthSummary = {
+  /** Current connectivity state. */
+  connectivity: SyncConnectivityState;
+  /**
+   * Number of messages currently in the dead letter store. Decreases as
+   * the engine self-heals — entries are auto-cleared on later success.
+   */
+  failedMessageCount: number;
+  /** Number of links currently in 'repairing' or 'degraded_poll' status. */
+  degradedLinkCount: number;
+};
+
 export interface SyncEngine {
   /**
    * The agent that the SyncEngine is attached to.
@@ -323,4 +376,35 @@ export interface SyncEngine {
    * be reused.
    */
   close(): Promise<void>;
+
+  // ---------------------------------------------------------------------------
+  // Dead letter / sync health
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Returns messages that are currently failing to sync, optionally filtered
+   * by tenant. Entries are auto-cleared when the same CID later succeeds
+   * (via push or pull), so the list reflects current health — not historical
+   * incidents. Sorted newest-first by `failedAt`.
+   */
+  getFailedMessages(tenantDid?: string): Promise<DeadLetterEntry[]>;
+
+  /**
+   * Remove dead letter entries for a CID. When `remoteEndpoint` is provided,
+   * only the entry for that specific CID + remote pair is removed. Without
+   * it, all entries for the CID (across all remotes) are removed. Returns
+   * `true` if at least one entry was found and removed.
+   */
+  clearFailedMessage(messageCid: string, remoteEndpoint?: string): Promise<boolean>;
+
+  /**
+   * Clear all dead letter entries, optionally scoped to a tenant.
+   */
+  clearAllFailedMessages(tenantDid?: string): Promise<void>;
+
+  /**
+   * Returns a summary of sync health: connectivity, failed message count,
+   * and degraded link count.
+   */
+  getSyncHealth(): Promise<SyncHealthSummary>;
 }