@transistorsoft/background-geolocation-types 5.0.0-beta.1 → 5.0.0-beta.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/core/api/BackgroundGeolocation.d.ts +369 -1
- package/dist/core/api/TransistorAuthorizationService.d.ts +124 -0
- package/dist/core/api/TransistorAuthorizationService.js +2 -0
- package/dist/core/config/Config.d.ts +46 -0
- package/dist/core/config/PersistenceConfig.d.ts +1 -1
- package/dist/enums/Event.d.ts +2 -0
- package/dist/enums/Event.js +2 -0
- package/dist/enums/LocationRequest.d.ts +20 -0
- package/dist/enums/LocationRequest.js +23 -0
- package/dist/enums/LogLevel.d.ts +11 -0
- package/dist/enums/LogLevel.js +12 -1
- package/dist/index.d.ts +2 -0
- package/dist/index.js +2 -0
- package/package.json +1 -1
|
@@ -1,6 +1,374 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
2
|
+
* Primary BackgroundGeolocation API
|
|
3
|
+
*
|
|
4
|
+
* __Overview__
|
|
5
|
+
*
|
|
6
|
+
* The `BackgroundGeolocation` interface defines the **complete, strongly-typed API surface**
|
|
7
|
+
* for Transistor Software’s Background Geolocation SDK.
|
|
8
|
+
* This is the main entry-point used by all JavaScript adapters:
|
|
9
|
+
*
|
|
10
|
+
* - React Native (`{{pluginName}}`)
|
|
11
|
+
* - Capacitor
|
|
12
|
+
* - Cordova
|
|
13
|
+
*
|
|
14
|
+
* The API provides:
|
|
15
|
+
*
|
|
16
|
+
* - **Configuration** via a single {@link Config} object composed of modular
|
|
17
|
+
* sub-configs (`GeoConfig`, `HttpConfig`, `PersistenceConfig`, etc)
|
|
18
|
+
* - **Lifecycle control** (`ready`, `start`, `stop`, `setConfig`, `reset`)
|
|
19
|
+
* - **Location tracking** (motion-based tracking, `getCurrentPosition`,
|
|
20
|
+
* `watchPosition`)
|
|
21
|
+
* - **Geofencing** (`addGeofence`, `onGeofence`, etc)
|
|
22
|
+
* - **Events subsystem** with fully-typed callbacks (`onLocation`,
|
|
23
|
+
* `onMotionChange`, `onHttp`, `onProviderChange`, etc)
|
|
24
|
+
* - **Native services** such as background-tasks, authorization workflows,
|
|
25
|
+
* scheduling, and device-capability checks
|
|
26
|
+
* - **Persistence + HTTP** via an internal SQLite buffer and optional
|
|
27
|
+
* auto-upload system
|
|
28
|
+
*
|
|
29
|
+
* __Typed Configuration (Compound Config)__
|
|
30
|
+
*
|
|
31
|
+
* Instead of a large “flat” configuration object, the SDK uses a
|
|
32
|
+
* *compound-configuration model*:
|
|
33
|
+
*
|
|
34
|
+
* ```ts
|
|
35
|
+
* import BackgroundGeolocation, {
|
|
36
|
+
* Config,
|
|
37
|
+
* GeoConfig,
|
|
38
|
+
* HttpConfig
|
|
39
|
+
* } from "{{pluginName}}";
|
|
40
|
+
*
|
|
41
|
+
* const config: Config = {
|
|
42
|
+
* geolocation: {
|
|
43
|
+
* desiredAccuracy: BackgroundGeolocation.DesiredAccuracy.High,
|
|
44
|
+
* distanceFilter: 20
|
|
45
|
+
* },
|
|
46
|
+
* http: {
|
|
47
|
+
* url: "https://example.com/locations",
|
|
48
|
+
* autoSync: true
|
|
49
|
+
* },
|
|
50
|
+
* persistence: {
|
|
51
|
+
* maxDaysToPersist: 7
|
|
52
|
+
* }
|
|
53
|
+
* };
|
|
54
|
+
*
|
|
55
|
+
* BackgroundGeolocation.ready(config);
|
|
56
|
+
* ```
|
|
57
|
+
*
|
|
58
|
+
* This structure ensures:
|
|
59
|
+
*
|
|
60
|
+
* - **Clear separation of concerns**
|
|
61
|
+
* - **Type-safe configuration**
|
|
62
|
+
* - **Automatic backwards-compatibility** with legacy flat keys
|
|
63
|
+
*
|
|
64
|
+
* __Typed Enum Namespaces__
|
|
65
|
+
*
|
|
66
|
+
* All configuration flags that were previously “magic constants”
|
|
67
|
+
* (e.g., `LOG_LEVEL_VERBOSE`, `DESIRED_ACCURACY_HIGH`) now live in
|
|
68
|
+
* strongly-typed namespaces attached to the default export:
|
|
69
|
+
*
|
|
70
|
+
* - {@link BackgroundGeolocation.LogLevel}
|
|
71
|
+
* - {@link BackgroundGeolocation.DesiredAccuracy}
|
|
72
|
+
* - {@link BackgroundGeolocation.PersistMode}
|
|
73
|
+
* - {@link BackgroundGeolocation.NotificationPriority}
|
|
74
|
+
* - {@link BackgroundGeolocation.Event}
|
|
75
|
+
* - …and more
|
|
76
|
+
*
|
|
77
|
+
* These can also be imported individually:
|
|
78
|
+
*
|
|
79
|
+
* ```ts
|
|
80
|
+
* import BackgroundGeolocation, { LogLevel } from "{{pluginName}}";
|
|
81
|
+
*
|
|
82
|
+
* BackgroundGeolocation.ready({
|
|
83
|
+
* logger: {
|
|
84
|
+
* logLevel: LogLevel.Debug
|
|
85
|
+
* }
|
|
86
|
+
* });
|
|
87
|
+
* ```
|
|
88
|
+
*
|
|
89
|
+
* __Event System__
|
|
90
|
+
*
|
|
91
|
+
* The SDK exposes a robust, typed event API:
|
|
92
|
+
*
|
|
93
|
+
* ```ts
|
|
94
|
+
* BackgroundGeolocation.onLocation((location) => {
|
|
95
|
+
* console.log("New location:", location);
|
|
96
|
+
* });
|
|
97
|
+
*
|
|
98
|
+
* BackgroundGeolocation.onMotionChange((event) => {
|
|
99
|
+
* console.log("Device is moving?", event.isMoving);
|
|
100
|
+
* });
|
|
101
|
+
* ```
|
|
102
|
+
*
|
|
103
|
+
* All events return **Subscription** objects which must be removed when no longer
|
|
104
|
+
* needed:
|
|
105
|
+
*
|
|
106
|
+
* ```ts
|
|
107
|
+
* const sub = BackgroundGeolocation.onHttp((e) => { ... });
|
|
108
|
+
* sub.remove();
|
|
109
|
+
* ```
|
|
110
|
+
*
|
|
111
|
+
* __Native Lifecycle Requirements__
|
|
112
|
+
*
|
|
113
|
+
* On both iOS and Android, `BackgroundGeolocation.ready(config)` must be called
|
|
114
|
+
* **exactly once per app launch**, before calling `start()`.
|
|
115
|
+
* The SDK automatically restores its last-known configuration from persistent
|
|
116
|
+
* storage after first install.
|
|
117
|
+
*
|
|
118
|
+
* __Philosophy of Operation__
|
|
119
|
+
*
|
|
120
|
+
* Transistorsoft’s tracking engine is built around:
|
|
121
|
+
*
|
|
122
|
+
* - **Motion-based state transitions** (stationary ↔ moving)
|
|
123
|
+
* - **Aggressive tracking only when moving**
|
|
124
|
+
* - **Energy-efficient passive monitoring when stationary**
|
|
125
|
+
* - **Reliable persistence via SQLite**
|
|
126
|
+
* - **Automatic retries + batching** for HTTP uploads
|
|
127
|
+
*
|
|
128
|
+
* Combined, this enables *battery-efficient*, *high-quality* background tracking
|
|
129
|
+
* across iOS and Android.
|
|
130
|
+
*
|
|
131
|
+
* __Capabilities__
|
|
132
|
+
*
|
|
133
|
+
* - High-frequency tracking while the device is moving
|
|
134
|
+
* - Zero-movement battery preservation
|
|
135
|
+
* - Geofence monitoring at scale (thousands of geofences)
|
|
136
|
+
* - Offline storage + sync when network is restored
|
|
137
|
+
* - Background tasks for long-running operations
|
|
138
|
+
* - Authorization state + system diagnostics
|
|
139
|
+
*
|
|
140
|
+
* __Getting Started__
|
|
141
|
+
*
|
|
142
|
+
* ```ts
|
|
143
|
+
* import BackgroundGeolocation from "{{pluginName}}";
|
|
144
|
+
*
|
|
145
|
+
* const state = await BackgroundGeolocation.ready({
|
|
146
|
+
* geolocation: { distanceFilter: 10 },
|
|
147
|
+
* http: { url: "https://example.com/locations", autoSync: true }
|
|
148
|
+
* });
|
|
149
|
+
*
|
|
150
|
+
* if (!state.enabled) {
|
|
151
|
+
* await BackgroundGeolocation.start();
|
|
152
|
+
* }
|
|
153
|
+
* ```
|
|
154
|
+
*
|
|
155
|
+
* Once `start()` is called, the SDK begins operating according to your
|
|
156
|
+
* configuration and continues running—even in the background—until you call
|
|
157
|
+
* `stop()`.
|
|
158
|
+
*
|
|
3
159
|
* @category Primary API
|
|
4
160
|
*/
|
|
5
161
|
export interface BackgroundGeolocation extends BackgroundGeolocationAPI {
|
|
162
|
+
/**
|
|
163
|
+
* __LogLevel__
|
|
164
|
+
* Controls verbosity of the SDK logger.
|
|
165
|
+
* Used by LoggerConfig.logLevel.
|
|
166
|
+
* Values range from silent (`Off`) to extremely verbose (`Verbose`).
|
|
167
|
+
*
|
|
168
|
+
* @example
|
|
169
|
+
* ```ts
|
|
170
|
+
* BackgroundGeolocation.ready({
|
|
171
|
+
* logger: {
|
|
172
|
+
* logLevel: BackgroundGeolocation.LogLevel.Verbose
|
|
173
|
+
* }
|
|
174
|
+
* });
|
|
175
|
+
* ```
|
|
176
|
+
* @readonly
|
|
177
|
+
*/
|
|
178
|
+
LogLevel: typeof import('../../enums/LogLevel').LogLevel;
|
|
179
|
+
/**
|
|
180
|
+
* __DesiredAccuracy__
|
|
181
|
+
* Controls the native location engine’s target accuracy.
|
|
182
|
+
* Higher accuracy consumes more battery.
|
|
183
|
+
* Used by GeoConfig.desiredAccuracy.
|
|
184
|
+
*
|
|
185
|
+
* @example
|
|
186
|
+
* ```ts
|
|
187
|
+
* BackgroundGeolocation.ready({
|
|
188
|
+
* geolocation: {
|
|
189
|
+
* desiredAccuracy: BackgroundGeolocation.DesiredAccuracy.High
|
|
190
|
+
* }
|
|
191
|
+
* });
|
|
192
|
+
* ```
|
|
193
|
+
* @readonly
|
|
194
|
+
*/
|
|
195
|
+
DesiredAccuracy: typeof import('../../enums/DesiredAccuracy').DesiredAccuracy;
|
|
196
|
+
/**
|
|
197
|
+
* __PersistMode__
|
|
198
|
+
* Controls which records the SDK persists to SQLite:
|
|
199
|
+
* locations only, geofences only, both, or none.
|
|
200
|
+
* Used by PersistenceConfig.persistMode.
|
|
201
|
+
*
|
|
202
|
+
* @example
|
|
203
|
+
* ```ts
|
|
204
|
+
* BackgroundGeolocation.ready({
|
|
205
|
+
* persistence: {
|
|
206
|
+
* persistMode: BackgroundGeolocation.PersistMode.All
|
|
207
|
+
* }
|
|
208
|
+
* });
|
|
209
|
+
* ```
|
|
210
|
+
* @readonly
|
|
211
|
+
*/
|
|
212
|
+
PersistMode: typeof import('../../enums/PersistMode').PersistMode;
|
|
213
|
+
/**
|
|
214
|
+
* __AuthorizationStrategy__
|
|
215
|
+
* Defines how the HTTP service performs authorization.
|
|
216
|
+
* Includes basic, JWT, and custom strategies.
|
|
217
|
+
* Used by AuthorizationConfig.strategy.
|
|
218
|
+
*
|
|
219
|
+
* @example
|
|
220
|
+
* ```ts
|
|
221
|
+
* BackgroundGeolocation.ready({
|
|
222
|
+
* authorization: {
|
|
223
|
+
* strategy: BackgroundGeolocation.AuthorizationStrategy.Jwt
|
|
224
|
+
* }
|
|
225
|
+
* });
|
|
226
|
+
* ```
|
|
227
|
+
* @readonly
|
|
228
|
+
*/
|
|
229
|
+
AuthorizationStrategy: typeof import('../../enums/AuthorizationStrategy').AuthorizationStrategy;
|
|
230
|
+
/**
|
|
231
|
+
* __LocationFilterPolicy__
|
|
232
|
+
* Selects the filtering engine policy for noise-reduction and smoothing.
|
|
233
|
+
* Used by GeoConfig.locationFilter.
|
|
234
|
+
*
|
|
235
|
+
* @example
|
|
236
|
+
* ```ts
|
|
237
|
+
* BackgroundGeolocation.ready({
|
|
238
|
+
* geolocation: {
|
|
239
|
+
* filter: {
|
|
240
|
+
* policy: BackgroundGeolocation.LocationFilterPolicy.Adjust
|
|
241
|
+
* }
|
|
242
|
+
* });
|
|
243
|
+
* ```
|
|
244
|
+
* @readonly
|
|
245
|
+
*/
|
|
246
|
+
LocationFilterPolicy: typeof import('../../enums/LocationFilterPolicy').LocationFilterPolicy;
|
|
247
|
+
/**
|
|
248
|
+
* __KalmanProfile__
|
|
249
|
+
* Selects a preset tuning profile for the Kalman filter used in the
|
|
250
|
+
* filtering engine (aggressive, moderate, or relaxed smoothing).
|
|
251
|
+
*
|
|
252
|
+
* @example
|
|
253
|
+
* ```ts
|
|
254
|
+
* BackgroundGeolocation.ready({
|
|
255
|
+
* geolocation: {
|
|
256
|
+
* kalmanProfile: BackgroundGeolocation.KalmanProfile.Aggressive
|
|
257
|
+
* }
|
|
258
|
+
* });
|
|
259
|
+
* ```
|
|
260
|
+
* @readonly
|
|
261
|
+
*/
|
|
262
|
+
KalmanProfile: typeof import('../../enums/KalmanProfile').KalmanProfile;
|
|
263
|
+
/**
|
|
264
|
+
* __HttpMethod__
|
|
265
|
+
* Defines the HTTP method used for uploads (POST, PUT, etc).
|
|
266
|
+
* Used by HttpConfig.method.
|
|
267
|
+
*
|
|
268
|
+
* @example
|
|
269
|
+
* ```ts
|
|
270
|
+
* BackgroundGeolocation.ready({
|
|
271
|
+
* http: {
|
|
272
|
+
* method: BackgroundGeolocation.HttpMethod.Post
|
|
273
|
+
* }
|
|
274
|
+
* });
|
|
275
|
+
* ```
|
|
276
|
+
* @readonly
|
|
277
|
+
*/
|
|
278
|
+
HttpMethod: typeof import('../../enums/HttpMethod').HttpMethod;
|
|
279
|
+
/**
|
|
280
|
+
* __TriggerActivity__
|
|
281
|
+
* Defines which physical motion activities can trigger motion-detection
|
|
282
|
+
* transitions (still → moving).
|
|
283
|
+
* Used by ActivityConfig.triggerActivities.
|
|
284
|
+
*
|
|
285
|
+
* @example
|
|
286
|
+
* ```ts
|
|
287
|
+
* BackgroundGeolocation.ready({
|
|
288
|
+
* activity: {
|
|
289
|
+
* triggerActivities: [
|
|
290
|
+
* BackgroundGeolocation.TriggerActivity.InVehicle
|
|
291
|
+
* ]
|
|
292
|
+
* }
|
|
293
|
+
* });
|
|
294
|
+
* ```
|
|
295
|
+
* @readonly
|
|
296
|
+
*/
|
|
297
|
+
TriggerActivity: typeof import('../../enums/TriggerActivity').TriggerActivity;
|
|
298
|
+
/**
|
|
299
|
+
* __NotificationPriority__
|
|
300
|
+
* Controls Android foreground-service notification priority and icon
|
|
301
|
+
* placement (top, bottom, hidden).
|
|
302
|
+
* Used by NotificationConfig.priority.
|
|
303
|
+
*
|
|
304
|
+
* @example
|
|
305
|
+
* ```ts
|
|
306
|
+
* BackgroundGeolocation.ready({
|
|
307
|
+
* notification: {
|
|
308
|
+
* priority: BackgroundGeolocation.NotificationPriority.High
|
|
309
|
+
* }
|
|
310
|
+
* });
|
|
311
|
+
* ```
|
|
312
|
+
* @readonly
|
|
313
|
+
*/
|
|
314
|
+
NotificationPriority: typeof import('../../enums/NotificationPriority').NotificationPriority;
|
|
315
|
+
/**
|
|
316
|
+
* __Event__
|
|
317
|
+
* Enumerates all event names emitted by the SDK (location, geofence,
|
|
318
|
+
* motionchange, heartbeat, etc).
|
|
319
|
+
*
|
|
320
|
+
* @readonly
|
|
321
|
+
*/
|
|
322
|
+
Event: typeof import('../../enums/Event').Event;
|
|
323
|
+
/**
|
|
324
|
+
* __LocationRequest__
|
|
325
|
+
* Defines the type of permission request made to iOS (Always, WhenInUse,
|
|
326
|
+
* or Any).
|
|
327
|
+
* Used by GeoConfig.locationAuthorizationRequest.
|
|
328
|
+
*
|
|
329
|
+
* @example
|
|
330
|
+
* ```ts
|
|
331
|
+
* BackgroundGeolocation.ready({
|
|
332
|
+
* geolocation: {
|
|
333
|
+
* locationAuthorizationRequest: BackgroundGeolocation.LocationRequest.Always
|
|
334
|
+
* }
|
|
335
|
+
* });
|
|
336
|
+
* ```
|
|
337
|
+
* @readonly
|
|
338
|
+
*/
|
|
339
|
+
LocationRequest: typeof import('../../enums/LocationRequest').LocationRequest;
|
|
340
|
+
/**
|
|
341
|
+
* __AccuracyAuthorization__
|
|
342
|
+
* iOS 14+: Indicates whether the user granted full or reduced accuracy.
|
|
343
|
+
* Used by ProviderChangeEvent.accuracyAuthorization and
|
|
344
|
+
* requestTemporaryFullAccuracy.
|
|
345
|
+
*
|
|
346
|
+
* @example
|
|
347
|
+
* ```ts
|
|
348
|
+
* BackgroundGeolocation.onProviderChange((event) => {
|
|
349
|
+
* if (event.accuracyAuthorization ===
|
|
350
|
+
* BackgroundGeolocation.AccuracyAuthorization.Reduced) {
|
|
351
|
+
* // Handle reduced-accuracy case
|
|
352
|
+
* }
|
|
353
|
+
* });
|
|
354
|
+
* ```
|
|
355
|
+
* @readonly
|
|
356
|
+
*/
|
|
357
|
+
AccuracyAuthorization: typeof import('../../enums/AccuracyAuthorization').AccuracyAuthorization;
|
|
358
|
+
/**
|
|
359
|
+
* __AuthorizationStatus__
|
|
360
|
+
* Represents OS-level authorization state for location-services
|
|
361
|
+
* (Denied, Restricted, Always, WhenInUse).
|
|
362
|
+
* Returned from requestPermission() and onProviderChange.
|
|
363
|
+
*
|
|
364
|
+
* @example
|
|
365
|
+
* ```ts
|
|
366
|
+
* const status = await BackgroundGeolocation.requestPermission();
|
|
367
|
+
* if (status === BackgroundGeolocation.AuthorizationStatus.Always) {
|
|
368
|
+
* // Good to start tracking
|
|
369
|
+
* }
|
|
370
|
+
* ```
|
|
371
|
+
* @readonly
|
|
372
|
+
*/
|
|
373
|
+
AuthorizationStatus: typeof import('../../enums/AuthorizationStatus').AuthorizationStatus;
|
|
6
374
|
}
|
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
import type { Config } from '../config/Config';
|
|
2
|
+
/**
|
|
3
|
+
* Represents an authorization token issued by a Transistorsoft Tracking Server.
|
|
4
|
+
*
|
|
5
|
+
* Returned from {@link TransistorAuthorizationService.findOrCreate} and consumed by
|
|
6
|
+
* `Config.authorization` / `transistorAuthorizationToken` flows.
|
|
7
|
+
*
|
|
8
|
+
* @category Demo / Debug Server
|
|
9
|
+
*/
|
|
10
|
+
export interface TransistorAuthorizationToken {
|
|
11
|
+
/** JWT access token used for `Authorization: Bearer <token>`. */
|
|
12
|
+
accessToken: string;
|
|
13
|
+
/** JWT refresh token used at the `refreshUrl` endpoint. */
|
|
14
|
+
refreshToken: string;
|
|
15
|
+
/**
|
|
16
|
+
* Expiry time of the access token (epoch milliseconds).
|
|
17
|
+
* Typically used to drive {@link AuthorizationConfig.expires}.
|
|
18
|
+
*/
|
|
19
|
+
expires: number;
|
|
20
|
+
/** Base tracker server URL that issued this token. */
|
|
21
|
+
url: string;
|
|
22
|
+
}
|
|
23
|
+
/**
|
|
24
|
+
* Transistor Software hosts a demo server at [tracker.transistorsoft.com](http://tracker.transistorsoft.com) which is
|
|
25
|
+
* designed to consume location data from devices running the Background Geolocation SDK.
|
|
26
|
+
*
|
|
27
|
+
* You may also run your own instance of Demo Server locally. See [background-geolocation-console](https://github.com/transistorsoft/background-geolocation-console)
|
|
28
|
+
*
|
|
29
|
+
* The test server is a great way to debug location problems or evalute the SDK's behaviour, since the results can easily
|
|
30
|
+
* be shared with *Transistor Software* when requesting support.
|
|
31
|
+
*
|
|
32
|
+
* 
|
|
33
|
+
*
|
|
34
|
+
*
|
|
35
|
+
* @example
|
|
36
|
+
* ```typescript
|
|
37
|
+
* // Url to demo server.
|
|
38
|
+
* const url = "http://tracker.transistorsoft.com";
|
|
39
|
+
* const orgname = "my-company-name";
|
|
40
|
+
* const username = "my-username";
|
|
41
|
+
*
|
|
42
|
+
* // Fetch an authoriztion token from server. The SDK will cache the received token.
|
|
43
|
+
* const token = await
|
|
44
|
+
* BackgroundGeolocation.findOrCreateTransistorAuthorizationToken(orgname, username, url);
|
|
45
|
+
*
|
|
46
|
+
* BackgroundGeolocation.ready({
|
|
47
|
+
* transistorAuthorizationToken: token
|
|
48
|
+
* })
|
|
49
|
+
* ```
|
|
50
|
+
*
|
|
51
|
+
* __Viewing Your Tracking Results__
|
|
52
|
+
*
|
|
53
|
+
* To *view* your tracking results in the browser, use your configured "Organization Name" and visit:
|
|
54
|
+
*
|
|
55
|
+
* http://tracker.transistorsoft.com/my-organization-name
|
|
56
|
+
*
|
|
57
|
+
* @category Demo / Debug Server
|
|
58
|
+
*/
|
|
59
|
+
export interface TransistorAuthorizationService {
|
|
60
|
+
/**
|
|
61
|
+
* Find or create a token for the given organization and username.
|
|
62
|
+
*
|
|
63
|
+
* @param orgName - Organization / company identifier.
|
|
64
|
+
* @param username - Username or device label.
|
|
65
|
+
* @param url - Optional tracker base URL. Defaults to the SDK's built‑in value.
|
|
66
|
+
*
|
|
67
|
+
* @returns A Promise resolving with a {@link TransistorAuthorizationToken} instance.
|
|
68
|
+
*
|
|
69
|
+
* @example
|
|
70
|
+
* ```typescript
|
|
71
|
+
* // Url to demo server.
|
|
72
|
+
* const url = "http://tracker.transistorsoft.com";
|
|
73
|
+
* const orgname = "my-company-name";
|
|
74
|
+
* const username = "my-username";
|
|
75
|
+
*
|
|
76
|
+
* // Fetch an authoriztion token from server. The SDK will cache the received token.
|
|
77
|
+
* const token = await
|
|
78
|
+
* BackgroundGeolocation.findOrCreateTransistorAuthorizationToken(orgname, username, url);
|
|
79
|
+
*
|
|
80
|
+
* BackgroundGeolocation.ready({
|
|
81
|
+
* transistorAuthorizationToken: token
|
|
82
|
+
* })
|
|
83
|
+
* ```
|
|
84
|
+
*/
|
|
85
|
+
findOrCreate(orgName: string, username: string, url?: string): Promise<TransistorAuthorizationToken>;
|
|
86
|
+
/**
|
|
87
|
+
* Destroy the token associated with the given tracker base URL.
|
|
88
|
+
*
|
|
89
|
+
* @param url - Tracker base URL. Defaults to the SDK's built‑in value.
|
|
90
|
+
*/
|
|
91
|
+
destroy(url?: string): Promise<void>;
|
|
92
|
+
/**
|
|
93
|
+
* Mutates a {@link Config} to apply the given Transistor token if present.
|
|
94
|
+
*
|
|
95
|
+
* The JS implementation typically:
|
|
96
|
+
* - Reads `config.transistorAuthorizationToken`
|
|
97
|
+
* - Deletes that property
|
|
98
|
+
* - Sets `config.http.url` or `config.url` to `"<token.url>/api/locations"`
|
|
99
|
+
* - Sets `config.authorization = { strategy: "jwt", ... }`
|
|
100
|
+
*
|
|
101
|
+
* If no `transistorAuthorizationToken` is found, the `config` is returned unchanged.
|
|
102
|
+
*
|
|
103
|
+
* @param config - A config that may contain a `transistorAuthorizationToken` field.
|
|
104
|
+
* @returns A {@link Config} with HTTP + authorization wired to the token, if present.
|
|
105
|
+
*
|
|
106
|
+
* @example
|
|
107
|
+
* ```ts
|
|
108
|
+
* async function applyDemoToken(
|
|
109
|
+
* service: TransistorAuthorizationService,
|
|
110
|
+
* config: Config
|
|
111
|
+
* ): Promise<Config> {
|
|
112
|
+
* const token = await service.findOrCreate('my-org', 'user@example.com');
|
|
113
|
+
*
|
|
114
|
+
* return service.applyIf({
|
|
115
|
+
* ...config,
|
|
116
|
+
* transistorAuthorizationToken: token
|
|
117
|
+
* });
|
|
118
|
+
* }
|
|
119
|
+
* ```
|
|
120
|
+
*/
|
|
121
|
+
applyIf<T extends Config & {
|
|
122
|
+
transistorAuthorizationToken?: TransistorAuthorizationToken;
|
|
123
|
+
}>(config: T): Config;
|
|
124
|
+
}
|
|
@@ -5,6 +5,7 @@ import { AppConfig } from './AppConfig';
|
|
|
5
5
|
import { PersistenceConfig } from './PersistenceConfig';
|
|
6
6
|
import { ActivityConfig } from './ActivityConfig';
|
|
7
7
|
import { AuthorizationConfig } from './AuthorizationConfig';
|
|
8
|
+
import { TransistorAuthorizationToken } from '../api/TransistorAuthorizationService';
|
|
8
9
|
/**
|
|
9
10
|
* Configuration API.
|
|
10
11
|
*
|
|
@@ -146,4 +147,49 @@ export interface Config {
|
|
|
146
147
|
* Authorization configuration.
|
|
147
148
|
*/
|
|
148
149
|
authorization?: AuthorizationConfig;
|
|
150
|
+
/**
|
|
151
|
+
* *Convenience* option to automatically configures the SDK to upload locations to the Transistor Software demo server
|
|
152
|
+
* at http://tracker.transistorsoft.com (or your own local instance of [background-geolocation-console](https://github.com/transistorsoft/background-geolocation-console))
|
|
153
|
+
*
|
|
154
|
+
* See {@link TransistorAuthorizationService}. This option will **automatically configure** the {@link HttpConfig.url}
|
|
155
|
+
* to point at the Demo server as well as well as the required {@link AuthorizationConfig} configuration.
|
|
156
|
+
*
|
|
157
|
+
* @example
|
|
158
|
+
* ```typescript
|
|
159
|
+
* const token = await
|
|
160
|
+
* BackgroundGeolocation.findOrCreateTransistorAuthorizationToken("my-company-name", "my-username");
|
|
161
|
+
*
|
|
162
|
+
* BackgroundGeolocation.ready({
|
|
163
|
+
* transistorAuthorizationToken: token
|
|
164
|
+
* });
|
|
165
|
+
* ```
|
|
166
|
+
*
|
|
167
|
+
* This *convenience* option merely performs the following [[Authorization]] configuration *automatically* for you:
|
|
168
|
+
*
|
|
169
|
+
* @example
|
|
170
|
+
* ```typescript
|
|
171
|
+
* // Base url to Transistor Demo Server.
|
|
172
|
+
* const url = "http://tracker.transistorsoft.com";
|
|
173
|
+
*
|
|
174
|
+
* // Register for an authorization token from server.
|
|
175
|
+
* const token = await
|
|
176
|
+
* BackgroundGeolocation.findOrCreateTransistorAuthorizationToken("my-company-name", "my-username");
|
|
177
|
+
*
|
|
178
|
+
* BackgroundGeolocation.ready({
|
|
179
|
+
* url: url + "/api/locations",
|
|
180
|
+
* authorization: {
|
|
181
|
+
* strategy: "JWT",
|
|
182
|
+
* accessToken: token.accessToken,
|
|
183
|
+
* refreshToken: token.refreshToken,
|
|
184
|
+
* refreshUrl: url + "/v2/refresh_token",
|
|
185
|
+
* refreshPayload: {
|
|
186
|
+
* refresh_token: "{refreshToken}"
|
|
187
|
+
* },
|
|
188
|
+
* expires: token.expires
|
|
189
|
+
* }
|
|
190
|
+
* });
|
|
191
|
+
* ```
|
|
192
|
+
*
|
|
193
|
+
*/
|
|
194
|
+
transistorAuthorization?: TransistorAuthorizationToken;
|
|
149
195
|
}
|
|
@@ -527,7 +527,7 @@ export interface PersistenceConfig {
|
|
|
527
527
|
* Disable the automatic insertion of a synthetic “provider-change” location
|
|
528
528
|
* into the SDK’s SQLite database (and its subsequent HTTP upload).
|
|
529
529
|
*
|
|
530
|
-
* By default, when an {@link onProviderChange} event fires, the Android SDK
|
|
530
|
+
* By default, when an {@link BackgroundGeolocation.onProviderChange} event fires, the Android SDK
|
|
531
531
|
* records a special location documenting *when* and *where* the device’s
|
|
532
532
|
* location-services state changed (e.g., GPS disabled).
|
|
533
533
|
* This behavior historically existed to support platforms with limited or
|
package/dist/enums/Event.d.ts
CHANGED
package/dist/enums/Event.js
CHANGED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Indicates what level of location authorization the SDK should request.
|
|
3
|
+
*
|
|
4
|
+
* | Name | Value | Description |
|
|
5
|
+
* |------------|--------------|----------------------------------------------------------|
|
|
6
|
+
* | Always | `"Always"` | Request full background + foreground authorization. |
|
|
7
|
+
* | WhenInUse | `"WhenInUse"`| Request foreground-only authorization. |
|
|
8
|
+
* | Any | `"Any"` | Accept *either* Always or WhenInUse (no specific request). |
|
|
9
|
+
*
|
|
10
|
+
* Mirrors native iOS authorization request options and existing RN adapter keys.
|
|
11
|
+
*
|
|
12
|
+
* See {@link GeoConfig.locationAuthorizationRequest}
|
|
13
|
+
*
|
|
14
|
+
* @category Config
|
|
15
|
+
*/
|
|
16
|
+
export declare const LocationRequest: {
|
|
17
|
+
readonly Always: "Always";
|
|
18
|
+
readonly WhenInUse: "WhenInUse";
|
|
19
|
+
readonly Any: "Any";
|
|
20
|
+
};
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.LocationRequest = void 0;
|
|
4
|
+
/**
|
|
5
|
+
* Indicates what level of location authorization the SDK should request.
|
|
6
|
+
*
|
|
7
|
+
* | Name | Value | Description |
|
|
8
|
+
* |------------|--------------|----------------------------------------------------------|
|
|
9
|
+
* | Always | `"Always"` | Request full background + foreground authorization. |
|
|
10
|
+
* | WhenInUse | `"WhenInUse"`| Request foreground-only authorization. |
|
|
11
|
+
* | Any | `"Any"` | Accept *either* Always or WhenInUse (no specific request). |
|
|
12
|
+
*
|
|
13
|
+
* Mirrors native iOS authorization request options and existing RN adapter keys.
|
|
14
|
+
*
|
|
15
|
+
* See {@link GeoConfig.locationAuthorizationRequest}
|
|
16
|
+
*
|
|
17
|
+
* @category Config
|
|
18
|
+
*/
|
|
19
|
+
exports.LocationRequest = {
|
|
20
|
+
Always: 'Always',
|
|
21
|
+
WhenInUse: 'WhenInUse',
|
|
22
|
+
Any: 'Any',
|
|
23
|
+
};
|
package/dist/enums/LogLevel.d.ts
CHANGED
|
@@ -1,6 +1,17 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Controls the verbosity of plugin logging.
|
|
3
3
|
*
|
|
4
|
+
* | Level | Value | Description |
|
|
5
|
+
* |---------|:-----:|---------------------------------|
|
|
6
|
+
* | Off | 0 | Disable all logging. |
|
|
7
|
+
* | Error | 1 | Log only critical failures. |
|
|
8
|
+
* | Warning | 2 | Log warnings + errors. |
|
|
9
|
+
* | Info | 3 | Operational information. |
|
|
10
|
+
* | Debug | 4 | Developer-level debug output. |
|
|
11
|
+
* | Verbose | 5 | Maximum detail. |
|
|
12
|
+
*
|
|
13
|
+
* Mirrors native logging constants on iOS & Android.
|
|
14
|
+
*
|
|
4
15
|
* @category Config
|
|
5
16
|
*/
|
|
6
17
|
export declare const LogLevel: {
|
package/dist/enums/LogLevel.js
CHANGED
|
@@ -4,6 +4,17 @@ exports.LogLevel = void 0;
|
|
|
4
4
|
/**
|
|
5
5
|
* Controls the verbosity of plugin logging.
|
|
6
6
|
*
|
|
7
|
+
* | Level | Value | Description |
|
|
8
|
+
* |---------|:-----:|---------------------------------|
|
|
9
|
+
* | Off | 0 | Disable all logging. |
|
|
10
|
+
* | Error | 1 | Log only critical failures. |
|
|
11
|
+
* | Warning | 2 | Log warnings + errors. |
|
|
12
|
+
* | Info | 3 | Operational information. |
|
|
13
|
+
* | Debug | 4 | Developer-level debug output. |
|
|
14
|
+
* | Verbose | 5 | Maximum detail. |
|
|
15
|
+
*
|
|
16
|
+
* Mirrors native logging constants on iOS & Android.
|
|
17
|
+
*
|
|
7
18
|
* @category Config
|
|
8
19
|
*/
|
|
9
20
|
exports.LogLevel = {
|
|
@@ -12,5 +23,5 @@ exports.LogLevel = {
|
|
|
12
23
|
Warning: 2,
|
|
13
24
|
Info: 3,
|
|
14
25
|
Debug: 4,
|
|
15
|
-
Verbose: 5
|
|
26
|
+
Verbose: 5,
|
|
16
27
|
};
|
package/dist/index.d.ts
CHANGED
|
@@ -3,6 +3,7 @@ export * from './enums/LogLevel';
|
|
|
3
3
|
export * from './enums/DesiredAccuracy';
|
|
4
4
|
export * from './enums/PersistMode';
|
|
5
5
|
export * from './enums/AuthorizationStrategy';
|
|
6
|
+
export * from './enums/LocationRequest';
|
|
6
7
|
export * from './enums/LocationFilterPolicy';
|
|
7
8
|
export * from './enums/KalmanProfile';
|
|
8
9
|
export * from './enums/HttpMethod';
|
|
@@ -47,3 +48,4 @@ export * from './core/api/State';
|
|
|
47
48
|
export * from './core/api/Logger';
|
|
48
49
|
export * from './core/api/DeviceSettings';
|
|
49
50
|
export * from './core/api/CurrentPositionRequest';
|
|
51
|
+
export * from './core/api/TransistorAuthorizationService';
|
package/dist/index.js
CHANGED
|
@@ -20,6 +20,7 @@ __exportStar(require("./enums/LogLevel"), exports);
|
|
|
20
20
|
__exportStar(require("./enums/DesiredAccuracy"), exports);
|
|
21
21
|
__exportStar(require("./enums/PersistMode"), exports);
|
|
22
22
|
__exportStar(require("./enums/AuthorizationStrategy"), exports);
|
|
23
|
+
__exportStar(require("./enums/LocationRequest"), exports);
|
|
23
24
|
__exportStar(require("./enums/LocationFilterPolicy"), exports);
|
|
24
25
|
__exportStar(require("./enums/KalmanProfile"), exports);
|
|
25
26
|
__exportStar(require("./enums/HttpMethod"), exports);
|
|
@@ -67,3 +68,4 @@ __exportStar(require("./core/api/State"), exports);
|
|
|
67
68
|
__exportStar(require("./core/api/Logger"), exports);
|
|
68
69
|
__exportStar(require("./core/api/DeviceSettings"), exports);
|
|
69
70
|
__exportStar(require("./core/api/CurrentPositionRequest"), exports);
|
|
71
|
+
__exportStar(require("./core/api/TransistorAuthorizationService"), exports);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@transistorsoft/background-geolocation-types",
|
|
3
|
-
"version": "5.0.0-beta.
|
|
3
|
+
"version": "5.0.0-beta.2",
|
|
4
4
|
"type": "commonjs",
|
|
5
5
|
"description": "Shared TypeScript type definitions and documentation for Transistor Software's Background Geolocation SDKs (React Native, Capacitor, Cordova)",
|
|
6
6
|
"author": "Transistor Software <info@transistorsoft.com>",
|