@keldra/sdk 0.1.5 → 0.1.6

package/README.md

@@ -31,8 +31,10 @@ npm install @keldra/sdk viem
 
 ```ts
 import { KeldraClient } from "@keldra/sdk";
-
-const client = KeldraClient.fromEnv();
+const client = await KeldraClient.createSecure(
+  process.env.KELDRA_API_KEY!,
+  { gatewayUrl: process.env.KELDRA_GATEWAY_URL ?? "https://keldra.network" },
+);
 const result = await client.relay("ethereum", signedTxHex);
 const limits = await client.limits();
 const usage = await client.usage("2026-02-01", "2026-02-20");
@@ -55,7 +57,7 @@ Then initialize directly:
 ```ts
 import { KeldraClient } from "@keldra/sdk";
 
-const client = KeldraClient.fromEnv();
+const client = await KeldraClient.fromEnvSecure();
 ```
 
 ## Backend Proxy Example (Next.js)
@@ -66,8 +68,10 @@ Keep Keldra calls on your server route:
 // app/api/relay/route.ts
 import { NextRequest, NextResponse } from "next/server";
 import { KeldraClient } from "@keldra/sdk";
-
-const client = KeldraClient.fromEnv();
+const client = await KeldraClient.createSecure(
+  process.env.KELDRA_API_KEY!,
+  { gatewayUrl: process.env.KELDRA_GATEWAY_URL ?? "https://keldra.network" },
+);
 
 export async function POST(req: NextRequest) {
   const body = await req.json();
@@ -92,6 +96,7 @@ import { createEncryptFn } from "@keldra/sdk/crypto";
 
 const client = KeldraClient.builder()
   .apiKey("kk_your_api_key")
+  .gatewayUrl("https://keldra.network")
   .withEncryption(createEncryptFn())
   .build();
 
@@ -105,7 +110,9 @@ const relay = await client.submit("ethereum", signedTxHex);
 import { KeldraClient } from "@keldra/sdk";
 import { wrapSigner } from "@keldra/sdk/ethers";
 
-const client = KeldraClient.create("kk_your_api_key");
+const client = await KeldraClient.createSecure("kk_your_api_key", {
+  gatewayUrl: "https://keldra.network",
+});
 const signer = wrapSigner(originalSigner, { client, chain: "ethereum" });
 
 const tx = await signer.sendTransaction({ to, value });
@@ -118,7 +125,9 @@ console.log(tx.hash);
 import { KeldraClient } from "@keldra/sdk";
 import { wrapWalletClient } from "@keldra/sdk/viem";
 
-const client = KeldraClient.create("kk_your_api_key");
+const client = await KeldraClient.createSecure("kk_your_api_key", {
+  gatewayUrl: "https://keldra.network",
+});
 const walletClient = wrapWalletClient(originalWalletClient, { client, chain: "ethereum" });
 
 const relayId = await walletClient.sendTransaction({ to, value });

package/dist/{client-q45X0E5a.d.ts → client-CFSlZ1qY.d.ts}

@@ -1,4 +1,4 @@
-import { K as KeldraClientConfig, D as DelayProfile, E as EncryptFn, C as Chain, h as RelayResult, g as RelayResponse, i as RelayStatusResponse, H as HealthResponse, b as ChainsResponse, M as MeLimitsResponse, d as MeUsageResponse } from './types-CL-VpP9K.js';
+import { K as KeldraClientConfig, E as EncryptFn, D as DelayProfile, C as Chain, h as RelayResult, g as RelayResponse, i as RelayStatusResponse, H as HealthResponse, b as ChainsResponse, M as MeLimitsResponse, d as MeUsageResponse } from './types-CL-VpP9K.js';
 
 type EnvMap = Record<string, string | undefined>;
 declare class KeldraClient {
@@ -12,10 +12,18 @@ declare class KeldraClient {
     private readonly encryptFn?;
     constructor(config: KeldraClientConfig);
     static create(apiKey: string): KeldraClient;
+    static createSecure(apiKey: string, options?: Omit<KeldraClientConfig, 'apiKey' | 'encryptFn' | 'noisePublicKey' | 'noiseKid'> & {
+        encryptFn?: EncryptFn;
+    }): Promise<KeldraClient>;
     static fromEnv(env?: EnvMap, options?: {
         apiKeyEnv?: string;
         gatewayUrlEnv?: string;
     }): KeldraClient;
+    static fromEnvSecure(env?: EnvMap, options?: {
+        apiKeyEnv?: string;
+        gatewayUrlEnv?: string;
+        encryptFn?: EncryptFn;
+    }): Promise<KeldraClient>;
     static builder(): KeldraClientBuilder;
     relay(chain: Chain, signedTx: string): Promise<RelayResult>;
     submit(chain: Chain, signedTx: string): Promise<RelayResponse>;
@@ -27,6 +35,7 @@ declare class KeldraClient {
     usage(from: string, to: string): Promise<MeUsageResponse>;
     fetchNoiseKey(): Promise<void>;
     get encrypted(): boolean;
+    private static resolveEncryptFn;
 }
 declare class KeldraClientBuilder {
     private config;

package/dist/{client-COg_GErM.d.cts → client-u777j3mH.d.cts}

@@ -1,4 +1,4 @@
-import { K as KeldraClientConfig, D as DelayProfile, E as EncryptFn, C as Chain, h as RelayResult, g as RelayResponse, i as RelayStatusResponse, H as HealthResponse, b as ChainsResponse, M as MeLimitsResponse, d as MeUsageResponse } from './types-CL-VpP9K.cjs';
+import { K as KeldraClientConfig, E as EncryptFn, D as DelayProfile, C as Chain, h as RelayResult, g as RelayResponse, i as RelayStatusResponse, H as HealthResponse, b as ChainsResponse, M as MeLimitsResponse, d as MeUsageResponse } from './types-CL-VpP9K.cjs';
 
 type EnvMap = Record<string, string | undefined>;
 declare class KeldraClient {
@@ -12,10 +12,18 @@ declare class KeldraClient {
     private readonly encryptFn?;
     constructor(config: KeldraClientConfig);
     static create(apiKey: string): KeldraClient;
+    static createSecure(apiKey: string, options?: Omit<KeldraClientConfig, 'apiKey' | 'encryptFn' | 'noisePublicKey' | 'noiseKid'> & {
+        encryptFn?: EncryptFn;
+    }): Promise<KeldraClient>;
     static fromEnv(env?: EnvMap, options?: {
         apiKeyEnv?: string;
         gatewayUrlEnv?: string;
     }): KeldraClient;
+    static fromEnvSecure(env?: EnvMap, options?: {
+        apiKeyEnv?: string;
+        gatewayUrlEnv?: string;
+        encryptFn?: EncryptFn;
+    }): Promise<KeldraClient>;
     static builder(): KeldraClientBuilder;
     relay(chain: Chain, signedTx: string): Promise<RelayResult>;
     submit(chain: Chain, signedTx: string): Promise<RelayResponse>;
@@ -27,6 +35,7 @@ declare class KeldraClient {
     usage(from: string, to: string): Promise<MeUsageResponse>;
     fetchNoiseKey(): Promise<void>;
     get encrypted(): boolean;
+    private static resolveEncryptFn;
 }
 declare class KeldraClientBuilder {
     private config;

package/dist/ethers/index.d.cts

@@ -1,5 +1,5 @@
 import { Signer } from 'ethers';
-import { K as KeldraClient } from '../client-COg_GErM.cjs';
+import { K as KeldraClient } from '../client-u777j3mH.cjs';
 import { C as Chain, g as RelayResponse } from '../types-CL-VpP9K.cjs';
 
 interface KeldraBroadcasterOptions {

package/dist/ethers/index.d.ts

@@ -1,5 +1,5 @@
 import { Signer } from 'ethers';
-import { K as KeldraClient } from '../client-q45X0E5a.js';
+import { K as KeldraClient } from '../client-CFSlZ1qY.js';
 import { C as Chain, g as RelayResponse } from '../types-CL-VpP9K.js';
 
 interface KeldraBroadcasterOptions {

package/dist/index.cjs

@@ -1,4 +1,4 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; } var _class;// src/errors.ts
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireWildcard(obj) { if (obj && obj.__esModule) { return obj; } else { var newObj = {}; if (obj != null) { for (var key in obj) { if (Object.prototype.hasOwnProperty.call(obj, key)) { newObj[key] = obj[key]; } } } newObj.default = obj; return newObj; } } function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } async function _asyncNullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return await rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; } async function _asyncOptionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = await fn(value); } else if (op === 'call' || op === 'optionalCall') { value = await fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; } var _class;// src/errors.ts
 var KeldraError = class _KeldraError extends Error {
   
   
@@ -64,9 +64,6 @@ function parseHex(hexStr) {
   }
   return bytes;
 }
-function toHex(bytes) {
-  return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
-}
 function toBase64(bytes) {
   if (typeof Buffer !== "undefined") {
     return Buffer.from(bytes).toString("base64");
@@ -202,14 +199,24 @@ var KeldraClient = class _KeldraClient {
   static create(apiKey) {
     return new _KeldraClient({ apiKey });
   }
-  static fromEnv(env = _nullishCoalesce(_optionalChain([globalThis, 'access', _2 => _2.process, 'optionalAccess', _3 => _3.env]), () => ( {})), options) {
+  static async createSecure(apiKey, options) {
+    const encryptFn = await _asyncNullishCoalesce(await _asyncOptionalChain([options, 'optionalAccess', async _2 => _2.encryptFn]), async () => ( await _KeldraClient.resolveEncryptFn()));
+    const client = new _KeldraClient({
+      ...options,
+      apiKey,
+      encryptFn
+    });
+    await client.fetchNoiseKey();
+    return client;
+  }
+  static fromEnv(env = _nullishCoalesce(_optionalChain([globalThis, 'access', _3 => _3.process, 'optionalAccess', _4 => _4.env]), () => ( {})), options) {
     if (isBrowserRuntime()) {
       throw KeldraError.config(
         "KeldraClient.fromEnv() is server-only. Load KELDRA_API_KEY on your backend."
       );
     }
-    const apiKeyName = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _4 => _4.apiKeyEnv]), () => ( DEFAULT_API_KEY_ENV));
-    const gatewayUrlName = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _5 => _5.gatewayUrlEnv]), () => ( DEFAULT_GATEWAY_ENV));
+    const apiKeyName = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _5 => _5.apiKeyEnv]), () => ( DEFAULT_API_KEY_ENV));
+    const gatewayUrlName = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _6 => _6.gatewayUrlEnv]), () => ( DEFAULT_GATEWAY_ENV));
     const apiKey = env[apiKeyName];
     if (!apiKey) {
       throw KeldraError.config(`${apiKeyName} is required`);
@@ -219,6 +226,19 @@ var KeldraClient = class _KeldraClient {
       gatewayUrl: _nullishCoalesce(env[gatewayUrlName], () => ( DEFAULT_GATEWAY_URL))
     });
   }
+  static async fromEnvSecure(env = _nullishCoalesce(_optionalChain([globalThis, 'access', _7 => _7.process, 'optionalAccess', _8 => _8.env]), () => ( {})), options) {
+    const apiKeyName = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _9 => _9.apiKeyEnv]), () => ( DEFAULT_API_KEY_ENV));
+    const gatewayUrlName = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _10 => _10.gatewayUrlEnv]), () => ( DEFAULT_GATEWAY_ENV));
+    const apiKey = env[apiKeyName];
+    const gatewayUrl = _nullishCoalesce(env[gatewayUrlName], () => ( DEFAULT_GATEWAY_URL));
+    if (!apiKey) {
+      throw KeldraError.config(`${apiKeyName} is required`);
+    }
+    return _KeldraClient.createSecure(apiKey, {
+      gatewayUrl,
+      encryptFn: _optionalChain([options, 'optionalAccess', _11 => _11.encryptFn])
+    });
+  }
   static builder() {
     return new KeldraClientBuilder();
   }
@@ -236,26 +256,21 @@ var KeldraClient = class _KeldraClient {
   }
   async submit(chain, signedTx) {
     const rawBytes = parseHex(signedTx);
-    let request;
-    if (this.noisePublicKey && this.noiseKid && this.encryptFn) {
-      const padded = padTransaction(rawBytes);
-      const encrypted = await this.encryptFn(padded, this.noisePublicKey);
-      const b64 = toBase64(encrypted);
-      request = {
-        chain,
-        signed_tx: "",
-        options: { delay_profile: this.defaultDelayProfile },
-        encrypted_payload: b64,
-        noise_kid: this.noiseKid
-      };
-    } else {
-      request = {
-        chain,
-        // Plain submit must keep the original signed tx bytes.
-        signed_tx: signedTx.startsWith("0x") ? signedTx : `0x${toHex(rawBytes)}`,
-        options: { delay_profile: this.defaultDelayProfile }
-      };
+    if (!(this.noisePublicKey && this.noiseKid && this.encryptFn)) {
+      throw KeldraError.config(
+        "Encryption is required. Configure .withEncryption(createEncryptFn()) and call fetchNoiseKey() before submit()."
+      );
     }
+    const padded = padTransaction(rawBytes);
+    const encrypted = await this.encryptFn(padded, this.noisePublicKey);
+    const b64 = toBase64(encrypted);
+    const request = {
+      chain,
+      signed_tx: "",
+      options: { delay_profile: this.defaultDelayProfile },
+      encrypted_payload: b64,
+      noise_kid: this.noiseKid
+    };
     return this.http.post(
       `${this.gatewayUrl}/v1/relay`,
       request
@@ -281,7 +296,7 @@ var KeldraClient = class _KeldraClient {
       }
       interval = Math.min(interval * 2, MAX_POLL_INTERVAL_MS);
     }
-    throw KeldraError.timeout(relayId, _nullishCoalesce(_optionalChain([lastStatus, 'optionalAccess', _6 => _6.status]), () => ( "queued")));
+    throw KeldraError.timeout(relayId, _nullishCoalesce(_optionalChain([lastStatus, 'optionalAccess', _12 => _12.status]), () => ( "queued")));
   }
   async health() {
     return this.http.get(`${this.gatewayUrl}/v1/health`);
@@ -308,6 +323,16 @@ var KeldraClient = class _KeldraClient {
   get encrypted() {
     return !!(this.noisePublicKey && this.noiseKid && this.encryptFn);
   }
+  static async resolveEncryptFn() {
+    try {
+      const mod = await Promise.resolve().then(() => _interopRequireWildcard(require("./crypto/index.cjs")));
+      return mod.createEncryptFn();
+    } catch (e3) {
+      throw KeldraError.config(
+        "Encryption helpers are not installed. Install @stablelib/x25519 @stablelib/chacha20poly1305 @stablelib/blake2s or provide encryptFn manually."
+      );
+    }
+  }
 };
 var KeldraClientBuilder = (_class = class {constructor() { _class.prototype.__init.call(this); }
   __init() {this.config = {}}

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-export { K as KeldraClient, a as KeldraClientBuilder } from './client-COg_GErM.cjs';
+export { K as KeldraClient, a as KeldraClientBuilder } from './client-u777j3mH.cjs';
 import { R as RelayStatus } from './types-CL-VpP9K.cjs';
 export { C as Chain, a as ChainConfig, b as ChainsResponse, D as DelayProfile, E as EncryptFn, H as HealthResponse, c as HealthStats, K as KeldraClientConfig, M as MeLimitsResponse, d as MeUsageResponse, N as NoiseKeyResponse, e as RelayOptions, f as RelayRequest, g as RelayResponse, h as RelayResult, i as RelayStatusResponse, T as TERMINAL_STATUSES, U as UsageDailyRow, j as UsageTotals } from './types-CL-VpP9K.cjs';
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { K as KeldraClient, a as KeldraClientBuilder } from './client-q45X0E5a.js';
+export { K as KeldraClient, a as KeldraClientBuilder } from './client-CFSlZ1qY.js';
 import { R as RelayStatus } from './types-CL-VpP9K.js';
 export { C as Chain, a as ChainConfig, b as ChainsResponse, D as DelayProfile, E as EncryptFn, H as HealthResponse, c as HealthStats, K as KeldraClientConfig, M as MeLimitsResponse, d as MeUsageResponse, N as NoiseKeyResponse, e as RelayOptions, f as RelayRequest, g as RelayResponse, h as RelayResult, i as RelayStatusResponse, T as TERMINAL_STATUSES, U as UsageDailyRow, j as UsageTotals } from './types-CL-VpP9K.js';
 

package/dist/index.js

@@ -64,9 +64,6 @@ function parseHex(hexStr) {
   }
   return bytes;
 }
-function toHex(bytes) {
-  return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
-}
 function toBase64(bytes) {
   if (typeof Buffer !== "undefined") {
     return Buffer.from(bytes).toString("base64");
@@ -202,6 +199,16 @@ var KeldraClient = class _KeldraClient {
   static create(apiKey) {
     return new _KeldraClient({ apiKey });
   }
+  static async createSecure(apiKey, options) {
+    const encryptFn = options?.encryptFn ?? await _KeldraClient.resolveEncryptFn();
+    const client = new _KeldraClient({
+      ...options,
+      apiKey,
+      encryptFn
+    });
+    await client.fetchNoiseKey();
+    return client;
+  }
   static fromEnv(env = globalThis.process?.env ?? {}, options) {
     if (isBrowserRuntime()) {
       throw KeldraError.config(
@@ -219,6 +226,19 @@ var KeldraClient = class _KeldraClient {
       gatewayUrl: env[gatewayUrlName] ?? DEFAULT_GATEWAY_URL
     });
   }
+  static async fromEnvSecure(env = globalThis.process?.env ?? {}, options) {
+    const apiKeyName = options?.apiKeyEnv ?? DEFAULT_API_KEY_ENV;
+    const gatewayUrlName = options?.gatewayUrlEnv ?? DEFAULT_GATEWAY_ENV;
+    const apiKey = env[apiKeyName];
+    const gatewayUrl = env[gatewayUrlName] ?? DEFAULT_GATEWAY_URL;
+    if (!apiKey) {
+      throw KeldraError.config(`${apiKeyName} is required`);
+    }
+    return _KeldraClient.createSecure(apiKey, {
+      gatewayUrl,
+      encryptFn: options?.encryptFn
+    });
+  }
   static builder() {
     return new KeldraClientBuilder();
   }
@@ -236,26 +256,21 @@ var KeldraClient = class _KeldraClient {
   }
   async submit(chain, signedTx) {
     const rawBytes = parseHex(signedTx);
-    let request;
-    if (this.noisePublicKey && this.noiseKid && this.encryptFn) {
-      const padded = padTransaction(rawBytes);
-      const encrypted = await this.encryptFn(padded, this.noisePublicKey);
-      const b64 = toBase64(encrypted);
-      request = {
-        chain,
-        signed_tx: "",
-        options: { delay_profile: this.defaultDelayProfile },
-        encrypted_payload: b64,
-        noise_kid: this.noiseKid
-      };
-    } else {
-      request = {
-        chain,
-        // Plain submit must keep the original signed tx bytes.
-        signed_tx: signedTx.startsWith("0x") ? signedTx : `0x${toHex(rawBytes)}`,
-        options: { delay_profile: this.defaultDelayProfile }
-      };
+    if (!(this.noisePublicKey && this.noiseKid && this.encryptFn)) {
+      throw KeldraError.config(
+        "Encryption is required. Configure .withEncryption(createEncryptFn()) and call fetchNoiseKey() before submit()."
+      );
     }
+    const padded = padTransaction(rawBytes);
+    const encrypted = await this.encryptFn(padded, this.noisePublicKey);
+    const b64 = toBase64(encrypted);
+    const request = {
+      chain,
+      signed_tx: "",
+      options: { delay_profile: this.defaultDelayProfile },
+      encrypted_payload: b64,
+      noise_kid: this.noiseKid
+    };
     return this.http.post(
       `${this.gatewayUrl}/v1/relay`,
       request
@@ -308,6 +323,16 @@ var KeldraClient = class _KeldraClient {
   get encrypted() {
     return !!(this.noisePublicKey && this.noiseKid && this.encryptFn);
   }
+  static async resolveEncryptFn() {
+    try {
+      const mod = await import("./crypto/index.js");
+      return mod.createEncryptFn();
+    } catch {
+      throw KeldraError.config(
+        "Encryption helpers are not installed. Install @stablelib/x25519 @stablelib/chacha20poly1305 @stablelib/blake2s or provide encryptFn manually."
+      );
+    }
+  }
 };
 var KeldraClientBuilder = class {
   config = {};

package/dist/viem/index.d.cts

@@ -1,5 +1,5 @@
 import { Transport, Chain as Chain$1, Account, WalletClient } from 'viem';
-import { K as KeldraClient } from '../client-COg_GErM.cjs';
+import { K as KeldraClient } from '../client-u777j3mH.cjs';
 import { C as Chain } from '../types-CL-VpP9K.cjs';
 
 interface KeldraViemOptions {

package/dist/viem/index.d.ts

@@ -1,5 +1,5 @@
 import { Transport, Chain as Chain$1, Account, WalletClient } from 'viem';
-import { K as KeldraClient } from '../client-q45X0E5a.js';
+import { K as KeldraClient } from '../client-CFSlZ1qY.js';
 import { C as Chain } from '../types-CL-VpP9K.js';
 
 interface KeldraViemOptions {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keldra/sdk",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "TypeScript SDK for Keldra relay API",
   "license": "MIT",
   "author": "Keldra",