# ApiVault Zero-Config Addon Integration Shim

`ApiVaultAddonShim.lua` is a ready-to-use drop-in integration file for external addons.

No addon-specific Lua edits are required.

## Install in another addon

1. Copy this file into the target addon folder:

```text
ApiVault/Integrations/ApiVaultAddonShim.lua
```

2. Add it near the end of the target addon's `.toc`:

```toc
## OptionalDeps: ApiVault
ApiVaultAddonShim.lua
```

If the `.toc` already has `## OptionalDeps`, append `ApiVault` to the existing line instead of adding a duplicate metadata line.

That is enough. The shim auto-detects the addon folder name, reads normal runtime metadata when available, checks common SavedVariables names without reading source files, registers with ApiVault when present, and safely does nothing when ApiVault is absent.

## What works without editing the shim

The shim ships standard callbacks for all ApiVault Public Developer API data lanes:

- metadata
- capabilities
- version info
- status
- SavedVariables status
- self-test
- runtime summary
- debug snapshot
- full report
- logs
- recent errors
- API traces
- event traces
- secure-risk reports
- checkpoints
- sessions
- pending report requests

It also includes bridge wrappers for:

- `Log(level, message, context)`
- `ReportError(errorInfo)`
- `TraceAPI(apiName, traceInfo)`
- `TraceEvent(eventName, traceInfo)`
- `ReportSecureRisk(riskInfo)`
- `ReportSavedVariables(statusInfo)`
- `ReportStatus(statusInfo)`
- `ReportSelfTest(resultInfo)`
- `ReportDebugSnapshot(snapshotInfo)`
- `Checkpoint(label, data)`
- `StartSession(name)`
- `EndSession(name)`
- `GetPendingRequests()`
- `AckRequest(requestId)`
- `ExportReport()`

These wrappers are optional for advanced addon authors. A normal addon does not have to call them.

## Optional advanced overrides

Advanced addons may override any standard callback by assigning a function to `ns.ApiVaultIntegration`, but this is optional.

Available override names:

```lua
ns.ApiVaultIntegration.OnGetMetadata = function(integration) end
ns.ApiVaultIntegration.OnGetCapabilities = function(integration) end
ns.ApiVaultIntegration.OnGetVersionInfo = function(integration) end
ns.ApiVaultIntegration.OnGetStatus = function(integration) end
ns.ApiVaultIntegration.OnGetSavedVariablesStatus = function(integration) end
ns.ApiVaultIntegration.OnRunSelfTest = function(integration) end
ns.ApiVaultIntegration.OnBuildRuntimeSummary = function(integration) end
ns.ApiVaultIntegration.OnBuildDebugSnapshot = function(integration) end
ns.ApiVaultIntegration.OnBuildReport = function(integration) end
ns.ApiVaultIntegration.OnGetLogs = function(integration) end
ns.ApiVaultIntegration.OnGetRecentErrors = function(integration) end
ns.ApiVaultIntegration.OnGetAPITraces = function(integration) end
ns.ApiVaultIntegration.OnGetEventTraces = function(integration) end
ns.ApiVaultIntegration.OnGetSecureRisks = function(integration) end
ns.ApiVaultIntegration.OnGetCheckpoints = function(integration) end
ns.ApiVaultIntegration.OnRequest = function(integration, request, bridge) end
ns.ApiVaultIntegration.OnBridgeUnavailable = function(integration) end
ns.ApiVaultIntegration.OnBeforeRegister = function(integration) end
ns.ApiVaultIntegration.OnAfterRegister = function(integration, registered) end
```

Again: overrides are not required.

## StockVault example

No StockVault Lua edits are required.

```toc
## OptionalDeps: ApiVault
ApiVaultAddonShim.lua
```

After `/reload`, use:

```text
/av addons
/av reports
```

Type `StockVault`. ApiVault should show the addon as integrated when both addons are loaded.

## MailVault example

No MailVault Lua edits are required.

```toc
## OptionalDeps: ApiVault
ApiVaultAddonShim.lua
```

After `/reload`, use:

```text
/av addons
/av reports
```

Type `MailVault`. ApiVault should show the addon as integrated when both addons are loaded.

## Safe failure behavior

If ApiVault is not installed or not loaded, the target addon still loads. The shim only stores a small `ns.ApiVaultIntegration` table and exits quietly.

## Safety policy

- No hard dependency on ApiVault.
- No force-loading of ApiVault.
- No runtime source-file reads.
- No `require`, `dofile`, `loadfile`, `os`, `io` or `debug` usage.
- No protected/secure execution.
- No `COMBAT_LOG_EVENT_UNFILTERED` registration.
- No BugGrabber, BugSack or BugGrabberDB mutation.
