Features

Company (fx-companyapp)

The bundled company management app, how it installs into the phone, its main settings and its full developer API.

#What it is

fx-companyapp is a company management app: employee roster, hiring and firing, ranks, company funds (deposit and withdraw), announcements, company invoices with commission, statistics, a business directory and an audit log.

#Requirements

Resource Required
fx-phone Yes (the app also installs into lb-phone or cylex_phone)
qb-core, or qbx_core with the qb-core bridge Yes
oxmysql Yes
A banking resource: tgiann-bank, okokBanking, qb-banking, qb-management or qb-bossmenu Yes, pick one in config.lua

#Installation

cfgensure oxmysql
ensure qb-core
ensure fx-phone
ensure fx-companyapp
  • Keep the folder name. Other scripts call this resource as exports['fx-companyapp'].
  • The database tables are created on first start. Import setup/sql/install.sql only if the console reports that the tables could not be created.
  • Choose the jobs that can use the app with Config.UseWhitelist, Config.JobWhitelist and Config.JobBlacklist. A job that is not allowed sees a "no company" screen.
  • Set Config.Banking.Provider and do one test deposit and one test withdrawal on a test character.

#How it registers into the phone

The resource has one adapter per phone in client/phone/. With Config.Phone.Resource = "auto" the first running phone wins, in the order fx-phone, lb-phone, cylex_phone.

  • The FX Phone adapter calls exports['fx-phone']:AddCustomApp with identifier = Config.AppIdentifier (default fx_company), name = Config.AppName, the description, developer, defaultApp = Config.DefaultApp, price = Config.AppPrice, a screenshot, ui and icon.
  • Notifications go through exports['fx-phone']:SendNotification.
  • With Config.Phone.WalletTransactions = true, deposits and withdrawals are also written to the phone's bank history with AddTransaction.

To keep the app from starting at all, set ['fx-companyapp'] = false in Config.BundledApps. See Apps.

#Config highlights

config.lua:

Setting Meaning
Config.AppName, Config.AppIdentifier, Config.AppPrice, Config.DefaultApp, Config.Developer How the app appears on the phone. Never set the identifier to company
Config.Phone Phone choice, per-phone scale, WalletTransactions
Config.Locale, Config.Theme, Config.Currency Language, first-open theme (system, corporate, midnight), currency symbol
Config.Account Player's personal account: bank or cash
Config.Banking.Provider tgiann-bank, okokBanking, qb-banking, qb-management, qbcore-society or custom (bank_adapter.lua)
Config.UseWhitelist, Config.JobWhitelist, Config.JobBlacklist Which jobs can open the app
Config.UnemployedJob Job given when someone is fired
Config.Permissions Who may do what, see below
Config.JobPermissionOverrides Per-job overrides of Config.Permissions
Config.ProtectHigherRanks Nobody can fire or re-rank someone at or above their own rank
Config.HireMode, Config.HireNearbyDistance, Config.DefaultHireGrade How hiring works
Config.MinKasaAmount, Config.MaxKasaAmount Limits for one in-app deposit or withdrawal
Config.HistoryLimit, Config.LogLimit, Config.PruneAfterDays How much history is shown and kept
Config.Invoices Company invoices: CompanyOnly, BlockSelf, BlockSameCompany, PayAccount, commission limits, TaxPercent, MaxAmount, MaxDistance, ExpireDays and more
Config.InvoicePresets, Config.JobTypes Ready invoice lists per business type
Config.Directory (config_directory.lua) Business directory defaults: categories, accent colours, allowed image hosts, text limits

Config.Permissions maps each action to "boss" (ranks flagged isboss), "member" (anyone in the company) or a grade level number (that grade and above). The actions are hire, fire, setGrade, withdraw, deposit, announce, viewLogs, viewKasa, invoice, viewInvoices, cancelInvoice, manageInvoices, viewStats, editProfile, viewMessages, takeLine.

config_server.lua is server only. It holds the log settings: Discord webhooks (a default, one per group and per company), which events are sent, and console output.

#API rules

  • Exports are server side unless listed under Client exports.
  • Actions return ok, value. When ok is true the second value is the result. When ok is false it is an error reason, listed at the end of this page.
  • Exports do not check player permissions. They act as the system. If you act on behalf of a player, ask first with HasPermission.
  • Hooks still run. A beforeFire hook blocks a fire whether it came from the app or from an export.
  • Changes are visible live. Open apps of the affected company refresh by themselves.
  • A job does not have to be in Config.JobWhitelist for the exports to work. The whitelist only controls who can open the app.
  • A job name is a non-empty string of at most 60 characters.

Many actions accept an opts table:

Field Type Meaning
actor string Name shown in the audit log and history. Default: the name of source, or "System"
source number Server id of the player who caused it, passed to hooks and events
notify boolean false sends the affected player no phone notification
title string Transaction title (funds only)
category string Transaction category (funds only)
log boolean false writes no history or audit row

#Server exports: company and employees

#GetPlayerCompany

Returns the player's company as the app sees it.

lua---@param src number
---@return table|nil company  { job, label, isboss, grade = { level, name } }
exports['fx-companyapp']:GetPlayerCompany(src)
lualocal company = exports['fx-companyapp']:GetPlayerCompany(source)

Returns nil when the player's job cannot use the app.

#IsJobAllowed

Tells whether a job can use the app.

lua---@param job string
---@return boolean
exports['fx-companyapp']:IsJobAllowed(job)
lualocal allowed = exports['fx-companyapp']:IsJobAllowed('mechanic')

#HasPermission

Tells whether a player may do an action in their company.

lua---@param src number
---@param action string  A key of Config.Permissions, e.g. 'withdraw'
---@return boolean
exports['fx-companyapp']:HasPermission(src, action)
luaif not exports['fx-companyapp']:HasPermission(source, 'withdraw') then return end

Always false when the player has no company.

#GetPermissions

Returns every permission of a player in one call.

lua---@param src number
---@return table<string, boolean> permissions
exports['fx-companyapp']:GetPermissions(src)
lualocal perms = exports['fx-companyapp']:GetPermissions(source)

#GetCompanyGrades

Returns a job's ranks, sorted by level.

lua---@param job string
---@return table[] grades  { level, name, isboss, payment }
exports['fx-companyapp']:GetCompanyGrades(job)
lualocal grades = exports['fx-companyapp']:GetCompanyGrades('mechanic')

#GetCompanyMembers

Returns every employee, online and offline, highest rank first.

lua---@param job string
---@return table[] members  { citizenid, name, grade, gradeName, isboss, online, onduty }
exports['fx-companyapp']:GetCompanyMembers(job)
lualocal members = exports['fx-companyapp']:GetCompanyMembers('mechanic')

The roster is cached per job and dropped on every hire, fire, rank change and job update.

#GetEmployee

Returns one employee of a job.

lua---@param job string
---@param who string|number  Citizen id or server id
---@return table|nil employee  { citizenid, source?, online, level, isboss, name }
exports['fx-companyapp']:GetEmployee(job, who)
lualocal emp = exports['fx-companyapp']:GetEmployee('mechanic', source)

Returns nil when they are not in that job. source is nil when the employee is offline.

#GetOnlineEmployees

Returns the online employees of a job.

lua---@param job string
---@param onDutyOnly? boolean
---@return table[] employees  { source, citizenid, onduty }
exports['fx-companyapp']:GetOnlineEmployees(job, onDutyOnly)
lualocal staff = exports['fx-companyapp']:GetOnlineEmployees('police', true)

#GetCompanySummary

Returns head counts, payroll and balance of a company.

lua---@param job string
---@return table|nil summary  { job, label, memberCount, onlineCount, onDutyCount, payroll, balance }
exports['fx-companyapp']:GetCompanySummary(job)
lualocal summary = exports['fx-companyapp']:GetCompanySummary('mechanic')

payroll is the sum of every employee's rank payment.

#Server exports: company funds

The funds live in the banking resource chosen in Config.Banking.Provider. These exports go through the same provider and write the in-app transaction history.

#GetCompanyBalance

Returns the company's funds.

lua---@param job string
---@return number balance
exports['fx-companyapp']:GetCompanyBalance(job)
lualocal balance = exports['fx-companyapp']:GetCompanyBalance('mechanic')

#CompanyAccountExists

Tells whether the banking resource has an account for the job.

lua---@param job string
---@return boolean
exports['fx-companyapp']:CompanyAccountExists(job)
lualocal exists = exports['fx-companyapp']:CompanyAccountExists('mechanic')

Providers that cannot tell (qb-banking, qb-management, qb-bossmenu) always return true.

#AddCompanyMoney

Adds money to the company funds and writes a history row.

lua---@param job string
---@param amount number  Positive; decimals are floored
---@param opts? table  { title?, category?, actor?, source?, log? }
---@return boolean ok
---@return number|string newBalanceOrReason
exports['fx-companyapp']:AddCompanyMoney(job, amount, opts)
lualocal ok, balance = exports['fx-companyapp']:AddCompanyMoney('mechanic', 2500, { title = 'Invoice #1042', category = 'invoice' })
  • Config.MaxKasaAmount does not apply here. It only limits a single in-app deposit or withdrawal.
  • Defaults: title "Income", category income, actor "System".
  • Failure reasons: invalidJob, invalidAmount, kasaUnavailable, generic, or the reason a beforeMoneyChange hook returned.

#RemoveCompanyMoney

Removes money from the company funds and writes a history row.

lua---@param job string
---@param amount number  Positive; decimals are floored
---@param opts? table  { title?, category?, actor?, source?, log? }
---@return boolean ok
---@return number|string newBalanceOrReason
exports['fx-companyapp']:RemoveCompanyMoney(job, amount, opts)
lualocal ok, balance = exports['fx-companyapp']:RemoveCompanyMoney('burger', 800, { title = 'Stock order', category = 'stock' })

Fails with insufficientKasa instead of going negative. Defaults: title "Expense", category expense.

#LogTransaction

Writes a history row without moving money.

lua---@param job string
---@param amount number  Positive = in, negative = out
---@param title string
---@param category? string
---@param actor? string
exports['fx-companyapp']:LogTransaction(job, amount, title, category, actor)
luaexports['fx-companyapp']:LogTransaction('mechanic', 500, 'Tow fee', 'service', 'John Doe')

Use it when your script already moved the money through the banking resource itself. Call it right after the money moved, so the account ledger does not record the movement a second time.

#GetCompanyTransactions

Returns the newest transactions of a company.

lua---@param job string
---@param limit? number  Default Config.HistoryLimit
---@return table[] transactions  { amount, title, category, actor, ts }
exports['fx-companyapp']:GetCompanyTransactions(job, limit)
lualocal rows = exports['fx-companyapp']:GetCompanyTransactions('mechanic', 20)

ts is a Unix timestamp.

#Server exports: employee management

These do what the app does, without the permission and rank-protection checks. The target gets a phone notification and their open app reloads.

#HireEmployee

Hires an online player.

lua---@param job string
---@param targetSrc number
---@param grade? number  Default Config.DefaultHireGrade
---@param opts? table  { actor?, source?, notify? }
---@return boolean ok
---@return string gradeNameOrReason
exports['fx-companyapp']:HireEmployee(job, targetSrc, grade, opts)
lualocal ok, res = exports['fx-companyapp']:HireEmployee('mechanic', targetId, 0, { actor = 'Job Center' })

Failure reasons: invalidJob, playerNotOnline, alreadyInCompany, invalidGrade.

#FireEmployee

Fires an employee, online or offline.

lua---@param job string
---@param citizenid string
---@param opts? table  { actor?, source?, notify? }
---@return boolean ok
---@return string nameOrReason
exports['fx-companyapp']:FireEmployee(job, citizenid, opts)
lualocal ok, name = exports['fx-companyapp']:FireEmployee('mechanic', 'ABC12345')

The employee is moved to Config.UnemployedJob. Fails with playerNotFound when the citizen id is not an employee of that job.

#SetEmployeeGrade

Changes an employee's rank, online or offline.

lua---@param job string
---@param citizenid string
---@param grade number
---@param opts? table  { actor?, source?, notify? }
---@return boolean ok
---@return string nameOrReason
exports['fx-companyapp']:SetEmployeeGrade(job, citizenid, grade, opts)
luaexports['fx-companyapp']:SetEmployeeGrade('police', 'ABC12345', 3, { actor = 'Command' })

The audit log records it as promoted or demoted.

#Server exports: audit log

#LogAction

Adds a row to the company's audit log.

lua---@param job string
---@param action string  Short key, at most 32 characters
---@param actor? string
---@param target? string
---@param detail? string  Line text shown in the app
exports['fx-companyapp']:LogAction(job, action, actor, target, detail)
luaexports['fx-companyapp']:LogAction('mechanic', 'craft', 'John Doe', nil, 'John Doe crafted 5x Repair Kit')

Known actions get their own icon: hired, fired, graded, deposit, withdraw, announce.

#GetCompanyLogs

Returns the newest audit rows of a company.

lua---@param job string
---@param limit? number  1 to 200, default Config.LogLimit
---@return table[] logs  { action, actor, target, detail, ts }
exports['fx-companyapp']:GetCompanyLogs(job, limit)
lualocal logs = exports['fx-companyapp']:GetCompanyLogs('mechanic', 50)

#Server exports: notifications

#NotifyPlayer

Sends a phone notification to an online player.

lua---@param src number
---@param title string
---@param message string
---@return boolean sent
exports['fx-companyapp']:NotifyPlayer(src, title, message)
luaexports['fx-companyapp']:NotifyPlayer(source, 'Shift', 'Your shift starts in 5 minutes')

#NotifyEmployee

Sends a phone notification by citizen id.

lua---@param citizenid string
---@param title string
---@param message string
---@return boolean sent
exports['fx-companyapp']:NotifyEmployee(citizenid, title, message)
luaexports['fx-companyapp']:NotifyEmployee('ABC12345', 'Payroll', 'Your bonus was paid')

Returns false when the player is offline. Nothing is queued.

#SendAnnouncement

Sends a notification to every online employee of a job.

lua---@param job string
---@param message string
---@param opts? table  { title?, onDutyOnly?, exclude?, actor?, log? }
---@return number sent  How many employees received it
exports['fx-companyapp']:SendAnnouncement(job, message, opts)
lualocal sent = exports['fx-companyapp']:SendAnnouncement('police', 'Code 3 at Legion Square', { onDutyOnly = true, title = 'Dispatch' })
  • exclude is a server id to skip. log = false writes no audit row.
  • Returns 0 for an invalid job or an empty message.

#Server exports: phone and app

#GetPhoneResource

Returns the phone resource in use on the server.

lua---@return string|nil phone  'fx-phone', 'lb-phone', 'cylex_phone' or nil
exports['fx-companyapp']:GetPhoneResource()
lualocal phone = exports['fx-companyapp']:GetPhoneResource()

#RefreshApp

Forces open apps to reload their data.

lua---@param target number|string  Server id or job name
---@param scope? string  'all' (default), 'members', 'kasa', 'logs' or 'invoices'
exports['fx-companyapp']:RefreshApp(target, scope)
luaexports['fx-companyapp']:RefreshApp('mechanic', 'kasa')

You only need this when your script changed something the app reads without going through these exports.

#GetVersionStatus

Returns the result of the update check.

lua---@return table status  { state, current, latest, behind }
exports['fx-companyapp']:GetVersionStatus()
lualocal status = exports['fx-companyapp']:GetVersionStatus()

#Server exports: invoices

Invoices are always issued in a company's name. When one is paid, the commission goes to the employee who issued it, the optional tax is removed and the rest goes to the company funds.

#CreateInvoice

Issues an invoice in a company's name.

lua---@param job string
---@param target number|string  Server id or citizen id
---@param amount number
---@param label string
---@param opts? table  { issuerSrc?, issuerCid?, issuerName?, note?, notify? }
---@return boolean ok
---@return table|string invoiceOrReason
exports['fx-companyapp']:CreateInvoice(job, target, amount, label, opts)
lualocal ok, inv = exports['fx-companyapp']:CreateInvoice('mechanic', customerSrc, 1500, 'Engine repair', { issuerSrc = source })
  • No permission check. Your resource decides who may bill.
  • Offline players can be invoiced by citizen id.
  • issuerSrc is the online employee who gets the commission. Without it the issuer is issuerCid / issuerName, or the company itself.
  • label is cut to Config.Invoices.LabelMaxLength.
  • Failure reasons: invalidJob, invalidAmount, invalidLabel, playerNotFound, or a hook's reason.

#PayInvoice

Pays an invoice from the payer's money.

lua---@param id number
---@param payerSrc number
---@param opts? table  { anyPayer? }
---@return boolean ok
---@return table|string invoiceOrReason
exports['fx-companyapp']:PayInvoice(id, payerSrc, opts)
lualocal ok, inv = exports['fx-companyapp']:PayInvoice(42, source)

Pays from Config.Invoices.PayAccount, with a cash fallback when PayFallbackToCash is on. Only the invoice's customer can pay unless opts.anyPayer = true.

#CancelInvoice

Cancels an unpaid invoice.

lua---@param id number
---@param opts? table  { actor?, source? }
---@return boolean ok
---@return number|string idOrReason
exports['fx-companyapp']:CancelInvoice(id, opts)
luaexports['fx-companyapp']:CancelInvoice(42, { actor = 'Dispatch' })

#GetInvoice

Returns one invoice.

lua---@param id number
---@return table|nil invoice
exports['fx-companyapp']:GetInvoice(id)
lualocal inv = exports['fx-companyapp']:GetInvoice(42)

Fields: id, job, companyLabel, label, note, amount, status, issuerCid, issuerName, targetCid, targetName, commissionPct, commission, tax, companyShare, closedBy, createdAt, closedAt. status is unpaid, paid, cancelled or expired.

#GetCompanyInvoices

Returns a company's invoices, newest first.

lua---@param job string
---@param filter? table  { status?, issuerCid?, targetCid?, limit?, offset? }
---@return table[] invoices
exports['fx-companyapp']:GetCompanyInvoices(job, filter)
lualocal unpaid = exports['fx-companyapp']:GetCompanyInvoices('mechanic', { status = 'unpaid', limit = 20 })

limit is at most 100.

#GetPlayerInvoices

Returns the invoices addressed to a player, from any company.

lua---@param who number|string  Server id or citizen id
---@param status? string
---@param limit? number
---@return table[] invoices
exports['fx-companyapp']:GetPlayerInvoices(who, status, limit)
lualocal invoices = exports['fx-companyapp']:GetPlayerInvoices(source, 'unpaid')

#GetUnpaidInvoiceCount

Returns how many unpaid invoices a player has.

lua---@param who number|string  Server id or citizen id
---@param job? string  Count only this company's invoices
---@return number count
exports['fx-companyapp']:GetUnpaidInvoiceCount(who, job)
lualocal count = exports['fx-companyapp']:GetUnpaidInvoiceCount(source)

#GetUnpaidInvoiceTotal

Returns the total unpaid amount a player owes.

lua---@param who number|string  Server id or citizen id
---@param job? string  Sum only this company's invoices
---@return number total
exports['fx-companyapp']:GetUnpaidInvoiceTotal(who, job)
lualocal total = exports['fx-companyapp']:GetUnpaidInvoiceTotal(source, 'mechanic')

#HasUnpaidInvoices

Tells whether a player has at least one unpaid company invoice.

lua---@param who number|string  Server id or citizen id
---@param notify? boolean  Send the "unpaid invoices" phone notification when it blocks
---@return boolean blocked
exports['fx-companyapp']:HasUnpaidInvoices(who, notify)
luaif exports['fx-companyapp']:HasUnpaidInvoices(citizenid, true) then return end

A database error returns false, so a failure never locks a garage.

#GetPendingCommission

Returns the commission waiting for an employee who was offline when an invoice was paid.

lua---@param who number|string  Server id or citizen id
---@return number amount
exports['fx-companyapp']:GetPendingCommission(who)
lualocal pending = exports['fx-companyapp']:GetPendingCommission('ABC12345')

#CanIssuePersonalInvoice

Tells whether a player may send an invoice in their own name.

lua---@param src number
---@return boolean allowed
---@return string|nil reason  'companyOnly'
exports['fx-companyapp']:CanIssuePersonalInvoice(src)
lualocal allowed = exports['fx-companyapp']:CanIssuePersonalInvoice(source)

Returns false, 'companyOnly' when the player belongs to a company and Config.Invoices.CompanyOnly is on. Meant for other billing scripts.

#GetInvoiceIssuer

Returns who an invoice from this player should be issued as.

lua---@param src number
---@return table issuer  { type = 'company', job, label } or { type = 'personal' }
exports['fx-companyapp']:GetInvoiceIssuer(src)
lualocal issuer = exports['fx-companyapp']:GetInvoiceIssuer(source)

#Server exports: invoice settings

#GetInvoiceSettings

Returns a company's invoice settings.

lua---@param job string
---@return table|nil settings  { commission, commissionMin, commissionMax, presets, presetType, allowCustom, maxAmount }
exports['fx-companyapp']:GetInvoiceSettings(job)
lualocal settings = exports['fx-companyapp']:GetInvoiceSettings('mechanic')

presets is a list of { label, price }.

#SetInvoiceSettings

Saves part of a company's invoice settings.

lua---@param job string
---@param patch table
---@return boolean ok
---@return table|string settingsOrReason
exports['fx-companyapp']:SetInvoiceSettings(job, patch)
lualocal ok, settings = exports['fx-companyapp']:SetInvoiceSettings('mechanic', { allowCustom = false })

Values are clamped to the config limits and the change is logged. Returns false, 'invalidJob' for a bad job or a patch that is not a table.

#GetCommission

Returns a company's commission percentage.

lua---@param job string
---@return number percent
exports['fx-companyapp']:GetCommission(job)
lualocal pct = exports['fx-companyapp']:GetCommission('mechanic')

#SetCommission

Sets a company's commission percentage.

lua---@param job string
---@param percent number
---@return boolean ok
---@return number|string percentOrReason
exports['fx-companyapp']:SetCommission(job, percent)
lualocal ok, pct = exports['fx-companyapp']:SetCommission('mechanic', 15)

The value is clamped to the commission limits; the second return value is what was stored.

#GetInvoicePresets

Returns a company's ready invoice list.

lua---@param job string
---@return table[] presets  { label, price }
exports['fx-companyapp']:GetInvoicePresets(job)
lualocal presets = exports['fx-companyapp']:GetInvoicePresets('mechanic')

#GetInvoiceTemplates

Returns the built-in invoice templates.

lua---@return table[] templates  { key, label, count }
exports['fx-companyapp']:GetInvoiceTemplates()
lualocal templates = exports['fx-companyapp']:GetInvoiceTemplates()

#Server exports: statistics

days is 1, 7, 30 or 90.

#GetCompanyStats

Returns income, expense and invoice statistics of a company.

lua---@param job string
---@param days number
---@return table|nil stats  { days, series, income, expense, net, categories, invoices, top }
exports['fx-companyapp']:GetCompanyStats(job, days)
lualocal stats = exports['fx-companyapp']:GetCompanyStats('mechanic', 30)
  • series is a list of { day, income, expense }.
  • categories has income and expense lists of { category, amount }.
  • invoices has count, gross, paidCount, paid, unpaidCount, unpaid, commission, tax, company.
  • top is the first five rows of GetEmployeeRanking.

#GetEmployeeRanking

Returns employees ranked by what they earned for the company.

lua---@param job string
---@param days number
---@return table[] ranking  { citizenid, name, issued, gross, paidCount, paid, commission, company }
exports['fx-companyapp']:GetEmployeeRanking(job, days)
lualocal ranking = exports['fx-companyapp']:GetEmployeeRanking('mechanic', 7)

#GetEmployeeStats

Returns one employee's statistics.

lua---@param job string
---@param citizenid string
---@param days number
---@return table|nil stats
exports['fx-companyapp']:GetEmployeeStats(job, citizenid, days)
lualocal stats = exports['fx-companyapp']:GetEmployeeStats('mechanic', 'ABC12345', 30)

The ranking fields plus pendingCommission, deposited, withdrawn, allTime = { issued, paid, commission } and recent (the last 30 invoices).

#Server exports: business directory

A directory key is the job name, or the group key when several jobs share one directory card.

#GetDirectoryKey

Returns the directory key a job belongs to.

lua---@param job string
---@return string|nil key
exports['fx-companyapp']:GetDirectoryKey(job)
lualocal key = exports['fx-companyapp']:GetDirectoryKey('mechanic')

#GetDirectoryProfile

Returns a business's directory profile.

lua---@param key string
---@return table|nil profile
exports['fx-companyapp']:GetDirectoryProfile(key)
lualocal profile = exports['fx-companyapp']:GetDirectoryProfile('mechanic')

Fields: name, slogan, description, hours, logo, banner, category, accent, location, listed, callable, messaging, callMode, callGrades. Saved values are laid over the defaults.

#SetDirectoryProfile

Changes a business's directory profile from code.

lua---@param key string
---@param patch table
---@return boolean ok
---@return table|string profileOrReason
exports['fx-companyapp']:SetDirectoryProfile(key, patch)
lualocal ok, profile = exports['fx-companyapp']:SetDirectoryProfile('mechanic', { slogan = 'Open every day' })

The patch goes through the same validation as an edit in the app (text limits, allowed image hosts). The stored location is kept. Returns false, 'invalidJob' for a bad key.

#Hooks

Hooks let you block an action before it happens, whether it came from the app or from an export.

#AddHook

Registers a function that runs before an action.

lua---@param name string  Hook name, see the table below
---@param fn fun(payload: table): boolean|nil, string|nil
---@return number|nil hookId
exports['fx-companyapp']:AddHook(name, fn)
lualocal id = exports['fx-companyapp']:AddHook('beforeFire', function(p)
    if p.job == 'police' and GlobalState.raidActive then return false, 'blocked' end
end)
  • Return false, 'reason' to cancel. Any other return value lets the action through.
  • The reason is shown to the player as error.<reason> from the locale file. Unknown reasons show the generic error.
  • Returns nil for an unknown hook name.
  • Hooks are removed when the resource that added them stops.
  • Keep hooks fast. They run inside the player's request.

#RemoveHook

Removes a hook.

lua---@param hookId number
---@return boolean removed
exports['fx-companyapp']:RemoveHook(hookId)
luaexports['fx-companyapp']:RemoveHook(id)
Hook Runs before Payload
beforeHire a hire job, grade, source, actor, targetSource, targetCitizenid, targetName, previousJob
beforeFire a fire job, grade, source, actor, targetSource, targetCitizenid, targetName
beforeSetGrade a rank change job, oldGrade, grade, source, actor, targetSource, targetCitizenid, targetName
beforeDeposit an in-app deposit job, source, actor, amount
beforeWithdraw an in-app withdrawal job, source, actor, amount
beforeAnnounce an in-app announcement job, source, actor, message
beforeMoneyChange AddCompanyMoney / RemoveCompanyMoney job, amount (negative = remove), source, actor, title, category, resource
beforeInvoiceCreate an app invoice / CreateInvoice job, label, amount, note, source, issuerCid, actor, targetSource, targetCid, targetName, resource
beforeInvoicePay an app payment / PayInvoice id, job, amount, label, source, payerCid, issuerCid
beforeInvoiceCancel an app cancel / CancelInvoice id, job, source, actor
beforeSettingsChange a boss saving invoice settings job, source, actor, settings

source is the player who did it, or nil for a system or export action. targetSource is nil when the target is offline.

#Server events

Fired after an action succeeded, with the same payload as the matching hook plus the result fields. They are local server events (TriggerEvent), so clients cannot fire them. Do not register them as net events.

Event Extra fields
fx-companyapp:server:hired gradeName
fx-companyapp:server:fired
fx-companyapp:server:gradeChanged gradeName
fx-companyapp:server:deposit balance (after)
fx-companyapp:server:withdraw balance (after)
fx-companyapp:server:moneyChanged balance (after), from AddCompanyMoney / RemoveCompanyMoney
fx-companyapp:server:announce sent
fx-companyapp:server:invoiceCreated id
fx-companyapp:server:invoicePaid commission, tax, companyShare, account, commissionState (paid, pending or company)
fx-companyapp:server:invoiceCancelled status
fx-companyapp:server:invoiceExpired status
fx-companyapp:server:settingsChanged settings (after)

The directory also fires fx-companyapp:server:profileChanged, fx-companyapp:server:directoryMessage and fx-companyapp:server:ticketReply.

luaAddEventHandler('fx-companyapp:server:withdraw', function(p)
    print(('%s withdrew %d from %s, %d left'):format(p.actor, p.amount, p.job, p.balance))
end)

#Client exports

#GetPhoneResource

Returns the phone in use on this client.

lua---@return string|nil phone  'fx-phone', 'lb-phone', 'cylex_phone' or nil
exports['fx-companyapp']:GetPhoneResource()
lualocal phone = exports['fx-companyapp']:GetPhoneResource()

#IsAppInstalled

Tells whether the app is registered on that phone.

lua---@return boolean
exports['fx-companyapp']:IsAppInstalled()
lualocal installed = exports['fx-companyapp']:IsAppInstalled()

#RefreshApp

Reloads this player's open app.

lua---@param scope? string  'all' (default), 'members', 'kasa', 'logs' or 'invoices'
---@return boolean sent
exports['fx-companyapp']:RefreshApp(scope)
luaexports['fx-companyapp']:RefreshApp('members')

#ReinstallApp

Registers the app into the phone again.

lua---@return boolean ok
exports['fx-companyapp']:ReinstallApp()
luaexports['fx-companyapp']:ReinstallApp()

#Notify

Shows a phone notification from the app on this client.

lua---@param title string
---@param message string
---@return boolean sent
exports['fx-companyapp']:Notify(title, message)
luaexports['fx-companyapp']:Notify('Shift', 'Your shift starts in 5 minutes')

#Error reasons

Returned as the second value when ok is false. Each has a text in locales/*.json under error..

Reason When
invalidJob Job name empty or too long; for hire and rank changes also when the job is not in your job list
invalidAmount Not a positive whole number, or too large
invalidLabel Invoice label empty or not a string
kasaUnavailable The banking resource has no account for this job
insufficientKasa Not enough company funds
insufficientPersonal (app only) The player lacks the money to deposit
playerNotFound The citizen id is not an employee of that job, or the invoice target cannot be found
playerNotOnline The hire target is not online
alreadyInCompany The hire target already has this job
invalidGrade The grade does not exist for the job
companyOnly The player must bill in the company's name
cannotTargetSelf (app only) Acting on yourself
protectedRank (app only) The target is at or above your rank
noPermission (app only) Missing permission
noCompany (app only) The player has no usable company
cooldown (app only) Too fast
blocked A hook cancelled it without giving a reason
generic The framework or bank refused it

#Troubleshooting

Symptom Cause
App does not appear in the phone The phone is not started, or started after this resource
"No company" screen for everyone The job is not in Config.JobWhitelist
Funds always show 0 Wrong Config.Banking.Provider, or that resource is not started
Deposit fails with "funds not ready" The job has no account in your banking resource
Rank names are empty, hiring fails qb-core starts after this resource, or job definitions are missing