@canva/error 1.2.0 → 2.1.0

package/index.d.ts

@@ -5,15 +5,18 @@ declare interface BaseCanvaError extends Error {
 
 /**
  * @public
- * Base Error thrown by Apps SDK methods
+ * An error thrown by the Apps SDK.
  */
 export declare const CanvaError: typeof CanvaErrorClass;
 
 /**
  * @public
- * Base Error thrown by Apps SDK methods
+ * An error thrown by the Apps SDK.
  */
 declare class CanvaErrorClass extends Error implements BaseCanvaError {
+  /**
+   * A code that identifies why the error was thrown.
+   */
   readonly code: ErrorCode;
 
   constructor(opts: { code: ErrorCode; message: string });
@@ -21,57 +24,38 @@ declare class CanvaErrorClass extends Error implements BaseCanvaError {
 
 /**
  * @public
- * Error codes that could be thrown by Apps SDK methods
+ * An error code that identifies why an error was thrown by the Apps SDK.
+ *
+ * @remarks
+ * The possible error codes include:
+ *
+ * - `"bad_external_service_response"` - A response from an external service is invalid or malformed.
+ * - `"bad_request"` - The app made a request with invalid or malformed inputs.
+ * - `"failed_precondition"` - The requested operation can't be performed because a precondition hasn't been met.
+ * - `"internal_error"` - An error occurred within the Apps SDK's internal implementation.
+ * - `"not_found"` - The specified resource couldn't be found.
+ * - `"not_allowed"` - The app isn't allowed to perform the requested operation.
+ * - `"permission_denied"` - The app isn't allowed perform the requested operation because the appropriate permissions aren't set.
+ * - `"quota_exceeded"` - The app or user has exceeded their allocated quota for a resource or service.
+ * - `"rate_limited"` - The app attempted too many operations within a certain period of time.
+ * - `"timeout"` - The requested operation took too long to complete.
+ * - `"unsupported_surface"` - The requested operation isn't supported on the current surface.
+ * - `"unsupported_page_type"` - The requested operation isn't supported on the current page.
+ * - `"user_offline"` - The requested operation can't be performed because the user is offline.
  */
 export declare type ErrorCode =
-  /**
-   * The system is currently unable to perform the requested operation because it is not in the necessary state.
-   * Refer to the error message for more information on how to satisfy the failed precondition.
-   */
-  | "FAILED_PRECONDITION"
-  /**
-   * The response received from an external service is invalid or malformed.
-   */
-  | "BAD_EXTERNAL_SERVICE_RESPONSE"
-  /**
-   * The request received from the client is invalid or malformed.
-   */
-  | "BAD_REQUEST"
-  /**
-   * An error occurred within the SDK's internal implementation.
-   */
-  | "INTERNAL_ERROR"
-  /**
-   * The allocated quota for the resource or service has been exceeded.
-   */
-  | "QUOTA_EXCEEDED"
-  /**
-   * The system has received too many requests in a short period of time.
-   */
-  | "RATE_LIMITED"
-  /**
-   * The caller does not have sufficient permissions to execute the specified operation.
-   */
-  | "PERMISSION_DENIED"
-  /**
-   * The specified operation is not supported on the surface.
-   */
-  | "UNSUPPORTED_SURFACE"
-  /**
-   * The user is currently offline and cannot perform the requested operation.
-   */
-  | "USER_OFFLINE"
-  /**
-   * The specified resource was not found
-   */
-  | "NOT_FOUND"
-  /**
-   * The specified operation was not allowed
-   */
-  | "NOT_ALLOWED"
-  /**
-   * The operation exceeded the maximum allowed time to complete.
-   */
-  | "TIMEOUT";
+  | "bad_external_service_response"
+  | "bad_request"
+  | "failed_precondition"
+  | "internal_error"
+  | "not_found"
+  | "not_allowed"
+  | "permission_denied"
+  | "quota_exceeded"
+  | "rate_limited"
+  | "timeout"
+  | "unsupported_surface"
+  | "unsupported_page_type"
+  | "user_offline";
 
 export {};

package/lib/cjs/sdk/error/fake/fake_canva_error.js

@@ -0,0 +1,19 @@
+"use strict"
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "FakeCanvaError", {
+    enumerable: true,
+    get: function() {
+        return FakeCanvaError;
+    }
+});
+class FakeCanvaError extends Error {
+    constructor(opts){
+        const message = `Fake mode error - [${opts.code}]:  ${opts.message}`;
+        super(message);
+        this.name = 'FakeCanvaError';
+        this.rawMessage = opts.message;
+        this.code = opts.code;
+    }
+}

package/lib/cjs/sdk/error/fake/inject.js

@@ -0,0 +1,20 @@
+"use strict"
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "injectError", {
+    enumerable: true,
+    get: function() {
+        return injectError;
+    }
+});
+const _fake_canva_error = require("./fake_canva_error");
+function injectError() {
+    return {
+        error: {
+            v2: {
+                CanvaError: _fake_canva_error.FakeCanvaError
+            }
+        }
+    };
+}

package/lib/cjs/sdk/error/index.js

@@ -1,5 +1,4 @@
-// must use relative paths
-"use strict";
+"use strict"
 Object.defineProperty(exports, "__esModule", {
     value: true
 });
@@ -17,5 +16,6 @@ function _export_star(from, to) {
     });
     return from;
 }
- // purposefully not exporting `BaseCanvaError` from '../.../api/error/api' since we want to export
- // the actual CanvaError class, and not the interface, to allow apps to do instanceof checks
+var _window___canva___sdkRegistration, _window___canva__;
+(_window___canva__ =
+window.__canva__) === null || _window___canva__ === void 0 ? void 0 : (_window___canva___sdkRegistration = _window___canva__.sdkRegistration) === null || _window___canva___sdkRegistration === void 0 ? void 0 : _window___canva___sdkRegistration.registerPackageVersion('error', '2.1.0', 'ga');

package/lib/cjs/sdk/error/public.js

@@ -8,5 +8,5 @@ Object.defineProperty(exports, "CanvaError", {
         return CanvaError;
     }
 });
-const { canva } = window;
-const CanvaError = canva.CanvaError;
+const { canva_sdk } = window;
+const CanvaError = canva_sdk.error.v2.CanvaError;

package/lib/cjs/sdk/error/test/index.js

@@ -0,0 +1,16 @@
+"use strict"
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "initTestEnvironment", {
+    enumerable: true,
+    get: function() {
+        return initTestEnvironment;
+    }
+});
+const _inject = require('../fake/inject');
+const _canva_sdk = require('../../utils/canva_sdk');
+function initTestEnvironment() {
+    (0, _canva_sdk.assertIsTestCanvaSdk)();
+    (0, _canva_sdk.injectFakeAPIClients)((0, _inject.injectError)());
+}

package/lib/cjs/sdk/utils/canva_sdk.js

@@ -0,0 +1,41 @@
+"use strict"
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: all[name]
+    });
+}
+_export(exports, {
+    getCanvaSdk: function() {
+        return getCanvaSdk;
+    },
+    assertIsTestCanvaSdk: function() {
+        return assertIsTestCanvaSdk;
+    },
+    injectFakeAPIClients: function() {
+        return injectFakeAPIClients;
+    }
+});
+function getCanvaSdk() {
+    return window.canva_sdk;
+}
+function assertIsTestCanvaSdk() {
+    var _window___canva__;
+    if ((_window___canva__ = window.__canva__) === null || _window___canva__ === void 0 ? void 0 : _window___canva__.uiKit) {
+        var _getCanvaSdk_error, _getCanvaSdk;
+        const CanvaError = (_getCanvaSdk = getCanvaSdk()) === null || _getCanvaSdk === void 0 ? void 0 : (_getCanvaSdk_error = _getCanvaSdk.error) === null || _getCanvaSdk_error === void 0 ? void 0 : _getCanvaSdk_error.v2.CanvaError;
+        throw new CanvaError({
+            code: 'failed_precondition',
+            message: "Canva App SDK: You're attempting to call `initTestEnvironment` in a non-test environment, such as in production. This method should be called in test environments, once and only once. For more info refer to https://canva.dev/docs/apps/testing/"
+        });
+    }
+}
+function injectFakeAPIClients(clients) {
+    window.canva_sdk = {
+        ...getCanvaSdk(),
+        ...clients
+    };
+}

package/lib/esm/sdk/error/fake/fake_canva_error.js

@@ -0,0 +1,9 @@
+export class FakeCanvaError extends Error {
+    constructor(opts){
+        const message = `Fake mode error - [${opts.code}]:  ${opts.message}`;
+        super(message);
+        this.name = 'FakeCanvaError';
+        this.rawMessage = opts.message;
+        this.code = opts.code;
+    }
+}

package/lib/esm/sdk/error/fake/inject.js

@@ -0,0 +1,10 @@
+import { FakeCanvaError } from './fake_canva_error';
+export function injectError() {
+    return {
+        error: {
+            v2: {
+                CanvaError: FakeCanvaError
+            }
+        }
+    };
+}

package/lib/esm/sdk/error/index.js

@@ -1,3 +1,4 @@
-// must use relative paths
-export * from './public'; // purposefully not exporting `BaseCanvaError` from '../.../api/error/api' since we want to export
- // the actual CanvaError class, and not the interface, to allow apps to do instanceof checks
+var _window___canva___sdkRegistration, _window___canva__;
+export * from './public';
+(_window___canva__ =
+window.__canva__) === null || _window___canva__ === void 0 ? void 0 : (_window___canva___sdkRegistration = _window___canva__.sdkRegistration) === null || _window___canva___sdkRegistration === void 0 ? void 0 : _window___canva___sdkRegistration.registerPackageVersion('error', '2.1.0', 'ga');

package/lib/esm/sdk/error/public.js

@@ -1,5 +1,2 @@
-const { canva } = window;
-/**
- * @public
- * Base Error thrown by Apps SDK methods
- */ export const CanvaError = canva.CanvaError;
+const { canva_sdk } = window;
+export const CanvaError = canva_sdk.error.v2.CanvaError;

package/lib/esm/sdk/error/test/index.js

@@ -0,0 +1,6 @@
+import { injectError } from '../fake/inject';
+import { assertIsTestCanvaSdk, injectFakeAPIClients } from '../../utils/canva_sdk';
+export function initTestEnvironment() {
+    assertIsTestCanvaSdk();
+    injectFakeAPIClients(injectError());
+}

package/lib/esm/sdk/utils/canva_sdk.js

@@ -0,0 +1,20 @@
+export function getCanvaSdk() {
+    return window.canva_sdk;
+}
+export function assertIsTestCanvaSdk() {
+    var _window___canva__;
+    if ((_window___canva__ = window.__canva__) === null || _window___canva__ === void 0 ? void 0 : _window___canva__.uiKit) {
+        var _getCanvaSdk_error, _getCanvaSdk;
+        const CanvaError = (_getCanvaSdk = getCanvaSdk()) === null || _getCanvaSdk === void 0 ? void 0 : (_getCanvaSdk_error = _getCanvaSdk.error) === null || _getCanvaSdk_error === void 0 ? void 0 : _getCanvaSdk_error.v2.CanvaError;
+        throw new CanvaError({
+            code: 'failed_precondition',
+            message: "Canva App SDK: You're attempting to call `initTestEnvironment` in a non-test environment, such as in production. This method should be called in test environments, once and only once. For more info refer to https://canva.dev/docs/apps/testing/"
+        });
+    }
+}
+export function injectFakeAPIClients(clients) {
+    window.canva_sdk = {
+        ...getCanvaSdk(),
+        ...clients
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canva/error",
-  "version": "1.2.0",
+  "version": "2.1.0",
   "description": "The Canva Apps SDK error library",
   "author": "Canva Pty Ltd.",
   "license": "SEE LICENSE IN LICENSE.md FILE",
@@ -8,14 +8,14 @@
   "module": "./lib/esm/sdk/error/index.js",
   "exports": {
     ".": {
-      "require": {
-        "types": "./index.d.ts",
-        "default": "./lib/cjs/sdk/error/index.js"
-      },
-      "import": {
-        "types": "./index.d.ts",
-        "default": "./lib/esm/sdk/error/index.js"
-      }
+      "types": "./index.d.ts",
+      "require": "./lib/cjs/sdk/error/index.js",
+      "import": "./lib/esm/sdk/error/index.js"
+    },
+    "./test": {
+      "types": "./test/index.d.ts",
+      "require": "./lib/cjs/sdk/error/test/index.js",
+      "import": "./lib/esm/sdk/error/test/index.js"
     }
   },
   "typings": "./index.d.ts"

package/test/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @public
+ * Initializes a test environment for the `@canva/error` package, enabling unit tests to mock Canva's APIs.
+ * @remarks
+ * This method should only be called once in a test environment, such as in a Jest setup file.
+ * @see
+ * https://www.canva.dev/docs/apps/testing/
+ */
+export declare function initTestEnvironment(): void;
+
+export {};