@wayq/beekon-rn 0.0.5 → 0.0.6

package/lib/typescript/src/beekon.d.ts

@@ -1,4 +1,6 @@
+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 { Location } from './types/location';
 import type { BeekonState } from './types/state';
@@ -49,6 +51,26 @@ declare class BeekonImpl {
      * in the AppDelegate). See the README.
      */
     resumeIfNeeded(): Promise<void>;
+    /**
+     * 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.
+     */
+    getCurrentLocation(options?: {
+        timeoutMs?: number;
+        accuracy?: AccuracyMode;
+    }): Promise<Location | null>;
     /**
      * 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
@@ -59,7 +81,7 @@ declare class BeekonImpl {
      */
     getLocations(from: Date, to: Date): Promise<Location[]>;
     /**
-     * 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.
      */
@@ -109,6 +131,13 @@ declare class BeekonImpl {
      * Returns an unsubscribe function.
      */
     onSyncStatus(cb: (s: SyncStatus) => void): () => void;
+    /**
+     * 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;
 }
 export declare const Beekon: BeekonImpl;
 export {};

package/lib/typescript/src/beekon.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"beekon.d.ts","sourceRoot":"","sources":["../../../src/beekon.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AA8F/C;;;;;;;;;;;;;;;;;GAiBG;AACH,cAAM,UAAU;IACd,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAkB;IAEtC;;;;;OAKG;IACG,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAKpD;;;;;OAKG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B,mEAAmE;IAC7D,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAK3B;;;;;;;;OAQG;IACG,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAKrC;;;;;;;OAOG;IACG,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAY7D;;;;OAIG;IACG,eAAe,CAAC,MAAM,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC;IASrD;;;OAGG;IACG,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC;IAQ3C;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,+EAA+E;IACzE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9D;;;;OAIG;IACG,YAAY,CAAC,SAAS,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ9D,2DAA2D;IACrD,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAInD,0CAA0C;IACpC,aAAa,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAKhD;;;;OAIG;IACH,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,WAAW,KAAK,IAAI,GAAG,MAAM,IAAI;IAIjD;;;;OAIG;IACH,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,KAAK,IAAI,GAAG,MAAM,IAAI;IAIjD;;;OAGG;IACH,eAAe,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,aAAa,KAAK,IAAI,GAAG,MAAM,IAAI;IAI3D;;;;OAIG;IACH,YAAY,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI,GAAG,MAAM,IAAI;CAGtD;AAED,eAAO,MAAM,MAAM,YAAmB,CAAC"}
+{"version":3,"file":"beekon.d.ts","sourceRoot":"","sources":["../../../src/beekon.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AA+G/C;;;;;;;;;;;;;;;;;GAiBG;AACH,cAAM,UAAU;IACd,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAkB;IAEtC;;;;;OAKG;IACG,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAKpD;;;;;OAKG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B,mEAAmE;IAC7D,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAK3B;;;;;;;;OAQG;IACG,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAKrC;;;;;;;;;;;;;;;OAeG;IACG,kBAAkB,CAAC,OAAO,CAAC,EAAE;QACjC,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,YAAY,CAAC;KACzB,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAY5B;;;;;;;OAOG;IACG,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAY7D;;;;OAIG;IACG,eAAe,CAAC,MAAM,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC;IASrD;;;OAGG;IACG,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC;IAQ3C;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,+EAA+E;IACzE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9D;;;;OAIG;IACG,YAAY,CAAC,SAAS,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ9D,2DAA2D;IACrD,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAInD,0CAA0C;IACpC,aAAa,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAKhD;;;;OAIG;IACH,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,WAAW,KAAK,IAAI,GAAG,MAAM,IAAI;IAIjD;;;;OAIG;IACH,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,KAAK,IAAI,GAAG,MAAM,IAAI;IAIjD;;;OAGG;IACH,eAAe,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,aAAa,KAAK,IAAI,GAAG,MAAM,IAAI;IAI3D;;;;OAIG;IACH,YAAY,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI,GAAG,MAAM,IAAI;IAIrD;;;;;OAKG;IACH,YAAY,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI,GAAG,MAAM,IAAI;CAGtD;AAED,eAAO,MAAM,MAAM,YAAmB,CAAC"}

package/lib/typescript/src/index.d.ts

@@ -1,6 +1,7 @@
 export { Beekon } from './beekon';
 export type { BeekonConfig, SyncConfig, NotificationConfig, } from './types/config';
-export type { AccuracyMode, StationaryMode, LocationTrigger, LocationQuality, MotionState, ActivityType, } from './types/enums';
+export type { AccuracyMode, StationaryMode, LocationTrigger, 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, GeofenceEvent, Transition, } from './types/geofence';
 export type { BeekonState, StopReason } from './types/state';

package/lib/typescript/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAElC,YAAY,EACV,YAAY,EACZ,UAAU,EACV,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,YAAY,EACZ,cAAc,EACd,eAAe,EACf,eAAe,EACf,WAAW,EACX,YAAY,GACb,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,YAAY,EACV,cAAc,EACd,aAAa,EACb,UAAU,GACX,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC7D,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAElC,YAAY,EACV,YAAY,EACZ,UAAU,EACV,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,YAAY,EACZ,cAAc,EACd,eAAe,EACf,eAAe,EACf,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,cAAc,GACf,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,UAAU,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAChF,YAAY,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,YAAY,EACV,cAAc,EACd,aAAa,EACb,UAAU,GACX,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC7D,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC"}

package/lib/typescript/src/internal/mappers.d.ts

@@ -1,17 +1,21 @@
+import type { AuthConfig, AuthTokens } from '../types/auth';
 import type { BeekonConfig } from '../types/config';
 import type { BeekonGeofence, GeofenceEvent } from '../types/geofence';
 import type { Location } from '../types/location';
 import type { BeekonState } from '../types/state';
 import type { SyncStatus } from '../types/sync';
-import type { WireConfig, WireGeofence, WireGeofenceEvent, WireKeyValue, WireLocation, WireState, WireSyncStatus } from '../NativeBeekonRn';
+import type { WireAuthConfig, WireAuthTokens, WireConfig, WireGeofence, WireGeofenceEvent, WireKeyValue, WireLocation, WireState, WireSyncStatus } from '../NativeBeekonRn';
 export declare function recordToEntries(record: Record<string, string> | undefined): WireKeyValue[];
 export declare function configToWire(config: BeekonConfig): WireConfig;
 export declare function geofenceToWire(g: BeekonGeofence): WireGeofence;
+export declare function authToWire(a: AuthConfig): WireAuthConfig;
 export declare function wireToLocation(w: WireLocation): Location;
 export declare function wireToGeofence(w: WireGeofence): BeekonGeofence;
 export declare function wireToGeofenceEvent(w: WireGeofenceEvent): GeofenceEvent;
 export declare function wireToState(w: WireState): BeekonState;
 export declare function wireToSyncStatus(w: WireSyncStatus): SyncStatus;
+/** `expiresAtMs` (epoch millis) becomes a `Date`; `null` propagates faithfully. */
+export declare function wireToAuthTokens(w: WireAuthTokens): AuthTokens;
 /**
  * Re-throw a native promise rejection as a typed {@link BeekonError}. The native
  * modules encode the kind in the error-code string (`STORAGE_FAILURE`,

package/lib/typescript/src/internal/mappers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mappers.d.ts","sourceRoot":"","sources":["../../../../src/internal/mappers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AASpD,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EAEd,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAc,MAAM,gBAAgB,CAAC;AAC9D,OAAO,KAAK,EAAe,UAAU,EAAE,MAAM,eAAe,CAAC;AAE7D,OAAO,KAAK,EACV,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,cAAc,EACf,MAAM,mBAAmB,CAAC;AAiB3B,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,GACzC,YAAY,EAAE,CAGhB;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,UAAU,CA0B7D;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,cAAc,GAAG,YAAY,CAS9D;AAID,wBAAgB,cAAc,CAAC,CAAC,EAAE,YAAY,GAAG,QAAQ,CA0CxD;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,YAAY,GAAG,cAAc,CAS9D;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,iBAAiB,GAAG,aAAa,CAOvE;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,SAAS,GAAG,WAAW,CAYrD;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,cAAc,GAAG,UAAU,CAW9D;AAoCD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,OAAO,GAAG,KAAK,CAQtD"}
+{"version":3,"file":"mappers.d.ts","sourceRoot":"","sources":["../../../../src/internal/mappers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAWpD,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EAEd,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAc,MAAM,gBAAgB,CAAC;AAC9D,OAAO,KAAK,EAAe,UAAU,EAAE,MAAM,eAAe,CAAC;AAE7D,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EACd,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,cAAc,EACf,MAAM,mBAAmB,CAAC;AAwB3B,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,GACzC,YAAY,EAAE,CAGhB;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,UAAU,CA+B7D;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,cAAc,GAAG,YAAY,CAS9D;AAID,wBAAgB,UAAU,CAAC,CAAC,EAAE,UAAU,GAAG,cAAc,CAqBxD;AAID,wBAAgB,cAAc,CAAC,CAAC,EAAE,YAAY,GAAG,QAAQ,CA0CxD;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,YAAY,GAAG,cAAc,CAS9D;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,iBAAiB,GAAG,aAAa,CAOvE;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,SAAS,GAAG,WAAW,CAYrD;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,cAAc,GAAG,UAAU,CAW9D;AAED,mFAAmF;AACnF,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,cAAc,GAAG,UAAU,CAO9D;AAoCD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,OAAO,GAAG,KAAK,CAQtD"}

package/lib/typescript/src/types/auth.d.ts

@@ -0,0 +1,99 @@
+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;
+};
+//# sourceMappingURL=auth.d.ts.map

package/lib/typescript/src/types/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../../src/types/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5D;;;;;;;;;;GAUG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,qFAAqF;IACrF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wFAAwF;IACxF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wFAAwF;IACxF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,qFAAqF;IACrF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6FAA6F;IAC7F,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,+DAA+D;IAC/D,iBAAiB,CAAC,EAAE,cAAc,CAAC;IACnC,kFAAkF;IAClF,eAAe,CAAC,EAAE,mBAAmB,CAAC;IACtC,qGAAqG;IACrG,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,uFAAuF;IACvF,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,iGAAiG;IACjG,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;IACvB,oFAAoF;IACpF,KAAK,EAAE,MAAM,CAAC;CACf,CAAC"}

package/lib/typescript/src/types/config.d.ts

@@ -1,3 +1,4 @@
+import type { AuthConfig } from './auth';
 import type { AccuracyMode, StationaryMode } from './enums';
 /**
  * Foreground-service notification overrides. **Android-only** — the platform
@@ -10,6 +11,14 @@ export type NotificationConfig = {
     title?: string;
     /** Notification body text. Defaults to no body. */
     text?: string;
+    /**
+     * Status-bar icon, given as an Android drawable or mipmap resource **name**
+     * — `"ic_notification"`, `"drawable/ic_x"`, or `"mipmap/ic_x"`. Android
+     * renders the small icon from its alpha channel only, so supply a monochrome
+     * silhouette on a transparent background. Falls back to the host app's
+     * launcher icon when omitted or unresolvable.
+     */
+    smallIcon?: string;
 };
 /**
  * Server-upload configuration. Presence of {@link BeekonConfig.sync} turns on
@@ -28,6 +37,13 @@ export type SyncConfig = {
     intervalSeconds?: number;
     /** Maximum locations per upload. Clamped to `[1, 1000]`. Default: `100`. */
     batchSize?: number;
+    /**
+     * Declarative token-refresh recipe. When set, the SDK attaches and natively
+     * refreshes the access token (proactively before expiry, reactively on
+     * `401`/`403`). Omit to keep the legacy static-{@link SyncConfig.headers}
+     * behaviour. Requires the native SDK ≥ 0.0.6. See {@link AuthConfig}.
+     */
+    auth?: AuthConfig;
 };
 /**
  * Tracking configuration. Every field is optional — `Beekon.start()` falls back

package/lib/typescript/src/types/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../../src/types/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,yEAAyE;IACzE,8BAA8B,CAAC,EAAE,MAAM,CAAC;IACxC,8EAA8E;IAC9E,iCAAiC,CAAC,EAAE,MAAM,CAAC;IAC3C,wDAAwD;IACxD,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,sDAAsD;IACtD,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,6EAA6E;IAC7E,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,qEAAqE;IACrE,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,2DAA2D;IAC3D,YAAY,CAAC,EAAE,kBAAkB,CAAC;CACnC,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../../src/types/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;CACnB,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,yEAAyE;IACzE,8BAA8B,CAAC,EAAE,MAAM,CAAC;IACxC,8EAA8E;IAC9E,iCAAiC,CAAC,EAAE,MAAM,CAAC;IAC3C,wDAAwD;IACxD,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,sDAAsD;IACtD,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,6EAA6E;IAC7E,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,qEAAqE;IACrE,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,2DAA2D;IAC3D,YAAY,CAAC,EAAE,kBAAkB,CAAC;CACnC,CAAC"}

package/lib/typescript/src/types/enums.d.ts

@@ -45,4 +45,18 @@ export type MotionState = 'moving' | 'stationary' | 'unknown';
  * {@link BeekonConfig.detectActivity} is enabled; otherwise `null`.
  */
 export type ActivityType = 'stationary' | 'walking' | 'running' | 'cycling' | 'automotive' | 'unknown';
+/**
+ * How the access token is attached to upload requests (token refresh).
+ *
+ * - `'bearer'` — `Authorization: Bearer <accessToken>` (JWT / OAuth2 style, default).
+ * - `'raw'` — `Authorization: <accessToken>` (the raw token, no scheme).
+ */
+export type AuthStrategy = 'bearer' | 'raw';
+/**
+ * Encoding of the token-refresh request body.
+ *
+ * - `'form'` — `application/x-www-form-urlencoded` (default; most OAuth2 endpoints).
+ * - `'json'` — `application/json`.
+ */
+export type AuthBodyFormat = 'form' | 'json';
 //# sourceMappingURL=enums.d.ts.map

package/lib/typescript/src/types/enums.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"enums.d.ts","sourceRoot":"","sources":["../../../../src/types/enums.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,UAAU,GAAG,KAAK,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,cAAc,GAAG,OAAO,GAAG,mBAAmB,CAAC;AAE5E;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GACvB,UAAU,GACV,QAAQ,GACR,SAAS,GACT,UAAU,GACV,QAAQ,CAAC;AAEb;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,IAAI,GAAG,aAAa,GAAG,kBAAkB,CAAC;AAExE,0DAA0D;AAC1D,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,YAAY,GAAG,SAAS,CAAC;AAE9D;;;GAGG;AACH,MAAM,MAAM,YAAY,GACpB,YAAY,GACZ,SAAS,GACT,SAAS,GACT,SAAS,GACT,YAAY,GACZ,SAAS,CAAC"}
+{"version":3,"file":"enums.d.ts","sourceRoot":"","sources":["../../../../src/types/enums.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,UAAU,GAAG,KAAK,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,cAAc,GAAG,OAAO,GAAG,mBAAmB,CAAC;AAE5E;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GACvB,UAAU,GACV,QAAQ,GACR,SAAS,GACT,UAAU,GACV,QAAQ,CAAC;AAEb;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,IAAI,GAAG,aAAa,GAAG,kBAAkB,CAAC;AAExE,0DAA0D;AAC1D,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,YAAY,GAAG,SAAS,CAAC;AAE9D;;;GAGG;AACH,MAAM,MAAM,YAAY,GACpB,YAAY,GACZ,SAAS,GACT,SAAS,GACT,SAAS,GACT,YAAY,GACZ,SAAS,CAAC;AAEd;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,KAAK,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,CAAC"}

package/lib/typescript/src/types/error.d.ts

@@ -1,14 +1,24 @@
 /**
- * Error kinds thrown across the bridge. These are the **only** errors Beekon
- * throws — permission / location-services / lifecycle problems never throw; they
- * surface on the `onState` stream as `stopped(reason)` instead.
+ * Error kinds thrown across the bridge.
+ *
+ * Lifecycle problems on the tracking path never throw — they surface on the
+ * `onState` stream as `stopped(reason)`. The exceptions are the storage/geofence
+ * kinds below and the precondition kinds thrown by the explicit one-shot
+ * `getCurrentLocation()` (which has no `onState` arc of its own to report on; a
+ * plain timeout returns `null` instead of throwing).
  *
  * - `'storage'` — a local-store (SQLite) read/write failed. Thrown by
  *   `getLocations()`, `deleteLocations()`, and `pendingUploadCount()`.
  * - `'invalidGeofence'` — a geofence passed to `addGeofences()` failed
  *   validation (empty/oversized id, or non-positive radius).
+ * - `'permissionDenied'` — location permission is missing. Thrown by
+ *   `getCurrentLocation()`.
+ * - `'locationServicesDisabled'` — system location services are off. Thrown by
+ *   `getCurrentLocation()`.
+ * - `'locationUnavailable'` — location is otherwise unavailable (e.g. Play
+ *   Services absent/old). Thrown by `getCurrentLocation()`.
  */
-export type BeekonErrorKind = 'storage' | 'invalidGeofence';
+export type BeekonErrorKind = 'storage' | 'invalidGeofence' | 'permissionDenied' | 'locationServicesDisabled' | 'locationUnavailable';
 /**
  * Typed error surfaced from the bridge. The native module rejects promises with
  * the kind encoded as the error code; the facade re-wraps into this.

package/lib/typescript/src/types/error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../../../src/types/error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,iBAAiB,CAAC;AAE5D;;;GAGG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,SAAgB,IAAI,EAAE,eAAe,CAAC;gBAE1B,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM;CAKnD"}
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../../../src/types/error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,eAAe,GACvB,SAAS,GACT,iBAAiB,GACjB,kBAAkB,GAClB,0BAA0B,GAC1B,qBAAqB,CAAC;AAE1B;;;GAGG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,SAAgB,IAAI,EAAE,eAAe,CAAC;gBAE1B,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM;CAKnD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wayq/beekon-rn",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "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",
@@ -45,9 +46,12 @@
     "android",
     "location",
     "tracking",
+    "location-tracking",
     "gps",
+    "gps-tracking",
     "background-location",
     "geolocation",
+    "geofencing",
     "beekon",
     "turbo-module"
   ],

package/scripts/fetch-beekonkit.sh

@@ -13,12 +13,12 @@
 
 set -euo pipefail
 
-VERSION="0.0.5"
+VERSION="0.0.6"
 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.6 BeekonKit.xcframework.zip. Matches the SwiftPM
+# `binaryTarget` checksum in beekon-ios-binary's Package.swift at tag v0.0.6
 # (SwiftPM's compute-checksum is the SHA256 of the zip).
-EXPECTED_SHA="437bf493d7de19d8df9599da097be162796a8304eb2d7826cf2505c33d4603f7"
+EXPECTED_SHA="eb0cd87c869cdbce5374569efa2d47f0f7e6c01ce18461c0653ef701163cf343"
 
 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 = {
@@ -112,6 +142,17 @@ 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;
+};
+
 export interface Spec extends TurboModule {
   /**
    * The config crosses as an untyped object (`ReadableMap` on Android,
@@ -125,6 +166,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
@@ -145,6 +199,7 @@ export interface Spec extends TurboModule {
   readonly onLocation: CodegenTypes.EventEmitter<WireLocation>;
   readonly onGeofenceEvent: CodegenTypes.EventEmitter<WireGeofenceEvent>;
   readonly onSyncStatus: CodegenTypes.EventEmitter<WireSyncStatus>;
+  readonly onAuthTokens: CodegenTypes.EventEmitter<WireAuthTokens>;
 }
 
 export default TurboModuleRegistry.getEnforcing<Spec>('BeekonRn');

package/src/beekon.ts

@@ -1,5 +1,7 @@
 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 { Location } from './types/location';
 import type { BeekonState } from './types/state';
@@ -9,6 +11,7 @@ import {
   geofenceToWire,
   recordToEntries,
   rethrowAsBeekonError,
+  wireToAuthTokens,
   wireToGeofence,
   wireToGeofenceEvent,
   wireToLocation,
@@ -19,11 +22,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 +38,10 @@ 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 lastState: BeekonState | undefined;
   private lastSyncStatus: SyncStatus | undefined;
+  private lastAuthTokens: AuthTokens | undefined;
 
   /** Idempotent: opens the native subscriptions the first time it is called. */
   ensureSubscribed(): void {
@@ -60,6 +65,11 @@ 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));
+    });
   }
 
   onState(cb: Listener<BeekonState>): () => void {
@@ -95,6 +105,15 @@ 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);
+    };
+  }
 }
 
 /**
@@ -160,6 +179,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 +231,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.
    */
@@ -277,6 +327,16 @@ 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);
+  }
 }
 
 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,