⚡
JavaScript / Node.js SDK
StableThe official TrueEntropy JavaScript client. TypeScript-first with ESM and CJS support, works in Node.js and Bun, with full access to QuBitLang metadata.
Installation
npm install @trueentropy/sdk
yarn add @trueentropy/sdk
pnpm add @trueentropy/sdk
Requires Node.js 18+ or Bun 1.0+. Ships with TypeScript declarations.
Quick Start
quickstart.ts
import { TrueEntropy } from '@trueentropy/sdk';
const client = new TrueEntropy('te_live_YOUR_KEY');
// Generate quantum random integers
const result = await client.integers({ count: 10, min: 1, max: 100 });
console.log(result.data.values);
// [42, 87, 13, 65, 91, 28, 74, 3, 56, 49]
// Access QuBitLang provenance metadata
console.log(result.metadata.qubitlangCircuit); // qrng_hadamard_v2.3
console.log(result.metadata.quantumBackend); // ibm_fez
console.log(result.metadata.nistVerified); // true
Configuration
config.ts
import { TrueEntropy } from '@trueentropy/sdk';
const client = new TrueEntropy('te_live_YOUR_KEY', {
baseUrl: 'https://api.trueentropy.net', // default
timeout: 30000, // ms
maxRetries: 3, // automatic retries
sandbox: false, // set true for sandbox
});
// Or use environment variable
// TRUEENTROPY_API_KEY=te_live_YOUR_KEY
const autoClient = new TrueEntropy(); // reads from process.env
Endpoint Methods
Integers
const result = await client.integers({ count: 5, min: 1, max: 1000 });
console.log(result.data.values); // [472, 829, 134, 567, 291]
Floats
const result = await client.floats({ count: 5, precision: 10 });
console.log(result.data.values); // [0.4721937482, 0.8291053847, ...]
Bytes
const result = await client.bytes({ count: 32, encoding: 'hex' });
console.log(result.data.bytes); // "a7f2b9c4d8e1..."
UUID
const result = await client.uuid({ count: 3 });
console.log(result.data.uuids);
// ["a7f2b9c4-d8e1-4f3a-b5c7-d9e2f4a6b8c0", ...]
Bitstring
const result = await client.bitstring({ length: 256 });
console.log(result.data.bits); // "10110100111010010110..."
Shuffle
const result = await client.shuffle({
items: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
});
console.log(result.data.shuffled); // [7, 3, 9, 1, 5, 10, 2, 8, 4, 6]
Batch
const result = await client.batch({
type: 'integers',
count: 100000,
params: { min: 1, max: 1000000 }
});
console.log(result.data.values.length); // 100000
Certificate
const cert = await client.certificate({ id: 'cert_a7f2b9c4d8e1' });
console.log(cert.certificate.provenance.qubitlangCircuit);
console.log(cert.certificate.verifyUrl);
Error Handling
errors.ts
import {
TrueEntropy,
AuthenticationError,
RateLimitError,
ValidationError,
TrueEntropyError,
} from '@trueentropy/sdk';
try {
const result = await client.integers({ count: 10 });
} catch (err) {
if (err instanceof AuthenticationError) {
console.error('Invalid API key', err.message);
} else if (err instanceof RateLimitError) {
console.error(`Rate limited. Retry after ${err.retryAfter}s`);
} else if (err instanceof ValidationError) {
console.error('Invalid params', err.code);
}
}
TypeScript Types
types.ts
import type {
IntegersResponse,
FloatsResponse,
BytesResponse,
UuidResponse,
BitstringResponse,
ShuffleResponse,
BatchResponse,
CertificateResponse,
QuBitLangMetadata,
} from '@trueentropy/sdk';
// All response types are fully typed
const result: IntegersResponse = await client.integers({ count: 5 });
const meta: QuBitLangMetadata = result.metadata;
Features
| Feature | Details |
|---|---|
| TypeScript | First-class TypeScript with full type declarations |
| Module formats | Ships as ESM and CJS - works everywhere |
| Runtimes | Node.js 18+, Bun 1.0+ |
| Retries | Exponential backoff with configurable maxRetries |
| Sandbox | Toggle sandbox: true for testing without consuming quota |
| Certificates | Built-in client.certificate() for provenance retrieval |
| QuBitLang metadata | Typed access to circuit, version, backend info on every response |