@farcaster/miniapp-core 0.0.0-canary-20250630212339

package/src/schemas/embeds.ts

@@ -0,0 +1,58 @@
+import { z } from 'zod/v4'
+import {
+  aspectRatioSchema,
+  buttonTitleSchema,
+  caip19TokenSchema,
+  hexColorSchema,
+  miniAppNameSchema,
+  secureUrlSchema,
+} from './shared.ts'
+
+export const actionLaunchFrameSchema = z.object({
+  type: z.literal('launch_frame'),
+  name: miniAppNameSchema,
+  url: secureUrlSchema.optional(),
+  splashImageUrl: secureUrlSchema.optional(),
+  splashBackgroundColor: hexColorSchema.optional(),
+})
+
+export const actionLaunchMiniAppSchema = z.object({
+  type: z.literal('launch_miniapp'),
+  name: miniAppNameSchema,
+  url: secureUrlSchema.optional(),
+  splashImageUrl: secureUrlSchema.optional(),
+  splashBackgroundColor: hexColorSchema.optional(),
+})
+
+export const actionViewTokenSchema = z.object({
+  type: z.literal('view_token'),
+  token: caip19TokenSchema,
+})
+
+export const actionSchema = z.discriminatedUnion('type', [
+  actionLaunchMiniAppSchema,
+  actionViewTokenSchema,
+  // Remove after compatibility period
+  actionLaunchFrameSchema,
+])
+
+export const buttonSchema = z.object({
+  title: buttonTitleSchema,
+  action: actionSchema,
+})
+
+export const miniAppEmbedNextSchema = z.object({
+  version: z.literal('next'),
+  imageUrl: secureUrlSchema,
+  aspectRatio: aspectRatioSchema.optional(),
+  button: buttonSchema,
+})
+
+export const safeParseMiniAppEmbed = (rawResponse: unknown) =>
+  miniAppEmbedNextSchema.safeParse(rawResponse)
+
+// Backward compatibility - also parse fc:frame meta tags
+export const safeParseFrameEmbed = safeParseMiniAppEmbed
+
+export type MiniAppEmbedNext = z.infer<typeof miniAppEmbedNextSchema>
+export type FrameEmbedNext = MiniAppEmbedNext

package/src/schemas/events.ts

@@ -0,0 +1,57 @@
+import { z } from 'zod/v4'
+import { notificationDetailsSchema } from './notifications.ts'
+
+export const eventMiniAppAddedSchema = z.object({
+  event: z.literal('miniapp_added'),
+  notificationDetails: notificationDetailsSchema.optional(),
+})
+
+export type EventMiniAppAdded = z.infer<typeof eventMiniAppAddedSchema>
+
+export const eventFrameAddedSchema = z.object({
+  event: z.literal('frame_added'),
+  notificationDetails: notificationDetailsSchema.optional(),
+})
+
+export type EventFrameAdded = z.infer<typeof eventFrameAddedSchema>
+
+export const eventMiniAppRemovedSchema = z.object({
+  event: z.literal('miniapp_removed'),
+})
+
+export type EventMiniAppRemoved = z.infer<typeof eventMiniAppRemovedSchema>
+
+export const eventFrameRemovedSchema = z.object({
+  event: z.literal('frame_removed'),
+})
+
+export type EventFrameRemoved = z.infer<typeof eventFrameRemovedSchema>
+
+export const eventNotificationsEnabledSchema = z.object({
+  event: z.literal('notifications_enabled'),
+  notificationDetails: notificationDetailsSchema.required(),
+})
+
+export type EventNotificationsEnabled = z.infer<
+  typeof eventNotificationsEnabledSchema
+>
+
+export const notificationsDisabledSchema = z.object({
+  event: z.literal('notifications_disabled'),
+})
+
+export type EventNotificationsDisabled = z.infer<
+  typeof notificationsDisabledSchema
+>
+
+export const serverEventSchema = z.discriminatedUnion('event', [
+  eventMiniAppAddedSchema,
+  eventMiniAppRemovedSchema,
+  eventNotificationsEnabledSchema,
+  notificationsDisabledSchema,
+  // Remove after compatibility period
+  eventFrameAddedSchema,
+  eventFrameRemovedSchema,
+])
+
+export type MiniAppServerEvent = z.infer<typeof serverEventSchema>

package/src/schemas/index.ts

@@ -0,0 +1,5 @@
+export * from './embeds.ts'
+export * from './events.ts'
+export * from './shared.ts'
+export * from './manifest.ts'
+export * from './notifications.ts'

package/src/schemas/manifest.ts

@@ -0,0 +1,142 @@
+import { z } from 'zod/v4'
+import { miniAppHostCapabilityList } from '../types.ts'
+import {
+  buttonTitleSchema,
+  createSimpleStringSchema,
+  domainSchema,
+  encodedJsonFarcasterSignatureSchema,
+  hexColorSchema,
+  miniAppNameSchema,
+  secureUrlSchema,
+} from './shared.ts'
+
+const primaryCategorySchema = z.enum([
+  'games',
+  'social',
+  'finance',
+  'utility',
+  'productivity',
+  'health-fitness',
+  'news-media',
+  'music',
+  'shopping',
+  'education',
+  'developer-tools',
+  'entertainment',
+  'art-creativity',
+])
+
+const chainList = [
+  'eip155:1', // Ethereum mainnet
+  'eip155:8453', // Base mainnet
+  'eip155:42161', // Arbitrum One
+  'eip155:421614', // Arbitrum Sepolia
+  'eip155:84532', // Base Sepolia
+  'eip155:666666666', // Degen
+  'eip155:100', // Gnosis
+  'eip155:10', // Optimism
+  'eip155:11155420', // Optimism Sepolia
+  'eip155:137', // Polygon
+  'eip155:11155111', // Ethereum Sepolia
+  'eip155:7777777', // Zora
+  'eip155:130', // Unichain
+  'eip155:10143', // Monad testnet
+  'eip155:42220', // Celo
+  'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp', // Solana
+] as const
+
+function removeArrayDuplicates<T>(arr: T[]) {
+  const set = new Set(arr)
+  return Array.from(set)
+}
+
+export const domainMiniAppConfigSchema = z
+  .object({
+    // 0.0.0 and 0.0.1 are not technically part of the spec but kept for
+    // backwards compatibility. next should always resolve to the most recent
+    // schema version.
+    version: z.union([
+      z.literal('0.0.0'),
+      z.literal('0.0.1'),
+      z.literal('1'),
+      z.literal('next'),
+    ]),
+    name: miniAppNameSchema,
+    iconUrl: secureUrlSchema,
+    homeUrl: secureUrlSchema,
+    /** deprecated, set ogImageUrl instead */
+    imageUrl: secureUrlSchema.optional(),
+    /** deprecated, will rely on fc:frame/fc:miniapp meta tag */
+    buttonTitle: buttonTitleSchema.optional(),
+    splashImageUrl: secureUrlSchema.optional(),
+    splashBackgroundColor: hexColorSchema.optional(),
+    webhookUrl: secureUrlSchema.optional(),
+    /** see: https://github.com/farcasterxyz/miniapps/discussions/191 */
+    subtitle: createSimpleStringSchema({ max: 30 }).optional(),
+    description: createSimpleStringSchema({ max: 170 }).optional(),
+    screenshotUrls: z.array(secureUrlSchema).max(3).optional(),
+    primaryCategory: primaryCategorySchema.optional(),
+    tags: z
+      .array(createSimpleStringSchema({ max: 20, noSpaces: true }))
+      .max(5)
+      .optional(),
+    heroImageUrl: secureUrlSchema.optional(),
+    tagline: createSimpleStringSchema({ max: 30 }).optional(),
+    ogTitle: createSimpleStringSchema({ max: 30 }).optional(),
+    ogDescription: createSimpleStringSchema({ max: 100 }).optional(),
+    ogImageUrl: secureUrlSchema.optional(),
+    /** see: https://github.com/farcasterxyz/miniapps/discussions/204 */
+    noindex: z.boolean().optional(),
+    /** see https://github.com/farcasterxyz/miniapps/discussions/256 */
+    requiredChains: z
+      .array(z.enum(chainList))
+      .transform(removeArrayDuplicates)
+      .optional(),
+    requiredCapabilities: z
+      .array(z.enum(miniAppHostCapabilityList))
+      .transform(removeArrayDuplicates)
+      .optional(),
+    /** see https://github.com/farcasterxyz/miniapps/discussions/158 */
+    /** Documentation will be added once this feature is finalized. */
+    castShareUrl: secureUrlSchema.optional(),
+    /** Canonical domain for the miniapp application */
+    canonicalDomain: domainSchema.optional(),
+  })
+  .refine(
+    (data) => {
+      if (data.castShareUrl === undefined) return true
+      try {
+        const homeUrlDomain = new URL(data.homeUrl).hostname
+        const castShareUrlDomain = new URL(data.castShareUrl).hostname
+        return homeUrlDomain === castShareUrlDomain
+      } catch {
+        return false
+      }
+    },
+    {
+      message: 'castShareUrl must have the same domain as homeUrl',
+      path: ['castShareUrl'],
+    },
+  )
+
+export const domainManifestSchema = z
+  .object({
+    accountAssociation: encodedJsonFarcasterSignatureSchema,
+    miniapp: domainMiniAppConfigSchema.optional(),
+    // Support both 'frame' and 'miniapp' during transition period
+    frame: domainMiniAppConfigSchema.optional(),
+  })
+  .refine(
+    (data) => {
+      // If both are provided, they must be identical
+      if (data.frame && data.miniapp) {
+        return JSON.stringify(data.frame) === JSON.stringify(data.miniapp)
+      }
+      return true
+    },
+    {
+      message:
+        'If both "frame" and "miniapp" are provided, they must be identical',
+      path: ['frame', 'miniapp'],
+    },
+  )

package/src/schemas/notifications.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod/v4'
+import { secureUrlSchema } from './shared.ts'
+
+export const notificationDetailsSchema = z.object({
+  url: z.string(),
+  token: z.string(),
+})
+
+export type MiniAppNotificationDetails = z.infer<
+  typeof notificationDetailsSchema
+>
+
+export const sendNotificationRequestSchema = z.object({
+  notificationId: z.string().max(128),
+  title: z.string().max(32),
+  body: z.string().max(128),
+  targetUrl: secureUrlSchema,
+  tokens: z.string().array().max(100),
+})
+
+export type SendNotificationRequest = z.infer<
+  typeof sendNotificationRequestSchema
+>
+
+export const sendNotificationResponseSchema = z.object({
+  result: z.object({
+    successfulTokens: z.array(z.string()),
+    invalidTokens: z.array(z.string()),
+    rateLimitedTokens: z.array(z.string()),
+  }),
+})
+
+export type SendNotificationResponse = z.infer<
+  typeof sendNotificationResponseSchema
+>

package/src/schemas/shared.ts

@@ -0,0 +1,138 @@
+import { z } from 'zod/v4'
+
+const SPECIAL_CHARS_PATTERN = /[@#$%^&*+=\/\\|~«»]/
+const REPEATED_PUNCTUATION_PATTERN = /(!{2,}|\?{2,}|-{2,})/
+
+// Unicode ranges for emoji detection:
+// \u{1F300}-\u{1F9FF} - Miscellaneous Symbols, Pictographs, Emoticons, Transport, Map, and Supplemental
+// \u{2702}-\u{27B0} - Dingbats
+// \u{2600}-\u{26FF} - Miscellaneous Symbols
+// \u{2B00}-\u{2BFF} - Miscellaneous Symbols and Arrows
+const EMOJI_PATTERN =
+  /[\u{1F300}-\u{1F9FF}]|[\u{2702}-\u{27B0}]|[\u{2600}-\u{26FF}]|[\u{2B00}-\u{2BFF}]/u
+
+export const createSimpleStringSchema = ({
+  max,
+  noSpaces,
+}: { max?: number; noSpaces?: boolean } = {}) => {
+  const stringValidations = noSpaces
+    ? z
+        .string()
+        .max(max ?? Number.POSITIVE_INFINITY)
+        .regex(/^\S*$/, 'Spaces are not allowed')
+    : z.string().max(max ?? Number.POSITIVE_INFINITY)
+
+  return stringValidations
+    .refine((value) => !EMOJI_PATTERN.test(value), {
+      message: 'Emojis and symbols are not allowed',
+    })
+    .refine((value) => !SPECIAL_CHARS_PATTERN.test(value), {
+      message:
+        'Special characters (@, #, $, %, ^, &, *, +, =, /, \\, |, ~, «, ») are not allowed',
+    })
+    .refine((value) => !REPEATED_PUNCTUATION_PATTERN.test(value), {
+      message: 'Repeated punctuations (!!, ??, --) are not allowed',
+    })
+}
+
+export const secureUrlSchema = z
+  .string()
+  .url()
+  .startsWith('https://', { message: 'Must be an https url' })
+  .max(1024)
+  .refine((url) => !url.includes(' '), {
+    message: 'URL must not contain spaces',
+  })
+  .refine(
+    (url) => {
+      try {
+        const hostname = new URL(url).hostname
+        // Check for localhost
+        if (hostname === 'localhost' || hostname.endsWith('.localhost')) {
+          return false
+        }
+        // Check for IPv4 addresses
+        const ipv4Regex = /^(\d{1,3}\.){3}\d{1,3}$/
+        if (ipv4Regex.test(hostname)) {
+          return false
+        }
+        // Check for IPv6 addresses (including brackets)
+        if (hostname.startsWith('[') && hostname.endsWith(']')) {
+          return false
+        }
+        return true
+      } catch {
+        return false
+      }
+    },
+    {
+      message: 'URL must not use IP addresses or localhost',
+    },
+  )
+
+export const miniAppNameSchema = z.string().max(32)
+export const buttonTitleSchema = z.string().max(32)
+
+const CAIP_19_REGEX =
+  /^[-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32}\/(?:[-a-z0-9]{3,8}:[-.%a-zA-Z0-9]{1,128}(?:\/[-.%a-zA-Z0-9]{1,78})?|native)$/
+
+export const caip19TokenSchema = z
+  .string()
+  .regex(CAIP_19_REGEX, { message: 'Invalid CAIP-19 asset ID' })
+
+export const hexColorSchema = z
+  .string()
+  .regex(/^#([0-9A-F]{3}|[0-9A-F]{6})$/i, {
+    message:
+      'Invalid hex color code. It should be in the format #RRGGBB or #RGB.',
+  })
+
+// Domain validation regex:
+// - Each label (part between dots) must start and end with alphanumeric
+// - Labels can contain hyphens in the middle
+// - Cannot have consecutive dots
+// - Must have at least one dot (TLD required)
+// - TLD must be at least 2 characters and only letters
+const DOMAIN_REGEX =
+  /^(?!.*\.\.)([a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z]{2,}$/
+
+export const domainSchema = z
+  .string()
+  .max(1024)
+  .regex(DOMAIN_REGEX, {
+    message: 'Must be a valid domain name (e.g., example.com, sub.example.com)',
+  })
+  .refine((value) => !value.includes('://'), {
+    message: 'Domain must not include protocol (http://, https://, etc.)',
+  })
+  .refine((value) => !value.includes('/'), {
+    message: 'Domain must not include path separators',
+  })
+  .refine((value) => !value.includes('@'), {
+    message: 'Domain must not include @ symbol',
+  })
+  .refine((value) => !value.includes(':'), {
+    message: 'Domain must not include port numbers',
+  })
+
+export const aspectRatioSchema = z.union([z.literal('1:1'), z.literal('3:2')])
+
+export const encodedJsonFarcasterSignatureSchema = z.object({
+  header: z.string(),
+  payload: z.string(),
+  signature: z.string(),
+})
+
+export type EncodedJsonFarcasterSignatureSchema = z.infer<
+  typeof encodedJsonFarcasterSignatureSchema
+>
+
+export const jsonFarcasterSignatureHeaderSchema = z.object({
+  fid: z.number(),
+  type: z.literal('app_key'),
+  key: z.string().startsWith('0x'),
+})
+
+export type JsonFarcasterSignatureHeaderSchema = z.infer<
+  typeof jsonFarcasterSignatureHeaderSchema
+>

package/src/solana.ts

@@ -0,0 +1,108 @@
+import {
+  Connection as SolanaConnection,
+  type SendOptions as SolanaSendOptions,
+  type Transaction as SolanaTransaction,
+  type VersionedTransaction as SolanaVersionedTransaction,
+} from '@solana/web3.js'
+
+export { SolanaConnection }
+export type { SolanaSendOptions }
+
+export type SolanaCombinedTransaction =
+  | SolanaTransaction
+  | SolanaVersionedTransaction
+
+export type SolanaConnectRequestArguments = {
+  method: 'connect'
+}
+export type SolanaSignMessageRequestArguments = {
+  method: 'signMessage'
+  params: {
+    message: string
+  }
+}
+export type SolanaSignAndSendTransactionRequestArguments = {
+  method: 'signAndSendTransaction'
+  params: {
+    transaction: SolanaCombinedTransaction
+    options?: SolanaSendOptions
+  }
+}
+export type SolanaSignTransactionRequestArguments<
+  T extends SolanaCombinedTransaction = SolanaTransaction,
+> = {
+  method: 'signTransaction'
+  params: {
+    transaction: T
+  }
+}
+
+export type SolanaRequestFn = ((
+  request: SolanaConnectRequestArguments,
+) => Promise<{ publicKey: string }>) &
+  ((request: SolanaSignMessageRequestArguments) => Promise<{
+    signature: string
+  }>) &
+  ((request: SolanaSignAndSendTransactionRequestArguments) => Promise<{
+    signature: string
+  }>) &
+  (<T extends SolanaCombinedTransaction>(
+    request: SolanaSignTransactionRequestArguments<T>,
+  ) => Promise<{ signedTransaction: T }>)
+
+export interface SolanaWalletProvider {
+  request: SolanaRequestFn
+
+  signMessage(message: string): Promise<{ signature: string }>
+  signTransaction<T extends SolanaCombinedTransaction>(
+    transaction: T,
+  ): Promise<{ signedTransaction: T }>
+  signAndSendTransaction(input: {
+    transaction: SolanaCombinedTransaction
+  }): Promise<{ signature: string }>
+}
+
+export const createSolanaWalletProvider = (
+  request: SolanaRequestFn,
+): SolanaWalletProvider => ({
+  request,
+  signMessage: (msg: string) =>
+    request({ method: 'signMessage', params: { message: msg } }),
+  signTransaction: <T extends SolanaCombinedTransaction>(transaction: T) =>
+    request({ method: 'signTransaction', params: { transaction } }),
+  signAndSendTransaction: (input: {
+    transaction: SolanaCombinedTransaction
+  }) =>
+    request({
+      method: 'signAndSendTransaction',
+      params: input,
+    }),
+})
+
+export type SolanaWireSignAndSendTransactionRequestArguments = {
+  method: 'signAndSendTransaction'
+  params: {
+    transaction: string
+    options?: SolanaSendOptions
+  }
+}
+
+export type SolanaWireSignTransactionRequestArguments = {
+  method: 'signTransaction'
+  params: {
+    transaction: string
+  }
+}
+
+export type SolanaWireRequestFn = ((
+  request: SolanaConnectRequestArguments,
+) => Promise<{ publicKey: string }>) &
+  ((request: SolanaSignMessageRequestArguments) => Promise<{
+    signature: string
+  }>) &
+  ((request: SolanaWireSignAndSendTransactionRequestArguments) => Promise<{
+    signature: string
+  }>) &
+  ((
+    request: SolanaWireSignTransactionRequestArguments,
+  ) => Promise<{ signedTransaction: string }>)

package/src/solanaWire.ts

@@ -0,0 +1,120 @@
+import {
+  Transaction as SolanaTransaction,
+  VersionedMessage as SolanaVersionedMessage,
+  VersionedTransaction as SolanaVersionedTransaction,
+} from '@solana/web3.js'
+
+import type {
+  SolanaCombinedTransaction,
+  SolanaConnectRequestArguments,
+  SolanaRequestFn,
+  SolanaSignAndSendTransactionRequestArguments,
+  SolanaSignMessageRequestArguments,
+  SolanaSignTransactionRequestArguments,
+  SolanaWireRequestFn,
+  SolanaWireSignAndSendTransactionRequestArguments,
+  SolanaWireSignTransactionRequestArguments,
+} from './solana.ts'
+
+function serializeTransaction(transaction: SolanaCombinedTransaction): string {
+  return Buffer.from(
+    transaction.serialize({
+      verifySignatures: false,
+    }),
+  ).toString('base64')
+}
+
+function unserializeTransaction(
+  transaction: string,
+): SolanaCombinedTransaction {
+  const bytes = Buffer.from(transaction, 'base64')
+  const version = SolanaVersionedMessage.deserializeMessageVersion(bytes)
+  return version === 'legacy'
+    ? SolanaVersionedTransaction.deserialize(bytes)
+    : SolanaTransaction.from(bytes)
+}
+
+export function wrapSolanaProviderRequest(
+  requestFn: SolanaRequestFn,
+): SolanaWireRequestFn {
+  const wrappedFn = async (
+    request:
+      | SolanaConnectRequestArguments
+      | SolanaSignMessageRequestArguments
+      | SolanaWireSignAndSendTransactionRequestArguments
+      | SolanaWireSignTransactionRequestArguments,
+  ) => {
+    if (request.method === 'connect') {
+      return await requestFn(request)
+    }
+    if (request.method === 'signMessage') {
+      return await requestFn(request)
+    }
+    if (request.method === 'signAndSendTransaction') {
+      const { transaction, options } = request.params
+      const params = {
+        transaction: unserializeTransaction(transaction),
+        options,
+      }
+      return await requestFn({
+        method: 'signAndSendTransaction',
+        params,
+      })
+    }
+    if (request.method === 'signTransaction') {
+      const { transaction } = request.params
+      const params = {
+        transaction: unserializeTransaction(transaction),
+      }
+      const { signedTransaction } = await requestFn({
+        method: 'signTransaction',
+        params,
+      })
+      return {
+        signedTransaction: serializeTransaction(signedTransaction),
+      }
+    }
+  }
+  return wrappedFn as SolanaWireRequestFn
+}
+
+export function unwrapSolanaProviderRequest(
+  wrappedRequestFn: SolanaWireRequestFn,
+): SolanaRequestFn {
+  const unwrappedFn = async <T extends SolanaCombinedTransaction>(
+    request:
+      | SolanaConnectRequestArguments
+      | SolanaSignMessageRequestArguments
+      | SolanaSignAndSendTransactionRequestArguments
+      | SolanaSignTransactionRequestArguments<T>,
+  ) => {
+    if (request.method === 'connect') {
+      return await wrappedRequestFn(request)
+    }
+    if (request.method === 'signMessage') {
+      return await wrappedRequestFn(request)
+    }
+    if (request.method === 'signAndSendTransaction') {
+      const { transaction, options } = request.params
+      const params = {
+        transaction: serializeTransaction(transaction),
+      }
+      return await wrappedRequestFn({
+        method: 'signAndSendTransaction',
+        params,
+      })
+    }
+    if (request.method === 'signTransaction') {
+      const { transaction } = request.params
+      const params = {
+        transaction: serializeTransaction(transaction),
+      }
+      const { signedTransaction } = await wrappedRequestFn({
+        method: 'signTransaction',
+        params,
+      })
+      return { signedTransaction: unserializeTransaction(signedTransaction) }
+    }
+  }
+  return unwrappedFn as SolanaRequestFn
+}