@contrail/documents 2.4.0 → 2.5.0-alpha.ea3ab65

package/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to `@contrail/documents` are documented here.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.5.0] - 2026-10-05
+
+### Added
+
+- `TransactionClientTraceFields` — `initiatedAt` (epoch ms the transaction was initiated, on the
+  sender's clock: the user's action completing, or the enqueue for a fallback), `initiatedSource`
+  (`TransactionInitiatedSource`: `user_action` | `enqueue_fallback`), and the sender's clock offset
+  estimate `initiatedClockOffsetMs` / `initiatedClockUncertaintyMs`. Carried, all optional, on
+  `WriteTransactionRequest`, `DocumentTransactionPayload`, `DocumentTransactionMessage` and
+  `DocumentTransaction`, so a receiver can measure an edit's path from the sender's action to its own
+  screen and correct for both clocks.
+- `traceId?: string` on `WriteTransactionResponse`, `DocumentTransactionPayload`,
+  `DocumentTransactionMessage` and `DocumentTransaction` — the server's append-span trace id, so the
+  sender and every receiver can be joined to the backend trace.
+- `createdOn?: string` on `DocumentTransaction` (replay items), matching what the broadcast already
+  carries, so replayed transactions can report the same legs as live ones.
+
 ## [2.4.0] - 2026-09-26
 
 Also shipped on the 1.x line as 1.21.0.

package/lib/types/document-transaction.d.ts

@@ -11,7 +11,14 @@ export type DocumentOperation = {
     elementId: string;
 };
 export type DocumentElementPatch = Partial<Omit<DocumentElement, 'id' | 'documentId'>>;
-interface WriteTransactionRequestBase {
+export type TransactionInitiatedSource = 'user_action' | 'enqueue_fallback';
+export interface TransactionClientTraceFields {
+    initiatedAt?: number;
+    initiatedSource?: TransactionInitiatedSource;
+    initiatedClockOffsetMs?: number;
+    initiatedClockUncertaintyMs?: number;
+}
+interface WriteTransactionRequestBase extends TransactionClientTraceFields {
     clientTransactionId?: string;
 }
 export interface InlineWriteTransactionRequest extends WriteTransactionRequestBase {
@@ -28,10 +35,13 @@ export interface WriteTransactionResponse {
     createdOn: string;
     createdById: string;
     clientTransactionId?: string;
+    traceId?: string;
 }
-interface DocumentTransactionBase {
+interface DocumentTransactionBase extends TransactionClientTraceFields {
     sequenceNumber: number;
     clientTransactionId?: string;
+    createdOn?: string;
+    traceId?: string;
 }
 export interface InlineDocumentTransaction extends DocumentTransactionBase {
     operations: DocumentOperation[];
@@ -47,12 +57,13 @@ export interface GetDocumentTransactionsResponse {
     hasMore: boolean;
     lastReturnedSequenceNumber: number;
 }
-interface DocumentTransactionMessageBase {
+interface DocumentTransactionMessageBase extends TransactionClientTraceFields {
     type: 'DOCUMENT_TRANSACTION';
     documentId: string;
     sequenceNumber: number;
     createdOn: string;
     clientTransactionId?: string;
+    traceId?: string;
 }
 export type DocumentTransactionMessage = (DocumentTransactionMessageBase & {
     operations: DocumentOperation[];
@@ -68,7 +79,8 @@ export interface TransactionUploadTarget {
 }
 export type DocumentTransactionPayload = {
     clientTransactionId?: string;
-} & ({
+    traceId?: string;
+} & TransactionClientTraceFields & ({
     operations: DocumentOperation[];
     operationsS3Key?: never;
 } | {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrail/documents",
-  "version": "2.4.0",
+  "version": "2.5.0-alpha.ea3ab65",
   "description": "Documents library for contrail platform",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",