@el-j/google-sheet-translations 3.0.0-beta.6 → 3.0.0-beta.8

package/dist/esm/index.js

@@ -3403,30 +3403,45 @@ function fetchChannelHistory(wsUrl, channelHex, cryptKey, options = {}) {
 		let quietTimer = null;
 		let overallTimeout = null;
 		let requestedHistory = false;
+		let abortListener = null;
+		let settled = false;
 		const cleanup = () => {
 			if (quietTimer) clearTimeout(quietTimer);
 			if (overallTimeout) clearTimeout(overallTimeout);
+			if (signal && abortListener) signal.removeEventListener("abort", abortListener);
 			try {
 				ws.close();
 			} catch {}
 		};
-		const finish = () => {
+		const finish = (result) => {
+			if (settled) return;
+			settled = true;
 			cleanup();
-			resolve(decryptedMessages);
+			resolve(result);
+		};
+		const rejectOnce = (error) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			reject(error);
 		};
 		const resetQuietTimer = () => {
 			if (quietTimer) clearTimeout(quietTimer);
-			quietTimer = setTimeout(finish, quietPeriodMs);
+			quietTimer = setTimeout(() => {
+				if (decryptedMessages.length > 0) finish(decryptedMessages);
+				else rejectOnce(/* @__PURE__ */ new Error(`Timeout after ${timeoutMs}ms waiting for CryptPad channel "${channelHex}" history.`));
+			}, quietPeriodMs);
 		};
 		overallTimeout = setTimeout(() => {
-			cleanup();
-			if (decryptedMessages.length > 0) resolve(decryptedMessages);
-			else reject(/* @__PURE__ */ new Error(`Timeout after ${timeoutMs}ms waiting for CryptPad channel "${channelHex}" history.`));
+			if (decryptedMessages.length > 0) finish(decryptedMessages);
+			else rejectOnce(/* @__PURE__ */ new Error(`Timeout after ${timeoutMs}ms waiting for CryptPad channel "${channelHex}" history.`));
 		}, timeoutMs);
-		if (signal) signal.addEventListener("abort", () => {
-			cleanup();
-			reject(/* @__PURE__ */ new Error("Operation aborted"));
-		});
+		if (signal) {
+			abortListener = () => {
+				rejectOnce(/* @__PURE__ */ new Error("Operation aborted"));
+			};
+			signal.addEventListener("abort", abortListener);
+		}
 		ws.onopen = () => {
 			ws.send(JSON.stringify([
 				seq++,
@@ -3492,21 +3507,37 @@ function broadcastChannelMessage(wsUrl, channelHex, cryptKey, message, options =
 		let seq = 1;
 		let timeout = null;
 		let sent = false;
+		let abortListener = null;
+		let settled = false;
 		const cleanup = () => {
 			if (timeout) clearTimeout(timeout);
+			if (signal && abortListener) signal.removeEventListener("abort", abortListener);
 			try {
 				ws.close();
 			} catch {}
 		};
-		timeout = setTimeout(() => {
+		const resolveOnce = () => {
+			if (settled) return;
+			settled = true;
 			cleanup();
-			if (sent) resolve();
-			else reject(/* @__PURE__ */ new Error(`Timeout after ${timeoutMs}ms broadcasting message to CryptPad channel "${channelHex}".`));
-		}, timeoutMs);
-		if (signal) signal.addEventListener("abort", () => {
+			resolve();
+		};
+		const rejectOnce = (error) => {
+			if (settled) return;
+			settled = true;
 			cleanup();
-			reject(/* @__PURE__ */ new Error("Operation aborted"));
-		});
+			reject(error);
+		};
+		timeout = setTimeout(() => {
+			if (sent) resolveOnce();
+			else rejectOnce(/* @__PURE__ */ new Error(`Timeout after ${timeoutMs}ms broadcasting message to CryptPad channel "${channelHex}".`));
+		}, timeoutMs);
+		if (signal) {
+			abortListener = () => {
+				rejectOnce(/* @__PURE__ */ new Error("Operation aborted"));
+			};
+			signal.addEventListener("abort", abortListener);
+		}
 		ws.onopen = () => {
 			ws.send(JSON.stringify([
 				seq++,
@@ -3530,15 +3561,13 @@ function broadcastChannelMessage(wsUrl, channelHex, cryptKey, message, options =
 						encrypted
 					]));
 					setTimeout(() => {
-						cleanup();
-						resolve();
+						resolveOnce();
 					}, 350);
 				}
 			} catch {}
 		};
 		ws.onerror = (err) => {
-			cleanup();
-			reject(/* @__PURE__ */ new Error(`CryptPad WebSocket broadcast error: ${String(err)}`));
+			rejectOnce(/* @__PURE__ */ new Error(`CryptPad WebSocket broadcast error: ${String(err)}`));
 		};
 	});
 }
@@ -3584,6 +3613,27 @@ function extractOnlyOfficeChannelId(metadataMessages) {
 }
 /**
 * Parses OnlyOffice incremental binary change records into cell coordinates and text values.
+*
+* ### OnlyOffice Document Server / CryptPad Binary Protocol Specification
+* OnlyOffice collaborative document changes are broadcast over Netflux real-time channels.
+* Each message contains a `changes` array of transaction objects.
+*
+* Inside each transaction, `change` is formatted with a command prefix followed by base64 binary:
+* `asc_<version>;<base64_binary_payload>` (e.g., `asc_1;<base64>`).
+*
+* The decoded binary stream represents OnlyOffice document AST changes:
+* - Text and identifiers are serialized as length-prefixed UTF-16LE strings.
+* - The marker byte `0x08` indicates the start of a UTF-16LE string entry, followed by a 4-byte
+*   little-endian unsigned integer (`UInt32LE`) specifying byte length, followed by the UTF-16LE payload.
+*
+* Two layout patterns are supported:
+* - **Case A (Explicit coordinate reference)**: A string matching coordinate syntax (e.g. `A1` or `sheet!B2`)
+*   followed closely (within 30 bytes) by another `0x08` marker holding the cell's UTF-16LE text value.
+* - **Case B (Binary header coordinates)**: Header packets store 0-based column index `c1` at byte 14
+*   and row index `r1` at byte 18 as `UInt32LE`, followed by string values starting at byte 40+.
+*
+* @param rtMessages - Decrypted raw change messages retrieved from the OnlyOffice RT Netflux channel.
+* @returns A mapping of cell coordinates (`A1` or `sheet!A1`) to cell text values.
 */
 function parseOnlyOfficeChanges(rtMessages) {
 	const cells = {};
@@ -3732,25 +3782,48 @@ var CryptPadClient = class {
 		this.password = options.password ?? process.env.CRYPTPAD_PASSWORD;
 		this.websocketUrl = options.websocketUrl;
 		this.timeoutMs = options.timeoutMs ?? 1e4;
+		this.onProgress = options.onProgress;
 		if (this.parsedUrl.isPasswordProtected && !this.password) throw new Error(`CryptPad pad "${this.parsedUrl.cleanUrl}" is password protected, but no password was provided. Set "password" option or CRYPTPAD_PASSWORD environment variable.`);
 	}
-	/** Gets or derives the symmetric key and primary Netflux channel ID. */
+	/**
+	* Gets or derives the symmetric key and primary Netflux channel ID.
+	*
+	* @returns The derived CryptPad channel hex ID and 32-byte TweetNaCl secretbox key.
+	*/
 	getKeys() {
 		if (!this.derivedKeys) this.derivedKeys = deriveCryptPadKeys(this.parsedUrl.seed, this.password);
 		return this.derivedKeys;
 	}
-	/** Resolves the Netflux WebSocket endpoint to connect to. */
+	/**
+	* Resolves the Netflux WebSocket endpoint to connect to.
+	*
+	* @param signal - Optional AbortSignal to cancel connection discovery.
+	* @returns The WebSocket endpoint URL (wss:// or ws://).
+	*/
 	async getWebsocketUrl(signal) {
 		if (this.websocketUrl) return this.websocketUrl;
 		return resolveCryptPadWebsocketUrl(this.parsedUrl.origin, signal);
 	}
 	/**
 	* Initializes the OnlyOffice RT channel for a brand-new CryptPad sheet that has never
-	* been opened in a browser. Generates a random 32-hex channel ID, broadcasts it as an
-	* encrypted metadata patch on the Netflux channel (the same thing the OnlyOffice browser
-	* client does on first open), and returns the new RT channel ID.
+	* been opened in a browser.
+	*
+	* ### CryptPad Protocol Details
+	* CryptPad pads use Netflux channels for real-time collaboration. The main pad channel
+	* stores document metadata. When a spreadsheet pad is opened in OnlyOffice, the OnlyOffice
+	* web wrapper creates a secondary Netflux channel for real-time document change frames
+	* and registers it in the pad's metadata channel.
+	*
+	* The metadata update is formatted as an edit sequence:
+	* `[sequenceNumber, [[offset, length, innerJsonString]]]`
+	* where `sequenceNumber` is 1, and `innerJsonString` is:
+	* `{"content":{"channel":"<32-hex-channel-id>"}}`.
 	*
-	* This removes the requirement to open the sheet in a browser before the CLI can write to it.
+	* Broadcasting this envelope over the main channel headlessly replicates OnlyOffice's
+	* first-open handshake without requiring a browser or headless browser session.
+	*
+	* @param signal - Optional AbortSignal to cancel the initialization.
+	* @returns The newly allocated 32-character hexadecimal RT channel ID.
 	*/
 	async initializeRtChannel(signal) {
 		const wsUrl = await this.getWebsocketUrl(signal);
@@ -3770,6 +3843,9 @@ var CryptPadClient = class {
 	/**
 	* Fetches the complete sheet data, including raw cell coordinate mappings,
 	* multi-sheet tabs, and structured rows formatted for translation ingestion.
+	*
+	* @param signal - Optional AbortSignal to cancel the fetch.
+	* @returns The structured {@link CryptPadSheetResult} containing grids, rows, and metadata.
 	*/
 	async fetchSheetData(signal) {
 		const wsUrl = await this.getWebsocketUrl(signal);
@@ -3810,6 +3886,10 @@ var CryptPadClient = class {
 	/**
 	* Directly fetches tabular translation rows `[ { key: '...', en: '...', de: '...' } ]`.
 	* If `sheetName` is provided, returns rows for that specific tab.
+	*
+	* @param sheetName - Optional tab/sheet name to extract rows from.
+	* @param signal - Optional AbortSignal to cancel the operation.
+	* @returns An array of {@link SheetRow} objects.
 	*/
 	async fetchSheetRows(sheetName, signal) {
 		const result = await this.fetchSheetData(signal);
@@ -3820,14 +3900,17 @@ var CryptPadClient = class {
 	* Broadcasts cell updates to the OnlyOffice real-time collaboration channel.
 	* If the sheet has never been opened in a browser (RT channel is None), it is
 	* automatically initialized headlessly — no browser required.
+	*
+	* @param updates - Array of cell updates containing coordinates and text values.
+	* @param signal - Optional AbortSignal to cancel the broadcast.
 	*/
 	async sendCellUpdates(updates, signal) {
 		if (updates.length === 0) return;
 		let rtChannel = (await this.fetchSheetData(signal)).metadata.rtChannelId;
 		if (!rtChannel) {
-			console.log("No OnlyOffice RT channel found. Initializing headlessly (no browser required)...");
+			this.onProgress?.("No OnlyOffice RT channel found. Initializing headlessly (no browser required)...");
 			rtChannel = await this.initializeRtChannel(signal);
-			console.log(`RT channel initialized: ${rtChannel}`);
+			this.onProgress?.(`RT channel initialized: ${rtChannel}`);
 			await new Promise((r) => setTimeout(r, 800));
 		}
 		const wsUrl = await this.getWebsocketUrl(signal);
@@ -3840,6 +3923,11 @@ var CryptPadClient = class {
 	}
 	/**
 	* Updates or appends rows in a target sheet tab, creating new cells as needed.
+	*
+	* @param sheetName - Target sheet tab name (e.g. 'i18n' or 'common').
+	* @param rows - Array of translation rows to write.
+	* @param options - Write options: override existing non-empty values and optional signal.
+	* @returns The total number of cell update records sent.
 	*/
 	async writeSheetRows(sheetName, rows, options = {}) {
 		if (rows.length === 0) return 0;
@@ -3979,7 +4067,7 @@ const CRYPTPAD_SHEET_OUTPUT_CAPABILITIES = createCapabilitySet({ writeTables: tr
 * Converts nested TranslationData `[locale][sheet][key] = value` into
 * tabular rows `Record<sheetName, SheetRow[]>`.
 */
-function convertTranslationsToSheetRows(translations, localeMapping = {}, keyColumnName = "key") {
+function convertTranslationsToSheetRows(translations, localeMapping = {}, keyColumnName = "var") {
 	const reverseMapping = {};
 	for (const [header, norm] of Object.entries(localeMapping)) reverseMapping[norm] = header;
 	const sheetRowsMap = {};
@@ -4018,7 +4106,7 @@ function createCryptPadSheetOutputProvider(options = {}) {
 				timeoutMs: options.timeoutMs
 			});
 			const effectiveMapping = options.localeMapping ?? payload.localeMapping ?? {};
-			const sheetRowsMap = convertTranslationsToSheetRows(payload.translations, effectiveMapping, options.keyColumnName ?? "key");
+			const sheetRowsMap = convertTranslationsToSheetRows(payload.translations, effectiveMapping, options.keyColumnName ?? "var");
 			const updatedSheets = [];
 			let totalUpdatedCells = 0;
 			for (const [sheetName, rows] of Object.entries(sheetRowsMap)) {
@@ -4400,7 +4488,7 @@ function createCryptPadWorkspaceOutputProvider(options, depsOverrides = {}) {
 		displayName: options.displayName ?? "CryptPad Workspace Output",
 		capabilities: CRYPTPAD_WORKSPACE_OUTPUT_CAPABILITIES,
 		async writeTranslations(payload) {
-			const snapshot = await deps.readSnapshot(options.filePath, options.authToken);
+			const snapshot = await deps.readSnapshot(options.filePath);
 			assertRevision(snapshot, options.expectedRevision);
 			const merged = mergeTranslations$1(snapshot.translations, payload.translations);
 			const nextRevision = snapshot.revision + 1;
@@ -4411,7 +4499,7 @@ function createCryptPadWorkspaceOutputProvider(options, depsOverrides = {}) {
 					...snapshot.metadata,
 					lastWriteProvider: "cryptpad-workspace-output"
 				}
-			}, options.authToken);
+			});
 			return {
 				wroteFiles: [options.filePath],
 				metadata: {
@@ -4422,6 +4510,14 @@ function createCryptPadWorkspaceOutputProvider(options, depsOverrides = {}) {
 		}
 	};
 }
+/**
+* Builds the {@link BuildSyncPlanInput} from a {@link TranslationSyncPayload}.
+* Falls back to using `payload.remoteTranslations` as the base if `payload.metadata.baseTranslations`
+* is not supplied.
+*
+* @param payload - The incoming sync payload containing local, remote, and optional base translations.
+* @returns The structured three-way sync plan input.
+*/
 function buildSyncInput(payload) {
 	return {
 		baseTranslations: payload.metadata?.baseTranslations ?? payload.remoteTranslations,
@@ -4447,7 +4543,7 @@ function createCryptPadWorkspaceSyncProvider(options, depsOverrides = {}) {
 		displayName: options.displayName ?? "CryptPad Workspace Sync",
 		capabilities: CRYPTPAD_WORKSPACE_SYNC_CAPABILITIES,
 		async syncTranslations(payload) {
-			const snapshot = await deps.readSnapshot(options.filePath, options.authToken);
+			const snapshot = await deps.readSnapshot(options.filePath);
 			assertRevision(snapshot, options.expectedRevision ?? (Number.isFinite(payload.metadata?.expectedRevision) ? Number(payload.metadata?.expectedRevision) : void 0));
 			const resolution = resolveSyncPlan(buildSyncInput(payload), options.conflictPolicy ?? "manual");
 			const nextRevision = snapshot.revision + 1;
@@ -4459,7 +4555,7 @@ function createCryptPadWorkspaceSyncProvider(options, depsOverrides = {}) {
 					lastSyncProvider: "cryptpad-workspace-sync",
 					policy: resolution.policy
 				}
-			}, options.authToken);
+			});
 			return {
 				changedKeys: resolution.appliedLocalChanges,
 				skippedKeys: resolution.skippedConflicts,
@@ -4921,7 +5017,6 @@ function createOutputProvider(providerId, options) {
 			if (typeof options.filePath !== "string" || options.filePath.trim().length === 0) throw new Error("cryptpad-workspace output provider requires a non-empty \"filePath\" option.");
 			return createCryptPadWorkspaceOutputProvider({
 				filePath: options.filePath,
-				authToken: typeof options.authToken === "string" ? options.authToken : void 0,
 				expectedRevision: typeof options.expectedRevision === "number" ? options.expectedRevision : void 0,
 				providerId: typeof options.providerId === "string" ? options.providerId : void 0,
 				displayName: typeof options.displayName === "string" ? options.displayName : void 0
@@ -4947,7 +5042,6 @@ function createSyncProvider(providerId, options) {
 			if (typeof options.filePath !== "string" || options.filePath.trim().length === 0) throw new Error("cryptpad-workspace sync provider requires a non-empty \"filePath\" option.");
 			return createCryptPadWorkspaceSyncProvider({
 				filePath: options.filePath,
-				authToken: typeof options.authToken === "string" ? options.authToken : void 0,
 				expectedRevision: typeof options.expectedRevision === "number" ? options.expectedRevision : void 0,
 				conflictPolicy: options.conflictPolicy === "remote-wins" || options.conflictPolicy === "local-wins" || options.conflictPolicy === "manual" ? options.conflictPolicy : void 0,
 				providerId: typeof options.providerId === "string" ? options.providerId : void 0,

package/dist/index.js

@@ -3436,30 +3436,45 @@ function fetchChannelHistory(wsUrl, channelHex, cryptKey, options = {}) {
 		let quietTimer = null;
 		let overallTimeout = null;
 		let requestedHistory = false;
+		let abortListener = null;
+		let settled = false;
 		const cleanup = () => {
 			if (quietTimer) clearTimeout(quietTimer);
 			if (overallTimeout) clearTimeout(overallTimeout);
+			if (signal && abortListener) signal.removeEventListener("abort", abortListener);
 			try {
 				ws.close();
 			} catch {}
 		};
-		const finish = () => {
+		const finish = (result) => {
+			if (settled) return;
+			settled = true;
 			cleanup();
-			resolve(decryptedMessages);
+			resolve(result);
+		};
+		const rejectOnce = (error) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			reject(error);
 		};
 		const resetQuietTimer = () => {
 			if (quietTimer) clearTimeout(quietTimer);
-			quietTimer = setTimeout(finish, quietPeriodMs);
+			quietTimer = setTimeout(() => {
+				if (decryptedMessages.length > 0) finish(decryptedMessages);
+				else rejectOnce(/* @__PURE__ */ new Error(`Timeout after ${timeoutMs}ms waiting for CryptPad channel "${channelHex}" history.`));
+			}, quietPeriodMs);
 		};
 		overallTimeout = setTimeout(() => {
-			cleanup();
-			if (decryptedMessages.length > 0) resolve(decryptedMessages);
-			else reject(/* @__PURE__ */ new Error(`Timeout after ${timeoutMs}ms waiting for CryptPad channel "${channelHex}" history.`));
+			if (decryptedMessages.length > 0) finish(decryptedMessages);
+			else rejectOnce(/* @__PURE__ */ new Error(`Timeout after ${timeoutMs}ms waiting for CryptPad channel "${channelHex}" history.`));
 		}, timeoutMs);
-		if (signal) signal.addEventListener("abort", () => {
-			cleanup();
-			reject(/* @__PURE__ */ new Error("Operation aborted"));
-		});
+		if (signal) {
+			abortListener = () => {
+				rejectOnce(/* @__PURE__ */ new Error("Operation aborted"));
+			};
+			signal.addEventListener("abort", abortListener);
+		}
 		ws.onopen = () => {
 			ws.send(JSON.stringify([
 				seq++,
@@ -3525,21 +3540,37 @@ function broadcastChannelMessage(wsUrl, channelHex, cryptKey, message, options =
 		let seq = 1;
 		let timeout = null;
 		let sent = false;
+		let abortListener = null;
+		let settled = false;
 		const cleanup = () => {
 			if (timeout) clearTimeout(timeout);
+			if (signal && abortListener) signal.removeEventListener("abort", abortListener);
 			try {
 				ws.close();
 			} catch {}
 		};
-		timeout = setTimeout(() => {
+		const resolveOnce = () => {
+			if (settled) return;
+			settled = true;
 			cleanup();
-			if (sent) resolve();
-			else reject(/* @__PURE__ */ new Error(`Timeout after ${timeoutMs}ms broadcasting message to CryptPad channel "${channelHex}".`));
-		}, timeoutMs);
-		if (signal) signal.addEventListener("abort", () => {
+			resolve();
+		};
+		const rejectOnce = (error) => {
+			if (settled) return;
+			settled = true;
 			cleanup();
-			reject(/* @__PURE__ */ new Error("Operation aborted"));
-		});
+			reject(error);
+		};
+		timeout = setTimeout(() => {
+			if (sent) resolveOnce();
+			else rejectOnce(/* @__PURE__ */ new Error(`Timeout after ${timeoutMs}ms broadcasting message to CryptPad channel "${channelHex}".`));
+		}, timeoutMs);
+		if (signal) {
+			abortListener = () => {
+				rejectOnce(/* @__PURE__ */ new Error("Operation aborted"));
+			};
+			signal.addEventListener("abort", abortListener);
+		}
 		ws.onopen = () => {
 			ws.send(JSON.stringify([
 				seq++,
@@ -3563,15 +3594,13 @@ function broadcastChannelMessage(wsUrl, channelHex, cryptKey, message, options =
 						encrypted
 					]));
 					setTimeout(() => {
-						cleanup();
-						resolve();
+						resolveOnce();
 					}, 350);
 				}
 			} catch {}
 		};
 		ws.onerror = (err) => {
-			cleanup();
-			reject(/* @__PURE__ */ new Error(`CryptPad WebSocket broadcast error: ${String(err)}`));
+			rejectOnce(/* @__PURE__ */ new Error(`CryptPad WebSocket broadcast error: ${String(err)}`));
 		};
 	});
 }
@@ -3617,6 +3646,27 @@ function extractOnlyOfficeChannelId(metadataMessages) {
 }
 /**
 * Parses OnlyOffice incremental binary change records into cell coordinates and text values.
+*
+* ### OnlyOffice Document Server / CryptPad Binary Protocol Specification
+* OnlyOffice collaborative document changes are broadcast over Netflux real-time channels.
+* Each message contains a `changes` array of transaction objects.
+*
+* Inside each transaction, `change` is formatted with a command prefix followed by base64 binary:
+* `asc_<version>;<base64_binary_payload>` (e.g., `asc_1;<base64>`).
+*
+* The decoded binary stream represents OnlyOffice document AST changes:
+* - Text and identifiers are serialized as length-prefixed UTF-16LE strings.
+* - The marker byte `0x08` indicates the start of a UTF-16LE string entry, followed by a 4-byte
+*   little-endian unsigned integer (`UInt32LE`) specifying byte length, followed by the UTF-16LE payload.
+*
+* Two layout patterns are supported:
+* - **Case A (Explicit coordinate reference)**: A string matching coordinate syntax (e.g. `A1` or `sheet!B2`)
+*   followed closely (within 30 bytes) by another `0x08` marker holding the cell's UTF-16LE text value.
+* - **Case B (Binary header coordinates)**: Header packets store 0-based column index `c1` at byte 14
+*   and row index `r1` at byte 18 as `UInt32LE`, followed by string values starting at byte 40+.
+*
+* @param rtMessages - Decrypted raw change messages retrieved from the OnlyOffice RT Netflux channel.
+* @returns A mapping of cell coordinates (`A1` or `sheet!A1`) to cell text values.
 */
 function parseOnlyOfficeChanges(rtMessages) {
 	const cells = {};
@@ -3765,25 +3815,48 @@ var CryptPadClient = class {
 		this.password = options.password ?? process.env.CRYPTPAD_PASSWORD;
 		this.websocketUrl = options.websocketUrl;
 		this.timeoutMs = options.timeoutMs ?? 1e4;
+		this.onProgress = options.onProgress;
 		if (this.parsedUrl.isPasswordProtected && !this.password) throw new Error(`CryptPad pad "${this.parsedUrl.cleanUrl}" is password protected, but no password was provided. Set "password" option or CRYPTPAD_PASSWORD environment variable.`);
 	}
-	/** Gets or derives the symmetric key and primary Netflux channel ID. */
+	/**
+	* Gets or derives the symmetric key and primary Netflux channel ID.
+	*
+	* @returns The derived CryptPad channel hex ID and 32-byte TweetNaCl secretbox key.
+	*/
 	getKeys() {
 		if (!this.derivedKeys) this.derivedKeys = deriveCryptPadKeys(this.parsedUrl.seed, this.password);
 		return this.derivedKeys;
 	}
-	/** Resolves the Netflux WebSocket endpoint to connect to. */
+	/**
+	* Resolves the Netflux WebSocket endpoint to connect to.
+	*
+	* @param signal - Optional AbortSignal to cancel connection discovery.
+	* @returns The WebSocket endpoint URL (wss:// or ws://).
+	*/
 	async getWebsocketUrl(signal) {
 		if (this.websocketUrl) return this.websocketUrl;
 		return resolveCryptPadWebsocketUrl(this.parsedUrl.origin, signal);
 	}
 	/**
 	* Initializes the OnlyOffice RT channel for a brand-new CryptPad sheet that has never
-	* been opened in a browser. Generates a random 32-hex channel ID, broadcasts it as an
-	* encrypted metadata patch on the Netflux channel (the same thing the OnlyOffice browser
-	* client does on first open), and returns the new RT channel ID.
+	* been opened in a browser.
+	*
+	* ### CryptPad Protocol Details
+	* CryptPad pads use Netflux channels for real-time collaboration. The main pad channel
+	* stores document metadata. When a spreadsheet pad is opened in OnlyOffice, the OnlyOffice
+	* web wrapper creates a secondary Netflux channel for real-time document change frames
+	* and registers it in the pad's metadata channel.
+	*
+	* The metadata update is formatted as an edit sequence:
+	* `[sequenceNumber, [[offset, length, innerJsonString]]]`
+	* where `sequenceNumber` is 1, and `innerJsonString` is:
+	* `{"content":{"channel":"<32-hex-channel-id>"}}`.
 	*
-	* This removes the requirement to open the sheet in a browser before the CLI can write to it.
+	* Broadcasting this envelope over the main channel headlessly replicates OnlyOffice's
+	* first-open handshake without requiring a browser or headless browser session.
+	*
+	* @param signal - Optional AbortSignal to cancel the initialization.
+	* @returns The newly allocated 32-character hexadecimal RT channel ID.
 	*/
 	async initializeRtChannel(signal) {
 		const wsUrl = await this.getWebsocketUrl(signal);
@@ -3803,6 +3876,9 @@ var CryptPadClient = class {
 	/**
 	* Fetches the complete sheet data, including raw cell coordinate mappings,
 	* multi-sheet tabs, and structured rows formatted for translation ingestion.
+	*
+	* @param signal - Optional AbortSignal to cancel the fetch.
+	* @returns The structured {@link CryptPadSheetResult} containing grids, rows, and metadata.
 	*/
 	async fetchSheetData(signal) {
 		const wsUrl = await this.getWebsocketUrl(signal);
@@ -3843,6 +3919,10 @@ var CryptPadClient = class {
 	/**
 	* Directly fetches tabular translation rows `[ { key: '...', en: '...', de: '...' } ]`.
 	* If `sheetName` is provided, returns rows for that specific tab.
+	*
+	* @param sheetName - Optional tab/sheet name to extract rows from.
+	* @param signal - Optional AbortSignal to cancel the operation.
+	* @returns An array of {@link SheetRow} objects.
 	*/
 	async fetchSheetRows(sheetName, signal) {
 		const result = await this.fetchSheetData(signal);
@@ -3853,14 +3933,17 @@ var CryptPadClient = class {
 	* Broadcasts cell updates to the OnlyOffice real-time collaboration channel.
 	* If the sheet has never been opened in a browser (RT channel is None), it is
 	* automatically initialized headlessly — no browser required.
+	*
+	* @param updates - Array of cell updates containing coordinates and text values.
+	* @param signal - Optional AbortSignal to cancel the broadcast.
 	*/
 	async sendCellUpdates(updates, signal) {
 		if (updates.length === 0) return;
 		let rtChannel = (await this.fetchSheetData(signal)).metadata.rtChannelId;
 		if (!rtChannel) {
-			console.log("No OnlyOffice RT channel found. Initializing headlessly (no browser required)...");
+			this.onProgress?.("No OnlyOffice RT channel found. Initializing headlessly (no browser required)...");
 			rtChannel = await this.initializeRtChannel(signal);
-			console.log(`RT channel initialized: ${rtChannel}`);
+			this.onProgress?.(`RT channel initialized: ${rtChannel}`);
 			await new Promise((r) => setTimeout(r, 800));
 		}
 		const wsUrl = await this.getWebsocketUrl(signal);
@@ -3873,6 +3956,11 @@ var CryptPadClient = class {
 	}
 	/**
 	* Updates or appends rows in a target sheet tab, creating new cells as needed.
+	*
+	* @param sheetName - Target sheet tab name (e.g. 'i18n' or 'common').
+	* @param rows - Array of translation rows to write.
+	* @param options - Write options: override existing non-empty values and optional signal.
+	* @returns The total number of cell update records sent.
 	*/
 	async writeSheetRows(sheetName, rows, options = {}) {
 		if (rows.length === 0) return 0;
@@ -4012,7 +4100,7 @@ const CRYPTPAD_SHEET_OUTPUT_CAPABILITIES = createCapabilitySet({ writeTables: tr
 * Converts nested TranslationData `[locale][sheet][key] = value` into
 * tabular rows `Record<sheetName, SheetRow[]>`.
 */
-function convertTranslationsToSheetRows(translations, localeMapping = {}, keyColumnName = "key") {
+function convertTranslationsToSheetRows(translations, localeMapping = {}, keyColumnName = "var") {
 	const reverseMapping = {};
 	for (const [header, norm] of Object.entries(localeMapping)) reverseMapping[norm] = header;
 	const sheetRowsMap = {};
@@ -4051,7 +4139,7 @@ function createCryptPadSheetOutputProvider(options = {}) {
 				timeoutMs: options.timeoutMs
 			});
 			const effectiveMapping = options.localeMapping ?? payload.localeMapping ?? {};
-			const sheetRowsMap = convertTranslationsToSheetRows(payload.translations, effectiveMapping, options.keyColumnName ?? "key");
+			const sheetRowsMap = convertTranslationsToSheetRows(payload.translations, effectiveMapping, options.keyColumnName ?? "var");
 			const updatedSheets = [];
 			let totalUpdatedCells = 0;
 			for (const [sheetName, rows] of Object.entries(sheetRowsMap)) {
@@ -4433,7 +4521,7 @@ function createCryptPadWorkspaceOutputProvider(options, depsOverrides = {}) {
 		displayName: options.displayName ?? "CryptPad Workspace Output",
 		capabilities: CRYPTPAD_WORKSPACE_OUTPUT_CAPABILITIES,
 		async writeTranslations(payload) {
-			const snapshot = await deps.readSnapshot(options.filePath, options.authToken);
+			const snapshot = await deps.readSnapshot(options.filePath);
 			assertRevision(snapshot, options.expectedRevision);
 			const merged = mergeTranslations$1(snapshot.translations, payload.translations);
 			const nextRevision = snapshot.revision + 1;
@@ -4444,7 +4532,7 @@ function createCryptPadWorkspaceOutputProvider(options, depsOverrides = {}) {
 					...snapshot.metadata,
 					lastWriteProvider: "cryptpad-workspace-output"
 				}
-			}, options.authToken);
+			});
 			return {
 				wroteFiles: [options.filePath],
 				metadata: {
@@ -4455,6 +4543,14 @@ function createCryptPadWorkspaceOutputProvider(options, depsOverrides = {}) {
 		}
 	};
 }
+/**
+* Builds the {@link BuildSyncPlanInput} from a {@link TranslationSyncPayload}.
+* Falls back to using `payload.remoteTranslations` as the base if `payload.metadata.baseTranslations`
+* is not supplied.
+*
+* @param payload - The incoming sync payload containing local, remote, and optional base translations.
+* @returns The structured three-way sync plan input.
+*/
 function buildSyncInput(payload) {
 	return {
 		baseTranslations: payload.metadata?.baseTranslations ?? payload.remoteTranslations,
@@ -4480,7 +4576,7 @@ function createCryptPadWorkspaceSyncProvider(options, depsOverrides = {}) {
 		displayName: options.displayName ?? "CryptPad Workspace Sync",
 		capabilities: CRYPTPAD_WORKSPACE_SYNC_CAPABILITIES,
 		async syncTranslations(payload) {
-			const snapshot = await deps.readSnapshot(options.filePath, options.authToken);
+			const snapshot = await deps.readSnapshot(options.filePath);
 			assertRevision(snapshot, options.expectedRevision ?? (Number.isFinite(payload.metadata?.expectedRevision) ? Number(payload.metadata?.expectedRevision) : void 0));
 			const resolution = resolveSyncPlan(buildSyncInput(payload), options.conflictPolicy ?? "manual");
 			const nextRevision = snapshot.revision + 1;
@@ -4492,7 +4588,7 @@ function createCryptPadWorkspaceSyncProvider(options, depsOverrides = {}) {
 					lastSyncProvider: "cryptpad-workspace-sync",
 					policy: resolution.policy
 				}
-			}, options.authToken);
+			});
 			return {
 				changedKeys: resolution.appliedLocalChanges,
 				skippedKeys: resolution.skippedConflicts,
@@ -4954,7 +5050,6 @@ function createOutputProvider(providerId, options) {
 			if (typeof options.filePath !== "string" || options.filePath.trim().length === 0) throw new Error("cryptpad-workspace output provider requires a non-empty \"filePath\" option.");
 			return createCryptPadWorkspaceOutputProvider({
 				filePath: options.filePath,
-				authToken: typeof options.authToken === "string" ? options.authToken : void 0,
 				expectedRevision: typeof options.expectedRevision === "number" ? options.expectedRevision : void 0,
 				providerId: typeof options.providerId === "string" ? options.providerId : void 0,
 				displayName: typeof options.displayName === "string" ? options.displayName : void 0
@@ -4980,7 +5075,6 @@ function createSyncProvider(providerId, options) {
 			if (typeof options.filePath !== "string" || options.filePath.trim().length === 0) throw new Error("cryptpad-workspace sync provider requires a non-empty \"filePath\" option.");
 			return createCryptPadWorkspaceSyncProvider({
 				filePath: options.filePath,
-				authToken: typeof options.authToken === "string" ? options.authToken : void 0,
 				expectedRevision: typeof options.expectedRevision === "number" ? options.expectedRevision : void 0,
 				conflictPolicy: options.conflictPolicy === "remote-wins" || options.conflictPolicy === "local-wins" || options.conflictPolicy === "manual" ? options.conflictPolicy : void 0,
 				providerId: typeof options.providerId === "string" ? options.providerId : void 0,