shopflo-appbrew 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,135 @@
-# Temporary Holding Version
+# shopflo-appbrew
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shopflo one-click checkout. Replaces the native checkout flow with a Shopflo-hosted checkout rendered in a WebView.
+
+## Blocks
+
+Registered via `registerShopfloBlocks(r)`:
+
+- `shopflo-web-view` — WebView that loads the Shopflo checkout URL.
+
+## Cart and checkout screens
+
+`registerShopfloScreens()` replaces the `cart` screen and adds `shopflo-checkout`, and sends every native checkout link (`checkout-address`, `add-address`, `payment`) to Shopflo. Call it in `initApp`, before the first render — the navigator reads the screen registry when it builds.
+
+```ts
+registerShopfloScreens()
+onConfigReady(() => setUpShopflo({ shopUrl, themeId, applicationId }))
+```
+
+The cart screen shows the native (config-driven) cart until Shopflo is usable, then the Shopflo WebView:
+
+| State | Cart tab shows |
+| --- | --- |
+| Health check pending, failed, or `enabled: false` | Native cart |
+| Shopflo enabled, cart empty | Native cart (Shopflo's token API rejects an empty cart) |
+| Shopflo enabled, cart has items | Shopflo WebView, kept after purchase so the thank-you page stays |
+
+The status is reactive: a cart opened before the health check settles switches to Shopflo when it lands. The health check retries once before falling back to native.
+
+### What a registered screen has to provide
+
+`app.components.register('screen', 'cart', …)` replaces the whole `ScreenBrewery`, not just its blocks. Everything `ScreenBrewery` normally does is now the screen's job:
+
+- **Safe areas** — wrap the content in `SafeAreaContainer` from `@gauntlet/brewery`. Without it the WebView starts at y = 0 and Shopflo's header and close button sit under the status bar, where iOS swallows the taps.
+- **Sizing** — there is no `ScreenContext`, so no `contentHeight`. `ShopfloWebview` sizes itself with `flex: 1` when it renders outside `ScreenBrewery`.
+- **Bottom bar** — `cart` is a bottom-bar tab in most themes. If the theme shows the bar it is drawn over the screen, so leave room for it.
+
+| Before | After |
+| --- | --- |
+| ![Shopflo header under the status bar](docs/images/cart-before.png) | ![Shopflo cart inside the safe area](docs/images/cart-after.png) |
+
+### Keeping the Appbrew app bar (recommended)
+
+If you need the Appbrew app bar as the header, render the WebView *inside* `ScreenBrewery` with `renderContent`, and control the rest from the `cart` screen's config. `ScreenBrewery` keeps its app bar, safe areas, `ScreenContext` and bottom-bar spacing, and swaps only the block list for what `renderContent` returns:
+
+```tsx
+showedShopflo.current = true
+return (
+  <ScreenBrewery
+    id={nativeScreenId}
+    style={{ backgroundColor: '#fff', flex: 1 }}
+    options={options}
+    renderContent={() => (
+      <BlockOverrideContext.Provider value={shopfloBlock}>
+        <ShopfloWebview
+          screenId={shopfloBlock.screenId}
+          componentId={shopfloBlock.componentId}
+          instanceId={shopfloBlock.instanceId}
+          index={0}
+          length={1}
+        />
+      </BlockOverrideContext.Provider>
+    )}
+  />
+)
+```
+
+Then switch off what you don't need on the `cart` screen. Both are per-screen theme settings, so they apply to the theme you edit; publish it to take effect.
+
+**In Studio:** open the app → **Design** → pick the theme → select the **Cart** screen, then click the element on the canvas to open its actions:
+
+| What | Click on the canvas | Action | Theme config it writes |
+| --- | --- | --- | --- |
+| Checkout bar (the screen's footer, `checkout-bar-v2`) | the checkout bar at the bottom | **Hide block** (eye icon; **Show block** undoes it) | `screens.cart.layout.footer.visibility.hide: true` |
+| App bar | the app bar at the top | **Hide app bar** (**Show app bar** undoes it) | `screens.cart.options.hideAppbar: true` |
+
+**In the theme JSON** (the same two keys, if you edit config directly):
+
+```jsonc
+"screens": {
+  "cart": {
+    "options": { "hideAppbar": true },          // false or absent: app bar shown
+    "layout": {
+      "footer": {
+        "componentId": "checkout-bar-v2",
+        "visibility": { "hide": true }           // false or absent: checkout bar shown
+      }
+    }
+  }
+}
+```
+
+What to set:
+
+1. **Checkout bar: always hide it.** `ScreenBrewery` renders it under the WebView, next to Shopflo's own Checkout button (screenshot below). Hiding it leaves no gap; the WebView takes the space.
+2. **App bar: your choice.** Keep it (`hideAppbar` false) to show the Appbrew header; its title and icons come from the screen's `layout.header`, falling back to the theme's global app bar, and are edited in Studio, not code. Hide it (`hideAppbar: true`) to give the WebView the full screen; `ScreenBrewery` still keeps it below the status bar.
+3. **Shopflo's own cart header: hide it** (on the Shopflo side) when you keep the app bar, or the screen shows two headers.
+
+- Keep the `ShopfloWebview` call as is; only the wrapper changes. Drop the `SafeAreaContainer` — `ScreenBrewery` handles the insets.
+- `ShopfloWebview` takes its height from `ScreenContext.contentHeight` here, so it fits between the app bar and the bottom bar without changes.
+- These are config changes to the `cart` screen, which the native cart (the fallback when Shopflo is off or the cart is empty) also renders — check the native cart still looks right without them.
+
+| App bar kept, checkout bar hidden | `hideAppbar: true` — full screen | Before the config changes |
+| --- | --- | --- |
+| ![Appbrew app bar over the Shopflo cart](docs/images/cart-appbar.png) | ![Shopflo cart full screen](docs/images/cart-appbar-hidden.png) | ![Two headers and two Checkout buttons](docs/images/cart-appbar-cart-screen.png) |
+
+The last one is `renderContent` without the config changes: the app bar is in place, but Shopflo's header and the native checkout bar still show.
+
+### Messages from the Shopflo page
+
+`ShopfloWebview` handles these `postMessage` events (only those with `source: 'SHOPFLO'`):
+
+| `type` | Action |
+| --- | --- |
+| `FLO_CART_UPDATE` | Empty cart: reset the Shopify cart and go back |
+| `FLO_ITEM_UPDATE` | Sync the line's quantity to the Shopify cart |
+| `FLO_CART_TO_CHECKOUT` | Switch the same token to the checkout view |
+| `CLOSE_CART_IFRAME` | Cart view's close (X): go back, or open `closeModalId` if set |
+| `FLO_EXIT_CHECKOUT` | From checkout: go home; from the cart: same as `CLOSE_CART_IFRAME` |
+
+## Provider
+
+`ShopfloProvider` implements `ICheckoutProvider`. `fetchCheckoutUrl()` exchanges the current Shopify cart token for a Shopflo checkout URL via `POST https://api.shopflo.co/kratos/api/v1/token/shopify-cart-token`, sending the cart token, `config.integrations.shopify.domain`, the storefront access token, and the customer access token (when signed in) — so the Shopify integration must be configured in the same app.
+
+## Settings
+
+Declared in the `appbrew` manifest under `config.integrations.shopflo`:
+
+| Key | Required | Purpose |
+| --- | --- | --- |
+| `salesChannelApiKey` | yes | Shopflo sales-channel API key, sent as the `Authorization` header (secret) |
+
+## Native dependencies
+
+The manifest sets `requiresNativeBuild: true`. Peer dependencies shipping native code: `react-native-webview`, `react-native-in-app-review`, `react-native-send-intent`, `react-native-safe-area-context`, so installing this integration in an app requires a new binary.

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "shopflo-appbrew",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "@gauntlet/brewery": ">0.36.0",
+    "@gauntlet/components": ">0.36.0",
+    "@gauntlet/state": ">0.36.0",
+    "@gauntlet/types": ">0.36.0",
+    "@react-navigation/native": "*",
+    "react": "*",
+    "react-native": "*",
+    "react-native-in-app-review": "*",
+    "react-native-loading-dots": "*",
+    "react-native-safe-area-context": "*",
+    "react-native-send-intent": "^1.3.0",
+    "react-native-uuid": "^2.0.1",
+    "react-native-webview": "*"
+  },
+  "description": "Shopflo one-click checkout and discounts.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shopflo-co/appbrew-shopflo.git",
+    "directory": "packages/shopflo"
+  },
+  "license": "ISC",
+  "keywords": [
+    "appbrew-integration"
+  ],
+  "appbrew": {
+    "settings": [
+      {
+        "key": "salesChannelApiKey",
+        "title": "Api Key",
+        "secret": true
+      },
+      {
+        "key": "enableShopfloCart",
+        "title": "Enable Shopflo Cart",
+        "type": "boolean",
+        "required": false
+      }
+    ],
+    "configKey": "shopflo",
+    "requiresNativeBuild": true
+  }
+}

package/src/blocks/shopflo-web-view.tsx

@@ -0,0 +1,442 @@
+import * as React from 'react'
+import {
+  ScreenContext,
+  useAnalytics,
+  useAppStore,
+  useBlock,
+  useBottomSheetModal,
+  useDeviceDimensions,
+  useLink,
+  useSetOverrideBack,
+  useSetWebUrl,
+} from '@gauntlet/state'
+import { WebView } from 'react-native-webview'
+import { Linking, Platform, View } from 'react-native'
+import { AnalyticsEvent, BaseBlockProps } from '@gauntlet/types'
+import LoadingDots from 'react-native-loading-dots'
+import { useBlockSettings } from '@gauntlet/components/style-utils'
+import { useSafeAreaInsets } from 'react-native-safe-area-context'
+import InAppReview from 'react-native-in-app-review'
+import SendIntentAndroid from 'react-native-send-intent'
+import { ShopfloProvider } from '../provider'
+import { isHomePage, isThankYou } from '@gauntlet/components/utils'
+import { useIsFocused } from '@react-navigation/native'
+import {
+  lastSegment,
+  toCartSignature,
+  toShopfloCartUrl,
+} from '../utils/shopflo'
+import { toUpiAppUrl } from '../utils/payment-intents'
+import type { ShopfloPage } from '../types'
+
+type ShopfloWebviewProps = BaseBlockProps & {
+  // 'cart' opens Shopflo's cart (cart token); 'checkout' a checkout (Token V2)
+  page?: ShopfloPage
+  // Set by the registered screens: they fall back to the native cart /
+  // checkout when the token call fails, instead of the backup-checkout redirect
+  onUnavailable?: () => void
+}
+
+export function ShopfloWebview(props: ShopfloWebviewProps) {
+  const { onUnavailable, page = 'cart' } = props
+  const webViewRef = React.useRef<WebView>(null)
+  const [checkoutData, setCheckoutData] = React.useState<
+    { checkoutUrl: string; tokenId: string; loadId: number } | undefined
+  >()
+  const isFocused = useIsFocused()
+  const cartSignature = useAppStore((s) => toCartSignature(s.cart.data.lineItems))
+  // Signature of the cart Shopflo currently shows; null until the first load
+  const loadedSignature = React.useRef<string | null>(null)
+  const block = useBlock(props.screenId, props.componentId, props.instanceId)
+  const settings = useBlockSettings(block)
+  const { width, height } = useDeviceDimensions()
+  const screen = React.useContext(ScreenContext)
+  const { gotoLink, back } = useLink()
+  const setWebUrl = useSetWebUrl()
+  const { openModal } = useBottomSheetModal()
+  const setOverrideBack = useSetOverrideBack()
+  const setCheckoutCompleted = useAppStore(
+    (s) => s.checkout.setCheckoutCompleted
+  )
+  const analytics = useAnalytics()
+  const { top, bottom } = useSafeAreaInsets()
+  const [keyboardHeight, setKeyboardHeight] = React.useState(0)
+  const appName = useAppStore.getState().constants.data?.env?.APP_NAME
+  const appVersion = useAppStore.getState().device.buildNumber
+  const shopifyDomain = useAppStore.getState().config.data?.integrations
+    ?.shopify?.domain as string
+  const userAgent = `Appbrew/${appName
+    ?.toLowerCase()
+    .replace(/\s/g, '')}/${Platform.OS.toLowerCase()}/${appVersion}`
+
+  const appbarHeight = useAppStore((store) => {
+    const h = Boolean(Number(store.config.data?.theme?.appBar.root?.height))
+      ? Number(store.config.data?.theme?.appBar.root?.height)
+      : 64
+    return h
+  })
+  const topOffset = settings?.options?.topOffset ?? 0
+  const defaultHeight = height - appbarHeight - top - bottom - topOffset
+
+  let h = screen?.value?.contentHeight ?? defaultHeight
+  if (!settings?.options?.ignoreKeyboardHeight && Platform.OS === 'android') {
+    h = h - keyboardHeight
+  }
+
+  const purchaseConfirmIdentifier = settings?.options?.purchaseConfirmIdentifier
+  const sendPurchasedEventDisabled =
+    settings.options?.sendPurchasedEventDisabled
+
+  const capturedCheckout = React.useRef(false)
+
+  React.useEffect(() => {
+    const id = screen?.value.keyboardHeightRef.current?.addListener((x) => {
+      setKeyboardHeight(x.value)
+    })
+    return () => {
+      if (id) {
+        screen?.value.keyboardHeightRef.current?.removeListener(id)
+      }
+    }
+  }, [screen])
+
+  const initializeWebView = React.useCallback(async () => {
+    if (!useAppStore.getState().modules.isModuleDefined('checkout')) {
+      console.error('Checkout module not found')
+      return
+    }
+
+    const checkoutProvider = useAppStore
+      .getState()
+      .modules.getModule<ShopfloProvider>('checkout')
+
+    if (!checkoutProvider) {
+      console.error('Failed to get checkout provider')
+      return
+    }
+
+    // Get the URL from the provider
+    loadedSignature.current = toCartSignature(
+      useAppStore.getState().cart.data.lineItems
+    )
+    const result =
+      page === 'checkout'
+        ? await checkoutProvider.fetchCheckoutUrl()
+        : await checkoutProvider.fetchCartUrl()
+    if (!result?.checkoutUrl || !result?.tokenId) {
+      console.error('Failed to get checkout URL')
+      if (onUnavailable) {
+        onUnavailable()
+        return
+      }
+      gotoLink({
+        kind: 'screen',
+        value: settings?.source?.backupCheckoutScreen ?? 'backup-checkout',
+      })
+      setOverrideBack('cart')
+      return
+    }
+
+    // The same cart_session_id returns the same URL, and an unchanged uri
+    // doesn't reload; loadId keys the WebView so Shopflo shows the new items
+    setCheckoutData((prev) => ({
+      checkoutUrl:
+        page === 'cart'
+          ? toShopfloCartUrl(result.checkoutUrl!)
+          : result.checkoutUrl!,
+      tokenId: result.tokenId!,
+      loadId: (prev?.loadId ?? 0) + 1,
+    }))
+    capturedCheckout.current = false
+  }, [page, settings, gotoLink, setOverrideBack, onUnavailable])
+
+  // On every visit, reload only if the app's cart changed since Shopflo got it.
+  // An empty cart (after purchase) keeps the thank-you page up
+  React.useEffect(() => {
+    if (!isFocused || !cartSignature) return
+    if (cartSignature === loadedSignature.current) return
+    initializeWebView()
+  }, [isFocused, cartSignature, initializeWebView])
+
+  // Shopflo already shows edits made inside it; record them as loaded so they
+  // don't trigger a reload of the cart the user is looking at
+  const syncFromShopflo = React.useCallback(
+    async (apply: () => Promise<unknown>) => {
+      try {
+        await apply()
+      } catch (error) {
+        console.warn('Syncing Shopflo cart change failed:', error)
+      }
+      loadedSignature.current = toCartSignature(
+        useAppStore.getState().cart.data.lineItems
+      )
+    },
+    []
+  )
+
+  const showInAppReview = React.useCallback(() => {
+    if (InAppReview.isAvailable()) {
+      setTimeout(() => {
+        InAppReview.RequestInAppReview().catch(console.error)
+      }, 5000)
+    }
+  }, [])
+
+  const handleCheckoutEvent = React.useCallback(async () => {
+    if (capturedCheckout.current) return
+    capturedCheckout.current = true
+
+    setCheckoutCompleted(true)
+
+    const payload = await useAppStore
+      .getState()
+      .modules.getModule<ShopfloProvider>('checkout')
+      ?.fetchOrderDetails(checkoutData?.tokenId)
+    const transformedPayload = transformCheckoutPayload(payload)
+    if (!transformedPayload) {
+      console.error('Failed to transform checkout payload')
+    }
+
+    analytics?.sendEvent(AnalyticsEvent.PURCHASE, transformedPayload)
+    useAppStore.getState().cart.resetCart()
+    setOverrideBack('home')
+    showInAppReview()
+
+    // Handle the redirect after purchase
+    if (!settings?.options?.redirectScreen) {
+      return
+    }
+    if (useAppStore.getState().user.isUserAuthenticated()) {
+      gotoLink({
+        kind: 'screen',
+        value: settings?.options?.redirectScreen,
+      })
+    } else {
+      gotoLink({
+        kind: 'screen',
+        value: 'home',
+      })
+    }
+  }, [
+    checkoutData,
+    gotoLink,
+    setOverrideBack,
+    settings,
+    showInAppReview,
+    setCheckoutCompleted,
+    analytics,
+  ])
+
+  const onMessageReceive = React.useCallback(
+    (event: any) => {
+      try {
+        const eventData = JSON.parse(event.nativeEvent.data)
+        const { type } = eventData
+        const cart = useAppStore.getState().cart
+        switch (type) {
+          // A quantity changed inside Shopflo; payload.item.id is the bare variant id
+          case 'FLO_ITEM_UPDATE': {
+            const item = eventData.payload?.item
+            const lineItem = cart.data.lineItems.find(
+              (li) => lastSegment(li.variantId) === String(item?.id)
+            )
+            if (!lineItem || lineItem.quantity === item.quantity) break
+            syncFromShopflo(() =>
+              Promise.resolve(
+                cart.updateQuantityForLineItem(lineItem.id, item.quantity)
+              )
+            )
+            break
+          }
+          // Everything was removed inside Shopflo: empty the app cart and leave
+          case 'FLO_CART_UPDATE': {
+            if (eventData.payload?.items?.length !== 0) break
+            const ids = cart.data.lineItems.map((li) => li.id)
+            if (ids.length) {
+              syncFromShopflo(() => cart.removeItemsFromCart(ids))
+            }
+            back()
+            break
+          }
+          // The cart view's close (X) posts CLOSE_CART_IFRAME, not FLO_EXIT_CHECKOUT
+          case 'CLOSE_CART_IFRAME':
+          case 'FLO_EXIT_CHECKOUT':
+            // On the cart screen Shopflo moved to checkout inside this WebView
+            // (is_cart_redirect); put it back on the cart so the next visit
+            // to the cart screen opens there
+            if (type === 'FLO_EXIT_CHECKOUT' && page === 'cart') {
+              setCheckoutData(
+                (prev) => prev && { ...prev, loadId: prev.loadId + 1 }
+              )
+            }
+            if (settings?.source?.closeModalId) {
+              openModal(settings.source.closeModalId)
+            } else {
+              back()
+            }
+            break
+          default:
+            return
+        }
+      } catch (error) {
+        console.error('Error parsing message from WebView:', error)
+      }
+    },
+    [page, settings, back, openModal, syncFromShopflo]
+  )
+
+  if (!checkoutData) return null
+
+  return (
+    <WebView
+      key={checkoutData.loadId}
+      ref={webViewRef}
+      applicationNameForUserAgent={userAgent}
+      source={{ uri: checkoutData?.checkoutUrl }}
+      startInLoadingState={true}
+      // Outside ScreenBrewery (the registered cart screen) there is no
+      // contentHeight, and defaultHeight would subtract an app bar that isn't drawn
+      style={screen ? { width: width, height: h } : { flex: 1, width: width }}
+      automaticallyAdjustContentInsets={false}
+      scrollEnabled={true}
+      nestedScrollEnabled={true}
+      javaScriptEnabled={true}
+      domStorageEnabled={true}
+      incognito={false}
+      originWhitelist={['*']}
+      onMessage={onMessageReceive}
+      onShouldStartLoadWithRequest={(e) => {
+        if (!e.url.startsWith('http')) {
+          if (e.url.startsWith('about:')) return false
+          if (
+            Platform.OS === 'android' &&
+            (e.url.startsWith('intent://') || e.url.startsWith('upi://'))
+          ) {
+            const upiAppUrl = toUpiAppUrl(e.url)
+            if (upiAppUrl) {
+              Linking.openURL(upiAppUrl).catch(() =>
+                SendIntentAndroid.openChromeIntent(e.url)
+              )
+            } else {
+              SendIntentAndroid.openChromeIntent(e.url)
+            }
+            return false
+          }
+          Linking.openURL(e.url)
+          return false
+        }
+        return true
+      }}
+      onLoadStart={(event) => {
+        const url = event.nativeEvent.url
+        setWebUrl(url)
+        if (url.includes('/cart')) {
+          webViewRef.current?.stopLoading()
+          // On the cart screen, going to 'cart' again would stack another one
+          // and mint a new token; on checkout this is back_url (exit). Leave
+          if (onUnavailable) {
+            back()
+            return
+          }
+          gotoLink({
+            kind: 'screen',
+            value: 'cart',
+          })
+        } else if (isHomePage(url, shopifyDomain)) {
+          webViewRef.current?.stopLoading()
+          gotoLink({
+            kind: 'screen',
+            value: 'home',
+          })
+        } else if (
+          isThankYou(url, purchaseConfirmIdentifier) &&
+          !sendPurchasedEventDisabled
+        ) {
+          handleCheckoutEvent()
+          setOverrideBack('home')
+        }
+      }}
+      renderLoading={() => (
+        <View
+          style={{
+            position: 'absolute',
+            alignItems: 'center',
+            justifyContent: 'center',
+            left: 0,
+            right: 0,
+            top: 0,
+            bottom: 0,
+          }}
+        >
+          <Loader colors={['#000', '#000', '#000', '#000']} />
+        </View>
+      )}
+    />
+  )
+}
+
+export function Loader({ colors }: { colors?: string[] }) {
+  const numOfDots = 4
+  return (
+    <View
+      style={{
+        width: 100,
+        backgroundColor: 'transparent',
+      }}
+    >
+      <LoadingDots
+        bounceHeight={5}
+        dots={numOfDots}
+        size={10}
+        colors={colors ?? Array(numOfDots).fill('#fff')}
+      />
+    </View>
+  )
+}
+
+/**
+ * Helper Functions
+ */
+
+const transformCheckoutPayload = (payload: any) => {
+  try {
+    const { response } = payload
+    const { order } = response
+    if (!order) return null
+
+    // Get coupon code if available
+    const coupon = order.discount_codes?.[0]?.code || ''
+
+    // Transform line items
+    const items = order.line_items.map((item: any) => ({
+      affiliation: item.vendor || '',
+      coupon,
+      discount: Number(item.total_discount),
+      handle: item.url?.replace('/products/', '') || '',
+      img_url: item.image || '',
+      item_brand: item.vendor,
+      item_category: item.product_type || '',
+      item_id: item.product_id?.toString(),
+      item_name: item.title,
+      item_variant: item.variant_id?.toString(),
+      url: item.url || '',
+      sku: item.sku,
+      price: Number(item.price),
+      quantity: item.quantity,
+    }))
+
+    return {
+      value: Number(order.total_price),
+      shipping: Number(order.total_shipping_price_set?.shop_money?.amount || 0),
+      items,
+      coupon,
+      sub_total: Number(order.subtotal_price),
+      checkout_token: order.token,
+      currency: order.currency,
+      discount: Number(order.total_discounts || 0),
+    }
+  } catch (error) {
+    console.error('Error transforming checkout payload:', error)
+    return null
+  }
+}