@canva/cli 0.0.1-beta.9 → 1.0.0

package/templates/dam/src/config.ts

@@ -1,95 +1,220 @@
 import type { Config } from "@canva/app-components";
+import { useIntl } from "react-intl";
 
 type ContainerTypes = "folder";
-export const config: Config<ContainerTypes> = {
-  serviceName: "Example App",
-  search: {
-    enabled: true,
-    filterFormConfig: {
-      containerTypes: ["folder"],
-      filters: [
-        {
-          filterType: "CHECKBOX",
-          label: "File Type",
-          key: "fileType",
-          options: [
-            { value: "mp4", label: "MP4" },
-            { value: "png", label: "PNG" },
-            { value: "jpeg", label: "JPEG" },
-          ],
-          allowCustomValue: true,
-        },
-        {
-          filterType: "RADIO",
-          label: "Size",
-          key: "size",
-          options: [
-            {
-              label: "Large (800+ px)",
-              value: "large",
-            },
-            {
-              label: "Medium (200-799px)",
-              value: "medium",
-            },
-          ],
-          allowCustomValue: true,
-          customValueInputType: "SIZE_RANGE",
-        },
-        {
-          filterType: "RADIO",
-          label: "Update Date",
-          key: "updateDate",
-          options: [
-            { value: ">now-30m", label: "Last 30 Minutes" },
-            { value: ">now-7d", label: "Last 7 days" },
-          ],
-          allowCustomValue: true,
-          customValueInputType: "DATE_RANGE",
-        },
-        {
-          filterType: "RADIO",
-          label: "Design Status",
-          key: "designStatus",
-          options: [
-            { value: "approved", label: "Approved" },
-            { value: "rejected", label: "Rejected" },
-            { value: "draft", label: "Draft" },
-          ],
-          allowCustomValue: true,
-          customValueInputType: "PLAIN_TEXT",
-        },
-      ],
+export const useConfig = (): Config<ContainerTypes> => {
+  const intl = useIntl();
+  return {
+    serviceName: intl.formatMessage({
+      defaultMessage: "Example App",
+      description:
+        "Name of the service where the app will pull digital assets from",
+    }),
+    search: {
+      enabled: true,
+      filterFormConfig: {
+        containerTypes: ["folder"],
+        filters: [
+          {
+            filterType: "CHECKBOX",
+            label: intl.formatMessage({
+              defaultMessage: "File Type",
+              description: "Label of filters for file type",
+            }),
+            key: "fileType",
+            // These options do not need to be translated as they are universal technical terms
+            /* eslint-disable formatjs/no-literal-string-in-object */
+            options: [
+              { value: "mp4", label: "MP4" },
+              { value: "png", label: "PNG" },
+              { value: "jpeg", label: "JPEG" },
+            ],
+            /* eslint-enable formatjs/no-literal-string-in-object */
+            allowCustomValue: true,
+          },
+          {
+            filterType: "RADIO",
+            label: intl.formatMessage({
+              defaultMessage: "Size",
+              description: "Label of filters for asset size",
+            }),
+            key: "size",
+            options: [
+              {
+                label: intl.formatMessage({
+                  defaultMessage: "Large (800+ px)",
+                  description: "One of the filter options for asset size",
+                }),
+                value: "large",
+              },
+              {
+                label: intl.formatMessage({
+                  defaultMessage: "Medium (200-799px)",
+                  description: "One of the filter options for asset size",
+                }),
+                value: "medium",
+              },
+            ],
+            allowCustomValue: true,
+            customValueInputType: "SIZE_RANGE",
+          },
+          {
+            filterType: "RADIO",
+            label: intl.formatMessage({
+              defaultMessage: "Update Date",
+              description: "Label of the filters for asset's update date",
+            }),
+            key: "updateDate",
+            options: [
+              {
+                value: ">now-30m",
+                label: intl.formatMessage({
+                  defaultMessage: "Last 30 Minutes",
+                  description:
+                    "One of the filter options for asset update date",
+                }),
+              },
+              {
+                value: ">now-7d",
+                label: intl.formatMessage({
+                  defaultMessage: "Last 7 days",
+                  description:
+                    "One of the filter options for asset update date",
+                }),
+              },
+            ],
+            allowCustomValue: true,
+            customValueInputType: "DATE_RANGE",
+          },
+          {
+            filterType: "RADIO",
+            label: intl.formatMessage({
+              defaultMessage: "Design Status",
+              description: "Label of the filters for asset's design status",
+            }),
+            key: "designStatus",
+            options: [
+              {
+                value: "approved",
+                label: intl.formatMessage({
+                  defaultMessage: "Approved",
+                  description:
+                    "One of the filter options for asset design status",
+                }),
+              },
+              {
+                value: "rejected",
+                label: intl.formatMessage({
+                  defaultMessage: "Rejected",
+                  description:
+                    "One of the filter options for asset design status",
+                }),
+              },
+              {
+                value: "draft",
+                label: intl.formatMessage({
+                  defaultMessage: "Draft",
+                  description:
+                    "One of the filter options for asset design status",
+                }),
+              },
+            ],
+            allowCustomValue: true,
+            customValueInputType: "PLAIN_TEXT",
+          },
+        ],
+      },
     },
-  },
-  containerTypes: [
-    {
-      value: "folder",
-      label: "Folders",
-      listingSurfaces: [
-        { surface: "HOMEPAGE" },
-        {
-          surface: "CONTAINER",
-          parentContainerTypes: ["folder"],
+    containerTypes: [
+      {
+        value: "folder",
+        label: intl.formatMessage({
+          defaultMessage: "Folders",
+          description: "Name of the asset container type",
+        }),
+        listingSurfaces: [
+          { surface: "HOMEPAGE" },
+          {
+            surface: "CONTAINER",
+            parentContainerTypes: ["folder"],
+          },
+          { surface: "SEARCH" },
+        ],
+        searchInsideContainer: {
+          enabled: true,
+          placeholder: intl.formatMessage({
+            defaultMessage: "Search for media inside this folder",
+            description: "Placeholder of a search input box",
+          }),
         },
-        { surface: "SEARCH" },
-      ],
-      searchInsideContainer: {
-        enabled: true,
-        placeholder: "Search for resources inside this folder",
       },
+    ],
+    sortOptions: [
+      {
+        value: "created_at DESC",
+        label: intl.formatMessage({
+          defaultMessage: "Creation date (newest)",
+          description: "One of the sort options",
+        }),
+      },
+      {
+        value: "created_at ASC",
+        label: intl.formatMessage({
+          defaultMessage: "Creation date (oldest)",
+          description: "One of the sort options",
+        }),
+      },
+      {
+        value: "updated_at DESC",
+        label: intl.formatMessage({
+          defaultMessage: "Updated (newest)",
+          description: "One of the sort options",
+        }),
+      },
+      {
+        value: "updated_at ASC",
+        label: intl.formatMessage({
+          defaultMessage: "Updated (oldest)",
+          description: "One of the sort options",
+        }),
+      },
+      {
+        value: "name ASC",
+        label: intl.formatMessage({
+          defaultMessage: "Name (A-Z)",
+          description: "One of the sort options",
+        }),
+      },
+      {
+        value: "name DESC",
+        label: intl.formatMessage({
+          defaultMessage: "Name (Z-A)",
+          description: "One of the sort options",
+        }),
+      },
+    ],
+    layouts: ["MASONRY", "LIST"],
+    resourceTypes: ["IMAGE", "VIDEO", "EMBED"],
+    moreInfoMessage: intl.formatMessage({
+      defaultMessage:
+        "At the moment, we only support images and videos. Corrupted and unsupported files will not appear.",
+      description: "Helper text to explain why some assets are not visible",
+    }),
+    // TODO remove `export` if your app does not support exporting the Canva design into an external platform
+    export: {
+      enabled: true,
+      // TODO provide a container type that user can choose to save into, or remove this field if user doesn't need to choose a container
+      containerTypes: ["folder"],
+      // TODO remove file types that are not supported by your platform
+      acceptedFileTypes: [
+        "png",
+        "pdf_standard",
+        "jpg",
+        "gif",
+        "svg",
+        "video",
+        "pptx",
+      ],
     },
-  ],
-  sortOptions: [
-    { value: "created_at DESC", label: "Creation date (newest)" },
-    { value: "created_at ASC", label: "Creation date (oldest)" },
-    { value: "updated_at DESC", label: "Updated (newest)" },
-    { value: "updated_at ASC", label: "Updated (oldest)" },
-    { value: "name ASC", label: "Name (A-Z)" },
-    { value: "name DESC", label: "Name (Z-A)" },
-  ],
-  layouts: ["MASONRY", "LIST"],
-  resourceTypes: ["IMAGE", "VIDEO", "EMBED"],
-  moreInfoMessage:
-    "At the moment, we only support images and videos. Corrupted and unsupported files will not appear.",
+  };
 };

package/templates/dam/src/index.tsx

@@ -1,8 +1,8 @@
+import { AppI18nProvider } from "@canva/app-i18n-kit";
 import { AppUiProvider } from "@canva/app-ui-kit";
 import { createRoot } from "react-dom/client";
 import { App } from "./app";
 import "@canva/app-ui-kit/styles.css";
-import { AppI18nProvider } from "@canva/app-i18n-kit";
 
 const root = createRoot(document.getElementById("root") as Element);
 function render() {

package/templates/dam/utils/backend/base_backend/create.ts

@@ -1,10 +1,10 @@
 /* eslint-disable no-console */
+import debug from "debug";
 import * as express from "express";
+import type { NextFunction, Request, Response } from "express";
+import * as fs from "fs";
 import * as http from "http";
 import * as https from "https";
-import * as fs from "fs";
-import type { Request, Response, NextFunction } from "express";
-import debug from "debug";
 
 const serverDebug = debug("server");
 

package/templates/dam/utils/backend/jwt_middleware/jwt_middleware.ts

@@ -1,11 +1,11 @@
 /* eslint-disable no-console */
 import * as chalk from "chalk";
 import * as debug from "debug";
-import type { Request, Response, NextFunction } from "express";
-import * as jwt from "jsonwebtoken";
-import { JwksClient, SigningKeyNotFoundError } from "jwks-rsa";
+import type { NextFunction, Request, Response } from "express";
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 import Express from "express-serve-static-core";
+import * as jwt from "jsonwebtoken";
+import { JwksClient, SigningKeyNotFoundError } from "jwks-rsa";
 
 /**
  * Prefix your start command with `DEBUG=express:middleware:jwt` to enable debug logging
@@ -110,7 +110,7 @@ export function createJwtMiddleware(
         return sendUnauthorizedResponse(res);
       }
 
-      req.canva = {
+      req["canva"] = {
         appId: payload.aud,
         brandId: payload.brandId,
         userId: payload.userId,

package/templates/dam/utils/backend/jwt_middleware/tests/jwt_middleware.tests.ts

@@ -446,7 +446,7 @@ describe("createJwtMiddleware", () => {
         expect(res.status).not.toHaveBeenCalled();
         expect(res.json).not.toHaveBeenCalled();
 
-        expect(req.canva).toEqual({
+        expect(req["canva"]).toEqual({
           userId: FAKE_USER_ID,
           brandId: FAKE_BRAND_ID,
           appId: FAKE_APP_ID,

package/templates/{base/webpack.config.cjs → dam/webpack.config.ts}

@@ -1,31 +1,36 @@
-require("dotenv").config();
-const path = require("path");
-const TerserPlugin = require("terser-webpack-plugin");
-const { DefinePlugin, optimize } = require("webpack");
-const chalk = require("chalk");
-const { transform } = require("@formatjs/ts-transformer");
-const ReactRefreshWebpackPlugin = require("@pmmmwh/react-refresh-webpack-plugin");
+import type { Configuration } from "webpack";
+import { DefinePlugin, optimize } from "webpack";
+import * as path from "path";
+import * as TerserPlugin from "terser-webpack-plugin";
+import { transform } from "@formatjs/ts-transformer";
+import * as chalk from "chalk";
+import { config } from "dotenv";
+import { Configuration as DevServerConfiguration } from "webpack-dev-server";
 
-/**
- *
- * @param {Object} [options]
- * @param {string} [options.appEntry=./src/index.tsx]
- * @param {string} [options.backendHost]
- * @param {Object} [options.devConfig]
- * @param {number} [options.devConfig.port]
- * @param {boolean} [options.devConfig.enableHmr]
- * @param {boolean} [options.devConfig.enableHttps]
- * @param {string} [options.devConfig.appOrigin]
- * @param {string} [options.devConfig.appId] - Deprecated in favour of appOrigin
- * @param {string} [options.devConfig.certFile]
- * @param {string} [options.devConfig.keyFile]
- * @returns {Object}
- */
-function buildConfig({
+config();
+
+type DevConfig = {
+  port: number;
+  enableHmr: boolean;
+  enableHttps: boolean;
+  appOrigin?: string;
+  appId?: string; // Deprecated in favour of appOrigin
+  certFile?: string;
+  keyFile?: string;
+};
+
+export function buildConfig({
   devConfig,
   appEntry = path.join(process.cwd(), "src", "index.tsx"),
   backendHost = process.env.CANVA_BACKEND_HOST,
-} = {}) {
+  // For IN_HARNESS, refer to the following docs for more information: https://www.canva.dev/docs/apps/test-harness/
+  inHarness = process.env.IN_HARNESS?.toLowerCase() === "true",
+}: {
+  devConfig?: DevConfig;
+  appEntry?: string;
+  backendHost?: string;
+  inHarness?: boolean;
+} = {}): Configuration & DevServerConfiguration {
   const mode = devConfig ? "development" : "production";
 
   if (!backendHost) {
@@ -46,9 +51,14 @@ function buildConfig({
   return {
     mode,
     context: path.resolve(process.cwd(), "./"),
-    entry: {
-      app: appEntry,
-    },
+    entry: inHarness
+      ? {
+          harness: path.join(process.cwd(), "harness", "harness.tsx"),
+          init: path.join(process.cwd(), "harness", "init.ts"),
+        }
+      : {
+          app: appEntry,
+        },
     target: "web",
     resolve: {
       alias: {
@@ -60,7 +70,7 @@ function buildConfig({
       extensions: [".ts", ".tsx", ".js", ".css", ".svg", ".woff", ".woff2"],
     },
     infrastructureLogging: {
-      level: "none",
+      level: inHarness ? "info" : "none",
     },
     module: {
       rules: [
@@ -172,35 +182,26 @@ function buildConfig({
       new DefinePlugin({
         BACKEND_HOST: JSON.stringify(backendHost),
       }),
-      // Apps can only submit a single JS file via the developer portal
+      // Apps can only submit a single JS file via the Developer Portal
       new optimize.LimitChunkCountPlugin({ maxChunks: 1 }),
-      mode === "development" && new ReactRefreshWebpackPlugin(),
     ].filter(Boolean),
     ...buildDevConfig(devConfig),
   };
 }
 
-/**
- *
- * @param {Object} [options]
- * @param {number} [options.port]
- * @param {boolean} [options.enableHmr]
- * @param {boolean} [options.enableHttps]
- * @param {string} [options.appOrigin]
- * @param {string} [options.appId] - Deprecated in favour of appOrigin
- * @param {string} [options.certFile]
- * @param {string} [options.keyFile]
- * @returns {Object|null}
- */
-function buildDevConfig(options) {
+function buildDevConfig(options?: DevConfig): {
+  devtool?: string;
+  devServer?: DevServerConfiguration;
+} {
   if (!options) {
-    return null;
+    return {};
   }
 
   const { port, enableHmr, appOrigin, appId, enableHttps, certFile, keyFile } =
     options;
+  const host = "localhost";
 
-  let devServer = {
+  let devServer: DevServerConfiguration = {
     server: enableHttps
       ? {
           type: "https",
@@ -210,7 +211,8 @@ function buildDevConfig(options) {
           },
         }
       : "http",
-    host: "localhost",
+    host,
+    allowedHosts: [host],
     historyApiFallback: {
       rewrites: [{ from: /^\/$/, to: "/app.js" }],
     },
@@ -227,31 +229,13 @@ function buildDevConfig(options) {
   if (enableHmr && appOrigin) {
     devServer = {
       ...devServer,
-      allowedHosts: new URL(appOrigin).hostname,
+      allowedHosts: [host, new URL(appOrigin).hostname],
       headers: {
         "Access-Control-Allow-Origin": appOrigin,
         "Access-Control-Allow-Credentials": "true",
         "Access-Control-Allow-Private-Network": "true",
       },
     };
-  } else if (enableHmr && appId) {
-    // Deprecated - App ID should not be used to configure HMR in the future and can be safely removed
-    // after a few months.
-
-    console.warn(
-      "Enabling Hot Module Replacement (HMR) with an App ID is deprecated, please see the README.md on how to update.",
-    );
-
-    const appDomain = `app-${appId.toLowerCase().trim()}.canva-apps.com`;
-    devServer = {
-      ...devServer,
-      allowedHosts: appDomain,
-      headers: {
-        "Access-Control-Allow-Origin": `https://${appDomain}`,
-        "Access-Control-Allow-Credentials": "true",
-        "Access-Control-Allow-Private-Network": "true",
-      },
-    };
   } else {
     if (enableHmr && !appOrigin) {
       console.warn(
@@ -267,6 +251,4 @@ function buildDevConfig(options) {
   };
 }
 
-module.exports = () => buildConfig();
-
-module.exports.buildConfig = buildConfig;
+export default buildConfig;

package/templates/data_connector/README.md

@@ -0,0 +1,84 @@
+# Data Connector Template
+
+## Overview
+
+This template provides a working example of a data connector app which uses the Canva Connect API as a data source. It demonstrates how to log in with OAuth and then fetch data from an external source, using Canva's API for listing Designs and Brand Templates. There are instructions below for how to configure your authentication settings to try it out.
+
+The template provides a list / detail interface for choosing a data source. The user would first select the data source they want to import from a list. Next, they configure the data source to select the desired query by applying search filters or sort criteria. The app turns their configured data source into an API request and then returns the data in a table format for use in a Canva Design.
+
+## Best Practices
+
+This template captures best practices for improving user experience in your application.
+
+### State Management
+
+In this template, we've set up state management using `React Context`. It's just one way to do it, not a strict rule. If your app gets more complicated, you might want to check out other options like `Redux` or `MobX`.
+
+### Routing
+
+As your application evolves, you may find the need for routing to manage multiple views or pages. In this template, we've integrated React Router to illustrate how routing can facilitate seamless navigation between various components.
+
+### App UI Kit
+
+The App UI Kit is a React-based component library designed for creating apps that emulate Canva's look and feel. We strongly recommend using the App UI Kit if you're planning to release an app to the public, because this makes it easier to comply with our [design guidelines](https://www.canva.dev/docs/apps/design-guidelines/).
+
+### Data Sources
+
+A data source is a type of data that this connector can retrieve. It has:
+
+- properties that define the configuration for this source - e.g. search criteria, ordering conditions, selection filters
+- UI for how to edit this configuration
+- columns to display for each data item
+- logic for how to fetch the data from an external API
+
+The initial data sources for the Canva Connect API (Designs and Brand Templates) in this template are located in `src/api/data_sources/`.
+
+This template provides a `DataSourceHandler` class in `src/api/data_source.ts` as a suggested starting point for defining a reusable concept for a data source and convert API responses into data table outputs.
+
+## Setup - Authentication
+
+This template is a working app that reads the [Canva Connect API](https://www.canva.dev/docs/connect/).
+
+To run it and authenticate with the Canva Connect API via OAuth you must first complete some authentication setup steps.
+
+### 0. Set up an App
+
+- If not already handled by the Canva CLI, you need to create an app.
+  Go to [Your Apps](https://www.canva.com/developers/apps) and create an app.
+- On the **Configuration** page, enable the `Data Connector` intent.
+
+### 1. Set up a Connect API Integration
+
+- Go to [Your Integrations](https://www.canva.com/developers/integrations/connect-api) and create a new integration
+- On the **Configuration** page, generate a client secret - you need the client ID and client secret in the app setup.
+- On the **Scopes** page, add the `designs:meta` and `brandtemplate:meta` read scopes
+- On the **Authentication** page, set `https://www.canva.com/apps/oauth/authorized` as an Authorized redirect
+
+### 2. Set up OAuth for the app
+
+- Go to [Your Apps](https://www.canva.com/developers/apps) and open your data connector app.
+- On the **Authentication** page, add an OAuth 2.0 provider with the following settings:
+  > Provider: `CanvaConnect`
+  >
+  > Client ID: `(generated in step 1)`
+  >
+  > Client secret: `(generated in step 1)`
+  >
+  > Credential transfer mode: `Headers (default)`
+  >
+  > Authorization server URL: `https://www.canva.com/api/oauth/authorize`
+  >
+  > Token exchange URL: `https://api.canva.com/rest/v1/oauth/token`
+  >
+  > Proof Key for Code Exchange (PKCE): `Enabled`
+
+### 3. Run your app
+
+- Run `npm start` to run the app.
+- You should be able to log in and then choose from the available data sources.
+
+### To use another OAuth source
+
+- `src/api/oauth.ts` has a `scope` property that will be used in the oauth flow.
+- This template starts with the scope for the Canva Connect API login set to `["design:meta:read", "brandtemplate:meta:read"]`
+- It should match the scopes set in Step 1.

package/templates/data_connector/canva-app.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://www.canva.dev/schemas/app/v1/manifest-schema.json",
+  "manifest_schema_version": 1,
+  "runtime": {
+    "permissions": [
+      {
+        "name": "canva:design:content:read",
+        "type": "mandatory"
+      },
+      {
+        "name": "canva:design:content:write",
+        "type": "mandatory"
+      }
+    ]
+  },
+  "intent": {
+    "data_connector": {
+      "enrolled": true
+    }
+  }
+}