@canva/cli 0.0.1-beta.8 → 1.0.0

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
+    }
+  }
+}

package/templates/data_connector/declarations/declarations.d.ts

@@ -0,0 +1,29 @@
+declare module "*.css" {
+  const styles: { [className: string]: string };
+  export = styles;
+}
+
+declare module "*.jpg" {
+  const content: string;
+  export default content;
+}
+
+declare module "*.jpeg" {
+  const content: string;
+  export default content;
+}
+
+declare module "*.png" {
+  const content: string;
+  export default content;
+}
+
+declare module "*.svg" {
+  const content: React.FunctionComponent<{
+    size?: "tiny" | "small" | "medium" | "large";
+    className?: string;
+  }>;
+  export default content;
+}
+
+declare const BACKEND_HOST: string;

package/templates/data_connector/eslint.config.mjs

@@ -0,0 +1,14 @@
+import canvaPlugin from "@canva/app-eslint-plugin";
+
+export default [
+  {
+    ignores: [
+      "**/node_modules/",
+      "**/dist",
+      "**/*.d.ts",
+      "**/*.d.tsx",
+      "**/*.config.*",
+    ],
+  },
+  ...canvaPlugin.configs.apps,
+];

package/templates/data_connector/package.json

@@ -0,0 +1,91 @@
+{
+  "private": true,
+  "name": "data_connector",
+  "description": "An example Canva Data Connector App",
+  "scripts": {
+    "extract": "formatjs extract \"src/**/*.{ts,tsx}\" --out-file dist/messages_en.json",
+    "build": "webpack --config webpack.config.ts --mode production && npm run extract",
+    "format": "prettier '**/*.{css,ts,tsx}' --no-config --write",
+    "format:check": "prettier '**/*.{css,ts,tsx}' --no-config --check --ignore-path",
+    "format:file": "prettier $1 --no-config --write",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "lint:types": "tsc",
+    "start": "ts-node ./scripts/start/start.ts",
+    "start:preview": "npm run start -- --preview",
+    "test": "jest --no-cache",
+    "test:watch": "jest --watchAll",
+    "test:update": "npm run test -- -u",
+    "postinstall": "ts-node ./scripts/copy_env.ts"
+  },
+  "dependencies": {
+    "@canva/app-i18n-kit": "^1.0.3",
+    "@canva/app-ui-kit": "^4.10.0",
+    "@canva/asset": "^2.2.1",
+    "@canva/design": "^2.7.2",
+    "@canva/error": "^2.1.0",
+    "@canva/intents": "^2.0.0",
+    "@canva/platform": "^2.2.0",
+    "@canva/user": "^2.1.1",
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
+    "react-error-boundary": "6.0.0",
+    "react-intl": "6.8.7",
+    "react-router-dom": "7.6.3"
+  },
+  "devDependencies": {
+    "@canva/app-eslint-plugin": "^1.0.0-beta.3",
+    "@canva/cli": ">= 0.0.1-beta.13",
+    "@formatjs/cli": "6.7.2",
+    "@formatjs/ts-transformer": "3.14.0",
+    "@ngrok/ngrok": "1.5.1",
+    "@pmmmwh/react-refresh-webpack-plugin": "0.6.1",
+    "@svgr/webpack": "8.1.0",
+    "@testing-library/react": "16.3.0",
+    "@types/express": "4.17.21",
+    "@types/express-serve-static-core": "5.0.6",
+    "@types/jest": "29.5.14",
+    "@types/jsonwebtoken": "9.0.10",
+    "@types/node": "20.19.2",
+    "@types/node-fetch": "2.6.12",
+    "@types/node-forge": "1.3.11",
+    "@types/nodemon": "1.19.6",
+    "@types/react": "18.3.12",
+    "@types/react-dom": "18.3.1",
+    "@types/webpack-env": "1.18.8",
+    "chalk": "4.1.2",
+    "cli-table3": "0.6.5",
+    "css-loader": "7.1.2",
+    "css-modules-typescript-loader": "4.0.1",
+    "cssnano": "7.0.7",
+    "debug": "4.4.1",
+    "dotenv": "16.6.0",
+    "express": "4.21.2",
+    "express-basic-auth": "1.2.1",
+    "jest": "29.7.0",
+    "jest-css-modules-transform": "4.4.2",
+    "jest-environment-jsdom": "29.7.0",
+    "jsonwebtoken": "9.0.2",
+    "jwks-rsa": "3.2.0",
+    "mini-css-extract-plugin": "2.9.2",
+    "node-fetch": "3.3.2",
+    "node-forge": "1.3.1",
+    "nodemon": "3.0.1",
+    "open": "8.4.2",
+    "postcss-loader": "8.1.1",
+    "prettier": "3.6.2",
+    "react-refresh": "0.17.0",
+    "style-loader": "4.0.0",
+    "terser-webpack-plugin": "5.3.14",
+    "tree-kill": "1.2.2",
+    "ts-jest": "29.4.0",
+    "ts-loader": "9.5.2",
+    "ts-node": "10.9.2",
+    "typescript": "5.8.2",
+    "url-loader": "4.1.1",
+    "webpack": "5.99.9",
+    "webpack-cli": "6.0.1",
+    "webpack-dev-server": "5.2.2",
+    "yargs": "17.7.2"
+  }
+}

package/templates/data_connector/scripts/ssl/ssl.ts

@@ -0,0 +1,131 @@
+import * as crypto from "crypto";
+import * as fs from "fs/promises";
+import { pki } from "node-forge";
+import * as path from "path";
+
+const SSL_CERT_DIR = path.resolve(process.cwd(), "..", "..", ".ssl");
+const CERT_FILE = path.resolve(SSL_CERT_DIR, "certificate.pem");
+const KEY_FILE = path.resolve(SSL_CERT_DIR, "private-key.pem");
+
+export interface Certificate {
+  keyFile: string;
+  certFile: string;
+}
+
+const CERT_ATTRS: { name: string; value: string }[] = [
+  {
+    name: "commonName",
+    value: "localhost",
+  },
+  {
+    name: "countryName",
+    value: "AU",
+  },
+  {
+    name: "stateOrProvinceName",
+    value: "New South Wales",
+  },
+  {
+    name: "localityName",
+    value: "Sydney",
+  },
+  {
+    name: "organizationName",
+    value: "Test",
+  },
+  {
+    name: "organizationalUnitName",
+    value: "Test",
+  },
+];
+
+const generateRsaKeys = async (): Promise<{
+  publicKey: string;
+  privateKey: string;
+}> =>
+  new Promise((resolve, reject) => {
+    crypto.generateKeyPair(
+      "rsa",
+      {
+        modulusLength: 2096,
+        publicKeyEncoding: {
+          type: "spki",
+          format: "pem",
+        },
+        privateKeyEncoding: {
+          type: "pkcs8",
+          format: "pem",
+        },
+      },
+      (err, publicKey, privateKey) => {
+        if (err) {
+          reject(err);
+        } else {
+          resolve({ publicKey, privateKey });
+        }
+      },
+    );
+  });
+
+const generateCertificate = (opts: {
+  privateKey: string;
+  publicKey: string;
+}): string => {
+  const privateKey = pki.privateKeyFromPem(opts.privateKey);
+  const publicKey = pki.publicKeyFromPem(opts.publicKey);
+
+  const cert = pki.createCertificate();
+
+  cert.publicKey = publicKey;
+  cert.serialNumber = "01";
+  cert.validity.notBefore = new Date();
+  cert.validity.notAfter = new Date();
+  cert.validity.notAfter.setFullYear(cert.validity.notBefore.getFullYear() + 1);
+
+  cert.setSubject(CERT_ATTRS);
+  cert.setIssuer(CERT_ATTRS);
+
+  // the actual certificate signing
+  cert.sign(privateKey);
+
+  // now convert the Forge certificate to PEM format
+  return pki.certificateToPem(cert);
+};
+
+const writeCertFiles = async (opts: {
+  cert: string;
+  privateKey: string;
+}): Promise<void> => {
+  const { cert, privateKey } = opts;
+
+  await fs.mkdir(SSL_CERT_DIR, { recursive: true });
+  await Promise.all([
+    fs.writeFile(CERT_FILE, cert, { encoding: "utf8" }),
+    fs.writeFile(KEY_FILE, privateKey, { encoding: "utf8" }),
+  ]);
+};
+
+const cerfFilesExist = async (): Promise<boolean> => {
+  try {
+    await Promise.all([
+      fs.access(CERT_FILE, fs.constants.R_OK | fs.constants.W_OK),
+      fs.access(KEY_FILE, fs.constants.R_OK | fs.constants.W_OK),
+    ]);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+export const createOrRetrieveCertificate = async (): Promise<Certificate> => {
+  if (!(await cerfFilesExist())) {
+    const keys = await generateRsaKeys();
+    const cert = generateCertificate(keys);
+    await writeCertFiles({ cert, privateKey: keys.privateKey });
+  }
+
+  return {
+    certFile: CERT_FILE,
+    keyFile: KEY_FILE,
+  };
+};

package/templates/data_connector/scripts/start/app_runner.ts

@@ -0,0 +1,201 @@
+/* eslint-disable no-console */
+import { generatePreviewUrl } from "@canva/cli";
+import * as ngrok from "@ngrok/ngrok";
+import * as chalk from "chalk";
+import * as Table from "cli-table3";
+import * as nodemon from "nodemon";
+import * as open from "open";
+import * as webpack from "webpack";
+import * as WebpackDevServer from "webpack-dev-server";
+import { buildConfig } from "../../webpack.config";
+import type { Certificate } from "../ssl/ssl";
+import { createOrRetrieveCertificate } from "../ssl/ssl";
+import type { Context } from "./context";
+
+export const infoChalk = chalk.blue.bold;
+export const warnChalk = chalk.bgYellow.bold;
+export const errorChalk = chalk.bgRed.bold;
+export const highlightChalk = chalk.greenBright.bold;
+export const linkChalk = chalk.cyan;
+
+export class AppRunner {
+  async run(ctx: Context) {
+    console.log(
+      infoChalk("Info:"),
+      `Starting development server for ${highlightChalk(ctx.entryDir)}\n`,
+    );
+
+    if (!ctx.hmrEnabled) {
+      console.log(
+        `${infoChalk(
+          "Note:",
+        )} Hot Module Replacement (HMR) not enabled. To enable it, please refer to the instructions in the ${highlightChalk(
+          "README.md",
+        )}\n`,
+      );
+    }
+
+    let cert: Certificate | undefined;
+    if (ctx.httpsEnabled) {
+      try {
+        cert = await createOrRetrieveCertificate();
+      } catch (err) {
+        console.log(
+          errorChalk("Error:"),
+          "Unable to generate SSL certificate.",
+        );
+        throw err;
+      }
+    }
+
+    const table = new Table({
+      colWidths: [30, 80],
+      wordWrap: true,
+      wrapOnWordBoundary: true,
+    });
+
+    const server = await this.runWebpackDevServer(ctx, table, cert);
+
+    await this.maybeRunBackendServer(ctx, table, cert, server);
+
+    await this.generateAndOpenPreviewUrl(ctx.openPreview, table);
+
+    console.log(table.toString(), "\n");
+
+    console.log(
+      `${infoChalk(
+        "Note:",
+      )} For instructions on how to set up the app via the Developer Portal, see the ${highlightChalk(
+        "README.md",
+      )}.\n`,
+    );
+  }
+
+  private readonly maybeRunBackendServer = async (
+    ctx: Context,
+    table: Table.Table,
+    cert: Certificate | undefined,
+    webpackDevServer: WebpackDevServer,
+  ) => {
+    if (!ctx.developerBackendEntryPath) {
+      return;
+    }
+
+    // App ID must be set when running a backend example
+    if (!ctx.appId) {
+      console.log(
+        errorChalk("Error:"),
+        `'CANVA_APP_ID' environment variable is undefined. Refer to the instructions in the ${highlightChalk(
+          "README.md",
+        )} on starting a backend example.`,
+      );
+      throw new Error("'CANVA_APP_ID' env variable not set.");
+    }
+
+    await new Promise((resolve) => {
+      const nodemonServer = nodemon({
+        script: ctx.developerBackendEntryPath,
+        ext: "ts",
+        env: {
+          SHOULD_ENABLE_HTTPS: ctx.httpsEnabled,
+          HTTPS_CERT_FILE: cert?.certFile || "",
+          HTTPS_KEY_FILE: cert?.keyFile || "",
+        },
+      });
+
+      nodemonServer.on("start", resolve);
+
+      nodemonServer.on("crash", async () => {
+        console.log(errorChalk("Shutting down local server.\n"));
+
+        await webpackDevServer.stop();
+        process.exit(1);
+      });
+    });
+
+    if (ctx.ngrokEnabled) {
+      console.log(
+        warnChalk("Warning:"),
+        `ngrok exposes a local port via a public URL. Be mindful of what's exposed and shut down the server when it's not in use.\n`,
+      );
+    }
+
+    let url = ctx.backendUrl;
+    if (ctx.ngrokEnabled) {
+      try {
+        const ngrokListener = await ngrok.forward({
+          addr: ctx.backendPort,
+          // requires an `NGROK_AUTHTOKEN` env var to be set
+          authtoken_from_env: true,
+        });
+        url = ngrokListener.url() ?? url;
+      } catch (err) {
+        console.log(
+          errorChalk("Error:"),
+          `Unable to start ngrok server: ${err}`,
+        );
+      }
+    }
+
+    table.push(["Base URL (Backend)", linkChalk(url)]);
+  };
+
+  private readonly runWebpackDevServer = async (
+    ctx: Context,
+    table: Table.Table,
+    cert: Certificate | undefined,
+  ): Promise<WebpackDevServer> => {
+    const runtimeWebpackConfig = buildConfig({
+      appEntry: ctx.frontendEntryPath,
+      backendHost: ctx.backendHost,
+      devConfig: {
+        port: ctx.frontendPort,
+        enableHmr: ctx.hmrEnabled,
+        appId: ctx.appId,
+        appOrigin: ctx.appOrigin,
+        enableHttps: ctx.httpsEnabled,
+        ...cert,
+      },
+    });
+
+    const compiler = webpack(runtimeWebpackConfig);
+    const server = new WebpackDevServer(
+      runtimeWebpackConfig.devServer,
+      compiler,
+    );
+    await server.start();
+
+    table.push(["Development URL (Frontend)", linkChalk(ctx.frontendUrl)]);
+
+    return server;
+  };
+
+  /**
+   * Calls the Canva CLI to generate a preview URL for the app
+   */
+  private readonly generateAndOpenPreviewUrl = async (
+    openPreview: boolean,
+    table: Table.Table,
+  ) => {
+    const previewCellHeader = { content: "Preview your app in Canva" };
+
+    const generatePreviewResult = await generatePreviewUrl();
+
+    if (!generatePreviewResult.success) {
+      table.push([
+        previewCellHeader,
+        { content: warnChalk(generatePreviewResult.message) },
+      ]);
+      return;
+    }
+
+    table.push([
+      previewCellHeader,
+      { content: "Preview URL", href: generatePreviewResult.data },
+    ]);
+
+    if (openPreview) {
+      open(generatePreviewResult.data);
+    }
+  };
+}