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

package/src/ExtensionServerClient/ExtensionServerClient.ts

@@ -0,0 +1,320 @@
+/* eslint-disable no-console */
+import {ExtensionServer} from './server-types.js'
+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']
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  protected listeners: Record<string, Set<(payload: any) => void>> = {}
+  protected connectionListeners: {close: Set<(event: Event) => void>; open: Set<(event: Event) => void>} = {
+    close: new Set(),
+    open: new Set(),
+  }
+
+  protected connected = false
+
+  private uiExtensionsByUuid: Record<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 as ExtensionServer.Options
+      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 as string]) {
+      this.listeners[event as string] = new Set()
+    }
+
+    this.listeners[event as string].add(listener)
+    return () => this.listeners[event as string].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 as string)) {
+      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'
+       *  }],
+       * }
+       * ```
+       */
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      ;(data as any).extensions?.forEach((extension: ExtensionPayload) => {
+        TRANSLATED_KEYS.forEach((key) => {
+          if (isUIExtension(extension)) {
+            extension.extensionPoints?.forEach((extensionPoint) => {
+              // eslint-disable-next-line @typescript-eslint/no-explicit-any
+              delete (extensionPoint as any)[key]
+            })
+          }
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          delete (extension as any)[key]
+        })
+      })
+      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 = args[0]
+    const data = args.length > 1 ? args[1] : undefined
+
+    if (this.EVENT_THAT_WILL_MUTATE_THE_SERVER.includes(event as string)) {
+      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
+        const typedData = data
+
+        if (event === 'dispatch') {
+          const {type, payload} = typedData as {type: string; payload: unknown}
+          this.listeners[type]?.forEach((listener) => listener(payload))
+          return
+        }
+
+        const filteredExtensions = typedData.extensions
+          ? filterExtensionsBySurface(typedData.extensions, this.options.surface)
+          : typedData.extensions
+
+        this.listeners[event]?.forEach((listener) => {
+          listener({...typedData, 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: Record<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: Record<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 = extension.extensionPoints as (string | {surface: Surface; [key: string]: unknown})[]
+      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/server-types.ts

@@ -0,0 +1,65 @@
+import {Surface} from './types.js'
+import {ExtensionPayload, ExtensionPoint, App} from '../types'
+import {FlattenedLocalization, LocalesOptions, Localization} from '../i18n'
+
+// Re-export and augment the global ExtensionServer namespace
+export namespace ExtensionServer {
+  export interface UIExtension extends ExtensionPayload {
+    extensionPoints: ExtensionPoint[]
+    localization?: FlattenedLocalization | Localization | null
+  }
+
+  export interface Client {
+    id: string
+    connection: WebSocket
+    options: Options
+    connect(options?: Options): () => void
+    on<TEvent extends keyof InboundEvents>(
+      event: TEvent,
+      listener: (payload: InboundEvents[TEvent]) => void,
+    ): () => void
+    persist<TEvent extends keyof OutboundPersistEvents>(event: TEvent, data: OutboundPersistEvents[TEvent]): void
+    emit<TEvent extends keyof DispatchEvents>(...args: EmitArgs<TEvent>): void
+    onConnection<TEvent extends 'close' | 'open'>(event: TEvent, listener: (event: Event) => void): () => void
+  }
+
+  export interface Options {
+    connection: {
+      url?: string
+      automaticConnect?: boolean
+      protocols?: string | string[]
+    }
+    surface?: Surface
+    locales?: LocalesOptions
+  }
+
+  export interface ServerEvents {
+    event: string
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    data: any
+  }
+
+  export interface InboundEvents extends DispatchEvents {
+    dispatch: {type: keyof DispatchEvents; payload: DispatchEvents[keyof DispatchEvents]}
+    connected: {extensions: ExtensionPayload[]; app?: App; store: string}
+    update: {extensions?: ExtensionPayload[]; app?: App}
+  }
+
+  export interface OutboundPersistEvents {
+    update: {
+      extensions?: ExtensionPayload[]
+      app?: App
+    }
+  }
+
+  export interface DispatchEvents {
+    refresh: {uuid: string}[]
+    focus: {uuid: string}[]
+    unfocus: void
+    navigate: {url: string}
+  }
+
+  export type EmitArgs<TEvent extends keyof DispatchEvents> = undefined extends DispatchEvents[TEvent]
+    ? [event: TEvent]
+    : [event: TEvent, payload: DispatchEvents[TEvent]]
+}

package/src/ExtensionServerClient/types.ts

@@ -0,0 +1,159 @@
+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 {}