@keldra/sdk 0.1.0 → 0.1.2

package/README.md

@@ -2,6 +2,12 @@
 
 TypeScript SDK for the Keldra relay API.
 
+## Security
+
+- Use this SDK with a server-side API key only.
+- Never ship `kk_...` keys in browser/client bundles.
+- Keep `KELDRA_API_KEY` in backend environment variables.
+
 ## Install
 
 ```bash
@@ -26,7 +32,7 @@ npm install @keldra/sdk viem
 ```ts
 import { KeldraClient } from "@keldra/sdk";
 
-const client = KeldraClient.create("kk_your_api_key");
+const client = KeldraClient.fromEnv();
 const result = await client.relay("ethereum", signedTxHex);
 const limits = await client.limits();
 const usage = await client.usage("2026-02-01", "2026-02-20");
@@ -35,6 +41,49 @@ console.log(result.relayId, result.status, result.txHash);
 console.log(limits.tier, usage.totals.relays_submitted);
 ```
 
+## API Key From .env
+
+Use environment variables on your backend:
+
+```env
+KELDRA_API_KEY=kk_your_api_key
+KELDRA_GATEWAY_URL=https://relay.keldra.io
+```
+
+Then initialize directly:
+
+```ts
+import { KeldraClient } from "@keldra/sdk";
+
+const client = KeldraClient.fromEnv();
+```
+
+## Backend Proxy Example (Next.js)
+
+Keep Keldra calls on your server route:
+
+```ts
+// app/api/relay/route.ts
+import { NextRequest, NextResponse } from "next/server";
+import { KeldraClient } from "@keldra/sdk";
+
+const client = KeldraClient.fromEnv();
+
+export async function POST(req: NextRequest) {
+  const body = await req.json();
+  const { chain, signedTx } = body as { chain: "ethereum"; signedTx: string };
+
+  if (!chain || !signedTx) {
+    return NextResponse.json({ error: "chain and signedTx are required" }, { status: 400 });
+  }
+
+  const relay = await client.relay(chain, signedTx);
+  return NextResponse.json(relay);
+}
+```
+
+Frontend calls your backend endpoint, not Keldra directly.
+
 ## Encrypted Transport
 
 ```ts

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

@@ -1,5 +1,6 @@
 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';
 
+type EnvMap = Record<string, string | undefined>;
 declare class KeldraClient {
     private readonly http;
     private readonly gatewayUrl;
@@ -11,6 +12,10 @@ declare class KeldraClient {
     private readonly encryptFn?;
     constructor(config: KeldraClientConfig);
     static create(apiKey: string): KeldraClient;
+    static fromEnv(env?: EnvMap, options?: {
+        apiKeyEnv?: string;
+        gatewayUrlEnv?: string;
+    }): KeldraClient;
     static builder(): KeldraClientBuilder;
     relay(chain: Chain, signedTx: string): Promise<RelayResult>;
     submit(chain: Chain, signedTx: string): Promise<RelayResponse>;

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

@@ -1,5 +1,6 @@
 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';
 
+type EnvMap = Record<string, string | undefined>;
 declare class KeldraClient {
     private readonly http;
     private readonly gatewayUrl;
@@ -11,6 +12,10 @@ declare class KeldraClient {
     private readonly encryptFn?;
     constructor(config: KeldraClientConfig);
     static create(apiKey: string): KeldraClient;
+    static fromEnv(env?: EnvMap, options?: {
+        apiKeyEnv?: string;
+        gatewayUrlEnv?: string;
+    }): KeldraClient;
     static builder(): KeldraClientBuilder;
     relay(chain: Chain, signedTx: string): Promise<RelayResult>;
     submit(chain: Chain, signedTx: string): Promise<RelayResponse>;

package/dist/ethers/index.d.cts

@@ -1,5 +1,5 @@
 import { Signer } from 'ethers';
-import { K as KeldraClient } from '../client-Bm1hg0EA.cjs';
+import { K as KeldraClient } from '../client-COg_GErM.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-03PUOnb6.js';
+import { K as KeldraClient } from '../client-q45X0E5a.js';
 import { C as Chain, g as RelayResponse } from '../types-CL-VpP9K.js';
 
 interface KeldraBroadcasterOptions {

package/dist/index.cjs

@@ -164,6 +164,11 @@ var DEFAULT_GATEWAY_URL = "http://localhost:3400";
 var DEFAULT_TIMEOUT_MS = 3e5;
 var DEFAULT_POLL_INTERVAL_MS = 2e3;
 var MAX_POLL_INTERVAL_MS = 15e3;
+var DEFAULT_API_KEY_ENV = "KELDRA_API_KEY";
+var DEFAULT_GATEWAY_ENV = "KELDRA_GATEWAY_URL";
+function isBrowserRuntime() {
+  return typeof window !== "undefined" && typeof document !== "undefined";
+}
 var KeldraClient = class _KeldraClient {
   
   
@@ -177,6 +182,11 @@ var KeldraClient = class _KeldraClient {
     if (!config.apiKey) {
       throw KeldraError.config("apiKey is required");
     }
+    if (isBrowserRuntime() && config.apiKey.startsWith("kk_")) {
+      throw KeldraError.config(
+        "Do not use a Keldra API key in browser code. Move SDK calls to your backend."
+      );
+    }
     this.http = new HttpClient(config.apiKey);
     this.gatewayUrl = (_nullishCoalesce(config.gatewayUrl, () => ( DEFAULT_GATEWAY_URL))).replace(
       /\/$/,
@@ -192,6 +202,23 @@ 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) {
+    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 apiKey = env[apiKeyName];
+    if (!apiKey) {
+      throw KeldraError.config(`${apiKeyName} is required`);
+    }
+    return new _KeldraClient({
+      apiKey,
+      gatewayUrl: _nullishCoalesce(env[gatewayUrlName], () => ( DEFAULT_GATEWAY_URL))
+    });
+  }
   static builder() {
     return new KeldraClientBuilder();
   }
@@ -253,7 +280,7 @@ var KeldraClient = class _KeldraClient {
       }
       interval = Math.min(interval * 2, MAX_POLL_INTERVAL_MS);
     }
-    throw KeldraError.timeout(relayId, _nullishCoalesce(_optionalChain([lastStatus, 'optionalAccess', _2 => _2.status]), () => ( "queued")));
+    throw KeldraError.timeout(relayId, _nullishCoalesce(_optionalChain([lastStatus, 'optionalAccess', _6 => _6.status]), () => ( "queued")));
   }
   async health() {
     return this.http.get(`${this.gatewayUrl}/v1/health`);

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-export { K as KeldraClient, a as KeldraClientBuilder } from './client-Bm1hg0EA.cjs';
+export { K as KeldraClient, a as KeldraClientBuilder } from './client-COg_GErM.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-03PUOnb6.js';
+export { K as KeldraClient, a as KeldraClientBuilder } from './client-q45X0E5a.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

@@ -164,6 +164,11 @@ var DEFAULT_GATEWAY_URL = "http://localhost:3400";
 var DEFAULT_TIMEOUT_MS = 3e5;
 var DEFAULT_POLL_INTERVAL_MS = 2e3;
 var MAX_POLL_INTERVAL_MS = 15e3;
+var DEFAULT_API_KEY_ENV = "KELDRA_API_KEY";
+var DEFAULT_GATEWAY_ENV = "KELDRA_GATEWAY_URL";
+function isBrowserRuntime() {
+  return typeof window !== "undefined" && typeof document !== "undefined";
+}
 var KeldraClient = class _KeldraClient {
   http;
   gatewayUrl;
@@ -177,6 +182,11 @@ var KeldraClient = class _KeldraClient {
     if (!config.apiKey) {
       throw KeldraError.config("apiKey is required");
     }
+    if (isBrowserRuntime() && config.apiKey.startsWith("kk_")) {
+      throw KeldraError.config(
+        "Do not use a Keldra API key in browser code. Move SDK calls to your backend."
+      );
+    }
     this.http = new HttpClient(config.apiKey);
     this.gatewayUrl = (config.gatewayUrl ?? DEFAULT_GATEWAY_URL).replace(
       /\/$/,
@@ -192,6 +202,23 @@ var KeldraClient = class _KeldraClient {
   static create(apiKey) {
     return new _KeldraClient({ apiKey });
   }
+  static fromEnv(env = globalThis.process?.env ?? {}, options) {
+    if (isBrowserRuntime()) {
+      throw KeldraError.config(
+        "KeldraClient.fromEnv() is server-only. Load KELDRA_API_KEY on your backend."
+      );
+    }
+    const apiKeyName = options?.apiKeyEnv ?? DEFAULT_API_KEY_ENV;
+    const gatewayUrlName = options?.gatewayUrlEnv ?? DEFAULT_GATEWAY_ENV;
+    const apiKey = env[apiKeyName];
+    if (!apiKey) {
+      throw KeldraError.config(`${apiKeyName} is required`);
+    }
+    return new _KeldraClient({
+      apiKey,
+      gatewayUrl: env[gatewayUrlName] ?? DEFAULT_GATEWAY_URL
+    });
+  }
   static builder() {
     return new KeldraClientBuilder();
   }

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-Bm1hg0EA.cjs';
+import { K as KeldraClient } from '../client-COg_GErM.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-03PUOnb6.js';
+import { K as KeldraClient } from '../client-q45X0E5a.js';
 import { C as Chain } from '../types-CL-VpP9K.js';
 
 interface KeldraViemOptions {

package/package.json

@@ -1,17 +1,10 @@
 {
   "name": "@keldra/sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "TypeScript SDK for Keldra relay API",
   "license": "MIT",
   "author": "Keldra",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/jperth86/keldra_relay.git"
-  },
   "homepage": "https://keldra.network",
-  "bugs": {
-    "url": "https://github.com/jperth86/keldra_relay/issues"
-  },
   "keywords": [
     "keldra",
     "relay",
@@ -33,23 +26,51 @@
   },
   "exports": {
     ".": {
-      "import": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
-      "require": { "types": "./dist/index.d.cts", "default": "./dist/index.cjs" }
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
     },
     "./crypto": {
-      "import": { "types": "./dist/crypto/index.d.ts", "default": "./dist/crypto/index.js" },
-      "require": { "types": "./dist/crypto/index.d.cts", "default": "./dist/crypto/index.cjs" }
+      "import": {
+        "types": "./dist/crypto/index.d.ts",
+        "default": "./dist/crypto/index.js"
+      },
+      "require": {
+        "types": "./dist/crypto/index.d.cts",
+        "default": "./dist/crypto/index.cjs"
+      }
     },
     "./ethers": {
-      "import": { "types": "./dist/ethers/index.d.ts", "default": "./dist/ethers/index.js" },
-      "require": { "types": "./dist/ethers/index.d.cts", "default": "./dist/ethers/index.cjs" }
+      "import": {
+        "types": "./dist/ethers/index.d.ts",
+        "default": "./dist/ethers/index.js"
+      },
+      "require": {
+        "types": "./dist/ethers/index.d.cts",
+        "default": "./dist/ethers/index.cjs"
+      }
     },
     "./viem": {
-      "import": { "types": "./dist/viem/index.d.ts", "default": "./dist/viem/index.js" },
-      "require": { "types": "./dist/viem/index.d.cts", "default": "./dist/viem/index.cjs" }
+      "import": {
+        "types": "./dist/viem/index.d.ts",
+        "default": "./dist/viem/index.js"
+      },
+      "require": {
+        "types": "./dist/viem/index.d.cts",
+        "default": "./dist/viem/index.cjs"
+      }
     }
   },
-  "files": ["dist", "README.md", "LICENSE"],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
   "scripts": {
     "build": "tsup",
     "test": "vitest run",
@@ -65,11 +86,21 @@
     "viem": "^2.0.0"
   },
   "peerDependenciesMeta": {
-    "@stablelib/blake2s": { "optional": true },
-    "@stablelib/chacha20poly1305": { "optional": true },
-    "@stablelib/x25519": { "optional": true },
-    "ethers": { "optional": true },
-    "viem": { "optional": true }
+    "@stablelib/blake2s": {
+      "optional": true
+    },
+    "@stablelib/chacha20poly1305": {
+      "optional": true
+    },
+    "@stablelib/x25519": {
+      "optional": true
+    },
+    "ethers": {
+      "optional": true
+    },
+    "viem": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@stablelib/blake2s": "^2.0.0",