added client lib

Author: abdullahwaqar

README.md

@@ -24,6 +24,55 @@ Designed for simplicity, privacy, and host control, AuthCell runs as a single co
 
 ---
 
+## Client Libraries
+
+AuthCell includes lightweight client libraries to simplify integration into your existing applications.
+Clients automatically deduce the server URL using the `AUTHCELL_URL` environment variable or fallback to `http://localhost:8080/v1`.
+
+---
+
+### Node.js / TypeScript Client
+
+**File:** `client/nodejs/index.ts`
+**Dependencies:** None (uses native `fetch`, Node.js v18+ required)
+
+**Example Use**
+
+```typescript
+import { AuthCellClient } from "./client/nodejs/index";
+
+const client = new AuthCellClient(); // will use AUTHCELL_URL or localhost
+
+async function main() {
+  const created = await client.createKey({ key_prefix: "demo_" });
+  console.log("Created key:", created.api_key);
+
+  const verified = await client.verifyKey(created.api_key);
+  console.log("Verification:", verified.valid);
+}
+
+main();
+```
+
+---
+
+### Planned Client SDKs
+
+| Language               | Status                        | Description                                       |
+| ---------------------- | ----------------------------- | ------------------------------------------------- |
+| **Node.js/TypeScript** | ✅ In repo (`client/nodejs/`) | Native fetch API, zero dependencies               |
+| **Python**             | Planned                       | HTTPx/Requests wrapper with auto server detection |
+
+---
+
+### Example ENV Configuration for Clients
+
+```bash
+export AUTHCELL_URL="https://authcell.mydomain.com/v1"
+```
+
+The client will automatically resolve this; no manual configuration required.
+
 ## API Endpoints
 
 API Documentation: [View in Postman Documenter](https://documenter.getpostman.com/view/28328727/2sB3QQJnT4#be11f7c6-14f0-4a50-9d05-a726046306fa)

client/nodejs/index.ts

@@ -0,0 +1,68 @@
+export interface APIKeyCreateResponse {
+	api_key: string;
+	id: string;
+	key_id: string;
+}
+
+export interface APIKeyVerifyResponse {
+	valid: boolean;
+}
+
+export class AuthCellClient {
+	private baseUrl: string;
+
+	constructor(baseUrl?: string) {
+		this.baseUrl =
+			baseUrl || process.env.AUTHCELL_URL || "http://localhost:8080/v1";
+	}
+
+	private async __request<T>(
+		path: string,
+		method: string,
+		body?: unknown,
+	): Promise<T> {
+		const headers = { "Content-Type": "application/json" };
+		const url = `${this.baseUrl}${path}`;
+		const res = await fetch(url, {
+			method,
+			headers,
+			body: body ? JSON.stringify(body) : undefined,
+		});
+		if (!res.ok) {
+			const err = await res.text();
+			throw new Error(`HTTP ${res.status}: ${err}`);
+		}
+		const data = await res.json();
+		return data.data as T;
+	}
+
+	async createKey(opts: {
+		key_prefix: string;
+		expires_at?: string;
+		rate_limit?: number;
+	}): Promise<APIKeyCreateResponse> {
+		return this.__request<APIKeyCreateResponse>("/keys", "POST", opts);
+	}
+
+	async verifyKey(api_key: string): Promise<APIKeyVerifyResponse> {
+		return this.__request<APIKeyVerifyResponse>("/keys/verify", "POST", {
+			api_key,
+		});
+	}
+
+	async getKey(id: string) {
+		return this.__request(`/keys/${id}`, "GET");
+	}
+
+	async revokeKey(id: string) {
+		return this.__request(`/keys/${id}`, "DELETE");
+	}
+
+	async listUsage(id: string) {
+		return this.__request(`/usage/${id}`, "GET");
+	}
+
+	async listAuditLog() {
+		return this.__request("/audit", "GET");
+	}
+}