Function: usePitcherApi()

usePitcherApi(options?): object

Check out the returned object documentation for the list of available methods.

Parameters

Parameter	Type
options?	ApiOptions

Returns

object

API

API: LowLevelApi

broadcast()

broadcast: (event) => Promise<any>

Broadcast an event to CatalogIQ.

Parameters

Parameter	Type	Description
event	PitcherEvent	The event to broadcast.

Returns

Promise<any>

Example

usePitcherApi()
  .broadcast({
    type: "canvas_updated",
    body: { context: { myContextProperty: 'test' } },
  })
  .then(function (result) {
    useUi().toast({
      message: "Canvas Populated.",
      type: "info",
    })
  })

enterFullscreen()

enterFullscreen: () => Promise<any>

Make the entire CatalogIQ fullscreen.

Returns

Promise<any>

Example

usePitcherApi().enterFullscreen()

exitFullscreen()

exitFullscreen: () => Promise<any>

Exit fullscreen mode.

Returns

Promise<any>

Example

usePitcherApi().exitFullscreen()

getRequestTypes()

getRequestTypes: () => Promise<any>

Get the request types.

Returns

Promise<any>

isFullscreen()

isFullscreen: () => Promise<any>

Return is CatalogIQ in fullscreen.

Returns

Promise<any>

Example

usePitcherApi().isFullscreen()

logout()

logout: () => Promise<any>

Log out the current user.

Returns

Promise<any>

Example

usePitcherApi().logout()

off()

off: (type, callback) => void

Unsubscribe from a given event type by its key and the attached callback reference.

Parameters

Parameter	Type	Description
type	string	The event type to unsubscribe from.
callback	(payload) => void	The callback function reference to remove.

Returns

void

Example

const callback = (event: object) => {
  // handle event
}
usePitcherApi().on('entered_fullscreen', callback)
// later
usePitcherApi().off('entered_fullscreen', callback)

on()

on: (type, callback) => void

Subscribe to a given event type by its key.

Parameters

Parameter	Type	Description
type	string	The event type to subscribe to.
callback	(payload) => void	The callback function to handle the event.

Returns

void

A Promise resolving to a cleanup function to unsubscribe from the event. *

Examples

const unsubscribeFromSectionListUpdate = usePitcherApi().on('entered_fullscreen', (event: object) => {
  // handle event
})
// later
unsubscribeFromSectionListUpdate()

quitInstance()

quitInstance: () => Promise<any>

Quit the current instance and go to the instance selection screen.

Returns

Promise<any>

Example

usePitcherApi().quitInstance()

subscribe()

subscribe: () => Promise<any>

Subscribe to updates.

Returns

Promise<any>

unsubscribe()

unsubscribe: () => Promise<any>

Unsubscribe from updates.

Returns

Promise<any>

assignCanvasTheme()

Parameters

Parameter	Type
payload	{ canvas_id: string; theme_id: string; }
payload.canvas_id	string
payload.theme_id	string

Returns

Promise<{ canvas_id: string; theme_id: string; }>

close()

Returns

Promise<any>

createCanvas()

Parameters

Parameter	Type
payload	Omit<CanvasCreateRequest, "instance_id">

Returns

Promise<CanvasRetrieve>

createEvent()

Parameters

Parameter	Type
payload	EventRequest

Returns

Promise<Event>

createFavorite()

Create a favorite

Parameters

Parameter	Type
payload	FavoriteCreateRequest

Returns

Promise<Favorite>

createFile()

Parameters

Parameter	Type
payload	Omit<AllFileCreateRequest, "instance_id">

Returns

Promise<FileRetrieve>

createFolder()

Creates a new folder.

Parameters

Parameter	Type	Description
payload	Omit<FolderCreateRequest, "instance_id">	The folder creation request payload, excluding the instance_id.

Returns

Promise<FolderRetrieve>

A promise that resolves to the created folder.

crmQuery()

Parameters

Parameter	Type
payload	CRMQueryPayload

Returns

Promise<any>

deleteCanvas()

Parameters

Parameter	Type
payload	{ id: string; }
payload.id	string

Returns

Promise<CanvasRetrieve>

deleteEvent()

Parameters

Parameter	Type
payload	Partial<Event>

Returns

Promise<void>

deleteFavorite()

Delete a favorite

Parameters

Parameter	Type
payload	{ favorite_id: string; }
payload.favorite_id	string

Returns

Promise<void>

deleteFile()

Parameters

Parameter	Type
payload	{ file_id: string; }
payload.file_id	string

Returns

Promise<string>

deleteFolder()

Deletes a folder.

Parameters

Parameter	Type	Description
payload	{ folder_id: string; }	An object containing the ID of the folder to delete.
payload.folder_id	string	The ID of the folder to delete.

Returns

Promise<void>

A promise that resolves when the folder is deleted.

downloadFile()

Parameters

Parameter	Type
payload	{ file_id: string; }
payload.file_id	string

Returns

Promise<null>

fetchDocumentInfo()

Parameters

Parameter	Type
payload	{ fileId: string; }
payload.fileId	string

Returns

Promise<{ [key: string]: unknown; pageCount: number; }>

Deprecated

• not used anymore

getAppConfig()

Parameters

Parameter	Type
payload	{ app_name: string; }
payload.app_name	string

Returns

Promise<Record<string, any>>

getCanvas()

Parameters

Parameter	Type
payload	{ fields: string; id: string; }
payload.fields?	string
payload.id	string

Returns

Promise<CanvasRetrieve>

getCanvases()

Fetches a list of canvases to use in your app.

Parameters

Parameter	Type
payload	GetCanvasesParams & object

Returns

Promise<PaginatedData<CanvasRetrieve>>

Example

// The `filters` object is a reserved payload key to transfer the metadata dict over the wire.
api.getCanvases({
  search: 'my search query',
  ordering: '-created_at',
  filters: {
    metadata__mydaterangefiltername__range: ['2023-12-10', '2023-12-22'],
    metadata__mymultiselectfiltername: ['optionAValue', 'optionCValue'],
  },
 fields: 'id,name,metadata',
})

getCanvasRecommendedFiles()

Parameters

Parameter	Type
payload	{ canvas_id: string; match: ("metadata" | "tags")[]; }
payload.canvas_id	string
payload.match?	("metadata" | "tags")[]

Returns

Promise<CanvasRecommendedFiles>

getCanvasTheme()

Parameters

Parameter	Type
payload	{ canvas_id: string; }
payload.canvas_id	string

Returns

Promise<CanvasThemeRetrieve>

getCoreFolders()

Parameters

Parameter	Type
payload	{ entity: CoreFolderEntityType; instance_id: string; parent_id: null | string; }
payload.entity	CoreFolderEntityType
payload.instance_id	string
payload.parent_id?	null | string

Returns

Promise<CoreFolderContentsRetrieve>

getEnv()

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

Returns

Promise<PitcherEnv>

Example

const env = usePitcherApi().getEnv().then((env) => {
  console.log(env.pitcher.user.name)
})

getEvents()

Parameters

Parameter	Type
payload	Partial<EventRequest>

Returns

Promise<PaginatedData<Event>>

getFavorites()

Get a list of favorites

Parameters

Parameter	Type
payload?	GetFavoritesParams

Returns

Promise<PaginatedFavoriteList>

getFile()

Parameters

Parameter	Type
payload	{ file_id: string; id: string; }
payload.file_id?	string
payload.id?	string

Returns

Promise<FileRetrieve>

getFileRevisionData()

Parameters

Parameter	Type
payload	{ file_id: string; revision_id: string; }
payload.file_id	string
payload.revision_id	string

Returns

Promise<FileRetrieve>

getFileRevisions()

Parameters

Parameter	Type
payload	{ file_id: string; id: string; }
payload.file_id?	string
payload.id?	string

Returns

Promise<FileRevision[]>

getFiles()

Parameters

Parameter	Type
payload	Partial<Omit<File, "type">> & object & object

Returns

Promise<PaginatedFileList>

getFolder()

Retrieves a folder by its ID.

Parameters

Parameter	Type	Description
payload	{ id: string; }	An object containing the folder ID.
payload.id	string	The ID of the folder to retrieve. Defaults to 'root'.

Returns

Promise<FolderRetrieve>

A promise that resolves to the retrieved folder.

getFolders()

Retrieves a list of folders.

Parameters

Parameter	Type	Description
payload	FolderListRequest	The payload containing the search, ordering, filters, fields, name, page, and page_size.

Returns

Promise<PaginatedFolderList>

A promise that resolves to the list of folders.

getInstanceMetadataTemplates()

Parameters

Parameter	Type
payload?	GetInstanceMetadataTemplatesPayload

Returns

Promise<PaginatedMetadataTemplateList>

getLanguages()

Fetches available languages for the logged-in user

Returns

Promise<Language[]>

getRecentFiles()

Parameters

Parameter	Type
payload?	GetRecentFilesPayload

Returns

Promise<File[]>

getThemes()

Parameters

Parameter	Type
payload	Partial<CanvasThemeRetrieve>

Returns

Promise<CanvasThemeRetrieve[]>

getUsers()

Parameters

Parameter	Type
payload?	GetUsersParams

Returns

Promise<PaginatedData<User>>

isOffline()

Returns

Promise<boolean>

moveFolderItems()

Moves items (files or folders) to a target folder.

Parameters

Parameter	Type	Description
payload	{ items: object[]; target_folder_id: string; }	The payload containing the target folder ID and items to move.
payload.items	object[]	An array of items to move, each with an ID and type.
payload.target_folder_id	string	The ID of the target folder.

Returns

Promise<FolderRetrieve>

A promise that resolves to the updated target folder.

notify()

Parameters

Parameter	Type
payload	NotificationPayload

Returns

Promise<void>

open()

Open a file in the CatalogIQ instance.

Parameters

Parameter	Type
payload	OpenRequestPayload

Returns

Promise<string>

openExternalUrl()

Open external URL in a new tab. Works on both web and mobile.

Parameters

Parameter	Type
payload	OpenExternalUrlRequestPayload

Returns

Promise<void>

openWebViewAlwaysOnTop()

Parameters

Parameter	Type
payload	OpenWebViewAlwaysOnTop

Returns

Promise<void>

patchCoreFolder()

Parameters

Parameter	Type
id	string
payload	Partial<CoreFolderRetrieve>

Returns

Promise<CoreFolderContentsRetrieve>

query()

Parameters

Parameter	Type
payload	QueryPayload

Returns

Promise<any>

refreshAccessToken()

Returns

any

refreshServiceToken()

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.

Parameters

Parameter	Type
payload?	RefreshServiceTokenRequest

Returns

Promise<RefreshServiceTokenResponse>

Promise resolving to an object containing the token

renderPageAsImage()

Renders a page from a file together with annotations.

Parameters

Parameter	Type	Description
payload	{ documentId: string; fileId: string; pageIndex: number; params: { width: number; } | { height: number; }; }	-
payload.documentId?	string	The ID of the document to render (optional). If not provided the fileId will be used.
payload.fileId	string	The ID of the file to render. Used when the documentId is not available.
payload.pageIndex	number	The index of the page to render.
payload.params	{ width: number; } | { height: number; }	The parameters to use for rendering the page.

Returns

Promise<ArrayBuffer>

A promise that resolves with the image as an ArrayBuffer.

Example

api.renderPageAsImage({
  fileId: '123456',
  documentId: '654321',
  pageIndex: 0,
  params: { width: 1920 },
})

search()

Parameters

Parameter	Type
payload	{ includeExpired: boolean; query: string; }
payload.includeExpired?	boolean
payload.query	string

Returns

Promise<any>

selectDeviceFile()

Dispatches iOS native file selector and returns the selected file.

Returns

Promise<DeviceFile>

Example

// iOS only method to select a file from the device.
api.selectDeviceFile()

share()

Dispatch iOS sharing dialog.

Parameters

Parameter	Type
payload	SharePayload

Returns

Promise<ShareResponse>

Example

api.share({text: "example text", subject: "example subject"})

shareCanvas()

Parameters

Parameter	Type
payload	{ id: string; }
payload.id	string

Returns

Promise<SharedLink>

showPeerSession()

Show peer session dialog with button coordinates, for local peer sharing feature.

Parameters

Parameter	Type
payload	ShowPeerSessionRequestPayload

Returns

Promise<void>

Example

api.showPeerSession({x: 100, y: 200})

showSyncbox()

Parameters

Parameter	Type
payload	ShowSyncboxRequestPayload

Returns

Promise<void>

submitUserFeedback()

Submit user feedback

Parameters

Parameter	Type
payload	SubmitUserFeedbackPayload

Returns

Promise<any>

toast()

Parameters

Parameter	Type
payload	{ message: string; type: string; }
payload.message	string
payload.type	string

Returns

Promise<void>

track()

Parameters

Parameter	Type
payload	{ event_name: string; payload: any; }
payload.event_name	string
payload.payload	any

Returns

Promise<any>

triggerNonFilesSync()

Dispatches iOS only sync method for non-files.

Returns

Promise<void>

Example

// iOS only method to sync non-files from the server.
api.triggerNonFilesSync()

unassignCanvasTheme()

Parameters

Parameter	Type
payload	{ canvas_id: string; }
payload.canvas_id	string

Returns

Promise<void>

updateCanvas()

Updates a canvas by ID

Parameters

Parameter	Type
payload	PatchedCanvasUpdateRequest & object

Returns

Promise<CanvasRetrieve>

Example

// The fields param is appended to the URL as a query param.
onMounted(() => {
  PitcherAPI.updateCanvas({
    id: '01HH4RCBH631K4JDHWAQB0RPR6',
    fields: 'id,name',
    name: 'To 3!',
  }).then((res) => {
    console.log(res)  // logs: { id: '01HH4RCBH631K4JDHWAQB0RPR6', name: 'To 3!' }
  })
})

updateCanvasIndicators()

Updates canvas indicators by canvas ID. It merges the passed object into existing canvas indicators adding new keys if they were empty and overriding pre-existing keys.

Indicators can also be updated using updateCanvas API but in this case passed object fully replaces existing indicators.

Parameters

Parameter	Type
payload	{ id: string; indicators: Record<string, CanvasIndicator>; instance_id: string; }
payload.id	string
payload.indicators	Record<string, CanvasIndicator>
payload.instance_id?	string

Returns

Promise<CanvasRetrieve>

Example

// The fields param is appended to the URL as a query param.
onMounted(() => {
  PitcherAPI.updateCanvasIndicators({
    id: '01J9XT0WVXRTETF4CQZP42CPZP',
    indicators: {
      existing: { type: 'info', label: 'new label' }, // will be overriden
      new: { type: 'info', label: 'INFO' }, // will be added
      removeExisting: null // will be set to null and ignored, it is the same as removal
   }
   }).then((res) => {
    console.log(res)  // entire canvas object, including indicators field
  })
})

updateEvent()

Parameters

Parameter	Type
payload	PatchedEventRequest

Returns

Promise<Event>

updateFile()

Parameters

Parameter	Type
payload	FileUpdateRequest & object

Returns

Promise<FileRetrieve>

updateFolder()

Updates an existing folder.

Parameters

Parameter	Type	Description
payload	UpdateFolderPayload	The folder update payload, including the folder ID and update data.

Returns

Promise<FolderRetrieve>

A promise that resolves to the updated folder.

updateMyUser()

Parameters

Parameter	Type
payload	UpdateEnvParams

Returns

Promise<User>