@hello.nrfcloud.com/nrfcloud-api-helpers 5.0.10 → 5.2.0

package/dist/api/FetchError.d.ts

@@ -0,0 +1,5 @@
+export declare class FetchError extends Error {
+    readonly statusCode: number;
+    constructor(statusCode: number, message: string);
+}
+export declare const toFetchError: (response: Response) => Promise<FetchError>;

package/dist/api/FetchError.js

@@ -0,0 +1,11 @@
+export class FetchError extends Error {
+    statusCode;
+    constructor(statusCode, message) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = 'FetchError';
+    }
+}
+export const toFetchError = async (response) => new FetchError(response.status, parseInt(response.headers.get('content-length') ?? '0', 10) > 0
+    ? await response.text()
+    : 'No content returned from server');

package/dist/api/bulkOps.d.ts

@@ -1,5 +1,6 @@
 import { type Static } from '@sinclair/typebox';
 import { type ValidationError } from './validatedFetch.js';
+import type { FetchError } from './FetchError.js';
 /**
  * @link https://api.nrfcloud.com/v1/#tag/Bulk-Ops-Requests/operation/FetchBulkOpsRequest
  */
@@ -11,7 +12,7 @@ export declare const bulkOpsRequests: ({ apiKey, endpoint, }: {
     apiKey: string;
     endpoint: URL;
 }, fetchImplementation?: typeof fetch) => (bulkOpsId: string) => Promise<{
-    error: Error | ValidationError;
+    error: FetchError | ValidationError;
 } | {
     result: Static<typeof BulkOpsRequestType>;
 }>;

package/dist/api/createFOTAJob.d.ts

@@ -1,5 +1,6 @@
 import { type Static } from '@sinclair/typebox';
-import type { ValidationError } from 'ajv';
+import type { ValidationError } from './validatedFetch.js';
+import type { FetchError } from './FetchError.js';
 export declare const CreatedFOTAJobType: import("@sinclair/typebox").TObject<{
     jobId: import("@sinclair/typebox").TString;
 }>;
@@ -10,7 +11,7 @@ export declare const createFOTAJob: ({ apiKey, endpoint, }: {
     deviceId: string;
     bundleId: string;
 }) => Promise<{
-    error: Error | ValidationError;
+    error: FetchError | ValidationError;
 } | {
     result: Static<typeof CreatedFOTAJobType>;
 }>;

package/dist/api/devices.d.ts

@@ -1,6 +1,7 @@
 import { type Static } from '@sinclair/typebox';
 import { type ValidationError } from './validatedFetch.js';
 import { DeviceShadow } from './DeviceShadow.js';
+import type { FetchError } from './FetchError.js';
 declare const Devices: import("@sinclair/typebox").TObject<{
     total: import("@sinclair/typebox").TInteger;
     items: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
@@ -33,12 +34,12 @@ export declare const devices: ({ endpoint, apiKey, }: {
     apiKey: string;
 }, fetchImplementation?: typeof fetch) => {
     list: () => Promise<{
-        error: Error | ValidationError;
+        error: FetchError | ValidationError;
     } | {
         result: Static<typeof Devices>;
     }>;
     get: (id: string) => Promise<{
-        error: Error | ValidationError;
+        error: FetchError | ValidationError;
     } | {
         result: Static<typeof DeviceShadow>;
     }>;
@@ -46,7 +47,7 @@ export declare const devices: ({ endpoint, apiKey, }: {
         desired?: Record<string, any>;
         reported?: Record<string, any>;
     }) => Promise<{
-        error: Error;
+        error: FetchError | ValidationError;
     } | {
         success: boolean;
     }>;
@@ -64,7 +65,7 @@ export declare const devices: ({ endpoint, apiKey, }: {
          */
         fwTypes?: FwType[];
     }[]) => Promise<{
-        error: Error;
+        error: FetchError | ValidationError;
     } | {
         bulkOpsRequestId: string;
     }>;

package/dist/api/devices.js

@@ -2,6 +2,7 @@ import { Type } from '@sinclair/typebox';
 import { slashless } from './slashless.js';
 import { validatedFetch } from './validatedFetch.js';
 import { DeviceShadow } from './DeviceShadow.js';
+import { toFetchError } from './FetchError.js';
 const Page = (Item) => Type.Object({
     total: Type.Integer(),
     items: Type.Array(Item),
@@ -47,9 +48,9 @@ export const devices = ({ endpoint, apiKey, }, fetchImplementation) => {
             },
             method: 'PATCH',
             body: JSON.stringify(state),
-        }).then((res) => {
+        }).then(async (res) => {
             if (res.status >= 400)
-                return { error: new Error(`Update failed: ${res.status}`) };
+                return { error: await toFetchError(res) };
             return { success: true };
         }),
         register: async (devices) => {
@@ -75,11 +76,8 @@ export const devices = ({ endpoint, apiKey, }, fetchImplementation) => {
                     type: 'application/octet-stream',
                 },
             }, ProvisionDevice);
-            if ('error' in maybeResult) {
-                return {
-                    error: maybeResult.error,
-                };
-            }
+            if ('error' in maybeResult)
+                return maybeResult;
             return { bulkOpsRequestId: maybeResult.result.bulkOpsRequestId };
         },
     };

package/dist/api/getAccountInfo.d.ts

@@ -1,5 +1,6 @@
 import { type Static } from '@sinclair/typebox';
-import type { ValidationError } from 'ajv';
+import type { ValidationError } from './validatedFetch.js';
+import type { FetchError } from './FetchError.js';
 declare const AccountInfoType: import("@sinclair/typebox").TObject<{
     mqttEndpoint: import("@sinclair/typebox").TString;
     mqttTopicPrefix: import("@sinclair/typebox").TString;
@@ -13,7 +14,7 @@ export declare const getAccountInfo: ({ apiKey, endpoint, }: {
     apiKey: string;
     endpoint: URL;
 }, fetchImplementation?: typeof fetch) => Promise<{
-    error: Error | ValidationError;
+    error: FetchError | ValidationError;
 } | {
     result: AccountInfo;
 }>;

package/dist/api/getCurrentMonthlyCosts.d.ts

@@ -1,9 +1,10 @@
-import type { ValidationError } from 'ajv';
+import type { ValidationError } from './validatedFetch.js';
+import type { FetchError } from './FetchError.js';
 export declare const getCurrentMonthlyCosts: ({ apiKey, endpoint, }: {
     apiKey: string;
     endpoint: URL;
 }, fetchImplementation?: typeof fetch) => () => Promise<{
-    error: Error | ValidationError;
+    error: FetchError | ValidationError;
 } | {
     currentMonthTotalCost: number;
 }>;

package/dist/api/getDeviceShadow.d.ts

@@ -1,5 +1,6 @@
 import { type Static } from '@sinclair/typebox';
-import type { ValidationError } from 'ajv';
+import type { ValidationError } from './validatedFetch.js';
+import type { FetchError } from './FetchError.js';
 declare const DeviceShadows: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
     id: import("@sinclair/typebox").TString;
     $meta: import("@sinclair/typebox").TObject<{
@@ -19,6 +20,6 @@ export declare const getDeviceShadow: ({ endpoint, apiKey, }: {
 }, fetchImplementation?: typeof fetch) => ((devices: string[]) => Promise<{
     shadows: Static<typeof DeviceShadows>;
 } | {
-    error: Error | ValidationError;
+    error: FetchError | ValidationError;
 }>);
 export {};

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

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

package/dist/api/getFOTABundle.spec.js

@@ -0,0 +1,92 @@
+import { describe, it, mock } from 'node:test';
+import assert from 'node:assert/strict';
+import { getFOTABundles } from './getFOTABundles.js';
+void describe('getFOTABundles()', () => {
+    void it('should fetch all FOTA bundles', async () => {
+        const mockFetch = mock.fn();
+        mockFetch.mock.mockImplementationOnce(() => ({
+            ok: true,
+            json: async () => Promise.resolve({
+                items: [
+                    {
+                        bundleId: 'APP*0038b655*v1.1.1-debug',
+                        lastModified: '2023-06-28T09:50:02.000Z',
+                        size: 418565,
+                        version: 'v1.1.1-debug',
+                        type: 'APP',
+                        filenames: ['hello-nrfcloud-thingy91-debug-v1.1.1-fwupd.bin'],
+                        name: 'hello.nrfcloud.com v1.1.1-debug',
+                        description: 'Firmware Update Image BIN file (thingy91, debug)',
+                    },
+                ],
+                total: 1,
+                pageNextToken: '102/B5fGZNAs7vcw8E2i611ID4apx/Du/2/H6nr2UDWk5eoihEeAgh6qoaGcDzAI4M8JCoO4iAAK96TWfuB19ru9c1PrnwiTUdw/sZzwrYSrS433vPjDJNvJUIEmqm9+V3ElM5M1bLmt6GrGa57SymHHK4nN0W+zHhmE97cCCfzJMBXhVTl3TzvBx5rE1KJYf',
+            }),
+        }), 0);
+        mockFetch.mock.mockImplementationOnce(() => ({
+            ok: true,
+            json: async () => Promise.resolve({
+                items: [
+                    {
+                        bundleId: 'APP*0103b0f9*v1.1.2-sol-dbg',
+                        lastModified: '2023-06-29T14:18:19.000Z',
+                        size: 426280,
+                        version: 'v1.1.2-sol-dbg',
+                        type: 'APP',
+                        filenames: ['hello-nrfcloud-thingy91-sol-dbg-v1.1.2-fwupd.bin'],
+                        name: 'hello.nrfcloud.com v1.1.2-sol-dbg',
+                        description: 'Firmware Update Image BIN file (thingy91, solar, debug)',
+                    },
+                ],
+                total: 1,
+            }),
+        }), 1);
+        const fetcher = getFOTABundles({
+            endpoint: new URL('https://example.com/'),
+            apiKey: 'some-key',
+        }, mockFetch);
+        const res = await fetcher();
+        assert.deepEqual(mockFetch.mock.calls[0]?.arguments, [
+            `https://example.com/v1/firmwares?pageLimit=100`,
+            {
+                headers: {
+                    Accept: 'application/json; charset=utf-8',
+                    Authorization: 'Bearer some-key',
+                },
+            },
+        ]);
+        assert.deepEqual(mockFetch.mock.calls[1]?.arguments, [
+            `https://example.com/v1/firmwares?pageLimit=100&pageNextToken=${encodeURIComponent(`102/B5fGZNAs7vcw8E2i611ID4apx/Du/2/H6nr2UDWk5eoihEeAgh6qoaGcDzAI4M8JCoO4iAAK96TWfuB19ru9c1PrnwiTUdw/sZzwrYSrS433vPjDJNvJUIEmqm9+V3ElM5M1bLmt6GrGa57SymHHK4nN0W+zHhmE97cCCfzJMBXhVTl3TzvBx5rE1KJYf`)}`,
+            {
+                headers: {
+                    Accept: 'application/json; charset=utf-8',
+                    Authorization: 'Bearer some-key',
+                },
+            },
+        ]);
+        assert.deepEqual(res, {
+            bundles: [
+                {
+                    bundleId: 'APP*0038b655*v1.1.1-debug',
+                    lastModified: '2023-06-28T09:50:02.000Z',
+                    size: 418565,
+                    version: 'v1.1.1-debug',
+                    type: 'APP',
+                    filenames: ['hello-nrfcloud-thingy91-debug-v1.1.1-fwupd.bin'],
+                    name: 'hello.nrfcloud.com v1.1.1-debug',
+                    description: 'Firmware Update Image BIN file (thingy91, debug)',
+                },
+                {
+                    bundleId: 'APP*0103b0f9*v1.1.2-sol-dbg',
+                    lastModified: '2023-06-29T14:18:19.000Z',
+                    size: 426280,
+                    version: 'v1.1.2-sol-dbg',
+                    type: 'APP',
+                    filenames: ['hello-nrfcloud-thingy91-sol-dbg-v1.1.2-fwupd.bin'],
+                    name: 'hello.nrfcloud.com v1.1.2-sol-dbg',
+                    description: 'Firmware Update Image BIN file (thingy91, solar, debug)',
+                },
+            ],
+        });
+    });
+});

package/dist/api/getFOTABundles.d.ts

@@ -0,0 +1,22 @@
+import { type Static } from '@sinclair/typebox';
+import type { ValidationError } from './validatedFetch.js';
+import { FwType } from './devices.js';
+import type { FetchError } from './FetchError.js';
+export declare const FOTABundle: import("@sinclair/typebox").TObject<{
+    bundleId: import("@sinclair/typebox").TString;
+    lastModified: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    size: import("@sinclair/typebox").TNumber;
+    version: import("@sinclair/typebox").TString;
+    type: import("@sinclair/typebox").TEnum<typeof FwType>;
+    filenames: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
+    name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    description: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+export declare const getFOTABundles: ({ apiKey, endpoint, }: {
+    apiKey: string;
+    endpoint: URL;
+}, fetchImplementation?: typeof fetch) => () => Promise<{
+    error: FetchError | ValidationError;
+} | {
+    bundles: Array<Static<typeof FOTABundle>>;
+}>;

package/dist/api/getFOTABundles.js

@@ -0,0 +1,73 @@
+import { Type } from '@sinclair/typebox';
+import { validatedFetch } from './validatedFetch.js';
+import { FwType } from './devices.js';
+export const FOTABundle = Type.Object({
+    bundleId: Type.String({
+        minLength: 1,
+        description: 'The ID of the bundle',
+        examples: ['APP*20a4b75a*v1.1.1-debug'],
+    }),
+    lastModified: Type.Optional(Type.String({
+        title: 'Timestamp',
+        description: 'ISO-8601 date-time string',
+        examples: ['2019-08-24T14:15:22Z'],
+    })),
+    size: Type.Number({
+        minimum: 0,
+        description: 'Size of the bundle in bytes',
+        examples: [418565],
+    }),
+    version: Type.String({ minLength: 1, examples: ['v1.1.1-debug'] }),
+    type: Type.Enum(FwType, { title: 'Firmware Type' }),
+    filenames: Type.Array(Type.String({
+        minLength: 1,
+        examples: ['hello-nrfcloud-thingy91-debug-v1.1.1-fwupd.bin'],
+    }), { description: 'The files in the bundle.' }),
+    name: Type.Optional(Type.String({
+        minLength: 1,
+        title: 'Name',
+        description: 'The name of the bundle',
+        examples: ['hello.nrfcloud.com v1.1.1-debug'],
+    })),
+    description: Type.Optional(Type.String({
+        minLength: 1,
+        title: 'Description',
+        description: 'The description of the bundle',
+        examples: ['Firmware Update Image BIN file (thingy91, debug)'],
+    })),
+});
+const FirmwaresType = Type.Object({
+    items: Type.Array(FOTABundle),
+    total: Type.Integer({
+        minimum: 0,
+        description: 'Reflects the total results returned by the query, which may be less than the total number of items available. If the response contains a pageNextToken value, you can supply the pageNextToken in the next request to get more results. The maximum value of total is the page limit of the request, or ten pages if no page limit is provided.',
+    }),
+    pageNextToken: Type.Optional(Type.String({
+        minLength: 1,
+        description: 'Token used to retrieve the next page of items in the list. Present in a response only if the total available results exceeds the specified limit on a page. This token does not change between requests. When supplying as a request parameter, use URL-encoding.',
+    })),
+}, {
+    title: 'Firmware bundles',
+    description: 'Returns the list of firmware bundles. See https://api.nrfcloud.com/v1#tag/Firmware-Bundles/operation/ListFirmware',
+});
+export const getFOTABundles = ({ apiKey, endpoint, }, fetchImplementation) => async () => {
+    const vf = validatedFetch({
+        endpoint,
+        apiKey,
+    }, fetchImplementation);
+    return paginateFirmwares(vf);
+};
+const paginateFirmwares = async (vf, bundles = [], pageNextToken = undefined) => {
+    const query = new URLSearchParams({ pageLimit: '100' });
+    if (pageNextToken !== undefined)
+        query.set('pageNextToken', pageNextToken);
+    const maybeBundles = await vf({
+        resource: `firmwares`,
+        query,
+    }, FirmwaresType);
+    if ('error' in maybeBundles)
+        return maybeBundles;
+    if (maybeBundles.result.pageNextToken !== undefined)
+        return paginateFirmwares(vf, [...bundles, ...maybeBundles.result.items], maybeBundles.result.pageNextToken);
+    return { bundles: [...bundles, ...maybeBundles.result.items] };
+};

package/dist/api/getFOTAJob.d.ts

@@ -1,6 +1,7 @@
 import { type Static } from '@sinclair/typebox';
-import type { ValidationError } from 'ajv';
+import type { ValidationError } from './validatedFetch.js';
 import { FwType } from './devices.js';
+import type { FetchError } from './FetchError.js';
 export declare enum FOTAJobStatus {
     CREATED = "CREATED",
     IN_PROGRESS = "IN_PROGRESS",
@@ -42,7 +43,7 @@ export declare const getFOTAJob: ({ apiKey, endpoint, }: {
 }, fetchImplementation?: typeof fetch) => ({ jobId, }: {
     jobId: string;
 }) => Promise<{
-    error: Error | ValidationError;
+    error: FetchError | ValidationError;
 } | {
     result: Static<typeof FOTAJobType>;
 }>;

package/dist/api/getLocationHistory.d.ts

@@ -1,5 +1,6 @@
 import { type Static } from '@sinclair/typebox';
-import type { ValidationError } from 'ajv';
+import type { ValidationError } from './validatedFetch.js';
+import type { FetchError } from './FetchError.js';
 export declare enum LocationHistoryServiceType {
     ANCHOR = "ANCHOR",
     GNSS = "GNSS",
@@ -39,7 +40,7 @@ export declare const getLocationHistory: ({ apiKey, endpoint, }: {
     start?: Date;
     end?: Date;
 }) => Promise<{
-    error: Error | ValidationError;
+    error: FetchError | ValidationError;
 } | {
     result: Static<typeof LocationHistoryType>;
 }>;

package/dist/api/groundFix.d.ts

@@ -1,5 +1,6 @@
 import { type Static } from '@sinclair/typebox';
 import { type ValidationError } from './validatedFetch.js';
+import type { FetchError } from './FetchError.js';
 export declare const lat: import("@sinclair/typebox").TNumber;
 export declare const lng: import("@sinclair/typebox").TNumber;
 export declare const accuracy: import("@sinclair/typebox").TNumber;
@@ -22,7 +23,7 @@ export declare const groundFix: ({ apiKey, endpoint, }: {
     tac: number;
     rsrp?: number;
 }) => Promise<{
-    error: Error | ValidationError;
+    error: FetchError | ValidationError;
 } | {
     result: Static<typeof GroundFixType>;
 }>;

package/dist/api/index.d.ts

@@ -13,3 +13,5 @@ export * from './groundFix.js';
 export * from './bulkOps.js';
 export * from './createFOTAJob.js';
 export * from './getFOTAJob.js';
+export * from './getFOTABundles.js';
+export * from './FetchError.js';

package/dist/api/index.js

@@ -13,3 +13,5 @@ export * from './groundFix.js';
 export * from './bulkOps.js';
 export * from './createFOTAJob.js';
 export * from './getFOTAJob.js';
+export * from './getFOTABundles.js';
+export * from './FetchError.js';

package/dist/api/serviceToken.d.ts

@@ -1,4 +1,5 @@
 import { type ValidationError } from './validatedFetch.js';
+import type { FetchError } from './FetchError.js';
 /**
  * @link https://api.nrfcloud.com/v1/#tag/Account/operation/GetServiceToken
  */
@@ -9,7 +10,7 @@ export declare const serviceToken: ({ apiKey, endpoint, }: {
     apiKey: string;
     endpoint: URL;
 }, fetchImplementation?: typeof fetch) => (() => Promise<{
-    error: Error | ValidationError;
+    error: FetchError | ValidationError;
 } | {
     token: string;
 }>);

package/dist/api/validatedFetch.d.ts

@@ -1,5 +1,6 @@
 import { type Static, type TObject } from '@sinclair/typebox';
 import type { ValueError } from '@sinclair/typebox/compiler';
+import type { FetchError } from './FetchError.js';
 export declare class ValidationError extends Error {
     errors: ValueError[];
     readonly isValidationError = true;
@@ -19,7 +20,7 @@ export declare const validatedFetch: ({ endpoint, apiKey }: {
 }) & {
     query?: URLSearchParams;
 }, schema: Schema) => Promise<{
-    error: Error | ValidationError;
+    error: FetchError | ValidationError;
 } | {
     result: Static<Schema>;
 }>;

package/dist/api/validatedFetch.js

@@ -1,6 +1,7 @@
 import {} from '@sinclair/typebox';
 import { slashless } from './slashless.js';
 import { validateWithTypeBox } from '@hello.nrfcloud.com/proto';
+import { toFetchError } from './FetchError.js';
 export class ValidationError extends Error {
     errors;
     isValidationError = true;
@@ -21,7 +22,7 @@ const validate = (SchemaObject, data) => {
 const fetchData = (fetchImplementation) => async (...args) => {
     const response = await (fetchImplementation ?? fetch)(...args);
     if (!response.ok)
-        throw new Error(`Error fetching status: ${response.status}`);
+        throw await toFetchError(response);
     return response.json();
 };
 export const validatedFetch = ({ endpoint, apiKey }, fetchImplementation) => async (params, schema) => {

package/dist/api/validatedFetch.spec.js

@@ -2,6 +2,7 @@ import { describe, it, mock } from 'node:test';
 import assert from 'node:assert/strict';
 import { Type } from '@sinclair/typebox';
 import { JSONPayload, validatedFetch } from './validatedFetch.js';
+import { FetchError } from './FetchError.js';
 void describe('validatedFetch()', () => {
     void it('should call an nRF Cloud API endpoint and validate the response', async () => {
         const mockFetch = mock.fn(() => ({
@@ -92,6 +93,22 @@ void describe('validatedFetch()', () => {
             },
         ]);
     });
+    void it('should return an error if the response is not OK', async () => {
+        const mockFetch = mock.fn(() => ({
+            ok: false,
+            status: 400,
+            text: async () => Promise.resolve('Bad Request'),
+            headers: new Map([[`content-length`, 'Bad Request'.length.toString()]]),
+        }));
+        const vf = validatedFetch({
+            endpoint: new URL('https://example.com/'),
+            apiKey: 'some-key',
+        }, mockFetch);
+        const res = await vf({ resource: 'foo' }, Type.Object({}));
+        assert.equal('error' in res, true);
+        assert.equal('result' in res, false);
+        assert.deepEqual('error' in res && res.error, new FetchError(400, 'Bad Request'));
+    });
 });
 void describe('JSONPayload()', () => {
     void it('should convert a an object to a payload definition to be used in validatedFetch', () => assert.deepEqual(JSONPayload({ foo: 'bar' }), {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hello.nrfcloud.com/nrfcloud-api-helpers",
-  "version": "5.0.10",
+  "version": "5.2.0",
   "description": "Helper functions for integrating nRF Cloud APIs in AWS lambdas written in TypeScript.",
   "exports": {
     "./*": {
@@ -32,14 +32,14 @@
   "author": "Nordic Semiconductor ASA | nordicsemi.no",
   "license": "BSD-3-Clause",
   "devDependencies": {
-    "@bifravst/eslint-config-typescript": "6.1.2",
-    "@bifravst/prettier-config": "1.0.2",
+    "@bifravst/eslint-config-typescript": "6.1.3",
+    "@bifravst/prettier-config": "1.0.3",
     "@commitlint/config-conventional": "19.2.2",
     "@types/aws-lambda": "8.10.138",
     "@types/node": "20.14.2",
     "husky": "9.0.11",
     "tsmatchers": "5.0.2",
-    "tsx": "4.15.1"
+    "tsx": "4.15.2"
   },
   "lint-staged": {
     "*.ts": [