@buoy-gg/clock 7.0.42

package/lib/typescript/components/ClockChip.d.ts

@@ -0,0 +1,11 @@
+import { type FloatingToolRenderContext } from "@buoy-gg/shared-ui";
+export declare const CLOCK_CHIP_ID = "clock-chip";
+/** Show the chip now (e.g. from the tool's header). */
+export declare function openClockChip(): void;
+/**
+ * Open the chip when an override starts and close it when the clock goes
+ * back to real time. Idempotent.
+ */
+export declare function watchClockChip(): void;
+export declare function ClockChip({ id, revealToken }: FloatingToolRenderContext): import("react").JSX.Element;
+//# sourceMappingURL=ClockChip.d.ts.map

package/lib/typescript/components/ClockToolView.d.ts

@@ -0,0 +1,10 @@
+import type { ClockSnapshot } from "../engine/clockStore";
+export type ClockActionHandler = (action: string, params?: Record<string, unknown>) => Promise<unknown>;
+export interface ClockToolViewProps {
+    snapshot: ClockSnapshot | null;
+    onAction: ClockActionHandler;
+    /** Reload the app's JS so screens re-read the clock. Hidden when absent. */
+    onReload?: () => void;
+}
+export declare function ClockToolView({ snapshot, onAction, onReload }: ClockToolViewProps): import("react").JSX.Element;
+//# sourceMappingURL=ClockToolView.d.ts.map

package/lib/typescript/components/TokenSection.d.ts

@@ -0,0 +1,10 @@
+import type { ClockSnapshot } from "../engine/clockStore";
+type Run = (action: string, params?: Record<string, unknown>) => void;
+export declare function TokenSection({ snapshot, run, openId, onToggle, }: {
+    snapshot: ClockSnapshot;
+    run: Run;
+    openId: string | null;
+    onToggle: (id: string) => void;
+}): import("react").JSX.Element;
+export {};
+//# sourceMappingURL=TokenSection.d.ts.map

package/lib/typescript/components/format.d.ts

@@ -0,0 +1,18 @@
+import type { ClockSnapshot } from "../engine/clockStore";
+import type { NightBadgeTone } from "@buoy-gg/shared-ui";
+/** "14:03:22" in the device's time zone. */
+export declare function formatClockTime(ms: number): string;
+/** "Tue, Sep 29, 2026". Built by hand so it reads the same on every engine. */
+export declare function formatClockDate(ms: number): string;
+/** "Sep 30 · 14:03" for the chip. */
+export declare function formatChipTime(ms: number, withSeconds?: boolean): string;
+/** "2026-09-29 14:03": what the time field shows and accepts. */
+export declare function formatInputTime(ms: number): string;
+/** "+1d 3h ahead" / "2h behind" / "matches real time". */
+export declare function formatOffset(offsetMs: number): string;
+export declare function clockStatus(snapshot: Pick<ClockSnapshot, "mode" | "rate">): {
+    label: string;
+    tone: NightBadgeTone;
+};
+export declare function jumpTestId(ms: number): string;
+//# sourceMappingURL=format.d.ts.map

package/lib/typescript/components/useLiveClock.d.ts

@@ -0,0 +1,22 @@
+import type { ClockSnapshot } from "../engine/clockStore";
+export interface LiveClock {
+    /** What the app's clock reads now. */
+    virtual: number;
+    /** The device's real clock now. */
+    real: number;
+}
+/**
+ * Keep a snapshot's clocks moving between snapshots. The store only emits on
+ * changes, so the display extrapolates from the last one: the app's clock
+ * advances `rate` times as fast as real time, or not at all when frozen.
+ *
+ * Elapsed time is measured from the snapshot's own `realNow`, not from when
+ * this component first saw it: a cached snapshot can be minutes old by the
+ * time the tool opens. On Buoy Desktop that assumes the desktop and device
+ * clocks agree, which NTP keeps within milliseconds for simulators and
+ * normally-configured phones.
+ *
+ * Only the component that calls this re-renders on the tick.
+ */
+export declare function useLiveClock(snapshot: ClockSnapshot | null, everyMs?: number): LiveClock;
+//# sourceMappingURL=useLiveClock.d.ts.map

package/lib/typescript/engine/clockMath.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The clock model, as pure functions of (anchor, real time).
+ *
+ * One anchor describes every override: at real time `anchorReal` the app's
+ * clock read `anchorVirtual`, and since then it has moved `rate` times as
+ * fast as the real clock (or not at all when frozen). Every operation
+ * re-anchors at the current moment, so the virtual clock never jumps unless
+ * the operation asked it to.
+ *
+ * Nothing here reads the clock or touches globals. Callers pass `real` in,
+ * so the whole model is testable without patching anything.
+ */
+export type ClockMode = "real" | "running" | "frozen";
+export interface ClockAnchor {
+    mode: ClockMode;
+    /** Real epoch ms when this anchor was set. */
+    anchorReal: number;
+    /** What the app's clock read at `anchorReal`. */
+    anchorVirtual: number;
+    /** Virtual ms per real ms while running. 1 = normal speed. */
+    rate: number;
+}
+export declare const REAL_ANCHOR: ClockAnchor;
+export declare const MIN_RATE = 0.1;
+export declare const MAX_RATE = 86400;
+export declare function virtualAt(anchor: ClockAnchor, real: number): number;
+/** Virtual minus real, at `real`. 0 when the override is off. */
+export declare function offsetAt(anchor: ClockAnchor, real: number): number;
+/** Move the app's clock to `target`. Keeps the current speed. */
+export declare function travelTo(anchor: ClockAnchor, real: number, target: number, freeze?: boolean): ClockAnchor;
+/** Move the app's clock by `deltaMs`. A frozen clock stays frozen. */
+export declare function shiftBy(anchor: ClockAnchor, real: number, deltaMs: number): ClockAnchor;
+/** Stop the app's clock at `at`, or at whatever it reads now. */
+export declare function freezeAt(anchor: ClockAnchor, real: number, at?: number): ClockAnchor;
+/** Start a frozen clock again from the moment it was frozen at. */
+export declare function resume(anchor: ClockAnchor, real: number): ClockAnchor;
+/** Run the app's clock `rate` times as fast, starting from what it reads now. */
+export declare function withRate(anchor: ClockAnchor, real: number, rate: number): ClockAnchor;
+export declare function isAnchor(value: unknown): value is ClockAnchor;
+/**
+ * "+1d", "-2h30m", "90s", "1.5 hours", "-1w 2d", or a number of ms.
+ * Months are 30 days and years 365 days; use setTime for calendar dates.
+ */
+export declare function parseDuration(input: string | number): number;
+/** "+2d 3h", "−45m", "+12s", "0s". Drops units below the two largest. */
+export declare function formatDuration(ms: number, { signed }?: {
+    signed?: boolean | undefined;
+}): string;
+/**
+ * An absolute time from user or agent input: epoch ms (number or digits),
+ * an ISO 8601 string, anything the platform's Date.parse accepts, or a
+ * relative "+1d" / "-2h" measured from `now`.
+ */
+export declare function parseTime(input: string | number, now: number, parse: (text: string) => number): number;
+export interface TimePreset {
+    id: string;
+    label: string;
+    /** Short line under the label. */
+    hint: string;
+    at(now: number, DateCtor: DateConstructor): number;
+}
+export declare const TIME_PRESETS: readonly TimePreset[];
+/** Jump sizes offered as one-tap chips. */
+export declare const JUMPS: readonly {
+    label: string;
+    ms: number;
+}[];
+export declare const SPEEDS: readonly number[];
+export declare function formatRate(rate: number): string;
+//# sourceMappingURL=clockMath.d.ts.map

package/lib/typescript/engine/clockStore.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The clock override's single source of truth on the device.
+ *
+ * Holds the anchor and settings, keeps the global patches in step with them
+ * (installed while an override is on, removed when it is reset), fires due
+ * timers on forward jumps, and saves every change. The UI, the sync adapter
+ * (desktop + MCP + Ask Buoy) and the floating chip all go through the
+ * actions here, so there is one behavior whichever surface changed the clock.
+ */
+import { type ClockAnchor, type ClockMode } from "./clockMath";
+import { type TimerSummary } from "./timers";
+import { type ClockSettings } from "./persistence";
+import { type TokenReport } from "../tokens/tokenStore";
+export interface LastJump {
+    /** Signed ms the clock moved. */
+    byMs: number;
+    /** Timer callbacks the jump ran. */
+    firedTimers: number;
+    /** Real ms when it happened. */
+    at: number;
+}
+export declare function subscribeClock(listener: () => void): () => void;
+export declare function getClockAnchor(): ClockAnchor;
+export declare function getClockSettings(): ClockSettings;
+/** What the app's clock reads now (real time when no override is on). */
+export declare function virtualNow(): number;
+export declare function isClockOverridden(): boolean;
+export type TimeInput = string | number;
+/** Move the app's clock to a moment. Keeps running unless `freeze`. */
+export declare function setTime(time: TimeInput, freeze?: boolean): ClockSnapshot;
+/**
+ * Move the app's clock by a duration ("+1d", "-2h", or ms). Moving forward
+ * runs the timers due inside the jump unless `fireTimers` is false (default:
+ * the `fireTimersOnJump` setting).
+ */
+export declare function shift(by: TimeInput, fireTimers?: boolean): ClockSnapshot;
+/** Stop the app's clock, at `time` if given, else at what it reads now. */
+export declare function freeze(time?: TimeInput): ClockSnapshot;
+/** Start a frozen clock again from where it stopped. */
+export declare function resume(): ClockSnapshot;
+/** Run the app's clock `rate` times as fast (1 = normal). */
+export declare function setRate(rate: number): ClockSnapshot;
+/** Back to the device's real clock. */
+export declare function reset(): ClockSnapshot;
+export declare function updateSettings(patch: Partial<ClockSettings>): ClockSnapshot;
+/** Timer callbacks a forward jump of `byMs` would run right now. */
+export declare function previewJump(byMs: number): number;
+/**
+ * Start tracking timers and restore a saved override. Idempotent. Runs at
+ * package import in dev builds on a real React Native runtime; call it from
+ * your entry file to have a saved override in place before any app module
+ * reads the clock.
+ */
+export declare function bootClock(): void;
+export declare function isClockBooted(): boolean;
+export interface ClockSnapshot {
+    mode: ClockMode;
+    /** Whether any override is on. */
+    active: boolean;
+    rate: number;
+    /** What the app's clock read when this snapshot was taken (epoch ms). */
+    virtualNow: number;
+    virtualIso: string;
+    /** The device's real clock at the same moment. */
+    realNow: number;
+    /** virtualNow − realNow. */
+    offsetMs: number;
+    /** The device's time zone, which the override never changes. */
+    timeZone: string;
+    timers: TimerSummary;
+    lastJump: LastJump | null;
+    changedAt: number | null;
+    settings: ClockSettings;
+    hydrated: boolean;
+    /** The app's sign-in tokens, read from Network's captured requests. */
+    tokens: TokenReport;
+    /** Which patches are live, for answering "why didn't X move". */
+    patched: {
+        date: boolean;
+        intl: boolean;
+        timers: boolean;
+        animatedOnRealClock: boolean;
+    };
+}
+export declare function getClockSnapshot(): ClockSnapshot;
+/**
+ * A snapshot object that only changes identity when the store changes,
+ * what `useSyncExternalStore` needs. Its times are as of that change; use
+ * `useLiveClock` for a ticking display.
+ */
+export declare function getStableClockSnapshot(): ClockSnapshot;
+/** Test seam. */
+export declare function __resetClockStoreForTests(): void;
+//# sourceMappingURL=clockStore.d.ts.map

package/lib/typescript/engine/patches.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The global patches: `Date`, no-argument `Intl.DateTimeFormat` formatting,
+ * and a real-clock scope for React Native's JS-driven animations.
+ *
+ * `Date` is replaced by a function that shares the real `Date.prototype`, so
+ * `instanceof Date`, `Object.prototype.toString` and every Date method keep
+ * working on dates made before, during and after an override. Only the two
+ * ways of asking "what time is it" change: `new Date()` with no arguments and
+ * `Date.now()`. `Date()` called without `new` returns the virtual time as a
+ * string, as it would natively.
+ *
+ * Everything is reversible: `uninstallDatePatches()` puts the originals back
+ * when the override is reset, so a clock at real time costs nothing.
+ */
+/**
+ * The real Date, captured once. If another copy of this package already
+ * installed its patch, that copy published the real constructor first.
+ */
+export declare const RealDate: DateConstructor;
+/**
+ * The device's real clock. Published on `globalThis.__buoyRealNow` so Buoy's
+ * own packages (license checks, sync throttles, Ask Buoy deadlines) can keep
+ * measuring real time while the app's clock is overridden.
+ */
+export declare function realNow(): number;
+/** What `Date.now()` returns right now, honoring real-clock scopes. */
+export declare function currentNow(): number;
+/** What the app's clock reads now, even inside a real-clock scope. */
+export declare function appNow(): number;
+/** Point the patches at a virtual clock, or `null` for real time. */
+export declare function setVirtualSource(source: ((real: number) => number) | null): void;
+/** Run `fn` against the real clock even while an override is active. */
+export declare function withRealClock<T>(fn: () => T): T;
+export declare const PatchedDate: DateConstructor;
+export declare function isDatePatched(): boolean;
+export declare function isIntlPatched(): boolean;
+/** Install the Date + Intl patches. Idempotent. */
+export declare function installDatePatches(): void;
+/** Put the real Date and Intl back. Idempotent. */
+export declare function uninstallDatePatches(): void;
+export declare function installAnimatedRealClock(Animated: unknown): boolean;
+export declare function isAnimatedRealClock(): boolean;
+//# sourceMappingURL=patches.d.ts.map

package/lib/typescript/engine/persistence.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Saving the override so it survives a reload.
+ *
+ * Writes go through Buoy's `persistentStorage` (a file under
+ * Documents/react-buoy/ when expo-file-system is installed, AsyncStorage
+ * otherwise). Reads try the same file SYNCHRONOUSLY first, through
+ * expo-file-system's `File.textSync()` (SDK 54+), so a saved override is back
+ * in place before the app's own modules read the clock. Without that API the
+ * read is async and the override lands a few milliseconds into startup.
+ */
+import { type ClockAnchor } from "./clockMath";
+export { readSavedSync } from "./readSavedSync";
+export interface ClockSettings {
+    /** Keep the override across reloads and restarts. */
+    persist: boolean;
+    /** Show the floating clock chip while an override is on. */
+    showChip: boolean;
+    /** Forward jumps run the timers that come due inside them. */
+    fireTimersOnJump: boolean;
+}
+export declare const DEFAULT_SETTINGS: ClockSettings;
+export interface SavedClock {
+    v: 1;
+    anchor: ClockAnchor | null;
+    settings: ClockSettings;
+}
+export declare const CLOCK_STORAGE_KEY: "@react_buoy_clock_state";
+export declare function parseSaved(raw: string | null | undefined): SavedClock | null;
+export declare function readSavedAsync(): Promise<SavedClock | null>;
+/** Queue a write; the last call wins. */
+export declare function writeSaved(saved: SavedClock): Promise<void>;
+//# sourceMappingURL=persistence.d.ts.map

package/lib/typescript/engine/readSavedSync.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Read the saved override synchronously, from the file persistentStorage
+ * writes under Documents/react-buoy/, via expo-file-system's `File.textSync()`
+ * (SDK 54+). `undefined` means a synchronous read isn't possible here.
+ */
+import { type SavedClock } from "./persistence";
+/** The saved override, read synchronously, or `undefined` if that's impossible here. */
+export declare function readSavedSync(): SavedClock | null | undefined;
+//# sourceMappingURL=readSavedSync.d.ts.map

package/lib/typescript/engine/readSavedSync.web.d.ts

@@ -0,0 +1,4 @@
+import type { SavedClock } from "./persistence";
+/** Web and Buoy Desktop never patch their own clock, so there is nothing to read early. */
+export declare function readSavedSync(): SavedClock | null | undefined;
+//# sourceMappingURL=readSavedSync.web.d.ts.map

package/lib/typescript/engine/timers.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Timer tracking, so a forward jump can fire the timers that would have come
+ * due inside it.
+ *
+ * `setTimeout` / `setInterval` are wrapped to remember each pending callback
+ * and when it is due on a "timer clock": real time plus every forward jump so
+ * far. A jump of Δ advances that clock and runs every callback now due, once,
+ * in due order, the same rule as Playwright's `clock.fastForward`. Timeouts
+ * still pending are rescheduled to their shortened remaining time. Timers
+ * created by those callbacks are scheduled from
+ * the new time and are not run by the same jump. Delays are never scaled:
+ * doing that at 60× would turn every tap into a long press, because
+ * Pressability times presses with setTimeout.
+ *
+ * Wrappers compose with other patches (Buoy's JS Top wraps the same globals):
+ * whatever was installed before is what gets called. Handles are the real
+ * handles, so code that stores or compares them sees no difference. Code that
+ * captured `setTimeout` before this module loaded is not tracked.
+ */
+export declare function isTimerTrackingInstalled(): boolean;
+/** Wrap the timer globals. Idempotent; safe to call before any override. */
+export declare function installTimerTracking(): boolean;
+/** Test seam: put the originals back and forget every handle. */
+export declare function uninstallTimerTracking(): void;
+export interface TimerSummary {
+    /** Pending timeouts plus live intervals. */
+    total: number;
+    timeouts: number;
+    intervals: number;
+    /** Real ms until the soonest one-shot timeout, if any. */
+    nextTimeoutInMs: number | null;
+}
+export declare function summarizeTimers(): TimerSummary;
+/** How many tracked timers a jump of `windowMs` would run. */
+export declare function countDueWithin(windowMs: number): number;
+/**
+ * Advance the timer clock by `windowMs` and run every tracked timer that is
+ * now due, once, soonest first. Due timeouts are cancelled so they do not run
+ * again; intervals keep ticking. Timeouts that are still pending are
+ * rescheduled to fire when their shortened remaining time runs out, so a 2h
+ * timeout fires one real hour after a +1h jump. Returns how many ran.
+ */
+export declare function fireDueWithin(windowMs: number): number;
+//# sourceMappingURL=timers.d.ts.map

package/lib/typescript/index.d.ts

@@ -0,0 +1,19 @@
+export { clockToolPreset, createClockTool } from "./preset";
+export { ClockBody } from "./components/ClockBody";
+export { ClockToolView } from "./components/ClockToolView";
+export type { ClockToolViewProps, ClockActionHandler } from "./components/ClockToolView";
+export { ClockChip, openClockChip, CLOCK_CHIP_ID } from "./components/ClockChip";
+export { useLiveClock } from "./components/useLiveClock";
+export { ClockToolIcon, CLOCK_TOOL_ICON_COLOR } from "@buoy-gg/shared-ui";
+export { clockSyncAdapter } from "./sync/clockSyncAdapter";
+export { bootClock, setTime, shift, freeze, resume, setRate, reset, updateSettings, virtualNow, isClockOverridden, getClockSnapshot, subscribeClock, previewJump, } from "./engine/clockStore";
+export type { ClockSnapshot, LastJump, TimeInput } from "./engine/clockStore";
+export type { ClockSettings } from "./engine/persistence";
+export { realNow, withRealClock } from "./engine/patches";
+export { parseDuration, formatDuration, TIME_PRESETS, type ClockMode, type ClockAnchor, } from "./engine/clockMath";
+export { startTokenWatch, getTokenReport } from "./tokens/tokenStore";
+export type { TokenReport, TokenSummary, TokenCheck } from "./tokens/tokenStore";
+export { jumpToTokenExpiry, failNextRequest, stopTokenCheck } from "./tokens/tokenActions";
+export { inspectToken, fingerprint as tokenFingerprint } from "./tokens/decode";
+export type { TokenInfo, TokenFormat } from "./tokens/decode";
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/preset.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Pre-configured Clock tool for FloatingDevTools.
+ *
+ * @example
+ * ```tsx
+ * import { clockToolPreset } from '@buoy-gg/clock';
+ *
+ * <FloatingDevTools apps={[clockToolPreset]} />
+ * ```
+ */
+import { ClockBody } from "./components/ClockBody";
+export declare const clockToolPreset: {
+    id: string;
+    name: string;
+    description: string;
+    slot: "both";
+    color: string;
+    icon: ({ size, color }: {
+        size: number;
+        color?: string;
+        slot?: string;
+    }) => import("react").JSX.Element;
+    component: typeof ClockBody;
+    modal: {
+        subtitle: string;
+    };
+};
+/** Create a custom Clock tool configuration. */
+export declare const createClockTool: (options?: (Record<never, never> & import("@buoy-gg/shared-ui").ToolPresetOverrides) | undefined) => {
+    id: string;
+    name: string;
+    description: string;
+    slot: "both";
+    color: string;
+    icon: ({ size, color }: {
+        size: number;
+        color?: string;
+        slot?: string;
+    }) => import("react").JSX.Element;
+    component: typeof ClockBody;
+    modal: {
+        subtitle: string;
+    };
+};
+//# sourceMappingURL=preset.d.ts.map

package/lib/typescript/sync/clockSyncAdapter.d.ts

@@ -0,0 +1,30 @@
+/**
+ * clockSyncAdapter: the clock override over external-sync.
+ *
+ * One adapter serves Buoy Desktop, the MCP server (`get_clock` /
+ * `clock_action`) and Ask Buoy's agent, so every surface gets the same
+ * actions with the same validation. Auto-discovery in @buoy-gg/core picks it
+ * up by export name and announces the "clock" capability.
+ *
+ * The snapshot carries both clocks as of the moment it was taken, plus the
+ * mode and rate, so a viewer can keep the display ticking without a stream
+ * of snapshots: virtual = virtualNow + (elapsed since receipt) × rate.
+ */
+import { type ClockSnapshot } from "../engine/clockStore";
+type Params = unknown;
+export declare const clockSyncAdapter: import("@buoy-gg/shared-ui").SyncAdapter<ClockSnapshot, {
+    getState(): ClockSnapshot;
+    setTime(params: Params): ClockSnapshot;
+    shift(params: Params): ClockSnapshot;
+    freeze(params: Params): ClockSnapshot;
+    resume(): ClockSnapshot;
+    setRate(params: Params): ClockSnapshot;
+    reset(): ClockSnapshot;
+    updateSettings(params: Params): ClockSnapshot;
+    jumpToTokenExpiry(params: Params): ClockSnapshot;
+    failNextRequest(params: Params): Promise<ClockSnapshot>;
+    stopTokenCheck(): Promise<ClockSnapshot>;
+}>;
+export type ClockAction = keyof NonNullable<typeof clockSyncAdapter.actions>;
+export {};
+//# sourceMappingURL=clockSyncAdapter.d.ts.map

package/lib/typescript/tokens/decode.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Read what a token says about itself, without any secret.
+ *
+ * Signed tokens carry their claims in plain (base64url) text: a JWT's middle
+ * part and a public PASETO's message are readable by anyone holding the token.
+ * The secret only proves the signature, which this never checks. Encrypted
+ * tokens (JWE, PASETO `local`) and opaque strings say nothing, so for those
+ * the expiry has to come from the response that issued them (see extract.ts).
+ *
+ * Pure, dependency-free and engine-agnostic: no `atob`, `TextDecoder` or
+ * `Buffer`, because none is guaranteed on every Hermes version.
+ */
+export type TokenFormat = "jwt" | "jwe" | "paseto-public" | "paseto-local" | "fernet" | "opaque";
+export interface TokenClaims {
+    /** Issuer, e.g. "https://securetoken.google.com/my-app". */
+    iss?: string;
+    aud?: string;
+    sub?: string;
+    scope?: string;
+    /** Signing algorithm from the JWT header (RS256, ES256, none...). */
+    alg?: string;
+    /** Cognito's `token_use`, or the JWT header `typ`. */
+    use?: string;
+}
+export interface TokenInfo {
+    format: TokenFormat;
+    /** "JWT · RS256", "Encrypted JWT", "PASETO v4", "Opaque". */
+    formatLabel: string;
+    /** Who likely issued it: "Firebase ID token", "Cognito access token"... */
+    hint?: string;
+    claims: TokenClaims;
+    /** Epoch ms. */
+    issuedAt?: number;
+    notBefore?: number;
+    expiresAt?: number;
+    /** Where `expiresAt` came from, in words ("exp claim"). */
+    expirySource?: string;
+    /**
+     * The token carries no expiry by design (an API key). Distinct from "we
+     * could not read one", which is every opaque token.
+     */
+    neverExpires?: boolean;
+}
+export declare function base64UrlToBytes(input: string): number[] | null;
+export declare function utf8Decode(bytes: number[]): string | null;
+/**
+ * An absolute time in whatever form a server chose: epoch seconds, epoch ms,
+ * or an ISO 8601 string. Numbers below 1e11 are seconds (1e11 s is the year
+ * 5138; 1e11 ms is 1973).
+ */
+export declare function absoluteTime(value: unknown, parse: (text: string) => number): number | undefined;
+/** A relative lifetime in seconds ("expires_in": 3600, Firebase's "3600"). */
+export declare function lifetimeSeconds(value: unknown): number | undefined;
+/**
+ * Everything a token says about itself. `null` when the string is not a
+ * token at all (too short, has spaces).
+ */
+export declare function inspectToken(raw: string, parse?: (text: string) => number): TokenInfo | null;
+/** Readable structure (not just a random string). */
+export declare function isStructured(info: TokenInfo | null): boolean;
+/**
+ * A short, stable id for a token that is not the token: FNV-1a over the whole
+ * string. Rows and refresh checks compare these, so the raw credential is
+ * never stored, synced or shown.
+ */
+export declare function fingerprint(token: string): string;
+//# sourceMappingURL=decode.d.ts.map

package/lib/typescript/tokens/extract.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Find tokens in captured network traffic. Pure: takes the Network tool's
+ * event shape (structurally, so this package never imports @buoy-gg/network)
+ * and returns what it saw.
+ *
+ * Two directions:
+ *
+ *  - Requests USE tokens: the Authorization header, token-named headers,
+ *    cookies and query parameters. Each becomes a candidate for a row.
+ *  - Responses ISSUE them: a login or refresh body (`access_token` with
+ *    `expires_in`, Supabase's `expires_at`, Cognito's `AuthenticationResult`,
+ *    Firebase's `expiresIn`, AWS's `Expiration`) and `Set-Cookie`. These give
+ *    opaque tokens an expiry they cannot carry themselves, and name the
+ *    endpoint that issued them.
+ *
+ * Raw token strings leave this module only as fingerprints.
+ */
+import { type TokenInfo } from "./decode";
+/** The fields of @buoy-gg/network's NetworkEvent this reads. */
+export interface CapturedRequest {
+    id: string;
+    method: string;
+    url: string;
+    status?: number;
+    requestHeaders?: Record<string, string>;
+    responseHeaders?: Record<string, string>;
+    responseData?: unknown;
+    /** Request start, epoch ms, as the app's clock read it. */
+    timestamp: number;
+    duration?: number;
+    override?: {
+        ruleId: string;
+    };
+}
+export type TokenLocation = "authorization" | "header" | "cookie" | "query";
+export interface TokenUse {
+    location: TokenLocation;
+    /** Header, cookie or parameter name. "Authorization" for that header. */
+    name: string;
+    /** "Bearer", "DPoP", "Token"... for the Authorization header. */
+    scheme?: string;
+    fp: string;
+    info: TokenInfo;
+}
+export interface Issuance {
+    fp: string;
+    info: TokenInfo;
+    /** "access", "id", "refresh", "session", "cookie", or the raw key. */
+    role: string;
+    /** Epoch ms on the app's clock, when known. */
+    expiresAt?: number;
+    expirySource?: string;
+    /**
+     * Set when the expiry was RELATIVE (`expires_in`, `Max-Age`): the app adds
+     * it to its own clock, the server to real time, so the two views differ
+     * once the app's clock is moved.
+     */
+    lifetimeMs?: number;
+    /** "POST /oauth/token". */
+    issuedBy: string;
+    /** The refresh token issued alongside, if any. */
+    refresh?: {
+        fp: string;
+        expiresAt?: number;
+        formatLabel: string;
+    };
+    /** Cookie name, for Set-Cookie issuances. */
+    cookie?: string;
+}
+export declare function originOf(url: string): string | null;
+export declare function hostOf(url: string): string;
+export declare function pathOf(url: string): string;
+export declare function tokensUsed(event: CapturedRequest, parse: (text: string) => number): TokenUse[];
+export declare function tokensIssued(event: CapturedRequest, parse: (text: string) => number): Issuance[];
+//# sourceMappingURL=extract.d.ts.map

package/lib/typescript/tokens/tokenActions.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The two ways to make an app refresh its token, and the check that watches
+ * whether it did. Apps refresh in one of two ways, so there are two actions:
+ *
+ *  - Proactively, by comparing the token's expiry with `Date.now()` before a
+ *    request or on a timer. `jumpToTokenExpiry` moves the app's clock to just
+ *    before the expiry (running due timers on the way), so the app's own
+ *    check fires. The server still accepts the old token, which is the point:
+ *    only the app's logic is under test.
+ *  - Reactively, after the server answers 401. Moving the app's clock cannot
+ *    cause that, because the server keeps real time, so `failNextRequest`
+ *    adds a one-shot Network override that answers the next request to the
+ *    token's API with a 401.
+ */
+import { type ClockSnapshot } from "../engine/clockStore";
+/**
+ * Move the app's clock to `leadMs` before the token expires (default 10 s,
+ * so the expiry happens in front of you), and watch for a new token.
+ */
+export declare function jumpToTokenExpiry(tokenId?: string, leadMs?: number): ClockSnapshot;
+/**
+ * Answer the next request to the token's API with `status` (401 by default),
+ * once, and watch for a new token.
+ */
+export declare function failNextRequest(tokenId?: string, status?: number, times?: number): Promise<ClockSnapshot>;
+/** Stop watching, and withdraw a 401 that has not reached the app yet. */
+export declare function stopTokenCheck(): Promise<ClockSnapshot>;
+//# sourceMappingURL=tokenActions.d.ts.map