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

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

@@ -0,0 +1,200 @@
+/**
+ * Configure the SDK to authenticate with your server using an
+ * {@link AuthorizationConfig.accessToken | access token} (e.g., a
+ * [JSON Web Token](https://jwt.io/)), and automatically request new tokens when
+ * the server returns **`401 Unauthorized`**.
+ *
+ * **Note:** Only [JSON Web Token](https://jwt.io/) (JWT) is currently supported.
+ *
+ * The SDK automatically attaches your token to each HTTP request:
+ *
+ * ```txt
+ * Authorization: Bearer XXX.YYY.ZZZ
+ * ```
+ *
+ * When using {@link Config.authorization}, **do not** manually define
+ * `Authorization` inside {@link HttpConfig.headers}. The SDK manages all JWT
+ * headers automatically.
+ *
+ * If you supply {@link AuthorizationConfig.refreshUrl},
+ * {@link AuthorizationConfig.refreshToken}, and
+ * {@link AuthorizationConfig.refreshPayload}, the SDK can automatically refresh
+ * expired tokens when a `401 Unauthorized` response is received.
+ *
+ * **Configuration**
+ *
+ * @example
+ * ```ts
+ * const token = getMyToken(); // Your own JWT fetch method
+ *
+ * // Listen for authorization refresh results
+ * BackgroundGeolocation.onAuthorization((event) => {
+ *   if (event.success) {
+ *     console.log("[authorization] SUCCESS:", event.response);
+ *   } else {
+ *     console.log("[authorization] ERROR:", event.error);
+ *   }
+ * });
+ *
+ * // Initialize with JWT authorization
+ * BackgroundGeolocation.ready({
+ *   http: {
+ *     url: "https://app.your.server.com/users/locations",
+ *     autoSync: true,
+ *   },
+ *   authorization: {
+ *     strategy: "JWT",
+ *     accessToken: token.accessToken,
+ *     refreshToken: token.refreshToken,
+ *     refreshUrl: "https://auth.your.server.com/tokens",
+ *     refreshPayload: {
+ *       the_refresh_token_field_name: "{refreshToken}"
+ *     },
+ *     expires: token.expiresAt,
+ *   }
+ * });
+ * ```
+ *
+ * **Receiving responses from** {@link AuthorizationConfig.refreshUrl}
+ *
+ * Whenever the SDK receives a response from your
+ * {@link refreshUrl}, it fires
+ * {@link BackgroundGeolocation.onAuthorization}. Your callback will receive an
+ * {@link AuthorizationEvent}.
+ *
+ * - On **success**, {@link AuthorizationEvent.response} contains the parsed JSON.
+ * - On **error**, {@link AuthorizationEvent.error} contains the error message.
+ *
+ * @example
+ * ```ts
+ * BackgroundGeolocation.onAuthorization((event) => {
+ *   if (event.success) {
+ *     console.log("[authorization] SUCCESS:", event.response);
+ *   } else {
+ *     console.log("[authorization] ERROR:", event.error);
+ *   }
+ * });
+ * ```
+ * @category Config
+ */
+export interface AuthorizationConfig {
+    /**
+     * Authorization strategy.  Only [JWT](https://jwt.io/) is supported.
+     */
+    strategy: string;
+    /**
+     * Authorization token (eg: [JWT](https://jwt.io/)) required for authorization by your server at {@link HttpConfig.url}.
+     *
+     * The SDK will automatically apply the configured `accessToken` to each HTTP request's `Authorization` header, eg:
+     *
+     * `"Authorization": "Bearer XXX.YYY.ZZZ"`
+     *
+     * You do **not** need to manually configure {@link HttpConfig.headers} with the `Authorization` parameter.  It is all **automatic**.
+     */
+    accessToken: string;
+    /**
+     * The token to be POSTed to {@link refreshUrl}, encoded into the {@link refreshPayload}, when a new {@link accessToken} is required after {@link expires} or when HTTP `401 Unauthorized` is received.
+     */
+    refreshToken?: string;
+    /**
+     * The url to your authorization server that provides new {@link accessToken} when expired.
+     *
+     * When the SDK receives a response the server, it will decode the JSON and recursively iterate through the keys, performing regular expressions and other String-analysis *to "taste"* the data in search of the following 3 items:
+     *
+     * 1. "access token"
+     * 2. "refresh token"
+     * 3. "expiry time"
+     *
+     * The SDK is designed to operate with *any* response data-structure.  For example, one authorization server might return a complex response such as:
+     *
+     * ```json
+     * {
+     *   "token": {
+     *     "access_token": "XXX.YYY.ZZZ",
+     *     "expires_at": 3900
+     *   },
+     *   "refresh_token": "smTsfaspfgaadsfgqZerUt0wueflasdfkaxjdfeKIacb"
+     * }
+     * ```
+     *
+     * While another server might return a flat response, such as:
+     *
+     * ```json
+     * {
+     *  "accessToken": "XXX.YYY.ZZZ",
+     *  "refreshToken": "smTsfaspfgaadsfgqZerUt0wueflasdfkaxjdfeKIacb",
+     *  "expiry": 3900
+     * }
+     * ```
+     *
+     * When the response from the server is received, the event {@link BackgroundGeolocation.onAuthorization} will be fired, provided with the {@link AuthorizationEvent}.
+     */
+    refreshUrl?: string;
+    /**
+     * Refresh payload will be encoded into the FORM POST to the {@link refreshUrl} when requesting a new {@link accessToken} after expiration.
+     *
+     * You *must* provide one field-template which will represent your "refresh token" using the value: __`{refreshToken}`__.  The SDK will
+     * _automatically_ replace this simple template with the configured {@link refreshToken}.
+     *
+     * @example
+     *
+     * ```typescript
+     * BackgroundGeolocation.ready({
+     *   authorization: {
+     *     strategy: "JWT",
+     *     accessToken: "XXX.YYY.ZZZ",
+     *     refreshUrl: "https://auth.your.server.com/tokens",
+     *     refreshToken: "smTsfaspfgaadsfgqZerUt0wueflasdfkaxjdfeKIacb",
+     *     refreshPayload: {
+     *       my_refresh_token: "{refreshToken}",
+     *       grant_type: "refresh_token",
+     *       foo: "another arbitrary field"
+     *     }
+     *   }
+     * });
+     * ```
+     *
+     * with the configuration above, a **`curl`** representation of the SDK's FORM POST, might look like this:
+     * ```bash
+     * $ curl -X POST \
+     *   -F 'my_refresh_token=smTsfaspfgaadsfgqZerUt0wueflasdfkaxjdfeKIacb' \
+     *   -F 'grant_type=refresh_token' \
+     *   -F 'foo=another arbitrary field' \
+     *   https://auth.your.server.com/tokens
+     * ```
+     *
+     */
+    refreshPayload?: Record<string, string>;
+    /**
+     * Optional headers applied on requests to {@link refreshUrl}
+     * Defaults to: `{"Authorization":  "Bearer {accessToken}"}`
+     *
+     * The template variable `{accessToken}` will automatically be replaced with your app's current auth token.
+     *
+     * If you do not want *any* headers applied on requests to {refreshUrl}, provide an empty `{}`.
+     *
+     * ## Example
+     *
+     * ```typescript
+     * BackgroundGeolocation.ready({
+     *   authorization: {
+     *     accessToken: "XXX.YYY.ZZZ",
+     *     refreshUrl: "https://auth.domain.com/tokens",
+     *     refreshToken: "smTsfaspfgaadsfgqZerUt0wueflasdfkaxjdfeKIacb",
+     *     refreshPayload: {
+     *       "my_refresh_token": "{refreshToken}", // <-- replaced with configured refreshToken above.
+     *       "grant_type": "refresh_token",        // <-- arbitrary fields required by your auth server
+     *       "foo": "another arbitrary field"
+     *     },
+     *     refreshHeaders: {}  // <-- Empty {} to provide no refreshHeaders.
+     *   )
+     * ));
+     * ```
+     *
+     */
+    refreshHeaders?: Record<string, string>;
+    /**
+     * Token expiry time in seconds.
+     */
+    expires?: number;
+}

package/dist/core/config/AuthorizationConfig.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,19 @@
+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;
+}

package/dist/core/config/CompoundConfig.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,149 @@
+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';
+/**
+ * Configuration API.
+ *
+ * The `Config` class defines all SDK options, grouped into compound
+ * configuration objects:
+ *
+ * - {@link GeoConfig} — Geolocation and filtering options
+ * - {@link AppConfig} — Application lifecycle options
+ * - {@link HttpConfig} — Networking and HTTP sync options
+ * - {@link PersistenceConfig} — Data persistence and database options
+ * - {@link LoggerConfig} — Logging and debugging options
+ * - {@link ActivityConfig} — Motion and activity-recognition options
+ *
+ * Instances of `Config` are consumed by {@link BackgroundGeolocation.ready}
+ * and {@link BackgroundGeolocation.setConfig}.
+ *
+ * @example
+ *
+ * ```ts
+ * import BackgroundGeolocation, {
+ *   Config,
+ *   GeoConfig,
+ *   ActivityConfig,
+ *   HttpConfig,
+ *   PersistenceConfig,
+ *   DesiredAccuracy,
+ *   PersistMode,
+ *   LogLevel,
+ *   AppConfig,
+ *   LoggerConfig,
+ *   State
+ * } from '{{pluginName}}';
+ *
+ * async function main() {
+ *   // Configure the SDK with compound configuration objects.
+ *   const config: Config = {
+ *     geolocation: {
+ *       desiredAccuracy: DesiredAccuracy.High,
+ *       distanceFilter: 20,
+ *       stopTimeout: 5,
+ *       stationaryRadius: 150,
+ *     },
+ *     activity: {
+ *       disableStopDetection: false,
+ *       motionTriggerDelay: 30000,
+ *     },
+ *     http: {
+ *       url: 'https://my.server.com/api/locations',
+ *       method: 'POST',
+ *       autoSync: true,
+ *       headers: {
+ *         Authorization: 'Bearer secret-token',
+ *       },
+ *       params: {
+ *         user_id: 123,
+ *       },
+ *     },
+ *     persistence: {
+ *       persistMode: PersistMode.All,
+ *       maxDaysToPersist: 14,
+ *       extras: { appVersion: '1.0.0' },
+ *     },
+ *     app: {
+ *       stopOnTerminate: false,
+ *       startOnBoot: true,
+ *       enableHeadless: true
+ *     },
+ *     logger: {
+ *       debug: true,
+ *       logLevel: LogLevel.Verbose,
+ *       logMaxDays: 3,
+ *     },
+ *   };
+ *
+ *   // Apply the configuration.
+ *   const state: State = await BackgroundGeolocation.ready(config);
+ *   console.log('[ready] BackgroundGeolocation is configured and ready to use');
+ *
+ *   if (!state.enabled) {
+ *     await BackgroundGeolocation.start();
+ *   }
+ *
+ *   // To modify configuration after initialization, use setConfig.
+ *   const updated: State = await BackgroundGeolocation.setConfig({
+ *     http: {
+ *       headers: {
+ *         Authorization: 'Bearer new-token',
+ *       },
+ *     },
+ *     logger: {
+ *       logLevel: LogLevel.Info
+ *     },
+ *   });
+ *
+ *   await BackgroundGeolocation.sync();
+ * }
+ *
+ * ```
+ * @category Primary API
+ * @category Config
+ */
+export interface Config {
+    /**
+     * Reset the plugin to its initial state before applying this configuration.  This is probably what you want.
+     *
+     * Defaults to `true`
+     *
+     * If you set this to `false`, the SDK will consume your `Config` only at the first install of your app.  Thereafter, the only way
+     * to change your configuration will be to call {@link BackgroundGeolocation.setConfig},
+     *
+     * You will certainly **NOT** want to use `reset: false` during development, as it will prevent your configuration changes from taking effect on subsequent app launches.
+     */
+    reset?: boolean;
+    /**
+     * Logger configuration.
+     */
+    logger?: LoggerConfig;
+    /**
+     * Geolocation configuration.
+     */
+    geolocation?: GeoConfig;
+    /**
+     * HTTP configuration.
+     */
+    http?: HttpConfig;
+    /**
+     * App configuration.
+     */
+    app?: AppConfig;
+    /**
+     * Persistence configuration.
+     */
+    persistence?: PersistenceConfig;
+    /**
+     * Motion Activity configuration.
+     */
+    activity?: ActivityConfig;
+    /**
+     * Authorization configuration.
+     */
+    authorization?: AuthorizationConfig;
+}

package/dist/core/config/Config.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });