@shopify/ui-extensions-server-kit 0.0.0-nightly-20250605112924

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from './context'
+export * from './ExtensionServerClient'
+export * from './hooks'
+export * from './state'
+export * from './types'
+export * from './utilities'
+export * from './i18n'

package/src/state/actions/actions.ts

@@ -0,0 +1,43 @@
+import type {ConnectedAction, UpdateAction, RefreshAction, FocusAction, UnfocusAction, LogAction} from './types'
+
+export function createConnectedAction(payload: ConnectedAction['payload']): ConnectedAction {
+  return {
+    type: 'connected',
+    payload,
+  }
+}
+
+export function createUpdateAction(payload: UpdateAction['payload']): UpdateAction {
+  return {
+    type: 'update',
+    payload,
+  }
+}
+
+export function createRefreshAction(payload: RefreshAction['payload']): RefreshAction {
+  return {
+    type: 'refresh',
+    payload,
+  }
+}
+
+export function createFocusAction(payload: FocusAction['payload']): FocusAction {
+  return {
+    type: 'focus',
+    payload,
+  }
+}
+
+export function createUnfocusAction(payload: UnfocusAction['payload']): UnfocusAction {
+  return {
+    type: 'unfocus',
+    payload,
+  }
+}
+
+export function createLogAction(payload: LogAction['payload']): LogAction {
+  return {
+    type: 'log',
+    payload,
+  }
+}

package/src/state/actions/index.ts

@@ -0,0 +1,2 @@
+export * from './actions'
+export * from './types'

package/src/state/actions/types.ts

@@ -0,0 +1,37 @@
+export interface ConnectedAction {
+  type: 'connected'
+  payload: ExtensionServer.InboundEvents['connected']
+}
+
+export interface UpdateAction {
+  type: 'update'
+  payload: ExtensionServer.InboundEvents['update']
+}
+
+export interface RefreshAction {
+  type: 'refresh'
+  payload: ExtensionServer.InboundEvents['refresh']
+}
+
+export interface FocusAction {
+  type: 'focus'
+  payload: ExtensionServer.InboundEvents['focus']
+}
+
+export interface UnfocusAction {
+  type: 'unfocus'
+  payload: ExtensionServer.InboundEvents['unfocus']
+}
+
+export interface LogAction {
+  type: 'log'
+  payload: ExtensionServer.InboundEvents['log']
+}
+
+export type ExtensionServerActions =
+  | ConnectedAction
+  | UpdateAction
+  | RefreshAction
+  | FocusAction
+  | UnfocusAction
+  | LogAction

package/src/state/index.ts

@@ -0,0 +1,2 @@
+export * from './actions'
+export * from './reducers'

package/src/state/reducers/constants.ts

@@ -0,0 +1,6 @@
+import type {ExtensionServerState} from './types'
+
+export const INITIAL_STATE: ExtensionServerState = {
+  extensions: [],
+  store: '',
+}

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

@@ -0,0 +1,174 @@
+import {extensionServerReducer} from './extensionServerReducer'
+import {INITIAL_STATE} from './constants'
+import {mockExtension, mockApp} from '../../testing'
+import {
+  createConnectedAction,
+  createUpdateAction,
+  createRefreshAction,
+  createFocusAction,
+  createUnfocusAction,
+  createLogAction,
+} from '../actions'
+
+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',
+    })
+  })
+
+  // eslint-disable-next-line vitest/no-disabled-tests
+  test.skip('refreshes extension url', async () => {
+    const extension = mockExtension()
+    const previousState: ExtensionServerState = {
+      store: 'test-store.com',
+      extensions: [extension],
+    }
+
+    const action = createRefreshAction([{uuid: extension.uuid}])
+
+    const state1 = extensionServerReducer(previousState, action)
+    // eslint-disable-next-line node/no-unsupported-features/node-builtins
+    const url1 = new URL(state1.extensions[0].assets.main.url)
+    const timestamp1 = url1.searchParams.get('lastUpdated') ?? ''
+
+    expect(timestamp1.length).toBeGreaterThan(0)
+
+    // sleep 1ms to guarantee new timestamp
+    await new Promise((resolve) => setTimeout(resolve, 1))
+
+    const state2 = extensionServerReducer(state1, action)
+    // eslint-disable-next-line node/no-unsupported-features/node-builtins
+    const url2 = new URL(state2.extensions[0].assets.main.url)
+    const timestamp2 = url2.searchParams.get('lastUpdated') ?? ''
+
+    expect(timestamp2.length).toBeGreaterThan(0)
+    expect(timestamp1).not.toStrictEqual(timestamp2)
+  })
+
+  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)
+    })
+  })
+
+  test('does not mutate the state when receiving log events', () => {
+    const extension = mockExtension()
+    const previousState: ExtensionServerState = {
+      store: 'test-store.com',
+      extensions: [extension],
+    }
+
+    const action = createLogAction({level: 'info', args: ['test'], extensionName: extension.name})
+    const state = extensionServerReducer(previousState, action)
+
+    expect(state).toStrictEqual(previousState)
+  })
+})

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,70 @@
+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,
+    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,180 @@
+/* eslint-disable @typescript-eslint/no-invalid-void-type */
+/* eslint-disable @shopify/strict-component-boundaries */
+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}
+      log: {level: string; args: unknown[]; extensionName: 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]>
+}
+
+export interface ResourceURL {
+  url: string
+}
+
+export interface Asset extends ResourceURL {
+  name: string
+  lastUpdated: number
+}
+
+export interface Metafield {
+  namespace: string
+  key: string
+}
+
+export interface ExtensionPoint {
+  target: string
+  surface: Surface
+  metafields?: Metafield[]
+  resource: ResourceURL
+  root: ResourceURL
+  localization?: FlattenedLocalization | Localization | null
+  name: string
+  description?: string
+  assets?: {[name: string]: Asset}
+}
+
+export 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: {[name: string]: Asset}
+  development: {
+    hidden: boolean
+    status: Status
+    focused?: boolean
+    resource: ResourceURL
+    root: ResourceURL
+    renderer: {
+      name: string
+      version: string
+    }
+  }
+  uuid: string
+  version: string
+  surface: Surface
+  name: string
+  description?: string
+  handle: string
+  extensionPoints: ExtensionPoints
+  capabilities?: Capabilities
+  authenticatedRedirectStartUrl?: string
+  authenticatedRedirectRedirectUrls?: string[]
+  localization?: FlattenedLocalization | Localization | null
+  settings?: {
+    fields?: {
+      type: string
+      key?: string
+      name?: string
+      description?: string
+      required?: boolean
+      validations?: any[]
+    }[]
+  }
+}
+
+export enum Status {
+  Error = 'error',
+  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[]
+}