feat(messaging-groups): wire optional recovery transport into client with recoverMessages()

Author: ioannischtz

ts-sdks/packages/messaging-groups/src/client.ts

@@ -33,9 +33,11 @@ import type {
 	GetMessageOptions,
 	GetMessagesOptions,
 	GetMessagesResult,
+	RecoverMessagesOptions,
 	SendMessageOptions,
 	SubscribeOptions,
 } from './messaging-types.js';
+import type { RecoveryTransport } from './recovery/transport.js';
 import type {
 	ArchiveGroupOptions,
 	CreateGroupOptions,
@@ -91,6 +93,7 @@ export function messagingGroups<
 	suinsConfig,
 	relayer,
 	attachments,
+	recovery,
 }: {
 	name?: Name;
 	/** Name under which the PermissionedGroupsClient extension is registered (default: 'groups'). */
@@ -105,6 +108,8 @@ export function messagingGroups<
 	relayer: RelayerConfig;
 	/** Attachment support. When omitted, messages cannot include files. */
 	attachments?: MessagingGroupsClientOptions<TApproveContext>['attachments'];
+	/** Optional recovery transport for fetching messages from an alternative storage backend. */
+	recovery?: RecoveryTransport;
 }) {
 	return {
 		name,
@@ -118,6 +123,7 @@ export function messagingGroups<
 				encryption,
 				relayer,
 				attachments,
+				recovery,
 			});
 		},
 	};
@@ -157,6 +163,7 @@ export class MessagingGroupsClient<TApproveContext = void> {
 	#packageConfig: MessagingGroupsPackageConfig;
 	#client: ClientWithCoreApi;
 	#attachments: AttachmentsManager<TApproveContext> | undefined;
+	#recovery: RecoveryTransport | undefined;
 	readonly #textEncoder = new TextEncoder();
 	readonly #textDecoder = new TextDecoder();
 
@@ -247,6 +254,8 @@ export class MessagingGroupsClient<TApproveContext = void> {
 					timeout: options.relayer.timeout,
 					onError: options.relayer.onError,
 				});
+
+		this.#recovery = options.recovery;
 	}
 
 	// === Private Helpers ===
@@ -523,6 +532,51 @@ export class MessagingGroupsClient<TApproveContext = void> {
 		this.transport.disconnect();
 	}
 
+	// === Recovery ===
+
+	/**
+	 * Fetch and decrypt messages from the recovery transport.
+	 *
+	 * Requires a `recovery` transport to be configured at client creation.
+	 * Recovery is read-only and does not require a signer.
+	 *
+	 * @throws {MessagingGroupsClientError} if no recovery transport is configured.
+	 */
+	async recoverMessages(
+		options: RecoverMessagesOptions<TApproveContext>,
+	): Promise<GetMessagesResult> {
+		if (!this.#recovery) {
+			throw new MessagingGroupsClientError(
+				'Recovery transport is not configured. Provide `recovery` when creating the messaging groups client.',
+			);
+		}
+
+		const { groupId, encryptionHistoryId } = this.derive.resolveGroupRef(options.groupRef);
+		const approveContext = this.#approveContextSpread(options);
+
+		const result = await this.#recovery.recoverMessages({
+			groupId,
+			afterOrder: options.afterOrder,
+			beforeOrder: options.beforeOrder,
+			limit: options.limit,
+		});
+
+		const settled = await Promise.allSettled(
+			result.messages.map((raw) =>
+				this.#decryptMessage(raw, { groupId, encryptionHistoryId }, approveContext),
+			),
+		);
+
+		const messages: DecryptedMessage[] = [];
+		for (const entry of settled) {
+			if (entry.status === 'fulfilled') {
+				messages.push(entry.value);
+			}
+		}
+
+		return { messages, hasNext: result.hasNext };
+	}
+
 	// === Private: sealApproveContext ===
 
 	/**
@@ -693,7 +747,11 @@ export class MessagingGroupsClient<TApproveContext = void> {
 	 * Returns a tuple of (PermissionedGroup<Messaging>, EncryptionHistory).
 	 * The objects are NOT shared - use createAndShareGroup for shared groups.
 	 */
-	async createGroup({ signer, transaction, ...callOptions }: CreateGroupOptions & { transaction?: Transaction }) {
+	async createGroup({
+		signer,
+		transaction,
+		...callOptions
+	}: CreateGroupOptions & { transaction?: Transaction }) {
 		return this.#executeTransaction(
 			this.tx.createGroup({ transaction, ...callOptions }),
 			signer,
@@ -705,7 +763,11 @@ export class MessagingGroupsClient<TApproveContext = void> {
 	 * Creates a new messaging group and shares both objects.
 	 * The transaction sender automatically becomes the creator with all permissions.
 	 */
-	async createAndShareGroup({ signer, transaction, ...callOptions }: CreateGroupOptions & { transaction?: Transaction }) {
+	async createAndShareGroup({
+		signer,
+		transaction,
+		...callOptions
+	}: CreateGroupOptions & { transaction?: Transaction }) {
 		return this.#executeTransaction(
 			this.tx.createAndShareGroup({ transaction, ...callOptions }),
 			signer,
@@ -717,7 +779,11 @@ export class MessagingGroupsClient<TApproveContext = void> {
 	 * Rotates the encryption key for a group.
 	 * Requires EncryptionKeyRotator permission.
 	 */
-	async rotateEncryptionKey({ signer, transaction, ...callOptions }: RotateEncryptionKeyOptions & { transaction?: Transaction }) {
+	async rotateEncryptionKey({
+		signer,
+		transaction,
+		...callOptions
+	}: RotateEncryptionKeyOptions & { transaction?: Transaction }) {
 		return this.#executeTransaction(
 			this.tx.rotateEncryptionKey({ transaction, ...callOptions }),
 			signer,
@@ -729,7 +795,11 @@ export class MessagingGroupsClient<TApproveContext = void> {
 	 * Atomically removes one or more members and rotates the encryption key.
 	 * Ensures removed members cannot decrypt new messages.
 	 */
-	async removeMembersAndRotateKey({ signer, transaction, ...callOptions }: RemoveMembersAndRotateKeyOptions & { transaction?: Transaction }) {
+	async removeMembersAndRotateKey({
+		signer,
+		transaction,
+		...callOptions
+	}: RemoveMembersAndRotateKeyOptions & { transaction?: Transaction }) {
 		return this.#executeTransaction(
 			this.tx.removeMembersAndRotateKey({ transaction, ...callOptions }),
 			signer,
@@ -740,7 +810,11 @@ export class MessagingGroupsClient<TApproveContext = void> {
 	/**
 	 * Removes the transaction sender from a messaging group.
 	 */
-	async leave({ signer, transaction, ...callOptions }: LeaveOptions & { transaction?: Transaction }) {
+	async leave({
+		signer,
+		transaction,
+		...callOptions
+	}: LeaveOptions & { transaction?: Transaction }) {
 		return this.#executeTransaction(
 			this.tx.leave({ transaction, ...callOptions }),
 			signer,
@@ -756,7 +830,11 @@ export class MessagingGroupsClient<TApproveContext = void> {
 	 *
 	 * After this call the group is paused and cannot be mutated.
 	 */
-	async archiveGroup({ signer, transaction, ...callOptions }: ArchiveGroupOptions & { transaction?: Transaction }) {
+	async archiveGroup({
+		signer,
+		transaction,
+		...callOptions
+	}: ArchiveGroupOptions & { transaction?: Transaction }) {
 		return this.#executeTransaction(
 			this.tx.archiveGroup({ transaction, ...callOptions }),
 			signer,
@@ -770,7 +848,11 @@ export class MessagingGroupsClient<TApproveContext = void> {
 	 * Sets the group name.
 	 * Requires `MetadataAdmin` permission.
 	 */
-	async setGroupName({ signer, transaction, ...callOptions }: SetGroupNameOptions & { transaction?: Transaction }) {
+	async setGroupName({
+		signer,
+		transaction,
+		...callOptions
+	}: SetGroupNameOptions & { transaction?: Transaction }) {
 		return this.#executeTransaction(
 			this.tx.setGroupName({ transaction, ...callOptions }),
 			signer,
@@ -782,7 +864,11 @@ export class MessagingGroupsClient<TApproveContext = void> {
 	 * Inserts a key-value pair into the group's metadata data map.
 	 * Requires `MetadataAdmin` permission.
 	 */
-	async insertGroupData({ signer, transaction, ...callOptions }: InsertGroupDataOptions & { transaction?: Transaction }) {
+	async insertGroupData({
+		signer,
+		transaction,
+		...callOptions
+	}: InsertGroupDataOptions & { transaction?: Transaction }) {
 		return this.#executeTransaction(
 			this.tx.insertGroupData({ transaction, ...callOptions }),
 			signer,
@@ -794,7 +880,11 @@ export class MessagingGroupsClient<TApproveContext = void> {
 	 * Removes a key-value pair from the group's metadata data map.
 	 * Requires `MetadataAdmin` permission.
 	 */
-	async removeGroupData({ signer, transaction, ...callOptions }: RemoveGroupDataOptions & { transaction?: Transaction }) {
+	async removeGroupData({
+		signer,
+		transaction,
+		...callOptions
+	}: RemoveGroupDataOptions & { transaction?: Transaction }) {
 		return this.#executeTransaction(
 			this.tx.removeGroupData({ transaction, ...callOptions }),
 			signer,
@@ -808,7 +898,11 @@ export class MessagingGroupsClient<TApproveContext = void> {
 	 * Sets a SuiNS reverse lookup on a messaging group.
 	 * Requires `ExtensionPermissionsAdmin` permission on the group.
 	 */
-	async setSuinsReverseLookup({ signer, transaction, ...callOptions }: SetSuinsReverseLookupOptions & { transaction?: Transaction }) {
+	async setSuinsReverseLookup({
+		signer,
+		transaction,
+		...callOptions
+	}: SetSuinsReverseLookupOptions & { transaction?: Transaction }) {
 		return this.#executeTransaction(
 			this.tx.setSuinsReverseLookup({ transaction, ...callOptions }),
 			signer,
@@ -820,7 +914,11 @@ export class MessagingGroupsClient<TApproveContext = void> {
 	 * Unsets a SuiNS reverse lookup on a messaging group.
 	 * Requires `ExtensionPermissionsAdmin` permission on the group.
 	 */
-	async unsetSuinsReverseLookup({ signer, transaction, ...callOptions }: UnsetSuinsReverseLookupOptions & { transaction?: Transaction }) {
+	async unsetSuinsReverseLookup({
+		signer,
+		transaction,
+		...callOptions
+	}: UnsetSuinsReverseLookupOptions & { transaction?: Transaction }) {
 		return this.#executeTransaction(
 			this.tx.unsetSuinsReverseLookup({ transaction, ...callOptions }),
 			signer,

ts-sdks/packages/messaging-groups/src/factory.ts

@@ -17,6 +17,7 @@ import {
 import { MessagingGroupsClientError } from './error.js';
 import type { AttachmentsConfig } from './attachments/types.js';
 import type { RelayerConfig } from './relayer/types.js';
+import type { RecoveryTransport } from './recovery/transport.js';
 import type { MessagingGroupsEncryptionOptions, MessagingGroupsPackageConfig } from './types.js';
 
 /**
@@ -55,6 +56,9 @@ export interface CreateMessagingGroupsClientOptions<TApproveContext = void> {
 
 	/** Attachment support. When omitted, messages cannot include files. */
 	attachments?: AttachmentsConfig;
+
+	/** Optional recovery transport for fetching messages from an alternative storage backend. */
+	recovery?: RecoveryTransport;
 }
 
 /**
@@ -123,6 +127,7 @@ export function createMessagingGroupsClient<TApproveContext = void>(
 				suinsConfig: options.suinsConfig,
 				relayer: options.relayer,
 				attachments: options.attachments,
+				recovery: options.recovery,
 			}),
 		);
 }

ts-sdks/packages/messaging-groups/src/messaging-types.ts

@@ -141,3 +141,18 @@ export type SubscribeOptions<TApproveContext = void> = WithApproveContext<
 	SubscribeOptionsBase,
 	TApproveContext
 >;
+
+// ── Recovery ─────────────────────────────────────────────────────
+
+interface RecoverMessagesOptionsBase {
+	groupRef: GroupRef;
+	afterOrder?: number;
+	beforeOrder?: number;
+	limit?: number;
+}
+
+/** Options for {@link MessagingGroupsClient.recoverMessages}. */
+export type RecoverMessagesOptions<TApproveContext = void> = WithApproveContext<
+	RecoverMessagesOptionsBase,
+	TApproveContext
+>;

ts-sdks/packages/messaging-groups/src/types.ts

@@ -12,6 +12,7 @@ import type { SuinsConfig } from './constants.js';
 import type { CryptoPrimitives } from './encryption/crypto-primitives.js';
 import type { SealPolicy } from './encryption/seal-policy.js';
 import type { RelayerConfig } from './relayer/types.js';
+import type { RecoveryTransport } from './recovery/transport.js';
 
 // === Package Configuration ===
 
@@ -135,6 +136,12 @@ export interface MessagingGroupsClientOptions<
 	 * and received attachments are not resolvable.
 	 */
 	attachments?: AttachmentsConfig;
+	/**
+	 * Optional recovery transport for fetching messages from an alternative
+	 * storage backend (e.g., Walrus). When provided, enables the
+	 * `recoverMessages()` method on the client.
+	 */
+	recovery?: RecoveryTransport;
 }
 
 // === Call/Tx Options (no signer) ===