# Public Developer API

ApiVault exposes a data-only debug bridge for external addons.

## Basic usage

```lua
local AV = ApiVault and ApiVault.GetPublicAPI and ApiVault:GetPublicAPI("MyAddon", 1)

if AV then
    AV:RegisterAddon({
        name = "MyAddon",
        version = "1.0.0",
        interface = select(4, GetBuildInfo()),
    })

    AV:Log("info", "MyAddon initialized")
    AV:TraceAPI("C_Item.GetItemInfo", {
        file = "MyAddon/Items.lua",
        line = 42,
        context = "Item cache refresh",
    })
end
```

## Bridge methods

```text
RegisterAddon(metadata)
Log(level, message, context)
ReportError(errorInfo)
TraceAPI(apiName, traceInfo)
TraceEvent(eventName, traceInfo)
ReportSecureRisk(riskInfo)
ReportSavedVariables(svInfo)
Checkpoint(label, data)
StartSession(name)
EndSession(name)
GetReport()
ExportReport()
HasCapability(name)
GetCapabilities()
GetVersion()
```

## Policy

```text
- Data-only bridge
- No addon-provided function execution
- No runtime file reads
- No protected/secure execution
```


## Opt-in report requests

ApiVault can create pending requests for integrated addons. This is opt-in only. ApiVault does not execute addon code.

Bridge methods added:

```text
GetPendingRequests()
AckRequest(requestId)
ReportStatus(statusInfo)
ReportSelfTest(resultInfo)
ReportDebugSnapshot(snapshotInfo)
```

Example:

```lua
local AV = ApiVault and ApiVault.GetPublicAPI and ApiVault:GetPublicAPI("MyAddon", 1)

if AV then
    for _, request in ipairs(AV:GetPendingRequests()) do
        if request.requestType == "full-debug-report" then
            AV:ReportStatus({ status = "reporting" })
            AV:ReportDebugSnapshot({ label = "manual report" })
            AV:AckRequest(request.id)
        end
    end
end
```


## SavedVariables report recommendation

For reliable SavedVariables visibility, addons should report their own DB names because `.toc` SavedVariables directives are not reliably exposed by runtime metadata APIs.

```lua
AV:ReportSavedVariables({
    name = "MyAddonDB",
    initialized = type(MyAddonDB) == "table",
    schemaVersion = type(MyAddonDB) == "table" and MyAddonDB.schemaVersion or nil,
    scope = "account",
    expectedFile = "WTF/Account/<Account>/SavedVariables/MyAddon.lua",
    source = "MyAddon ApiVaultBridge",
})
```
