npx --yes nukebase start

# What it does, in order:
#   1. signs you in — a browser tab opens, click Confirm once
#      (no account yet? it creates one on the free plan, no card)
#   2. creates the project and puts it online
#   3. downloads it into this folder and runs npm install
#
# Name and size up front if you like:
npx --yes nukebase start myapp 256mb      # sizes: 128mb, 256mb, 512mb, 1gb

node server/database.js      # run the whole thing locally at http://127.0.0.1:3000

npx --yes nukebase push            # upload your changes to the live server and restart it
npx --yes nukebase pull            # download the live server's code to this folder
npx --yes nukebase logs --follow   # stream the live server's output
npx --yes nukebase start           # inside a project: restart it (also resumes a paused one)

# Tired of typing npx? Install once per computer and drop the prefix:
npm i -g nukebase
nukebase push

module.exports = ({
  // Data
  get, set, update, increment, remove, query, data,
  // Files
  getFile, setFile, removeFile, listFiles, fileStat, fileUrlFor, FILES_DIR,
  // Extension points
  addDbTrigger, addFileTrigger, addCallable, addConnectionTrigger,
  // Server
  addDomain, startDB, checkAuth, withBody, hashToken, generateRequestId
}) => {

  const path = require("path");

  const nukebase = addDomain({
    authPath: ["users"],
    host: "127.0.0.1", // optional - defaults to "127.0.0.1"
    port: 3000 // optional - defaults to 3000
  });

  nukebase.app.serveStatic("/*", path.join(__dirname, "../public"),
    (res, req) => { return true; }
  );

  startDB(nukebase);
}

// Basic setup - pass the domain object to startDB
const nukebase = addDomain({
  authPath: ["users"],
  host: "127.0.0.1", // optional
  port: 3000 // optional
});

startDB(nukebase);

nukebase env push          # make the hosted environment equal to ./.env, then restart
nukebase env list          # variable names currently set (add --show to print values)

// Serve everything in ../public at the root
nukebase.app.serveStatic("/*", path.join(__dirname, "../public"));

// Serve a private directory (no auth callback = open access)
nukebase.app.serveStatic("/assets/*", path.join(__dirname, "assets"));

// Only logged-in users can access /private/*
nukebase.app.serveStatic("/private/*", path.join(__dirname, "../private"),
  async (res, req) => {
    return Boolean(req.uid);
  }
);

// Admins only
nukebase.app.serveStatic("/admin/*", path.join(__dirname, "../admin"),
  async (res, req) => {
    return req.claims?.role === "admin";
  }
);

// Durable set — waits for fsync before resolving
await set(["users", "john", "email"], "john@example.com", "root", { durable: true });

// Durable update
await update(["users", "john"], { lastLogin: Date.now() }, "root", { durable: true });

// Durable remove
await remove(["users", "john", "tempData"], "root", { durable: true });

// Client (async)
const user = await get(["users", "john"]);
console.log(user.data);

// Server (sync)
const user = get(["users", "john"]);
console.log(user.data);

// Integer segment → array container is auto-created
set(["messages", 0], "hi");
// Result: { messages: ["hi"] }

// String segment → object container is auto-created
set(["messages", "0"], "hi");
// Result: { messages: { "0": "hi" } }

// Mixed: a nested integer segment creates an array inside an object
set(["users", "matt", "scores", 0], 100);
// Result: { users: { matt: { scores: [100] } } }

// Set a complete object
set(["users", "john"], { name: "John Doe", age: 32 }).then(response => {
    console.log("User created successfully");
});

// Set a single value
set(["users", "john", "email"], "john@example.com").then(response => {
    console.log(response);
});

// Auto-creates parent objects - even if 'users' doesn't exist
set(["users", "alice", "profile", "preferences", "theme"], "dark").then(response => {
    // Creates: { users: { alice: { profile: { preferences: { theme: "dark" } } } } }
    console.log("Theme set with auto-created parent objects");
});

// Get a single user
get(["users", "john"]).then(response => {
    console.log(response.data);  // User data
});

// Get entire collection
get(["users"]).then(response => {
    const users = response.data;
    // Process users...
});

// Update specific fields
update(["users", "john"], {
    lastLogin: Date.now(),
    loginCount: 42
}).then(response => {
    console.log(response);
});

// Update a single property
update(["users", "john", "status"], "online").then(response => {
    console.log(response);
});

// Auto-creates missing parent objects
update(["settings", "app", "notifications", "email"], true).then(response => {
    // If 'settings' doesn't exist, creates the entire path
    console.log("Setting created with auto-generated parents");
});

// Add 1 to a single counter
const r = await increment(["posts", "p1", "views"], 1);
console.log(r.data);  // 43 — the RESULTING value, so no follow-up get() is needed

// Negative deltas subtract
await increment(["users", "john", "credits"], -10);

// A nested object of numbers is applied as ONE all-or-nothing write
const r2 = await increment(["stats", "2026-08"], {
  views: 1,
  bandwidth: 84213,
  byCountry: { US: 1 }
});
console.log(r2.data);
// { views: 1291, bandwidth: 9930118, byCountry: { US: 402 } }
// Every field resolved to its new absolute value

// Missing values start at 0 — no need to seed a counter before using it
await increment(["stats", "brand-new-key"], 5);   // → 5

// Durable, like the other writes
await increment(["ledger", "balance"], 250, "root", { durable: true });

module.exports = {
  "accounts": {
    "$id": {
      "write": "$id == admin.uid",
      // Blocks any increment that would take the balance negative
      "balance": { "validate": "newData >= 0" },
      // Caps how much a single increment may add
      "score":   { "validate": "newData - data <= 10" }
    }
  }
};

// Remove a user
remove(["users", "john"]).then(response => {
    console.log("User deleted");
});

// Remove a specific field
remove(["users", "john", "temporaryToken"]).then(response => {
    console.log(response);
});

module.exports = ({ data, get, set, ... }) => {

  // Direct read — access the raw database object
  const userName = data.users?.john?.name;  // "John"
  const allUsers = data.users;  // { john: {...}, alice: {...} }

  // Compared to using get():
  const user = get(["users", "john"]);
  console.log(user.data.name);  // "John"
};

// Basic equality check
query({
    path: ["users"],
    query: "child.age == 32"
}).then(response => {
    console.log(response.data);  // All users who are exactly 32
});

// Using comparison operators
query({
    path: ["products"],
    query: "child.price < 50"
}).then(response => {
    console.log(response.data);  // All products under $50
});

// Compound conditions with AND (&&)
query({
    path: ["products"],
    query: "child.price < 100 && child.category == 'electronics'"
}).then(response => {
    console.log(response.data);  // Affordable electronics
});

// Compound conditions with OR (||)
query({
    path: ["users"],
    query: "child.role == 'admin' || child.role == 'moderator'"
}).then(response => {
    console.log(response.data);  // All admins and moderators
});

// Text search with includes()
query({
    path: ["posts"],
    query: "child.title.includes('JavaScript')"
}).then(response => {
    console.log(response.data);  // Posts with "JavaScript" in the title
});

// Checking nested properties with childPath
query({
    path: ["users"],
    childPath: ["profile", "location"],
    query: "child == 'New York'"  // child refers to the location value
}).then(response => {
    // Returns: { matt123: { profile: { location: "New York" } } }
    // `child` in the query is the value at childPath; the response wraps
    // that value back in the childPath structure to mirror the DB shape.
    console.log(response.data);
});

// Combining multiple conditions
query({
    path: ["orders"],
    query: "child.status == 'pending' && child.total > 100 && child.items.length > 2"
}).then(response => {
    console.log(response.data);  // Large pending orders with multiple items
});

// Checking if a property exists
query({
    path: ["users"],
    query: "child.premiumAccount == true"
}).then(response => {
    console.log(response.data);  // All premium users
});

// Using NOT operator
query({
    path: ["tasks"],
    query: "child.completed != true"
}).then(response => {
    console.log(response.data);  // All incomplete tasks
});

// Date comparisons (assuming timestamps)
query({
    path: ["events"],
    query: "child.date > " + Date.now()
}).then(response => {
    console.log(response.data);  // Future events
});

// WRONG — a shared collection with an ownership rule. The collection check
// runs once with $orderId unbound, so this returns nothing at all.
//   rules: { "orders": { "$orderId": { "read": "admin.uid == data.ownerId" } } }
query({ path: ["orders"], query: "child.status == 'open'" });

// RIGHT — give each user their own subtree, grant that, and query inside it.
//   rules: { "orders": { "$uid": { "read": "admin.uid == $uid" } } }
query({ path: ["orders", myUid], query: "child.status == 'open'" });

// Also fine — a genuinely public collection.
//   rules: { "posts": { "$postId": { "read": "true" } } }
query({ path: ["posts"], query: "child.published == true" });

// Top 10 posts by view count
const top = await query({
    path: ["posts"],
    query: "child.published == true",
    orderBy: ["views"],
    desc: true,
    limit: 10
});
// Read the results IN ORDER via response.order — a JSON object's key
// order is not something to depend on.
top.order.forEach(key => console.log(key, top.data[key].views));

// Order by a nested field
await query({
    path: ["products"],
    query: "true",
    orderBy: ["meta", "rating"],
    desc: true,
    limit: 20
});

// Order by record key (just omit orderBy)
await query({ path: ["messages"], query: "true", limit: 50 });

// Cursor pagination — the correct way to walk a large collection
let cursor;
for (;;) {
  const page = await query({
    path: ["events"],
    query: "true",
    orderBy: ["ts"],
    limit: 100,
    ...(cursor && { cursor })
  });
  page.order.forEach(k => handle(page.data[k]));
  if (!page.nextCursor) break;   // absent == you reached the end
  cursor = page.nextCursor;
}

// Offset pagination — simpler, but O(offset) to skip. Prefer a cursor
// for anything deep.
await query({ path: ["events"], query: "true", orderBy: ["ts"],
              startAt: 200, limit: 100 });

// Just the number
const c = await query({ path: ["users"], query: "child.active == true", count: true });
console.log(c.count);   // 8412   (c.data is null)

module.exports = {
  "posts": {
    // Two separate single-field indexes. The inner arrays are required —
    // ["views","createdAt"] would read as ONE nested path, not two indexes.
    "index": [["views"], ["createdAt"], ["meta", "rating"]],

    "$id": { "read": "true", "write": "admin.uid == data.authorId" }
  },

  "users": {
    "index": [["city"]],
    "$uid": { "read": "true" }
  }
};

// Data structure:
// {
//   users: {
//     matt123: {
//       public: { name: "Matt", age: 25, city: "NYC" },
//       private: { ssn: "123-45-6789", salary: 80000 }
//     },
//     john456: {
//       public: { name: "John", age: 30, city: "LA" },
//       private: { ssn: "987-65-4321", salary: 90000 }
//     }
//   }
// }

// Query WITHOUT childPath - queries full user objects
query({
    path: ["users"],
    query: "child.public.age > 21"
}).then(response => {
    console.log(response.data);
    // Returns: {
    //   matt123: { public: {...}, private: {...} },
    //   john456: { public: {...}, private: {...} }
    // }
    // You get FULL user objects including private data
});

// Query WITH childPath - queries only public portion.
// `child` inside the query refers to the data AT childPath ("public").
// The response value MIRRORS the database shape: each match is wrapped
// in the same childPath structure, so you can read it the same way you'd
// read the original tree.
query({
    path: ["users"],
    childPath: ["public"],
    query: "child.age > 21"  // child still refers to the "public" object
}).then(response => {
    console.log(response.data);
    // Returns: {
    //   matt123: { public: { name: "Matt", age: 25, city: "NYC" } },
    //   john456: { public: { name: "John", age: 30, city: "LA" } }
    // }
    // The "public" wrapper is preserved; "private" is not present because
    // the query never walked into it.
});

// Multiple childPath levels — wrapper is nested to match
query({
    path: ["users"],
    childPath: ["public", "address"],
    query: "child.city == 'NYC'"  // child refers to the "address" object
}).then(response => {
    console.log(response.data);
    // Returns: {
    //   matt123: { public: { address: { city: "NYC", state: "NY" } } }
    // }
    // Each childPath segment shows up in the response, in order.
});

// Use Case 1: Return a smaller payload
// childPath narrows what is READ and SENT, not what is PERMITTED. It is a
// shape and bandwidth tool, not an authorization one — see Query authorization.
query({
    path: ["users"],
    childPath: ["public"],
    query: "child.verified == true"
}).then(response => {
    // Only the "public" subtree is walked and returned. This does not grant
    // or deny anything: if the query is authorized at all, it is authorized
    // for every child at that path.
    displayPublicProfiles(response.data);
});

// Use Case 2: Performance - Return only needed data
// When clients only need profile info, not full user objects
query({
    path: ["users"],
    childPath: ["profile"],
    query: "child.country == 'USA'"
}).then(response => {
    // Smaller response payload, faster transmission
    renderUserProfiles(response.data);
});

// Use Case 3: Complex filtering on nested arrays
// Query specific nested collections
query({
    path: ["orders"],
    childPath: ["items"],
    query: "child.quantity > 5"
}).then(response => {
    // Returns: {
    //   order123: { items: { itemA: {quantity: 10, ...}, ... } }
    // }
    // The "items" wrapper is preserved so the result mirrors the DB shape.
    console.log("Orders with high-quantity items:", response.data);
});

// Use Case 4: Separating data concerns
// Different parts of your app query different data sections
query({
    path: ["products"],
    childPath: ["inventory"],
    query: "child.stock < 10"
}).then(response => {
    // Warehouse dashboard only needs inventory data
    showLowStockAlert(response.data);
});

// Data structure:
// users.matt123 = { scores: [42, 87, 99], name: "Matt" }
// users.john456 = { scores: [10, 20, 30], name: "John" }

// childPath ending at index 0 of "scores"
query({
    path: ["users"],
    childPath: ["scores", 0],
    query: "child > 25"   // child refers to the integer at scores[0]
}).then(response => {
    console.log(response.data);
    // Returns: {
    //   matt123: { scores: [42] }
    // }
    // The wrapper preserves the array shape from the DB.
});

// childPath ending at index 1 of "scores"
query({
    path: ["users"],
    childPath: ["scores", 1],
    query: "child > 25"
}).then(response => {
    console.log(response.data);
    // Returns: {
    //   matt123: { scores: [null, 87] }
    // }
    // Index 1 is preserved. The leading slot is null because the query only
    // matched scores[1] — sparse-array slots become explicit nulls when JSON
    // is sent over the WebSocket. The matched value is still at index 1.
});

import createClient from './sdkmod.js';
const { getFile, setFile, listFiles, removeFile, fileUrl } = await createClient();

// Upload — body may be a Blob, File, ArrayBuffer, TypedArray or string
const picker = document.querySelector('input[type=file]');
const result = await setFile(["posts", "p1", "attachments", "hero.png"], picker.files[0], {
  onProgress: (fraction) => { bar.style.width = (fraction * 100) + '%'; }
});
// result → { status: "Success", size: 84213, type: "image/png",
//            name: "hero.png", path: ["posts","p1","attachments","hero.png"] }

// Download — resolves with a Blob
const blob = await getFile(["posts", "p1", "attachments", "hero.png"]);
img.src = URL.createObjectURL(blob);

// Or skip the download entirely and link straight to it.
// Rules still apply when the browser fetches the URL — this is a link, not a bypass.
img.src = fileUrl(["posts", "p1", "attachments", "hero.png"]);
// → "/_file/posts/p1/attachments/hero.png"

// List one directory level
const entries = await listFiles(["posts", "p1", "attachments"]);
// → [{ name: "hero.png", isDir: false, size: 84213, type: "image/png", mtime: 1770000000000 }, …]
// Names are relative — build a child path as [...path, entry.name]

// Delete. Directories need { recursive: true } so a mistyped path
// cannot take a whole tree with it.
await removeFile(["posts", "p1", "attachments", "hero.png"]);
await removeFile(["posts", "p1", "attachments"], { recursive: true });

const controller = new AbortController();
cancelBtn.onclick = () => controller.abort();

try {
  await setFile(["uploads", "big.zip"], file, {
    signal: controller.signal,
    onProgress: (p) => console.log(Math.round(p * 100) + '%')
  });
} catch (err) {
  if (err.name === 'AbortError') return;      // user cancelled
  switch (err.status) {
    case 403: alert("A rule refused this upload"); break;
    case 409: alert("A file with that name (differing only by case) already exists"); break;
    case 413: alert("File is too large"); break;
    case 429: alert("Too many uploads — slow down"); break;
    default:  alert("Upload failed: " + err.body);
  }
}

module.exports = ({ getFile, setFile, removeFile, listFiles,
                   fileStat, fileUrlFor, addFileTrigger, FILES_DIR, ... }) => {

  // Write. content may be a Buffer, TypedArray or string.
  const w = await setFile(["reports", "2026-08.csv"], csvString);
  // → { status: "Success", size: 4821, type: "text/csv", name: "2026-08.csv" }

  // Read. Resolves with a Buffer in .data.
  const r = await getFile(["reports", "2026-08.csv"]);
  // → { status: "Success", data: <Buffer>, name, size, type, mtime }
  // → { status: "Path not found", data: null }  if it isn't there

  // List one level.
  const l = await listFiles(["reports"]);
  // → { status: "Success", data: [{ name, isDir, size, type, mtime }, …] }
  // Capped at FILE_MAX_DIR_ENTRIES; a truncated listing sets .truncated = true

  // Delete. Directories require { recursive: true }.
  await removeFile(["reports", "2026-08.csv"]);
  await removeFile(["reports"], "root", { recursive: true });

  // Synchronous stat — no await, returns undefined if nothing is there.
  const st = fileStat(["reports", "2026-08.csv"]);
  // → { name, ext: ".csv", size, type, mtime, isDir: false }

  // Build the URL a client would fetch.
  fileUrlFor(["reports", "2026-08.csv"]);  // "/_file/reports/2026-08.csv"
};

module.exports = {
  "posts": {
    "$id": {
      "read":  "true",
      "write": "admin.uid == data.authorId",

      "attachments": {
        "fileRead":  "true",
        // A file rule reaching for a sibling RECORD must go through `root` —
        // `data` here is file-side state, not the post.
        "fileWrite": "admin.uid == root.posts[$id]?.authorId",
        "fileValidate": "file.size < 10 * 1024 * 1024 && file.type.startsWith('image/')"
      }
    }
  },

  "avatars": {
    "$uid": {
      "fileRead":  "true",
      "fileWrite": "admin.uid == $uid",
      "fileValidate": "file.size <= 2 * 1024 * 1024"
    }
  }
};

// app.js — the cost of an upload is the DELTA. An upload to a path that
// already holds a file REPLACES it, so it only costs the difference.
const d = (c) => c.file.size - (c.existing?.size ?? 0);

addFileTrigger("reserve", ["uploads"], (c) =>
  increment(["usage", c.path[1], "bytes"],  d(c)));

addFileTrigger("release", ["uploads"], (c) =>
  increment(["usage", c.path[1], "bytes"], -d(c)));

// Deletions give the space back.
addFileTrigger("remove", ["uploads"], (c) =>
  increment(["usage", c.path[1], "bytes"], -(c.existing?.size ?? 0)));

"uploads": {
  "$uid": {
    "fileRead":  "admin.uid == $uid",
    "fileWrite": "admin.uid == $uid",
    "fileValidate":
      "(root.usage?.[$uid]?.bytes ?? 0) + file.size - (data?.size ?? 0) <= 5e8"
  }
}

// These two rules are at the SAME LEVEL (both are direct children of the parent)
module.exports = {
  "pets": {
    "read": "true",  // Rule 1: Anyone can read pets
    "write": "admin.claims.role == 'petOwner'",  // Rule 2: Must be pet owner
    "validate": "newData.type == 'cat' || newData.type == 'dog'"  // Only cats/dogs
  },
  "$other": {  // ← This is at the SAME LEVEL as "pets" above
    "read": "admin.claims.role == 'admin'",  // Rule 3: Must be admin
    "write": "false",  // Rule 4: No writes allowed
    "validate": "newData != null"  // Not empty
  }
}

// When accessing "pets":
// Read: BOTH "true" AND "admin.claims.role == 'admin'" must pass → Fails for non-admins!
// Write: BOTH "admin.claims.role == 'petOwner'" AND "false" must pass → Always fails!
// Validate: ONLY the "pets" rule applies (most specific)

module.exports = {
  "users": {
    "$userId": {
      // Don't grant a blanket read at $userId — that grant cascades down
      // and would override the deeper email rule. Grant read on the
      // public-facing fields instead.
      "write": "admin.uid == $userId",   // Only the user can edit their profile
      "name":  { "read": "true" },       // Public
      "bio":   { "read": "true" },       // Public
      "email": { "read": "admin.uid == $userId" }  // Private — only the user
    }
  }
};

module.exports = {
  "store": {
    "write": "admin.claims.role == 'admin'",
    "products": {
      "write": "admin.claims.role == 'manager'",
      "$productId": {
        "write":    "admin.uid == data.ownerId",
        "validate": "newData.name && newData.price > 0"
      }
    }
  }
};

// Simple read rule
// Don't put "read": "true" at the $postId level — it would cascade and
// override the draft restriction. Grant read on the published fields only.
"posts": {
  "$postId": {
    "title": { "read": "true" },
    "body":  { "read": "true" },
    "draft": { "read": "admin.uid == root.posts[$postId]?.authorId" }  // Only the author. `data` here is the draft itself, so reach the post via root
  }
}

// Using variables in paths
"users": {
  "$userId": {
    "name":  { "read": "true" },                       // Public
    "email": { "read": "admin.uid == $userId" }        // Only the user can read their own email
  }
}

// Basic write rule
"posts": {
  "$postId": {
    "write": "admin.uid == data.authorId",  // Only author can edit
    "createdAt": {
      "write": "!data"  // Can only set createdAt when creating (no previous data)
    }
  }
}

// How write rules cascade along the target path
// (any rule along the path that returns true is sufficient)
"store": {
  "write": "false",  // Blocks writes that TARGET ["store"] directly
  "products": {
    "write": "admin.claims.role == 'manager'",  // Applies when writing AT ["store","products"] or deeper
    "$productId": {
      "write": "admin.uid == data.ownerId"      // Applies when writing AT ["store","products",<id>]
    }
  }
}

// What actually happens:
// set(["store"], ...)                      → only store.write applies        → DENIED
// set(["store","products"], ...)           → store.write OR store.products.write
//                                            → ALLOWED if user is a manager
// set(["store","products","abc"], ...)     → store.write OR store.products.write
//                                            OR store.products.$productId.write
//                                            → ALLOWED if manager OR uid == data.ownerId

// Simple field validation
"users": {
  "$userId": {
    "age": {
      "validate": "newData >= 13 && newData <= 120"
    },
    "email": {
      "validate": "newData.includes('@') && newData.includes('.')"
    }
  }
}

// Validating objects with required fields
"posts": {
  "$postId": {
    "validate": "newData.title && newData.content && newData.title.length <= 200"
  }
}

// Using data and newData to compare old and new values
"users": {
  "$userId": {
    "credits": {
      // Ensure credits can only increase, not decrease
      "validate": "newData >= data"
    }
  }
}

// Complex validation with multiple conditions
"products": {
  "$productId": {
    "validate": "newData.name && newData.price > 0 && newData.stock >= 0"
  }
}

// Example: update(["users", "john", "tags"], ["red", "blue", "green"])
// This generates paths:
// 1. ["users", "john", "tags"]     ← Entire array
// 2. ["users", "john", "tags", "0"] ← Element 0: "red"
// 3. ["users", "john", "tags", "1"] ← Element 1: "blue"
// 4. ["users", "john", "tags", "2"] ← Element 2: "green"

// METHOD 1: Validate the ENTIRE array
"users": {
  "$userId": {
    "tags": {
      // newData = entire array ["red", "blue", "green"]
      "validate": "Array.isArray(newData) && newData.length <= 5"
    }
  }
}

// METHOD 2: Validate EACH element using wildcard
"users": {
  "$userId": {
    "tags": {
      "$index": {  // $index matches "0", "1", "2", etc.
        // newData = individual element ("red", "blue", or "green")
        "validate": "typeof newData === 'string' && newData.length < 20"
      }
    }
  }
}

// METHOD 3: COMBINE both approaches
"users": {
  "$userId": {
    "tags": {
      // Validate array properties
      "validate": "Array.isArray(newData) && newData.length <= 5",
      "$index": {
        // Validate each element
        "validate": "typeof newData === 'string' && newData.length < 20"
      }
    }
  }
}

// Complex array validation with element uniqueness check
"users": {
  "$userId": {
    "favoriteColors": {
      "$index": {
        // Each color must be a valid hex code
        "validate": "typeof newData === 'string' && /^#[0-9A-F]{6}$/i.test(newData)"
      }
    }
  }
}

"posts": {
  "$id": {
    "read":  "true",
    "write": "admin.uid == data.authorId",

    "attachments": {
      "fileRead":  "true",                                    // download + list
      // A file rule reaching for a sibling RECORD must go through `root` —
      // `data` here is the stat of the file path, not the post.
      "fileWrite": "admin.uid == root.posts[$id]?.authorId",  // upload + delete
      "fileValidate":
        "file.size < 10 * 1024 * 1024 && file.type.startsWith('image/')"
    }
  }
}

module.exports = {
  "posts": {
    // A LIST of field paths, each itself an array. The inner arrays are
    // required: ["views","createdAt"] would read as one NESTED path
    // (child.views.createdAt), not two separate indexes.
    "index": [["views"], ["createdAt"], ["meta", "rating"]],

    "$id": { "read": "true", "write": "admin.uid == data.authorId" }
  }
};

// In a callable
addCallable("getProfile", (data, admin, sessionId) => {
  if (!admin.uid) return { status: "Failed", message: "Login required" };
  return get(["users", admin.uid]).data;
});

// In a connection trigger
addConnectionTrigger("open", (admin, sessionId) => {
  console.log("Connected:", admin.uid || "anonymous", "from", admin.ip);
});

// In a postWithBody handler (req.admin)
nukebase.app.postWithBody("/api/me", (res, req) => {
  if (!req.admin.uid) return res.send(JSON.stringify({ status: "Failed" }), "401 Unauthorized");
  res.send(JSON.stringify({ uid: req.admin.uid, claims: req.admin.claims }));
});

// In a raw post handler (manual checkAuth)
nukebase.app.post("/api/me-raw", (res, req) => {
  const admin = checkAuth(req, res);
  res.end(JSON.stringify({ uid: admin.uid }));
});

// In a security rule (rules.js)
module.exports = {
  "users": {
    "$userId": {
      "write": "admin.uid == $userId",
      "private": { "read": "admin.uid == $userId" }
    },
    "adminPanel": {
      "read": "admin.claims.role == 'admin'"
    }
  }
};

// Create a trigger for when a request is updated
addDbTrigger("update", ["requests", "$requestId"], function(context) {
  // The context object contains all relevant information about the change
  const beforeNotes = context.dataBefore?.notes;
  const afterNotes = context.dataAfter?.notes;
  // Replace "pizza" with pizza emoji
  const newNotes = afterNotes.replaceAll("pizza", "🍕");
  // Avoid infinite loop by checking if we already replaced
  if (newNotes === afterNotes) {
    return;
  }
  // Update the data with our modified version
  update(context.path, { notes: newNotes });
});

// React to orders being created. dataBefore is undefined when nothing existed
// at the order's path before this write — that is the "is this new?" test.
// Registering on "set" (not "update") also keeps this from refiring when the
// trigger's own update() call below runs.
addDbTrigger("set", ["orders", "$orderId"], function(context) {
  if (context.dataBefore === undefined && context.dataAfter) {
    const orderId = context.path[1];  // wildcard segment, filled in
    update(context.path, {
      status: "processing",
      processingStart: Date.now()
    });
  }
});

addCallable("getUsersCount", async function (data, admin, sessionId) {
  //get all users
  var res = get(["users"])
  //Count how many users
  count = Object.keys(res.data).length
  //return number
  return count
});

// When a client connects
addConnectionTrigger("open", function (admin, sessionId) {
    // Record session start time
    update(["sessions", admin.uid, sessionId], {
        start: Date.now()
    });
});

// When a client disconnects
addConnectionTrigger("close", function (admin, sessionId) {
    // Record session end time
    update(["sessions", admin.uid, sessionId], {
        end: Date.now()
    });
});

// postWithBody automatically parses the body AND runs checkAuth()
nukebase.app.postWithBody('/api/contact', (res, req) => {
  // req.admin is automatically populated by checkAuth()
  if (!req.admin.uid) {
    return res.send(JSON.stringify({ status: "Failed", message: "Not authenticated" }));
  }

  const { name, email, message } = req.body;

  // Save to database with the authenticated user's ID
  set(["contactForms", generateRequestId()], {
    name,
    email,
    message,
    userId: req.admin.uid,
    timestamp: Date.now()
  });

  res.send(JSON.stringify({ status: "Success" }));
});

// req object includes:
// req.admin    - Auth object from checkAuth() (always present)
// req.body     - Parsed request body
// req.host     - Request host header
// req.method   - HTTP method
// req.getHeader(name) - Get any request header
//
// req.admin includes (always present):
// req.admin.cookies   - Parsed cookies object
// req.admin.urlParams - Parsed query string parameters
// req.admin.referer, req.admin.userAgent, req.admin.ip, req.admin.url
//
// req.admin includes (only when authenticated):
// req.admin.uid, req.admin.username, req.admin.email, req.admin.token, req.admin.claims

nukebase.app.postWithBody('/api/import', (res, req) => {
  // req.body holds the parsed payload, up to 10 MB
  res.send(JSON.stringify({ status: "Success" }));
}, { maxBytes: 10 * 1024 * 1024 });

// Raw post — no automatic parsing, no req.admin
nukebase.app.post('/api/status', (res, req) => {
  // Must manually call checkAuth(req, res) to get auth info
  const auth = checkAuth(req, res);

  if (!auth.uid) {
    res.writeStatus("401 Unauthorized");
    return res.end(JSON.stringify({ status: "Failed", message: "Not authenticated" }));
  }

  res.end(JSON.stringify({
    status: "Success",
    user: auth.username,
    role: auth.claims.role
  }));
});

// Raw post only has access to raw uWebSockets methods:
// req.getHeader(name) - Get a request header
// req.getUrl()        - Get the URL path
// req.getQuery()      - Get the raw query string
// req.getMethod()     - Get the HTTP method

module.exports = ({ get, set, update, addCallable, startDB, addDomain, ... }) => {

  // Import the server SDK for external connections
  const path = require('path');
  const createServerClient = require('../sys/serversdk.js');

  // Connect to an external NukeBase database
  // Note: External connections ARE async (like client-side)
  // The second argument is REQUIRED: a JSON file holding { uid, token } for the
  // session to connect as. Use a build token (dashboard → Signed-in devices →
  // Create build token) for the account that owns the other project; keep the
  // file out of public/. The SDK sends them as cookies.
  createServerClient('wss://other-project.nukebase.com',
                     path.join(__dirname, 'external-session.json')).then(externalDb => {
    console.log('Connected to external database');

    // Use the external database with async operations
    addCallable("getExternalData", async function(data, admin, sessionId) {
      // Local database (sync)
      const localUser = get(["users", admin.uid]);

      // External database (async - requires await)
      const externalData = await externalDb.get(["sharedData", data.itemId]);

      return {
        local: localUser.data,
        external: externalData.data
      };
    });

    // Subscribe to changes on external database
    externalDb.getSub({
      event: "value@",
      path: ["notifications"]
    }, (event) => {
      // When external data changes, update local database
      set(["cache", "externalNotifications"], event.data);
    });

  }).catch(err => {
    console.error('Failed to connect to external database:', err);
  });

  // Set up local domain
  const nukebase = addDomain({
    authPath: ["users"]
  });

  startDB(nukebase);
};

"users": {
  "$uid": {
    "pushTokens": { "write": "$uid == admin.uid" }   // each user saves only their own devices
  }
}

document.querySelector("#notify").onclick = async () => {
  const status = await client.push.enable(["users", myUid, "pushTokens"]);
  if (status === "on") showMessage("Notifications are on");
  if (status === "install-first") showMessage("Tap Share, then Add to Home Screen, then open the app from your Home Screen");
  if (status === "blocked") showMessage("Notifications are blocked in your settings for this site");
};

module.exports = ({ get, set, addDbTrigger, sendPush /* , … */ }) => {

  // anywhere on the server: a trigger, a callable, a timer
  sendPush(["users", uid, "pushTokens"], {
    title: "Your order is ready",
    body: "Pick it up any time before 5pm.",
    url: "/orders"
  });

"pushTokens": {
  "-u5r83BoVpsmbv4AmSUnmA": {                       // an Android phone (Chrome)
    "endpoint": "https://fcm.googleapis.com/fcm/send/cmJI…",
    "expirationTime": null,
    "keys": { "p256dh": "BDF4XAl5…", "auth": "-u5r83BoVpsmbv4AmSUnmA" }
  },
  "AA6TAGG9CDXjJHKtGKMTjg": {                       // an iPhone (Home Screen app)
    "endpoint": "https://web.push.apple.com/QKVLecOK…",
    "keys": { "p256dh": "BK2nrxlT…", "auth": "AA6TAGG9CDXjJHKtGKMTjg" }
  }
}

{
  sent: 2,      // accepted by the push service
  removed: 1,   // devices that are gone (uninstalled, permission revoked); deleted where they were found
  failed: 0     // temporary errors (push service down, rate limited); not retried automatically
}

addDbTrigger("set", ["chats", "$chatId", "messages", "$msgId"], (context) => {
  if (context.dataBefore !== undefined) return;
  const msg = context.dataAfter;
  const unread = increment(["users", msg.to, "unread"], 1).data;   // the recipient's new total
  sendPush(["users", msg.to, "pushTokens"], {
    title: msg.fromName,
    body: msg.text,
    url: `/chats/${context.path[1]}`,
    badge: unread
  });
});

async function openInbox() {
  showInbox();
  await client.set(["users", myUid, "unread"], 0);
  client.push.setBadge(0);          // this device, right now
}

module.exports = {
  // 1. Each user saves their own devices
  "users": { "$uid": { "pushTokens": { "write": "$uid == admin.uid" } } },

  // 2. Team members save a device to their team
  "teams": { "$teamId": { "pushTokens": {
    "write": "root.teams[$teamId].members?.[admin.uid] === true"
  } } },

  // 3. No sign-in needed: anyone may add a device, but only something shaped like one
  "fans": { "$device": {
    "write": "true",
    "validate": "newData == null || (typeof newData.endpoint === 'string' && newData.endpoint.startsWith('https://') && newData.keys?.auth === $device)"
  } }
};

addDbTrigger("set", ["repairs", "$id"], (context) => {
  if (context.dataBefore !== undefined) return;          // only brand-new requests
  const repair = context.dataAfter;
  const landlord = get(["buildings", repair.building, "owner"]).data;
  sendPush(["users", landlord, "pushTokens"], {
    title: `New repair: ${repair.flat}`,
    body: repair.summary,
    url: `/repairs/${context.path[1]}`,
    tag: `repair-${context.path[1]}`
  });
});

addDbTrigger("update", ["teams", "$teamId", "nextRun"], (context) => {
  const teamId = context.path[1];
  sendPush(["teams", teamId, "pushTokens"], {
    title: "Saturday's run has changed",
    body: `Now ${context.dataAfter.time} at ${context.dataAfter.place}`,
    url: `/teams/${teamId}`,
    topic: "next-run"                                  // a newer change replaces an undelivered older one
  });
});

setInterval(() => {
  const soon = Date.now() + 24 * 60 * 60 * 1000;
  const due = query({ path: ["bookings"], query: `child.at <= ${soon} && !child.reminded` }).data || {};
  for (const [id, b] of Object.entries(due)) {
    update(["bookings", id], { reminded: true });         // mark first: never send twice
    sendPush(["users", b.uid, "pushTokens"], {
      title: "Appointment tomorrow",
      body: `${new Date(b.at).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" })} with ${b.groomer}`,
      url: `/bookings/${id}`
    });
  }
}, 60 * 1000);

addCallable("orderReady", async (data, admin) => {
  if (!admin.claims?.staff) return { status: "Failed", message: "Staff only" };
  const order = get(["orders", data.orderId]).data;
  if (!order) return { status: "Failed", message: "No such order" };
  update(["orders", data.orderId], { status: "ready" });
  // The server picks the target from the order, never from the caller.
  return sendPush(["users", order.customerUid, "pushTokens"], { title: "Your order is ready", url: `/orders/${data.orderId}` });
});

// Browser, no sign-in (uses rule 3 above):
await client.push.enable(["fans"]);

// Server: every fan device, plus every signed-in user
addDbTrigger("set", ["shows", "$id"], (context) => {
  if (context.dataBefore !== undefined) return;
  sendPush([["fans"], ["users", "$uid", "pushTokens"]], {
    title: "New show announced",
    body: context.dataAfter.venue,
    url: "/shows"
  });
});

{
  "name": "Pawsbook",
  "short_name": "Pawsbook",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#4361ee",
  "icons": [
    { "src": "/icon-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icon-512.png", "sizes": "512x512", "type": "image/png" }
  ]
}

<link rel="manifest" href="/manifest.webmanifest">
<link rel="apple-touch-icon" href="/icon-192.png">
<meta name="theme-color" content="#4361ee">

const client = await createClient();

client.onUpdate(() => {
  showBanner("A new version is ready", { action: "Reload", onClick: () => location.reload() });
});

// Or turn the page cache off for this app. Push keeps working.
const client = await createClient({ pageCache: false });

configurePush({
  publicKey:  "BPaste-your-65-byte-public-key-here…",   // 65 bytes, base64url
  privateKey: "paste-your-32-byte-private-key-here…",   // 32 bytes, base64url
  contact:    "mailto:hello@pawsbook.com"          // optional
});

const client = await createClient({ offline: { enabled: true } });
// or, with a URL:  createClient(url, { offline: { enabled: true, maxBytes: 50 * 1024 * 1024 } })

// Reads answered from the cache say so
const r = await client.get(["notes", "n1"]);
if (r.fromCache) showStaleHint(r.cachedAt);

// Writes made offline are accepted locally and replay later
const w = await client.set(["notes", "n1"], { text: "written on the train" });
if (w.status === "Queued") showPendingBadge();

client.offline.onSync((e) => {
  if (e.type === "failed") toast("A change could not be saved: " + JSON.stringify(e.op.path));
  if (e.type === "drained") hidePendingBadge();
});

server/data/
├── data.json                  # { "users": "$split", "posts": [...] }
└── users/
    ├── data.json              # { "alice": {...}, "bob": "$split" }
    └── bob/
        └── data.json          # { ...bob's subtree... }

module.exports = ({
  // Data
  get, set, update, increment, remove, query, data,
  // Files
  getFile, setFile, removeFile, listFiles, fileStat, fileUrlFor, FILES_DIR,
  // Extension points
  addDbTrigger, addFileTrigger, addCallable, addConnectionTrigger,
  // Server
  addDomain, startDB, checkAuth, withBody, hashToken, generateRequestId
}) => {

// Set up a domain
const nukebase = addDomain({
  authPath: ["users"],  // Path where user authentication data is stored
  host: "127.0.0.1", // optional
  port: 3000 // optional
});

// Enable username/password auth (/login, /changepassword; /createuser ships disabled).
// Omit it and the app is passwordless — /logout and session validation
// are in core either way.
require("./extensions/auth")({
  app: nukebase.app,
  authPath: nukebase.authPath,
  get, set, update, remove, query, generateRequestId, hashToken
});

// Configure middleware for serving static files
const path = require('path');
nukebase.app.serveStatic("/*", path.join(__dirname, "../public"),
  (res, req) => { return true; }
);

// Add a database trigger for important changes
addDbTrigger("value", ["orders", "$orderId"], function(context) {
  // Only trigger if data has actually changed
  if (JSON.stringify(context.dataAfter) !== JSON.stringify(context.dataBefore)) {
    set(["logs", generateRequestId()], {
      path: context.path,
      timestamp: Date.now(),
      oldValue: context.dataBefore,
      newValue: context.dataAfter,
      change: "Important data changed"
    });
  }
});

// Add a callable for client calculations
addCallable("addNumbers", function(data, admin, sessionId) {
  // Extract numbers from the request
  const { num1, num2 } = data;
  // Perform the calculation on the server
  const sum = num1 + num2;
  // Return the result to the client
  return sum;
});

// Atomic counter — no read-modify-write race
addDbTrigger("set", ["orders", "$orderId"], function(context) {
  increment(["stats", "ordersPlaced"], 1);
});

// Keep a per-user storage ledger the file rules can read.
// reserve books the cost before the bytes; release refunds every path
// that doesn't commit; remove gives the space back. Book the DIFFERENCE —
// an upload over an existing file replaces it. See File Quotas.
const delta = (ctx) => ctx.file.size - (ctx.existing?.size ?? 0);
addFileTrigger("reserve", ["uploads"], (ctx) => {
  increment(["usage", ctx.path[1], "bytes"], delta(ctx));
});
addFileTrigger("release", ["uploads"], (ctx) => {
  increment(["usage", ctx.path[1], "bytes"], -delta(ctx));
});
addFileTrigger("remove", ["uploads"], (ctx) => {
  increment(["usage", ctx.path[1], "bytes"], -(ctx.existing?.size ?? 0));
});

// Track user connections
addConnectionTrigger("open", function(admin, sessionId) {
  // Anonymous visitors connect too, and have no uid to key on
  if (!admin.uid) return;
  // Record when user connects
  update(["sessions", admin.uid, sessionId], {
    start: Date.now()
  });

  // Update user status
  update(["users", admin.uid], {
    online: true,
    lastSeen: Date.now()
  });
});

// Handle user disconnections
addConnectionTrigger("close", function(admin, sessionId) {
  if (!admin.uid) return;
  // Record when user disconnects
  update(["sessions", admin.uid, sessionId], {
    end: Date.now()
  });

  // Update user status
  update(["users", admin.uid], {
    online: false,
    lastSeen: Date.now()
  });
});

startDB(nukebase);
console.log("🚀 NukeBase server running on http://127.0.0.1:3000");
};

<script type="module">
  import createClient from './sdkmod.js';

  // ============================================
  // PATTERN 1: Full client object
  // ============================================
  const db = await createClient();

  // Use methods with db. prefix
  await db.set(['users', 'john'], { name: 'John', age: 30 });
  const user = await db.get(['users', 'john']);

  // ============================================
  // PATTERN 2: Destructured methods (recommended)
  // All examples below use this pattern
  // ============================================
  const { set, get, update, increment, remove, query,
          getSub, querySub, getSubChanged, querySubChanged,
          getFile, setFile, listFiles, removeFile, fileUrl,
          callableFunction, reconnect, onConnectionChange,
          login, logout, createUser, changePassword, magicLink } = await createClient();

  console.log("Connected and ready to use NukeBase");

  // Use methods directly without prefix
  await set(['users', 'alice'], { name: 'Alice', age: 28 });
  const userData = await get(['users', 'alice']);

  // ============================================
  // PATTERN 3: Attach to window (global access)
  // Useful for multi-file apps or console debugging
  // ============================================
  const client = await createClient();

  // Attach full client object
  window.db = client;

  // Optional: expose individual helpers directly
  Object.assign(window, client);

  // Now use from anywhere: window.db.get(...) or just get(...)
</script>

const client = await createClient();

client.onConnectionChange((online) => {
  document.querySelector("#offline-banner").hidden = online;
  document.querySelector("#book").disabled = !online;
});

document.querySelector("#book").onclick = async () => {
  const r = await client.callableFunction("bookSlot", { time: "3pm" });
  if (r.status === "Offline") showMessage("You need a connection to book");
};

// Subscribe to changes on a path
const unsubscribe = getSub({
    event: "value@",
    path: ["users", "john"]
}, event => {
    // This fires immediately with current data, then on every change
    console.log("User data:", event.data);
});

// When finished listening
unsubscribe();

// Subscribe to active users
const unsubscribe = querySub({
    event: "value@",
    path: ["users"],
    query: "child.status == 'online'"
}, event => {
    // Receives all currently online users immediately, then updates
    const onlineUsers = event.data;
    updateOnlineUsersList(onlineUsers);
});

const unsubscribe = querySub({
    path: ["players"],
    query: "child.active == true",
    orderBy: ["score"],
    desc: true,
    limit: 10
}, event => {
    // Fires immediately with the current top 10, then on every write
    // beneath ["players"] that changes it.
    // Read them IN ORDER through event.order — object key order is not
    // something to depend on.
    renderLeaderboard(event.order.map(k => event.data[k]));
});

// A live feed of the 50 newest items, as a delta stream
const unsub2 = querySubChanged({
    path: ["events"],
    query: "true",
    orderBy: ["ts"],
    desc: true,
    limit: 50
}, event => {
    // The FIRST payload is the whole window — a starting state to merge into.
    // Every payload after that contains only the records this write touched
    // AND that fall inside the window.
    Object.assign(feed, event.data);
});

// Subscribe to public profiles only (excludes private data)
const unsubscribe = querySub({
    event: "value@",
    path: ["users"],
    childPath: ["public"],
    query: "child.verified == true"
}, event => {
    // Receives the public subtree wrapped under its childPath key,
    // mirroring the DB shape. "private" is never traversed or sent.
    // Response: { matt123: { public: { verified: true, name: "Matt", ... } } }
    displayVerifiedUsers(event.data);
});

// Subscribe to inventory changes for low stock items
const unsubscribe2 = querySub({
    event: "value@",
    path: ["products"],
    childPath: ["inventory"],
    query: "child.stock < 10"
}, event => {
    // Only the inventory subtree is fetched and pushed; product details
    // outside "inventory" never enter the payload.
    // Response: { productA: { inventory: { stock: 5, ... } } }
    showLowStockAlert(event.data);
});

// Use with querySubChanged for efficient updates
const unsubscribe3 = querySubChanged({
    event: "value@",
    path: ["users"],
    childPath: ["profile"],
    query: "child.country == 'USA'"
}, event => {
    // Only fires when USA profiles change
    // Only returns the profile portion that changed
    console.log("Updated USA profiles:", event.data);
});

// getSubChanged - watching a collection
const unsubscribe = getSubChanged({
    event: "value@",
    path: ["users"]
}, event => {
    // Initial: all users
    // If John updates his email:
    // event.data = { john: { name: "John", email: "new@email.com", age: 25 } }
    // You get John's COMPLETE object
    updateChangedUsers(event.data);
});

// getSubChanged - watching a specific user
const unsubscribe2 = getSubChanged({
    event: "value@",
    path: ["users", "john"]
}, event => {
    // Initial: John's complete data
    // If John's email changes:
    // event.data = { email: "new@email.com" }
    // You get ONLY the changed field
    Object.assign(currentUser, event.data);  // Merge changes
});

// getSubChanged - watching a specific field
const unsubscribe3 = getSubChanged({
    event: "value@",
    path: ["users", "john", "status"]
}, event => {
    // Initial: "online"
    // If status changes:
    // event.data = "offline"
    // You get just the new value
    updateStatusIndicator(event.data);
});

// With query filtering - returns only the changed items
const unsubscribe4 = querySubChanged({
    event: "value@",
    path: ["users"],
    query: "child.age > 21"
}, event => {
    // If user John (age 25) updates only his name:
    // event.data = { john: { name: "John Doe", age: 25, email: "john@example.com" } }
    // You get John's COMPLETE object, not just the changed name field
    console.log("Users that changed:", event.data);
});

// Example: monitoring low stock products
const unsubscribe5 = querySubChanged({
    event: "value@",
    path: ["products"],
    query: "child.stock < 5"
}, event => {
    // If product ABC updates its price, you get:
    // { ABC: { name: "Widget", stock: 3, price: 29.99 } }
    // The complete product object for ONLY the product that changed
    Object.keys(event.data).forEach(productId => {
        updateSingleProduct(productId, event.data[productId]);
    });
});

// Listen only for updates to user data
const unsubscribe = getSub({
    event: "update@",
    path: ["users", "john"]
}, event => {
    console.log("User was updated:", event.data);
});

// Listen for new data being set
const unsubscribe2 = getSub({
    event: "set@",
    path: ["orders"]
}, event => {
    console.log("New order created:", event.data);
});

// Listen for data removal
const unsubscribe3 = getSub({
    event: "remove@",
    path: ["users"]
}, event => {
    console.log("A user was deleted:", event.path);
});

// Operation-specific with getSubChanged
const unsubscribe4 = getSubChanged({
    event: "set@",
    path: ["products"]
}, event => {
    // Only fires when NEW products are created (not updates)
    console.log("New products added:", event.data);
});

// Operation-specific with queries
const unsubscribe5 = querySub({
    event: "update@",
    path: ["users"],
    query: "child.status == 'premium'"
}, event => {
    // Only fires when premium users are UPDATED (not created or deleted)
    console.log("Premium users updated:", event.data);
});

// Combining with querySubChanged
const unsubscribe6 = querySubChanged({
    event: "remove@",
    path: ["tasks"],
    query: "child.completed == true"
}, event => {
    // Only fires when completed tasks are DELETED
    console.log("Completed tasks removed:", event.data);
});

// Default behavior without prefix (same as value@)
const unsubscribe7 = getSub({
    path: ["users", "john"]
}, event => {
    // Fires on ANY change: set, update, or remove
    // event parameter defaults to "value@" if not specified
    console.log("Something changed:", event.data);
});

// Set up subscriptions at different levels
getSub({
    event: "value@",
    path: ["calls"]
}, (event) => {
    console.log("1. Calls level:", event.data);
});

getSub({
    event: "value@",
    path: ["calls", "123"]
}, (event) => {
    console.log("2. Specific call:", event.data);
});

getSub({
    event: "value@",
    path: ["calls", "123", "answer"]
}, (event) => {
    console.log("3. Answer level:", event.data);
});

// Scenario 1: Change at deep level (bubbles UP)
await set(["calls", "123", "answer"], { type: "answer", sdp: "..." });
// ✅ Fires: 1. Calls level (bubbled up)
// ✅ Fires: 2. Specific call (bubbled up)
// ✅ Fires: 3. Answer level (direct match)

// Scenario 2: Change at middle level (bubbles UP, not DOWN)
await update(["calls", "123"], { status: "active" });
// ✅ Fires: 1. Calls level (bubbled up)
// ✅ Fires: 2. Specific call (direct match)
// ❌ NOT fired: 3. Answer level (no trickle down)

// Scenario 3: Change at top level (no trickle DOWN)
await set(["calls"], { "456": { offer: {...} } });
// ✅ Fires: 1. Calls level (direct match)
// ❌ NOT fired: 2. Specific call (no trickle down)
// ❌ NOT fired: 3. Answer level (no trickle down)

// Call the server callable
const response = await callableFunction("addNumbers", { num1: 5, num2: 7 });
console.log(`The sum is: ${response.data}`);  // Output: The sum is: 12

const nukebase = addDomain({ authPath: ["users"] });

// Enables /login and /changepassword.
// (/createuser ships commented out — accounts are created by the email flows.)
// Omit this and your app is passwordless — /logout and session
// validation keep working either way.
require("./extensions/auth")({
  app: nukebase.app,
  authPath: nukebase.authPath,
  get, set, update, remove, query, generateRequestId, hashToken,
  sessionTokenTtlMs: 24 * 60 * 60 * 1000   // optional, default 24h
});

// Import and destructure the methods you need
import createClient from './sdkmod.js';
const { login } = await createClient();

// Login with username and password
const result = await login("username", "password");
if (result && result.status === "Success") {
    console.log('Authenticated as:', result.username);
}

// Resume session (if cookies are already set)
const result2 = await login();
if (result2 && result2.status === "Success") {
    console.log('Session resumed:', result2.uid);
}

// Upgrade a demo account to a full account
// Preconditions: valid demo cookies AND the account currently has
// no username and no password set. After the first upgrade, calling
// login(...) again just resumes the existing session — it will not
// overwrite the username/password.
const result3 = await login("newUsername", "newPassword");
if (result3 && result3.status === "Success") {
    console.log('Demo account upgraded:', result3.username);
}

import createClient from './sdkmod.js';
const { createUser } = await createClient();

// Create a demo/anonymous account (no credentials) — logs in immediately
const result = await createUser();
if (result && result.status === "Success") {
    console.log('Demo account created:', result.uid);
}

// Create a full account with username and password — logs in immediately
const result2 = await createUser("myUsername", "myPassword");
if (result2 && result2.status === "Success") {
    console.log('Account created:', result2.username);
}
// Note: Fails if already signed in - logout first
// For passwordless signup, use POST /magic-signup instead

import createClient from './sdkmod.js';
const { logout } = await createClient();

const result = await logout();
if (result && result.status === "Success") {
    console.log('Logged out successfully');
}

import createClient from './sdkmod.js';
const { changePassword } = await createClient();

const result = await changePassword("newPassword123");
if (result && result.status === "Success") {
    console.log('Password changed successfully');
} else {
    console.log('Failed to change password');
}

const nukebase = addDomain({ authPath: ["users"] });

require("./extensions/easy-login")({
  app: nukebase.app,
  authPath: nukebase.authPath,
  get, set, query, generateRequestId, hashToken,
  redirectPath: "/dashboard",          // optional, default "/"
  brandName: "Acme",                   // optional, shown in the email
  sessionTokenTtlMs: 24 * 60 * 60 * 1000  // optional, default 24h
});

// 1. Ask for a link
const r = await fetch("/auth/email", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "matt@example.com" })
});
const { status, message } = await r.json();
// Always the same generic response, whether or not the account exists

// 2. The user clicks the link in their inbox. It lands on
//    /auth/callback?code=..., which creates the account if it's new,
//    sets the session cookies, and redirects to redirectPath.

// 3. Anywhere after that:
const me = await (await fetch("/auth/me", { method: "POST" })).json();
// → { email: "matt@example.com" }  or  { email: null }

// 4. Sign out with the core endpoint
await fetch("/logout", { method: "POST" });

const r = await fetch("/magic-link", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "matt@example.com" })
});
const { status, message } = await r.json();
// status === "Success" whether or not the address exists (anti-enumeration)

// Email-only signup via /magic-signup — user must click the link in their inbox
const r = await fetch("/magic-signup", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "matt@example.com" })
});
const result = await r.json();
// result.status === "Success", result.message tells the user to check email
// A taken address answers status "Failed", "An account with that email already exists"
// (no uid / token returned here — the session is established by /magiclink)

// In your rules.js
module.exports = {
  "users": {
    "$userId": {
      // Only the user themselves can edit
      "write": "admin.uid == $userId",

      // Don't grant read at $userId — it would cascade and expose "private".
      // Split the data into public/private subnodes and grant read on each.
      "public":  { "read": "true" },                    // Anyone can read public profile
      "private": { "read": "admin.uid == $userId" }     // Only the user
    }
  },

  "adminPanel": {
    // Only users with admin role can access
    "read":  "admin.claims.role == 'admin'",
    "write": "admin.claims.role == 'admin'"
  }
};

// Set all claims at once
set(["users", uid, "auth", "claims"], { role: "admin", plan: "pro" });

// Update or add a single claim
update(["users", uid, "auth", "claims"], { role: "editor" });

// Remove a single claim
remove(["users", uid, "auth", "claims", "role"]);

module.exports = {
  "adminPanel": {
    "read": "admin.claims.role == 'admin'",
    "write": "admin.claims.role == 'admin'"
  },
  "premiumContent": {
    "read": "admin.claims.plan == 'pro'"
  }
};

  "users": {
    "ML96SDE5": { // Unique user UID (hex, generated by generateRequestId)
      "auth": {
        "username": "matt123",                    // Lowercased username/email (optional for demo accounts)
        "password": "$argon2id$v=19$m=65536,...", // argon2id hash — never plaintext
        "tokens": {
          // Keys are SHA-256 hashes of the raw session token (the cookie value).
          // Values are expiration timestamps in ms since epoch.
          "8f3a...e21c": 1748357368415,
          "b12d...07ff": 1748357670935
        },
        "claims": { // Optional custom claims (free-form object)
          "role": "admin",
          "plan": "pro"
        }
      }
    }
  }

{
  // The operation performed
  action: "get", 
  
  // Data from the operation
  data: {
    "user123": { name: "John", age: 32 },
    "user456": { name: "Jane", age: 28 }
  },
  
  // For tracking the request
  requestId: "RH8HZX9P",
  
  // Success or Failed
  status: "Success"
}

{
  status: "Failed",
  action: "set",
  requestId: "RH8HZX9P",
  message: "Error description here"
}

{
  status: "Success",
  action: "query",
  requestId: "RH8HZX9P",

  data:  { p14: {...}, p3: {...}, p91: {...} },
  order: ["p14", "p3", "p91"],   // the authoritative ordering — read through this

  plan:      "index-order",      // scan | index-filter | index-order | index-union | index-count
  examined:  11,                 // records the engine had to look at
  truncated: false,              // true ⇒ status is "Incomplete"
  nextCursor: "W1s0MiwicDkxIl0"  // absent when there are no more results
}

// getSub / getSubChanged
{
  status: "Success",
  action: "getSub",
  event:  "value@",
  path:   ["users", "john"],
  data:   { name: "John", age: 32 }
}

// querySub / querySubChanged — the window is echoed back so the SDK can
// route the notification to exactly the handler that asked for it.
{
  status: "Success",
  action: "querySub",
  event:  "value@",
  path:   ["players"],
  data:   { p14: {...}, p3: {...} },

  childPath: [],                 // echoed window ↓
  query:     "child.active == true",
  orderBy:   ["score"],          // null means "ordered by record key"
  desc:      true,
  limit:     10,
  startAt:   null,               // absent parameters echo as null, not omitted
  cursor:    null,

  order: ["p14", "p3"],          // plus plan/examined/truncated/nextCursor
  plan:  "index-order"           // for windowed subscriptions
}

<script type="module">
  import createClient from './sdkmod.js';

  // Destructure all the methods you need
  const { set, get, update, increment, query, callableFunction,
          getSub, querySub, getSubChanged, querySubChanged,
          setFile, getFile, listFiles, removeFile, fileUrl } = await createClient();

  console.log('✅ Connected to NukeBase');

  // Set data
  await set(["users", "matt"], {
    name: "Matt",
    color: "red",
    count: 0
  });

  // Get data
  const sessions = await get(["sessions"]);
  console.log('Sessions:', sessions.data);

  // Update data
  await update(["users", "matt"], {
    leadsSent: "Pending"
  });

  await update(["users", "matt", "count"], 5);

  // Query data
  const results = await query({
    path: ["sessions"],
    query: "child.count > 0"
  });
  console.log('Query results:', results.data);

  // Atomic counter — no read-modify-write race, and the new value comes back
  const bumped = await increment(["users", "matt", "count"], 1);
  console.log('New count:', bumped.data);

  // Sorted, paged query. Read results through .order — object key order
  // is not something to depend on.
  const top = await query({
    path: ["sessions"],
    query: "child.count > 0",
    orderBy: ["count"],
    desc: true,
    limit: 10
  });
  top.order.forEach(k => console.log(k, top.data[k].count));

  // Upload a file, then link to it
  const picker = document.querySelector('input[type=file]');
  if (picker?.files[0]) {
    try {
      await setFile(["users", "matt", "avatar.png"], picker.files[0], {
        onProgress: p => console.log(Math.round(p * 100) + '%')
      });
      document.querySelector('img').src = fileUrl(["users", "matt", "avatar.png"]);
    } catch (err) {
      // File methods THROW (unlike the data methods above, which resolve
      // with { status: "Failed" }). Branch on the HTTP status.
      console.error('Upload failed:', err.status, err.body);
    }
  }

  // Call a server callable
  const functionResult = await callableFunction("custom1", 23);
  console.log('Function result:', functionResult);

  // Subscribe to changes
  const unsubscribe1 = getSub({
    event: "value@",
    path: ["sessions"]
  }, data => {
    console.log('Sessions updated:', data);
  });

  // Query subscription
  const unsubscribe2 = querySub({
    event: "value@",
    path: ["sessions"],
    query: "child.count == 4"
  }, data => {
    console.log('Matching sessions:', data);
  });

  // Changed-only subscription
  const unsubscribe3 = getSubChanged({
    event: "value@",
    path: ["sessions"]
  }, data => {
    console.log('Changed sessions:', data);
  });

  // Query changed subscription
  const unsubscribe4 = querySubChanged({
    event: "value@",
    path: ["sessions"],
    query: "child.count != 4"
  }, data => {
    console.log('Changed query results:', data);
  });

  // Later, to unsubscribe:
  // unsubscribe1();
  // unsubscribe2();
  // unsubscribe3();
  // unsubscribe4();

</script>