URL expander intent

// For usage information, see the README.md file.
import type {
  ExpandUrlRequest,
  ExpandUrlResponse,
  GetContentRequest,
  GetContentResponse,
  UrlExpanderIntent,
} from "@canva/intents/asset";
import { prepareUrlExpander } from "@canva/intents/asset";
import { exampleAssets } from "./asset";
import { mapBaseAssetToURLExpanderAsset } from "./mapper";

/**
 * Retrieves the reference of an asset by an URL.
 *
 * @param request - The request object containing the an URL, and the requestConnection callback.
 * @returns A promise resolving to the reference content or an error status
 */
async function expandUrl(
  request: ExpandUrlRequest,
): Promise<ExpandUrlResponse> {
  /**
   * If your app requires OAuth to access user data, you can use the auth and oauth module to handle authentication.
   * Here's an example of how to request a connection and authorization:
   * ```
   * if (!await oauth.getAccessToken()) {
   *  await request.requestConnection();
   *  await oauth.requestAuthorization();
   * }
   * ```
   * Please await the completion of requests before proceeding with any further logic.
   * RequestConnection allows the user trigger the connection flow by themselves through the Canva UI.
   */
  const foundAsset = exampleAssets.find((a) => a.url === request.url);

  if (foundAsset) {
    return {
      status: "completed",
      result: {
        ref: {
          type: "asset",
          id: foundAsset.id,
          name: foundAsset.name,
          iconUrl: foundAsset.url,
          description: foundAsset.mimeType,
        },
      },
    };
  } else {
    return { status: "not_found" };
  }
}

/**
 * Retrieves the full content of an asset by its reference ID.
 *
 * @param request - The request object containing the asset reference, and the requestConnection callback.
 * @returns A promise resolving to the asset content or an error status
 */
async function getContent(
  request: GetContentRequest,
): Promise<GetContentResponse> {
  const { ref } = request;

  /**
   * Implement a similar OAuth flow as shown in the expandUrl handler,
   * to ensure you can retrieve the token when getContent is being called independently.
   * Please await the completion of requests before proceeding with any further logic.
   * RequestConnection allows the user trigger the connection flow by themselves through the Canva UI.
   */

  const foundAsset = exampleAssets.find((asset) => asset.id === ref.id);

  if (!foundAsset) {
    return {
      status: "app_error",
      message: "Asset not found",
    };
  }

  return {
    status: "completed",
    result: {
      type: "asset",
      asset: mapBaseAssetToURLExpanderAsset(foundAsset),
    },
  };
}

// Configure the URL Expander intent with required callbacks
const urlExpander: UrlExpanderIntent = {
  expandUrl,
  getContent,
};
prepareUrlExpander(urlExpander);

import type {
  Asset,
  AudioAsset,
  DocumentAsset,
  ImageAsset,
  SheetAsset,
  VideoAsset,
} from "@canva/intents/asset";
import type { BaseAsset } from "./asset";

export function mapBaseAssetToURLExpanderAsset(asset: BaseAsset): Asset {
  switch (asset.type) {
    case "audio":
      return {
        type: "audio",
        name: asset.name,
        url: asset.url,
        mimeType: asset.mimeType as AudioAsset["mimeType"],
      };
    case "image":
      return {
        type: "image",
        name: asset.name,
        url: asset.url,
        thumbnailUrl: asset.thumbnailUrl || "",
        mimeType: asset.mimeType as ImageAsset["mimeType"],
      };
    case "video":
      return {
        type: "video",
        name: asset.name,
        url: asset.url,
        thumbnailImageUrl: asset.thumbnailImageUrl || asset.thumbnailUrl || "",
        mimeType: asset.mimeType as VideoAsset["mimeType"],
      };
    case "document":
      return {
        type: "document",
        name: asset.name,
        url: asset.url,
        mimeType: asset.mimeType as DocumentAsset["mimeType"],
      };
    case "sheet":
      return {
        type: "sheet",
        name: asset.name,
        url: asset.url,
        mimeType: asset.mimeType as SheetAsset["mimeType"],
      };
    case "generic":
      return {
        type: "generic",
        name: asset.name,
        url: asset.url,
        mimeType: asset.mimeType,
      };
    default:
      throw new Error(`Unsupported asset type: ${asset.type}`);
  }
}

# URL expander intent

This example demonstrates how to build a URL expander intent app that allows users to paste URLs from external platforms and have the app automatically fetch and import the associated assets into Canva designs. The app shows how to implement both the URL expansion logic and content retrieval for various asset types.

For API reference docs and instructions on running this example, see: https://www.canva.dev/docs/apps/examples/url-expander-intent/.

NOTE: This example differs from what is expected for public apps to pass a Canva review:

- **Static assets**: This example uses static Canva-hosted URLs for media content. Production apps should use CDN/hosting services and implement the `upload` function from `@canva/asset` package for real media uploads.
- **OAuth authentication**: The example includes commented-out OAuth patterns but doesn't implement actual authentication. Production apps should implement proper OAuth flows using the `@canva/app-oauth` package to access user data from external platforms.
- **API integration**: This example uses mock data. Production apps need to implement proper API authentication, rate limiting, and error handling for external data sources.
- **Localization**: Text content is hardcoded in English. Production apps require proper internationalization using the `@canva/app-i18n-kit` package for multi-language support.
- **Error handling**: Production apps should have comprehensive error handling for network failures, API errors, invalid URLs, and unsupported asset types.
- **Code structure**: The code structure is simplified. Production apps using [intents](https://www.canva.dev/docs/apps/intents/) are recommended to call the prepareUrlExpander function from src/intents/url_expander/index.tsx