@farcaster/snap 1.3.2 → 1.4.0

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { POST_GRID_TAP_KEY, PAGE_ROOT_TYPE, ELEMENT_TYPE, MEDIA_TYPE, DEFAULT_THEME_ACCENT, DEFAULT_LIST_STYLE, DEFAULT_SLIDER_STEP, PALETTE_COLOR, PALETTE_COLOR_VALUES, PALETTE_LIGHT_HEX, PALETTE_DARK_HEX, type PaletteColor, } from "./constants.js";
-export { rootSchema, firstPageRootSchema, payloadSchema, type SnapAction, type SnapContext, type SnapResponse, type SnapFunction, type SnapPayload, } from "./schemas.js";
-export { validatePage, validateFirstPage, type ValidationResult, } from "./validator.js";
+export { snapResponseSchema, firstPageResponseSchema, payloadSchema, type SnapAction, type SnapContext, type SnapResponse, type SnapHandlerResult, type SnapFunction, type SnapPayload, } from "./schemas.js";
+export { validateSnapResponse, validateFirstPageResponse, type ValidationResult, } from "./validator.js";

package/dist/index.js

@@ -1,3 +1,3 @@
 export { POST_GRID_TAP_KEY, PAGE_ROOT_TYPE, ELEMENT_TYPE, MEDIA_TYPE, DEFAULT_THEME_ACCENT, DEFAULT_LIST_STYLE, DEFAULT_SLIDER_STEP, PALETTE_COLOR, PALETTE_COLOR_VALUES, PALETTE_LIGHT_HEX, PALETTE_DARK_HEX, } from "./constants.js";
-export { rootSchema, firstPageRootSchema, payloadSchema, } from "./schemas.js";
-export { validatePage, validateFirstPage, } from "./validator.js";
+export { snapResponseSchema, firstPageResponseSchema, payloadSchema, } from "./schemas.js";
+export { validateSnapResponse, validateFirstPageResponse, } from "./validator.js";

package/dist/schemas.d.ts

@@ -13,6 +13,7 @@ declare const buttonSchema: z.ZodObject<{
         secondary: "secondary";
     }>>;
 }, z.core.$strip>;
+export type Button = z.infer<typeof buttonSchema>;
 /** Any single page element, including media and `group` */
 declare const elementSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"text">;
@@ -326,6 +327,7 @@ declare const elementSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         accent: "accent";
     }>>;
 }, z.core.$strip>], "type">;
+export type Element = z.infer<typeof elementSchema>;
 declare const elementsSchema: z.ZodObject<{
     type: z.ZodLiteral<"stack">;
     children: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -641,10 +643,8 @@ declare const elementsSchema: z.ZodObject<{
         }>>;
     }, z.core.$strip>], "type">>;
 }, z.core.$strict>;
-export type Button = z.infer<typeof buttonSchema>;
-export type Element = z.infer<typeof elementSchema>;
 export type Elements = z.infer<typeof elementsSchema>;
-export declare const rootSchema: z.ZodObject<{
+export declare const snapResponseSchema: z.ZodObject<{
     version: z.ZodLiteral<"1.0">;
     page: z.ZodObject<{
         theme: z.ZodDefault<z.ZodOptional<z.ZodObject<{
@@ -998,7 +998,9 @@ export declare const rootSchema: z.ZodObject<{
         }, z.core.$strip>>>;
     }, z.core.$strict>;
 }, z.core.$strict>;
-export declare const firstPageRootSchema: z.ZodObject<{
+export type SnapResponse = z.infer<typeof snapResponseSchema>;
+export type SnapHandlerResult = z.input<typeof snapResponseSchema>;
+export declare const firstPageResponseSchema: z.ZodObject<{
     version: z.ZodLiteral<"1.0">;
     page: z.ZodObject<{
         theme: z.ZodDefault<z.ZodOptional<z.ZodObject<{
@@ -1352,6 +1354,7 @@ export declare const firstPageRootSchema: z.ZodObject<{
         }, z.core.$strip>>>;
     }, z.core.$strict>;
 }, z.core.$strict>;
+export type FirstPageResponse = z.infer<typeof firstPageResponseSchema>;
 export declare const payloadSchema: z.ZodObject<{
     fid: z.ZodNumber;
     inputs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodObject<{
@@ -1361,26 +1364,40 @@ export declare const payloadSchema: z.ZodObject<{
     button_index: z.ZodNumber;
     timestamp: z.ZodNumber;
 }, z.core.$strict>;
-export type SnapResponse = z.infer<typeof rootSchema>;
-export type SnapPage = SnapResponse["page"];
 export type SnapPayload = z.infer<typeof payloadSchema>;
+export declare const ACTION_TYPE_GET: "get";
+export declare const ACTION_TYPE_POST: "post";
+declare const snapGetActionSchema: z.ZodObject<{
+    type: z.ZodLiteral<"get">;
+}, z.core.$strip>;
+export type SnapGetAction = z.infer<typeof snapGetActionSchema>;
 declare const snapPostActionSchema: z.ZodObject<{
     fid: z.ZodNumber;
     inputs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodObject<{
         row: z.ZodNumber;
         col: z.ZodNumber;
     }, z.core.$strict>]>>>;
+    button_index: z.ZodNumber;
     timestamp: z.ZodNumber;
     type: z.ZodLiteral<"post">;
-    buttonIndex: z.ZodNumber;
 }, z.core.$strict>;
 export type SnapPostAction = z.infer<typeof snapPostActionSchema>;
-export type SnapAction = {
-    type: "get";
-} | SnapPostAction;
+export declare const snapActionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"get">;
+}, z.core.$strip>, z.ZodObject<{
+    fid: z.ZodNumber;
+    inputs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodObject<{
+        row: z.ZodNumber;
+        col: z.ZodNumber;
+    }, z.core.$strict>]>>>;
+    button_index: z.ZodNumber;
+    timestamp: z.ZodNumber;
+    type: z.ZodLiteral<"post">;
+}, z.core.$strict>], "type">;
+export type SnapAction = z.infer<typeof snapActionSchema>;
 export type SnapContext = {
     action: SnapAction;
     request: Request;
 };
-export type SnapFunction = (ctx: SnapContext) => Promise<SnapResponse>;
+export type SnapFunction = (ctx: SnapContext) => Promise<SnapHandlerResult>;
 export {};

package/dist/schemas.js

@@ -368,7 +368,7 @@ const elementsSchema = z
     }),
 })
     .strict();
-export const rootSchema = z
+export const snapResponseSchema = z
     .object({
     version: z.literal(SPEC_VERSION),
     page: z
@@ -402,9 +402,9 @@ export const rootSchema = z
 })
     .strict();
 // extra constraints for the first page to make it look nicer
-export const firstPageRootSchema = rootSchema.superRefine((root, ctx) => {
-    const body = root.page.elements.children;
-    const hasTextTitleOrBody = body.some((el) => el.type === ELEMENT_TYPE.text &&
+export const firstPageResponseSchema = snapResponseSchema.superRefine((response, ctx) => {
+    const elements = response.page.elements.children;
+    const hasTextTitleOrBody = elements.some((el) => el.type === ELEMENT_TYPE.text &&
         (el.style === TEXT_STYLE.title || el.style === TEXT_STYLE.body));
     if (!hasTextTitleOrBody) {
         ctx.addIssue({
@@ -413,8 +413,8 @@ export const firstPageRootSchema = rootSchema.superRefine((root, ctx) => {
             path: ["page", "elements", "children"],
         });
     }
-    const hasInteractive = body.some((el) => INTERACTIVE_ELEMENT_TYPES.includes(el.type));
-    const hasMedia = body.some((el) => MEDIA_ELEMENT_TYPES.includes(el.type));
+    const hasInteractive = elements.some((el) => INTERACTIVE_ELEMENT_TYPES.includes(el.type));
+    const hasMedia = elements.some((el) => MEDIA_ELEMENT_TYPES.includes(el.type));
     if (!hasInteractive && !hasMedia) {
         ctx.addIssue({
             code: "custom",
@@ -443,10 +443,17 @@ export const payloadSchema = z
     timestamp: z.number().int(),
 })
     .strict();
+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
-    .omit({ button_index: true })
     .extend({
-    type: z.literal("post"),
-    buttonIndex: payloadSchema.shape.button_index,
+    type: z.literal(ACTION_TYPE_POST),
 })
     .strict();
+export const snapActionSchema = z.discriminatedUnion("type", [
+    snapGetActionSchema,
+    snapPostActionSchema,
+]);

package/dist/server/parseRequest.js

@@ -1,4 +1,4 @@
-import { payloadSchema } from "../schemas.js";
+import { ACTION_TYPE_GET, ACTION_TYPE_POST, payloadSchema, } from "../schemas.js";
 import { decodePayload, verifyJFSRequestBody } from "./verify.js";
 import { z } from "zod";
 /** Default replay window per SPEC.md § Replay Protection (5 minutes). */
@@ -26,7 +26,7 @@ export async function parseRequest(request, options = {}) {
     if (request.method === "GET") {
         return {
             success: true,
-            action: { type: "get" },
+            action: { type: ACTION_TYPE_GET },
         };
     }
     const maxSkew = DEFAULT_SNAP_POST_MAX_SKEW_SECONDS;
@@ -81,11 +81,8 @@ export async function parseRequest(request, options = {}) {
     return {
         success: true,
         action: {
-            type: "post",
-            fid: body.fid,
-            inputs: body.inputs,
-            buttonIndex: body.button_index,
-            timestamp: body.timestamp,
+            type: ACTION_TYPE_POST,
+            ...body,
         },
     };
 }

package/dist/ui/catalog.d.ts

@@ -240,7 +240,7 @@ export declare const snapJsonRenderCatalog: import("@json-render/core").Catalog<
         snap_post: {
             description: string;
             params: z.ZodObject<{
-                buttonIndex: z.ZodNumber;
+                button_index: z.ZodNumber;
                 target: z.ZodString;
                 label: z.ZodOptional<z.ZodString>;
                 style: z.ZodOptional<z.ZodEnum<{

package/dist/ui/catalog.js

@@ -18,7 +18,7 @@ import { groupProps } from "./group.js";
 import { stackProps } from "./stack.js";
 import { actionButtonProps } from "./button.js";
 const snapPostParams = z.object({
-    buttonIndex: z.number().int().nonnegative(),
+    button_index: z.number().int().nonnegative(),
     target: z.string(),
     label: z.string().optional(),
     style: z.enum(BUTTON_STYLE_VALUES).optional(),

package/dist/validator.d.ts

@@ -3,5 +3,5 @@ export type ValidationResult = {
     valid: boolean;
     issues: z.core.$ZodIssue[];
 };
-export declare function validatePage(json: unknown): ValidationResult;
-export declare function validateFirstPage(json: unknown): ValidationResult;
+export declare function validateSnapResponse(json: unknown): ValidationResult;
+export declare function validateFirstPageResponse(json: unknown): ValidationResult;

package/dist/validator.js

@@ -1,5 +1,5 @@
 import { BUTTON_GROUP_STYLE, DEFAULT_BUTTON_LAYOUT, ELEMENT_TYPE, LIMITS, SPACER_SIZE, TEXT_STYLE, } from "./constants.js";
-import { firstPageRootSchema, rootSchema, } from "./schemas.js";
+import { firstPageResponseSchema, snapResponseSchema, } from "./schemas.js";
 /** Not in SPEC — rough px used only for {@link measureHeightBudget}. */
 const PAGE_HEIGHT_HEURISTIC = {
     baseChromePx: 32,
@@ -116,8 +116,8 @@ function heightBudgetValidationErrorForRoot(root) {
         : DEFAULT_BUTTON_LAYOUT;
     return heightBudgetValidationError(root.page.elements.children, root.page.buttons ?? [], layout);
 }
-export function validatePage(json) {
-    const parsed = rootSchema.safeParse(json);
+export function validateSnapResponse(json) {
+    const parsed = snapResponseSchema.safeParse(json);
     if (!parsed.success) {
         return {
             valid: false,
@@ -130,8 +130,8 @@ export function validatePage(json) {
     }
     return { valid: true, issues: [] };
 }
-export function validateFirstPage(json) {
-    const parsed = firstPageRootSchema.safeParse(json);
+export function validateFirstPageResponse(json) {
+    const parsed = firstPageResponseSchema.safeParse(json);
     if (!parsed.success) {
         return {
             valid: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farcaster/snap",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "description": "Farcaster Snaps 🫰",
   "repository": {
     "type": "git",

package/src/index.ts

@@ -13,17 +13,18 @@ export {
   type PaletteColor,
 } from "./constants";
 export {
-  rootSchema,
-  firstPageRootSchema,
+  snapResponseSchema,
+  firstPageResponseSchema,
   payloadSchema,
   type SnapAction,
   type SnapContext,
   type SnapResponse,
+  type SnapHandlerResult,
   type SnapFunction,
   type SnapPayload,
 } from "./schemas";
 export {
-  validatePage,
-  validateFirstPage,
+  validateSnapResponse,
+  validateFirstPageResponse,
   type ValidationResult,
 } from "./validator";

package/src/schemas.ts

@@ -391,6 +391,8 @@ const buttonSchema = z
     }
   });
 
+export type Button = z.infer<typeof buttonSchema>;
+
 /** Child elements allowed inside `group` (no media, no nested group) */
 const groupChildElementSchema = z.discriminatedUnion("type", [
   textElementSchema,
@@ -431,6 +433,8 @@ const elementSchema = z.discriminatedUnion("type", [
   barChartElementSchema,
 ]);
 
+export type Element = z.infer<typeof elementSchema>;
+
 const elementsSchema = z
   .object({
     type: z.literal(PAGE_ROOT_TYPE.stack),
@@ -443,11 +447,9 @@ const elementsSchema = z
   })
   .strict();
 
-export type Button = z.infer<typeof buttonSchema>;
-export type Element = z.infer<typeof elementSchema>;
 export type Elements = z.infer<typeof elementsSchema>;
 
-export const rootSchema = z
+export const snapResponseSchema = z
   .object({
     version: z.literal(SPEC_VERSION),
     page: z
@@ -481,37 +483,48 @@ export const rootSchema = z
   })
   .strict();
 
+// canonical snap response type
+export type SnapResponse = z.infer<typeof snapResponseSchema>;
+// what snap handlers may return (keeps optional fields optional)
+export type SnapHandlerResult = z.input<typeof snapResponseSchema>;
+
 // extra constraints for the first page to make it look nicer
-export const firstPageRootSchema = rootSchema.superRefine((root, ctx) => {
-  const body = root.page.elements.children;
-
-  const hasTextTitleOrBody = body.some(
-    (el) =>
-      el.type === ELEMENT_TYPE.text &&
-      (el.style === TEXT_STYLE.title || el.style === TEXT_STYLE.body),
-  );
-  if (!hasTextTitleOrBody) {
-    ctx.addIssue({
-      code: "custom",
-      message:
-        'first page must have at least one text element with style "title" or "body"',
-      path: ["page", "elements", "children"],
-    });
-  }
+export const firstPageResponseSchema = snapResponseSchema.superRefine(
+  (response, ctx) => {
+    const elements = response.page.elements.children;
+
+    const hasTextTitleOrBody = elements.some(
+      (el) =>
+        el.type === ELEMENT_TYPE.text &&
+        (el.style === TEXT_STYLE.title || el.style === TEXT_STYLE.body),
+    );
+    if (!hasTextTitleOrBody) {
+      ctx.addIssue({
+        code: "custom",
+        message:
+          'first page must have at least one text element with style "title" or "body"',
+        path: ["page", "elements", "children"],
+      });
+    }
 
-  const hasInteractive = body.some((el) =>
-    INTERACTIVE_ELEMENT_TYPES.includes(el.type),
-  );
-  const hasMedia = body.some((el) => MEDIA_ELEMENT_TYPES.includes(el.type));
-  if (!hasInteractive && !hasMedia) {
-    ctx.addIssue({
-      code: "custom",
-      message:
-        "first page must have at least one interactive element (button_group, slider, text_input, toggle) or media element (image, grid)",
-      path: ["page", "elements", "children"],
-    });
-  }
-});
+    const hasInteractive = elements.some((el) =>
+      INTERACTIVE_ELEMENT_TYPES.includes(el.type),
+    );
+    const hasMedia = elements.some((el) =>
+      MEDIA_ELEMENT_TYPES.includes(el.type),
+    );
+    if (!hasInteractive && !hasMedia) {
+      ctx.addIssue({
+        code: "custom",
+        message:
+          "first page must have at least one interactive element (button_group, slider, text_input, toggle) or media element (image, grid)",
+        path: ["page", "elements", "children"],
+      });
+    }
+  },
+);
+
+export type FirstPageResponse = z.infer<typeof firstPageResponseSchema>;
 
 const postInputValueSchema = z.union([
   z.string(),
@@ -535,29 +548,35 @@ export const payloadSchema = z
   })
   .strict();
 
-export type SnapResponse = z.infer<typeof rootSchema>;
-export type SnapPage = SnapResponse["page"];
 export type SnapPayload = z.infer<typeof payloadSchema>;
 
+export const ACTION_TYPE_GET = "get" as const;
+export const ACTION_TYPE_POST = "post" as const;
+
+const snapGetActionSchema = z.object({
+  type: z.literal(ACTION_TYPE_GET),
+});
+
+export type SnapGetAction = z.infer<typeof snapGetActionSchema>;
+
 const snapPostActionSchema = payloadSchema
-  .omit({ button_index: true })
   .extend({
-    type: z.literal("post"),
-    buttonIndex: payloadSchema.shape.button_index,
+    type: z.literal(ACTION_TYPE_POST),
   })
   .strict();
 
 export type SnapPostAction = z.infer<typeof snapPostActionSchema>;
 
-export type SnapAction =
-  | {
-      type: "get";
-    }
-  | SnapPostAction;
+export const snapActionSchema = z.discriminatedUnion("type", [
+  snapGetActionSchema,
+  snapPostActionSchema,
+]);
+
+export type SnapAction = z.infer<typeof snapActionSchema>;
 
 export type SnapContext = {
   action: SnapAction;
   request: Request;
 };
 
-export type SnapFunction = (ctx: SnapContext) => Promise<SnapResponse>;
+export type SnapFunction = (ctx: SnapContext) => Promise<SnapHandlerResult>;

package/src/server/parseRequest.ts

@@ -1,4 +1,9 @@
-import { payloadSchema, type SnapAction } from "../schemas";
+import {
+  ACTION_TYPE_GET,
+  ACTION_TYPE_POST,
+  payloadSchema,
+  type SnapAction,
+} from "../schemas";
 import { decodePayload, verifyJFSRequestBody } from "./verify";
 import { z } from "zod";
 
@@ -66,7 +71,7 @@ export async function parseRequest(
   if (request.method === "GET") {
     return {
       success: true,
-      action: { type: "get" },
+      action: { type: ACTION_TYPE_GET },
     };
   }
 
@@ -129,11 +134,8 @@ export async function parseRequest(
   return {
     success: true,
     action: {
-      type: "post",
-      fid: body.fid,
-      inputs: body.inputs,
-      buttonIndex: body.button_index,
-      timestamp: body.timestamp,
+      type: ACTION_TYPE_POST,
+      ...body,
     },
   };
 }

package/src/ui/catalog.ts

@@ -19,7 +19,7 @@ import { stackProps } from "./stack.js";
 import { actionButtonProps } from "./button.js";
 
 const snapPostParams = z.object({
-  buttonIndex: z.number().int().nonnegative(),
+  button_index: z.number().int().nonnegative(),
   target: z.string(),
   label: z.string().optional(),
   style: z.enum(BUTTON_STYLE_VALUES).optional(),

package/src/validator.ts

@@ -8,13 +8,13 @@ import {
   TEXT_STYLE,
 } from "./constants";
 import {
-  firstPageRootSchema,
-  rootSchema,
+  firstPageResponseSchema,
+  snapResponseSchema,
   type Button,
   type Element,
 } from "./schemas";
 
-type SnapRoot = z.infer<typeof rootSchema>;
+type SnapRoot = z.infer<typeof snapResponseSchema>;
 
 export type ValidationResult = {
   valid: boolean;
@@ -158,8 +158,8 @@ function heightBudgetValidationErrorForRoot(
   );
 }
 
-export function validatePage(json: unknown): ValidationResult {
-  const parsed = rootSchema.safeParse(json);
+export function validateSnapResponse(json: unknown): ValidationResult {
+  const parsed = snapResponseSchema.safeParse(json);
   if (!parsed.success) {
     return {
       valid: false,
@@ -175,8 +175,8 @@ export function validatePage(json: unknown): ValidationResult {
   return { valid: true, issues: [] };
 }
 
-export function validateFirstPage(json: unknown): ValidationResult {
-  const parsed = firstPageRootSchema.safeParse(json);
+export function validateFirstPageResponse(json: unknown): ValidationResult {
+  const parsed = firstPageResponseSchema.safeParse(json);
   if (!parsed.success) {
     return {
       valid: false,