@heossi/qnsi 0.3.2

package/CHANGELOG.md

@@ -0,0 +1,67 @@
+# @heossi/qnsi
+
+## 0.3.0
+
+### Minor Changes
+
+- Framework-adapter consolidation: the former standalone satellites
+  `@heossi/qnsi-browser`, `-langchain-qnsp`, `-llamaindex-qnsp`, and
+  `-autogen-qnsp` are folded in as subpaths of the one SDK —
+  `@heossi/qnsi/browser` (client-side PQC encryption/signing via
+  `@noble/post-quantum`), `@heossi/qnsi/langchain` (governed-agent
+  toolkit), `@heossi/qnsi/llamaindex` (SSE-X encrypted vector store), and
+  `@heossi/qnsi/autogen` (enclave code executor). Each subpath is
+  self-contained (no internal `@heossi/qnsi-*` workspace deps) and
+  preserves the prior behavior, endpoints, SSE-X token crypto, and
+  activation `sdkId`s byte-for-byte. Framework integrations
+  (`@langchain/core`, `llamaindex`, `autogen`) are **optional**
+  `peerDependencies`; `@noble/hashes`/`@noble/post-quantum` are runtime
+  deps for the browser + llamaindex SSE-X paths. The four standalone
+  packages are deleted (they were never published). Non-breaking: the
+  root export and `@heossi/qnsi/activation` are unchanged.
+
+## 0.2.0
+
+### Minor Changes
+
+- Single-SDK consolidation: completes the `@qnsp` → `@heossi/qnsi` scope
+  migration, folds the CLI in as the `qnsp` bin, and exposes the inlined
+  activation client as the `@heossi/qnsi/activation` subpath. The retired
+  standalone satellites (`-cli`, `-browser`, `-sdk-activation`,
+  `-langchain-qnsp`, `-llamaindex-qnsp`, `-autogen-qnsp`) are unpublished;
+  `@heossi/qnsi` is the one SDK to install.
+
+## 0.1.0 — 2026-04-30
+
+**Initial release.** The single-package Node.js / TypeScript SDK for QNSP, replacing the 11 per-service `@heossi/qnsi-*-sdk` packages with one consolidated entry point.
+
+### Why this exists
+
+The previous TypeScript SDK family was fragmented across 11 packages (`@heossi/qnsi-vault-sdk`, `@heossi/qnsi-kms-client`, `@heossi/qnsi-audit-sdk`, `@heossi/qnsi-auth-sdk`, `@heossi/qnsi-tenant-sdk`, `@heossi/qnsi-access-control-sdk`, `@heossi/qnsi-billing-sdk`, `@heossi/qnsi-crypto-inventory-sdk`, `@heossi/qnsi-storage-sdk`, `@heossi/qnsi-search-sdk`, `@heossi/qnsi-ai-sdk`). Each ran its own activation handshake, kept its own version, owned its own CHANGELOG, and emitted its own activation telemetry — making it hard to answer simple questions like "did this developer's SDK reach our backend?" or "which SDK install tripped the activation gate?".
+
+`@heossi/qnsi` collapses that into one package with eleven sub-namespaces, mirroring the `qnsp` Python / Go / Rust SDK shape. One activation, one connection pool, one CHANGELOG, one source of truth — same diagnostic surface as the other-language SDKs.
+
+### Added
+
+- `QnspClient({ apiKey, baseUrl?, timeoutMs? })` — top-level client. Lazily activates against `/billing/v1/sdk/activate` on first request, reports `sdkId="qnsp"` and `sdkVersion="0.1.0"`.
+- Eleven service sub-clients sharing one HTTP pool + one activation cache:
+  - `qnsp.vault` (createSecret / getSecret / getSecretVersion / rotateSecret / deleteSecret / listSecretVersions)
+  - `qnsp.kms` (createKey / listKeys / getKey / rotateKey / deleteKey / sign / verify / wrap / unwrap)
+  - `qnsp.audit` (logEvent / ingestEvents / listEvents)
+  - `qnsp.auth` (login / refreshToken / revoke / WebAuthn passkey lifecycle / MFA / SAML / OIDC / risk-based auth)
+  - `qnsp.tenant` (CRUD / crypto-policy management / quota / health)
+  - `qnsp.access` (RBAC roles, role assignments, checkPermission)
+  - `qnsp.billing` (entitlements, usage meters, invoices, credit balance)
+  - `qnsp.cryptoInventory` (CBOM: assets, discovery runs, PQC readiness)
+  - `qnsp.storage` (PQC-encrypted object storage with SSE-X)
+  - `qnsp.search` (encrypted vector search)
+  - `qnsp.ai` (model registry, workloads, inference, artifacts)
+- `parseQnspWebhook` and `verifyQnspWebhookSignature` — HMAC-SHA-256 verification + replay protection, identical to the helpers in the Python / Go / Rust SDKs.
+- Typed error hierarchy: `QnspError`, `QnspNetworkError`, `QnspAuthError`, `QnspApiError`, `QnspWebhookError`.
+- Top-level introspection: `tenantId()`, `tier()`, `limits()`, `hasFeature(name)`, `ensureActivated()`.
+
+### Migration
+
+The 11 per-service `@heossi/qnsi-*-sdk` packages on npm are now `npm deprecate`d to point at `@heossi/qnsi`. Existing installs continue to work; new code should reach for `@heossi/qnsi` directly. See the [Migration section in the README](./README.md#migration-from-per-service-sdks) for the import-by-import mapping.
+
+The internal QNSP monorepo continues to use the per-service packages for service-to-service calls; that migration will happen in a separate wave and is invisible to external consumers.

package/LICENSE.md

@@ -0,0 +1,8 @@
+# QNSP Licensing
+
+This repository is **multi-licensed**.
+
+- Source code under `packages/*` and selected `apps/*` directories is licensed **per package**. Refer to the `LICENSE` file inside each package directory.
+- Public SDK packages (those with `publishConfig.access: "public"`) are licensed under the **Apache License 2.0**.
+- Core platform packages (including `apps/ai-orchestrator` and `packages/kms`, and `packages/liboqs-native`) are licensed under the **Business Source License 1.1** with a Change License of **GPL-2.0-or-later**.
+- Materials under `docs/patent-ip-candidates` are **Proprietary**.

package/README.md

@@ -0,0 +1,200 @@
+# @heossi/qnsi — Node.js / TypeScript SDK for the Quantum-Native Security Infrastructure
+
+[![npm version](https://img.shields.io/npm/v/@heossi/qnsi.svg)](https://www.npmjs.com/package/@heossi/qnsi)
+[![License](https://img.shields.io/npm/l/@heossi/qnsi.svg)](./LICENSE)
+
+The official **single-package** Node.js / TypeScript SDK for QNSI. Covers the full customer-facing platform — vault, KMS, audit, auth, tenant, access-control, billing, crypto-inventory, storage, search, and AI orchestrator — plus webhook signature verification. Mirrors the shape of the `qnsp` Python / Go / Rust SDKs byte-for-byte: same wire contracts, same algorithm names, same FIPS 203 / 204 / 205 posture.
+
+> **Free tier available.** Free-forever account at <https://cloud.qnsp.cuilabs.io/auth> — 60-second signup, no credit card. Includes 10 GB PQC storage, 50 000 API calls/month, 20 KMS keys, 25 vault secrets.
+
+## Why one package?
+
+Previous TypeScript consumers had to install up to 11 separate `@heossi/qnsi-*-sdk` packages and keep their versions in sync. `@heossi/qnsi` collapses that into a single dependency with sub-namespaces:
+
+```ts
+import { QnspClient } from "@heossi/qnsi";
+
+const qnsp = new QnspClient({ apiKey: process.env.QNSP_API_KEY! });
+
+await qnsp.vault.createSecret({ ... });   // was @heossi/qnsi-vault-sdk
+await qnsp.kms.sign(keyId, data);          // was @heossi/qnsi-kms-client
+await qnsp.audit.logEvent({ ... });        // was @heossi/qnsi-audit-sdk
+await qnsp.tenant.getTenant(tenantId);     // was @heossi/qnsi-tenant-sdk
+// ...
+```
+
+One activation handshake on first use, shared across all 11 sub-clients. One version bump per QNSI release. One CHANGELOG. One source of truth.
+
+## Install
+
+```bash
+pnpm add @heossi/qnsi
+# or
+npm install @heossi/qnsi
+# or
+yarn add @heossi/qnsi
+```
+
+Requires Node.js ≥ 22.0.0. ESM-first; CommonJS consumers can `await import("@heossi/qnsi")`.
+
+## Quick start
+
+```ts
+import { QnspClient } from "@heossi/qnsi";
+
+const qnsp = new QnspClient({ apiKey: process.env.QNSP_API_KEY! });
+
+// Vault — PQC-encrypted secret storage
+const secret = await qnsp.vault.createSecret({
+  name: "openai-api-key",
+  payloadB64: Buffer.from("sk-...").toString("base64"),
+  algorithm: "ml-kem-768",
+});
+
+// KMS — server-side PQC keys
+const key = await qnsp.kms.createKey({ algorithm: "ml-dsa-65", purpose: "signing" });
+const sig = await qnsp.kms.sign(key.keyId as string, new TextEncoder().encode("hello"));
+const ok  = await qnsp.kms.verify(key.keyId as string, new TextEncoder().encode("hello"), sig);
+
+// Audit — immutable, hash-chained event log
+await qnsp.audit.logEvent({
+  eventType: "model.inference",
+  payload: { modelId: "gpt-4o", latencyMs: 412 },
+});
+
+// Tenant, access, billing, crypto-inventory, storage, search, ai, auth — all on one client
+await qnsp.tenant.getTenant(await qnsp.tenantId());
+await qnsp.access.checkPermission({ subjectId: "user-1", permission: "vault.read" });
+await qnsp.billing.getEntitlements();
+```
+
+## Modules
+
+Each sub-namespace wraps one QNSI backend service:
+
+| Sub-client | Wraps | Key methods |
+|---|---|---|
+| `qnsp.vault` | `apps/vault-service` (`/vault/v1`) | `createSecret`, `getSecret`, `getSecretVersion`, `rotateSecret`, `deleteSecret`, `listSecretVersions` |
+| `qnsp.kms` | `apps/kms-service` (`/kms/v1`) | `createKey`, `listKeys`, `getKey`, `rotateKey`, `deleteKey`, `sign`, `verify`, `wrap`, `unwrap` |
+| `qnsp.audit` | `apps/audit-service` (`/audit/v1`) | `logEvent`, `ingestEvents`, `listEvents` |
+| `qnsp.auth` | `apps/auth-service` (`/auth/v1`) | `login`, `refreshToken`, `revoke`, WebAuthn passkey lifecycle, `mfaChallenge` / `mfaVerify`, `federateSAML` / `federateOIDC`, `evaluateRisk` |
+| `qnsp.tenant` | `apps/tenant-service` (`/tenant/v1`) | `createTenant`, `getTenant`, `updateTenant`, `listTenants`, `getCryptoPolicy`, `upsertCryptoPolicy`, `getCurrentHealth`, `getCurrentQuotas` |
+| `qnsp.access` | `apps/access-control-service` (`/access/v1`) | `createRole`, `getRole`, `listRoles`, `deleteRole`, `assignRole`, `revokeRoleAssignment`, `checkPermission` |
+| `qnsp.billing` | `apps/billing-service` (`/billing/v1`) | `getEntitlements`, `ingestMeter`, `ingestMeters`, `listInvoices`, `getInvoice`, `getCreditBalance` |
+| `qnsp.cryptoInventory` | `apps/crypto-inventory-service` (`/crypto/v1`) | `listAssets`, `getAsset`, `getAssetStats`, `discoverAssets`, `getReadinessScore` |
+| `qnsp.storage` | `apps/storage-service` (`/storage/storage/v1`) | `putObject`, `getObject` (returns `[bytes, descriptor]`), `deleteObject`, `listObjects`, `listBuckets` |
+| `qnsp.search` | `apps/search-service` (`/search/v1`) | `createIndex`, `listIndexes`, `deleteIndex`, `upsertVectors`, `query` |
+| `qnsp.ai` | `apps/ai-orchestrator` (`/ai/v1`) | model registry (`registerModel`, `listModels`, `getModel`, `updateModel`, `activateModel`, `deployModel`), workloads (`submitWorkload`, `getWorkload`, `listWorkloads`, `cancelWorkload`), `invokeInference`, `registerArtifact` |
+
+## Verifying inbound webhooks
+
+QNSI signs every webhook with HMAC-SHA-256. Verify the **raw body** before parsing JSON:
+
+```ts
+import { parseQnspWebhook, QnspWebhookError } from "@heossi/qnsi";
+
+app.post("/webhooks/qnsp", express.raw({ type: "application/json" }), (req, res) => {
+  try {
+    const event = parseQnspWebhook({
+      body: req.body, // raw Buffer
+      signatureHeader: req.header("x-qnsp-signature") ?? "",
+      timestampHeader: req.header("x-qnsp-timestamp"),
+      secret: process.env.QNSP_WEBHOOK_SECRET!,
+    });
+    if (event.eventType === "key.rotated") {
+      // ...
+    }
+    res.sendStatus(200);
+  } catch (err) {
+    if (err instanceof QnspWebhookError) {
+      res.status(400).send(err.reason);
+    } else {
+      throw err;
+    }
+  }
+});
+```
+
+Constant-time HMAC comparison, 5-minute replay window by default (`MAX_WEBHOOK_SKEW_MS`), refuses payloads missing required fields.
+
+## Error handling
+
+All errors descend from `QnspError`:
+
+| Class | When |
+|---|---|
+| `QnspNetworkError` | DNS, TLS, timeout, or connection failure |
+| `QnspAuthError` | API key rejected at activation |
+| `QnspApiError` | A service returned 4xx/5xx with a structured body |
+| `QnspWebhookError` | HMAC mismatch, expired timestamp, malformed body, etc. |
+
+```ts
+import { QnspApiError, QnspNetworkError } from "@heossi/qnsi";
+
+try {
+  await qnsp.vault.getSecret("missing");
+} catch (err) {
+  if (err instanceof QnspApiError) console.log("HTTP", err.statusCode, err.code);
+  else if (err instanceof QnspNetworkError) console.log("could not reach QNSI:", err.message);
+  else throw err;
+}
+```
+
+## Activation + tier introspection
+
+`QnspClient` performs a one-shot handshake against `/billing/v1/sdk/activate` on first use. The result is cached in memory; subsequent calls reuse it until ~60 s before expiry. You can inspect the current activation:
+
+```ts
+await qnsp.tenantId();      // resolved tenant
+await qnsp.tier();          // plan tier
+await qnsp.limits();        // full limits dict
+await qnsp.hasFeature("sseEnabled");  // convenience boolean
+
+// Force the handshake at startup so you fail fast on a bad key:
+await qnsp.ensureActivated();
+```
+
+If the activation token is rotated server-side, the SDK invalidates its cache and retries the originating request once on a 401.
+
+## Migration from per-service SDKs
+
+The per-service `@heossi/qnsi-*-sdk` packages on npm are now **deprecated** in favour of `@heossi/qnsi`. They continue to install and work, but new code should use this package.
+
+| Before | After |
+|---|---|
+| `import { VaultClient } from "@heossi/qnsi-vault-sdk"` | `import { QnspClient } from "@heossi/qnsi"` then `qnsp.vault` |
+| `import { KmsClient } from "@heossi/qnsi-kms-client"` | `qnsp.kms` |
+| `import { AuthClient } from "@heossi/qnsi-auth-sdk"` | `qnsp.auth` |
+| `import { TenantClient } from "@heossi/qnsi-tenant-sdk"` | `qnsp.tenant` |
+| `import { AccessControlClient } from "@heossi/qnsi-access-control-sdk"` | `qnsp.access` |
+| `import { BillingClient } from "@heossi/qnsi-billing-sdk"` | `qnsp.billing` |
+| `import { CryptoInventoryClient } from "@heossi/qnsi-crypto-inventory-sdk"` | `qnsp.cryptoInventory` |
+| `import { StorageClient } from "@heossi/qnsi-storage-sdk"` | `qnsp.storage` |
+| `import { SearchClient } from "@heossi/qnsi-search-sdk"` | `qnsp.search` |
+| `import { AiOrchestratorClient } from "@heossi/qnsi-ai-sdk"` | `qnsp.ai` |
+| `import { AuditClient } from "@heossi/qnsi-audit-sdk"` | `qnsp.audit` |
+
+The constructor signature is simpler — one `apiKey` for everything, instead of a per-service config:
+
+```ts
+// Before — 11 packages, 11 activation handshakes, 11 versions to keep in sync
+import { VaultClient } from "@heossi/qnsi-vault-sdk";
+import { KmsClient } from "@heossi/qnsi-kms-client";
+import { AuditClient } from "@heossi/qnsi-audit-sdk";
+
+const vault = new VaultClient({ apiKey, baseUrl: "https://api.qnsp.cuilabs.io/proxy/vault", tier });
+const kms   = new KmsClient({   apiKey, baseUrl: "https://api.qnsp.cuilabs.io/proxy/kms",   tier });
+const audit = new AuditClient({ apiKey, baseUrl: "https://api.qnsp.cuilabs.io/proxy/audit", tier });
+
+// After — one package, one activation, one client
+import { QnspClient } from "@heossi/qnsi";
+
+const qnsp = new QnspClient({ apiKey });
+// qnsp.vault, qnsp.kms, qnsp.audit, ... all share one connection pool + one activation cache
+```
+
+The wire contracts are identical, so migrating method-by-method is mechanical.
+
+## License
+
+Apache-2.0. See [LICENSE](./LICENSE).

package/dist/_activation/activation-client.d.ts

@@ -0,0 +1,65 @@
+/**
+ * SDK Activation Client
+ *
+ * Handles activation handshake with the QNSP billing-service.
+ * Browser-compatible — uses global fetch, no node: imports.
+ *
+ * Every SDK must call `activateSdk()` before performing operations.
+ * The activation validates the API key against the QNSP backend,
+ * returns tier limits, and issues a short-lived activation token.
+ *
+ * Activation tokens are cached in-memory and auto-refreshed before expiry.
+ *
+ * @module
+ */
+import { type SdkActivationError, type SdkActivationLimits, type SdkActivationResponse, type SdkIdentifier } from "./types.js";
+/**
+ * Typed error for SDK activation failures.
+ */
+export declare class SdkActivationError_ extends Error {
+    readonly code: SdkActivationError["code"];
+    readonly statusCode: number;
+    constructor(code: SdkActivationError["code"], message: string, statusCode: number);
+}
+/**
+ * Configuration for SDK activation.
+ */
+export interface SdkActivationConfig {
+    /** QNSP API key (required — get one at https://cloud.qnsp.cuilabs.io/signup) */
+    readonly apiKey: string;
+    /** SDK package identifier */
+    readonly sdkId: SdkIdentifier;
+    /** SDK version string */
+    readonly sdkVersion: string;
+    /** Override platform URL (defaults to https://api.qnsp.cuilabs.io) */
+    readonly platformUrl?: string | undefined;
+    /** Override activation timeout in ms (defaults to 15000) */
+    readonly timeoutMs?: number | undefined;
+    /** Custom fetch implementation (for testing or non-standard runtimes) */
+    readonly fetchImpl?: (typeof globalThis)["fetch"] | undefined;
+}
+/**
+ * Activate an SDK against the QNSP platform.
+ *
+ * This must be called before any SDK operations. It validates the API key,
+ * returns the tenant's tier and limits, and caches the activation token.
+ *
+ * Cached activations are returned immediately if still valid.
+ * Tokens are auto-refreshed 5 minutes before expiry.
+ *
+ * @throws {SdkActivationError_} if the API key is invalid, account is suspended, or service is unavailable
+ */
+export declare function activateSdk(config: SdkActivationConfig): Promise<SdkActivationResponse>;
+/**
+ * Get the cached activation for an SDK, or null if not activated.
+ */
+export declare function getCachedActivation(config: SdkActivationConfig): SdkActivationResponse | null;
+/**
+ * Get the tier limits from a cached activation.
+ */
+export declare function getActivationLimits(config: SdkActivationConfig): SdkActivationLimits | null;
+/**
+ * Clear all cached activations. Primarily for testing.
+ */
+export declare function clearActivationCache(): void;
+//# sourceMappingURL=activation-client.d.ts.map

package/dist/_activation/activation-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activation-client.d.ts","sourceRoot":"","sources":["../../src/_activation/activation-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACN,KAAK,kBAAkB,EAEvB,KAAK,mBAAmB,EAExB,KAAK,qBAAqB,EAE1B,KAAK,aAAa,EAClB,MAAM,YAAY,CAAC;AAOpB;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,IAAI,EAAE,kBAAkB,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;CAMjF;AAUD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,gFAAgF;IAChF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6BAA6B;IAC7B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,yBAAyB;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,sEAAsE;IACtE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,yEAAyE;IACzE,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,UAAU,CAAC,CAAC,OAAO,CAAC,GAAG,SAAS,CAAC;CAC9D;AAsBD;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CA+G7F;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,qBAAqB,GAAG,IAAI,CAS7F;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,mBAAmB,GAAG,IAAI,CAG3F;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C"}

package/dist/_activation/activation-client.js

@@ -0,0 +1,164 @@
+/**
+ * SDK Activation Client
+ *
+ * Handles activation handshake with the QNSP billing-service.
+ * Browser-compatible — uses global fetch, no node: imports.
+ *
+ * Every SDK must call `activateSdk()` before performing operations.
+ * The activation validates the API key against the QNSP backend,
+ * returns tier limits, and issues a short-lived activation token.
+ *
+ * Activation tokens are cached in-memory and auto-refreshed before expiry.
+ *
+ * @module
+ */
+import { SdkActivationErrorSchema, SdkActivationResponseSchema, } from "./types.js";
+const ACTIVATION_PATH = "/billing/v1/sdk/activate";
+const DEFAULT_PLATFORM_URL = "https://api.qnsp.cuilabs.io";
+const ACTIVATION_TIMEOUT_MS = 15_000;
+const REFRESH_BUFFER_SECONDS = 300; // Refresh 5 minutes before expiry
+/**
+ * Typed error for SDK activation failures.
+ */
+export class SdkActivationError_ extends Error {
+    code;
+    statusCode;
+    constructor(code, message, statusCode) {
+        super(message);
+        this.name = "SdkActivationError";
+        this.code = code;
+        this.statusCode = statusCode;
+    }
+}
+/** In-memory activation cache keyed by `${platformUrl}:${apiKeyPrefix}:${sdkId}` */
+const activationCache = new Map();
+function cacheKey(config) {
+    const url = config.platformUrl ?? DEFAULT_PLATFORM_URL;
+    // Use first 8 chars of API key for cache key (avoid storing full key in memory map keys)
+    const keyPrefix = config.apiKey.slice(0, 8);
+    return `${url}:${keyPrefix}:${config.sdkId}`;
+}
+function detectRuntime() {
+    if (typeof globalThis.process !== "undefined" && globalThis.process.versions?.node) {
+        return "node";
+    }
+    if ("window" in globalThis && "document" in globalThis) {
+        return "browser";
+    }
+    return "edge";
+}
+/**
+ * Activate an SDK against the QNSP platform.
+ *
+ * This must be called before any SDK operations. It validates the API key,
+ * returns the tenant's tier and limits, and caches the activation token.
+ *
+ * Cached activations are returned immediately if still valid.
+ * Tokens are auto-refreshed 5 minutes before expiry.
+ *
+ * @throws {SdkActivationError_} if the API key is invalid, account is suspended, or service is unavailable
+ */
+export async function activateSdk(config) {
+    if (!config.apiKey || config.apiKey.trim().length === 0) {
+        throw new SdkActivationError_("INVALID_API_KEY", `QNSP ${config.sdkId}: apiKey is required. ` +
+            "Get your free API key at https://cloud.qnsp.cuilabs.io/signup — " +
+            "no credit card required (FREE tier: 10 GB storage, 50,000 API calls/month). " +
+            `Docs: https://docs.qnsp.cuilabs.io/sdk/${config.sdkId}`, 401);
+    }
+    const key = cacheKey(config);
+    const cached = activationCache.get(key);
+    const now = Date.now();
+    // Return cached activation if still valid (with refresh buffer)
+    if (cached && cached.expiresAt - REFRESH_BUFFER_SECONDS * 1000 > now) {
+        return cached.response;
+    }
+    const platformUrl = (config.platformUrl ?? DEFAULT_PLATFORM_URL).replace(/\/$/, "");
+    const timeoutMs = config.timeoutMs ?? ACTIVATION_TIMEOUT_MS;
+    const fetchFn = config.fetchImpl ?? globalThis.fetch;
+    const body = {
+        sdkId: config.sdkId,
+        sdkVersion: config.sdkVersion,
+        runtime: detectRuntime(),
+    };
+    let response;
+    try {
+        response = await fetchFn(`${platformUrl}${ACTIVATION_PATH}`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${config.apiKey}`,
+            },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    catch (cause) {
+        throw new SdkActivationError_("SERVICE_UNAVAILABLE", `QNSP ${config.sdkId}: Failed to reach QNSP platform for activation. ` +
+            `Ensure network connectivity to ${platformUrl}. ` +
+            `Error: ${cause instanceof Error ? cause.message : String(cause)}`, 503);
+    }
+    if (!response.ok) {
+        let errorBody;
+        try {
+            const json = await response.json();
+            const parsed = SdkActivationErrorSchema.safeParse(json);
+            if (parsed.success) {
+                errorBody = parsed.data;
+            }
+        }
+        catch {
+            // Ignore JSON parse errors — use status code
+        }
+        if (errorBody) {
+            throw new SdkActivationError_(errorBody.code, errorBody.error, response.status);
+        }
+        if (response.status === 401) {
+            throw new SdkActivationError_("INVALID_API_KEY", `QNSP ${config.sdkId}: Invalid API key. ` +
+                "Get your API key at https://cloud.qnsp.cuilabs.io/api-keys", 401);
+        }
+        if (response.status === 429) {
+            throw new SdkActivationError_("RATE_LIMITED", `QNSP ${config.sdkId}: Activation rate limited. Please retry after a short delay.`, 429);
+        }
+        throw new SdkActivationError_("SERVICE_UNAVAILABLE", `QNSP ${config.sdkId}: Activation failed with HTTP ${response.status}`, response.status);
+    }
+    const json = await response.json();
+    const parsed = SdkActivationResponseSchema.safeParse(json);
+    if (!parsed.success) {
+        throw new SdkActivationError_("SERVICE_UNAVAILABLE", `QNSP ${config.sdkId}: Invalid activation response from platform`, 502);
+    }
+    const activation = parsed.data;
+    // Cache the activation
+    activationCache.set(key, {
+        response: activation,
+        expiresAt: now + activation.expiresInSeconds * 1000,
+    });
+    return activation;
+}
+/**
+ * Get the cached activation for an SDK, or null if not activated.
+ */
+export function getCachedActivation(config) {
+    const key = cacheKey(config);
+    const cached = activationCache.get(key);
+    if (!cached)
+        return null;
+    if (cached.expiresAt < Date.now()) {
+        activationCache.delete(key);
+        return null;
+    }
+    return cached.response;
+}
+/**
+ * Get the tier limits from a cached activation.
+ */
+export function getActivationLimits(config) {
+    const activation = getCachedActivation(config);
+    return activation?.limits ?? null;
+}
+/**
+ * Clear all cached activations. Primarily for testing.
+ */
+export function clearActivationCache() {
+    activationCache.clear();
+}
+//# sourceMappingURL=activation-client.js.map

package/dist/_activation/activation-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activation-client.js","sourceRoot":"","sources":["../../src/_activation/activation-client.ts"],"names":[],"mappings":"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"}

package/dist/_activation/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Inlined copy of @heossi/qnsi-sdk-activation (workspace package, not published).
+ * Bundled here so @heossi/qnsi has no external @heossi/qnsi-* dependencies.
+ * Keep this folder in sync with packages/sdk-activation/src/ when changes
+ * land upstream — both files are minimal (activation-client.ts +
+ * types.ts) so a manual diff is tractable.
+ */
+export { activateSdk, clearActivationCache, getActivationLimits, getCachedActivation, type SdkActivationConfig, SdkActivationError_, } from "./activation-client.js";
+export { type SdkActivationError, SdkActivationErrorSchema, type SdkActivationLimits, SdkActivationLimitsSchema, type SdkActivationRequest, SdkActivationRequestSchema, type SdkActivationResponse, SdkActivationResponseSchema, type SdkIdentifier, SdkIdentifierSchema, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/_activation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/_activation/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACN,WAAW,EACX,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,KAAK,mBAAmB,EACxB,mBAAmB,GACnB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACN,KAAK,kBAAkB,EACvB,wBAAwB,EACxB,KAAK,mBAAmB,EACxB,yBAAyB,EACzB,KAAK,oBAAoB,EACzB,0BAA0B,EAC1B,KAAK,qBAAqB,EAC1B,2BAA2B,EAC3B,KAAK,aAAa,EAClB,mBAAmB,GACnB,MAAM,YAAY,CAAC"}

package/dist/_activation/index.js

@@ -0,0 +1,10 @@
+/**
+ * Inlined copy of @heossi/qnsi-sdk-activation (workspace package, not published).
+ * Bundled here so @heossi/qnsi has no external @heossi/qnsi-* dependencies.
+ * Keep this folder in sync with packages/sdk-activation/src/ when changes
+ * land upstream — both files are minimal (activation-client.ts +
+ * types.ts) so a manual diff is tractable.
+ */
+export { activateSdk, clearActivationCache, getActivationLimits, getCachedActivation, SdkActivationError_, } from "./activation-client.js";
+export { SdkActivationErrorSchema, SdkActivationLimitsSchema, SdkActivationRequestSchema, SdkActivationResponseSchema, SdkIdentifierSchema, } from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/_activation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/_activation/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACN,WAAW,EACX,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EAEnB,mBAAmB,GACnB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAEN,wBAAwB,EAExB,yBAAyB,EAEzB,0BAA0B,EAE1B,2BAA2B,EAE3B,mBAAmB,GACnB,MAAM,YAAY,CAAC"}