@kushbitx/sdk 0.1.2 → 0.1.4

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.00098 USDC | Receive structured token-risk evidence with missing checks identified. |
-| Transaction preflight | 0.00098 USDC | Inspect an unsigned Base transaction before signing. |
+| 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. `canSign` needs the transaction to state `chainId: 8453`; a missing or other chainId is never accepted. 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 = { chainId: 8453, 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, another network, 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:

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: { chainId?: number | string | bigint; from?: Address | null; to: Address; value?: string; data?: string }): Promise<`0x${string}`>;
+/** True only for ALLOW on this exact Base transaction before expiresAt. chainId must be stated and be 8453; a missing or other chainId, or any changed field, is false. */
+export declare function canSign(report: PreflightReport | Record<string, unknown>, transaction: { chainId: number | string | bigint; 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) {
@@ -123,3 +125,42 @@ 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.
+// The transaction's own chainId goes into the digest (default 8453 when absent), so a report for Base never
+// matches the same fields on another network.
+const BASE_CHAIN_ID = 8453;
+function chainIdOf(transaction) {
+  const raw = transaction?.chainId;
+  if (raw === undefined || raw === null) return BASE_CHAIN_ID;
+  if (typeof raw === 'bigint') return Number(raw);
+  if (typeof raw === 'string' && /^0x[0-9a-f]+$/i.test(raw)) return Number(BigInt(raw));
+  if (typeof raw === 'string' && /^[0-9]+$/.test(raw)) return Number(raw);
+  if (typeof raw === 'number' && Number.isInteger(raw)) return raw;
+  return NaN;
+}
+export async function preflightDigest(transaction) {
+  const { from = null, to, value = '0', data = '0x' } = transaction || {};
+  const chainId = chainIdOf(transaction);
+  if (!Number.isInteger(chainId)) throw new Error('chainId must be an integer');
+  const canonical = JSON.stringify({ chainId, 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 Base transaction (chainId 8453, stated), before expiresAt. Anything else: do not sign. */
+export async function canSign(report, transaction, now = Date.now()) {
+  if (!report || typeof report !== 'object' || report.verdict !== 'ALLOW' || typeof report.transactionDigest !== 'string') return false;
+  // The transaction must state chainId 8453; a missing chainId is never assumed to be Base.
+  if (!transaction || typeof transaction !== 'object' || transaction.chainId === undefined || transaction.chainId === null || chainIdOf(transaction) !== BASE_CHAIN_ID) return false;
+  if (report.chainId !== undefined && Number(report.chainId) !== BASE_CHAIN_ID) return false;
+  if (!report.expiresAt || !(Date.parse(report.expiresAt) > now)) return false;
+  try {
+    return report.transactionDigest.toLowerCase() === await preflightDigest(transaction);
+  } catch {
+    return false;
+  }
+}

package/package.json

@@ -1,11 +1,17 @@
 {
   "name": "@kushbitx/sdk",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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,7 +24,9 @@
     "base",
     "usdc",
     "payment-security",
-    "spendguard"
+    "spendguard",
+    "preflight",
+    "typescript"
   ],
   "homepage": "https://github.com/BHamim/kushbitx-sdk#readme",
   "repository": {
@@ -29,5 +37,6 @@
     "url": "https://github.com/BHamim/kushbitx-sdk/issues",
     "email": "admin@kushbitx.com"
   },
-  "license": "Apache-2.0"
+  "license": "Apache-2.0",
+  "types": "./kushbitx.d.ts"
 }