@shopify/ui-extensions-server-kit 0.0.0-experimental-20260902222805

package/src/state/reducers/extensionServerReducer.test.ts

@@ -0,0 +1,165 @@
+import {extensionServerReducer} from './extensionServerReducer'
+import {INITIAL_STATE} from './constants'
+import {mockExtension, mockApp} from '../../testing'
+import {
+  createConnectedAction,
+  createUpdateAction,
+  createRefreshAction,
+  createFocusAction,
+  createUnfocusAction,
+} from '../actions'
+import {vi} from 'vitest'
+
+import type {ExtensionServerState} from './types'
+
+describe('extensionServerReducer()', () => {
+  test('connects to server', () => {
+    const app = mockApp()
+    const extension = mockExtension()
+    const action = createConnectedAction({app, extensions: [extension], store: 'test-store.com'})
+    const state = extensionServerReducer(INITIAL_STATE, action)
+
+    expect(state).toStrictEqual({
+      app,
+      extensions: [extension],
+      store: 'test-store.com',
+    })
+  })
+
+  test('replaces existing app and extensions when connecting twice', () => {
+    const app = mockApp()
+    const extension = mockExtension()
+    const action1 = createConnectedAction({app, extensions: [extension], store: 'test-store.com'})
+    const initialState = extensionServerReducer(INITIAL_STATE, action1)
+
+    expect(initialState).toStrictEqual({
+      app,
+      extensions: [extension],
+      store: 'test-store.com',
+    })
+
+    const currentExtension = initialState.extensions[0]
+    const newExtension = {...currentExtension, uuid: 'new-uuid'}
+    const newApp = {...app, id: 'new-id'}
+    const action2 = createConnectedAction({app: newApp, extensions: [newExtension], store: 'test-store.com'})
+    const secondState = extensionServerReducer(initialState, action2)
+
+    expect(secondState).toStrictEqual({
+      app: newApp,
+      extensions: [newExtension],
+      store: 'test-store.com',
+    })
+  })
+
+  test('receives updates from the server', () => {
+    const extension1 = mockExtension()
+    const extension2 = mockExtension()
+    const previousState: ExtensionServerState = {
+      store: 'test-store.com',
+      extensions: [extension1, extension2],
+    }
+
+    const app = mockApp()
+    const updated1 = {...extension1, version: 'v2'}
+    const action = createUpdateAction({app, extensions: [updated1]})
+
+    const state = extensionServerReducer(previousState, action)
+
+    expect(state).toStrictEqual({
+      app,
+      extensions: [updated1, extension2],
+      store: 'test-store.com',
+    })
+  })
+
+  test('maintains extension order after update', () => {
+    const extension1 = mockExtension()
+    const extension2 = mockExtension()
+    const previousState: ExtensionServerState = {
+      store: 'test-store.com',
+      extensions: [extension1, extension2],
+    }
+
+    const app = mockApp()
+    const updated2 = {...extension2, version: 'v2'}
+    const action = createUpdateAction({app, extensions: [updated2]})
+
+    const state = extensionServerReducer(previousState, action)
+
+    expect(state).toStrictEqual({
+      app,
+      extensions: [extension1, updated2],
+      store: 'test-store.com',
+    })
+  })
+
+  test('refreshes extension url', () => {
+    vi.useFakeTimers()
+    const time1 = 1000
+    vi.setSystemTime(time1)
+
+    const extension = mockExtension()
+    const previousState: ExtensionServerState = {
+      store: 'test-store.com',
+      extensions: [extension],
+    }
+
+    const action = createRefreshAction([{uuid: extension.uuid}])
+
+    const state1 = extensionServerReducer(previousState, action)
+
+    const url1 = new URL(state1.extensions[0].assets.main.url)
+    const timestamp1 = url1.searchParams.get('lastUpdated')
+
+    expect(timestamp1).toBe(time1.toString())
+
+    const time2 = 2000
+    vi.setSystemTime(time2)
+
+    const state2 = extensionServerReducer(state1, action)
+
+    const url2 = new URL(state2.extensions[0].assets.main.url)
+    const timestamp2 = url2.searchParams.get('lastUpdated')
+
+    expect(timestamp2).toBe(time2.toString())
+
+    vi.useRealTimers()
+  })
+
+  describe('focus', () => {
+    test('focuses only one extension', () => {
+      const extension1 = mockExtension()
+      const extension2 = mockExtension()
+
+      const previousState: ExtensionServerState = {
+        store: 'test-store.com',
+        extensions: [extension1, extension2],
+      }
+
+      const action1 = createFocusAction([{uuid: extension1.uuid}])
+      const state1 = extensionServerReducer(previousState, action1)
+
+      expect(state1.extensions[0].development.focused).toBe(true)
+
+      const action2 = createFocusAction([{uuid: extension2.uuid}])
+      const state2 = extensionServerReducer(state1, action2)
+
+      expect(state2.extensions[0].development.focused).toBe(false)
+      expect(state2.extensions[1].development.focused).toBe(true)
+    })
+
+    test('unfocuses extension', () => {
+      const extension = mockExtension({development: {focused: true}})
+
+      const previousState: ExtensionServerState = {
+        store: 'test-store.com',
+        extensions: [extension],
+      }
+
+      const action = createUnfocusAction()
+      const state = extensionServerReducer(previousState, action)
+
+      expect(state.extensions[0].development.focused).toBe(false)
+    })
+  })
+})

package/src/state/reducers/extensionServerReducer.ts

@@ -0,0 +1,87 @@
+import {set, replaceUpdated, assetToString} from '../../utilities'
+import type {ExtensionServerActions} from '../actions'
+import type {ExtensionPayload} from '../../types'
+
+import type {ExtensionServerState} from './types'
+
+export function extensionServerReducer(state: ExtensionServerState, action: ExtensionServerActions) {
+  switch (action.type) {
+    case 'connected': {
+      const extensions = (action.payload.extensions ?? []).map((extension) => {
+        Object.keys(extension.assets).forEach(
+          (asset) => (extension.assets[asset].url = assetToString(extension.assets[asset])),
+        )
+        return extension
+      })
+      return {
+        ...state,
+        store: action.payload.store,
+        app: action.payload.app,
+        extensions,
+      } as ExtensionServerState
+    }
+
+    case 'update': {
+      const extensions = (action.payload.extensions ?? []).map((extension) => {
+        Object.keys(extension.assets).forEach(
+          (asset) => (extension.assets[asset].url = assetToString(extension.assets[asset])),
+        )
+        return extension
+      })
+      return {
+        ...state,
+        app: {...(state.app ?? {}), ...(action.payload.app ?? {})},
+        extensions: replaceUpdated(state.extensions, extensions, ({uuid}) => uuid),
+      } as ExtensionServerState
+    }
+
+    case 'refresh': {
+      return {
+        ...state,
+        extensions: state.extensions.map((extension) => {
+          if (action.payload.some(({uuid}) => extension.uuid === uuid)) {
+            const assets: ExtensionPayload['assets'] = {}
+            Object.keys(extension.assets).forEach((asset) => {
+              const resourceURL = {...extension.assets[asset]}
+              resourceURL.lastUpdated = Date.now()
+              resourceURL.url = assetToString(resourceURL)
+
+              assets[asset] = resourceURL
+            })
+            return set(extension, (ext) => ext.assets, assets)
+          }
+          return extension
+        }),
+      }
+    }
+
+    case 'focus': {
+      return {
+        ...state,
+        extensions: state.extensions.map((extension) => {
+          if (action.payload.some(({uuid}) => extension.uuid === uuid)) {
+            return set(extension, (ext) => ext.development.focused, true)
+          } else if (extension.development.focused) {
+            return set(extension, (ext) => ext.development.focused, false)
+          }
+          return extension
+        }),
+      }
+    }
+
+    case 'unfocus': {
+      return {
+        ...state,
+        extensions: state.extensions.map((extension) => {
+          if (extension.development.focused) {
+            return set(extension, (ext) => ext.development.focused, false)
+          }
+          return extension
+        }),
+      }
+    }
+
+    default:
+      return state
+  }
+}

package/src/state/reducers/index.ts

@@ -0,0 +1,3 @@
+export * from './constants'
+export * from './extensionServerReducer'
+export * from './types'

package/src/state/reducers/types.ts

@@ -0,0 +1,7 @@
+import type {App, ExtensionPayload} from '../../types'
+
+export interface ExtensionServerState {
+  app?: App
+  extensions: ExtensionPayload[]
+  store: string
+}

package/src/testing/MockExtensionServerProvider.tsx

@@ -0,0 +1,36 @@
+import {ExtensionServerProvider, extensionServerContext} from '../context'
+import {useExtensionServerContext} from '../hooks'
+import React, {useMemo} from 'react'
+import type {ExtensionServerProviderProps, ExtensionServerContext} from '../context'
+
+interface InternalProviderProps extends Partial<ExtensionServerContext> {
+  children?: ExtensionServerProviderProps['children']
+}
+
+function InternalProvider({children, ...mocks}: InternalProviderProps) {
+  const actual = useExtensionServerContext()
+
+  const context = useMemo(
+    () => ({
+      ...actual,
+      ...mocks,
+    }),
+    [actual, mocks],
+  )
+
+  return <extensionServerContext.Provider value={context}>{children}</extensionServerContext.Provider>
+}
+
+type MockExtensionServerProviderProps = Partial<ExtensionServerProviderProps> & InternalProviderProps
+
+export function MockExtensionServerProvider({
+  children,
+  options = {connection: {}},
+  ...props
+}: MockExtensionServerProviderProps) {
+  return (
+    <ExtensionServerProvider options={options}>
+      <InternalProvider {...props}>{children}</InternalProvider>
+    </ExtensionServerProvider>
+  )
+}

package/src/testing/app.ts

@@ -0,0 +1,15 @@
+import {App} from '../types'
+
+export function mockApp(): App {
+  return {
+    id: 'id-1',
+    apiKey: '12345',
+    applicationUrl: 'www.applicationUrl.com',
+    title: 'App title',
+    url: 'mock url',
+    mobileUrl: 'mock mobile url',
+    icon: {
+      transformedSrc: 'www.transformed-src.com',
+    },
+  }
+}

package/src/testing/extensions.ts

@@ -0,0 +1,71 @@
+import {ExtensionPayload, Status} from '../types'
+
+type DeepPartial<T> = {
+  [P in keyof T]?: DeepPartial<T[P]>
+}
+
+let id = 0
+
+function pad(num: number) {
+  return `00000000000${num}`.slice(-12)
+}
+
+export function mockExtension(obj: DeepPartial<ExtensionPayload> = {}): ExtensionPayload {
+  const uuid = `00000000-0000-0000-0000-${pad(id++)}`
+  const lastUpdated = Date.now()
+  return {
+    handle: 'my-extension',
+    name: 'My extension',
+    description: 'My extension description',
+    surface: 'admin',
+    type: 'purchase_option',
+    externalType: 'external_type',
+    uuid,
+    version: 'extension version',
+    ...obj,
+    assets: {
+      main: {
+        name: 'main',
+        url: `https://secure-link.com/extensions/${uuid}/assets/handle.js?lastUpdated=${lastUpdated}`,
+        lastUpdated,
+      },
+      ...((obj.assets ?? {}) as any),
+    },
+    development: {
+      hidden: false,
+      status: Status.Success,
+      resource: {
+        url: 'resourceUrl',
+      },
+      root: {
+        url: `https://secure-link.com/extensions/${uuid}`,
+      },
+      renderer: {
+        name: 'render name',
+        version: '1.0.0',
+      },
+      ...((obj.development ?? {}) as any),
+    },
+    // this is due to the naive DeepPartial but also more complex ones
+    // [see stackoverflow](https://stackoverflow.com/a/68699273) assume that
+    // `DeepPartial<Array<T>> === Array<T | undefined>` while we are looking for
+    // `DeepPartial<Array<T>> === Array<T> | undefined`.
+    // This is the case for extension points and seems hard to fix
+    // in a generalized, non-surprising way
+    extensionPoints: obj.extensionPoints as any,
+    capabilities: obj.capabilities as any,
+    supportedFeatures: obj.supportedFeatures as any,
+    localization: obj.localization as any,
+    authenticatedRedirectStartUrl: obj.authenticatedRedirectStartUrl as any,
+    authenticatedRedirectRedirectUrls: obj.authenticatedRedirectRedirectUrls as any,
+    settings: {
+      fields: [
+        {
+          key: 'sample-key',
+          name: 'sample_name',
+          type: 'sample_type',
+        },
+      ],
+    },
+  }
+}

package/src/testing/index.ts

@@ -0,0 +1,3 @@
+export * from './MockExtensionServerProvider'
+export * from './app'
+export * from './extensions'

package/src/types.ts

@@ -0,0 +1,204 @@
+import {FlattenedLocalization, Localization} from './i18n'
+import './ExtensionServerClient/types'
+import type {Surface} from './ExtensionServerClient/types'
+
+declare global {
+  namespace ExtensionServer {
+    type ServerEvents =
+      | {
+          event: 'dispatch'
+          data: InboundEvents['dispatch']
+        }
+      | {
+          event: 'connected'
+          data: InboundEvents['connected']
+        }
+      | {
+          event: 'update'
+          data: InboundEvents['update']
+        }
+
+    interface InboundEvents extends DispatchEvents {
+      dispatch: {type: keyof DispatchEvents; payload: DispatchEvents[keyof DispatchEvents]}
+      connected: {extensions: ExtensionPayload[]; app?: App; store: string}
+      update: {extensions?: ExtensionPayload[]; app?: App}
+    }
+
+    interface OutboundPersistEvents {
+      update: {
+        extensions?: ({uuid: string} & DeepPartial<ExtensionPayload>)[]
+        app?: DeepPartial<App>
+      }
+    }
+
+    interface DispatchEvents {
+      refresh: {uuid: string}[]
+      focus: {uuid: string}[]
+      unfocus: void
+      navigate: {url: string}
+    }
+
+    // API responses
+    namespace API {
+      interface BaseResponse {
+        app: App
+        root: ResourceURL
+        socket: ResourceURL
+        devConsole: ResourceURL
+        store: string
+        version: string
+      }
+
+      interface ExtensionsResponse extends BaseResponse {
+        extensions: ExtensionPayload[]
+      }
+
+      interface ExtensionResponse extends BaseResponse {
+        extension: ExtensionPayload
+      }
+    }
+
+    interface UIExtension extends ExtensionPayload {
+      extensionPoints: ExtensionPoint[]
+      apiVersion: string
+    }
+  }
+}
+
+export type DeepPartial<T> = {
+  [P in keyof T]?: DeepPartial<T[P]>
+}
+
+interface ResourceURL {
+  url: string
+}
+
+export interface Asset extends ResourceURL {
+  name: string
+  lastUpdated: number
+}
+
+interface Metafield {
+  namespace: string
+  key: string
+}
+
+export interface ExtensionPointIntercept {
+  event: string
+  blocking: boolean
+  applies_to?: string[]
+}
+
+export interface ExtensionPointCapabilities {
+  allow_direct_linking?: boolean
+  intercepts?: ExtensionPointIntercept[]
+}
+
+export interface ExtensionPoint {
+  target: string
+  surface: Surface
+  metafields?: Metafield[]
+  resource: ResourceURL
+  root: ResourceURL
+  localization?: FlattenedLocalization | Localization | null
+  name: string
+  description?: string
+  assets?: Record<string, Asset>
+  capabilities?: ExtensionPointCapabilities
+}
+
+type ExtensionPoints = string[] | ExtensionPoint[] | null
+
+interface CollectBuyerConsentCapabilities {
+  smsMarketing: boolean
+  customerPrivacy: boolean
+}
+
+interface IframeCapabilities {
+  sources: string[]
+}
+
+interface Capabilities {
+  apiAccess: boolean
+  blockProgress: boolean
+  networkAccess: boolean
+  collectBuyerConsent: CollectBuyerConsentCapabilities
+  iframe: IframeCapabilities
+}
+
+export interface ExtensionPayload {
+  type: string
+  externalType: string
+  assets: Record<string, Asset>
+  development: {
+    hidden: boolean
+    status: Status
+    focused?: boolean
+    resource: ResourceURL
+    root: ResourceURL
+    renderer: {
+      name: string
+      version: string
+    }
+    error?: {
+      message: string
+      file?: string
+    }
+  }
+  uuid: string
+  version: string
+  surface: Surface
+  name: string
+  description?: string
+  handle: string
+  extensionPoints: ExtensionPoints
+  capabilities?: Capabilities
+  supportedFeatures: ExtensionSupportedFeatures
+  authenticatedRedirectStartUrl?: string
+  authenticatedRedirectRedirectUrls?: string[]
+  localization?: FlattenedLocalization | Localization | null
+  settings?: {
+    fields?: {
+      type: string
+      key?: string
+      name?: string
+      description?: string
+      required?: boolean
+      validations?: unknown[]
+    }[]
+  }
+}
+
+export interface ExtensionSupportedFeatures {
+  runsOffline: boolean
+}
+
+export enum Status {
+  Success = 'success',
+}
+
+export interface App {
+  id: string
+  apiKey: string
+  url: string
+  mobileUrl: string
+  applicationUrl: string
+  handle?: string | null
+  title: string
+  developerName?: string
+  icon: {
+    transformedSrc: string
+  }
+  installation?: {
+    launchUrl: string
+  }
+  supportEmail?: string
+  supportLocales?: string[]
+  allowedDomains?: string[]
+  assets?: {
+    [key: string]: {
+      url: string
+      lastUpdated: number
+    }
+  }
+}

package/src/utilities/assetToString.test.ts

@@ -0,0 +1,16 @@
+import {assetToString} from './assetToString'
+import type {Asset} from '../types'
+
+describe('assetToString tests', () => {
+  test('creates a URL string from an asset', () => {
+    const asset: Asset = {
+      name: 'main',
+      url: 'http://localhost:8000/extensions/00000000/assets/handle.js',
+      lastUpdated: 1637004124,
+    }
+
+    const url = assetToString(asset)
+
+    expect(url).toBe(`${asset.url}?lastUpdated=${asset.lastUpdated}`)
+  })
+})

package/src/utilities/assetToString.ts

@@ -0,0 +1,7 @@
+import type {Asset} from '../types'
+
+export function assetToString(asset: Asset) {
+  const url = new URL(asset.url)
+  url.searchParams.set('lastUpdated', String(asset.lastUpdated))
+  return url.toString()
+}

package/src/utilities/index.ts

@@ -0,0 +1,6 @@
+export * from './noop'
+export * from './replaceUpdated'
+export * from './set'
+export * from './assetToString'
+export * from './isValidSurface'
+export * from './isUIExtension'

package/src/utilities/isUIExtension.ts

@@ -0,0 +1,8 @@
+export function isUIExtension(extension: unknown): extension is ExtensionServer.UIExtension {
+  const ext = extension as ExtensionServer.UIExtension
+  return (
+    ext.type === 'ui_extension' &&
+    Array.isArray(ext.extensionPoints) &&
+    ext.extensionPoints.every((extensionPoint: unknown) => typeof extensionPoint === 'object')
+  )
+}

package/src/utilities/isValidSurface.ts

@@ -0,0 +1,6 @@
+import {AVAILABLE_SURFACES} from '../ExtensionServerClient/types'
+import type {Surface} from '../ExtensionServerClient/types'
+
+export function isValidSurface(surface: unknown): surface is Surface {
+  return Boolean(surface) && AVAILABLE_SURFACES.includes(surface as Surface)
+}

package/src/utilities/noop.ts

@@ -0,0 +1 @@
+export const noop = () => {}

package/src/utilities/replaceUpdated.test.ts

@@ -0,0 +1,26 @@
+/* eslint-disable id-length */
+import {replaceUpdated} from './replaceUpdated'
+
+describe('replaceUpdated', () => {
+  test('replaces updated items in place, and appends new items', () => {
+    const arr = [
+      {id: 1, a: 'a'},
+      {id: 2, a: 'b'},
+      {id: 3, a: 'c'},
+      {id: 4, a: 'd'},
+    ]
+
+    const updates = [
+      {id: 2, a: 'updated'},
+      {id: 5, a: 'e'},
+    ]
+
+    expect(replaceUpdated(arr, updates, ({id}) => id)).toStrictEqual([
+      {id: 1, a: 'a'},
+      {id: 2, a: 'updated'},
+      {id: 3, a: 'c'},
+      {id: 4, a: 'd'},
+      {id: 5, a: 'e'},
+    ])
+  })
+})

package/src/utilities/replaceUpdated.ts

@@ -0,0 +1,15 @@
+export function replaceUpdated<T>(arr: T[], updates: T[], cb: (v: T) => unknown): T[] {
+  const updatesMap = new Map(updates.map((updated) => [cb(updated), updated]))
+  const updated = arr.map((item) => {
+    const key = cb(item)
+    if (updatesMap.has(key)) {
+      const updated = updatesMap.get(key)!
+      updatesMap.delete(key)
+      return updated
+    } else {
+      return item
+    }
+  })
+
+  return [...updated, ...updatesMap.values()]
+}