@msssystems/mss-link-sdk 0.1.2 → 0.1.5

package/dist/client/decryption-errors.d.ts

@@ -0,0 +1,7 @@
+export type LocalCryptoErrorCode = 'corrupt_session' | 'missing_local_session' | 'unsupported_envelope' | 'local_crypto_unavailable' | 'unknown';
+export declare class LocalCryptoError extends Error {
+    readonly code: LocalCryptoErrorCode;
+    readonly cause?: unknown;
+    constructor(code: LocalCryptoErrorCode, message: string, cause?: unknown);
+}
+export declare function normalizeLocalCryptoError(error: unknown): LocalCryptoError;

package/dist/client/decryption-errors.js

@@ -0,0 +1,36 @@
+export class LocalCryptoError extends Error {
+    code;
+    cause;
+    constructor(code, message, cause) {
+        super(message);
+        this.name = 'LocalCryptoError';
+        this.code = code;
+        this.cause = cause;
+    }
+}
+export function normalizeLocalCryptoError(error) {
+    if (error instanceof LocalCryptoError) {
+        return error;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    const normalizedMessage = message.toLowerCase();
+    if (normalizedMessage.includes('corrupt') ||
+        normalizedMessage.includes('ratchet')) {
+        return new LocalCryptoError('corrupt_session', message, error);
+    }
+    if (normalizedMessage.includes('missing') ||
+        normalizedMessage.includes('not found') ||
+        normalizedMessage.includes('session')) {
+        return new LocalCryptoError('missing_local_session', message, error);
+    }
+    if (normalizedMessage.includes('unsupported') ||
+        normalizedMessage.includes('envelope')) {
+        return new LocalCryptoError('unsupported_envelope', message, error);
+    }
+    if (normalizedMessage.includes('indexeddb') ||
+        normalizedMessage.includes('wasm') ||
+        normalizedMessage.includes('browser')) {
+        return new LocalCryptoError('local_crypto_unavailable', message, error);
+    }
+    return new LocalCryptoError('unknown', message, error);
+}

package/dist/client/index.d.ts

@@ -1,5 +1,12 @@
 export * from './api-base-url';
 export * from './client-options';
+export * from './decryption-errors';
+export * from './local-crypto-health';
+export * from './local-crypto-health.contracts';
+export * from './media-message.contracts';
+export * from './media-message-metadata';
 export * from './message.contracts';
+export * from './message-decryption.contracts';
+export * from './message-decryption-state';
 export * from './message.mapper';
 export * from './mss-link-browser-client';

package/dist/client/index.js

@@ -1,5 +1,12 @@
 export * from './api-base-url';
 export * from './client-options';
+export * from './decryption-errors';
+export * from './local-crypto-health';
+export * from './local-crypto-health.contracts';
+export * from './media-message.contracts';
+export * from './media-message-metadata';
 export * from './message.contracts';
+export * from './message-decryption.contracts';
+export * from './message-decryption-state';
 export * from './message.mapper';
 export * from './mss-link-browser-client';

package/dist/client/local-crypto-health.contracts.d.ts

@@ -0,0 +1,9 @@
+import type { LocalCryptoErrorCode } from './decryption-errors';
+export type LocalCryptoHealthStatus = 'ready' | 'recovery_required' | 'corrupt' | 'unavailable';
+export type LocalCryptoHealthErrorCode = LocalCryptoErrorCode;
+export interface LocalCryptoHealth {
+    ready: boolean;
+    status: LocalCryptoHealthStatus;
+    errorCode?: LocalCryptoHealthErrorCode;
+    checkedAt: string;
+}

package/dist/client/local-crypto-health.contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/client/local-crypto-health.d.ts

@@ -0,0 +1,2 @@
+import type { LocalCryptoHealth } from './local-crypto-health.contracts';
+export declare function checkLocalCryptoHealth(checkReady: () => Promise<void>): Promise<LocalCryptoHealth>;

package/dist/client/local-crypto-health.js

@@ -0,0 +1,29 @@
+import { normalizeLocalCryptoError } from './decryption-errors';
+export async function checkLocalCryptoHealth(checkReady) {
+    try {
+        await checkReady();
+        return {
+            ready: true,
+            status: 'ready',
+            checkedAt: new Date().toISOString(),
+        };
+    }
+    catch (error) {
+        const normalizedError = normalizeLocalCryptoError(error);
+        return {
+            ready: false,
+            status: getLocalCryptoHealthStatus(normalizedError.code),
+            errorCode: normalizedError.code,
+            checkedAt: new Date().toISOString(),
+        };
+    }
+}
+function getLocalCryptoHealthStatus(errorCode) {
+    if (errorCode === 'corrupt_session') {
+        return 'corrupt';
+    }
+    if (errorCode === 'local_crypto_unavailable') {
+        return 'unavailable';
+    }
+    return 'recovery_required';
+}

package/dist/client/media-message-metadata.d.ts

@@ -0,0 +1,4 @@
+import type { MediaMessageAttachmentInput, MediaMessageMetadataPayload } from './media-message.contracts';
+export declare function buildMediaMessageMetadataPayload(attachments: MediaMessageAttachmentInput[], caption?: string): MediaMessageMetadataPayload;
+export declare function serializeMediaMessageMetadata(payload: MediaMessageMetadataPayload): string;
+export declare function extractMediaAssetIds(attachments: MediaMessageAttachmentInput[]): string[];

package/dist/client/media-message-metadata.js

@@ -0,0 +1,56 @@
+export function buildMediaMessageMetadataPayload(attachments, caption) {
+    if (attachments.length === 0) {
+        throw new Error('Media message must contain at least one attachment.');
+    }
+    const payload = {
+        schema: 'mss.link.media-message.v1',
+        attachments: attachments.map(normalizeAttachment),
+    };
+    if (caption && caption.trim().length > 0) {
+        payload.caption = caption.trim();
+    }
+    return payload;
+}
+export function serializeMediaMessageMetadata(payload) {
+    return JSON.stringify({
+        schema: payload.schema,
+        attachments: payload.attachments.map((attachment) => ({
+            assetId: attachment.assetId,
+            mimeType: attachment.mimeType,
+            size: attachment.size,
+            ...(attachment.originalName
+                ? { originalName: attachment.originalName }
+                : {}),
+            ...(attachment.uploadedAt ? { uploadedAt: attachment.uploadedAt } : {}),
+        })),
+        ...(payload.caption ? { caption: payload.caption } : {}),
+    });
+}
+export function extractMediaAssetIds(attachments) {
+    return attachments.map((attachment) => attachment.assetId);
+}
+function normalizeAttachment(attachment) {
+    const assetId = attachment.assetId.trim();
+    const mimeType = attachment.mimeType.trim();
+    const size = String(attachment.size);
+    if (!assetId) {
+        throw new Error('Media attachment assetId is required.');
+    }
+    if (!mimeType) {
+        throw new Error('Media attachment mimeType is required.');
+    }
+    if (!size || size === 'NaN') {
+        throw new Error('Media attachment size is required.');
+    }
+    return {
+        assetId,
+        mimeType,
+        size,
+        ...(attachment.originalName?.trim()
+            ? { originalName: attachment.originalName.trim() }
+            : {}),
+        ...(attachment.uploadedAt?.trim()
+            ? { uploadedAt: attachment.uploadedAt.trim() }
+            : {}),
+    };
+}

package/dist/client/media-message.contracts.d.ts

@@ -0,0 +1,25 @@
+export interface MediaMessageAttachmentInput {
+    assetId: string;
+    mimeType: string;
+    size: string | number;
+    originalName?: string;
+    uploadedAt?: string;
+}
+export interface SendMediaMessageParams {
+    chatId: string;
+    targetUserId: string;
+    attachments: MediaMessageAttachmentInput[];
+    caption?: string;
+}
+export interface MediaMessageAttachmentMetadata {
+    assetId: string;
+    mimeType: string;
+    size: string;
+    originalName?: string;
+    uploadedAt?: string;
+}
+export interface MediaMessageMetadataPayload {
+    schema: 'mss.link.media-message.v1';
+    attachments: MediaMessageAttachmentMetadata[];
+    caption?: string;
+}

package/dist/client/media-message.contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/client/message-decryption-state.d.ts

@@ -0,0 +1,2 @@
+import type { CreateMessageDecryptionStateIndexInput, EncryptedMessageRef, MessageDecryptStateIndex } from './message-decryption.contracts';
+export declare function createMessageDecryptionStateIndex<TMessage extends EncryptedMessageRef>({ messages, decryptedMessages, isDecrypting, decryptError, }: CreateMessageDecryptionStateIndexInput<TMessage>): MessageDecryptStateIndex;

package/dist/client/message-decryption-state.js

@@ -0,0 +1,81 @@
+import { normalizeLocalCryptoError } from './decryption-errors';
+export function createMessageDecryptionStateIndex({ messages, decryptedMessages, isDecrypting, decryptError, }) {
+    const decryptedById = createDecryptedMessageIndex(decryptedMessages);
+    const index = new Map();
+    for (const message of messages) {
+        const decrypted = findDecryptedMessage(decryptedById, message);
+        const state = createMessageDecryptState({
+            message,
+            decrypted,
+            isDecrypting,
+            decryptError,
+        });
+        index.set(message.id, state);
+        if (message.clientMessageId) {
+            index.set(message.clientMessageId, state);
+        }
+    }
+    return index;
+}
+function createMessageDecryptState({ message, decrypted, isDecrypting, decryptError, }) {
+    const baseState = createBaseMessageDecryptState(message);
+    if (decrypted?.text) {
+        return {
+            ...baseState,
+            status: 'decrypted',
+            text: decrypted.text,
+        };
+    }
+    if (isDecrypting) {
+        return {
+            ...baseState,
+            status: 'pending',
+            reason: 'local_sync_in_progress',
+        };
+    }
+    if (decryptError) {
+        return {
+            ...baseState,
+            status: 'failed',
+            reason: 'local_crypto_error',
+            errorCode: getDecryptErrorCode(decryptError),
+        };
+    }
+    return {
+        ...baseState,
+        status: 'recovery_required',
+        reason: 'local_message_missing',
+        errorCode: 'missing_local_session',
+    };
+}
+function createBaseMessageDecryptState(message) {
+    if (message.clientMessageId) {
+        return {
+            messageId: message.id,
+            clientMessageId: message.clientMessageId,
+        };
+    }
+    return {
+        messageId: message.id,
+    };
+}
+function createDecryptedMessageIndex(messages) {
+    const index = new Map();
+    for (const message of messages) {
+        index.set(message.id, message);
+    }
+    return index;
+}
+function findDecryptedMessage(index, message) {
+    const byMessageId = index.get(message.id);
+    if (byMessageId) {
+        return byMessageId;
+    }
+    if (message.clientMessageId) {
+        return index.get(message.clientMessageId);
+    }
+    return undefined;
+}
+function getDecryptErrorCode(error) {
+    return normalizeLocalCryptoError(error).code;
+}

package/dist/client/message-decryption.contracts.d.ts

@@ -0,0 +1,24 @@
+import type { LocalCryptoErrorCode } from './decryption-errors';
+import type { DecryptedMessage } from './message.contracts';
+export type MessageDecryptStatus = 'decrypted' | 'pending' | 'failed' | 'recovery_required';
+export type MessageDecryptReason = 'local_sync_in_progress' | 'local_message_missing' | 'local_crypto_error';
+export type MessageDecryptErrorCode = LocalCryptoErrorCode;
+export interface EncryptedMessageRef {
+    id: string;
+    clientMessageId?: string | null;
+}
+export interface MessageDecryptState {
+    messageId: string;
+    clientMessageId?: string | null;
+    status: MessageDecryptStatus;
+    reason?: MessageDecryptReason;
+    errorCode?: MessageDecryptErrorCode;
+    text?: string;
+}
+export type MessageDecryptStateIndex = Map<string, MessageDecryptState>;
+export interface CreateMessageDecryptionStateIndexInput<TMessage extends EncryptedMessageRef = EncryptedMessageRef> {
+    messages: TMessage[];
+    decryptedMessages: DecryptedMessage[];
+    isDecrypting: boolean;
+    decryptError: unknown;
+}

package/dist/client/message-decryption.contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/client/mss-link-browser-client.d.ts

@@ -1,4 +1,6 @@
 import type { MssLinkBrowserClientOptions } from './client-options';
+import type { LocalCryptoHealth } from './local-crypto-health.contracts';
+import type { SendMediaMessageParams } from './media-message.contracts';
 import type { DecryptedMessage } from './message.contracts';
 export declare class MssLinkBrowserClient {
     private readonly userId;
@@ -16,12 +18,14 @@ export declare class MssLinkBrowserClient {
     constructor(options: MssLinkBrowserClientOptions);
     setAccessToken(accessToken: string | null): void;
     ensureReady(): Promise<void>;
+    getLocalCryptoHealth(): Promise<LocalCryptoHealth>;
     sendMessage(params: {
         chatId: string;
         targetUserId: string;
         text: string;
         kind?: string;
     }): Promise<string>;
+    sendMediaMessage(params: SendMediaMessageParams): Promise<string>;
     syncMessages(): Promise<void>;
     getLocalMessages(chatId: string): Promise<DecryptedMessage[]>;
     reset(): void;

package/dist/client/mss-link-browser-client.js

@@ -1,4 +1,7 @@
 import { normalizeProductApiBaseUrl } from './api-base-url';
+import { normalizeLocalCryptoError } from './decryption-errors';
+import { checkLocalCryptoHealth } from './local-crypto-health';
+import { buildMediaMessageMetadataPayload, extractMediaAssetIds, serializeMediaMessageMetadata, } from './media-message-metadata';
 import { mapLocalSdkMessage } from './message.mapper';
 import { WasmCallQueue } from './wasm-call-queue';
 const DEFAULT_DEVICE_ID = 1;
@@ -43,20 +46,56 @@ export class MssLinkBrowserClient {
         this.wasmClient?.setAccessToken(accessToken);
     }
     async ensureReady() {
-        await this.runWithClient(async (client) => {
-            await client.ensureDeviceRegistered(this.registrationId, this.signedPrekeyId, this.initialOneTimePrekeyCount);
-            await client.replenishOneTimePreKeys(this.minOneTimePrekeys, this.replenishOneTimePrekeys);
-        });
+        try {
+            await this.runWithClient(async (client) => {
+                await client.ensureDeviceRegistered(this.registrationId, this.signedPrekeyId, this.initialOneTimePrekeyCount);
+                await client.replenishOneTimePreKeys(this.minOneTimePrekeys, this.replenishOneTimePrekeys);
+            });
+        }
+        catch (error) {
+            throw normalizeLocalCryptoError(error);
+        }
+    }
+    async getLocalCryptoHealth() {
+        return checkLocalCryptoHealth(() => this.ensureReady());
     }
     async sendMessage(params) {
-        return this.runWithClient((client) => client.sendMessage(params.chatId, params.targetUserId, params.text, params.kind ?? 'TEXT'));
+        try {
+            await this.ensureReady();
+            return this.runWithClient((client) => client.sendMessage(params.chatId, params.targetUserId, params.text, params.kind ?? 'TEXT'));
+        }
+        catch (error) {
+            throw normalizeLocalCryptoError(error);
+        }
+    }
+    async sendMediaMessage(params) {
+        try {
+            await this.ensureReady();
+            const payload = buildMediaMessageMetadataPayload(params.attachments, params.caption);
+            const metadataJson = serializeMediaMessageMetadata(payload);
+            const mediaAssetIds = extractMediaAssetIds(params.attachments);
+            return this.runWithClient((client) => client.sendMediaMessage(params.chatId, params.targetUserId, metadataJson, mediaAssetIds));
+        }
+        catch (error) {
+            throw normalizeLocalCryptoError(error);
+        }
     }
     async syncMessages() {
-        await this.runWithClient((client) => client.syncMessages());
+        try {
+            await this.runWithClient((client) => client.syncMessages());
+        }
+        catch (error) {
+            throw normalizeLocalCryptoError(error);
+        }
     }
     async getLocalMessages(chatId) {
-        const rawMessages = await this.runWithClient((client) => client.getLocalMessages(chatId));
-        return rawMessages.map((message) => mapLocalSdkMessage(message));
+        try {
+            const rawMessages = await this.runWithClient((client) => client.getLocalMessages(chatId));
+            return rawMessages.map((message) => mapLocalSdkMessage(message));
+        }
+        catch (error) {
+            throw normalizeLocalCryptoError(error);
+        }
     }
     reset() {
         this.wasmClient?.free();
@@ -78,7 +117,7 @@ export class MssLinkBrowserClient {
         return this.wasmClient;
     }
     loadWasmModule() {
-        this.wasmModulePromise ??= import('@msssystems/mss-crypto-wasm');
+        this.wasmModulePromise ??= import('@msssystems/mss-crypto-wasm').then((module) => module);
         return this.wasmModulePromise;
     }
 }

package/dist/client/wasm-client.types.d.ts

@@ -1,6 +1,9 @@
 import type { WasmMssClient } from '@msssystems/mss-crypto-wasm';
-export type WasmMssClientConstructor = new (userId: string, deviceId: number, apiBaseUrl: string) => WasmMssClient;
+export interface MssLinkWasmClient extends WasmMssClient {
+    sendMediaMessage(chatId: string, targetUserId: string, metadataJson: string, mediaAssetIds: string[]): Promise<string>;
+}
+export type WasmMssClientConstructor = new (userId: string, deviceId: number, apiBaseUrl: string) => MssLinkWasmClient;
 export interface MssCryptoWasmModule {
     WasmMssClient: WasmMssClientConstructor;
 }
-export type WasmMssClientInstance = WasmMssClient;
+export type WasmMssClientInstance = MssLinkWasmClient;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msssystems/mss-link-sdk",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "description": "Official managed application SDK for MSS ecosystem",
   "type": "module",
   "main": "./dist/index.js",
@@ -53,7 +53,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "peerDependencies": {
-    "@msssystems/mss-crypto-wasm": "^0.1.16",
+    "@msssystems/mss-crypto-wasm": "^0.1.17",
     "@nestjs/common": "^10.0.0 || ^11.0.0",
     "@nestjs/core": "^10.0.0 || ^11.0.0",
     "express": "^4.0.0 || ^5.0.0",
@@ -77,7 +77,7 @@
     }
   },
   "devDependencies": {
-    "@msssystems/mss-crypto-wasm": "^0.1.16",
+    "@msssystems/mss-crypto-wasm": "^0.1.17",
     "@nestjs/common": "^11.0.1",
     "@nestjs/core": "^11.0.1",
     "@types/express": "^5.0.0",