@wayq/beekon-rn 0.0.5 → 0.0.7

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;
 };
 
 /**
@@ -62,4 +78,17 @@ export type BeekonConfig = {
   sync?: SyncConfig;
   /** Android-only notification overrides. Ignored on iOS. */
   notification?: NotificationConfig;
+  /**
+   * Beekon license token (a `license-format-v1` JWS). The **highest-priority**
+   * supply channel (spec §9): it overrides the platform manifest value
+   * (`in.wayq.beekon.license` meta-data on Android, `BeekonLicenseKey` in
+   * `Info.plist` on iOS). `undefined`, blank, or whitespace-only means unset —
+   * the SDK falls through to the manifest, then to evaluation mode.
+   *
+   * The license **never blocks** the SDK; observe the outcome via
+   * {@link Beekon.licenseStatus} / {@link Beekon.onLicenseStatus}. Safe to commit
+   * to source control: a token is app-id-bound and product-bound, so it is
+   * useless to anyone else. Default: unset.
+   */
+  licenseKey?: string;
 };

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

package/src/types/license.ts

@@ -0,0 +1,47 @@
+/**
+ * Why an invalid license token failed verification (license-format-v1 §8.1).
+ * These are the exact wire-stable identifiers — the string names *are* the
+ * contract, shared verbatim with both native SDKs.
+ *
+ * - `'malformed'` — unparseable: bad encoding, structure, header, or claim types.
+ * - `'unknownKey'` — signed with a key this SDK build does not embed (update the SDK).
+ * - `'badSignature'` — the ES256 signature does not verify.
+ * - `'appIdMismatch'` — the license does not cover this application id.
+ * - `'productMismatch'` — the license does not cover this framework (here, `rn`).
+ * - `'unsupportedVersion'` — the token's claim schema is newer than this SDK understands.
+ */
+export type LicenseInvalidReason =
+  | 'malformed'
+  | 'unknownKey'
+  | 'badSignature'
+  | 'appIdMismatch'
+  | 'productMismatch'
+  | 'unsupportedVersion';
+
+/**
+ * License verification status for the **current platform** (license-format-v1
+ * §8). Purely observational — no status ever blocks, degrades, or delays the
+ * SDK. Use the `status` field as a discriminator.
+ *
+ * - `'notDetermined'` — before the first (lazy) validation completes.
+ * - `'evaluation'` — no license key supplied through any channel; running free.
+ * - `'expired'` — the license's expiry has passed.
+ * - `'updateEntitlementLapsed'` — this SDK build is newer than the license's
+ *   covered update window. Still fully functional; renew to cover newer releases.
+ * - `'licensed'` — a valid license covering this app, framework, and SDK release;
+ *   carries the opaque `tier` and `entitlements` (empty when the token carried none).
+ * - `'invalid'` — verification failed; see {@link LicenseInvalidReason}.
+ *
+ * **Platform divergence is legal** (spec §8.2): Android and iOS validate
+ * independently, so for one app the two platforms may report different statuses
+ * (e.g. a license scoped to `["android"]` reads `licensed` on Android and
+ * `invalid` / `productMismatch` on iOS). This value reflects only the platform
+ * you are running on; the wrapper never merges across platforms.
+ */
+export type LicenseStatus =
+  | { status: 'notDetermined' }
+  | { status: 'evaluation' }
+  | { status: 'expired' }
+  | { status: 'updateEntitlementLapsed' }
+  | { status: 'licensed'; tier: string; entitlements: string[] }
+  | { status: 'invalid'; reason: LicenseInvalidReason };