@farcaster/snap-hono 0.0.0-canary-20260330145610

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+import type { Hono } from "hono";
+import { type SnapFunction } from "@farcaster/snap";
+export type SnapHandlerOptions = {
+    /**
+     * Route path to register GET and POST handlers on.
+     * @default "/"
+     */
+    path?: string;
+    /**
+     * When true, skip JFS signature verification only. POST bodies must still be JFS-shaped JSON.
+     * When omitted, default to {@link envSkipJFSVerification}.
+     */
+    skipJFSVerification?: boolean;
+    /**
+     * Text shown on GET requests from browsers / non-snap clients.
+     * @default "This is a Farcaster Snap server."
+     */
+    fallbackText?: string;
+};
+/**
+ * Register GET and POST snap handlers on `app` at `options.path` (default `/`).
+ *
+ * - GET  → calls `snapFn({ action: { type: "get" }, request })` and returns the response.
+ * - POST → parses the JFS-shaped JSON body; verifies it via {@link verifyJFSRequestBody} unless
+ *          `skipJFSVerification` is true, then calls `snapFn({ action, request })` and returns the response.
+ *
+ * All parsing, schema validation, signature verification, and error responses
+ * are handled automatically. `SnapContext.request` is the raw `Request` so handlers
+ * can read query params, headers, or the URL when needed.
+ */
+export declare function registerSnapHandler(app: Hono, snapFn: SnapFunction, options?: SnapHandlerOptions): void;

package/dist/index.js

@@ -0,0 +1,75 @@
+import { cors } from "hono/cors";
+import { parseRequest, sendResponse, MEDIA_TYPE, } from "@farcaster/snap";
+/**
+ * Register GET and POST snap handlers on `app` at `options.path` (default `/`).
+ *
+ * - GET  → calls `snapFn({ action: { type: "get" }, request })` and returns the response.
+ * - POST → parses the JFS-shaped JSON body; verifies it via {@link verifyJFSRequestBody} unless
+ *          `skipJFSVerification` is true, then calls `snapFn({ action, request })` and returns the response.
+ *
+ * All parsing, schema validation, signature verification, and error responses
+ * are handled automatically. `SnapContext.request` is the raw `Request` so handlers
+ * can read query params, headers, or the URL when needed.
+ */
+export function registerSnapHandler(app, snapFn, options = {}) {
+    const path = options.path ?? "/";
+    const fallbackText = options.fallbackText ??
+        "This is a Farcaster Snap server. See https://snap.farcaster.xyz for more info.";
+    app.use(path, cors({ origin: "*" }));
+    app.get(path, async (c) => {
+        const accept = c.req.header("Accept");
+        if (!clientWantsSnapResponse(accept)) {
+            return c.text(fallbackText, 200);
+        }
+        const response = await snapFn({
+            action: { type: "get" },
+            request: c.req.raw,
+        });
+        return sendResponse(response);
+    });
+    app.post(path, async (c) => {
+        const raw = c.req.raw;
+        const skipJFSVerification = options.skipJFSVerification !== undefined
+            ? options.skipJFSVerification
+            : envSkipJFSVerification();
+        const parsed = await parseRequest(raw, { skipJFSVerification });
+        if (!parsed.success) {
+            const err = parsed.error;
+            switch (err.type) {
+                case "method_not_allowed":
+                    return c.json({ error: err.message }, 405);
+                case "invalid_json":
+                    return c.json({ error: err.message }, 400);
+                case "validation":
+                    return c.json({ error: "invalid POST body", issues: err.issues }, 400);
+                case "replay":
+                    return c.json({ error: err.message }, 400);
+                case "signature":
+                    return c.json({ error: err.message }, 401);
+                default: {
+                    const _exhaustive = err;
+                    throw new Error(`unexpected parse error: ${String(_exhaustive)}`);
+                }
+            }
+        }
+        const response = await snapFn({ action: parsed.action, request: raw });
+        return sendResponse(response);
+    });
+}
+function clientWantsSnapResponse(accept) {
+    if (!accept || accept.trim() === "")
+        return false;
+    const want = MEDIA_TYPE.toLowerCase();
+    for (const part of accept.split(",")) {
+        const media = part.trim().split(";")[0]?.trim().toLowerCase();
+        if (media === want)
+            return true;
+    }
+    return false;
+}
+function envSkipJFSVerification() {
+    const v = process.env.SKIP_JFS_VERIFICATION?.trim().toLowerCase();
+    if (v === "1" || v === "true" || v === "yes")
+        return true;
+    return false;
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@farcaster/snap-hono",
+  "version": "0.0.0-canary-20260330145610",
+  "description": "Hono integration for Farcaster Snap servers",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/farcasterxyz/snap.git",
+    "directory": "pkgs/hono"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@farcaster/snap": "0.0.0-canary-20260330145610"
+  },
+  "peerDependencies": {
+    "@farcaster/snap": "0.0.0-canary-20260330145610",
+    "hono": ">=4.0.0"
+  },
+  "devDependencies": {
+    "@farcaster/jfs": "^0.2.2",
+    "@types/node": "^25.5.0",
+    "hono": "^4.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/index.ts

@@ -0,0 +1,119 @@
+import type { Hono } from "hono";
+import { cors } from "hono/cors";
+import {
+  parseRequest,
+  sendResponse,
+  MEDIA_TYPE,
+  type ParseRequestOptions,
+  type SnapFunction,
+} from "@farcaster/snap";
+
+export type SnapHandlerOptions = {
+  /**
+   * Route path to register GET and POST handlers on.
+   * @default "/"
+   */
+  path?: string;
+
+  /**
+   * When true, skip JFS signature verification only. POST bodies must still be JFS-shaped JSON.
+   * When omitted, default to {@link envSkipJFSVerification}.
+   */
+  skipJFSVerification?: boolean;
+
+  /**
+   * Text shown on GET requests from browsers / non-snap clients.
+   * @default "This is a Farcaster Snap server."
+   */
+  fallbackText?: string;
+};
+
+/**
+ * Register GET and POST snap handlers on `app` at `options.path` (default `/`).
+ *
+ * - GET  → calls `snapFn({ action: { type: "get" }, request })` and returns the response.
+ * - POST → parses the JFS-shaped JSON body; verifies it via {@link verifyJFSRequestBody} unless
+ *          `skipJFSVerification` is true, then calls `snapFn({ action, request })` and returns the response.
+ *
+ * All parsing, schema validation, signature verification, and error responses
+ * are handled automatically. `SnapContext.request` is the raw `Request` so handlers
+ * can read query params, headers, or the URL when needed.
+ */
+export function registerSnapHandler(
+  app: Hono,
+  snapFn: SnapFunction,
+  options: SnapHandlerOptions = {},
+): void {
+  const path = options.path ?? "/";
+  const fallbackText =
+    options.fallbackText ??
+    "This is a Farcaster Snap server. See https://snap.farcaster.xyz for more info.";
+
+  app.use(path, cors({ origin: "*" }));
+
+  app.get(path, async (c) => {
+    const accept = c.req.header("Accept");
+    if (!clientWantsSnapResponse(accept)) {
+      return c.text(fallbackText, 200);
+    }
+
+    const response = await snapFn({
+      action: { type: "get" },
+      request: c.req.raw,
+    });
+    return sendResponse(response);
+  });
+
+  app.post(path, async (c) => {
+    const raw = c.req.raw;
+    const skipJFSVerification =
+      options.skipJFSVerification !== undefined
+        ? options.skipJFSVerification
+        : envSkipJFSVerification();
+
+    const parsed = await parseRequest(raw, { skipJFSVerification });
+
+    if (!parsed.success) {
+      const err = parsed.error;
+      switch (err.type) {
+        case "method_not_allowed":
+          return c.json({ error: err.message }, 405);
+        case "invalid_json":
+          return c.json({ error: err.message }, 400);
+        case "validation":
+          return c.json(
+            { error: "invalid POST body", issues: err.issues },
+            400,
+          );
+        case "replay":
+          return c.json({ error: err.message }, 400);
+        case "signature":
+          return c.json({ error: err.message }, 401);
+        default: {
+          const _exhaustive: never = err;
+          throw new Error(`unexpected parse error: ${String(_exhaustive)}`);
+        }
+      }
+    }
+
+    const response = await snapFn({ action: parsed.action, request: raw });
+
+    return sendResponse(response);
+  });
+}
+
+function clientWantsSnapResponse(accept: string | undefined): boolean {
+  if (!accept || accept.trim() === "") return false;
+  const want = MEDIA_TYPE.toLowerCase();
+  for (const part of accept.split(",")) {
+    const media = part.trim().split(";")[0]?.trim().toLowerCase();
+    if (media === want) return true;
+  }
+  return false;
+}
+
+function envSkipJFSVerification(): boolean {
+  const v = process.env.SKIP_JFS_VERIFICATION?.trim().toLowerCase();
+  if (v === "1" || v === "true" || v === "yes") return true;
+  return false;
+}