@canva/cli 0.0.1-beta.3 → 0.0.1-beta.30

package/templates/data_connector/src/api/data_source.ts

@@ -0,0 +1,96 @@
+import type { DataTable } from "@canva/intents/data";
+import { toDataTable, type DataTableColumn } from "src/utils";
+
+/**
+ * This file defines types and classes related to data source configuration, fetching and outputting as a data table.
+ * When data is loaded, the app will save the data source config so that it can be queried again later to refresh the data.
+ * Strongly typed data sources are simple to reload and validate.
+ */
+
+/**
+ * The data source configuration represents all parameters that are needed to represent the data source so that it can be queried again later.
+ * This includes the schema, any filters that are applied to the data source, and any other parameters that are needed to fetch the data.
+ */
+export interface DataSourceConfig {
+  // a unique identifier for the data source that is used to associated the saved data source config with the data source handler
+  schema: string;
+}
+
+/**
+ * the API response item is a generic type that represents the data returned from the API
+ */
+export interface APIResponseItem {
+  id: string;
+}
+
+export class DataAPIError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "APIError";
+  }
+}
+
+/**
+ * The data source handler class defines a particular data source and how to fetch data from it.
+ * In this template, the two data sources are brand templates and designs. Each data source has its own handler.
+ * The handler defines the schema for the data source configuration (what filters are applied to get the requested data), the columns to display, and how to fetch data from the API.
+ * It also defines the UI for how this source is represented on the data source selection page and how to render the data source configuration page where any filters can be set.
+ */
+export class DataSourceHandler<
+  T extends DataSourceConfig,
+  R extends APIResponseItem,
+> {
+  schema: string;
+  constructor(
+    // the configuration for this data source. The default values will be overridden by the user setting filters, or on app launch if the previous state is restored
+    public sourceConfig: T,
+    // the columns to display in the data table output. In this template they are fixed, but they could be dynamic based on the data source and configuration
+    public columns: DataTableColumn<R>[],
+    // the fetch logic for turning the data source configuration into an array of data items to turn into a data table
+    public fetchData: (
+      source: T,
+      authToken: string,
+      rowLimit: number,
+      signal: AbortSignal | undefined,
+    ) => Promise<R[]>,
+    // the UI for the data source selection page. This is where the user chooses which data source to use.
+    public selectionPage: () => JSX.Element,
+    // the UI for the data source configuration page. This is where the user sets any filters or other parameters for the data source.
+    public configPage: (sourceConfig: T) => JSX.Element,
+  ) {
+    this.schema = sourceConfig.schema;
+  }
+
+  /**
+   * A type guard / type predicate to check if the data source configuration matches the schema of this data source handler.
+   * @param source the data source configuration to match against
+   * @returns
+   */
+  matchSource(source: DataSourceConfig): source is T {
+    return source.schema === this.schema;
+  }
+
+  /**
+   * The buildTable function is called to fetch data from the API and return it as a data table.
+   * @param source the data source configuration
+   * @param authToken the auth token to use for the API request
+   * @param rowLimit the maximum number of rows to return
+   * @param signal an optional abort signal to cancel the request
+   * @returns a data table with the data from the API
+   */
+  async fetchAndBuildTable(
+    source: T,
+    authToken: string,
+    rowLimit: number,
+    signal: AbortSignal | undefined,
+  ): Promise<DataTable> {
+    let apiData: R[];
+    try {
+      apiData = await this.fetchData(source, authToken || "", rowLimit, signal);
+    } catch {
+      throw new DataAPIError("Failed to fetch data from API");
+    }
+    // the toDataTable utility takes the API data and the configured columns and turns it into a data table
+    return toDataTable(apiData, this.columns, rowLimit);
+  }
+}

package/templates/data_connector/src/api/data_sources/designs.tsx

@@ -0,0 +1,253 @@
+/* eslint-disable formatjs/no-literal-string-in-object */
+import type { APIResponseItem, DataSourceConfig } from "../data_source";
+import { DataAPIError, DataSourceHandler } from "../data_source";
+import type { CanvaItemResponse } from "../connect_client";
+
+import type { SelectOption } from "@canva/app-ui-kit";
+import { Button, DatabaseIcon, HorizontalCard, Rows } from "@canva/app-ui-kit";
+import { useAppContext } from "src/context";
+import { Header } from "src/components";
+import {
+  ownershipFilter,
+  sortOrderField,
+} from "src/components/inputs/messages";
+import { useIntl } from "react-intl";
+import { SelectField } from "src/components/inputs/select_field";
+import { dateCell, numberCell, stringCell } from "src/utils";
+import { Paths } from "src/routes";
+import { useNavigate } from "react-router-dom";
+import { useState } from "react";
+
+export interface DesignsDataSource extends DataSourceConfig {
+  ownership: "any" | "owned" | "shared";
+  sort_by:
+    | "relevance"
+    | "modified_descending"
+    | "modified_ascending"
+    | "title_descending"
+    | "title_ascending";
+}
+
+export interface CanvaDesign extends APIResponseItem {
+  title: string;
+  created_at: number;
+  updated_at: number;
+  page_count: number;
+}
+
+export const designsSource = new DataSourceHandler<
+  DesignsDataSource,
+  CanvaDesign
+>(
+  {
+    schema: "designs/v1",
+    ownership: "any",
+    sort_by: "relevance",
+  },
+  [
+    {
+      label: "ID",
+      getValue: (design: CanvaDesign) => `ID ${design.id}`,
+      toCell: stringCell,
+    },
+    {
+      label: "Title",
+      getValue: "title",
+      toCell: stringCell,
+    },
+    {
+      label: "Created At",
+      getValue: "created_at",
+      toCell: dateCell,
+    },
+    {
+      label: "Updated At",
+      getValue: "updated_at",
+      toCell: dateCell,
+    },
+    {
+      label: "Page Count",
+      getValue: "page_count",
+      toCell: numberCell,
+    },
+  ],
+  (
+    source: DesignsDataSource,
+    authToken: string,
+    rowLimit: number,
+    signal: AbortSignal | undefined,
+  ) =>
+    getDesigns(authToken, rowLimit, signal, source.ownership, source.sort_by),
+  DesignSelection,
+  DesignsSourceConfig,
+);
+
+export async function getDesigns(
+  authToken: string,
+  rowLimit: number,
+  signal: AbortSignal | undefined,
+  ownership: string,
+  sort_by: string,
+  continuation?: string,
+  allItems: CanvaDesign[] = [],
+): Promise<CanvaDesign[]> {
+  const baseUrl = `https://api.canva.com/rest/v1/designs`;
+  const url = continuation
+    ? `${baseUrl}?continuation=${continuation}`
+    : `${baseUrl}?ownership=${ownership}&sort_by=${sort_by}`;
+
+  return fetch(url, {
+    headers: {
+      Authorization: `Bearer ${authToken}`,
+    },
+    signal,
+  })
+    .then((response) => {
+      if (!response.ok) {
+        throw new DataAPIError(
+          `Canva Connect response was not ok: ${response.statusText || response.status}`,
+        );
+      }
+      return response.json();
+    })
+    .then((data: CanvaItemResponse<CanvaDesign>) => {
+      const updatedItems = [...allItems, ...data.items];
+
+      if (data.continuation && updatedItems.length < rowLimit) {
+        return getDesigns(
+          authToken,
+          rowLimit,
+          signal,
+          ownership,
+          sort_by,
+          data.continuation,
+          updatedItems,
+        );
+      }
+
+      return updatedItems;
+    });
+}
+
+function DesignSelection() {
+  const intl = useIntl();
+  const { setDataSourceHandler } = useAppContext();
+  const navigate = useNavigate();
+
+  const title = intl.formatMessage({
+    defaultMessage: "Designs",
+    description:
+      "Main heading on the designs button displayed when selecting the import type.",
+  });
+
+  const description = intl.formatMessage({
+    defaultMessage: "Query designs",
+    description:
+      "Subtext on the designs selection button displayed when selecting the import type.",
+  });
+
+  const handleClick = () => {
+    setDataSourceHandler(
+      designsSource as unknown as DataSourceHandler<
+        DataSourceConfig,
+        APIResponseItem
+      >,
+    );
+    navigate(Paths.DATA_SOURCE_CONFIG);
+  };
+
+  return (
+    <HorizontalCard
+      key="designs"
+      title={title}
+      thumbnail={{ icon: () => <DatabaseIcon /> }}
+      onClick={handleClick}
+      description={description}
+      ariaLabel={description}
+    />
+  );
+}
+
+function DesignsSourceConfig(sourceConfig: DesignsDataSource) {
+  const intl = useIntl();
+  const { loadDataSource } = useAppContext();
+  const [ownership, setOwnership] = useState<string>(sourceConfig.ownership);
+  const [sortOrder, setSortOrder] = useState<string>(sourceConfig.sort_by);
+  const [isLoading, setIsLoading] = useState(false);
+
+  const loadDesigns = async () => {
+    setIsLoading(true);
+    loadDataSource("Canva Designs", {
+      schema: "designs/v1",
+      ownership,
+      sort_by: sortOrder,
+    } as DesignsDataSource).then(() => {
+      setIsLoading(false);
+    });
+  };
+
+  const ownershipOptions: SelectOption<string>[] = [
+    { value: "any", label: intl.formatMessage(ownershipFilter.any) },
+    { value: "owned", label: intl.formatMessage(ownershipFilter.owned) },
+    { value: "shared", label: intl.formatMessage(ownershipFilter.shared) },
+  ];
+
+  const sortOrderOptions: SelectOption<string>[] = [
+    { value: "relevance", label: intl.formatMessage(sortOrderField.relevance) },
+    {
+      value: "modified_descending",
+      label: intl.formatMessage(sortOrderField.modifiedDesc),
+    },
+    {
+      value: "modified_ascending",
+      label: intl.formatMessage(sortOrderField.modifiedAsc),
+    },
+    {
+      value: "title_descending",
+      label: intl.formatMessage(sortOrderField.titleDesc),
+    },
+    {
+      value: "title_ascending",
+      label: intl.formatMessage(sortOrderField.titleAsc),
+    },
+  ];
+
+  return (
+    <div>
+      <Rows spacing="2u">
+        <Header
+          title={intl.formatMessage({
+            defaultMessage: "Canva Designs",
+            description: "The header text for the designs data source",
+          })}
+          showBack={true}
+        />
+
+        <SelectField
+          label={intl.formatMessage(ownershipFilter.label)}
+          options={ownershipOptions}
+          value={ownership}
+          onChange={setOwnership}
+        />
+        <SelectField
+          label={intl.formatMessage(sortOrderField.label)}
+          options={sortOrderOptions}
+          value={sortOrder}
+          onChange={setSortOrder}
+        />
+        <Button
+          variant="primary"
+          loading={isLoading}
+          onClick={async () => {
+            loadDesigns();
+          }}
+        >
+          {intl.formatMessage({
+            defaultMessage: "Load Designs",
+            description: "Button for saving and applying the query filter",
+          })}
+        </Button>
+      </Rows>
+    </div>
+  );
+}

package/templates/data_connector/src/api/data_sources/index.ts

@@ -0,0 +1,4 @@
+import { designsSource } from "./designs";
+import { brandTemplatesSource } from "./templates";
+
+export const DATA_SOURCES = [designsSource, brandTemplatesSource];

package/templates/data_connector/src/api/data_sources/templates.tsx

@@ -0,0 +1,287 @@
+/* eslint-disable formatjs/no-literal-string-in-object */
+import { useAppContext } from "src/context";
+import type { APIResponseItem, DataSourceConfig } from "../data_source";
+import { DataAPIError, DataSourceHandler } from "../data_source";
+import type { CanvaItemResponse } from "../connect_client";
+import { dateCell, stringCell } from "src/utils";
+import type { SelectOption } from "@canva/app-ui-kit";
+import {
+  Button,
+  HorizontalCard,
+  Rows,
+  TableMergedHeaderCellsIcon,
+} from "@canva/app-ui-kit";
+import { useIntl } from "react-intl";
+import {
+  datasetFilter,
+  ownershipFilter,
+  sortOrderField,
+} from "src/components/inputs/messages";
+import { SelectField } from "src/components/inputs/select_field";
+import { Header } from "src/components";
+import { useNavigate } from "react-router-dom";
+import { Paths } from "src/routes";
+import { useState } from "react";
+
+export interface BrandTemplatesDataSource extends DataSourceConfig {
+  dataset: "any" | "non_empty" | "empty";
+  ownership: "any" | "owned" | "shared";
+  sort_by:
+    | "relevance"
+    | "modified_descending"
+    | "modified_ascending"
+    | "title_descending"
+    | "title_ascending";
+}
+
+export interface CanvaBrandTemplate extends APIResponseItem {
+  title: string;
+  created_at: number;
+  updated_at: number;
+  view_url: string;
+  create_url: string;
+}
+
+export const brandTemplatesSource = new DataSourceHandler<
+  BrandTemplatesDataSource,
+  CanvaBrandTemplate
+>(
+  {
+    schema: "brand_templates/v1",
+    dataset: "any",
+    ownership: "any",
+    sort_by: "relevance",
+  },
+  [
+    {
+      label: "ID",
+      getValue: (template: CanvaBrandTemplate) => `ID ${template.id}`,
+      toCell: stringCell,
+    },
+    {
+      label: "Title",
+      getValue: "title",
+      toCell: stringCell,
+    },
+    {
+      label: "Created At",
+      getValue: "created_at",
+      toCell: dateCell,
+    },
+    {
+      label: "Updated At",
+      getValue: "updated_at",
+      toCell: dateCell,
+    },
+    {
+      label: "View URL",
+      getValue: "view_url",
+      toCell: stringCell,
+    },
+    {
+      label: "Create URL",
+      getValue: "create_url",
+      toCell: stringCell,
+    },
+  ],
+  (
+    source: BrandTemplatesDataSource,
+    authToken: string,
+    rowLimit: number,
+    signal: AbortSignal | undefined,
+  ) =>
+    getBrandTemplates(
+      authToken,
+      rowLimit,
+      signal,
+      source.dataset,
+      source.ownership,
+      source.sort_by,
+    ),
+  BrandTemplatesSelection,
+  BrandTemplatesSourceConfig,
+);
+
+export async function getBrandTemplates(
+  authToken: string,
+  rowLimit: number,
+  signal: AbortSignal | undefined,
+  ownership: string,
+  dataset: string,
+  sort_by: string,
+  continuation?: string,
+  allItems: CanvaBrandTemplate[] = [],
+): Promise<CanvaBrandTemplate[]> {
+  const baseUrl = `https://api.canva.com/rest/v1/brand-templates`;
+  const url = continuation
+    ? `${baseUrl}?continuation=${continuation}`
+    : `${baseUrl}?ownership=${ownership}&dataset=${dataset}&sort_by=${sort_by}`;
+
+  return fetch(url, {
+    headers: {
+      Authorization: `Bearer ${authToken}`,
+    },
+    signal,
+  })
+    .then((response) => {
+      if (!response.ok) {
+        throw new DataAPIError(
+          `Canva Connect response was not ok: ${response.statusText || response.status}`,
+        );
+      }
+      return response.json();
+    })
+    .then((data: CanvaItemResponse<CanvaBrandTemplate>) => {
+      const updatedItems = [...allItems, ...data.items];
+
+      if (data.continuation && updatedItems.length < rowLimit) {
+        return getBrandTemplates(
+          authToken,
+          rowLimit,
+          signal,
+          ownership,
+          dataset,
+          sort_by,
+          data.continuation,
+          updatedItems,
+        );
+      }
+
+      return updatedItems;
+    });
+}
+
+function BrandTemplatesSelection() {
+  const intl = useIntl();
+  const { setDataSourceHandler } = useAppContext();
+  const navigate = useNavigate();
+
+  const title = intl.formatMessage({
+    defaultMessage: "Brand Templates",
+    description:
+      "Main heading on the brand templates button displayed when selecting the import type.",
+  });
+
+  const description = intl.formatMessage({
+    defaultMessage: "Query brand templates",
+    description:
+      "Subtext on the brand templates button displayed when selecting the import type.",
+  });
+
+  const handleClick = () => {
+    setDataSourceHandler(
+      brandTemplatesSource as unknown as DataSourceHandler<
+        DataSourceConfig,
+        APIResponseItem
+      >,
+    );
+    navigate(Paths.DATA_SOURCE_CONFIG);
+  };
+
+  return (
+    <HorizontalCard
+      key="brand-templates"
+      title={title}
+      thumbnail={{ icon: () => <TableMergedHeaderCellsIcon /> }}
+      onClick={handleClick}
+      description={description}
+      ariaLabel={description}
+    />
+  );
+}
+
+function BrandTemplatesSourceConfig(sourceConfig: BrandTemplatesDataSource) {
+  const { loadDataSource } = useAppContext();
+  const [ownership, setOwnership] = useState<string>(sourceConfig.ownership);
+  const [sortOrder, setSortOrder] = useState<string>(sourceConfig.sort_by);
+  const [dataset, setDataset] = useState<string>(sourceConfig.dataset);
+  const [isLoading, setIsLoading] = useState(false);
+  const intl = useIntl();
+
+  const loadTemplates = async () => {
+    loadDataSource("Canva Brand Templates", {
+      schema: "brand_templates/v1",
+      ownership,
+      dataset,
+      sort_by: sortOrder,
+    } as BrandTemplatesDataSource).then(() => {
+      setIsLoading(false);
+    });
+  };
+
+  const ownershipOptions: SelectOption<string>[] = [
+    { value: "any", label: intl.formatMessage(ownershipFilter.any) },
+    { value: "owned", label: intl.formatMessage(ownershipFilter.owned) },
+    { value: "shared", label: intl.formatMessage(ownershipFilter.shared) },
+  ];
+
+  const sortOrderOptions: SelectOption<string>[] = [
+    { value: "relevance", label: intl.formatMessage(sortOrderField.relevance) },
+    {
+      value: "modified_descending",
+      label: intl.formatMessage(sortOrderField.modifiedDesc),
+    },
+    {
+      value: "modified_ascending",
+      label: intl.formatMessage(sortOrderField.modifiedAsc),
+    },
+    {
+      value: "title_descending",
+      label: intl.formatMessage(sortOrderField.titleDesc),
+    },
+    {
+      value: "title_ascending",
+      label: intl.formatMessage(sortOrderField.titleAsc),
+    },
+  ];
+
+  const datasetOptions: SelectOption<string>[] = [
+    { value: "any", label: intl.formatMessage(datasetFilter.any) },
+    { value: "non_empty", label: intl.formatMessage(datasetFilter.nonEmpty) },
+    { value: "empty", label: intl.formatMessage(datasetFilter.empty) },
+  ];
+
+  return (
+    <div>
+      <Header
+        title={intl.formatMessage({
+          defaultMessage: "Canva Brand Templates",
+          description: "The header text for the brand templates data source",
+        })}
+        showBack={true}
+      />
+      <Rows spacing="2u">
+        <SelectField
+          label={intl.formatMessage(ownershipFilter.label)}
+          options={ownershipOptions}
+          value={ownership}
+          onChange={setOwnership}
+        />
+        <SelectField
+          label={intl.formatMessage(datasetFilter.label)}
+          options={datasetOptions}
+          value={dataset}
+          onChange={setDataset}
+        />
+        <SelectField
+          label={intl.formatMessage(sortOrderField.label)}
+          options={sortOrderOptions}
+          value={sortOrder}
+          onChange={setSortOrder}
+        />
+        <Button
+          variant="primary"
+          loading={isLoading}
+          onClick={async () => {
+            loadTemplates();
+          }}
+        >
+          {intl.formatMessage({
+            defaultMessage: "Load Templates",
+            description: "Button for saving and applying the query filter",
+          })}
+        </Button>
+      </Rows>
+    </div>
+  );
+}

package/templates/data_connector/src/api/fetch_data_table.ts

@@ -0,0 +1,51 @@
+import type {
+  FetchDataTableParams,
+  FetchDataTableResult,
+} from "@canva/intents/data";
+import { DATA_SOURCES } from "./data_sources";
+import {
+  appError,
+  completeDataTable,
+  outdatedSourceRef,
+  remoteRequestFailed,
+} from "src/utils/fetch_result";
+import { DataAPIError } from ".";
+
+/**
+ * This function handles parsing the data fetch parameters and calling the appropriate handler for the data source.
+ * @param fetchParams
+ * @param authToken
+ * @returns
+ */
+export const buildDataTableResult = async (
+  fetchParams: FetchDataTableParams,
+  authToken?: string,
+): Promise<FetchDataTableResult> => {
+  const source = JSON.parse(fetchParams.dataSourceRef.source);
+  const rowLimit = fetchParams.limit.row - 1; // -1 for the header row
+
+  const dataHandler = DATA_SOURCES.find((handler) =>
+    handler.matchSource(source),
+  );
+  if (!dataHandler) {
+    // the configured source does not match the expected data source type
+    // return an error result which will prompt the user to reconfigure the data source
+    return outdatedSourceRef();
+  }
+  try {
+    const dataTable = await dataHandler.fetchAndBuildTable(
+      source,
+      authToken || "",
+      rowLimit,
+      fetchParams.signal,
+    );
+    return completeDataTable(dataTable);
+  } catch (error) {
+    if (error instanceof DataAPIError) {
+      return remoteRequestFailed();
+    }
+    return appError(
+      error instanceof Error ? error.message : "An unknown error occurred",
+    );
+  }
+};

package/templates/data_connector/src/api/index.ts

@@ -0,0 +1,4 @@
+export * from "./connect_client";
+export * from "./fetch_data_table";
+export * from "./data_source";
+export * from "./oauth";

package/templates/data_connector/src/api/oauth.ts

@@ -0,0 +1,8 @@
+/**
+ * The scopes to request as part of the OAuth flow.
+ * These scopes are required to read the user's designs and brand templates.
+ *
+ * @see https://www.canva.dev/docs/apps/authenticating-users/oauth/#overview - for more information about using the @canva/user package to support OAuth login.
+ * @see https://www.canva.dev/docs/connect/appendix/scopes/ - for a full list of Canva Connect API scopes.
+ */
+export const scope = new Set(["design:meta:read", "brandtemplate:meta:read"]);