chainmerge-sdk 0.1.2

package/README.md

@@ -0,0 +1,86 @@
+# chainmerge-sdk
+
+TypeScript/JavaScript SDK for the ChainMerge multichain transaction decoder API.
+
+ChainMerge normalizes transactions from multiple chains (Ethereum, Solana, Cosmos, Aptos, Sui, Polkadot, Bitcoin, Starknet, etc.) into a single JSON shape. This SDK makes it easy for dapps, wallets, and backends to call the `/api/decode` endpoint and work with typed results.
+
+## Installation
+
+```bash
+npm install chainmerge-sdk
+# or
+yarn add chainmerge-sdk
+```
+
+## Quick start
+
+```ts
+import { ChainMergeClient } from "chainmerge-sdk";
+
+const client = new ChainMergeClient({
+  baseUrl: "http://127.0.0.1:8080", // or your hosted URL
+  // apiKey: "optional-api-key",
+});
+
+async function main() {
+  const tx = await client.decodeTx({
+    chain: "ethereum",
+    hash: "0xd5d0587189f3411699ae946baa2a7d3ebfaf13133f9014a22bab6948591611ad",
+  });
+
+  console.log("normalized tx:", tx);
+
+  for (const event of tx.events) {
+    if (event.event_type === "token_transfer") {
+      console.log(
+        `Token transfer of ${event.amount} from ${event.from} to ${event.to} (token: ${event.token})`,
+      );
+    }
+  }
+}
+
+main().catch((err) => {
+  console.error("decode failed:", err);
+});
+```
+
+## API
+
+### `new ChainMergeClient(options)`
+
+- **`baseUrl`** (string, required): Base URL of the ChainMerge API (`http://127.0.0.1:8080`, `https://api.chainmerge.io`, etc.). No trailing slash.
+- **`apiKey`** (string, optional): Sent as `x-api-key` header if provided.
+- **`fetchImpl`** (function, optional): Custom `fetch` implementation for environments where `fetch` is not global (e.g. Node.js < 18).
+
+### `client.decodeTx({ chain, hash, rpcUrl? })`
+
+Decode a single transaction.
+
+- **`chain`**: One of `"solana" | "ethereum" | "cosmos" | "aptos" | "sui" | "polkadot" | "bitcoin" | "starknet"`.
+- **`hash`**: Transaction hash string.
+- **`rpcUrl`** (optional): Override RPC URL for this request; if omitted, ChainMerge's internal defaults and env config are used.
+
+Returns a `Promise<NormalizedTransaction>`, where:
+
+- `NormalizedTransaction` includes:
+  - `chain`, `tx_hash`, `sender?`, `receiver?`, `value?`
+  - `events: NormalizedEvent[]`, with event types like `"token_transfer"`.
+
+Errors from the API are thrown as `Error` instances with extra properties:
+
+- `error.code`
+- `error.retryable`
+
+## Publishing (repo maintainers)
+
+From the `sdk/js` directory:
+
+```bash
+npm install
+npm run build
+
+# first time: npm login
+npm publish --access public
+```
+
+Make sure you bump the `version` field in `package.json` before publishing a new release.

package/dist/client.d.ts

@@ -0,0 +1,35 @@
+import type { Chain, NormalizedTransaction } from "./types.js";
+export interface ChainMergeClientOptions {
+    /**
+     * Base URL of the ChainMerge API, e.g.:
+     * - "http://127.0.0.1:8080" for local development
+     * - "https://api.chainmerge.io" for a hosted deployment
+     *
+     * Do not include a trailing slash.
+     */
+    baseUrl: string;
+    /**
+     * Optional API key that will be sent as "x-api-key".
+     */
+    apiKey?: string;
+    /**
+     * Custom fetch implementation for environments where "fetch"
+     * is not globally available (e.g. Node < 18).
+     */
+    fetchImpl?: typeof fetch;
+}
+export declare class ChainMergeClient {
+    private readonly baseUrl;
+    private readonly apiKey?;
+    private readonly fetchImpl;
+    constructor(options: ChainMergeClientOptions);
+    /**
+     * Decode a single transaction into a normalized representation.
+     */
+    decodeTx(params: {
+        chain: Chain;
+        hash: string;
+        rpcUrl?: string;
+    }): Promise<NormalizedTransaction>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAA8C,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAE3G,MAAM,WAAW,uBAAuB;IACtC;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAE7B,OAAO,EAAE,uBAAuB;IAU5C;;OAEG;IACG,QAAQ,CAAC,MAAM,EAAE;QACrB,KAAK,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAiCnC"}

package/dist/client.js

@@ -0,0 +1,38 @@
+export class ChainMergeClient {
+    constructor(options) {
+        if (!options.baseUrl) {
+            throw new Error("ChainMergeClient: baseUrl is required");
+        }
+        this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+        this.apiKey = options.apiKey;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+    }
+    /**
+     * Decode a single transaction into a normalized representation.
+     */
+    async decodeTx(params) {
+        const search = new URLSearchParams({
+            chain: params.chain,
+            hash: params.hash.trim(),
+        });
+        if (params.rpcUrl?.trim()) {
+            search.set("rpc_url", params.rpcUrl.trim());
+        }
+        const url = `${this.baseUrl}/api/decode?${search.toString()}`;
+        const res = await this.fetchImpl(url, {
+            headers: {
+                ...(this.apiKey ? { "x-api-key": this.apiKey } : null),
+            },
+        });
+        const body = (await res.json());
+        if (!res.ok) {
+            const envelope = body;
+            const error = new Error(envelope.error.message);
+            error.code = envelope.error.code;
+            error.retryable = envelope.error.retryable;
+            throw error;
+        }
+        const envelope = body;
+        return envelope.decoded;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./client.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export * from "./client.js";

package/dist/types.d.ts

@@ -0,0 +1,40 @@
+export type Chain = "solana" | "ethereum" | "cosmos" | "aptos" | "sui" | "polkadot" | "bitcoin" | "starknet";
+export type EventType = "token_transfer" | "unsupported";
+export interface NormalizedEvent {
+    event_type: EventType;
+    token?: string;
+    from?: string;
+    to?: string;
+    amount?: string;
+    raw_program?: string;
+}
+export type ActionType = "transfer" | "swap" | "nft_transfer" | "stake" | "bridge" | "unknown";
+export interface Action {
+    action_type: ActionType;
+    from?: string;
+    to?: string;
+    amount?: string;
+    token?: string;
+    metadata?: unknown;
+}
+export interface NormalizedTransaction {
+    chain: Chain;
+    tx_hash: string;
+    sender?: string;
+    receiver?: string;
+    value?: string;
+    events: NormalizedEvent[];
+    actions: Action[];
+}
+export interface ErrorEnvelope {
+    code: string;
+    message: string;
+    retryable: boolean;
+}
+export interface DecodeSuccessEnvelope {
+    decoded: NormalizedTransaction;
+}
+export interface DecodeErrorEnvelope {
+    error: ErrorEnvelope;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,KAAK,GACb,QAAQ,GACR,UAAU,GACV,QAAQ,GACR,OAAO,GACP,KAAK,GACL,UAAU,GACV,SAAS,GACT,UAAU,CAAC;AAEf,MAAM,MAAM,SAAS,GAAG,gBAAgB,GAAG,aAAa,CAAC;AAEzD,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,SAAS,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,UAAU,GAClB,UAAU,GACV,MAAM,GACN,cAAc,GACd,OAAO,GACP,QAAQ,GACR,SAAS,CAAC;AAEd,MAAM,WAAW,MAAM;IACrB,WAAW,EAAE,UAAU,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,qBAAqB,CAAC;CAChC;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,aAAa,CAAC;CACtB"}

package/dist/types.js

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

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "chainmerge-sdk",
+  "version": "0.1.2",
+  "description": "TypeScript/JavaScript SDK for the ChainMerge multichain transaction decoder API.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "lint": "echo \"no lint configured\"",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "blockchain",
+    "multichain",
+    "sdk",
+    "transaction-decoder",
+    "chainmerge"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/I-lost-everytime/Chaincodec.git"
+  },
+  "bugs": {
+    "url": "https://github.com/I-lost-everytime/Chaincodec/issues"
+  },
+  "homepage": "https://github.com/I-lost-everytime/Chaincodec#readme",
+  "devDependencies": {
+    "typescript": "^5.6.3"
+  }
+}