@farcaster/snap 0.0.0-canary-20260330145610

package/dist/constants.d.ts

@@ -0,0 +1,135 @@
+export declare const POST_GRID_TAP_KEY: "grid_tap";
+export declare const SPEC_VERSION: "1.0";
+export declare const MEDIA_TYPE: "application/json+farcaster-snap";
+export declare const LIMITS: {
+    readonly maxElementsPerPage: 5;
+    readonly maxButtonsPerPage: 4;
+    readonly maxVideoDurationSeconds: 30;
+    readonly maxTextInputChars: 280;
+    readonly maxListItems: 4;
+    readonly minListItems: 1;
+    readonly minButtonGroupOptions: 2;
+    readonly maxButtonGroupOptions: 4;
+    readonly maxButtonGroupOptionChars: 40;
+    readonly maxButtonLabelChars: 30;
+    readonly listItemContentMaxChars: 100;
+    readonly listItemTrailingMaxChars: 40;
+    readonly minGridCols: 2;
+    readonly maxGridCols: 64;
+    readonly minGridRows: 2;
+    readonly maxGridRows: 8;
+    readonly minGroupChildren: 2;
+    readonly maxGroupChildren: 3;
+    readonly maxBarChartBars: 6;
+    readonly barChartLabelMaxChars: 40;
+    readonly maxEstimatedPageHeightPx: 500;
+};
+export declare const TEXT_STYLE: {
+    readonly title: "title";
+    readonly body: "body";
+    readonly caption: "caption";
+    readonly label: "label";
+};
+export declare const TEXT_STYLE_VALUES: readonly ["title", "body", "caption", "label"];
+export declare const TEXT_ALIGN_VALUES: readonly ["left", "center", "right"];
+export declare const IMAGE_ASPECT_VALUES: readonly ["1:1", "16:9", "4:3", "3:4", "9:16"];
+export declare const VIDEO_ASPECT_VALUES: readonly ["1:1", "16:9", "9:16"];
+export declare const SPACER_SIZE: {
+    readonly small: "small";
+    readonly medium: "medium";
+    readonly large: "large";
+};
+export declare const SPACER_SIZE_VALUES: readonly ["small", "medium", "large"];
+/**
+ * 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 declare const PALETTE_COLOR: {
+    readonly gray: "gray";
+    readonly blue: "blue";
+    readonly red: "red";
+    readonly amber: "amber";
+    readonly green: "green";
+    readonly teal: "teal";
+    readonly purple: "purple";
+    readonly pink: "pink";
+};
+export declare const PALETTE_COLOR_VALUES: readonly ["gray", "blue", "red", "amber", "green", "teal", "purple", "pink"];
+export type PaletteColor = (typeof PALETTE_COLOR_VALUES)[number];
+/** Light-mode hex for each palette color (emulator / reference client). */
+export declare const PALETTE_LIGHT_HEX: Record<PaletteColor, string>;
+/** Dark-mode hex for each palette color (reference). */
+export declare const PALETTE_DARK_HEX: Record<PaletteColor, string>;
+export declare const PROGRESS_COLOR_VALUES: readonly ["accent", "gray", "blue", "red", "amber", "green", "teal", "purple", "pink"];
+export declare const LIST_STYLE_VALUES: readonly ["ordered", "unordered", "plain"];
+export declare const DEFAULT_LIST_STYLE: "ordered";
+export declare const GRID_CELL_SIZE_VALUES: readonly ["auto", "square"];
+export declare const GRID_GAP_VALUES: readonly ["none", "small", "medium"];
+export declare const BUTTON_GROUP_STYLE: {
+    readonly row: "row";
+    readonly stack: "stack";
+    readonly grid: "grid";
+};
+export declare const BUTTON_GROUP_STYLE_VALUES: readonly ["row", "stack", "grid"];
+export declare const BUTTON_ACTION: {
+    readonly post: "post";
+    readonly link: "link";
+    readonly mini_app: "mini_app";
+    readonly sdk: "sdk";
+};
+export declare const BUTTON_ACTION_VALUES: readonly ["post", "link", "mini_app", "sdk"];
+export declare const BUTTON_STYLE: {
+    readonly primary: "primary";
+    readonly secondary: "secondary";
+};
+export declare const BUTTON_STYLE_VALUES: readonly ["primary", "secondary"];
+export declare const BUTTON_LAYOUT_VALUES: readonly ["stack", "row", "grid"];
+export declare const DEFAULT_BUTTON_LAYOUT: "stack";
+export declare const BAR_CHART_COLOR_VALUES: readonly ["accent", "gray", "blue", "red", "amber", "green", "teal", "purple", "pink"];
+export declare const EFFECT_VALUES: readonly ["confetti"];
+export declare const GROUP_LAYOUT_VALUES: readonly ["row"];
+/** Only valid as `page.elements`: vertical container for the page body (matches json-render trees). */
+export declare const PAGE_ROOT_TYPE: {
+    readonly stack: "stack";
+};
+export declare const ELEMENT_TYPE: {
+    readonly text: "text";
+    readonly image: "image";
+    readonly video: "video";
+    readonly divider: "divider";
+    readonly spacer: "spacer";
+    readonly progress: "progress";
+    readonly list: "list";
+    readonly grid: "grid";
+    readonly text_input: "text_input";
+    readonly slider: "slider";
+    readonly button_group: "button_group";
+    readonly toggle: "toggle";
+    readonly group: "group";
+    readonly bar_chart: "bar_chart";
+};
+export type ElementType = (typeof ELEMENT_TYPE)[keyof typeof ELEMENT_TYPE];
+export declare const HTTPS_PREFIX: "https://";
+export declare const HTTP_PREFIX: "http://";
+/** 6-digit hex only (#RRGGBB); used for grid cell backgrounds (free hex). */
+export declare const HEX_COLOR_6_RE: RegExp;
+/** Default snap accent when `page.theme` or `page.theme.accent` is omitted (SPEC.md). */
+export declare const DEFAULT_THEME_ACCENT: "purple";
+export declare const TEXT_CONTENT_MAX: {
+    readonly title: 80;
+    readonly body: 160;
+    readonly caption: 100;
+    readonly label: 40;
+};
+export declare const SLIDER_STEP_ALIGN_EPS = 0.000001;
+export declare const DEFAULT_SLIDER_STEP: 1;
+export declare const MEDIA_ELEMENT_TYPES: ElementType[];
+export declare const INTERACTIVE_ELEMENT_TYPES: ElementType[];

package/dist/constants.js

@@ -0,0 +1,202 @@
+export const POST_GRID_TAP_KEY = "grid_tap";
+export const SPEC_VERSION = "1.0";
+export const MEDIA_TYPE = "application/json+farcaster-snap";
+export const LIMITS = {
+    maxElementsPerPage: 5,
+    maxButtonsPerPage: 4,
+    maxVideoDurationSeconds: 30,
+    maxTextInputChars: 280,
+    maxListItems: 4,
+    minListItems: 1,
+    minButtonGroupOptions: 2,
+    maxButtonGroupOptions: 4,
+    maxButtonGroupOptionChars: 40,
+    maxButtonLabelChars: 30,
+    listItemContentMaxChars: 100,
+    listItemTrailingMaxChars: 40,
+    minGridCols: 2,
+    maxGridCols: 64,
+    minGridRows: 2,
+    maxGridRows: 8,
+    minGroupChildren: 2,
+    maxGroupChildren: 3,
+    maxBarChartBars: 6,
+    barChartLabelMaxChars: 40,
+    maxEstimatedPageHeightPx: 500,
+};
+export const TEXT_STYLE = {
+    title: "title",
+    body: "body",
+    caption: "caption",
+    label: "label",
+};
+export const TEXT_STYLE_VALUES = [
+    TEXT_STYLE.title,
+    TEXT_STYLE.body,
+    TEXT_STYLE.caption,
+    TEXT_STYLE.label,
+];
+export const TEXT_ALIGN_VALUES = ["left", "center", "right"];
+export const IMAGE_ASPECT_VALUES = [
+    "1:1",
+    "16:9",
+    "4:3",
+    "3:4",
+    "9:16",
+];
+export const VIDEO_ASPECT_VALUES = ["1:1", "16:9", "9:16"];
+export const SPACER_SIZE = {
+    small: "small",
+    medium: "medium",
+    large: "large",
+};
+export const SPACER_SIZE_VALUES = [
+    SPACER_SIZE.small,
+    SPACER_SIZE.medium,
+    SPACER_SIZE.large,
+];
+/**
+ * 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",
+};
+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,
+];
+/** Light-mode hex for each palette color (emulator / reference client). */
+export const PALETTE_LIGHT_HEX = {
+    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 = {
+    gray: "#8F8F8F",
+    blue: "#006FFE",
+    red: "#F13342",
+    amber: "#FFAE00",
+    green: "#00AC3A",
+    teal: "#00AA96",
+    purple: "#A78BFA",
+    pink: "#F12B82",
+};
+export const PROGRESS_COLOR_VALUES = [
+    "accent",
+    ...PALETTE_COLOR_VALUES,
+];
+export const LIST_STYLE_VALUES = ["ordered", "unordered", "plain"];
+export const DEFAULT_LIST_STYLE = "ordered";
+export const GRID_CELL_SIZE_VALUES = ["auto", "square"];
+export const GRID_GAP_VALUES = ["none", "small", "medium"];
+export const BUTTON_GROUP_STYLE = {
+    row: "row",
+    stack: "stack",
+    grid: "grid",
+};
+export const BUTTON_GROUP_STYLE_VALUES = [
+    BUTTON_GROUP_STYLE.row,
+    BUTTON_GROUP_STYLE.stack,
+    BUTTON_GROUP_STYLE.grid,
+];
+export const BUTTON_ACTION = {
+    post: "post",
+    link: "link",
+    mini_app: "mini_app",
+    sdk: "sdk",
+};
+export const BUTTON_ACTION_VALUES = [
+    BUTTON_ACTION.post,
+    BUTTON_ACTION.link,
+    BUTTON_ACTION.mini_app,
+    BUTTON_ACTION.sdk,
+];
+export const BUTTON_STYLE = {
+    primary: "primary",
+    secondary: "secondary",
+};
+export const BUTTON_STYLE_VALUES = [
+    BUTTON_STYLE.primary,
+    BUTTON_STYLE.secondary,
+];
+export const BUTTON_LAYOUT_VALUES = ["stack", "row", "grid"];
+export const DEFAULT_BUTTON_LAYOUT = BUTTON_LAYOUT_VALUES[0];
+export const BAR_CHART_COLOR_VALUES = [
+    "accent",
+    ...PALETTE_COLOR_VALUES,
+];
+export const EFFECT_VALUES = ["confetti"];
+export const GROUP_LAYOUT_VALUES = ["row"];
+/** Only valid as `page.elements`: vertical container for the page body (matches json-render trees). */
+export const PAGE_ROOT_TYPE = {
+    stack: "stack",
+};
+export const ELEMENT_TYPE = {
+    text: "text",
+    image: "image",
+    video: "video",
+    divider: "divider",
+    spacer: "spacer",
+    progress: "progress",
+    list: "list",
+    grid: "grid",
+    text_input: "text_input",
+    slider: "slider",
+    button_group: "button_group",
+    toggle: "toggle",
+    group: "group",
+    bar_chart: "bar_chart",
+};
+export const HTTPS_PREFIX = "https://";
+export const HTTP_PREFIX = "http://";
+/** 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,
+    [TEXT_STYLE.caption]: 100,
+    [TEXT_STYLE.label]: 40,
+};
+export const SLIDER_STEP_ALIGN_EPS = 1e-6;
+export const DEFAULT_SLIDER_STEP = 1;
+export const MEDIA_ELEMENT_TYPES = [
+    ELEMENT_TYPE.image,
+    ELEMENT_TYPE.video,
+    ELEMENT_TYPE.grid,
+];
+export const INTERACTIVE_ELEMENT_TYPES = [
+    ELEMENT_TYPE.button_group,
+    ELEMENT_TYPE.slider,
+    ELEMENT_TYPE.text_input,
+    ELEMENT_TYPE.toggle,
+];

package/dist/http.d.ts

@@ -0,0 +1,48 @@
+import { type SnapAction, type SnapResponse, type SnapPage } from "./schemas.js";
+import { z } from "zod";
+export type ParseRequestError = {
+    type: "method_not_allowed";
+    message: string;
+} | {
+    type: "invalid_json";
+    message: string;
+} | {
+    type: "validation";
+    issues: z.core.$ZodIssue[];
+} | {
+    type: "replay";
+    message: string;
+} | {
+    type: "signature";
+    message: string;
+};
+export type ParseRequestOptions = {
+    /**
+     * When true, skip {@link verifyJFSRequestBody} (signature checks).
+     */
+    skipJFSVerification?: boolean;
+};
+export type ParseRequestResult = {
+    success: true;
+    action: SnapAction;
+} | {
+    success: false;
+    error: ParseRequestError;
+};
+/**
+ * Parse and validate Farcaster snap requests:
+ * - `GET` is allowed for first-page loads and returns `{ type: "get" }`.
+ * - `POST`: the body must be JSON in JFS form (`header` / `payload` / `signature`) even if JFS verification is skipped.
+ */
+export declare function parseRequest(request: Request, options?: ParseRequestOptions): Promise<ParseRequestResult>;
+export type SendResponseOptions = ResponseInit & {
+    /** When false, invalid pages return 500 instead of 400. Default true. */
+    clientErrorOnInvalid?: boolean;
+};
+/**
+ * Validate a snap root or bare `page` object, then return a JSON Response for the client.
+ * Sets `Content-Type: application/json+farcaster-snap`.
+ *
+ * On validation failure returns JSON `{ "error": "...", "issues": [...] }` with status 400 or 500.
+ */
+export declare function sendResponse(payload: SnapResponse | SnapPage, init?: SendResponseOptions): Response;

package/dist/http.js

@@ -0,0 +1,146 @@
+import { MEDIA_TYPE, SPEC_VERSION } from "./constants.js";
+import { decodePayload, verifyJFSRequestBody } from "./verify.js";
+import { payloadSchema, rootSchema, } from "./schemas.js";
+import { validatePage } from "./validator.js";
+import { z } from "zod";
+/** Default replay window per SPEC.md § Replay Protection (5 minutes). */
+const DEFAULT_SNAP_POST_MAX_SKEW_SECONDS = 300;
+function isRecord(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+function normalizeToRoot(payload) {
+    if (isRecord(payload) && "version" in payload && "page" in payload) {
+        return payload;
+    }
+    return { version: SPEC_VERSION, page: payload };
+}
+const requestBodySchema = z.object({
+    header: z.string(),
+    payload: z.string(),
+    signature: z.string(),
+});
+/**
+ * Parse and validate Farcaster snap requests:
+ * - `GET` is allowed for first-page loads and returns `{ type: "get" }`.
+ * - `POST`: the body must be JSON in JFS form (`header` / `payload` / `signature`) even if JFS verification is skipped.
+ */
+export async function parseRequest(request, options = {}) {
+    if (!["GET", "POST"].includes(request.method)) {
+        return {
+            success: false,
+            error: {
+                type: "method_not_allowed",
+                message: `expected POST, received ${request.method}`,
+            },
+        };
+    }
+    if (request.method === "GET") {
+        return {
+            success: true,
+            action: { type: "get" },
+        };
+    }
+    const maxSkew = DEFAULT_SNAP_POST_MAX_SKEW_SECONDS;
+    const nowSec = Math.floor(Date.now() / 1000);
+    const text = await request.text();
+    let jsonBody;
+    try {
+        jsonBody = JSON.parse(text);
+    }
+    catch {
+        return {
+            success: false,
+            error: {
+                type: "invalid_json",
+                message: "request body is not valid JSON",
+            },
+        };
+    }
+    const parsed = requestBodySchema.safeParse(jsonBody);
+    if (!parsed.success) {
+        return {
+            success: false,
+            error: { type: "invalid_json", message: parsed.error.message },
+        };
+    }
+    if (!options.skipJFSVerification) {
+        const jfs = await verifyJFSRequestBody(parsed.data);
+        if (!jfs.valid) {
+            return {
+                success: false,
+                error: { type: "signature", message: jfs.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 (Math.abs(nowSec - body.timestamp) > maxSkew) {
+        return {
+            success: false,
+            error: {
+                type: "replay",
+                message: `timestamp outside allowed skew of ${maxSkew}s`,
+            },
+        };
+    }
+    return {
+        success: true,
+        action: {
+            type: "post",
+            fid: body.fid,
+            inputs: body.inputs,
+            buttonIndex: body.button_index,
+            timestamp: body.timestamp,
+        },
+    };
+}
+/**
+ * Validate a snap root or bare `page` object, then return a JSON Response for the client.
+ * Sets `Content-Type: application/json+farcaster-snap`.
+ *
+ * On validation failure returns JSON `{ "error": "...", "issues": [...] }` with status 400 or 500.
+ */
+export function sendResponse(payload, init) {
+    const rootUnknown = normalizeToRoot(payload);
+    const validation = validatePage(rootUnknown);
+    const clientError = init?.clientErrorOnInvalid !== false;
+    const status = init?.status;
+    if (!validation.valid) {
+        const errStatus = clientError ? 400 : 500;
+        return new Response(JSON.stringify({
+            error: clientError
+                ? "invalid snap page"
+                : "server produced an invalid snap page",
+            issues: validation.issues,
+        }), {
+            status: status ?? errStatus,
+            headers: {
+                "Content-Type": "application/json; charset=utf-8",
+                ...normalizeHeaders(init?.headers),
+            },
+        });
+    }
+    const finalized = rootSchema.parse(rootUnknown);
+    const headers = new Headers(init?.headers);
+    headers.set("Content-Type", `${MEDIA_TYPE}; charset=utf-8`);
+    return new Response(JSON.stringify(finalized), {
+        ...init,
+        status: status ?? init?.status ?? 200,
+        headers,
+    });
+}
+function normalizeHeaders(h) {
+    if (h === undefined)
+        return {};
+    const out = {};
+    new Headers(h).forEach((value, key) => {
+        out[key] = value;
+    });
+    return out;
+}

package/dist/hubs.d.ts

@@ -0,0 +1,37 @@
+import { type Hex } from "viem";
+/**
+ * Default hub HTTP base URL (Hubble HTTP API on the public hub TLS port).
+ */
+export declare const DEFAULT_SNAP_HUB_HTTP_BASE_URL = "https://rho.farcaster.xyz:3381";
+type DecodedSignedKeyRequestMetadata = {
+    requestFid: bigint;
+    requestSigner: Hex;
+    signature: Uint8Array;
+    deadline: bigint;
+};
+type ActiveEd25519Signer = {
+    publicKey: Uint8Array;
+    /**
+     * From the latest ADD event for this key. `null` when metadata is empty or not decodable
+     * as `SignedKeyRequestMetadata`.
+     */
+    signedKeyRequestMetadata: DecodedSignedKeyRequestMetadata | null;
+};
+type FetchSignerKeysResult = {
+    ok: true;
+    signers: ActiveEd25519Signer[];
+} | {
+    ok: false;
+    message: string;
+};
+type FetchSignerKeysFromHubHttpOptions = {
+    /** Override global `fetch` (tests or non-Request environments). */
+    fetchFn?: typeof fetch;
+    signal?: AbortSignal;
+};
+/**
+ * Loads on-chain signer events via Hubble HTTP API (`GET /v1/onChainSignersByFid`)
+ * and returns active Ed25519 delegate keys from signer events.
+ */
+export declare function getActiveEd25519SignerKeysFromHubHttp(httpBaseUrl: string, fid: number, options?: FetchSignerKeysFromHubHttpOptions): Promise<FetchSignerKeysResult>;
+export {};