@venturekit-pro/audit 0.0.0-dev.20260602192622

package/dist/types.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Audit-event domain types.
+ *
+ * Mirrors `audit_events` table columns 1:1, with the caller-facing
+ * `record()` input shape derived from it. Keep these aligned with the
+ * SQL in `migrations/vk_audit_0001_init.sql`.
+ */
+/**
+ * Actor that performed the action. Mirrors the Postgres
+ * `vk_audit_actor_type` enum.
+ *
+ *   user    — end-user via session token (Cognito sub, etc).
+ *   service — internal service identity (workflow runner, worker).
+ *   cron    — scheduled-job Lambda.
+ *   api_key — programmatic-access key (the actor id carries the
+ *             key prefix; never the raw key).
+ *   system  — bootstrap / migration / cross-tenant maintenance.
+ */
+export type AuditActorType = 'user' | 'service' | 'cron' | 'api_key' | 'system';
+/**
+ * Outcome of the audited action. Mirrors the Postgres
+ * `vk_audit_status` enum and matches `venturekit-cms`'s legacy
+ * `job_status` shape so apps porting from `jobs_log` get a 1:1
+ * mapping.
+ */
+export type AuditStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'skipped';
+/**
+ * Compound identity of the actor.
+ */
+export interface AuditActor {
+    type: AuditActorType;
+    /**
+     * Free-form id. User → auth sub. Service → service name. api_key →
+     * key prefix. cron → schedule rule name. Optional for system / bootstrap.
+     */
+    id?: string | null;
+}
+/**
+ * The thing the action was done to. Optional — events like
+ * `cron.tick` don't target a specific row.
+ */
+export interface AuditTarget {
+    /** Logical type (e.g. `'blog_post'`, `'social_post'`, `'editorial_run'`). */
+    type: string;
+    /** Primary key of the target row. */
+    id: string;
+    /** Optional secondary identifier for human-readable refs (slug, label). */
+    slug?: string | null;
+}
+/**
+ * Caller-facing input to `record()`. Strictly typed on the in-args
+ * the package guarantees to preserve; opaque `payload` carries
+ * whatever else the event-kind needs.
+ *
+ * Strictly audit-scoped: WHO did WHAT, TO WHAT, WHEN, HOW IT WENT.
+ * Domain-specific fields (cost, tokens, payment amounts, …) live
+ * in their own packages' tables and reference this one via
+ * `correlationId`.
+ */
+export interface AuditEventInput {
+    /** Tenant the event belongs to. Pass `null` only for platform-wide events. */
+    tenantId: string | null;
+    /** Who did the thing. */
+    actor: AuditActor;
+    /** Free-form, namespaced event kind (e.g. `'blog.save'`). */
+    kind: string;
+    /** Optional target row. */
+    target?: AuditTarget;
+    /** Outcome. Defaults to `'succeeded'`. */
+    status?: AuditStatus;
+    /** Free-form details. Caller's responsibility to keep small + PII-free. */
+    payload?: Record<string, unknown>;
+    /** Threads multiple events into one logical operation. */
+    correlationId?: string | null;
+    /** Optional idempotency token for safe retries. */
+    idempotencyKey?: string | null;
+    /** Failure summary when `status === 'failed'`. */
+    errorMessage?: string | null;
+}
+/**
+ * Persisted row shape. Mirrors `audit_events` columns post-mapping
+ * (snake_case → camelCase). Returned by `record()` and the query
+ * helpers.
+ */
+export interface AuditEvent {
+    id: string;
+    tenantId: string | null;
+    actorType: AuditActorType;
+    actorId: string | null;
+    kind: string;
+    targetType: string | null;
+    targetId: string | null;
+    targetSlug: string | null;
+    status: AuditStatus;
+    payload: Record<string, unknown>;
+    correlationId: string | null;
+    idempotencyKey: string | null;
+    errorMessage: string | null;
+    createdAt: string;
+}
+/**
+ * Minimal querier shape — a function that runs a parameterized SQL
+ * statement and returns rows. Matches `@venturekit/data`'s `Querier`
+ * type so consumers can pass `query` directly. Kept structural so
+ * apps using a different Postgres driver can still inject their own
+ * adapter.
+ */
+export type Querier = <T = Record<string, unknown>[]>(sql: string, params?: unknown[]) => Promise<T>;
+/**
+ * Counters returned by `countEvents()` / `countEventsByKind()`. The
+ * audit package's only aggregation surface — anything more domain-
+ * specific (cost rollups, payment totals, token usage) lives in the
+ * package that owns those concerns.
+ */
+export interface EventCount {
+    /** Number of events matching the filter. */
+    count: number;
+    /** Per-prefix split when caller passes `byKindPrefix`. */
+    byKindPrefix: Record<string, number>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,GACtB,MAAM,GACN,SAAS,GACT,MAAM,GACN,SAAS,GACT,QAAQ,CAAC;AAEb;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEpF;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,cAAc,CAAC;IACrB;;;OAGG;IACH,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,yBAAyB;IACzB,KAAK,EAAE,UAAU,CAAC;IAClB,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,2BAA2B;IAC3B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAGlC,0DAA0D;IAC1D,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,mDAAmD;IACnD,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,kDAAkD;IAClD,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,cAAc,CAAC;IAC1B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,WAAW,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAClD,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,OAAO,EAAE,KACf,OAAO,CAAC,CAAC,CAAC,CAAC;AAEhB;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC"}

package/dist/types.js

@@ -0,0 +1,9 @@
+/**
+ * Audit-event domain types.
+ *
+ * Mirrors `audit_events` table columns 1:1, with the caller-facing
+ * `record()` input shape derived from it. Keep these aligned with the
+ * SQL in `migrations/vk_audit_0001_init.sql`.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@venturekit-pro/audit",
+  "version": "0.0.0-dev.20260602192622",
+  "description": "Append-only audit + cost-tracking log for VentureKit applications",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src/migrations/*.sql"
+  ],
+  "vk": {
+    "migrations": "src/migrations"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/venturekit-dev/venturekit.private.git",
+    "directory": "packages/pro/audit"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "license": "SEE LICENSE IN ../LICENSE",
+  "licenseHeader": "VentureKit Pro Commercial License — production use requires a valid VentureKit Pro license key. See https://venturekit.dev/pricing.",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "keywords": [
+    "venturekit",
+    "saas",
+    "audit",
+    "cost-tracking",
+    "compliance"
+  ],
+  "dependencies": {
+    "@venturekit/core": "0.0.0-dev.20260602192622"
+  },
+  "peerDependencies": {
+    "@venturekit/data": "0.0.0-dev.20260602192622"
+  },
+  "peerDependenciesMeta": {
+    "@venturekit/data": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "@venturekit/data": "0.0.0-dev.20260602192622",
+    "typescript": "^5.3.0"
+  },
+  "scripts": {
+    "build": "tsc && node -e \"require('fs').cpSync('src/migrations','dist/migrations',{recursive:true})\"",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist"
+  }
+}

package/src/migrations/vk_audit_0001_init.sql

@@ -0,0 +1,152 @@
+-- @venturekit-pro/audit — initial schema.
+--
+-- One canonical, append-only `audit_events` table. Stores WHO did
+-- WHAT, TO WHAT, WHEN, and HOW IT WENT. Nothing else.
+--
+-- **Strict scope.** The audit package does not know about LLM costs,
+-- token counts, image generation, payment amounts, or any other
+-- domain concern. Those live in their own packages / tables
+-- (e.g. `@venturekit-pro/ai`'s `llm_cost_events`); audit events
+-- merely reference them by `target_type` / `target_id` /
+-- `correlation_id`.
+--
+-- Append-only by construction:
+--   - No UPDATE / DELETE statements are issued by the package code.
+--   - DB-level REVOKE on `audit_events` from the application role
+--     at the bottom of this migration enforces it physically.
+--     Privileged maintenance (retention pruning) runs as a
+--     separate role.
+--
+-- Idempotency:
+--   - `idempotency_key` is OPTIONAL on insert. When set, the
+--     partial unique index makes a re-insert a no-op (caller
+--     catches the duplicate-key error in `record()` and returns
+--     the original row).
+
+CREATE EXTENSION IF NOT EXISTS pgcrypto;
+
+-- ─── Status enum ────────────────────────────────────────────────────
+--
+-- Outcome of an audited action. Mirrors the standard `job_status`
+-- shape so callers can map 1:1.
+
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_type WHERE typname = 'vk_audit_status') THEN
+    CREATE TYPE vk_audit_status AS ENUM (
+      'queued',
+      'running',
+      'succeeded',
+      'failed',
+      'skipped'
+    );
+  END IF;
+END
+$$;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_type WHERE typname = 'vk_audit_actor_type') THEN
+    CREATE TYPE vk_audit_actor_type AS ENUM (
+      'user',      -- end-user via session token
+      'service',   -- internal service identity
+      'cron',      -- scheduled-job Lambda
+      'api_key',   -- programmatic-access key
+      'system'     -- bootstrap / migration / cross-tenant maintenance
+    );
+  END IF;
+END
+$$;
+
+-- ─── audit_events ───────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS audit_events (
+  id              uuid                PRIMARY KEY DEFAULT gen_random_uuid(),
+  -- tenant_id is nullable so we can record platform-wide events
+  -- (e.g. cron sweeps that fan out across every tenant). Per-tenant
+  -- views filter on `tenant_id = $1`; the rare cross-tenant rows
+  -- show up only when querying with `tenant_id IS NULL`.
+  tenant_id       uuid,
+  -- WHO did the thing.
+  actor_type      vk_audit_actor_type NOT NULL,
+  -- Free-form actor id. For users: their auth id (e.g. Cognito sub).
+  -- For services: service name. For api_key: key prefix. For cron:
+  -- schedule rule name. NULL only for bootstrap / system rows.
+  actor_id        text,
+  -- WHAT happened. Free-form, app-namespaced (e.g. `'blog.save'`,
+  -- `'order.refunded'`, `'security.login'`). The package never
+  -- enumerates these; the calling app owns its kind taxonomy.
+  kind            text                NOT NULL,
+  -- WHAT it was done to (optional). target_type + target_id together
+  -- identify the row this event mutated or read.
+  target_type     text,
+  target_id       text,
+  -- Secondary identifier for human-readable references (slug, label).
+  target_slug     text,
+  -- Outcome of the action. Finalized rows are NEVER UPDATE'd; long
+  -- operations write a `running` row, then a separate `succeeded` /
+  -- `failed` / `skipped` row with the same `correlation_id`.
+  status          vk_audit_status     NOT NULL DEFAULT 'succeeded',
+  -- Free-form payload. Caller's responsibility to keep this small
+  -- (~< 32KB) and PII-free. Heavy artifacts go in S3 + are
+  -- referenced by URL/key.
+  payload         jsonb               NOT NULL DEFAULT '{}'::jsonb,
+
+  -- ─── Cross-event correlation ─────────────────────────────────────
+
+  -- Threads multiple events into one logical operation (a workflow
+  -- run, an HTTP request, a saga).
+  correlation_id  text,
+  -- Optional idempotency token; supports safe retry of e.g. cron
+  -- ticks. NULL is allowed and skips the dedup check.
+  idempotency_key text,
+  -- Human-readable failure summary when `status = 'failed'`.
+  error_message   text,
+
+  created_at      timestamptz         NOT NULL DEFAULT now()
+);
+
+-- ─── Indexes ────────────────────────────────────────────────────────
+
+-- Main page query: "show me the last N events for this tenant".
+CREATE INDEX IF NOT EXISTS audit_events_tenant_created_idx
+  ON audit_events (tenant_id, created_at DESC);
+
+-- Filtered list: "show me the last N 'order.refunded' events".
+CREATE INDEX IF NOT EXISTS audit_events_tenant_kind_idx
+  ON audit_events (tenant_id, kind, created_at DESC);
+
+-- Per-entity history: "every event touching blog_post X".
+CREATE INDEX IF NOT EXISTS audit_events_target_idx
+  ON audit_events (tenant_id, target_type, target_id, created_at DESC);
+
+-- Correlation join: "every event in this workflow run".
+CREATE INDEX IF NOT EXISTS audit_events_correlation_idx
+  ON audit_events (correlation_id, created_at DESC)
+  WHERE correlation_id IS NOT NULL;
+
+-- Idempotency dedup. Partial because the vast majority of rows
+-- have idempotency_key = NULL.
+CREATE UNIQUE INDEX IF NOT EXISTS audit_events_idempotency_unique
+  ON audit_events (idempotency_key)
+  WHERE idempotency_key IS NOT NULL;
+
+-- ─── Append-only enforcement at the storage layer ───────────────────
+--
+-- The application role can INSERT and SELECT but never UPDATE /
+-- DELETE. A privileged maintenance role (whatever the app uses to
+-- run migrations) retains full privileges, and is what retention
+-- sweeps run as.
+--
+-- We don't know the application role's name at migration time — apps
+-- vary (`venturekit_cms_app`, `myapp_runtime`, …). The REVOKE here
+-- targets `PUBLIC` which covers the default no-role-set case AND
+-- means the application role inherits the lockdown unless explicitly
+-- granted UPDATE/DELETE. Apps that grant their runtime role
+-- `ALL PRIVILEGES` on the schema must re-revoke after this migration.
+
+REVOKE UPDATE, DELETE ON audit_events FROM PUBLIC;
+
+-- A convenience GRANT so the app role still works for inserts and
+-- reads when only PUBLIC's privileges were revoked.
+GRANT SELECT, INSERT ON audit_events TO PUBLIC;