@zuzjs/flare-admin 0.1.4 → 0.1.6

package/README.md

@@ -22,7 +22,7 @@ admin.auth()
                                                socket elevated ✓
 ```
 
-**No MongoDB URI is ever shared.** The SDK talks to FlareServer's `/admin/token` REST endpoint using only the `adminKey`. This works identically whether you self-host Flare or use it as SaaS at `https://flare.zuz.com.pk`.
+**No MongoDB URI is ever shared.** The SDK talks to FlareServer's `/admin/token` REST endpoint using only the `adminKey`.
 
 ---
 
@@ -44,8 +44,6 @@ pnpm add @zuzjs/flare-admin
 flare app create my-app
 ```
 
-This prints two configs:
-
 | Config | Safe for... |
 |---|---|
 | `apiKey` | Browser / client-side |
@@ -55,7 +53,7 @@ This prints two configs:
 
 ```bash
 # .env (server-side only)
-FLARE_URL=hhttps://flare.zuzcdn.net       # your FlareServer URL
+FLARE_URL=https://flare.zuzcdn.net
 FLARE_APP_ID=my-app
 FLARE_ADMIN_KEY=FA_ADMIN_xxxxxxxxxxxx
 ```
@@ -78,14 +76,9 @@ const admin = connectApp({
 import { getApp } from "@zuzjs/flare-admin";
 
 app.post("/login", async (req, res) => {
-  // --- your existing auth logic ---
   const user = await myAuthLogic(req.body);
   if (!user) return res.status(401).json({ error: "invalid credentials" });
 
-  // Set your own session / cookie as normal
-  req.session.userId = user.id;
-
-  // --- the bridge ---
   const flareToken = await getApp().auth().createCustomToken(user.id, {
     role:   user.isAdmin ? "admin" : "user",
     claims: { email: user.email, plan: user.plan },
@@ -104,12 +97,11 @@ import FlareClient from "@zuzjs/flare";
 const flare = new FlareClient({
   endpoint: "https://flare.zuzcdn.net",
   appId:    "my-app",
-  apiKey:   "FA_xxxxxxxx",           // browser-safe key
+  apiKey:   "FA_xxxxxxxx",
 });
 
 flare.connect();
 
-// After login:
 const { flareToken } = await fetch("/login", { method: "POST", body: ... }).then(r => r.json());
 await flare.auth(flareToken);
 // ✅ Socket is now elevated — auth.uid and auth.role are set
@@ -125,51 +117,80 @@ Initialize a FlareAdmin app. Idempotent — safe to call at module scope.
 
 ```typescript
 const admin = connectApp({
-  serverUrl:  string;   // FlareServer base URL
-  appId:      string;   // App ID from `flare app create`
-  adminKey:   string;   // Admin key — server-side only
-  defaultTtl?: string;  // Default token TTL, e.g. "24h" (default)
+  serverUrl:   string;   // FlareServer base URL
+  appId:       string;   // App ID from `flare app create`
+  adminKey:    string;   // Admin key — server-side only
+  httpBase?:   string;   // Override base URL for all admin HTTP APIs (e.g. proxy)
+  defaultTtl?: string;   // Default token TTL, e.g. "24h" (default)
+  dataMapper?: Record<string, (row: any) => any>; // Per-collection response mappers
 });
 ```
 
+`httpBase` routes all admin HTTP traffic through a different base URL (useful for proxies or gateways). When set, it replaces `serverUrl` as the base for every `/admin/*` HTTP request. Trailing slashes are normalized automatically.
+
 ### `getApp(name?)`
 
-Retrieve an already-initialized app instance.
+Retrieve an already-initialized app instance. Throws if not initialized.
 
-### `auth(name?)`
+### `disconnectApp(name?)`
 
-Shorthand for `getApp(name).auth()`.
+Disconnect and remove an app from the registry. Returns `true` if the app existed.
+
+```typescript
+disconnectApp();        // default app
+disconnectApp("app-a"); // named app
+```
+
+### `disconnectAllApps()`
+
+Disconnect and clear every initialized app.
+
+```typescript
+disconnectAllApps();
+```
+
+### `app.disconnect()`
+
+Close the WebSocket connection on a specific app instance. Safe to call multiple times.
+
+```typescript
+admin.disconnect();
+```
+
+---
+
+## Auth
 
 ### `admin.auth().createCustomToken(uid, opts?)`
 
-Mint a custom auth token.
+Mint a custom auth token for use by the browser client.
 
 ```typescript
 const token = await admin.auth().createCustomToken(uid, {
   role?:   "user" | "admin" | "anon",  // default: "user"
-  claims?: Record<string, unknown>,    // extra JWT payload fields
+  claims?: Record<string, unknown>,
   ttl?:   string,                      // e.g. "1h", "7d"
 });
 ```
 
 ### `admin.auth().getTicket(uid, opts?)`
 
-Mint a one-time ticket from `/admin/ticket` for WebSocket auth flows.
+Mint a one-time ticket for WebSocket auth flows.
 
 ```typescript
 const ticket = await admin.auth().getTicket(uid, {
-  role?: "user" | "admin" | "anon", // default: "user"
-  email?: string,
-  sid?: string,
-  ttlSeconds?: number,                  // server clamps to safe range
-  ip?: string,                          // optional override
+  role?:       "user" | "admin" | "anon",
+  email?:      string,
+  sid?:        string,
+  ttlSeconds?: number,
+  ip?:         string,
 });
 
-// ticket shape
+// ticket shape:
 // {
-//   ticket: "websocket:550e8400-e29b-41d4-a716-446655440000",
+//   ticket: "websocket:550e8400-...",
 //   tag: "websocket",
-//   uuid: "550e8400-e29b-41d4-a716-446655440000",
+//   uuid: "550e8400-...",
 //   expires_at: "2026-04-15T12:34:56Z",
 //   one_time: true,
 //   uid: "user_123",
@@ -178,39 +199,157 @@ const ticket = await admin.auth().getTicket(uid, {
 // }
 ```
 
-Short REST example for `/admin/ticket`:
+---
 
-```http
-POST /admin/ticket
-Authorization: Bearer FA_ADMIN_xxxxxxxxxxxx
-Content-Type: application/json
+## Database
 
-{
-  "appId": "my-app",
-  "uid": "user_123",
-  "role": "user",
-  "ttlSeconds": 300
-}
+```typescript
+// One-shot queries (bypasses security rules)
+const users = await admin.db().collection("users").get();
+
+await admin.db().collection("users").doc("alice").set({ name: "Alice" });
+await admin.db().collection("users").doc("alice").update({ plan: "pro" });
+await admin.db().collection("users").doc("alice").delete();
+
+// Rich queries
+const seniors = await admin.db()
+  .collection("users")
+  .where({ age: ">= 60" })
+  .orderBy("name")
+  .limit(10)
+  .get();
 ```
 
-```json
-{
-  "ticket": {
-    "ticket": "websocket:550e8400-e29b-41d4-a716-446655440000",
-    "tag": "websocket",
-    "uuid": "550e8400-e29b-41d4-a716-446655440000",
-    "expires_at": "2026-04-15T12:34:56Z",
-    "one_time": true,
-    "uid": "user_123",
-    "role": "user",
-    "ip": "203.0.113.20"
-  }
-}
+### Query Builder
+
+`admin.db().collection(...)` supports the full structured query API:
+
+**Filters:** `where`, `and`, `or`, `in`, `andIn`, `orIn`, `notIn`, `andNotIn`, `orNotIn`, `arrayContains`, `andArrayContains`, `orArrayContains`, `arrayContainsAny`, `andArrayContainsAny`, `orArrayContainsAny`, `some`, `andSome`, `orSome`, `like`, `andLike`, `orLike`, `notLike`, `andNotLike`, `orNotLike`, `exists`, `andExists`, `orExists`, `notExists`, `andNotExists`, `orNotExists`
+
+**Sort / cursor / aggregate:** `latest`, `newest`, `oldest`, `orderBy`, `limit`, `offset`, `startAt`, `startAfter`, `endAt`, `endBefore`, `count`, `sum`, `avg`, `min`, `max`, `distinct`, `groupBy`, `having`, `select`, `distinctField`, `vectorSearch`
+
+**Joins:** `join`, `Join`, `joinNested`, `JoinNested`, `withRelation`
+
+```typescript
+const rows = await admin.db()
+  .collection("boards")
+  .where({ uid: userId })
+  .orSome("team", { uid: userId })
+  .join("lists",   { source: "id",       target: "boardId", as: "lists" })
+  .join("users",   { source: "team.uid", target: "id",      as: "teamMembers" })
+  .joinNested("lists", "cards", { source: "id", target: "listId", as: "cards" })
+  .withRelation("team.uid->users.id as collaborators")
+  .orderBy("updatedAt", "desc")
+  .limit(20)
+  .get();
+```
+
+### `allowSensitiveAuthUserFields(false)`
+
+Auth-user joins default to full fields. Pass `false` to restrict to public-profile-only output:
+
+```typescript
+const safeBoards = await admin.db()
+  .collection("boards")
+  .join("users", { source: "team.uid", target: "id", as: "team" })
+  .allowSensitiveAuthUserFields(false)
+  .get();
+```
+
+### `getRawQuery()`
+
+Inspect the structured query that will be sent:
+
+```typescript
+const raw = admin.db()
+  .collection("boards")
+  .where({ uid: userId })
+  .getRawQuery();
+
+console.log(raw.collection, raw.query);
 ```
 
 ---
 
-## Security rules on the server
+## Realtime
+
+### `admin.live().collection(...).onSnapshot(cb)`
+
+Single-snapshot subscription — fires once on the initial data load, then auto-unsubscribes:
+
+```typescript
+const unsub = admin.live()
+  .collection("orders")
+  .where({ status: "pending" })
+  .orderBy("createdAt", "desc")
+  .onSnapshot((snap) => {
+    console.log(snap.type, snap.data);
+  });
+```
+
+### `.stream(options?)` — live batched stream
+
+Returns a long-lived `AdminCollectionStream<T>` that maintains a local snapshot and fans out batched change events to listeners.
+
+```typescript
+const stream = admin.live()
+  .collection("orders")
+  .where({ status: "pending" })
+  .stream({
+    flushMs?:      number,                   // batch flush delay in ms (default: 24)
+    maxBatchSize?: number,                   // max changes per flush (default: 200)
+    insertAt?:     "start" | "end",          // where new docs land (default: "end")
+    maxDocs?:      number,                   // cap the local snapshot size
+    sort?:         (a: T, b: T) => number,   // comparator applied after each flush
+    idField?:      string,                   // identity field name (default: "id")
+    getId?:        (doc: T) => string,       // custom id extractor
+  });
+
+// Subscribe to changes
+const off = stream.listen((docs, meta) => {
+  console.log(meta.reason, meta.version, docs.length);
+  // meta.reason: "snapshot" | "change-batch"
+  // meta.ready:  true after the first snapshot arrives
+});
+
+// Read the current snapshot without subscribing
+const current = stream.getSnapshot();
+
+// Remove a specific listener (does not close the stream)
+off();
+
+// Close the stream and release the WebSocket subscription
+stream.close();
+```
+
+### `.asStore(options?)` — framework-agnostic external store
+
+Returns an `AdminCollectionExternalStore<T>` compatible with React `useSyncExternalStore` or any subscribe/getSnapshot pattern:
+
+```typescript
+const store = admin.live()
+  .collection("orders")
+  .asStore({ flushMs: 50 });
+
+// React
+import { useSyncExternalStore } from "react";
+const orders = useSyncExternalStore(store.subscribe, store.getSnapshot);
+
+// Or directly
+const unsub = store.subscribe(() => {
+  console.log(store.getSnapshot());
+});
+
+store.close(); // release when done
+```
+
+### Realtime query builder parity
+
+The same query builder surface (`where`, `orderBy`, `join`, `limit`, etc.) is available on `admin.live().collection(...)` just like on `admin.db().collection(...)`.
+
+---
+
+## Security rules
 
 Once a client calls `flare.auth(token)`, the FlareServer socket has:
 
@@ -219,8 +358,6 @@ auth.uid   = the uid you passed to createCustomToken()
 auth.role  = "user" | "admin" | "anon"
 ```
 
-Use these in your security rules:
-
 ```json
 {
   "users":    { ".read": "auth != null",          ".write": "auth.uid == $docId" },
@@ -240,129 +377,166 @@ const adminB = connectApp({ serverUrl, appId: "app-b", adminKey: "..." }, "b");
 
 const tokenA = await getApp("a").auth().createCustomToken(userId);
 const tokenB = await getApp("b").auth().createCustomToken(userId);
-```
-
-## Admin-Only Auth Join Field Control
 
-Auth-user joins in admin SDK default to full fields.
-
-Use `allowSensitiveAuthUserFields(false)` per query when you want public-profile-only output:
-
-```typescript
-const safeBoards = await admin.db()
-  .collection("boards")
-  .join("users", { source: "team.uid", target: "id", as: "team" })
-  .allowSensitiveAuthUserFields(false)
-  .get();
+disconnectAllApps();
 ```
 
-Important:
-- This option is admin-only.
-- Normal client/system query paths cannot enable sensitive auth-user fields.
-
-## Data Mapper (Admin)
+---
 
-You can pass `dataMapper` in `connectApp(...)` to shape inbound data in admin SDK reads.
+## Data Mapper
 
-Mapping rules:
-- Base collection rows use the mapper key matching the collection name.
-- Join payload rows use the mapper key matching join `as`.
+Pass `dataMapper` in `connectApp(...)` to shape inbound data. Keys match collection names or join aliases (`as`).
 
 ```typescript
 const admin = connectApp({
   serverUrl: process.env.FLARE_URL!,
-  appId: process.env.FLARE_APP_ID!,
-  adminKey: process.env.FLARE_ADMIN_KEY!,
+  appId:     process.env.FLARE_APP_ID!,
+  adminKey:  process.env.FLARE_ADMIN_KEY!,
   dataMapper: {
     boards: (row) => ({
-      id: row.id,
-      name: row.name,
-      description: row.description,
+      id:        row.id,
+      name:      row.name,
       createdAt: new Date(row.createdAt ?? row.created_at),
     }),
     team: (row) => ({
-      id: row.id,
-      name: row.authMeta?.additionalParams?.name || "Unknown",
+      id:    row.id,
+      name:  row.authMeta?.additionalParams?.name || "Unknown",
       email: row.email,
-      createdAt: new Date(row.createdAt ?? row.created_at),
     }),
   },
 });
-
-const rows = await admin.db()
-  .collection("boards")
-  .where({ boardId: "123" })
-  .join("users", {
-    source: "team.uid",
-    target: "uid",
-    as: "team",
-  })
-  .get();
-
-// rows[*] is mapped by dataMapper.boards
-// rows[*].team[*] is mapped by dataMapper.team (join alias)
 ```
 
-Tip: for `as: "team"`, define `dataMapper.team`.
+For `join(..., { as: "team" })`, define `dataMapper.team`.
 
 ---
 
-## Query Builder Parity (Admin)
+## Storage API (S3-like)
 
-`admin.db().collection(...)` and `admin.connection().collection(...)` are aligned with the client-style query builder API.
-
-### Supported filter helpers
+```typescript
+import { connectApp, AdminStorageSignedAction } from "@zuzjs/flare-admin";
 
-`where`, `and`, `or`, `in`, `andIn`, `orIn`, `notIn`, `andNotIn`, `orNotIn`, `arrayContains`, `andArrayContains`, `orArrayContains`, `arrayContainsAny`, `andArrayContainsAny`, `orArrayContainsAny`, `some`, `andSome`, `orSome`, `like`, `andLike`, `orLike`, `notLike`, `andNotLike`, `orNotLike`, `exists`, `andExists`, `orExists`, `notExists`, `andNotExists`, `orNotExists`
+const storage = admin.storage();
 
-### Supported sort / cursor / aggregate helpers
+await storage.createBucket("reports");
 
-`latest`, `newest`, `oldest`, `orderBy`, `limit`, `offset`, `startAt`, `startAfter`, `endAt`, `endBefore`, `count`, `sum`, `avg`, `min`, `max`, `distinct`, `groupBy`, `having`, `select`, `distinctField`, `vectorSearch`
+await storage.putObject({
+  bucket:      "reports",
+  key:         "weekly/summary.json",
+  body:        Buffer.from(JSON.stringify({ ok: true })),
+  contentType: "application/json",
+  encrypt:     true,
+});
 
-### Supported join helpers
+const meta       = await storage.headObject({ bucket: "reports", key: "weekly/summary.json" });
+const downloaded = await storage.getObject({ bucket: "reports", key: "weekly/summary.json", decrypt: true });
 
-`join`, `Join`, `joinNested`, `JoinNested`, `withRelation`
+await storage.deleteObjects({ bucket: "reports", keys: ["weekly/summary.json"] });
+```
 
-Example:
+### Signed URLs
 
 ```typescript
-const rows = await admin.db()
-  .collection("boards")
-  .where({ uid: userId })
-  .orSome("team", { uid: userId })
-  .join("lists", { source: "id", target: "boardId", as: "lists" })
-  .join("users", { source: "team.uid", target: "id", as: "teamMembers" })
-  .joinNested("lists", "cards", { source: "id", target: "listId", as: "cards" })
-  .withRelation("team.uid->users.id as collaborators")
-  .orderBy("updatedAt", "desc")
-  .limit(20)
-  .get();
+const signedUpload = await admin.createSignedUrl({
+  bucket:           "reports",
+  key:              "uploads/big-video.mp4",
+  action:           AdminStorageSignedAction.Upload,
+  expiresInSeconds: 300,
+  contentType:      "video/mp4",
+  encrypt:          true,
+});
+
+await fetch(signedUpload.url, {
+  method:  signedUpload.method,
+  headers: { "Content-Type": "video/mp4" },
+  body:    videoBuffer,
+});
+
+const signedDownload = await admin.createSignedUrl({
+  bucket:           "reports",
+  key:              "uploads/big-video.mp4",
+  action:           AdminStorageSignedAction.Download,
+  expiresInSeconds: 300,
+  decrypt:          true,
+  allowedOrigins:   ["https://app.example.com"],
+});
 ```
 
-### Realtime parity
+Notes:
+- `forceDownload` and `embedOnly` are mutually exclusive.
+- `allowedOrigins` defaults to `['*']` if omitted.
 
-The same query builder surface is available on socket subscriptions:
+### Direct download helpers
 
 ```typescript
-const stop = admin.connection()
-  .collection("boards")
-  .where({ uid: userId })
-  .join("lists", { source: "id", target: "boardId", as: "lists" })
-  .onSnapshot((event) => {
-    console.log(event.type, event.data);
-  });
+const directUrl = await admin.getObjectUrl({
+  bucket:           "reports",
+  key:              "weekly/summary.json",
+  expiresInSeconds: 120,
+  allowedOrigins:   ["*"],
+});
+
+const triggered = await admin.downloadObject({
+  bucket:         "reports",
+  key:            "weekly/summary.json",
+  filename:       "summary.json",
+  forceDownload:  true,
+  allowedOrigins: ["https://app.example.com"],
+});
 ```
 
-### Debugging structured query output
+### Storage rules
+
+```txt
+service zuz.storage {
+  match /storage/{bucket}/objects {
+    match /{document=**} {
+      allow read: if auth != null;
+
+      allow write: if auth != null
+        && requestData.storage.usage.storageBytes + requestData.size
+           <= requestData.storage.plan.storageBytes;
+
+      allow delete: if auth != null;
+    }
+  }
+}
+```
 
-Both DB and realtime collection references provide `getRawQuery()`:
+### External AWS SDK from Flare `/aws` config
 
 ```typescript
-const raw = admin.db()
-  .collection("boards")
-  .where({ uid: userId })
-  .withRelation("team.uid->users.id as collaborators")
-  .getRawQuery();
+import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
 
-console.log(raw.collection, raw.query);
+const aws = await admin.storage().awsConfig("storage-server-id");
+
+const s3 = new S3Client({
+  endpoint:       aws.endpoint,
+  region:         aws.region,
+  forcePathStyle: Boolean(aws.forcePathStyle),
+  credentials: {
+    accessKeyId:     aws.accessKeyId,
+    secretAccessKey: aws.secretAccessKey,
+  },
+});
+
+await s3.send(new PutObjectCommand({
+  Bucket:      aws.bucket,
+  Key:         `${aws.prefix ?? ""}manual/test.txt`,
+  Body:        "hello",
+  ContentType: "text/plain",
+}));
+```
+
+---
+
+## Push Notifications
+
+```typescript
+await admin.notifications().send({
+  uid:   "user_123",
+  title: "Hello",
+  body:  "Your order shipped!",
+  data:  { orderId: "abc" },
+});
 ```