@farcaster/frame-sdk 0.0.55 → 0.0.56

package/dist/types.d.ts

@@ -1,6 +1,7 @@
 import type { AddMiniApp, ComposeCast, Context, FrameNotificationDetails, GetCapabilities, GetChains, ImpactOccurred, NotificationOccurred, Ready, SelectionChanged, SendToken, SetPrimaryButtonOptions, SignIn, SolanaWalletProvider, SwapToken, ViewCast, ViewProfile, ViewToken } from '@farcaster/frame-core';
 import type { EventEmitter } from 'eventemitter3';
 import type * as Provider from 'ox/Provider';
+import type { Back } from './back.ts';
 declare global {
     interface Window {
         ReactNativeWebView: {
@@ -25,6 +26,7 @@ export type EventMap = {
         notificationDetails: FrameNotificationDetails;
     }) => void;
     notificationsDisabled: () => void;
+    backNavigationTriggered: () => void;
 };
 export type Emitter = Compute<EventEmitter<EventMap>>;
 type SetPrimaryButton = (options: SetPrimaryButtonOptions) => Promise<void>;
@@ -33,6 +35,7 @@ export type FrameSDK = {
     getChains: GetChains;
     isInMiniApp: () => Promise<boolean>;
     context: Promise<Context.FrameContext>;
+    back: Back;
     actions: {
         ready: (options?: Partial<Ready.ReadyOptions>) => Promise<void>;
         openUrl: (url: string) => Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farcaster/frame-sdk",
-  "version": "0.0.55",
+  "version": "0.0.56",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -23,7 +23,7 @@
     "comlink": "^4.4.2",
     "eventemitter3": "^5.0.1",
     "ox": "^0.4.4",
-    "@farcaster/frame-core": "0.1.4"
+    "@farcaster/frame-core": "0.1.5"
   },
   "scripts": {
     "clean": "rm -rf dist",

package/src/back.ts

@@ -0,0 +1,143 @@
+import type { WireFrameHost } from '@farcaster/frame-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
+  frameHost: Remote<WireFrameHost>
+}) => Back = ({ frameHost, 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 frameHost.updateBackState({
+        visible: true,
+      })
+      this.visible = true
+    },
+    async hide() {
+      await frameHost.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/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
+}

package/src/sdk.ts

@@ -4,37 +4,14 @@ import {
   SignIn,
 } from '@farcaster/frame-core'
 import { createLightClient } from '@farcaster/quick-auth/light'
-import { EventEmitter } from 'eventemitter3'
 import * as Siwe from 'ox/Siwe'
+import { createBack } from './back.ts'
 import { ethereumProvider, getEthereumProvider } from './ethereumProvider.ts'
 import { frameHost } from './frameHost.ts'
+import { emitter } from './sdkEmitter.ts'
 import { getSolanaProvider } from './solanaProvider.ts'
-import type { Emitter, EventMap, FrameSDK } from './types.ts'
+import type { FrameSDK } from './types.ts'
 
-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()
 let cachedIsInMiniAppResult: boolean | null = null
 
 /**
@@ -101,9 +78,12 @@ export const sdk: FrameSDK = {
   getChains: frameHost.getChains,
   isInMiniApp,
   context: frameHost.context,
+  back: createBack({ frameHost, emitter }),
   actions: {
     setPrimaryButton: frameHost.setPrimaryButton.bind(frameHost),
-    ready: frameHost.ready.bind(frameHost),
+    ready: async (options = {}) => {
+      return await frameHost.ready(options)
+    },
     close: frameHost.close.bind(frameHost),
     viewCast: frameHost.viewCast.bind(frameHost),
     viewProfile: frameHost.viewProfile.bind(frameHost),
@@ -202,6 +182,8 @@ if (typeof document !== 'undefined') {
         })
       } else if (frameEvent.event === 'notifications_disabled') {
         emitter.emit('notificationsDisabled')
+      } else if (frameEvent.event === 'back_navigation_triggered') {
+        emitter.emit('backNavigationTriggered')
       }
     }
   })
@@ -230,6 +212,8 @@ if (typeof window !== 'undefined') {
           })
         } else if (frameEvent.event === 'notifications_disabled') {
           emitter.emit('notificationsDisabled')
+        } else if (frameEvent.event === 'back_navigation_triggered') {
+          emitter.emit('backNavigationTriggered')
         }
       }
     }

package/src/sdkEmitter.ts

@@ -0,0 +1,27 @@
+import EventEmitter from 'eventemitter3'
+import type { Emitter, EventMap } from './types.ts'
+
+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),
+  }
+}
+
+export const emitter = createEmitter()

package/src/types.ts

@@ -20,6 +20,7 @@ import type {
 } from '@farcaster/frame-core'
 import type { EventEmitter } from 'eventemitter3'
 import type * as Provider from 'ox/Provider'
+import type { Back } from './back.ts'
 
 declare global {
   interface Window {
@@ -51,6 +52,7 @@ export type EventMap = {
     notificationDetails: FrameNotificationDetails
   }) => void
   notificationsDisabled: () => void
+  backNavigationTriggered: () => void
 }
 
 export type Emitter = Compute<EventEmitter<EventMap>>
@@ -62,6 +64,7 @@ export type FrameSDK = {
   getChains: GetChains
   isInMiniApp: () => Promise<boolean>
   context: Promise<Context.FrameContext>
+  back: Back
   actions: {
     ready: (options?: Partial<Ready.ReadyOptions>) => Promise<void>
     openUrl: (url: string) => Promise<void>