@bounded-sh/core 0.0.3 → 0.0.5

package/dist/client/operations.d.ts

@@ -25,6 +25,18 @@ export declare class InsufficientBalanceError extends Error {
     deficitSol: number;
     constructor(address: string, balanceLamports: number, estimatedCostLamports: number, deficitLamports: number, deficitSol: number);
 }
+/**
+ * Return the leaf document key (last path segment) for a document path.
+ *
+ * Bounded rows carry `_id` (and `pathId`) set to the FULL document path
+ * (e.g. `"rooms/r1/prompts/8rd49se3sg"`). Apps that build a child path from a
+ * row naturally want the bare doc key, not the whole path — using the full path
+ * doubles it (`rooms/r1/prompts/rooms/r1/prompts/8rd.../votes/...`) → 403/404.
+ * `docId` extracts that leaf key. Tolerates leading slashes and a trailing `*`.
+ *
+ * @example docId("rooms/r1/prompts/8rd49se3sg") // "8rd49se3sg"
+ */
+export declare function docId(path: string): string;
 /**
  * Options for the get function.
  */

package/dist/index.d.ts

@@ -1,12 +1,13 @@
 export { init } from './client/config';
 export { getConfig, ClientConfig } from './client/config';
 export { getWebhookKeysUrl } from './client/config';
-export { get, getMany, set, setMany, setFile, getFiles, search, queryAggregate, runQuery, runQueryMany, runExpression, runExpressionMany, signMessage, signTransaction, signAndSubmitTransaction, count, aggregate, RequestOverrides, SetOptions, GetOptions, SearchOptions, RunQueryOptions, CountOptions, AggregateOptions, AggregateOperation, AggregateResult, AggregateSpec, AggregateRow, QueryAggregateOptions, RunExpressionOptions, RunExpressionResult, InsufficientBalanceError, GetManyResult } from './client/operations';
+export { get, getMany, docId, set, setMany, setFile, getFiles, search, queryAggregate, runQuery, runQueryMany, runExpression, runExpressionMany, signMessage, signTransaction, signAndSubmitTransaction, count, aggregate, RequestOverrides, SetOptions, GetOptions, SearchOptions, RunQueryOptions, CountOptions, AggregateOptions, AggregateOperation, AggregateResult, AggregateSpec, AggregateRow, QueryAggregateOptions, RunExpressionOptions, RunExpressionResult, InsufficientBalanceError, GetManyResult } from './client/operations';
 export { subscribe, closeAllSubscriptions, clearCache, getCachedData, reconnectWithNewAuth } from './client/subscription';
 export { hasActiveConnection, wsGet, wsSet, wsQuery, wsDelete, wsGetMany } from './client/subscription-v2';
 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';

package/dist/index.js

@@ -4277,6 +4277,87 @@ const pendingRequests = {};
 const GET_CACHE_TTL = 500; // Adjust this value as needed (in milliseconds)
 // Last time we cleaned up the cache
 let lastCacheCleanup = Date.now();
+/**
+ * Return the leaf document key (last path segment) for a document path.
+ *
+ * Bounded rows carry `_id` (and `pathId`) set to the FULL document path
+ * (e.g. `"rooms/r1/prompts/8rd49se3sg"`). Apps that build a child path from a
+ * row naturally want the bare doc key, not the whole path — using the full path
+ * doubles it (`rooms/r1/prompts/rooms/r1/prompts/8rd.../votes/...`) → 403/404.
+ * `docId` extracts that leaf key. Tolerates leading slashes and a trailing `*`.
+ *
+ * @example docId("rooms/r1/prompts/8rd49se3sg") // "8rd49se3sg"
+ */
+function docId(path) {
+    if (typeof path !== 'string')
+        return '';
+    let p = path.startsWith('/') ? path.slice(1) : path;
+    if (p.endsWith('*') && p.length > 1)
+        p = p.slice(0, -1);
+    if (p.endsWith('/'))
+        p = p.slice(0, -1);
+    const segments = p.split('/').filter(Boolean);
+    return segments.length ? segments[segments.length - 1] : '';
+}
+/**
+ * Additively attach a convenience bare `id` (the leaf doc key) to a returned row.
+ *
+ * Rows already carry `_id`/`pathId` = the full document path; this leaves those
+ * untouched and adds `id` = the last path segment so `row.id` is the doc key apps
+ * expect. No-ops for non-objects, arrays, and rows that already define `id`
+ * (never clobber a user field named `id`). Source for the leaf is `_id` (falling
+ * back to `pathId`/`relativePath`/`absolutePath`).
+ */
+function withBareId(row) {
+    var _a, _b, _c;
+    if (!row || typeof row !== 'object' || Array.isArray(row))
+        return row;
+    const r = row;
+    if ('id' in r)
+        return row; // don't clobber an explicit user field
+    const source = (_c = (_b = (_a = r._id) !== null && _a !== void 0 ? _a : r.pathId) !== null && _b !== void 0 ? _b : r.relativePath) !== null && _c !== void 0 ? _c : r.absolutePath;
+    if (typeof source !== 'string' || source.length === 0)
+        return row;
+    const leaf = docId(source);
+    if (!leaf)
+        return row;
+    return Object.assign(Object.assign({}, r), { id: leaf });
+}
+/**
+ * Normalize a raw read response from the worker into the SDK's stable shape and
+ * attach the bare `id` to every returned row (Bug 1 + Bug 2).
+ *
+ * - Single-document path: returns EXACTLY ONE shape — the resolved document, or
+ *   `null` if missing (Firebase/Mongo convention). Unwraps the ambiguous
+ *   `{ data, status }` envelope the worker sometimes emits for a single doc so a
+ *   single-doc `get` never sometimes-returns the doc and sometimes the envelope.
+ * - Collection path: preserves the `{ data, nextCursor, ... }` envelope and maps
+ *   the bare `id` onto each row in `data`.
+ */
+function normalizeReadResult(responseData, pathIsDocument) {
+    if (pathIsDocument) {
+        let doc = responseData;
+        // Unwrap the single-doc envelope `{ data, status }` (Bug 2). A real document
+        // never has the exact shape `{ data, status }` with nothing else meaningful,
+        // so detect the envelope by `data` being present alongside a numeric `status`.
+        if (doc && typeof doc === 'object' && !Array.isArray(doc) &&
+            'data' in doc && 'status' in doc && typeof doc.status === 'number') {
+            doc = doc.data;
+        }
+        if (doc === undefined || doc === null)
+            return null;
+        return withBareId(doc);
+    }
+    // Collection read. The worker body is `{ data: rows[], nextCursor?, status? }`.
+    if (responseData && typeof responseData === 'object' && !Array.isArray(responseData) && Array.isArray(responseData.data)) {
+        return Object.assign(Object.assign({}, responseData), { data: responseData.data.map((row) => withBareId(row)) });
+    }
+    // Some paths return a bare array of rows — map id onto each.
+    if (Array.isArray(responseData)) {
+        return responseData.map((row) => withBareId(row));
+    }
+    return responseData;
+}
 function hashForKey$1(value) {
     let h = 5381;
     for (let i = 0; i < value.length; i++) {
@@ -4701,7 +4782,7 @@ async function get(path, opts = {}) {
                         if (hasActiveConnection()) {
                             if (pathIsDocument) {
                                 const wsResult = await wsGet(normalizedPath);
-                                const responseData = wsResult;
+                                const responseData = normalizeReadResult(wsResult, true);
                                 if (!opts.bypassCache) {
                                     getCache[cacheKey] = { data: responseData, expiresAt: now + GET_CACHE_TTL };
                                 }
@@ -4713,7 +4794,7 @@ async function get(path, opts = {}) {
                                     sort: undefined,
                                     includeSubPaths: opts.includeSubPaths,
                                 });
-                                const responseData = wsResult;
+                                const responseData = normalizeReadResult(wsResult, false);
                                 if (!opts.bypassCache) {
                                     getCache[cacheKey] = { data: responseData, expiresAt: now + GET_CACHE_TTL };
                                 }
@@ -4744,7 +4825,11 @@ async function get(path, opts = {}) {
                     const apiPath = `items?path=${path}${promptQueryParam}${filterParam}${sortParam}${includeSubPathsParam}${shapeParam}${limitParam}${cursorParam}`;
                     response = await makeApiRequest('GET', apiPath, null, opts._overrides);
                 }
-                const responseData = response.data;
+                // Normalize the worker's raw body into the SDK's stable shape:
+                //   - single-doc path → the resolved document or null (Bug 2), and
+                //   - collection path → `{ data, nextCursor }` preserved,
+                // with the bare `id` (leaf doc key) attached to every returned row (Bug 1).
+                const responseData = normalizeReadResult(response.data, pathIsDocument);
                 // Cache the response (unless bypassing cache)
                 if (!opts.bypassCache) {
                     getCache[cacheKey] = {
@@ -4842,11 +4927,16 @@ async function getMany(paths, opts = {}) {
                 const normalizedPath = uncachedPaths[i];
                 const serverResult = serverResultsMap.get(normalizedPath);
                 if (serverResult) {
-                    results[originalIndex] = serverResult;
-                    if (!serverResult.error && !opts.bypassCache) {
+                    // getMany batches single-doc paths — attach the bare `id` (leaf doc
+                    // key) to each returned doc, additive (Bug 1), matching get().
+                    const normalizedResult = serverResult.error
+                        ? serverResult
+                        : Object.assign(Object.assign({}, serverResult), { data: withBareId(serverResult.data) });
+                    results[originalIndex] = normalizedResult;
+                    if (!normalizedResult.error && !opts.bypassCache) {
                         const cacheKey = `${principalKey}|${normalizedPath}:`;
                         getCache[cacheKey] = {
-                            data: serverResult.data,
+                            data: normalizedResult.data,
                             expiresAt: now + GET_CACHE_TTL
                         };
                     }
@@ -5391,6 +5481,7 @@ var operations = /*#__PURE__*/Object.freeze({
     aggregate: aggregate,
     clearReadCacheForAuthChange: clearReadCacheForAuthChange,
     count: count,
+    docId: docId,
     get: get,
     getFiles: getFiles,
     getMany: getMany,
@@ -5978,14 +6069,46 @@ function handleServerMessage(connection, message) {
         }
     }
 }
+/**
+ * Additively attach the bare `id` (leaf doc key) to a subscription row (Bug 1).
+ * Rows carry `_id`/`pathId` = the full document path; this leaves those as-is and
+ * adds `id` = the last path segment so `row.id` is the doc key apps expect. No-ops
+ * for non-objects and rows that already define `id`.
+ */
+function withSubscriptionId(row) {
+    var _a, _b, _c;
+    if (!row || typeof row !== 'object' || Array.isArray(row))
+        return row;
+    if ('id' in row)
+        return row;
+    const source = (_c = (_b = (_a = row._id) !== null && _a !== void 0 ? _a : row.pathId) !== null && _b !== void 0 ? _b : row.relativePath) !== null && _c !== void 0 ? _c : row.absolutePath;
+    if (typeof source !== 'string' || source.length === 0)
+        return row;
+    const leaf = docId(source);
+    if (!leaf)
+        return row;
+    return Object.assign(Object.assign({}, row), { id: leaf });
+}
+/**
+ * The `onData` payload follows the path: a collection delivers a bare array of
+ * rows, a single-doc path delivers the document (or null). Attach the bare `id`
+ * to each returned row in either case, additive (Bug 1).
+ */
+function addIdsToSubscriptionData(data) {
+    if (Array.isArray(data))
+        return data.map(withSubscriptionId);
+    return withSubscriptionId(data);
+}
 function notifyCallbacks(subscription, data) {
     var _a;
+    // Attach the bare `id` (leaf doc key) to every delivered row (Bug 1).
+    const decorated = addIdsToSubscriptionData(data);
     // Snapshot the callbacks array so that unsubscriptions during
     // notification don't cause callbacks to be skipped.
     const callbacks = subscription.callbacks.slice();
     for (const callback of callbacks) {
         try {
-            (_a = callback.onData) === null || _a === void 0 ? void 0 : _a.call(callback, data);
+            (_a = callback.onData) === null || _a === void 0 ? void 0 : _a.call(callback, decorated);
         }
         catch (error) {
             console.error('[WS v2] Error in subscription callback:', error);
@@ -6076,7 +6199,7 @@ async function subscribeV2(path, subscriptionOptions, roomRoutePath) {
     if (cachedEntry && Date.now() - cachedEntry.timestamp < CACHE_TTL && subscriptionOptions.onData) {
         setTimeout(() => {
             var _a;
-            (_a = subscriptionOptions.onData) === null || _a === void 0 ? void 0 : _a.call(subscriptionOptions, cachedEntry.data);
+            (_a = subscriptionOptions.onData) === null || _a === void 0 ? void 0 : _a.call(subscriptionOptions, addIdsToSubscriptionData(cachedEntry.data));
         }, 0);
     }
     // Get or create connection for this routing target (room-scoped when a
@@ -6106,7 +6229,7 @@ async function subscribeV2(path, subscriptionOptions, roomRoutePath) {
         if (existingSubscription.lastData !== undefined && subscriptionOptions.onData) {
             setTimeout(() => {
                 var _a;
-                (_a = subscriptionOptions.onData) === null || _a === void 0 ? void 0 : _a.call(subscriptionOptions, existingSubscription.lastData);
+                (_a = subscriptionOptions.onData) === null || _a === void 0 ? void 0 : _a.call(subscriptionOptions, addIdsToSubscriptionData(existingSubscription.lastData));
             }, 0);
         }
         return async () => {
@@ -6614,6 +6737,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.
 //
@@ -7815,6 +8005,7 @@ exports.count = count;
 exports.createSessionWithSignature = createSessionWithSignature;
 exports.defineLiveModule = defineLiveModule;
 exports.deriveUserIdentityFromIdToken = deriveUserIdentityFromIdToken;
+exports.docId = docId;
 exports.functions = functions;
 exports.genAuthNonce = genAuthNonce;
 exports.genSolanaMessage = genSolanaMessage;
@@ -7835,6 +8026,7 @@ exports.isEffectResult = isEffectResult;
 exports.live = live;
 exports.liveIntent = intent;
 exports.liveStatus = status;
+exports.now = now;
 exports.queryAggregate = queryAggregate;
 exports.reconnectWithNewAuth = reconnectWithNewAuth;
 exports.refreshSession = refreshSession;
@@ -7855,6 +8047,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;