|
| 1 | +/** |
| 2 | + * @beta |
| 3 | + * @hidden |
| 4 | + * User information required by specific apps |
| 5 | + * @internal |
| 6 | + * Limited to Microsoft-internal use |
| 7 | + * @module |
| 8 | + */ |
| 9 | + |
| 10 | +import { callFunctionInHostAndHandleResponse } from '../../internal/communication'; |
| 11 | +import { registerHandlerHelper } from '../../internal/handlers'; |
| 12 | +import { ensureInitialized } from '../../internal/internalAPIs'; |
| 13 | +import { ResponseHandler } from '../../internal/responseHandler'; |
| 14 | +import { ApiName, ApiVersionNumber, getApiVersionTag } from '../../internal/telemetry'; |
| 15 | +import { ISerializable } from '../../public'; |
| 16 | +import { FrameContexts } from '../../public/constants'; |
| 17 | +import { isSdkError, SdkError } from '../../public/interfaces'; |
| 18 | +import { runtime } from '../../public/runtime'; |
| 19 | +import { |
| 20 | + Content, |
| 21 | + ContentRequest, |
| 22 | + PreCheckContextResponse, |
| 23 | + SidePanelError, |
| 24 | + SidePanelErrorCode, |
| 25 | + SidePanelErrorImpl, |
| 26 | +} from './sidePanelInterfaces'; |
| 27 | + |
| 28 | +const copilotTelemetryVersionNumber: ApiVersionNumber = ApiVersionNumber.V_2; |
| 29 | + |
| 30 | +/** |
| 31 | + * @hidden |
| 32 | + * @internal |
| 33 | + * Limited to Microsoft-internal use |
| 34 | + * @beta |
| 35 | + * @returns boolean to represent whether copilot.sidePanel capability is supported |
| 36 | + * |
| 37 | + * @throws Error if {@linkcode app.initialize} has not successfully completed |
| 38 | + */ |
| 39 | +export function isSupported(): boolean { |
| 40 | + return ensureInitialized(runtime) && !!runtime.supports.copilot?.sidePanel; |
| 41 | +} |
| 42 | + |
| 43 | +/** |
| 44 | + * @beta |
| 45 | + * @hidden |
| 46 | + * Determines if the provided error object is an instance of SidePanelError or SdkError. |
| 47 | + * @internal |
| 48 | + * Limited to Microsoft-internal use |
| 49 | + * @param err The error object to check whether it is of SidePanelError type |
| 50 | + */ |
| 51 | +export function isResponseAReportableError(err: unknown): err is SidePanelError | SdkError { |
| 52 | + if (typeof err !== 'object' || err === null) { |
| 53 | + return false; |
| 54 | + } |
| 55 | + |
| 56 | + const error = err as SidePanelError; |
| 57 | + |
| 58 | + return ( |
| 59 | + (Object.values(SidePanelErrorCode).includes(error.errorCode as SidePanelErrorCode) && |
| 60 | + (error.message === undefined || typeof error.message === 'string')) || |
| 61 | + isSdkError(err) // If the error is an SdkError, it can be considered a SidePanelError |
| 62 | + ); |
| 63 | +} |
| 64 | +/** |
| 65 | + * Get user content data from the hub to send to copilot app. |
| 66 | + * |
| 67 | + * @returns { Promise<Content> } - promise resolves with a content object containing user content data |
| 68 | + * @throws { SidePanelError | SdkError } - Throws a SidePanelError or SdkError if host SDK returns an error as a response to this call |
| 69 | + * |
| 70 | + * @hidden |
| 71 | + * @beta |
| 72 | + * @internal |
| 73 | + * Limited to Microsoft-internal use |
| 74 | + */ |
| 75 | +export async function getContent(request?: ContentRequest): Promise<Content> { |
| 76 | + ensureInitialized(runtime); |
| 77 | + const input = request ? [new SerializableContentRequest(request)] : []; |
| 78 | + return callFunctionInHostAndHandleResponse( |
| 79 | + ApiName.Copilot_SidePanel_GetContent, |
| 80 | + input, |
| 81 | + new GetContentResponseHandler(), |
| 82 | + getApiVersionTag(copilotTelemetryVersionNumber, ApiName.Copilot_SidePanel_GetContent), |
| 83 | + isResponseAReportableError, |
| 84 | + ); |
| 85 | +} |
| 86 | + |
| 87 | +/** |
| 88 | + * When the copilot detects a contextual query it gets the user consent status before making the getContent call. |
| 89 | + * |
| 90 | + * @returns { Promise<PreCheckContextResponse> } - promise resolves with a content object containing user content data |
| 91 | + * @throws { SidePanelError | SdkError } - Throws a SidePanelError or SdkError if host SDK returns an error as a response to this call |
| 92 | + * |
| 93 | + * @hidden |
| 94 | + * @beta |
| 95 | + * @internal |
| 96 | + * Limited to Microsoft-internal use |
| 97 | + */ |
| 98 | +export async function preCheckUserConsent(): Promise<PreCheckContextResponse> { |
| 99 | + ensureInitialized(runtime); |
| 100 | + return callFunctionInHostAndHandleResponse( |
| 101 | + ApiName.Copilot_SidePanel_PreCheckUserConsent, |
| 102 | + [], |
| 103 | + new PreCheckContextResponseHandler(), |
| 104 | + getApiVersionTag(copilotTelemetryVersionNumber, ApiName.Copilot_SidePanel_PreCheckUserConsent), |
| 105 | + isResponseAReportableError, |
| 106 | + ); |
| 107 | +} |
| 108 | + |
| 109 | +/** Register user action content select handler function type */ |
| 110 | +export type userActionHandlerType = (selectedContent: Content) => void; |
| 111 | +/** |
| 112 | + * @hidden |
| 113 | + * @beta |
| 114 | + * Registers a handler to get updated content data from the hub to send to copilot app. |
| 115 | + * This handler will be called when the user selects content in the application. |
| 116 | + * @param handler - The handler for getting user action content select. |
| 117 | + * |
| 118 | + * @internal |
| 119 | + * Limited to Microsoft-internal use |
| 120 | + */ |
| 121 | +export function registerUserActionContentSelect(handler: userActionHandlerType): void { |
| 122 | + registerHandlerHelper( |
| 123 | + getApiVersionTag(copilotTelemetryVersionNumber, ApiName.Copilot_SidePanel_RegisterUserActionContentSelect), |
| 124 | + 'copilot.sidePanel.userActionContentSelect', |
| 125 | + handler, |
| 126 | + [FrameContexts.content], |
| 127 | + () => { |
| 128 | + if (!isSupported()) { |
| 129 | + throw copilotSidePanelNotSupportedOnPlatformError; |
| 130 | + } |
| 131 | + }, |
| 132 | + ); |
| 133 | +} |
| 134 | + |
| 135 | +/** |
| 136 | + * @hidden |
| 137 | + * @beta |
| 138 | + * @internal |
| 139 | + * Limited to Microsoft-internal use |
| 140 | + * |
| 141 | + * Error thrown when the copilot side panel API is not supported on the current platform. |
| 142 | + */ |
| 143 | +export const copilotSidePanelNotSupportedOnPlatformError = new SidePanelErrorImpl( |
| 144 | + SidePanelErrorCode.NotSupportedOnPlatform, |
| 145 | + 'This API is not supported on the current platform.', |
| 146 | +); |
| 147 | +class GetContentResponseHandler extends ResponseHandler<Content, Content> { |
| 148 | + public validate(response: Content): boolean { |
| 149 | + return response !== null && typeof response === 'object'; |
| 150 | + } |
| 151 | + |
| 152 | + public deserialize(response: Content): Content { |
| 153 | + return response; |
| 154 | + } |
| 155 | +} |
| 156 | + |
| 157 | +class PreCheckContextResponseHandler extends ResponseHandler<PreCheckContextResponse, PreCheckContextResponse> { |
| 158 | + public validate(response: PreCheckContextResponse): boolean { |
| 159 | + return response !== null && typeof response === 'object'; |
| 160 | + } |
| 161 | + |
| 162 | + public deserialize(response: PreCheckContextResponse): PreCheckContextResponse { |
| 163 | + return response; |
| 164 | + } |
| 165 | +} |
| 166 | + |
| 167 | +class SerializableContentRequest implements ISerializable { |
| 168 | + public constructor(private contentRequest: ContentRequest) {} |
| 169 | + public serialize(): object { |
| 170 | + return this.contentRequest; |
| 171 | + } |
| 172 | +} |
0 commit comments