@forge/migrations 0.0.0-experimental-416047f

package/out/migration/migration.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Migration = void 0;
+const tslib_1 = require("tslib");
+const node_fetch_1 = tslib_1.__importDefault(require("node-fetch"));
+const utils_1 = require("./utils");
+class Migration {
+    constructor() {
+        this.basePath = '/app/migration/forge/v1';
+        this.sendProgress = async (transferId, progress) => {
+            const result = await utils_1.invokePOSTApi(`${this.basePath}/progress/${transferId}`, progress);
+            return utils_1.getResponseBody(result);
+        };
+        this.getMappingById = async (transferId, namespace, keys) => {
+            const result = await utils_1.invokePOSTApi(`${this.basePath}/mapping/${transferId}/find?namespace=${namespace}`, keys);
+            return utils_1.getResponseBody(result);
+        };
+        this.getAppDataList = async (transferId) => {
+            const result = await utils_1.invokeGETApi(`${this.basePath}/data/${transferId}/all`);
+            return utils_1.getResponseBody(result);
+        };
+        this.getAppDataPayload = async (s3Key) => {
+            const result = await utils_1.invokeGETApi(`${this.basePath}/data/${s3Key}`);
+            const responseBody = await utils_1.getResponseBody(result);
+            return node_fetch_1.default(responseBody.url);
+        };
+        this.updateFeedback = async (transferId, feedback) => {
+            const result = await utils_1.invokePOSTApi(`${this.basePath}/feedback/${transferId}`, feedback);
+            return utils_1.getResponseBody(result);
+        };
+        this.getMappings = async (transferId, namespace, lastEntity, pageSize) => {
+            let queryParams = `namespace=${namespace}`;
+            if (pageSize != undefined) {
+                queryParams = queryParams + `&pageSize=${pageSize}`;
+            }
+            if (lastEntity != undefined) {
+                queryParams = queryParams + `&lastEntity=${lastEntity}`;
+            }
+            const result = await utils_1.invokeGETApi(`${this.basePath}/mapping/${transferId}/page?${queryParams}`);
+            const mappingResponse = await utils_1.getResponseBody(result);
+            let results = [];
+            if (mappingResponse.items != null) {
+                results = Object.entries(mappingResponse.items).map((item) => {
+                    return { key: item[0], value: item[1] };
+                });
+            }
+            return {
+                results: results,
+                nextCursor: mappingResponse.meta.lastEntity != null ? mappingResponse.meta.lastEntity : undefined
+            };
+        };
+        this.getContainers = async (transferId, containerType, lastEntity, pageSize) => {
+            let queryParams = `containerType=${containerType}`;
+            if (pageSize != undefined) {
+                queryParams = queryParams + `&pageSize=${pageSize}`;
+            }
+            if (lastEntity != undefined) {
+                queryParams = queryParams + `&lastEntity=${lastEntity}`;
+            }
+            const result = await utils_1.invokeGETApi(`${this.basePath}/container/${transferId}/page?${queryParams}`);
+            const containerResponse = await utils_1.getResponseBody(result);
+            let results = [];
+            if (containerResponse.containers != null) {
+                results = Object.entries(containerResponse.containers).map((item) => {
+                    return { key: item[0], value: item[1] };
+                });
+            }
+            return {
+                results: results,
+                nextCursor: containerResponse.meta.lastEntity != null ? containerResponse.meta.lastEntity : undefined
+            };
+        };
+        this.list = async (options, pageSize) => {
+            if (options.namespace != undefined)
+                return this.getMappings(options.transferId, options.namespace, options.cursor, pageSize);
+            else
+                return this.getContainers(options.transferId, options.containerType, options.cursor, pageSize);
+        };
+    }
+}
+exports.Migration = Migration;

package/out/migration/query-api.d.ts

@@ -0,0 +1,11 @@
+import { QueryBuilder, Result, ListOptions, ListResults } from './migration-adaptor';
+import { Migration } from './migration';
+export declare class DefaultQueryBuilder implements QueryBuilder {
+    private migration;
+    private queryOptions;
+    constructor(migration: Pick<Migration, 'list'>, queryOptions: ListOptions);
+    cursor(cursor: string): QueryBuilder;
+    getOne(): Promise<Result | undefined>;
+    getMany(): Promise<ListResults>;
+}
+//# sourceMappingURL=query-api.d.ts.map

package/out/migration/query-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-api.d.ts","sourceRoot":"","sources":["../../src/migration/query-api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACrF,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,qBAAa,mBAAoB,YAAW,YAAY;IAC1C,OAAO,CAAC,SAAS;IAA2B,OAAO,CAAC,YAAY;gBAAxD,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,EAAU,YAAY,EAAE,WAAW;IAEzF,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY;IAO9B,MAAM,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAOrC,OAAO,IAAI,OAAO,CAAC,WAAW,CAAC;CAGtC"}

package/out/migration/query-api.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultQueryBuilder = void 0;
+class DefaultQueryBuilder {
+    constructor(migration, queryOptions) {
+        this.migration = migration;
+        this.queryOptions = queryOptions;
+    }
+    cursor(cursor) {
+        return new DefaultQueryBuilder(this.migration, Object.assign(Object.assign({}, this.queryOptions), { cursor }));
+    }
+    async getOne() {
+        const listResults = await this.migration.list(this.queryOptions, 1);
+        if (listResults.results && listResults.results.length > 0) {
+            return listResults.results[0];
+        }
+    }
+    async getMany() {
+        return this.migration.list(this.queryOptions);
+    }
+}
+exports.DefaultQueryBuilder = DefaultQueryBuilder;

package/out/migration/utils.d.ts

@@ -0,0 +1,5 @@
+import { APIResponse } from '@forge/api';
+export declare function getResponseBody(response: APIResponse): Promise<any>;
+export declare function invokePOSTApi(url: string, payload: any): Promise<APIResponse>;
+export declare function invokeGETApi(url: string): Promise<APIResponse>;
+//# sourceMappingURL=utils.d.ts.map

package/out/migration/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/migration/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAGzC,wBAAsB,eAAe,CAAC,QAAQ,EAAE,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,CAazE;AAED,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,GAAG,OAAO,CAAC,WAAW,CAAC,CAQnF;AAED,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAEpE"}

package/out/migration/utils.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.invokeGETApi = exports.invokePOSTApi = exports.getResponseBody = void 0;
+const errors_1 = require("./errors");
+async function getResponseBody(response) {
+    if (response.status !== 200) {
+        throw errors_1.APIError.forStatus(response.status, response.statusText);
+    }
+    const responseText = await response.text();
+    try {
+        if (responseText !== '' && responseText !== undefined) {
+            return JSON.parse(responseText);
+        }
+    }
+    catch (error) {
+        throw errors_1.APIError.forUnexpected(`Response text was not a valid JSON: ${responseText}`);
+    }
+}
+exports.getResponseBody = getResponseBody;
+async function invokePOSTApi(url, payload) {
+    return global.api.asApp().__requestAtlassian(url, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json'
+        },
+        body: JSON.stringify(payload)
+    });
+}
+exports.invokePOSTApi = invokePOSTApi;
+async function invokeGETApi(url) {
+    return global.api.asApp().__requestAtlassian(url);
+}
+exports.invokeGETApi = invokeGETApi;

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@forge/migrations",
+  "version": "0.0.0-experimental-416047f",
+  "description": "App migration methods for Forge app",
+  "main": "out/index.js",
+  "scripts": {
+    "build": "yarn run clean && yarn run compile",
+    "clean": "rm -rf ./out && rm -f tsconfig.tsbuildinfo",
+    "compile": "tsc -b -v"
+  },
+  "author": "Atlassian",
+  "license": "UNLICENSED",
+  "devDependencies": {
+    "@types/node": "^12.12.63",
+    "@types/node-fetch": "^2.5.7",
+    "node-fetch": "2.6.1"
+  },
+  "dependencies": {
+    "@forge/api": "^2.6.1"
+  }
+}

package/src/__test__/errors.test.ts

@@ -0,0 +1,15 @@
+import { APIError } from '../migration/errors';
+
+describe('APIError', () => {
+  describe('forStatus', () => {
+    it.each([
+      [400, 'Bad request'],
+      [401, 'Unauthorized'],
+      [403, 'Forbidden'],
+      [404, 'Not Found'],
+      [500, 'Internal server error']
+    ] as const)('should contain the correct error message for a code of %s', (status, message) => {
+      expect(APIError.forStatus(status, message).message).toEqual(message);
+    });
+  });
+});

package/src/__test__/migration.test.ts

@@ -0,0 +1,243 @@
+import { APIError } from '../migration/errors';
+import { migration } from '../migration';
+import { Progress } from '../migration/migration-adaptor';
+import { when } from 'jest-when';
+import fetch, { Response } from 'node-fetch';
+import { mocked } from 'ts-jest/utils';
+
+let transferId: string;
+let invalidTransferId: string;
+let progress: Progress;
+let keys: string[];
+let invalidKeys: string[];
+let namespace: string;
+let mappingByKeyResponseWithKeys: string;
+let mappingByKeyResponseWithInvalidKeys: string;
+let s3Key: string;
+let invalidS3Key: string;
+let feedbackPayload: object;
+let appDataListResponse: string;
+let appDataPayloadResponse: string;
+jest.mock('node-fetch');
+
+describe('migration', () => {
+  beforeAll(() => {
+    (global as any).api = {
+      asApp: jest.fn().mockReturnValue({
+        __requestAtlassian: jest.fn()
+      })
+    };
+    transferId = '521ee36a-b673-3dc6-b60b-12460332c200';
+    invalidTransferId = '521ee36a-b673-3dc6-b60b-12460332c001';
+  });
+
+  describe('sendMigrationProgress', () => {
+    beforeAll(() => {
+      progress = { status: 'IN_PROGRESS', percent: 10, message: 'reporting' };
+      when((global as any).api.asApp().__requestAtlassian)
+        .calledWith(`/app/migration/forge/v1/progress/${transferId}`, {
+          method: 'POST',
+          headers: {
+            'content-type': 'application/json'
+          },
+          body: JSON.stringify(progress)
+        })
+        .mockReturnValue({
+          status: 200,
+          text: jest.fn().mockImplementationOnce(() => Promise.resolve()),
+          json: jest.fn().mockImplementationOnce(() => Promise.resolve())
+        })
+        .calledWith(`/app/migration/forge/v1/progress/${invalidTransferId}`, {
+          method: 'POST',
+          headers: {
+            'content-type': 'application/json'
+          },
+          body: JSON.stringify(progress)
+        })
+        .mockReturnValue({
+          status: 403,
+          statusText: 'Forbidden'
+        });
+    });
+
+    it('should update progress when sendProgress method called with valid transferId', async () => {
+      const returnedValue = migration.sendProgress(transferId, progress);
+      await expect(returnedValue).resolves.toBeUndefined();
+    });
+
+    it('should return 403 when sendProgress method called with invalid transferId', async () => {
+      const returnedValue = migration.sendProgress(invalidTransferId, progress);
+      await expect(returnedValue).rejects.toThrow(APIError.forStatus(403, 'Forbidden'));
+    });
+  });
+
+  describe('getMappingById', () => {
+    beforeAll(() => {
+      keys = ['email/abc@example.com', 'email/admin@example.com'];
+      invalidKeys = ['email/abc@example.com', 'email/admin@example'];
+      namespace = 'identity:user';
+      mappingByKeyResponseWithKeys =
+        '{"email/abc@example.com":"5a20a4d7c6bd4a32df3a711","email/admin@example.com":"5a29c4ae20cfc31b0dc0e112"}';
+      mappingByKeyResponseWithInvalidKeys = '{"email/abc@example.com":"5a20a4d7c6bd4a32df3a711"}';
+
+      when((global as any).api.asApp().__requestAtlassian)
+        .calledWith(`/app/migration/forge/v1/mapping/${transferId}/find?namespace=${namespace}`, {
+          method: 'POST',
+          headers: {
+            'content-type': 'application/json'
+          },
+          body: JSON.stringify(keys)
+        })
+        .mockReturnValue({
+          status: 200,
+          text: jest.fn().mockResolvedValue(mappingByKeyResponseWithKeys),
+          json: jest.fn().mockResolvedValue(JSON.parse(mappingByKeyResponseWithKeys))
+        })
+        .calledWith(`/app/migration/forge/v1/mapping/${transferId}/find?namespace=${namespace}`, {
+          method: 'POST',
+          headers: {
+            'content-type': 'application/json'
+          },
+          body: JSON.stringify(invalidKeys)
+        })
+        .mockReturnValue({
+          status: 200,
+          text: jest.fn().mockResolvedValue(mappingByKeyResponseWithInvalidKeys),
+          json: jest.fn().mockResolvedValue(JSON.parse(mappingByKeyResponseWithInvalidKeys))
+        })
+        .calledWith(`/app/migration/forge/v1/mapping/${invalidTransferId}/find?namespace=${namespace}`, {
+          method: 'POST',
+          headers: {
+            'content-type': 'application/json'
+          },
+          body: JSON.stringify(keys)
+        })
+        .mockReturnValue({
+          status: 403,
+          statusText: 'Forbidden'
+        });
+    });
+
+    it('should return MappingResponse when getMappingById method called with valid transferId', async () => {
+      const returnedValue = await migration.getMappingById(transferId, namespace, keys);
+      expect(JSON.stringify(returnedValue)).toEqual(mappingByKeyResponseWithKeys);
+    });
+
+    it('should return 403 when getMappingById method called with invalid transferId', async () => {
+      const returnedValue = migration.getMappingById(invalidTransferId, namespace, keys);
+      await expect(returnedValue).rejects.toThrow(APIError.forStatus(403, 'Forbidden'));
+    });
+
+    it('should return MappingResponse except for invalid keys when getMappingById method called with valid transferId', async () => {
+      const returnedValue = await migration.getMappingById(transferId, namespace, invalidKeys);
+      expect(JSON.stringify(returnedValue)).toEqual(mappingByKeyResponseWithInvalidKeys);
+    });
+  });
+
+  describe('getAppDataList', () => {
+    beforeAll(() => {
+      appDataListResponse =
+        '[{"s3Key":"2ea231e3-ab0d-4236-97f7-26f951df1c11","label":null},{"s3Key":"317a3631-2fef-4940-a418-7096e971eb11","label":null}]';
+
+      when((global as any).api.asApp().__requestAtlassian)
+        .calledWith(`/app/migration/forge/v1/data/${transferId}/all`)
+        .mockReturnValue({
+          status: 200,
+          text: jest.fn().mockResolvedValue(appDataListResponse),
+          json: jest.fn().mockResolvedValue(JSON.parse(appDataListResponse))
+        })
+        .calledWith(`/app/migration/forge/v1/data/${invalidTransferId}/all`)
+        .mockReturnValue({
+          status: 403,
+          statusText: 'Forbidden'
+        });
+    });
+
+    it('should return AppDataListResponse when getAppDataList method called with valid transferId', async () => {
+      const returnedValue = await migration.getAppDataList(transferId);
+      expect(returnedValue).toEqual(JSON.parse(appDataListResponse));
+    });
+
+    it('should return 403 when getAppDataList method called with invalid transferId', async () => {
+      const returnedValue = migration.getAppDataList(invalidTransferId);
+      await expect(returnedValue).rejects.toThrow(APIError.forStatus(403, 'Forbidden'));
+    });
+  });
+
+  describe('getAppDataPayload', () => {
+    beforeAll(() => {
+      s3Key = '7941b65d-094b-4305-97f2-e2b412c6db0a';
+      invalidS3Key = '7941b65d-094b-4305-97f2-e2b412c000';
+      appDataPayloadResponse = '{ "url": "https://rps--stg-east--app-migration-service--ams.s3.amazonaws.com/test"}';
+
+      mocked(fetch).mockImplementation(() =>
+        Promise.resolve({
+          text: () => Promise.resolve('Sample app data')
+        } as Response)
+      );
+
+      when((global as any).api.asApp().__requestAtlassian)
+        .calledWith(`/app/migration/forge/v1/data/${s3Key}`)
+        .mockReturnValue({
+          status: 200,
+          text: jest.fn().mockResolvedValue(JSON.stringify(appDataPayloadResponse)),
+          json: jest.fn().mockResolvedValue(JSON.parse(appDataPayloadResponse))
+        })
+        .calledWith(`/app/migration/forge/v1/data/${invalidS3Key}`)
+        .mockReturnValue({
+          status: 403,
+          statusText: 'Forbidden'
+        });
+    });
+
+    it('should return Response when getAppDataPayload method called with valid S3Key', async () => {
+      const returnedValue = await migration.getAppDataPayload(s3Key);
+      await expect(returnedValue.text()).resolves.toBe('Sample app data');
+    });
+
+    it('should return 403 when getAppDataPayload method called with invalid S3Key', async () => {
+      const returnedValue = migration.getAppDataPayload(invalidS3Key);
+      await expect(returnedValue).rejects.toThrow(APIError.forStatus(403, 'Forbidden'));
+    });
+  });
+
+  describe('updateFeedback', () => {
+    beforeAll(() => {
+      feedbackPayload = { transferId: transferId, msg: 'Current Data processed, send next' };
+      when((global as any).api.asApp().__requestAtlassian)
+        .calledWith(`/app/migration/forge/v1/feedback/${transferId}`, {
+          method: 'POST',
+          headers: {
+            'content-type': 'application/json'
+          },
+          body: JSON.stringify(feedbackPayload)
+        })
+        .mockReturnValue({
+          status: 200,
+          text: jest.fn().mockImplementationOnce(() => Promise.resolve()),
+          json: jest.fn().mockImplementationOnce(() => Promise.resolve())
+        })
+        .calledWith(`/app/migration/forge/v1/feedback/${invalidTransferId}`, {
+          method: 'POST',
+          headers: {
+            'content-type': 'application/json'
+          },
+          body: JSON.stringify(feedbackPayload)
+        })
+        .mockReturnValue({
+          status: 403,
+          statusText: 'Forbidden'
+        });
+    });
+
+    it('should send feedback when updateFeedback method called with valid transferId', async () => {
+      const returnedValue = migration.updateFeedback(transferId, feedbackPayload);
+      await expect(returnedValue).resolves.toBeUndefined();
+    });
+
+    it('should return 403 when updateFeedback method called with invalid transferId', async () => {
+      const returnedValue = migration.updateFeedback(invalidTransferId, feedbackPayload);
+      await expect(returnedValue).rejects.toThrow(APIError.forStatus(403, 'Forbidden'));
+    });
+  });
+});

package/src/__test__/query-api.test.ts

@@ -0,0 +1,177 @@
+import { ListResults, Result } from '../migration/migration-adaptor';
+import { when } from 'jest-when';
+import { migration } from '../migration';
+
+describe('QueryApi', () => {
+  const transferId = '521ee36a-b673-3dc6-b60b-12460332c200';
+
+  (global as any).api = {
+    asApp: jest.fn().mockReturnValue({
+      __requestAtlassian: jest.fn()
+    })
+  };
+
+  describe('getMappings', () => {
+    let expectedMappingsResultMany: ListResults;
+    let expectedMappingsResultManyWithCursor: ListResults;
+    let expectedMappingsResultSingle: Result;
+    let lastEntityId: string;
+
+    beforeAll(() => {
+      lastEntityId = 'base64:ZW1haWwvYWRtaW5AZXhhbXBsZS5jb20vNg';
+      const mappingsResponse = `{"meta":{"pageSize":5000,"hasNext":false,"lastEntity":"${lastEntityId}"},"items":{"email/admin@example.com":"5a29c4ae20cfc31b0dc0eafe","confluence.userkey/2c9682714db22c7c014db22f51970002":"5a29c4ae20cfc31b0dc0eafe"}}`;
+
+      const mappingsResponseWithoutLastEntity =
+        '{"meta":{"pageSize":5000,"hasNext":false,"lastEntity":null},"items":{"email/admin@example.com":"5a29c4ae20cfc31b0dc0eafe","confluence.userkey/2c9682714db22c7c014db22f51970002":"5a29c4ae20cfc31b0dc0eafe"}}';
+
+      const valueObject = '5a29c4ae20cfc31b0dc0eafe' as any;
+      when((global as any).api.asApp().__requestAtlassian)
+        .calledWith(
+          `/app/migration/forge/v1/mapping/${transferId}/page?namespace=identity:user&lastEntity=${lastEntityId}`
+        )
+        .mockReturnValue({
+          status: 200,
+          text: jest.fn().mockResolvedValue(mappingsResponseWithoutLastEntity),
+          json: jest.fn().mockResolvedValue(JSON.parse(mappingsResponseWithoutLastEntity))
+        })
+        .calledWith(`/app/migration/forge/v1/mapping/${transferId}/page?namespace=identity:user`)
+        .mockReturnValue({
+          status: 200,
+          text: jest.fn().mockResolvedValue(mappingsResponse),
+          json: jest.fn().mockResolvedValue(JSON.parse(mappingsResponse))
+        })
+        .calledWith(`/app/migration/forge/v1/mapping/${transferId}/page?namespace=identity:user&pageSize=1`)
+        .mockReturnValue({
+          status: 200,
+          text: jest.fn().mockResolvedValue(mappingsResponse),
+          json: jest.fn().mockResolvedValue(JSON.parse(mappingsResponse))
+        })
+        .calledWith(
+          `/app/migration/forge/v1/mapping/${transferId}/page?namespace=identity:user&pageSize=1&lastEntity=${lastEntityId}`
+        )
+        .mockReturnValue({
+          status: 200,
+          text: jest.fn().mockResolvedValue(mappingsResponse),
+          json: jest.fn().mockResolvedValue(JSON.parse(mappingsResponse))
+        });
+
+      expectedMappingsResultMany = {
+        results: [
+          {
+            key: 'email/admin@example.com',
+            value: valueObject
+          },
+          { key: 'confluence.userkey/2c9682714db22c7c014db22f51970002', value: valueObject }
+        ],
+        nextCursor: undefined
+      };
+
+      expectedMappingsResultManyWithCursor = {
+        results: [
+          { key: 'email/admin@example.com', value: valueObject },
+          { key: 'confluence.userkey/2c9682714db22c7c014db22f51970002', value: valueObject }
+        ],
+        nextCursor: lastEntityId
+      };
+      expectedMappingsResultSingle = { key: 'email/admin@example.com', value: valueObject };
+    });
+
+    it('should fetch multiple values for getMappings', async () => {
+      const results = await migration.getMappings(transferId, 'identity:user').getMany();
+
+      expect(results).toEqual(expectedMappingsResultManyWithCursor);
+    });
+
+    it('should allow specifying a cursor for getMappings with getMany', async () => {
+      const result = await migration.getMappings(transferId, 'identity:user').cursor(lastEntityId).getMany();
+      expect(result).toEqual(expectedMappingsResultMany);
+    });
+
+    it('get single mapping when getMappings called with getOne', async () => {
+      const result = await migration.getMappings(transferId, 'identity:user').getOne();
+
+      expect(result).toEqual(expectedMappingsResultSingle);
+    });
+
+    it('should allow specifying a cursor for getMappings with getOne', async () => {
+      const result = await migration.getMappings(transferId, 'identity:user').cursor(lastEntityId).getOne();
+
+      expect(result).toEqual(expectedMappingsResultSingle);
+    });
+  });
+
+  describe('getContainers', () => {
+    let expectedResultContainersManyWithCursor: ListResults;
+    let expectedResultContainersManyWithoutCursor: ListResults;
+    let expectedResultContainersSingle: Result;
+    let lastEntityId: string;
+
+    beforeAll(() => {
+      lastEntityId = 'db11c8af-c82b-3569-9a11-f288c9cc9535';
+      const containersResponse = `{"meta":{"pageSize":0,"hasNext":false,"lastEntity":"${lastEntityId}"},"containers":[{ "key": "TES", "sourceId": "884737", "type": "ConfluenceSpace" }]}`;
+
+      const containersResponseWithoutLastEntity =
+        '{"meta":{"pageSize":0,"hasNext":false,"lastEntity":null},"containers":[{ "key": "TES", "sourceId": "884737", "type": "ConfluenceSpace" }]}';
+
+      expectedResultContainersManyWithCursor = {
+        results: [{ key: '0', value: { key: 'TES', sourceId: '884737', type: 'ConfluenceSpace' } }],
+        nextCursor: lastEntityId
+      };
+      expectedResultContainersManyWithoutCursor = {
+        results: [{ key: '0', value: { key: 'TES', sourceId: '884737', type: 'ConfluenceSpace' } }],
+        nextCursor: undefined
+      };
+      expectedResultContainersSingle = { key: '0', value: { key: 'TES', sourceId: '884737', type: 'ConfluenceSpace' } };
+
+      when((global as any).api.asApp().__requestAtlassian)
+        .calledWith(
+          `/app/migration/forge/v1/container/${transferId}/page?containerType=ConfluenceSpace&lastEntity=${lastEntityId}`
+        )
+        .mockReturnValue({
+          status: 200,
+          text: jest.fn().mockResolvedValue(containersResponseWithoutLastEntity),
+          json: jest.fn().mockResolvedValue(JSON.parse(containersResponseWithoutLastEntity))
+        })
+        .calledWith(`/app/migration/forge/v1/container/${transferId}/page?containerType=ConfluenceSpace`)
+        .mockReturnValue({
+          status: 200,
+          text: jest.fn().mockResolvedValue(containersResponse),
+          json: jest.fn().mockResolvedValue(JSON.parse(containersResponse))
+        })
+        .calledWith(`/app/migration/forge/v1/container/${transferId}/page?containerType=ConfluenceSpace&pageSize=1`)
+        .mockReturnValue({
+          status: 200,
+          text: jest.fn().mockResolvedValue(containersResponse),
+          json: jest.fn().mockResolvedValue(JSON.parse(containersResponse))
+        })
+        .calledWith(
+          `/app/migration/forge/v1/container/${transferId}/page?containerType=ConfluenceSpace&pageSize=1&lastEntity=${lastEntityId}`
+        )
+        .mockReturnValue({
+          status: 200,
+          text: jest.fn().mockResolvedValue(containersResponse),
+          json: jest.fn().mockResolvedValue(JSON.parse(containersResponse))
+        });
+    });
+
+    it('should allow specifying a cursor for getContainers with getMany', async () => {
+      const result = await migration.getContainers(transferId, 'ConfluenceSpace').cursor(lastEntityId).getMany();
+      expect(result).toEqual(expectedResultContainersManyWithoutCursor);
+    });
+
+    it('should fetch multiple values when getContainers is called with getMany', async () => {
+      const result = await migration.getContainers(transferId, 'ConfluenceSpace').getMany();
+      expect(result).toEqual(expectedResultContainersManyWithCursor);
+    });
+
+    it('should allow specifying a cursor for getContainers with getOne', async () => {
+      const result = await migration.getContainers(transferId, 'ConfluenceSpace').cursor(lastEntityId).getOne();
+      expect(result).toEqual(expectedResultContainersSingle);
+    });
+
+    it('get single mapping when getContainers called with getOne', async () => {
+      const result = await migration.getContainers(transferId, 'ConfluenceSpace').getOne();
+      expect(result).toEqual(expectedResultContainersSingle);
+    });
+  });
+});

package/src/index.ts

@@ -0,0 +1,3 @@
+import { migration } from './migration';
+
+export { migration };

package/src/migration/errors.ts

@@ -0,0 +1,13 @@
+export class APIError extends Error {
+  private constructor(message: string) {
+    super(message);
+  }
+
+  public static forStatus(status: number, message: string): APIError {
+    return new APIError(message);
+  }
+
+  public static forUnexpected(message: string): APIError {
+    return new APIError(message);
+  }
+}