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",
    })
  })

broadcastToWebviews()

broadcastToWebviews: (event) => Promise<any>

Broadcast an event to webviews only (iOS only).

Parameters

Parameter	Type	Description
event	PitcherEvent	The event to broadcast.

Returns

Promise<any>

Example

usePitcherApi()
  .broadcastToWebviews({
    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>

crmSmartDeleteObjects()

Deletes CRM objects from local CRM data (iOS only). Uses Salesforce Mobile SDK SmartStore to delete records. Each object in the payload specifies a table name and an array of IDs to delete.

Parameters

Parameter	Type	Description
payload	CRMSmartDeleteObjectsPayload	The delete payload containing an array of CRMDeleteObject items.

Returns

Promise<any>

• Promise resolving with the result of the delete operation.

Throws

• Throws an error if the payload is invalid.

Example

// iOS only method to delete CRM objects.
api.crmSmartDeleteObjects({
  objects: [
    {
      table_name: 'Account',
      ids: ['001xx000003DGbQAAW', '001xx000003DGbRABW']
    },
    {
      table_name: 'Contact',
      ids: ['003xx000004TmiQAAS']
    }
  ]
})

crmSmartObjectMetadata()

Retrieves metadata for a CRM smart object (iOS only). Fetches object metadata from the Salesforce Mobile SDK cache.

Parameters

Parameter	Type	Description
payload	CRMSmartObjectMetadataPayload	The payload containing the object name.

Returns

Promise<any>

• Promise resolving with the object metadata.

Throws

• Throws an error if the object name is not provided.

Example

// iOS only method to retrieve CRM object metadata.
api.crmSmartObjectMetadata({ object: 'Account' })

crmSmartObjectValidationRules()

Retrieves validation rules for a CRM smart object (iOS only). This method fetches the validation rules configured for a specific CRM object type from the local SmartStore cache.

Parameters

Parameter	Type	Description
payload	CRMSmartObjectValidationRulesPayload	The payload containing the object name.

Returns

Promise<any>

• Promise resolving with the validation rules for the specified object.

Examples

// iOS only method to get validation rules for an Account object.
api.crmSmartObjectValidationRules({ object: 'Account' })

// Get validation rules for a Contact object.
api.crmSmartObjectValidationRules({ object: 'Contact' })

crmSmartQuery()

Executes a SmartStore query against local CRM data (iOS only). Uses Salesforce Mobile SDK SmartStore query syntax. Validates that the query uses SmartStore syntax before execution.

Parameters

Parameter	Type	Description
payload	CRMQueryPayload	The query payload containing the SmartStore query string.

Returns

Promise<any[]>

• Promise resolving with an array of query results from SmartStore.

Throws

• Throws an error if the query is not a valid SmartStore query.

Example

// iOS only method to execute a SmartStore query.
api.crmSmartQuery({ query: 'SELECT {Account:Id}, {Account:Name} FROM {Account} ORDER BY {Account:Name} LIMIT 10' })

crmSmartUpsertObjects()

Upserts CRM objects into local CRM data (iOS only). Uses Salesforce Mobile SDK SmartStore to insert or update records. Each object in the payload specifies a table name, the objects to upsert, and an optional external ID path.

Important: Always provide external_id_path when performing updates to ensure records are matched correctly. Without it, the operation may create duplicate records instead of updating existing ones.

Note: When creating new records, you must provide an explicit identifier field (e.g., Id) in each record object passed from the frontend. The backend does not auto-generate IDs.

Parameters

Parameter	Type	Description
payload	UpsertCRMObjectsPayload	The upsert payload containing an array of UpsertCRMObject items.

Returns

Promise<any>

• Promise resolving with the result of the upsert operation.

Throws

• Throws an error if the payload is invalid.

Example

// iOS only method to upsert CRM objects.

// Updating existing records - always include external_id_path
api.crmSmartUpsertObjects({
  objects: [
    {
      table_name: 'Account',
      objects: [{ Id: '001xx000003DGbQAAW', Name: 'Acme Corp Updated' }],
      external_id_path: 'Id' // Required for updates to match existing records
    }
  ]
})

// Creating new records - explicit ID required in each record
api.crmSmartUpsertObjects({
  objects: [
    {
      table_name: 'Account',
      objects: [
        { Id: '001xx000003NEW001', Name: 'New Company' }, // Explicit ID required
        { Id: '001xx000003NEW002', Name: 'Another Company' }
      ]
    }
  ]
})

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.

deleteLocalFile()

Deletes a local file on iOS devices from Pitcher Folders.

Parameters

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

Returns

Promise<void>

Example

// iOS only method to delete a local file.
api.deleteLocalFile({ url: 'file:///var/mobile/Containers/Data/Application/x/Documents/Pitcher%20Folders/ARPhotocapture/x.png' })

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>