@orthacms/activity-server 0.0.0-reserve.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ortha CMS contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+# @orthacms/activity-server
+
+Part of [Ortha CMS](https://github.com/ortha-source/ortha-cms).
+
+```sh
+npm install @orthacms/activity-server
+```

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { ActivityPlugin } from './lib/utils/activity-plugin';
+export { ActivityModule } from './lib/activity.module';
+export { ActivityService } from './lib/activity/services/activity.service';
+export { DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE, SORTABLE_FIELDS, SORT_ORDERS } from './lib/activity/activity.constants';
+export type { SortableField, SortOrder } from './lib/activity/activity.constants';
+export type { ActivityEventView, ActivityListView } from './lib/activity/types/activity-view';
+export { activityEvents } from './lib/schema';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,0CAA0C,CAAC;AAC3E,OAAO,EACH,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,WAAW,EACd,MAAM,mCAAmC,CAAC;AAC3C,YAAY,EACR,aAAa,EACb,SAAS,EACZ,MAAM,mCAAmC,CAAC;AAC3C,YAAY,EACR,iBAAiB,EACjB,gBAAgB,EACnB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.activityEvents = exports.SORT_ORDERS = exports.SORTABLE_FIELDS = exports.MAX_PAGE_SIZE = exports.DEFAULT_PAGE_SIZE = exports.ActivityService = exports.ActivityModule = exports.ActivityPlugin = void 0;
+var activity_plugin_1 = require("./lib/utils/activity-plugin");
+Object.defineProperty(exports, "ActivityPlugin", { enumerable: true, get: function () { return activity_plugin_1.ActivityPlugin; } });
+var activity_module_1 = require("./lib/activity.module");
+Object.defineProperty(exports, "ActivityModule", { enumerable: true, get: function () { return activity_module_1.ActivityModule; } });
+var activity_service_1 = require("./lib/activity/services/activity.service");
+Object.defineProperty(exports, "ActivityService", { enumerable: true, get: function () { return activity_service_1.ActivityService; } });
+var activity_constants_1 = require("./lib/activity/activity.constants");
+Object.defineProperty(exports, "DEFAULT_PAGE_SIZE", { enumerable: true, get: function () { return activity_constants_1.DEFAULT_PAGE_SIZE; } });
+Object.defineProperty(exports, "MAX_PAGE_SIZE", { enumerable: true, get: function () { return activity_constants_1.MAX_PAGE_SIZE; } });
+Object.defineProperty(exports, "SORTABLE_FIELDS", { enumerable: true, get: function () { return activity_constants_1.SORTABLE_FIELDS; } });
+Object.defineProperty(exports, "SORT_ORDERS", { enumerable: true, get: function () { return activity_constants_1.SORT_ORDERS; } });
+var schema_1 = require("./lib/schema");
+Object.defineProperty(exports, "activityEvents", { enumerable: true, get: function () { return schema_1.activityEvents; } });

package/dist/lib/activity/activity-filter.d.ts

@@ -0,0 +1,14 @@
+import { type FilterSchema } from '@orthacms/utils-server';
+/**
+ * The filterable surface of the audit log for the query-builder engine.
+ * Field keys mirror the `activity_events` column property names so the
+ * translator can resolve each to its Drizzle column. Deliberately omits
+ * `meta` (open jsonb) and `createdAt` (kept off the wire) — only the
+ * indexed, frozen-snapshot columns are exposed.
+ *
+ * A user-supplied `?filter=` is validated against this schema and then
+ * AND-ed with the structured query params (`subjectType`, `kind`, …) the
+ * controller already accepts, so the two filter surfaces compose.
+ */
+export declare const ACTIVITY_FILTER_SCHEMA: FilterSchema;
+//# sourceMappingURL=activity-filter.d.ts.map

package/dist/lib/activity/activity-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-filter.d.ts","sourceRoot":"","sources":["../../../src/lib/activity/activity-filter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE5E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,EAAE,YASpC,CAAC"}

package/dist/lib/activity/activity-filter.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ACTIVITY_FILTER_SCHEMA = void 0;
+const utils_server_1 = require("@orthacms/utils-server");
+/**
+ * The filterable surface of the audit log for the query-builder engine.
+ * Field keys mirror the `activity_events` column property names so the
+ * translator can resolve each to its Drizzle column. Deliberately omits
+ * `meta` (open jsonb) and `createdAt` (kept off the wire) — only the
+ * indexed, frozen-snapshot columns are exposed.
+ *
+ * A user-supplied `?filter=` is validated against this schema and then
+ * AND-ed with the structured query params (`subjectType`, `kind`, …) the
+ * controller already accepts, so the two filter surfaces compose.
+ */
+exports.ACTIVITY_FILTER_SCHEMA = {
+    fields: {
+        kind: { type: utils_server_1.ScalarFieldType.String },
+        subjectType: { type: utils_server_1.ScalarFieldType.String },
+        subjectId: { type: utils_server_1.ScalarFieldType.String },
+        actorId: { type: utils_server_1.ScalarFieldType.Uuid },
+        actorEmail: { type: utils_server_1.ScalarFieldType.String },
+        at: { type: utils_server_1.ScalarFieldType.Date }
+    }
+};

package/dist/lib/activity/activity.constants.d.ts

@@ -0,0 +1,18 @@
+/** Default page size for `GET /api/activity`. */
+export declare const DEFAULT_PAGE_SIZE = 25;
+/** Upper bound on the requested page size (the largest option the UI offers). */
+export declare const MAX_PAGE_SIZE = 100;
+/**
+ * Max length of the raw `?filter=` JSON string. A coarse first guard against
+ * oversized payloads, ahead of the filter engine's node/depth caps.
+ */
+export declare const FILTER_MAX_LENGTH = 4096;
+/** Columns the read API permits sorting by (whitelist — keys are the wire values). */
+export declare const SORTABLE_FIELDS: readonly ["at", "kind"];
+/** A field the read API may sort by. */
+export type SortableField = (typeof SORTABLE_FIELDS)[number];
+/** Sort directions the read API accepts. */
+export declare const SORT_ORDERS: readonly ["asc", "desc"];
+/** A sort direction accepted by the read API. */
+export type SortOrder = (typeof SORT_ORDERS)[number];
+//# sourceMappingURL=activity.constants.d.ts.map

package/dist/lib/activity/activity.constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity.constants.d.ts","sourceRoot":"","sources":["../../../src/lib/activity/activity.constants.ts"],"names":[],"mappings":"AAAA,iDAAiD;AACjD,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC,iFAAiF;AACjF,eAAO,MAAM,aAAa,MAAM,CAAC;AAEjC;;;GAGG;AACH,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC,sFAAsF;AACtF,eAAO,MAAM,eAAe,yBAA0B,CAAC;AAEvD,wCAAwC;AACxC,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D,4CAA4C;AAC5C,eAAO,MAAM,WAAW,0BAA2B,CAAC;AAEpD,iDAAiD;AACjD,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/lib/activity/activity.constants.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SORT_ORDERS = exports.SORTABLE_FIELDS = exports.FILTER_MAX_LENGTH = exports.MAX_PAGE_SIZE = exports.DEFAULT_PAGE_SIZE = void 0;
+/** Default page size for `GET /api/activity`. */
+exports.DEFAULT_PAGE_SIZE = 25;
+/** Upper bound on the requested page size (the largest option the UI offers). */
+exports.MAX_PAGE_SIZE = 100;
+/**
+ * Max length of the raw `?filter=` JSON string. A coarse first guard against
+ * oversized payloads, ahead of the filter engine's node/depth caps.
+ */
+exports.FILTER_MAX_LENGTH = 4096;
+/** Columns the read API permits sorting by (whitelist — keys are the wire values). */
+exports.SORTABLE_FIELDS = ['at', 'kind'];
+/** Sort directions the read API accepts. */
+exports.SORT_ORDERS = ['asc', 'desc'];

package/dist/lib/activity/controllers/list-activity.controller.d.ts

@@ -0,0 +1,14 @@
+import { ActivityService } from '../services/activity.service';
+import { ListActivityQueryDto } from '../dto/list-activity-query.dto';
+import type { ActivityListView } from '../types/activity-view';
+/**
+ * `GET /api/activity` — the global audit log. Read-only; gated on
+ * `activity:read` (admin-only by the v1 role matrix). All filtering,
+ * pagination, and sorting is delegated to {@link ActivityService.list}.
+ */
+export declare class ListActivityController {
+    private readonly activity;
+    constructor(activity: ActivityService);
+    list(query: ListActivityQueryDto): Promise<ActivityListView>;
+}
+//# sourceMappingURL=list-activity.controller.d.ts.map

package/dist/lib/activity/controllers/list-activity.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-activity.controller.d.ts","sourceRoot":"","sources":["../../../../src/lib/activity/controllers/list-activity.controller.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AACtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D;;;;GAIG;AACH,qBAGa,sBAAsB;IACnB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,eAAe;IAGtD,IAAI,CAAU,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAGxE"}

package/dist/lib/activity/controllers/list-activity.controller.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ListActivityController = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+const identity_server_1 = require("@orthacms/identity-server");
+const activity_service_1 = require("../services/activity.service");
+const list_activity_query_dto_1 = require("../dto/list-activity-query.dto");
+/**
+ * `GET /api/activity` — the global audit log. Read-only; gated on
+ * `activity:read` (admin-only by the v1 role matrix). All filtering,
+ * pagination, and sorting is delegated to {@link ActivityService.list}.
+ */
+let ListActivityController = class ListActivityController {
+    activity;
+    constructor(activity) {
+        this.activity = activity;
+    }
+    list(query) {
+        return this.activity.list(query);
+    }
+};
+exports.ListActivityController = ListActivityController;
+tslib_1.__decorate([
+    (0, common_1.Get)(),
+    tslib_1.__param(0, (0, common_1.Query)()),
+    tslib_1.__metadata("design:type", Function),
+    tslib_1.__metadata("design:paramtypes", [list_activity_query_dto_1.ListActivityQueryDto]),
+    tslib_1.__metadata("design:returntype", Promise)
+], ListActivityController.prototype, "list", null);
+exports.ListActivityController = ListActivityController = tslib_1.__decorate([
+    (0, common_1.UseGuards)(identity_server_1.PermissionsGuard),
+    (0, identity_server_1.RequirePermissions)(identity_server_1.PERMISSIONS.ACTIVITY_READ),
+    (0, common_1.Controller)('activity'),
+    tslib_1.__metadata("design:paramtypes", [activity_service_1.ActivityService])
+], ListActivityController);

package/dist/lib/activity/dto/list-activity-query.dto.d.ts

@@ -0,0 +1,46 @@
+import { type SortableField, type SortOrder } from '../activity.constants';
+/**
+ * Query parameters for `GET /api/activity`. All filters are optional and
+ * intersected (AND). Pagination is 1-based; the service applies the defaults
+ * (page 1, {@link DEFAULT_PAGE_SIZE}) so the contract has one source of truth.
+ * `@Type`/`@Transform` coerce the raw query strings — the host's global
+ * `ValidationPipe` transforms but does not implicitly convert.
+ */
+export declare class ListActivityQueryDto {
+    /** Restrict to one subject kind (e.g. `'user'`). */
+    subjectType?: string;
+    /** Restrict to one subject id (a specific entity's history). */
+    subjectId?: string;
+    /** Restrict to one actor. */
+    actorId?: string;
+    /**
+     * Restrict to one or more event kinds. Accepts a comma-separated list
+     * (`?kind=user.invited,user.suspended`) → matched with `IN`. Kinds are
+     * owned by the emitting plugins, so this is validated as free text, not
+     * against a central catalogue.
+     */
+    kind?: string[];
+    /** Case-insensitive substring search over the actor email snapshot. */
+    actorEmail?: string;
+    /**
+     * Structured filter tree as a JSON string (`?filter=<json>`), produced by
+     * the admin query builder and validated against the activity filter schema
+     * by `parseFilterTree`. Length-capped here as a first line of defence; the
+     * engine's node/depth caps bound the parsed shape. AND-ed with the other
+     * params.
+     */
+    filter?: string;
+    /** Inclusive lower bound on the event time (ISO 8601). */
+    from?: string;
+    /** Inclusive upper bound on the event time (ISO 8601). */
+    to?: string;
+    /** 1-based page number. */
+    page?: number;
+    /** Rows per page, capped at {@link MAX_PAGE_SIZE}. */
+    pageSize?: number;
+    /** Column to sort by (whitelisted). Defaults to `at`. */
+    sort?: SortableField;
+    /** Sort direction. Defaults to `desc`. */
+    order?: SortOrder;
+}
+//# sourceMappingURL=list-activity-query.dto.d.ts.map

package/dist/lib/activity/dto/list-activity-query.dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-activity-query.dto.d.ts","sourceRoot":"","sources":["../../../../src/lib/activity/dto/list-activity-query.dto.ts"],"names":[],"mappings":"AAcA,OAAO,EAMH,KAAK,aAAa,EAClB,KAAK,SAAS,EACjB,MAAM,uBAAuB,CAAC;AAE/B;;;;;;GAMG;AACH,qBAAa,oBAAoB;IAC7B,oDAAoD;IAUpD,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,gEAAgE;IAUhE,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,6BAA6B;IAQ7B,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;OAKG;IAmBH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB,uEAAuE;IAUvE,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;OAMG;IAYH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,0DAA0D;IAS1D,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,0DAA0D;IAS1D,EAAE,CAAC,EAAE,MAAM,CAAC;IAEZ,2BAA2B;IAW3B,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,sDAAsD;IAatD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,yDAAyD;IAQzD,IAAI,CAAC,EAAE,aAAa,CAAC;IAErB,0CAA0C;IAQ1C,KAAK,CAAC,EAAE,SAAS,CAAC;CACrB"}

package/dist/lib/activity/dto/list-activity-query.dto.js

@@ -0,0 +1,197 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ListActivityQueryDto = void 0;
+const tslib_1 = require("tslib");
+const swagger_1 = require("@nestjs/swagger");
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+const activity_constants_1 = require("../activity.constants");
+/**
+ * Query parameters for `GET /api/activity`. All filters are optional and
+ * intersected (AND). Pagination is 1-based; the service applies the defaults
+ * (page 1, {@link DEFAULT_PAGE_SIZE}) so the contract has one source of truth.
+ * `@Type`/`@Transform` coerce the raw query strings — the host's global
+ * `ValidationPipe` transforms but does not implicitly convert.
+ */
+class ListActivityQueryDto {
+    /** Restrict to one subject kind (e.g. `'user'`). */
+    subjectType;
+    /** Restrict to one subject id (a specific entity's history). */
+    subjectId;
+    /** Restrict to one actor. */
+    actorId;
+    /**
+     * Restrict to one or more event kinds. Accepts a comma-separated list
+     * (`?kind=user.invited,user.suspended`) → matched with `IN`. Kinds are
+     * owned by the emitting plugins, so this is validated as free text, not
+     * against a central catalogue.
+     */
+    kind;
+    /** Case-insensitive substring search over the actor email snapshot. */
+    actorEmail;
+    /**
+     * Structured filter tree as a JSON string (`?filter=<json>`), produced by
+     * the admin query builder and validated against the activity filter schema
+     * by `parseFilterTree`. Length-capped here as a first line of defence; the
+     * engine's node/depth caps bound the parsed shape. AND-ed with the other
+     * params.
+     */
+    filter;
+    /** Inclusive lower bound on the event time (ISO 8601). */
+    from;
+    /** Inclusive upper bound on the event time (ISO 8601). */
+    to;
+    /** 1-based page number. */
+    page;
+    /** Rows per page, capped at {@link MAX_PAGE_SIZE}. */
+    pageSize;
+    /** Column to sort by (whitelisted). Defaults to `at`. */
+    sort;
+    /** Sort direction. Defaults to `desc`. */
+    order;
+}
+exports.ListActivityQueryDto = ListActivityQueryDto;
+tslib_1.__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        type: String,
+        maxLength: 255,
+        example: 'user',
+        description: "Restrict to one subject kind (e.g. `'user'`)."
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(255),
+    tslib_1.__metadata("design:type", String)
+], ListActivityQueryDto.prototype, "subjectType", void 0);
+tslib_1.__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        type: String,
+        maxLength: 255,
+        description: "Restrict to one subject id (a specific entity's history). Text, not always a uuid — the audit outlives its subjects."
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(255),
+    tslib_1.__metadata("design:type", String)
+], ListActivityQueryDto.prototype, "subjectId", void 0);
+tslib_1.__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        type: String,
+        format: 'uuid',
+        description: 'Restrict to the events recorded for one actor.'
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsUUID)(),
+    tslib_1.__metadata("design:type", String)
+], ListActivityQueryDto.prototype, "actorId", void 0);
+tslib_1.__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        type: String,
+        example: 'user.invited,user.suspended',
+        description: 'Comma-separated event kinds, matched with `IN`. Kinds are owned by the emitting plugins, so this is free text rather than a central catalogue.'
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_transformer_1.Transform)(({ value }) => typeof value === 'string'
+        ? value
+            .split(',')
+            .map((part) => part.trim())
+            .filter(Boolean)
+        : value),
+    (0, class_validator_1.IsArray)(),
+    (0, class_validator_1.IsString)({ each: true }),
+    (0, class_validator_1.MaxLength)(255, { each: true }),
+    tslib_1.__metadata("design:type", Array)
+], ListActivityQueryDto.prototype, "kind", void 0);
+tslib_1.__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        type: String,
+        maxLength: 255,
+        description: 'Case-insensitive substring search over the frozen actor-email snapshot.'
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(255),
+    tslib_1.__metadata("design:type", String)
+], ListActivityQueryDto.prototype, "actorEmail", void 0);
+tslib_1.__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        type: String,
+        maxLength: activity_constants_1.FILTER_MAX_LENGTH,
+        example: '{"op":"and","rules":[{"field":"kind","op":"eq","value":"user.invited"}]}',
+        description: 'Structured filter tree as a JSON string, produced by the admin query builder and validated against the activity filter schema. AND-ed with the other params.'
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(activity_constants_1.FILTER_MAX_LENGTH),
+    tslib_1.__metadata("design:type", String)
+], ListActivityQueryDto.prototype, "filter", void 0);
+tslib_1.__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        type: String,
+        format: 'date-time',
+        example: '2026-01-01T00:00:00.000Z',
+        description: 'Inclusive lower bound on the event time (ISO 8601).'
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsISO8601)(),
+    tslib_1.__metadata("design:type", String)
+], ListActivityQueryDto.prototype, "from", void 0);
+tslib_1.__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        type: String,
+        format: 'date-time',
+        example: '2026-02-01T00:00:00.000Z',
+        description: 'Inclusive upper bound on the event time (ISO 8601).'
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsISO8601)(),
+    tslib_1.__metadata("design:type", String)
+], ListActivityQueryDto.prototype, "to", void 0);
+tslib_1.__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        type: 'integer',
+        minimum: 1,
+        default: 1,
+        description: '1-based page number.'
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_transformer_1.Type)(() => Number),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    tslib_1.__metadata("design:type", Number)
+], ListActivityQueryDto.prototype, "page", void 0);
+tslib_1.__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        type: 'integer',
+        minimum: 1,
+        maximum: activity_constants_1.MAX_PAGE_SIZE,
+        default: activity_constants_1.DEFAULT_PAGE_SIZE,
+        description: `Rows per page, capped at ${activity_constants_1.MAX_PAGE_SIZE}.`
+    }),
+    (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)(activity_constants_1.MAX_PAGE_SIZE),
+    tslib_1.__metadata("design:type", Number)
+], ListActivityQueryDto.prototype, "pageSize", void 0);
+tslib_1.__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        enum: [...activity_constants_1.SORTABLE_FIELDS],
+        default: 'at',
+        description: 'Column to sort by (whitelisted).'
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsIn)(activity_constants_1.SORTABLE_FIELDS),
+    tslib_1.__metadata("design:type", String)
+], ListActivityQueryDto.prototype, "sort", void 0);
+tslib_1.__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        enum: [...activity_constants_1.SORT_ORDERS],
+        default: 'desc',
+        description: 'Sort direction.'
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsIn)(activity_constants_1.SORT_ORDERS),
+    tslib_1.__metadata("design:type", String)
+], ListActivityQueryDto.prototype, "order", void 0);

package/dist/lib/activity/infrastructure/audit-event-mapping.d.ts

@@ -0,0 +1,60 @@
+import type { DomainEvent } from '@orthacms/database';
+/**
+ * The values one audit row needs, derived purely from a {@link DomainEvent}.
+ * Mirrors an `activity_events` insert: `id` is the **event's** id (so a
+ * re-delivered event maps to the same row — the subscriber inserts it
+ * `ON CONFLICT DO NOTHING` for idempotency), and `at` is the event's domain
+ * time.
+ */
+export interface AuditRow {
+    /** Primary key = the source event id, making redelivery idempotent. */
+    id: string;
+    /** The `user.*` / `workspace.*` audit kind (see the mapping table below). */
+    kind: string;
+    /** The kind of entity acted upon (`'user'` / `'workspace'`). */
+    subjectType: string;
+    /** The acted-upon entity's id (text). */
+    subjectId: string;
+    /** Who performed it, or `null` for a system-initiated event. */
+    actorId: string | null;
+    /** Frozen actor email snapshot, or `null`. */
+    actorEmail: string | null;
+    /** Open per-kind payload, or `null` when the kind carries none. */
+    meta: Record<string, unknown> | null;
+    /** Logical event time (the event's `occurredAt`). */
+    at: Date;
+}
+/**
+ * Thrown when an event cannot be mapped to a row that identifies its subject.
+ *
+ * Refusing is the point. `subject_id` is the **only** handle an audit row keeps
+ * on the entity it is about — there is no FK, no denormalised name, and
+ * `actor_email` belongs to the actor — so a row written with an empty subject
+ * is not a degraded record, it is an unreadable one, and nothing downstream can
+ * repair it. Throwing leaves the outbox row undispatched, so the dispatcher
+ * retries it with backoff and parks it at `MAX_DELIVERY_ATTEMPTS` where the
+ * dead-letter query (`dispatched_at IS NULL AND attempts >= 15`) surfaces it.
+ * The gap becomes loud instead of becoming a row nobody can read.
+ */
+export declare class UnmappableAuditEventError extends Error {
+    constructor(event: DomainEvent, reason: string);
+}
+/**
+ * Every event kind the activity subscriber audits — the dispatcher delivers
+ * only these to it.
+ */
+export declare const AUDITED_EVENT_KINDS: readonly string[];
+/**
+ * Maps a domain event to the audit row it should produce, or `null` when the
+ * kind is not audited. Pure and DB-free — the safety-net unit test asserts each
+ * kind's row equals what the old in-band recorder wrote.
+ *
+ * Throws {@link UnmappableAuditEventError} when the kind **is** audited but the
+ * payload cannot identify its subject. `null` and a throw mean different things
+ * on purpose: `null` is "not our event, skip it" and the dispatcher marks the
+ * row delivered; a throw is "this should have been audited and cannot be", so
+ * the row stays undispatched, is retried with backoff, and finally parks as a
+ * dead letter rather than becoming a row nobody can read.
+ */
+export declare function toAuditRow(event: DomainEvent): AuditRow | null;
+//# sourceMappingURL=audit-event-mapping.d.ts.map

package/dist/lib/activity/infrastructure/audit-event-mapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-event-mapping.d.ts","sourceRoot":"","sources":["../../../../src/lib/activity/infrastructure/audit-event-mapping.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGtD;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACrB,uEAAuE;IACvE,EAAE,EAAE,MAAM,CAAC;IACX,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,8CAA8C;IAC9C,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACrC,qDAAqD;IACrD,EAAE,EAAE,IAAI,CAAC;CACZ;AAgKD;;;;;;;;;;;GAWG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;gBACpC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM;CAMjD;AA+OD;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAE3B,SAAS,MAAM,EAAE,CAAC;AAgBvB;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,GAAG,QAAQ,GAAG,IAAI,CAiB9D"}