@canva/cli 0.0.1-beta.1

package/templates/dam/webpack.config.cjs

@@ -0,0 +1,270 @@
+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");
+
+/**
+ *
+ * @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({
+  devConfig,
+  appEntry = path.join(process.cwd(), "src", "index.tsx"),
+  backendHost = process.env.CANVA_BACKEND_HOST,
+} = {}) {
+  const mode = devConfig ? "development" : "production";
+
+  if (!backendHost) {
+    console.error(
+      chalk.redBright.bold("BACKEND_HOST is undefined."),
+      `Refer to "Customizing the backend host" in the README.md for more information.`,
+    );
+    process.exit(-1);
+  } else if (backendHost.includes("localhost") && mode === "production") {
+    console.error(
+      chalk.redBright.bold(
+        "BACKEND_HOST should not be set to localhost for production builds!",
+      ),
+      `Refer to "Customizing the backend host" in the README.md for more information.`,
+    );
+  }
+
+  return {
+    mode,
+    context: path.resolve(process.cwd(), "./"),
+    entry: {
+      app: appEntry,
+    },
+    target: "web",
+    resolve: {
+      alias: {
+        assets: path.resolve(process.cwd(), "assets"),
+        utils: path.resolve(process.cwd(), "utils"),
+        styles: path.resolve(process.cwd(), "styles"),
+        src: path.resolve(process.cwd(), "src"),
+      },
+      extensions: [".ts", ".tsx", ".js", ".css", ".svg", ".woff", ".woff2"],
+    },
+    infrastructureLogging: {
+      level: "none",
+    },
+    module: {
+      rules: [
+        {
+          test: /\.tsx?$/,
+          exclude: /node_modules/,
+          use: [
+            {
+              loader: "ts-loader",
+              options: {
+                transpileOnly: true,
+                getCustomTransformers() {
+                  return {
+                    before: [
+                      transform({
+                        overrideIdFn: "[sha512:contenthash:base64:6]",
+                      }),
+                    ],
+                  };
+                },
+              },
+            },
+          ],
+        },
+        {
+          test: /\.css$/,
+          exclude: /node_modules/,
+          use: [
+            "style-loader",
+            {
+              loader: "css-loader",
+              options: {
+                modules: true,
+              },
+            },
+            {
+              loader: "postcss-loader",
+              options: {
+                postcssOptions: {
+                  plugins: [require("cssnano")({ preset: "default" })],
+                },
+              },
+            },
+          ],
+        },
+        {
+          test: /\.(png|jpg|jpeg)$/i,
+          type: "asset/inline",
+        },
+        {
+          test: /\.(woff|woff2)$/,
+          type: "asset/inline",
+        },
+        {
+          test: /\.svg$/,
+          oneOf: [
+            {
+              issuer: /\.[jt]sx?$/,
+              resourceQuery: /react/, // *.svg?react
+              use: ["@svgr/webpack", "url-loader"],
+            },
+            {
+              type: "asset/resource",
+              parser: {
+                dataUrlCondition: {
+                  maxSize: 200,
+                },
+              },
+            },
+          ],
+        },
+        {
+          test: /\.css$/,
+          include: /node_modules/,
+          use: [
+            "style-loader",
+            "css-loader",
+            {
+              loader: "postcss-loader",
+              options: {
+                postcssOptions: {
+                  plugins: [require("cssnano")({ preset: "default" })],
+                },
+              },
+            },
+          ],
+        },
+      ],
+    },
+    optimization: {
+      minimizer: [
+        new TerserPlugin({
+          terserOptions: {
+            format: {
+              // Turned on because emoji and regex is not minified properly using default
+              // https://github.com/facebook/create-react-app/issues/2488
+              ascii_only: true,
+            },
+          },
+        }),
+      ],
+    },
+    output: {
+      filename: `[name].js`,
+      path: path.resolve(process.cwd(), "dist"),
+      clean: true,
+    },
+    plugins: [
+      new DefinePlugin({
+        BACKEND_HOST: JSON.stringify(backendHost),
+      }),
+      // Apps can only submit a single JS file via the developer portal
+      new optimize.LimitChunkCountPlugin({ maxChunks: 1 }),
+    ],
+    ...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) {
+  if (!options) {
+    return null;
+  }
+
+  const { port, enableHmr, appOrigin, appId, enableHttps, certFile, keyFile } =
+    options;
+
+  let devServer = {
+    server: enableHttps
+      ? {
+          type: "https",
+          options: {
+            cert: certFile,
+            key: keyFile,
+          },
+        }
+      : "http",
+    host: "localhost",
+    historyApiFallback: {
+      rewrites: [{ from: /^\/$/, to: "/app.js" }],
+    },
+    port,
+    client: {
+      logging: "verbose",
+    },
+    static: {
+      directory: path.resolve(process.cwd(), "assets"),
+      publicPath: "/assets",
+    },
+  };
+
+  if (enableHmr && appOrigin) {
+    devServer = {
+      ...devServer,
+      allowedHosts: 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(
+        "Attempted to enable Hot Module Replacement (HMR) without configuring App Origin... Disabling HMR.",
+      );
+    }
+    devServer.webSocketServer = false;
+  }
+
+  return {
+    devtool: "source-map",
+    devServer,
+  };
+}
+
+module.exports = () => buildConfig();
+
+module.exports.buildConfig = buildConfig;

package/templates/gen_ai/README.md

@@ -0,0 +1,27 @@
+## Generative AI Template
+
+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.
+
+### Loading state
+
+Creating AI assets can be time-consuming, often resulting in users facing extended waiting periods. Incorporating placeholders, a loading bar, and a message indicating the expected wait time can help alleviate the perceived wait time. We highly encourage adopting this approach and customizing it to suit your specific use case.
+
+### Obscenity filter
+
+In this template, we've included a basic obscenity filter to stop users from creating offensive or harmful content. However, you might need additional filters or checks after content generation to ensure it meets your standards.
+
+### Backend
+
+This template includes a simple Express server as a sample backend. Please note that this server is not production-ready, and we advise using it solely for instructional purposes to demonstrate API calls.
+
+### Thumbnails
+
+This template illustrates how your API could return thumbnails and demonstrates their usage within the code. Thumbnails play a crucial role in optimizing image uploads and previews by providing quick visual feedback and reducing load times.

package/templates/gen_ai/backend/database/database.ts

@@ -0,0 +1,42 @@
+import * as fs from "fs/promises";
+import * as path from "path";
+
+/**
+ * This file creates a "database" out of a JSON file. It's only for
+ * demonstration purposes. A real app should use a real database.
+ */
+const DATABASE_FILE_PATH = path.join(__dirname, "db.json");
+
+interface Database<T> {
+  read(): Promise<T>;
+  write(data: T): Promise<void>;
+}
+
+export class JSONFileDatabase<T> implements Database<T> {
+  constructor(private readonly seedData: T) {}
+
+  // Creates a database file if one doesn't already exist
+  private async init(): Promise<void> {
+    try {
+      // Do nothing, since the database is initialized
+      await fs.stat(DATABASE_FILE_PATH);
+    } catch {
+      const file = JSON.stringify(this.seedData);
+      await fs.writeFile(DATABASE_FILE_PATH, file);
+    }
+  }
+
+  // Loads and parses the database file
+  async read(): Promise<T> {
+    await this.init();
+    const file = await fs.readFile(DATABASE_FILE_PATH, "utf8");
+    return JSON.parse(file);
+  }
+
+  // Overwrites the database file with provided data
+  async write(data: T): Promise<void> {
+    await this.init();
+    const file = JSON.stringify(data);
+    await fs.writeFile(DATABASE_FILE_PATH, file);
+  }
+}

package/templates/gen_ai/backend/routers/auth.ts

@@ -0,0 +1,285 @@
+import * as chalk from "chalk";
+import * as crypto from "crypto";
+import "dotenv/config";
+import * as express from "express";
+import * as cookieParser from "cookie-parser";
+import * as basicAuth from "express-basic-auth";
+import { JSONFileDatabase } from "../database/database";
+import { getTokenFromQueryString } from "../../utils/backend/jwt_middleware/jwt_middleware";
+import { createJwtMiddleware } from "../../utils/backend/jwt_middleware";
+
+/**
+ * These are the hard-coded credentials for logging in to this template.
+ */
+const USERNAME = "username";
+const PASSWORD = "password";
+
+const COOKIE_EXPIRY_MS = 5 * 60 * 1000; // 5 minutes
+
+const CANVA_BASE_URL = "https://canva.com";
+
+interface Data {
+  users: string[];
+}
+
+/**
+ * For more information on Authentication, refer to our documentation: {@link https://www.canva.dev/docs/apps/authenticating-users/#types-of-authentication}.
+ */
+export const createAuthRouter = () => {
+  const APP_ID = getAppId();
+
+  /**
+   * Set up a database with a "users" table. In this example code, the
+   * database is simply a JSON file.
+   */
+  const db = new JSONFileDatabase<Data>({ users: [] });
+
+  const router = express.Router();
+
+  /**
+   * The `cookieParser` middleware allows the routes to read and write cookies.
+   *
+   * By passing a value into the middleware, we enable the "signed cookies" feature of Express.js. The
+   * value should be static and cryptographically generated. If it's dynamic (as shown below), cookies
+   * won't persist between server restarts.
+   *
+   * TODO: Replace `crypto.randomUUID()` with a static value, loaded via an environment variable.
+   */
+  router.use(cookieParser(crypto.randomUUID()));
+
+  /**
+   * This endpoint is hit at the start of the authentication flow. It contains a state which must
+   * be passed back to canva so that Canva can verify the response. It must also set a nonce in the
+   * user's browser cookies and send the nonce back to Canva as a url parameter.
+   *
+   * If Canva can validate the state, it will then redirect back to the chosen redirect url.
+   */
+  router.get("/configuration/start", async (req, res) => {
+    /**
+     * Generate a unique nonce for each request. A nonce is a random, single-use value
+     * that's impossible to guess or enumerate. We recommended using a Version 4 UUID that
+     * is cryptographically secure, such as one generated by the `randomUUID` method.
+     */
+    const nonce = crypto.randomUUID();
+    // Set the expiry time for the nonce. We recommend 5 minutes.
+    const expiry = Date.now() + COOKIE_EXPIRY_MS;
+
+    // Create a JSON string that contains the nonce and an expiry time
+    const nonceWithExpiry = JSON.stringify([nonce, expiry]);
+
+    // Set a cookie that contains the nonce and the expiry time
+    res.cookie("nonce", nonceWithExpiry, {
+      secure: true,
+      httpOnly: true,
+      maxAge: COOKIE_EXPIRY_MS,
+      signed: true,
+    });
+
+    // Create the query parameters that Canva requires
+    const params = new URLSearchParams({
+      nonce,
+      state: req?.query?.state?.toString() || "",
+    });
+
+    // Redirect to Canva with required parameters
+    res.redirect(302, `${CANVA_BASE_URL}/apps/configure/link?${params}`);
+  });
+
+  /**
+   * This endpoint renders a login page. Once the user logs in, they're
+   * redirected back to Canva, which completes the authentication flow.
+   */
+  router.get(
+    "/redirect-url",
+    /**
+     * Use a JSON Web Token (JWT) to verify incoming requests. The JWT is
+     * extracted from the `canva_user_token` parameter.
+     */
+    createJwtMiddleware(APP_ID, getTokenFromQueryString),
+    /**
+     * Warning: For demonstration purposes, we're using basic authentication and
+     * hard- coding a username and password. This is not a production-ready
+     * solution!
+     */
+    basicAuth({
+      users: { [USERNAME]: PASSWORD },
+      challenge: true,
+    }),
+    async (req, res) => {
+      const failureResponse = () => {
+        const params = new URLSearchParams({
+          success: "false",
+          state: req.query.state?.toString() || "",
+        });
+        res.redirect(302, `${CANVA_BASE_URL}/apps/configured?${params}`);
+      };
+
+      // Get the nonce and expiry time stored in the cookie.
+      const cookieNonceAndExpiry = req.signedCookies.nonce;
+
+      // Get the nonce from the query parameter.
+      const queryNonce = req.query.nonce?.toString();
+
+      // After reading the cookie, clear it. This forces abandoned auth flows to be restarted.
+      res.clearCookie("nonce");
+
+      let cookieNonce = "";
+      let expiry = 0;
+
+      try {
+        [cookieNonce, expiry] = JSON.parse(cookieNonceAndExpiry);
+      } catch {
+        // If the nonce can't be parsed, assume something has been compromised and exit.
+        return failureResponse();
+      }
+
+      // If the nonces are empty, exit the authentication flow.
+      if (
+        isEmpty(cookieNonceAndExpiry) ||
+        isEmpty(queryNonce) ||
+        isEmpty(cookieNonce)
+      ) {
+        return failureResponse();
+      }
+
+      /**
+       * Check that:
+       *
+       * - The nonce in the cookie and query parameter contain the same value
+       * - The nonce has not expired
+       *
+       * **Note:** We could rely on the cookie expiry, but that is vulnerable to tampering
+       * with the browser's time. This allows us to double-check based on server time.
+       */
+      if (expiry < Date.now() || cookieNonce !== queryNonce) {
+        return failureResponse();
+      }
+
+      // Get the userId from JWT middleware
+      const { userId } = req.canva;
+
+      // Load the database
+      const data = await db.read();
+
+      // Add the user to the database
+      if (!data.users.includes(userId)) {
+        data.users.push(userId);
+        await db.write(data);
+      }
+
+      // Create query parameters for redirecting back to Canva
+      const params = new URLSearchParams({
+        success: "true",
+        state: req?.query?.state?.toString() || "",
+      });
+
+      // Redirect the user back to Canva
+      res.redirect(302, `${CANVA_BASE_URL}/apps/configured?${params}`);
+    },
+  );
+
+  /**
+   * TODO: Add this middleware to all routes that will receive requests from
+   * your app.
+   */
+  const jwtMiddleware = createJwtMiddleware(APP_ID);
+
+  /**
+   * This endpoint is called when a user disconnects an app from their account.
+   * The app is expected to de-authenticate the user on its backend, so if the
+   * user reconnects the app, they'll need to re-authenticate.
+   *
+   * Note: The name of the endpoint is *not* configurable.
+   *
+   * Note: This endpoint is called by Canva's backend directly and must be
+   * exposed via a public URL. To test this endpoint, add a proxy URL, such as
+   * one generated by nGrok, to the 'Add authentication' section in the
+   * Developer Portal. Localhost addresses will not work to test this endpoint.
+   */
+  router.post("/configuration/delete", jwtMiddleware, async (req, res) => {
+    // Get the userId from JWT middleware
+    const { userId } = req.canva;
+
+    // Load the database
+    const data = await db.read();
+
+    // Remove the user from the database
+    await db.write({
+      users: data.users.filter((user) => user !== userId),
+    });
+
+    // Confirm that the user was removed
+    res.send({
+      type: "SUCCESS",
+    });
+  });
+
+  /**
+   * All routes that start with /api will be protected by JWT authentication
+   */
+  router.use("/api", jwtMiddleware);
+
+  /**
+   * This endpoint checks if a user is authenticated.
+   */
+  router.post("/api/authentication/status", async (req, res) => {
+    // Load the database
+    const data = await db.read();
+
+    // Check if the user is authenticated
+    const isAuthenticated = data.users.includes(req.canva.userId);
+
+    // Return the authentication status
+    res.send({
+      isAuthenticated,
+    });
+  });
+
+  return router;
+};
+
+/**
+ * Checks if a given param is nullish or an empty string
+ *
+ * @param str The string to check
+ * @returns true if the string is nullish or empty, false otherwise
+ */
+function isEmpty(str?: string): boolean {
+  return str == null || str.length === 0;
+}
+
+/**
+ * Retrieves the CANVA_APP_ID from the environment variables.
+ * Throws an error if the CANVA_APP_ID environment variable is undefined or set to a default value.
+ *
+ * @returns {string} The Canva App ID
+ * @throws {Error} If CANVA_APP_ID environment variable is undefined or set to a default value
+ */
+function getAppId(): string {
+  // TODO: Set the CANVA_APP_ID environment variable in the project's .env file
+  const appId = process.env.CANVA_APP_ID;
+
+  if (!appId) {
+    throw new Error(
+      `The CANVA_APP_ID environment variable is undefined. Set the variable in the project's .env file.`,
+    );
+  }
+
+  if (appId === "YOUR_APP_ID_HERE") {
+    // eslint-disable-next-line no-console
+    console.log(
+      chalk.bgRedBright(
+        "Default 'CANVA_APP_ID' environment variable detected.",
+      ),
+    );
+    // eslint-disable-next-line no-console
+    console.log(
+      "Please update the 'CANVA_APP_ID' environment variable in your project's `.env` file " +
+        `with the App ID obtained from the Canva Developer Portal: ${chalk.greenBright(
+          "https://www.canva.com/developers/apps",
+        )}\n`,
+    );
+  }
+
+  return appId;
+}