nodestack-client 1.2.0 → 2.0.0

package/README.md

@@ -1,22 +1,25 @@
 # 🚀 nodestack-client
 
-> **The Official Lightweight, Type-Safe JavaScript & TypeScript Client SDK for [NodeStack](https://github.com/satya-jugran/nodebase)**
+> **The Official Lightweight, Type-Safe JavaScript & TypeScript Client SDK for [NodeStack](https://github.com/satya-jugran/nodestack)**
 >
 > Published on npm: [`nodestack-client`](https://www.npmjs.com/package/nodestack-client)
 
 [![npm version](https://img.shields.io/npm/v/nodestack-client.svg?color=blue)](https://www.npmjs.com/package/nodestack-client)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-7.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.
+- 🏢 **Multi-Application & App Scoping (v2.0)**: Fluent `client.app(slug)` scoping with automatic `x-nodestack-app` header injection, scoped SSE streams, and administrative `client.apps` management.
 - 🔒 **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`.
+- 🔍 **SQLite FTS5 Full-Text Search**: Embedded BM25 relevance ranking, keyword prefix matching, and contextual snippet highlighting.
+- 🔔 **Outbound Webhooks Service**: Programmatic webhook registration, test dispatch, delivery inspection, and HMAC-SHA256 signature verification (`client.webhooks`).
 - 📁 **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.
+- 🌐 **Isomorphic**: Modern Browsers, React / Next.js (SSR + Client), Vue, Svelte, Node.js (20+ / 22+ / 24+), Bun, Deno, and React Native.
 
 ---
 
@@ -97,6 +100,63 @@ const serverClient = new NodeStackClient('http://127.0.0.1:8090', {
 
 ---
 
+## 🏢 Multi-Application & App Scoping (v2.0)
+
+NodeStack v2.0 supports hosting multiple isolated applications on a single backend instance. `nodestack-client` makes targeting and managing applications seamless:
+
+### 1. Scoped Client Instances (`client.app`)
+Call `client.app(slug)` to create a scoped client. It shares the same connection config and auth store (or a custom one) while automatically scoping all requests:
+- Automatically injects `x-nodestack-app: slug` on all collection requests.
+- Scopes Realtime SSE streams (`/api/realtime?app=slug`).
+- Generates scoped file URLs (`/api/apps/:appId/files/...`).
+
+```typescript
+const client = new NodeStackClient('http://127.0.0.1:8090');
+
+// Scope to the 'ecommerce' application
+const shopClient = client.app('ecommerce');
+
+// All queries now operate within 'ecommerce' SQLite database
+const products = await shopClient.collection('products').getList(1, 20);
+
+// File URLs automatically point to the app-scoped file route:
+// http://127.0.0.1:8090/api/apps/ecommerce/files/products/rec_123/image.png
+const imgUrl = shopClient.files.getUrl(products.items[0], products.items[0].cover);
+
+// Realtime SSE scoped to 'ecommerce'
+shopClient.collection('orders').subscribe('*', (e) => {
+  console.log('New shop order:', e.record);
+});
+```
+
+### 2. Multi-App Management Service (`client.apps`)
+Administrative scripts or superusers can provision, inspect, and delete applications programmatically:
+
+```typescript
+// Authenticate as superuser
+await client.admins.authWithPassword('admin@nodestack.io', 'AdminPass123!');
+
+// List hosted applications
+const apps = await client.apps.getList(1, 50);
+
+// Create a new app from a starter template ('saas' | 'blog' | 'ecommerce' | 'blank')
+const newApp = await client.apps.create({
+  name: 'Analytics Dashboard',
+  slug: 'analytics',
+  template: 'saas',
+});
+
+// Update app details
+await client.apps.update(newApp.id, {
+  name: 'Analytics Production',
+});
+
+// Delete an application (deletes its SQLite DB & uploaded files)
+await client.apps.delete(newApp.id);
+```
+
+---
+
 ## 📋 Record Operations (CRUD)
 
 ### 1. Fetch Paginated Records (`getList`)
@@ -110,7 +170,21 @@ const result = await client.collection('posts').getList(1, 10, {
 console.log(result.page, result.totalPages, result.items);
 ```
 
-### 2. Fetch All Records Across Pages (`getFullList`)
+### 2. Full-Text Search with BM25 Scoring & Snippets (`search`)
+Query records using embedded SQLite FTS5 with BM25 relevance ranking and keyword highlight snippets:
+```typescript
+const searchResults = await client.collection('posts').getList(1, 10, {
+  search: 'distributed systems',
+  snippetTag: 'mark',     // Highlight tag (default: <mark>)
+  snippetLength: 25,       // Max words per snippet excerpt
+});
+
+console.log(searchResults.items[0]._score);    // BM25 relevance score
+console.log(searchResults.items[0]._snippet);  // Best matching snippet excerpt
+console.log(searchResults.items[0]._snippets); // Per-field snippet map: { title: "...", content: "..." }
+```
+
+### 3. 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({
@@ -119,13 +193,13 @@ const allPosts = await client.collection('posts').getFullList({
 });
 ```
 
-### 3. Find First Matching Record (`getFirstListItem`)
+### 4. 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)
+### 5. Create Record (JSON or File Uploads)
 ```typescript
 // Plain JSON
 const newPost = await client.collection('posts').create({
@@ -141,7 +215,7 @@ formData.append('coverImage', fileInput.files[0]);
 const postWithImage = await client.collection('posts').create(formData);
 ```
 
-### 5. Update & Delete Records
+### 6. Update & Delete Records
 ```typescript
 // Update
 const updated = await client.collection('posts').update('rec_123', {
@@ -280,6 +354,45 @@ client.setChaos(null);
 
 ---
 
+## 🔔 Outbound Webhooks Management & Signature Verification
+
+Manage outbound webhook subscriptions, inspect delivery logs, and cryptographically verify incoming webhook payloads:
+
+```typescript
+// 1. Create a webhook subscription
+const webhook = await client.webhooks.create({
+  name: 'Slack Order Dispatcher',
+  url: 'https://api.myapp.com/webhooks/orders',
+  collection: 'orders',
+  action: 'create', // 'create' | 'update' | 'delete' | '*'
+  secret: 'whsec_9948a8cf38b1e42c',
+  enabled: true,
+});
+
+// 2. Dispatch an instant test payload
+await client.webhooks.test(webhook.id, { test: true });
+
+// 3. Inspect delivery history logs
+const deliveries = await client.webhooks.getDeliveries({
+  webhookId: webhook.id,
+  status: 'failed',
+});
+
+// 4. Retry a failed delivery attempt
+if (deliveries.items.length > 0) {
+  await client.webhooks.retryDelivery(deliveries.items[0].id);
+}
+
+// 5. Verify HMAC-SHA256 signature in your receiving server/microservice
+const isValid = client.webhooks.verifySignature(
+  rawRequestBodyString,
+  requestHeaders['x-nodestack-signature'],
+  'whsec_9948a8cf38b1e42c'
+);
+```
+
+---
+
 ## 📄 License
 
 MIT © NodeStack Contributors

package/dist/Client.d.ts

@@ -5,6 +5,9 @@ import { RealtimeService } from './services/RealtimeService';
 import { AdminService } from './services/AdminService';
 import { CollectionService } from './services/CollectionService';
 import { DemoService } from './services/DemoService';
+import { SnapshotService } from './services/SnapshotService';
+import { WebhookService } from './services/WebhookService';
+import { AppService } from './services/AppService';
 import type { ClientOptions, SendOptions, RecordModel, ChaosOptions } from './types';
 /**
  * Main NodeStack Client SDK entry point.
@@ -16,7 +19,11 @@ export declare class NodeStackClient<TCollections extends Record<string, any> =
     readonly realtime: RealtimeService;
     readonly admins: AdminService;
     readonly collections: CollectionService;
+    readonly snapshots: SnapshotService;
     readonly demo: DemoService;
+    readonly webhooks: WebhookService;
+    readonly apps: AppService;
+    readonly appSlug?: string;
     private customFetch?;
     private defaultHeaders;
     private defaultTimeout;
@@ -63,5 +70,10 @@ export declare class NodeStackClient<TCollections extends Record<string, any> =
      * Fetches system metrics & analytics (Admin only).
      */
     metrics(): Promise<any>;
+    /**
+     * Returns a new NodeStackClient instance scoped to a specific application/MVP.
+     * Inherits baseUrl, authStore, customFetch, defaultHeaders, and defaultTimeout.
+     */
+    app<TAppCollections extends Record<string, any> = Record<string, RecordModel>>(slug: string, options?: Partial<ClientOptions>): NodeStackClient<TAppCollections>;
 }
 //# sourceMappingURL=Client.d.ts.map

package/dist/Client.d.ts.map

@@ -1 +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,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,KAAK,EACV,aAAa,EACb,WAAW,EACX,WAAW,EACX,YAAY,EACb,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;IAC/C,SAAgB,IAAI,EAAE,WAAW,CAAC;IAElC,OAAO,CAAC,WAAW,CAAC,CAAe;IACnC,OAAO,CAAC,cAAc,CAAyB;IAC/C,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,cAAc,CAA8C;gBAExD,OAAO,GAAE,MAAY,EAAE,OAAO,GAAE,aAAkB;IAe9D;;;OAGG;IACI,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,GAAG,IAAI;IAInD;;OAEG;IACI,QAAQ,IAAI,YAAY,GAAG,IAAI;IAItC;;;;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;IAsJ/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"}
+{"version":3,"file":"Client.d.ts","sourceRoot":"","sources":["../src/Client.ts"],"names":[],"mappings":"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"}

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

@@ -1 +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"}
+{"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,CAIxE;IAED;;OAEG;IACI,KAAK,IAAI,IAAI,CAInB;IAED;;;OAGG;IACI,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,EAAE,eAAe,UAAQ,GAAG,MAAM,IAAI,CAajF;IAED;;OAEG;IACH,SAAS,CAAC,MAAM,IAAI,IAAI,CAQvB;CACF"}

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

@@ -1 +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"}
+{"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;IAE9B,YAAY,UAAU,GAAE,MAA4B,EAAE,aAAa,CAAC,EAAE,WAAW,EAWhF;IAED,OAAO,CAAC,WAAW;IAiBH,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,UAAU,GAAG,IAAI,GAAG,IAAI,CAgBjF;IAEe,KAAK,IAAI,IAAI,CAU5B;CACF"}

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

@@ -1 +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"}
+{"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;IAEpC,YAAY,OAAO,GAAE,0BAA+B,EAiBnD;IAEM,MAAM;QAET,IAAI;QACJ,OAAO;QACP,GAAG;QACH,MAAM;QACN,IAAI;QACJ,OAAO;MAEV;CACF"}

package/dist/index.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   AdminService: () => AdminService,
+  AppService: () => AppService,
   BaseAuthStore: () => BaseAuthStore,
   BaseService: () => BaseService,
   ClientResponseError: () => ClientResponseError,
@@ -32,8 +33,12 @@ __export(index_exports, {
   NodeStackClient: () => NodeStackClient,
   RealtimeService: () => RealtimeService,
   RecordService: () => RecordService,
+  SnapshotService: () => SnapshotService,
+  WebhookService: () => WebhookService,
+  computeWebhookSignature: () => computeWebhookSignature,
   decodeJwtPayload: () => decodeJwtPayload,
-  default: () => NodeStackClient
+  default: () => NodeStackClient,
+  verifyWebhookSignature: () => verifyWebhookSignature
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -463,7 +468,8 @@ var FileService = class extends BaseService {
     const cleanCol = encodeURIComponent(collectionName);
     const cleanId = encodeURIComponent(recordId);
     const cleanFile = encodeURIComponent(filename);
-    let url = `${cleanBase}/api/files/${cleanCol}/${cleanId}/${cleanFile}`;
+    const appSlug = options.app || this.client.appSlug;
+    let url = appSlug && appSlug !== "default" ? `${cleanBase}/api/apps/${encodeURIComponent(appSlug)}/files/${cleanCol}/${cleanId}/${cleanFile}` : `${cleanBase}/api/files/${cleanCol}/${cleanId}/${cleanFile}`;
     const queryParts = [];
     if (options.download) {
       queryParts.push("download=1");
@@ -536,8 +542,16 @@ var RealtimeService = class extends BaseService {
         const EventSourceClass = this.getEventSourceConstructor();
         const base = (this.client.baseUrl || "").replace(/\/+$/, "");
         let url = `${base}/api/realtime`;
+        const queryParams = new URLSearchParams();
         if (this.client.authStore.token) {
-          url += `?token=${encodeURIComponent(this.client.authStore.token)}`;
+          queryParams.append("token", this.client.authStore.token);
+        }
+        if (this.client.appSlug) {
+          queryParams.append("app", this.client.appSlug);
+        }
+        const qs = queryParams.toString();
+        if (qs) {
+          url += `?${qs}`;
         }
         this.eventSource = new EventSourceClass(url);
         const handleConnect = async (event) => {
@@ -769,6 +783,8 @@ var AdminService = class extends BaseService {
 
 // src/services/CollectionService.ts
 var CollectionService = class extends BaseService {
+  list = this.getList.bind(this);
+  get = this.getOne.bind(this);
   /**
    * Retrieves all collection schema models.
    */
@@ -875,15 +891,288 @@ var DemoService = class extends BaseService {
   }
 };
 
+// src/services/SnapshotService.ts
+var SnapshotService = class extends BaseService {
+  /**
+   * Retrieves all snapshots, active baseline, and live drift information.
+   */
+  async list() {
+    return this.send("/api/snapshots", {
+      method: "GET"
+    });
+  }
+  /**
+   * Alias for list() to retrieve status.
+   */
+  async getStatus() {
+    return this.list();
+  }
+  /**
+   * Creates a new application state snapshot.
+   * If snapshot limit (10) is reached, evictOldest: true can be passed to confirm eviction of the oldest.
+   */
+  async create(options) {
+    return this.send("/api/snapshots", {
+      method: "POST",
+      body: options || {}
+    });
+  }
+  /**
+   * Retrieves a specific snapshot by ID.
+   */
+  async get(id) {
+    return this.send(`/api/snapshots/${encodeURIComponent(id)}`, {
+      method: "GET"
+    });
+  }
+  /**
+   * Restores application state to a specific snapshot.
+   * Note: Future snapshots are NOT deleted; history remains intact.
+   */
+  async restore(id) {
+    return this.send(`/api/snapshots/${encodeURIComponent(id)}/restore`, {
+      method: "POST"
+    });
+  }
+  /**
+   * Deletes a specific snapshot by ID.
+   */
+  async delete(id) {
+    return this.send(`/api/snapshots/${encodeURIComponent(id)}`, {
+      method: "DELETE"
+    });
+  }
+  /**
+   * Clears all saved snapshots.
+   */
+  async clear() {
+    return this.send("/api/snapshots", {
+      method: "DELETE"
+    });
+  }
+};
+
+// src/services/WebhookService.ts
+function computeWebhookSignature(payload, secret) {
+  const str = typeof payload === "string" ? payload : JSON.stringify(payload);
+  try {
+    const nodeCrypto = typeof require !== "undefined" ? require("crypto") : typeof globalThis !== "undefined" ? globalThis.require?.("crypto") || globalThis.crypto : null;
+    if (nodeCrypto && typeof nodeCrypto.createHmac === "function") {
+      return nodeCrypto.createHmac("sha256", secret).update(str, "utf8").digest("hex");
+    }
+  } catch {
+  }
+  throw new Error("[NodeStackClient] HMAC-SHA256 computation requires crypto module.");
+}
+function verifyWebhookSignature(payload, signatureHeader, secret) {
+  if (!signatureHeader || !secret) return false;
+  let expected = "";
+  try {
+    expected = computeWebhookSignature(payload, secret);
+  } catch {
+    return false;
+  }
+  let cleanHeader = signatureHeader.trim();
+  if (cleanHeader.startsWith("sha256=")) {
+    cleanHeader = cleanHeader.substring(7);
+  } else if (cleanHeader.startsWith("sha256:")) {
+    cleanHeader = cleanHeader.substring(7);
+  }
+  if (cleanHeader.length !== expected.length) return false;
+  try {
+    const nodeCrypto = typeof require !== "undefined" ? require("crypto") : typeof globalThis !== "undefined" ? globalThis.require?.("crypto") : null;
+    const buf = typeof Buffer !== "undefined" ? Buffer : typeof globalThis !== "undefined" ? globalThis.Buffer : null;
+    if (nodeCrypto && typeof nodeCrypto.timingSafeEqual === "function" && buf) {
+      return nodeCrypto.timingSafeEqual(buf.from(cleanHeader, "hex"), buf.from(expected, "hex"));
+    }
+  } catch {
+  }
+  let diff = 0;
+  for (let i = 0; i < cleanHeader.length; i++) {
+    diff |= cleanHeader.charCodeAt(i) ^ expected.charCodeAt(i);
+  }
+  return diff === 0;
+}
+var WebhookService = class extends BaseService {
+  /**
+   * Retrieves all configured outbound webhooks.
+   */
+  async getList(options = {}) {
+    const res = await this.send("/api/webhooks", {
+      method: "GET",
+      query: options
+    });
+    return Array.isArray(res) ? res : [];
+  }
+  /**
+   * Retrieves a single webhook by ID.
+   */
+  async getOne(id) {
+    return this.send(`/api/webhooks/${encodeURIComponent(id)}`, {
+      method: "GET"
+    });
+  }
+  /**
+   * Creates a new outbound webhook configuration.
+   */
+  async create(data) {
+    return this.send("/api/webhooks", {
+      method: "POST",
+      body: data
+    });
+  }
+  /**
+   * Updates an existing webhook configuration.
+   */
+  async update(id, data) {
+    return this.send(`/api/webhooks/${encodeURIComponent(id)}`, {
+      method: "PATCH",
+      body: data
+    });
+  }
+  /**
+   * Deletes a configured webhook by ID.
+   */
+  async delete(id) {
+    await this.send(`/api/webhooks/${encodeURIComponent(id)}`, {
+      method: "DELETE"
+    });
+    return true;
+  }
+  /**
+   * Dispatches a live test event to the target webhook endpoint with an optional payload.
+   */
+  async test(id, payload) {
+    return this.send(`/api/webhooks/${encodeURIComponent(id)}/test`, {
+      method: "POST",
+      body: payload !== void 0 ? { payload } : {}
+    });
+  }
+  /**
+   * Retrieves overall webhook health and delivery statistics.
+   */
+  async getStats() {
+    return this.send("/api/webhooks/stats", {
+      method: "GET"
+    });
+  }
+  /**
+   * Queries paginated webhook delivery logs with optional filtering by webhook ID, collection, status, or search.
+   */
+  async getDeliveries(options = {}) {
+    return this.send("/api/webhooks/deliveries", {
+      method: "GET",
+      query: options
+    });
+  }
+  /**
+   * Retrieves complete delivery log details including headers and request/response payloads.
+   */
+  async getDelivery(id) {
+    return this.send(`/api/webhooks/deliveries/${encodeURIComponent(id)}`, {
+      method: "GET"
+    });
+  }
+  /**
+   * Manually retries a failed delivery attempt to its target endpoint.
+   */
+  async retryDelivery(id) {
+    return this.send(`/api/webhooks/deliveries/${encodeURIComponent(id)}/retry`, {
+      method: "POST"
+    });
+  }
+  /**
+   * Clears delivery history logs. If olderThanDays is specified, only deletes logs older than that many days.
+   */
+  async clearDeliveries(olderThanDays) {
+    const query = {};
+    if (olderThanDays !== void 0 && olderThanDays !== null) {
+      query.olderThanDays = olderThanDays;
+    }
+    return this.send("/api/webhooks/deliveries", {
+      method: "DELETE",
+      query
+    });
+  }
+  /**
+   * Verifies an incoming X-NodeStack-Signature header against the expected secret.
+   */
+  verifySignature(payload, signatureHeader, secret) {
+    return verifyWebhookSignature(payload, signatureHeader, secret);
+  }
+  /**
+   * Computes an HMAC-SHA256 signature for a payload and secret string.
+   */
+  computeSignature(payload, secret) {
+    return computeWebhookSignature(payload, secret);
+  }
+  static verifySignature = verifyWebhookSignature;
+  static computeSignature = computeWebhookSignature;
+};
+
+// src/services/AppService.ts
+var AppService = class extends BaseService {
+  list = this.getList.bind(this);
+  get = this.getOne.bind(this);
+  /**
+   * Retrieves all configured applications.
+   */
+  async getList() {
+    const res = await this.send("/api/apps", {
+      method: "GET"
+    });
+    return Array.isArray(res) ? res : res?.items || [];
+  }
+  /**
+   * Retrieves a single application by ID or slug.
+   */
+  async getOne(appId) {
+    return this.send(`/api/apps/${encodeURIComponent(appId)}`, {
+      method: "GET"
+    });
+  }
+  /**
+   * Creates a new application.
+   */
+  async create(data) {
+    return this.send("/api/apps", {
+      method: "POST",
+      body: data
+    });
+  }
+  /**
+   * Updates an existing application.
+   */
+  async update(appId, data) {
+    return this.send(`/api/apps/${encodeURIComponent(appId)}`, {
+      method: "PATCH",
+      body: data
+    });
+  }
+  /**
+   * Deletes an application by ID or slug.
+   */
+  async delete(appId) {
+    await this.send(`/api/apps/${encodeURIComponent(appId)}`, {
+      method: "DELETE"
+    });
+    return true;
+  }
+};
+
 // src/Client.ts
-var NodeStackClient = class {
+var NodeStackClient = class _NodeStackClient {
   baseUrl;
   authStore;
   files;
   realtime;
   admins;
   collections;
+  snapshots;
   demo;
+  webhooks;
+  apps;
+  appSlug;
   customFetch;
   defaultHeaders;
   defaultTimeout;
@@ -896,11 +1185,15 @@ var NodeStackClient = class {
     this.defaultHeaders = options.headers || {};
     this.defaultTimeout = options.timeout || 12e4;
     this.chaosOptions = options.chaos ? { ...options.chaos } : null;
+    this.appSlug = options.app;
     this.files = new FileService(this);
     this.realtime = new RealtimeService(this, options.EventSource);
     this.admins = new AdminService(this);
     this.collections = new CollectionService(this);
+    this.snapshots = new SnapshotService(this);
     this.demo = new DemoService(this);
+    this.webhooks = new WebhookService(this);
+    this.apps = new AppService(this);
   }
   /**
    * Dynamically configure latency & chaos simulation options for all future requests.
@@ -954,6 +1247,9 @@ var NodeStackClient = class {
     if (this.authStore.token && !headers["Authorization"] && !headers["authorization"]) {
       headers["Authorization"] = `Bearer ${this.authStore.token}`;
     }
+    if (this.appSlug && !headers["x-nodestack-app"] && !headers["X-NodeStack-App"]) {
+      headers["x-nodestack-app"] = this.appSlug;
+    }
     const effectiveChaos = {
       ...this.chaosOptions || {},
       ...options.chaos || {},
@@ -1070,6 +1366,21 @@ var NodeStackClient = class {
   async metrics() {
     return this.send("/api/metrics", { method: "GET" });
   }
+  /**
+   * Returns a new NodeStackClient instance scoped to a specific application/MVP.
+   * Inherits baseUrl, authStore, customFetch, defaultHeaders, and defaultTimeout.
+   */
+  app(slug, options = {}) {
+    return new _NodeStackClient(this.baseUrl, {
+      authStore: options.authStore || this.authStore,
+      fetch: options.fetch || this.customFetch,
+      headers: { ...this.defaultHeaders, ...options.headers || {} },
+      timeout: options.timeout !== void 0 ? options.timeout : this.defaultTimeout,
+      chaos: options.chaos !== void 0 ? options.chaos ? { ...options.chaos } : void 0 : this.chaosOptions ? { ...this.chaosOptions } : void 0,
+      app: slug,
+      EventSource: options.EventSource || this.realtime.customEventSource
+    });
+  }
 };
 
 // src/auth/MemoryAuthStore.ts