QuantumChain TypeScript/JavaScript SDK

Production-ready SDK for integrating QuantumChain quantum-safe cryptography into your React, Next.js, or Node.js applications.

Features

• 🔐 API Key Authentication - Secure authentication with automatic tenant/app detection
• ⚡ Quantum-Safe Signatures - Hybrid classical + post-quantum cryptography
• 📦 React Hooks - Easy integration with React/Next.js
• 🔄 Auto-Retry - Built-in retry logic with exponential backoff
• 📊 Receipt Management - Track all signatures with blockchain anchoring
• 🎯 TypeScript - Full type safety and IntelliSense support

Installation

npm install @quantumchain/sdk
# or
yarn add @quantumchain/sdk
# or
pnpm add @quantumchain/sdk

Quick Start

Basic Usage (Node.js/TypeScript)

import { QuantumChain } from '@quantumchain/sdk';

// Initialize SDK
const client = new QuantumChain({
  apiKey: process.env.QUANTUMCHAIN_API_KEY,
  baseUrl: 'https://api.quantumchain.com', // or your Gateway URL
  tenantId: 'your-tenant-id', // Optional: auto-detected from API key
});

// Sign a message
const result = await client.sign({
  message: 'Hello, QuantumChain!',
  algorithm: 'Hybrid', // Uses Dilithium3 + Ed25519 hybrid
});

console.log('Receipt ID:', result.receipt_id);
console.log('Status:', result.status); // 'pending', 'anchored', or 'failed'

// Verify a signature
const verifyResult = await client.verify({
  message: 'Hello, QuantumChain!',
  signature: result.signature,
  publicKeys: result.public_key,
});

console.log('Valid:', verifyResult.valid);

React/Next.js with Hooks

'use client';

import { useSign, useVerify } from '@quantumchain/sdk';

export default function MyComponent() {
  const { sign, result, loading, error } = useSign({
    apiKey: process.env.NEXT_PUBLIC_QUANTUMCHAIN_API_KEY,
    baseUrl: process.env.NEXT_PUBLIC_QUANTUMCHAIN_BASE_URL,
  });

  const { verify, result: verifyResult } = useVerify({
    apiKey: process.env.NEXT_PUBLIC_QUANTUMCHAIN_API_KEY,
  });

  const handleSign = async () => {
    await sign({
      message: 'Hello from React!',
      algorithm: 'Hybrid',
    });
  };

  return (
    <div>
      <button onClick={handleSign} disabled={loading}>
        {loading ? 'Signing...' : 'Sign Message'}
      </button>
      {result && <p>Receipt: {result.receipt_id}</p>}
      {error && <p>Error: {error.message}</p>}
    </div>
  );
}

API Reference

Configuration

interface QuantumChainConfig {
  apiKey?: string;           // API key (required)
  baseUrl?: string;          // Gateway URL (default: http://localhost:8080)
  timeout?: number;          // Request timeout in ms (default: 30000)
  retries?: number;          // Retry attempts (default: 3)
  tenantId?: string;         // Optional: auto-detected from API key
  applicationId?: string;    // Optional
}

Methods

sign(request: SignRequest): Promise<SignResponse>

Sign a message with quantum-safe cryptography.

const result = await client.sign({
  message: 'Your message', // string, Buffer, or Uint8Array
  tenantId: 'optional',     // Auto-detected from API key if not provided
  applicationId: 'optional',
  algorithm: 'Hybrid',      // 'Hybrid', 'Dilithium3', 'Dilithium5', 'SPHINCS+'
  keyId: 'optional',        // Auto-generated if not provided
  metadata: { /* custom data */ },
});

verify(request: VerifyRequest): Promise<VerifyResponse>

Verify a signature.

const result = await client.verify({
  message: 'Your message',
  signature: 'signature-string',
  publicKeys: 'public-key-string' | ['key1', 'key2'],
  tenantId: 'optional',
  applicationId: 'optional',
});

getReceipt(receiptId: string): Promise<ReceiptResponse>

Get a receipt by ID.

const receipt = await client.getReceipt('receipt-uuid');

listReceipts(options?): Promise<{ receipts, total, page, limit }>

List receipts with optional filters.

const { receipts, total } = await client.listReceipts({
  tenantId: 'optional',
  applicationId: 'optional',
  page: 1,
  limit: 20,
  dateFrom: '2024-01-01',
  dateTo: '2024-12-31',
});

getReceiptProof(receiptId: string)

Get blockchain anchoring proof for a receipt.

const proof = await client.getReceiptProof('receipt-uuid');
console.log('Anchored:', proof.anchored);
console.log('Block Number:', proof.block_number);

generateKey(options?)

Generate a new quantum-safe key pair.

const key = await client.generateKey({
  tenantId: 'optional',
  applicationId: 'optional',
  algorithm: 'Hybrid',
});

listKeys(options?)

List all keys for a tenant/application.

const { keys } = await client.listKeys({
  tenantId: 'optional',
  applicationId: 'optional',
});

React Hooks

useQuantumChain(config?)

Base hook for SDK access.

const { client, loading, error, clearError } = useQuantumChain({
  apiKey: 'your-api-key',
});

useSign(config?)

Hook for signing messages.

const { sign, result, loading, error } = useSign({
  apiKey: 'your-api-key',
});

useVerify(config?)

Hook for verifying signatures.

const { verify, result, loading, error } = useVerify({
  apiKey: 'your-api-key',
});

useReceipt(config?)

Hook for getting receipts.

const { getReceipt, getProof, receipt, loading } = useReceipt({
  apiKey: 'your-api-key',
});

useReceipts(config?)

Hook for listing receipts.

const { listReceipts, receipts, total, loading } = useReceipts({
  apiKey: 'your-api-key',
});

useKeys(config?)

Hook for key management.

const { generateKey, listKeys, keys, loading } = useKeys({
  apiKey: 'your-api-key',
});

Environment Variables

Next.js / React

NEXT_PUBLIC_QUANTUMCHAIN_API_KEY=your-api-key-here
NEXT_PUBLIC_QUANTUMCHAIN_BASE_URL=https://api.quantumchain.com

Node.js

QUANTUMCHAIN_API_KEY=your-api-key-here
QUANTUMCHAIN_BASE_URL=https://api.quantumchain.com

Getting Your API Key

1. Log in to the Admin Console: http://localhost:3000
2. Navigate to API Keys section
3. Click Create API Key
4. Copy the API key (shown only once)
5. Use it in your SDK configuration

The API key automatically associates with your tenant, so you don't need to provide tenantId in most cases.

How It Works

1. API Key Created: Admin creates an API key for a tenant in the Admin Console
2. SDK Initialized: Your app initializes the SDK with the API key
3. Auto-Detection: SDK automatically detects tenant/app from the API key
4. Sign/Verify: Your app uses quantum-safe cryptography via simple SDK calls
5. Receipts & Logs: All operations are logged and tracked automatically
6. Blockchain Anchoring: Receipts are automatically anchored to the blockchain

Examples

See the examples/ directory for:

• basic.ts - Basic Node.js usage
• react-simple.tsx - Simple React example
• nextjs-example.tsx - Full Next.js integration
• react-example.tsx - React with hooks

Error Handling

All SDK methods throw QuantumChainError with:

• message - Human-readable error message
• statusCode - HTTP status code (if applicable)
• code - Error code
• details - Additional error details

try {
  await client.sign({ message: 'test' });
} catch (error: QuantumChainError) {
  if (error.statusCode === 401) {
    console.error('Invalid API key');
  } else {
    console.error('Error:', error.message);
  }
}

Support

• Documentation: https://docs.quantumchain.com
• Issues: GitHub Issues
• Email: [email protected]

License

MIT