@kushbitx/sdk 0.1.1 → 0.1.3

package/README.md

@@ -9,9 +9,10 @@ Zero-dependency ESM client and runnable Node.js example for the complete KushBit
 | Token market preview | Free | Inspect basic Base token market data without connecting a wallet. |
 | Data coverage check | Free | See which risk checks have enough evidence before buying a report. |
 | SpendGuard | Free pilot | Evaluate payment policy before money moves, with optional protected policies and human approval. |
-| Token-risk report | 0.25 USDC | Receive structured token-risk evidence with missing checks identified. |
-| Transaction preflight | 0.05 USDC | Inspect an unsigned Base transaction before signing. |
-| Payment verification | 0.01 USDC | Verify an existing Base USDC payment against the expected recipient and amount. |
+| Token-risk report | 0.001 USDC | Receive structured token-risk evidence with missing checks identified. |
+| Transaction preflight | 0.001 USDC | Inspect an unsigned Base transaction before signing. |
+| Payment verification | 0.00288 USDC | Verify an existing Base USDC payment against the expected recipient and amount. |
+| KushBitx Preflight | 0.005 USDC | One verdict (ALLOW, REVIEW, BLOCK) before money moves, fail-closed: transaction simulation, approval and transfer decoding, token and recipient screening, optional protected SpendGuard policy. Does not detect prompt injection (use Protected SpendGuard). Service name `kushbitx-preflight`. |
 
 Paid endpoints use x402 and require explicit payment. There is no subscription. A delivered report can be `INCOMPLETE` when evidence is unavailable and may still incur the displayed fee.
 
@@ -33,6 +34,38 @@ console.log(preview);
 
 The SDK never requests, stores, or signs with a private key. It can discover an x402 challenge, prepare recovery, submit an externally signed payment authorization, and recover a report.
 
+## TypeScript
+
+Types ship with the package (`kushbitx.d.ts`), including `PreflightInput` and `PreflightReport`:
+
+```ts
+import { KushBitxClient, type PreflightInput } from '@kushbitx/sdk';
+
+const kushbitx = new KushBitxClient();
+const input: PreflightInput = { chainId: 8453, to: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', data: '0x', intent: 'contract_call' };
+const { challenge } = await kushbitx.getPaymentChallenge('kushbitx-preflight', input); // HTTP 402, nothing charged
+```
+
+### Preflight 1.1: sign only the transaction that was checked
+
+Send `from`; without it the verdict is REVIEW. Each response has `transactionDigest` and `expiresAt` (60 seconds). For swaps, add `expectedTokenOut`, and optionally `minAmountOut` and `expectedRecipient`.
+
+```js
+import { canSign } from '@kushbitx/sdk';
+
+const tx = { from: wallet, to, value: '0', data };   // the exact unsigned transaction
+// ... pay for POST /api/preflight with your x402 client, get `report` ...
+if (await canSign(report, tx)) {
+  // ALLOW, same digest, not expired: sign now
+} else {
+  // REVIEW, BLOCK, changed transaction or expired: do not sign
+}
+```
+
+Required checks per transaction type: `requiredChecks` in https://kushbitx.com/api/services.
+
+Current prices: https://kushbitx.com/api/services
+
 ## Runnable example
 
 Download `agent.mjs`, then run a free flow without installing packages:
@@ -62,11 +95,16 @@ import { KushBitxClient } from 'https://kushbitx.com/sdk/kushbitx.mjs';
 ## Links
 
 - Website: https://kushbitx.com
+- Source: https://github.com/BHamim/kushbitx-sdk
 - Tools: https://kushbitx.com/#tools
 - SpendGuard: https://kushbitx.com/spendguard
 - Integration example: https://kushbitx.com/examples/agent.mjs
 - Contact: Admin@kushbitx.com
 
+## Community contributions
+
+- [@mengxin10086](https://github.com/mengxin10086) built an independent MCP bridge for the free KushBitx endpoints. KushBitx reviewed and accepted commit `0e4d3226` ([source at that commit](https://github.com/mengxin10086/kushbitx-mcp-agent/tree/0e4d32267d4692d32cfb7c451d391cd59093a883)). It is third-party code, maintained by its author.
+
 ## Security
 
 Do not disclose suspected vulnerabilities in public issues. Report them privately to Admin@kushbitx.com.

package/kushbitx.d.ts

@@ -0,0 +1,158 @@
+// Type declarations for @kushbitx/sdk 0.1.3. The SDK never requests, stores or signs with a private key.
+
+/** Paid service names accepted by the payment helpers, and the route each one calls. */
+export type PaidService =
+  | 'token-risk'
+  | 'preflight' | 'transaction-preflight'
+  | 'payment' | 'payment-proof' | 'verify-payment'
+  | 'kushbitx-preflight';
+
+export declare const paidServices: Readonly<Record<PaidService, string>>;
+
+export interface ClientOptions {
+  /** API origin. Default https://kushbitx.com (use https://staging.kushbitx.com for the Testnet sandbox). */
+  baseUrl?: string;
+  /** Fetch implementation. Default globalThis.fetch. */
+  fetchFn?: typeof fetch;
+}
+
+export type Address = `0x${string}`;
+export type Verdict = 'ALLOW' | 'WARN' | 'BLOCK' | 'INCOMPLETE';
+
+export interface TokenInput { chain: 'base'; address: Address }
+export interface TransactionInput { chain: 'base'; to: Address; from?: Address; valueWei?: string; data?: `0x${string}` }
+export interface PaymentProofInput { chain: 'base'; txHash: `0x${string}`; expectedTo: Address; expectedAmount: string; expectedFrom?: Address }
+
+/** Input of KushBitx Preflight (POST /api/preflight, 0.005 USDC). */
+export interface PreflightInput {
+  chainId: 8453;
+  to: Address;
+  /** Signing wallet. Required in practice: without it the verdict is REVIEW (sender_unknown). */
+  from?: Address;
+  /** Native ETH value in wei. */
+  value?: string;
+  data?: `0x${string}`;
+  intent?: 'swap' | 'transfer' | 'approve' | 'buy_token' | 'contract_call';
+  tokenAddress?: Address;
+  amount?: string;
+  /** Protected SpendGuard policy; send the agent key as Authorization: Bearer. Base USDC transfers only. */
+  policy?: { policyId: string; agentId: string; requestId: string };
+  /** Swap: who must receive the output. Default: from. */
+  expectedRecipient?: Address;
+  /** Swap: smallest acceptable output, in token units (for example "25.5"). */
+  minAmountOut?: string;
+  /** Swap: token the swap must deliver; 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE for native ETH. */
+  expectedTokenOut?: Address;
+}
+
+export type PreflightTransactionType = 'native_transfer' | 'erc20_transfer' | 'approval' | 'swap' | 'contract_call';
+
+export interface PreflightFinding {
+  code: string;
+  severity: 'info' | 'low' | 'medium' | 'high' | 'critical';
+  kind: 'fact' | 'inference';
+  message: string;
+  source: string;
+  sourceTimestamp: string;
+  onchainBlock: number | null;
+  evidence?: Record<string, unknown>;
+}
+
+export interface PreflightReport {
+  /** "1.1" since 2026-10-31. */
+  reportVersion: string;
+  service: 'preflight';
+  generatedAt: string;
+  checkedAt: string;
+  /** checkedAt + 60 seconds. Do not sign after this time. */
+  expiresAt: string;
+  /** Compare with preflightDigest(transaction) before signing. */
+  transactionDigest: `0x${string}`;
+  transactionDigestMethod: string;
+  validity: string;
+  transactionType: PreflightTransactionType;
+  /** Checks this transaction type needs; a missing one gives REVIEW. */
+  requiredChecks: string[];
+  /** Simulated transfers and approvals (eth_simulateV1), and the swap output check. */
+  effects: { simulated: boolean; transfers?: Array<Record<string, unknown>>; approvals?: Array<Record<string, unknown>>; swap?: { expectedRecipient: Address; expectedTokenOut: Address; receivedAtomic: string; minAmountOutAtomic: string | null }; error?: string } | null;
+  input: Record<string, unknown>;
+  chainId: 8453;
+  onchainBlock: number | null;
+  verdict: 'ALLOW' | 'REVIEW' | 'BLOCK';
+  /** What Preflight does not check, such as prompt injection. */
+  notChecked: string[];
+  riskLevel: 'low' | 'medium' | 'high' | 'critical' | 'unknown';
+  reasonCodes: string[];
+  findings: PreflightFinding[];
+  checksPerformed: string[];
+  checksUnavailable: string[];
+  limitations: string[];
+  reports: Record<string, unknown>;
+  attribution?: { text: string; url: string; logo: string; scope: string };
+}
+
+export interface SpendPolicy {
+  maxPerTransaction: string;
+  remainingDailyBudget: string;
+  requireHumanAbove: string;
+  maxRepeats: number;
+  allowedRecipients: Address[];
+  blockUnknownRecipients: boolean;
+}
+
+export interface SpendInput {
+  agentId: string;
+  requestId: string;
+  chain: 'base';
+  asset: 'USDC';
+  recipient: Address;
+  amount: string;
+  policy: SpendPolicy;
+  context?: { repeatCount?: number; agentProofDecision?: 'ALLOW' | 'WARN' | 'BLOCK' | 'INCOMPLETE' | 'UNKNOWN' };
+}
+
+export interface PaymentChallenge {
+  service: PaidService;
+  path: string;
+  /** The 402 JSON body (x402Version, accepts, resource). */
+  challenge: Record<string, unknown>;
+  /** The base64 PAYMENT-REQUIRED header, for an x402 client. */
+  paymentRequired: string | null;
+}
+
+export interface RecoveryCredentials { id: string; key: string; [k: string]: unknown }
+
+/** The digest KushBitx Preflight returns in transactionDigest, computed locally from the transaction you will sign. */
+export declare function preflightDigest(transaction: { from?: Address | null; to: Address; value?: string; data?: string }): Promise<`0x${string}`>;
+/** True only for ALLOW on this exact transaction before expiresAt. */
+export declare function canSign(report: PreflightReport | Record<string, unknown>, transaction: { from?: Address | null; to: Address; value?: string; data?: string }, now?: number): Promise<boolean>;
+
+export declare class KushBitxClient {
+  constructor(options?: ClientOptions);
+  baseUrl: string;
+  request(path: string, options?: { method?: string; body?: unknown; bearer?: string; headers?: Record<string, string> }): Promise<{ response: Response; data: unknown; parseError: unknown }>;
+  expect<T = Record<string, unknown>>(path: string, options?: { method?: string; body?: unknown; bearer?: string; headers?: Record<string, string> }, statuses?: number[]): Promise<T>;
+
+  /** Free market preview; no risk verdict. */
+  previewToken(address: Address): Promise<Record<string, unknown>>;
+  /** Free SpendGuard check. Advisory only: the caller supplies the policy. */
+  evaluateSpend(input: SpendInput): Promise<Record<string, unknown>>;
+  createSpendPolicy(policy: Record<string, unknown>): Promise<Record<string, unknown>>;
+  getSpendPolicy(policyId: string, adminKey: string): Promise<Record<string, unknown>>;
+  updateSpendPolicy(policyId: string, adminKey: string, policy: Record<string, unknown>): Promise<Record<string, unknown>>;
+  requestSpendDecision(input: Record<string, unknown>, agentKey: string): Promise<Record<string, unknown>>;
+  getSpendDecision(decisionId: string, key: string): Promise<Record<string, unknown>>;
+  approveSpendDecision(decisionId: string, adminKey: string): Promise<Record<string, unknown>>;
+
+  /** Ask for the x402 challenge (HTTP 402). Nothing is charged. */
+  getPaymentChallenge(service: 'kushbitx-preflight', input: PreflightInput): Promise<PaymentChallenge>;
+  getPaymentChallenge(service: 'token-risk', input: TokenInput): Promise<PaymentChallenge>;
+  getPaymentChallenge(service: 'preflight' | 'transaction-preflight', input: TransactionInput): Promise<PaymentChallenge>;
+  getPaymentChallenge(service: 'payment' | 'payment-proof' | 'verify-payment', input: PaymentProofInput): Promise<PaymentChallenge>;
+  /** Store recovery credentials before signing, so an interrupted call can be restored without paying again. */
+  prepareRecovery(service: PaidService, input: object): Promise<RecoveryCredentials>;
+  /** Send an externally signed payment (PAYMENT-SIGNATURE). Returns the report, or a pending status (HTTP 202). */
+  submitPaidCheck(service: 'kushbitx-preflight', input: PreflightInput, auth: { paymentSignature: string; reportId: string; recoveryKey: string }): Promise<PreflightReport | Record<string, unknown>>;
+  submitPaidCheck(service: PaidService, input: object, auth: { paymentSignature: string; reportId: string; recoveryKey: string }): Promise<Record<string, unknown>>;
+  restoreReport(args: { id: string; key: string; txHash?: string }): Promise<Record<string, unknown>>;
+}

package/kushbitx.mjs

@@ -4,7 +4,9 @@ const PAID_SERVICES = Object.freeze({
   'transaction-preflight': '/api/transaction-preflight',
   payment: '/api/verify-payment',
   'payment-proof': '/api/verify-payment',
-  'verify-payment': '/api/verify-payment'
+  'verify-payment': '/api/verify-payment',
+  // KushBitx Preflight (0.005 USDC): one verdict before money moves. 'preflight' stays Transaction Preflight.
+  'kushbitx-preflight': '/api/preflight'
 });
 
 function required(value, name) {
@@ -12,6 +14,17 @@ function required(value, name) {
   return value;
 }
 
+function errorMessage(data) {
+  return data && typeof data === 'object' && typeof data.error === 'string' ? data.error : '';
+}
+
+// A success needs a JSON object body. null, arrays, scalars and invalid JSON are errors.
+function jsonObject({ data, parseError }, status) {
+  if (parseError) throw new Error('KushBitx returned invalid JSON with HTTP ' + status, { cause: parseError });
+  if (data === null || typeof data !== 'object' || Array.isArray(data)) throw new Error('KushBitx returned an empty or non-object JSON body with HTTP ' + status);
+  return data;
+}
+
 export class KushBitxClient {
   constructor({ baseUrl = 'https://kushbitx.com', fetchFn = globalThis.fetch } = {}) {
     if (typeof fetchFn !== 'function') throw new Error('A fetch implementation is required');
@@ -29,14 +42,22 @@ export class KushBitxClient {
       },
       ...(body === undefined ? {} : { body: JSON.stringify(body) })
     });
-    const data = await response.json().catch(() => ({}));
-    return { response, data };
+    // An unreadable body stays visible as data=null; it is never replaced by an empty object.
+    let data = null;
+    let parseError = null;
+    try {
+      data = await response.json();
+    } catch (error) {
+      parseError = error;
+    }
+    return { response, data, parseError };
   }
 
   async expect(path, options, statuses = [200]) {
     const result = await this.request(path, options);
-    if (!statuses.includes(result.response.status)) throw new Error(result.data.error || 'KushBitx request failed with HTTP ' + result.response.status);
-    return result.data;
+    const { status } = result.response;
+    if (!statuses.includes(status)) throw new Error(errorMessage(result.data) || 'KushBitx request failed with HTTP ' + status);
+    return jsonObject(result, status);
   }
 
   previewToken(address) {
@@ -75,8 +96,8 @@ export class KushBitxClient {
     const path = PAID_SERVICES[service];
     if (!path) throw new Error('Unknown paid service');
     const result = await this.request(path, { body: input });
-    if (result.response.status !== 402) throw new Error(result.data.error || 'Expected an HTTP 402 payment challenge');
-    return { service, path, challenge: result.data, paymentRequired: result.response.headers.get('PAYMENT-REQUIRED') };
+    if (result.response.status !== 402) throw new Error(errorMessage(result.data) || 'Expected an HTTP 402 payment challenge');
+    return { service, path, challenge: jsonObject(result, 402), paymentRequired: result.response.headers.get('PAYMENT-REQUIRED') };
   }
 
   prepareRecovery(service, input) {
@@ -104,3 +125,20 @@ export class KushBitxClient {
 }
 
 export const paidServices = PAID_SERVICES;
+
+// Preflight 1.1: the digest the service returns in transactionDigest. Compute it from the transaction you are about
+// to sign; sign only when it matches an ALLOW verdict that has not expired.
+// sha256 of JSON {chainId,from,to,value,data} in that key order; from, to and data lowercase; value a decimal wei string.
+export async function preflightDigest({ from = null, to, value = '0', data = '0x' }) {
+  const canonical = JSON.stringify({ chainId: 8453, from: from ? String(from).toLowerCase() : null, to: required(to, 'to').toLowerCase(), value: BigInt(value || '0').toString(), data: String(data || '0x').toLowerCase() });
+  const subtle = globalThis.crypto?.subtle ?? (await import('node:crypto')).webcrypto.subtle;
+  const hash = await subtle.digest('SHA-256', new TextEncoder().encode(canonical));
+  return '0x' + Array.from(new Uint8Array(hash), b => b.toString(16).padStart(2, '0')).join('');
+}
+
+/** True only for an ALLOW verdict on this exact transaction, before expiresAt. Anything else: do not sign. */
+export async function canSign(report, transaction, now = Date.now()) {
+  if (!report || report.verdict !== 'ALLOW' || typeof report.transactionDigest !== 'string') return false;
+  if (!report.expiresAt || !(Date.parse(report.expiresAt) > now)) return false;
+  return report.transactionDigest === await preflightDigest(transaction);
+}

package/package.json

@@ -1,11 +1,17 @@
 {
   "name": "@kushbitx/sdk",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Zero-dependency ESM client for KushBitx AgentProof services on Base",
   "type": "module",
-  "exports": "./kushbitx.mjs",
+  "exports": {
+    ".": {
+      "types": "./kushbitx.d.ts",
+      "import": "./kushbitx.mjs"
+    }
+  },
   "files": [
     "kushbitx.mjs",
+    "kushbitx.d.ts",
     "README.md",
     "LICENSE"
   ],
@@ -18,16 +24,19 @@
     "base",
     "usdc",
     "payment-security",
-    "spendguard"
+    "spendguard",
+    "preflight",
+    "typescript"
   ],
-  "homepage": "https://kushbitx.com/developers",
+  "homepage": "https://github.com/BHamim/kushbitx-sdk#readme",
   "repository": {
-    "type": "url",
-    "url": "https://kushbitx.com/developers"
+    "type": "git",
+    "url": "git+https://github.com/BHamim/kushbitx-sdk.git"
   },
   "bugs": {
-    "url": "https://kushbitx.com/developers",
+    "url": "https://github.com/BHamim/kushbitx-sdk/issues",
     "email": "admin@kushbitx.com"
   },
-  "license": "Apache-2.0"
+  "license": "Apache-2.0",
+  "types": "./kushbitx.d.ts"
 }