@bounded-sh/core 0.0.2 → 0.0.4

package/README.md

@@ -63,7 +63,7 @@ function getConfig(): Promise<ClientConfig>;
 function get(path: string): Promise<any>;
 function getMany(paths: string[], options?: { bypassCache?: boolean }): Promise<GetManyResult[]>;
 function set(path: string, data: any, options?: SetOptions): Promise<any>;
-function setMany(paths: { [key: string]: any }, options?: SetOptions): Promise<any>;
+function setMany(many: { path: string; document: any }[], options?: SetOptions): Promise<any>;
 function setFile(path: string, file: File, metadata?: any): Promise<any>;
 function getFiles(path: string): Promise<any>;
 function runQuery(queryString: string, variables?: any): Promise<any>;
@@ -75,4 +75,4 @@ function subscribe(path: string, options?: SubscriptionOptions): Promise<() => v
 
 ## Contributing
 
-Please see the main repository for contribution guidelines.
+Please see the main repository for contribution guidelines.

package/dist/client/live.d.ts

@@ -12,6 +12,31 @@ export type LiveIntentOptions = {
      */
     fireAndForget?: boolean;
 };
+export type LiveStatusOptions = {
+    /** Per-call timeout (ms) for the HTTP request to the realtime worker. */
+    timeoutMs?: number;
+    /** Extra headers (advanced/testing). */
+    headers?: Record<string, string>;
+};
+export type LiveStopReason = 'idle' | 'lifetime' | 'error' | 'manual' | 'evicted' | string;
+export type LiveStatus = {
+    available: boolean;
+    started: boolean;
+    module?: string;
+    etag?: string;
+    running?: boolean;
+    tick?: number;
+    lastErr?: string | null;
+    stopReason?: LiveStopReason | null;
+    lastTickAt?: number | null;
+    nextTickAt?: number | null;
+    nextAlarmAt?: number | null;
+    generation?: number;
+    connections?: number;
+    startedAtMs?: number | null;
+    stoppedAtMs?: number | null;
+    reason?: string;
+};
 export declare class LiveIntentError extends Error {
     statusCode?: number | undefined;
     details?: any | undefined;
@@ -33,8 +58,21 @@ export declare class LiveIntentError extends Error {
 export declare function intent(roomPath: string, intent: unknown, opts?: LiveIntentOptions): Promise<{
     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.
+ */
+export declare function status(roomPath: string, opts?: LiveStatusOptions): Promise<LiveStatus>;
 export type SubscribeViewOptions = {
-    /** Address whose view to read. Defaults to the logged-in user's address. */
+    /** User id whose view to read. Defaults to the logged-in user's @user.id. */
+    userId?: string;
+    /** Legacy alias for wallet-address keyed view docs. Prefer userId for new rooms. */
     address?: string;
     /** Called with the latest per-player view document. */
     onData: (view: any) => void;
@@ -44,10 +82,11 @@ export type SubscribeViewOptions = {
 /**
  * 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
@@ -57,5 +96,6 @@ export declare function subscribeView(roomPath: string, opts: SubscribeViewOptio
 /** The `bounded.live` namespace surface. */
 export declare const live: {
     intent: typeof intent;
+    status: typeof status;
     subscribeView: typeof subscribeView;
 };

package/dist/client/operations.d.ts

@@ -236,6 +236,13 @@ export declare function runExpressionMany(many: {
     returnType?: 'Bool' | 'String' | 'Int' | 'UInt';
     _overrides?: RequestOverrides;
 }[]): Promise<RunExpressionResult[]>;
+/**
+ * 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.
+ */
 export declare function set(path: string, document: any, options?: SetOptions): Promise<any>;
 export declare function setMany(many: {
     path: string;

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export { hasActiveConnection, wsGet, wsSet, wsQuery, wsDelete, wsGetMany } from
 export * from './types';
 export { increment, serverTimestamp } from './client/field-values';
 export type { FieldOperation } from './client/field-values';
+export { now, toSeconds, toMillis } from './time';
 export { getIdToken, deriveUserIdentityFromIdToken } from './utils/utils';
 export type { UserIdentity } from './utils/utils';
 export { WebSessionManager } from './utils/web-session-manager';
@@ -23,7 +24,7 @@ export { RealtimeStore, getRealtimeStore, resetRealtimeStore } from './client/re
 export type { StorageTier, SubscriptionStatus, SubscriptionState, SubscribeOptions, DeltaChange } from './client/realtime-store';
 export { functions, invoke as invokeFunction, FunctionInvokeError } from './client/functions';
 export type { InvokeOptions } from './client/functions';
-export { live, intent as liveIntent, subscribeView as subscribeLiveView, LiveIntentError } from './client/live';
-export type { LiveIntentOptions, SubscribeViewOptions } from './client/live';
+export { live, intent as liveIntent, status as liveStatus, subscribeView as subscribeLiveView, LiveIntentError } from './client/live';
+export type { LiveIntentOptions, LiveStatus, LiveStatusOptions, SubscribeViewOptions } from './client/live';
 export { withEffects, isEffectResult, defineLiveModule, EFFECT_INTENT_ADDRESS } from './client/live-effects';
 export type { Effect, EffectKind, EffectResult, LiveIntent, LiveTickResult, LiveModule } from './client/live-effects';

package/dist/index.js

@@ -4929,6 +4929,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
@@ -6607,6 +6614,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.
 //
@@ -7510,6 +7584,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
@@ -7522,18 +7597,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) {
@@ -7614,7 +7685,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,
         });
     }
@@ -7642,43 +7713,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
@@ -7689,7 +7812,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
@@ -7778,6 +7901,8 @@ exports.invokeFunction = invoke;
 exports.isEffectResult = isEffectResult;
 exports.live = live;
 exports.liveIntent = intent;
+exports.liveStatus = status;
+exports.now = now;
 exports.queryAggregate = queryAggregate;
 exports.reconnectWithNewAuth = reconnectWithNewAuth;
 exports.refreshSession = refreshSession;
@@ -7798,6 +7923,8 @@ exports.signSessionCreateMessage = signSessionCreateMessage;
 exports.signTransaction = signTransaction;
 exports.subscribe = subscribe;
 exports.subscribeLiveView = subscribeView;
+exports.toMillis = toMillis;
+exports.toSeconds = toSeconds;
 exports.withEffects = withEffects;
 exports.wsDelete = wsDelete;
 exports.wsGet = wsGet;