@transistorsoft/background-geolocation-types 5.0.0-beta.1 → 5.0.0-beta.3

package/dist/core/api/TransistorAuthorizationService.d.ts

@@ -0,0 +1,124 @@
+import type { Config } from '../config/Config';
+/**
+ * Represents an authorization token issued by a Transistorsoft Tracking Server.
+ *
+ * Returned from {@link TransistorAuthorizationService.findOrCreate} and consumed by
+ * `Config.authorization` / `transistorAuthorizationToken` flows.
+ *
+ * @category Demo / Debug Server
+ */
+export interface TransistorAuthorizationToken {
+    /** JWT access token used for `Authorization: Bearer <token>`. */
+    accessToken: string;
+    /** JWT refresh token used at the `refreshUrl` endpoint. */
+    refreshToken: string;
+    /**
+     * Expiry time of the access token (epoch milliseconds).
+     * Typically used to drive {@link AuthorizationConfig.expires}.
+     */
+    expires: number;
+    /** Base tracker server URL that issued this token. */
+    url: string;
+}
+/**
+ * Transistor Software hosts a demo server at [tracker.transistorsoft.com](http://tracker.transistorsoft.com) which is
+ * designed to consume location data from devices running the Background Geolocation SDK.
+ *
+ * You may also run your own instance of Demo Server locally.  See [background-geolocation-console](https://github.com/transistorsoft/background-geolocation-console)
+ *
+ * The test server is a great way to debug location problems or evalute the SDK's behaviour, since the results can easily
+ * be shared with *Transistor Software* when requesting support.
+ *
+ * ![](https://dl.dropboxusercontent.com/s/3abuyyhioyypk8c/screenshot-tracker-transistorsoft.png?dl=1)
+ *
+ *
+ * @example
+ * ```typescript
+ * // Url to demo server.
+ * const url = "http://tracker.transistorsoft.com";
+ * const orgname = "my-company-name";
+ * const username = "my-username";
+ *
+ * // Fetch an authoriztion token from server.  The SDK will cache the received token.
+ * const token = await
+ *   BackgroundGeolocation.findOrCreateTransistorAuthorizationToken(orgname, username, url);
+ *
+ * BackgroundGeolocation.ready({
+ *   transistorAuthorizationToken: token
+ * })
+ * ```
+ *
+ * __Viewing Your Tracking Results__
+ *
+ * To *view* your tracking results in the browser, use your configured "Organization Name" and visit:
+ *
+ * http://tracker.transistorsoft.com/my-organization-name
+ *
+ * @category Demo / Debug Server
+ */
+export interface TransistorAuthorizationService {
+    /**
+     * Find or create a token for the given organization and username.
+     *
+     * @param orgName - Organization / company identifier.
+     * @param username - Username or device label.
+     * @param url - Optional tracker base URL. Defaults to the SDK's built‑in value.
+     *
+     * @returns A Promise resolving with a {@link TransistorAuthorizationToken} instance.
+     *
+     * @example
+     * ```typescript
+     * // Url to demo server.
+     * const url = "http://tracker.transistorsoft.com";
+     * const orgname = "my-company-name";
+     * const username = "my-username";
+     *
+     * // Fetch an authoriztion token from server.  The SDK will cache the received token.
+     * const token = await
+     *   BackgroundGeolocation.findOrCreateTransistorAuthorizationToken(orgname, username, url);
+     *
+     * BackgroundGeolocation.ready({
+     *   transistorAuthorizationToken: token
+     * })
+     * ```
+     */
+    findOrCreate(orgName: string, username: string, url?: string): Promise<TransistorAuthorizationToken>;
+    /**
+     * Destroy the token associated with the given tracker base URL.
+     *
+     * @param url - Tracker base URL. Defaults to the SDK's built‑in value.
+     */
+    destroy(url?: string): Promise<void>;
+    /**
+     * Mutates a {@link Config} to apply the given Transistor token if present.
+     *
+     * The JS implementation typically:
+     * - Reads `config.transistorAuthorizationToken`
+     * - Deletes that property
+     * - Sets `config.http.url` or `config.url` to `"<token.url>/api/locations"`
+     * - Sets `config.authorization = { strategy: "jwt", ... }`
+     *
+     * If no `transistorAuthorizationToken` is found, the `config` is returned unchanged.
+     *
+     * @param config - A config that may contain a `transistorAuthorizationToken` field.
+     * @returns A {@link Config} with HTTP + authorization wired to the token, if present.
+     *
+     * @example
+     * ```ts
+     * async function applyDemoToken(
+     *   service: TransistorAuthorizationService,
+     *   config: Config
+     * ): Promise<Config> {
+     *   const token = await service.findOrCreate('my-org', 'user@example.com');
+     *
+     *   return service.applyIf({
+     *     ...config,
+     *     transistorAuthorizationToken: token
+     *   });
+     * }
+     * ```
+     */
+    applyIf<T extends Config & {
+        transistorAuthorizationToken?: TransistorAuthorizationToken;
+    }>(config: T): Config;
+}

package/dist/core/config/Config.d.ts

@@ -5,6 +5,7 @@ import { AppConfig } from './AppConfig';
 import { PersistenceConfig } from './PersistenceConfig';
 import { ActivityConfig } from './ActivityConfig';
 import { AuthorizationConfig } from './AuthorizationConfig';
+import { TransistorAuthorizationToken } from '../api/TransistorAuthorizationService';
 /**
  * Configuration API.
  *
@@ -146,4 +147,49 @@ export interface Config {
      * Authorization configuration.
      */
     authorization?: AuthorizationConfig;
+    /**
+      * *Convenience* option to automatically configures the SDK to upload locations to the Transistor Software demo server
+      * at http://tracker.transistorsoft.com (or your own local instance of [background-geolocation-console](https://github.com/transistorsoft/background-geolocation-console))
+      *
+      * See {@link TransistorAuthorizationService}.  This option will **automatically configure** the {@link HttpConfig.url}
+      * to point at the Demo server as well as well as the required {@link AuthorizationConfig} configuration.
+      *
+      * @example
+      * ```typescript
+      * const token = await
+      *   BackgroundGeolocation.findOrCreateTransistorAuthorizationToken("my-company-name", "my-username");
+      *
+      * BackgroundGeolocation.ready({
+      *   transistorAuthorizationToken: token
+      * });
+      * ```
+      *
+      * This *convenience* option merely performs the following [[Authorization]] configuration *automatically* for you:
+      *
+      * @example
+      * ```typescript
+      * // Base url to Transistor Demo Server.
+      * const url = "http://tracker.transistorsoft.com";
+      *
+      * // Register for an authorization token from server.
+      * const token = await
+      *   BackgroundGeolocation.findOrCreateTransistorAuthorizationToken("my-company-name", "my-username");
+      *
+      * BackgroundGeolocation.ready({
+      *   url: url + "/api/locations",
+      *   authorization: {
+      *     strategy: "JWT",
+      *     accessToken: token.accessToken,
+      *     refreshToken: token.refreshToken,
+      *     refreshUrl: url + "/v2/refresh_token",
+      *     refreshPayload: {
+      *       refresh_token: "{refreshToken}"
+      *     },
+      *     expires: token.expires
+      *   }
+      * });
+      * ```
+      *
+      */
+    transistorAuthorization?: TransistorAuthorizationToken;
 }

package/dist/core/config/PersistenceConfig.d.ts

@@ -527,7 +527,7 @@ export interface PersistenceConfig {
      * Disable the automatic insertion of a synthetic “provider-change” location
      * into the SDK’s SQLite database (and its subsequent HTTP upload).
      *
-     * By default, when an {@link onProviderChange} event fires, the Android SDK
+     * By default, when an {@link BackgroundGeolocation.onProviderChange} event fires, the Android SDK
      * records a special location documenting *when* and *where* the device’s
      * location-services state changed (e.g., GPS disabled).
      * This behavior historically existed to support platforms with limited or

package/dist/enums/AccuracyAuthorization.d.ts

@@ -14,3 +14,8 @@ export declare const AccuracyAuthorization: {
     readonly Full: 0;
     readonly Reduced: 1;
 };
+/**
+ * Type union of the AccuracyAuthorization values.
+ * @internal @hidden
+ */
+export type AccuracyAuthorization = (typeof AccuracyAuthorization)[keyof typeof AccuracyAuthorization];

package/dist/enums/ActivityType.d.ts

@@ -26,3 +26,8 @@ export declare const ActivityType: {
     /** Airborne activity (iOS 15+). */
     readonly Airborne: 5;
 };
+/**
+ * Type union of the ActivityType values.
+ * @internal @hidden
+ */
+export type ActivityType = (typeof ActivityType)[keyof typeof ActivityType];

package/dist/enums/AuthorizationStatus.d.ts

@@ -18,3 +18,7 @@ export declare const AuthorizationStatus: {
     readonly Always: 3;
     readonly WhenInUse: 4;
 };
+/**
+ * @hidden @internal
+ */
+export type AuthorizationStatus = (typeof AuthorizationStatus)[keyof typeof AuthorizationStatus];

package/dist/enums/AuthorizationStrategy.d.ts

@@ -8,3 +8,7 @@ export declare const AuthorizationStrategy: {
     readonly Jwt: "jwt";
     readonly Sas: "sas";
 };
+/**
+ * @internal @hidden
+ */
+export type AuthorizationStrategy = (typeof AuthorizationStrategy)[keyof typeof AuthorizationStrategy];

package/dist/enums/DesiredAccuracy.d.ts

@@ -11,3 +11,5 @@ export declare const DesiredAccuracy: {
     readonly VeryLow: 1000;
     readonly Lowest: 3000;
 };
+/** @internal @hidden */
+export type DesiredAccuracy = typeof DesiredAccuracy[keyof typeof DesiredAccuracy];

package/dist/enums/Event.d.ts

@@ -4,6 +4,8 @@
  * @category Events
  */
 export declare const Event: {
+    readonly Boot: "boot";
+    readonly Terminate: "terminate";
     readonly Location: "location";
     readonly MotionChange: "motionchange";
     readonly ActivityChange: "activitychange";
@@ -19,3 +21,8 @@ export declare const Event: {
     readonly Schedule: "schedule";
     readonly Notification: "notification";
 };
+/**
+ * Event names emitted by the SDK.
+ * @hidden @internal
+ */
+export type Event = (typeof Event)[keyof typeof Event];

package/dist/enums/Event.js

@@ -7,6 +7,8 @@ exports.Event = void 0;
  * @category Events
  */
 exports.Event = {
+    Boot: 'boot',
+    Terminate: 'terminate',
     Location: 'location',
     MotionChange: 'motionchange',
     ActivityChange: 'activitychange',

package/dist/enums/GeofenceAction.d.ts

@@ -16,3 +16,8 @@ export declare const GeofenceAction: {
     readonly Exit: "EXIT";
     readonly Dwell: "DWELL";
 };
+/**
+ * Union of geofence transition strings.
+ * @internal @hidden
+ */
+export type GeofenceAction = (typeof GeofenceAction)[keyof typeof GeofenceAction];

package/dist/enums/HttpMethod.d.ts

@@ -9,3 +9,5 @@ export declare const HttpMethod: {
     readonly Put: "PUT";
     readonly Patch: "PATCH";
 };
+/** @internal @hidden */
+export type HttpMethod = (typeof HttpMethod)[keyof typeof HttpMethod];

package/dist/enums/KalmanProfile.d.ts

@@ -28,3 +28,5 @@ export declare const KalmanProfile: {
     /** Conservative — maximum smoothing, slower reaction to change. */
     readonly Conservative: 2;
 };
+/** @internal @hidden */
+export type KalmanProfile = (typeof KalmanProfile)[keyof typeof KalmanProfile];

package/dist/enums/LocationError.d.ts

@@ -21,3 +21,8 @@ export declare const LocationError: {
     readonly Timeout: 408;
     readonly Cancelled: 499;
 };
+/**
+ * Union type of possible location error codes.
+ * @internal @hidden
+ */
+export type LocationError = (typeof LocationError)[keyof typeof LocationError];

package/dist/enums/LocationFilterPolicy.d.ts

@@ -106,3 +106,5 @@ export declare const LocationFilterPolicy: {
     /** Aggressive — filters heavily, preferring stability over responsiveness. */
     readonly Conservative: 2;
 };
+/** @internal @hidden */
+export type LocationFilterPolicy = (typeof LocationFilterPolicy)[keyof typeof LocationFilterPolicy];

package/dist/enums/LocationRequest.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Indicates what level of location authorization the SDK should request.
+ *
+ * | Name       | Value        | Description                                              |
+ * |------------|--------------|----------------------------------------------------------|
+ * | Always     | `"Always"`   | Request full background + foreground authorization.      |
+ * | WhenInUse  | `"WhenInUse"`| Request foreground-only authorization.                   |
+ * | Any        | `"Any"`      | Accept *either* Always or WhenInUse (no specific request). |
+ *
+ * Mirrors native iOS authorization request options and existing RN adapter keys.
+ *
+ * See {@link GeoConfig.locationAuthorizationRequest}
+ *
+ * @category Config
+ */
+export declare const LocationRequest: {
+    readonly Always: "Always";
+    readonly WhenInUse: "WhenInUse";
+    readonly Any: "Any";
+};
+/**
+ * Type union of all LocationRequest values.
+ * @internal @hidden
+ */
+export type LocationRequest = (typeof LocationRequest)[keyof typeof LocationRequest];

package/dist/enums/LocationRequest.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocationRequest = void 0;
+/**
+ * Indicates what level of location authorization the SDK should request.
+ *
+ * | Name       | Value        | Description                                              |
+ * |------------|--------------|----------------------------------------------------------|
+ * | Always     | `"Always"`   | Request full background + foreground authorization.      |
+ * | WhenInUse  | `"WhenInUse"`| Request foreground-only authorization.                   |
+ * | Any        | `"Any"`      | Accept *either* Always or WhenInUse (no specific request). |
+ *
+ * Mirrors native iOS authorization request options and existing RN adapter keys.
+ *
+ * See {@link GeoConfig.locationAuthorizationRequest}
+ *
+ * @category Config
+ */
+exports.LocationRequest = {
+    Always: 'Always',
+    WhenInUse: 'WhenInUse',
+    Any: 'Any',
+};

package/dist/enums/LogLevel.d.ts

@@ -1,6 +1,17 @@
 /**
  * Controls the verbosity of plugin logging.
  *
+ * | Level   | Value | Description                     |
+ * |---------|:-----:|---------------------------------|
+ * | Off     |   0   | Disable all logging.            |
+ * | Error   |   1   | Log only critical failures.     |
+ * | Warning |   2   | Log warnings + errors.          |
+ * | Info    |   3   | Operational information.        |
+ * | Debug   |   4   | Developer-level debug output.   |
+ * | Verbose |   5   | Maximum detail.                 |
+ *
+ * Mirrors native logging constants on iOS & Android.
+ *
  * @category Config
  */
 export declare const LogLevel: {
@@ -11,3 +22,8 @@ export declare const LogLevel: {
     readonly Debug: 4;
     readonly Verbose: 5;
 };
+/**
+ * Type union of all LogLevel values.
+ * @internal @hidden
+ */
+export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];

package/dist/enums/LogLevel.js

@@ -4,6 +4,17 @@ exports.LogLevel = void 0;
 /**
  * Controls the verbosity of plugin logging.
  *
+ * | Level   | Value | Description                     |
+ * |---------|:-----:|---------------------------------|
+ * | Off     |   0   | Disable all logging.            |
+ * | Error   |   1   | Log only critical failures.     |
+ * | Warning |   2   | Log warnings + errors.          |
+ * | Info    |   3   | Operational information.        |
+ * | Debug   |   4   | Developer-level debug output.   |
+ * | Verbose |   5   | Maximum detail.                 |
+ *
+ * Mirrors native logging constants on iOS & Android.
+ *
  * @category Config
  */
 exports.LogLevel = {
@@ -12,5 +23,5 @@ exports.LogLevel = {
     Warning: 2,
     Info: 3,
     Debug: 4,
-    Verbose: 5
+    Verbose: 5,
 };

package/dist/enums/LogLevelName.d.ts

@@ -1 +1,14 @@
-export {};
+/**
+ * Log severity level used by {@link Logger.debug} {@link Logger.info}, etc.
+ * @hidden
+ * @internal
+ */
+export declare const LogLevelName: {
+    readonly Debug: "debug";
+    readonly Notice: "notice";
+    readonly Info: "info";
+    readonly Warn: "warn";
+    readonly Error: "error";
+};
+/** @internal @hidden */
+export type LogLevelName = typeof LogLevelName[keyof typeof LogLevelName];

package/dist/enums/MotionActivityType.d.ts

@@ -12,3 +12,5 @@ export declare const MotionActivityType: {
     readonly InVehicle: "in_vehicle";
     readonly Unknown: "unknown";
 };
+/** @internal @hidden */
+export type MotionActivityType = typeof MotionActivityType[keyof typeof MotionActivityType];

package/dist/enums/NotificationPriority.d.ts

@@ -20,3 +20,5 @@ export declare const NotificationPriority: {
     /** Notification strongly weighted to bottom of list; icon hidden. */
     readonly Min: -2;
 };
+/** @internal @hidden */
+export type NotificationPriority = (typeof NotificationPriority)[keyof typeof NotificationPriority];

package/dist/enums/PersistMode.d.ts

@@ -10,3 +10,5 @@ export declare const PersistMode: {
     readonly Geofence: -1;
     readonly None: 0;
 };
+/** @internal @hidden */
+export type PersistMode = (typeof PersistMode)[keyof typeof PersistMode];

package/dist/enums/TrackingMode.d.ts

@@ -12,3 +12,5 @@ export declare const TrackingMode: {
     readonly Geofences: 0;
     readonly Location: 1;
 };
+/** @internal @hidden */
+export type TrackingMode = typeof TrackingMode[keyof typeof TrackingMode];

package/dist/enums/TriggerActivity.d.ts

@@ -11,3 +11,5 @@ export declare const TriggerActivity: {
     readonly OnBicycle: "on_bicycle";
     readonly InVehicle: "in_vehicle";
 };
+/** @internal @hidden */
+export type TriggerActivity = (typeof TriggerActivity)[keyof typeof TriggerActivity];

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export * from './enums/LogLevel';
 export * from './enums/DesiredAccuracy';
 export * from './enums/PersistMode';
 export * from './enums/AuthorizationStrategy';
+export * from './enums/LocationRequest';
 export * from './enums/LocationFilterPolicy';
 export * from './enums/KalmanProfile';
 export * from './enums/HttpMethod';
@@ -47,3 +48,4 @@ export * from './core/api/State';
 export * from './core/api/Logger';
 export * from './core/api/DeviceSettings';
 export * from './core/api/CurrentPositionRequest';
+export * from './core/api/TransistorAuthorizationService';

package/dist/index.js

@@ -20,6 +20,7 @@ __exportStar(require("./enums/LogLevel"), exports);
 __exportStar(require("./enums/DesiredAccuracy"), exports);
 __exportStar(require("./enums/PersistMode"), exports);
 __exportStar(require("./enums/AuthorizationStrategy"), exports);
+__exportStar(require("./enums/LocationRequest"), exports);
 __exportStar(require("./enums/LocationFilterPolicy"), exports);
 __exportStar(require("./enums/KalmanProfile"), exports);
 __exportStar(require("./enums/HttpMethod"), exports);
@@ -67,3 +68,4 @@ __exportStar(require("./core/api/State"), exports);
 __exportStar(require("./core/api/Logger"), exports);
 __exportStar(require("./core/api/DeviceSettings"), exports);
 __exportStar(require("./core/api/CurrentPositionRequest"), exports);
+__exportStar(require("./core/api/TransistorAuthorizationService"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transistorsoft/background-geolocation-types",
-  "version": "5.0.0-beta.1",
+  "version": "5.0.0-beta.3",
   "type": "commonjs",
   "description": "Shared TypeScript type definitions and documentation for Transistor Software's Background Geolocation SDKs (React Native, Capacitor, Cordova)",
   "author": "Transistor Software <info@transistorsoft.com>",

package/dist/core/config/CompoundConfig.d.ts

@@ -1,19 +0,0 @@
-import { LoggerConfig } from './LoggerConfig';
-import { HttpConfig } from './HttpConfig';
-import { GeoConfig } from './GeoConfig';
-import { AppConfig } from './AppConfig';
-import { PersistenceConfig } from './PersistenceConfig';
-import { ActivityConfig } from './ActivityConfig';
-import { AuthorizationConfig } from './AuthorizationConfig';
-/**
- * Root compound configuration object for the BackgroundGeolocation SDK.
- */
-export interface CompoundConfig {
-    logger?: LoggerConfig;
-    geolocation?: GeoConfig;
-    http?: HttpConfig;
-    app?: AppConfig;
-    persistence?: PersistenceConfig;
-    activity?: ActivityConfig;
-    authorization?: AuthorizationConfig;
-}