@farcaster/frame-core 0.0.0-canary-20250430150627

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@farcaster/frame-core",
+  "version": "0.0.0-canary-20250430150627",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/farcasterxyz/frames.git",
+    "directory": "packages/frame-core"
+  },
+  "main": "dist/index.js",
+  "module": "esm/index.js",
+  "files": [
+    "dist",
+    "esm",
+    "src"
+  ],
+  "devDependencies": {
+    "@vitest/coverage-v8": "^2.1.8",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.9",
+    "@farcaster/tsconfig": "0.0.2"
+  },
+  "dependencies": {
+    "ox": "^0.4.4",
+    "zod": "^3.24.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "rm -rf dist esm",
+    "prebuild": "npm run clean",
+    "build": "pnpm build:cjs & pnpm build:esm",
+    "build:cjs": "tsc -p tsconfig.node.json",
+    "build:esm": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest --coverage"
+  }
+}

package/src/actions/AddFrame.ts

@@ -0,0 +1,51 @@
+import * as Errors from '../errors'
+import type { OneOf } from '../internal/types'
+import type { FrameNotificationDetails } from '../schemas'
+
+export type AddFrameResult = {
+  notificationDetails?: FrameNotificationDetails
+}
+
+export type AddFrame = () => Promise<AddFrameResult>
+
+type InvalidDomainManifestJsonError = {
+  type: 'invalid_domain_manifest'
+}
+
+type RejectedByUserJsonError = {
+  type: 'rejected_by_user'
+}
+
+export type AddFrameJsonError =
+  | InvalidDomainManifestJsonError
+  | RejectedByUserJsonError
+
+export type AddFrameRejectedReason = AddFrameJsonError['type']
+
+export type AddFrameJsonResult = OneOf<
+  { result: AddFrameResult } | { error: AddFrameJsonError }
+>
+
+export type WireAddFrame = () => Promise<AddFrameJsonResult>
+
+/**
+ * Thrown when the frame does not have a valid domain manifest.
+ */
+export class InvalidDomainManifest extends Errors.BaseError {
+  override readonly name = 'AddFrame.InvalidDomainManifest'
+
+  constructor() {
+    super('Invalid domain manifest')
+  }
+}
+
+/**
+ * Thrown when add frame action was rejected by the user.
+ */
+export class RejectedByUser extends Errors.BaseError {
+  override readonly name = 'AddFrame.RejectedByUser'
+
+  constructor() {
+    super('Add frame rejected by user')
+  }
+}

package/src/actions/ComposeCast.ts

@@ -0,0 +1,36 @@
+export type Options<close extends boolean | undefined = undefined> = {
+  /**
+   * Suggested text for the body of the cast.
+   *
+   * Mentions can be included using the human-writeable form (e.g. @farcaster).
+   **/
+  text?: string
+
+  /** Suggested embeds. Max two. */
+  embeds?: [] | [string] | [string, string]
+
+  /** Suggested parent. */
+  parent?: { type: 'cast'; hash: string }
+
+  /** Whether the app should be closed when this action is called. */
+  close?: close
+}
+
+export type Result<close extends boolean | undefined = undefined> =
+  close extends true
+    ? undefined
+    : {
+        cast: {
+          /** Cast of the created cast */
+          hash: string
+
+          /** Text of the created cast */
+          text?: string
+
+          /** Embeds of the created cast */
+          embeds?: [] | [string] | [string, string]
+
+          /** Parent of the created cast */
+          parent?: { type: 'cast'; hash: string }
+        }
+      }

package/src/actions/Ready.ts

@@ -0,0 +1,15 @@
+export type ReadyOptions = {
+  /**
+   * Disable native gestures. Use this option if your frame uses gestures
+   * that conflict with native gestures.
+   *
+   * @defaultValue false
+   */
+  disableNativeGestures: boolean
+}
+
+export const DEFAULT_READY_OPTIONS = {
+  disableNativeGestures: false,
+} satisfies ReadyOptions
+
+export type Ready = (options?: Partial<ReadyOptions>) => void

package/src/actions/SendToken.ts

@@ -0,0 +1,57 @@
+export type SendTokenOptions = {
+  /**
+   * CAIP-19 asset ID
+   * For example, Base USDC:
+   * eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
+   */
+  token?: string
+
+  /**
+   * Token amount, as numeric string.
+   * For example, 10 USDC: 1000000
+   */
+  amount?: string
+
+  /**
+   * Recipient address.
+   */
+  recipientAddress?: string
+
+  /**
+   * Recipient fid.
+   */
+  recipientFid?: number
+}
+
+type SendTokenDetails = {
+  /**
+   * Tx identifier.
+   */
+  transaction: `0x${string}`
+}
+
+type SendTokenErrorDetails = {
+  /**
+   * Error code.
+   */
+  error: string
+  /**
+   * Error message.
+   */
+  message?: string
+}
+
+export type SendTokenErrorReason = 'rejected_by_user' | 'send_failed'
+
+export type SendTokenResult =
+  | {
+      success: true
+      send: SendTokenDetails
+    }
+  | {
+      success: false
+      reason: SendTokenErrorReason
+      error?: SendTokenErrorDetails
+    }
+
+export type SendToken = (options: SendTokenOptions) => Promise<SendTokenResult>

package/src/actions/SignIn.ts

@@ -0,0 +1,51 @@
+import * as Errors from '../errors'
+import type { OneOf } from '../internal/types'
+
+export type SignInOptions = {
+  /**
+   * A random string used to prevent replay attacks.
+   */
+  nonce: string
+
+  /**
+   * Start time at which the signature becomes valid.
+   * ISO 8601 datetime.
+   */
+  notBefore?: string
+
+  /**
+   * Expiration time at which the signature is no longer valid.
+   * ISO 8601 datetime.
+   */
+  expirationTime?: string
+}
+
+export type SignInResult = {
+  signature: string
+  message: string
+}
+
+export type SignIn = (options: SignInOptions) => Promise<SignInResult>
+
+type RejectedByUserJsonError = {
+  type: 'rejected_by_user'
+}
+
+export type SignInJsonError = RejectedByUserJsonError
+
+export type SignInJsonResult = OneOf<
+  { result: SignInResult } | { error: SignInJsonError }
+>
+
+export type WireSignIn = (options: SignInOptions) => Promise<SignInJsonResult>
+
+/**
+ * Thrown when a sign in action was rejected.
+ */
+export class RejectedByUser extends Errors.BaseError {
+  override readonly name = 'SignIn.RejectedByUser'
+
+  constructor() {
+    super('Sign in rejected by user')
+  }
+}

package/src/actions/SwapToken.ts

@@ -0,0 +1,54 @@
+export type SwapTokenOptions = {
+  /**
+   * CAIP-19 asset ID
+   * For example, Base USDC:
+   * eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
+   */
+  sellToken?: string
+
+  /**
+   * CAIP-19 token ID. For example, OP ETH:
+   * eip155:10/native
+   */
+  buyToken?: string
+
+  /**
+   * Sell token amount, as numeric string.
+   * For example, 10 USDC: 1000000
+   */
+  sellAmount?: string
+}
+
+type SwapTokenDetails = {
+  /**
+   * Array of tx identifiers in order of execution.
+   * Some swaps will have both an approval and swap tx.
+   */
+  transactions: `0x${string}`[]
+}
+
+type SwapTokenErrorDetails = {
+  /**
+   * Error code.
+   */
+  error: string
+  /**
+   * Error message.
+   */
+  message?: string
+}
+
+export type SwapErrorReason = 'rejected_by_user' | 'swap_failed'
+
+export type SwapTokenResult =
+  | {
+      success: true
+      swap: SwapTokenDetails
+    }
+  | {
+      success: false
+      reason: SwapErrorReason
+      error?: SwapTokenErrorDetails
+    }
+
+export type SwapToken = (options: SwapTokenOptions) => Promise<SwapTokenResult>

package/src/actions/ViewProfile.ts

@@ -0,0 +1,5 @@
+export type ViewProfileOptions = {
+  fid: number
+}
+
+export type ViewProfile = (options: ViewProfileOptions) => Promise<void>

package/src/actions/ViewToken.ts

@@ -0,0 +1,5 @@
+export type ViewTokenOptions = {
+  token: string
+}
+
+export type ViewToken = (options: ViewTokenOptions) => Promise<void>

package/src/actions/index.ts

@@ -0,0 +1,8 @@
+export * as AddFrame from './AddFrame'
+export * as ComposeCast from './ComposeCast'
+export * as Ready from './Ready'
+export * as SignIn from './SignIn'
+export * as SendToken from './SendToken'
+export * as SwapToken from './SwapToken'
+export * as ViewProfile from './ViewProfile'
+export * as ViewToken from './ViewToken'

package/src/context.ts

@@ -0,0 +1,90 @@
+import type { FrameNotificationDetails } from './schemas'
+
+export type CastEmbedLocationContext = {
+  type: 'cast_embed'
+  embed: string
+  cast: {
+    fid: number
+    hash: string
+  }
+}
+
+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
+  | 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 FrameContext = {
+  client: ClientContext
+  user: UserContext
+  location?: LocationContext
+}

package/src/errors.ts

@@ -0,0 +1,21 @@
+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/index.ts

@@ -0,0 +1,7 @@
+export * from './actions'
+export * from './wallet'
+export * as Errors from './errors'
+export * as Context from './context'
+export * as Manifest from './manifest'
+export * from './types'
+export * from './schemas'

package/src/internal/types.ts

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

@@ -0,0 +1,113 @@
+/**
+ * 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://warpcast.com/~/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
+}

package/src/schemas/embeds.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod'
+import {
+  aspectRatioSchema,
+  buttonTitleSchema,
+  caip19TokenSchema,
+  frameNameSchema,
+  hexColorSchema,
+  secureUrlSchema,
+} from './shared'
+
+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

@@ -0,0 +1,41 @@
+import { z } from 'zod'
+import { notificationDetailsSchema } from './notifications'
+
+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

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