npm package: @frontrowcc/frame-sdk
Description: This is the opinionated SDK that is used when building extensions for the Frontrow Platform.
Latest version: 0.3.3

# Frontrow Frame SDK

This is the opinionated SDK that is used when building extensions for the Frontrow Platform.

## Methods

- `navigate` - Will navigate the FrontRow Client App to the provided pathname
- `resizeFrame` - Will resize the FrontRow Client App (height only)
- `getChannelID` - Returns the ChannelID of the FrontRow Client App
- `getParentLocation` - Returns an object with parent Location information
- `getPlatform` - Returns the platform, one of: 'web', 'android', 'ios'
- `getTheme` - Returns the them value of the FrontRow Client App ('light'|'dark')
- `getToken` - Returns the OTP token string
- `onThemeChange` - Will call a callback if theme changes
- `share` - Will open a share dialog with the provided URL
- `download` - Will download the file at the provided URL
- `promptOptions` - Will prompt the user with options and return their selection or a cancel option. Takes an array of options with `id` and `label` properties, and an optional `onConfirm` callback. Returns a Promise that resolves with the selected option or cancel option.
- `emojiPicker` - Will prompt the user with an emoji half sheet and return their emoji selection or cancel option. Supports an option callback
- `subscribe` - Triggers the subscription flow in the parent window
- `login` - Triggers the login flow in the parent window
- `signup` - Triggers the signup flow in the parent window
- `unlock` - Triggers the unlock flow in the parent window with a subscription ID and one-time purchase IDs
- `unlockContent` - Triggers the unlock content flow in the parent window using access endpoints for specific content
- `onUserUpdated` - Will call a callback when the user updates

## Examples

### Navigating the Parent Client

```JSX
import { navigate } from '@frontrowcc/frame-sdk'

const HomeButton = () => {
  const onClick = () => {
    navigate({ pathname: '/' })
  }

  return <button onClick={onClick}>Go Home</button>
}
```

### Resizing the Frame on the Parent Client

```JSX
import { resizeFrame } from '@frontrowcc/frame-sdk'

type ListProps = {
  children: ReactNode
}

const ContentContainer = ({ children }: ListProps) => {
  const ref = useRef()
  const height = useRef<number>(0)

  useEffect(() => {
    if (ref.current) {
      const handleResize = () => {
        const newHeight = ref.current.getBoundingClientRect().height

        if (newHeight !== height) {
          height.current = newHeight
          // Call the resize function
          resizeFrame({ height: newHeight })
        }
      }

      const resizeObserver = new ResizeObserver(handleResize)

      resizeObserver.observe(ref.current)

      return () => {
        resizeObserver.disconnect()
      }
    }
  }, [ref])

  return <div ref={ref}>{children}</div>
}
```

### Listening to theme changes

The parent app has views that can be in either light or dark mode, this value can be retrieved using a getter fn `getTheme` which will return a Theme type of 'light' | 'dark'.

You can also subscribe to theme changes by registering a callback function like this:

```JSX
import { onThemeChange, getTheme } from '@frontrowcc/frame-sdk'

const intialTheme = getTheme()

// Set your themes initial Value, example:
document.documentElement.setAttribute('data-theme', initialTheme)


onThemeChange((theme) => {
  // Set your themes updated Value, example:
  document.documentElement.setAttribute('data-theme', theme)
})
```

### Downloading files

The SDK provides a `download` function that allows you to trigger a file download in the parent app. Here's how to use it:

```JSX
import { download } from `@frontrowcc/frame-sdk`

const DownloadButton = () => {
  const onClick = () => {
    download({
      url: 'https://example.com/really-cool-thing.png',
      filename: 'CoolestThingEver.png' // optional
    })
  }

  return <button onClick={onClick}>Download Cool Thing</button>
}
```

### Sharing files

The SDK provides a `share` function that allows you to trigger sharing in the parent app. Here's how to use it:

```JSX
import { share } from `@frontrowcc/frame-sdk`

const ShareButton = () => {
  const onClick = () => {
    share({ url: 'https://example.com/really-cool-thing.png' })
  }

  return <button onClick={onClick}>Share Cool Thing</button>
}
```

### Prompting for options

The SDK provides a `promptOptions` function that allows you to present a list of options to the user and handle their selection. Here's how to use it:

**prompOptions will return a promise**

```JSX
import { promptOptions } from '@frontrowcc/frame-sdk'

const OptionsButton = () => {
  const onClick = async () => {
    const options = [
      { id: 'option1', label: 'First Option' },
      { id: 'option2', label: 'Second Option' }
    ]

    const result = await promptOptions({ options })

    // Handle the selected option or cancellation
    if ('cancel' in result) {
      console.log('Selection was cancelled')
    } else {
      console.log(`Selected option: ${result.label} (${result.id})`)
    }
  }

  return <button onClick={onClick}>Show Options</button>
}

```

### Emoji Picker

The SDK provides a `emojiPicker` function that allows you to trigger an emojiPicker to the user. Here's how to use it:

**emojiPicker will return a promise**

```JSX
import { emojiPicker } from '@frontrowcc/frame-sdk'

const EmojiButton = () => {
  const onClick = async () => {

    const { emoji, cancel } = await emojiPicker()

    // Handle the selected option or cancellation
    if (cancel) {
      console.log('Selection was cancelled')
    } else {
      console.log(`Selected option: ${emoji}`)
    }
  }

  return <button onClick={onClick}>Show EmojiPicker</button>
}

```

### Subscription Flow

The SDK provides a method to trigger subscription flows in the parent app:

```JSX
import { subscribe } from '@frontrowcc/frame-sdk'

const SubscribeButton = () => {
  const handleSubscribe = () => {
    subscribe({ subscriptionID: 'premium-plan' })
  }

  return <button onClick={handleSubscribe}>Subscribe to Premium</button>
}
```

### Unlock Flow

The SDK provides a method to trigger unlock flows in the parent app with a subscription ID and one-time purchase IDs:

```JSX
import { unlock } from '@frontrowcc/frame-sdk'

const UnlockButton = () => {
  const handleUnlock = () => {
    unlock({
      subscriptionID: 'premium-monthly',
      oneTimePurchaseIDs: ['lifetime-access', 'special-feature']
    })
  }

  return <button onClick={handleUnlock}>Unlock Premium Features</button>
}
```

### Unlock Content Flow

The SDK provides a method to trigger unlock flows for specific content using access endpoints:

```JSX
import { unlockContent } from '@frontrowcc/frame-sdk'

const UnlockContentButton = () => {
  const handleUnlockContent = () => {
    unlockContent({
      contentType: 'video',
      contentID: 'video-123'
    })
  }

  return <button onClick={handleUnlockContent}>Unlock This Content</button>
}
```

### Listening to User Updates

You can listen for user updates using the `onUserUpdated` callback:

```JSX
import { onUserUpdated } from '@frontrowcc/frame-sdk'

// Set up the callback when your component mounts
useEffect(() => {
  onUserUpdated(() => {
    console.log('User has been updated!')
    // Refresh user data, update UI, etc.
  })
}, [])
```