quesen-sdk (JavaScript / TypeScript)

Official Quesen SDK for Node 18+, Bun, Deno, and modern browsers. Zero runtime dependencies. Same 3-line integration pattern as every other Quesen SDK:

import { QuesenClient } from "quesen-sdk";

const q = new QuesenClient({
  baseUrl: "https://quesen.example.com",
  apiKey: process.env.QUESEN_API_KEY,
});

const verdict = await q.validate({
  domain_age_days: 1,
  engagement_ratio: 0.95,
  scam_keyword_count: 4,
});

if (verdict.decision === "SKIP") return; // respect the deterministic answer

Why deterministic? No LLM, no randomness. Same input in, same decision out. Every response embeds engine_version, weights, thresholds, plus (v1.10+) input_snapshot_hash and commit_sha for self-contained replay.

---

Status: v0.2.0 · tracks Quesen engine v1.10.0 · backward compatible with every deployed engine version.

---

Install

npm i quesen-sdk           # or: yarn add quesen-sdk / bun add quesen-sdk

---

Feature surface

• .health() — liveness probe.
• .version() — engine + report_schema versions + weights + thresholds + feature flags.
• .validate(input) — the main decision endpoint. Response carries input_snapshot_hash + commit_sha against v1.10+ engines.
• .simulate(input) — counterfactual scoring with weights_override / thresholds_override.
• .report(input) — post-decision outcome feedback (v1.1 schema with realized_pnl, venue, etc.).

Receipt provenance (v1.10, tracked in SDK v0.2.0)

const verdict = await q.validate({
  domain_age_days: 1,
  engagement_ratio: 0.95,
  scam_keyword_count: 4,
});

console.log(verdict.input_snapshot_hash);
// e.g. "2b0a…" — 64-char lowercase SHA-256 hex over canonical-JSON of the request
//                 (with client_request_id excluded from hash material)
console.log(verdict.commit_sha);
// e.g. "0b77cf…" — 40-char lowercase git SHA of Shxnque/quesen HEAD at decision
//                    time, or the sentinel "unknown"

Client-side reconstruction (verify the engine evaluated exactly what you sent):

async function inputSnapshotHash(payload: Record<string, unknown>): Promise<string> {
  const toHash: Record<string, unknown> = {};
  const keys = Object.keys(payload).sort();
  for (const k of keys) {
    if (k === "client_request_id") continue;
    if (payload[k] === null || payload[k] === undefined) continue;
    toHash[k] = payload[k];
  }
  const canonical = JSON.stringify(toHash);
  const bytes = new TextEncoder().encode(canonical);
  const digest = await crypto.subtle.digest("SHA-256", bytes);
  return [...new Uint8Array(digest)]
    .map((b) => b.toString(16).padStart(2, "0"))
    .join("");
}

Backward compatibility. Both fields are typed as string | undefined. Against a pre-v1.10 engine they simply won't be set; type-checking stays clean.

v1.5.0 on-chain enrichment (optional)

Pass chain + contract_address to enable deterministic on-chain enrichment. Requires the Quesen server to be started with QUESEN_ONCHAIN_ENABLED=true and per-chain QUESEN_ONCHAIN_RPC_<SLUG> set.

const verdict = await q.validate({
  engagement_ratio: 0.9,
  chain: "base",
  contract_address: "0x4200000000000000000000000000000000000006",
});

if (verdict.onchain_enrichment?.holder_concentration.top1_share ?? 0 > 0.6) {
  // Read the enrichment on the client side too if you want extra logging.
}

---

Errors

All errors extend QuesenError:

Class	Trigger
QuesenAuthError	401 (missing/invalid API key)
QuesenValidationError	422 (input shape)
QuesenRateLimitError	429 (per-key rate limit)
QuesenServerError	5xx after retries
QuesenTimeout	timeoutMs exceeded
QuesenTransportError	network failure

5xx errors are retried with exponential backoff (default 2 retries). Business errors (401 / 422 / 429) surface immediately.

---

Doctrine

This SDK is bound by Quesen's published design principles (see Shxnque/quesen):

• §2 determinism — never adds randomness, never adds an LLM in the loop.
• §11 ecosystem neutrality — zero runtime dependencies.
• §12 anti-bureaucracy — one client, one file, one intent.
• Receipt provenance forwarded — input_snapshot_hash + commit_sha typed on ValidateResult (v0.2.0+).

---

Development

cd sdks/js
yarn install
yarn test           # vitest
yarn build          # emit dist/ (tsc)