@farcaster/miniapp-core 0.0.0-canary-20250630212339

package/src/actions/AddMiniApp.ts

@@ -0,0 +1,51 @@
+import * as Errors from '../errors.ts'
+import type { OneOf } from '../internal/types.ts'
+import type { MiniAppNotificationDetails } from '../schemas/index.ts'
+
+export type AddMiniAppResult = {
+  notificationDetails?: MiniAppNotificationDetails
+}
+
+export type AddMiniApp = () => Promise<AddMiniAppResult>
+
+type InvalidDomainManifestJsonError = {
+  type: 'invalid_domain_manifest'
+}
+
+type RejectedByUserJsonError = {
+  type: 'rejected_by_user'
+}
+
+export type AddMiniAppJsonError =
+  | InvalidDomainManifestJsonError
+  | RejectedByUserJsonError
+
+export type AddMiniAppRejectedReason = AddMiniAppJsonError['type']
+
+export type AddMiniAppJsonResult = OneOf<
+  { result: AddMiniAppResult } | { error: AddMiniAppJsonError }
+>
+
+export type WireAddMiniApp = () => Promise<AddMiniAppJsonResult>
+
+/**
+ * Thrown when the miniapp does not have a valid domain manifest.
+ */
+export class InvalidDomainManifest extends Errors.BaseError {
+  override readonly name = 'AddMiniApp.InvalidDomainManifest'
+
+  constructor() {
+    super('Invalid domain manifest')
+  }
+}
+
+/**
+ * Thrown when add miniapp action was rejected by the user.
+ */
+export class RejectedByUser extends Errors.BaseError {
+  override readonly name = 'AddMiniApp.RejectedByUser'
+
+  constructor() {
+    super('Add miniapp rejected by user')
+  }
+}

package/src/actions/ComposeCast.ts

@@ -0,0 +1,44 @@
+export type Options<close extends boolean | undefined = undefined> = {
+  /**
+   * Suggested text for the body of the cast.
+   *
+   * Mentions can be included using the human-writable 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
+
+  /** Whether the cast should be posted to a channel. */
+  channelKey?: string
+}
+
+export type ComposeCastInnerResult = {
+  /** 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 }
+
+  /** Channel key of the created cast */
+  channelKey?: string
+}
+
+export type Result<close extends boolean | undefined = undefined> =
+  close extends true
+    ? undefined
+    : {
+        cast: ComposeCastInnerResult | null
+      }

package/src/actions/Haptics.ts

@@ -0,0 +1,9 @@
+// Haptics types
+export type ImpactOccurredType = 'light' | 'medium' | 'heavy' | 'soft' | 'rigid'
+export type NotificationOccurredType = 'success' | 'warning' | 'error'
+
+export type ImpactOccurred = (type: ImpactOccurredType) => Promise<void>
+export type NotificationOccurred = (
+  type: NotificationOccurredType,
+) => Promise<void>
+export type SelectionChanged = () => Promise<void>

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,67 @@
+import * as Errors from '../errors.ts'
+import type { OneOf } from '../internal/types.ts'
+
+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
+
+  /**
+   * Whether an [Auth
+   * Address](https://github.com/farcasterxyz/protocol/discussions/225) signed
+   * message is acceptable. Defaults to `false` to maintain backwards
+   * compatibility, though applications should set this to `true` for the best
+   * user experience assuming their verification method supports it.
+   *
+   * @default false
+   */
+  acceptAuthAddress?: boolean
+}
+
+export type SignInResult = {
+  signature: string
+  message: string
+
+  /**
+   * Indicates if the signature was produced by a custody or auth address.
+   */
+  authMethod: 'custody' | 'authAddress'
+}
+
+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, 1 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/ViewCast.ts

@@ -0,0 +1,27 @@
+export type ViewCastOptions = {
+  /**
+   * The hash of the cast to view.
+   * @example "0x6a112e2d35e2d2008e25dd29811e8769d1edd9ca"
+   */
+  hash: string
+
+  /**
+   * Whether the app should be closed when this action is called.
+   * If true, the app will be closed after opening the cast view.
+   */
+  close?: boolean
+}
+
+/**
+ * Opens a cast view in the Farcaster client.
+ *
+ * @example
+ * ```ts
+ * await sdk.actions.viewCast({
+ *   hash: "0x6a112e2d35e2d2008e25dd29811e8769d1edd9ca"
+ * })
+ * ```
+ *
+ * @see {@link https://miniapps.farcaster.xyz/docs/sdk/actions/view-cast | View Cast Documentation}
+ */
+export type ViewCast = (options: ViewCastOptions) => Promise<void>

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,10 @@
+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

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

@@ -0,0 +1,117 @@
+import type { MiniAppNotificationDetails } 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?: MiniAppNotificationDetails
+  safeAreaInsets?: SafeAreaInsets
+}
+
+export type ClientFeatures = {
+  haptics: boolean
+}
+
+export type MiniAppContext = {
+  client: ClientContext
+  user: UserContext
+  location?: LocationContext
+  features?: ClientFeatures
+}

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,10 @@
+export * from './actions/index.ts'
+export * from './wallet/index.ts'
+export * as Back from './back.ts'
+export * as Errors from './errors.ts'
+export * as Context from './context.ts'
+export * as Manifest from './manifest.ts'
+export * from './types.ts'
+export * from './schemas/index.ts'
+export * from './solana.ts'
+export * from './solanaWire.ts'

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,131 @@
+/**
+ * Farcaster manifest for a domain hosted at `/.well-known/farcaster.json`
+ */
+export type Manifest = {
+  accountAssociation: AccountAssociation
+  miniapp?: MiniAppConfig
+  frame?: MiniAppConfig
+}
+
+/**
+ * Signed domain association linking this miniapp 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
+}
+
+/**
+ * MiniApp configuration
+ *
+ * @example
+ * ``ts
+ * const miniapp: MiniAppConfig = {
+ *   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 MiniAppConfig = {
+  /**
+   * 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 miniapp 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 miniapp application uses notifications.
+   */
+  webhookUrl?: string
+
+  /**
+   * Canonical domain for the miniapp application.
+   * If specified, this domain will be treated as the primary domain for the miniapp.
+   * Max length of 1024 characters.
+   */
+  canonicalDomain?: string
+}
+
+/**
+ * Helper function to get the MiniApp config from a manifest,
+ * supporting both 'miniapp' and 'frame' properties during the transition period
+ */
+export function getMiniAppConfig(
+  manifest: Manifest,
+): MiniAppConfig | undefined {
+  return manifest.miniapp || manifest.frame
+}