@qnsp/storage-sdk 0.0.1

package/src/index.ts

@@ -0,0 +1,664 @@
+import { performance } from "node:perf_hooks";
+
+import type {
+	StorageClientTelemetry,
+	StorageClientTelemetryConfig,
+	StorageClientTelemetryEvent,
+} from "./observability.js";
+import { createStorageClientTelemetry, isStorageClientTelemetry } from "./observability.js";
+
+/**
+ * @qnsp/storage-sdk
+ *
+ * TypeScript SDK client for the QNSP storage-service API.
+ * Provides a high-level interface for document upload, download, and management operations.
+ */
+
+export interface StorageClientConfig {
+	readonly baseUrl: string;
+	readonly apiKey?: string;
+	readonly tenantId: string;
+	readonly timeoutMs?: number;
+	readonly telemetry?: StorageClientTelemetry | StorageClientTelemetryConfig;
+}
+
+type InternalStorageClientConfig = {
+	readonly baseUrl: string;
+	readonly apiKey: string;
+	readonly tenantId: string;
+	readonly timeoutMs: number;
+};
+
+export interface InitiateUploadOptions {
+	readonly name: string;
+	readonly mimeType: string;
+	readonly sizeBytes: number;
+	readonly classification?: string;
+	readonly metadata?: Record<string, unknown>;
+	readonly tags?: readonly string[];
+	readonly retentionPolicy?: {
+		readonly mode?: "compliance" | "governance" | null;
+		readonly retainUntil?: string | null;
+		readonly legalHolds?: readonly string[];
+	};
+}
+
+export interface UploadPartResult {
+	readonly uploadId: string;
+	readonly partId: number;
+	readonly status: string;
+	readonly sizeBytes: number;
+	readonly checksumSha3: string;
+	readonly retries: number;
+	readonly totalParts: number;
+	readonly completedParts: number;
+	readonly bytesReceived: number;
+	readonly lastPartNumber: number;
+	readonly resumeToken: string | null;
+	readonly scan?: {
+		readonly status: string;
+		readonly signature: string | null;
+		readonly engine: string | null;
+	};
+}
+
+export interface CompleteUploadResult {
+	readonly documentId: string;
+	readonly tenantId: string;
+	readonly version: number;
+	readonly sizeBytes: number;
+	readonly checksumSha3: string;
+	readonly parts: readonly {
+		readonly partId: number;
+		readonly checksumSha3: string;
+		readonly sizeBytes: number;
+	}[];
+	readonly downloadManifest: unknown;
+	readonly cdnDownload?: {
+		readonly url: string;
+		readonly expiresAt: string;
+		readonly token: string;
+	} | null;
+}
+
+export interface DownloadDescriptor {
+	readonly documentId: string;
+	readonly tenantId: string;
+	readonly version: number;
+	readonly sizeBytes: number;
+	readonly checksumSha3: string;
+	readonly manifest: unknown;
+}
+
+export interface UploadStatus {
+	readonly uploadId: string;
+	readonly documentId: string;
+	readonly tenantId: string;
+	readonly status: "pending" | "committed" | "aborted" | "quarantined";
+	readonly totalParts: number;
+	readonly completedParts: number;
+	readonly bytesReceived: number;
+	readonly lastPartNumber: number;
+	readonly chunkSizeBytes: number;
+	readonly totalSizeBytes: number;
+	readonly expiresAt: string;
+	readonly resumeToken: string | null;
+	readonly createdAt: string;
+	readonly updatedAt: string;
+}
+
+export interface DocumentPolicies {
+	readonly documentId: string;
+	readonly tenantId: string;
+	readonly compliance: {
+		readonly retentionMode: "compliance" | "governance" | null;
+		readonly retainUntil: string | null;
+		readonly legalHolds: readonly string[];
+		readonly wormLockExpiresAt: string | null;
+	};
+	readonly lifecycle?: {
+		readonly currentTier?: "hot" | "warm" | "cold" | "frozen";
+		readonly targetTier?: "hot" | "warm" | "cold" | "frozen" | null;
+		readonly transitionAfter?: string | null;
+	};
+}
+
+export interface UpdatePoliciesRequest {
+	readonly retentionMode?: "compliance" | "governance";
+	readonly retainUntil?: string;
+	readonly legalHolds?: readonly string[];
+	readonly wormLockExpiresAt?: string;
+}
+
+export interface ApplyLegalHoldRequest {
+	readonly holdId: string;
+}
+
+export interface ScheduleTransitionRequest {
+	readonly targetTier: "hot" | "warm" | "cold" | "frozen";
+	readonly transitionAfter: string;
+}
+
+interface RequestOptions {
+	readonly body?: unknown;
+	readonly headers?: Record<string, string>;
+	readonly signal?: AbortSignal;
+	readonly operation?: string;
+	readonly telemetryRoute?: string;
+	readonly telemetryTarget?: string;
+}
+
+export class StorageClient {
+	private readonly config: InternalStorageClientConfig;
+	private readonly telemetry: StorageClientTelemetry | null;
+	private readonly targetService: string;
+
+	constructor(config: StorageClientConfig) {
+		this.config = {
+			baseUrl: config.baseUrl.replace(/\/$/, ""),
+			apiKey: config.apiKey ?? "",
+			tenantId: config.tenantId,
+			timeoutMs: config.timeoutMs ?? 30_000,
+		};
+
+		this.telemetry = config.telemetry
+			? isStorageClientTelemetry(config.telemetry)
+				? config.telemetry
+				: createStorageClientTelemetry(config.telemetry)
+			: null;
+
+		try {
+			this.targetService = new URL(this.config.baseUrl).host;
+		} catch {
+			this.targetService = "storage-service";
+		}
+	}
+
+	private async request<T>(method: string, path: string, options?: RequestOptions): Promise<T> {
+		const url = `${this.config.baseUrl}${path}`;
+		const headers: Record<string, string> = {
+			"Content-Type": "application/json",
+			...options?.headers,
+		};
+
+		if (this.config.apiKey) {
+			headers["Authorization"] = `Bearer ${this.config.apiKey}`;
+		}
+
+		const controller = new AbortController();
+		const timeoutId = setTimeout(() => controller.abort(), this.config.timeoutMs);
+		const signal = options?.signal ?? controller.signal;
+		const route = options?.telemetryRoute ?? new URL(path, this.config.baseUrl).pathname;
+		const target = options?.telemetryTarget ?? this.targetService;
+		const start = performance.now();
+		let status: "ok" | "error" = "ok";
+		let httpStatus: number | undefined;
+		let errorMessage: string | undefined;
+
+		try {
+			const init: RequestInit = {
+				method,
+				headers,
+				signal,
+			};
+
+			if (options?.body !== undefined) {
+				init.body = JSON.stringify(options.body);
+			}
+
+			const response = await fetch(url, init);
+
+			clearTimeout(timeoutId);
+			httpStatus = response.status;
+
+			if (!response.ok) {
+				status = "error";
+				const errorText = await response.text().catch(() => "Unknown error");
+				errorMessage = errorText;
+				throw new Error(
+					`Storage API error: ${response.status} ${response.statusText} - ${errorText}`,
+				);
+			}
+
+			if (response.status === 204) {
+				return undefined as T;
+			}
+
+			return (await response.json()) as T;
+		} catch (error) {
+			clearTimeout(timeoutId);
+			status = "error";
+			if (!errorMessage && error instanceof Error) {
+				errorMessage = error.message;
+			}
+			if (error instanceof Error && error.name === "AbortError") {
+				errorMessage = `timeout after ${this.config.timeoutMs}ms`;
+				throw new Error(`Request timeout after ${this.config.timeoutMs}ms`);
+			}
+			throw error;
+		} finally {
+			const durationMs = performance.now() - start;
+			const event: StorageClientTelemetryEvent = {
+				operation: options?.operation ?? `${method} ${route}`,
+				method,
+				route,
+				target,
+				status,
+				durationMs,
+				...(typeof httpStatus === "number" ? { httpStatus } : {}),
+				...(status === "error" && errorMessage ? { error: errorMessage } : {}),
+			};
+			this.recordTelemetryEvent(event);
+		}
+	}
+
+	async initiateUpload(options: InitiateUploadOptions): Promise<{
+		readonly uploadId: string;
+		readonly documentId: string;
+		readonly tenantId: string;
+		readonly chunkSizeBytes: number;
+		readonly totalSizeBytes: number;
+		readonly totalParts: number;
+		readonly expiresAt: string;
+		readonly resumeToken: string | null;
+		readonly pqc: {
+			readonly provider: string;
+			readonly algorithm: string;
+			readonly keyId: string;
+		};
+	}> {
+		return this.request("POST", "/storage/v1/documents", {
+			body: {
+				name: options.name,
+				mimeType: options.mimeType,
+				sizeBytes: options.sizeBytes,
+				classification: options.classification ?? "confidential",
+				metadata: options.metadata ?? {},
+				tags: options.tags ?? [],
+				retentionPolicy: options.retentionPolicy,
+			},
+			operation: "initiateUpload",
+		});
+	}
+
+	async uploadPart(
+		uploadId: string,
+		partId: number,
+		data: ReadableStream<Uint8Array> | Buffer | Uint8Array,
+	): Promise<UploadPartResult> {
+		const url = `${this.config.baseUrl}/storage/v1/uploads/${uploadId}/parts/${partId}`;
+		const headers: Record<string, string> = {
+			"Content-Type": "application/octet-stream",
+		};
+
+		if (this.config.apiKey) {
+			headers["Authorization"] = `Bearer ${this.config.apiKey}`;
+		}
+
+		const bytesSent =
+			data instanceof Buffer || data instanceof Uint8Array ? data.byteLength : undefined;
+		const route = "/storage/v1/uploads/:uploadId/parts/:partId";
+		const start = performance.now();
+		let status: "ok" | "error" = "ok";
+		let httpStatus: number | undefined;
+		let errorMessage: string | undefined;
+
+		const body =
+			data instanceof ReadableStream
+				? data
+				: data instanceof Buffer
+					? new ReadableStream({
+							start(controller) {
+								controller.enqueue(new Uint8Array(data));
+								controller.close();
+							},
+						})
+					: new ReadableStream({
+							start(controller) {
+								controller.enqueue(data);
+								controller.close();
+							},
+						});
+
+		const controller = new AbortController();
+		const timeoutId = setTimeout(() => controller.abort(), this.config.timeoutMs);
+
+		try {
+			const response = await fetch(url, {
+				method: "PUT",
+				headers,
+				body,
+				signal: controller.signal,
+			});
+
+			clearTimeout(timeoutId);
+			httpStatus = response.status;
+
+			if (!response.ok) {
+				status = "error";
+				const errorText = await response.text().catch(() => "Unknown error");
+				errorMessage = errorText;
+				throw new Error(
+					`Upload part error: ${response.status} ${response.statusText} - ${errorText}`,
+				);
+			}
+
+			return (await response.json()) as UploadPartResult;
+		} catch (error) {
+			clearTimeout(timeoutId);
+			status = "error";
+			if (!errorMessage && error instanceof Error) {
+				errorMessage = error.message;
+			}
+			if (error instanceof Error && error.name === "AbortError") {
+				errorMessage = `timeout after ${this.config.timeoutMs}ms`;
+				throw new Error(`Request timeout after ${this.config.timeoutMs}ms`);
+			}
+			throw error;
+		} finally {
+			const durationMs = performance.now() - start;
+			const event: StorageClientTelemetryEvent = {
+				operation: "uploadPart",
+				method: "PUT",
+				route,
+				target: this.targetService,
+				status,
+				durationMs,
+				...(typeof httpStatus === "number" ? { httpStatus } : {}),
+				...(status === "error" && errorMessage ? { error: errorMessage } : {}),
+				...(typeof bytesSent === "number" ? { bytesSent } : {}),
+			};
+			this.recordTelemetryEvent(event);
+		}
+	}
+
+	async getUploadStatus(uploadId: string): Promise<UploadStatus> {
+		// Use GET since we need the full status object
+		return this.request<UploadStatus>("GET", `/storage/v1/uploads/${uploadId}`, {
+			operation: "getUploadStatus",
+			telemetryRoute: "/storage/v1/uploads/:uploadId",
+		});
+	}
+
+	async completeUpload(uploadId: string): Promise<CompleteUploadResult> {
+		return this.request("POST", `/storage/v1/uploads/${uploadId}/complete`, {
+			operation: "completeUpload",
+			telemetryRoute: "/storage/v1/uploads/:uploadId/complete",
+		});
+	}
+
+	async getDownloadDescriptor(
+		documentId: string,
+		version: number,
+		options?: {
+			readonly token?: string | null;
+			readonly expiresAt?: number | null;
+			readonly signature?: string | null;
+		},
+	): Promise<DownloadDescriptor> {
+		const params = new URLSearchParams({
+			tenantId: this.config.tenantId,
+		});
+
+		if (options?.token) {
+			params.set("token", options.token);
+		}
+		if (options?.expiresAt) {
+			params.set("expiresAt", String(options.expiresAt));
+		}
+		if (options?.signature) {
+			params.set("signature", options.signature);
+		}
+
+		return this.request(
+			"GET",
+			`/storage/v1/documents/${documentId}/versions/${version}/download?${params}`,
+			{
+				operation: "getDownloadDescriptor",
+				telemetryRoute: "/storage/v1/documents/:documentId/versions/:version/download",
+			},
+		);
+	}
+
+	async downloadStream(
+		documentId: string,
+		version: number,
+		options?: {
+			readonly token?: string | null;
+			readonly expiresAt?: number | null;
+			readonly signature?: string | null;
+			readonly range?: string | null;
+		},
+	): Promise<{
+		readonly stream: ReadableStream<Uint8Array>;
+		readonly statusCode: 200 | 206;
+		readonly totalSize: number;
+		readonly contentLength: number;
+		readonly range?: { readonly start: number; readonly end: number };
+		readonly checksumSha3: string;
+	}> {
+		const params = new URLSearchParams({
+			tenantId: this.config.tenantId,
+		});
+
+		if (options?.token) {
+			params.set("token", options.token);
+		}
+		if (options?.expiresAt) {
+			params.set("expiresAt", String(options.expiresAt));
+		}
+		if (options?.signature) {
+			params.set("signature", options.signature);
+		}
+		if (options?.range) {
+			params.set("range", options.range);
+		}
+
+		const url = `${this.config.baseUrl}/storage/v1/documents/${documentId}/versions/${version}/content?${params}`;
+		const headers: Record<string, string> = {};
+
+		if (options?.range) {
+			headers["Range"] = options.range;
+		}
+
+		if (this.config.apiKey) {
+			headers["Authorization"] = `Bearer ${this.config.apiKey}`;
+		}
+
+		const controller = new AbortController();
+		const timeoutId = setTimeout(() => controller.abort(), this.config.timeoutMs);
+		const route = "/storage/v1/documents/:documentId/versions/:version/content";
+		const start = performance.now();
+		let status: "ok" | "error" = "ok";
+		let httpStatus: number | undefined;
+		let errorMessage: string | undefined;
+		let bytesReceived: number | undefined;
+
+		try {
+			const response = await fetch(url, {
+				method: "GET",
+				headers,
+				signal: controller.signal,
+			});
+
+			clearTimeout(timeoutId);
+			httpStatus = response.status;
+
+			if (!response.ok) {
+				status = "error";
+				const errorText = await response.text().catch(() => "Unknown error");
+				errorMessage = errorText;
+				throw new Error(`Download error: ${response.status} ${response.statusText} - ${errorText}`);
+			}
+
+			const contentRange = response.headers.get("Content-Range");
+			const rangeMatch = contentRange?.startsWith("bytes ")
+				? contentRange.match(/bytes (\d+)-(\d+)\/(\d+)/)
+				: null;
+
+			const parsedRange =
+				rangeMatch?.[1] && rangeMatch[2]
+					? {
+							start: Number.parseInt(rangeMatch[1], 10),
+							end: Number.parseInt(rangeMatch[2], 10),
+						}
+					: undefined;
+
+			const totalSize = rangeMatch?.[3]
+				? Number.parseInt(rangeMatch[3], 10)
+				: Number.parseInt(response.headers.get("X-Total-Size") ?? "0", 10);
+			const contentLength = Number.parseInt(response.headers.get("Content-Length") ?? "0", 10);
+			const checksumSha3 = response.headers.get("X-Checksum-Sha3") ?? "";
+
+			const stream =
+				response.body ??
+				new ReadableStream<Uint8Array>({
+					start(controller) {
+						controller.close();
+					},
+				});
+
+			bytesReceived = contentLength > 0 ? contentLength : totalSize > 0 ? totalSize : undefined;
+
+			const statusCode = (response.status === 206 ? 206 : 200) as 200 | 206;
+
+			return {
+				stream,
+				statusCode,
+				totalSize: totalSize > 0 ? totalSize : contentLength,
+				contentLength: contentLength > 0 ? contentLength : totalSize,
+				checksumSha3,
+				...(parsedRange ? { range: parsedRange } : {}),
+			};
+		} catch (error) {
+			clearTimeout(timeoutId);
+			status = "error";
+			if (!errorMessage && error instanceof Error) {
+				errorMessage = error.message;
+			}
+			if (error instanceof Error && error.name === "AbortError") {
+				errorMessage = `timeout after ${this.config.timeoutMs}ms`;
+				throw new Error(`Request timeout after ${this.config.timeoutMs}ms`);
+			}
+			throw error;
+		} finally {
+			const durationMs = performance.now() - start;
+			const event: StorageClientTelemetryEvent = {
+				operation: "downloadStream",
+				method: "GET",
+				route,
+				target: this.targetService,
+				status,
+				durationMs,
+				...(typeof httpStatus === "number" ? { httpStatus } : {}),
+				...(status === "error" && errorMessage ? { error: errorMessage } : {}),
+				...(typeof bytesReceived === "number" ? { bytesReceived } : {}),
+			};
+			this.recordTelemetryEvent(event);
+		}
+	}
+
+	/**
+	 * Retrieve document policies (compliance + lifecycle summary).
+	 * Requires x-tenant-id header.
+	 */
+	async getDocumentPolicies(documentId: string): Promise<DocumentPolicies> {
+		return this.request("GET", `/storage/v1/documents/${documentId}/policies`, {
+			operation: "getDocumentPolicies",
+			telemetryRoute: "/storage/v1/documents/:documentId/policies",
+			headers: {
+				"x-tenant-id": this.config.tenantId,
+			},
+		});
+	}
+
+	/**
+	 * Update document retention/WORM/legal hold list atomically.
+	 * Requires x-tenant-id header.
+	 */
+	async updateDocumentPolicies(
+		documentId: string,
+		input: UpdatePoliciesRequest,
+	): Promise<DocumentPolicies> {
+		return this.request("PATCH", `/storage/v1/documents/${documentId}/policies`, {
+			body: input,
+			operation: "updateDocumentPolicies",
+			telemetryRoute: "/storage/v1/documents/:documentId/policies",
+			headers: {
+				"x-tenant-id": this.config.tenantId,
+			},
+		});
+	}
+
+	/**
+	 * Apply a legal hold by id. Hold ids are caller-defined.
+	 * Requires x-tenant-id header.
+	 */
+	async applyLegalHold(
+		documentId: string,
+		request: ApplyLegalHoldRequest,
+	): Promise<{
+		readonly documentId: string;
+		readonly tenantId: string;
+		readonly legalHolds: readonly string[];
+	}> {
+		return this.request("POST", `/storage/v1/documents/${documentId}/legal-holds`, {
+			body: request,
+			operation: "applyLegalHold",
+			telemetryRoute: "/storage/v1/documents/:documentId/legal-holds",
+			headers: {
+				"x-tenant-id": this.config.tenantId,
+			},
+		});
+	}
+
+	/**
+	 * Release a legal hold by id.
+	 * Requires x-tenant-id header.
+	 */
+	async releaseLegalHold(documentId: string, holdId: string): Promise<void> {
+		return this.request("DELETE", `/storage/v1/documents/${documentId}/legal-holds/${holdId}`, {
+			operation: "releaseLegalHold",
+			telemetryRoute: "/storage/v1/documents/:documentId/legal-holds/:holdId",
+			headers: {
+				"x-tenant-id": this.config.tenantId,
+			},
+		});
+	}
+
+	/**
+	 * Schedule a lifecycle tier transition for a document.
+	 * Requires x-tenant-id header.
+	 */
+	async scheduleLifecycleTransition(
+		documentId: string,
+		request: ScheduleTransitionRequest,
+	): Promise<{
+		readonly documentId: string;
+		readonly tenantId: string;
+		readonly lifecycle: {
+			readonly currentTier?: "hot" | "warm" | "cold" | "frozen";
+			readonly targetTier?: "hot" | "warm" | "cold" | "frozen" | null;
+			readonly transitionAfter?: string | null;
+		};
+	}> {
+		return this.request("POST", `/storage/v1/documents/${documentId}/lifecycle/transitions`, {
+			body: request,
+			operation: "scheduleLifecycleTransition",
+			telemetryRoute: "/storage/v1/documents/:documentId/lifecycle/transitions",
+			headers: {
+				"x-tenant-id": this.config.tenantId,
+			},
+		});
+	}
+
+	private recordTelemetryEvent(event: StorageClientTelemetryEvent): void {
+		if (!this.telemetry) {
+			return;
+		}
+		this.telemetry.record(event);
+	}
+}
+
+export * from "./events.js";
+export * from "./observability.js";