@wayq/beekon-rn 0.0.5 → 0.0.6

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,
@@ -17,6 +20,8 @@ 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,
@@ -37,6 +42,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,10 +80,15 @@ 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,
   };
 }
@@ -87,6 +104,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 +222,16 @@ 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,
+  };
+}
+
 function toStopReason(s: string | undefined): StopReason {
   return oneOf<StopReason>(
     s,
@@ -235,6 +287,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;
+};

package/src/types/config.ts

@@ -1,3 +1,4 @@
+import type { AuthConfig } from './auth';
 import type { AccuracyMode, StationaryMode } from './enums';
 
 /**
@@ -11,6 +12,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;
 };
 
 /**
@@ -30,6 +39,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;
 };
 
 /**

package/src/types/enums.ts

@@ -62,3 +62,19 @@ export type ActivityType =
   | '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';

package/src/types/error.ts

@@ -1,14 +1,29 @@
 /**
- * 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