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.
PrintOptions	Options for activity.print: openNative.
PrintResponse	A generated PDF result (plus openedNatively when openNative was requested).
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.
InsightSource	Alias of InsightWorkflowSource; accepted by insight.query.
InsightQueryResult	Ad-hoc query result: { headers, rows, details }.
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, scoped?: boolean }.
FileScope	{ _id, uid, workspaceId?, readers?: string[] } — workspaceId absent for an unscoped file.
FileListOptions	{ search?: string | string[], matchType?: 'all' | 'any', skip?, limit?, sortBy?: 'name' | 'created', reverse? }.
ScopedFile	{ _id, name, uid, workspaceId, type?, length?, created?, updated?, tags? }.
FileListResponse	{ files: ScopedFile[], hasMore, total }.

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).

Credentials

Type	Shape
CredentialType	'basic' | 'apiKey' | 'custom'.
CredentialData ★	The secret payload: CredentialBasicData | CredentialApiKeyData | CredentialCustomData.
CredentialBasicData	{ username, password }.
CredentialApiKeyData	{ apiKey }.
CredentialCustomData	Free-form JSON object (CredentialJsonValue values, 1–50 top-level keys).
CredentialCreateResponse	{ _id } — the new credential's id.
CredentialListItem ★	Metadata only: { _id, name, type, workspaceId?, appId?, readers?, createdBy, created, updated }.
CredentialDetails<T> ★	Decrypted result of get: { type, secret: T }.
CredentialUpdate	{ name?, secret? } — secret replaces the whole payload.
CredentialReader	network_<workspaceId> / team_<teamId> / user_<userId>; workspace credentials only.

Actions

Type	Shape
ActionTriggerTarget ★	{ actionId?, key?, workspaceId? } — one of actionId or key; workspaceId optional, needed with a key in a private app.
ActionRun ★	One run: { _id, actionId, workspaceId, event, triggeredBy?, status, exitCode?, output?, message?, wallTimeMs?, created, finishedAt? } plus admin-only arguments?, stdout?, stderr?, execRunId?.
ActionRunStatus	'queued' | 'running' | 'completed' | 'runtime_error' | 'timeout' | 'output_limit' | 'infra_error' | 'cancelled' | 'config_error' | 'denied'.
ActionEvent	'manual' for SDK-triggered runs; also the phase, workspace and schedule event names.
ACTION_RUN_ACTIVE_STATUSES	Constant ['queued', 'running'] — the non-terminal statuses.

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.