@forge/sql 2.2.0-next.1 → 2.2.0-next.3

package/out/__test__/sql.test.js

@@ -4,7 +4,7 @@ const node_fetch_1 = require("node-fetch");
 const api_1 = require("@forge/api");
 const sql_1 = require("../sql");
 const sql_statement_1 = require("../sql-statement");
-const response_handler_1 = require("../utils/response-handler");
+const errors_1 = require("../errors");
 jest.mock('@forge/api');
 describe('SqlClient', () => {
     let sqlClient;
@@ -83,11 +83,19 @@ describe('SqlClient', () => {
             });
             expect(result).toEqual({ rows: [] });
         });
-        it('should handle errors from getResponseBody', async () => {
+        it('should handle invalid JSON body', async () => {
             const responseText = 'Invalid JSON';
             const response = new node_fetch_1.Response(responseText, { status: 200 });
             mockFetch.mockResolvedValue(response);
-            await expect(sqlClient.storageApi('INVALID SQL QUERY')).rejects.toThrow(`Unexpected error. Response was not valid JSON: ${responseText}`);
+            await expect(sqlClient.storageApi('SELECT * from strange;')).rejects.toThrow(`Unexpected error. Response was not valid JSON: ${responseText}`);
+        });
+        it('should throw ForgeSQLAPIError on API error', async () => {
+            const forgeError = { code: 'INVALID_QUERY', message: 'Invalid SQL query' };
+            const mockResponse = new node_fetch_1.Response(JSON.stringify(forgeError), {
+                status: 400
+            });
+            mockFetch.mockResolvedValue(mockResponse);
+            await expect(sqlClient.storageApi('INVALID SQL QUERY')).rejects.toThrow(new errors_1.ForgeSQLAPIError(mockResponse, forgeError));
         });
     });
     describe('prepare', () => {
@@ -112,8 +120,40 @@ describe('SqlClient', () => {
             expect(result).toEqual(mockResult);
         });
         it('should handle API errors', async () => {
-            mockFetch.mockResolvedValue(new node_fetch_1.Response(JSON.stringify({ code: 'INVALID_QUERY', message: 'Invalid SQL query' }), { status: 400 }));
-            await expect(sqlClient.executeRaw('INVALID SQL QUERY')).rejects.toThrow(new response_handler_1.ApiError(400, 'INVALID_QUERY', 'Invalid SQL query'));
+            const forgeError = { code: 'INVALID_QUERY', message: 'Invalid SQL query' };
+            const mockResponse = new node_fetch_1.Response(JSON.stringify(forgeError), {
+                status: 400
+            });
+            mockFetch.mockResolvedValue(mockResponse);
+            await expect(sqlClient.executeRaw('INVALID SQL QUERY')).rejects.toThrow(new errors_1.ForgeSQLAPIError(mockResponse, forgeError));
+        });
+    });
+    describe('_provision', () => {
+        it('should work if the response is a 201', async () => {
+            const mockResponse = new node_fetch_1.Response(JSON.stringify({ success: true }), {
+                status: 201,
+                statusText: 'OK'
+            });
+            mockFetch.mockResolvedValue(mockResponse);
+            await sqlClient._provision();
+            expect(mockFetch).toHaveBeenCalledWith('/api/v1/provision', expect.objectContaining({ method: 'POST' }));
+        });
+        it('should work if the response is a 204', async () => {
+            const mockResponse = new node_fetch_1.Response(undefined, {
+                status: 204,
+                statusText: 'OK'
+            });
+            mockFetch.mockResolvedValue(mockResponse);
+            await sqlClient._provision();
+            expect(mockFetch).toHaveBeenCalledWith('/api/v1/provision', expect.objectContaining({ method: 'POST' }));
+        });
+        it('should throw an error if the response is not 201 or 204', async () => {
+            const mockResponse = new node_fetch_1.Response('Server Error', {
+                status: 500,
+                statusText: 'Bad Request'
+            });
+            mockFetch.mockResolvedValue(mockResponse);
+            await expect(sqlClient._provision()).rejects.toThrow('Unexpected error in provision request');
         });
     });
 });

package/out/errorCodes.d.ts

@@ -1,7 +1,7 @@
 export declare const errorCodes: {
-    SQL_EXECUTION_ERROR: string;
-    INVALID_SQL_QUERY: string;
-    QUERY_TIMED_OUT: string;
-    APP_NOT_ENABLED: string;
+    readonly SQL_EXECUTION_ERROR: "SQL_EXECUTION_ERROR";
+    readonly INVALID_SQL_QUERY: "INVALID_SQL_QUERY";
+    readonly QUERY_TIMED_OUT: "QUERY_TIMED_OUT";
+    readonly APP_NOT_ENABLED: "APP_NOT_ENABLED";
 };
 //# sourceMappingURL=errorCodes.d.ts.map

package/out/errorCodes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errorCodes.d.ts","sourceRoot":"","sources":["../src/errorCodes.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,UAAU;;;;;CAKtB,CAAC"}
+{"version":3,"file":"errorCodes.d.ts","sourceRoot":"","sources":["../src/errorCodes.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,UAAU;;;;;CAUb,CAAC"}

package/out/errors.d.ts

@@ -0,0 +1,39 @@
+import { APIResponse } from '@forge/api';
+export interface ForgeError {
+    code: string;
+    message: string;
+    suggestion?: string;
+    context?: Record<string, unknown>;
+}
+export declare class ForgeSQLError extends Error {
+    constructor(message: string);
+}
+export interface APIErrorResponseDetails extends Pick<APIResponse, 'status' | 'statusText'> {
+    traceId?: string | null;
+}
+export declare class ForgeSQLAPIUnknownError extends ForgeSQLError {
+    code: string;
+    responseText?: string;
+    status: number;
+    statusText: string;
+    traceId?: string | null;
+    constructor(responseDetails: APIErrorResponseDetails, body?: string, message?: string);
+}
+export declare class ForgeSQLAPIError extends ForgeSQLAPIUnknownError {
+    code: string;
+    serverMessage: string;
+    suggestion?: string;
+    context?: Record<string, unknown>;
+    constructor(responseDetails: APIErrorResponseDetails, forgeError: ForgeError, message?: string);
+}
+export declare class MigrationExecutionError extends ForgeSQLError {
+    readonly migrationName: string;
+    readonly migrationsYetToRun: string[];
+    constructor(migrationName: string, migrationsYetToRun: string[]);
+}
+export declare class MigrationCheckPointError extends ForgeSQLError {
+    readonly migrationName: string;
+    readonly migrationsYetToRun: string[];
+    constructor(migrationName: string, migrationsYetToRun: string[]);
+}
+//# sourceMappingURL=errors.d.ts.map

package/out/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAGzC,MAAM,WAAW,UAAU;IAKzB,IAAI,EAAE,MAAM,CAAC;IAGb,OAAO,EAAE,MAAM,CAAC;IAGhB,UAAU,CAAC,EAAE,MAAM,CAAC;IAGpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAGnC;AAGD,qBAAa,aAAc,SAAQ,KAAK;gBAC1B,OAAO,EAAE,MAAM;CAI5B;AAMD,MAAM,WAAW,uBAAwB,SAAQ,IAAI,CAAC,WAAW,EAAE,QAAQ,GAAG,YAAY,CAAC;IAEzF,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAOD,qBAAa,uBAAwB,SAAQ,aAAa;IACxD,IAAI,SAAmB;IAGvB,YAAY,CAAC,EAAE,MAAM,CAAC;IAGtB,MAAM,EAAE,MAAM,CAAC;IAGf,UAAU,EAAE,MAAM,CAAC;IAGnB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;gBAEZ,eAAe,EAAE,uBAAuB,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;CAQtF;AAMD,qBAAa,gBAAiB,SAAQ,uBAAuB;IAK3D,IAAI,EAAE,MAAM,CAAC;IAEb,aAAa,EAAE,MAAM,CAAC;IAEtB,UAAU,CAAC,EAAE,MAAM,CAAC;IAGpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAEtB,eAAe,EAAE,uBAAuB,EAAE,UAAU,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,MAAM;CAU/F;AAED,qBAAa,uBAAwB,SAAQ,aAAa;IAEtD,QAAQ,CAAC,aAAa,EAAE,MAAM;IAC9B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,EAAE;gBAD5B,aAAa,EAAE,MAAM,EACrB,kBAAkB,EAAE,MAAM,EAAE;CAIxC;AAED,qBAAa,wBAAyB,SAAQ,aAAa;IAEvD,QAAQ,CAAC,aAAa,EAAE,MAAM;IAC9B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,EAAE;gBAD5B,aAAa,EAAE,MAAM,EACrB,kBAAkB,EAAE,MAAM,EAAE;CAIxC"}

package/out/errors.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MigrationCheckPointError = exports.MigrationExecutionError = exports.ForgeSQLAPIError = exports.ForgeSQLAPIUnknownError = exports.ForgeSQLError = void 0;
+class ForgeSQLError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ForgeSQLError';
+    }
+}
+exports.ForgeSQLError = ForgeSQLError;
+class ForgeSQLAPIUnknownError extends ForgeSQLError {
+    code = 'UNKNOWN_ERROR';
+    responseText;
+    status;
+    statusText;
+    traceId;
+    constructor(responseDetails, body, message) {
+        super(message || 'Unexpected error in Forge SQL API request');
+        this.code = 'UNKNOWN_ERROR';
+        this.status = responseDetails.status;
+        this.statusText = responseDetails.statusText;
+        this.traceId = responseDetails.traceId;
+        this.responseText = body;
+    }
+}
+exports.ForgeSQLAPIUnknownError = ForgeSQLAPIUnknownError;
+class ForgeSQLAPIError extends ForgeSQLAPIUnknownError {
+    code;
+    serverMessage;
+    suggestion;
+    context;
+    constructor(responseDetails, forgeError, message) {
+        super(responseDetails, undefined, message || forgeError.message);
+        const { code, message: serverMessage, suggestion, context = {}, ...additionalData } = forgeError;
+        this.code = code;
+        this.serverMessage = serverMessage;
+        this.suggestion = suggestion;
+        this.context = { ...context, ...additionalData };
+    }
+}
+exports.ForgeSQLAPIError = ForgeSQLAPIError;
+class MigrationExecutionError extends ForgeSQLError {
+    migrationName;
+    migrationsYetToRun;
+    constructor(migrationName, migrationsYetToRun) {
+        super(`Failed to execute migration with name ${migrationName}`);
+        this.migrationName = migrationName;
+        this.migrationsYetToRun = migrationsYetToRun;
+    }
+}
+exports.MigrationExecutionError = MigrationExecutionError;
+class MigrationCheckPointError extends ForgeSQLError {
+    migrationName;
+    migrationsYetToRun;
+    constructor(migrationName, migrationsYetToRun) {
+        super(`Failed to checkpoint after running migration with name ${migrationName}`);
+        this.migrationName = migrationName;
+        this.migrationsYetToRun = migrationsYetToRun;
+    }
+}
+exports.MigrationCheckPointError = MigrationCheckPointError;

package/out/index.d.ts

@@ -1,8 +1,9 @@
 import { sql } from './sql';
 import { errorCodes } from './errorCodes';
+import { ForgeError, ForgeSQLAPIUnknownError, ForgeSQLAPIError } from './errors';
 import { migrationRunner } from './migration';
 import type { Result, UpdateQueryResponse } from './utils/types';
 export type { Result, UpdateQueryResponse };
-export { errorCodes, migrationRunner, sql };
+export { errorCodes, migrationRunner, sql, ForgeError, ForgeSQLAPIUnknownError, ForgeSQLAPIError };
 export default sql;
 //# sourceMappingURL=index.d.ts.map

package/out/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAC5B,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEjE,YAAY,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;AAE5C,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,GAAG,EAAE,CAAC;AAC5C,eAAe,GAAG,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAC5B,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACjF,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEjE,YAAY,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;AAE5C,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,GAAG,EAAE,UAAU,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,CAAC;AAEnG,eAAe,GAAG,CAAC"}

package/out/index.js

@@ -1,10 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.sql = exports.migrationRunner = exports.errorCodes = void 0;
+exports.ForgeSQLAPIError = exports.ForgeSQLAPIUnknownError = exports.sql = exports.migrationRunner = exports.errorCodes = void 0;
 const sql_1 = require("./sql");
 Object.defineProperty(exports, "sql", { enumerable: true, get: function () { return sql_1.sql; } });
 const errorCodes_1 = require("./errorCodes");
 Object.defineProperty(exports, "errorCodes", { enumerable: true, get: function () { return errorCodes_1.errorCodes; } });
+const errors_1 = require("./errors");
+Object.defineProperty(exports, "ForgeSQLAPIUnknownError", { enumerable: true, get: function () { return errors_1.ForgeSQLAPIUnknownError; } });
+Object.defineProperty(exports, "ForgeSQLAPIError", { enumerable: true, get: function () { return errors_1.ForgeSQLAPIError; } });
 const migration_1 = require("./migration");
 Object.defineProperty(exports, "migrationRunner", { enumerable: true, get: function () { return migration_1.migrationRunner; } });
 exports.default = sql_1.sql;

package/out/migration.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.migrationRunner = exports.MigrationRunner = void 0;
 const sql_1 = require("./sql");
-const response_handler_1 = require("./utils/response-handler");
+const errors_1 = require("./errors");
 const SCHEMA_VERSION_TABLE_CREATE_QUERY = 'CREATE TABLE IF NOT EXISTS __migrations (id BIGINT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(255) NOT NULL, migratedAt TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP);';
 const INSERT_SCHEMA_VERSION_QUERY = 'INSERT INTO __migrations (name) VALUES (?);';
 const LIST_MIGRATIONS_QUERY = 'SELECT id, name, migratedAt FROM __migrations;';
@@ -47,13 +47,13 @@ class MigrationRunner {
                 await this.sqlClient.executeRaw(migration.statement);
             }
             catch (error) {
-                throw new response_handler_1.MigrationExecutionError(migration.name, migrationsToRun.map((m) => m.name));
+                throw new errors_1.MigrationExecutionError(migration.name, migrationsToRun.map((m) => m.name));
             }
             try {
                 await this.sqlClient.prepare(INSERT_SCHEMA_VERSION_QUERY).bindParams(migration.name).execute();
             }
             catch (error) {
-                throw new response_handler_1.MigrationCheckPointError(migration.name, migrationsToRun.map((m) => m.name));
+                throw new errors_1.MigrationCheckPointError(migration.name, migrationsToRun.map((m) => m.name));
             }
             migrationsSuccessfullyRun.push(migration.name);
         }

package/out/sql.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sql.d.ts","sourceRoot":"","sources":["../src/sql.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAY,MAAM,eAAe,CAAC;AAEjD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE9D,qBAAa,SAAS;YACN,WAAW;IAYnB,UAAU,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,GAAE,aAAkB,EAAE,MAAM,SAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAQhH,OAAO,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAI1D,UAAU,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAI9D,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CAMlC;AAED,eAAO,MAAM,GAAG,WAAkB,CAAC"}
+{"version":3,"file":"sql.d.ts","sourceRoot":"","sources":["../src/sql.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAI9D,qBAAa,SAAS;YACN,WAAW;IAYnB,UAAU,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,GAAE,aAAkB,EAAE,MAAM,SAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAiBhH,OAAO,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAI1D,UAAU,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAK9D,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CASlC;AAED,eAAO,MAAM,GAAG,WAAkB,CAAC"}

package/out/sql.js

@@ -2,8 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sql = exports.SqlClient = void 0;
 const api_1 = require("@forge/api");
-const response_handler_1 = require("./utils/response-handler");
 const sql_statement_1 = require("./sql-statement");
+const error_handling_1 = require("./utils/error-handling");
+const errors_1 = require("./errors");
 class SqlClient {
     async sendRequest(path, options) {
         const response = await (0, api_1.__fetchProduct)({ provider: 'app', remote: 'sql' })(path, {
@@ -21,7 +22,14 @@ class SqlClient {
             method: 'POST',
             body: JSON.stringify({ query, params, method })
         });
-        return await (0, response_handler_1.getResponseBody)(response);
+        await (0, error_handling_1.checkResponseError)(response);
+        const responseText = await response.text();
+        try {
+            return JSON.parse(responseText);
+        }
+        catch (error) {
+            throw new errors_1.ForgeSQLError(`Unexpected error. Response was not valid JSON: ${responseText}`);
+        }
     }
     prepare(query) {
         return new sql_statement_1.SqlStatement(query, this.storageApi.bind(this));
@@ -33,7 +41,7 @@ class SqlClient {
         const response = await this.sendRequest('/api/v1/provision', {
             method: 'POST'
         });
-        await (0, response_handler_1.getResponseBody)(response);
+        await (0, error_handling_1.checkResponseError)(response, 'Unexpected error in provision request');
     }
 }
 exports.SqlClient = SqlClient;

package/out/utils/__test__/error-handling.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=error-handling.test.d.ts.map

package/out/utils/__test__/error-handling.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handling.test.d.ts","sourceRoot":"","sources":["../../../src/utils/__test__/error-handling.test.ts"],"names":[],"mappings":""}

package/out/utils/__test__/error-handling.test.js

@@ -0,0 +1,201 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_fetch_1 = require("node-fetch");
+const errors_1 = require("../../errors");
+const error_handling_1 = require("../error-handling");
+describe('errorFromResponse', () => {
+    const traceId = 'trace-id';
+    it('should do nothing if response is ok', async () => {
+        const mockResponse = new node_fetch_1.Response('OK', {
+            status: 200,
+            statusText: 'OK'
+        });
+        await expect((0, error_handling_1.checkResponseError)(mockResponse)).resolves.toBeUndefined();
+    });
+    describe('Forge errors - ForgeSQLAPIError', () => {
+        const message = 'A test error has occurred';
+        const code = 'ERROR_CODE';
+        const suggestion = 'Do something different';
+        it('should return a ForgeSQLAPIError when response body is a Forge error', async () => {
+            const mockResponse = new node_fetch_1.Response(JSON.stringify({ code, message }), {
+                status: 400,
+                statusText: 'Bad Request',
+                headers: { 'x-trace-id': traceId }
+            });
+            try {
+                await (0, error_handling_1.checkResponseError)(mockResponse);
+                throw new Error('Expected error to be thrown');
+            }
+            catch (error) {
+                expect(error).toBeInstanceOf(errors_1.ForgeSQLAPIError);
+                expect(error).toMatchObject({
+                    status: 400,
+                    statusText: 'Bad Request',
+                    traceId,
+                    code,
+                    message,
+                    serverMessage: message
+                });
+            }
+        });
+        it('should include custom message if provided', async () => {
+            const customMessage = 'A custom message';
+            const mockResponse = new node_fetch_1.Response(JSON.stringify({ code, message }), {
+                status: 400,
+                statusText: 'Bad Request',
+                headers: { 'x-trace-id': traceId }
+            });
+            try {
+                await (0, error_handling_1.checkResponseError)(mockResponse, customMessage);
+                throw new Error('Expected error to be thrown');
+            }
+            catch (error) {
+                expect(error).toBeInstanceOf(errors_1.ForgeSQLAPIError);
+                expect(error).toMatchObject({
+                    status: 400,
+                    statusText: 'Bad Request',
+                    traceId,
+                    code,
+                    message: customMessage,
+                    serverMessage: message
+                });
+            }
+        });
+        it('should include context if present in the Forge error', async () => {
+            const context = { key: 'value' };
+            const mockResponse = new node_fetch_1.Response(JSON.stringify({ code, message, context }), {
+                status: 400,
+                statusText: 'Bad Request',
+                headers: { 'x-trace-id': traceId }
+            });
+            try {
+                await (0, error_handling_1.checkResponseError)(mockResponse);
+                throw new Error('Expected error to be thrown');
+            }
+            catch (error) {
+                expect(error).toBeInstanceOf(errors_1.ForgeSQLAPIError);
+                expect(error).toMatchObject({
+                    code,
+                    message,
+                    context,
+                    status: 400,
+                    statusText: 'Bad Request',
+                    traceId
+                });
+            }
+        });
+        it('should include top level additional fields if present in the Forge error', async () => {
+            const extraFields = { extraValue: 'value', debug: true };
+            const mockResponse = new node_fetch_1.Response(JSON.stringify({ code, message, ...extraFields }), {
+                status: 400,
+                statusText: 'Bad Request',
+                headers: { 'x-trace-id': traceId }
+            });
+            try {
+                await (0, error_handling_1.checkResponseError)(mockResponse);
+                throw new Error('Expected error to be thrown');
+            }
+            catch (error) {
+                expect(error).toBeInstanceOf(errors_1.ForgeSQLAPIError);
+                expect(error).toMatchObject({
+                    code,
+                    message,
+                    context: extraFields,
+                    status: 400,
+                    statusText: 'Bad Request',
+                    traceId
+                });
+            }
+        });
+        it('should merge context and additional top level fields if both present in the Forge error', async () => {
+            const context = { key: 'value' };
+            const extraFields = { extraValue: 'value', debug: true };
+            const mockResponse = new node_fetch_1.Response(JSON.stringify({ code, message, context, ...extraFields }), {
+                status: 400,
+                statusText: 'Bad Request',
+                headers: { 'x-trace-id': traceId }
+            });
+            try {
+                await (0, error_handling_1.checkResponseError)(mockResponse);
+                throw new Error('Expected error to be thrown');
+            }
+            catch (error) {
+                expect(error).toBeInstanceOf(errors_1.ForgeSQLAPIError);
+                expect(error).toMatchObject({
+                    code,
+                    message,
+                    context: { ...context, ...extraFields },
+                    status: 400,
+                    statusText: 'Bad Request',
+                    traceId
+                });
+            }
+        });
+        it('should include suggestion if present in the Forge error', async () => {
+            const mockResponse = new node_fetch_1.Response(JSON.stringify({ code, message, suggestion }), {
+                status: 400,
+                statusText: 'Bad Request',
+                headers: { 'x-trace-id': traceId }
+            });
+            try {
+                await (0, error_handling_1.checkResponseError)(mockResponse);
+                throw new Error('Expected error to be thrown');
+            }
+            catch (error) {
+                expect(error).toBeInstanceOf(errors_1.ForgeSQLAPIError);
+                expect(error).toMatchObject({
+                    code,
+                    message,
+                    suggestion,
+                    status: 400,
+                    statusText: 'Bad Request',
+                    traceId
+                });
+            }
+        });
+    });
+    describe('Unknown or not forge errors - ForgeSQLAPIUnknownError', () => {
+        it('returns an ForgeSQLAPIUnknownError when no response body', async () => {
+            const mockResponse = new node_fetch_1.Response(undefined, {
+                status: 404,
+                statusText: 'Not Found',
+                headers: { 'x-trace-id': traceId }
+            });
+            try {
+                await (0, error_handling_1.checkResponseError)(mockResponse);
+                throw new Error('Expected error to be thrown');
+            }
+            catch (error) {
+                expect(error).toBeInstanceOf(errors_1.ForgeSQLAPIUnknownError);
+                expect(error).toMatchObject({
+                    code: 'UNKNOWN_ERROR',
+                    status: 404,
+                    statusText: 'Not Found',
+                    traceId
+                });
+            }
+        });
+        it("returns ForgeSQLAPIUnknownError if there is a JSON body that isn't a forge error", async () => {
+            const body = JSON.stringify({ not: 'a forge error' });
+            const mockResponse = new node_fetch_1.Response(body, {
+                status: 500,
+                statusText: 'Internal Server Error',
+                headers: { 'x-trace-id': traceId }
+            });
+            try {
+                await (0, error_handling_1.checkResponseError)(mockResponse);
+                throw new Error('Expected error to be thrown');
+            }
+            catch (error) {
+                expect(error).toBeInstanceOf(errors_1.ForgeSQLAPIUnknownError);
+                expect(error).toMatchObject({
+                    code: 'UNKNOWN_ERROR',
+                    status: 500,
+                    statusText: 'Internal Server Error',
+                    responseText: body,
+                    traceId
+                });
+            }
+        });
+    });
+});

package/out/utils/error-handling.d.ts

@@ -0,0 +1,5 @@
+import { APIResponse } from '@forge/api';
+import { ForgeError } from '../errors';
+export declare function isForgeError(body: unknown): body is ForgeError;
+export declare function checkResponseError(response: APIResponse, message?: string): Promise<void>;
+//# sourceMappingURL=error-handling.d.ts.map

package/out/utils/error-handling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handling.d.ts","sourceRoot":"","sources":["../../src/utils/error-handling.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAA2B,UAAU,EAA6C,MAAM,WAAW,CAAC;AAG3G,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,UAAU,CAO9D;AASD,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgC/F"}

package/out/utils/error-handling.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkResponseError = exports.isForgeError = void 0;
+const errors_1 = require("../errors");
+function isForgeError(body) {
+    if (typeof body === 'object' && body !== null) {
+        if ('code' in body && 'message' in body) {
+            return true;
+        }
+    }
+    return false;
+}
+exports.isForgeError = isForgeError;
+async function checkResponseError(response, message) {
+    if (response.ok) {
+        return;
+    }
+    const responseText = await response.text();
+    const details = {
+        status: response.status,
+        statusText: response.statusText,
+        traceId: response.headers.get('x-trace-id')
+    };
+    try {
+        const parsedBody = JSON.parse(responseText);
+        if (isForgeError(parsedBody)) {
+            throw new errors_1.ForgeSQLAPIError(details, parsedBody, message);
+        }
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+        }
+        else {
+            throw error;
+        }
+    }
+    throw new errors_1.ForgeSQLAPIUnknownError(details, responseText, message);
+}
+exports.checkResponseError = checkResponseError;

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/utils/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,oBAAY,QAAQ,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,QAAQ,CAAC,CAAC;AAGnE,MAAM,WAAW,mBAAmB;IAElC,YAAY,EAAE,MAAM,CAAC;IAErB,UAAU,EAAE,MAAM,CAAC;IAEnB,IAAI,EAAE,MAAM,CAAC;IAEb,QAAQ,EAAE,MAAM,CAAC;IAEjB,YAAY,EAAE,MAAM,CAAC;IAErB,aAAa,EAAE,MAAM,CAAC;CACvB;AAWD,MAAM,WAAW,MAAM,CAAC,QAAQ,GAAG,GAAG;IAKpC,IAAI,EAAE,QAAQ,SAAS,mBAAmB,GAAG,mBAAmB,GAAG,QAAQ,EAAE,CAAC;IAM9E,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/utils/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,oBAAY,QAAQ,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,QAAQ,CAAC,CAAC;AAGnE,MAAM,WAAW,mBAAmB;IAElC,YAAY,EAAE,MAAM,CAAC;IAErB,UAAU,EAAE,MAAM,CAAC;IAEnB,IAAI,EAAE,MAAM,CAAC;IAEb,QAAQ,EAAE,MAAM,CAAC;IAEjB,YAAY,EAAE,MAAM,CAAC;IAErB,aAAa,EAAE,MAAM,CAAC;CACvB;AAWD,MAAM,WAAW,MAAM,CAAC,QAAQ,GAAG,GAAG;IAKpC,IAAI,EAAE,QAAQ,SAAS,mBAAmB,GAAG,mBAAmB,GAAG,QAAQ,EAAE,CAAC;IAO9E,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forge/sql",
-  "version": "2.2.0-next.1",
+  "version": "2.2.0-next.3",
   "description": "Forge SQL sdk",
   "author": "Atlassian",
   "license": "UNLICENSED",
@@ -22,6 +22,6 @@
     "jest-when": "^3.6.0"
   },
   "dependencies": {
-    "@forge/api": "^4.0.0"
+    "@forge/api": "^4.1.0-next.0"
   }
 }

package/out/utils/__test__/response-handler.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=response-handler.test.d.ts.map

package/out/utils/__test__/response-handler.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"response-handler.test.d.ts","sourceRoot":"","sources":["../../../src/utils/__test__/response-handler.test.ts"],"names":[],"mappings":""}

package/out/utils/__test__/response-handler.test.js

@@ -1,60 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const response_handler_1 = require("../response-handler");
-describe('getResponseBody', () => {
-    it('should return parsed response when response is ok', async () => {
-        const mockResponse = {
-            text: jest.fn().mockResolvedValue(JSON.stringify({ rows: [] })),
-            ok: true,
-            status: 200
-        };
-        const result = await (0, response_handler_1.getResponseBody)(mockResponse);
-        expect(result).toEqual({ rows: [] });
-    });
-    it('should throw ApiError with parsed error when response is not ok and error JSON is valid', async () => {
-        const mockResponse = {
-            text: jest
-                .fn()
-                .mockResolvedValue(JSON.stringify({ code: 'ERROR_CODE', message: 'Error Title', debug: { info: 'detail' } })),
-            ok: false,
-            status: 400
-        };
-        await expect((0, response_handler_1.getResponseBody)(mockResponse)).rejects.toThrow(response_handler_1.ApiError);
-        await expect((0, response_handler_1.getResponseBody)(mockResponse)).rejects.toMatchObject({
-            status: 400,
-            code: 'ERROR_CODE',
-            message: 'Error Title',
-            debug: { info: 'detail' }
-        });
-    });
-    it('should throw ApiError with UNKNOWN_ERROR when response is not ok and error JSON is invalid', async () => {
-        const mockResponse = {
-            text: jest.fn().mockResolvedValue('Invalid JSON'),
-            ok: false,
-            status: 500
-        };
-        await expect((0, response_handler_1.getResponseBody)(mockResponse)).rejects.toThrow(response_handler_1.ApiError);
-        await expect((0, response_handler_1.getResponseBody)(mockResponse)).rejects.toMatchObject({
-            status: 500,
-            code: 'UNKNOWN_ERROR',
-            message: 'Invalid JSON'
-        });
-    });
-    it('should throw Error when response text is not valid JSON', async () => {
-        const mockResponse = {
-            text: jest.fn().mockResolvedValue('Invalid JSON'),
-            ok: true,
-            status: 200
-        };
-        await expect((0, response_handler_1.getResponseBody)(mockResponse)).rejects.toThrowError(new Error('Unexpected error. Response was not valid JSON: Invalid JSON'));
-    });
-});
-describe('ApiError', () => {
-    it('should create an ApiError with correct properties', () => {
-        const error = new response_handler_1.ApiError(404, 'NOT_FOUND', 'Resource not found');
-        expect(error).toBeInstanceOf(Error);
-        expect(error.status).toBe(404);
-        expect(error.code).toBe('NOT_FOUND');
-        expect(error.message).toBe('Resource not found');
-    });
-});

package/out/utils/response-handler.d.ts

@@ -1,20 +0,0 @@
-import { Response, Result } from './types';
-export declare class ApiError extends Error {
-    readonly status: number;
-    readonly code: string;
-    readonly suggestion?: string | undefined;
-    readonly debug?: any;
-    constructor(status: number, code: string, message: string, suggestion?: string | undefined, debug?: any);
-}
-export declare class MigrationExecutionError extends Error {
-    readonly migrationName: string;
-    readonly migrationsYetToRun: string[];
-    constructor(migrationName: string, migrationsYetToRun: string[]);
-}
-export declare class MigrationCheckPointError extends Error {
-    readonly migrationName: string;
-    readonly migrationsYetToRun: string[];
-    constructor(migrationName: string, migrationsYetToRun: string[]);
-}
-export declare function getResponseBody<DataType>(response: Response): Promise<Result<DataType>>;
-//# sourceMappingURL=response-handler.d.ts.map

package/out/utils/response-handler.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"response-handler.d.ts","sourceRoot":"","sources":["../../src/utils/response-handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAE3C,qBAAa,QAAS,SAAQ,KAAK;IAE/B,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM;IAErB,QAAQ,CAAC,UAAU,CAAC;IACpB,QAAQ,CAAC,KAAK,CAAC;gBAJN,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACN,UAAU,CAAC,oBAAQ,EACnB,KAAK,CAAC,KAAK;CAIvB;AAED,qBAAa,uBAAwB,SAAQ,KAAK;IAE9C,QAAQ,CAAC,aAAa,EAAE,MAAM;IAC9B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,EAAE;gBAD5B,aAAa,EAAE,MAAM,EACrB,kBAAkB,EAAE,MAAM,EAAE;CAIxC;AAED,qBAAa,wBAAyB,SAAQ,KAAK;IAE/C,QAAQ,CAAC,aAAa,EAAE,MAAM;IAC9B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,EAAE;gBAD5B,aAAa,EAAE,MAAM,EACrB,kBAAkB,EAAE,MAAM,EAAE;CAIxC;AAED,wBAAsB,eAAe,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CA2B7F"}

package/out/utils/response-handler.js

@@ -1,61 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getResponseBody = exports.MigrationCheckPointError = exports.MigrationExecutionError = exports.ApiError = void 0;
-class ApiError extends Error {
-    status;
-    code;
-    suggestion;
-    debug;
-    constructor(status, code, message, suggestion, debug) {
-        super(message);
-        this.status = status;
-        this.code = code;
-        this.suggestion = suggestion;
-        this.debug = debug;
-    }
-}
-exports.ApiError = ApiError;
-class MigrationExecutionError extends Error {
-    migrationName;
-    migrationsYetToRun;
-    constructor(migrationName, migrationsYetToRun) {
-        super(`Failed to execute migration with name ${migrationName}`);
-        this.migrationName = migrationName;
-        this.migrationsYetToRun = migrationsYetToRun;
-    }
-}
-exports.MigrationExecutionError = MigrationExecutionError;
-class MigrationCheckPointError extends Error {
-    migrationName;
-    migrationsYetToRun;
-    constructor(migrationName, migrationsYetToRun) {
-        super(`Failed to checkpoint after running migration with name ${migrationName}`);
-        this.migrationName = migrationName;
-        this.migrationsYetToRun = migrationsYetToRun;
-    }
-}
-exports.MigrationCheckPointError = MigrationCheckPointError;
-async function getResponseBody(response) {
-    const responseText = await response.text();
-    if (!response.ok) {
-        try {
-            const parsedError = JSON.parse(responseText);
-            throw new ApiError(response.status, parsedError?.code, parsedError?.message, parsedError?.suggestion, parsedError?.debug);
-        }
-        catch (e) {
-            if (!(e instanceof ApiError)) {
-                throw new ApiError(response.status, 'UNKNOWN_ERROR', `${responseText}`);
-            }
-            else {
-                throw e;
-            }
-        }
-    }
-    try {
-        return JSON.parse(responseText);
-    }
-    catch (error) {
-        throw new Error(`Unexpected error. Response was not valid JSON: ${responseText}`);
-    }
-}
-exports.getResponseBody = getResponseBody;