Audit Logging | blade47/dub Wiki | doc0

Public

Audit Logging | blade47/dub Wiki | doc0

Field Name	Zod Type	Nullable	Description
`id`	`z.string()`	No	Unique audit log identifier prefixed with `audit_`. Sources: apps/web/lib/api/audit-logs/schemas.ts:17-17
`timestamp`	`z.string()`	No	ISO 8601 timestamp generated at record creation. Sources: apps/web/lib/api/audit-logs/schemas.ts:18-18
`workspace_id`	`z.string()`	No	Prefixed workspace identifier associated with the event. Sources: apps/web/lib/api/audit-logs/schemas.ts:19-19
`program_id`	`z.string()`	No	Program identifier associated with the workspace action. Sources: apps/web/lib/api/audit-logs/schemas.ts:20-20
`action`	`z.string()`	No	Categorized action string validated against supported actions. Sources: apps/web/lib/api/audit-logs/schemas.ts:21-21
`actor_id`	`z.string()`	No	Identifier of the user or system entity performing the action. Sources: apps/web/lib/api/audit-logs/schemas.ts:22-22
`actor_type`	`z.string()`	No	Classification of the actor, defaulting to `user`. Sources: apps/web/lib/api/audit-logs/schemas.ts:23-23
`actor_name`	`z.string()`	No	Display name of the actor. Sources: apps/web/lib/api/audit-logs/schemas.ts:24-24
`description`	`z.string()`	No	Human-readable narrative description of the event. Sources: apps/web/lib/api/audit-logs/schemas.ts:25-25
`targets`	`z.string()`	Yes	JSON-serialized array of targeted resources and entity metadata. Sources: apps/web/lib/api/audit-logs/schemas.ts:26-26
`ip_address`	`z.string()`	Yes	Client IP address captured from request headers or Vercel runtime. Sources: apps/web/lib/api/audit-logs/schemas.ts:27-27
`user_agent`	`z.string()`	Yes	Client user-agent string extracted from request headers. Sources: apps/web/lib/api/audit-logs/schemas.ts:28-28
`metadata`	`z.string()`	Yes	JSON-serialized custom metadata dictionary. Sources: apps/web/lib/api/audit-logs/schemas.ts:29-29

Schema Name	Target Field / Property	Zod Definition / Type	Purpose
`auditLogFilterSchemaTB`	`workspaceId`	`z.string().transform(prefixWorkspaceId)`	Validates and prefixes workspace ID. Sources: apps/web/lib/api/audit-logs/get-audit-logs.ts:7-7
`auditLogFilterSchemaTB`	`programId`	`z.string()`	Identifies the program context. Sources: apps/web/lib/api/audit-logs/get-audit-logs.ts:8-8
`auditLogFilterSchemaTB`	`start` / `end`	`z.string()`	Query time boundaries. Sources: apps/web/lib/api/audit-logs/get-audit-logs.ts:9-10
`auditLogResponseSchemaTB`	`id` / `timestamp` / `action`	`z.string()`	Core event metadata identifiers. Sources: apps/web/lib/api/audit-logs/get-audit-logs.ts:14-16
`auditLogResponseSchemaTB`	`actor_id` / `actor_type` / `actor_name`	`z.string()`	Actor identity attributes. Sources: apps/web/lib/api/audit-logs/get-audit-logs.ts:17-19
`auditLogResponseSchemaTB`	`description` / `ip_address` / `user_agent`	`z.string()`	Narrative and client connection details. Sources: apps/web/lib/api/audit-logs/get-audit-logs.ts:20-22
`auditLogResponseSchemaTB`	`targets` / `metadata`	`z.string()`	Serialized JSON target resources and custom metadata. Sources: apps/web/lib/api/audit-logs/get-audit-logs.ts:23-24

export async function exportAuditLogs() {
  const response = await fetch(
    `/api/audit-logs/export?workspaceId=${workspaceId}`,
    {
      method: "POST",
      body: JSON.stringify({ start, end }),
      headers: { "Content-Type": "application/json" },
    },
  );
 
  if (!response.ok) {
    const { error } = await response.json();
    throw new Error(error.message);
  }
 
  const blob = await response.blob();
  const url = window.URL.createObjectURL(blob);
  const a = document.createElement("a");
  a.href = url;
  a.download = `Dub Audit Logs Export - ${new Date().toISOString()}.csv`;
  a.click();
}

Column Name	Prisma Type	Modifiers / Attributes	Description
`id`	`String`	`@id @default(cuid())`	Unique identifier for the activity log entry. Sources: apps/web/prisma/schema/activity.prisma:2-2
`workspaceId`	`String`	None	Workspace context identifier. Sources: apps/web/prisma/schema/activity.prisma:3-3
`programId`	`String`	None	Program context identifier. Sources: apps/web/prisma/schema/activity.prisma:4-4
`parentResourceType`	`String`	`@nullable`	Optional parent resource classification. Sources: apps/web/prisma/schema/activity.prisma:5-5
`parentResourceId`	`String`	`@nullable`	Optional parent resource identifier. Sources: apps/web/prisma/schema/activity.prisma:6-6
`resourceType`	`String`	None	Target resource classification. Sources: apps/web/prisma/schema/activity.prisma:7-7
`resourceId`	`String`	None	Target resource identifier. Sources: apps/web/prisma/schema/activity.prisma:8-8
`userId`	`String`	`@nullable`	Optional actor user identifier. Sources: apps/web/prisma/schema/activity.prisma:9-9
`action`	`String`	None	Performed action identifier string. Sources: apps/web/prisma/schema/activity.prisma:10-10
`description`	`String`	`@nullable @db.Text`	Optional human-readable narrative text. Sources: apps/web/prisma/schema/activity.prisma:11-11
`batchId`	`String`	`@nullable`	Optional batch grouping identifier. Sources: apps/web/prisma/schema/activity.prisma:12-12
`changeSet`	`Json`	`@nullable`	Structured diff payload JSON. Sources: apps/web/prisma/schema/activity.prisma:13-13
`createdAt`	`DateTime`	`@default(now())`	Timestamp when the entry was recorded. Sources: apps/web/prisma/schema/activity.prisma:14-14

Design Choice	Benefit	Cost
Whitelisted Actions Without ChangeSet	Allows creation events (like rewards and leads) to log without prior diff states. Sources: apps/web/lib/api/activity-log/track-activity-log.ts:11-15	Requires maintaining explicit exemption arrays when new lifecycle creation actions are introduced. Sources: apps/web/lib/api/activity-log/track-activity-log.ts:11-15
Separate Transactional Helper (`trackActivityLogsTx`)	Prevents dangling activity records when parent business logic transactions roll back. Sources: apps/web/lib/api/activity-log/track-activity-log.ts:68-93	Callers must explicitly thread the transaction client `tx` through repository service layers. Sources: apps/web/lib/api/activity-log/track-activity-log.ts:68-74
JSON ChangeSet Column with FieldDiff Schema	Stores arbitrary structural updates (`old` and `new` unknown values) flexibly. Sources: apps/web/prisma/schema/activity.prisma:13-13, apps/web/lib/zod/schemas/activity-log.ts:57-60	Loses relational column-level indexing on inner diff properties within queries. Sources: apps/web/prisma/schema/activity.prisma:1-20

export async function trackCommissionActivityLog({
  old: oldCommissions,
  new: newCommissions,
  ...baseInput
}: TrackActivityLogParams) {
  const activityLogs: TrackActivityLogInput[] = [];
 
  const oldById = new Map((oldCommissions ?? []).map((c) => [c.id, c]));
  const newById = new Map((newCommissions ?? []).map((c) => [c.id, c]));
 
  const commissionIds = [
    ...new Set([...oldById.keys(), ...newById.keys()]),
  ].sort();
 
  for (const id of commissionIds) {
    const oldCommission = oldById.get(id);
    const newCommission = newById.get(id);
 
    if (oldCommission && newCommission) {
      const oldSnapshot = toCommissionActivitySnapshot(oldCommission);
      const newSnapshot = toCommissionActivitySnapshot(newCommission);
 
      const diff = getResourceDiff(oldSnapshot, newSnapshot, {
        fields: COMMISSION_ACTIVITY_FIELDS,
      });
 
      if (diff) {
        activityLogs.push({
          ...baseInput,
          resourceId: newCommission.id,
          resourceType: "commission",
          action: "commission.updated",
          changeSet: {
            commission: {
              old: oldSnapshot,
              new: newSnapshot,
            },
          },
        });
      }
    }
  }
 
  return await trackActivityLog(activityLogs);
}

Reward Action	Trigger Condition	ChangeSet Structure
`reward.created`	`old` is `null` and `new` is present	`{ reward: { old: null, new: newSnapshot } }`
`reward.updated`	Both `old` and `new` are present, and `getResourceDiff` finds changes	`{ reward: { old: oldSnapshot, new: newSnapshot } }`
`reward.deleted`	`old` is present and `new` is `null`	`{ reward: { old: oldSnapshot, new: null } }`
`reward.conditionAdded`	Modifier ID exists in new modifiers but not old	`{ reward: { old: null, new: { ...newReward, modifiers: [newMod] } } }`
`reward.conditionUpdated`	Modifier ID exists in both but `modifierEquals` returns false	`{ reward: { old: { ...oldReward, modifiers: [oldMod] }, new: { ...newReward, modifiers: [newMod] } } }`
`reward.conditionRemoved`	Modifier ID exists in old modifiers but is missing in new	`{ reward: { old: { ...oldReward, modifiers: [oldMod] }, new: null } }`

Hook Name	Target Endpoint	Enabling Conditions	Returned Properties
`useActivityLogs`	`/api/activity-logs?${searchParams}`	`enabled && workspaceId && query?.resourceType && (query?.parentResourceId
`usePartnerActivityLogs`	`/api/partner-profile/programs/${programSlug}/activity-logs?${searchParams}`	`enabled && programSlug && query?.resourceType && query?.resourceId`	`activityLogs`, `error`, `loading`, `mutate`
`usePartnerEnrollmentHistorySheet`	Route query params via `useRouterStuff`	`partner?.id` exists	`hasActivityLogs`, `partnerEnrollmentHistorySheet`, `setIsOpen`

export const recordApiLog = async ({
  workspaceId,
  method,
  path,
  routePattern,
  statusCode,
  duration,
  userAgent,
  requestBody,
  queryParams,
  responseBody,
  tokenId,
  userId,
  requestType,
}: RecordApiLogParams) => {
  const apiLog: ApiLogInput = {
    id: createId({ prefix: "req_" }),
    timestamp: new Date().toISOString(),
    workspace_id: workspaceId,
    method,
    path: path.replace("/api/", "/"),
    route_pattern: routePattern,
    status_code: statusCode,
    duration,
    user_agent: userAgent ?? "",
    request_body: JSON.stringify(requestBody),
    query_params: queryParams ? JSON.stringify(queryParams) : "",
    response_body: JSON.stringify(responseBody),
    token_id: tokenId ?? "",
    user_id: userId ?? "",
    request_type: requestType,
  };
  return await recordApiLogTB(apiLog);
};

Endpoint Route	Required Permission	Query Validation Schema	Retention & Enrichment Behavior
`GET /api/logs`	`workspaces.read`	`getApiLogsQuerySchema` via `searchParams`	Applies `getApiLogsDateRange` based on workspace plan, fetches filtered logs, and enriches them. Sources: apps/web/app/api/logs/route.ts:8-40
`GET /api/logs/:logId`	`workspaces.read`	Route parameter `logId`	Fetches single log by ID, throws `not_found` if missing or older than plan retention date, and enriches log data. Sources: apps/web/app/api/logs/logId/route.ts:9-45