ApiBridge

Source: shiva-core/server/sv_api_bridge.lua

Server-side global that connects the FiveM server to the external shiva-api HTTP service. Events emitted via ApiBridge.relay() are queued and flushed in batches.

Availability

ApiBridge is a server-only global. It is available in all server-side shiva module scripts automatically. Client scripts do not have access to it.

When api.endpoint is not configured in config/api.lua, ApiBridge silently no-ops — all calls are safe to make even without shiva-api installed.

Configuration

shiva-core/config/api.lua:

return {
    endpoint          = '',       -- shiva-api base URL, e.g. 'http://localhost:4000'
    secret            = '',       -- shared HMAC secret
    flushInterval     = 2000,     -- ms between batch flushes (default: 2000)
    maxQueueSize      = 200,      -- max queued events before forced flush (default: 200)
    heartbeatInterval = 30000,    -- ms between heartbeat pings (default: 30000)
    relay = {
        events = {},              -- event names to auto-relay from EventBus
    },
}

Methods

ApiBridge.connect()

Establish the connection and start the flush loop. Called automatically by shiva-core on boot — you don't need to call this manually.

ApiBridge.connect()

ApiBridge.relay(event, payload)

Queue an event to be sent to shiva-api.

Parameter	Type	Description
event	string	Event name
payload	table	Payload (must be JSON-serialisable)

ApiBridge.relay('player:moneyChanged', {
    playerId = source,
    amount   = 500,
    type     = 'cash',
})

Events are not sent immediately — they are batched and flushed every flushInterval milliseconds.

ApiBridge.disconnect()

Stop the flush loop and close the connection. Called automatically on resource stop.

ApiBridge.disconnect()

ApiBridge.isReachable()

Returns true if the last heartbeat to shiva-api succeeded.

if ApiBridge.isReachable() then
    ApiBridge.relay('audit:action', payload)
end

ApiBridge.queueDepth()

Returns the number of events currently waiting in the queue.

Log.info('api', 'queue depth', { depth = ApiBridge.queueDepth() })

Auto-relay via EventBus

Set relay.events in the config to automatically forward EventBus events to shiva-api without any extra code:

relay = {
    events = {
        'player:moneyChanged',
        'player:jobChanged',
        'economy:transaction',
    },
},

Any time one of those events fires on the EventBus, ApiBridge will queue it automatically.

Example

-- In any server-side service
RegisterCommand('give', function(source, args)
    local amount = tonumber(args[1]) or 0
    Economy:give(source, 'cash', amount)

    ApiBridge.relay('economy:giveCommand', {
        admin    = GetPlayerName(source),
        amount   = amount,
        serverId = source,
    })
end)