@farcaster/frame-sdk 0.0.0-canary-20250430150627

package/dist/types.d.ts

@@ -0,0 +1,52 @@
+import type { AddFrame, ComposeCast, Context, FrameNotificationDetails, Ready, SendToken, SetPrimaryButtonOptions, SignIn, SwapToken, ViewProfile, ViewToken } from '@farcaster/frame-core';
+import type { EventEmitter } from 'eventemitter3';
+import type * as Provider from 'ox/Provider';
+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;
+    frameAdded: ({ notificationDetails, }: {
+        notificationDetails?: FrameNotificationDetails;
+    }) => void;
+    frameAddRejected: ({ reason, }: {
+        reason: AddFrame.AddFrameRejectedReason;
+    }) => void;
+    frameRemoved: () => void;
+    notificationsEnabled: ({ notificationDetails, }: {
+        notificationDetails: FrameNotificationDetails;
+    }) => void;
+    notificationsDisabled: () => void;
+};
+export type Emitter = Compute<EventEmitter<EventMap>>;
+type SetPrimaryButton = (options: SetPrimaryButtonOptions) => Promise<void>;
+export type FrameSDK = {
+    context: Promise<Context.FrameContext>;
+    actions: {
+        ready: (options?: Partial<Ready.ReadyOptions>) => Promise<void>;
+        openUrl: (url: string) => Promise<void>;
+        close: () => Promise<void>;
+        setPrimaryButton: SetPrimaryButton;
+        addFrame: AddFrame.AddFrame;
+        signIn: SignIn.SignIn;
+        viewProfile: ViewProfile.ViewProfile;
+        composeCast: <close extends boolean | undefined = undefined>(options?: ComposeCast.Options<close>) => Promise<ComposeCast.Result<close>>;
+    };
+    experimental: {
+        viewToken: ViewToken.ViewToken;
+        sendToken: SendToken.SendToken;
+        swapToken: SwapToken.SwapToken;
+    };
+    wallet: {
+        ethProvider: Provider.Provider;
+    };
+} & Emitter;
+export {};

package/dist/types.js

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

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@farcaster/frame-sdk",
+  "version": "0.0.0-canary-20250430150627",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/farcasterxyz/frames.git",
+    "directory": "packages/frame-sdk"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "devDependencies": {
+    "esbuild": "^0.25.0",
+    "mipd": "^0.0.7",
+    "typescript": "^5.7.2",
+    "@farcaster/tsconfig": "0.0.2"
+  },
+  "dependencies": {
+    "comlink": "^4.4.2",
+    "eventemitter3": "^5.0.1",
+    "ox": "^0.4.4",
+    "@farcaster/frame-core": "0.0.0-canary-20250430150627"
+  },
+  "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/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/frameHost.ts

@@ -0,0 +1,5 @@
+import type { WireFrameHost } from '@farcaster/frame-core'
+import { wrap } from 'comlink'
+import { endpoint } from './endpoint'
+
+export const frameHost = wrap<WireFrameHost>(endpoint)

package/src/index.ts

@@ -0,0 +1,6 @@
+import { sdk } from './sdk'
+
+export * from './sdk'
+export * from '@farcaster/frame-core'
+
+export default sdk

package/src/provider.ts

@@ -0,0 +1,161 @@
+import type {
+  EthProviderWireEvent,
+  FrameClientEvent,
+} from '@farcaster/frame-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 { frameHost } from './frameHost'
+
+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 provider: Provider.Provider = Provider.from({
+  ...emitter,
+  async request(args) {
+    // @ts-expect-error
+    const request = store.prepare(args)
+
+    try {
+      const response = await frameHost
+        .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 frameHost.ethProviderRequest(request)
+      }
+
+      if (
+        e instanceof Provider.ProviderRpcError ||
+        e instanceof RpcResponse.BaseError
+      ) {
+        throw e
+      }
+
+      throw new RpcResponse.InternalError({
+        message: e instanceof Error ? e.message : undefined,
+      })
+    }
+  },
+})
+
+function announceProvider(
+  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', () => {
+    frameHost.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 frameEvent = event.data as FrameClientEvent
+      if (frameEvent.event === 'eip6963:announceProvider') {
+        announceProvider({
+          info: frameEvent.info,
+          provider: provider as EIP1193Provider,
+        })
+      }
+    }
+  })
+}
+
+// Required to pass SSR
+if (typeof window !== 'undefined') {
+  // forward eip6963:requestProvider events to the host
+  window.addEventListener('eip6963:requestProvider', () => {
+    frameHost.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 frameEvent = event.data.event as FrameClientEvent
+        if (frameEvent.event === 'eip6963:announceProvider') {
+          announceProvider({
+            info: frameEvent.info,
+            provider: provider as EIP1193Provider,
+          })
+        }
+      }
+    }
+  })
+}

package/src/sdk.ts

@@ -0,0 +1,140 @@
+import { AddFrame, type FrameClientEvent, SignIn } from '@farcaster/frame-core'
+import { EventEmitter } from 'eventemitter3'
+import { frameHost } from './frameHost'
+import { provider } from './provider'
+import type { Emitter, EventMap, FrameSDK } from './types'
+
+export function createEmitter(): Emitter {
+  const emitter = new EventEmitter<EventMap>()
+
+  return {
+    get eventNames() {
+      return emitter.eventNames.bind(emitter)
+    },
+    get listenerCount() {
+      return emitter.listenerCount.bind(emitter)
+    },
+    get listeners() {
+      return emitter.listeners.bind(emitter)
+    },
+    addListener: emitter.addListener.bind(emitter),
+    emit: emitter.emit.bind(emitter),
+    off: emitter.off.bind(emitter),
+    on: emitter.on.bind(emitter),
+    once: emitter.once.bind(emitter),
+    removeAllListeners: emitter.removeAllListeners.bind(emitter),
+    removeListener: emitter.removeListener.bind(emitter),
+  }
+}
+
+const emitter = createEmitter()
+
+export const sdk: FrameSDK = {
+  ...emitter,
+  context: frameHost.context,
+  actions: {
+    setPrimaryButton: frameHost.setPrimaryButton.bind(frameHost),
+    ready: frameHost.ready.bind(frameHost),
+    close: frameHost.close.bind(frameHost),
+    viewProfile: frameHost.viewProfile.bind(frameHost),
+    signIn: async (options) => {
+      const response = await frameHost.signIn(options)
+      if (response.result) {
+        return response.result
+      }
+
+      if (response.error.type === 'rejected_by_user') {
+        throw new SignIn.RejectedByUser()
+      }
+
+      throw new Error('Unreachable')
+    },
+    openUrl: (urlArg: string | { url: string }) => {
+      const url = typeof urlArg === 'string' ? urlArg : urlArg.url
+      return frameHost.openUrl(url.trim())
+    },
+    addFrame: async () => {
+      const response = await frameHost.addFrame()
+      if (response.result) {
+        return response.result
+      }
+
+      if (response.error.type === 'invalid_domain_manifest') {
+        throw new AddFrame.InvalidDomainManifest()
+      }
+
+      if (response.error.type === 'rejected_by_user') {
+        throw new AddFrame.RejectedByUser()
+      }
+
+      throw new Error('Unreachable')
+    },
+    composeCast(options = {}) {
+      return frameHost.composeCast(options) as never
+    },
+  },
+  experimental: {
+    viewToken: frameHost.viewToken.bind(frameHost),
+    sendToken: frameHost.sendToken.bind(frameHost),
+    swapToken: frameHost.swapToken.bind(frameHost),
+  },
+  wallet: {
+    ethProvider: provider,
+  },
+}
+
+// Required to pass SSR
+if (typeof document !== 'undefined') {
+  // react native webview events
+  document.addEventListener('FarcasterFrameEvent', (event) => {
+    if (event instanceof MessageEvent) {
+      const frameEvent = event.data as FrameClientEvent
+      if (frameEvent.event === 'primary_button_clicked') {
+        emitter.emit('primaryButtonClicked')
+      } else if (frameEvent.event === 'frame_added') {
+        emitter.emit('frameAdded', {
+          notificationDetails: frameEvent.notificationDetails,
+        })
+      } else if (frameEvent.event === 'frame_add_rejected') {
+        emitter.emit('frameAddRejected', { reason: frameEvent.reason })
+      } else if (frameEvent.event === 'frame_removed') {
+        emitter.emit('frameRemoved')
+      } else if (frameEvent.event === 'notifications_enabled') {
+        emitter.emit('notificationsEnabled', {
+          notificationDetails: frameEvent.notificationDetails,
+        })
+      } else if (frameEvent.event === 'notifications_disabled') {
+        emitter.emit('notificationsDisabled')
+      }
+    }
+  })
+}
+
+// Required to pass SSR
+if (typeof window !== 'undefined') {
+  // web events
+  window.addEventListener('message', (event) => {
+    if (event instanceof MessageEvent) {
+      if (event.data.type === 'frameEvent') {
+        const frameEvent = event.data.event as FrameClientEvent
+        if (frameEvent.event === 'primary_button_clicked') {
+          emitter.emit('primaryButtonClicked')
+        } else if (frameEvent.event === 'frame_added') {
+          emitter.emit('frameAdded', {
+            notificationDetails: frameEvent.notificationDetails,
+          })
+        } else if (frameEvent.event === 'frame_add_rejected') {
+          emitter.emit('frameAddRejected', { reason: frameEvent.reason })
+        } else if (frameEvent.event === 'frame_removed') {
+          emitter.emit('frameRemoved')
+        } else if (frameEvent.event === 'notifications_enabled') {
+          emitter.emit('notificationsEnabled', {
+            notificationDetails: frameEvent.notificationDetails,
+          })
+        } else if (frameEvent.event === 'notifications_disabled') {
+          emitter.emit('notificationsDisabled')
+        }
+      }
+    }
+  })
+}

package/src/types.ts

@@ -0,0 +1,75 @@
+import type {
+  AddFrame,
+  ComposeCast,
+  Context,
+  FrameNotificationDetails,
+  Ready,
+  SendToken,
+  SetPrimaryButtonOptions,
+  SignIn,
+  SwapToken,
+  ViewProfile,
+  ViewToken,
+} from '@farcaster/frame-core'
+import type { EventEmitter } from 'eventemitter3'
+import type * as Provider from 'ox/Provider'
+
+declare global {
+  interface Window {
+    // Exposed by react-native-webview
+    ReactNativeWebView: {
+      postMessage: (message: string) => void
+    }
+  }
+}
+
+/** Combines members of an intersection into a readable type. */
+// https://twitter.com/mattpocockuk/status/1622730173446557697?s=20&t=v01xkqU3KO0Mg
+type Compute<type> = { [key in keyof type]: type[key] } & unknown
+
+export type EventMap = {
+  primaryButtonClicked: () => void
+  frameAdded: ({
+    notificationDetails,
+  }: {
+    notificationDetails?: FrameNotificationDetails
+  }) => void
+  frameAddRejected: ({
+    reason,
+  }: { reason: AddFrame.AddFrameRejectedReason }) => void
+  frameRemoved: () => void
+  notificationsEnabled: ({
+    notificationDetails,
+  }: {
+    notificationDetails: FrameNotificationDetails
+  }) => void
+  notificationsDisabled: () => void
+}
+
+export type Emitter = Compute<EventEmitter<EventMap>>
+
+type SetPrimaryButton = (options: SetPrimaryButtonOptions) => Promise<void>
+
+export type FrameSDK = {
+  context: Promise<Context.FrameContext>
+  actions: {
+    ready: (options?: Partial<Ready.ReadyOptions>) => Promise<void>
+    openUrl: (url: string) => Promise<void>
+    close: () => Promise<void>
+    setPrimaryButton: SetPrimaryButton
+    addFrame: AddFrame.AddFrame
+    signIn: SignIn.SignIn
+    viewProfile: ViewProfile.ViewProfile
+    composeCast: <close extends boolean | undefined = undefined>(
+      options?: ComposeCast.Options<close>,
+    ) => Promise<ComposeCast.Result<close>>
+  }
+  experimental: {
+    viewToken: ViewToken.ViewToken
+    sendToken: SendToken.SendToken
+    swapToken: SwapToken.SwapToken
+  }
+  wallet: {
+    ethProvider: Provider.Provider
+  }
+} & Emitter