@bounded-sh/core 0.0.2 → 0.0.4

package/dist/index.mjs

@@ -4909,6 +4909,13 @@ async function runExpressionMany(many) {
         throw error;
     }
 }
+/**
+ * Write a document at `path`. Sugar for a one-element {@link setMany}.
+ *
+ * **Delete:** pass `null` as the document to delete it — `set(path, null)` is
+ * the delete (there is no separate `del`/`remove`). It is routed through the
+ * collection's policy `delete` rule and broadcasts a delete to subscribers.
+ */
 async function set(path, document, options) {
     const result = await setMany([{ path, document }], options);
     // Clear cache entries that might be affected by this update
@@ -6587,6 +6594,73 @@ function serverTimestamp() {
     return { operation: 'time', value: 'now' };
 }
 
+/**
+ * Time units in Bounded — read this once and never get a 1000× timestamp bug.
+ *
+ * **Bounded's policy/proof layer is Unix SECONDS.** `@time.now` in a rule,
+ * `rollingSum` `windowSeconds`, `scheduledAt`, and any timestamp *field your
+ * policy compares against `@time.now`* are all **seconds**. (This is also what
+ * the chain uses — Solana's on-chain clock is `unix_timestamp` in seconds — so a
+ * single seconds unit works for both onchain and offchain rules.)
+ *
+ * **JavaScript is MILLISECONDS.** `Date.now()`, `new Date().getTime()`, and the
+ * auto-stamped system fields `_createdAt` / `_updatedAt` are all **ms**.
+ *
+ * Comparing across the two (e.g. `@time.now - myField` where `myField` was set
+ * from `Date.now()`) is 1000× off, so a freshness / TTL check silently treats
+ * every row as ancient (or far-future) and drops it — which reads as "realtime
+ * isn't delivering" when the data is actually fine.
+ *
+ * **The rules:**
+ * - To **write** a timestamp a policy will read, prefer **`serverTimestamp()`**
+ *   (from this package) — the *server* stamps it in seconds, so it matches
+ *   `@time.now` AND can't be forged by the client (use it for TTLs, rate windows,
+ *   anti-cheat). Use `now()` only when you need the value in client code before
+ *   the write.
+ * - To **compare** timestamps in client/render code, use `now()` (seconds), not
+ *   `Date.now()` (ms), and `toSeconds()` to convert the ms system fields
+ *   (`_createdAt`/`_updatedAt`) or any `Date.now()` value first.
+ */
+/**
+ * Current time as a **Unix timestamp in seconds** — the unit Bounded policy rules
+ * use (`@time.now`). Use this (not `Date.now()`) when you need a timestamp in
+ * client code (e.g. a freshness check). For a value you *store* and a policy
+ * reads, prefer the server-authoritative {@link serverTimestamp} instead.
+ *
+ * ```ts
+ * // stale if >15s old — seconds vs seconds ✓
+ * if (now() - doc.lastSeenSeconds > 15) renderStale();
+ * ```
+ */
+function now() {
+    return Math.floor(Date.now() / 1000);
+}
+/**
+ * Convert a JavaScript millisecond timestamp to Bounded's **seconds**. Accepts a
+ * `Date`, or an ms number such as `Date.now()` or a doc's `_createdAt` /
+ * `_updatedAt` system field.
+ *
+ * ```ts
+ * // doc is >15s old (compare the ms system field in seconds):
+ * if (now() - toSeconds(doc._updatedAt) > 15) renderStale();
+ * ```
+ */
+function toSeconds(msOrDate) {
+    const ms = msOrDate instanceof Date ? msOrDate.getTime() : msOrDate;
+    return Math.floor(ms / 1000);
+}
+/**
+ * Convert a Bounded **seconds** timestamp back to JavaScript **milliseconds** —
+ * e.g. to build a `Date` or do client-side date math/formatting.
+ *
+ * ```ts
+ * new Date(toMillis(doc.createdAtSeconds)).toLocaleString();
+ * ```
+ */
+function toMillis(seconds) {
+    return seconds * 1000;
+}
+
 // ---------------------------------------------------------------------------
 // realtime-store.ts — Client-side state manager for realtime apps.
 //
@@ -7490,6 +7564,7 @@ const functions = { invoke };
 // collection. This file is the consumer surface around that runtime:
 //
 //   bounded.live.intent(roomPath, intent)  -> POST {realtime}/live/intent
+//   bounded.live.status(roomPath)          -> GET  {realtime}/live/status
 //
 // It mirrors `functions.invoke` exactly: it attaches the caller's session token
 // AUTOMATICALLY (the same token the SDK uses for data reads/writes), and throws
@@ -7502,18 +7577,14 @@ const functions = { invoke };
 // Addressing: clients address rooms BY PATH (the `path` field in the body). The
 // worker derives the roomId from `body.path` and sets X-Room-Id internally;
 // clients NEVER set X-Room-Id. The caller's address is taken server-side from
-// the Authorization header (auth.userAddress) — it is NOT sent in the body.
+// the Authorization header (auth.userId/userAddress) — it is NOT sent in the
+// body.
 //
 // Subscribing to your view: a per-player view doc lives at
-// `<roomPath>/view/<myAddress>` (the policy declares
-// `rooms/$roomId/view/$addr` ephemeral with `read: $addr == @user.address`).
-// That path has an EVEN segment count, so it is an ordinary document path —
-// plain `subscribe('<roomPath>/view/<myAddress>', { onData })` already works.
-// `subscribeView()` below is thin sugar over that (path construction + address
-// defaulting); it adds zero new transport.
-//
-// Status polling (GET /live/status?path=<sessionCollection>/<roomId>) is out of
-// scope for this piece — see follow-up.
+// `<roomPath>/view/<myUserId>` (the policy declares
+// `rooms/$roomId/view/$userId` ephemeral with `read: $userId == @user.id`).
+// Wallet-address keyed view paths remain supported through opts.address for
+// older policies, but new live rooms should key views by @user.id.
 // ---------------------------------------------------------------------------
 class LiveIntentError extends Error {
     constructor(message, statusCode, details) {
@@ -7594,7 +7665,7 @@ async function intent(roomPath, intent, opts = {}) {
         res = await fetch(`${base}/live/intent`, {
             method: 'POST',
             headers,
-            body: JSON.stringify({ path: roomPath, intent }),
+            body: JSON.stringify({ path: normalizedRoomPath, intent }),
             signal: controller.signal,
         });
     }
@@ -7622,43 +7693,95 @@ async function intent(roomPath, intent, opts = {}) {
     }
     return (body !== null && body !== void 0 ? body : { ok: true });
 }
+/**
+ * Fetch the runtime status for a live room.
+ *
+ *   const s = await bounded.live.status('rooms/abc');
+ *   console.log(s.running, s.stopReason, s.generation, s.etag);
+ *
+ * This is diagnostic/ops surface. It reports whether the room facet exists,
+ * whether it is currently ticking, why it last stopped, which module etag is
+ * loaded, and the current generation used after terminal restarts.
+ */
+async function status(roomPath, opts = {}) {
+    var _a, _b, _c, _d, _e;
+    if (!roomPath || typeof roomPath !== 'string') {
+        throw new LiveIntentError('A room path is required');
+    }
+    const normalizedRoomPath = roomPath.replace(/\/$/, '');
+    const config = await getConfig();
+    const base = realtimeHttpBase(config.wsApiUrl);
+    const headers = Object.assign({ 'X-App-Id': config.appId, 'X-Public-App-Id': config.appId }, ((_a = opts.headers) !== null && _a !== void 0 ? _a : {}));
+    const controller = new AbortController();
+    const timeoutMs = (_b = opts.timeoutMs) !== null && _b !== void 0 ? _b : 15000;
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let res;
+    try {
+        res = await fetch(`${base}/live/status?path=${encodeURIComponent(normalizedRoomPath)}`, {
+            method: 'GET',
+            headers,
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        clearTimeout(timer);
+        if ((err === null || err === void 0 ? void 0 : err.name) === 'AbortError') {
+            throw new LiveIntentError(`Live status for "${normalizedRoomPath}" timed out after ${timeoutMs}ms`);
+        }
+        throw new LiveIntentError(`Failed to reach the realtime worker: ${(_c = err === null || err === void 0 ? void 0 : err.message) !== null && _c !== void 0 ? _c : String(err)}`);
+    }
+    clearTimeout(timer);
+    let body = null;
+    const text = await res.text();
+    if (text) {
+        try {
+            body = JSON.parse(text);
+        }
+        catch (_f) {
+            body = { raw: text };
+        }
+    }
+    if (!res.ok) {
+        const message = (_e = (_d = body === null || body === void 0 ? void 0 : body.error) !== null && _d !== void 0 ? _d : body === null || body === void 0 ? void 0 : body.message) !== null && _e !== void 0 ? _e : `Live status failed with HTTP ${res.status}`;
+        throw new LiveIntentError(message, res.status, body);
+    }
+    return body;
+}
 /**
  * Subscribe to YOUR per-player view of a room. Thin sugar over:
  *
- *   subscribe('<roomPath>/view/<myAddress>', { onData, onError })
+ *   subscribe('<roomPath>/view/<myUserId>', { onData, onError })
  *
- * The address defaults to the logged-in user's address (from the session
- * token's claims); pass `opts.address` to override. Returns the unsubscribe
+ * The view id defaults to the logged-in user's @user.id (from the session token
+ * claims); pass `opts.userId` to override. `opts.address` is kept as a legacy
+ * alias for older wallet-address keyed policies. Returns the unsubscribe
  * function (a Promise<() => Promise<void>>, same as `subscribe`).
  *
  * Note: this is a browser-first helper (the WS subscription manager is
  * browser-oriented). Server consumers should use `live.intent`.
  */
 async function subscribeView(roomPath, opts) {
-    var _a;
+    var _a, _b, _c;
     if (!roomPath || typeof roomPath !== 'string') {
         throw new LiveIntentError('A room path is required');
     }
     if (!opts || typeof opts.onData !== 'function') {
         throw new LiveIntentError('subscribeView requires an onData callback');
     }
-    let address = opts.address;
-    if (!address) {
+    let viewUserId = (_a = opts.userId) !== null && _a !== void 0 ? _a : opts.address;
+    if (!viewUserId) {
         const config = await getConfig();
         const info = await getUserInfo(config.isServer);
-        // getUserInfo returns the RAW idToken payload — the wallet address lives in
-        // the `custom:walletAddress` claim, NOT a flat `address` field. Reading only
-        // `.address` meant auto-resolution NEVER worked, forcing every caller (browser
-        // AND server) to pass opts.address — the client having to hand the backend an
-        // identity it already authenticated. Resolve it from the actual claim so a
-        // logged-in caller never needs to pass its own address.
-        address = (_a = info === null || info === void 0 ? void 0 : info.address) !== null && _a !== void 0 ? _a : info === null || info === void 0 ? void 0 : info['custom:walletAddress'];
+        // getUserInfo returns the RAW idToken payload. The universal live view key
+        // is @user.id (`custom:userId`); wallet-address keyed views are still
+        // resolved as a compatibility fallback for older policies.
+        viewUserId = (_c = (_b = info === null || info === void 0 ? void 0 : info['custom:userId']) !== null && _b !== void 0 ? _b : info === null || info === void 0 ? void 0 : info['custom:walletAddress']) !== null && _c !== void 0 ? _c : info === null || info === void 0 ? void 0 : info.address;
     }
-    if (!address || typeof address !== 'string') {
-        throw new LiveIntentError('Could not resolve a player address for subscribeView; pass opts.address or log in first');
+    if (!viewUserId || typeof viewUserId !== 'string') {
+        throw new LiveIntentError('Could not resolve a player view id for subscribeView; pass opts.userId or log in first');
     }
     const normalizedRoomPath = roomPath.replace(/\/$/, '');
-    const viewPath = `${normalizedRoomPath}/view/${address}`;
+    const viewPath = `${normalizedRoomPath}/view/${viewUserId}`;
     // This is a LIVE/room subscription by construction (the caller hands us the
     // room path), so we route its connection to the per-room DO where the live
     // view fan-out runs. App code passes NO routing — the room path is the helper's
@@ -7669,7 +7792,7 @@ async function subscribeView(roomPath, opts) {
     return subscribeV2(viewPath, { onData: opts.onData, onError: opts.onError }, normalizedRoomPath);
 }
 /** The `bounded.live` namespace surface. */
-const live = { intent, subscribeView };
+const live = { intent, status, subscribeView };
 
 // ---------------------------------------------------------------------------
 // live-effects.ts -- AUTHOR-facing types + helpers for writing a Bounded live
@@ -7722,5 +7845,5 @@ function defineLiveModule(mod) {
     return mod;
 }
 
-export { EFFECT_INTENT_ADDRESS, FunctionInvokeError, InsufficientBalanceError, LiveIntentError, ReactNativeSessionManager, RealtimeStore, ServerSessionManager, WebSessionManager, aggregate, buildSetDocumentsTransaction, clearCache, closeAllSubscriptions, convertRemainingAccounts, count, createSessionWithSignature, defineLiveModule, deriveUserIdentityFromIdToken, functions, genAuthNonce, genSolanaMessage, get, getActiveSessionManager, getCachedData, getConfig, getFiles, getIdToken, getMany, getRealtimeStore, getWebhookKeysUrl, hasActiveConnection, increment, init, invoke as invokeFunction, isEffectResult, live, intent as liveIntent, queryAggregate, reconnectWithNewAuth, refreshSession, resetRealtimeStore, revokeSession, runExpression, runExpressionMany, runQuery, runQueryMany, search, serverTimestamp, set, setFile, setMany, signAndSubmitTransaction, signMessage, signSessionCreateMessage, signTransaction, subscribe, subscribeView as subscribeLiveView, withEffects, wsDelete, wsGet, wsGetMany, wsQuery, wsSet };
+export { EFFECT_INTENT_ADDRESS, FunctionInvokeError, InsufficientBalanceError, LiveIntentError, ReactNativeSessionManager, RealtimeStore, ServerSessionManager, WebSessionManager, aggregate, buildSetDocumentsTransaction, clearCache, closeAllSubscriptions, convertRemainingAccounts, count, createSessionWithSignature, defineLiveModule, deriveUserIdentityFromIdToken, functions, genAuthNonce, genSolanaMessage, get, getActiveSessionManager, getCachedData, getConfig, getFiles, getIdToken, getMany, getRealtimeStore, getWebhookKeysUrl, hasActiveConnection, increment, init, invoke as invokeFunction, isEffectResult, live, intent as liveIntent, status as liveStatus, now, queryAggregate, reconnectWithNewAuth, refreshSession, resetRealtimeStore, revokeSession, runExpression, runExpressionMany, runQuery, runQueryMany, search, serverTimestamp, set, setFile, setMany, signAndSubmitTransaction, signMessage, signSessionCreateMessage, signTransaction, subscribe, subscribeView as subscribeLiveView, toMillis, toSeconds, withEffects, wsDelete, wsGet, wsGetMany, wsQuery, wsSet };
 //# sourceMappingURL=index.mjs.map