feat(api): add agent location and API integration [EXT-6966]

lib/agent.ts

@@ -0,0 +1,29 @@
+import { Channel } from './channel'
+import { MemoizedSignal, Signal } from './signal'
+import { AgentAPI, AgentContext, ConnectMessage, ToolbarAction } from './types'
+
+export default function createAgent(
+  channel: Channel,
+  contextData: ConnectMessage['agent'],
+): AgentAPI {
+  if (!contextData) {
+    throw new Error('Context data is required')
+  }
+
+  const contextChanged = new MemoizedSignal<[AgentContext]>(contextData)
+
+  const toolbarActionSignal = new Signal<[ToolbarAction]>()
+
+  channel.addHandler('contextChanged', (newContext: AgentContext) => {
+    contextChanged.dispatch(newContext)
+  })
+
+  channel.addHandler('toolbarAction', (action: ToolbarAction) => {
+    toolbarActionSignal.dispatch(action)
+  })
+
+  return {
+    onContextChange: (handler) => contextChanged.attach(handler),
+    onToolbarAction: (handler) => toolbarActionSignal.attach(handler),
+  }
+}

lib/api.ts

@@ -8,6 +8,7 @@ import createDialogs from './dialogs'
 import createEditor from './editor'
 import createNavigator from './navigator'
 import createApp from './app'
+import createAgent from './agent'
 import locations from './locations'
 import {
   EntryFieldInfo,
@@ -45,6 +46,7 @@ const LOCATION_TO_API_PRODUCERS: { [location: string]: ProducerFunc[] } = {
   [locations.LOCATION_PAGE]: [makeSharedAPI],
   [locations.LOCATION_HOME]: [makeSharedAPI],
   [locations.LOCATION_APP_CONFIG]: [makeSharedAPI, makeAppAPI],
+  [locations.LOCATION_AGENT]: [makeSharedAPI, makeAgentAPI],
 }
 
 export default function createAPI(
@@ -166,3 +168,9 @@ function makeAppAPI(channel: Channel) {
     app,
   }
 }
+
+function makeAgentAPI(channel: Channel, { agent }: ConnectMessage) {
+  return {
+    agent: createAgent(channel, agent),
+  }
+}

lib/locations.ts

@@ -10,6 +10,7 @@ const locations: Locations = {
   LOCATION_PAGE: 'page',
   LOCATION_APP_CONFIG: 'app-config',
   LOCATION_HOME: 'home',
+  LOCATION_AGENT: 'agent',
 }
 
 export default locations

lib/types/agent.types.ts

@@ -0,0 +1,20 @@
+export interface AgentContext {
+  view: string
+  metadata: {
+    entryId?: string
+    contentTypeId?: string
+    lastFocusedFieldId?: string
+  }
+}
+
+export type ToolbarActionName = 'chat.history' | 'chat.back' | 'chat.close'
+
+export interface ToolbarAction {
+  name: ToolbarActionName
+  action: 'click'
+}
+
+export interface AgentAPI {
+  onContextChange: (handler: (context: AgentContext) => void) => VoidFunction
+  onToolbarAction: (handler: (action: ToolbarAction) => void) => VoidFunction
+}

lib/types/api.types.ts

@@ -22,6 +22,7 @@ import { NavigatorAPI } from './navigator.types'
 import { EntryFieldInfo, FieldInfo } from './field.types'
 import { Adapter, KeyValueMap } from 'contentful-management/types'
 import { CMAClient } from './cmaClient.types'
+import { AgentAPI, AgentContext } from './agent.types'
 
 /* User API */
 
@@ -342,6 +343,14 @@ export type ConfigAppSDK<InstallationParameters extends KeyValueMap = KeyValueMa
   app: AppConfigAPI
 }
 
+export type AgentAppSDK<InstallationParameters extends KeyValueMap = KeyValueMap> = BaseAppSDK<
+  InstallationParameters,
+  never,
+  never
+> & {
+  agent: AgentAPI
+}
+
 export type KnownAppSDK<
   InstallationParameters extends KeyValueMap = KeyValueMap,
   InstanceParameters extends KeyValueMap = KeyValueMap,
@@ -354,6 +363,7 @@ export type KnownAppSDK<
   | PageAppSDK<InstallationParameters>
   | ConfigAppSDK<InstallationParameters>
   | HomeAppSDK<InstallationParameters>
+  | AgentAppSDK<InstallationParameters>
 
 /** @deprecated consider using {@link BaseAppSDK} */
 export type BaseExtensionSDK = BaseAppSDK
@@ -392,6 +402,7 @@ export interface Locations {
   LOCATION_PAGE: 'page'
   LOCATION_HOME: 'home'
   LOCATION_APP_CONFIG: 'app-config'
+  LOCATION_AGENT: 'agent'
 }
 
 export interface ConnectMessage {
@@ -421,4 +432,5 @@ export interface ConnectMessage {
   hostnames: HostnamesAPI
   release?: Release
   uiLanguageLocale: string
+  agent?: AgentContext
 }

lib/types/index.ts

@@ -34,8 +34,11 @@ export type {
   UserAPI,
   JSONPatchItem,
   HostnamesAPI,
+  AgentAppSDK,
 } from './api.types'
 
+export type { AgentAPI, AgentContext, ToolbarAction, ToolbarActionName } from './agent.types'
+
 export type {
   AppConfigAPI,
   AppState,

test/mocks/agent.ts

@@ -0,0 +1,22 @@
+import { AgentContext } from '../../lib/types'
+
+export const mockAgentContext: AgentContext = {
+  view: 'entry-editor',
+  metadata: {
+    entryId: 'test-entry-123',
+    contentTypeId: 'test-content-type-456',
+    lastFocusedFieldId: 'test-field-789',
+  },
+}
+
+export const mockAgentContextMinimal: AgentContext = {
+  view: 'home',
+  metadata: {},
+}
+
+export const mockAgentContextWithPartialMetadata: AgentContext = {
+  view: 'page',
+  metadata: {
+    entryId: 'entry-abc',
+  },
+}

test/mocks/connectMessage.ts

@@ -1,4 +1,5 @@
 import { ConnectMessage } from '../../lib/types'
+import { mockAgentContext } from './agent'
 
 export const baseConnectMessage: ConnectMessage = {
   id: 'test-app-id',
@@ -207,4 +208,10 @@ export const baseConnectMessage: ConnectMessage = {
   uiLanguageLocale: 'en-US',
 } as any // Type assertion to work with complex nested types in testing
 
+export const connectMessageWithAgent: ConnectMessage = {
+  ...baseConnectMessage,
+  location: 'agent',
+  agent: mockAgentContext,
+} as any
+
 export default baseConnectMessage