@canva/cli 0.0.1-beta.1

package/templates/gen_ai/src/api/api.ts

@@ -0,0 +1,228 @@
+import { auth } from "@canva/user";
+import { POLLING_INTERVAL_IN_SECONDS } from "src/config";
+
+/**
+ * Represents the structure of an image.
+ */
+export interface ImageType {
+  /** The label of the image. */
+  label: string;
+  /** Information about the full-size version of the image. */
+  fullsize: { width: number; height: number; url: string };
+  /** Information about the thumbnail version of the image. */
+  thumbnail: { width: number; height: number; url: string };
+}
+
+/**
+ * Represents the result of generating images.
+ */
+interface ImageGenerationResult {
+  /** An array of generated images. */
+  images: ImageType[];
+  /** The remaining credits. */
+  credits: number;
+}
+
+interface ImageGenerationJobStatusResponse {
+  status: "completed" | "processing";
+  images: ImageType[];
+  credits: number;
+}
+
+interface QueueImageGenerationResponse {
+  jobId: string;
+}
+
+/**
+ * Represents the result of retrieving remaining credits.
+ */
+interface RemainingCreditsResult {
+  /** The remaining credits. */
+  credits: number;
+}
+
+/**
+ * Represents the result of retrieving the logged in status of the user.
+ */
+export type LoggedInState =
+  | "authenticated"
+  | "not_authenticated"
+  | "checking"
+  | "error";
+
+const endpoints = {
+  queueImageGeneration: "/api/queue-image-generation",
+  getImageGenerationJobStatus: "/api/job-status",
+  cancelImageGenerationJob: "/api/job-status/cancel",
+  getRemainingCredits: "/api/credits",
+  purchaseCredits: "/api/purchase-credits",
+  getLoggedInStatus: "/api/authentication/status",
+};
+
+/**
+ * queues image generation based on the provided prompt and number of images.
+ * @param {Object} options - The options for generating images.
+ * @param {string} options.prompt - The prompt for generating images.
+ * @param {number} options.numberOfImages - The number of images to generate.
+ * @returns {Promise<QueueImageGenerationResponse>} A promise that resolves to the created job ID.
+ */
+export const queueImageGeneration = async ({
+  prompt,
+  numberOfImages,
+}: {
+  prompt: string;
+  numberOfImages: number;
+}): Promise<QueueImageGenerationResponse> => {
+  const url = new URL(endpoints.queueImageGeneration, BACKEND_HOST);
+  url.searchParams.append("count", numberOfImages.toString());
+  url.searchParams.append("prompt", prompt);
+
+  const result: QueueImageGenerationResponse = await sendRequest(url);
+
+  return result;
+};
+
+/**
+ * Retrieves the status of an image generation job.
+ * @param {string} jobId - The ID of the job to retrieve status for.
+ * @returns {Promise<ImageGenerationResult>} A promise that resolves to the image generation result.
+ */
+export const getImageGenerationJobStatus = async ({
+  jobId,
+}: {
+  jobId: string;
+}): Promise<ImageGenerationResult> => {
+  const url = new URL(endpoints.getImageGenerationJobStatus, BACKEND_HOST);
+  url.searchParams.append("jobId", jobId);
+
+  // Define a maximum number of polling attempts
+  const maxAttempts = 10;
+  let attempts = 0;
+
+  while (attempts < maxAttempts) {
+    try {
+      const response = (await sendRequest(
+        url,
+      )) as ImageGenerationJobStatusResponse;
+      if (response.status === "completed") {
+        return { images: response.images, credits: response.credits };
+      } else if (response.status === "processing") {
+        // Job is still processing, wait and continue polling
+        await new Promise((resolve) =>
+          setTimeout(resolve, POLLING_INTERVAL_IN_SECONDS * 1000),
+        );
+        attempts++;
+      } else if (response.status === "cancelled") {
+        throw new Error("Job not found");
+      }
+    } catch (error) {
+      // Handle errors here
+      throw new Error(`Error while polling job status ${error}`);
+    }
+  }
+
+  throw new Error("Maximum polling attempts reached");
+};
+
+/**
+ * Cancels an image generation job based on the provided job ID.
+ * @param {string} jobId - The ID of the job to cancel.
+ * @returns {Promise<void>} - A promise that resolves if the job is successfully cancelled, otherwise rejects with an error.
+ */
+export const cancelImageGenerationJob = async (
+  jobId: string,
+): Promise<void> => {
+  const url = new URL(endpoints.cancelImageGenerationJob, BACKEND_HOST);
+  url.searchParams.append("jobId", jobId);
+
+  try {
+    await sendRequest(url, {
+      method: "POST",
+    });
+  } catch {
+    throw new Error("Failed to cancel job.");
+  }
+};
+
+/**
+ * Retrieves the remaining credits.
+ * @returns {Promise<RemainingCreditsResult>} - A promise that resolves to the remaining credits.
+ */
+export const getRemainingCredits =
+  async (): Promise<RemainingCreditsResult> => {
+    const url = new URL(endpoints.getRemainingCredits, BACKEND_HOST);
+
+    const result: RemainingCreditsResult = await sendRequest(url);
+
+    return result;
+  };
+
+/**
+ * Purchases credits for the user.
+ * @returns {Promise<RemainingCreditsResult>} - A promise that resolves to the remaining credits after purchasing.
+ */
+export const purchaseCredits = async (): Promise<RemainingCreditsResult> => {
+  const url = new URL(endpoints.purchaseCredits, BACKEND_HOST);
+
+  const result: RemainingCreditsResult = await sendRequest(url, {
+    method: "POST",
+  });
+
+  return result;
+};
+
+/**
+ * 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.
+ */
+export const checkAuthenticationStatus = async (): Promise<LoggedInState> => {
+  try {
+    const url = new URL(endpoints.getLoggedInStatus, BACKEND_HOST);
+    const result: { isAuthenticated: string } = await sendRequest(url, {
+      method: "POST",
+    });
+
+    if (result?.isAuthenticated) {
+      return "authenticated";
+    } else {
+      return "not_authenticated";
+    }
+  } catch (error) {
+    // eslint-disable-next-line no-console
+    console.error(error);
+    return "error";
+  }
+};
+
+/**
+ * Sends a request to the specified URL with authorization headers.
+ * @param {URL} url - The URL to send the request to.
+ * @param {RequestInit} [options] - Optional fetch options to be passed to the fetch function.
+ * @returns {Promise<Object>} - A promise that resolves to the response body.
+ */
+const sendRequest = async <T>(url: URL, options?: RequestInit): Promise<T> => {
+  const token = await auth.getCanvaUserToken();
+  const res = await fetch(url, {
+    headers: {
+      ...options?.headers,
+      Authorization: `Bearer ${token}`,
+    },
+    ...options,
+  });
+
+  if (!res.ok) {
+    throw new Error(`Request failed with status ${res.status}`);
+  }
+
+  // Check Content-Type header to determine how to parse response body
+  const contentType = res.headers.get("content-type");
+  if (contentType && contentType.includes("application/json")) {
+    // Parse response body as JSON
+    return (await res.json()) as T;
+  } else {
+    // Parse response body as text
+    return (await res.text()) as unknown as T;
+  }
+};

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

@@ -0,0 +1 @@
+export * from "./api";

package/templates/gen_ai/src/app.tsx

@@ -0,0 +1,13 @@
+import { Outlet } from "react-router-dom";
+import { Rows } from "@canva/app-ui-kit";
+import { Footer } from "./components";
+import * as styles from "styles/components.css";
+
+export const App = () => (
+  <div className={styles.scrollContainer}>
+    <Rows spacing="3u">
+      <Outlet />
+      <Footer />
+    </Rows>
+  </div>
+);

package/templates/gen_ai/src/components/app_error.tsx

@@ -0,0 +1,18 @@
+import { Alert } from "@canva/app-ui-kit";
+import { useAppContext } from "src/context";
+
+export const AppError = () => {
+  const { loadingApp, creditsError, appError, setAppError } = useAppContext();
+  if (loadingApp || (!appError && !creditsError)) {
+    return null;
+  }
+
+  return (
+    <Alert
+      tone="critical"
+      onDismiss={creditsError ? undefined : () => setAppError("")}
+    >
+      {creditsError || appError}
+    </Alert>
+  );
+};

package/templates/gen_ai/src/components/footer.messages.ts

@@ -0,0 +1,53 @@
+import { defineMessages } from "react-intl";
+
+export const FooterMessages = defineMessages({
+  /** Indicates actions users can take or instructions provided to the user. */
+  generateAgain: {
+    defaultMessage: "Generate again",
+    description:
+      "A button label to generate another image based on the previous prompt",
+  },
+  generateImage: {
+    defaultMessage: "Generate image",
+    description: "A button label to generate an image from a prompt",
+  },
+  signUpOrLogin: {
+    defaultMessage: "Sign up or log in to generate",
+    description:
+      "A button label to sign up or log in, before the user is able to generate an image",
+  },
+  purchaseMoreCredits: {
+    defaultMessage: "Purchase more credits",
+    description:
+      "A button label to open a page where the user can purchase more credits",
+  },
+  startOver: {
+    defaultMessage: "Start over",
+    description: "A button label to start the image generation process over",
+  },
+
+  /** Messages related to handling errors that occur during operations. */
+  appErrorGeneratingImagesFailed: {
+    defaultMessage: "Generating images has failed, please try again.",
+    description:
+      "A message to indicate that generating images has failed, but the user is able to make another attempt",
+  },
+
+  /** Messages related to prompts and user input validation. */
+  promptMissingErrorMessage: {
+    defaultMessage: "Please describe what you want to create",
+    description:
+      "An error message to indicate that the user did not supply a prompt to generate an image, and this has to be provided before generating",
+  },
+  promptNoCreditsRemaining: {
+    defaultMessage: "No credits remaining.",
+    description:
+      "A message to indicate that the user has no credits remaining, and is unable to generate an image",
+  },
+  promptObscenityErrorMessage: {
+    defaultMessage:
+      "Something you typed may result in content that doesn’t meet our policies.",
+    description:
+      "An error message to indicate that the user typed something that may result in content that for example could be offensive or violent",
+  },
+});

package/templates/gen_ai/src/components/footer.tsx

@@ -0,0 +1,157 @@
+import { useNavigate, useLocation } from "react-router-dom";
+import { Rows, Button } from "@canva/app-ui-kit";
+import { queueImageGeneration, purchaseCredits } from "src/api";
+import { LoggedInStatus, RemainingCredits } from "src/components";
+import { NUMBER_OF_IMAGES_TO_GENERATE } from "src/config";
+import { useAppContext } from "src/context";
+import { Paths } from "src/routes";
+import { useAuth } from "src/services";
+import { getObsceneWords } from "src/utils";
+import { useIntl } from "react-intl";
+import { FooterMessages as Messages } from "./footer.messages";
+
+export const Footer = () => {
+  const navigate = useNavigate();
+  const { pathname } = useLocation();
+  const { requestAuthentication } = useAuth();
+  const isRootRoute = pathname === Paths.HOME;
+  const {
+    loggedInState,
+    setAppError,
+    promptInput,
+    setPromptInput,
+    setPromptInputError,
+    loadingApp,
+    isLoadingImages,
+    setJobId,
+    setIsLoadingImages,
+    remainingCredits,
+    setRemainingCredits,
+  } = useAppContext();
+  const intl = useIntl();
+
+  const hasRemainingCredits = remainingCredits > 0;
+
+  const isCreditRemaining = () => {
+    if (!hasRemainingCredits) {
+      setPromptInputError(
+        intl.formatMessage(Messages.promptNoCreditsRemaining),
+      );
+      return false;
+    }
+    return true;
+  };
+
+  const isPromptInputFilled = () => {
+    if (!promptInput) {
+      setPromptInputError(
+        intl.formatMessage(Messages.promptMissingErrorMessage),
+      );
+      return false;
+    }
+    return true;
+  };
+
+  const isPromptInputClean = () => {
+    const obsceneWords = getObsceneWords(promptInput);
+    if (obsceneWords.length > 0) {
+      setPromptInputError(
+        intl.formatMessage(Messages.promptObscenityErrorMessage),
+      );
+      return false;
+    }
+    return true;
+  };
+
+  const onGenerateClick = async () => {
+    if (
+      !isCreditRemaining() ||
+      !isPromptInputFilled() ||
+      !isPromptInputClean()
+    ) {
+      return;
+    }
+
+    setIsLoadingImages(true);
+    try {
+      const { jobId } = await queueImageGeneration({
+        prompt: promptInput,
+        numberOfImages: NUMBER_OF_IMAGES_TO_GENERATE,
+      });
+
+      setJobId(jobId);
+    } catch {
+      setAppError(intl.formatMessage(Messages.appErrorGeneratingImagesFailed));
+    }
+    navigate(Paths.RESULTS);
+  };
+
+  const onSignUpOrLogInClick = async () => {
+    await requestAuthentication();
+  };
+
+  const onPurchaseMoreCredits = async () => {
+    const { credits } = await purchaseCredits();
+
+    setRemainingCredits(credits);
+  };
+
+  const reset = () => {
+    setPromptInput("");
+    navigate(Paths.HOME);
+  };
+
+  const footerButtons = [
+    {
+      variant: "primary" as const,
+      onClick: onGenerateClick,
+      value: isRootRoute
+        ? intl.formatMessage(Messages.generateImage)
+        : intl.formatMessage(Messages.generateAgain),
+      visible: hasRemainingCredits,
+    },
+    {
+      variant: "primary" as const,
+      onClick: onSignUpOrLogInClick,
+      value: intl.formatMessage(Messages.signUpOrLogin),
+      visible: loggedInState === "not_authenticated" && !hasRemainingCredits,
+    },
+    {
+      variant: "primary" as const,
+      onClick: onPurchaseMoreCredits,
+      value: intl.formatMessage(Messages.purchaseMoreCredits),
+      visible: loggedInState === "authenticated" && !hasRemainingCredits,
+    },
+    {
+      variant: "secondary" as const,
+      onClick: reset,
+      value: intl.formatMessage(Messages.startOver),
+      visible: !isRootRoute,
+    },
+  ];
+
+  if (isLoadingImages) {
+    return null;
+  }
+
+  return (
+    <Rows spacing="1u">
+      {footerButtons.map(
+        ({ visible, variant, onClick, value }) =>
+          visible && (
+            <Button
+              key={value}
+              variant={variant}
+              onClick={onClick}
+              loading={loadingApp}
+              stretch={true}
+            >
+              {value}
+            </Button>
+          ),
+      )}
+      <RemainingCredits />
+      <LoggedInStatus />
+    </Rows>
+  );
+};

package/templates/gen_ai/src/components/image_grid.tsx

@@ -0,0 +1,96 @@
+import { Grid, ImageCard, Rows, Text } from "@canva/app-ui-kit";
+import type { QueuedImage } from "@canva/asset";
+import { upload } from "@canva/asset";
+import { addNativeElement, ui } from "@canva/design";
+import type { ImageType } from "src/api";
+import { useAppContext } from "src/context";
+import * as styles from "styles/utils.css";
+import { FormattedMessage } from "react-intl";
+
+const THUMBNAIL_HEIGHT = 150;
+
+const uploadImage = async (image: ImageType): Promise<QueuedImage> => {
+  // Upload the image using @canva/asset.
+  const queuedImage = await upload({
+    type: "IMAGE",
+    mimeType: "image/jpeg",
+    thumbnailUrl: image.thumbnail.url,
+    url: image.fullsize.url,
+    width: image.fullsize.width,
+    height: image.fullsize.height,
+  });
+
+  return queuedImage;
+};
+
+export const ImageGrid = () => {
+  const { generatedImages } = useAppContext();
+
+  const onDragStart = async (
+    event: React.DragEvent<HTMLElement>,
+    image: ImageType,
+  ) => {
+    const parentNode = event.currentTarget.parentElement;
+    try {
+      parentNode?.classList.add(styles.hidden);
+
+      await ui.startDrag(event, {
+        type: "IMAGE",
+        resolveImageRef: () => uploadImage(image),
+        previewUrl: image.thumbnail.url,
+        previewSize: {
+          width: image.thumbnail.width,
+          height: image.thumbnail.height,
+        },
+        fullSize: {
+          width: image.fullsize.width,
+          height: image.fullsize.height,
+        },
+      });
+    } finally {
+      parentNode?.classList.remove(styles.hidden);
+    }
+  };
+
+  const onImageClick = async (image: ImageType) => {
+    const queuedImage = await uploadImage(image);
+
+    await addNativeElement({
+      type: "IMAGE",
+      ref: queuedImage.ref,
+    });
+  };
+
+  const intl = useIntl();
+
+  return (
+    <Rows spacing="1u">
+      <Text size="medium" variant="bold">
+        <FormattedMessage
+          defaultMessage="Select or drag to add to design"
+          description="Instruction to the user on how they can add the generated image to their design"
+        />
+      </Text>
+      <Grid columns={2} spacing="2u">
+        {generatedImages.map((image, index) => (
+          <ImageCard
+            key={index}
+            thumbnailUrl={image.thumbnail.url}
+            onClick={() => onImageClick(image)}
+            ariaLabel={intl.formatMessage({
+              defaultMessage: "Add image to design",
+              description:
+                "Aria label for the image card. When the image card is pressed, it will add the image to the design",
+            })}
+            alt={image.label}
+            thumbnailHeight={THUMBNAIL_HEIGHT}
+            borderRadius="standard"
+            onDragStart={(event: React.DragEvent<HTMLElement>) =>
+              onDragStart(event, image)
+            }
+          />
+        ))}
+      </Grid>
+    </Rows>
+  );
+};

package/templates/gen_ai/src/components/index.ts

@@ -0,0 +1,8 @@
+export * from "./app_error";
+export * from "./footer";
+export * from "./image_grid";
+export * from "./loading_results";
+export * from "./logged_in_status";
+export * from "./prompt_input";
+export * from "./report_box";
+export * from "./remaining_credits";