tychat-contracts 1.4.4 → 1.4.6

package/.github/workflows/publish-npm.yml

@@ -0,0 +1,25 @@
+name: Publish packages
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - 'v*.*.*'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+          cache: npm
+      - run: npm ci
+      - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/dist/analytics/analytics-kafka-topics.d.ts

@@ -11,4 +11,8 @@ export declare const TOPIC_ANALYTICS_DASHBOARD = "analytics.dashboard";
 export declare const TOPIC_ANALYTICS_TIMESERIES = "analytics.timeseries";
 /** Topic for requesting event details with pagination. */
 export declare const TOPIC_ANALYTICS_EVENTS_LIST = "analytics.events.list";
+/** Topic for ingesting tenant user-action audit rows (dedicated table). */
+export declare const TOPIC_ANALYTICS_TENANT_AUDIT_INGEST = "analytics.tenant_audit.ingest";
+/** Topic for paginated tenant audit log listing. */
+export declare const TOPIC_ANALYTICS_TENANT_AUDIT_LIST = "analytics.tenant_audit.list";
 //# sourceMappingURL=analytics-kafka-topics.d.ts.map

package/dist/analytics/analytics-kafka-topics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analytics-kafka-topics.d.ts","sourceRoot":"","sources":["../../src/analytics/analytics-kafka-topics.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,kEAAkE;AAClE,eAAO,MAAM,qBAAqB,oBAAoB,CAAC;AAEvD,sEAAsE;AACtE,eAAO,MAAM,sBAAsB,qBAAqB,CAAC;AAEzD,oEAAoE;AACpE,eAAO,MAAM,yBAAyB,wBAAwB,CAAC;AAE/D,8DAA8D;AAC9D,eAAO,MAAM,0BAA0B,yBAAyB,CAAC;AAEjE,0DAA0D;AAC1D,eAAO,MAAM,2BAA2B,0BAA0B,CAAC"}
+{"version":3,"file":"analytics-kafka-topics.d.ts","sourceRoot":"","sources":["../../src/analytics/analytics-kafka-topics.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,kEAAkE;AAClE,eAAO,MAAM,qBAAqB,oBAAoB,CAAC;AAEvD,sEAAsE;AACtE,eAAO,MAAM,sBAAsB,qBAAqB,CAAC;AAEzD,oEAAoE;AACpE,eAAO,MAAM,yBAAyB,wBAAwB,CAAC;AAE/D,8DAA8D;AAC9D,eAAO,MAAM,0BAA0B,yBAAyB,CAAC;AAEjE,0DAA0D;AAC1D,eAAO,MAAM,2BAA2B,0BAA0B,CAAC;AAEnE,2EAA2E;AAC3E,eAAO,MAAM,mCAAmC,kCAAkC,CAAC;AAEnF,oDAAoD;AACpD,eAAO,MAAM,iCAAiC,gCAAgC,CAAC"}

package/dist/analytics/analytics-kafka-topics.js

@@ -3,7 +3,7 @@
  * Kafka topic names used by the analytics service.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TOPIC_ANALYTICS_EVENTS_LIST = exports.TOPIC_ANALYTICS_TIMESERIES = exports.TOPIC_ANALYTICS_DASHBOARD = exports.TOPIC_ANALYTICS_REPORT = exports.TOPIC_ANALYTICS_EVENT = void 0;
+exports.TOPIC_ANALYTICS_TENANT_AUDIT_LIST = exports.TOPIC_ANALYTICS_TENANT_AUDIT_INGEST = exports.TOPIC_ANALYTICS_EVENTS_LIST = exports.TOPIC_ANALYTICS_TIMESERIES = exports.TOPIC_ANALYTICS_DASHBOARD = exports.TOPIC_ANALYTICS_REPORT = exports.TOPIC_ANALYTICS_EVENT = void 0;
 /** Topic for ingesting analytic events from all microservices. */
 exports.TOPIC_ANALYTICS_EVENT = 'analytics.event';
 /** Topic for requesting a report grouped by event type and period. */
@@ -14,3 +14,7 @@ exports.TOPIC_ANALYTICS_DASHBOARD = 'analytics.dashboard';
 exports.TOPIC_ANALYTICS_TIMESERIES = 'analytics.timeseries';
 /** Topic for requesting event details with pagination. */
 exports.TOPIC_ANALYTICS_EVENTS_LIST = 'analytics.events.list';
+/** Topic for ingesting tenant user-action audit rows (dedicated table). */
+exports.TOPIC_ANALYTICS_TENANT_AUDIT_INGEST = 'analytics.tenant_audit.ingest';
+/** Topic for paginated tenant audit log listing. */
+exports.TOPIC_ANALYTICS_TENANT_AUDIT_LIST = 'analytics.tenant_audit.list';

package/dist/analytics/create-tenant-audit-log.dto.d.ts

@@ -0,0 +1,23 @@
+/** Outcome of the audited HTTP mutation. */
+export declare const TENANT_AUDIT_OUTCOMES: readonly ["success", "failure"];
+export type TenantAuditOutcome = (typeof TENANT_AUDIT_OUTCOMES)[number];
+/**
+ * Payload for persisting a tenant-scoped user action audit row (HTTP mutation).
+ */
+export declare class CreateTenantAuditLogDto {
+    eventId: string;
+    tenant: string;
+    actorType: string;
+    actorId: string;
+    action: string;
+    targetType?: string | null;
+    targetId?: string | null;
+    outcome: TenantAuditOutcome;
+    httpMethod: string;
+    httpPath: string;
+    httpStatus: number;
+    errorCode?: string | null;
+    metadata?: Record<string, unknown> | null;
+    occurredAt: string;
+}
+//# sourceMappingURL=create-tenant-audit-log.dto.d.ts.map

package/dist/analytics/create-tenant-audit-log.dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-tenant-audit-log.dto.d.ts","sourceRoot":"","sources":["../../src/analytics/create-tenant-audit-log.dto.ts"],"names":[],"mappings":"AAgBA,4CAA4C;AAC5C,eAAO,MAAM,qBAAqB,iCAAkC,CAAC;AACrE,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE;;GAEG;AACH,qBAAa,uBAAuB;IAGlC,OAAO,EAAE,MAAM,CAAC;IAOhB,MAAM,EAAE,MAAM,CAAC;IAMf,SAAS,EAAE,MAAM,CAAC;IAMlB,OAAO,EAAE,MAAM,CAAC;IAShB,MAAM,EAAE,MAAM,CAAC;IAMf,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAM3B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAIzB,OAAO,EAAE,kBAAkB,CAAC;IAM5B,UAAU,EAAE,MAAM,CAAC;IAMnB,QAAQ,EAAE,MAAM,CAAC;IAMjB,UAAU,EAAE,MAAM,CAAC;IAMnB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAK1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAI1C,UAAU,EAAE,MAAM,CAAC;CACpB"}

package/dist/analytics/create-tenant-audit-log.dto.js

@@ -0,0 +1,131 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CreateTenantAuditLogDto = exports.TENANT_AUDIT_OUTCOMES = void 0;
+const swagger_1 = require("@nestjs/swagger");
+const class_validator_1 = require("class-validator");
+/** Outcome of the audited HTTP mutation. */
+exports.TENANT_AUDIT_OUTCOMES = ['success', 'failure'];
+/**
+ * Payload for persisting a tenant-scoped user action audit row (HTTP mutation).
+ */
+class CreateTenantAuditLogDto {
+    eventId;
+    tenant;
+    actorType;
+    actorId;
+    action;
+    targetType;
+    targetId;
+    outcome;
+    httpMethod;
+    httpPath;
+    httpStatus;
+    errorCode;
+    metadata;
+    occurredAt;
+}
+exports.CreateTenantAuditLogDto = CreateTenantAuditLogDto;
+__decorate([
+    (0, swagger_1.ApiProperty)({ description: 'Unique id for idempotent insert', format: 'uuid' }),
+    (0, class_validator_1.IsUUID)(),
+    __metadata("design:type", String)
+], CreateTenantAuditLogDto.prototype, "eventId", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({ description: 'Tenant slug' }),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    (0, class_validator_1.MinLength)(1),
+    (0, class_validator_1.MaxLength)(255),
+    __metadata("design:type", String)
+], CreateTenantAuditLogDto.prototype, "tenant", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({ example: 'user', description: 'Actor category' }),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    (0, class_validator_1.MaxLength)(64),
+    __metadata("design:type", String)
+], CreateTenantAuditLogDto.prototype, "actorType", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({ description: 'Authenticated user id (sub)' }),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    (0, class_validator_1.MaxLength)(255),
+    __metadata("design:type", String)
+], CreateTenantAuditLogDto.prototype, "actorId", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        example: 'http.mutation',
+        description: 'Deterministic action key (e.g. http.mutation)',
+    }),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    (0, class_validator_1.MaxLength)(128),
+    __metadata("design:type", String)
+], CreateTenantAuditLogDto.prototype, "action", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({ example: 'http' }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(64),
+    __metadata("design:type", Object)
+], CreateTenantAuditLogDto.prototype, "targetType", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({ description: 'Route param id when present' }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(255),
+    __metadata("design:type", Object)
+], CreateTenantAuditLogDto.prototype, "targetId", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({ enum: exports.TENANT_AUDIT_OUTCOMES }),
+    (0, class_validator_1.IsIn)([...exports.TENANT_AUDIT_OUTCOMES]),
+    __metadata("design:type", String)
+], CreateTenantAuditLogDto.prototype, "outcome", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({ example: 'POST' }),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    (0, class_validator_1.MaxLength)(16),
+    __metadata("design:type", String)
+], CreateTenantAuditLogDto.prototype, "httpMethod", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({ example: '/patients/123' }),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    (0, class_validator_1.MaxLength)(2048),
+    __metadata("design:type", String)
+], CreateTenantAuditLogDto.prototype, "httpPath", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({ example: 201 }),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(100),
+    (0, class_validator_1.Max)(599),
+    __metadata("design:type", Number)
+], CreateTenantAuditLogDto.prototype, "httpStatus", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({ description: 'On failure, stable error code if available' }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(128),
+    __metadata("design:type", Object)
+], CreateTenantAuditLogDto.prototype, "errorCode", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({ description: 'Minimal non-PII context' }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsObject)(),
+    __metadata("design:type", Object)
+], CreateTenantAuditLogDto.prototype, "metadata", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({ description: 'When the action completed (UTC ISO-8601)' }),
+    (0, class_validator_1.IsISO8601)(),
+    __metadata("design:type", String)
+], CreateTenantAuditLogDto.prototype, "occurredAt", void 0);

package/dist/analytics/index.d.ts

@@ -1,6 +1,8 @@
 export * from './event-analytic.enum';
 export * from './followup-analytic-event-type.util';
 export * from './create-analytic-event.dto';
+export * from './create-tenant-audit-log.dto';
+export * from './list-tenant-audit-logs-query.dto';
 export * from './analytics-query.dto';
 export * from './analytics-kafka-topics';
 export * from './analytics-emitter.helper';

package/dist/analytics/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/analytics/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,qCAAqC,CAAC;AACpD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/analytics/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,qCAAqC,CAAC;AACpD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,oCAAoC,CAAC;AACnD,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC"}

package/dist/analytics/index.js

@@ -17,6 +17,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./event-analytic.enum"), exports);
 __exportStar(require("./followup-analytic-event-type.util"), exports);
 __exportStar(require("./create-analytic-event.dto"), exports);
+__exportStar(require("./create-tenant-audit-log.dto"), exports);
+__exportStar(require("./list-tenant-audit-logs-query.dto"), exports);
 __exportStar(require("./analytics-query.dto"), exports);
 __exportStar(require("./analytics-kafka-topics"), exports);
 __exportStar(require("./analytics-emitter.helper"), exports);

package/dist/analytics/list-tenant-audit-logs-query.dto.d.ts

@@ -0,0 +1,12 @@
+import type { ParsedFilterDto } from '../filters/parsed-filter.dto';
+/**
+ * Allowed tenant_audit_logs columns for filtering (camelCase API keys).
+ */
+export declare const TENANT_AUDIT_LIST_FILTER_KEYS: readonly ["actorId", "action", "outcome", "httpMethod", "httpPath", "httpStatus", "occurredAt"];
+export type TenantAuditListFilterKeyDto = (typeof TENANT_AUDIT_LIST_FILTER_KEYS)[number];
+export declare class ListTenantAuditLogsQueryDto {
+    page?: number;
+    limit?: number;
+    filters?: ParsedFilterDto[];
+}
+//# sourceMappingURL=list-tenant-audit-logs-query.dto.d.ts.map

package/dist/analytics/list-tenant-audit-logs-query.dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-tenant-audit-logs-query.dto.d.ts","sourceRoot":"","sources":["../../src/analytics/list-tenant-audit-logs-query.dto.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAEpE;;GAEG;AACH,eAAO,MAAM,6BAA6B,iGAQhC,CAAC;AACX,MAAM,MAAM,2BAA2B,GAAG,CAAC,OAAO,6BAA6B,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzF,qBAAa,2BAA2B;IAMtC,IAAI,CAAC,EAAE,MAAM,CAAC;IAQd,KAAK,CAAC,EAAE,MAAM,CAAC;IAUf,OAAO,CAAC,EAAE,eAAe,EAAE,CAAC;CAC7B"}

package/dist/analytics/list-tenant-audit-logs-query.dto.js

@@ -0,0 +1,60 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ListTenantAuditLogsQueryDto = exports.TENANT_AUDIT_LIST_FILTER_KEYS = void 0;
+const swagger_1 = require("@nestjs/swagger");
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+/**
+ * Allowed tenant_audit_logs columns for filtering (camelCase API keys).
+ */
+exports.TENANT_AUDIT_LIST_FILTER_KEYS = [
+    'actorId',
+    'action',
+    'outcome',
+    'httpMethod',
+    'httpPath',
+    'httpStatus',
+    'occurredAt',
+];
+class ListTenantAuditLogsQueryDto {
+    page;
+    limit;
+    filters;
+}
+exports.ListTenantAuditLogsQueryDto = ListTenantAuditLogsQueryDto;
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({ example: 1, minimum: 1, default: 1 }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_transformer_1.Type)(() => Number),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    __metadata("design:type", Number)
+], ListTenantAuditLogsQueryDto.prototype, "page", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({ example: 20, minimum: 1, maximum: 100, default: 20 }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_transformer_1.Type)(() => Number),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    (0, class_validator_1.Max)(100),
+    __metadata("design:type", Number)
+], ListTenantAuditLogsQueryDto.prototype, "limit", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'JSON string with an array of filter objects `{ key, op, value }`. ' +
+            'Example: `[{"key":"outcome","op":"==","value":"success"}]`.',
+        type: String,
+        example: '[{"key":"outcome","op":"==","value":"success"}]',
+    }),
+    (0, class_validator_1.IsOptional)(),
+    __metadata("design:type", Array)
+], ListTenantAuditLogsQueryDto.prototype, "filters", void 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tychat-contracts",
-  "version": "1.4.4",
+  "version": "1.4.6",
   "description": "DTOs compartilhados com class-validator (API e microserviços)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/analytics/analytics-kafka-topics.ts

@@ -16,3 +16,9 @@ export const TOPIC_ANALYTICS_TIMESERIES = 'analytics.timeseries';
 
 /** Topic for requesting event details with pagination. */
 export const TOPIC_ANALYTICS_EVENTS_LIST = 'analytics.events.list';
+
+/** Topic for ingesting tenant user-action audit rows (dedicated table). */
+export const TOPIC_ANALYTICS_TENANT_AUDIT_INGEST = 'analytics.tenant_audit.ingest';
+
+/** Topic for paginated tenant audit log listing. */
+export const TOPIC_ANALYTICS_TENANT_AUDIT_LIST = 'analytics.tenant_audit.list';

package/src/analytics/create-tenant-audit-log.dto.ts

@@ -0,0 +1,105 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import {
+  IsIn,
+  IsInt,
+  IsISO8601,
+  IsNotEmpty,
+  IsObject,
+  IsOptional,
+  IsString,
+  IsUUID,
+  Max,
+  MaxLength,
+  Min,
+  MinLength,
+} from 'class-validator';
+
+/** Outcome of the audited HTTP mutation. */
+export const TENANT_AUDIT_OUTCOMES = ['success', 'failure'] as const;
+export type TenantAuditOutcome = (typeof TENANT_AUDIT_OUTCOMES)[number];
+
+/**
+ * Payload for persisting a tenant-scoped user action audit row (HTTP mutation).
+ */
+export class CreateTenantAuditLogDto {
+  @ApiProperty({ description: 'Unique id for idempotent insert', format: 'uuid' })
+  @IsUUID()
+  eventId: string;
+
+  @ApiProperty({ description: 'Tenant slug' })
+  @IsString()
+  @IsNotEmpty()
+  @MinLength(1)
+  @MaxLength(255)
+  tenant: string;
+
+  @ApiProperty({ example: 'user', description: 'Actor category' })
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(64)
+  actorType: string;
+
+  @ApiProperty({ description: 'Authenticated user id (sub)' })
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(255)
+  actorId: string;
+
+  @ApiProperty({
+    example: 'http.mutation',
+    description: 'Deterministic action key (e.g. http.mutation)',
+  })
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(128)
+  action: string;
+
+  @ApiPropertyOptional({ example: 'http' })
+  @IsOptional()
+  @IsString()
+  @MaxLength(64)
+  targetType?: string | null;
+
+  @ApiPropertyOptional({ description: 'Route param id when present' })
+  @IsOptional()
+  @IsString()
+  @MaxLength(255)
+  targetId?: string | null;
+
+  @ApiProperty({ enum: TENANT_AUDIT_OUTCOMES })
+  @IsIn([...TENANT_AUDIT_OUTCOMES])
+  outcome: TenantAuditOutcome;
+
+  @ApiProperty({ example: 'POST' })
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(16)
+  httpMethod: string;
+
+  @ApiProperty({ example: '/patients/123' })
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(2048)
+  httpPath: string;
+
+  @ApiProperty({ example: 201 })
+  @IsInt()
+  @Min(100)
+  @Max(599)
+  httpStatus: number;
+
+  @ApiPropertyOptional({ description: 'On failure, stable error code if available' })
+  @IsOptional()
+  @IsString()
+  @MaxLength(128)
+  errorCode?: string | null;
+
+  @ApiPropertyOptional({ description: 'Minimal non-PII context' })
+  @IsOptional()
+  @IsObject()
+  metadata?: Record<string, unknown> | null;
+
+  @ApiProperty({ description: 'When the action completed (UTC ISO-8601)' })
+  @IsISO8601()
+  occurredAt: string;
+}

package/src/analytics/index.ts

@@ -1,6 +1,8 @@
 export * from './event-analytic.enum';
 export * from './followup-analytic-event-type.util';
 export * from './create-analytic-event.dto';
+export * from './create-tenant-audit-log.dto';
+export * from './list-tenant-audit-logs-query.dto';
 export * from './analytics-query.dto';
 export * from './analytics-kafka-topics';
 export * from './analytics-emitter.helper';

package/src/analytics/list-tenant-audit-logs-query.dto.ts

@@ -0,0 +1,45 @@
+import { ApiPropertyOptional } from '@nestjs/swagger';
+import { Type } from 'class-transformer';
+import { IsInt, IsOptional, Max, Min } from 'class-validator';
+import type { ParsedFilterDto } from '../filters/parsed-filter.dto';
+
+/**
+ * Allowed tenant_audit_logs columns for filtering (camelCase API keys).
+ */
+export const TENANT_AUDIT_LIST_FILTER_KEYS = [
+  'actorId',
+  'action',
+  'outcome',
+  'httpMethod',
+  'httpPath',
+  'httpStatus',
+  'occurredAt',
+] as const;
+export type TenantAuditListFilterKeyDto = (typeof TENANT_AUDIT_LIST_FILTER_KEYS)[number];
+
+export class ListTenantAuditLogsQueryDto {
+  @ApiPropertyOptional({ example: 1, minimum: 1, default: 1 })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  page?: number;
+
+  @ApiPropertyOptional({ example: 20, minimum: 1, maximum: 100, default: 20 })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(100)
+  limit?: number;
+
+  @ApiPropertyOptional({
+    description:
+      'JSON string with an array of filter objects `{ key, op, value }`. ' +
+      'Example: `[{"key":"outcome","op":"==","value":"success"}]`.',
+    type: String,
+    example: '[{"key":"outcome","op":"==","value":"success"}]',
+  })
+  @IsOptional()
+  filters?: ParsedFilterDto[];
+}