@canva/cli 0.0.1-beta.1

package/templates/dam/scripts/start/context.ts

@@ -0,0 +1,165 @@
+import * as fs from "fs";
+import * as path from "path";
+
+interface CliArgs {
+  example?: string;
+  useHttps?: boolean;
+  ngrok?: boolean;
+}
+
+interface EnvVars {
+  frontendPort: number;
+  backendPort: number;
+  hmrEnabled: boolean;
+  appId?: string;
+  appOrigin?: string;
+  backendHost?: string;
+}
+
+export class Context {
+  private readonly envVars: EnvVars;
+
+  constructor(
+    private env: NodeJS.ProcessEnv = process.env,
+    private readonly args: CliArgs,
+  ) {
+    this.envVars = this.parseAndValidateEnvironmentVariables();
+  }
+
+  static get srcDir() {
+    const src = path.join(Context.rootDir, "src");
+
+    if (!fs.existsSync(src)) {
+      throw new Error(`Directory does not exist: ${src}`);
+    }
+
+    return src;
+  }
+
+  static get readmeDir() {
+    return path.join(Context.rootDir, "README.md");
+  }
+
+  get entryDir() {
+    return Context.srcDir;
+  }
+
+  get ngrokEnabled() {
+    return !!this.args.ngrok;
+  }
+
+  get hmrEnabled() {
+    return this.envVars.hmrEnabled;
+  }
+
+  get httpsEnabled() {
+    return !!this.args.useHttps;
+  }
+
+  get frontendEntryPath() {
+    const frontendEntryPath = path.join(this.entryDir, "index.tsx");
+
+    if (!fs.existsSync(frontendEntryPath)) {
+      throw new Error(
+        `Entry point for frontend does not exist: ${frontendEntryPath}`,
+      );
+    }
+
+    return frontendEntryPath;
+  }
+
+  get frontendUrl() {
+    return `${this.protocol}://localhost:${this.envVars.frontendPort}`;
+  }
+
+  get frontendPort() {
+    return this.envVars.frontendPort;
+  }
+
+  get developerBackendEntryPath(): string | undefined {
+    const developerBackendEntryPath = path.join(
+      Context.rootDir,
+      "backend",
+      "server.ts",
+    );
+
+    if (!fs.existsSync(developerBackendEntryPath)) {
+      return undefined;
+    }
+
+    return developerBackendEntryPath;
+  }
+
+  get backendUrl() {
+    return `${this.protocol}://localhost:${this.envVars.backendPort}`;
+  }
+
+  get backendHost() {
+    let backendHost = this.envVars.backendHost;
+
+    // if there's no custom URL provided by the developer, we fallback to our localhost backend
+    if (!backendHost || backendHost.trim() === "") {
+      backendHost = this.backendUrl;
+    }
+
+    return backendHost;
+  }
+
+  get backendPort() {
+    return this.envVars.backendPort;
+  }
+
+  get appOrigin(): string | undefined {
+    return this.envVars.appOrigin;
+  }
+
+  get appId(): string | undefined {
+    return this.envVars.appId;
+  }
+
+  private get protocol(): "https" | "http" {
+    return this.httpsEnabled ? "https" : "http";
+  }
+
+  private static get rootDir() {
+    return path.join(process.cwd());
+  }
+
+  private parseAndValidateEnvironmentVariables(): EnvVars {
+    const {
+      CANVA_FRONTEND_PORT,
+      CANVA_BACKEND_PORT,
+      CANVA_BACKEND_HOST,
+      CANVA_APP_ID,
+      CANVA_APP_ORIGIN,
+      CANVA_HMR_ENABLED,
+    } = this.env;
+
+    if (!CANVA_FRONTEND_PORT) {
+      throw new Error(
+        "CANVA_FRONTEND_PORT environment variable is not defined",
+      );
+    }
+
+    if (!CANVA_BACKEND_PORT) {
+      throw new Error("CANVA_BACKEND_PORT environment variable is not defined");
+    }
+
+    const envVars: EnvVars = {
+      frontendPort: parseInt(CANVA_FRONTEND_PORT, 10),
+      backendPort: parseInt(CANVA_BACKEND_PORT, 10),
+      hmrEnabled: CANVA_HMR_ENABLED?.toLowerCase().trim() === "true",
+      appId: CANVA_APP_ID,
+      appOrigin: CANVA_APP_ORIGIN,
+      backendHost: CANVA_BACKEND_HOST,
+    };
+
+    if (envVars.hmrEnabled && envVars.appOrigin == null) {
+      throw new Error(
+        "CANVA_HMR_ENABLED environment variable is TRUE, but CANVA_APP_ORIGIN is not set. Refer to the instructions in the README.md on configuring HMR.",
+      );
+    }
+
+    return envVars;
+  }
+}

package/templates/dam/scripts/start/start.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import * as yargs from "yargs";
+import { AppRunner } from "./app_runner";
+import { hideBin } from "yargs/helpers";
+import { Context } from "./context";
+
+const appRunner = new AppRunner();
+
+yargs(hideBin(process.argv))
+  .version(false)
+  .help()
+  .option("ngrok", {
+    description: "Run backend server via ngrok.",
+    type: "boolean",
+    // npm swallows command line args instead of forwarding to the script
+    default:
+      process.env.npm_config_ngrok?.toLocaleLowerCase().trim() === "true",
+  })
+  .option("use-https", {
+    description: "Start local development server on HTTPS.",
+    type: "boolean",
+    // npm swallows commands line args instead of forwarding to the script
+    default:
+      process.env.npm_config_use_https?.toLocaleLowerCase().trim() === "true",
+  })
+  .command(
+    "$0",
+    "Starts local development",
+    () => {},
+    (args) => {
+      const ctx = new Context(process.env, args);
+      appRunner.run(ctx);
+    },
+  )
+  .parse();

package/templates/dam/src/adapter.ts

@@ -0,0 +1,44 @@
+import type {
+  FindResourcesRequest,
+  FindResourcesResponse,
+} from "@canva/app-components";
+import { auth } from "@canva/user";
+
+export async function findResources(
+  request: FindResourcesRequest<"folder">,
+): Promise<FindResourcesResponse> {
+  const userToken = await auth.getCanvaUserToken();
+
+  // TODO: Update the API path to match your backend
+  // If using the backend example, the URL should be updated to `${BACKEND_HOST}/api/resources/find` to ensure requests are authenticated in production
+  const url = new URL(`${BACKEND_HOST}/resources/find`);
+
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${userToken}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(request),
+    });
+    const body = await response.json();
+
+    if (body.resources) {
+      return {
+        type: "SUCCESS",
+        resources: body.resources,
+        continuation: body.continuation,
+      };
+    }
+    return {
+      type: "ERROR",
+      errorCode: body.errorCode || "INTERNAL_ERROR",
+    };
+  } catch {
+    return {
+      type: "ERROR",
+      errorCode: "INTERNAL_ERROR",
+    };
+  }
+}

package/templates/dam/src/app.tsx

@@ -0,0 +1,147 @@
+import { useEffect, useState } from "react";
+import { SearchableListView } from "@canva/app-components";
+import { Alert, Box, Button, LoadingIndicator, Rows } from "@canva/app-ui-kit";
+import type { Authentication } from "@canva/user";
+import { auth } from "@canva/user";
+import { findResources } from "./adapter";
+import { config } from "./config";
+import * as styles from "./index.css";
+import "@canva/app-ui-kit/styles.css";
+
+type AuthenticationState =
+  | "authenticated"
+  | "not_authenticated"
+  | "checking"
+  | "cancelled"
+  | "error";
+
+/**
+ * This endpoint is defined in the ./backend/server.ts file. You need to
+ * register the endpoint in the Developer Portal before sending requests.
+ *
+ * BACKEND_HOST is configured in the root .env file, for more information,
+ * refer to the README.md.
+ */
+const AUTHENTICATION_CHECK_URL = `${BACKEND_HOST}/api/authentication/status`;
+
+const checkAuthenticationStatus = async (
+  auth: Authentication,
+): Promise<AuthenticationState> => {
+  /**
+   * Send a request to an endpoint that checks if the user is authenticated.
+   * This is example code, intended to convey the basic idea. When implementing this in your app, you might want more advanced checks.
+   *
+   * Note: You must register the provided endpoint via the Developer Portal.
+   */
+  try {
+    const token = await auth.getCanvaUserToken();
+    const res = await fetch(AUTHENTICATION_CHECK_URL, {
+      headers: {
+        Authorization: `Bearer ${token}`,
+      },
+      method: "POST",
+    });
+    const body = await res.json();
+
+    if (body?.isAuthenticated) {
+      return "authenticated";
+    } else {
+      return "not_authenticated";
+    }
+  } catch (error) {
+    // eslint-disable-next-line no-console
+    console.error(error);
+    return "error";
+  }
+};
+
+export function App() {
+  // Keep track of the user's authentication status.
+  const [authState, setAuthState] = useState<AuthenticationState>("checking");
+
+  useEffect(() => {
+    setAuthState("checking");
+    checkAuthenticationStatus(auth).then((status) => {
+      setAuthState(status);
+    });
+  }, []);
+
+  useEffect(() => {
+    if (authState === "not_authenticated") {
+      startAuthenticationFlow();
+    }
+  }, [authState]);
+
+  const startAuthenticationFlow = async () => {
+    try {
+      const response = await auth.requestAuthentication();
+      switch (response.status) {
+        case "COMPLETED":
+          setAuthState("authenticated");
+          break;
+        case "ABORTED":
+          // eslint-disable-next-line no-console
+          console.warn("Authentication aborted by user.");
+          setAuthState("cancelled");
+          break;
+        case "DENIED":
+          // eslint-disable-next-line no-console
+          console.warn("Authentication denied by user", response.details);
+          setAuthState("cancelled");
+          break;
+        default:
+          // eslint-disable-next-line no-console
+          console.log("Unknown auth state");
+          break;
+      }
+    } catch (e) {
+      // eslint-disable-next-line no-console
+      console.error(e);
+      setAuthState("error");
+    }
+  };
+
+  if (authState === "error") {
+    // eslint-disable-next-line no-console
+    console.warn(
+      "Warning: authentication not enabled on this app. Please enable auth with the instructions in README",
+    );
+    // Comment this next line out for production apps
+    setAuthState("authenticated");
+  }
+
+  // If user has denied or aborted auth flow
+  if (authState === "cancelled") {
+    return (
+      <Box paddingEnd="2u" height="full" className={styles.centerInPage}>
+        <Rows spacing="2u" align="center">
+          <Alert tone="critical">
+            Something went wrong while authenticating
+          </Alert>
+          <Button
+            variant="primary"
+            onClick={startAuthenticationFlow}
+            stretch={true}
+          >
+            Start authentication flow
+          </Button>
+        </Rows>
+      </Box>
+    );
+  }
+
+  return authState === "authenticated" ? (
+    <Box className={styles.rootWrapper}>
+      <SearchableListView config={config} findResources={findResources} />
+    </Box>
+  ) : (
+    <Box
+      width="full"
+      height="full"
+      paddingTop="1u"
+      className={styles.centerInPage}
+    >
+      <LoadingIndicator size="large" />
+    </Box>
+  );
+}

package/templates/dam/src/config.ts

@@ -0,0 +1,95 @@
+import type { Config } from "@canva/app-components";
+
+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",
+        },
+      ],
+    },
+  },
+  containerTypes: [
+    {
+      value: "folder",
+      label: "Folders",
+      listingSurfaces: [
+        { surface: "HOMEPAGE" },
+        {
+          surface: "CONTAINER",
+          parentContainerTypes: ["folder"],
+        },
+        { surface: "SEARCH" },
+      ],
+      searchInsideContainer: {
+        enabled: true,
+        placeholder: "Search for resources inside this folder",
+      },
+    },
+  ],
+  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.css

@@ -0,0 +1,10 @@
+.rootWrapper {
+  height: 100%;
+  overflow-y: hidden;
+}
+
+.centerInPage {
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+}

package/templates/dam/src/index.tsx

@@ -0,0 +1,22 @@
+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() {
+  root.render(
+    <AppI18nProvider>
+      <AppUiProvider>
+        <App />
+      </AppUiProvider>
+    </AppI18nProvider>,
+  );
+}
+
+render();
+
+if (module.hot) {
+  module.hot.accept("./app", render);
+}

package/templates/dam/tsconfig.json

@@ -0,0 +1,54 @@
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "es2018",
+      "es2019.array",
+      "es2019.object",
+      "es2019.string",
+      "es2020.promise",
+      "es2020.string"
+    ],
+    "types": ["node", "webpack-env", "jest"],
+    "composite": false,
+    "declaration": false,
+    "declarationMap": false,
+    "experimentalDecorators": true,
+    "importHelpers": true,
+    "noImplicitOverride": true,
+    "moduleResolution": "node",
+    "rootDir": ".",
+    "outDir": "dist",
+    "strict": true,
+    "skipLibCheck": true,
+    "target": "ES2019",
+    "sourceMap": true,
+    "inlineSources": true,
+    "module": "ESNext",
+    "noImplicitAny": false,
+    "removeComments": true,
+    "preserveConstEnums": true,
+    "allowSyntheticDefaultImports": true,
+    "baseUrl": "./",
+    "paths": {
+      "assets": ["./assets"],
+      "styles": ["./styles"]
+    }
+  },
+  "include": [
+    "./src/**/*",
+    "./backend/**/*",
+    "./utils/**/*",
+    "./scripts/**/*",
+    "./declarations/declarations.d.ts",
+    "./styles/**/*",
+    "./node_modules/@types/**/*"
+  ],
+  "ts-node": {
+    "compilerOptions": {
+      "module": "commonjs"
+    }
+  }
+}

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

@@ -0,0 +1,104 @@
+/* eslint-disable no-console */
+import * as express from "express";
+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");
+
+interface BaseServer {
+  app: express.Express;
+
+  /**
+   * Starts the server on the address or port provided
+   * @param address port number or string address or if left undefined express defaults to port 3000
+   */
+  start: (address: number | string | undefined) => void;
+}
+
+/**
+ * createBaseServer instantiates a customised express server with:
+ * - json body handling
+ * - health check endpoint
+ * - catchall endpoint
+ * - error handler catch route
+ * - process termination handling
+ * - debug logging - prefix starting your server with `DEBUG=server npm run XXX`
+ *
+ * @returns BaseServer object containing the express app and a start function
+ */
+export function createBaseServer(router: express.Router): BaseServer {
+  const SHOULD_ENABLE_HTTPS = process.env?.SHOULD_ENABLE_HTTPS === "true";
+  const HTTPS_CERT_FILE = process.env?.HTTPS_CERT_FILE;
+  const HTTPS_KEY_FILE = process.env?.HTTPS_KEY_FILE;
+
+  const app = express();
+  app.use(express.json());
+
+  // It can help to provide an extra layer of obsecurity to reduce server fingerprinting.
+  app.disable("x-powered-by");
+
+  // Health check endpoint
+  app.get("/healthz", (req, res: Response) => {
+    res.sendStatus(200);
+  });
+
+  // logging middleware
+  app.use((req: Request, res: Response, next: NextFunction) => {
+    serverDebug(`${new Date().toISOString()}: ${req.method} ${req.url}`);
+    next();
+  });
+
+  // Custom routes router
+  app.use(router);
+
+  // catch all router
+  app.all("*", (req, res) => {
+    res.status(404).send({
+      error: `unhandled '${req.method}' on '${req.url}'`,
+    });
+  });
+
+  // default error handler
+  app.use((err, req, res, next) => {
+    console.error(err.stack);
+    res.status(500).send({
+      error: "something went wrong",
+    });
+  });
+
+  let server;
+  if (SHOULD_ENABLE_HTTPS) {
+    if (!HTTPS_CERT_FILE || !HTTPS_KEY_FILE) {
+      throw new Error(
+        "Looks like you're running the example with --use-https flag, but SSL certificates haven't been generated. Please remove the .ssl/ folder and re-run the command again.",
+      );
+    }
+
+    server = https.createServer(
+      {
+        key: fs.readFileSync(HTTPS_KEY_FILE),
+        cert: fs.readFileSync(HTTPS_CERT_FILE),
+      },
+      app,
+    );
+  } else {
+    server = http.createServer(app);
+  }
+
+  return {
+    app,
+    start: (address: number | string | undefined) => {
+      console.log(`Listening on '${address}'`);
+      server.listen(address);
+      process.on("SIGTERM", () => {
+        serverDebug("SIGTERM signal received: closing HTTP server");
+        server.close(() => {
+          serverDebug("HTTP server closed");
+        });
+      });
+    },
+  };
+}

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

@@ -0,0 +1 @@
+export { createJwtMiddleware } from "./jwt_middleware";