@epochcore/qaas-sdk 1.0.0 → 1.2.0

package/dist/index.js

@@ -23,91 +23,232 @@ __export(index_exports, {
   ALGORITHMS: () => ALGORITHMS,
   QaaSClient: () => QaaSClient,
   QaaSError: () => QaaSError,
-  qaas: () => qaas
+  QaaSRateLimitError: () => QaaSRateLimitError,
+  QaaSValidationError: () => QaaSValidationError,
+  SIGNATURE_MAX_AGE_MS: () => SIGNATURE_MAX_AGE_MS
 });
 module.exports = __toCommonJS(index_exports);
+var SDK_VERSION = "1.2.0";
+var SDK_USER_AGENT = `EpochCore-QaaS-SDK/${SDK_VERSION}`;
+var _crypto = typeof globalThis.crypto !== "undefined" ? globalThis.crypto : require("crypto").webcrypto;
+var MIN_TIMEOUT_MS = 5e3;
+var MAX_TIMEOUT_MS = 12e4;
+var DEFAULT_TIMEOUT_MS = 3e4;
+var SIGNATURE_MAX_AGE_MS = 3e5;
+var DEFAULT_RATE_LIMIT = 10;
+var DEFAULT_RATE_BURST = 20;
+var MAX_BODY_SIZE = 1048576;
+var MAX_SHOTS = 1e5;
+var MIN_SHOTS = 1;
+var MAX_ALGORITHM_ID_LENGTH = 64;
+var MAX_RETRY_ATTEMPTS = 3;
+var RETRY_BASE_MS = 500;
+var VALID_BACKENDS = /* @__PURE__ */ new Set([
+  "simulator",
+  "qiskit_aer",
+  "cirq",
+  "pennylane",
+  "ibm_quantum"
+]);
+var TokenBucket = class {
+  constructor(capacity, refillRate) {
+    this.capacity = capacity;
+    this.refillRate = refillRate;
+    this.tokens = capacity;
+    this.lastRefill = Date.now();
+  }
+  tryConsume() {
+    this.refill();
+    if (this.tokens >= 1) {
+      this.tokens -= 1;
+      return true;
+    }
+    return false;
+  }
+  refill() {
+    const now = Date.now();
+    const elapsed = (now - this.lastRefill) / 1e3;
+    this.tokens = Math.min(this.capacity, this.tokens + elapsed * this.refillRate);
+    this.lastRefill = now;
+  }
+};
+async function hmacSign(secret, message) {
+  const enc = new TextEncoder();
+  const key = await _crypto.subtle.importKey(
+    "raw",
+    enc.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const sig = await _crypto.subtle.sign("HMAC", key, enc.encode(message));
+  return Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function generateNonce() {
+  const bytes = new Uint8Array(16);
+  _crypto.getRandomValues(bytes);
+  return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function validateRunRequest(req) {
+  if (!req.algorithm_id || typeof req.algorithm_id !== "string") {
+    throw new QaaSValidationError("algorithm_id is required and must be a string");
+  }
+  if (req.algorithm_id.length > MAX_ALGORITHM_ID_LENGTH) {
+    throw new QaaSValidationError(`algorithm_id exceeds max length of ${MAX_ALGORITHM_ID_LENGTH}`);
+  }
+  if (!/^[A-Z0-9_]+$/.test(req.algorithm_id)) {
+    throw new QaaSValidationError("algorithm_id must contain only uppercase letters, digits, and underscores");
+  }
+  if (req.backend !== void 0) {
+    if (!VALID_BACKENDS.has(req.backend)) {
+      throw new QaaSValidationError(
+        `Invalid backend "${req.backend}". Must be one of: ${[...VALID_BACKENDS].join(", ")}`
+      );
+    }
+  }
+  if (req.shots !== void 0) {
+    if (typeof req.shots !== "number" || !Number.isInteger(req.shots)) {
+      throw new QaaSValidationError("shots must be an integer");
+    }
+    if (req.shots < MIN_SHOTS || req.shots > MAX_SHOTS) {
+      throw new QaaSValidationError(`shots must be between ${MIN_SHOTS} and ${MAX_SHOTS}`);
+    }
+  }
+  if (!req.parameters || typeof req.parameters !== "object" || Array.isArray(req.parameters)) {
+    throw new QaaSValidationError("parameters must be a non-null object");
+  }
+  const serialized = JSON.stringify(req.parameters);
+  if (serialized.length > MAX_BODY_SIZE) {
+    throw new QaaSValidationError(`parameters exceed max size of ${MAX_BODY_SIZE} bytes`);
+  }
+}
 var QaaSClient = class {
   constructor(config = {}) {
-    this.baseUrl = config.baseUrl || "https://api.qaas.epochcoreqcs.com";
+    this.baseUrl = (config.baseUrl || "https://api.qaas.epochcoreqcs.com").replace(/\/+$/, "");
     this.apiKey = config.apiKey;
-    this.timeout = config.timeout || 3e4;
+    this.apiSecret = config.apiSecret;
+    this.enableSigning = config.enableSigning ?? !!config.apiSecret;
+    this.maxRetries = Math.min(Math.max(config.maxRetries ?? MAX_RETRY_ATTEMPTS, 0), 5);
+    const raw = config.timeout ?? DEFAULT_TIMEOUT_MS;
+    this.timeout = Math.min(Math.max(raw, MIN_TIMEOUT_MS), MAX_TIMEOUT_MS);
+    this.rateLimiter = new TokenBucket(
+      config.rateBurst ?? DEFAULT_RATE_BURST,
+      config.rateLimit ?? DEFAULT_RATE_LIMIT
+    );
   }
-  async request(path, options = {}) {
+  async request(method, path, body) {
+    if (!this.rateLimiter.tryConsume()) {
+      throw new QaaSRateLimitError("Client-side rate limit exceeded. Wait and retry.");
+    }
+    if (body && body.length > MAX_BODY_SIZE) {
+      throw new QaaSValidationError(`Request body exceeds max size of ${MAX_BODY_SIZE} bytes`);
+    }
+    const requestId = generateNonce();
+    const timestamp = Date.now().toString();
     const headers = {
       "Content-Type": "application/json",
-      ...options.headers || {}
+      "User-Agent": SDK_USER_AGENT,
+      "X-Request-Id": requestId,
+      "X-Timestamp": timestamp
     };
     if (this.apiKey) {
       headers["X-API-Key"] = this.apiKey;
     }
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
-    try {
-      const response = await fetch(`${this.baseUrl}${path}`, {
-        ...options,
-        headers,
-        signal: controller.signal
-      });
-      if (!response.ok) {
-        const error = await response.json().catch(() => ({ error: "Unknown error" }));
-        throw new QaaSError(
-          error.error || `Request failed with status ${response.status}`,
-          response.status,
-          error
+    if (this.enableSigning && this.apiSecret) {
+      const nonce = generateNonce();
+      const sigPayload = [method, path, timestamp, nonce, body || ""].join("\n");
+      const signature = await hmacSign(this.apiSecret, sigPayload);
+      headers["X-Signature"] = signature;
+      headers["X-Nonce"] = nonce;
+    }
+    let lastError;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      if (attempt > 0) {
+        const delay = RETRY_BASE_MS * Math.pow(2, attempt - 1);
+        const jitter = Math.random() * delay * 0.5;
+        await new Promise((r) => setTimeout(r, delay + jitter));
+      }
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+      try {
+        const response = await fetch(`${this.baseUrl}${path}`, {
+          method,
+          headers,
+          body: body || void 0,
+          signal: controller.signal
+        });
+        if (response.status === 429 && attempt < this.maxRetries) {
+          const retryAfter = response.headers.get("Retry-After");
+          if (retryAfter) {
+            await new Promise((r) => setTimeout(r, parseInt(retryAfter, 10) * 1e3));
+          }
+          lastError = new QaaSError("Rate limited by server", 429);
+          continue;
+        }
+        if ([502, 503, 504].includes(response.status) && attempt < this.maxRetries) {
+          lastError = new QaaSError(`Server error ${response.status}`, response.status);
+          continue;
+        }
+        if (!response.ok) {
+          const error = await response.json().catch(() => ({}));
+          throw new QaaSError(
+            typeof error.error === "string" ? error.error : `Request failed (${response.status})`,
+            response.status
+          );
+        }
+        return await response.json();
+      } catch (err) {
+        if (err instanceof QaaSError) throw err;
+        if (err instanceof QaaSValidationError) throw err;
+        if (err instanceof DOMException && err.name === "AbortError") {
+          lastError = new QaaSError(`Request timed out after ${this.timeout}ms`, 408);
+          if (attempt < this.maxRetries) continue;
+          throw lastError;
+        }
+        lastError = new QaaSError(
+          err instanceof Error ? err.message : "Network error",
+          0
         );
+        if (attempt < this.maxRetries) continue;
+      } finally {
+        clearTimeout(timeoutId);
       }
-      return await response.json();
-    } finally {
-      clearTimeout(timeoutId);
     }
+    throw lastError ?? new QaaSError("Request failed after retries", 0);
   }
-  /**
-   * Check API health and status
-   */
+  // ═══════════════════════════════════════════════════════════════════
+  // API Methods
+  // ═══════════════════════════════════════════════════════════════════
   async health() {
-    return this.request("/health");
+    return this.request("GET", "/health");
   }
-  /**
-   * Get pricing information for all tiers
-   */
   async getPricing() {
-    return this.request("/api/pricing");
+    return this.request("GET", "/api/pricing");
   }
-  /**
-   * Get available algorithms for your tier
-   */
   async getAlgorithms() {
-    return this.request("/api/quantum/algorithms");
+    return this.request("GET", "/api/quantum/algorithms");
   }
-  /**
-   * Get algorithms filtered by category
-   */
   async getAlgorithmsByCategory(category) {
     const response = await this.getAlgorithms();
     return response.algorithms.filter((algo) => algo.category === category);
   }
-  /**
-   * Run a quantum algorithm
-   */
   async runAlgorithm(request) {
-    return this.request("/api/quantum/run", {
-      method: "POST",
-      body: JSON.stringify(request)
-    });
+    validateRunRequest(request);
+    return this.request("POST", "/api/quantum/run", JSON.stringify(request));
   }
-  /**
-   * Get current usage statistics
-   */
   async getUsage() {
-    return this.request("/api/quantum/usage");
+    return this.request("GET", "/api/quantum/usage");
   }
-  // ==========================================
-  // Convenience methods for common algorithms
-  // ==========================================
-  /**
-   * Run Markowitz portfolio optimization (QAOA)
-   */
+  // ═══════════════════════════════════════════════════════════════════
+  // Convenience methods
+  // ═══════════════════════════════════════════════════════════════════
   async optimizePortfolio(params) {
+    if (!Array.isArray(params.assets) || params.assets.length === 0) {
+      throw new QaaSValidationError("assets must be a non-empty array of strings");
+    }
+    if (params.assets.length !== params.returns.length) {
+      throw new QaaSValidationError("assets and returns arrays must have equal length");
+    }
     return this.runAlgorithm({
       algorithm_id: "QAOA_PORT_001",
       parameters: {
@@ -119,24 +260,31 @@ var QaaSClient = class {
       backend: params.backend || "simulator"
     });
   }
-  /**
-   * Run Value at Risk (VaR) estimation
-   */
   async estimateVaR(params) {
+    if (typeof params.portfolio_value !== "number" || params.portfolio_value <= 0) {
+      throw new QaaSValidationError("portfolio_value must be a positive number");
+    }
+    if (!Array.isArray(params.returns_history) || params.returns_history.length === 0) {
+      throw new QaaSValidationError("returns_history must be a non-empty array");
+    }
+    const cl = params.confidence_level ?? 0.95;
+    if (cl <= 0 || cl >= 1) {
+      throw new QaaSValidationError("confidence_level must be between 0 and 1 (exclusive)");
+    }
     return this.runAlgorithm({
       algorithm_id: "AE_PROB_004",
       parameters: {
         portfolio_value: params.portfolio_value,
         returns_history: params.returns_history,
-        confidence_level: params.confidence_level ?? 0.95
+        confidence_level: cl
       },
       backend: params.backend || "simulator"
     });
   }
-  /**
-   * Run Grover search for arbitrage opportunities
-   */
   async findArbitrage(params) {
+    if (!Array.isArray(params.price_matrix) || params.price_matrix.length === 0) {
+      throw new QaaSValidationError("price_matrix must be a non-empty 2D array");
+    }
     return this.runAlgorithm({
       algorithm_id: "GROVER_BOOL_003",
       parameters: {
@@ -146,23 +294,30 @@ var QaaSClient = class {
       backend: params.backend || "simulator"
     });
   }
-  /**
-   * Solve a QUBO problem
-   */
   async solveQUBO(params) {
+    if (!Array.isArray(params.Q_matrix) || params.Q_matrix.length === 0) {
+      throw new QaaSValidationError("Q_matrix must be a non-empty 2D array");
+    }
+    const reads = params.num_reads ?? 1e3;
+    if (reads < 1 || reads > 1e5) {
+      throw new QaaSValidationError("num_reads must be between 1 and 100,000");
+    }
     return this.runAlgorithm({
       algorithm_id: "QAOA_QUBO_001",
       parameters: {
         Q: params.Q_matrix,
-        num_reads: params.num_reads ?? 1e3
+        num_reads: reads
       },
       backend: params.backend || "simulator"
     });
   }
-  /**
-   * Run Monte Carlo amplitude estimation
-   */
   async monteCarloEstimate(params) {
+    if (!params.target_function || typeof params.target_function !== "string") {
+      throw new QaaSValidationError("target_function is required");
+    }
+    if (params.target_function.length > 1e4) {
+      throw new QaaSValidationError("target_function exceeds max length of 10,000 characters");
+    }
     return this.runAlgorithm({
       algorithm_id: "AE_PROB_002",
       parameters: {
@@ -173,18 +328,132 @@ var QaaSClient = class {
       backend: params.backend || "simulator"
     });
   }
+  // ═══════════════════════════════════════════════════════════════════
+  // Quantum Teleportation (GROT) — via godel-task-router
+  // ═══════════════════════════════════════════════════════════════════
+  async quantumTeleport(params = {}) {
+    return this.request(
+      "POST",
+      "/v1/quantum/multi-hop/teleport",
+      JSON.stringify({
+        qubits: params.qubits ?? 8,
+        state: params.state ?? "ghz",
+        oscillation_cycles: params.oscillation_cycles ?? 3,
+        source_backend: params.source_backend,
+        destination_backend: params.destination_backend
+      })
+    );
+  }
+  async quantumTeleportStatus() {
+    return this.request("GET", "/v1/quantum/multi-hop/status");
+  }
+  async quantumTeleportPlan(params = {}) {
+    return this.request(
+      "POST",
+      "/v1/quantum/multi-hop/plan",
+      JSON.stringify({
+        qubits: params.qubits ?? 8,
+        state: params.state ?? "ghz",
+        strategy: params.strategy ?? "combined"
+      })
+    );
+  }
+  // ═══════════════════════════════════════════════════════════════════
+  // Quantum Random Number Generation (QRNG)
+  // ═══════════════════════════════════════════════════════════════════
+  /**
+   * Generate quantum random bits.
+   *
+   * @param params.bits - Number of random bits (1–4096, default 256)
+   * @param params.format - Output format: 'hex' | 'int' | 'bytes' (default 'hex')
+   */
+  async generateQRNG(params = {}) {
+    const bits = params.bits ?? 256;
+    if (typeof bits !== "number" || !Number.isInteger(bits)) {
+      throw new QaaSValidationError("bits must be an integer");
+    }
+    if (bits < 1 || bits > 4096) {
+      throw new QaaSValidationError("bits must be between 1 and 4096");
+    }
+    const format = params.format ?? "hex";
+    if (!["hex", "int", "bytes"].includes(format)) {
+      throw new QaaSValidationError("format must be hex, int, or bytes");
+    }
+    return this.request(
+      "POST",
+      "/v1/random/generate",
+      JSON.stringify({ bits, format })
+    );
+  }
+  /**
+   * Generate a quantum random number in the range [0, 1).
+   * Convenience wrapper over generateQRNG for normalized floats.
+   *
+   * @param count - How many floats to generate (1–1024, default 1)
+   * @returns Array of floats in [0, 1), each derived from 32 quantum bits
+   */
+  async generateQuantumFloats(count = 1) {
+    if (typeof count !== "number" || !Number.isInteger(count)) {
+      throw new QaaSValidationError("count must be an integer");
+    }
+    if (count < 1 || count > 1024) {
+      throw new QaaSValidationError("count must be between 1 and 1024");
+    }
+    const totalBits = count * 32;
+    const response = await this.generateQRNG({ bits: Math.min(totalBits, 4096), format: "bytes" });
+    const bytes = response.value;
+    const floats = [];
+    for (let i = 0; i < count && i * 4 + 3 < bytes.length; i++) {
+      const u32 = (bytes[i * 4] << 24 | bytes[i * 4 + 1] << 16 | bytes[i * 4 + 2] << 8 | bytes[i * 4 + 3]) >>> 0;
+      floats.push(u32 / 4294967295);
+    }
+    return floats;
+  }
+  /**
+   * Generate a quantum-random cryptographic key.
+   *
+   * @param length - Key length in bytes (1–64, default 32)
+   */
+  async generateQuantumKey(length = 32) {
+    if (typeof length !== "number" || !Number.isInteger(length)) {
+      throw new QaaSValidationError("length must be an integer");
+    }
+    if (length < 1 || length > 64) {
+      throw new QaaSValidationError("length must be between 1 and 64");
+    }
+    return this.request(
+      "POST",
+      "/v1/random/key",
+      JSON.stringify({ length })
+    );
+  }
+  /**
+   * Generate a quantum-random UUID v4.
+   */
+  async generateQuantumUUID() {
+    return this.request("POST", "/v1/random/uuid", "{}");
+  }
 };
 var QaaSError = class extends Error {
-  constructor(message, statusCode, response) {
+  constructor(message, statusCode) {
     super(message);
     this.statusCode = statusCode;
-    this.response = response;
     this.name = "QaaSError";
   }
 };
-var qaas = new QaaSClient();
+var QaaSValidationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "QaaSValidationError";
+  }
+};
+var QaaSRateLimitError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "QaaSRateLimitError";
+  }
+};
 var ALGORITHMS = {
-  // Amplitude Estimation
   AMPLITUDE_ESTIMATION: {
     PROB_001: "AE_PROB_001",
     PROB_002: "AE_PROB_002",
@@ -192,7 +461,6 @@ var ALGORITHMS = {
     VAR: "AE_PROB_004",
     CVAR: "AE_PROB_005"
   },
-  // Grover Search
   GROVER: {
     BOOLEAN_SAT: "GROVER_BOOL_001",
     PORTFOLIO_CONSTRAINT: "GROVER_BOOL_002",
@@ -200,7 +468,6 @@ var ALGORITHMS = {
     COMPLIANCE: "GROVER_BOOL_004",
     PATTERN: "GROVER_BOOL_005"
   },
-  // QAOA Portfolio
   QAOA_PORTFOLIO: {
     MARKOWITZ: "QAOA_PORT_001",
     RISK_PARITY: "QAOA_PORT_002",
@@ -208,7 +475,6 @@ var ALGORITHMS = {
     MIN_VARIANCE: "QAOA_PORT_004",
     BLACK_LITTERMAN: "QAOA_PORT_005"
   },
-  // QUBO
   QUBO: {
     GENERAL: "QAOA_QUBO_001",
     MAX_CUT: "QAOA_QUBO_002",
@@ -222,5 +488,7 @@ var ALGORITHMS = {
   ALGORITHMS,
   QaaSClient,
   QaaSError,
-  qaas
+  QaaSRateLimitError,
+  QaaSValidationError,
+  SIGNATURE_MAX_AGE_MS
 });