Server

Use these exports to read or manage dealership data from another resource. Call them on the server.

The dealership management exports are admin-gated - they check Framework.isAdmin(playerId) for the player you pass in.

🏢 Dealership Management

addDealership

Creates a new dealership.

---@param playerId number | Admin who is creating the dealership
---@param dealership table | Dealership payload (name, type, area, points, business?, framework_job?, blip?)
---@return table result | { success: boolean, error?: string, dealershipId?: string }
local result = exports.rcore_dealership:addDealership(playerId, dealership)

Admin only. Validates the payload (name, type, area polygon, and required points) and broadcasts the new dealership to all clients.

updateDealership

Updates an existing dealership.

---@param playerId number | Admin performing the update
---@param dealership table | Dealership payload including numeric `id`
---@return table result | { success: boolean, error?: string }
local result = exports.rcore_dealership:updateDealership(playerId, dealership)

Admin only. Changing framework_job clears the dealership's existing permissions.

deleteDealership

Deletes a dealership.

---@param playerId number | Admin performing the deletion
---@param dealershipId number
exports.rcore_dealership:deleteDealership(playerId, dealershipId)

Admin only. Broadcasts the deletion to all clients.

updateDealershipPoint

Updates a single named point of a dealership.

---@param playerId number | Admin performing the update
---@param dealershipId number
---@param pointName string | Zone/point key
---@param coords table | New point coordinates
exports.rcore_dealership:updateDealershipPoint(playerId, dealershipId, pointName, coords)

Admin only.

deleteDealershipPoint

Removes a named point from a dealership.

---@param playerId number | Admin performing the change
---@param dealershipId number
---@param pointName string | Point key to remove
exports.rcore_dealership:deleteDealershipPoint(playerId, dealershipId, pointName)

Admin only.

addDealershipModels

Adds vehicle models to a dealership's catalog.

---@param playerId number | Admin performing the change
---@param dealershipId number
---@param models table|nil | Map of model -> { price = number|nil }. If nil, auto-adds all models matching the dealership type.
---@return table result | { success: boolean, error?: string, addedModels?: string[] }
local result = exports.rcore_dealership:addDealershipModels(playerId, dealershipId, models)

Admin only. Models already in the catalog are skipped.

deleteDealershipModels

Removes vehicle models from a dealership's catalog.

---@param playerId number | Admin performing the change
---@param dealershipId number
---@param models table|nil | Array of model name strings to remove. If nil, removes ALL models.
---@return table result | { success: boolean, error?: string }
local result = exports.rcore_dealership:deleteDealershipModels(playerId, dealershipId, models)

Admin only. Note models here is a list of model names, not a map. Passing nil clears every model.

👔 Employees & Permissions

getDealershipTopEmployee

Returns the top employee of the current period for a dealership.

---@param dealershipId number
---@return table|nil employee | { actor_identifier, actor_name, total_revenue, total_stocked, total_orders, total_test_drives }
local employee = exports.rcore_dealership:getDealershipTopEmployee(dealershipId)

Returns nil if there was no activity in the period. Ranked by revenue, then stock, then orders.

hasEmployeePermission

Checks whether a player's job and grade grant a permission at a business dealership.

---@param playerId number
---@param dealershipId number
---@param permission string | A DealershipPermission value
---@return boolean
local allowed = exports.rcore_dealership:hasEmployeePermission(playerId, dealershipId, permission)

Returns false if the dealership is not a business or the player's job does not match its framework_job.

getEmployeePermissions

Returns the full grade-to-permission map for a business dealership.

---@param playerId number | Must be employed at the dealership's job
---@param dealershipId number
---@return table permissions | { [grade] = { [permission] = true } }
local permissions = exports.rcore_dealership:getEmployeePermissions(playerId, dealershipId)

Returns {} unless the querying player works at the dealership.

setEmployeePermission

Grants or revokes a permission for a job grade at a business dealership.

---@param playerId number|nil | Actor. Must have MANAGE_PERMISSIONS. Pass nil for a trusted server-side call (skips the check).
---@param dealershipId number
---@param grade number | Job grade
---@param permission string | A DealershipPermission value
---@param enabled boolean | true to grant, false to revoke
exports.rcore_dealership:setEmployeePermission(playerId, dealershipId, grade, permission, enabled)

The change is audit-logged when a player performed it.

getDealershipBossJobGradeId

Returns the boss (highest) job grade id for a business dealership.

---@param dealershipId number
---@return number|nil
local bossGrade = exports.rcore_dealership:getDealershipBossJobGradeId(dealershipId)

💰 Finance

isPlateFinanced

Checks whether a plate is under an active finance contract for an identifier.

---@param identifier string | Player/character identifier (not a server id)
---@param plate string
---@return boolean
local financed = exports.rcore_dealership:isPlateFinanced(identifier, plate)

getPlayerFinances

Returns a player's active vehicle finance contracts with display info.

---@param playerId number
---@return table finances | Array of finance entries (balance, installments, plate, vehicle info, ...)
local finances = exports.rcore_dealership:getPlayerFinances(playerId)

Returns {} if the player's identifier cannot be resolved.

🔢 Purchase

validatePlate

Validates a custom plate against length, allowed characters, and uniqueness.

---@param plate string
---@return boolean valid
---@return string|nil reason | A PurchaseReason (PLATE_INVALID, PLATE_TOO_SHORT, PLATE_TOO_LONG, PLATE_TAKEN)
---@return any extra | Min/max length for the length errors
local valid, reason = exports.rcore_dealership:validatePlate(plate)

Length bounds come from Config.Dealership.Purchase.CustomPlate.

📋 NPC Orders

generateNpcOrder

Generates a random NPC vehicle order for a business dealership.

---@param dealershipId number
---@return number|nil orderId
local orderId = exports.rcore_dealership:generateNpcOrder(dealershipId)

Returns nil if the dealership is not a business, has no models, or has no models under the value cap. The Billboard Ads upgrade raises the cap and biases orders toward pricier vehicles.

hasDealershipPendingOrders

Checks whether a dealership has any pending or in-progress orders.

---@param dealershipId number
---@return boolean
local hasOrders = exports.rcore_dealership:hasDealershipPendingOrders(dealershipId)

hasDealershipOnlineEmployees

Checks whether any employee of the dealership's job is online.

---@param dealershipId number
---@return boolean
local hasEmployees = exports.rcore_dealership:hasDealershipOnlineEmployees(dealershipId)

🚗 Test Drive

canPlayerStartTestDrive

Checks whether a player may start a test drive.

---@param playerId number
---@param dealershipId number
---@param driveType string | A TestDriveType value (customer or business)
---@return boolean allowed
---@return string|nil reason | A deny reason (COOLDOWN, PENALTY, WRONG_JOB, ...)
---@return any extra | Remaining time in ms for COOLDOWN/PENALTY
local allowed, reason = exports.rcore_dealership:canPlayerStartTestDrive(playerId, dealershipId, driveType)

Business drives require the dealership's job and the TEST_DRIVE permission. Customer drives check penalty and cooldown windows.

getPlayerTestDrivePenalties

Checks whether an identifier is currently banned from test drives.

---@param identifier string | Player/character identifier (not a server id)
---@return boolean allowed
---@return number|nil remainingMs | Time left on the ban when not allowed
local allowed, remainingMs = exports.rcore_dealership:getPlayerTestDrivePenalties(identifier)

Thresholds come from Config.Dealership.TestDrive.Penalty.

⬆️ Upgrades

hasDealershipUpgrade

Checks whether a dealership has a boolean upgrade active.

---@param dealershipId number
---@param upgrade string | A DealershipUpgrade value
---@return boolean
local hasUpgrade = exports.rcore_dealership:hasDealershipUpgrade(dealershipId, upgrade)

Only returns true for boolean upgrades. Leveled upgrades (stored as a number) are not reported here - use getDealershipUpgrades to read their level.

getDealershipUpgrades

Returns all upgrades for a dealership.

---@param dealershipId number
---@return table upgrades | { [upgrade] = true | level(number) }
local upgrades = exports.rcore_dealership:getDealershipUpgrades(dealershipId)

Returns {} for non-business or unloaded dealerships.

🧾 Audit

recordAudit

Writes an audit-log entry for a business dealership and notifies open tablets.

---@param dealershipId number
---@param action string | An AuditAction key
---@param playerId number | Player who performed the action
---@param value any | Optional logged value (tables are JSON-encoded)
---@param metadata table | Optional extra data (JSON-encoded)
exports.rcore_dealership:recordAudit(dealershipId, action, playerId, value, metadata)

Silently ignored if the dealership is not a loaded business or the player's identifier cannot be resolved.