@pitcher/js-api 1.22.0-alpha.6 → 1.22.0-beta.1

package/lib/sdk/api/modules/ui/content.ui.d.ts

@@ -1,7 +1,57 @@
 import { UiSelectContentRequest, UiSelectContentResponse, UiOpenRequest, UiToastRequest, UiPreselectSfdcMeetingIdRequest, UiPreselectSfdcMeetingIdResponse } from './types.ui';
 
+/**
+ * @hidden
+ * @deprecated
+ */
 export declare function ui_select_content(payload?: UiSelectContentRequest): Promise<UiSelectContentResponse>;
-export declare function select_content(payload?: UiSelectContentRequest): Promise<UiSelectContentResponse>;
+/**
+ * Allows the user to select (and preselect) content from the instance.
+ *
+ * Opens the content selector dialog to allow the user to select content and handle the outcome. This method allows you to
+ * prompt the user to select content from the CatalogIQ instance and use that content in your application.
+ *
+ * @example
+ * const api = useApi() // or useUi() if you know that you 're in UI context
+ * api
+ *   .selectContent({
+ *     selections: [
+ *       { fileId: "01HCZ623YYRFJQ0F7B69VWE510", type: "file" },
+ *       {
+ *         fileId: "01HD3XGZ5FN90QJGK7CH8TBZDF",
+ *         type: "page",
+ *         pageIndex: 2,
+ *       },
+ *     ],
+ *   })
+ *
+ * @param payload optional payload to preselect specific content
+ * @returns Promise with the user action and selected content
+ */
+export declare function selectContent(payload?: UiSelectContentRequest): Promise<UiSelectContentResponse>;
+/**
+ * Open a file in the CatalogIQ instance.
+ */
 export declare function open(payload: UiOpenRequest): Promise<void>;
+/**
+ * Show a toast message to the user.
+ *
+ * @example
+ * useUi().toast({ type: 'info', message: 'Hello, world!' })
+ */
 export declare function toast(payload: UiToastRequest): Promise<void>;
-export declare function preselect_sfdc_meeting_id(payload: UiPreselectSfdcMeetingIdRequest): Promise<UiPreselectSfdcMeetingIdResponse>;
+/**
+ * Preselect a meeting in the top meeting bar by Salesforce Meeting ID. From there, the user can easily start the meeting
+ * with a single click.
+ *
+ * @example
+ * const objectFetchedFromSalesforce = {
+ *   // fetch dynamically from Salesforce or provide in another way
+ *   EventId: '00U1r00000D1J1zEAF',
+ * }
+ * ui.preselectSfdcMeetingId({ eventId: objectFetchedFromSalesforce.EventId }).then((response) => {
+ *   // e.g. display advanced meeting details inside your app
+ *   console.log(response.event)
+ * })
+ */
+export declare function preselectSfdcMeetingId(payload: UiPreselectSfdcMeetingIdRequest): Promise<UiPreselectSfdcMeetingIdResponse>;

package/lib/sdk/api/modules/ui/index.d.ts

@@ -1,15 +1,152 @@
 import { UiMeetingCanceledPayload, UiCanvasUpdatedPayload, UiSectionListUpdatedPayload, UiAppSetDataPayload, UiAppUpdateDataPayload, UiBroadcastRequest, UiMessagePayloads } from './types.ui';
 
-export declare function on<T extends keyof UiMessagePayloads>(type: T, handler: (data: UiMessagePayloads[T]) => Promise<void>): Promise<() => void>;
-export declare function on_meeting_canceled(handler: (data: UiMeetingCanceledPayload) => Promise<void>): Promise<() => void>;
-export declare function on_canvas_updated(handler: (data: UiCanvasUpdatedPayload) => Promise<void>): Promise<() => void>;
-export declare function on_section_list_updated(handler: (data: UiSectionListUpdatedPayload) => Promise<void>): Promise<() => void>;
-export declare function on_app_set_data(handler: (data: UiAppSetDataPayload) => Promise<void>): Promise<() => void>;
-export declare function on_app_update_data(handler: (data: UiAppUpdateDataPayload) => Promise<void>): Promise<() => void>;
-export declare function ui_broadcast(payload: UiBroadcastRequest): Promise<void>;
-export * from './content.ui';
-export * from './loading.ui';
-export * from './location.ui';
-export * from './app-errors.ui';
-export * from './canvas.ui';
-export * from './post-call.ui';
+/**
+ * Subscribe to a given event type by its key.
+ *
+ * @example
+ * const unsubscribeFromSectionListUpdate = useUi().on('ui_section_list_updated', (event: object) => {
+ *   // handle event
+ * })
+ *
+ * // later
+ * unsubscribeFromSectionListUpdate.then(unsubscribe => unsubscribe())
+ *
+ * @param type The event type/key to subscribe to.
+ * @param handler The handler function to call when the event is emitted.
+ * @returns A Promise resolving to a cleanup function to unsubscribe from the event.
+ */
+declare function on<T extends keyof UiMessagePayloads>(type: T, handler: (data: UiMessagePayloads[T]) => Promise<void>): Promise<() => void>;
+/**
+ * Subscribe to the meeting canceled event.
+ *
+ * @example
+ * const unsubscribeFromMeetingCanceled = useUi().onMeetingCanceled((event: {
+ *   accountId?: string;
+ *   eventId?: string;
+ * }) => {
+ *   // handle event
+ * })
+ *
+ * // later
+ * unsubscribeFromMeetingCanceled.then(cancel => cancel())
+ *
+ * @param handler
+ * @returns A Promise resolving to a cleanup function to unsubscribe from the event.
+ */
+declare function onMeetingCanceled(handler: (data: UiMeetingCanceledPayload) => Promise<void>): Promise<() => void>;
+/**
+ * Subscribe to the canvas updated event. It is triggered when the current canvas of the app is updated.
+ *
+ * @example
+ * const unsubscribePromise = useUi().onCanvasUpdated((event: { canvas }) => {
+ *   // handle event
+ * })
+ *
+ * // later
+ * unsubscribePromise.then(unsubscribe => unsubscribe())
+ *
+ * @returns A Promise resolving to a cleanup function to unsubscribe from the event.
+ */
+declare function onCanvasUpdated(handler: (data: UiCanvasUpdatedPayload) => Promise<void>): Promise<() => void>;
+/**
+ * Subscribe to the section list updated event. It is triggered when the list of sections (products) in the current canvas
+ * is updated.
+ *
+ * @example
+ * const unsubscribePromise = useUi().onSectionListUpdated((event: { canvas }) => {
+ *   // handle event
+ * })
+ *
+ * // later
+ * unsubscribePromise.then(unsubscribe => unsubscribe())
+ *
+ * @returns A Promise resolving to a cleanup function to unsubscribe from the event.
+ */
+declare function onSectionListUpdated(handler: (data: UiSectionListUpdatedPayload) => Promise<void>): Promise<() => void>;
+/**
+ * Subscribe to the app set data event. It is triggered when the app data is set. This event is triggered when the app is
+ * loaded and in certain other cases after loading.
+ *
+ * This is the main event for the canvas app to receive data from the CatalogIQ instance and know about its environment.
+ *
+ * @example
+ * let user = null
+ * let isEditMode = null
+ * let activeCanvas = null
+ * let isPrintMode = false
+ * const unsubscribePromise = useUi().onAppSetData((data) => {
+ *   user = data?.user
+ *   isEditMode = data?.is_edit_mode
+ *   activeCanvas = data?.canvas
+ *   isPrintMode = data?.display_mode === 'print' || data?.client === 'dsr'
+ *   // ...mode logic...
+ * })
+ *
+ * // later
+ * unsubscribePromise.then(unsubscribe => unsubscribe())
+ *
+ * @returns A Promise resolving to a cleanup function to unsubscribe from the event.
+ */
+declare function onAppSetData(handler: (data: UiAppSetDataPayload) => Promise<void>): Promise<() => void>;
+/**
+ * Subscribe to the app update data event. It is triggered when the user changes from edit mode to view mode or vice versa
+ * and when the call is started or ended.
+ *
+ * @example
+ * let inCall = false
+ * let isEditMode = false
+ * const unsubscribePromise = useUi().onAppUpdateData((data) => {
+ *   isEditMode = data?.is_edit_mode
+ *   inCall = data?.in_call
+ *   // ...mode logic...
+ * })
+ *
+ * // later
+ * unsubscribePromise.then(unsubscribe => unsubscribe())
+ *
+ * @returns A Promise resolving to a cleanup function to unsubscribe from the event.
+ */
+declare function onAppUpdateData(handler: (data: UiAppUpdateDataPayload) => Promise<void>): Promise<() => void>;
+/**
+ * Broadcast event to the UI. Hidden from the documentation.
+ *
+ * @hidden
+ */
+declare function uiBroadcast(payload: UiBroadcastRequest): Promise<void>;
+declare const _default: {
+    completePostcall(payload: import('../../../../main.lib').UiCompletePostcallRequest): Promise<void>;
+    stopMeeting(): Promise<void>;
+    enablePostcallSubmit(): Promise<void>;
+    disablePostcallSubmit(): Promise<void>;
+    setPostcallStyle(payload: import('../../../../main.lib').UiSetPostcallStyleRequest): Promise<void>;
+    updateCanvas(payload: import('../../../../main.lib').UiUpdateCanvasRequest): Promise<import('../../../../main.lib').CanvasRetrieve>;
+    appLoaded(): Promise<void>;
+    appResize(payload: import('../../../../main.lib').UiAppResizeRequest): Promise<void>;
+    canvasNavigateNextPage(): Promise<void>;
+    canvasNavigatePreviousPage(): Promise<void>;
+    canvasNavigatePage(payload: import('../../../../main.lib').UiCanvasNavigatePageRequest): Promise<void>;
+    openCanvasOverlay(payload: {
+        id: import('../../../../main.lib').CanvasRetrieve["id"];
+        edit_mode?: boolean;
+        fullscreen?: boolean;
+        component_id?: string;
+        section_id?: string;
+    }): Promise<void>;
+    selectCanvases(payload?: import('../../../../main.lib').UiSelectCanvasesRequest): Promise<import('../../../../main.lib').UiSelectCanvasesResponse>;
+    captureAppError(payload: import('../../../../main.lib').UiCaptureAppErrorRequest): Promise<void>;
+    updateLocation(payload: import('../../../../main.lib').UpdateLocationPitcherEvent): Promise<any>;
+    embeddableReady(): Promise<void>;
+    ui_select_content(payload?: import('../../../../main.lib').UiSelectContentRequest): Promise<import('../../../../main.lib').UiSelectContentResponse>;
+    selectContent(payload?: import('../../../../main.lib').UiSelectContentRequest): Promise<import('../../../../main.lib').UiSelectContentResponse>;
+    open(payload: import('../../../../main.lib').UiOpenRequest): Promise<void>;
+    toast(payload: import('../../../../main.lib').UiToastRequest): Promise<void>;
+    preselectSfdcMeetingId(payload: import('../../../../main.lib').UiPreselectSfdcMeetingIdRequest): Promise<import('../../../../main.lib').UiPreselectSfdcMeetingIdResponse>;
+    on: typeof on;
+    onMeetingCanceled: typeof onMeetingCanceled;
+    onCanvasUpdated: typeof onCanvasUpdated;
+    onSectionListUpdated: typeof onSectionListUpdated;
+    onAppSetData: typeof onAppSetData;
+    onAppUpdateData: typeof onAppUpdateData;
+    uiBroadcast: typeof uiBroadcast;
+};
+export default _default;

package/lib/sdk/api/modules/ui/loading.ui.d.ts

@@ -1 +1,9 @@
-export declare function embeddable_ready(): Promise<void>;
+/**
+ * This event is used for appJson.module.canvas.start_in_loading_mode: true apps.
+ * A loading curtain is displayed until you call this event.
+ *
+ * @example
+ * useUi().embeddableReady()
+ *
+ */
+export declare function embeddableReady(): Promise<void>;

package/lib/sdk/api/modules/ui/location.ui.d.ts

@@ -1,3 +1,20 @@
 import { UpdateLocationPitcherEvent } from '../../../interfaces';
 
-export declare function update_location(payload: UpdateLocationPitcherEvent): Promise<any>;
+/**
+ * Navigate to another page in the CatalogIQ instance.
+ *
+ * [//]: # 'TODO: This is a very powerful event, we need to expand documentation here'
+ *
+ * @example
+ * const canvasId = '1234567890abcdef12345678' // obtain target canvasId
+ * useUi().updateLocation({
+ *   action: 'restore',
+ *   routes: {
+ *     'slotty-ui': {
+ *       path: '/canvases/saved-canvases/' + canvasId + '/build/present',
+ *       query: {},
+ *     },
+ *   },
+ * })
+ */
+export declare function updateLocation(payload: UpdateLocationPitcherEvent): Promise<any>;

package/lib/sdk/api/modules/ui/post-call.ui.d.ts

@@ -1,6 +1,37 @@
 import { UiCompletePostcallRequest, UiSetPostcallStyleRequest } from './types.ui';
 
-export declare function complete_postcall(payload: UiCompletePostcallRequest): Promise<void>;
-export declare function enable_postcall_submit(): Promise<void>;
-export declare function disable_postcall_submit(): Promise<void>;
-export declare function set_postcall_style(payload: UiSetPostcallStyleRequest): Promise<void>;
+/**
+ * Ends current meeting and shows postcall form.
+ *
+ * @example
+ * useUi().completePostcall({ was_successfully_submitted: true })
+ */
+export declare function completePostcall(payload: UiCompletePostcallRequest): Promise<void>;
+/**
+ * Ends current meeting and shows postcall form.
+ *
+ * @example
+ * useUi().stopMeeting()
+ */
+export declare function stopMeeting(): Promise<void>;
+/**
+ * Mark the postcall form as possible to submit by the user.
+ *
+ * @example
+ * useUi().enablePostcallSubmit()
+ */
+export declare function enablePostcallSubmit(): Promise<void>;
+/**
+ * Mark the postcall form as **not** possible to submit by the user. Useful while processing the form data.
+ *
+ * @example
+ * useUi().disablePostcallSubmit()
+ */
+export declare function disablePostcallSubmit(): Promise<void>;
+/**
+ * Change the height of the postcall form.
+ *
+ * @example
+ * useUi().setPostcallStyle({ height: 100 })
+ */
+export declare function setPostcallStyle(payload: UiSetPostcallStyleRequest): Promise<void>;

package/lib/sdk/api/modules/ui/types.ui.d.ts

@@ -1,24 +1,30 @@
 import { SelectedPage as ContentSelectorSelectedPage, SelectedFile as ContentSelectorSelectedFile } from '@content-selector/stores/app';
-import { CanvasSection, ComponentNode, EmbeddableProps, SfEvent } from '../../../../main.lib';
+import { Selection } from '@content-selector/appTypes';
+import { CanvasSelection } from '@canvas-selector/appTypes';
+import { ComponentNode, EmbeddableProps } from '@canvas-builder/types/canvas';
+import { SfEvent } from '../../../../types/sfdc';
 import { Mutable } from '../../../../types/ts';
-import { Canvas, User } from '../../../../../types/openapi';
+import { CanvasRetrieve, User, Canvas, CanvasSection } from '../../../../../types/openapi';
 import { OpenRequestPayload } from '../../../payload.types';
 
 export declare const UI_MESSAGE: "UI_MESSAGE";
 export declare const UI_API_METHOD_TYPES: {
     readonly UI_BROADCAST: "ui_broadcast";
     readonly UI_SELECT_CONTENT: "ui_select_content";
+    readonly UI_SELECT_CANVASES: "ui_select_canvases";
     readonly UI_OPEN: "ui_open";
     readonly UI_EMBEDDABLE_READY: "ui_embeddable_ready";
     readonly UI_TOAST: "ui_toast";
     readonly UI_CAPTURE_APP_ERROR: "ui_capture_app_error";
     readonly UI_UPDATE_CANVAS: "ui_update_canvas";
+    readonly UI_OPEN_CANVAS_OVERLAY: "ui_open_canvas_overlay";
     readonly UI_UPDATE_LOCATION: "ui_update_location";
     readonly UI_PRESELECT_SFDC_MEETING_ID: "ui_preselect_sfdc_meeting_id";
     readonly UI_SET_POSTCALL_STYLE: "ui_set_postcall_style";
     readonly UI_ENABLE_POSTCALL_SUBMIT: "ui_enable_postcall_submit";
     readonly UI_DISABLE_POSTCALL_SUBMIT: "ui_disable_postcall_submit";
     readonly UI_COMPLETE_POSTCALL: "ui_complete_postcall";
+    readonly UI_STOP_MEETING: "ui_stop_meeting";
     readonly UI_CANVAS_NAVIGATE_NEXT_PAGE: "ui_canvas_navigate_next_page";
     readonly UI_CANVAS_NAVIGATE_PREVIOUS_PAGE: "ui_canvas_navigate_previous_page";
     readonly UI_CANVAS_NAVIGATE_PAGE: "ui_canvas_navigate_page";
@@ -34,38 +40,87 @@ export declare const UI_MESSAGE_TYPES: {
 };
 export declare const UI_NATIVE_MESSAGE_TYPES: readonly ["ui_app_set_data", "ui_app_update_data", "ui_canvas_updated"];
 export type UiBroadcastRequest = Record<string, any>;
-export type UiSelectContentRequest = Record<string, never>;
+export type UiSelectContentRequest = {
+    /** Array of selections */
+    selections?: Selection[];
+};
 export type UiSelectContentResponse = {
+    /** User action result */
     user_action: 'cancelled' | 'selected';
+    /** Selected content */
     content?: (ContentSelectorSelectedFile | ContentSelectorSelectedPage)[];
 };
+export type UiSelectCanvasesRequest = {
+    /** Array of selections */
+    selections?: CanvasSelection[];
+    allowed_types?: ('canvas' | 'canvas-template' | 'section' | 'section-template')[];
+};
+export type UiSelectCanvasesResponse = {
+    /** User action result */
+    user_action: 'cancelled' | 'selected';
+    /** Selected canvases */
+    canvases?: Canvas[];
+};
+/**
+ * Error object to send to Pitcher sentry instance
+ */
 export type UiCaptureAppErrorRequest = Record<string, any>;
-export type UiUpdateCanvasRequest = Mutable<Canvas> & {
+export type UiUpdateCanvasRequest = Mutable<CanvasRetrieve> & {
+    /** Comma-separated list of field keys to return from the server */
     fields?: string;
 };
 export type UiOpenRequest = OpenRequestPayload;
 export type UiCompletePostcallRequest = {
+    /** Indicates if the postcall was successfully submitted */
     was_successfully_submitted?: boolean;
 };
 export type UiSetPostcallStyleRequest = Record<string, any>;
 export type UiAppResizeRequest = {
+    /** Requested height as the number of pixels */
     height: number;
 };
-export type UiCanvasNavigatePageReuqest = {
+export type UiCanvasNavigatePageRequest = {
+    /** The id of the component we want to navigate to */
     page: ComponentNode['id'];
 };
 export interface UiToastRequest {
+    /**
+     * Type of the toast, influences the default icon
+     * @defaultValue **REQUIRED**
+     */
     type: 'info' | 'error' | 'warning' | 'success' | 'loading';
+    /**
+     * Text to show inside the toast
+     * @defaultValue **REQUIRED**
+     */
     message: string;
+    /**
+     * Optional, value in milliseconds
+     * @defaultValue 3500
+     */
     duration?: number;
+    /**
+     * Visibility of the close button, default is true
+     * @defaultValue true
+     */
     closable?: boolean;
+    /**
+     * Toast won't be hidden as long as it is hovered
+     * @defaultValue true
+     */
     keepAliveOnHover?: boolean;
+    /**
+     * Set to `false` to hide the icon
+     * @defaultValue true
+     */
     showIcon?: boolean;
 }
 export interface UiPreselectSfdcMeetingIdRequest {
+    /** Salesforce Meeting ID */
     eventId: string;
 }
 export interface UiPreselectSfdcMeetingIdResponse {
+    /** Salesforce Event */
     event: SfEvent | null;
 }
 export type UiMessagePayloads = {
@@ -76,36 +131,58 @@ export type UiMessagePayloads = {
     [UI_MESSAGE_TYPES.UI_SECTION_LIST_UPDATED]: UiSectionListUpdatedPayload;
 };
 export type UiMessageEnvelope<T extends (typeof UI_MESSAGE_TYPES)[keyof typeof UI_MESSAGE_TYPES] = (typeof UI_MESSAGE_TYPES)[keyof typeof UI_MESSAGE_TYPES]> = {
+    /** Message type */
     type: T;
+    /** Message body */
     body: UiMessagePayloads[T];
 };
 export type UiMeetingCanceledPayload = {
+    /** Account ID */
     accountId?: string;
+    /** Event ID */
     eventId?: string;
 };
 export type UiAppSetDataPayload = {
+    /** Client name */
     client: string | null;
+    /** Platform name */
     platform: string | undefined;
+    /** User information */
     user: User | null;
+    /** Edit mode status */
     is_edit_mode: boolean;
+    /** Call status */
     in_call: boolean;
-    canvas: Canvas;
+    /** Canvas data */
+    canvas: CanvasRetrieve;
+    /** Section used in canvas */
     used_in_section: CanvasSection | null;
+    /** Component ID */
     component_id: string;
+    /** Embeddable settings */
     settings: EmbeddableProps['settings'] | null;
+    /** Width of the canvas */
     width: string | undefined;
+    /** Height of the canvas */
     height: string | undefined;
+    /** Display mode */
     display_mode: string | undefined;
 };
 export type UiAppUpdateDataPayload = {
+    /** Call status */
     in_call: boolean;
+    /** Edit mode status */
     is_edit_mode: boolean;
 };
 export type UiCanvasUpdatedPayload = {
-    canvas: Canvas;
+    /** Canvas data */
+    canvas: CanvasRetrieve;
 };
 export type UiSectionListUpdatedPayload = {
+    /** List of section IDs */
     section_list_ids: string[];
+    /** Section list component ID */
     section_list_component_id: string;
-    canvas: Canvas | null;
+    /** Canvas data */
+    canvas: CanvasRetrieve | null;
 };

package/lib/sdk/api/modules/users.d.ts

@@ -3,4 +3,9 @@ import { PaginatedData } from '../../../types/paginatedData';
 import { User } from '../../../../types/openapi';
 
 export declare function getUsers(payload?: GetUsersParams): Promise<PaginatedData<User>>;
-export declare function refreshServiceToken(payload: RefreshServiceTokenRequest): Promise<RefreshServiceTokenResponse>;
+/**
+ * Ask for a refreshed Salesforce token. In case the token hasn't expired yet, this method will return the same token as the current one found in the (`getEnv`)[#getenv] result.
+ * @returns Promise resolving to an object containing the token
+ */
+export declare function refreshServiceToken(payload?: RefreshServiceTokenRequest): Promise<RefreshServiceTokenResponse>;
+export declare function refreshAccessToken(): any;