@farcaster/miniapp-sdk 0.0.0-canary-20250630212339

package/dist/types.d.ts

@@ -0,0 +1,74 @@
+import type { AddMiniApp, ComposeCast, Context, GetCapabilities, GetChains, ImpactOccurred, MiniAppNotificationDetails, NotificationOccurred, Ready, SelectionChanged, SendToken, SetPrimaryButtonOptions, SignIn, SolanaWalletProvider, SwapToken, ViewCast, ViewProfile, ViewToken } from '@farcaster/miniapp-core';
+import type { EventEmitter } from 'eventemitter3';
+import type * as Provider from 'ox/Provider';
+import type { Back } from './back.ts';
+import type { QuickAuth } from './quickAuth.ts';
+declare global {
+    interface Window {
+        ReactNativeWebView: {
+            postMessage: (message: string) => void;
+        };
+    }
+}
+/** Combines members of an intersection into a readable type. */
+type Compute<type> = {
+    [key in keyof type]: type[key];
+} & unknown;
+export type EventMap = {
+    primaryButtonClicked: () => void;
+    miniAppAdded: ({ notificationDetails, }: {
+        notificationDetails?: MiniAppNotificationDetails;
+    }) => void;
+    miniAppAddRejected: ({ reason, }: {
+        reason: AddMiniApp.AddMiniAppRejectedReason;
+    }) => void;
+    miniAppRemoved: () => void;
+    notificationsEnabled: ({ notificationDetails, }: {
+        notificationDetails: MiniAppNotificationDetails;
+    }) => void;
+    notificationsDisabled: () => void;
+    backNavigationTriggered: () => void;
+};
+export type Emitter = Compute<EventEmitter<EventMap>>;
+type SetPrimaryButton = (options: SetPrimaryButtonOptions) => Promise<void>;
+export type MiniAppSDK = {
+    getCapabilities: GetCapabilities;
+    getChains: GetChains;
+    isInMiniApp: () => Promise<boolean>;
+    context: Promise<Context.MiniAppContext>;
+    back: Back;
+    quickAuth: QuickAuth;
+    actions: {
+        ready: (options?: Partial<Ready.ReadyOptions>) => Promise<void>;
+        openUrl: (url: string) => Promise<void>;
+        close: () => Promise<void>;
+        setPrimaryButton: SetPrimaryButton;
+        addFrame: AddMiniApp.AddMiniApp;
+        addMiniApp: AddMiniApp.AddMiniApp;
+        signIn: SignIn.SignIn;
+        viewCast: ViewCast.ViewCast;
+        viewProfile: ViewProfile.ViewProfile;
+        composeCast: <close extends boolean | undefined = undefined>(options?: ComposeCast.Options<close>) => Promise<ComposeCast.Result<close>>;
+        viewToken: ViewToken.ViewToken;
+        sendToken: SendToken.SendToken;
+        swapToken: SwapToken.SwapToken;
+    };
+    experimental: {
+        getSolanaProvider: () => Promise<SolanaWalletProvider | undefined>;
+        /**
+         * @deprecated - use `sdk.quickAuth.getToken`
+         */
+        quickAuth: QuickAuth['getToken'];
+    };
+    wallet: {
+        ethProvider: Provider.Provider;
+        getEthereumProvider: () => Promise<Provider.Provider | undefined>;
+        getSolanaProvider: () => Promise<SolanaWalletProvider | undefined>;
+    };
+    haptics: {
+        impactOccurred: ImpactOccurred;
+        notificationOccurred: NotificationOccurred;
+        selectionChanged: SelectionChanged;
+    };
+} & Emitter;
+export {};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@farcaster/miniapp-sdk",
+  "version": "0.0.0-canary-20250630212339",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/farcasterxyz/frames.git",
+    "directory": "packages/miniapp-sdk"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "devDependencies": {
+    "esbuild": "^0.25.0",
+    "mipd": "^0.0.7",
+    "typescript": "^5.8.3",
+    "@farcaster/tsconfig": "0.0.0-canary-20250630212339"
+  },
+  "dependencies": {
+    "@farcaster/quick-auth": "^0.0.6",
+    "comlink": "^4.4.2",
+    "eventemitter3": "^5.0.1",
+    "ox": "^0.4.4",
+    "@farcaster/miniapp-core": "0.0.0-canary-20250630212339"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "prebuild": "npm run clean",
+    "build": "pnpm build:cjs && pnpm build:umd",
+    "build:cjs": "tsc",
+    "build:umd": "node scripts/build.js",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/back.ts

@@ -0,0 +1,143 @@
+import type { WireMiniAppHost } from '@farcaster/miniapp-core'
+import type { Remote } from 'comlink'
+import type { Emitter } from './types.ts'
+
+export type Back = {
+  visible: boolean
+  show: () => Promise<void>
+  hide: () => Promise<void>
+  onback: (() => unknown) | null
+  enableWebNavigation: () => Promise<void>
+  disableWebNavigation: () => Promise<void>
+}
+
+export const createBack: (options: {
+  emitter: Emitter
+  miniAppHost: Remote<WireMiniAppHost>
+}) => Back = ({ miniAppHost, emitter }) => {
+  let teardownWebNavigation: (() => void) | undefined = undefined
+  let backCb: (() => unknown) | null = null
+
+  return {
+    visible: false,
+    get onback() {
+      return backCb
+    },
+    set onback(cb) {
+      if (backCb) {
+        emitter.removeListener('backNavigationTriggered', backCb)
+      }
+      backCb = cb
+      if (cb) {
+        emitter.addListener('backNavigationTriggered', cb)
+      }
+    },
+    async show() {
+      await miniAppHost.updateBackState({
+        visible: true,
+      })
+      this.visible = true
+    },
+    async hide() {
+      await miniAppHost.updateBackState({
+        visible: false,
+      })
+      this.visible = false
+    },
+    async enableWebNavigation() {
+      teardownWebNavigation = setupWebBack({
+        back: this,
+        emitter,
+      })
+    },
+    async disableWebNavigation() {
+      teardownWebNavigation?.()
+      teardownWebNavigation = undefined
+    },
+  }
+}
+
+function setupWebBack({
+  emitter,
+  back,
+}: {
+  emitter: Emitter
+  back: Back
+}) {
+  const navigation = getWebNavigation()
+  if (navigation) {
+    return setupNavigationApi({ emitter, back, navigation })
+  }
+
+  if (typeof window !== 'undefined') {
+    return setupFallback({ emitter, back, window })
+  }
+}
+
+function getWebNavigation(): Navigation | undefined {
+  if (typeof window !== 'undefined' && window.navigation !== undefined) {
+    return window.navigation
+  }
+}
+
+function setupNavigationApi({
+  emitter,
+  back,
+  navigation,
+}: {
+  emitter: Emitter
+  back: Back
+  navigation: Navigation
+}) {
+  function handleNavigateSuccess() {
+    if (navigation.canGoBack) {
+      back.show()
+    } else {
+      back.hide()
+    }
+  }
+
+  function handleBackNavigationTriggered() {
+    if (back.visible && navigation.canGoBack) {
+      navigation.back()
+    }
+  }
+
+  navigation.addEventListener('navigatesuccess', handleNavigateSuccess)
+  emitter.addListener('backNavigationTriggered', handleBackNavigationTriggered)
+
+  return () => {
+    navigation.removeEventListener('navigatesuccess', handleNavigateSuccess)
+    emitter.removeListener(
+      'backNavigationTriggered',
+      handleBackNavigationTriggered,
+    )
+  }
+}
+
+function setupFallback({
+  emitter,
+  back,
+  window,
+}: {
+  emitter: Emitter
+  back: Back
+  window: Window
+}) {
+  back.show()
+
+  function handleBackNavigationTriggered() {
+    if (back.visible) {
+      window.history.back()
+    }
+  }
+
+  emitter.addListener('backNavigationTriggered', handleBackNavigationTriggered)
+
+  return () => {
+    emitter.removeListener(
+      'backNavigationTriggered',
+      handleBackNavigationTriggered,
+    )
+  }
+}

package/src/endpoint.ts

@@ -0,0 +1,34 @@
+import { type Endpoint, windowEndpoint } from 'comlink'
+
+const mockEndpoint: Endpoint = {
+  postMessage() {
+    // noop
+  },
+  addEventListener: () => {
+    // noop
+  },
+  removeEventListener: () => {
+    // noop
+  },
+}
+
+const webViewEndpoint: Endpoint = {
+  postMessage: (data: unknown) => {
+    console.debug('[webview:req]', data)
+    window.ReactNativeWebView.postMessage(JSON.stringify(data))
+  },
+  addEventListener: (_, listener, ...args) => {
+    document.addEventListener('FarcasterFrameCallback', listener, ...args)
+  },
+  removeEventListener: (_, listener) => {
+    document.removeEventListener('FarcasterFrameCallback', listener)
+  },
+}
+
+export const endpoint = (() => {
+  // No actions are actually gonna take place during SSR, thus it's safe to return mocked endpoint
+  if (typeof window === 'undefined') return mockEndpoint
+  return window?.ReactNativeWebView
+    ? webViewEndpoint
+    : windowEndpoint(window?.parent ?? window)
+})()

package/src/ethereumProvider.ts

@@ -0,0 +1,183 @@
+import type {
+  EthProviderWireEvent,
+  MiniAppClientEvent,
+  MiniAppHostCapability,
+} from '@farcaster/miniapp-core'
+import type {
+  AnnounceProviderParameters,
+  AnnounceProviderReturnType,
+  EIP1193Provider,
+  EIP6963ProviderDetail,
+} from 'mipd'
+import * as Provider from 'ox/Provider'
+import * as RpcRequest from 'ox/RpcRequest'
+import * as RpcResponse from 'ox/RpcResponse'
+import { miniAppHost } from './miniAppHost.ts'
+
+const emitter = Provider.createEmitter()
+const store = RpcRequest.createStore()
+
+type GenericProviderRpcError = {
+  code: number
+  details?: string
+}
+
+function toProviderRpcError({
+  code,
+  details,
+}: GenericProviderRpcError): Provider.ProviderRpcError {
+  switch (code) {
+    case 4001:
+      return new Provider.UserRejectedRequestError()
+    case 4100:
+      return new Provider.UnauthorizedError()
+    case 4200:
+      return new Provider.UnsupportedMethodError()
+    case 4900:
+      return new Provider.DisconnectedError()
+    case 4901:
+      return new Provider.ChainDisconnectedError()
+    default:
+      return new Provider.ProviderRpcError(
+        code,
+        details ?? 'Unknown provider RPC error',
+      )
+  }
+}
+
+export const ethereumProvider: Provider.Provider = Provider.from({
+  ...emitter,
+  async request(args) {
+    // @ts-expect-error
+    const request = store.prepare(args)
+
+    try {
+      const response = await miniAppHost
+        .ethProviderRequestV2(request)
+        .then((res) => RpcResponse.parse(res, { request, raw: true }))
+
+      if (response.error) {
+        throw toProviderRpcError(response.error)
+      }
+
+      return response.result
+    } catch (e) {
+      // ethProviderRequestV2 not supported, fall back to v1
+      if (
+        e instanceof Error &&
+        e.message.match(/cannot read property 'apply'/i)
+      ) {
+        return await miniAppHost.ethProviderRequest(request)
+      }
+
+      if (
+        e instanceof Provider.ProviderRpcError ||
+        e instanceof RpcResponse.BaseError
+      ) {
+        throw e
+      }
+
+      throw new RpcResponse.InternalError({
+        message: e instanceof Error ? e.message : undefined,
+      })
+    }
+  },
+})
+
+export async function getEthereumProvider(): Promise<
+  Provider.Provider | undefined
+> {
+  try {
+    const capabilities = await miniAppHost.getCapabilities()
+    if (
+      !capabilities.includes('wallet.getEthereumProvider') &&
+      !capabilities.includes('wallet.getEvmProvider' as MiniAppHostCapability)
+    ) {
+      // We used getEvmProvider for a short period before getEthereumProvider.
+      // In case we're talking to an old host, we check the old key.
+      return undefined
+    }
+    return ethereumProvider
+  } catch {
+    // If this is an old frame host that doesn't support getCapabilities,
+    // getEthereumProvider will assume that it's supported
+    return ethereumProvider
+  }
+}
+
+function announceEvmProvider(
+  detail: AnnounceProviderParameters,
+): AnnounceProviderReturnType {
+  const event: CustomEvent<EIP6963ProviderDetail> = new CustomEvent(
+    'eip6963:announceProvider',
+    { detail: Object.freeze(detail) },
+  )
+
+  window.dispatchEvent(event)
+
+  const handler = () => window.dispatchEvent(event)
+  window.addEventListener('eip6963:requestProvider', handler)
+  return () => window.removeEventListener('eip6963:requestProvider', handler)
+}
+
+// Required to pass SSR
+if (typeof document !== 'undefined') {
+  // forward eip6963:requestProvider events to the host
+  document.addEventListener('eip6963:requestProvider', () => {
+    miniAppHost.eip6963RequestProvider()
+  })
+
+  // react native webview events
+  document.addEventListener('FarcasterFrameEthProviderEvent', (event) => {
+    if (event instanceof MessageEvent) {
+      const ethProviderEvent = event.data as EthProviderWireEvent
+      // @ts-expect-error
+      emitter.emit(ethProviderEvent.event, ...ethProviderEvent.params)
+    }
+  })
+
+  document.addEventListener('FarcasterFrameEvent', (event) => {
+    if (event instanceof MessageEvent) {
+      const miniAppEvent = event.data as MiniAppClientEvent
+      if (miniAppEvent.event === 'eip6963:announceProvider') {
+        announceEvmProvider({
+          info: miniAppEvent.info,
+          provider: ethereumProvider as EIP1193Provider,
+        })
+      }
+    }
+  })
+}
+
+// Required to pass SSR
+if (typeof window !== 'undefined') {
+  // forward eip6963:requestProvider events to the host
+  window.addEventListener('eip6963:requestProvider', () => {
+    miniAppHost.eip6963RequestProvider()
+  })
+
+  // web events
+  window.addEventListener('message', (event) => {
+    if (event instanceof MessageEvent) {
+      if (event.data.type === 'frameEthProviderEvent') {
+        const ethProviderEvent = event.data as EthProviderWireEvent
+        // @ts-expect-error
+        emitter.emit(ethProviderEvent.event, ...ethProviderEvent.params)
+      }
+    }
+  })
+
+  window.addEventListener('message', (event) => {
+    if (event instanceof MessageEvent) {
+      if (event.data.type === 'frameEvent') {
+        const miniAppEvent = event.data.event as MiniAppClientEvent
+        if (miniAppEvent.event === 'eip6963:announceProvider') {
+          announceEvmProvider({
+            info: miniAppEvent.info,
+            provider: ethereumProvider as EIP1193Provider,
+          })
+        }
+      }
+    }
+  })
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+import { sdk } from './sdk.ts'
+
+export * from './miniAppHost.ts'
+export * from './sdk.ts'
+export * from '@farcaster/miniapp-core'
+
+export * as QuickAuth from './quickAuth.ts'
+
+export { quickAuth } from './quickAuth.ts'
+
+export default sdk

package/src/miniAppHost.ts

@@ -0,0 +1,8 @@
+import type { WireMiniAppHost } from '@farcaster/miniapp-core'
+import { wrap } from 'comlink'
+import { endpoint } from './endpoint.ts'
+
+export const miniAppHost = wrap<WireMiniAppHost>(endpoint)
+
+// Backward compatibility
+export const frameHost = miniAppHost

package/src/navigation.d.ts

@@ -0,0 +1,191 @@
+interface Window {
+  readonly navigation?: Navigation
+}
+
+interface NavigationEventMap {
+  navigate: NavigateEvent
+  navigatesuccess: Event
+  navigateerror: ErrorEvent
+  currententrychange: NavigationCurrentEntryChangeEvent
+}
+
+interface NavigationResult {
+  committed: Promise<NavigationHistoryEntry>
+  finished: Promise<NavigationHistoryEntry>
+}
+
+declare class Navigation extends EventTarget {
+  entries(): NavigationHistoryEntry[]
+  readonly currentEntry: NavigationHistoryEntry | null
+  updateCurrentEntry(options: NavigationUpdateCurrentEntryOptions): void
+  readonly transition: NavigationTransition | null
+
+  readonly canGoBack: boolean
+  readonly canGoForward: boolean
+
+  navigate(url: string, options?: NavigationNavigateOptions): NavigationResult
+  reload(options?: NavigationReloadOptions): NavigationResult
+
+  traverseTo(key: string, options?: NavigationOptions): NavigationResult
+  back(options?: NavigationOptions): NavigationResult
+  forward(options?: NavigationOptions): NavigationResult
+
+  onnavigate: ((this: Navigation, ev: NavigateEvent) => any) | null
+  onnavigatesuccess: ((this: Navigation, ev: Event) => any) | null
+  onnavigateerror: ((this: Navigation, ev: ErrorEvent) => any) | null
+  oncurrententrychange:
+    | ((this: Navigation, ev: NavigationCurrentEntryChangeEvent) => any)
+    | null
+
+  addEventListener<K extends keyof NavigationEventMap>(
+    type: K,
+    listener: (this: Navigation, ev: NavigationEventMap[K]) => any,
+    options?: boolean | AddEventListenerOptions,
+  ): void
+  addEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | AddEventListenerOptions,
+  ): void
+  removeEventListener<K extends keyof NavigationEventMap>(
+    type: K,
+    listener: (this: Navigation, ev: NavigationEventMap[K]) => any,
+    options?: boolean | EventListenerOptions,
+  ): void
+  removeEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | EventListenerOptions,
+  ): void
+}
+
+declare class NavigationTransition {
+  readonly navigationType: NavigationTypeString
+  readonly from: NavigationHistoryEntry
+  readonly finished: Promise<void>
+}
+
+interface NavigationHistoryEntryEventMap {
+  dispose: Event
+}
+
+interface NavigationHistoryEntry extends EventTarget {
+  readonly key: string
+  readonly id: string
+  readonly url: string | null
+  readonly index: number
+  readonly sameDocument: boolean
+
+  getState(): unknown
+
+  ondispose: ((this: NavigationHistoryEntry, ev: Event) => any) | null
+
+  addEventListener<K extends keyof NavigationHistoryEntryEventMap>(
+    type: K,
+    listener: (
+      this: NavigationHistoryEntry,
+      ev: NavigationHistoryEntryEventMap[K],
+    ) => any,
+    options?: boolean | AddEventListenerOptions,
+  ): void
+  addEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | AddEventListenerOptions,
+  ): void
+  removeEventListener<K extends keyof NavigationHistoryEntryEventMap>(
+    type: K,
+    listener: (
+      this: NavigationHistoryEntry,
+      ev: NavigationHistoryEntryEventMap[K],
+    ) => any,
+    options?: boolean | EventListenerOptions,
+  ): void
+  removeEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | EventListenerOptions,
+  ): void
+}
+
+declare let NavigationHistoryEntry: {
+  prototype: NavigationHistoryEntry
+  new (): NavigationHistoryEntry
+}
+
+type NavigationTypeString = 'reload' | 'push' | 'replace' | 'traverse'
+
+interface NavigationUpdateCurrentEntryOptions {
+  state: unknown
+}
+
+interface NavigationOptions {
+  info?: unknown
+}
+
+interface NavigationNavigateOptions extends NavigationOptions {
+  state?: unknown
+  history?: 'auto' | 'push' | 'replace'
+}
+
+interface NavigationReloadOptions extends NavigationOptions {
+  state?: unknown
+}
+
+declare class NavigationCurrentEntryChangeEvent extends Event {
+  constructor(type: string, eventInit?: NavigationCurrentEntryChangeEventInit)
+
+  readonly navigationType: NavigationTypeString | null
+  readonly from: NavigationHistoryEntry
+}
+
+interface NavigationCurrentEntryChangeEventInit extends EventInit {
+  navigationType?: NavigationTypeString | null
+  from: NavigationHistoryEntry
+}
+
+declare class NavigateEvent extends Event {
+  constructor(type: string, eventInit?: NavigateEventInit)
+
+  readonly navigationType: NavigationTypeString
+  readonly canIntercept: boolean
+  readonly userInitiated: boolean
+  readonly hashChange: boolean
+  readonly hasUAVisualTransition: boolean
+  readonly destination: NavigationDestination
+  readonly signal: AbortSignal
+  readonly formData: FormData | null
+  readonly downloadRequest: string | null
+  readonly info?: unknown
+
+  intercept(options?: NavigationInterceptOptions): void
+  scroll(): void
+}
+
+interface NavigateEventInit extends EventInit {
+  navigationType?: NavigationTypeString
+  canIntercept?: boolean
+  userInitiated?: boolean
+  hashChange?: boolean
+  destination: NavigationDestination
+  signal: AbortSignal
+  formData?: FormData | null
+  downloadRequest?: string | null
+  info?: unknown
+}
+
+interface NavigationInterceptOptions {
+  handler?: () => Promise<void>
+  focusReset?: 'after-transition' | 'manual'
+  scroll?: 'after-transition' | 'manual'
+}
+
+declare class NavigationDestination {
+  readonly url: string
+  readonly key: string | null
+  readonly id: string | null
+  readonly index: number
+  readonly sameDocument: boolean
+
+  getState(): unknown
+}