# 7 · Developer API

Integrate garages, dealerships, rentals and other server resources through stable exports.

# Server Key Exports

Key creation and removal should be performed from trusted **server-side** resources.

## Recommended simple API

```lua
-- Permanent owner key + physical key item.
exports.nord_vehiclekeys:GiveKeys(source, plate)

-- Remove access/key for the plate.
exports.nord_vehiclekeys:RemoveKeys(source, plate)

-- Check access.
local hasKey, keyType, expiresAt = exports.nord_vehiclekeys:HasKeys(source, plate)
```

Aliases:

```lua
exports.nord_vehiclekeys:AddKey(source, plate)
exports.nord_vehiclekeys:DeleteKey(source, plate)
exports.nord_vehiclekeys:GiveOwnerKey(source, plate)
```

Shared and temporary keys:

```lua
exports.nord_vehiclekeys:GiveSharedKey(source, plate, 0)      -- permanent shared
exports.nord_vehiclekeys:GiveSharedKey(source, plate, 3600)   -- timed shared
exports.nord_vehiclekeys:GiveTempKey(source, plate, 900)      -- temporary
```

Advanced API:

```lua
exports.nord_vehiclekeys:GiveKey(source, plate, 'owner', 0)
exports.nord_vehiclekeys:GiveKey(source, plate, 'shared', 3600)
exports.nord_vehiclekeys:GiveTemporaryKey(source, plate, 900)
exports.nord_vehiclekeys:RemoveKey(source, plate)
exports.nord_vehiclekeys:HasKey(source, plate)
```


# Physical Key Item Exports

These exports work directly with the physical key item layer.

```lua
exports.nord_vehiclekeys:GivePhysicalKeyItem(source, plate, 'owner', 0)
exports.nord_vehiclekeys:RemovePhysicalKeyItem(source, plate)
exports.nord_vehiclekeys:HasPhysicalKeyItem(source, plate)
```

Normally, use `GiveKeys` / `RemoveKeys` instead because they keep permission state and the physical item synchronized.

Use the physical-item exports only when you deliberately need low-level control.


# Server Vehicle Exports

Vehicle state exports operate on a network ID.

```lua
exports.nord_vehiclekeys:SetLockState(netId, true)
exports.nord_vehiclekeys:GetLockState(netId)
exports.nord_vehiclekeys:ToggleLock(netId)
exports.nord_vehiclekeys:LockVehicle(netId)
exports.nord_vehiclekeys:UnlockVehicle(netId)
exports.nord_vehiclekeys:RegisterOwnedVehicle(netId)
exports.nord_vehiclekeys:SetVehicleOwner(netId, identifier)
```

`RegisterOwnedVehicle` is useful after spawning a framework-owned vehicle so the resource can initialize its authoritative state.

`SetVehicleOwner` creates a runtime ownership override for trusted custom/standalone integrations.


# Client Exports

Client exports are useful for UI, vehicle interactions and custom gameplay.

```lua
local hasKey = exports.nord_vehiclekeys:HasKey(vehicleOrPlate)
local hasLocal = exports.nord_vehiclekeys:HasLocalKey(vehicleOrPlate)

exports.nord_vehiclekeys:ToggleLock(vehicle)
exports.nord_vehiclekeys:LockVehicle(vehicle)
exports.nord_vehiclekeys:UnlockVehicle(vehicle)

local vehicle, distance = exports.nord_vehiclekeys:GetClosestVehicle(10.0)
exports.nord_vehiclekeys:OpenKeyRemote(slot)
```

The theft module also exposes:

```lua
exports.nord_vehiclekeys:StartLockpick(vehicle)
exports.nord_vehiclekeys:StartHotwire(vehicle)
exports.nord_vehiclekeys:StartCarjack(vehicle, driver)
```

Physical item-use handlers are also exposed internally for inventory integration, but normal external resources should use the higher-level key exports.


# Garage Integration

A garage that spawns a player's owned vehicle should register the entity and only issue a key when the garage intentionally wants to hand one to the player.

Server example:

```lua
local netId = NetworkGetNetworkIdFromEntity(vehicle)
exports.nord_vehiclekeys:RegisterOwnedVehicle(netId)
exports.nord_vehiclekeys:GiveKeys(source, plate)
```

If the garage stores the vehicle and should remove the currently issued key:

```lua
exports.nord_vehiclekeys:RemoveKeys(source, plate)
```

Do not create an insecure client event that accepts an arbitrary `source` and `plate` and forwards them directly to `GiveKeys`.


# Dealership Integration

When a player purchases a vehicle, issue the key **after** the purchase and ownership transaction succeeds.

```lua
-- purchase validated, money removed and ownership row saved first
exports.nord_vehiclekeys:GiveKeys(source, plate)
```

When a dealership sells/transfers/removes a vehicle from a player, remove the old holder's key deliberately:

```lua
exports.nord_vehiclekeys:RemoveKeys(oldOwnerSource, plate)
```

If the new owner is online:

```lua
exports.nord_vehiclekeys:GiveKeys(newOwnerSource, plate)
```

This keeps physical key ownership explicit and avoids silent regeneration.


# Rental Integration

Rental scripts should normally use temporary keys.

Example 30-minute rental:

```lua
exports.nord_vehiclekeys:GiveTempKey(source, plate, 1800)
```

When the rental ends early:

```lua
exports.nord_vehiclekeys:RemoveKeys(source, plate)
```

For a shared company vehicle with a known duration:

```lua
exports.nord_vehiclekeys:GiveSharedKey(source, plate, 3600)
```

Choose `temporary` for a short-lived one-player rental and `shared` when the semantics are intentionally shared access.