TypeScript Integration

Define the API response types

type AssetType = "emoji" | "flag" | "flags";

interface AssetApiSuccess {
  ok: true;
  data: {
    type: AssetType;
    id: string;
    quality: string;
    path: string;
    url: string;
    mimeType: "image/svg+xml" | "image/png";
  };
  meta: { apiVersion: "1.0.0" };
}

interface AssetApiError {
  ok: false;
  error: { code: string; message: string };
  meta: { apiVersion: "1.0.0" };
}

type AssetApiResponse = AssetApiSuccess | AssetApiError;

These interfaces describe the documented JSON shape. TypeScript does not validate untrusted network data at runtime.

Create a typed resolver

const CDN = "https://softhoursdiary-emojis.pages.dev";

type AssetQuality = "svg" | "png" | "s" | "m" | "l" | "1x1" | "4x3";

export async function resolveAsset(
  type: AssetType,
  id: string,
  quality?: AssetQuality
): Promise<AssetApiSuccess["data"]> {
  const params = new URLSearchParams({ type, id });
  if (quality) params.set("quality", quality);

  const response = await fetch(CDN + "/api/v1/asset?" + params);
  const result = await response.json() as AssetApiResponse;

  if (!response.ok || !result.ok) {
    throw new Error(result.ok ? "Asset lookup failed." : result.error.message);
  }

  return result.data;
}

Use a resolved URL

import { resolveAsset } from "./asset-api";

export async function Reaction() {
  const asset = await resolveAsset("emoji", "1f632", "svg");

  return (
    <img
      src={asset.url}
      alt="Surprised face"
      width={36}
      height={36}
    />
  );
}

Supported quality unions

Use the quality set that matches the selected type. Invalid combinations return an HTTP 400 error response.

Runtime validation

Always check response.ok and the response body's ok field before reading data. Use URLSearchParams so literal Unicode IDs are encoded correctly.

A successful response means the URL was generated. It does not guarantee the underlying image file exists.

See the REST JSON API guide for all error codes and fields.