@bounded-sh/core 0.0.3 → 0.0.4

package/dist/index.mjs

@@ -6594,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.
 //
@@ -7778,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, status as liveStatus, 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