clutch-hub-sdk-js 4.0.0 → 4.1.0

package/.github/workflows/npm-publish.yml

@@ -46,6 +46,9 @@ jobs:
       - name: Build package
         run: npm run build
 
+      - name: Test (against dist/)
+        run: npm test
+
       - name: Run semantic-release
         id: semantic-release
         run: |

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [4.1.0](https://github.com/clutchprotocol/clutch-hub-sdk-js/compare/v4.0.0...v4.1.0) (2026-09-10)
+
+
+### Features
+
+* bound every hub HTTP request with a timeout ([bdd1b3d](https://github.com/clutchprotocol/clutch-hub-sdk-js/commit/bdd1b3dae5f9335c7acd6b0cc2c9bfa3df836809))
+
+
+### Bug Fixes
+
+* normalize hash arguments before querying the hub for offers ([1cd0dfd](https://github.com/clutchprotocol/clutch-hub-sdk-js/commit/1cd0dfd63616b3ee7554770ec644cce1c6a711fb))
+
 ## [4.0.0](https://github.com/clutchprotocol/clutch-hub-sdk-js/compare/v3.0.0...v4.0.0) (2026-09-04)
 
 

package/CLAUDE.md

@@ -19,8 +19,10 @@ Only four source files — the SDK is deliberately small:
   `Signature`, …).
 - `src/index.ts` — barrel re-exports. New public symbols must be reachable from here.
 
-There is no test suite. `test_rlp_fix.{js,mjs}` are ad-hoc manual scripts run against `dist/` after
-`npm run build` — not wired into CI.
+Tests live in `test/*.test.mjs` and use Node's built-in runner (`npm test` → `node --test test/`),
+no framework. They import from `dist/`, so `npm run build` first; the release workflow runs them
+after the build and before semantic-release. `test_rlp_fix.{js,mjs}` and `test_wire_v3.mjs` at the
+repo root are older ad-hoc manual scripts, not part of `npm test`.
 
 ## Transaction Lifecycle (client side)
 
@@ -44,7 +46,11 @@ legacy JSON-string quoting); empty referrer encodes as `''`.
 
 ## Public API Surface (`ClutchHubSdk`)
 
-- **Constructor / identity**: `new ClutchHubSdk(apiUrl, publicKey, privateKey?)`, `getPublicKey()`,
+- **Constructor / identity**: `new ClutchHubSdk(apiUrl, publicKey, privateKey?, chainId?, options?)`
+  where `options.timeoutMs` bounds every hub HTTP request (default `DEFAULT_HTTP_TIMEOUT_MS`,
+  30 s; `0` disables). Hash arguments to `listRideOffers`/`subscribeRideOffers` go through
+  `normalizeTxHashForQuery` (strip `0x`, lowercase) because the hub matches them as exact
+  strings. `getPublicKey()`,
   `setPrivateKey(privateKey)`, `isAuthenticated()`. The private key (constructor arg or
   `setPrivateKey`) is required for token issuance — `generateToken` demands a signed
   proof-of-key-ownership challenge. It is kept in a module-global map keyed by publicKey

package/README.md

@@ -25,18 +25,22 @@ import { ClutchHubSdk } from 'clutch-hub-sdk-js';
 
 // privateKey is needed for authenticated calls: generateToken requires a signed
 // proof-of-key-ownership challenge (the key stays local, it is never sent).
-const sdk = new ClutchHubSdk('http://localhost:3000', publicKey, privateKey);
+// chainId comes from your own config, never from the hub. The optional fifth argument
+// sets the HTTP timeout (default 30 s; 0 disables it).
+const sdk = new ClutchHubSdk('http://localhost:3000', publicKey, privateKey, 2077, { timeoutMs: 30_000 });
 
-// Create, sign, and submit a ride request
+// Create, sign, and submit a ride request. Amounts are bigint: 1 USD = 1,000,000 CLT.
 const unsigned = await sdk.createUnsignedRideRequest({
   pickup: { latitude: 35.7, longitude: 51.4 },
   dropoff: { latitude: 35.8, longitude: 51.5 },
-  fare: 1000,
+  fare: 5_000_000n,
 });
-const signed = await sdk.signTransaction(unsigned, privateKey);
+const signed = await sdk.signTransaction(unsigned, privateKey, { type: 'RideRequest', fare: 5_000_000n });
 await sdk.submitTransaction(signed.rawTransaction);
 ```
 
+Hash arguments (`listRideOffers`, `subscribeRideOffers`) accept the `0x`-prefixed form that `signTransaction` returns; the SDK normalizes them to the form the hub matches on.
+
 ## Features
 
 - Client-side signing (private keys never sent to server)

package/dist/sdk.d.ts

@@ -8,6 +8,18 @@ export declare function stripHexPrefix(hex: string): string;
  * and remove the `0x` prefix.
  */
 export declare function normalizeTxHashForRlp(hex: string): string;
+/** Default timeout for every HTTP request the SDK makes to the hub, in milliseconds. */
+export declare const DEFAULT_HTTP_TIMEOUT_MS = 30000;
+/** Optional settings for {@link ClutchHubSdk}. */
+export interface ClutchHubSdkOptions {
+    /**
+     * HTTP timeout for every hub request (queries, mutations, `generateToken`), in milliseconds.
+     * Defaults to {@link DEFAULT_HTTP_TIMEOUT_MS}. `0` disables it, which is what the SDK did
+     * before this option existed: a request the hub never answered hung the caller forever.
+     * Subscriptions ride on graphql-ws and are unaffected.
+     */
+    timeoutMs?: number;
+}
 declare global {
     interface Window {
         Buffer: typeof Buffer;
@@ -118,8 +130,10 @@ export declare class ClutchHubSdk {
      *   it is defeats the check chain_id exists to provide. If omitted, `signTransaction` still
      *   verifies every other `expected` field but skips the chain_id pin (nothing was pinned to
      *   check against) rather than failing every real transaction against a phantom "chain 0".
+     * @param options Optional settings — see {@link ClutchHubSdkOptions}. Today that is the HTTP
+     *   timeout (`timeoutMs`, default {@link DEFAULT_HTTP_TIMEOUT_MS}).
      */
-    constructor(apiUrl: string, publicKey: string, privateKey?: string, chainId?: number);
+    constructor(apiUrl: string, publicKey: string, privateKey?: string, chainId?: number, options?: ClutchHubSdkOptions);
     /**
      * Get the current public key associated with this SDK instance.
      * @returns The public key string

package/dist/sdk.js

@@ -30,6 +30,17 @@ export function normalizeTxHashForRlp(hex) {
     }
     return stripHexPrefix(s);
 }
+/**
+ * The hub stores transaction hashes as 64 lowercase hex characters with no `0x`, and its
+ * hash-taking query arguments (`listRideOffers`, `rideOffersUpdated`) match as exact strings.
+ * A hash as returned by `signTransaction` (`0x…`) therefore has to be normalized before it
+ * can be queried with, or the hub answers with an empty list.
+ */
+function normalizeTxHashForQuery(hex) {
+    return normalizeTxHashForRlp(hex).toLowerCase();
+}
+/** Default timeout for every HTTP request the SDK makes to the hub, in milliseconds. */
+export const DEFAULT_HTTP_TIMEOUT_MS = 30000;
 if (typeof window !== 'undefined' && !window.Buffer) {
     window.Buffer = Buffer;
 }
@@ -273,11 +284,16 @@ export class ClutchHubSdk {
      *   it is defeats the check chain_id exists to provide. If omitted, `signTransaction` still
      *   verifies every other `expected` field but skips the chain_id pin (nothing was pinned to
      *   check against) rather than failing every real transaction against a phantom "chain 0".
+     * @param options Optional settings — see {@link ClutchHubSdkOptions}. Today that is the HTTP
+     *   timeout (`timeoutMs`, default {@link DEFAULT_HTTP_TIMEOUT_MS}).
      */
-    constructor(apiUrl, publicKey, privateKey, chainId) {
+    constructor(apiUrl, publicKey, privateKey, chainId, options = {}) {
         this.token = null;
         this.tokenExpireTime = 0;
-        this.apiClient = axios.create({ baseURL: apiUrl });
+        this.apiClient = axios.create({
+            baseURL: apiUrl,
+            timeout: options.timeoutMs ?? DEFAULT_HTTP_TIMEOUT_MS,
+        });
         this.publicKey = publicKey;
         this.chainId = chainId ?? 0;
         this.chainIdConfigured = chainId !== undefined;
@@ -664,7 +680,7 @@ export class ClutchHubSdk {
         }
       }
     `;
-        return this.subscribeGraphqlListField(query, { rideRequestTxHash }, 'rideOffersUpdated', handlers);
+        return this.subscribeGraphqlListField(query, { rideRequestTxHash: normalizeTxHashForQuery(rideRequestTxHash) }, 'rideOffersUpdated', handlers);
     }
     /**
      * Subscribe to active trips, optionally filtered by driver or passenger address.
@@ -745,7 +761,7 @@ export class ClutchHubSdk {
         }
       }
     `;
-        const result = await this.executeGraphQL(query, { rideRequestTxHash });
+        const result = await this.executeGraphQL(query, { rideRequestTxHash: normalizeTxHashForQuery(rideRequestTxHash) });
         return result.listRideOffers.map((r) => ({ ...r, fare: BigInt(r.fare) }));
     }
     /**

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "clutch-hub-sdk-js",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "JavaScript SDK for interacting with the clutch-hub-api",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "tsc",
+    "test": "node --test test/",
     "prepare": "npm run build"
   },
   "keywords": [

package/src/sdk.ts

@@ -56,6 +56,30 @@ export function normalizeTxHashForRlp(hex: string): string {
   return stripHexPrefix(s);
 }
 
+/**
+ * The hub stores transaction hashes as 64 lowercase hex characters with no `0x`, and its
+ * hash-taking query arguments (`listRideOffers`, `rideOffersUpdated`) match as exact strings.
+ * A hash as returned by `signTransaction` (`0x…`) therefore has to be normalized before it
+ * can be queried with, or the hub answers with an empty list.
+ */
+function normalizeTxHashForQuery(hex: string): string {
+  return normalizeTxHashForRlp(hex).toLowerCase();
+}
+
+/** Default timeout for every HTTP request the SDK makes to the hub, in milliseconds. */
+export const DEFAULT_HTTP_TIMEOUT_MS = 30_000;
+
+/** Optional settings for {@link ClutchHubSdk}. */
+export interface ClutchHubSdkOptions {
+  /**
+   * HTTP timeout for every hub request (queries, mutations, `generateToken`), in milliseconds.
+   * Defaults to {@link DEFAULT_HTTP_TIMEOUT_MS}. `0` disables it, which is what the SDK did
+   * before this option existed: a request the hub never answered hung the caller forever.
+   * Subscriptions ride on graphql-ws and are unaffected.
+   */
+  timeoutMs?: number;
+}
+
 // Expose Buffer to browser contexts
 declare global {
   interface Window { Buffer: typeof Buffer }
@@ -412,9 +436,20 @@ export class ClutchHubSdk {
    *   it is defeats the check chain_id exists to provide. If omitted, `signTransaction` still
    *   verifies every other `expected` field but skips the chain_id pin (nothing was pinned to
    *   check against) rather than failing every real transaction against a phantom "chain 0".
+   * @param options Optional settings — see {@link ClutchHubSdkOptions}. Today that is the HTTP
+   *   timeout (`timeoutMs`, default {@link DEFAULT_HTTP_TIMEOUT_MS}).
    */
-  constructor(apiUrl: string, publicKey: string, privateKey?: string, chainId?: number) {
-    this.apiClient = axios.create({ baseURL: apiUrl });
+  constructor(
+    apiUrl: string,
+    publicKey: string,
+    privateKey?: string,
+    chainId?: number,
+    options: ClutchHubSdkOptions = {}
+  ) {
+    this.apiClient = axios.create({
+      baseURL: apiUrl,
+      timeout: options.timeoutMs ?? DEFAULT_HTTP_TIMEOUT_MS,
+    });
     this.publicKey = publicKey;
     this.chainId = chainId ?? 0;
     this.chainIdConfigured = chainId !== undefined;
@@ -883,7 +918,7 @@ export class ClutchHubSdk {
     `;
     return this.subscribeGraphqlListField<AvailableRideOffer>(
       query,
-      { rideRequestTxHash },
+      { rideRequestTxHash: normalizeTxHashForQuery(rideRequestTxHash) },
       'rideOffersUpdated',
       handlers
     );
@@ -1000,7 +1035,7 @@ export class ClutchHubSdk {
     `;
     const result = await this.executeGraphQL<{
       listRideOffers: (Omit<AvailableRideOffer, 'fare'> & { fare: string })[];
-    }>(query, { rideRequestTxHash });
+    }>(query, { rideRequestTxHash: normalizeTxHashForQuery(rideRequestTxHash) });
     return result.listRideOffers.map((r) => ({ ...r, fare: BigInt(r.fare) }));
   }
 

package/test/hash-args.test.mjs

@@ -0,0 +1,37 @@
+// Runs against dist/ — `npm run build` first. `node --test test/` (Node >= 20, no framework).
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { ClutchHubSdk } from '../dist/index.js';
+
+const HASH = 'ae174ce0588b221ed24d685518d486513187ab5ee649347062e75066a2aa9a37';
+
+// The hub matches hash arguments as exact strings, without 0x and in lowercase. The SDK must
+// send that form whatever the caller passed, or the hub answers with an empty list.
+function sdkWithRecordingPost() {
+  const sdk = new ClutchHubSdk('http://hub.test', '0x4196c526e2bb5dd02c2e2613b43291b0736afc47');
+  const sent = [];
+  sdk.apiClient.post = async (_url, body) => {
+    sent.push(body);
+    return { data: { data: { listRideOffers: [{ txHash: 'ff', rideRequestTxHash: HASH, fare: '5000000', driverAddress: '0x1' }] } } };
+  };
+  return { sdk, sent };
+}
+
+test('listRideOffers strips a 0x prefix before querying the hub', async () => {
+  const { sdk, sent } = sdkWithRecordingPost();
+  const offers = await sdk.listRideOffers('0x' + HASH);
+  assert.equal(sent[0].variables.rideRequestTxHash, HASH);
+  assert.equal(offers[0].fare, 5000000n);
+});
+
+test('listRideOffers lowercases and unquotes a legacy JSON-wrapped hash', async () => {
+  const { sdk, sent } = sdkWithRecordingPost();
+  await sdk.listRideOffers(JSON.stringify('0X' + HASH.toUpperCase()));
+  assert.equal(sent[0].variables.rideRequestTxHash, HASH);
+});
+
+test('listRideOffers passes an already-normalized hash through unchanged', async () => {
+  const { sdk, sent } = sdkWithRecordingPost();
+  await sdk.listRideOffers(HASH);
+  assert.equal(sent[0].variables.rideRequestTxHash, HASH);
+});

package/test/http-timeout.test.mjs

@@ -0,0 +1,23 @@
+// Runs against dist/ — `npm run build` first. `node --test test/` (Node >= 20, no framework).
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { ClutchHubSdk, DEFAULT_HTTP_TIMEOUT_MS } from '../dist/index.js';
+
+const PK = '0x4196c526e2bb5dd02c2e2613b43291b0736afc47';
+
+test('the hub HTTP client has a timeout by default', () => {
+  const sdk = new ClutchHubSdk('http://hub.test', PK);
+  assert.equal(DEFAULT_HTTP_TIMEOUT_MS, 30_000);
+  assert.equal(sdk.apiClient.defaults.timeout, DEFAULT_HTTP_TIMEOUT_MS);
+});
+
+test('timeoutMs overrides the default, and 0 disables it', () => {
+  assert.equal(new ClutchHubSdk('http://hub.test', PK, undefined, 2077, { timeoutMs: 5_000 }).apiClient.defaults.timeout, 5_000);
+  assert.equal(new ClutchHubSdk('http://hub.test', PK, undefined, 2077, { timeoutMs: 0 }).apiClient.defaults.timeout, 0);
+});
+
+test('the four-argument constructor still works unchanged', () => {
+  const sdk = new ClutchHubSdk('http://hub.test', PK, undefined, 2077);
+  assert.equal(sdk.getPublicKey(), PK);
+  assert.equal(sdk.apiClient.defaults.timeout, DEFAULT_HTTP_TIMEOUT_MS);
+});