@farcaster/frame-core 0.0.0-canary-20250630194123 → 0.0.0-canary-20250630212526

package/src/actions/index.ts

@@ -1,10 +0,0 @@
-export * as AddMiniApp from './AddMiniApp.ts'
-export * as ComposeCast from './ComposeCast.ts'
-export * as Haptics from './Haptics.ts'
-export * as Ready from './Ready.ts'
-export * as SignIn from './SignIn.ts'
-export * as SendToken from './SendToken.ts'
-export * as SwapToken from './SwapToken.ts'
-export * as ViewCast from './ViewCast.ts'
-export * as ViewProfile from './ViewProfile.ts'
-export * as ViewToken from './ViewToken.ts'

package/src/back.ts

@@ -1,15 +0,0 @@
-export type BackState = {
-  /**
-   * Is the back control visible. Note that on mobile devices Farcaster clients
-   * may support a gesture based control rather than button control.
-   *
-   * @default false
-   */
-  visible: boolean
-}
-
-export const DEFAULT_BACK_STATE = {
-  visible: false,
-} satisfies BackState
-
-export type UpdateBackState = (state: BackState) => Promise<void>

package/src/context.ts

@@ -1,117 +0,0 @@
-import type { FrameNotificationDetails } from './schemas/index.ts'
-
-export type MiniappUser = {
-  fid: number
-  username?: string
-  displayName?: string
-  pfpUrl?: string
-}
-
-export interface MiniappCast {
-  author: MiniappUser
-  hash: string
-  parentHash?: string
-  parentFid?: number
-  timestamp?: number
-  mentions?: MiniappUser[]
-  text: string
-  embeds?: string[]
-  channelKey?: string
-}
-
-export type CastEmbedLocationContext = {
-  type: 'cast_embed'
-  embed: string
-  cast: MiniappCast
-}
-
-export type CastShareLocationContext = {
-  type: 'cast_share'
-  cast: MiniappCast
-}
-
-export type NotificationLocationContext = {
-  type: 'notification'
-  notification: {
-    notificationId: string
-    title: string
-    body: string
-  }
-}
-
-export type LauncherLocationContext = {
-  type: 'launcher'
-}
-
-export type ChannelLocationContext = {
-  type: 'channel'
-  channel: {
-    /**
-     * Channel key identifier
-     */
-    key: string
-
-    /**
-     * Channel name
-     */
-    name: string
-
-    /**
-     * Channel profile image URL
-     */
-    imageUrl?: string
-  }
-}
-
-export type LocationContext =
-  | CastEmbedLocationContext
-  | CastShareLocationContext
-  | NotificationLocationContext
-  | LauncherLocationContext
-  | ChannelLocationContext
-
-export type AccountLocation = {
-  placeId: string
-
-  /**
-   * Human-readable string describing the location
-   */
-  description: string
-}
-
-export type UserContext = {
-  fid: number
-  username?: string
-  displayName?: string
-
-  /**
-   * Profile image URL
-   */
-  pfpUrl?: string
-  location?: AccountLocation
-}
-
-export type SafeAreaInsets = {
-  top: number
-  bottom: number
-  left: number
-  right: number
-}
-
-export type ClientContext = {
-  clientFid: number
-  added: boolean
-  notificationDetails?: FrameNotificationDetails
-  safeAreaInsets?: SafeAreaInsets
-}
-
-export type ClientFeatures = {
-  haptics: boolean
-}
-
-export type FrameContext = {
-  client: ClientContext
-  user: UserContext
-  location?: LocationContext
-  features?: ClientFeatures
-}

package/src/errors.ts

@@ -1,21 +0,0 @@
-export type GlobalErrorType<name extends string = 'Error'> = Error & {
-  name: name
-}
-
-export class BaseError<
-  cause extends Error | undefined = undefined,
-> extends Error {
-  override name = 'BaseError'
-  cause: cause
-
-  constructor(message: string, options: BaseError.Options<cause> = {}) {
-    super(message, options.cause ? { cause: options.cause } : undefined)
-    this.cause = options.cause as any
-  }
-}
-
-export declare namespace BaseError {
-  type Options<cause extends Error | undefined = Error | undefined> = {
-    cause?: cause | undefined
-  }
-}

package/src/internal/types.ts

@@ -1,20 +0,0 @@
-type Compute<type> = { [key in keyof type]: type[key] } & unknown
-
-type KeyofUnion<type> = type extends type ? keyof type : never
-
-export type OneOf<
-  union extends object,
-  fallback extends object | undefined = undefined,
-  ///
-  keys extends KeyofUnion<union> = KeyofUnion<union>,
-> = union extends infer item
-  ? Compute<
-      item & {
-        [key in Exclude<keys, keyof item>]?: fallback extends object
-          ? key extends keyof fallback
-            ? fallback[key]
-            : undefined
-          : undefined
-      }
-    >
-  : never

package/src/manifest.ts

@@ -1,120 +0,0 @@
-/**
- * Farcaster manifest for a domain hosted at `/.well-known/farcaster.json`
- */
-export type Manifest = {
-  accountAssociation: AccountAssociation
-  frame: FrameConfig
-}
-
-/**
- * Signed domain association linking this frame to a Farcaster account
- *
- * A DomainAssociation can be generated using the {@link https://farcaster.xyz/~/developers/domains | Warpcast
- * Domains Developer} tool.
- */
-export type AccountAssociation = {
-  /**
-   * Base64URL encoded JFS signature
-   */
-  header: string
-
-  /**
-   * Base64URL encoded payload signature
-   */
-  payload: string
-
-  /**
-   * Base64URL encoded signature
-   */
-  signature: string
-}
-
-/**
- * Frame configuration
- *
- * @example
- * ``ts
- * const frame: FrameConfig = {
- *   version: '1',
- *   name: 'Yoink!',
- *   homeUrl: 'https://yoink.party',
- *   iconUrl: 'https://yoink.party/img/icon.png',
- *   imageUrl: 'https://yoink.party/framesV2/opengraph-image',
- *   buttonTitle: '🚩 Start',
- *   splashImageUrl: 'https://yoink.party/img/splash.png',
- *   splashImageBackgroundColor: '#eeeee4',
- *   webhookUrl: 'https://yoink.party/webhook'
- * };
- * ``
- */
-export type FrameConfig = {
-  /**
-   * Manifest version
-   *
-   * Must be the literal '1'.
-   */
-  version: '1'
-
-  /**
-   * App name that will be displayed to users
-   *
-   * Max length of 32 characters.
-   */
-  name: string
-
-  /**
-   * Default launch URL
-   *
-   * Max length of 1024 characters.
-   */
-  homeUrl: string
-
-  /**
-   * Icon URL
-   *
-   * Max length of 1024 characters. Image must be 200x200px and less than 1MB.
-   */
-  iconUrl: string
-
-  /**
-   * Image URL
-   *
-   * Max length of 1024 characters. Image must have a 3:2 ratio.
-   */
-  imageUrl: string
-
-  /**
-   * Default button title to use when frame is rendered.
-   *
-   * Max length of 32 characters.
-   */
-  buttonTitle: string
-
-  /**
-   * Splash image URL
-   *
-   * Max length of 1024 characters. Image must be 200x200px and less than 1MB.
-   */
-  splashImageUrl?: string
-
-  /**
-   * Splash background color
-   *
-   * Must be a hex color code.
-   */
-  splashBackgroundColor?: string
-
-  /**
-   * URL to which clients will POST server events.
-   * Max length of 1024 characters.
-   * Required if the frame application uses notifications.
-   */
-  webhookUrl?: string
-
-  /**
-   * Canonical domain for the frame application.
-   * If specified, this domain will be treated as the primary domain for the frame.
-   * Max length of 1024 characters.
-   */
-  canonicalDomain?: string
-}

package/src/schemas/embeds.ts

@@ -1,44 +0,0 @@
-import { z } from 'zod/v4'
-import {
-  aspectRatioSchema,
-  buttonTitleSchema,
-  caip19TokenSchema,
-  frameNameSchema,
-  hexColorSchema,
-  secureUrlSchema,
-} from './shared.ts'
-
-export const actionLaunchFrameSchema = z.object({
-  type: z.literal('launch_frame'),
-  name: frameNameSchema,
-  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', [
-  actionLaunchFrameSchema,
-  actionViewTokenSchema,
-])
-
-export const buttonSchema = z.object({
-  title: buttonTitleSchema,
-  action: actionSchema,
-})
-
-export const frameEmbedNextSchema = z.object({
-  version: z.literal('next'),
-  imageUrl: secureUrlSchema,
-  aspectRatio: aspectRatioSchema.optional(),
-  button: buttonSchema,
-})
-
-export const safeParseFrameEmbed = (rawResponse: unknown) =>
-  frameEmbedNextSchema.safeParse(rawResponse)
-
-export type FrameEmbedNext = z.infer<typeof frameEmbedNextSchema>

package/src/schemas/events.ts

@@ -1,41 +0,0 @@
-import { z } from 'zod/v4'
-import { notificationDetailsSchema } from './notifications.ts'
-
-export const eventFrameAddedSchema = z.object({
-  event: z.literal('frame_added'),
-  notificationDetails: notificationDetailsSchema.optional(),
-})
-
-export type EventFrameAdded = z.infer<typeof eventFrameAddedSchema>
-
-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', [
-  eventFrameAddedSchema,
-  eventFrameRemovedSchema,
-  eventNotificationsEnabledSchema,
-  notificationsDisabledSchema,
-])
-
-export type FrameServerEvent = z.infer<typeof serverEventSchema>

package/src/schemas/index.ts

@@ -1,5 +0,0 @@
-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

@@ -1,125 +0,0 @@
-import { z } from 'zod/v4'
-import { miniAppHostCapabilityList } from '../types.ts'
-import {
-  buttonTitleSchema,
-  createSimpleStringSchema,
-  domainSchema,
-  encodedJsonFarcasterSignatureSchema,
-  frameNameSchema,
-  hexColorSchema,
-  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 domainFrameConfigSchema = 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: frameNameSchema,
-    iconUrl: secureUrlSchema,
-    homeUrl: secureUrlSchema,
-    /** deprecated, set ogImageUrl instead */
-    imageUrl: secureUrlSchema.optional(),
-    /** deprecated, will rely on fc:frame 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 frame 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,
-  frame: domainFrameConfigSchema.optional(),
-})

package/src/schemas/notifications.ts

@@ -1,33 +0,0 @@
-import { z } from 'zod/v4'
-import { secureUrlSchema } from './shared.ts'
-
-export const notificationDetailsSchema = z.object({
-  url: z.string(),
-  token: z.string(),
-})
-
-export type FrameNotificationDetails = 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

@@ -1,138 +0,0 @@
-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 frameNameSchema = 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
->