@qnsp/sdk-activation 0.1.1

package/dist/types.js

@@ -0,0 +1,84 @@
+/**
+ * SDK Activation Types
+ *
+ * Shared contract between SDK clients and the billing-service activation endpoint.
+ * Browser-compatible — no node: imports.
+ *
+ * @module
+ */
+import { z } from "zod";
+/**
+ * SDK identifier sent during activation to identify which package is being used.
+ */
+export const SdkIdentifierSchema = z.enum([
+    "browser-sdk",
+    "vault-sdk",
+    "storage-sdk",
+    "search-sdk",
+    "kms-client",
+    "ai-sdk",
+    "tenant-sdk",
+    "billing-sdk",
+    "auth-sdk",
+    "audit-sdk",
+    "access-control-sdk",
+    "crypto-inventory-sdk",
+]);
+/**
+ * Request body for POST /billing/v1/sdk/activate
+ */
+export const SdkActivationRequestSchema = z.object({
+    /** The SDK package requesting activation */
+    sdkId: SdkIdentifierSchema,
+    /** SDK version string (e.g., "0.1.0") */
+    sdkVersion: z.string().min(1).max(32),
+    /** Runtime environment: "browser", "node", "edge" */
+    runtime: z.enum(["browser", "node", "edge"]),
+});
+/**
+ * Tier limits returned in the activation response.
+ * Subset of full TierLimits — only what SDKs need for client-side enforcement.
+ */
+export const SdkActivationLimitsSchema = z.object({
+    storageGB: z.number(),
+    apiCalls: z.number(),
+    enclavesEnabled: z.boolean(),
+    aiTrainingEnabled: z.boolean(),
+    aiInferenceEnabled: z.boolean(),
+    sseEnabled: z.boolean(),
+    vaultEnabled: z.boolean(),
+});
+/**
+ * Successful activation response from billing-service.
+ */
+export const SdkActivationResponseSchema = z.object({
+    /** Whether activation succeeded */
+    activated: z.literal(true),
+    /** Tenant ID associated with the API key */
+    tenantId: z.string().uuid(),
+    /** Current pricing tier */
+    tier: z.string().min(1),
+    /** Tier limits for client-side enforcement */
+    limits: SdkActivationLimitsSchema,
+    /** Activation token — opaque string, valid for `expiresInSeconds` */
+    activationToken: z.string().min(1),
+    /** Token validity in seconds (default: 3600 = 1 hour) */
+    expiresInSeconds: z.number().int().positive(),
+    /** ISO 8601 timestamp of activation */
+    activatedAt: z.string().datetime(),
+});
+/**
+ * Error response from the activation endpoint.
+ */
+export const SdkActivationErrorSchema = z.object({
+    activated: z.literal(false),
+    error: z.string(),
+    code: z.enum([
+        "INVALID_API_KEY",
+        "ACCOUNT_SUSPENDED",
+        "TIER_INSUFFICIENT",
+        "RATE_LIMITED",
+        "SERVICE_UNAVAILABLE",
+    ]),
+});
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,IAAI,CAAC;IACzC,aAAa;IACb,WAAW;IACX,aAAa;IACb,YAAY;IACZ,YAAY;IACZ,QAAQ;IACR,YAAY;IACZ,aAAa;IACb,UAAU;IACV,WAAW;IACX,oBAAoB;IACpB,sBAAsB;CACtB,CAAC,CAAC;AAIH;;GAEG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IAClD,4CAA4C;IAC5C,KAAK,EAAE,mBAAmB;IAC1B,yCAAyC;IACzC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;IACrC,qDAAqD;IACrD,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;CAC5C,CAAC,CAAC;AAIH;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,eAAe,EAAE,CAAC,CAAC,OAAO,EAAE;IAC5B,iBAAiB,EAAE,CAAC,CAAC,OAAO,EAAE;IAC9B,kBAAkB,EAAE,CAAC,CAAC,OAAO,EAAE;IAC/B,UAAU,EAAE,CAAC,CAAC,OAAO,EAAE;IACvB,YAAY,EAAE,CAAC,CAAC,OAAO,EAAE;CACzB,CAAC,CAAC;AAIH;;GAEG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IACnD,mCAAmC;IACnC,SAAS,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC;IAC1B,4CAA4C;IAC5C,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE;IAC3B,2BAA2B;IAC3B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,8CAA8C;IAC9C,MAAM,EAAE,yBAAyB;IACjC,qEAAqE;IACrE,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAClC,yDAAyD;IACzD,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IAC7C,uCAAuC;IACvC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAClC,CAAC,CAAC;AAIH;;GAEG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,SAAS,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;IAC3B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC;QACZ,iBAAiB;QACjB,mBAAmB;QACnB,mBAAmB;QACnB,cAAc;QACd,qBAAqB;KACrB,CAAC;CACF,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@qnsp/sdk-activation",
+  "version": "0.1.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "license": "Apache-2.0",
+  "description": "SDK activation and usage metering for QNSP platform SDKs. Ensures all SDK usage is tied to a registered QNSP account.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^6.0.2",
+    "vitest": "4.1.2"
+  },
+  "engines": {
+    "node": ">=24.12.0"
+  },
+  "keywords": [
+    "qnsp",
+    "sdk",
+    "activation",
+    "metering",
+    "pqc",
+    "post-quantum",
+    "post-quantum-cryptography",
+    "cryptography",
+    "api-key",
+    "free-tier",
+    "quantum-safe",
+    "typescript",
+    "nodejs"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cuilabs/qnsp",
+    "directory": "packages/sdk-activation"
+  },
+  "homepage": "https://cloud.qnsp.cuilabs.io",
+  "bugs": {
+    "url": "https://github.com/cuilabs/qnsp/issues"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "lint": "biome check .",
+    "test": "vitest run",
+    "typecheck": "tsc --project tsconfig.json --noEmit"
+  }
+}

package/src/activation-client.test.ts

@@ -0,0 +1,169 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import {
+	activateSdk,
+	clearActivationCache,
+	getActivationLimits,
+	getCachedActivation,
+	type SdkActivationConfig,
+	SdkActivationError_,
+} from "./activation-client.js";
+
+const BASE_CONFIG: SdkActivationConfig = {
+	apiKey: "qnsp_test_key_00000000",
+	sdkId: "vault-sdk",
+	sdkVersion: "0.3.0",
+	platformUrl: "https://api.qnsp.cuilabs.io",
+};
+
+describe("SdkActivationError_", () => {
+	it("creates error with correct properties", () => {
+		const err = new SdkActivationError_("INVALID_API_KEY", "bad key", 401);
+		expect(err.name).toBe("SdkActivationError");
+		expect(err.code).toBe("INVALID_API_KEY");
+		expect(err.message).toBe("bad key");
+		expect(err.statusCode).toBe(401);
+		expect(err).toBeInstanceOf(Error);
+	});
+});
+
+describe("activateSdk", () => {
+	beforeEach(() => {
+		clearActivationCache();
+	});
+
+	it("rejects empty API key", async () => {
+		await expect(activateSdk({ ...BASE_CONFIG, apiKey: "" })).rejects.toThrow(SdkActivationError_);
+
+		try {
+			await activateSdk({ ...BASE_CONFIG, apiKey: "   " });
+		} catch (err) {
+			expect(err).toBeInstanceOf(SdkActivationError_);
+			expect((err as SdkActivationError_).code).toBe("INVALID_API_KEY");
+			expect((err as SdkActivationError_).statusCode).toBe(401);
+		}
+	});
+
+	it("throws SERVICE_UNAVAILABLE on network failure", async () => {
+		const config: SdkActivationConfig = {
+			...BASE_CONFIG,
+			platformUrl: "https://localhost:1",
+			timeoutMs: 500,
+			fetchImpl: () => {
+				throw new Error("Connection refused");
+			},
+		};
+
+		await expect(activateSdk(config)).rejects.toThrow(SdkActivationError_);
+
+		try {
+			await activateSdk(config);
+		} catch (err) {
+			expect((err as SdkActivationError_).code).toBe("SERVICE_UNAVAILABLE");
+			expect((err as SdkActivationError_).statusCode).toBe(503);
+		}
+	});
+
+	it("throws on 401 response", async () => {
+		const config: SdkActivationConfig = {
+			...BASE_CONFIG,
+			fetchImpl: () => Promise.resolve(new Response(null, { status: 401 })),
+		};
+
+		try {
+			await activateSdk(config);
+		} catch (err) {
+			expect(err).toBeInstanceOf(SdkActivationError_);
+			expect((err as SdkActivationError_).code).toBe("INVALID_API_KEY");
+			expect((err as SdkActivationError_).statusCode).toBe(401);
+		}
+	});
+
+	it("parses 401 JSON error body and preserves api-keys guidance when present", async () => {
+		const config: SdkActivationConfig = {
+			...BASE_CONFIG,
+			fetchImpl: () =>
+				Promise.resolve(
+					new Response(
+						JSON.stringify({
+							activated: false,
+							code: "INVALID_API_KEY",
+							error: "Invalid API key. Get your key at https://cloud.qnsp.cuilabs.io/api-keys",
+						}),
+						{ status: 401, headers: { "content-type": "application/json" } },
+					),
+				),
+		};
+
+		try {
+			await activateSdk(config);
+		} catch (err) {
+			expect(err).toBeInstanceOf(SdkActivationError_);
+			expect((err as SdkActivationError_).message).toContain("cloud.qnsp.cuilabs.io/api-keys");
+		}
+	});
+
+	it("throws on 429 response", async () => {
+		const config: SdkActivationConfig = {
+			...BASE_CONFIG,
+			fetchImpl: () => Promise.resolve(new Response(null, { status: 429 })),
+		};
+
+		try {
+			await activateSdk(config);
+		} catch (err) {
+			expect(err).toBeInstanceOf(SdkActivationError_);
+			expect((err as SdkActivationError_).code).toBe("RATE_LIMITED");
+			expect((err as SdkActivationError_).statusCode).toBe(429);
+		}
+	});
+
+	it("caches successful activation and returns from cache", async () => {
+		const activationResponse = {
+			activated: true,
+			tenantId: "a1b2c3d4-e5f6-4789-8abc-def012345678",
+			tier: "dev-starter",
+			activationToken: "tok_test",
+			expiresInSeconds: 3600,
+			activatedAt: "2026-03-13T10:00:00Z",
+			limits: {
+				storageGB: 5,
+				apiCalls: 10_000,
+				enclavesEnabled: false,
+				aiTrainingEnabled: false,
+				aiInferenceEnabled: false,
+				sseEnabled: false,
+				vaultEnabled: true,
+			},
+		};
+
+		const config: SdkActivationConfig = {
+			...BASE_CONFIG,
+			fetchImpl: () =>
+				Promise.resolve(
+					new Response(JSON.stringify(activationResponse), {
+						status: 200,
+						headers: { "content-type": "application/json" },
+					}),
+				),
+		};
+
+		const result = await activateSdk(config);
+		expect(result.activated).toBe(true);
+		expect(result.tier).toBe("dev-starter");
+		expect(result.limits.apiCalls).toBe(10_000);
+
+		// Should return from cache
+		const cached = getCachedActivation(config);
+		expect(cached).not.toBeNull();
+		expect(cached?.tenantId).toBe("a1b2c3d4-e5f6-4789-8abc-def012345678");
+
+		const limits = getActivationLimits(config);
+		expect(limits).not.toBeNull();
+		expect(limits?.storageGB).toBe(5);
+	});
+
+	it("returns null for uncached activation", () => {
+		expect(getCachedActivation(BASE_CONFIG)).toBeNull();
+		expect(getActivationLimits(BASE_CONFIG)).toBeNull();
+	});
+});

package/src/activation-client.ts

@@ -0,0 +1,243 @@
+/**
+ * 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,
+	SdkActivationErrorSchema,
+	type SdkActivationLimits,
+	type SdkActivationRequest,
+	type SdkActivationResponse,
+	SdkActivationResponseSchema,
+	type SdkIdentifier,
+} 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 {
+	readonly code: SdkActivationError["code"];
+	readonly statusCode: number;
+
+	constructor(code: SdkActivationError["code"], message: string, statusCode: number) {
+		super(message);
+		this.name = "SdkActivationError";
+		this.code = code;
+		this.statusCode = statusCode;
+	}
+}
+
+/**
+ * Cached activation state.
+ */
+interface ActivationState {
+	readonly response: SdkActivationResponse;
+	readonly expiresAt: number; // Unix timestamp in ms
+}
+
+/**
+ * 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;
+}
+
+/** In-memory activation cache keyed by `${platformUrl}:${apiKeyPrefix}:${sdkId}` */
+const activationCache = new Map<string, ActivationState>();
+
+function cacheKey(config: SdkActivationConfig): string {
+	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(): "browser" | "node" | "edge" {
+	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: SdkActivationConfig): Promise<SdkActivationResponse> {
+	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: SdkActivationRequest = {
+		sdkId: config.sdkId,
+		sdkVersion: config.sdkVersion,
+		runtime: detectRuntime(),
+	};
+
+	let response: 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: SdkActivationError | undefined;
+		try {
+			const json: unknown = 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: unknown = 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: SdkActivationConfig): SdkActivationResponse | null {
+	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: SdkActivationConfig): SdkActivationLimits | null {
+	const activation = getCachedActivation(config);
+	return activation?.limits ?? null;
+}
+
+/**
+ * Clear all cached activations. Primarily for testing.
+ */
+export function clearActivationCache(): void {
+	activationCache.clear();
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+/**
+ * @qnsp/sdk-activation
+ *
+ * SDK activation and usage metering for QNSP platform SDKs.
+ * Ensures all SDK usage is tied to a registered QNSP account.
+ *
+ * Browser-compatible — no node: imports.
+ *
+ * @module
+ */
+
+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";

package/src/types.ts

@@ -0,0 +1,99 @@
+/**
+ * SDK Activation Types
+ *
+ * Shared contract between SDK clients and the billing-service activation endpoint.
+ * Browser-compatible — no node: imports.
+ *
+ * @module
+ */
+
+import { z } from "zod";
+
+/**
+ * SDK identifier sent during activation to identify which package is being used.
+ */
+export const SdkIdentifierSchema = z.enum([
+	"browser-sdk",
+	"vault-sdk",
+	"storage-sdk",
+	"search-sdk",
+	"kms-client",
+	"ai-sdk",
+	"tenant-sdk",
+	"billing-sdk",
+	"auth-sdk",
+	"audit-sdk",
+	"access-control-sdk",
+	"crypto-inventory-sdk",
+]);
+
+export type SdkIdentifier = z.infer<typeof SdkIdentifierSchema>;
+
+/**
+ * Request body for POST /billing/v1/sdk/activate
+ */
+export const SdkActivationRequestSchema = z.object({
+	/** The SDK package requesting activation */
+	sdkId: SdkIdentifierSchema,
+	/** SDK version string (e.g., "0.1.0") */
+	sdkVersion: z.string().min(1).max(32),
+	/** Runtime environment: "browser", "node", "edge" */
+	runtime: z.enum(["browser", "node", "edge"]),
+});
+
+export type SdkActivationRequest = z.infer<typeof SdkActivationRequestSchema>;
+
+/**
+ * Tier limits returned in the activation response.
+ * Subset of full TierLimits — only what SDKs need for client-side enforcement.
+ */
+export const SdkActivationLimitsSchema = z.object({
+	storageGB: z.number(),
+	apiCalls: z.number(),
+	enclavesEnabled: z.boolean(),
+	aiTrainingEnabled: z.boolean(),
+	aiInferenceEnabled: z.boolean(),
+	sseEnabled: z.boolean(),
+	vaultEnabled: z.boolean(),
+});
+
+export type SdkActivationLimits = z.infer<typeof SdkActivationLimitsSchema>;
+
+/**
+ * Successful activation response from billing-service.
+ */
+export const SdkActivationResponseSchema = z.object({
+	/** Whether activation succeeded */
+	activated: z.literal(true),
+	/** Tenant ID associated with the API key */
+	tenantId: z.string().uuid(),
+	/** Current pricing tier */
+	tier: z.string().min(1),
+	/** Tier limits for client-side enforcement */
+	limits: SdkActivationLimitsSchema,
+	/** Activation token — opaque string, valid for `expiresInSeconds` */
+	activationToken: z.string().min(1),
+	/** Token validity in seconds (default: 3600 = 1 hour) */
+	expiresInSeconds: z.number().int().positive(),
+	/** ISO 8601 timestamp of activation */
+	activatedAt: z.string().datetime(),
+});
+
+export type SdkActivationResponse = z.infer<typeof SdkActivationResponseSchema>;
+
+/**
+ * Error response from the activation endpoint.
+ */
+export const SdkActivationErrorSchema = z.object({
+	activated: z.literal(false),
+	error: z.string(),
+	code: z.enum([
+		"INVALID_API_KEY",
+		"ACCOUNT_SUSPENDED",
+		"TIER_INSUFFICIENT",
+		"RATE_LIMITED",
+		"SERVICE_UNAVAILABLE",
+	]),
+});
+
+export type SdkActivationError = z.infer<typeof SdkActivationErrorSchema>;

package/tsconfig.build.json

@@ -0,0 +1,11 @@
+{
+	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		"ignoreDeprecations": "6.0",
+		"declaration": true,
+		"declarationMap": true,
+		"sourceMap": true
+	},
+	"include": ["src/**/*"],
+	"exclude": ["node_modules", "dist", "**/*.test.ts"]
+}