nodestack-client 1.0.0

package/README.md

@@ -0,0 +1,248 @@
+# 🚀 nodestack-client
+
+> **The Official Lightweight, Type-Safe JavaScript & TypeScript Client SDK for [NodeStack](https://github.com/satya-jugran/nodebase)**
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A zero-dependency, isomorphic JavaScript and TypeScript client for NodeStack with out-of-the-box support for:
+- ⚡ **Zero runtime dependencies**: Built purely on standard Web APIs (`fetch`, `FormData`, `AbortController`, `EventSource`).
+- 🪶 **Ultra-lightweight footprint**: `< 10 KB` minified + gzipped.
+- 🔒 **Pluggable & Reactive Auth**: `LocalAuthStore` (localStorage), `MemoryAuthStore` (Node/SSR/testing), and reactive `onChange` state subscriptions.
+- 📦 **Fluent Record CRUD & Batch Pagination**: `getList`, `getFullList`, `getFirstListItem`, `create`, `update`, `delete`, `export`, and `import`.
+- 📁 **File Uploads & Protected File URLs**: Seamless `FormData` file uploads and URL generation with automatic token appending.
+- 📡 **Multiplexed Realtime SSE**: Single persistent connection with auto-handshake (`NS_CONNECT`), dynamic subscription sync, and automatic reconnection.
+- 🎯 **100% Type Safety**: Works seamlessly with `nodestack typegen` and `GET /api/types.d.ts` for autocompleted collection names and typed record returns.
+- 🌐 **Isomorphic**: Modern Browsers, React / Next.js (SSR + Client), Vue, Svelte, Node.js (18+ / 22+), Bun, Deno, and React Native.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install nodestack-client
+```
+
+Or using Yarn / PNPM / Bun:
+```bash
+pnpm add nodestack-client
+# or
+bun add nodestack-client
+```
+
+---
+
+## ⚡ Quick Start
+
+```typescript
+import { NodeStackClient } from 'nodestack-client';
+
+// Initialize client
+const client = new NodeStackClient('http://127.0.0.1:8090');
+
+// Fetch paginated records
+const result = await client.collection('posts').getList(1, 20, {
+  filter: "status = 'published' && views >= 10",
+  sort: '-created',
+});
+
+console.log(`Found ${result.totalItems} posts:`, result.items);
+```
+
+---
+
+## 🔐 Authentication
+
+### Authenticate as an Auth Collection User (e.g. `users`)
+```typescript
+const authData = await client.collection('users').authWithPassword('alice@example.com', 'password123');
+
+console.log('Logged in user:', client.authStore.model);
+console.log('JWT Token:', client.authStore.token);
+console.log('Is valid:', client.authStore.isValid);
+```
+
+### Authenticate as a Superuser / Admin
+```typescript
+const adminAuth = await client.admins.authWithPassword('admin@nodestack.io', 'MySecretAdminPassword');
+console.log('Logged in superuser:', adminAuth.admin.email);
+```
+
+### Reactive Auth State Changes
+```typescript
+// Subscribe to login / logout events (ideal for React, Vue, Svelte stores)
+const unbind = client.authStore.onChange((token, model) => {
+  console.log('Auth state changed:', { token, model });
+});
+
+// Logout
+client.authStore.clear();
+
+// Unsubscribe listener
+unbind();
+```
+
+### SSR & Node.js Environments (`MemoryAuthStore`)
+In Node.js scripts or server-side rendering where `window.localStorage` is unavailable:
+```typescript
+import { NodeStackClient, MemoryAuthStore } from 'nodestack-client';
+
+const serverClient = new NodeStackClient('http://127.0.0.1:8090', {
+  authStore: new MemoryAuthStore(),
+});
+```
+
+---
+
+## 📋 Record Operations (CRUD)
+
+### 1. Fetch Paginated Records (`getList`)
+```typescript
+const result = await client.collection('posts').getList(1, 10, {
+  filter: "category = 'Tech' && price <= 50",
+  sort: '-created,title',
+  expand: 'author,comments',
+});
+
+console.log(result.page, result.totalPages, result.items);
+```
+
+### 2. Fetch All Records Across Pages (`getFullList`)
+Auto-paginates in batches and returns all matching records as a single array:
+```typescript
+const allPosts = await client.collection('posts').getFullList({
+  batch: 200,
+  filter: "published = true",
+});
+```
+
+### 3. Find First Matching Record (`getFirstListItem`)
+```typescript
+// Throws ClientResponseError(404) if no match is found
+const post = await client.collection('posts').getFirstListItem("slug = 'hello-world'");
+```
+
+### 4. Create Record (JSON or File Uploads)
+```typescript
+// Plain JSON
+const newPost = await client.collection('posts').create({
+  title: 'My First Post',
+  published: true,
+});
+
+// Multipart Form Data (File Upload)
+const formData = new FormData();
+formData.append('title', 'Post with Cover Photo');
+formData.append('coverImage', fileInput.files[0]);
+
+const postWithImage = await client.collection('posts').create(formData);
+```
+
+### 5. Update & Delete Records
+```typescript
+// Update
+const updated = await client.collection('posts').update('rec_123', {
+  title: 'Updated Title',
+});
+
+// Delete
+await client.collection('posts').delete('rec_123');
+```
+
+---
+
+## 📁 File URLs Helper
+
+NodeStack provides protected and public file serving at `/api/files/:collection/:recordId/:filename`. Construct fully-qualified URLs easily:
+
+```typescript
+const record = await client.collection('posts').getOne('rec_123');
+
+// 1. Standard URL for <img> tags
+const imageUrl = client.files.getUrl(record, record.coverImage);
+
+// 2. Trigger browser download dialog
+const downloadUrl = client.files.getUrl(record, record.attachment, {
+  download: true,
+});
+
+// 3. Attach authentication token for protected files
+const protectedUrl = client.files.getUrl(record, record.secretDoc, {
+  token: true, // Uses active authStore token
+});
+```
+
+---
+
+## 📡 Realtime Subscriptions (SSE)
+
+NodeStack uses Server-Sent Events (SSE) with an initial `NS_CONNECT` handshake and multiplexed collection channels. `nodestack-client` manages this with automatic reconnection and topic synchronization:
+
+```typescript
+// 1. Subscribe to all changes in a collection
+const unsubscribe = await client.collection('posts').subscribe('*', (event) => {
+  console.log(`Action: ${event.action}`); // 'create' | 'update' | 'delete'
+  console.log('Record:', event.record);
+});
+
+// 2. Subscribe to a specific record by ID
+const unbindRecord = await client.collection('posts').subscribe('rec_123', (event) => {
+  console.log('Record updated:', event.record);
+});
+
+// 3. Clean up subscriptions when unmounting
+await unsubscribe();
+await unbindRecord();
+```
+
+---
+
+## 🎯 End-to-End Type Safety
+
+Pair `nodestack-client` with `nodestack typegen`:
+
+```bash
+# Generate TypeScript definitions from your running server
+npx nodestack typegen > src/types/nodestack.ts
+```
+
+Then supply your `SchemaCollections` dictionary to `NodeStackClient`:
+
+```typescript
+import { NodeStackClient } from 'nodestack-client';
+import { SchemaCollections } from './types/nodestack';
+
+const client = new NodeStackClient<SchemaCollections>('http://127.0.0.1:8090');
+
+// Autocomplete for collection names: 'posts' | 'users' | 'orders'
+// Return types are automatically inferred as PostRecord, UserRecord, etc.
+const posts = await client.collection('posts').getList();
+posts.items[0].title; // Fully typed!
+```
+
+---
+
+## 🛡️ Error Handling
+
+When NodeStack returns an error (4xx or 5xx), a `ClientResponseError` is thrown:
+
+```typescript
+import { ClientResponseError } from 'nodestack-client';
+
+try {
+  await client.collection('posts').getOne('missing_id');
+} catch (err) {
+  if (err instanceof ClientResponseError) {
+    console.error('Status:', err.status);     // e.g. 404
+    console.error('Message:', err.message);   // e.g. "Record not found"
+    console.error('Data:', err.data);         // Raw response JSON
+    console.error('Is Aborted:', err.isAbort);
+  }
+}
+```
+
+---
+
+## 📄 License
+
+MIT © NodeStack Contributors

package/dist/Client.d.ts

@@ -0,0 +1,55 @@
+import { BaseAuthStore } from './auth/BaseAuthStore';
+import { RecordService } from './services/RecordService';
+import { FileService } from './services/FileService';
+import { RealtimeService } from './services/RealtimeService';
+import { AdminService } from './services/AdminService';
+import { CollectionService } from './services/CollectionService';
+import type { ClientOptions, SendOptions, RecordModel } from './types';
+/**
+ * Main NodeStack Client SDK entry point.
+ */
+export declare class NodeStackClient<TCollections extends Record<string, any> = Record<string, RecordModel>> {
+    readonly baseUrl: string;
+    readonly authStore: BaseAuthStore;
+    readonly files: FileService;
+    readonly realtime: RealtimeService;
+    readonly admins: AdminService;
+    readonly collections: CollectionService;
+    private customFetch?;
+    private defaultHeaders;
+    private defaultTimeout;
+    private recordServices;
+    constructor(baseUrl?: string, options?: ClientOptions);
+    /**
+     * Returns a RecordService for interacting with a specific collection.
+     * If a schema map type is provided to NodeStackClient, collection names
+     * and record response types are automatically inferred and type-safe.
+     */
+    collection<K extends keyof TCollections>(name: K): RecordService<TCollections[K]>;
+    collection<T = RecordModel>(name: string): RecordService<T>;
+    /**
+     * Sends an HTTP request to NodeStack with automatic authentication,
+     * header injection, query serialization, and standardized error handling.
+     */
+    send<T = any>(path: string, options?: SendOptions): Promise<T>;
+    /**
+     * Checks backend system health.
+     */
+    health(): Promise<{
+        status: string;
+        [key: string]: any;
+    }>;
+    /**
+     * Retrieves server runtime settings.
+     */
+    settings(): Promise<any>;
+    /**
+     * Fetches request logs (Admin only).
+     */
+    logs(page?: number, perPage?: number): Promise<any>;
+    /**
+     * Fetches system metrics & analytics (Admin only).
+     */
+    metrics(): Promise<any>;
+}
+//# sourceMappingURL=Client.d.ts.map

package/dist/Client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Client.d.ts","sourceRoot":"","sources":["../src/Client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAGrD,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,KAAK,EACV,aAAa,EACb,WAAW,EACX,WAAW,EACZ,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,qBAAa,eAAe,CAAC,YAAY,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC;IACjG,SAAgB,OAAO,EAAE,MAAM,CAAC;IAChC,SAAgB,SAAS,EAAE,aAAa,CAAC;IACzC,SAAgB,KAAK,EAAE,WAAW,CAAC;IACnC,SAAgB,QAAQ,EAAE,eAAe,CAAC;IAC1C,SAAgB,MAAM,EAAE,YAAY,CAAC;IACrC,SAAgB,WAAW,EAAE,iBAAiB,CAAC;IAE/C,OAAO,CAAC,WAAW,CAAC,CAAe;IACnC,OAAO,CAAC,cAAc,CAAyB;IAC/C,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,cAAc,CAA8C;gBAExD,OAAO,GAAE,MAAY,EAAE,OAAO,GAAE,aAAkB;IAa9D;;;;OAIG;IACI,UAAU,CAAC,CAAC,SAAS,MAAM,YAAY,EAAE,IAAI,EAAE,CAAC,GAAG,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IACjF,UAAU,CAAC,CAAC,GAAG,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,CAAC,CAAC,CAAC;IAWlE;;;OAGG;IACU,IAAI,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,CAAC,CAAC;IA4H/E;;OAEG;IACU,MAAM,IAAI,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;KAAE,CAAC;IAItE;;OAEG;IACU,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC;IAIrC;;OAEG;IACU,IAAI,CAAC,IAAI,SAAI,EAAE,OAAO,SAAK,GAAG,OAAO,CAAC,GAAG,CAAC;IAOvD;;OAEG;IACU,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC;CAGrC"}

package/dist/auth/BaseAuthStore.d.ts

@@ -0,0 +1,38 @@
+import type { RecordModel, AdminModel } from '../types';
+export type AuthChangeListener = (token: string, model: RecordModel | AdminModel | null) => void;
+/**
+ * Lightweight helper to decode JWT payload without external dependencies.
+ */
+export declare function decodeJwtPayload(token: string): Record<string, any> | null;
+/**
+ * Base abstract class for authentication stores.
+ */
+export declare abstract class BaseAuthStore {
+    protected _token: string;
+    protected _model: RecordModel | AdminModel | null;
+    private _listeners;
+    get token(): string;
+    get model(): RecordModel | AdminModel | null;
+    /**
+     * Returns true if a token exists and has not yet expired.
+     */
+    get isValid(): boolean;
+    /**
+     * Saves the token and associated user or admin model.
+     */
+    save(token: string, model?: RecordModel | AdminModel | null): void;
+    /**
+     * Clears the current authentication state.
+     */
+    clear(): void;
+    /**
+     * Subscribes to changes in authentication state (token or model).
+     * Returns an unbind function.
+     */
+    onChange(callback: AuthChangeListener, fireImmediately?: boolean): () => void;
+    /**
+     * Triggers all subscribed change listeners.
+     */
+    protected notify(): void;
+}
+//# sourceMappingURL=BaseAuthStore.d.ts.map

package/dist/auth/BaseAuthStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseAuthStore.d.ts","sourceRoot":"","sources":["../../src/auth/BaseAuthStore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAExD,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,UAAU,GAAG,IAAI,KAAK,IAAI,CAAC;AAEjG;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAqC1E;AAED;;GAEG;AACH,8BAAsB,aAAa;IACjC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAM;IAC9B,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,UAAU,GAAG,IAAI,CAAQ;IACzD,OAAO,CAAC,UAAU,CAAsC;IAExD,IAAW,KAAK,IAAI,MAAM,CAEzB;IAED,IAAW,KAAK,IAAI,WAAW,GAAG,UAAU,GAAG,IAAI,CAElD;IAED;;OAEG;IACH,IAAW,OAAO,IAAI,OAAO,CAgB5B;IAED;;OAEG;IACI,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,UAAU,GAAG,IAAI,GAAG,IAAI;IAMzE;;OAEG;IACI,KAAK,IAAI,IAAI;IAMpB;;;OAGG;IACI,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,EAAE,eAAe,UAAQ,GAAG,MAAM,IAAI;IAelF;;OAEG;IACH,SAAS,CAAC,MAAM,IAAI,IAAI;CASzB"}

package/dist/auth/LocalAuthStore.d.ts

@@ -0,0 +1,21 @@
+import { BaseAuthStore } from './BaseAuthStore';
+import type { RecordModel, AdminModel } from '../types';
+export interface StorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/**
+ * Storage-backed AuthStore that syncs token and model with localStorage
+ * (or any custom StorageLike object, such as sessionStorage or AsyncStorage).
+ * Safely degrades to memory if storage is not available.
+ */
+export declare class LocalAuthStore extends BaseAuthStore {
+    private storageKey;
+    private storage?;
+    constructor(storageKey?: string, customStorage?: StorageLike);
+    private loadInitial;
+    save(token: string, model?: RecordModel | AdminModel | null): void;
+    clear(): void;
+}
+//# sourceMappingURL=LocalAuthStore.d.ts.map

package/dist/auth/LocalAuthStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocalAuthStore.d.ts","sourceRoot":"","sources":["../../src/auth/LocalAuthStore.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAExD,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACpC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAID;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,aAAa;IAC/C,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,OAAO,CAAC,CAAc;gBAElB,UAAU,GAAE,MAA4B,EAAE,aAAa,CAAC,EAAE,WAAW;IAajF,OAAO,CAAC,WAAW;IAiBH,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,UAAU,GAAG,IAAI,GAAG,IAAI;IAkBlE,KAAK,IAAI,IAAI;CAW9B"}

package/dist/auth/MemoryAuthStore.d.ts

@@ -0,0 +1,8 @@
+import { BaseAuthStore } from './BaseAuthStore';
+/**
+ * In-memory authentication store.
+ * Ideal for Node.js scripts, server-side rendering (SSR), and testing environments.
+ */
+export declare class MemoryAuthStore extends BaseAuthStore {
+}
+//# sourceMappingURL=MemoryAuthStore.d.ts.map

package/dist/auth/MemoryAuthStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryAuthStore.d.ts","sourceRoot":"","sources":["../../src/auth/MemoryAuthStore.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,aAAa;CAEjD"}

package/dist/errors/ClientResponseError.d.ts

@@ -0,0 +1,29 @@
+export interface ClientResponseErrorOptions {
+    url?: string;
+    status?: number;
+    data?: any;
+    isAbort?: boolean;
+    originalError?: any;
+    message?: string;
+}
+/**
+ * Standardized client response error representing failed HTTP requests
+ * or network exceptions when interacting with NodeStack.
+ */
+export declare class ClientResponseError extends Error {
+    readonly url: string;
+    readonly status: number;
+    readonly data: any;
+    readonly isAbort: boolean;
+    readonly originalError?: any;
+    constructor(options?: ClientResponseErrorOptions);
+    toJSON(): {
+        name: string;
+        message: string;
+        url: string;
+        status: number;
+        data: any;
+        isAbort: boolean;
+    };
+}
+//# sourceMappingURL=ClientResponseError.d.ts.map

package/dist/errors/ClientResponseError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClientResponseError.d.ts","sourceRoot":"","sources":["../../src/errors/ClientResponseError.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,0BAA0B;IACzC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,GAAG,CAAC;IACX,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,aAAa,CAAC,EAAE,GAAG,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,SAAgB,GAAG,EAAE,MAAM,CAAC;IAC5B,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,IAAI,EAAE,GAAG,CAAC;IAC1B,SAAgB,OAAO,EAAE,OAAO,CAAC;IACjC,SAAgB,aAAa,CAAC,EAAE,GAAG,CAAC;gBAExB,OAAO,GAAE,0BAA+B;IAmB7C,MAAM;;;;;;;;CAUd"}