lazypock 0.1.0

package/src/http.ts

@@ -0,0 +1,195 @@
+// ── HTTP Client ─────────────────────────────────────────
+// Only relies on globalThis.fetch — works in browser, React Native, and Node 18+
+
+import { ApiError, type Method, type RequestOptions } from "./types";
+import type { AuthStore } from "./auth";
+
+/**
+ * Low-level HTTP client wrapping `fetch` with automatic auth token injection.
+ * Only relies on `globalThis.fetch` — works in browser, React Native, and Node 18+.
+ */
+export class HttpClient {
+	private baseUrl: string;
+	private authStore: AuthStore;
+	private defaultFetch: typeof globalThis.fetch;
+
+	/**
+	 * @param baseUrl The API base URL (e.g. `http://localhost:4000/api`). Trailing slash stripped.
+	 * @param authStore The auth store providing the token for Authorization headers.
+	 */
+	constructor(baseUrl: string, authStore: AuthStore) {
+		this.baseUrl = baseUrl.replace(/\/+$/, "");
+		this.authStore = authStore;
+		this.defaultFetch = globalThis.fetch.bind(globalThis);
+	}
+
+	private async refreshAuth(): Promise<{
+		token: string;
+		record: Record<string, unknown>;
+	} | null> {
+		const collection = this.authStore.collectionName;
+		if (!collection) return null;
+		try {
+			const url =
+				this.baseUrl + "/" + encodeURIComponent(collection) + "/auth-refresh";
+			const headers: Record<string, string> = {
+				"Content-Type": "application/json",
+			};
+			if (this.authStore.token) {
+				headers["Authorization"] = "Bearer " + this.authStore.token;
+			}
+			const res = await this.defaultFetch(url, {
+				method: "POST",
+				headers,
+			});
+			if (!res.ok) {
+				this.authStore.clear();
+				return null;
+			}
+			const data = (await res.json()) as Record<string, unknown>;
+			if (data && typeof data.token === "string") {
+				this.authStore.set(
+					data.token,
+					(data.record as Record<string, unknown> as any) ?? null,
+				);
+				return data as { token: string; record: Record<string, unknown> };
+			}
+			return null;
+		} catch {
+			return null;
+		}
+	}
+
+	/**
+	 * Make an HTTP request with automatic auth token injection and optional auto-refresh.
+	 *
+	 * @param method HTTP method.
+	 * @param path URL path (appended to baseUrl).
+	 * @param body JSON-serializable body, or FormData for file uploads.
+	 * @param options Optional request options.
+	 * @returns Parsed JSON response, or null for 204 No Content.
+	 * @throws {ApiError} On non-2xx responses.
+	 */
+	async request<T = unknown>(
+		method: Method,
+		path: string,
+		body?: unknown,
+		options?: RequestOptions,
+	): Promise<T | null> {
+		// Auto-refresh if token is expired
+		if (this.authStore.isExpired && this.authStore.collectionName) {
+			await this.refreshAuth();
+		}
+
+		let url = this.baseUrl + path;
+		if (options?.params) {
+			const qs = new URLSearchParams(options.params).toString();
+			if (qs) {
+				url += (path.includes("?") ? "&" : "?") + qs;
+			}
+		}
+		const headers: Record<string, string> = {
+			...options?.headers,
+		};
+
+		// Don't set Content-Type for FormData (browser sets multipart boundary)
+		if (!(body instanceof FormData)) {
+			headers["Content-Type"] = "application/json";
+		}
+
+		if (this.authStore.token) {
+			headers["Authorization"] = "Bearer " + this.authStore.token;
+		}
+
+		const init: RequestInit = {
+			method,
+			headers,
+			signal: options?.signal,
+		};
+
+		if (body != null && method !== "GET" && method !== "DELETE") {
+			if (body instanceof FormData) {
+				init.body = body;
+			} else {
+				init.body = JSON.stringify(body);
+			}
+		}
+
+		const fetcher = options?.fetch ?? this.defaultFetch;
+		const res = await fetcher(url, init);
+
+		if (res.status === 204) return null;
+
+		// Safely parse JSON — some errored responses may have empty or non-JSON bodies
+		let bodyText = "";
+		let data: Record<string, unknown> = {};
+		try {
+			bodyText = await res.text();
+			if (bodyText) {
+				data = JSON.parse(bodyText) as Record<string, unknown>;
+			}
+		} catch {
+			// Not JSON — keep data as empty object
+		}
+
+		if (!res.ok) {
+			throw new ApiError(
+				(typeof data.message === "string" ? data.message : res.statusText) ||
+					`Request failed with status ${res.status}`,
+				data,
+				res.status,
+			);
+		}
+
+		return data as T;
+	}
+
+	/**
+	 * HTTP GET.
+	 * @param path URL path.
+	 * @param options Optional request options.
+	 */
+	get<T = unknown>(path: string, options?: RequestOptions): Promise<T | null> {
+		return this.request<T>("GET", path, undefined, options);
+	}
+
+	/**
+	 * HTTP POST.
+	 * @param path URL path.
+	 * @param body Optional request body.
+	 * @param options Optional request options.
+	 */
+	post<T = unknown>(
+		path: string,
+		body?: unknown,
+		options?: RequestOptions,
+	): Promise<T | null> {
+		return this.request<T>("POST", path, body, options);
+	}
+
+	/**
+	 * HTTP PATCH.
+	 * @param path URL path.
+	 * @param body Optional request body.
+	 * @param options Optional request options.
+	 */
+	patch<T = unknown>(
+		path: string,
+		body?: unknown,
+		options?: RequestOptions,
+	): Promise<T | null> {
+		return this.request<T>("PATCH", path, body, options);
+	}
+
+	/**
+	 * HTTP DELETE.
+	 * @param path URL path.
+	 * @param options Optional request options.
+	 */
+	delete<T = unknown>(
+		path: string,
+		options?: RequestOptions,
+	): Promise<T | null> {
+		return this.request<T>("DELETE", path, undefined, options);
+	}
+}

package/src/index.ts

@@ -0,0 +1,423 @@
+// ── Lazypock SDK — Root Client ─────────────────────────
+// Usage:
+//   const client = new LazypockClient({ baseUrl: 'http://localhost:4000/api' });
+//   await client.authStore.init();
+//   await client.login('admin@example.com', 'password');
+//   const records = await client.collection('articles').list();
+
+import { HttpClient } from "./http";
+import {
+	AuthStore,
+	memoryStorage,
+	type StorageAdapter,
+	type AuthModel,
+} from "./auth";
+import { CollectionService } from "./collection";
+import {
+	ApiError,
+	type ApiRecord,
+	type ListResult,
+	type RequestOptions,
+} from "./types";
+import { RealtimeService, wsUrlFromBaseUrl } from "./realtime";
+import { FilesService, getFileUrl, type FileRecord } from "./files";
+
+export {
+	AuthStore,
+	ApiError,
+	RealtimeService,
+	wsUrlFromBaseUrl,
+	FilesService,
+	getFileUrl,
+};
+export type {
+	StorageAdapter,
+	AuthModel,
+	ApiRecord,
+	ListResult,
+	RequestOptions,
+	FileRecord,
+};
+
+/** Options for constructing a {@link LazypockClient}. */
+export interface LazypockClientOptions {
+	/** API base URL (e.g. 'http://localhost:4000/api') */
+	baseUrl: string;
+	/** Custom storage adapter (default: localStorage fallback) */
+	storage?: StorageAdapter;
+	/** Explicit auth store instance (for sharing across modules) */
+	authStore?: AuthStore;
+	/** Real-time service for Phoenix Channel WebSocket subscriptions */
+	realtime?: RealtimeService;
+}
+
+/**
+ * Lazypock API client.
+ *
+ * Provides methods for authentication, CRUD operations on dynamic collections,
+ * file management, and real-time subscriptions.
+ *
+ * @example
+ * ```ts
+ * const client = new LazypockClient({ baseUrl: 'http://localhost:4000/api' });
+ * await client.login('admin@example.com', 'password');
+ * const posts = await client.collection('posts').list();
+ * ```
+ */
+export class LazypockClient {
+	readonly http: HttpClient;
+	readonly authStore: AuthStore;
+	readonly realtime: RealtimeService;
+	readonly files: FilesService;
+	private collectionCache = new Map<string, CollectionService>();
+
+	/**
+	 * Create a new Lazypock client.
+	 * @param options Configuration options.
+	 */
+	constructor(options: LazypockClientOptions) {
+		const baseUrl = options.baseUrl.replace(/\/+$/, "");
+		this.authStore =
+			options.authStore ?? new AuthStore(options.storage ?? memoryStorage);
+		this.http = new HttpClient(baseUrl, this.authStore);
+		this.realtime = options.realtime ?? new RealtimeService();
+		this.files = new FilesService(this.http);
+	}
+
+	/**
+	 * Get or create a typed service for the given collection.
+	 * Services are cached after first access.
+	 *
+	 * @param name The collection name.
+	 * @returns A {@link CollectionService} instance.
+	 */
+	collection(name: string): CollectionService {
+		let svc = this.collectionCache.get(name);
+		if (!svc) {
+			svc = new CollectionService(this.http, name, this.authStore);
+			this.collectionCache.set(name, svc);
+		}
+		return svc as unknown as CollectionService;
+	}
+
+	// ── Auth ──
+
+	/** Check whether any superuser exists (for login vs setup screen routing). */
+	async checkSuperuser(): Promise<{ has_superuser: boolean } | null> {
+		return this.http.get<{ has_superuser: boolean }>("/superusers/check");
+	}
+
+	/**
+	 * Create the initial superuser account.
+	 * Only works when no superuser exists yet.
+	 * Stores the returned token in the auth store.
+	 * @param email Superuser email.
+	 * @param password Superuser password (min 8 chars).
+	 */
+	async setup(
+		email: string,
+		password: string,
+	): Promise<({ token: string } & Record<string, unknown>) | null> {
+		const data = await this.http.post<
+			{ token: string } & Record<string, unknown>
+		>("/superusers/setup", { email, password });
+		if (data) {
+			this.authStore.setCollectionName(null);
+			this.authStore.set(data.token, null);
+		}
+		return data;
+	}
+
+	/**
+	 * Authenticate as a superuser or auth collection user.
+	 *
+	 * When `collection` is provided, authenticates against
+	 * `/{collection}/auth-with-password`. Otherwise logs in as superuser.
+	 * Stores the returned token in the auth store.
+	 *
+	 * @param email User email or identity.
+	 * @param password User password.
+	 * @param collection Optional auth collection name.
+	 */
+	async login(
+		email: string,
+		password: string,
+		collection?: string,
+	): Promise<({ token: string } & Record<string, unknown>) | null> {
+		let data;
+		if (collection) {
+			data = await this.http.post<
+				{ token: string; record: Record<string, unknown> } & Record<
+					string,
+					unknown
+				>
+			>("/" + encodeURIComponent(collection) + "/auth-with-password", {
+				identity: email,
+				password,
+			});
+			if (data && data.record) {
+				this.authStore.setCollectionName(collection);
+				this.authStore.set(data.token, data.record as unknown as AuthModel);
+			}
+		} else {
+			data = await this.http.post<{ token: string } & Record<string, unknown>>(
+				"/superusers/login",
+				{ email, password },
+			);
+			if (data) {
+				this.authStore.setCollectionName(null);
+				this.authStore.set(data.token, null);
+			}
+		}
+		return data;
+	}
+
+	/** Fetch the current superuser profile and refresh the auth model. */
+	async me<T = ApiRecord>(options?: RequestOptions): Promise<T | null> {
+		const data = await this.http.get<T>("/superusers/me", options);
+		if (data) {
+			// Update the auth model with fresh data
+			this.authStore.set(this.authStore.token, data as unknown as AuthModel);
+		}
+		return data;
+	}
+
+	/**
+	 * Authenticate against an auth collection with email/password.
+	 * Stores the returned token and user record in the auth store.
+	 *
+	 * @param collection The auth collection name.
+	 * @param identity Email or username.
+	 * @param password Password.
+	 * @param options Optional request options.
+	 */
+	async authWithPassword(
+		collection: string,
+		identity: string,
+		password: string,
+		options?: RequestOptions,
+	): Promise<
+		({ token: string; record: ApiRecord } & Record<string, unknown>) | null
+	> {
+		const data = await this.http.post<
+			{ token: string; record: ApiRecord } & Record<string, unknown>
+		>(
+			"/" + encodeURIComponent(collection) + "/auth-with-password",
+			{ identity, password },
+			options,
+		);
+		if (data) {
+			this.authStore.setCollectionName(collection);
+			this.authStore.set(data.token, data.record as unknown as AuthModel);
+		}
+		return data;
+	}
+
+	/**
+	 * Refresh an auth collection token.
+	 * Uses the currently stored auth token.
+	 *
+	 * @param collection The auth collection name.
+	 * @param options Optional request options.
+	 */
+	async authRefresh(
+		collection: string,
+		options?: RequestOptions,
+	): Promise<
+		({ token: string; record: ApiRecord } & Record<string, unknown>) | null
+	> {
+		const data = await this.http.post<
+			{ token: string; record: ApiRecord } & Record<string, unknown>
+		>(
+			"/" + encodeURIComponent(collection) + "/auth-refresh",
+			undefined,
+			options,
+		);
+		if (data) {
+			this.authStore.setCollectionName(collection);
+			this.authStore.set(data.token, data.record as unknown as AuthModel);
+		}
+		return data;
+	}
+
+	/** Clear the current auth state and remove persisted tokens. */
+	logout(): void {
+		this.authStore.clear();
+	}
+
+	// ── Health ──
+
+	/** Ping the API health endpoint. */
+	health(options?: RequestOptions): Promise<Record<string, unknown> | null> {
+		return this.http.get<Record<string, unknown>>("/health", options);
+	}
+
+	// ── Collection Management (admin) ──
+
+	/**
+	 * List all collections (admin).
+	 * @param q URL query string (e.g. `page=1&perPage=200`).
+	 * @param options Optional request options.
+	 */
+	listCollections(
+		q?: string,
+		options?: RequestOptions,
+	): Promise<ListResult<ApiRecord> | null> {
+		return this.http.get<ListResult<ApiRecord>>(
+			"/collections" + (q ? "?" + q : ""),
+			options,
+		);
+	}
+
+	/**
+	 * Get a single collection by ID or name.
+	 * @param id Collection ID or name.
+	 * @param options Optional request options.
+	 */
+	getCollection(
+		id: string,
+		options?: RequestOptions,
+	): Promise<ApiRecord | null> {
+		return this.http.get<ApiRecord>(
+			"/collections/" + encodeURIComponent(id),
+			options,
+		);
+	}
+
+	/**
+	 * Create a new collection (admin).
+	 * @param data Collection definition (name, type, fields, options, rules, etc.).
+	 * @param options Optional request options.
+	 */
+	createCollection(
+		data: Record<string, unknown>,
+		options?: RequestOptions,
+	): Promise<ApiRecord | null> {
+		return this.http.post<ApiRecord>("/collections", data, options);
+	}
+
+	/**
+	 * Update an existing collection (admin).
+	 * @param id Collection ID or name.
+	 * @param data Updated collection fields.
+	 * @param options Optional request options.
+	 */
+	updateCollection(
+		id: string,
+		data: Record<string, unknown>,
+		options?: RequestOptions,
+	): Promise<ApiRecord | null> {
+		return this.http.patch<ApiRecord>(
+			"/collections/" + encodeURIComponent(id),
+			data,
+			options,
+		);
+	}
+
+	/**
+	 * Delete a collection (admin).
+	 * @param id Collection ID or name.
+	 * @param options Optional request options.
+	 */
+	deleteCollection(id: string, options?: RequestOptions): Promise<null> {
+		return this.http.delete("/collections/" + encodeURIComponent(id), options);
+	}
+
+	// ── Records (dynamic collection) ──
+
+	/**
+	 * List records from a dynamic collection with optional filter/sort/pagination.
+	 *
+	 * @param coll Collection name.
+	 * @param params Query parameters including:
+	 *   - `filter` — PocketBase filter syntax (e.g. `title~'hello' && published=true`)
+	 *   - `sort` — Comma-separated, `-` prefix for DESC (e.g. `-created,title`)
+	 *   - `page` — Page number (default: 1)
+	 *   - `perPage` — Items per page (default: 30, max: 200)
+	 *   - `expand` — Comma-separated relation fields (e.g. `author,category`)
+	 * @param options Optional request options.
+	 */
+	listRecords(
+		coll: string,
+		params?: Record<string, string>,
+		options?: RequestOptions,
+	): Promise<ListResult<ApiRecord> | null> {
+		const qs = params ? "?" + new URLSearchParams(params).toString() : "";
+		return this.http.get<ListResult<ApiRecord>>(
+			"/" + encodeURIComponent(coll) + qs,
+			options,
+		);
+	}
+
+	/**
+	 * Get a single record by ID.
+	 * @param coll Collection name.
+	 * @param id Record ID.
+	 * @param options Optional request options.
+	 */
+	getRecord(
+		coll: string,
+		id: string,
+		options?: RequestOptions,
+	): Promise<ApiRecord | null> {
+		return this.http.get<ApiRecord>(
+			"/" + encodeURIComponent(coll) + "/" + encodeURIComponent(id),
+			options,
+		);
+	}
+
+	/**
+	 * Create a record in a dynamic collection.
+	 * @param coll Collection name.
+	 * @param data Record fields.
+	 * @param options Optional request options.
+	 */
+	createRecord(
+		coll: string,
+		data: Record<string, unknown>,
+		options?: RequestOptions,
+	): Promise<ApiRecord | null> {
+		return this.http.post<ApiRecord>(
+			"/" + encodeURIComponent(coll),
+			data,
+			options,
+		);
+	}
+
+	/**
+	 * Update a record in a dynamic collection.
+	 * @param coll Collection name.
+	 * @param id Record ID.
+	 * @param data Updated record fields.
+	 * @param options Optional request options.
+	 */
+	updateRecord(
+		coll: string,
+		id: string,
+		data: Record<string, unknown>,
+		options?: RequestOptions,
+	): Promise<ApiRecord | null> {
+		return this.http.patch<ApiRecord>(
+			"/" + encodeURIComponent(coll) + "/" + encodeURIComponent(id),
+			data,
+			options,
+		);
+	}
+
+	/**
+	 * Delete a record from a dynamic collection.
+	 * @param coll Collection name.
+	 * @param id Record ID.
+	 * @param options Optional request options.
+	 */
+	deleteRecord(
+		coll: string,
+		id: string,
+		options?: RequestOptions,
+	): Promise<null> {
+		return this.http.delete(
+			"/" + encodeURIComponent(coll) + "/" + encodeURIComponent(id),
+			options,
+		);
+	}
+}