@zuzjs/flare-admin 0.1.5 → 0.1.7

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.
+
+### `disconnectApp(name?)`
+
+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()`
 
-### `auth(name?)`
+Close the WebSocket connection on a specific app instance. Safe to call multiple times.
 
-Shorthand for `getApp(name).auth()`.
+```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,75 +199,105 @@ 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
+---
 
-{
-  "appId": "my-app",
-  "uid": "user_123",
-  "role": "user",
-  "ttlSeconds": 300
-}
-```
+## Database
 
-```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"
-  }
-}
+```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();
 ```
 
----
+### Query Builder
 
-## Security rules on the server
+`admin.db().collection(...)` supports the full structured query API:
 
-Once a client calls `flare.auth(token)`, the FlareServer socket has:
+**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`
 
-```
-auth.uid   = the uid you passed to createCustomToken()
-auth.role  = "user" | "admin" | "anon"
-```
+**Sort / cursor / aggregate:** `latest`, `newest`, `oldest`, `orderBy`, `limit`, `offset`, `startAt`, `startAfter`, `endAt`, `endBefore`, `count`, `sum`, `avg`, `min`, `max`, `distinct`, `groupBy`, `having`, `select`, `distinctField`, `vectorSearch`
 
-Use these in your security rules:
+**Joins:** `join`, `Join`, `joinNested`, `JoinNested`, `withRelation`
 
-```json
-{
-  "users":    { ".read": "auth != null",          ".write": "auth.uid == $docId" },
-  "posts":    { ".read": "true",                  ".write": "auth != null" },
-  "settings": { ".read": "auth != null",          ".write": "auth.role == 'admin'" },
-  "*":        { ".read": "false",                 ".write": "false" }
-}
+```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();
 ```
 
----
+### Bulk Writes (Memory Efficient)
 
-## Multi-tenant / multiple apps
+`addMany`, `updateMany`, and id-based `deleteMany` run in bounded chunks so large datasets can be processed with controlled memory usage.
 
 ```typescript
-const adminA = connectApp({ serverUrl, appId: "app-a", adminKey: "..." }, "a");
-const adminB = connectApp({ serverUrl, appId: "app-b", adminKey: "..." }, "b");
+const users = admin.db().collection<{ name: string; plan?: string }>("users");
+
+const addResult = await users.addMany(
+  [{ name: "Alice" }, { name: "Bob" }],
+  {
+    batchSize: 500,
+    concurrency: 8,
+    onProgress: (p) => {
+      console.log("addMany", p.processed, p.total, p.percent);
+    },
+  },
+);
+
+const updateResult = await users.updateMany(
+  [
+    { id: "user_1", data: { plan: "pro" } },
+    { id: "user_2", data: { plan: "team" } },
+  ],
+  { continueOnError: true },
+);
+
+// Delete specific ids with progress
+const deleteByIdsResult = await users.deleteMany(["user_3", "user_4"], {
+  onProgress: (p) => console.log("deleteMany(ids)", p.processed, p.total),
+});
 
-const tokenA = await getApp("a").auth().createCustomToken(userId);
-const tokenB = await getApp("b").auth().createCustomToken(userId);
+// Existing query-based deleteMany remains available
+const deletedByQueryCount = await admin.db()
+  .collection("users")
+  .where({ plan: "free" })
+  .deleteMany();
+
+console.log({ addResult, updateResult, deleteByIdsResult, deletedByQueryCount });
 ```
 
-## Admin-Only Auth Join Field Control
+```typescript
+// Stream input from an async source (best for huge datasets)
+async function* rows() {
+  for (let i = 0; i < 1_000_000; i += 1) {
+    yield { name: `user-${i}` };
+  }
+}
+
+await admin.db().collection("users").addMany(rows(), { batchSize: 1000, concurrency: 4 });
+```
 
-Auth-user joins in admin SDK default to full fields.
+### `allowSensitiveAuthUserFields(false)`
 
-Use `allowSensitiveAuthUserFields(false)` per query when you want public-profile-only output:
+Auth-user joins default to full fields. Pass `false` to restrict to public-profile-only output:
 
 ```typescript
 const safeBoards = await admin.db()
@@ -256,195 +307,236 @@ const safeBoards = await admin.db()
   .get();
 ```
 
-Important:
-- This option is admin-only.
-- Normal client/system query paths cannot enable sensitive auth-user fields.
+### `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);
+```
 
-## Data Mapper (Admin)
+---
 
-You can pass `dataMapper` in `connectApp(...)` to shape inbound data in admin SDK reads.
+## Realtime
 
-Mapping rules:
-- Base collection rows use the mapper key matching the collection name.
-- Join payload rows use the mapper key matching join `as`.
+### `admin.live().collection(...).onSnapshot(cb)`
+
+Single-snapshot subscription — fires once on the initial data load, then auto-unsubscribes:
 
 ```typescript
-const admin = connectApp({
-  serverUrl: process.env.FLARE_URL!,
-  appId: process.env.FLARE_APP_ID!,
-  adminKey: process.env.FLARE_ADMIN_KEY!,
-  dataMapper: {
-    boards: (row) => ({
-      id: row.id,
-      name: row.name,
-      description: row.description,
-      createdAt: new Date(row.createdAt ?? row.created_at),
-    }),
-    team: (row) => ({
-      id: row.id,
-      name: row.authMeta?.additionalParams?.name || "Unknown",
-      email: row.email,
-      createdAt: new Date(row.createdAt ?? row.created_at),
-    }),
-  },
+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
 });
 
-const rows = await admin.db()
-  .collection("boards")
-  .where({ boardId: "123" })
-  .join("users", {
-    source: "team.uid",
-    target: "uid",
-    as: "team",
-  })
-  .get();
+// Read the current snapshot without subscribing
+const current = stream.getSnapshot();
 
-// rows[*] is mapped by dataMapper.boards
-// rows[*].team[*] is mapped by dataMapper.team (join alias)
+// Remove a specific listener (does not close the stream)
+off();
+
+// Close the stream and release the WebSocket subscription
+stream.close();
 ```
 
-Tip: for `as: "team"`, define `dataMapper.team`.
+### `.asStore(options?)` — framework-agnostic external store
 
----
+Returns an `AdminCollectionExternalStore<T>` compatible with React `useSyncExternalStore` or any subscribe/getSnapshot pattern:
 
-## Query Builder Parity (Admin)
+```typescript
+const store = admin.live()
+  .collection("orders")
+  .asStore({ flushMs: 50 });
 
-`admin.db().collection(...)` and `admin.connection().collection(...)` are aligned with the client-style query builder API.
+// React
+import { useSyncExternalStore } from "react";
+const orders = useSyncExternalStore(store.subscribe, store.getSnapshot);
 
-### Supported filter helpers
+// Or directly
+const unsub = store.subscribe(() => {
+  console.log(store.getSnapshot());
+});
 
-`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`
+store.close(); // release when done
+```
 
-### Supported sort / cursor / aggregate helpers
+### Realtime query builder parity
 
-`latest`, `newest`, `oldest`, `orderBy`, `limit`, `offset`, `startAt`, `startAfter`, `endAt`, `endBefore`, `count`, `sum`, `avg`, `min`, `max`, `distinct`, `groupBy`, `having`, `select`, `distinctField`, `vectorSearch`
+The same query builder surface (`where`, `orderBy`, `join`, `limit`, etc.) is available on `admin.live().collection(...)` just like on `admin.db().collection(...)`.
 
-### Supported join helpers
+---
 
-`join`, `Join`, `joinNested`, `JoinNested`, `withRelation`
+## Security rules
 
-Example:
+Once a client calls `flare.auth(token)`, the FlareServer socket has:
 
-```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();
+```
+auth.uid   = the uid you passed to createCustomToken()
+auth.role  = "user" | "admin" | "anon"
+```
+
+```json
+{
+  "users":    { ".read": "auth != null",          ".write": "auth.uid == $docId" },
+  "posts":    { ".read": "true",                  ".write": "auth != null" },
+  "settings": { ".read": "auth != null",          ".write": "auth.role == 'admin'" },
+  "*":        { ".read": "false",                 ".write": "false" }
+}
 ```
 
-### Realtime parity
+---
 
-The same query builder surface is available on socket subscriptions:
+## Multi-tenant / multiple apps
 
 ```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 adminA = connectApp({ serverUrl, appId: "app-a", adminKey: "..." }, "a");
+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);
+
+disconnectAllApps();
 ```
 
-### Debugging structured query output
+---
 
-Both DB and realtime collection references provide `getRawQuery()`:
+## Data Mapper
 
-```typescript
-const raw = admin.db()
-  .collection("boards")
-  .where({ uid: userId })
-  .withRelation("team.uid->users.id as collaborators")
-  .getRawQuery();
+Pass `dataMapper` in `connectApp(...)` to shape inbound data. Keys match collection names or join aliases (`as`).
 
-console.log(raw.collection, raw.query);
+```typescript
+const admin = connectApp({
+  serverUrl: process.env.FLARE_URL!,
+  appId:     process.env.FLARE_APP_ID!,
+  adminKey:  process.env.FLARE_ADMIN_KEY!,
+  dataMapper: {
+    boards: (row) => ({
+      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",
+      email: row.email,
+    }),
+  },
+});
 ```
 
+For `join(..., { as: "team" })`, define `dataMapper.team`.
+
+---
+
 ## Storage API (S3-like)
 
 ```typescript
 import { connectApp, AdminStorageSignedAction } from "@zuzjs/flare-admin";
 
-const admin = connectApp({
-  serverUrl: process.env.FLARE_URL!,
-  appId: process.env.FLARE_APP_ID!,
-  adminKey: process.env.FLARE_ADMIN_KEY!,
-});
-
 const storage = admin.storage();
 
 await storage.createBucket("reports");
 
 await storage.putObject({
-  bucket: "reports",
-  key: "weekly/summary.json",
-  body: Buffer.from(JSON.stringify({ ok: true })),
+  bucket:      "reports",
+  key:         "weekly/summary.json",
+  body:        Buffer.from(JSON.stringify({ ok: true })),
   contentType: "application/json",
-  encrypt: true,
+  encrypt:     true,
 });
 
-const meta = await storage.headObject({
-  bucket: "reports",
-  key: "weekly/summary.json",
-});
+const meta       = await storage.headObject({ bucket: "reports", key: "weekly/summary.json" });
+const downloaded = await storage.getObject({ bucket: "reports", key: "weekly/summary.json", decrypt: true });
 
-const downloaded = await storage.getObject({
-  bucket: "reports",
-  key: "weekly/summary.json",
-  decrypt: true,
-});
+await storage.deleteObjects({ bucket: "reports", keys: ["weekly/summary.json"] });
+```
 
-const signedDownload = await admin.createSignedUrl({
-  bucket: "reports",
-  key: "weekly/summary.json",
-  action: AdminStorageSignedAction.Download,
-  expiresInSeconds: 180,
-  forceDownload: true,
-  allowedOrigins: ["https://app.example.com"],
-  embedOnly: false,
+### Signed URLs
+
+```typescript
+const signedUpload = await admin.createSignedUrl({
+  bucket:           "reports",
+  key:              "uploads/big-video.mp4",
+  action:           AdminStorageSignedAction.Upload,
+  expiresInSeconds: 300,
+  contentType:      "video/mp4",
+  encrypt:          true,
 });
 
-await storage.deleteObjects({
-  bucket: "reports",
-  keys: ["weekly/summary.json"],
+await fetch(signedUpload.url, {
+  method:  signedUpload.method,
+  headers: { "Content-Type": "video/mp4" },
+  body:    videoBuffer,
 });
 
-console.log(meta.size, downloaded.contentBase64, signedDownload.url);
+const signedDownload = await admin.createSignedUrl({
+  bucket:           "reports",
+  key:              "uploads/big-video.mp4",
+  action:           AdminStorageSignedAction.Download,
+  expiresInSeconds: 300,
+  decrypt:          true,
+  allowedOrigins:   ["https://app.example.com"],
+});
 ```
 
-Direct signed-download helpers:
+Notes:
+- `forceDownload` and `embedOnly` are mutually exclusive.
+- `allowedOrigins` defaults to `['*']` if omitted.
+
+### Direct download helpers
 
 ```typescript
 const directUrl = await admin.getObjectUrl({
-  bucket: "reports",
-  key: "weekly/summary.json",
+  bucket:           "reports",
+  key:              "weekly/summary.json",
   expiresInSeconds: 120,
-  allowedOrigins: ["*"],
+  allowedOrigins:   ["*"],
 });
 
 const triggered = await admin.downloadObject({
-  bucket: "reports",
-  key: "weekly/summary.json",
-  filename: "summary.json",
-  forceDownload: true,
+  bucket:         "reports",
+  key:            "weekly/summary.json",
+  filename:       "summary.json",
+  forceDownload:  true,
   allowedOrigins: ["https://app.example.com"],
 });
-
-console.log(directUrl, triggered.triggered);
 ```
 
-## App-Level Storage Rules (Samples)
-
-Use `service zuz.storage` rules to enforce per-app policy on top of platform limits.
-
-Example 1: Authenticated read, quota-aware write
+### Storage rules
 
 ```txt
 service zuz.storage {
@@ -454,9 +546,7 @@ service zuz.storage {
 
       allow write: if auth != null
         && requestData.storage.usage.storageBytes + requestData.size
-           <= requestData.storage.plan.storageBytes
-        && requestData.storage.usage.bandwidthBytes + requestData.size
-           <= requestData.storage.plan.bandwidthBytes;
+           <= requestData.storage.plan.storageBytes;
 
       allow delete: if auth != null;
     }
@@ -464,115 +554,40 @@ service zuz.storage {
 }
 ```
 
-Example 2: Pro-plan write + admin override
-
-```txt
-service zuz.storage {
-  match /storage/{bucket}/objects {
-    match /{document=**} {
-      allow read: if auth != null;
-
-      allow write: if auth != null
-        && (
-          auth.role == 'admin'
-          || auth.claims.plan == 'pro'
-        )
-        && requestData.storage.usage.storageBytes + requestData.size
-           <= requestData.storage.plan.storageBytes
-        && requestData.storage.usage.bandwidthBytes + requestData.size
-           <= requestData.storage.plan.bandwidthBytes;
-
-      allow delete: if auth != null
-        && (auth.role == 'admin' || auth.claims.plan == 'pro');
-    }
-  }
-}
-```
-
-Apply rules with admin API:
-
-```http
-POST /v1/apps/{appId}/admin/storage/rules
-Authorization: Bearer FA_ADMIN_xxxxxxxxxxxx
-Content-Type: application/json
-
-{
-  "rulesDsl": "service zuz.storage { match /storage/{bucket}/objects { match /{document=**} { allow read: if auth != null; } } }"
-}
-```
-
-Tip: map users to app-level plans through app settings (`storagePlans`, `storageUserPlans`, `storageDefaultPlanId`) so `requestData.storage.plan.*` resolves correctly at runtime.
-
-## Storage Signed URLs
-
-Create signed URLs for first-party upload/download/delete/edit without exposing admin key to file-transfer clients.
-
-```typescript
-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,
-  forceDownload: false,
-  allowedOrigins: ["https://app.example.com"],
-  embedOnly: true,
-});
-
-const bytes = await fetch(signedDownload.url, { method: signedDownload.method }).then((r) => r.arrayBuffer());
-
-console.log("expiresAt", signedDownload.expiresAt, "ttl", signedDownload.expiresInSeconds);
-```
-
-Notes:
-- `token` (for example `st_...`) is a signed ticket identifier; expiry is returned as `expiresAt`/`expiresInSeconds`.
-- `forceDownload` and `embedOnly` are mutually exclusive.
-- `allowedOrigins` defaults to `['*']` if omitted.
-- `downloadObject(...)` triggers a browser click only when `document` is available. In server runtimes, it returns `{ ok, url, filename, triggered: false }` so you can redirect, proxy, or return the signed URL.
-
-## External AWS SDK Init From Flare `/aws` Config
+### External AWS SDK from Flare `/aws` config
 
 ```typescript
 import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
-import { connectApp } from "@zuzjs/flare-admin";
-
-const admin = connectApp({
-  serverUrl: process.env.FLARE_URL!,
-  appId: process.env.FLARE_APP_ID!,
-  adminKey: process.env.FLARE_ADMIN_KEY!,
-});
 
 const aws = await admin.storage().awsConfig("storage-server-id");
 
 const s3 = new S3Client({
-  endpoint: aws.endpoint,
-  region: aws.region,
+  endpoint:       aws.endpoint,
+  region:         aws.region,
   forcePathStyle: Boolean(aws.forcePathStyle),
   credentials: {
-    accessKeyId: aws.accessKeyId,
+    accessKeyId:     aws.accessKeyId,
     secretAccessKey: aws.secretAccessKey,
   },
 });
 
 await s3.send(new PutObjectCommand({
-  Bucket: aws.bucket,
-  Key: `${aws.prefix ?? ""}manual/admin-test.txt`,
-  Body: "hello from admin external sdk",
+  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" },
+});
+```