@saturation-api/js
Version:
TypeScript SDK for the Saturation API
2,397 lines • 113 kB
TypeScript
export type Project = {
/**
* Project identifier (alias in user mode, UUID in system mode)
*/
id: string;
/**
* Project display name
*/
name?: string | null;
/**
* Project icon or emoji
*/
icon?: string | null;
/**
* Project image URL
*/
imageUrl?: string | null;
/**
* Associated project space ID (deprecated, use space object)
*/
spaceId?: string | null;
/**
* Project space/folder information
*/
space?: {
/**
* Space identifier
*/
id?: string;
/**
* Space display name
*/
name?: string;
} | null;
/**
* Template project ID (deprecated, use template object)
*/
templateId?: string | null;
/**
* Template project information
*/
template?: {
/**
* Template identifier
*/
id?: string;
/**
* Template name
*/
name?: string;
} | null;
/**
* Project status
*/
status: 'active' | 'archived';
/**
* Project labels for categorization
*/
labels?: Array<string>;
/**
* Project creation timestamp
*/
createdAt: string;
/**
* Project last update timestamp
*/
updatedAt: string;
};
export type CreateProjectInput = {
/**
* Project display name (defaults to "Untitled Project")
*/
name?: string | null;
/**
* Project icon or emoji
*/
icon?: string | null;
/**
* Project image URL
*/
imageUrl?: string | null;
/**
* Associated project space ID
*/
spaceId?: string | null;
/**
* Project status
*/
status?: 'active' | 'archived';
/**
* Template project ID if creating from template
*/
templateId?: string | null;
/**
* Labels to assign to the project (will be created if they don't exist)
*/
labels?: Array<string>;
};
export type UpdateProjectInput = {
/**
* Project display name
*/
name?: string | null;
/**
* Project icon or emoji
*/
icon?: string | null;
/**
* Project image URL
*/
imageUrl?: string | null;
/**
* Associated project space ID
*/
spaceId?: string | null;
/**
* Project status
*/
status?: 'active' | 'archived';
/**
* Labels for the project (replaces all existing labels)
*/
labels?: Array<string>;
};
/**
* Request body for creating budget lines within an account.
* If the target account doesn't exist, it will be automatically created along with any necessary parent accounts.
*
*/
export type CreateBudgetInput = {
/**
* Target account ID or account code where lines will be added. Use "root" for top-level budget.
* The account must already exist in the budget hierarchy.
*
*/
accountId?: string;
/**
* Array of budget lines to create (line items, accounts, subtotals, or markups)
*/
lines?: Array<{
/**
* Type of budget line
*/
type?: 'line' | 'account' | 'subtotal' | 'markup';
/**
* Account code or ID
*/
accountId?: string;
/**
* Line description
*/
description?: string;
/**
* Phase-specific data
*/
phaseData?: {
[key: string]: unknown;
};
}>;
/**
* Where to insert the new lines
*/
insert?: {
mode?: 'append' | 'prepend' | 'after' | 'before';
/**
* Line ID for after/before mode
*/
lineId?: string;
};
/**
* ID interpretation mode - "user" for human-friendly IDs (default), "system" for database IDs
*/
idMode?: 'user' | 'system';
};
export type Budget = {
account: Account;
/**
* Sub-account hierarchy
*/
subAccounts?: {
[key: string]: Account;
};
/**
* Budget phases
*/
phases?: Array<Phase>;
/**
* Fringe benefits
*/
fringes?: Array<Fringe>;
/**
* Global variables
*/
globals?: Array<Global>;
};
export type Account = {
/**
* Account system identifier
*/
id: string;
/**
* User-friendly account code/number
*/
accountId?: string | null;
/**
* Account description
*/
description?: string | null;
/**
* Hierarchical path in budget tree
*/
path: string;
/**
* Budget lines within this account
*/
lines: Array<BudgetLine>;
/**
* Calculated totals for each phase
*/
totals: {
[key: string]: number;
};
contact?: Contact;
/**
* Last modification time (ISO 8601). Updated whenever the actual or any of its persisted fields change
*/
readonly lastModified?: string;
};
/**
* Lightweight account representation for listing endpoints
*/
export type AccountSummary = {
/**
* Account system identifier
*/
id: string;
/**
* User-friendly account code/number
*/
accountId: string | null;
/**
* Hierarchical path in budget tree
*/
path: string;
/**
* Account description
*/
description: string | null;
/**
* Last modification time (ISO 8601). Updated whenever this sub-actual or any of its persisted fields change
*/
readonly lastModified?: string;
};
export type BudgetLine = {
/**
* Type of budget line
*/
type: 'line' | 'account' | 'subtotal' | 'markup' | 'fringes';
/**
* Budget line identifier (system ID)
*/
id: string;
/**
* Account identifier (user-friendly ID like account code)
*/
accountId?: string | null;
/**
* Budget line description
*/
description?: string | null;
/**
* Hierarchical path in budget tree (e.g., /2000/2150)
*/
path: string;
/**
* Calculated totals for each phase
*/
totals: {
[key: string]: number;
};
/**
* Tags for categorization and filtering
*/
tags?: Array<string>;
contact?: Contact;
/**
* Detailed phase-specific data (expandable)
*/
phaseData?: {
[key: string]: LinePhaseData;
};
/**
* Last modification time (ISO 8601)
*/
lastModified?: string;
};
export type BudgetLineItem = BudgetLine & {
type: 'line';
} & {
/**
* Always "line" for regular budget line items
*/
type?: 'line';
};
export type BudgetAccountLine = BudgetLine & {
type: 'account';
} & {
/**
* Always "account" for account lines
*/
type?: 'account';
};
export type BudgetSubtotalLine = BudgetLine & {
type: 'subtotal';
} & {
/**
* Always "subtotal" for subtotal lines
*/
type?: 'subtotal';
/**
* URL-friendly slug derived from description
*/
alias?: string | null;
/**
* Visual color for UI display
*/
color?: 'red' | 'rose' | 'pink' | 'fuchsia' | 'purple' | 'violet' | 'indigo' | 'blue' | 'sky' | 'cyan' | 'teal' | 'green' | 'yellow' | 'amber' | 'orange';
};
export type BudgetMarkupLine = BudgetLine & {
type: 'markup';
} & {
/**
* Always "markup" for markup/overhead lines
*/
type?: 'markup';
/**
* Account IDs this markup applies to
*/
includeAccounts?: Array<string>;
};
export type BudgetFringeLine = BudgetLine & {
type: 'fringes';
} & {
/**
* Always "fringes" for fringe benefit lines
*/
type?: 'fringes';
/**
* Detailed fringe calculations by phase and type
*/
breakdown?: {
[key: string]: {
[key: string]: FringeBreakdown;
};
};
};
export type LinePhaseData = {
/**
* Quantity value for calculations
*/
quantity?: number | null;
/**
* Unit of measurement
*/
unit?: string | null;
/**
* Rate per unit
*/
rate?: number | null;
/**
* Multiplier factor
*/
multiplier?: number | null;
/**
* Applied fringe benefit IDs
*/
fringes?: Array<string>;
/**
* Date range for this phase data
*/
date?: {
startDate?: string | null;
endDate?: string | null;
};
/**
* Overtime hours
*/
overtime?: number | null;
overtimeDetail?: OvertimeDetail;
/**
* Formula for dynamic quantity calculation
*/
quantityFormula?: string;
/**
* Formula for dynamic rate calculation
*/
rateFormula?: string;
/**
* Formula for dynamic multiplier calculation
*/
multiplierFormula?: string;
/**
* Total fringe benefit amount
*/
fringeTotal?: number;
/**
* Breakdown of fringe calculations
*/
fringeBreakdown?: {
[key: string]: FringeBreakdown;
};
};
export type FringeBreakdown = {
/**
* Fringe benefit identifier
*/
id: string;
/**
* Fringe code (e.g., FICA, HEALTH)
*/
code?: string | null;
/**
* Calculated fringe amount
*/
amount: number;
};
export type OvertimeDetail = {
/**
* Overtime calculation mode
*/
mode: 'formula' | 'flat';
/**
* Fixed overtime amount (for flat mode)
*/
flatAmount?: number;
/**
* Number of overtime hours
*/
overtimeHours?: number;
/**
* Regular hours before overtime
*/
baseHours: number;
/**
* Overtime multiplier thresholds
*/
multipliers?: Array<{
/**
* Hour threshold for this multiplier
*/
threshold?: number;
/**
* Multiplier rate (e.g., 1.5 for time-and-a-half)
*/
multiplier?: number;
}>;
};
export type Phase = {
/**
* Phase type
*/
type: 'estimate' | 'actual' | 'rollup' | 'committed';
/**
* Phase system identifier
*/
id: string;
/**
* User-friendly phase alias
*/
alias: string;
/**
* Phase display name
*/
name?: string | null;
/**
* Whether phase is hidden from view
*/
isHidden: boolean;
/**
* Whether phase is locked from editing
*/
isLocked: boolean;
/**
* Currency configuration (for estimate phases)
*/
currency?: {
/**
* ISO 4217 currency code
*/
code?: string | null;
/**
* Currency symbol
*/
symbol?: string | null;
/**
* Exchange rate multiplier
*/
exchangeRate?: number | null;
} | null;
/**
* Rollup operation (for rollup phases)
*/
operation?: 'sum' | 'difference';
/**
* Phase IDs to aggregate (for rollup phases)
*/
phaseIds?: Array<string>;
/**
* Last modification time (ISO 8601)
*/
lastModified: string;
};
export type Fringe = {
/**
* Fringe system identifier
*/
id: string;
/**
* User-friendly fringe code
*/
code?: string | null;
/**
* Fringe benefit description
*/
description?: string | null;
/**
* Fringe calculation units
*/
units: 'percent' | 'flat' | 'total';
/**
* Fringe rate (decimal for percent, amount for flat)
*/
rate?: number | null;
/**
* Maximum salary subject to this fringe
*/
cutoff?: number | null;
/**
* Last modification time (ISO 8601)
*/
lastModified: string;
};
export type Global = {
/**
* Global variable system identifier
*/
id: string;
/**
* Variable symbol for use in formulas
*/
symbol?: string | null;
/**
* Variable description
*/
description?: string | null;
/**
* Unit of measurement
*/
unit?: string | null;
/**
* Formula expression for calculating value
*/
formula?: string | null;
/**
* Last modification time (ISO 8601)
*/
lastModified: string;
};
export type Actual = {
/**
* Actual entry identifier
*/
id: string;
/**
* Actual entry description
*/
description?: string | null;
/**
* Actual amount
*/
amount?: number | null;
/**
* Actual entry date
*/
date?: string | null;
/**
* Associated account ID(s)
*/
accountId?: string | null | Array<string>;
/**
* Whether this actual has sub-actuals
*/
expanded: boolean;
/**
* Actual entry type
*/
type?: string;
/**
* Attached files
*/
attachments?: Array<File>;
/**
* Reference identifier
*/
ref?: string | null;
/**
* Payment identifier
*/
payId?: string | null;
/**
* Actual entry status
*/
status?: string;
/**
* Additional notes
*/
notes?: string | null;
/**
* Associated tags
*/
tags?: Array<string>;
/**
* Associated purchase order ID
*/
purchaseOrderId?: string | null;
/**
* Associated transaction ID
*/
transactionId?: string | null;
contact?: Contact;
/**
* Sub-actual entries
*/
subactuals?: Array<SubActual>;
account?: BudgetLine;
/**
* Last modification time (ISO 8601)
*/
lastModified: string;
};
export type SubActual = {
/**
* Sub-actual identifier
*/
id: string;
/**
* Sub-actual description
*/
description?: string | null;
/**
* Sub-actual amount
*/
amount: number;
/**
* Sub-actual date
*/
date?: string | null;
/**
* Associated account ID
*/
accountId?: string | null;
account?: BudgetLine;
/**
* Last modification time (ISO 8601)
*/
lastModified: string;
};
export type Contact = {
/**
* Contact identifier
*/
id: string;
/**
* Contact display title
*/
contactTitle?: string | null;
/**
* Contact name
*/
name?: string | null;
/**
* Contact email address
*/
email?: string | null;
/**
* Contact company
*/
company?: string | null;
/**
* Contact type (Person, Company, etc.)
*/
type?: string | null;
/**
* Contact job title
*/
jobTitle?: string | null;
/**
* Contact hourly rate
*/
rate?: number | null;
/**
* Last modification time (ISO 8601)
*/
lastModified: string;
secureInfo?: ContactSecureInfo;
origin?: ContactOrigin;
/**
* Startwork agreements
*/
startwork?: Array<ContactStartwork>;
linkedUser?: ContactUser;
/**
* Banking information
*/
bankInfo?: Array<ContactBankAccount>;
/**
* Tax documents
*/
taxDocuments?: Array<File>;
/**
* File attachments
*/
attachments?: Array<File>;
/**
* Associated projects
*/
projects?: {
[key: string]: ContactProject;
};
};
export type ContactSecureInfo = {
/**
* Contact address
*/
address?: string | null;
/**
* Contact phone number
*/
phone?: string | null;
/**
* Last 4 digits of tax ID
*/
taxIdLast4?: string | null;
};
export type ContactOrigin = {
/**
* How the contact was created
*/
origin?: 'onboarding' | 'manual';
/**
* Contact creation timestamp
*/
createdAt?: string | null;
createdByUser?: ContactUser;
};
export type ContactStartwork = {
/**
* Startwork agreement identifier
*/
id: string;
/**
* Agreement title
*/
title: string;
/**
* Signature timestamp
*/
signedOn: string;
};
export type ContactUser = {
/**
* User identifier
*/
id: string;
/**
* User name
*/
name: string;
/**
* User email address
*/
email: string;
};
export type ContactBankAccount = {
/**
* Bank account identifier
*/
id: string;
/**
* Bank name
*/
bankName: string;
/**
* Account type (checking, savings, etc.)
*/
accountType: string;
/**
* Last 4 digits of account number
*/
accountLast4: string;
};
/**
* Input for creating a new contact
*/
export type CreateContactInput = {
/**
* Contact name
*/
name: string;
/**
* Contact email address
*/
email?: string;
/**
* Company name
*/
company?: string;
/**
* Contact type
*/
type?: 'Person' | 'Company';
/**
* Job title
*/
jobTitle?: string;
/**
* Hourly rate
*/
rate?: number;
/**
* Phone number
*/
phone?: string;
/**
* Physical address
*/
address?: string;
/**
* Last 4 digits of tax ID
*/
taxIdLast4?: string;
};
/**
* Input for updating an existing contact
*/
export type UpdateContactInput = {
/**
* Contact name
*/
name?: string;
/**
* Contact email address
*/
email?: string;
/**
* Company name
*/
company?: string;
/**
* Contact type
*/
type?: 'Person' | 'Company';
/**
* Job title
*/
jobTitle?: string;
/**
* Hourly rate
*/
rate?: number;
/**
* Phone number
*/
phone?: string;
/**
* Physical address
*/
address?: string;
/**
* Last 4 digits of tax ID
*/
taxIdLast4?: string;
};
export type ContactProject = {
/**
* Project identifier
*/
id: string;
/**
* Project name
*/
name: string;
/**
* Project alias
*/
alias: string;
/**
* Associated accounts within this project
*/
accounts?: Array<ContactProjectAccount>;
};
export type ContactProjectAccount = {
/**
* Account identifier
*/
accountId: string;
/**
* Account number
*/
accountNumber: string;
/**
* Account name
*/
accountName: string;
};
export type PurchaseOrder = {
/**
* Purchase order identifier
*/
id: string;
/**
* Purchase order number
*/
purchaseOrderId?: string | null;
/**
* Purchase order title
*/
title?: string | null;
/**
* Purchase order date
*/
date?: string | null;
/**
* Total amount
*/
amount: number;
/**
* Amount paid
*/
paidAmount: number;
/**
* Purchase order status
*/
status: 'draft' | 'approved' | 'rejected' | 'pending' | 'paid';
/**
* Attached files
*/
attachments?: Array<File>;
/**
* Additional notes
*/
notes?: string | null;
/**
* Line items
*/
items?: Array<PurchaseOrderItem>;
contact?: Contact;
/**
* Associated actual entries
*/
actuals?: Array<Actual>;
/**
* Last modification time (ISO 8601)
*/
lastModified: string;
};
/**
* Input for creating a new purchase order
*/
export type CreatePurchaseOrderInput = {
/**
* Purchase order number
*/
purchaseOrderId?: string;
/**
* Purchase order title
*/
title?: string;
/**
* Purchase order date
*/
date?: string;
/**
* Total amount
*/
amount: number;
/**
* Purchase order status
*/
status?: 'draft' | 'approved' | 'rejected' | 'pending' | 'paid';
/**
* Additional notes
*/
notes?: string;
/**
* Associated contact ID
*/
contactId?: string;
/**
* Line items
*/
items?: Array<CreatePurchaseOrderItemInput>;
};
/**
* Input for updating an existing purchase order
*/
export type UpdatePurchaseOrderInput = {
/**
* Purchase order number
*/
purchaseOrderId?: string;
/**
* Purchase order title
*/
title?: string;
/**
* Purchase order date
*/
date?: string;
/**
* Total amount
*/
amount?: number;
/**
* Purchase order status
*/
status?: 'draft' | 'approved' | 'rejected' | 'pending' | 'paid';
/**
* Additional notes
*/
notes?: string;
/**
* Associated contact ID
*/
contactId?: string;
};
/**
* Input for purchase order line item
*/
export type CreatePurchaseOrderItemInput = {
/**
* Item description
*/
description?: string;
/**
* Item quantity
*/
quantity?: number;
/**
* Price per unit
*/
unitPrice?: number;
/**
* Total line price
*/
totalPrice?: number;
/**
* Associated account ID
*/
accountId?: string;
};
/**
* Input for creating a new actual entry
*/
export type CreateActualInput = {
/**
* Actual entry description
*/
description: string;
/**
* Actual amount
*/
amount: number;
/**
* Actual date
*/
date: string;
/**
* Associated account ID(s)
*/
accountId?: string | Array<string>;
/**
* Reference identifier
*/
ref?: string;
/**
* Payment identifier
*/
payId?: string;
/**
* Actual entry status
*/
status?: string;
/**
* Additional notes
*/
notes?: string;
/**
* Associated tags
*/
tags?: Array<string>;
/**
* Associated purchase order ID
*/
purchaseOrderId?: string;
/**
* Associated transaction ID
*/
transactionId?: string;
/**
* Associated contact ID
*/
contactId?: string;
};
/**
* Input for updating an existing actual entry
*/
export type UpdateActualInput = {
/**
* Actual entry description
*/
description?: string;
/**
* Actual amount
*/
amount?: number;
/**
* Actual date
*/
date?: string;
/**
* Associated account ID(s)
*/
accountId?: string | Array<string>;
/**
* Reference identifier
*/
ref?: string;
/**
* Payment identifier
*/
payId?: string;
/**
* Actual entry status
*/
status?: string;
/**
* Additional notes
*/
notes?: string;
/**
* Associated tags
*/
tags?: Array<string>;
/**
* Associated purchase order ID
*/
purchaseOrderId?: string;
/**
* Associated transaction ID
*/
transactionId?: string;
/**
* Associated contact ID
*/
contactId?: string;
};
/**
* Input for updating an existing transaction
*/
export type UpdateTransactionInput = {
/**
* Associated project ID
*/
projectId?: string;
/**
* Associated account ID
*/
accountId?: string;
/**
* Associated contact ID
*/
contactId?: string;
/**
* Transaction description
*/
description?: string;
/**
* Additional notes
*/
notes?: string;
};
export type PurchaseOrderItem = {
/**
* Item identifier
*/
id: string;
/**
* Item description
*/
description?: string | null;
/**
* Item quantity
*/
quantity: number;
/**
* Price per unit
*/
unitPrice: number;
/**
* Total line price
*/
totalPrice: number;
/**
* Associated account ID
*/
accountId?: string | null;
account?: BudgetLine;
/**
* Last modification time (ISO 8601)
*/
lastModified: string;
};
export type Transaction = {
/**
* Transaction identifier
*/
id: string;
/**
* Transaction type
*/
type: 'bank.deposit' | 'bank.withdrawal' | 'bank.ach' | 'bank.wire' | 'card.spend' | 'card.payment' | 'card.dispute' | 'card.refund' | 'card.cashback';
/**
* Transaction status
*/
status: 'posted' | 'pending' | 'void';
/**
* Transaction sub-status
*/
subStatus?: 'settled' | 'refund' | 'reverse' | 'rejected';
/**
* Transaction description
*/
description: string;
/**
* Transaction amount
*/
amount: number;
/**
* Transaction date
*/
date: string;
/**
* Associated project ID
*/
projectId?: string | null;
/**
* Whether transaction has account assignment
*/
hasAccount: boolean;
/**
* Whether transaction has been converted to actual
*/
isActualized: boolean;
source?: TransactionSource;
/**
* Attached files
*/
attachments?: Array<File>;
contact?: Contact;
project?: Project;
account?: BudgetLine;
actual?: Actual;
};
export type TransactionSource = {
/**
* Source identifier
*/
id: string;
/**
* Source type (bank, card, etc.)
*/
type: string;
/**
* Source name
*/
name: string;
/**
* Last 4 digits of source identifier
*/
last4: string;
};
export type File = {
/**
* File identifier (DigitalOcean Spaces object key)
*/
id: string;
/**
* Original filename
*/
name: string;
/**
* MIME type
*/
type: string;
/**
* File size in bytes
*/
size: number;
};
/**
* Project space/folder for organizing projects
*/
export type Space = {
/**
* Space identifier (alias in user mode, UUID in system mode)
*/
id: string;
/**
* URL-friendly space identifier
*/
alias: string;
/**
* Space display name
*/
name: string;
/**
* Space image/banner URL
*/
image?: string | null;
/**
* Whether the space is archived
*/
archived: boolean;
/**
* Number of projects in this space
*/
projectCount?: number;
/**
* Projects in this space (when expanded)
*/
projects?: Array<Project>;
/**
* Space creation timestamp
*/
createdAt?: string;
/**
* Space last update timestamp
*/
updatedAt?: string;
};
export type CreateSpaceInput = {
/**
* Space name (required)
*/
name: string;
/**
* Space image/banner URL
*/
image?: string | null;
/**
* Initial archived status
*/
archived?: boolean;
};
export type UpdateSpaceInput = {
/**
* Updated space name
*/
name?: string;
/**
* Updated space image URL
*/
image?: string | null;
/**
* Updated archived status
*/
archived?: boolean;
};
/**
* Budget comment entity
*/
export type Comment = {
/**
* Comment identifier
*/
id: string;
/**
* Comment content (HTML or plain text)
*/
content: string;
/**
* Associated account ID
*/
accountId?: string | null;
/**
* Associated budget line ID
*/
lineId?: string | null;
author: {
/**
* Author user ID
*/
id?: string;
/**
* Author display name
*/
name?: string;
/**
* Author email
*/
email?: string;
};
/**
* Comment creation timestamp
*/
createdAt: string;
/**
* Comment last update timestamp
*/
updatedAt?: string;
};
/**
* Public ratepack containing reusable rate/cost data
*/
export type PublicRatepack = {
/**
* Unique ratepack identifier
*/
id: string;
/**
* Ratepack display name
*/
name: string;
/**
* URL-safe alias for the ratepack
*/
alias?: string | null;
/**
* Optional ratepack description
*/
description?: string | null;
/**
* List of available ratepack versions
*/
versions: Array<string>;
/**
* Latest published version identifier
*/
latestVersion?: string | null;
/**
* Ratepack creation timestamp
*/
createdAt: string;
/**
* Ratepack last update timestamp
*/
updatedAt: string;
};
/**
* Individual rate item from a public ratepack
*/
export type PublicRate = {
/**
* Unique rate identifier
*/
id: string;
/**
* Rate display name
*/
name?: string | null;
/**
* Rate emoji or icon
*/
emoji?: string | null;
/**
* Rate description
*/
description?: string | null;
/**
* Additional notes about the rate
*/
note?: string | null;
/**
* Rate quantity
*/
quantity?: number | null;
/**
* Rate amount per unit
*/
rate?: number | null;
/**
* Unit of measurement
*/
unit?: 'hour' | 'day' | 'week' | 'month' | 'year' | 'each' | 'sqft' | 'sqm' | 'lnft' | 'lnm';
/**
* Rate multiplier
*/
multiplier?: number | null;
/**
* Associated contact ID (usually null for public rates)
*/
contactId?: string | null;
/**
* Agreement or contract reference
*/
agreement?: string;
/**
* Local/regional identifier
*/
local?: string;
/**
* Rate effective date
*/
effectiveDate?: string;
/**
* Rate expiration date
*/
expirationDate?: string;
/**
* Categorization labels
*/
labels?: Array<string>;
};
/**
* Individual rate item within a workspace ratepack
*/
export type Rate = {
/**
* Unique item identifier
*/
id: string;
/**
* Item display name
*/
name?: string | null;
/**
* Item emoji or icon
*/
emoji?: string | null;
/**
* Item description
*/
description?: string | null;
/**
* Additional notes about the item
*/
note?: string | null;
/**
* Item quantity
*/
quantity?: number | null;
/**
* Item rate or cost per unit
*/
rate?: number | null;
/**
* Unit of measurement
*/
unit?: 'hour' | 'day' | 'week' | 'month' | 'year' | 'each' | 'sqft' | 'sqm' | 'lnft' | 'lnm';
/**
* Rate multiplier
*/
multiplier?: number | null;
/**
* Associated contact ID
*/
contactId?: string | null;
contact?: Contact;
};
/**
* Input for creating a new rate
*/
export type CreateRateInput = {
/**
* Rate name
*/
name?: string;
/**
* Rate emoji or icon
*/
emoji?: string;
/**
* Rate description
*/
description?: string;
/**
* Additional notes
*/
note?: string;
/**
* Rate quantity
*/
quantity?: number;
/**
* Rate or cost
*/
rate?: number;
/**
* Unit of measurement
*/
unit?: 'hour' | 'day' | 'week' | 'month' | 'year' | 'each' | 'sqft' | 'sqm' | 'lnft' | 'lnm';
/**
* Rate multiplier
*/
multiplier?: number;
/**
* Associated contact ID
*/
contactId?: string;
};
/**
* Input for updating a rate
*/
export type UpdateRateInput = {
/**
* Updated rate name
*/
name?: string;
/**
* Updated rate emoji or icon
*/
emoji?: string;
/**
* Updated rate description
*/
description?: string;
/**
* Updated additional notes
*/
note?: string;
/**
* Updated rate quantity
*/
quantity?: number;
/**
* Updated rate or cost
*/
rate?: number;
/**
* Updated unit of measurement
*/
unit?: 'hour' | 'day' | 'week' | 'month' | 'year' | 'each' | 'sqft' | 'sqm' | 'lnft' | 'lnm';
/**
* Updated rate multiplier
*/
multiplier?: number;
/**
* Updated associated contact/vendor ID
*/
contactId?: string;
};
/**
* Tag entity for categorizing budget line items
*/
export type Tag = {
/**
* Unique tag identifier (same as tag name)
*/
id: string;
/**
* Tag name (1-100 characters, immutable after creation)
*/
name: string;
/**
* Optional hex color code for visual identification
*/
color?: string;
/**
* Optional description for documentation purposes
*/
description?: string;
};
/**
* Request schema for creating a new tag
*/
export type CreateTagRequest = {
/**
* Tag name (must be unique within project)
*/
name: string;
/**
* Optional hex color code for visual identification
*/
color?: string;
/**
* Optional description for documentation purposes
*/
description?: string;
};
/**
* Request schema for updating an existing tag (only color can be updated)
*/
export type UpdateTagRequest = {
/**
* New hex color code
*/
color?: string;
};
/**
* Request schema for creating a new budget phase
*/
export type CreatePhaseRequest = {
/**
* Phase name
*/
name: string;
/**
* Phase type
*/
type: 'estimate' | 'actual' | 'rollup' | 'committed';
/**
* Phase color for UI display
*/
color?: 'red' | 'rose' | 'pink' | 'fuchsia' | 'purple' | 'violet' | 'indigo' | 'blue' | 'sky' | 'cyan' | 'teal' | 'green' | 'yellow' | 'amber' | 'orange';
currency?: {
/**
* Currency code (e.g., USD, EUR)
*/
code?: string | null;
/**
* Currency symbol
*/
symbol?: string | null;
/**
* Exchange rate multiplier
*/
exchangeRate?: number | null;
} | null;
/**
* ID of phase to copy data from
*/
copyPhase?: string;
/**
* Whether phase is hidden
*/
isHidden?: boolean;
/**
* For rollup phases - IDs of phases to aggregate
*/
phaseIds?: Array<string>;
/**
* For rollup phases - operation to perform
*/
operation?: 'sum' | 'difference';
/**
* ID interpretation mode - "user" for human-friendly IDs (default), "system" for database IDs
*/
idMode?: 'user' | 'system';
};
/**
* Request schema for updating an existing budget phase
*/
export type UpdatePhaseRequest = {
/**
* Updated phase name
*/
name?: string;
/**
* Updated phase color
*/
color?: 'red' | 'rose' | 'pink' | 'fuchsia' | 'purple' | 'violet' | 'indigo' | 'blue' | 'sky' | 'cyan' | 'teal' | 'green' | 'yellow' | 'amber' | 'orange';
currency?: {
/**
* Currency code
*/
code?: string | null;
/**
* Currency symbol
*/
symbol?: string | null;
/**
* Exchange rate multiplier
*/
exchangeRate?: number | null;
} | null;
/**
* Updated hidden status
*/
isHidden?: boolean;
/**
* ID interpretation mode - "user" for human-friendly IDs (default), "system" for database IDs
*/
idMode?: 'user' | 'system';
};
/**
* Request schema for creating a new fringe benefit
*/
export type CreateFringeRequest = {
/**
* Fringe code/symbol
*/
code: string;
/**
* Fringe description
*/
description?: string;
/**
* Fringe calculation units
*/
units: 'percent' | 'flat' | 'total';
/**
* Fringe rate (decimal for percent, amount for flat)
*/
rate: number;
/**
* Salary cutoff limit
*/
cutoff?: number | null;
/**
* ID interpretation mode - "user" for human-friendly IDs (default), "system" for database IDs
*/
idMode?: 'user' | 'system';
};
/**
* Request schema for updating an existing fringe benefit
*/
export type UpdateFringeRequest = {
/**
* Updated fringe code
*/
code?: string;
/**
* Updated description
*/
description?: string;
/**
* Updated units
*/
units?: 'percent' | 'flat' | 'total';
/**
* Updated rate
*/
rate?: number;
/**
* Updated cutoff
*/
cutoff?: number | null;
/**
* ID interpretation mode - "user" for human-friendly IDs (default), "system" for database IDs
*/
idMode?: 'user' | 'system';
};
/**
* Request schema for creating a new global variable
*/
export type CreateGlobalRequest = {
/**
* Variable symbol for formulas
*/
symbol: string;
/**
* Variable description
*/
description: string;
/**
* Formula or value
*/
formula: string;
/**
* Unit type
*/
unit?: string;
/**
* ID interpretation mode - "user" for human-friendly IDs (default), "system" for database IDs
*/
idMode?: 'user' | 'system';
};
/**
* Request schema for updating an existing global variable
*/
export type UpdateGlobalRequest = {
/**
* Updated symbol
*/
symbol?: string;
/**
* Updated description
*/
description?: string;
/**
* Updated formula
*/
formula?: string;
/**
* Updated unit
*/
unit?: string;
/**
* ID interpretation mode - "user" for human-friendly IDs (default), "system" for database IDs
*/
idMode?: 'user' | 'system';
};
/**
* Request schema for updating an existing budget line
*/
export type UpdateBudgetLineRequest = {
/**
* Updated line description (set to null to remove)
*/
description?: string | null;
/**
* Updated account ID (set to null to remove)
*/
accountId?: string | null;
/**
* Convert this line to an account type
*/
convertToAccount?: boolean;
/**
* Updated phase-specific data (partial updates supported)
*/
phaseData?: {
[key: string]: {
/**
* Updated quantity
*/
quantity?: number | null;
/**
* Updated unit
*/
unit?: string | null;
/**
* Updated rate
*/
rate?: number | null;
/**
* Updated multiplier
*/
multiplier?: number | null;
/**
* Fringe IDs to apply
*/
fringes?: Array<string>;
};
};
/**
* ID interpretation mode - "user" for human-friendly IDs (default), "system" for database IDs
*/
idMode?: 'user' | 'system';
};
/**
* Financial totals aggregated from all budget line items assigned to this tag
*/
export type TagTotals = {
/**
* Total amounts by phase ID. Keys depend on idMode parameter:
* - idMode=user: phase aliases (e.g., "estimate", "actual")
* - idMode=system: internal database IDs (UUID strings)
*
*/
phaseTotals: {
[key: string]: number;
};
/**
* Fringe benefit totals by phase ID. Keys follow same format as phaseTotals.
*
*/
fringeTotals: {
[key: string]: number;
};
/**
* Total actual expenses for this tag across all phases
*/
actualTotal: number;
};
/**
* Single tag response with financial totals included.
* Used for endpoints that return individual tag details.
*
*/
export type TagResponse = Tag & {
totals: TagTotals;
};
/**
* Multiple tags response for list endpoints
*/
export type TagsResponse = {
/**
* Array of tags with their financial totals
*/
tags: Array<TagResponse>;
};
export type _Error = {
/**
* Error message
*/
error: string;
/**
* Additional error details
*/
details?: {
[key: string]: unknown;
};
/**
* Error code
*/
code?: string;
};
/**
* Project identifier (alias or ID)
*/
export type ProjectId = string;
/**
* ID interpretation mode. Controls how path and query parameter IDs (like lineId, accountId, phaseId) are interpreted - 'user' for human-readable IDs (account codes, phase names), 'system' for database IDs (UUIDs/nanoids). Also affects the format of IDs in responses.
*/
export type IdMode = 'user' | 'system';
/**
* Return results on or after this date (ISO 8601)
*/
export type StartDate = string;
/**
* Return results on or before this date (ISO 8601)
*/
export type EndDate = string;
/**
* Filter by whether attachments are present
*/
export type HasAttachments = boolean;
export type ListProjectsData = {
body?: never;
path?: never;
query?: {
/**
* Return only projects matching these IDs or aliases
*/
id?: string | Array<string>;
/**
* Return projects belonging to these space IDs or aliases
*/
spaceId?: string | Array<string>;
/**
* Filter by project status
*/
status?: 'active' | 'archived';
/**
* Case-insensitive substring match on project name
*/
name?: string | Array<string>;
/**
* Case-insensitive substring match on space name
*/
spaceName?: string | Array<string>;
/**
* Return projects that include all specified labels
*/
labels?: string | Array<string>;
};
url: '/projects';
};
export type ListProjectsErrors = {
/**
* Bad request - invalid parameters or request body
*/
400: _Error;
/**
* Unauthorized - invalid or missing API key
*/
401: _Error;
/**
* Internal server error
*/
500: _Error;
};
export type ListProjectsError = ListProjectsErrors[keyof ListProjectsErrors];
export type ListProjectsResponses = {
/**
* List of projects
*/
200: {
projects?: Array<Project>;
};
};
export type ListProjectsResponse = ListProjectsResponses[keyof ListProjectsResponses];
export type CreateProjectData = {
body: CreateProjectInput;
path?: never;
query?: never;
url: '/projects';
};
export type CreateProjectErrors = {
/**
* Bad request - invalid parameters or request body
*/
400: _Error;
/**
* Unauthorized - invalid or missing API key
*/
401: _Error;
/**
* Internal server error
*/
500: _Error;
};
export type CreateProjectError = CreateProjectErrors[keyof CreateProjectErrors];
export type CreateProjectResponses = {
/**
* Project created successfully
*/
201: Project;
};
export type CreateProjectResponse = CreateProjectResponses[keyof CreateProjectResponses];
export type DeleteProjectData = {
body?: never;
path: {
/**
* Project identifier (alias or ID)
*/
projectId: string;
};
query?: never;
url: '/projects/{projectId}';
};
export type DeleteProjectErrors = {
/**
* Unauthorized - invalid or missing API key
*/
401: _Error;
/**
* Resource not found
*/
404: _Error;
/**
* Internal server error
*/
500: _Error;
};
export type DeleteProjectError = DeleteProjectErrors[keyof DeleteProjectErrors];
export type DeleteProjectResponses = {
/**
* Project deleted successfully
*/
204: void;
};
export type DeleteProjectResponse = DeleteProjectResponses[keyof DeleteProjectResponses];
export type GetProjectData = {
body?: never;
path: {
/**
* Project identifier (alias or ID)
*/
projectId: string;
};
query?: never;
url: '/projects/{projectId}';
};
export type GetProjectErrors = {
/**
* Unauthorized - invalid or missing API key
*/
401: _Error;
/**
* Resource not found
*/
404: _Error;
/**
* Internal server error
*/
500: _Error;
};
export type GetProjectError = GetProjectErrors[keyof GetProjectErrors];
export type GetProjectResponses = {
/**
* Project details
*/
200: Project;
};
export type GetProjectResponse = GetProjectResponses[keyof GetProjectResponses];
export type UpdateProjectData = {
body: UpdateProjectInput;
path: {
/**
* Project identifier (alias or ID)
*/
projectId: string;
};
query?: never;
url: '/projects/{projectId}';
};
export type UpdateProjectErrors = {
/**
* Bad request - invalid parameters or request body
*/
400: _Error;
/**
* Unauthorized - invalid or missing API key
*/
401: _Error;
/**
* Resource not found
*/
404: _Error;
/**
* Internal server error
*/
500: _Error;
};
export type UpdateProjectError = UpdateProjectErrors[keyof UpdateProjectErrors];
export type UpdateProjectResponses = {
/**
* Project updated successfully
*/
200: Project;
};
export type UpdateProjectResponse = UpdateProjectResponses[keyof UpdateProjectResponses];
export type GetBudgetData = {
body?: never;
path: {
/**
* Project identifier (alias or ID)
*/
projectId: string;
};
query?: {
/**
* Filter by account ID or code (defaults to root account)
*/
accountId?: string;
/**
* Filter by phase ID(s)
*/
phaseId?: string | Array<string>;
/**
* Include hidden phases in the response
*/
includeHiddenPhases?: boolean;
/**
* Exclude sub-accounts from the response
*/
excludeSubAccounts?: boolean;
/**
* Filter budget by tag names (can be single tag or array of tags)
*/
tags?: string | Array<string>;
/**
* How to apply the tag filter
*/
tagFilterMode?: 'contains' | 'excludes';
/**
* Include related data in the response
*/
expands?: Array<'fringes' | 'phases' | 'globals' | 'lines.contact' | 'lines.phaseData'>;
/**
* ID interpretation mode. Controls how path and query parameter IDs (like lineId, accountId, phaseId) are interpreted - 'user' for human-readable IDs (account codes, phase names), 'system' for database IDs (UUIDs/nanoids). Also affects the format of IDs in responses.
*/
idMode?: 'user' | 'system';
};
url: '/projects/{projectId}/budget';
};
export type GetBudgetErrors = {
/**
* Unauthorized - invalid or missing API key
*/
401: _Error;
/**
* Resource not found
*/
404: _Error;
/**
* Internal server error
*/
500: _Error;
};
export type GetBudgetError = GetBudgetErrors[keyof GetBudgetErrors];
export type GetBudgetResponses = {
/**
* Budget information
*/
200: Budget;
};
export type GetBudgetResponse = GetBudgetResponses[keyof GetBudgetResponses];
export type CreateBudgetLinesData = {
body: CreateBudgetInput;
path: {
/**
* Project identifier (alias or ID)
*/
projectId: string;
};
query?: never;
url: '/projects/{projectId}/budget';
};
export type CreateBudgetLinesErrors = {
/**
* Bad request - invalid parameters or request body
*/
400: _Error;
/**
* Unauthorized - invalid or missing API key
*/
401: _Error;
/**
* Resource not found
*/
404: _Error;
/**
* Internal server error
*/
500: _Error;
};
export type CreateBudgetLinesError = CreateBudgetLinesErrors[keyof CreateBudgetLinesErrors];
export type CreateBudgetLinesResponses = {
/**
* Budget lines created successfully
*/
201: Budget;
};
export type CreateBudgetLinesResponse = CreateBudgetLinesResponses[keyof CreateBudgetLinesResponses];
export type DeleteBudgetLineData = {
body?: never;
path: {
/**
* Project identifier (alias or ID)
*/
projectId: string;
/**
* Budget line identifier. Can be either a user-friendly ID (e.g., account code) or a system ID (UUID/nanoid), depending on the idMode parameter
*/
lineId: string;
};
query?: {
/**
* ID interpretation mode. Controls how path and query parameter IDs (like lineId, accountId, phaseId) are interpreted - 'user' for human-readable IDs (account codes, phase names), 'system' for database IDs (UUIDs/nanoids). Also affects the format of IDs in responses.
*/
idMode?: 'user' | 'system';
};
url: '/projects/{projectId}/budget/line/{lineId}';
};
export type DeleteBudgetLineErrors = {
/**
* Unauthorized - invalid or missing API key
*/
401: _Error;
/**
* Resource not found
*/
404: _Error;
/**
* Internal server error
*/
500: _Error;
};
export type DeleteBudgetLineError = DeleteBudgetLineErrors[keyof DeleteBudgetLineErrors];
export type DeleteBudgetLineResponses = {
/**
* Budget line deleted successfully
*/
204: void;
};
export type DeleteBudgetLineResponse = DeleteBudgetLineResponses[keyof DeleteBudgetLineResponses];
export type GetBudgetLineData = {
body?: never;
path: {
/**
* Project identifier (alias or ID)
*/
projectId: string;
/**
* Budget line identifier. Can be either a user-friendly ID (e.g., account code) or a system ID (UUID/nanoid), depending on the idMode parameter
*/
lineId: string;
};
query?: {
/**
* Include hidden phases in the response
*/
includeHiddenPhases?: boolean;
/**
* Filter budget line by tag names (can be single tag or array of tags)
*/
tags?: string | Array<string>;
/**
* How to apply the tag filter
*/
tagFilterMode?: 'contains' | 'excludes';
/**
* Include related data in the response
*/
expands?: Array<'contact' | 'phaseData'>;
/**
* ID interpretation mode. Controls how path and query parameter IDs (like lineId, accountId, phaseId) are interpreted - 'user' for human-readable IDs (account codes, phase names), 'system' for database IDs (UUIDs/nanoids). Also affects the format of IDs in responses.
*/
idMode?: 'user' | 'system';
};
url: '/projects/{projectId}/budget/line/{lineId}';
};
export type GetBudgetLineErrors = {
/**
* Unauthorized - invalid or missing API key
*/
401: _Error;
/**
* Resource not found
*/
404: _Error;
/**
* Internal server e