@farcaster/frame-core 0.0.0-canary-20250430150627

package/src/schemas/manifest.ts

@@ -0,0 +1,68 @@
+import { z } from 'zod'
+import {
+  buttonTitleSchema,
+  createSimpleStringSchema,
+  encodedJsonFarcasterSignatureSchema,
+  frameNameSchema,
+  hexColorSchema,
+  secureUrlSchema,
+} from './shared'
+
+const primaryCategorySchema = z.enum([
+  'games',
+  'social',
+  'finance',
+  'utility',
+  'productivity',
+  'health-fitness',
+  'news-media',
+  'music',
+  'shopping',
+  'education',
+  'developer-tools',
+  'entertainment',
+  'art-creativity',
+])
+
+export const domainFrameConfigSchema = z.object({
+  // 0.0.0 and 0.0.1 are not technically part of the spec but kept for
+  // backwards compatibilty. 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(),
+})
+
+export const domainManifestSchema = z.object({
+  accountAssociation: encodedJsonFarcasterSignatureSchema,
+  frame: domainFrameConfigSchema.optional(),
+})

package/src/schemas/notifications.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod'
+import { secureUrlSchema } from './shared'
+
+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

@@ -0,0 +1,81 @@
+import { z } from 'zod'
+
+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)
+
+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.',
+  })
+
+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/types.ts

@@ -0,0 +1,95 @@
+import type {
+  AddFrame,
+  ComposeCast,
+  Ready,
+  SendToken,
+  SignIn,
+  SwapToken,
+  ViewProfile,
+  ViewToken,
+} from './actions'
+import type { FrameContext } from './context'
+import type {
+  EventFrameAdded,
+  EventFrameRemoved,
+  EventNotificationsDisabled,
+  EventNotificationsEnabled,
+} from './schemas'
+import type { Ethereum } from './wallet'
+
+export type SetPrimaryButtonOptions = {
+  text: string
+  loading?: boolean
+  disabled?: boolean
+  hidden?: boolean
+}
+
+// start backwards compat, remove in 1.0
+export * from './wallet/ethereum'
+export { DEFAULT_READY_OPTIONS, ReadyOptions } from './actions/Ready'
+export type SignInOptions = SignIn.SignInOptions
+// end backwards compat
+
+export type SetPrimaryButton = (options: SetPrimaryButtonOptions) => void
+
+export type WireFrameHost = {
+  context: FrameContext
+  close: () => void
+  ready: Ready.Ready
+  openUrl: (url: string) => void
+  signIn: SignIn.WireSignIn
+  setPrimaryButton: SetPrimaryButton
+  ethProviderRequest: Ethereum.EthProvideRequest
+  ethProviderRequestV2: Ethereum.RpcTransport
+  eip6963RequestProvider: () => void
+  addFrame: AddFrame.WireAddFrame
+  viewProfile: ViewProfile.ViewProfile
+  viewToken: ViewToken.ViewToken
+  sendToken: SendToken.SendToken
+  swapToken: SwapToken.SwapToken
+  composeCast: <close extends boolean | undefined = undefined>(
+    options: ComposeCast.Options<close>,
+  ) => Promise<ComposeCast.Result<close>>
+}
+
+export type FrameHost = {
+  context: FrameContext
+  close: () => void
+  ready: Ready.Ready
+  openUrl: (url: string) => void
+  signIn: SignIn.SignIn
+  setPrimaryButton: SetPrimaryButton
+  ethProviderRequest: Ethereum.EthProvideRequest
+  ethProviderRequestV2: Ethereum.RpcTransport
+  /**
+   * Receive forwarded eip6963:requestProvider events from the frame document.
+   * Hosts must emit an EventEip6963AnnounceProvider in response.
+   */
+  eip6963RequestProvider: () => void
+  addFrame: AddFrame.AddFrame
+  viewProfile: ViewProfile.ViewProfile
+  viewToken: ViewToken.ViewToken
+  sendToken: SendToken.SendToken
+  swapToken: SwapToken.SwapToken
+  composeCast: <close extends boolean | undefined = undefined>(
+    options: ComposeCast.Options<close>,
+  ) => Promise<ComposeCast.Result<close>>
+}
+
+export type EventFrameAddRejected = {
+  event: 'frame_add_rejected'
+  reason: AddFrame.AddFrameRejectedReason
+}
+
+export type EventPrimaryButtonClicked = {
+  event: 'primary_button_clicked'
+}
+
+export type FrameClientEvent =
+  | EventFrameAdded
+  | EventFrameAddRejected
+  | EventFrameRemoved
+  | EventNotificationsEnabled
+  | EventNotificationsDisabled
+  | EventPrimaryButtonClicked
+  | Ethereum.EventEip6963AnnounceProvider

package/src/wallet/ethereum.ts

@@ -0,0 +1,65 @@
+import type * as Address from 'ox/Address'
+import type * as Provider from 'ox/Provider'
+import type * as RpcRequest from 'ox/RpcRequest'
+import type * as RpcResponse from 'ox/RpcResponse'
+import type * as RpcSchema from 'ox/RpcSchema'
+
+export type EthProvideRequest<
+  schema extends RpcSchema.Generic = RpcSchema.Default,
+> = Provider.RequestFn<schema>
+
+export type FrameEthProviderEventData = {
+  type: 'frame_eth_provider_event'
+} & EthProviderWireEvent
+
+export type RpcTransport = (
+  request: RpcRequest.RpcRequest,
+) => Promise<RpcResponse.RpcResponse>
+
+export type ProviderRpcError = {
+  code: number
+  details?: string
+  message?: string
+}
+
+export type EthProviderWireEvent =
+  | {
+      event: 'accountsChanged'
+      params: [readonly Address.Address[]]
+    }
+  | {
+      event: 'chainChanged'
+      params: [string]
+    }
+  | {
+      event: 'connect'
+      params: [Provider.ConnectInfo]
+    }
+  | {
+      event: 'disconnect'
+      params: [ProviderRpcError]
+    }
+  | {
+      event: 'message'
+      params: [Provider.Message]
+    }
+
+export type EmitEthProvider = <event extends EthProviderWireEvent['event']>(
+  event: event,
+  params: Extract<EthProviderWireEvent, { event: event }>['params'],
+) => void
+
+/**
+ * Metadata of the EIP-1193 Provider.
+ */
+export interface EIP6963ProviderInfo {
+  icon: `data:image/${string}` // RFC-2397
+  name: string
+  rdns: string
+  uuid: string
+}
+
+export type EventEip6963AnnounceProvider = {
+  event: 'eip6963:announceProvider'
+  info: EIP6963ProviderInfo
+}

package/src/wallet/index.ts

@@ -0,0 +1 @@
+export * as Ethereum from './ethereum'