JavaScript SDK

Zero-dependency fetch-based client for Node 18+ and modern browsers.

Download

zeq_client.js online · v1.1.3zero-dep · Node 18+

Single-file ES-module (works as CJS too). Uses the built-in global fetch. Verified live: NM21 → 1.98049e20 N, binding_overlay: 1.1.3.

Download zeq_client.js

Quickstart

import { ZeqClient } from './zeq_client.js';

const client = new ZeqClient({ token: 'zeq_ak_...' });
const r = await client.compute('NM21', {
  m1: 5.972e24, m2: 7.342e22, r: 3.844e8
});
console.log(r.value, r.unit);  // → 1.98049e+20 N

// CommonJS:
const { ZeqClient } = require('./zeq_client.js');

// CLI smoke test:
//   ZEQ_TOKEN=zeq_ak_... node zeq_client.js

Full source — zeq_client.js

Why inline? The full SDK source is pasted below so the mathematics is auditable. Copy-paste it, read it, self-host it — you never have to trust the Zeq API as a black box. Use our key for convenience, or wire it into your own backend. The v1.1.3 binding contract and ZeqProof HMAC are identical either way.
zeq_client.js 4373 bytes 124 lines ES module · Node 18+ 
/**
 * ZeqClient — JavaScript / Node.js SDK wrapper for the Zeq API
 * ================================================================
 * Single-file, zero-dependency, ES-module compatible with Node >= 18
 * (uses the built-in global `fetch`). Works in modern browsers too.
 *
 * Mirrors the v1.1.3 binding contract of `zeq_client.py`:
 *   - POST /api/zeq/compute  { operator_id, inputs } -> numeric result
 *   - POST /api/zeq/prove    { operator_id, inputs } -> ZeqProof HMAC
 *
 * [Zeq Daemon] HulyaPulse 1.287 Hz — τ_zeqond = 0.777 s — α_K = 0.00129
 */

export const ALPHA_SPEC = 0.00129;
export const F_HULYA    = 1.287;
export const TAU_ZEQOND = 0.777;

export class ZeqError extends Error {
  constructor(message, { status = 0, code = 'UNKNOWN', body = null } = {}) {
    super(message);
    this.name = 'ZeqError';
    this.status = status;
    this.code = code;
    this.body = body;
  }
}

export class ZeqClient {
  /**
   * @param {object}  opts
   * @param {string}  opts.token    - Bearer API key (zeq_ak_...)
   * @param {string} [opts.baseUrl] - Default "https://www.zeq.dev"
   * @param {number} [opts.timeoutMs] - Fetch timeout, default 10 000
   */
  constructor({ token, baseUrl = 'https://www.zeq.dev', timeoutMs = 10_000 } = {}) {
    if (!token) throw new Error('ZeqClient requires a `token` Bearer API key');
    this.token = token;
    this.baseUrl = baseUrl.replace(/\/+$/, '');
    this.timeoutMs = timeoutMs;
  }

  async _post(path, body) {
    const ctrl = new AbortController();
    const t = setTimeout(() => ctrl.abort(), this.timeoutMs);
    try {
      const res = await fetch(`${this.baseUrl}${path}`, {
        method: 'POST',
        signal: ctrl.signal,
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${this.token}`,
        },
        body: JSON.stringify(body),
      });
      const text = await res.text();
      let json;
      try { json = JSON.parse(text); } catch { json = { raw: text }; }
      if (!res.ok) {
        throw new ZeqError(
          json?.error?.message || `HTTP ${res.status}`,
          { status: res.status, code: json?.error?.code || 'HTTP_ERROR', body: json }
        );
      }
      return json;
    } finally {
      clearTimeout(t);
    }
  }

  /**
   * Execute a physics operator.
   *
   * @param {string} operatorId e.g. "NM21"
   * @param {object} inputs     e.g. { m1: 5.972e24, m2: 7.342e22, r: 3.844e8 }
   * @returns {Promise<object>} Full response: value, unit, uncertainty,
   *          solver, binding_overlay, zeqProof, compliance, zeqState, cko.
   */
  compute(operatorId, inputs) {
    return this._post('/api/zeq/compute', { operator_id: operatorId, inputs });
  }

  /**
   * Same payload as compute(), returns a signed ZeqProof HMAC envelope.
   */
  prove(operatorId, inputs) {
    return this._post('/api/zeq/prove', { operator_id: operatorId, inputs });
  }

  /**
   * GET /api/zeq/pulse — read HulyaPulse phase + Zeqond index.
   */
  async pulse() {
    const res = await fetch(`${this.baseUrl}/api/zeq/pulse`, {
      headers: { 'Authorization': `Bearer ${this.token}` }
    });
    return res.json();
  }
}

// CommonJS shim so `require('zeq_client')` works from plain Node scripts.
if (typeof module !== 'undefined' && typeof module.exports !== 'undefined') {
  module.exports = { ZeqClient, ZeqError, ALPHA_SPEC, F_HULYA, TAU_ZEQOND };
}

// ── CLI smoke test ────────────────────────────────────────────────────────
// Run with:  ZEQ_TOKEN=zeq_ak_... node zeq_client.js
if (typeof process !== 'undefined' && import.meta?.url === `file://${process.argv[1]}`) {
  const token = process.env.ZEQ_TOKEN;
  if (!token) {
    console.error('Set ZEQ_TOKEN=<zeq_ak_...> to run the smoke test.');
    process.exit(1);
  }
  const client = new ZeqClient({ token });
  console.log('═'.repeat(70));
  console.log('NM21 — Earth–Moon gravitational force  (expected ≈ 1.98e20 N)');
  console.log('═'.repeat(70));
  const r = await client.compute('NM21', { m1: 5.972e24, m2: 7.342e22, r: 3.844e8 });
  console.log(`value           = ${r.value}`);
  console.log(`unit            = ${r.unit}`);
  console.log(`uncertainty     = ${r.uncertainty}`);
  console.log(`solver          = ${r.solver}`);
  console.log(`binding_overlay = ${r.binding_overlay}`);
  console.log(`zeqProof        = ${(r.zeqProof || '').slice(0, 24)}…`);
}