@farcaster/snap-hono 1.1.8 → 1.2.1

package/src/payloadToResponse.ts

@@ -1,8 +1,8 @@
 import {
   MEDIA_TYPE,
-  rootSchema,
-  type SnapResponseInput,
-  validatePage,
+  type SnapHandlerResult,
+  validateSnapResponse,
+  snapResponseSchema,
 } from "@farcaster/snap";
 
 type PayloadToResponseOptions = {
@@ -13,13 +13,13 @@ type PayloadToResponseOptions = {
 const DEFAULT_LINK_MEDIA_TYPES = [MEDIA_TYPE, "text/html"] as const;
 
 export function payloadToResponse(
-  payload: SnapResponseInput,
+  payload: SnapHandlerResult,
   options: Partial<PayloadToResponseOptions> = {},
 ): Response {
   const resourcePath = options.resourcePath ?? "/";
   const mediaTypes = options.mediaTypes ?? [...DEFAULT_LINK_MEDIA_TYPES];
 
-  const validation = validatePage(payload);
+  const validation = validateSnapResponse(payload);
   if (!validation.valid) {
     return new Response(
       JSON.stringify({
@@ -35,7 +35,7 @@ export function payloadToResponse(
     );
   }
 
-  const finalized = rootSchema.parse(payload);
+  const finalized = snapResponseSchema.parse(payload);
   return new Response(JSON.stringify(finalized), {
     status: 200,
     headers: {

package/src/renderSnapPage.ts

@@ -1,16 +1,115 @@
-import type { SnapResponseInput } from "@farcaster/snap";
-
-const PALETTE: Record<string, string> = {
-  gray: "#8F8F8F",
-  blue: "#006BFF",
-  red: "#FC0036",
-  amber: "#FFAE00",
-  green: "#28A948",
-  teal: "#00AC96",
-  purple: "#8B5CF6",
-  pink: "#F32782",
+import type {
+  SnapPageElementInput,
+  SnapHandlerResult,
+  PaletteColor,
+} from "@farcaster/snap";
+import {
+  DEFAULT_THEME_ACCENT,
+  PALETTE_LIGHT_HEX,
+  PALETTE_COLOR_ACCENT,
+} from "@farcaster/snap";
+
+type SnapPage = SnapHandlerResult["page"];
+type SnapPageButton = NonNullable<SnapPage["buttons"]>[number];
+
+// ─── OG meta ────────────────────────────────────────────
+
+export type RenderSnapPageOptions = {
+  /** Absolute URL of the /~/og-image PNG route. */
+  ogImageUrl?: string;
+  /** Canonical pathname + search of the snap page (e.g. "/snap" or "/"). */
+  resourcePath?: string;
+  /** Optional og:site_name value (e.g. from SNAP_OG_SITE_NAME env). */
+  siteName?: string;
 };
 
+type PageMeta = {
+  title: string;
+  description: string;
+  imageUrl?: string;
+  imageAlt?: string;
+};
+
+export function extractPageMeta(page: SnapPage): PageMeta {
+  let title = "Farcaster Snap";
+  let description = "";
+  let imageUrl: string | undefined;
+  let imageAlt: string | undefined;
+
+  for (const el of page.elements.children) {
+    if (el.type === "text") {
+      const style = el.style;
+      const content = el.content;
+      if (style === "title" && title === "Farcaster Snap" && content) {
+        title = content;
+      } else if (
+        (style === "body" || style === "caption") &&
+        !description &&
+        content
+      ) {
+        description = content;
+      }
+    }
+    if (el.type === "image" && !imageUrl) {
+      imageUrl = el.url;
+      imageAlt = el.alt;
+    }
+  }
+
+  return {
+    title,
+    description: description || title,
+    imageUrl,
+    imageAlt,
+  };
+}
+
+function buildOgMeta(opts: {
+  title: string;
+  description: string;
+  pageUrl: string;
+  ogImageUrl?: string;
+  imageAlt?: string;
+  siteName?: string;
+}): string {
+  const { title, description, pageUrl, ogImageUrl, imageAlt, siteName } = opts;
+
+  const imgUrl = ogImageUrl ?? undefined;
+  const twitterCard = imgUrl ? "summary_large_image" : "summary";
+
+  const lines = [
+    `<meta name="description" content="${esc(description)}">`,
+    `<meta property="og:title" content="${esc(title)}">`,
+    `<meta property="og:description" content="${esc(description)}">`,
+    `<meta property="og:url" content="${esc(pageUrl)}">`,
+    `<meta property="og:type" content="website">`,
+    `<meta property="og:locale" content="en_US">`,
+  ];
+
+  if (siteName) {
+    lines.push(`<meta property="og:site_name" content="${esc(siteName)}">`);
+  }
+
+  if (imgUrl) {
+    lines.push(`<meta property="og:image" content="${esc(imgUrl)}">`);
+    lines.push(
+      `<meta property="og:image:alt" content="${esc(imageAlt ?? title)}">`,
+    );
+  }
+
+  lines.push(
+    `<meta name="twitter:card" content="${twitterCard}">`,
+    `<meta name="twitter:title" content="${esc(title)}">`,
+    `<meta name="twitter:description" content="${esc(description)}">`,
+  );
+
+  if (imgUrl) {
+    lines.push(`<meta name="twitter:image" content="${esc(imgUrl)}">`);
+  }
+
+  return lines.join("\n");
+}
+
 const FC_ICON = `<svg viewBox="0 0 520 457" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M519.801 0V61.6809H458.172V123.31H477.054V123.331H519.801V456.795H416.57L416.507 456.49L363.832 207.03C358.81 183.251 345.667 161.736 326.827 146.434C307.988 131.133 284.255 122.71 260.006 122.71H259.8C235.551 122.71 211.818 131.133 192.979 146.434C174.139 161.736 160.996 183.259 155.974 207.03L103.239 456.795H0V123.323H42.7471V123.31H61.6262V61.6809H0V0H519.801Z" fill="currentColor"/></svg>`;
 
 function esc(s: string): string {
@@ -21,20 +120,24 @@ function esc(s: string): string {
     .replace(/"/g, "&quot;");
 }
 
-function accentHex(accent: string | undefined): string {
-  return PALETTE[accent ?? "purple"] ?? PALETTE.purple!;
+function accentHex(accent: PaletteColor | undefined): string {
+  return accent && PALETTE_LIGHT_HEX[accent]
+    ? PALETTE_LIGHT_HEX[accent]
+    : PALETTE_LIGHT_HEX[DEFAULT_THEME_ACCENT];
 }
 
-function colorHex(color: string | undefined, accent: string): string {
-  if (!color || color === "accent") return accent;
-  return PALETTE[color] ?? accent;
+function colorHex(
+  color: PaletteColor | typeof PALETTE_COLOR_ACCENT | undefined,
+  accent: string,
+): string {
+  if (!color || color === PALETTE_COLOR_ACCENT) return accent;
+  return PALETTE_LIGHT_HEX[color] ?? accent;
 }
 
 // ─── Element renderers ──────────────────────────────────
 
-function renderElement(el: Record<string, unknown>, accent: string): string {
-  const type = el.type as string;
-  switch (type) {
+function renderElement(el: SnapPageElementInput, accent: string): string {
+  switch (el.type) {
     case "text":
       return renderText(el, accent);
     case "image":
@@ -59,25 +162,20 @@ function renderElement(el: Record<string, unknown>, accent: string): string {
       return renderGroup(el, accent);
     case "divider":
       return `<hr style="border:none;border-top:1px solid #E5E7EB;margin:4px 0">`;
-    case "spacer": {
-      const sizes: Record<string, string> = {
-        small: "8px",
-        medium: "16px",
-        large: "24px",
-      };
-      return `<div style="height:${
-        sizes[(el.size as string) ?? "medium"] ?? "16px"
-      }"></div>`;
-    }
+    case "spacer":
+      return renderSpacer(el);
     default:
       return "";
   }
 }
 
-function renderText(el: Record<string, unknown>, _accent: string): string {
-  const style = el.style as string;
-  const content = esc(el.content as string);
-  const align = (el.align as string) ?? "left";
+function renderText(
+  el: Extract<SnapPageElementInput, { type: "text" }>,
+  _accent: string,
+): string {
+  const style = el.style;
+  const content = esc(el.content);
+  const align = el.align ?? "left";
   const styles: Record<string, string> = {
     title: "font-size:20px;font-weight:700;color:#111",
     body: "font-size:15px;line-height:1.5;color:#374151",
@@ -90,27 +188,24 @@ function renderText(el: Record<string, unknown>, _accent: string): string {
   };text-align:${align}">${content}</div>`;
 }
 
-function renderImage(el: Record<string, unknown>): string {
-  const url = esc(el.url as string);
-  const aspect = (el.aspect as string) ?? "16:9";
+function renderImage(
+  el: Extract<SnapPageElementInput, { type: "image" }>,
+): string {
+  const url = esc(el.url);
+  const aspect = el.aspect ?? "16:9";
   const [w, h] = aspect.split(":").map(Number);
   const ratio = w && h ? `${w}/${h}` : "16/9";
   return `<div style="aspect-ratio:${ratio};border-radius:8px;overflow:hidden;background:#F3F4F6"><img src="${url}" alt="${esc(
-    (el.alt as string) ?? "",
+    el.alt ?? "",
   )}" style="width:100%;height:100%;object-fit:cover"></div>`;
 }
 
-function renderGrid(el: Record<string, unknown>): string {
-  const cols = el.cols as number;
-  const rows = el.rows as number;
-  const cells = el.cells as Array<{
-    row: number;
-    col: number;
-    color?: string;
-    content?: string;
-  }>;
-  const cellSize = (el.cellSize as string) ?? "auto";
-  const gap = (el.gap as string) ?? "small";
+function renderGrid(
+  el: Extract<SnapPageElementInput, { type: "grid" }>,
+): string {
+  const { cols, rows, cells } = el;
+  const cellSize = el.cellSize ?? "auto";
+  const gap = el.gap ?? "small";
   const gapPx: Record<string, string> = {
     none: "0",
     small: "2px",
@@ -135,11 +230,12 @@ function renderGrid(el: Record<string, unknown>): string {
   }">${cellsHtml}</div>`;
 }
 
-function renderProgress(el: Record<string, unknown>, accent: string): string {
-  const value = el.value as number;
-  const max = el.max as number;
-  const label = el.label as string | undefined;
-  const color = colorHex(el.color as string | undefined, accent);
+function renderProgress(
+  el: Extract<SnapPageElementInput, { type: "progress" }>,
+  accent: string,
+): string {
+  const { value, max, label } = el;
+  const color = colorHex(el.color, accent);
   const pct = max > 0 ? Math.min(100, (value / max) * 100) : 0;
   const labelHtml = label
     ? `<div style="font-size:13px;color:#6B7280;margin-bottom:4px">${esc(
@@ -149,19 +245,18 @@ function renderProgress(el: Record<string, unknown>, accent: string): string {
   return `<div>${labelHtml}<div style="height:8px;background:#E5E7EB;border-radius:4px;overflow:hidden"><div style="height:100%;width:${pct}%;background:${color};border-radius:4px"></div></div></div>`;
 }
 
-function renderBarChart(el: Record<string, unknown>, accent: string): string {
-  const bars = el.bars as Array<{
-    label: string;
-    value: number;
-    color?: string;
-  }>;
+function renderBarChart(
+  el: Extract<SnapPageElementInput, { type: "bar_chart" }>,
+  accent: string,
+): string {
+  const { bars } = el;
   const max =
-    (el.max as number | undefined) ?? Math.max(...bars.map((b) => b.value), 1);
-  const defaultColor = colorHex(el.color as string | undefined, accent);
+    el.max ?? Math.max(...bars.map((b: { value: number }) => b.value), 1);
+  const defaultColor = colorHex(el.color, accent);
 
   let html = `<div style="display:flex;align-items:flex-end;gap:12px;height:120px">`;
   for (const bar of bars) {
-    const color = bar.color ? PALETTE[bar.color] ?? defaultColor : defaultColor;
+    const color = colorHex(bar.color, defaultColor);
     const pct = max > 0 ? (bar.value / max) * 100 : 0;
     html += `<div style="flex:1;display:flex;flex-direction:column;align-items:center;height:100%;justify-content:flex-end">`;
     html += `<div style="font-size:11px;color:#6B7280;margin-bottom:4px">${bar.value}</div>`;
@@ -175,12 +270,11 @@ function renderBarChart(el: Record<string, unknown>, accent: string): string {
   return html;
 }
 
-function renderList(el: Record<string, unknown>): string {
-  const style = (el.style as string) ?? "ordered";
-  const items = el.items as Array<{
-    content: string;
-    trailing?: string;
-  }>;
+function renderList(
+  el: Extract<SnapPageElementInput, { type: "list" }>,
+): string {
+  const style = el.style ?? "ordered";
+  const { items } = el;
 
   let html = "";
   for (let i = 0; i < items.length; i++) {
@@ -204,11 +298,11 @@ function renderList(el: Record<string, unknown>): string {
 }
 
 function renderButtonGroup(
-  el: Record<string, unknown>,
+  el: Extract<SnapPageElementInput, { type: "button_group" }>,
   accent: string,
 ): string {
-  const options = el.options as string[];
-  const layout = (el.style as string) ?? "row";
+  const { options } = el;
+  const layout = el.style ?? "row";
   const dir = layout === "stack" ? "column" : "row";
   let html = `<div style="display:flex;flex-direction:${dir};gap:8px">`;
   for (const opt of options) {
@@ -220,13 +314,12 @@ function renderButtonGroup(
   return html;
 }
 
-function renderSlider(el: Record<string, unknown>, accent: string): string {
-  const label = el.label as string | undefined;
-  const min = el.min as number;
-  const max = el.max as number;
-  const value = (el.value as number) ?? (min + max) / 2;
-  const minLabel = el.minLabel as string | undefined;
-  const maxLabel = el.maxLabel as string | undefined;
+function renderSlider(
+  el: Extract<SnapPageElementInput, { type: "slider" }>,
+  accent: string,
+): string {
+  const { label, min, max, minLabel, maxLabel } = el;
+  const value = el.value ?? (min + max) / 2;
 
   const labelHtml = label
     ? `<div style="font-size:13px;color:#6B7280;margin-bottom:4px">${esc(
@@ -243,14 +336,19 @@ function renderSlider(el: Record<string, unknown>, accent: string): string {
   return `<div>${labelHtml}<div style="display:flex;align-items:center;gap:8px">${minL}<input type="range" min="${min}" max="${max}" value="${value}" disabled style="flex:1;accent-color:${accent};opacity:0.7">${maxL}</div></div>`;
 }
 
-function renderTextInput(el: Record<string, unknown>): string {
-  const placeholder = esc((el.placeholder as string) ?? "");
+function renderTextInput(
+  el: Extract<SnapPageElementInput, { type: "text_input" }>,
+): string {
+  const placeholder = esc(el.placeholder ?? "");
   return `<input type="text" placeholder="${placeholder}" disabled style="width:100%;padding:10px 12px;border-radius:8px;border:1px solid #E5E7EB;background:#F9FAFB;font-size:14px;color:#9CA3AF;font-family:inherit;box-sizing:border-box">`;
 }
 
-function renderToggle(el: Record<string, unknown>, accent: string): string {
-  const label = esc(el.label as string);
-  const value = el.value as boolean;
+function renderToggle(
+  el: Extract<SnapPageElementInput, { type: "toggle" }>,
+  accent: string,
+): string {
+  const label = esc(el.label);
+  const { value } = el;
   const bg = value ? accent : "#D1D5DB";
   const tx = value ? "20px" : "2px";
   return `<div style="display:flex;align-items:center;justify-content:space-between">
@@ -259,10 +357,23 @@ function renderToggle(el: Record<string, unknown>, accent: string): string {
 </div>`;
 }
 
-function renderGroup(el: Record<string, unknown>, accent: string): string {
-  const children = el.children as Array<Record<string, unknown>>;
+function renderSpacer(
+  el: Extract<SnapPageElementInput, { type: "spacer" }>,
+): string {
+  const sizes: Record<string, string> = {
+    small: "8px",
+    medium: "16px",
+    large: "24px",
+  };
+  return `<div style="height:${sizes[el.size ?? "medium"] ?? "16px"}"></div>`;
+}
+
+function renderGroup(
+  el: Extract<SnapPageElementInput, { type: "group" }>,
+  accent: string,
+): string {
   let html = `<div style="display:flex;gap:12px">`;
-  for (const child of children) {
+  for (const child of el.children) {
     html += `<div style="flex:1">${renderElement(child, accent)}</div>`;
   }
   html += `</div>`;
@@ -272,8 +383,8 @@ function renderGroup(el: Record<string, unknown>, accent: string): string {
 // ─── Buttons ────────────────────────────────────────────
 
 function renderButtons(
-  buttons: Array<Record<string, unknown>> | undefined,
-  layout: string | undefined,
+  buttons: SnapPage["buttons"],
+  layout: SnapPage["button_layout"],
   accent: string,
 ): string {
   if (!buttons || buttons.length === 0) return "";
@@ -293,13 +404,15 @@ function renderButtons(
 
   let html = `<div style="${wrap}${dir};gap:8px;margin-top:12px">`;
   for (let i = 0; i < buttons.length; i++) {
-    const btn = buttons[i]!;
-    const label = esc(btn.label as string);
-    const style = (btn.style as string) ?? (i === 0 ? "primary" : "secondary");
+    const btn: SnapPageButton = buttons[i]!;
+    const label = esc(btn.label);
+    const style = btn.style ?? (i === 0 ? "primary" : "secondary");
     const bg = style === "primary" ? accent : "transparent";
     const color = style === "primary" ? "#fff" : accent;
     const border = style === "primary" ? "none" : `2px solid ${accent}`;
-    html += `<button onclick="showModal()" style="flex:1;padding:10px 16px;border-radius:10px;background:${bg};color:${color};border:${border};font-size:14px;font-weight:600;cursor:pointer;font-family:inherit">${label}</button>`;
+    const pad = style === "primary" ? "18px 16px" : "10px 16px";
+    const minH = style === "primary" ? "min-height:52px;" : "";
+    html += `<button onclick="showModal()" style="flex:1;${minH}padding:${pad};border-radius:10px;background:${bg};color:${color};border:${border};font-size:14px;font-weight:600;cursor:pointer;font-family:inherit;box-sizing:border-box">${label}</button>`;
   }
   html += `</div>`;
   return html;
@@ -307,16 +420,26 @@ function renderButtons(
 
 // ─── Main renderer ──────────────────────────────────────
 
-export function renderSnapPage(snap: SnapResponseInput, snapOrigin: string): string {
+export function renderSnapPage(
+  snap: SnapHandlerResult,
+  snapOrigin: string,
+  opts?: RenderSnapPageOptions,
+): string {
   const page = snap.page;
   const accent = accentHex(page.theme?.accent);
 
-  // Extract title for <title> tag
-  const titleEl = page.elements.children.find(
-    (el) =>
-      el.type === "text" && (el as Record<string, unknown>).style === "title",
-  ) as Record<string, unknown> | undefined;
-  const pageTitle = titleEl ? esc(titleEl.content as string) : "Farcaster Snap";
+  const meta = extractPageMeta(page);
+  const pageTitle = esc(meta.title);
+  const resourcePath = opts?.resourcePath ?? "/";
+  const pageUrl = snapOrigin.replace(/\/$/, "") + resourcePath;
+  const ogMeta = buildOgMeta({
+    title: meta.title,
+    description: meta.description,
+    pageUrl,
+    ogImageUrl: opts?.ogImageUrl,
+    imageAlt: meta.imageAlt ?? meta.imageUrl ? meta.title : undefined,
+    siteName: opts?.siteName,
+  });
 
   const snapUrl = encodeURIComponent(snapOrigin + "/");
 
@@ -324,17 +447,13 @@ export function renderSnapPage(snap: SnapResponseInput, snapOrigin: string): str
   let elementsHtml = "";
   for (const el of page.elements.children) {
     elementsHtml += `<div style="margin-bottom:12px">${renderElement(
-      el as Record<string, unknown>,
+      el,
       accent,
     )}</div>`;
   }
 
   // Render buttons
-  const buttonsHtml = renderButtons(
-    page.buttons as Array<Record<string, unknown>> | undefined,
-    page.button_layout as string | undefined,
-    accent,
-  );
+  const buttonsHtml = renderButtons(page.buttons, page.button_layout, accent);
 
   return `<!DOCTYPE html>
 <html lang="en">
@@ -342,6 +461,7 @@ export function renderSnapPage(snap: SnapResponseInput, snapOrigin: string): str
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>${pageTitle}</title>
+${ogMeta}
 <style>
 *{margin:0;padding:0;box-sizing:border-box}
 body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;background:#0A0A0A;min-height:100vh;display:flex;align-items:center;justify-content:center;flex-direction:column;padding:24px}