Server SDK
Read and write Pomavo data from your plugin backend with the typed PomavoClient: tickets, comments, links, attachments, automations, and more.
The PomavoClient
When your plugin needs to read or write Pomavo data - fetch a ticket, add a comment, run a query - it uses the PomavoClient from @pomavo/sdk/server. The client is a thin, typed wrapper over the Pomavo REST API, authenticated with an integration API key.
import { PomavoClient } from '@pomavo/sdk/server';
const client = new PomavoClient({
baseUrl: pomavoApiBaseUrl, // from the install event
apiKey: integrationApiKey, // from the install event's integrations[]
orgId: orgId, // the installing organization
});baseUrl, the integration apiKey, and the org are all delivered to your backend during the install lifecycle event. Store them per installation and construct a client per request.
Working with Tickets
// Fetch by numeric id or by sequence ("BUG-123")
const ticket = await client.getTicket(123);
const bySeq = await client.getTicketBySequence('BUG-123');
// Search with the Pomavo query language
const results = await client.searchTickets('status:open assignee:me', {
page: 1,
pageSize: 20,
});
// Create a ticket
const created = await client.createTicket({
clientTicketId: crypto.randomUUID(),
templateId: 1,
fields: [
{ templateFieldId: 'title', value: 'New task from my plugin' },
{ templateFieldId: 'description', value: 'Created via the SDK.' },
],
});
// Move it through its workflow
const transitions = await client.getTransitions(created.id);
await client.transitionTicket(created.id, transitions[0].toStateId);Comments, Links & Attachments
// Comments
await client.addComment(ticket.id, 'Synced from GitHub ✔');
const comments = await client.listComments(ticket.id);
// Links between tickets
const linkTypes = await client.listLinkTypes(ticket.id);
await client.linkTickets(ticket.id, otherTicket.id, linkTypes[0].id);
// Attachments
const files = await client.getAttachments(ticket.clientTicketId);
await client.uploadAttachment(ticket.id, buffer, 'report.pdf', 'application/pdf');API Surface
The client groups methods by resource. The most commonly used:
getTicket(id)
getTicketBySequence(sequenceNumber)
searchTickets(query, options)
createTicket(request)
updateTicket(id, request)
getTransitions(ticketId)
transitionTicket(ticketId, toStateId)Error Handling
Every failed request throws a PomavoApiError carrying the HTTP status and the response body, so you can branch on it precisely:
import { PomavoApiError } from '@pomavo/sdk/server';
try {
const ticket = await client.getTicket(123);
} catch (error) {
if (error instanceof PomavoApiError) {
console.error(`Pomavo API ${error.status}:`, error.message);
console.error('Body:', error.body);
} else {
throw error;
}
}TypeScript Types
The SDK ships full type definitions for the shapes you pass and receive:
import type {
Ticket,
Template,
Project,
CreateTicketRequest,
SearchResult,
} from '@pomavo/sdk/server';The integration API key carries exactly the permissions the installing org granted, based on the requestedPermissions from your manifest's resources.integrations. Calls outside those scopes fail with a 403, surfaced as a PomavoApiError.