@pitcher/js-api 1.21.0-beta.14 → 1.21.0-beta.15

package/lib/main.lib.d.ts

@@ -18,6 +18,7 @@ export { default as CDrawer } from './components/CDrawer/CDrawer.vue';
 export { default as CDrawerContent } from './components/CDrawerContent/CDrawerContent.vue';
 export { default as CDropdown } from './components/CDropdown/CDropdown.vue';
 export { default as CErrorFullScreen } from './components/CError/CErrorFullScreen.vue';
+export { default as CFileThumbnail } from './components/CFileThumbnail/CFileThumbnail.vue';
 export { default as CIcon, type Props as CIconProps } from './components/CIcon/CIcon.vue';
 export { default as CImage } from './components/CImage/CImage.vue';
 export { default as CInput } from './components/CInput/CInput.vue';
@@ -104,42 +105,43 @@ export { default as useBindValidation } from './composables/useBindValidation';
 export { default as useCanvasOverlay } from './composables/useCanvasOverlay';
 export { default as useInfiniteScroll } from './composables/useInfiniteScroll';
 export { default as useWindowEvents } from './composables/useWindowEvents';
-export { default as useDetailsView } from './composables/useDetailsView';
 export { default as useConfirmation } from './composables/useConfirmation';
 export { default as useLocation } from './composables/useLocation';
 export { default as useRecentFiles } from './composables/recentFiles.use';
 export { default as useToast } from './composables/useToast';
+export { default as useSuggestedTags } from './composables/suggestedTags.use';
 export * from './plugins/vueQuery';
+export * from './apps/canvas-builder/util/canvas.util';
+export * from './apps/canvas-builder/util/tree';
+export * from './components/filters/filter.util';
+export * from './util/anchor';
 export * from './util/array';
-export * from './util/object';
-export * from './util/userAgents';
-export * from './util/image';
 export * from './util/casing';
-export * from './util/query';
-export * from './util/reactive';
-export * from './util/date';
-export * from './util/number';
-export * from './util/network';
-export * from './util/tsHelpers';
 export * from './util/color';
-export * from './util/user';
+export * from './util/date';
+export * from './util/dev.util';
 export * from './util/dom';
-export * from './util/anchor';
-export * from './util/translations';
-export * from './util/message-event';
 export * from './util/font.util';
-export * from './util/timer';
-export * from './components/filters/filter.util';
-export * from './apps/canvas-builder/util/tree';
-export * from './apps/canvas-builder/util/canvas.util';
-export * from './util/navigation.util';
 export * from './util/fullscreen.util';
+export * from './util/image';
 export * from './util/location.util';
-export * from './util/dev.util';
+export * from './util/message-event';
+export * from './util/navigation.util';
+export * from './util/network';
+export * from './util/number';
+export * from './util/object';
+export * from './util/query';
+export * from './util/reactive';
+export * from './util/timer';
+export * from './util/translations';
+export * from './util/tsHelpers';
+export * from './util/user';
+export * from './util/userAgents';
 export * from './sdk/main';
 export * from '../types/openapi';
 export * from './components/CGlobalSearch/CGlobalSearch.types';
 export * from './types/dataTable';
+export * from './types/filter';
 export * from './types/sfdc';
 export * from './types/ts';
 export * from './types/paginatedData';
@@ -170,6 +172,7 @@ export * from './constants/timers.const';
 export * from './constants/url.const';
 export * from './constants/conventions.const';
 export * from './constants/config.const';
+export * from './constants/pitcherSettings.const';
 export * from './api/events/events.queries';
 export * from './api/users/users.queries';
 export * from './api/canvases/canvases.queries';

package/lib/sdk/api/HighLevelApi.d.ts

@@ -1,23 +1,116 @@
 import { LowLevelApi } from './LowLevelApi';
 import { PitcherEvent, ApiOptions } from '../interfaces';
 import * as modules from '@sdk/api/modules';
+/**
+ * Creates a high-level API instance and caches it. Reterns a new instance only if new options are provided.
+ */
 export declare function createHighLevelApi(options?: ApiOptions): {
+    /**
+     * Subscribe to a given event type by its key.
+     *
+     * @param {string} type - The event type to subscribe to.
+     * @param {(payload: PitcherEvent) => void} callback - The callback function to handle the event.
+     * @returns A Promise resolving to a cleanup function to unsubscribe from the event.     * @example
+     *
+     * @example
+     * const unsubscribeFromSectionListUpdate = usePitcherApi().on('entered_fullscreen', (event: object) => {
+     *   // handle event
+     * })
+     * // later
+     * unsubscribeFromSectionListUpdate()
+     */
     on: (type: string, callback: (payload: PitcherEvent) => void) => void;
+    /**
+     * Unsubscribe from a given event type by its key and the attached callback reference.
+     * @param {string} type - The event type to unsubscribe from.
+     * @param {(payload: PitcherEvent) => void} callback - The callback function reference to remove.
+     *
+     * @example
+     * const callback = (event: object) => {
+     *   // handle event
+     * }
+     * usePitcherApi().on('entered_fullscreen', callback)
+     * // later
+     * usePitcherApi().off('entered_fullscreen', callback)
+     */
     off: (type: string, callback: (payload: PitcherEvent) => void) => void;
+    /**
+     * Make the entire CatalogIQ fullscreen.
+     *
+     * @example
+     * usePitcherApi().enterFullscreen()
+     */
     enterFullscreen: () => Promise<any>;
+    /**
+     * Exit fullscreen mode.
+     *
+     * @example
+     * usePitcherApi().exitFullscreen()
+     */
     exitFullscreen: () => Promise<any>;
+    /**
+     * Return is CatalogIQ in fullscreen.
+     *
+     * @example
+     * usePitcherApi().isFullscreen()
+     */
+    isFullscreen: () => Promise<any>;
+    /**
+     * Log out the current user.
+     *
+     * @example
+     * usePitcherApi().logout()
+     */
     logout: () => Promise<any>;
+    /**
+     * Quit the current instance and go to the instance selection screen.
+     *
+     * @example
+     * usePitcherApi().quitInstance()
+     */
     quitInstance: () => Promise<any>;
+    /**
+     * Get the request types.
+     *
+     * @returns {Promise<any>}
+     */
     getRequestTypes: () => Promise<any>;
+    /**
+     * Broadcast an event to CatalogIQ.
+     * @param {PitcherEvent} event - The event to broadcast.
+     *
+     * @example
+     * usePitcherApi()
+     *   .broadcast({
+     *     type: "canvas_updated",
+     *     body: { context: { myContextProperty: 'test' } },
+     *   })
+     *   .then(function (result) {
+     *     useUi().toast({
+     *       message: "Canvas Populated.",
+     *       type: "info",
+     *     })
+     *   })
+     */
     broadcast: (event: PitcherEvent) => Promise<any>;
+    /**
+     * Subscribe to updates.
+     *
+     * @returns {Promise<void>}
+     */
     subscribe: () => Promise<any>;
+    /**
+     * Unsubscribe from updates.
+     *
+     * @returns {Promise<void>}
+     */
     unsubscribe: () => Promise<any>;
     open(payload?: import('../payload.types').OpenRequestPayload): Promise<string>;
     openExternalUrl(payload: import('../payload.types').OpenExternalUrlRequestPayload): Promise<void>;
     getEnv(): Promise<import('../interfaces').PitcherEnv>;
     updateMyUser(payload: {
-        language?: import('../../main.lib').LanguageEnum;
-        dark_mode?: boolean;
+        language?: import('../../main.lib').LanguageEnum | undefined;
+        dark_mode?: boolean | undefined;
     }): Promise<import('../../main.lib').User>;
     getLanguages(): Promise<modules.Language[]>;
     getEvents(payload: Partial<import('../../main.lib').EventRequest>): Promise<import('../../main.lib').PaginatedData<import('../../main.lib').Event>>;

package/lib/sdk/api/modules/admin/canvas.admin.d.ts

@@ -5,17 +5,16 @@ import { PaginatedData } from '../../../../types/paginatedData';
 /**
  * Creates a new canvas.
  *
- * ```
+ * @example
  *  adminApi.createCanvas({
  *    name: 'my new canvas';
  *  })
- * ```
  */
 export declare function createCanvas(payload: CanvasCreateRequest): Promise<CanvasRetrieve>;
 /**
  * Fetches a list of canvases to use in your app.
  *
- * ```
+ * @example
  * // The `filters` object is a reserved payload key to transfer the metadata dict over the wire.
  * adminApi.getCanvases({
  *   search: 'my search query',
@@ -26,7 +25,6 @@ export declare function createCanvas(payload: CanvasCreateRequest): Promise<Canv
  *   },
  *  fields: 'id,name,metadata',
  * })
- * ```
  */
 export declare function getCanvases(payload: GetCanvasesParams & {
     filters?: Record<string, any>;
@@ -35,12 +33,11 @@ export declare function getCanvases(payload: GetCanvasesParams & {
 /**
  * Fetches a canvas by id with the defined fields or all of them.
  *
- * ```
+ * @example
  * // The `filters` object is a reserved payload key to transfer the metadata dict over the wire.
  * adminApi.getCanvas({
  *  fields: 'id,name,metadata',
  * })
- * ```
  */
 export declare function getCanvas(payload: {
     id: CanvasRetrieve['id'];
@@ -49,7 +46,7 @@ export declare function getCanvas(payload: {
 /**
  * Updates a canvas by ID and returns the defined fields or all of them.
  *
- * ```
+ * @example
  * // The fields param is appended to the URL as a query param.
  * onMounted(() => {
  *   adminApi.updateCanvas({
@@ -60,7 +57,6 @@ export declare function getCanvas(payload: {
  *     console.log(res)  // logs: { id: '01HH4RCBH631K4JDHWAQB0RPR6', name: 'To 3!' }
  *   })
  * })
- * ```
  */
 export declare function updateCanvas(payload: PatchedCanvasUpdateRequest & {
     id: CanvasRetrieve['id'];

package/lib/sdk/api/modules/admin/env.admin.d.ts

@@ -3,8 +3,9 @@ import { AdminEnv } from './types.admin';
 /**
  * Fetches the necessary info for the app to know where it is embedded.
  *
- * ```
+ * Check out [usePitcherApi().getEnv()](../internal/functions/createHighLevelApi.md#getenv) for more information.
+ *
+ * @example
  * adminApi.getEnv()
- * ```
  */
 export declare function getEnv(): Promise<AdminEnv>;

package/lib/sdk/api/modules/admin/files.admin.d.ts

@@ -2,11 +2,13 @@ import { AdminSelectContentRequest, AdminSelectContentResponse } from './types.a
 import { File, PaginatedFileList } from '../../../../../types/openapi';
 
 /**
- * Fetches the config values for an installed app by its name.
+ * Get the metadata object of an app with a given name.
  *
- * ```
- * adminApi.getAppConfig({ app_name: 'my-app' })
- * ```
+ * @param {object} payload - The payload object.
+ * @param {string} payload.app_name - `name` value from `app.json` of the app you want to get the metadata of.
+ *
+ * @example
+ * useAdmin().getAppConfig({ app_name: 'my-app' })
  */
 export declare function getAppConfig(payload: {
     app_name: string;
@@ -14,9 +16,8 @@ export declare function getAppConfig(payload: {
 /**
  * Fetches a file by ID.
  *
- * ```
+ * @example
  * adminApi.getFile({ id: 'my-file-id' })
- * ```
  */
 export declare function getFile(payload: {
     id: File['id'];
@@ -24,14 +25,14 @@ export declare function getFile(payload: {
 /**
  * Lists available files.
  *
- * ```
+ * @example
  * adminApi.getFiles()
- * ```
  */
 export declare function getFiles(payload: Record<string, any>): Promise<PaginatedFileList>;
 /**
  * Opens a selector that allows you to select (and preselect) from your Pitcher uploaded content.
- * ```
+ *
+ * @example
  * const api = useApi() // or useAdmin() if you know that you 're in Admin app context
  * api
  *   .select_content({
@@ -44,6 +45,5 @@ export declare function getFiles(payload: Record<string, any>): Promise<Paginate
  *       },
  *     ],
  *   })
- * ```
  */
 export declare function selectContent(payload: AdminSelectContentRequest): Promise<AdminSelectContentResponse>;

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

@@ -1,6 +1,19 @@
 import { AdminToastRequest, ADMIN_MESSAGE_TYPES, AdminMessagePayloads } from './types.admin';
 
+/**
+ * Subscribe to a given event type by its key.
+ *
+ * @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(type: (typeof ADMIN_MESSAGE_TYPES)[keyof typeof ADMIN_MESSAGE_TYPES], handler: (data: AdminMessagePayloads[typeof type]) => Promise<void>): Promise<() => void>;
+/**
+ * Show a toast message to the user. Compatible with the UI API version of this method.
+ *
+ * @example
+ * useAdmin().toast({ type: 'info', message: 'Hello, world!' })
+ */
 declare function toast(payload: AdminToastRequest): Promise<void>;
 declare const _default: {
     getAppConfig(payload: {

package/lib/sdk/api/modules/admin/metadataTemplates.admin.d.ts

@@ -4,8 +4,7 @@ import { GetInstanceMetadataTemplatesPayload } from '../../../payload.types';
 /**
  * Fetches a list of metadata templates to use in your app. Instance is auto-injected by admin app if in instance scope.
  *
- * ```
+ * @example
  * adminApi.getInstanceMetadataTemplates()
- * ```
  **/
 export declare function getInstanceMetadataTemplates(payload?: GetInstanceMetadataTemplatesPayload): Promise<PaginatedMetadataTemplateList>;

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

@@ -26,42 +26,135 @@ export declare const ADMIN_API_METHOD_TYPES: {
 export type AdminMessagePayloads = {
     [ADMIN_MESSAGE_TYPES.ENV_CHANGED]: AdminEnv;
 };
+/**
+ * Represents an admin request with a specific payload.
+ * @template Payload - The type of the payload data.
+ */
 export type AdminRequest<Payload = any> = {
+    /**
+     * Unique identifier for the request.
+     */
     id: string;
+    /**
+     * Type of the admin API request.
+     */
     type: (typeof ADMIN_API_TYPES)['ADMIN_REQUEST'];
+    /**
+     * Body of the request containing the method type and payload data.
+     */
     body: {
+        /**
+         * Type of the admin API method.
+         */
         type: (typeof ADMIN_API_METHOD_TYPES)[keyof typeof ADMIN_API_METHOD_TYPES];
+        /**
+         * Payload data for the request.
+         */
         data: Payload;
     };
 };
+/**
+ * Represents a request to show a toast notification.
+ */
 export interface AdminToastRequest {
+    /**
+     * Type of the toast notification.
+     */
     type: 'info' | 'error' | 'warning' | 'success' | 'loading';
+    /**
+     * Message to be displayed in the toast.
+     */
     message: string;
+    /**
+     * Duration for which the toast should be displayed (optional).
+     */
     duration?: number;
+    /**
+     * Indicates if the toast can be closed manually (optional).
+     */
     closable?: boolean;
+    /**
+     * Indicates if the toast should remain visible when hovered over (optional).
+     */
     keepAliveOnHover?: boolean;
+    /**
+     * Indicates if an icon should be shown in the toast (optional).
+     */
     showIcon?: boolean;
 }
+/**
+ * Represents a request to select content.
+ */
 export type AdminSelectContentRequest = {
+    /**
+     * List of selections to be made (optional).
+     */
     selections?: Selection[];
 };
+/**
+ * Represents a response to a content selection request.
+ */
 export type AdminSelectContentResponse = {
+    /**
+     * Action taken by the user.
+     */
     user_action: 'cancelled' | 'selected';
+    /**
+     * Selected content, if any.
+     */
     content?: (ContentSelectorSelectedFile | ContentSelectorSelectedPage)[];
 };
+/**
+ * Represents an admin response with a specific payload.
+ * @template Response - The type of the response data.
+ */
 export type AdminResponse<Response = any> = {
+    /**
+     * Unique identifier for the response.
+     */
     id: string;
+    /**
+     * Type of the admin API response.
+     */
     type: (typeof ADMIN_API_TYPES)['ADMIN_RESPONSE'];
+    /**
+     * Body of the response containing the response data.
+     */
     body: Response;
 };
+/**
+ * Represents an admin message with a specific payload.
+ * @template Payload - The type of the message data.
+ */
 export type AdminMessage<Payload = any> = {
+    /**
+     * Unique identifier for the message.
+     */
     id: string;
+    /**
+     * Type of the admin message.
+     */
     type: typeof ADMIN_MESSAGE;
+    /**
+     * Body of the message containing the message type and payload data.
+     */
     body: {
+        /**
+         * Type of the admin message.
+         */
         type: (typeof ADMIN_MESSAGE_TYPES)[keyof typeof ADMIN_MESSAGE_TYPES];
+        /**
+         * Payload data for the message.
+         */
         data: Payload;
     };
 };
+/**
+ * Represents the admin environment.
+ */
 export type AdminEnv = {
+    /**
+     * Pitcher environment settings.
+     */
     pitcher: PitcherEnv['pitcher'];
 };

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

@@ -5,7 +5,7 @@ import { PaginatedData } from '../../../types/paginatedData';
 /**
  * Fetches a list of canvases to use in your app.
  *
- * ```
+ * @example
  * // The `filters` object is a reserved payload key to transfer the metadata dict over the wire.
  * api.getCanvases({
  *   search: 'my search query',
@@ -16,7 +16,6 @@ import { PaginatedData } from '../../../types/paginatedData';
  *   },
  *  fields: 'id,name,metadata',
  * })
- * ```
  */
 export declare function getCanvases(payload: GetCanvasesParams & {
     filters?: Record<string, any>;
@@ -29,7 +28,7 @@ export declare function deleteCanvas(payload: {
 /**
  * Updates a canvas by ID
  *
- * ```
+ * @example
  * // The fields param is appended to the URL as a query param.
  * onMounted(() => {
  *   PitcherAPI.updateCanvas({
@@ -40,7 +39,6 @@ export declare function deleteCanvas(payload: {
  *     console.log(res)  // logs: { id: '01HH4RCBH631K4JDHWAQB0RPR6', name: 'To 3!' }
  *   })
  * })
- * ```
  */
 export declare function updateCanvas(payload: PatchedCanvasUpdateRequest & {
     id: CanvasRetrieve['id'];

package/lib/sdk/api/modules/dsr/env.dsr.d.ts

@@ -1,10 +1,11 @@
 import { DsrEnv } from './types.dsr';
 
 /**
- * Fetches the necessary info for the app to know where it is embedded. LaunchDarkly flags are omitted for now as they are not yet used.
+ * Fetches the necessary info for the app to know where it is embedded.
  *
- * ```
+ * Check out [usePitcherApi().getEnv()](../internal/functions/createHighLevelApi.md#getenv) for more information.
+ *
+ * @example
  * useDsr().getEnv()
- * ```
  */
 export declare function getEnv(): Promise<DsrEnv>;

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

@@ -1,5 +1,12 @@
 import { DSR_MESSAGE_TYPES, DsrMessagePayloads } from './types.dsr';
 
+/**
+ * Subscribe to a given event type by its key.
+ *
+ * @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(type: (typeof DSR_MESSAGE_TYPES)[keyof typeof DSR_MESSAGE_TYPES], handler: (data: DsrMessagePayloads[typeof type]) => Promise<void>): Promise<() => void>;
 declare const _default: {
     embeddable_ready(): Promise<void>;

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

@@ -1 +1,7 @@
+/**
+ * Signal to DSR that the app is ready to be shown.
+ *
+ * @example
+ * useDsr().embeddable_ready()
+ */
 export declare function embeddable_ready(): Promise<void>;

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

@@ -1,6 +1,22 @@
 import { PitcherEnv } from '../../interfaces';
 import { User } from '../../../../types/openapi';
 
+/**
+ * Fetches the necessary info for the app to know where it is embedded.
+ *
+ * It contains information about:
+ * - user
+ * - instance
+ * - organization
+ * - security token to query Pitcher REST API
+ * - Salesforce connection information (if connected) including security token to query Salesforce REST API
+ * - Auth0 token information
+ *
+ * @example
+ * const env = usePitcherApi().getEnv().then((env) => {
+ *   console.log(env.pitcher.user.name)
+ * })
+ */
 export declare function getEnv(): Promise<PitcherEnv>;
 type UpdateEnvParams = Pick<User, 'language' | 'dark_mode'>;
 export declare function updateMyUser(payload: UpdateEnvParams): Promise<User>;

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

@@ -1,8 +1,17 @@
 import { Favorite, FavoriteCreateRequest, PaginatedFavoriteList } from '../../../../types/openapi';
 import { GetFavoritesParams } from '../../../types/favorites';
 
+/**
+ * Get a list of favorites
+ */
 export declare function getFavorites(payload?: GetFavoritesParams): Promise<PaginatedFavoriteList>;
+/**
+ * Create a favorite
+ */
 export declare function createFavorite(payload: FavoriteCreateRequest): Promise<Favorite>;
+/**
+ * Delete a favorite
+ */
 export declare function deleteFavorite(payload: {
     favorite_id: Favorite['id'];
 }): Promise<void>;

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

@@ -1,3 +1,6 @@
 import { SubmitUserFeedbackPayload } from '../../payload.types';
 
+/**
+ * Submit user feedback
+ */
 export declare function submitUserFeedback(payload: SubmitUserFeedbackPayload): Promise<any>;

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

@@ -27,9 +27,8 @@ export declare function createFile(payload: Omit<AllFileCreateRequest, 'instance
 /**
  * Dispatches iOS native file selector and returns the selected file.
  *
- * ```
+ * @example
  * // iOS only method to select a file from the device.
  * api.selectDeviceFile()
- * ```
  */
 export declare function selectDeviceFile(): Promise<DeviceFile>;

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

@@ -1,16 +1,45 @@
 import { File, Folder, FolderRetrieve, FolderCreateRequest, FolderUpdateRequest } from '../../../../types/openapi';
 
+/**
+ * Retrieves a folder by its ID.
+ * @param payload - An object containing the folder ID.
+ * @param payload.id - The ID of the folder to retrieve. Defaults to 'root'.
+ * @returns A promise that resolves to the retrieved folder.
+ */
 export declare function getFolder(payload?: {
     id: FolderRetrieve['id'];
 }): Promise<FolderRetrieve>;
+/**
+ * Creates a new folder.
+ * @param payload - The folder creation request payload, excluding the instance_id.
+ * @returns A promise that resolves to the created folder.
+ */
 export declare function createFolder(payload: Omit<FolderCreateRequest, 'instance_id'>): Promise<FolderRetrieve>;
 type UpdateFolderPayload = FolderUpdateRequest & {
     id: Folder['id'];
 };
+/**
+ * Updates an existing folder.
+ * @param payload - The folder update payload, including the folder ID and update data.
+ * @returns A promise that resolves to the updated folder.
+ */
 export declare function updateFolder(payload: UpdateFolderPayload): Promise<FolderRetrieve>;
+/**
+ * Deletes a folder.
+ * @param payload - An object containing the ID of the folder to delete.
+ * @param payload.folder_id - The ID of the folder to delete.
+ * @returns A promise that resolves when the folder is deleted.
+ */
 export declare function deleteFolder(payload: {
     folder_id: FolderRetrieve['id'];
 }): Promise<void>;
+/**
+ * Moves items (files or folders) to a target folder.
+ * @param payload - The payload containing the target folder ID and items to move.
+ * @param payload.target_folder_id - The ID of the target folder.
+ * @param payload.items - An array of items to move, each with an ID and type.
+ * @returns A promise that resolves to the updated target folder.
+ */
 export declare function moveFolderItems(payload: {
     target_folder_id: Folder['id'];
     items: {