@farcaster/snap 2.0.0 → 2.0.1

package/dist/schemas.d.ts

@@ -1,8 +1,21 @@
 import { z } from "zod";
 import type { Spec } from "@json-render/core";
-import { type SnapDataStore } from "./dataStore.js";
+import { type SpecVersion } from "./constants.js";
+declare const themeAccentSchema: z.ZodEnum<{
+    gray: "gray";
+    blue: "blue";
+    red: "red";
+    amber: "amber";
+    green: "green";
+    teal: "teal";
+    purple: "purple";
+    pink: "pink";
+}>;
 export declare const snapResponseSchema: z.ZodObject<{
-    version: z.ZodLiteral<"1.0">;
+    version: z.ZodEnum<{
+        "1.0": "1.0";
+        "2.0": "2.0";
+    }>;
     theme: z.ZodDefault<z.ZodOptional<z.ZodObject<{
         accent: z.ZodDefault<z.ZodEnum<{
             gray: "gray";
@@ -21,13 +34,60 @@ export declare const snapResponseSchema: z.ZodObject<{
     ui: z.ZodCustom<Spec, Spec>;
 }, z.core.$strict>;
 export type SnapResponse = z.infer<typeof snapResponseSchema>;
-export type SnapHandlerResult = z.input<typeof snapResponseSchema>;
+/**
+ * Permissive element input type for snap handler authors.
+ * Allows dynamic element construction without requiring exact UIElement types.
+ */
+export type SnapElementInput = {
+    type: string;
+    props?: Record<string, unknown>;
+    children?: string[];
+    on?: Record<string, unknown>;
+    [key: string]: unknown;
+};
+/**
+ * Permissive input type for the `ui` field in snap handler return values.
+ * Accepts dynamically-built element maps (e.g. `Record<string, SnapElementInput>`)
+ * without requiring exact UIElement types.
+ */
+export type SnapSpecInput = {
+    root: string;
+    elements: Record<string, SnapElementInput>;
+    state?: Record<string, unknown>;
+};
+/**
+ * Return type for snap handler functions.
+ * Uses permissive input types so handlers can build elements dynamically
+ * without type casts. Runtime validation via the Zod schema still catches invalid shapes.
+ */
+export type SnapHandlerResult = {
+    version: SpecVersion;
+    theme?: {
+        accent?: z.input<typeof themeAccentSchema>;
+    };
+    effects?: z.input<typeof snapResponseSchema>["effects"];
+    ui: SnapSpecInput;
+};
 export declare const payloadSchema: z.ZodObject<{
-    fid: z.ZodNumber;
+    fid: z.ZodOptional<z.ZodNumber>;
     inputs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>>;
-    button_index: z.ZodNumber;
     timestamp: z.ZodNumber;
-}, z.core.$strict>;
+    audience: z.ZodString;
+    user: z.ZodObject<{
+        fid: z.ZodNumber;
+    }, z.core.$strip>;
+    surface: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"cast">;
+        cast: z.ZodObject<{
+            hash: z.ZodString;
+            author: z.ZodObject<{
+                fid: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"standalone">;
+    }, z.core.$strip>], "type">;
+}, z.core.$strip>;
 export type SnapPayload = z.infer<typeof payloadSchema>;
 export declare const ACTION_TYPE_GET: "get";
 export declare const ACTION_TYPE_POST: "post";
@@ -36,27 +96,54 @@ declare const snapGetActionSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type SnapGetAction = z.infer<typeof snapGetActionSchema>;
 declare const snapPostActionSchema: z.ZodObject<{
-    fid: z.ZodNumber;
+    fid: z.ZodOptional<z.ZodNumber>;
     inputs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>>;
-    button_index: z.ZodNumber;
     timestamp: z.ZodNumber;
+    audience: z.ZodString;
+    user: z.ZodObject<{
+        fid: z.ZodNumber;
+    }, z.core.$strip>;
+    surface: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"cast">;
+        cast: z.ZodObject<{
+            hash: z.ZodString;
+            author: z.ZodObject<{
+                fid: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"standalone">;
+    }, z.core.$strip>], "type">;
     type: z.ZodLiteral<"post">;
-}, z.core.$strict>;
+}, z.core.$strip>;
 export type SnapPostAction = z.infer<typeof snapPostActionSchema>;
 export declare const snapActionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"get">;
 }, z.core.$strip>, z.ZodObject<{
-    fid: z.ZodNumber;
+    fid: z.ZodOptional<z.ZodNumber>;
     inputs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>>;
-    button_index: z.ZodNumber;
     timestamp: z.ZodNumber;
+    audience: z.ZodString;
+    user: z.ZodObject<{
+        fid: z.ZodNumber;
+    }, z.core.$strip>;
+    surface: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"cast">;
+        cast: z.ZodObject<{
+            hash: z.ZodString;
+            author: z.ZodObject<{
+                fid: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"standalone">;
+    }, z.core.$strip>], "type">;
     type: z.ZodLiteral<"post">;
-}, z.core.$strict>], "type">;
+}, z.core.$strip>], "type">;
 export type SnapAction = z.infer<typeof snapActionSchema>;
 export type SnapContext = {
     action: SnapAction;
     request: Request;
-    data: SnapDataStore;
 };
 export type SnapFunction = (ctx: SnapContext) => Promise<SnapHandlerResult>;
 export {};

package/dist/schemas.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
-import { EFFECT_VALUES, SPEC_VERSION, } from "./constants.js";
-import { DEFAULT_THEME_ACCENT, PALETTE_COLOR_VALUES, } from "./colors.js";
+import { EFFECT_VALUES, SUPPORTED_SPEC_VERSIONS, } from "./constants.js";
+import { DEFAULT_THEME_ACCENT, PALETTE_COLOR_VALUES } from "./colors.js";
 // ─── Theme ─────────────────────────────────────────────
 const themeAccentSchema = z.enum(PALETTE_COLOR_VALUES, {
     message: `accent must be a palette color: ${PALETTE_COLOR_VALUES.join(", ")}`,
@@ -15,7 +15,7 @@ const themeSchema = z
 // typed here via the json-render Spec type.
 export const snapResponseSchema = z
     .object({
-    version: z.literal(SPEC_VERSION),
+    version: z.enum(SUPPORTED_SPEC_VERSIONS),
     theme: themeSchema.optional().default({ accent: DEFAULT_THEME_ACCENT }),
     effects: z.array(z.enum(EFFECT_VALUES)).optional(),
     ui: z.custom((val) => val != null &&
@@ -31,24 +31,42 @@ const postInputValueSchema = z.union([
     z.boolean(),
     z.array(z.string()),
 ]);
+const standaloneSurfaceSchema = z.object({
+    type: z.literal("standalone"),
+});
+const castSurfaceSchema = z.object({
+    type: z.literal("cast"),
+    cast: z.object({
+        hash: z.string(),
+        author: z.object({
+            fid: z.number().int().nonnegative(),
+        }),
+    }),
+});
+const surfaceSchema = z.discriminatedUnion("type", [
+    castSurfaceSchema,
+    standaloneSurfaceSchema,
+]);
 export const payloadSchema = z
     .object({
-    fid: z.number().int().nonnegative(),
+    fid: z.number().int().nonnegative().optional(), // deprecated in favor of user.fid
     inputs: z.record(z.string(), postInputValueSchema).default({}),
-    button_index: z.number().int().nonnegative(),
     timestamp: z.number().int(),
+    audience: z.string(),
+    user: z.object({
+        fid: z.number().int().nonnegative(),
+    }),
+    surface: surfaceSchema,
 })
-    .strict();
+    .strip();
 export const ACTION_TYPE_GET = "get";
 export const ACTION_TYPE_POST = "post";
 const snapGetActionSchema = z.object({
     type: z.literal(ACTION_TYPE_GET),
 });
-const snapPostActionSchema = payloadSchema
-    .extend({
+const snapPostActionSchema = payloadSchema.extend({
     type: z.literal(ACTION_TYPE_POST),
-})
-    .strict();
+});
 export const snapActionSchema = z.discriminatedUnion("type", [
     snapGetActionSchema,
     snapPostActionSchema,

package/dist/server/parseRequest.d.ts

@@ -15,6 +15,12 @@ export type ParseRequestError = {
 } | {
     type: "signature";
     message: string;
+} | {
+    type: "origin_mismatch";
+    message: string;
+} | {
+    type: "fid_mismatch";
+    message: string;
 };
 export type ParseRequestOptions = {
     /**
@@ -27,6 +33,10 @@ export type ParseRequestOptions = {
      * potential replays. Defaults to 300 (5 minutes) when not provided.
      */
     maxSkewSeconds?: number;
+    /**
+     * The origin of the request. Derived from the request when not provided.
+     */
+    requestOrigin?: string;
 };
 export type ParseRequestResult = {
     success: true;

package/dist/server/parseRequest.js

@@ -51,6 +51,14 @@ export async function parseRequest(request, options = {}) {
             error: { type: "invalid_json", message: parsed.error.message },
         };
     }
+    const payloadParsed = payloadSchema.safeParse(decodePayload(parsed.data.payload));
+    if (!payloadParsed.success) {
+        return {
+            success: false,
+            error: { type: "validation", issues: payloadParsed.error.issues },
+        };
+    }
+    const body = payloadParsed.data;
     if (!options.skipJFSVerification) {
         const jfs = await verifyJFSRequestBody(parsed.data);
         if (!jfs.valid) {
@@ -59,21 +67,54 @@ export async function parseRequest(request, options = {}) {
                 error: { type: "signature", message: jfs.error.message },
             };
         }
+        if (jfs.signingUserFid !== body.user.fid) {
+            return {
+                success: false,
+                error: {
+                    type: "fid_mismatch",
+                    message: `JFS header fid "${jfs.signingUserFid}" does not match user.fid "${body.user.fid}"`,
+                },
+            };
+        }
     }
-    const payloadParsed = payloadSchema.safeParse(decodePayload(parsed.data.payload));
-    if (!payloadParsed.success) {
+    if (Math.abs(nowSec - body.timestamp) > maxSkew) {
         return {
             success: false,
-            error: { type: "validation", issues: payloadParsed.error.issues },
+            error: {
+                type: "replay",
+                message: `timestamp outside allowed skew of ${maxSkew}s`,
+            },
         };
     }
-    const body = payloadParsed.data;
-    if (Math.abs(nowSec - body.timestamp) > maxSkew) {
+    // Audience validation: ensure the payload audience matches the server origin.
+    let expectedOrigin = options.requestOrigin;
+    if (expectedOrigin === undefined) {
+        try {
+            const url = new URL(request.url);
+            const proto = request.headers.get("x-forwarded-proto") ??
+                url.protocol.replace(":", "");
+            const host = request.headers.get("x-forwarded-host") ?? url.host;
+            expectedOrigin = `${proto}://${host}`;
+        }
+        catch {
+            // do nothing
+        }
+    }
+    if (expectedOrigin !== undefined && body.audience !== expectedOrigin) {
         return {
             success: false,
             error: {
-                type: "replay",
-                message: `timestamp outside allowed skew of ${maxSkew}s`,
+                type: "origin_mismatch",
+                message: `payload audience "${body.audience}" does not match expected origin "${expectedOrigin}"`,
+            },
+        };
+    }
+    if (body.fid !== undefined && body.fid !== body.user.fid) {
+        return {
+            success: false,
+            error: {
+                type: "fid_mismatch",
+                message: `fid "${body.fid}" does not match user.fid "${body.user.fid}"`,
             },
         };
     }

package/dist/server/verify.d.ts

@@ -9,6 +9,7 @@ export declare function verifyJFSRequestBody<TPayload>(requestBody: {
     error: Error;
 } | {
     valid: true;
+    signingUserFid: number;
     data: TPayload;
 }>;
 export declare function decodePayload<TPayload>(payload: string): TPayload;

package/dist/server/verify.js

@@ -69,6 +69,7 @@ export async function verifyJFSRequestBody(requestBody, options = {}) {
     return {
         valid: true,
         data: payload,
+        signingUserFid: header.fid,
     };
 }
 export function decodePayload(payload) {

package/dist/ui/badge.d.ts

@@ -1,7 +1,12 @@
 import { z } from "zod";
+export declare const BADGE_VARIANTS: readonly ["default", "outline"];
 export declare const BADGE_MAX_LABEL_CHARS = 30;
 export declare const badgeProps: z.ZodObject<{
     label: z.ZodString;
+    variant: z.ZodOptional<z.ZodEnum<{
+        default: "default";
+        outline: "outline";
+    }>>;
     color: z.ZodOptional<z.ZodEnum<{
         gray: "gray";
         blue: "blue";
@@ -14,18 +19,18 @@ export declare const badgeProps: z.ZodObject<{
         accent: "accent";
     }>>;
     icon: z.ZodOptional<z.ZodEnum<{
-        check: "check";
-        repeat: "repeat";
         "arrow-right": "arrow-right";
         "arrow-left": "arrow-left";
         "external-link": "external-link";
         "chevron-right": "chevron-right";
+        check: "check";
         x: "x";
         "alert-triangle": "alert-triangle";
         info: "info";
         clock: "clock";
         heart: "heart";
         "message-circle": "message-circle";
+        repeat: "repeat";
         share: "share";
         user: "user";
         users: "users";

package/dist/ui/badge.js

@@ -1,9 +1,11 @@
 import { z } from "zod";
 import { PROGRESS_COLOR_VALUES } from "../colors.js";
 import { ICON_NAMES } from "./icon.js";
+export const BADGE_VARIANTS = ["default", "outline"];
 export const BADGE_MAX_LABEL_CHARS = 30;
 export const badgeProps = z.object({
     label: z.string().min(1).max(BADGE_MAX_LABEL_CHARS),
+    variant: z.enum(BADGE_VARIANTS).optional(),
     color: z.enum(PROGRESS_COLOR_VALUES).optional(),
     icon: z.enum(ICON_NAMES).optional(),
 });

package/dist/ui/bar-chart.d.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+export declare const barChartProps: z.ZodObject<{
+    bars: z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        value: z.ZodNumber;
+        color: z.ZodOptional<z.ZodEnum<{
+            gray: "gray";
+            blue: "blue";
+            red: "red";
+            amber: "amber";
+            green: "green";
+            teal: "teal";
+            purple: "purple";
+            pink: "pink";
+        }>>;
+    }, z.core.$strip>>;
+    max: z.ZodOptional<z.ZodNumber>;
+    color: z.ZodOptional<z.ZodEnum<{
+        gray: "gray";
+        blue: "blue";
+        red: "red";
+        amber: "amber";
+        green: "green";
+        teal: "teal";
+        purple: "purple";
+        pink: "pink";
+        accent: "accent";
+    }>>;
+}, z.core.$strip>;
+export type BarChartProps = z.infer<typeof barChartProps>;

package/dist/ui/bar-chart.js

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import { BAR_CHART_COLOR_VALUES, PALETTE_COLOR_VALUES } from "../colors.js";
+import { BAR_CHART_MAX_BARS, BAR_CHART_LABEL_MAX_CHARS, } from "../constants.js";
+export const barChartProps = z
+    .object({
+    bars: z
+        .array(z.object({
+        label: z.string().min(1).max(BAR_CHART_LABEL_MAX_CHARS),
+        value: z.number().nonnegative(),
+        color: z.enum(PALETTE_COLOR_VALUES).optional(),
+    }))
+        .min(1)
+        .max(BAR_CHART_MAX_BARS),
+    max: z.number().nonnegative().optional(),
+    color: z.enum(BAR_CHART_COLOR_VALUES).optional(),
+})
+    .superRefine((val, ctx) => {
+    if (val.max !== undefined) {
+        for (let i = 0; i < val.bars.length; i++) {
+            const bar = val.bars[i];
+            if (bar.value > val.max) {
+                ctx.addIssue({
+                    code: "custom",
+                    message: `bar value (${bar.value}) exceeds chart max (${val.max})`,
+                    path: ["bars", i, "value"],
+                });
+            }
+        }
+    }
+});

package/dist/ui/button.d.ts

@@ -1,27 +1,25 @@
 import { z } from "zod";
-export declare const BUTTON_VARIANTS: readonly ["default", "secondary", "outline", "ghost"];
+export declare const BUTTON_VARIANTS: readonly ["secondary", "primary"];
 export declare const BUTTON_MAX_LABEL_CHARS = 30;
 export declare const buttonProps: z.ZodObject<{
     label: z.ZodString;
     variant: z.ZodOptional<z.ZodEnum<{
-        default: "default";
         secondary: "secondary";
-        outline: "outline";
-        ghost: "ghost";
+        primary: "primary";
     }>>;
     icon: z.ZodOptional<z.ZodEnum<{
-        check: "check";
-        repeat: "repeat";
         "arrow-right": "arrow-right";
         "arrow-left": "arrow-left";
         "external-link": "external-link";
         "chevron-right": "chevron-right";
+        check: "check";
         x: "x";
         "alert-triangle": "alert-triangle";
         info: "info";
         clock: "clock";
         heart: "heart";
         "message-circle": "message-circle";
+        repeat: "repeat";
         share: "share";
         user: "user";
         users: "users";

package/dist/ui/button.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { ICON_NAMES } from "./icon.js";
-export const BUTTON_VARIANTS = ["default", "secondary", "outline", "ghost"];
+export const BUTTON_VARIANTS = ["secondary", "primary"];
 export const BUTTON_MAX_LABEL_CHARS = 30;
 export const buttonProps = z.object({
     label: z.string().min(1).max(BUTTON_MAX_LABEL_CHARS),