@s-hirano-ist/s-core 1.2.0 → 1.3.0

package/dist/common/entities/common-entity.js

@@ -1,37 +1,270 @@
 import { z } from "zod";
 import { idGenerator } from "../services/id-generator";
-// common value objects
+/**
+ * Zod schema for validating UUIDv7 identifiers.
+ *
+ * @remarks
+ * UUIDv7 is time-ordered, making it suitable for database primary keys.
+ * Auto-generates a new UUIDv7 if no value is provided.
+ *
+ * @example
+ * ```typescript
+ * const id = Id.parse(undefined); // Auto-generates UUIDv7
+ * const id2 = Id.parse("01912c9a-5e8a-7b5c-8a1b-2c3d4e5f6a7b");
+ * ```
+ *
+ * @see {@link makeId} for factory function
+ */
 export const Id = z
     .uuid({ version: "v7" })
     .default(() => idGenerator.uuidv7())
     .brand();
+/**
+ * Creates a validated Id from an optional string.
+ *
+ * @param id - Optional UUIDv7 string. If not provided, generates a new one.
+ * @returns A branded Id value
+ * @throws {ZodError} When the provided string is not a valid UUIDv7
+ *
+ * @example
+ * ```typescript
+ * const newId = makeId(); // Auto-generate
+ * const existingId = makeId("01912c9a-5e8a-7b5c-8a1b-2c3d4e5f6a7b");
+ * ```
+ */
 export const makeId = (id) => {
     if (!id)
         return Id.parse(idGenerator.uuidv7());
     return Id.parse(id);
 };
+/**
+ * Zod schema for validating user identifiers.
+ *
+ * @remarks
+ * Validates that the user ID is a non-empty string.
+ * Used for multi-tenant data isolation across all domains.
+ *
+ * @example
+ * ```typescript
+ * const userId = UserId.parse("auth0|123456789");
+ * ```
+ *
+ * @see {@link makeUserId} for factory function
+ */
 export const UserId = z.string().min(1, "required").brand();
+/**
+ * Creates a validated UserId from a string.
+ *
+ * @param v - The user ID string (typically from Auth0)
+ * @returns A branded UserId value
+ * @throws {ZodError} When the string is empty
+ *
+ * @example
+ * ```typescript
+ * const userId = makeUserId("auth0|123456789");
+ * ```
+ */
 export const makeUserId = (v) => UserId.parse(v);
+/**
+ * Zod schema for validating creation timestamps.
+ *
+ * @remarks
+ * Validates that the value is a valid Date object.
+ * Used to track when entities are created.
+ *
+ * @example
+ * ```typescript
+ * const timestamp = CreatedAt.parse(new Date());
+ * ```
+ *
+ * @see {@link makeCreatedAt} for factory function
+ */
 export const CreatedAt = z.date().brand();
+/**
+ * Creates a validated CreatedAt timestamp.
+ *
+ * @param createdAt - Optional Date. If not provided, uses current time.
+ * @returns A branded CreatedAt value
+ * @throws {ZodError} When the value is not a valid Date
+ *
+ * @example
+ * ```typescript
+ * const now = makeCreatedAt(); // Current time
+ * const specific = makeCreatedAt(new Date("2024-01-01"));
+ * ```
+ */
 export const makeCreatedAt = (createdAt) => {
     if (!createdAt)
         return CreatedAt.parse(new Date());
     return CreatedAt.parse(createdAt);
 };
+/**
+ * Zod schema for validating update timestamps.
+ *
+ * @remarks
+ * Validates that the value is a valid Date object.
+ * Used to track when entities are last modified.
+ *
+ * @example
+ * ```typescript
+ * const timestamp = UpdatedAt.parse(new Date());
+ * ```
+ *
+ * @see {@link makeUpdatedAt} for factory function
+ */
+export const UpdatedAt = z.date().brand();
+/**
+ * Creates a validated UpdatedAt timestamp.
+ *
+ * @param updatedAt - Optional Date. If not provided, uses current time.
+ * @returns A branded UpdatedAt value
+ * @throws {ZodError} When the value is not a valid Date
+ *
+ * @example
+ * ```typescript
+ * const now = makeUpdatedAt(); // Current time
+ * const specific = makeUpdatedAt(new Date("2024-01-01"));
+ * ```
+ */
+export const makeUpdatedAt = (updatedAt) => {
+    if (!updatedAt)
+        return UpdatedAt.parse(new Date());
+    return UpdatedAt.parse(updatedAt);
+};
+/**
+ * Zod schema for the UNEXPORTED status literal.
+ *
+ * @remarks
+ * Represents the initial state of all content entities.
+ * Content transitions from UNEXPORTED to EXPORTED when published.
+ *
+ * @see {@link ExportedStatus} for the exported state
+ * @see {@link Status} for the union type
+ */
 export const UnexportedStatus = z.literal("UNEXPORTED");
+/**
+ * Creates an UnexportedStatus value.
+ *
+ * @returns The literal "UNEXPORTED" status
+ *
+ * @example
+ * ```typescript
+ * const status = makeUnexportedStatus(); // "UNEXPORTED"
+ * ```
+ */
 export const makeUnexportedStatus = () => UnexportedStatus.parse("UNEXPORTED");
+/**
+ * Zod schema for the LAST_UPDATED status literal.
+ *
+ * @remarks
+ * Represents the intermediate state of content entities during batch processing.
+ * Content transitions from UNEXPORTED to LAST_UPDATED when marked for export,
+ * then from LAST_UPDATED to EXPORTED when finalized.
+ * Can be reverted back to UNEXPORTED if something goes wrong.
+ *
+ * @see {@link UnexportedStatus} for the initial state
+ * @see {@link ExportedStatus} for the final state
+ * @see {@link Status} for the union type
+ */
+export const LastUpdatedStatus = z.literal("LAST_UPDATED");
+/**
+ * Creates a LastUpdatedStatus value.
+ *
+ * @returns The literal "LAST_UPDATED" status
+ *
+ * @example
+ * ```typescript
+ * const status = makeLastUpdatedStatus(); // "LAST_UPDATED"
+ * ```
+ */
+export const makeLastUpdatedStatus = () => LastUpdatedStatus.parse("LAST_UPDATED");
+/**
+ * Zod schema for validating export timestamps.
+ *
+ * @remarks
+ * Validates that the value is a valid Date object.
+ * Used to track when entities are exported/published.
+ *
+ * @example
+ * ```typescript
+ * const timestamp = ExportedAt.parse(new Date());
+ * ```
+ *
+ * @see {@link makeExportedAt} for factory function
+ */
 export const ExportedAt = z.date().brand();
+/**
+ * Creates a validated ExportedAt timestamp.
+ *
+ * @param exportedAt - Optional Date. If not provided, uses current time.
+ * @returns A branded ExportedAt value
+ * @throws {ZodError} When the value is not a valid Date
+ *
+ * @example
+ * ```typescript
+ * const now = makeExportedAt(); // Current time
+ * const specific = makeExportedAt(new Date("2024-01-01"));
+ * ```
+ */
 export const makeExportedAt = (exportedAt) => {
     if (!exportedAt)
         return ExportedAt.parse(new Date());
     return ExportedAt.parse(exportedAt);
 };
+/**
+ * Zod schema for the EXPORTED status with timestamp.
+ *
+ * @remarks
+ * Represents the published state of content entities.
+ * Includes both the status literal and the export timestamp.
+ *
+ * @example
+ * ```typescript
+ * const exported = ExportedStatus.parse({
+ *   status: "EXPORTED",
+ *   exportedAt: new Date()
+ * });
+ * ```
+ *
+ * @see {@link UnexportedStatus} for the initial state
+ * @see {@link makeExportedStatus} for factory function
+ */
 export const ExportedStatus = z.object({
     status: z.literal("EXPORTED"),
     exportedAt: ExportedAt,
 });
+/**
+ * Creates an ExportedStatus with current timestamp.
+ *
+ * @returns An ExportedStatus object with status "EXPORTED" and current time
+ *
+ * @example
+ * ```typescript
+ * const status = makeExportedStatus();
+ * // { status: "EXPORTED", exportedAt: Date }
+ * ```
+ */
 export const makeExportedStatus = () => ExportedStatus.parse({ status: "EXPORTED", exportedAt: new Date() });
-// Legacy compatibility - will be removed in future
+/**
+ * Creates a Status value from a string.
+ *
+ * @param status - The status string ("UNEXPORTED", "LAST_UPDATED", or "EXPORTED")
+ * @returns The status value
+ *
+ * @deprecated This is for legacy compatibility. Use {@link makeUnexportedStatus},
+ * {@link makeLastUpdatedStatus}, or {@link makeExportedStatus} instead.
+ *
+ * @example
+ * ```typescript
+ * // Prefer these:
+ * const unexported = makeUnexportedStatus();
+ * const lastUpdated = makeLastUpdatedStatus();
+ * const exported = makeExportedStatus();
+ *
+ * // Instead of:
+ * const status = makeStatus("UNEXPORTED");
+ * ```
+ */
 export const makeStatus = (status) => {
     return status;
 };

package/dist/common/entities/common-entity.js.map

@@ -1 +1 @@
-{"version":3,"file":"common-entity.js","sourceRoot":"","sources":["../../../common/entities/common-entity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAEvD,uBAAuB;AAEvB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;KACjB,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;KACvB,OAAO,CAAC,GAAG,EAAE,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC;KACnC,KAAK,EAAQ,CAAC;AAEhB,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,EAAW,EAAM,EAAE;IACzC,IAAI,CAAC,EAAE;QAAE,OAAO,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC;IAC/C,OAAO,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AACrB,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,KAAK,EAAY,CAAC;AAEtE,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAEjE,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,EAAe,CAAC;AAEvD,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,SAAgB,EAAa,EAAE;IAC5D,IAAI,CAAC,SAAS;QAAE,OAAO,SAAS,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;IACnD,OAAO,SAAS,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;AACnC,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;AAExD,MAAM,CAAC,MAAM,oBAAoB,GAAG,GAAqB,EAAE,CAC1D,gBAAgB,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;AAEtC,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,EAAgB,CAAC;AAEzD,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,UAAiB,EAAc,EAAE;IAC/D,IAAI,CAAC,UAAU;QAAE,OAAO,UAAU,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;IACrD,OAAO,UAAU,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;AACrC,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;IAC7B,UAAU,EAAE,UAAU;CACtB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAmB,EAAE,CACtD,cAAc,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,IAAI,IAAI,EAAE,EAAE,CAAC,CAAC;AAItE,mDAAmD;AACnD,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,MAAiC,EAAU,EAAE;IACvE,OAAO,MAAgB,CAAC;AACzB,CAAC,CAAC"}
+{"version":3,"file":"common-entity.js","sourceRoot":"","sources":["../../../common/entities/common-entity.ts"],"names":[],"mappings":"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"}

package/dist/common/events/base-domain-event.d.ts

@@ -1,12 +1,44 @@
 import type { DomainEvent } from "./domain-event.interface";
+/**
+ * Abstract base class for all domain events.
+ *
+ * @remarks
+ * Provides common functionality for domain events including automatic
+ * timestamp generation. Extend this class to create specific event types.
+ *
+ * @example
+ * ```typescript
+ * class ArticleCreatedEvent extends BaseDomainEvent {
+ *   constructor(data: { title: string; userId: string; caller: string }) {
+ *     super(
+ *       "article.created",
+ *       { title: data.title },
+ *       { caller: data.caller, userId: data.userId }
+ *     );
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link DomainEvent} for the interface
+ */
 export declare abstract class BaseDomainEvent implements DomainEvent {
+    /** The type of event (e.g., "article.created") */
     readonly eventType: string;
+    /** Event-specific data */
     readonly payload: Record<string, unknown>;
+    /** Contextual information about the event */
     readonly metadata: {
         timestamp: Date;
         caller: string;
         userId: string;
     };
+    /**
+     * Creates a new domain event.
+     *
+     * @param eventType - The type identifier for the event
+     * @param payload - Event-specific data
+     * @param metadata - Contextual information (timestamp is auto-generated)
+     */
     constructor(eventType: string, payload: Record<string, unknown>, metadata: {
         caller: string;
         userId: string;

package/dist/common/events/base-domain-event.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base-domain-event.d.ts","sourceRoot":"","sources":["../../../common/events/base-domain-event.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D,8BAAsB,eAAgB,YAAW,WAAW;IAC3D,SAAgB,SAAS,EAAE,MAAM,CAAC;IAClC,SAAgB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjD,SAAgB,QAAQ,EAAE;QACzB,SAAS,EAAE,IAAI,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;KACf,CAAC;gBAGD,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,QAAQ,EAAE;QACT,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;KACf;CASF"}
+{"version":3,"file":"base-domain-event.d.ts","sourceRoot":"","sources":["../../../common/events/base-domain-event.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,8BAAsB,eAAgB,YAAW,WAAW;IAC3D,kDAAkD;IAClD,SAAgB,SAAS,EAAE,MAAM,CAAC;IAElC,0BAA0B;IAC1B,SAAgB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEjD,6CAA6C;IAC7C,SAAgB,QAAQ,EAAE;QACzB,SAAS,EAAE,IAAI,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;KACf,CAAC;IAEF;;;;;;OAMG;gBAEF,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,QAAQ,EAAE;QACT,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;KACf;CASF"}

package/dist/common/events/base-domain-event.js

@@ -1,7 +1,39 @@
+/**
+ * Abstract base class for all domain events.
+ *
+ * @remarks
+ * Provides common functionality for domain events including automatic
+ * timestamp generation. Extend this class to create specific event types.
+ *
+ * @example
+ * ```typescript
+ * class ArticleCreatedEvent extends BaseDomainEvent {
+ *   constructor(data: { title: string; userId: string; caller: string }) {
+ *     super(
+ *       "article.created",
+ *       { title: data.title },
+ *       { caller: data.caller, userId: data.userId }
+ *     );
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link DomainEvent} for the interface
+ */
 export class BaseDomainEvent {
+    /** The type of event (e.g., "article.created") */
     eventType;
+    /** Event-specific data */
     payload;
+    /** Contextual information about the event */
     metadata;
+    /**
+     * Creates a new domain event.
+     *
+     * @param eventType - The type identifier for the event
+     * @param payload - Event-specific data
+     * @param metadata - Contextual information (timestamp is auto-generated)
+     */
     constructor(eventType, payload, metadata) {
         this.eventType = eventType;
         this.payload = payload;

package/dist/common/events/base-domain-event.js.map

@@ -1 +1 @@
-{"version":3,"file":"base-domain-event.js","sourceRoot":"","sources":["../../../common/events/base-domain-event.ts"],"names":[],"mappings":"AAEA,MAAM,OAAgB,eAAe;IACpB,SAAS,CAAS;IAClB,OAAO,CAA0B;IACjC,QAAQ,CAItB;IAEF,YACC,SAAiB,EACjB,OAAgC,EAChC,QAGC;QAED,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,QAAQ,GAAG;YACf,GAAG,QAAQ;YACX,SAAS,EAAE,IAAI,IAAI,EAAE;SACrB,CAAC;IACH,CAAC;CACD"}
+{"version":3,"file":"base-domain-event.js","sourceRoot":"","sources":["../../../common/events/base-domain-event.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,OAAgB,eAAe;IACpC,kDAAkD;IAClC,SAAS,CAAS;IAElC,0BAA0B;IACV,OAAO,CAA0B;IAEjD,6CAA6C;IAC7B,QAAQ,CAItB;IAEF;;;;;;OAMG;IACH,YACC,SAAiB,EACjB,OAAgC,EAChC,QAGC;QAED,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,QAAQ,GAAG;YACf,GAAG,QAAQ;YACX,SAAS,EAAE,IAAI,IAAI,EAAE;SACrB,CAAC;IACH,CAAC;CACD"}

package/dist/common/events/domain-event.interface.d.ts

@@ -1,13 +1,67 @@
+/**
+ * Base interface for all domain events.
+ *
+ * @remarks
+ * Domain events represent significant occurrences within the domain.
+ * They are used for cross-cutting concerns like notifications, logging, and analytics.
+ *
+ * @example
+ * ```typescript
+ * const event: DomainEvent = {
+ *   eventType: "article.created",
+ *   payload: { title: "New Article", url: "https://example.com" },
+ *   metadata: {
+ *     timestamp: new Date(),
+ *     caller: "addArticle",
+ *     userId: "user-123"
+ *   }
+ * };
+ * ```
+ *
+ * @see {@link BaseDomainEvent} for abstract base class
+ * @see {@link DomainEventHandler} for handling events
+ */
 export type DomainEvent = {
+    /** The type of event (e.g., "article.created", "book.deleted") */
     eventType: string;
+    /** Event-specific data */
     payload: Record<string, unknown>;
+    /** Contextual information about the event */
     metadata: {
+        /** When the event occurred */
         timestamp: Date;
+        /** The function/method that triggered the event */
         caller: string;
+        /** The user who triggered the event */
         userId: string;
     };
 };
+/**
+ * Interface for handling domain events.
+ *
+ * @remarks
+ * Implement this interface to create event handlers for specific event types.
+ * Handlers are typically used for side effects like sending notifications.
+ *
+ * @example
+ * ```typescript
+ * class ArticleCreatedHandler implements DomainEventHandler {
+ *   async handle(event: DomainEvent): Promise<void> {
+ *     if (event.eventType === "article.created") {
+ *       await sendNotification(event.payload);
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link DomainEvent} for the event structure
+ */
 export type DomainEventHandler = {
+    /**
+     * Handles a domain event.
+     *
+     * @param event - The domain event to handle
+     */
     handle(event: DomainEvent): Promise<void>;
 };
 //# sourceMappingURL=domain-event.interface.d.ts.map

package/dist/common/events/domain-event.interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"domain-event.interface.d.ts","sourceRoot":"","sources":["../../../common/events/domain-event.interface.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,QAAQ,EAAE;QACT,SAAS,EAAE,IAAI,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;KACf,CAAC;CACF,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAChC,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1C,CAAC"}
+{"version":3,"file":"domain-event.interface.d.ts","sourceRoot":"","sources":["../../../common/events/domain-event.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,WAAW,GAAG;IACzB,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;IAClB,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,6CAA6C;IAC7C,QAAQ,EAAE;QACT,8BAA8B;QAC9B,SAAS,EAAE,IAAI,CAAC;QAChB,mDAAmD;QACnD,MAAM,EAAE,MAAM,CAAC;QACf,uCAAuC;QACvC,MAAM,EAAE,MAAM,CAAC;KACf,CAAC;CACF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAChC;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1C,CAAC"}

package/dist/common/events/system-error-event.d.ts

@@ -1,5 +1,41 @@
 import { BaseDomainEvent } from "./base-domain-event";
+/**
+ * Domain event for system errors.
+ *
+ * @remarks
+ * Used to track and notify about system-level errors.
+ * The shouldNotify flag controls whether external notifications (e.g., Pushover) are sent.
+ *
+ * @example
+ * ```typescript
+ * const event = new SystemErrorEvent({
+ *   message: "Database connection failed",
+ *   status: 500,
+ *   caller: "connectDatabase",
+ *   userId: "system",
+ *   shouldNotify: true,
+ *   extraData: { host: "localhost", port: 5432 }
+ * });
+ *
+ * // event.eventType === "system.error"
+ * await eventHandler.handle(event);
+ * ```
+ *
+ * @see {@link SystemWarningEvent} for non-critical issues
+ * @see {@link BaseDomainEvent} for base class
+ */
 export declare class SystemErrorEvent extends BaseDomainEvent {
+    /**
+     * Creates a new system error event.
+     *
+     * @param data - Error event data
+     * @param data.message - Human-readable error message
+     * @param data.status - HTTP status code representing the error severity
+     * @param data.caller - The function/method where the error occurred
+     * @param data.userId - The user affected (defaults to "system")
+     * @param data.extraData - Additional context about the error
+     * @param data.shouldNotify - Whether to send external notifications (defaults to false)
+     */
     constructor(data: {
         message: string;
         status: number;

package/dist/common/events/system-error-event.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"system-error-event.d.ts","sourceRoot":"","sources":["../../../common/events/system-error-event.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD,qBAAa,gBAAiB,SAAQ,eAAe;gBACxC,IAAI,EAAE;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,YAAY,CAAC,EAAE,OAAO,CAAC;KACvB;CAeD"}
+{"version":3,"file":"system-error-event.d.ts","sourceRoot":"","sources":["../../../common/events/system-error-event.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,gBAAiB,SAAQ,eAAe;IACpD;;;;;;;;;;OAUG;gBACS,IAAI,EAAE;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,YAAY,CAAC,EAAE,OAAO,CAAC;KACvB;CAeD"}

package/dist/common/events/system-error-event.js

@@ -1,5 +1,41 @@
 import { BaseDomainEvent } from "./base-domain-event";
+/**
+ * Domain event for system errors.
+ *
+ * @remarks
+ * Used to track and notify about system-level errors.
+ * The shouldNotify flag controls whether external notifications (e.g., Pushover) are sent.
+ *
+ * @example
+ * ```typescript
+ * const event = new SystemErrorEvent({
+ *   message: "Database connection failed",
+ *   status: 500,
+ *   caller: "connectDatabase",
+ *   userId: "system",
+ *   shouldNotify: true,
+ *   extraData: { host: "localhost", port: 5432 }
+ * });
+ *
+ * // event.eventType === "system.error"
+ * await eventHandler.handle(event);
+ * ```
+ *
+ * @see {@link SystemWarningEvent} for non-critical issues
+ * @see {@link BaseDomainEvent} for base class
+ */
 export class SystemErrorEvent extends BaseDomainEvent {
+    /**
+     * Creates a new system error event.
+     *
+     * @param data - Error event data
+     * @param data.message - Human-readable error message
+     * @param data.status - HTTP status code representing the error severity
+     * @param data.caller - The function/method where the error occurred
+     * @param data.userId - The user affected (defaults to "system")
+     * @param data.extraData - Additional context about the error
+     * @param data.shouldNotify - Whether to send external notifications (defaults to false)
+     */
     constructor(data) {
         super("system.error", {
             message: data.message,

package/dist/common/events/system-error-event.js.map

@@ -1 +1 @@
-{"version":3,"file":"system-error-event.js","sourceRoot":"","sources":["../../../common/events/system-error-event.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD,MAAM,OAAO,gBAAiB,SAAQ,eAAe;IACpD,YAAY,IAOX;QACA,KAAK,CACJ,cAAc,EACd;YACC,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,YAAY,EAAE,IAAI,CAAC,YAAY,IAAI,KAAK;SACxC,EACD;YACC,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,QAAQ;SAC/B,CACD,CAAC;IACH,CAAC;CACD"}
+{"version":3,"file":"system-error-event.js","sourceRoot":"","sources":["../../../common/events/system-error-event.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,OAAO,gBAAiB,SAAQ,eAAe;IACpD;;;;;;;;;;OAUG;IACH,YAAY,IAOX;QACA,KAAK,CACJ,cAAc,EACd;YACC,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,YAAY,EAAE,IAAI,CAAC,YAAY,IAAI,KAAK;SACxC,EACD;YACC,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,QAAQ;SAC/B,CACD,CAAC;IACH,CAAC;CACD"}

package/dist/common/events/system-warning-event.d.ts

@@ -1,5 +1,40 @@
 import { BaseDomainEvent } from "./base-domain-event";
+/**
+ * Domain event for system warnings.
+ *
+ * @remarks
+ * Used to track non-critical issues that don't require immediate action.
+ * The shouldNotify flag controls whether external notifications are sent.
+ *
+ * @example
+ * ```typescript
+ * const event = new SystemWarningEvent({
+ *   message: "Cache miss rate above threshold",
+ *   status: 200,
+ *   caller: "cacheService",
+ *   shouldNotify: false,
+ *   extraData: { missRate: 0.75 }
+ * });
+ *
+ * // event.eventType === "system.warning"
+ * await eventHandler.handle(event);
+ * ```
+ *
+ * @see {@link SystemErrorEvent} for critical errors
+ * @see {@link BaseDomainEvent} for base class
+ */
 export declare class SystemWarningEvent extends BaseDomainEvent {
+    /**
+     * Creates a new system warning event.
+     *
+     * @param data - Warning event data
+     * @param data.message - Human-readable warning message
+     * @param data.status - HTTP status code (typically 2xx for warnings)
+     * @param data.caller - The function/method where the warning occurred
+     * @param data.userId - The user affected (defaults to "system")
+     * @param data.extraData - Additional context about the warning
+     * @param data.shouldNotify - Whether to send external notifications (defaults to false)
+     */
     constructor(data: {
         message: string;
         status: number;

package/dist/common/events/system-warning-event.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"system-warning-event.d.ts","sourceRoot":"","sources":["../../../common/events/system-warning-event.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD,qBAAa,kBAAmB,SAAQ,eAAe;gBAC1C,IAAI,EAAE;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,YAAY,CAAC,EAAE,OAAO,CAAC;KACvB;CAeD"}
+{"version":3,"file":"system-warning-event.d.ts","sourceRoot":"","sources":["../../../common/events/system-warning-event.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,kBAAmB,SAAQ,eAAe;IACtD;;;;;;;;;;OAUG;gBACS,IAAI,EAAE;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,YAAY,CAAC,EAAE,OAAO,CAAC;KACvB;CAeD"}

package/dist/common/events/system-warning-event.js

@@ -1,5 +1,40 @@
 import { BaseDomainEvent } from "./base-domain-event";
+/**
+ * Domain event for system warnings.
+ *
+ * @remarks
+ * Used to track non-critical issues that don't require immediate action.
+ * The shouldNotify flag controls whether external notifications are sent.
+ *
+ * @example
+ * ```typescript
+ * const event = new SystemWarningEvent({
+ *   message: "Cache miss rate above threshold",
+ *   status: 200,
+ *   caller: "cacheService",
+ *   shouldNotify: false,
+ *   extraData: { missRate: 0.75 }
+ * });
+ *
+ * // event.eventType === "system.warning"
+ * await eventHandler.handle(event);
+ * ```
+ *
+ * @see {@link SystemErrorEvent} for critical errors
+ * @see {@link BaseDomainEvent} for base class
+ */
 export class SystemWarningEvent extends BaseDomainEvent {
+    /**
+     * Creates a new system warning event.
+     *
+     * @param data - Warning event data
+     * @param data.message - Human-readable warning message
+     * @param data.status - HTTP status code (typically 2xx for warnings)
+     * @param data.caller - The function/method where the warning occurred
+     * @param data.userId - The user affected (defaults to "system")
+     * @param data.extraData - Additional context about the warning
+     * @param data.shouldNotify - Whether to send external notifications (defaults to false)
+     */
     constructor(data) {
         super("system.warning", {
             message: data.message,

package/dist/common/events/system-warning-event.js.map

@@ -1 +1 @@
-{"version":3,"file":"system-warning-event.js","sourceRoot":"","sources":["../../../common/events/system-warning-event.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD,MAAM,OAAO,kBAAmB,SAAQ,eAAe;IACtD,YAAY,IAOX;QACA,KAAK,CACJ,gBAAgB,EAChB;YACC,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,YAAY,EAAE,IAAI,CAAC,YAAY,IAAI,KAAK;SACxC,EACD;YACC,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,QAAQ;SAC/B,CACD,CAAC;IACH,CAAC;CACD"}
+{"version":3,"file":"system-warning-event.js","sourceRoot":"","sources":["../../../common/events/system-warning-event.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,OAAO,kBAAmB,SAAQ,eAAe;IACtD;;;;;;;;;;OAUG;IACH,YAAY,IAOX;QACA,KAAK,CACJ,gBAAgB,EAChB;YACC,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,YAAY,EAAE,IAAI,CAAC,YAAY,IAAI,KAAK;SACxC,EACD;YACC,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,QAAQ;SAC/B,CACD,CAAC;IACH,CAAC;CACD"}

package/dist/common/index.d.ts

@@ -1,3 +1,26 @@
+/**
+ * @packageDocumentation
+ *
+ * Common utilities shared across all domains.
+ *
+ * @remarks
+ * Provides foundational building blocks including:
+ *
+ * - **Entities** - Common value objects (Id, UserId, CreatedAt, Status)
+ * - **Events** - Domain event infrastructure (BaseDomainEvent, SystemEvents)
+ * - **Services** - Shared services (ID generation, entity factory)
+ * - **Types** - Common type definitions
+ *
+ * @example
+ * ```typescript
+ * import { makeId, makeUserId, makeCreatedAt, UnexportedStatus } from "@repo/core/common";
+ *
+ * const id = makeId();
+ * const userId = makeUserId("user-123");
+ * const createdAt = makeCreatedAt();
+ * const status = UnexportedStatus;
+ * ```
+ */
 export * from "./entities/common-entity";
 export * from "./events/base-domain-event";
 export * from "./events/domain-event.interface";