All helpers take a Querier first — <T>(sql: string, params?: unknown[]) => Promise<T>, satisfied by @venturekit/data’s query or a transaction’s query.
| Function | Signature | Description |
|---|
record(q, input) | (Querier, AuditEventInput) => Promise<AuditEvent> | Append one event. Idempotent when idempotencyKey is set |
listEvents(q, args) | (Querier, ListEventsArgs) => Promise<AuditEvent[]> | Filter by kind, kindPrefix, targetType/targetId, correlationId, actorType, status; limit + beforeId keyset pagination |
countEvents(q, args) | (Querier, CountEventsArgs) => Promise<EventCount> | Same filters plus since/until and an optional byKindPrefix: string[] split → { count, byKindPrefix } |
monthlyEventCounts(q, args) | (Querier, MonthlyEventCountsArgs) => Promise<MonthlyCountBucket[]> | monthCount monthly buckets ({ month, count, byKindPrefix }) |
previewPrune(q, options) | (Querier, PruneOptions) => Promise<Array<{ id, createdAt, tenantId, kind }>> | Rows that pruneAuditEvents would delete — safe from the app role |
pruneAuditEvents(q, options) | (Querier, PruneOptions) => Promise<number> | Delete events older than olderThanDays in batches (batchSize default 1000, max 100 000), optionally for one tenantId. Needs DELETE privileges |
getAuditMigrationsDir() | () => string | Absolute path of the shipped vk_audit_*.sql migrations (auto-discovered by vk migrate) |
| Type | Description |
|---|
AuditEventInput | { tenantId: string | null, actor, kind, target?, status?, payload?, correlationId?, idempotencyKey?, errorMessage? } |
AuditEvent | Persisted row — id, tenantId, actorType, actorId, kind, targetType, targetId, targetSlug, status, payload, correlationId, idempotencyKey, errorMessage, createdAt |
AuditActor | { type: AuditActorType, id?: string | null } |
AuditActorType | 'user' | 'service' | 'cron' | 'api_key' | 'system' |
AuditTarget | { type: string, id: string, slug?: string | null } |
AuditStatus | 'queued' | 'running' | 'succeeded' | 'failed' | 'skipped' (Postgres enum vk_audit_status) |
ListEventsArgs / CountEventsArgs / MonthlyEventCountsArgs | Filter shapes described above |
EventCount / MonthlyCountBucket | Aggregation results |
PruneOptions | { olderThanDays: number, batchSize?: number, tenantId?: string | null } |
Querier | The query-function shape every helper accepts |