@farcaster/snap 1.4.1 → 1.5.1

package/src/constants.ts

@@ -62,79 +62,14 @@ export const SPACER_SIZE_VALUES = [
   SPACER_SIZE.large,
 ] as const;
 
-/**
- * Named color palette for snaps. Snap authors specify a name; the client maps
- * it to a hex value appropriate for its current light/dark mode.
- *
- * Light-mode hex values (used by emulator):
- *   gray=#8F8F8F  blue=#006BFF  red=#FC0036  amber=#FFAE00
- *   green=#28A948  teal=#00AC96  purple=#8B5CF6  pink=#F32782
- *
- * Dark-mode hex values (for reference; client-owned):
- *   gray=#8F8F8F  blue=#006FFE  red=#F13342  amber=#FFAE00
- *   green=#00AC3A  teal=#00AA96  purple=#A78BFA  pink=#F12B82
- */
-export const PALETTE_COLOR = {
-  gray: "gray",
-  blue: "blue",
-  red: "red",
-  amber: "amber",
-  green: "green",
-  teal: "teal",
-  purple: "purple",
-  pink: "pink",
-} as const;
-
-export const PALETTE_COLOR_ACCENT = "accent" as const;
-
-export const PALETTE_COLOR_VALUES = [
-  PALETTE_COLOR.gray,
-  PALETTE_COLOR.blue,
-  PALETTE_COLOR.red,
-  PALETTE_COLOR.amber,
-  PALETTE_COLOR.green,
-  PALETTE_COLOR.teal,
-  PALETTE_COLOR.purple,
-  PALETTE_COLOR.pink,
-] as const;
-
-export type PaletteColor = (typeof PALETTE_COLOR_VALUES)[number];
-
-/** Light-mode hex for each palette color (emulator / reference client). */
-export const PALETTE_LIGHT_HEX: Record<PaletteColor, string> = {
-  gray: "#8F8F8F",
-  blue: "#006BFF",
-  red: "#FC0036",
-  amber: "#FFAE00",
-  green: "#28A948",
-  teal: "#00AC96",
-  purple: "#8B5CF6",
-  pink: "#F32782",
-};
-
-/** Dark-mode hex for each palette color (reference). */
-export const PALETTE_DARK_HEX: Record<PaletteColor, string> = {
-  gray: "#8F8F8F",
-  blue: "#006FFE",
-  red: "#F13342",
-  amber: "#FFAE00",
-  green: "#00AC3A",
-  teal: "#00AA96",
-  purple: "#A78BFA",
-  pink: "#F12B82",
-};
-
-export const PROGRESS_COLOR_VALUES = [
-  PALETTE_COLOR_ACCENT,
-  ...PALETTE_COLOR_VALUES,
-] as const;
-
 export const LIST_STYLE_VALUES = ["ordered", "unordered", "plain"] as const;
 
 export const DEFAULT_LIST_STYLE = "ordered" as const;
 
 export const GRID_CELL_SIZE_VALUES = ["auto", "square"] as const;
 export const GRID_GAP_VALUES = ["none", "small", "medium"] as const;
+export const DEFAULT_GRID_GAP =
+  "small" as const satisfies (typeof GRID_GAP_VALUES)[number];
 
 export const BUTTON_GROUP_STYLE = {
   row: "row",
@@ -152,14 +87,32 @@ export const BUTTON_ACTION = {
   post: "post",
   link: "link",
   mini_app: "mini_app",
-  sdk: "sdk",
+  client: "client",
 } as const;
 
 export const BUTTON_ACTION_VALUES = [
   BUTTON_ACTION.post,
   BUTTON_ACTION.link,
   BUTTON_ACTION.mini_app,
-  BUTTON_ACTION.sdk,
+  BUTTON_ACTION.client,
+] as const;
+
+export const CLIENT_ACTION = {
+  view_cast: "view_cast",
+  view_profile: "view_profile",
+  compose_cast: "compose_cast",
+  view_token: "view_token",
+  send_token: "send_token",
+  swap_token: "swap_token",
+} as const;
+
+export const CLIENT_ACTION_VALUES = [
+  CLIENT_ACTION.view_cast,
+  CLIENT_ACTION.view_profile,
+  CLIENT_ACTION.compose_cast,
+  CLIENT_ACTION.view_token,
+  CLIENT_ACTION.send_token,
+  CLIENT_ACTION.swap_token,
 ] as const;
 
 export const BUTTON_STYLE = {
@@ -175,11 +128,6 @@ export const BUTTON_STYLE_VALUES = [
 export const BUTTON_LAYOUT_VALUES = ["stack", "row", "grid"] as const;
 export const DEFAULT_BUTTON_LAYOUT = BUTTON_LAYOUT_VALUES[0];
 
-export const BAR_CHART_COLOR_VALUES = [
-  PALETTE_COLOR_ACCENT,
-  ...PALETTE_COLOR_VALUES,
-] as const;
-
 export const EFFECT_VALUES = ["confetti"] as const;
 
 export const GROUP_LAYOUT_VALUES = ["row"] as const;
@@ -213,9 +161,6 @@ export const HTTP_PREFIX = "http://" as const;
 /** 6-digit hex only (#RRGGBB); used for grid cell backgrounds (free hex). */
 export const HEX_COLOR_6_RE = /^#[0-9a-fA-F]{6}$/;
 
-/** Default snap accent when `page.theme` or `page.theme.accent` is omitted (SPEC.md). */
-export const DEFAULT_THEME_ACCENT = PALETTE_COLOR.purple;
-
 export const TEXT_CONTENT_MAX = {
   [TEXT_STYLE.title]: 80,
   [TEXT_STYLE.body]: 160,

package/src/index.ts

@@ -3,24 +3,33 @@ export {
   PAGE_ROOT_TYPE,
   ELEMENT_TYPE,
   MEDIA_TYPE,
-  DEFAULT_THEME_ACCENT,
   DEFAULT_LIST_STYLE,
   DEFAULT_SLIDER_STEP,
+  CLIENT_ACTION,
+  CLIENT_ACTION_VALUES,
+} from "./constants";
+export {
+  DEFAULT_THEME_ACCENT,
   PALETTE_COLOR,
   PALETTE_COLOR_ACCENT,
   PALETTE_COLOR_VALUES,
   PALETTE_LIGHT_HEX,
   PALETTE_DARK_HEX,
   type PaletteColor,
-} from "./constants";
+} from "./colors";
 export {
+  ACTION_TYPE_GET,
+  ACTION_TYPE_POST,
   snapResponseSchema,
   firstPageResponseSchema,
   payloadSchema,
+  clientActionSchema,
+  createDefaultDataStore,
   type Button,
   type Element,
   type Elements,
   type GroupChildElement,
+  type ClientAction,
   type SnapAction,
   type SnapPageElementInput,
   type SnapContext,
@@ -28,6 +37,9 @@ export {
   type SnapHandlerResult,
   type SnapFunction,
   type SnapPayload,
+  type DataStoreValue,
+  type SnapDataStore,
+  type SnapDataStoreOperations,
 } from "./schemas";
 export {
   validateSnapResponse,

package/src/schemas.ts

@@ -1,16 +1,16 @@
 import { z } from "zod";
 import {
-  BAR_CHART_COLOR_VALUES,
   BUTTON_ACTION,
   BUTTON_ACTION_VALUES,
+  CLIENT_ACTION,
   BUTTON_GROUP_STYLE,
   BUTTON_GROUP_STYLE_VALUES,
   BUTTON_LAYOUT_VALUES,
   BUTTON_STYLE_VALUES,
   DEFAULT_BUTTON_LAYOUT,
+  DEFAULT_GRID_GAP,
   DEFAULT_LIST_STYLE,
   DEFAULT_SLIDER_STEP,
-  DEFAULT_THEME_ACCENT,
   EFFECT_VALUES,
   ELEMENT_TYPE,
   GRID_CELL_SIZE_VALUES,
@@ -25,8 +25,6 @@ import {
   LIST_STYLE_VALUES,
   MEDIA_ELEMENT_TYPES,
   PAGE_ROOT_TYPE,
-  PALETTE_COLOR_VALUES,
-  PROGRESS_COLOR_VALUES,
   SLIDER_STEP_ALIGN_EPS,
   SPACER_SIZE,
   SPACER_SIZE_VALUES,
@@ -36,6 +34,12 @@ import {
   TEXT_STYLE,
   TEXT_STYLE_VALUES,
 } from "./constants";
+import {
+  BAR_CHART_COLOR_VALUES,
+  DEFAULT_THEME_ACCENT,
+  PALETTE_COLOR_VALUES,
+  PROGRESS_COLOR_VALUES,
+} from "./colors";
 
 /**
  * post/link/mini_app targets must be HTTPS in production; allow HTTP only for
@@ -66,33 +70,10 @@ const themeSchema = z
   })
   .strict();
 
-const httpsUrl = z.string().refine((s) => s.startsWith(HTTPS_PREFIX), {
-  message: "URL must use HTTPS",
+const imageUrlSchema = z.string().refine((s) => s.startsWith(HTTPS_PREFIX), {
+  message: "image URL must use HTTPS",
 });
 
-function hasAllowedMediaExtension(
-  urlString: string,
-  allowedExtensions: string[],
-): boolean {
-  try {
-    const url = new URL(urlString);
-    if (url.protocol !== "https:") return false;
-    const lowerPathname = url.pathname.toLowerCase();
-    return allowedExtensions.some((extension) =>
-      lowerPathname.endsWith(`.${extension}`),
-    );
-  } catch {
-    return false;
-  }
-}
-
-const imageUrlSchema = z
-  .string()
-  .refine((s) => hasAllowedMediaExtension(s, ["jpg", "png", "gif", "webp"]), {
-    message:
-      "image URL must use HTTPS and end with a supported extension (.jpg, .png, .gif, .webp)",
-  });
-
 const textAlignSchema = z.enum(TEXT_ALIGN_VALUES);
 
 const textElementSchema = z
@@ -206,7 +187,7 @@ const gridElementSchema = z
     rows: z.number().int().min(LIMITS.minGridRows).max(LIMITS.maxGridRows),
     cells: z.array(gridCellSchema),
     cellSize: z.enum(GRID_CELL_SIZE_VALUES).optional(),
-    gap: z.enum(GRID_GAP_VALUES).optional(),
+    gap: z.enum(GRID_GAP_VALUES).default(DEFAULT_GRID_GAP),
     interactive: z.boolean().optional(),
   })
   .superRefine((val, ctx) => {
@@ -368,26 +349,146 @@ const buttonActionSchema = z.enum(BUTTON_ACTION_VALUES);
 
 const buttonStyleSchema = z.enum(BUTTON_STYLE_VALUES);
 
+/* ------------------------------------------------------------------ */
+/*  Client action schemas                                              */
+/* ------------------------------------------------------------------ */
+
+const viewCastClientActionSchema = z
+  .object({
+    type: z.literal(CLIENT_ACTION.view_cast),
+    hash: z.string().min(1),
+  })
+  .strict();
+
+const viewProfileClientActionSchema = z
+  .object({
+    type: z.literal(CLIENT_ACTION.view_profile),
+    fid: z.number().int().nonnegative(),
+  })
+  .strict();
+
+const composeCastClientActionSchema = z
+  .object({
+    type: z.literal(CLIENT_ACTION.compose_cast),
+    text: z.string().optional(),
+    embeds: z
+      .array(z.string())
+      .max(2, { message: "compose_cast embeds: max 2 URLs" })
+      .optional(),
+    parent: z
+      .object({
+        type: z.literal("cast"),
+        hash: z.string().min(1),
+      })
+      .strict()
+      .optional(),
+    channelKey: z.string().optional(),
+  })
+  .strict();
+
+const viewTokenClientActionSchema = z
+  .object({
+    type: z.literal(CLIENT_ACTION.view_token),
+    /** CAIP-19 asset ID (e.g. "eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913") */
+    token: z.string().min(1),
+  })
+  .strict();
+
+const sendTokenClientActionSchema = z
+  .object({
+    type: z.literal(CLIENT_ACTION.send_token),
+    /** CAIP-19 asset ID */
+    token: z.string().optional(),
+    /** Amount in raw token units (e.g. "1000000" for 1 USDC) */
+    amount: z.string().optional(),
+    recipientFid: z.number().int().nonnegative().optional(),
+    recipientAddress: z.string().optional(),
+  })
+  .strict();
+
+const swapTokenClientActionSchema = z
+  .object({
+    type: z.literal(CLIENT_ACTION.swap_token),
+    /** CAIP-19 asset ID to sell */
+    sellToken: z.string().optional(),
+    /** CAIP-19 asset ID to buy */
+    buyToken: z.string().optional(),
+    /** Amount in raw token units */
+    sellAmount: z.string().optional(),
+  })
+  .strict();
+
+export const clientActionSchema = z.discriminatedUnion("type", [
+  viewCastClientActionSchema,
+  viewProfileClientActionSchema,
+  composeCastClientActionSchema,
+  viewTokenClientActionSchema,
+  sendTokenClientActionSchema,
+  swapTokenClientActionSchema,
+]);
+
+export type ClientAction = z.infer<typeof clientActionSchema>;
+
+/* ------------------------------------------------------------------ */
+/*  Button schema                                                      */
+/* ------------------------------------------------------------------ */
+
 const buttonSchema = z
   .object({
     label: z.string().min(1).max(LIMITS.maxButtonLabelChars),
     action: buttonActionSchema,
-    /** URL (HTTPS for post/link/mini_app) or SDK action id (e.g. cast:view:...) */
-    target: z.string().min(1),
+    /** URL target for post/link/mini_app buttons */
+    target: z.string().min(1).optional(),
+    /** Structured client action for client buttons */
+    client_action: clientActionSchema.optional(),
     style: buttonStyleSchema.optional(),
   })
   .superRefine((val, ctx) => {
-    if (
-      (val.action === BUTTON_ACTION.post ||
-        val.action === BUTTON_ACTION.link ||
-        val.action === BUTTON_ACTION.mini_app) &&
-      !isSecureOrLoopbackHttpButtonTarget(val.target)
-    ) {
-      ctx.addIssue({
-        code: "custom",
-        message: `button target must use HTTPS (or http:// on localhost / 127.0.0.1 for development) for action "${val.action}" (received: ${val.target})`,
-        path: ["target"],
-      });
+    if (val.action === BUTTON_ACTION.client) {
+      // client buttons require client_action, must not have target
+      if (val.client_action === undefined) {
+        ctx.addIssue({
+          code: "custom",
+          message: `button with action "client" must include a "client_action" object`,
+          path: ["client_action"],
+        });
+      }
+      if (val.target !== undefined) {
+        ctx.addIssue({
+          code: "custom",
+          message: `button with action "client" must not include "target"`,
+          path: ["target"],
+        });
+      }
+    } else {
+      // post/link/mini_app buttons require target, must not have client_action
+      if (val.target === undefined) {
+        ctx.addIssue({
+          code: "custom",
+          message: `button with action "${val.action}" must include a "target" URL`,
+          path: ["target"],
+        });
+      }
+      if (val.client_action !== undefined) {
+        ctx.addIssue({
+          code: "custom",
+          message: `button with action "${val.action}" must not include "client_action"`,
+          path: ["client_action"],
+        });
+      }
+      if (
+        val.target &&
+        (val.action === BUTTON_ACTION.post ||
+          val.action === BUTTON_ACTION.link ||
+          val.action === BUTTON_ACTION.mini_app) &&
+        !isSecureOrLoopbackHttpButtonTarget(val.target)
+      ) {
+        ctx.addIssue({
+          code: "custom",
+          message: `button target must use HTTPS (or http:// on localhost / 127.0.0.1 for development) for action "${val.action}" (received: ${val.target})`,
+          path: ["target"],
+        });
+      }
     }
   });
 
@@ -578,9 +679,46 @@ export const snapActionSchema = z.discriminatedUnion("type", [
 
 export type SnapAction = z.infer<typeof snapActionSchema>;
 
+export type DataStoreValue =
+  | string
+  | number
+  | boolean
+  | null
+  | DataStoreValue[]
+  | { [key: string]: DataStoreValue };
+
+export type SnapDataStoreOperations = {
+  get(key: string): Promise<DataStoreValue | null>;
+  set(key: string, value: DataStoreValue): Promise<void>;
+};
+
+export type SnapDataStore = SnapDataStoreOperations & {
+  withLock<T>(fn: (store: SnapDataStoreOperations) => Promise<T>): Promise<T>;
+};
+
+export function createDefaultDataStore(): SnapDataStore {
+  const err = new Error(
+    "Data store is not configured. Use withUpstash() from @farcaster/snap-upstash or provide a data store implementation.",
+  );
+  return {
+    get(_key: string): Promise<never> {
+      return Promise.reject(err);
+    },
+    set(_key: string, _value: DataStoreValue): Promise<never> {
+      return Promise.reject(err);
+    },
+    withLock<T>(
+      _fn: (store: SnapDataStoreOperations) => Promise<T>,
+    ): Promise<never> {
+      return Promise.reject(err);
+    },
+  };
+}
+
 export type SnapContext = {
   action: SnapAction;
   request: Request;
+  data: SnapDataStore;
 };
 
 export type SnapFunction = (ctx: SnapContext) => Promise<SnapHandlerResult>;

package/src/server/parseRequest.ts

@@ -7,7 +7,6 @@ import {
 import { decodePayload, verifyJFSRequestBody } from "./verify";
 import { z } from "zod";
 
-/** Default replay window per SPEC.md § Replay Protection (5 minutes). */
 const DEFAULT_SNAP_POST_MAX_SKEW_SECONDS = 300 as const;
 
 export type ParseRequestError =
@@ -37,6 +36,13 @@ export type ParseRequestOptions = {
    * When true, skip {@link verifyJFSRequestBody} (signature checks).
    */
   skipJFSVerification?: boolean;
+
+  /**
+   * Maximum allowed absolute difference between the request timestamp and the
+   * server clock, in seconds. Requests outside this window are rejected as
+   * potential replays. Defaults to 300 (5 minutes) when not provided.
+   */
+  maxSkewSeconds?: number;
 };
 
 export type ParseRequestResult =
@@ -75,7 +81,7 @@ export async function parseRequest(
     };
   }
 
-  const maxSkew = DEFAULT_SNAP_POST_MAX_SKEW_SECONDS;
+  const maxSkew = options.maxSkewSeconds ?? DEFAULT_SNAP_POST_MAX_SKEW_SECONDS;
   const nowSec = Math.floor(Date.now() / 1000);
 
   const text = await request.text();

package/src/ui/bar-chart.ts

@@ -1,9 +1,6 @@
 import { z } from "zod";
-import {
-  BAR_CHART_COLOR_VALUES,
-  LIMITS,
-  PALETTE_COLOR_VALUES,
-} from "../constants.js";
+import { LIMITS } from "../constants.js";
+import { BAR_CHART_COLOR_VALUES, PALETTE_COLOR_VALUES } from "../colors.js";
 
 export const barChartProps = z.object({
   bars: z

package/src/ui/button-group.ts

@@ -1,13 +1,26 @@
 import { z } from "zod";
-import { BUTTON_GROUP_STYLE_VALUES, LIMITS } from "../constants.js";
+import {
+  BUTTON_GROUP_STYLE,
+  BUTTON_GROUP_STYLE_VALUES,
+  LIMITS,
+} from "../constants.js";
 
-export const buttonGroupProps = z.object({
-  name: z.string().min(1),
-  options: z
-    .array(z.string())
-    .min(LIMITS.minButtonGroupOptions)
-    .max(LIMITS.maxButtonGroupOptions),
-  style: z.enum(BUTTON_GROUP_STYLE_VALUES).optional(),
-});
+export const buttonGroupProps = z
+  .object({
+    name: z.string().min(1),
+    options: z
+      .array(z.string().max(LIMITS.maxButtonGroupOptionChars))
+      .min(LIMITS.minButtonGroupOptions)
+      .max(LIMITS.maxButtonGroupOptions),
+    style: z.enum(BUTTON_GROUP_STYLE_VALUES).optional(),
+  })
+  .transform((val) => ({
+    ...val,
+    style:
+      val.style ??
+      (val.options.length <= 3
+        ? BUTTON_GROUP_STYLE.row
+        : BUTTON_GROUP_STYLE.stack),
+  }));
 
 export type ButtonGroupProps = z.infer<typeof buttonGroupProps>;

package/src/ui/button.ts

@@ -4,7 +4,8 @@ import { BUTTON_ACTION_VALUES, BUTTON_STYLE_VALUES } from "../constants.js";
 export const actionButtonProps = z.object({
   label: z.string(),
   action: z.enum(BUTTON_ACTION_VALUES),
-  target: z.string(),
+  target: z.string().optional(),
+  client_action: z.record(z.string(), z.unknown()).optional(),
   style: z.enum(BUTTON_STYLE_VALUES).optional(),
 });
 

package/src/ui/catalog.ts

@@ -29,6 +29,10 @@ const snapTargetParams = z.object({
   target: z.string(),
 });
 
+const snapClientParams = z.object({
+  client_action: z.record(z.string(), z.unknown()),
+});
+
 /**
  * Basic catalog: one json-render component per snap element type, plus ActionButton for snap buttons.
  * Does not validate cross-field rules (media count, height budget); snap JSON still goes through `@farcaster/snap` validation.
@@ -102,7 +106,7 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
     ActionButton: {
       props: actionButtonProps,
       description:
-        "Snap action button: post (next page), link (browser), mini_app, sdk — target is HTTPS URL or SDK id.",
+        "Snap action button: post (next page), link (browser), mini_app, client — target is HTTPS URL or client_action object.",
     },
   },
   actions: {
@@ -119,10 +123,10 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
       description: "Open `target` as an in-app Farcaster mini app.",
       params: snapTargetParams,
     },
-    snap_sdk: {
+    snap_client: {
       description:
-        "Run a Farcaster client SDK action (cast:view, user:follow, …).",
-      params: snapTargetParams,
+        "Trigger a Farcaster client action (view_cast, view_profile, compose_cast, …).",
+      params: snapClientParams,
     },
   },
 });

package/src/ui/group.ts

@@ -1,7 +1,8 @@
 import { z } from "zod";
+import { GROUP_LAYOUT_VALUES } from "../constants.js";
 
 export const groupProps = z.object({
-  layout: z.enum(["row", "grid"]),
+  layout: z.enum(GROUP_LAYOUT_VALUES),
 });
 
 export type GroupProps = z.infer<typeof groupProps>;

package/src/ui/progress.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { PROGRESS_COLOR_VALUES } from "../constants.js";
+import { PROGRESS_COLOR_VALUES } from "../colors.js";
 
 export const progressProps = z.object({
   value: z.number(),

package/src/ui/schema.ts

@@ -31,7 +31,7 @@ export const snapJsonRenderSchema = defineSchema(
     defaultRules: [
       "You are generating auxiliary UI for a Farcaster Snap. Prefer components matching snap element types (Text, Image, ButtonGroup, …).",
       "Snap pages use a Stack root with at most 5 body children and 1 media element (Image or Grid); keep generated trees small.",
-      "Bottom-of-card snap buttons are ActionButton components; use actions post / link / mini_app / sdk per SPEC.md.",
+      "Bottom-of-card snap buttons are ActionButton components; use actions post / link / mini_app / client.",
     ],
   },
 );

package/src/ui/spacer.ts

@@ -1,8 +1,8 @@
 import { z } from "zod";
-import { SPACER_SIZE_VALUES } from "../constants.js";
+import { SPACER_SIZE, SPACER_SIZE_VALUES } from "../constants.js";
 
 export const spacerProps = z.object({
-  size: z.enum(SPACER_SIZE_VALUES).optional(),
+  size: z.enum(SPACER_SIZE_VALUES).default(SPACER_SIZE.medium),
 });
 
 export type SpacerProps = z.infer<typeof spacerProps>;

package/src/ui/toggle.ts

@@ -3,7 +3,7 @@ import { z } from "zod";
 export const toggleProps = z.object({
   name: z.string().min(1),
   label: z.string(),
-  value: z.boolean().optional(),
+  value: z.boolean().default(false),
 });
 
 export type ToggleProps = z.infer<typeof toggleProps>;