@farcaster/snap 1.4.0 → 1.5.0

package/dist/colors.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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_ACCENT: "accent";
+export declare const DEFAULT_THEME_ACCENT: "purple";
+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 BAR_CHART_COLOR_VALUES: readonly ["accent", "gray", "blue", "red", "amber", "green", "teal", "purple", "pink"];

package/dist/colors.js

@@ -0,0 +1,64 @@
+/**
+ * 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_ACCENT = "accent";
+export const DEFAULT_THEME_ACCENT = PALETTE_COLOR.purple;
+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 = [
+    PALETTE_COLOR_ACCENT,
+    ...PALETTE_COLOR_VALUES,
+];
+export const BAR_CHART_COLOR_VALUES = [
+    PALETTE_COLOR_ACCENT,
+    ...PALETTE_COLOR_VALUES,
+];

package/dist/constants.d.ts

@@ -38,35 +38,6 @@ export declare const SPACER_SIZE: {
     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"];
@@ -91,7 +62,6 @@ export declare const BUTTON_STYLE: {
 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). */
@@ -118,8 +88,6 @@ 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;

package/dist/constants.js

@@ -53,64 +53,6 @@ export const SPACER_SIZE_VALUES = [
     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"];
@@ -147,10 +89,6 @@ export const BUTTON_STYLE_VALUES = [
 ];
 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). */
@@ -176,8 +114,6 @@ 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,

package/dist/index.d.ts

@@ -1,3 +1,4 @@
-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 { snapResponseSchema, firstPageResponseSchema, payloadSchema, type SnapAction, type SnapContext, type SnapResponse, type SnapHandlerResult, type SnapFunction, type SnapPayload, } from "./schemas.js";
+export { POST_GRID_TAP_KEY, PAGE_ROOT_TYPE, ELEMENT_TYPE, MEDIA_TYPE, DEFAULT_LIST_STYLE, DEFAULT_SLIDER_STEP, } from "./constants.js";
+export { DEFAULT_THEME_ACCENT, PALETTE_COLOR, PALETTE_COLOR_ACCENT, PALETTE_COLOR_VALUES, PALETTE_LIGHT_HEX, PALETTE_DARK_HEX, type PaletteColor, } from "./colors.js";
+export { ACTION_TYPE_GET, ACTION_TYPE_POST, snapResponseSchema, firstPageResponseSchema, payloadSchema, createDefaultDataStore, type Button, type Element, type Elements, type GroupChildElement, type SnapAction, type SnapPageElementInput, type SnapContext, type SnapResponse, type SnapHandlerResult, type SnapFunction, type SnapPayload, type DataStoreValue, type SnapDataStore, type SnapDataStoreOperations, } from "./schemas.js";
 export { validateSnapResponse, validateFirstPageResponse, type ValidationResult, } from "./validator.js";

package/dist/index.js

@@ -1,3 +1,4 @@
-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 { snapResponseSchema, firstPageResponseSchema, payloadSchema, } from "./schemas.js";
+export { POST_GRID_TAP_KEY, PAGE_ROOT_TYPE, ELEMENT_TYPE, MEDIA_TYPE, DEFAULT_LIST_STYLE, DEFAULT_SLIDER_STEP, } from "./constants.js";
+export { DEFAULT_THEME_ACCENT, PALETTE_COLOR, PALETTE_COLOR_ACCENT, PALETTE_COLOR_VALUES, PALETTE_LIGHT_HEX, PALETTE_DARK_HEX, } from "./colors.js";
+export { ACTION_TYPE_GET, ACTION_TYPE_POST, snapResponseSchema, firstPageResponseSchema, payloadSchema, createDefaultDataStore, } from "./schemas.js";
 export { validateSnapResponse, validateFirstPageResponse, } from "./validator.js";

package/dist/schemas.d.ts

@@ -14,6 +14,146 @@ declare const buttonSchema: z.ZodObject<{
     }>>;
 }, z.core.$strip>;
 export type Button = z.infer<typeof buttonSchema>;
+/** Child elements allowed inside `group` (no media, no nested group) */
+declare const groupChildElementSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"text">;
+    style: z.ZodEnum<{
+        title: "title";
+        body: "body";
+        caption: "caption";
+        label: "label";
+    }>;
+    content: z.ZodString;
+    align: z.ZodOptional<z.ZodEnum<{
+        left: "left";
+        center: "center";
+        right: "right";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"divider">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"spacer">;
+    size: z.ZodDefault<z.ZodEnum<{
+        small: "small";
+        medium: "medium";
+        large: "large";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"progress">;
+    value: z.ZodNumber;
+    max: z.ZodNumber;
+    label: z.ZodOptional<z.ZodString>;
+    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>, z.ZodObject<{
+    type: z.ZodLiteral<"list">;
+    style: z.ZodDefault<z.ZodEnum<{
+        ordered: "ordered";
+        unordered: "unordered";
+        plain: "plain";
+    }>>;
+    items: z.ZodArray<z.ZodObject<{
+        content: z.ZodString;
+        trailing: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"text_input">;
+    name: z.ZodString;
+    placeholder: z.ZodOptional<z.ZodString>;
+    maxLength: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodPipe<z.ZodObject<{
+    type: z.ZodLiteral<"slider">;
+    name: z.ZodString;
+    min: z.ZodNumber;
+    max: z.ZodNumber;
+    step: z.ZodDefault<z.ZodNumber>;
+    value: z.ZodOptional<z.ZodNumber>;
+    label: z.ZodOptional<z.ZodString>;
+    minLabel: z.ZodOptional<z.ZodString>;
+    maxLabel: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodTransform<{
+    value: number;
+    type: "slider";
+    name: string;
+    min: number;
+    max: number;
+    step: number;
+    label?: string | undefined;
+    minLabel?: string | undefined;
+    maxLabel?: string | undefined;
+}, {
+    type: "slider";
+    name: string;
+    min: number;
+    max: number;
+    step: number;
+    value?: number | undefined;
+    label?: string | undefined;
+    minLabel?: string | undefined;
+    maxLabel?: string | undefined;
+}>>, z.ZodPipe<z.ZodObject<{
+    type: z.ZodLiteral<"button_group">;
+    name: z.ZodString;
+    options: z.ZodArray<z.ZodString>;
+    style: z.ZodOptional<z.ZodEnum<{
+        row: "row";
+        stack: "stack";
+        grid: "grid";
+    }>>;
+}, z.core.$strip>, z.ZodTransform<{
+    style: "row" | "stack" | "grid";
+    type: "button_group";
+    name: string;
+    options: string[];
+}, {
+    type: "button_group";
+    name: string;
+    options: string[];
+    style?: "row" | "stack" | "grid" | undefined;
+}>>, z.ZodObject<{
+    type: z.ZodLiteral<"toggle">;
+    name: z.ZodString;
+    label: z.ZodString;
+    value: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"bar_chart">;
+    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>], "type">;
+export type GroupChildElement = z.infer<typeof groupChildElementSchema>;
 /** Any single page element, including media and `group` */
 declare const elementSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"text">;
@@ -328,6 +468,7 @@ declare const elementSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }>>;
 }, z.core.$strip>], "type">;
 export type Element = z.infer<typeof elementSchema>;
+export type SnapPageElementInput = z.input<typeof elementSchema>;
 declare const elementsSchema: z.ZodObject<{
     type: z.ZodLiteral<"stack">;
     children: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -1395,9 +1536,21 @@ export declare const snapActionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"post">;
 }, z.core.$strict>], "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 declare function createDefaultDataStore(): SnapDataStore;
 export type SnapContext = {
     action: SnapAction;
     request: Request;
+    data: SnapDataStore;
 };
 export type SnapFunction = (ctx: SnapContext) => Promise<SnapHandlerResult>;
 export {};

package/dist/schemas.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
-import { BAR_CHART_COLOR_VALUES, BUTTON_ACTION, BUTTON_ACTION_VALUES, BUTTON_GROUP_STYLE, BUTTON_GROUP_STYLE_VALUES, BUTTON_LAYOUT_VALUES, BUTTON_STYLE_VALUES, DEFAULT_BUTTON_LAYOUT, DEFAULT_LIST_STYLE, DEFAULT_SLIDER_STEP, DEFAULT_THEME_ACCENT, EFFECT_VALUES, ELEMENT_TYPE, GRID_CELL_SIZE_VALUES, GRID_GAP_VALUES, GROUP_LAYOUT_VALUES, HEX_COLOR_6_RE, HTTP_PREFIX, HTTPS_PREFIX, IMAGE_ASPECT_VALUES, INTERACTIVE_ELEMENT_TYPES, LIMITS, LIST_STYLE_VALUES, MEDIA_ELEMENT_TYPES, PAGE_ROOT_TYPE, PALETTE_COLOR_VALUES, PROGRESS_COLOR_VALUES, SLIDER_STEP_ALIGN_EPS, SPACER_SIZE, SPACER_SIZE_VALUES, SPEC_VERSION, TEXT_ALIGN_VALUES, TEXT_CONTENT_MAX, TEXT_STYLE, TEXT_STYLE_VALUES, } from "./constants.js";
+import { BUTTON_ACTION, BUTTON_ACTION_VALUES, BUTTON_GROUP_STYLE, BUTTON_GROUP_STYLE_VALUES, BUTTON_LAYOUT_VALUES, BUTTON_STYLE_VALUES, DEFAULT_BUTTON_LAYOUT, DEFAULT_LIST_STYLE, DEFAULT_SLIDER_STEP, EFFECT_VALUES, ELEMENT_TYPE, GRID_CELL_SIZE_VALUES, GRID_GAP_VALUES, GROUP_LAYOUT_VALUES, HEX_COLOR_6_RE, HTTP_PREFIX, HTTPS_PREFIX, IMAGE_ASPECT_VALUES, INTERACTIVE_ELEMENT_TYPES, LIMITS, LIST_STYLE_VALUES, MEDIA_ELEMENT_TYPES, PAGE_ROOT_TYPE, SLIDER_STEP_ALIGN_EPS, SPACER_SIZE, SPACER_SIZE_VALUES, SPEC_VERSION, TEXT_ALIGN_VALUES, TEXT_CONTENT_MAX, TEXT_STYLE, TEXT_STYLE_VALUES, } from "./constants.js";
+import { BAR_CHART_COLOR_VALUES, DEFAULT_THEME_ACCENT, PALETTE_COLOR_VALUES, PROGRESS_COLOR_VALUES, } from "./colors.js";
 /**
  * post/link/mini_app targets must be HTTPS in production; allow HTTP only for
  * loopback hosts so local snap servers (e.g. http://localhost:3014/snap) validate.
@@ -457,3 +458,17 @@ export const snapActionSchema = z.discriminatedUnion("type", [
     snapGetActionSchema,
     snapPostActionSchema,
 ]);
+export function createDefaultDataStore() {
+    const err = new Error("Data store is not configured. Use withUpstash() from @farcaster/snap-upstash or provide a data store implementation.");
+    return {
+        get(_key) {
+            return Promise.reject(err);
+        },
+        set(_key, _value) {
+            return Promise.reject(err);
+        },
+        withLock(_fn) {
+            return Promise.reject(err);
+        },
+    };
+}

package/dist/ui/bar-chart.js

@@ -1,5 +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
         .array(z.object({

package/dist/ui/progress.js

@@ -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(),
     max: z.number(),

package/package.json

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

package/src/colors.ts

@@ -0,0 +1,73 @@
+/**
+ * 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 DEFAULT_THEME_ACCENT = PALETTE_COLOR.purple;
+
+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 BAR_CHART_COLOR_VALUES = [
+  PALETTE_COLOR_ACCENT,
+  ...PALETTE_COLOR_VALUES,
+] as const;

package/src/constants.ts

@@ -62,71 +62,6 @@ 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_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 = [
-  "accent",
-  ...PALETTE_COLOR_VALUES,
-] as const;
-
 export const LIST_STYLE_VALUES = ["ordered", "unordered", "plain"] as const;
 
 export const DEFAULT_LIST_STYLE = "ordered" as const;
@@ -173,11 +108,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 = [
-  "accent",
-  ...PALETTE_COLOR_VALUES,
-] as const;
-
 export const EFFECT_VALUES = ["confetti"] as const;
 
 export const GROUP_LAYOUT_VALUES = ["row"] as const;
@@ -211,9 +141,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,25 +3,39 @@ export {
   PAGE_ROOT_TYPE,
   ELEMENT_TYPE,
   MEDIA_TYPE,
-  DEFAULT_THEME_ACCENT,
   DEFAULT_LIST_STYLE,
   DEFAULT_SLIDER_STEP,
+} 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,
+  createDefaultDataStore,
+  type Button,
+  type Element,
+  type Elements,
+  type GroupChildElement,
   type SnapAction,
+  type SnapPageElementInput,
   type SnapContext,
   type SnapResponse,
   type SnapHandlerResult,
   type SnapFunction,
   type SnapPayload,
+  type DataStoreValue,
+  type SnapDataStore,
+  type SnapDataStoreOperations,
 } from "./schemas";
 export {
   validateSnapResponse,

package/src/schemas.ts

@@ -1,6 +1,5 @@
 import { z } from "zod";
 import {
-  BAR_CHART_COLOR_VALUES,
   BUTTON_ACTION,
   BUTTON_ACTION_VALUES,
   BUTTON_GROUP_STYLE,
@@ -10,7 +9,6 @@ import {
   DEFAULT_BUTTON_LAYOUT,
   DEFAULT_LIST_STYLE,
   DEFAULT_SLIDER_STEP,
-  DEFAULT_THEME_ACCENT,
   EFFECT_VALUES,
   ELEMENT_TYPE,
   GRID_CELL_SIZE_VALUES,
@@ -25,8 +23,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 +32,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
@@ -407,6 +409,8 @@ const groupChildElementSchema = z.discriminatedUnion("type", [
   barChartElementSchema,
 ]);
 
+export type GroupChildElement = z.infer<typeof groupChildElementSchema>;
+
 const groupElementSchema = z.object({
   type: z.literal(ELEMENT_TYPE.group),
   layout: z.enum(GROUP_LAYOUT_VALUES),
@@ -435,6 +439,8 @@ const elementSchema = z.discriminatedUnion("type", [
 
 export type Element = z.infer<typeof elementSchema>;
 
+export type SnapPageElementInput = z.input<typeof elementSchema>;
+
 const elementsSchema = z
   .object({
     type: z.literal(PAGE_ROOT_TYPE.stack),
@@ -574,9 +580,44 @@ 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/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/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(),