@hello.nrfcloud.com/nrfcloud-api-helpers 3.0.74 → 4.0.1

package/dist/api/getAccountInfo.d.ts

@@ -14,5 +14,7 @@ export declare const getAccountInfo: ({ apiKey, endpoint, }: {
     endpoint: URL;
 }, fetchImplementation?: typeof fetch) => Promise<{
     error: Error | ValidationError;
-} | AccountInfo>;
+} | {
+    result: AccountInfo;
+}>;
 export {};

package/dist/api/getAccountInfo.js

@@ -17,5 +17,5 @@ export const getAccountInfo = async ({ apiKey, endpoint, }, fetchImplementation)
     }, AccountInfoType);
     if ('error' in maybeAccount)
         return maybeAccount;
-    return maybeAccount.result;
+    return maybeAccount;
 };

package/dist/api/getAccountInfo.spec.js

@@ -13,7 +13,7 @@ void describe('getAccountInfo()', () => {
             json: async () => Promise.resolve(APIresponse),
         }));
         assert.equal('error' in res, false);
-        check(res).is(objectMatching({
+        check('result' in res && res.result).is(objectMatching({
             mqttEndpoint: 'mqtt.nrfcloud.com',
             mqttTopicPrefix: 'prod/b8b26bc5-2814-4063-b4fa-83ecddb2fec7/',
             team: {

package/dist/api/getLocationHistory.d.ts

@@ -0,0 +1,46 @@
+import { type Static } from '@sinclair/typebox';
+import type { ValidationError } from 'ajv';
+export declare enum LocationHistoryServiceType {
+    ANCHOR = "ANCHOR",
+    GNSS = "GNSS",
+    GPS = "GPS",
+    MCELL = "MCELL",
+    MCELL_EVAL = "MCELL_EVAL",
+    SCELL = "SCELL",
+    SCELL_EVAL = "SCELL_EVAL",
+    WIFI = "WIFI",
+    WIFI_EVAL = "WIFI_EVAL"
+}
+declare const LocationHistoryType: import("@sinclair/typebox").TObject<{
+    items: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        id: import("@sinclair/typebox").TString;
+        deviceId: import("@sinclair/typebox").TString;
+        serviceType: import("@sinclair/typebox").TEnum<typeof LocationHistoryServiceType>;
+        insertedAt: import("@sinclair/typebox").TString;
+        lat: import("@sinclair/typebox").TString;
+        lon: import("@sinclair/typebox").TString;
+        meta: import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TAny>;
+        uncertainty: import("@sinclair/typebox").TRegExp;
+        anchors: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+            macAddress: import("@sinclair/typebox").TRegExp;
+            name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRegExp>;
+        }>>>;
+    }>>;
+    total: import("@sinclair/typebox").TNumber;
+    pageNextToken: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+export type LocationHistory = Static<typeof LocationHistoryType>;
+export declare const getLocationHistory: ({ apiKey, endpoint, }: {
+    apiKey: string;
+    endpoint: URL;
+}, fetchImplementation?: typeof fetch) => ({ deviceId, pageNextToken, start, end, }: {
+    deviceId: string;
+    pageNextToken?: string;
+    start?: Date;
+    end?: Date;
+}) => Promise<{
+    error: Error | ValidationError;
+} | {
+    result: Static<typeof LocationHistoryType>;
+}>;
+export {};

package/dist/api/getLocationHistory.js

@@ -0,0 +1,97 @@
+import { Type } from '@sinclair/typebox';
+import { validatedFetch } from './validatedFetch.js';
+export var LocationHistoryServiceType;
+(function (LocationHistoryServiceType) {
+    LocationHistoryServiceType["ANCHOR"] = "ANCHOR";
+    LocationHistoryServiceType["GNSS"] = "GNSS";
+    LocationHistoryServiceType["GPS"] = "GPS";
+    LocationHistoryServiceType["MCELL"] = "MCELL";
+    LocationHistoryServiceType["MCELL_EVAL"] = "MCELL_EVAL";
+    LocationHistoryServiceType["SCELL"] = "SCELL";
+    LocationHistoryServiceType["SCELL_EVAL"] = "SCELL_EVAL";
+    LocationHistoryServiceType["WIFI"] = "WIFI";
+    LocationHistoryServiceType["WIFI_EVAL"] = "WIFI_EVAL";
+})(LocationHistoryServiceType || (LocationHistoryServiceType = {}));
+const LocationHistoryType = Type.Object({
+    items: Type.Array(Type.Object({
+        id: Type.String({
+            minLength: 1,
+            title: 'ID',
+            description: 'Universally unique identifier',
+            examples: ['bc631093-7f7c-4c1b-aa63-a68c759bcd5c'],
+        }),
+        deviceId: Type.String({
+            minLength: 1,
+            title: 'This is the canonical device id used in the device certificate, and as the MQTT client id.',
+            examples: ['nrf-1234567890123456789000'],
+        }),
+        serviceType: Type.Enum(LocationHistoryServiceType, {
+            title: 'Tracker Service Type',
+            description: 'This is the service used to obtain the location of a device. The "_EVAL" suffix means the location was obtained using an evaluation token. GNSS location is derived on the device and reported back to the cloud. "GPS" type has been deprecated, but will still return for older records.',
+            examples: ['location'],
+        }),
+        insertedAt: Type.String({
+            title: 'Insertion Time',
+            description: 'HTML-encoded ISO-8601 date-time string denoting the start or end of a date range. If the string includes only a date, the time is the beginning of the day (00:00:00).',
+            examples: ['2021-08-31T20:00:00Z'],
+        }),
+        lat: Type.String({
+            minLength: 1,
+            examples: ['63.41999531'],
+            description: 'Latitude in degrees',
+        }),
+        lon: Type.String({
+            minLength: 1,
+            examples: ['-122.688408'],
+            description: 'Longitude in degrees',
+        }),
+        meta: Type.Record(Type.String({ minLength: 1 }), Type.Any(), {
+            title: 'GNSS metatdata',
+            description: 'Metadata sent from device when reporting GNSS location in PVT format. Can include other non-gnss related key/value pairs for easy retrieval later. Only populated for GNSS PVT formatted fixes, empty object otherwise.',
+        }),
+        uncertainty: Type.RegExp(/^[0-9.]+$/, {
+            title: 'Uncertainty',
+            description: 'Radius of the uncertainty circle around the location in meters. Also known as Horizontal Positioning Error (HPE).',
+            examples: ['2420', '13.012'],
+        }),
+        anchors: Type.Optional(Type.Array(Type.Object({
+            macAddress: Type.RegExp(/^([0-9a-f]{2}:){5}[0-9a-f]{2}$/i, {
+                title: 'Mac Address',
+                description: 'String comprised of 6 hexadecimal pairs, separated by colons or dashes. When used in a positioning request, it must be universally assigned. See this help page for details.',
+                examples: ['FE:1E:41:2D:9E:53'],
+            }),
+            name: Type.Optional(Type.RegExp(/^[a-z0-9_ -]{1,32}$/i, {
+                title: 'Name',
+                description: 'Limit 32 characters. Only numbers, letters, underscores, dashes, and spaces allowed. All other characters will be removed.',
+                examples: ['anchor-1'],
+            })),
+        }))),
+    })),
+    total: Type.Number({ minimum: 0 }),
+    pageNextToken: Type.Optional(Type.String({ minLength: 1 })),
+}, {
+    title: 'Location History',
+    description: 'See https://api.nrfcloud.com/v1#tag/Location-History/operation/GetLocationHistory',
+});
+export const getLocationHistory = ({ apiKey, endpoint, }, fetchImplementation) => async ({ deviceId, pageNextToken, start, end, }) => {
+    const query = new URLSearchParams({
+        pageLimit: '100',
+        deviceId,
+    });
+    if (start !== undefined)
+        query.set('start', start.toISOString());
+    if (end !== undefined)
+        query.set('end', end.toISOString());
+    if (pageNextToken !== undefined)
+        query.set('pageNextToken', pageNextToken);
+    const maybeHistory = await validatedFetch({
+        endpoint,
+        apiKey,
+    }, fetchImplementation)({
+        resource: 'location/history',
+        query,
+    }, LocationHistoryType);
+    if ('error' in maybeHistory)
+        return maybeHistory;
+    return maybeHistory;
+};

package/dist/api/getLocationHistory.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/api/getLocationHistory.spec.js

@@ -0,0 +1,35 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { getLocationHistory } from './getLocationHistory.js';
+import APIresponse from './test-data/location.json';
+import { aString, arrayMatching, check, objectMatching } from 'tsmatchers';
+await describe('getLocationHistory()', async () => {
+    await it('return the location history', async () => {
+        const res = await getLocationHistory({
+            endpoint: new URL('https://example.com/'),
+            apiKey: 'some-key',
+        }, () => Promise.resolve({
+            ok: true,
+            json: async () => Promise.resolve(APIresponse),
+        }))({
+            deviceId: 'oob-355025930003742',
+        });
+        assert.equal('error' in res, false);
+        check('result' in res && res.result).is(objectMatching({
+            items: arrayMatching([
+                objectMatching({
+                    id: '3b45f2db-3b0c-4be8-be9a-273f12697fc4',
+                    deviceId: 'oob-355025930003742',
+                    serviceType: 'MCELL',
+                    insertedAt: '2024-06-04T09:54:52.651Z',
+                    uncertainty: '301',
+                    lat: '59.92335269',
+                    lon: '10.68829941',
+                    meta: {},
+                }),
+            ]),
+            total: 100,
+            pageNextToken: aString,
+        }));
+    });
+});

package/dist/api/index.d.ts

@@ -4,6 +4,7 @@ export * from './getCurrentMonthlyCosts.js';
 export * from './createAccountDevice.js';
 export * from './slashless.js';
 export * from './getAccountInfo.js';
+export * from './getLocationHistory.js';
 export * from './deleteAccountDevice.js';
 export * from './getDeviceShadow.js';
 export * from './DeviceShadow.js';

package/dist/api/index.js

@@ -4,6 +4,7 @@ export * from './getCurrentMonthlyCosts.js';
 export * from './createAccountDevice.js';
 export * from './slashless.js';
 export * from './getAccountInfo.js';
+export * from './getLocationHistory.js';
 export * from './deleteAccountDevice.js';
 export * from './getDeviceShadow.js';
 export * from './DeviceShadow.js';

package/dist/api/test-data/location.json

@@ -0,0 +1,26 @@
+{
+    "items": [
+        {
+            "id": "3b45f2db-3b0c-4be8-be9a-273f12697fc4",
+            "deviceId": "oob-355025930003742",
+            "serviceType": "MCELL",
+            "insertedAt": "2024-06-04T09:54:52.651Z",
+            "uncertainty": "301",
+            "lat": "59.92335269",
+            "lon": "10.68829941",
+            "meta": {}
+        },
+        {
+            "id": "1d2d7188-ef48-427f-9e7d-55caf47958ac",
+            "deviceId": "oob-355025930003742",
+            "serviceType": "WIFI",
+            "insertedAt": "2024-06-04T09:54:47.014Z",
+            "uncertainty": "15.066",
+            "lat": "59.9212502",
+            "lon": "10.6885059",
+            "meta": {}
+        }
+    ],
+    "total": 100,
+    "pageNextToken": "G6QAUI3UVncWwk%2Bps9f3dKLy3I6kBRhUXs5fmFKo3JJn4JADhwMGFhAH3BIINuA4xsDGDT8Ev7rn%2FV45Dd2vBBCx6wxjnHJOFJ6JQyLRS0Kmudiqz%2FMEsmojHdxaYxOCA06orvL7gm7dxH2o06ADouim%2BstZ2lqDqFDECoX6Rh%2FJGB5dsxTPDQM%3D"
+}

package/dist/api/validatedFetch.d.ts

@@ -8,7 +8,7 @@ export declare class ValidationError extends Error {
 export declare const validatedFetch: ({ endpoint, apiKey }: {
     apiKey: string;
     endpoint: URL;
-}, fetchImplementation?: typeof fetch) => <Schema extends TObject<import("@sinclair/typebox").TProperties>>(params: {
+}, fetchImplementation?: typeof fetch) => <Schema extends TObject<import("@sinclair/typebox").TProperties>>(params: ({
     resource: string;
 } | {
     resource: string;
@@ -16,6 +16,8 @@ export declare const validatedFetch: ({ endpoint, apiKey }: {
 } | {
     resource: string;
     method: string;
+}) & {
+    query?: URLSearchParams;
 }, schema: Schema) => Promise<{
     error: Error | ValidationError;
 } | {

package/dist/api/validatedFetch.js

@@ -25,7 +25,7 @@ const fetchData = (fetchImplementation) => async (...args) => {
     return response.json();
 };
 export const validatedFetch = ({ endpoint, apiKey }, fetchImplementation) => async (params, schema) => {
-    const { resource } = params;
+    const { resource, query } = params;
     const args = {
         headers: headers(apiKey),
     };
@@ -38,7 +38,7 @@ export const validatedFetch = ({ endpoint, apiKey }, fetchImplementation) => asy
     else if ('method' in params) {
         args.method = params.method;
     }
-    return fetchData(fetchImplementation)(`${slashless(endpoint)}/v1/${resource}`, args)
+    return fetchData(fetchImplementation)(`${slashless(endpoint)}/v1/${resource}${query !== undefined ? `?${query.toString()}` : ''}`, args)
         .then((res) => ({ result: validate(schema, res) }))
         .catch((error) => ({
         error,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hello.nrfcloud.com/nrfcloud-api-helpers",
-  "version": "3.0.74",
+  "version": "4.0.1",
   "description": "Helper functions for integrating nRF Cloud APIs in AWS lambdas written in TypeScript.",
   "exports": {
     "./*": {
@@ -82,9 +82,9 @@
   ],
   "prettier": "@bifravst/prettier-config",
   "peerDependencies": {
-    "@aws-sdk/client-dynamodb": "^3.588.0",
-    "@aws-sdk/client-ssm": "^3.588.0",
-    "@aws-sdk/util-dynamodb": "^3.588.0",
+    "@aws-sdk/client-dynamodb": "^3.590.0",
+    "@aws-sdk/client-ssm": "^3.590.0",
+    "@aws-sdk/util-dynamodb": "^3.590.0",
     "@bifravst/aws-ssm-settings-helpers": "^1.1.26",
     "@hello.nrfcloud.com/proto": "^13.0.8",
     "@sinclair/typebox": "^0.32.31"