Types

Every method in the API is fully typed. This page catalogues the exported types so you can find the shape a method takes or returns. The authoritative source is src/types.ts and the per-module files (file, http, metrics). Import them from the package:

import type { Activity, Workflow, User, Signal, HailerError } from '@hailer/app-sdk';

★ marks the most commonly used entity/payload types.

Core entities

Type	Shape
User ★	A Hailer user. Only _id, firstname, lastname are populated on returned users.
Workspace ★	A workspace: _id, name.
Team	A team: { _id, name }.
TeamsByWorkspace	Map of workspaceId → Team[].
TeamAccount	An { account, team } pair.
Activity ★	A full activity: process, phase, fields, location, files, followers, etc.
Workflow ★	A workflow (process) definition: fields, phases, ordering, templates.
WorkflowField	One field definition on a workflow.
WorkflowFieldType	Union of field type strings.
WorkflowPhase	One phase in a workflow.
DocumentTemplate	A print/document template descriptor.
Config ★	App config: { [fieldName]: string }.
Settings ★	User UI settings: { theme: 'light' | 'dark'; preferredLanguages: string[] }.
Signal ★	A pushed signal: { name, data }.
ApiInfo	Return shape of HailerApi.info().

Activity field values

Type	Shape
ActivityFieldValue	Union of allowed field value shapes.
ActivityFieldUpdateValue	ActivityFieldValue | null (null clears the field).
ActivityFieldRange	{ start, end }.
ActivityFieldLink	Linked activity: { _id, name }.
ActivityFieldCountry	{ code } (ISO cca2).
ActivityFieldError	{ error? }.
ActivityLocation	Location geometry: { data[], label?, type }.
IdSetUpdate	Add/remove/replace map: '*'?: null, [id]: true | null.

Activity operations

Type	Shape
ActivityListOptions	List sort/paging/include flags.
ActivityCreateOptions	Create-time extras (team, files, followers, location, …).
ActivityUpdateOptions	Update-time extras.
ActivityKanbanListOptions	Kanban filter/search/paging.
PrintRequest	An activity print request.
PrintResponse	A generated PDF result.
KanbanListResponse	Phases→activities map with meta.
KanbanLoadResponse	A single activity in kanban form.

Insights

Type	Shape
InsightDoc ★	An insight document: presets, sources, publicKey.
InsightPublic	Omit<InsightDoc, '_id'>.
InsightData	RPC insight result: { headers, rows, time }.
InsightWorkflowSource	An insight data-source definition.
InsightResponse	Public insight result: { insight, data }.
InsightResponseData	Public insight data: { headers, rows, time }.
InsightResponseAsObjectItem / InsightResponseAsObjects	Rows mapped to objects.

Forms

Type	Shape
FormsData	Payload for a form submission.
FormsResponse	A public form's definition.
FormCreateResponse	Result of a form submission.

Permissions

Type	Shape
PermissionMap ★	Top-level per-user permission map (workflow + workspace), keyed by workspace.
PermissionType	'admin' | 'own' | 'ownteam' | 'any' | 'edit'.
PermissionPath	A permission grant path.
Member	A member with info + permissions.
WorkflowPermission / WorkflowPhasePermission	Permission-level unions.
WorkflowPermissionMap	Per-workflow permission structure.
WorkspaceRolesPermission	Role booleans (isAdmin, isOwner, …).

Products & marketplace

Type	Shape
Product ★	A marketplace product (extends ProductType).
ProductType	{ type?: 'app' | 'template' | 'integration' | 'expert' | 'ai-agent' }.
ProductVersion	A product with its versions.
Version	One version: { version, description, packageHash, created }.
ProductListResponse	{ products, totalCount }.
ProductSearchFilter	Search filter (extends ProductType).
ProductSearchOption	Search paging/sort.
IdsMap	{ [templateId]: string } install-id mapping.

Payments & pricing

Type	Shape
PricingData	Pricing configuration for a product.
PricingPlan	One pricing plan.
PaymentProvider / PricingProviders	Provider configuration.
CreatePricingRequest / UpdatePricingRequest	Pricing write requests.
CreatePurchaseRequest / CreatePurchaseResponse	Purchase flow.
Purchase	A purchase/subscription record.
StripeTaxCalculationRequest / StripeTaxCalculationResponse	Stripe tax calculation.

Files (from modules/file)

Type	Shape
FileResponse	{ filename, data (base64), mimeType, tags: string[] }.
UploadOptions	{ isPublic?: boolean }.

HTTP (from modules/http)

Type	Shape
HTTPFetchOptions	{ method?, headers?, body? }.
HTTPUploadEntry	{ name, value, filename? }.
HTTPFetchResponse	{ status, statusText, headers, body }.
HTTPWebSocket	Proxied WebSocket handle (send, close, on*, readyState, connectionId).

Metrics (from modules/metrics)

Type	Shape
MetricDefinition	A metric's descriptor.
MetricData	A metric's data.
MetricOptions	Query options (time range, aggregation, groupBy, topk, label filters).
WorkspaceMetricsListOptions / WorkspaceMetricsListResult	Admin workspace lookup.
UserMetricsListOptions / UserMetricsListResult	Admin user lookup.

Ball tracking

Type	Shape
BallHolderEntry ★	{ activityId, discussionId, activityName, ballHolder }.
BallHolder	{ userId, assignedAt }.

Errors

Type	Shape
HailerError ★	The error class thrown by every API method.
ApiError	Raw error: { code, msg, debug }.

Admin

The admin request/response types back hailer.admin (internal). They include AdminWorkspace, AdminWorkspaceListRequest / AdminWorkspaceListResponse, AdminWorkspaceOverrides, AdminWorkspaceMarketplaceSettings, AdminWorkspaceUsersListRequest / AdminWorkspaceUsersListResponse, AdminUpdateUserRequest / AdminUpdateUserResponse, AdminUpdateTokenBalanceRequest, AdminTokenTransaction*, AdminInvoice*, AdminRevenue*, AdminDashboard*, AdminReferral*, AdminCreateStripeSessionRequest / Response, and AdminCreateInvoiceIntegrationRequest / Response. See src/types.ts.