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

package/src/ExtensionServerClient/ExtensionServerClient.ts

@@ -0,0 +1,311 @@
+/* eslint-disable @typescript-eslint/no-dynamic-delete */
+/* eslint-disable no-console */
+import {Surface} from './types.js'
+import {
+  FlattenedLocalization,
+  Localization,
+  TRANSLATED_KEYS,
+  getFlattenedLocalization,
+  isFlattenedTranslations,
+} from '../i18n'
+import {isUIExtension, isValidSurface} from '../utilities'
+import {DeepPartial, ExtensionPayload, ExtensionPoint} from '../types'
+
+export class ExtensionServerClient implements ExtensionServer.Client {
+  public id: string
+
+  public connection!: WebSocket
+
+  public options: ExtensionServer.Options
+
+  protected EVENT_THAT_WILL_MUTATE_THE_SERVER = ['update']
+
+  protected listeners: {[key: string]: Set<any>} = {}
+  protected connectionListeners: {close: Set<any>; open: Set<any>} = {close: new Set(), open: new Set()}
+
+  protected connected = false
+
+  private uiExtensionsByUuid: {[key: string]: ExtensionServer.UIExtension} = {}
+
+  constructor(options: DeepPartial<ExtensionServer.Options> = {}) {
+    this.id = (Math.random() + 1).toString(36).substring(7)
+    this.options = getValidatedOptions({
+      ...options,
+      connection: {
+        automaticConnect: true,
+        protocols: [],
+        ...(options.connection ?? {}),
+      },
+    }) as ExtensionServer.Options
+
+    this.setupConnection(this.options.connection.automaticConnect)
+  }
+
+  public connect(options: ExtensionServer.Options = {connection: {}}) {
+    const newOptions = mergeOptions(this.options, options)
+    const optionsChanged = JSON.stringify(newOptions) !== JSON.stringify(this.options)
+
+    if (optionsChanged) {
+      this.options = newOptions
+      this.setupConnection(true)
+    }
+
+    return () => {
+      this.closeConnection()
+    }
+  }
+
+  public on<TEvent extends keyof ExtensionServer.InboundEvents>(
+    event: TEvent,
+    listener: (payload: ExtensionServer.InboundEvents[TEvent]) => void,
+  ): () => void {
+    if (!this.listeners[event]) {
+      this.listeners[event] = new Set()
+    }
+
+    this.listeners[event].add(listener)
+    return () => this.listeners[event].delete(listener)
+  }
+
+  public persist<TEvent extends keyof ExtensionServer.OutboundPersistEvents>(
+    event: TEvent,
+    data: ExtensionServer.OutboundPersistEvents[TEvent],
+  ): void {
+    if (this.EVENT_THAT_WILL_MUTATE_THE_SERVER.includes(event)) {
+      if (!this.options.locales) {
+        return this.connection?.send(JSON.stringify({event, data}))
+      }
+
+      /**
+       * Since each websocket connection will have its own translated values
+       * we need to strip out all translated properties to prevent
+       * mutating the Dev Server's data
+       * Before:
+       * ```
+       * {
+       *  name: 'en name'
+       *  localization: {...},
+       *  extensionPoints: [{
+       *    target: 'admin.product.item.action'
+       *    name: 'en name'
+       *    description: 'en description'
+       *    localization: {...}
+       *  }],
+       * }
+       * ```
+       * After:
+       * ```
+       *  extensionPoints: [{
+       *    target: 'admin.product.item.action'
+       *  }],
+       * }
+       * ```
+       */
+      data.extensions?.forEach((extension) => {
+        TRANSLATED_KEYS.forEach((key) => {
+          if (isUIExtension(extension)) {
+            extension.extensionPoints?.forEach((extensionPoint) => {
+              delete extensionPoint[key as keyof ExtensionPoint]
+            })
+          }
+          delete extension[key as keyof ExtensionPayload]
+        })
+      })
+      return this.connection?.send(JSON.stringify({event, data}))
+    }
+
+    console.warn(`You tried to use "persist" with a dispatch event. Please use the "emit" method instead.`)
+  }
+
+  public emit<TEvent extends keyof ExtensionServer.DispatchEvents>(...args: ExtensionServer.EmitArgs<TEvent>): void {
+    const [event, data] = args
+
+    if (this.EVENT_THAT_WILL_MUTATE_THE_SERVER.includes(event)) {
+      return console.warn(
+        `You tried to use "emit" with a the "${event}" event. Please use the "persist" method instead to persist changes to the server.`,
+      )
+    }
+
+    this.connection?.send(JSON.stringify({event: 'dispatch', data: {type: event, payload: data}}))
+  }
+
+  public onConnection<TEvent extends keyof typeof this.connectionListeners>(
+    event: TEvent,
+    listener: (event: Event) => void,
+  ): () => void {
+    this.connectionListeners[event].add(listener)
+    return () => this.connectionListeners[event].delete(listener)
+  }
+
+  protected initializeConnection() {
+    if (!this.connection) {
+      return
+    }
+
+    this.connection.addEventListener('open', (event) => {
+      this.connected = true
+      this.connectionListeners.open.forEach((listener) => listener(event))
+    })
+
+    this.connection.addEventListener('close', (event) => {
+      this.connected = false
+      this.connectionListeners.close.forEach((listener) => listener(event))
+    })
+
+    this.connection?.addEventListener('message', (message) => {
+      try {
+        const {event, data} = JSON.parse(message.data) as ExtensionServer.ServerEvents
+
+        if (event === 'dispatch') {
+          const {type, payload} = data
+          this.listeners[type]?.forEach((listener) => listener(payload))
+          return
+        }
+
+        const filteredExtensions = data.extensions
+          ? filterExtensionsBySurface(data.extensions, this.options.surface)
+          : data.extensions
+
+        this.listeners[event]?.forEach((listener) => {
+          listener({...data, extensions: this._getLocalizedExtensions(filteredExtensions)})
+        })
+        // eslint-disable-next-line no-catch-all/no-catch-all
+      } catch (err) {
+        console.error(
+          `[ExtensionServer] Something went wrong while parsing a server message:`,
+          err instanceof Error ? err.message : err,
+        )
+      }
+    })
+  }
+
+  protected setupConnection(connectWebsocket = true) {
+    if (!this.options.connection.url) {
+      return
+    }
+
+    if (!connectWebsocket) {
+      return
+    }
+
+    this.closeConnection()
+
+    this.connection = new WebSocket(this.options.connection.url, this.options.connection.protocols)
+
+    this.initializeConnection()
+  }
+
+  protected closeConnection() {
+    if (this.connected) {
+      this.connection?.close()
+    }
+  }
+
+  private _getLocalizedExtensions(extensions?: ExtensionPayload[]) {
+    return extensions?.map((extension) => {
+      if (!this.options.locales || !isUIExtension(extension)) {
+        return extension
+      }
+
+      const shouldUpdateTranslations =
+        this.uiExtensionsByUuid[extension.uuid]?.localization?.lastUpdated !== extension.localization?.lastUpdated
+
+      const localization = shouldUpdateTranslations
+        ? getFlattenedLocalization(extension.localization, this.options.locales)
+        : this.uiExtensionsByUuid[extension.uuid]?.localization ?? extension.localization
+
+      const parsedTranslation: {[key: string]: string} =
+        localization && isFlattenedTranslations(localization) ? JSON.parse(localization.translations) : localization
+
+      const localizedExtension = {
+        ...extension,
+        localization,
+        name:
+          parsedTranslation && extension.name.startsWith('t:')
+            ? this._getLocalizedValue(parsedTranslation, extension.name)
+            : extension.name,
+        ...(extension.description && {
+          description:
+            parsedTranslation && extension.description?.startsWith('t:')
+              ? this._getLocalizedValue(parsedTranslation, extension.description)
+              : extension.description,
+        }),
+      }
+
+      this.uiExtensionsByUuid[extension.uuid] = {
+        ...localizedExtension,
+        extensionPoints: this._getLocalizedExtensionPoints(localization, localizedExtension),
+      }
+
+      return this.uiExtensionsByUuid[extension.uuid]
+    })
+  }
+
+  private _getLocalizedExtensionPoints(
+    localization: FlattenedLocalization | Localization | null | undefined,
+    {extensionPoints, name, description}: ExtensionServer.UIExtension,
+  ): ExtensionPoint[] {
+    if (!localization || !isFlattenedTranslations(localization)) {
+      return extensionPoints
+    }
+
+    return extensionPoints?.map((extensionPoint) => {
+      return {
+        ...extensionPoint,
+        localization,
+        name,
+        ...(description && {description}),
+      }
+    })
+  }
+
+  private _getLocalizedValue(translations: {[x: string]: string}, value: string): string {
+    const translationKey = value.replace('t:', '')
+    return translations[translationKey] || value
+  }
+}
+
+function mergeOptions(options: ExtensionServer.Options, newOptions: ExtensionServer.Options) {
+  return getValidatedOptions({
+    ...options,
+    ...newOptions,
+    connection: {
+      ...options.connection,
+      ...newOptions.connection,
+    },
+  })
+}
+
+function getValidatedOptions<TOptions extends DeepPartial<ExtensionServer.Options>>(options: TOptions): TOptions {
+  if (!isValidSurface(options.surface)) {
+    delete options.surface
+  }
+  return options
+}
+
+function filterExtensionsBySurface(extensions: ExtensionPayload[], surface: Surface | undefined): ExtensionPayload[] {
+  if (!surface) {
+    return extensions
+  }
+
+  return extensions.filter((extension) => {
+    if (extension.surface === surface) {
+      return true
+    }
+
+    if (Array.isArray(extension.extensionPoints)) {
+      const extensionPoints: (string | {surface: Surface; [key: string]: any})[] = extension.extensionPoints
+      const extensionPointMatchingSurface = extensionPoints.filter((extensionPoint) => {
+        if (typeof extensionPoint === 'string') {
+          return false
+        }
+
+        return extensionPoint.surface === surface
+      })
+
+      return extensionPointMatchingSurface.length > 0
+    }
+
+    return false
+  })
+}

package/src/ExtensionServerClient/index.ts

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

package/src/ExtensionServerClient/types.ts

@@ -0,0 +1,161 @@
+/* eslint-disable @typescript-eslint/no-invalid-void-type */
+/* eslint-disable @typescript-eslint/no-empty-interface */
+import type {LocalesOptions} from '../i18n'
+
+declare global {
+  namespace ExtensionServer {
+    /**
+     * Events being received by the extension server where the keys are the event names
+     * and the values are the payload of the given action. In case no payload is
+     * required, a value of void should be used.
+     */
+    interface InboundEvents {
+      //
+    }
+
+    /**
+     * Events being sent to the extension server where the keys are the event names
+     * and the values are the payload of the given action. In case no payload is
+     * required, a value of void should be used.
+     *
+     * Persist events are those that will generate changes on the server, like
+     * update and connected events. Dispatch events are those that will
+     * simply be proxied to the clients connected to the server.
+     */
+    interface OutboundPersistEvents {
+      //
+    }
+
+    interface DispatchEvents {
+      //
+    }
+
+    /**
+     * Extension server client class options. These are used to configure
+     * the client class.
+     */
+    interface Options {
+      connection: {
+        /**
+         * The absolute URL of the WebSocket.
+         */
+        url?: string
+
+        /**
+         * This defines if we should automatically attempt to connect when the
+         * class is instantiated.
+         *
+         * @defaultValue true
+         */
+        automaticConnect?: boolean
+
+        /**
+         * The sub-protocol selected by the server.
+         *
+         * @defaultValue []
+         */
+        protocols?: string | string[]
+      }
+      /**
+       * If provided the extension server will only return extensions that matches the specified surface
+       */
+      surface?: Surface
+
+      /**
+       * If provided the extension server will return a requested translations object with flattened
+       * translations for each extension matching the requested locales
+       */
+      locales?: LocalesOptions
+    }
+
+    /**
+     * Extension server client class. This class will be used to connect and
+     * communicate with the extension server.
+     */
+    interface Client {
+      /**
+       * Connection options
+       */
+      options: Options
+
+      /**
+       * Reconnecting WebSocket Client
+       */
+      connection: WebSocket
+
+      /**
+       * Function to add an event listener to messages coming from
+       * the extension server connection.
+       */
+      on<TEvent extends keyof ExtensionServer.InboundEvents>(
+        event: TEvent,
+        cb: EventListener<TEvent>,
+      ): EventUnsubscriber
+
+      /**
+       * Function to emit an event that will persist changes to the extension server.
+       */
+      persist<TEvent extends keyof OutboundPersistEvents>(event: TEvent, payload: OutboundPersistEvents[TEvent]): void
+
+      /**
+       * Function to emit an event to the extension server.
+       */
+      emit<TEvent extends keyof DispatchEvents>(...args: EmitArgs<TEvent>): void
+
+      /**
+       * Function that opens a connection with the extensions server.
+       */
+      connect(options?: Options): () => void
+    }
+
+    /**
+     * This defines how the ExtensionServer client's static class is defined and the constructor
+     * arguments it requires.
+     *
+     * @example
+     * ```
+     * const client = new ExtensionServer({ url: 'wss://localhost:1234' });
+     * ```
+     */
+    type StaticClient = Static<ExtensionServer.Client, [option?: ExtensionServer.Options]>
+
+    // Utilities
+
+    /**
+     * This helper type allows us to account for nullish payloads on the emit function.
+     * In practice, this will allow TypeScript to type-check the event being emitted
+     * and, if the payload isn't required, the second argument won't be necessary.
+     */
+    type EmitArgs<TEvent extends keyof ExtensionServer.DispatchEvents> =
+      ExtensionServer.DispatchEvents[TEvent] extends void
+        ? [event: TEvent]
+        : [event: TEvent, payload: ExtensionServer.DispatchEvents[TEvent]]
+
+    /**
+     * This is a helper interface that allows us to define the static methods of a given
+     * class. This is useful to define static methods, static properties
+     * and constructor variables.
+     */
+    interface Static<T = unknown, TArgs extends unknown[] = unknown[]> {
+      prototype: T
+      new (...args: TArgs): T
+    }
+
+    /**
+     * This helper creates a partial interface with exception to the defined key values.
+     */
+    type PartialExcept<TOject, TKey extends keyof TOject> = Partial<Omit<TOject, TKey>> & Pick<TOject, TKey>
+
+    type EventListener<TEvent extends keyof ExtensionServer.InboundEvents> = (
+      payload: ExtensionServer.InboundEvents[TEvent],
+    ) => void
+
+    type EventUnsubscriber = () => void
+  }
+}
+
+export const AVAILABLE_SURFACES = ['admin', 'checkout', 'post_purchase', 'point_of_sale', 'customer-accounts'] as const
+
+export type Surface = (typeof AVAILABLE_SURFACES)[number]
+
+export {}

package/src/context/ExtensionServerProvider.test.tsx

@@ -0,0 +1,173 @@
+import {ExtensionServerProvider} from './ExtensionServerProvider'
+import {mockApp, mockExtension} from '../testing'
+import {useExtensionServerContext} from '../hooks'
+import {createConnectedAction} from '../state'
+import WS from 'jest-websocket-mock'
+import {renderHook, withProviders} from '@shopify/ui-extensions-test-utils'
+
+describe('ExtensionServerProvider tests', () => {
+  describe('client tests', () => {
+    test('creates a new ExtensionServerClient instance', async () => {
+      const options = {connection: {url: 'ws://example-host.com:8000/extensions/'}}
+
+      const wrapper = renderHook(useExtensionServerContext, withProviders(ExtensionServerProvider), {options})
+
+      expect(wrapper.result.client).toBeDefined()
+    })
+
+    test('does not start a new connection if an empty url is passed', async () => {
+      const options = {connection: {}}
+
+      const wrapper = renderHook(useExtensionServerContext, withProviders(ExtensionServerProvider), {options})
+
+      expect(wrapper.result.client.connection).toBeUndefined()
+    })
+  })
+
+  describe('connect tests', () => {
+    test('starts a new connection by calling connect', async () => {
+      const options = {connection: {url: 'ws://example-host.com:8000/extensions/'}}
+      const socket = new WS(options.connection.url, {jsonProtocol: true})
+      const wrapper = renderHook(useExtensionServerContext, withProviders(ExtensionServerProvider), {
+        options: {
+          connection: {url: ''},
+        },
+      })
+
+      expect(socket.server.clients()).toHaveLength(0)
+
+      wrapper.act(({connect}) => connect(options))
+
+      expect(wrapper.result.client.connection).toBeDefined()
+      expect(socket.server.clients()).toHaveLength(1)
+      socket.close()
+    })
+  })
+
+  describe('dispatch tests', () => {
+    test('updates the state', async () => {
+      const options = {connection: {url: 'ws://example-host.com:8000/extensions/'}}
+      const app = mockApp()
+      const extension = mockExtension()
+      const payload = {app, extensions: [extension], store: 'test-store.com'}
+      const wrapper = renderHook(useExtensionServerContext, withProviders(ExtensionServerProvider), {options})
+
+      wrapper.act(({dispatch}) => {
+        dispatch({type: 'connected', payload})
+      })
+
+      expect(wrapper.result.state).toStrictEqual({
+        app,
+        extensions: [extension],
+        store: 'test-store.com',
+      })
+    })
+  })
+
+  describe('state tests', () => {
+    let socket: WS
+    const options = {connection: {url: 'ws://example-host.com:8000/extensions/'}}
+
+    beforeEach(() => {
+      socket = new WS(options.connection.url, {jsonProtocol: true})
+    })
+
+    afterEach(() => {
+      socket.close()
+    })
+
+    test('persists connection data to the state', async () => {
+      const app = mockApp()
+      const extension = mockExtension()
+      const data = {app, store: 'test-store.com', extensions: [extension]}
+      const wrapper = renderHook(useExtensionServerContext, withProviders(ExtensionServerProvider), {options})
+
+      wrapper.act(() => socket.send({event: 'connected', data}))
+
+      expect(wrapper.result.state).toEqual({
+        app,
+        extensions: [extension],
+        store: 'test-store.com',
+      })
+    })
+
+    test('persists update data to the state', async () => {
+      const app = mockApp()
+      const extension = mockExtension()
+      const update = {...extension, version: 'v2'}
+      const data = {app, store: 'test-store.com', extensions: [extension]}
+      const wrapper = renderHook(useExtensionServerContext, withProviders(ExtensionServerProvider), {options})
+
+      wrapper.act(({dispatch}) => {
+        dispatch(createConnectedAction(data))
+
+        socket.send({event: 'update', data: {...data, extensions: [update]}})
+      })
+
+      expect(wrapper.result.state).toEqual({
+        app,
+        extensions: [update],
+        store: 'test-store.com',
+      })
+    })
+
+    // eslint-disable-next-line vitest/no-disabled-tests
+    test.skip('persists refresh data to the state', async () => {
+      const app = mockApp()
+      const extension = mockExtension()
+      const data = {app, store: 'test-store.com', extensions: [extension]}
+      const wrapper = renderHook(useExtensionServerContext, withProviders(ExtensionServerProvider), {options})
+
+      wrapper.act(({dispatch}) => {
+        dispatch(createConnectedAction(data))
+
+        socket.send({
+          event: 'dispatch',
+          data: {type: 'refresh', payload: [{uuid: extension.uuid}]},
+        })
+      })
+
+      const [updatedExtension] = wrapper.result.state.extensions
+      expect(updatedExtension.assets.main.url).not.toEqual(extension.assets.main.url)
+    })
+
+    test('persists focus data to the state', async () => {
+      const app = mockApp()
+      const extension = mockExtension()
+      const data = {app, store: 'test-store.com', extensions: [extension]}
+      const wrapper = renderHook(useExtensionServerContext, withProviders(ExtensionServerProvider), {options})
+
+      wrapper.act(({dispatch}) => {
+        dispatch(createConnectedAction(data))
+
+        socket.send({
+          event: 'dispatch',
+          data: {type: 'focus', payload: [{uuid: extension.uuid}]},
+        })
+      })
+
+      const [updatedExtension] = wrapper.result.state.extensions
+      expect(updatedExtension.development.focused).toBe(true)
+    })
+
+    test('persists unfocus data to the state', async () => {
+      const app = mockApp()
+      const extension = mockExtension()
+      extension.development.focused = true
+      const data = {app, store: 'test-store.com', extensions: [extension]}
+      const wrapper = renderHook(useExtensionServerContext, withProviders(ExtensionServerProvider), {options})
+
+      wrapper.act(({dispatch}) => {
+        dispatch(createConnectedAction(data))
+
+        socket.send({
+          event: 'dispatch',
+          data: {type: 'unfocus'},
+        })
+      })
+
+      const [updatedExtension] = wrapper.result.state.extensions
+      expect(updatedExtension.development.focused).toBe(false)
+    })
+  })
+})

package/src/context/ExtensionServerProvider.tsx

@@ -0,0 +1,48 @@
+import {extensionServerContext} from './constants'
+import {
+  createConnectedAction,
+  createUpdateAction,
+  createRefreshAction,
+  createFocusAction,
+  createUnfocusAction,
+  createLogAction,
+} from '../state'
+
+import {ExtensionServerClient} from '../ExtensionServerClient'
+import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect'
+import {useExtensionServerState} from '../hooks/useExtensionServerState'
+import React, {useCallback, useMemo, useState} from 'react'
+
+import type {ExtensionServerProviderProps} from './types'
+
+export function ExtensionServerProvider({children, options: defaultOptions}: ExtensionServerProviderProps) {
+  const [state, dispatch] = useExtensionServerState()
+  const [options, setOptions] = useState(defaultOptions)
+  const [client] = useState<ExtensionServer.Client>(() => new ExtensionServerClient())
+
+  const connect = useCallback(
+    (newOptions: ExtensionServer.Options = options) => {
+      setOptions(newOptions)
+    },
+    [options],
+  )
+
+  useIsomorphicLayoutEffect(() => client.connect(options), [client, options])
+
+  useIsomorphicLayoutEffect(() => {
+    const listeners = [
+      client.on('update', (payload) => dispatch(createUpdateAction(payload))),
+      client.on('connected', (payload) => dispatch(createConnectedAction(payload))),
+      client.on('refresh', (payload) => dispatch(createRefreshAction(payload))),
+      client.on('focus', (payload) => dispatch(createFocusAction(payload))),
+      client.on('unfocus', (payload) => dispatch(createUnfocusAction(payload))),
+      client.on('log', (payload) => dispatch(createLogAction(payload))),
+    ]
+
+    return () => listeners.forEach((unsubscribe) => unsubscribe())
+  }, [dispatch])
+
+  const context = useMemo(() => ({dispatch, state, connect, client}), [dispatch, connect, state, client])
+
+  return <extensionServerContext.Provider value={context}>{children}</extensionServerContext.Provider>
+}