@wayq/beekon-rn 0.0.5 → 0.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wayq/beekon-rn",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "React Native binding for the Beekon location SDK (Android + iOS).",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",
@@ -20,6 +20,7 @@
     "scripts/fetch-beekonkit.sh",
     "*.podspec",
     "LICENSE.txt",
+    "CHANGELOG.md",
     "!ios/build",
     "!android/build",
     "!android/gradle",
@@ -37,7 +38,8 @@
     "fetch-beekonkit": "bash scripts/fetch-beekonkit.sh",
     "prepare": "yarn fetch-beekonkit && bob build",
     "typecheck": "tsc",
-    "lint": "eslint \"**/*.{js,ts,tsx}\""
+    "lint": "eslint \"**/*.{js,ts,tsx}\"",
+    "test": "jest"
   },
   "keywords": [
     "react-native",
@@ -45,9 +47,12 @@
     "android",
     "location",
     "tracking",
+    "location-tracking",
     "gps",
+    "gps-tracking",
     "background-location",
     "geolocation",
+    "geofencing",
     "beekon",
     "turbo-module"
   ],
@@ -71,12 +76,15 @@
     "@eslint/js": "^10.0.1",
     "@react-native/babel-preset": "0.85.0",
     "@react-native/eslint-config": "0.85.0",
+    "@types/jest": "^29.5.14",
     "@types/react": "^19.2.0",
+    "babel-jest": "^29.7.0",
     "del-cli": "^7.0.0",
     "eslint": "^9.39.4",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-ft-flow": "^3.0.11",
     "eslint-plugin-prettier": "^5.5.5",
+    "jest": "^29.7.0",
     "prettier": "^3.8.1",
     "react": "19.2.3",
     "react-native": "0.85.0",

package/scripts/fetch-beekonkit.sh

@@ -13,12 +13,12 @@
 
 set -euo pipefail
 
-VERSION="0.0.5"
+VERSION="0.0.7"
 URL="https://github.com/wayqteam/beekon-ios-binary/releases/download/v${VERSION}/BeekonKit.xcframework.zip"
-# SHA256 of the v0.0.5 BeekonKit.xcframework.zip. Matches the SwiftPM
-# `binaryTarget` checksum in beekon-ios-binary's Package.swift at tag v0.0.5
+# SHA256 of the v0.0.7 BeekonKit.xcframework.zip. Matches the SwiftPM
+# `binaryTarget` checksum in beekon-ios-binary's Package.swift at tag v0.0.7
 # (SwiftPM's compute-checksum is the SHA256 of the zip).
-EXPECTED_SHA="437bf493d7de19d8df9599da097be162796a8304eb2d7826cf2505c33d4603f7"
+EXPECTED_SHA="48803b540f063f609230f44a0f5b7faca125847db9f4628d0bf5d31d351a762b"
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 DEST_DIR="${ROOT}/ios/Frameworks"

package/src/NativeBeekonRn.ts

@@ -27,17 +27,47 @@ export type WireKeyValue = {
   value: string;
 };
 
+/** Flat wire form of `AuthResponseMapping`. Omitted keys use common-name detection. */
+export type WireAuthResponseMapping = {
+  accessToken?: string;
+  refreshToken?: string;
+  expiresIn?: string;
+  expiresAt?: string;
+};
+
+/**
+ * Flat wire form of `AuthConfig` on {@link WireSyncConfig.auth}. Enums travel as
+ * strings (`strategy`: 'bearer'|'raw'; `refreshBodyFormat`: 'form'|'json'),
+ * string maps as `WireKeyValue[]`, and `expiresAtMs` is epoch milliseconds.
+ */
+export type WireAuthConfig = {
+  accessToken?: string;
+  refreshToken?: string;
+  expiresAtMs?: number;
+  strategy: string;
+  refreshUrl?: string;
+  refreshPayload: WireKeyValue[];
+  refreshHeaders: WireKeyValue[];
+  refreshBodyFormat: string;
+  responseMapping: WireAuthResponseMapping;
+  skewMarginSeconds: number;
+  seedEpoch?: number;
+};
+
 export type WireSyncConfig = {
   url: string;
   headers: WireKeyValue[];
   intervalSeconds: number;
   batchSize: number;
+  /** Token-refresh recipe; omitted keeps static-header auth. */
+  auth?: WireAuthConfig;
 };
 
 /** Android-only foreground-service notification overrides. iOS ignores it. */
 export type WireNotificationConfig = {
   title?: string;
   text?: string;
+  smallIcon?: string;
 };
 
 export type WireConfig = {
@@ -54,6 +84,13 @@ export type WireConfig = {
   sync?: WireSyncConfig;
   /** Android-only; the iOS native module ignores it. */
   notification?: WireNotificationConfig;
+  /**
+   * License token (license-format-v1 §9). Omitted/`undefined` means unset — the
+   * native SDK falls through to the manifest / Info.plist. The wrapper passes it
+   * through verbatim (no trimming or fallback). `configure` crosses as an untyped
+   * object, so this field documents the shape rather than altering codegen.
+   */
+  licenseKey?: string;
 };
 
 export type WireLocation = {
@@ -112,6 +149,40 @@ export type WireSyncStatus = {
   failure?: string;
 };
 
+/**
+ * A token set the SDK rotated, delivered on `onAuthTokens`. `expiresAtMs` is
+ * epoch milliseconds; both it and `refreshToken` are `null` when absent.
+ */
+export type WireAuthTokens = {
+  accessToken: string;
+  refreshToken: string | null;
+  expiresAtMs: number | null;
+  epoch: number;
+};
+
+/**
+ * Flat wire form of the current platform's native license status
+ * (license-format-v1 §8). `status` is the wire-stable identifier; `tier` and
+ * `entitlements` are populated only when `status === 'licensed'` (null / empty
+ * otherwise), and `reason` only when `status === 'invalid'`.
+ */
+export type WireLicenseStatus = {
+  /**
+   * One of: 'notDetermined' | 'licensed' | 'evaluation' | 'expired' |
+   * 'updateEntitlementLapsed' | 'invalid'.
+   */
+  status: string;
+  /** The opaque pricing tier; `null` unless `status === 'licensed'`. */
+  tier: string | null;
+  /** Opaque feature-gate strings; empty unless `status === 'licensed'`. */
+  entitlements: string[];
+  /**
+   * `null` unless `status === 'invalid'`. One of: 'malformed' | 'unknownKey' |
+   * 'badSignature' | 'appIdMismatch' | 'productMismatch' | 'unsupportedVersion'.
+   */
+  reason: string | null;
+};
+
 export interface Spec extends TurboModule {
   /**
    * The config crosses as an untyped object (`ReadableMap` on Android,
@@ -125,6 +196,19 @@ export interface Spec extends TurboModule {
   stop(): Promise<void>;
   resumeIfNeeded(): Promise<void>;
 
+  /**
+   * One immediate fix. `accuracy` `''` uses the configured mode (a plain
+   * `string` rather than `string | null` for portable Codegen, matching
+   * `deleteLocations`). Resolves a 0- or 1-element array — empty means timeout /
+   * no fix — rather than a nullable struct, which Codegen does not portably
+   * support. Rejects with `PERMISSION_DENIED` / `LOCATION_SERVICES_DISABLED` /
+   * `LOCATION_UNAVAILABLE` on a precondition failure.
+   */
+  getCurrentLocation(
+    timeoutMs: number,
+    accuracy: string
+  ): Promise<WireLocation[]>;
+
   getLocations(fromMs: number, toMs: number): Promise<WireLocation[]>;
   /**
    * A negative `beforeMs` deletes all stored locations (the wire encoding of
@@ -141,10 +225,19 @@ export interface Spec extends TurboModule {
   removeGeofences(ids: string[]): Promise<void>;
   listGeofences(): Promise<WireGeofence[]>;
 
+  /**
+   * The current platform's native license status (license-format-v1 §8). Each
+   * native SDK validates independently; this reflects only the platform you are
+   * running on — no cross-platform merging.
+   */
+  licenseStatus(): Promise<WireLicenseStatus>;
+
   readonly onState: CodegenTypes.EventEmitter<WireState>;
   readonly onLocation: CodegenTypes.EventEmitter<WireLocation>;
   readonly onGeofenceEvent: CodegenTypes.EventEmitter<WireGeofenceEvent>;
   readonly onSyncStatus: CodegenTypes.EventEmitter<WireSyncStatus>;
+  readonly onAuthTokens: CodegenTypes.EventEmitter<WireAuthTokens>;
+  readonly onLicenseStatus: CodegenTypes.EventEmitter<WireLicenseStatus>;
 }
 
 export default TurboModuleRegistry.getEnforcing<Spec>('BeekonRn');

package/src/beekon.ts

@@ -1,6 +1,9 @@
 import NativeBeekon from './NativeBeekonRn';
+import type { AuthTokens } from './types/auth';
 import type { BeekonConfig } from './types/config';
+import type { AccuracyMode } from './types/enums';
 import type { BeekonGeofence, GeofenceEvent } from './types/geofence';
+import type { LicenseStatus } from './types/license';
 import type { Location } from './types/location';
 import type { BeekonState } from './types/state';
 import type { SyncStatus } from './types/sync';
@@ -9,8 +12,10 @@ import {
   geofenceToWire,
   recordToEntries,
   rethrowAsBeekonError,
+  wireToAuthTokens,
   wireToGeofence,
   wireToGeofenceEvent,
+  wireToLicenseStatus,
   wireToLocation,
   wireToState,
   wireToSyncStatus,
@@ -19,11 +24,11 @@ import {
 type Listener<T> = (value: T) => void;
 
 /**
- * Fans the four native EventEmitters out to multiple JS subscribers and adds
- * replay-1 semantics for `state` / `syncStatus` (RN EventEmitters don't replay,
- * so we cache the latest value and hand it to new subscribers immediately —
- * matching the native StateFlow / AsyncStream contract). `location` /
- * `geofenceEvent` are plain fan-out with no replay.
+ * Fans the five native EventEmitters out to multiple JS subscribers and adds
+ * replay-1 semantics for `state` / `syncStatus` / `authTokens` (RN EventEmitters
+ * don't replay, so we cache the latest value and hand it to new subscribers
+ * immediately — matching the native StateFlow / AsyncStream contract).
+ * `location` / `geofenceEvent` are plain fan-out with no replay.
  *
  * Native subscriptions are opened once, on first use, and kept for the app
  * lifetime — the native module collects its flows continuously regardless, so
@@ -35,8 +40,12 @@ class EventHub {
   private readonly locationListeners = new Set<Listener<Location>>();
   private readonly geofenceListeners = new Set<Listener<GeofenceEvent>>();
   private readonly syncListeners = new Set<Listener<SyncStatus>>();
+  private readonly authTokenListeners = new Set<Listener<AuthTokens>>();
+  private readonly licenseListeners = new Set<Listener<LicenseStatus>>();
   private lastState: BeekonState | undefined;
   private lastSyncStatus: SyncStatus | undefined;
+  private lastAuthTokens: AuthTokens | undefined;
+  private lastLicenseStatus: LicenseStatus | undefined;
 
   /** Idempotent: opens the native subscriptions the first time it is called. */
   ensureSubscribed(): void {
@@ -60,6 +69,16 @@ class EventHub {
       this.lastSyncStatus = s;
       this.syncListeners.forEach((cb) => cb(s));
     });
+    NativeBeekon.onAuthTokens((w) => {
+      const t = wireToAuthTokens(w);
+      this.lastAuthTokens = t;
+      this.authTokenListeners.forEach((cb) => cb(t));
+    });
+    NativeBeekon.onLicenseStatus((w) => {
+      const s = wireToLicenseStatus(w);
+      this.lastLicenseStatus = s;
+      this.licenseListeners.forEach((cb) => cb(s));
+    });
   }
 
   onState(cb: Listener<BeekonState>): () => void {
@@ -95,6 +114,24 @@ class EventHub {
       this.syncListeners.delete(cb);
     };
   }
+
+  onAuthTokens(cb: Listener<AuthTokens>): () => void {
+    this.ensureSubscribed();
+    this.authTokenListeners.add(cb);
+    if (this.lastAuthTokens !== undefined) cb(this.lastAuthTokens);
+    return () => {
+      this.authTokenListeners.delete(cb);
+    };
+  }
+
+  onLicenseStatus(cb: Listener<LicenseStatus>): () => void {
+    this.ensureSubscribed();
+    this.licenseListeners.add(cb);
+    if (this.lastLicenseStatus !== undefined) cb(this.lastLicenseStatus);
+    return () => {
+      this.licenseListeners.delete(cb);
+    };
+  }
 }
 
 /**
@@ -160,6 +197,37 @@ class BeekonImpl {
     await NativeBeekon.resumeIfNeeded();
   }
 
+  /**
+   * Return a single fresh fix on demand — for the moment a host needs an
+   * immediate position (e.g. the instant a trip starts).
+   *
+   * Independent of tracking: works whether or not a session is running and never
+   * starts, stops, or disturbs one. The fix is not persisted and does not appear
+   * on `onLocation` — it is returned here only, tagged `'manual'`.
+   *
+   * Resolves `null` if no usable fix arrives within `timeoutMs` (default
+   * 15000). `accuracy` overrides the configured mode for this call only;
+   * omitted uses the configured mode.
+   *
+   * Throws `BeekonError` with kind `'permissionDenied'`,
+   * `'locationServicesDisabled'`, or `'locationUnavailable'` on a precondition
+   * failure.
+   */
+  async getCurrentLocation(options?: {
+    timeoutMs?: number;
+    accuracy?: AccuracyMode;
+  }): Promise<Location | null> {
+    try {
+      const wires = await NativeBeekon.getCurrentLocation(
+        options?.timeoutMs ?? 15000,
+        options?.accuracy ?? ''
+      );
+      return wires.length === 0 ? null : wireToLocation(wires[0]!);
+    } catch (e) {
+      rethrowAsBeekonError(e);
+    }
+  }
+
   /**
    * Read persisted fixes in the inclusive range `[from, to]`, oldest first.
    * Reads come from the SDK's local storage (Room on Android, GRDB on iOS) — the
@@ -181,7 +249,7 @@ class BeekonImpl {
   }
 
   /**
-   * Delete stored locations captured at or before `before` (all of them when
+   * Delete stored locations captured before `before` (all of them when
    * `before` is omitted). Returns the number of rows removed. Throws
    * `BeekonError` with kind `'storage'` on a failure.
    */
@@ -243,6 +311,16 @@ class BeekonImpl {
     return wires.map(wireToGeofence);
   }
 
+  /**
+   * The current platform's license status (license-format-v1 §8). Android and
+   * iOS validate independently — this reflects the platform you are running on,
+   * with no cross-platform merging. Purely observational: a license never blocks,
+   * degrades, or delays the SDK. For live transitions use {@link onLicenseStatus}.
+   */
+  async licenseStatus(): Promise<LicenseStatus> {
+    return wireToLicenseStatus(await NativeBeekon.licenseStatus());
+  }
+
   /**
    * Subscribe to tracking-state transitions (`idle` / `tracking` /
    * `stopped(reason)`). The current state is delivered to new subscribers
@@ -277,6 +355,26 @@ class BeekonImpl {
   onSyncStatus(cb: (s: SyncStatus) => void): () => void {
     return this.hub.onSyncStatus(cb);
   }
+
+  /**
+   * Subscribe to token rotations the SDK performed during a native refresh (see
+   * `SyncConfig.auth`). Mirror them into your own session store. The latest
+   * rotation is delivered to new subscribers immediately (replay-1). Sensitive —
+   * delivered in-process only, never logged. Returns an unsubscribe function.
+   */
+  onAuthTokens(cb: (t: AuthTokens) => void): () => void {
+    return this.hub.onAuthTokens(cb);
+  }
+
+  /**
+   * Subscribe to license-status transitions for the current platform
+   * (license-format-v1 §8). The current status is delivered to new subscribers
+   * immediately (replay-1), then again on each transition (the first validation
+   * is lazy). Purely observational. Returns an unsubscribe function.
+   */
+  onLicenseStatus(cb: (s: LicenseStatus) => void): () => void {
+    return this.hub.onLicenseStatus(cb);
+  }
 }
 
 export const Beekon = new BeekonImpl();

package/src/index.tsx

@@ -12,7 +12,10 @@ export type {
   LocationQuality,
   MotionState,
   ActivityType,
+  AuthStrategy,
+  AuthBodyFormat,
 } from './types/enums';
+export type { AuthConfig, AuthResponseMapping, AuthTokens } from './types/auth';
 export type { Location } from './types/location';
 export type {
   BeekonGeofence,
@@ -21,4 +24,5 @@ export type {
 } from './types/geofence';
 export type { BeekonState, StopReason } from './types/state';
 export type { SyncStatus, SyncFailure } from './types/sync';
+export type { LicenseStatus, LicenseInvalidReason } from './types/license';
 export { BeekonError, type BeekonErrorKind } from './types/error';

package/src/internal/mappers.ts

@@ -1,7 +1,10 @@
+import type { AuthConfig, AuthTokens } from '../types/auth';
 import type { BeekonConfig } from '../types/config';
 import type {
   AccuracyMode,
   ActivityType,
+  AuthBodyFormat,
+  AuthStrategy,
   LocationQuality,
   LocationTrigger,
   MotionState,
@@ -12,15 +15,19 @@ import type {
   GeofenceEvent,
   Transition,
 } from '../types/geofence';
+import type { LicenseInvalidReason, LicenseStatus } from '../types/license';
 import type { Location } from '../types/location';
 import type { BeekonState, StopReason } from '../types/state';
 import type { SyncFailure, SyncStatus } from '../types/sync';
 import { BeekonError, type BeekonErrorKind } from '../types/error';
 import type {
+  WireAuthConfig,
+  WireAuthTokens,
   WireConfig,
   WireGeofence,
   WireGeofenceEvent,
   WireKeyValue,
+  WireLicenseStatus,
   WireLocation,
   WireState,
   WireSyncStatus,
@@ -37,6 +44,13 @@ const DEFAULTS = {
   detectActivity: false,
   syncIntervalSeconds: 300,
   syncBatchSize: 100,
+  authStrategy: 'bearer' as AuthStrategy,
+  authBodyFormat: 'form' as AuthBodyFormat,
+  authSkewMarginSeconds: 60,
+  authRefreshHeaders: { Authorization: 'Bearer {accessToken}' } as Record<
+    string,
+    string
+  >,
 };
 
 // --- Public → wire ---------------------------------------------------------
@@ -68,11 +82,20 @@ export function configToWire(config: BeekonConfig): WireConfig {
           headers: recordToEntries(sync.headers),
           intervalSeconds: sync.intervalSeconds ?? DEFAULTS.syncIntervalSeconds,
           batchSize: sync.batchSize ?? DEFAULTS.syncBatchSize,
+          auth: sync.auth ? authToWire(sync.auth) : undefined,
         }
       : undefined,
     notification: config.notification
-      ? { title: config.notification.title, text: config.notification.text }
+      ? {
+          title: config.notification.title,
+          text: config.notification.text,
+          smallIcon: config.notification.smallIcon,
+        }
       : undefined,
+    // Passed through verbatim — `undefined` is omitted and the native SDK falls
+    // through to manifest/Info.plist. No wrapper-side trimming or fallback
+    // (blank/whitespace handling lives in the native SDK; spec §9).
+    licenseKey: config.licenseKey,
   };
 }
 
@@ -87,6 +110,31 @@ export function geofenceToWire(g: BeekonGeofence): WireGeofence {
   };
 }
 
+// `expiresAt` (a `Date`) becomes epoch millis on the wire; the native side
+// converts to epoch seconds. String maps travel as `WireKeyValue[]`.
+export function authToWire(a: AuthConfig): WireAuthConfig {
+  return {
+    accessToken: a.accessToken,
+    refreshToken: a.refreshToken,
+    expiresAtMs: a.expiresAt?.getTime(),
+    strategy: a.strategy ?? DEFAULTS.authStrategy,
+    refreshUrl: a.refreshUrl,
+    refreshPayload: recordToEntries(a.refreshPayload),
+    refreshHeaders: recordToEntries(
+      a.refreshHeaders ?? DEFAULTS.authRefreshHeaders
+    ),
+    refreshBodyFormat: a.refreshBodyFormat ?? DEFAULTS.authBodyFormat,
+    responseMapping: {
+      accessToken: a.responseMapping?.accessToken,
+      refreshToken: a.responseMapping?.refreshToken,
+      expiresIn: a.responseMapping?.expiresIn,
+      expiresAt: a.responseMapping?.expiresAt,
+    },
+    skewMarginSeconds: a.skewMarginSeconds ?? DEFAULTS.authSkewMarginSeconds,
+    seedEpoch: a.seedEpoch,
+  };
+}
+
 // --- Wire → public ---------------------------------------------------------
 
 export function wireToLocation(w: WireLocation): Location {
@@ -180,6 +228,60 @@ export function wireToSyncStatus(w: WireSyncStatus): SyncStatus {
   }
 }
 
+/** `expiresAtMs` (epoch millis) becomes a `Date`; `null` propagates faithfully. */
+export function wireToAuthTokens(w: WireAuthTokens): AuthTokens {
+  return {
+    accessToken: w.accessToken,
+    refreshToken: w.refreshToken,
+    expiresAt: w.expiresAtMs == null ? null : new Date(w.expiresAtMs),
+    epoch: w.epoch,
+  };
+}
+
+/**
+ * Decode the wire-stable license status into the public discriminated union. The
+ * native side already decided the status (the wrapper performs no validation) —
+ * this only re-shapes the flat wire form and validates the enum strings.
+ */
+export function wireToLicenseStatus(w: WireLicenseStatus): LicenseStatus {
+  switch (w.status) {
+    case 'licensed':
+      return {
+        status: 'licensed',
+        tier: w.tier ?? '',
+        entitlements: w.entitlements ?? [],
+      };
+    case 'invalid':
+      return {
+        status: 'invalid',
+        reason: oneOf<LicenseInvalidReason>(
+          w.reason,
+          [
+            'malformed',
+            'unknownKey',
+            'badSignature',
+            'appIdMismatch',
+            'productMismatch',
+            'unsupportedVersion',
+          ],
+          'malformed'
+        ),
+      };
+    case 'evaluation':
+      return { status: 'evaluation' };
+    case 'expired':
+      return { status: 'expired' };
+    case 'updateEntitlementLapsed':
+      return { status: 'updateEntitlementLapsed' };
+    case 'notDetermined':
+      return { status: 'notDetermined' };
+    default:
+      // Forward-compat: an unknown status string means a native build newer than
+      // this wrapper — surface as notDetermined rather than throwing.
+      return { status: 'notDetermined' };
+  }
+}
+
 function toStopReason(s: string | undefined): StopReason {
   return oneOf<StopReason>(
     s,
@@ -235,6 +337,12 @@ function codeToKind(code: string | undefined): BeekonErrorKind | undefined {
       return 'storage';
     case 'INVALID_GEOFENCE':
       return 'invalidGeofence';
+    case 'PERMISSION_DENIED':
+      return 'permissionDenied';
+    case 'LOCATION_SERVICES_DISABLED':
+      return 'locationServicesDisabled';
+    case 'LOCATION_UNAVAILABLE':
+      return 'locationUnavailable';
     default:
       return undefined;
   }

package/src/types/auth.ts

@@ -0,0 +1,101 @@
+import type { AuthBodyFormat, AuthStrategy } from './enums';
+
+/**
+ * Where the SDK reads rotated tokens from the JSON response to a refresh
+ * request. Mirrors the native `AuthResponseMapping` (iOS) / `ResponseMapping`
+ * (Android).
+ *
+ * Each value is a response key. An omitted field falls back to common-name
+ * detection: `access_token`/`accessToken`/`token` for the access token,
+ * `refresh_token`/`refreshToken` for a rotated refresh token, and `expires_in`
+ * (relative seconds) or `expires_at`/`expires` (absolute epoch seconds) for the
+ * expiry. The default (all-omitted) is pure common-name detection.
+ */
+export type AuthResponseMapping = {
+  /** Response key holding the new access token. Omitted uses common-name detection. */
+  accessToken?: string;
+  /** Response key holding a rotated refresh token. Omitted uses common-name detection. */
+  refreshToken?: string;
+  /** Response key holding a relative lifetime in seconds. Omitted uses detection. */
+  expiresIn?: string;
+  /** Response key holding an absolute expiry in epoch seconds. Omitted uses detection. */
+  expiresAt?: string;
+};
+
+/**
+ * Declarative recipe for native token refresh, set on `SyncConfig.auth`.
+ * Mirrors the native `AuthConfig`.
+ *
+ * When present, the SDK attaches the access token to every upload (per
+ * {@link AuthConfig.strategy}), refreshes it **proactively** before
+ * {@link AuthConfig.expiresAt} and **reactively** on a `401`/`403`, then retries
+ * the upload — all natively, so it works in the background and on a cold launch
+ * with no host involvement. Omit {@link AuthConfig.refreshUrl} to disable
+ * refresh and keep the legacy behaviour (a `401`/`403` pauses sync and surfaces
+ * `SyncFailure 'auth'`).
+ *
+ * **Tokens are a seed, not config.** {@link AuthConfig.accessToken},
+ * {@link AuthConfig.refreshToken} and {@link AuthConfig.expiresAt} are supplied
+ * once; the SDK then owns and rotates the live token set in secure storage
+ * (Keychain / encrypted prefs). Observe rotations via `Beekon.onAuthTokens()` to
+ * mirror the tokens into your own session store.
+ *
+ * Requires the native SDK ≥ 0.0.6; with an older native binary the recipe is
+ * ignored and only static `SyncConfig.headers` apply.
+ */
+export type AuthConfig = {
+  /** Initial access token. A seed: the SDK owns and rotates it after first persist. */
+  accessToken?: string;
+  /** Initial refresh token POSTed to {@link AuthConfig.refreshUrl}. A seed. */
+  refreshToken?: string;
+  /** Absolute expiry of {@link AuthConfig.accessToken}. Omitted disables proactive refresh. */
+  expiresAt?: Date;
+  /** How the access token is attached. Default: `'bearer'`. */
+  strategy?: AuthStrategy;
+  /** Authorization server's refresh endpoint. Omitted disables refresh. */
+  refreshUrl?: string;
+  /**
+   * Form fields POSTed to {@link AuthConfig.refreshUrl}. A value containing
+   * `{refreshToken}` is substituted with the current refresh token. Default: empty.
+   */
+  refreshPayload?: Record<string, string>;
+  /**
+   * Headers sent on the refresh request. A value containing `{accessToken}` is
+   * substituted with the current access token. Default:
+   * `{ Authorization: 'Bearer {accessToken}' }`.
+   */
+  refreshHeaders?: Record<string, string>;
+  /** Encoding of the refresh request body. Default: `'form'`. */
+  refreshBodyFormat?: AuthBodyFormat;
+  /** Where to read rotated tokens from the refresh response. Default: detection. */
+  responseMapping?: AuthResponseMapping;
+  /** Seconds before {@link AuthConfig.expiresAt} at which a proactive refresh fires. Default: `60`. */
+  skewMarginSeconds?: number;
+  /**
+   * Optional monotonic re-seed signal. When greater than the SDK's stored epoch,
+   * a re-supplied seed replaces the rotated token set (e.g. after the user
+   * re-authenticates). Omitted adopts a re-supplied seed only when no token has
+   * been stored yet.
+   */
+  seedEpoch?: number;
+};
+
+/**
+ * A token set the SDK rotated, delivered via `Beekon.onAuthTokens()`. Mirrors
+ * the native `AuthTokens` (iOS) / `TokenRefresh` (Android).
+ *
+ * Treat these as sensitive: they are delivered in-process only and are never
+ * logged or persisted to plaintext. Use them to mirror the SDK's current
+ * credentials into your own session store. The latest rotation is replayed to
+ * new subscribers (replay-1).
+ */
+export type AuthTokens = {
+  /** The rotated access token now in use. */
+  accessToken: string;
+  /** The current refresh token (rotated if the server returned a new one), or `null`. */
+  refreshToken: string | null;
+  /** Absolute expiry of {@link AuthTokens.accessToken}, or `null` if the response carried none. */
+  expiresAt: Date | null;
+  /** The SDK's monotonic token generation, incremented on each successful refresh. */
+  epoch: number;
+};