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

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

@@ -1,200 +1,9 @@
-/**
- * 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/Config.d.ts

@@ -6,190 +6,14 @@ import { PersistenceConfig } from './PersistenceConfig';
 import { ActivityConfig } from './ActivityConfig';
 import { AuthorizationConfig } from './AuthorizationConfig';
 import { TransistorAuthorizationToken } from '../api/TransistorAuthorizationService';
-/**
- * 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;
-    /**
-      * *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;
+    transistorAuthorizationToken?: TransistorAuthorizationToken;
 }