From 8dc8b54b26544554f98d7af32200d6bf9a01d300 Mon Sep 17 00:00:00 2001
From: Alois <aloisianer@proton.me>
Date: Fri, 3 Jul 2026 14:45:55 +0200
Subject: [PATCH] (feat): add codec helpers to ts-sdk

---
 README.md           |  9 +++++++++
 docs/WASM-CLIENT.md | 10 ++++++++++
 src/sdk/index.ts    | 32 ++++++++++++++++++++++++++++++++
 3 files changed, 51 insertions(+)

diff --git a/README.md b/README.md
index 265f7b3..048b882 100644
--- a/README.md
+++ b/README.md
@@ -72,6 +72,15 @@ console.log("Connected MTP client", clientId, client.state);
 
 Use `MTPClient.crypto` for SDK-level crypto helpers such as `generateKeyring()`, `generateEd25519()`, `keyringFromEd25519()`, `verifyEd25519()`, `sha256()`, `sha256Double()`, `hkdfExpand()`, and `deriveEncryptionKey()`.
 
+Use `codec` to encode and decode MTP frames from the main SDK export:
+
+```typescript
+import { codec } from "mtp";
+
+const frame = codec.encode("SomeType", { value: "hello" });
+const parsed = codec.decode(frame);
+```
+
 ## Getting Started
 
 Add the `mtp` crate with your desired features:
diff --git a/docs/WASM-CLIENT.md b/docs/WASM-CLIENT.md
index b70ab3a..3cd4699 100644
--- a/docs/WASM-CLIENT.md
+++ b/docs/WASM-CLIENT.md
@@ -258,6 +258,16 @@ Raw message helpers that remain available include:
 - `format_frame(frame)`
 - `parse_auth_response(frame)`
 
+The SDK export also exposes the same frame codec through `codec`:
+
+```typescript
+import { codec } from "mtp";
+
+const frame = codec.encode("SomeType", { value: "hello" });
+const parsed = codec.decode(frame);
+const display = codec.format(frame);
+```
+
 Raw crypto and key helpers include:
 
 - `ed25519_generate()`
diff --git a/src/sdk/index.ts b/src/sdk/index.ts
index 9038e06..eabcc8a 100644
--- a/src/sdk/index.ts
+++ b/src/sdk/index.ts
@@ -75,6 +75,36 @@ export interface MTPRaw {
 
 export type MTPBytesInput = Uint8Array | number[];
 
+export interface MTPCodecOptions {
+  id?: number;
+  sender?: bigint | number;
+  receiver?: bigint | number;
+}
+
+export interface MTPCodec {
+  encode(type: MTPCommunicationType, data: Record<string, unknown>, options?: MTPCodecOptions): Uint8Array;
+  decode(frame: MTPBytesInput): ParsedFrame;
+  format(frame: MTPBytesInput): string;
+}
+
+export function encode(type: MTPCommunicationType, data: Record<string, unknown>, options?: MTPCodecOptions): Uint8Array {
+  return bindings.build_frame(type, data, options ?? {});
+}
+
+export function decode(frame: MTPBytesInput): ParsedFrame {
+  return bindings.parse_frame(bytesFrom(frame, "frame"));
+}
+
+export function format(frame: MTPBytesInput): string {
+  return bindings.format_frame(bytesFrom(frame, "frame"));
+}
+
+export const codec: MTPCodec = {
+  encode,
+  decode,
+  format,
+};
+
 export interface MTPCredentials {
   clientId: bigint | string | number | null;
   keyring: MTPBytesInput;
@@ -335,12 +365,14 @@ async function withTimeout(promise, timeoutMs, message) {
 
 export class MTPClient {
   static readonly crypto = crypto;
+  static readonly codec = codec;
 
   #credentials: InternalCredentials | null;
   #options: NormalizedMTPClientOptions;
   readonly raw: MTPRaw;
 
   readonly crypto = MTPClient.crypto;
+  readonly codec = MTPClient.codec;
 
   private constructor(options: NormalizedMTPClientOptions, client: RawBindings.WasmClient) {
     this.#options = options;