@headless-lms/core 0.1.0

package/dist/discussion/events.d.ts

@@ -0,0 +1,101 @@
+import { NewDomainEvent } from "../types/shared.js";
+import { EventOf, EventOfValues, RuntimeEventDefinition, VersionedDomainEvent } from "../shared/events.js";
+import "../shared/ports.js";
+//#region src/discussion/events.d.ts
+declare const discussionEvents: {
+  commentCreated: RuntimeEventDefinition<VersionedDomainEvent<{
+    id: string;
+    orgId: string;
+    activityId: string;
+    parentId: string | null;
+    orgUserId: string;
+    body: string;
+    status: "pending" | "published" | "removed";
+    removedBy: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+  }, "discussion.comment.created", 1>, {
+    id: string;
+    orgId: string;
+    activityId: string;
+    parentId: string | null;
+    orgUserId: string;
+    body: string;
+    status: "pending" | "published" | "removed";
+    removedBy: string | null;
+    createdAt: unknown;
+    updatedAt: unknown;
+  }>;
+  commentPublished: RuntimeEventDefinition<VersionedDomainEvent<{
+    id: string;
+    orgId: string;
+    activityId: string;
+    parentId: string | null;
+    orgUserId: string;
+    body: string;
+    status: "pending" | "published" | "removed";
+    removedBy: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+  }, "discussion.comment.published", 1>, {
+    id: string;
+    orgId: string;
+    activityId: string;
+    parentId: string | null;
+    orgUserId: string;
+    body: string;
+    status: "pending" | "published" | "removed";
+    removedBy: string | null;
+    createdAt: unknown;
+    updatedAt: unknown;
+  }>;
+  commentRemoved: RuntimeEventDefinition<VersionedDomainEvent<{
+    id: string;
+    orgId: string;
+    activityId: string;
+    parentId: string | null;
+    orgUserId: string;
+    body: string;
+    status: "pending" | "published" | "removed";
+    removedBy: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+  }, "discussion.comment.removed", 1>, {
+    id: string;
+    orgId: string;
+    activityId: string;
+    parentId: string | null;
+    orgUserId: string;
+    body: string;
+    status: "pending" | "published" | "removed";
+    removedBy: string | null;
+    createdAt: unknown;
+    updatedAt: unknown;
+  }>;
+  commentReported: RuntimeEventDefinition<VersionedDomainEvent<{
+    id: string;
+    orgId: string;
+    commentId: string;
+    orgUserId: string;
+    reason: string;
+    resolvedAt: Date | null;
+    createdAt: Date;
+  }, "discussion.comment.reported", 1>, {
+    id: string;
+    orgId: string;
+    commentId: string;
+    orgUserId: string;
+    reason: string;
+    resolvedAt: unknown;
+    createdAt: unknown;
+  }>;
+};
+type CommentCreated = EventOf<typeof discussionEvents.commentCreated>;
+type CommentPublished = EventOf<typeof discussionEvents.commentPublished>;
+type CommentRemoved = EventOf<typeof discussionEvents.commentRemoved>;
+type CommentReported = EventOf<typeof discussionEvents.commentReported>;
+type CommentEvent = EventOfValues<typeof discussionEvents>;
+type NewDiscussionEvent = NewDomainEvent<CommentEvent>;
+//#endregion
+export { CommentCreated, CommentEvent, CommentPublished, CommentRemoved, CommentReported, NewDiscussionEvent, discussionEvents };
+//# sourceMappingURL=events.d.ts.map

package/dist/discussion/events.js

@@ -0,0 +1,29 @@
+import { commentReportSchema, commentSchema } from "../types/schemas/discussion.js";
+import { defineEvent } from "../shared/events.js";
+//#region src/discussion/events.ts
+const discussionEvents = {
+	commentCreated: defineEvent({
+		type: "discussion.comment.created",
+		version: 1,
+		data: commentSchema
+	}),
+	commentPublished: defineEvent({
+		type: "discussion.comment.published",
+		version: 1,
+		data: commentSchema
+	}),
+	commentRemoved: defineEvent({
+		type: "discussion.comment.removed",
+		version: 1,
+		data: commentSchema
+	}),
+	commentReported: defineEvent({
+		type: "discussion.comment.reported",
+		version: 1,
+		data: commentReportSchema
+	})
+};
+//#endregion
+export { discussionEvents };
+
+//# sourceMappingURL=events.js.map

package/dist/discussion/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","names":[],"sources":["../../src/discussion/events.ts"],"sourcesContent":["import { commentReportSchema, commentSchema } from '../types/schemas/index.js';\nimport {\n  defineEvent,\n  type EventOf,\n  type EventOfValues,\n  type NewDomainEvent,\n} from '../shared/ports.js';\n\nexport const discussionEvents = {\n  commentCreated: defineEvent({\n    type: 'discussion.comment.created',\n    version: 1,\n    data: commentSchema,\n  }),\n  commentPublished: defineEvent({\n    type: 'discussion.comment.published',\n    version: 1,\n    data: commentSchema,\n  }),\n  commentRemoved: defineEvent({\n    type: 'discussion.comment.removed',\n    version: 1,\n    data: commentSchema,\n  }),\n  commentReported: defineEvent({\n    type: 'discussion.comment.reported',\n    version: 1,\n    data: commentReportSchema,\n  }),\n};\n\nexport type CommentCreated = EventOf<typeof discussionEvents.commentCreated>;\nexport type CommentPublished = EventOf<typeof discussionEvents.commentPublished>;\nexport type CommentRemoved = EventOf<typeof discussionEvents.commentRemoved>;\nexport type CommentReported = EventOf<typeof discussionEvents.commentReported>;\nexport type CommentEvent = EventOfValues<typeof discussionEvents>;\nexport type NewDiscussionEvent = NewDomainEvent<CommentEvent>;\n"],"mappings":";;;AAQA,MAAa,mBAAmB;CAC9B,gBAAgB,YAAY;EAC1B,MAAM;EACN,SAAS;EACT,MAAM;CACR,CAAC;CACD,kBAAkB,YAAY;EAC5B,MAAM;EACN,SAAS;EACT,MAAM;CACR,CAAC;CACD,gBAAgB,YAAY;EAC1B,MAAM;EACN,SAAS;EACT,MAAM;CACR,CAAC;CACD,iBAAiB,YAAY;EAC3B,MAAM;EACN,SAAS;EACT,MAAM;CACR,CAAC;AACH"}

package/dist/discussion/index.d.ts

@@ -0,0 +1,8 @@
+import { CommentListItem, CommentReaction, CommentReportSummary, CommentSettings, CommentStatus, CommentView, CommentsConfig, ListCommentsQuery, ReactionCounts, ReactionEmoji } from "../types/schemas/discussion.js";
+import { Comment, CommentAuthor, CommentReport } from "../types/discussion.js";
+import { CommentEvent, discussionEvents } from "./events.js";
+import "./model.js";
+import "./types.js";
+import { ActivityComments, Actor, AuthorRecord, CommentReactions, CommentWithContext, CourseAccessReader, DiscussionRepository, DiscussionService, DiscussionUnitOfWork, DiscussionWriteScope, PostCommentInput } from "./ports.js";
+import { DEFAULT_SETTINGS, DiscussionServiceImpl } from "./service.js";
+export { type ActivityComments, type Actor, type AuthorRecord, type Comment, type CommentAuthor, type CommentEvent, type CommentListItem, type CommentReaction, type CommentReactions, type CommentReport, type CommentReportSummary, type CommentSettings, type CommentStatus, type CommentView, type CommentWithContext, type CommentsConfig, type CourseAccessReader, DEFAULT_SETTINGS, type DiscussionRepository, type DiscussionService, DiscussionServiceImpl, type DiscussionUnitOfWork, type DiscussionWriteScope, type ListCommentsQuery, type PostCommentInput, type ReactionCounts, type ReactionEmoji, discussionEvents };

package/dist/discussion/index.js

@@ -0,0 +1,3 @@
+import { discussionEvents } from "./events.js";
+import { DEFAULT_SETTINGS, DiscussionServiceImpl } from "./service.js";
+export { DEFAULT_SETTINGS, DiscussionServiceImpl, discussionEvents };

package/dist/discussion/model.d.ts

@@ -0,0 +1,5 @@
+import { ActivityCommentsRule } from "../types/schemas/content.js";
+import { CommentReaction, CommentSettings, CommentStatus } from "../types/schemas/discussion.js";
+import { Comment, CommentAuthor, CommentReport } from "../types/discussion.js";
+import "../types/index.js";
+export type { ActivityCommentsRule, Comment, CommentAuthor, CommentReaction, CommentReport, CommentSettings, CommentStatus };

package/dist/discussion/model.js

@@ -0,0 +1 @@
+export {};

package/dist/discussion/ports.d.ts

@@ -0,0 +1,112 @@
+import { Page } from "../types/shared.js";
+import { Role } from "../types/schemas/organizations.js";
+import { Activity } from "../types/schemas/content.js";
+import { CommentListItem, CommentView, CommentsConfig, ListCommentsQuery, ReactionCounts, ReactionEmoji } from "../types/schemas/discussion.js";
+import { Comment, CommentAuthor, CommentReport } from "../types/discussion.js";
+import "../types/index.js";
+import { OutboxAppender, UnitOfWork } from "../shared/ports.js";
+import "./model.js";
+import "./types.js";
+//#region src/discussion/ports.d.ts
+/** An activity's comments as this reader may see them, with the config that
+ *  decided it. */
+interface ActivityComments {
+  config: CommentsConfig;
+  comments: CommentView[];
+}
+interface CommentReactions {
+  reactions: ReactionCounts;
+  viewerReaction?: ReactionEmoji;
+}
+interface CommentWithContext {
+  comment: Comment;
+  courseId: string;
+  activityTitle: string;
+}
+/**
+ * Who is acting, and the role they hold in this org right now.
+ *
+ * The role is resolved at the HTTP edge from the session's active-org
+ * org user and handed in — read fresh on every request, never stored on a
+ * comment. Core does not look a role up to authorise.
+ */
+interface Actor {
+  id: string;
+  role: Role;
+}
+type PostCommentInput = {
+  actor: Actor;
+  activityId: string;
+  parentId: string | null;
+  body: string;
+};
+/** A profile row as the repository loads it, keyed by `org_users.id`. `email`
+ *  is stripped before comments are served and kept only for the staff list. */
+interface AuthorRecord extends CommentAuthor {
+  email: string;
+}
+interface DiscussionService {
+  /** Post a root comment or a reply. Lands pending where review is required and
+   *  the poster is not staff. */
+  postComment(orgId: string, input: PostCommentInput): Promise<CommentView>;
+  /** Author-only. Throws ForbiddenError for anyone else, staff included. */
+  edit(orgId: string, commentId: string, actor: Actor, body: string): Promise<CommentView>;
+  /** The author, or anyone whose role is staff. */
+  remove(orgId: string, commentId: string, actor: Actor): Promise<Comment>;
+  /** Staff only. Returns the comment to published. */
+  restore(orgId: string, commentId: string, actor: Actor): Promise<Comment>;
+  /** Staff only. Publishes a pending comment. */
+  approve(orgId: string, commentId: string, actor: Actor): Promise<Comment>;
+  /** Make a comment published, whichever state it is in. Staff only. */
+  publish(orgId: string, commentId: string, actor: Actor): Promise<Comment>;
+  /** The activity's comments as this reader may see them. */
+  activityComments(orgId: string, activityId: string, actor: Actor): Promise<ActivityComments>;
+  /**
+   * The org's comments, filtered. Staff-scoped: rows carry the author's email
+   * and a removed comment's body, neither of which a learner may see, so the
+   * edge admits only staff.
+   *
+   * No rule is applied beyond the filters — this is what exists, not what
+   * someone is allowed to read.
+   */
+  listComments(orgId: string, query: ListCommentsQuery): Promise<Page<CommentListItem>>;
+  setReaction(orgId: string, commentId: string, actor: Actor, emoji: ReactionEmoji | null): Promise<CommentReactions>;
+  resolveReports(orgId: string, commentId: string, actor: Actor): Promise<void>;
+  /** Accepted even on locked comments — a locked activity can still hold
+   *  something a moderator needs to see. */
+  reportComment(orgId: string, commentId: string, actor: Actor, reason: string): Promise<CommentReport>;
+  /** Plain read of one comment — no rules applied. */
+  getComment(orgId: string, commentId: string): Promise<Comment | null>;
+}
+interface CourseAccessReader {
+  hasCourseAccess(orgId: string, orgUserId: string, courseId: string): Promise<boolean>;
+}
+interface ActivityGetter {
+  getActivity(orgId: string, activityId: string): Promise<Activity | null>;
+}
+interface DiscussionRepository {
+  insertComment(orgId: string, comment: Comment): Promise<Comment>;
+  findComment(orgId: string, id: string): Promise<Comment | null>;
+  updateComment(orgId: string, id: string, patch: Partial<Pick<Comment, 'body' | 'status' | 'removedBy' | 'updatedAt'>>): Promise<Comment | null>;
+  /** Every comment on the activity, oldest first, including removed ones. */
+  listByActivity(orgId: string, activityId: string): Promise<Comment[]>;
+  reactionsOf(orgId: string, commentIds: string[], viewerId: string): Promise<Record<string, CommentReactions>>;
+  setReaction(orgId: string, commentId: string, orgUserId: string, emoji: ReactionEmoji | null): Promise<void>;
+  /** Returns null when this person has already reported this comment. */
+  insertReport(orgId: string, report: CommentReport): Promise<CommentReport | null>;
+  /** Every unresolved report against the given comments. */
+  listOpenReports(orgId: string, commentIds: string[]): Promise<CommentReport[]>;
+  resolveReportsFor(orgId: string, commentId: string, resolvedAt: Date): Promise<void>;
+  authorsOf(orgId: string, orgUserIds: string[]): Promise<Record<string, AuthorRecord>>;
+  listComments(orgId: string, query: ListCommentsQuery): Promise<Page<CommentWithContext>>;
+}
+/** Writes that emit events run through this scope so the row and the outbox
+ *  entry commit in one transaction. */
+interface DiscussionWriteScope {
+  discussion: DiscussionRepository;
+  outbox: OutboxAppender;
+}
+type DiscussionUnitOfWork = UnitOfWork<DiscussionWriteScope>;
+//#endregion
+export { ActivityComments, ActivityGetter, Actor, AuthorRecord, CommentReactions, CommentWithContext, CourseAccessReader, DiscussionRepository, DiscussionService, DiscussionUnitOfWork, DiscussionWriteScope, PostCommentInput };
+//# sourceMappingURL=ports.d.ts.map

package/dist/discussion/ports.js

@@ -0,0 +1 @@
+export {};

package/dist/discussion/service.d.ts

@@ -0,0 +1,67 @@
+import { Page } from "../types/shared.js";
+import { Logger } from "../types/ports.js";
+import { CommentListItem, CommentView, CommentsConfig, ListCommentsQuery, ReactionEmoji } from "../types/schemas/discussion.js";
+import { Comment, CommentReport } from "../types/discussion.js";
+import "../shared/ports.js";
+import { SettingsService } from "../shared/settings.js";
+import "./model.js";
+import "./types.js";
+import { ActivityComments, ActivityGetter, Actor, CommentReactions, CourseAccessReader, DiscussionRepository, DiscussionService, DiscussionUnitOfWork, PostCommentInput } from "./ports.js";
+//#region src/discussion/service.d.ts
+/** A course with no stored settings. Discussion is opt-in, so the common case
+ *  persists no row at all and every existing course stays silent. */
+declare const DEFAULT_SETTINGS: {
+  readonly enabled: false;
+  readonly threaded: true;
+  readonly requireReview: false;
+  readonly reactions: true;
+};
+type DiscussionServiceParams = {
+  repo: DiscussionRepository;
+  access: CourseAccessReader;
+  content: ActivityGetter;
+  uow: DiscussionUnitOfWork;
+  settings: SettingsService;
+  logger?: Logger;
+};
+declare class DiscussionServiceImpl implements DiscussionService {
+  private readonly repo;
+  private readonly access;
+  private readonly content;
+  private readonly uow;
+  private readonly settings;
+  private readonly logger;
+  constructor(params: DiscussionServiceParams);
+  resolveConfig(orgId: string, activityId: string): Promise<CommentsConfig>;
+  /** Any org user that is not a learner moderates. The role arrives from
+   *  the edge already resolved; core never looks one up to authorise. */
+  private isStaff;
+  private toAuthor;
+  private toView;
+  private peopleIn;
+  private renderOne;
+  private hasAccess;
+  postComment(orgId: string, { activityId, actor, parentId, body }: PostCommentInput): Promise<CommentView>;
+  activityComments(orgId: string, activityId: string, actor: Actor): Promise<ActivityComments>;
+  edit(orgId: string, commentId: string, actor: Actor, body: string): Promise<CommentView>;
+  remove(orgId: string, commentId: string, actor: Actor): Promise<Comment>;
+  restore(orgId: string, commentId: string, actor: Actor): Promise<Comment>;
+  /** Load a comment together with its activity's resolved comments config,
+   *  having proved the actor may reach that activity at all. Every path that
+   *  acts on one comment needs the pair, and none should read the row twice. */
+  private loadWithConfig;
+  setReaction(orgId: string, commentId: string, actor: Actor, emoji: ReactionEmoji | null): Promise<CommentReactions>;
+  approve(orgId: string, commentId: string, actor: Actor): Promise<Comment>;
+  /** Loads the comment and dispatches to whichever transition applies — the
+   *  caller must not decide that itself. `approve` and `restore` still enforce
+   *  their own staff check; the check here covers the third path, where a
+   *  comment is already published and neither of them would run. */
+  publish(orgId: string, commentId: string, actor: Actor): Promise<Comment>;
+  resolveReports(orgId: string, commentId: string, actor: Actor): Promise<void>;
+  reportComment(orgId: string, commentId: string, actor: Actor, reason: string): Promise<CommentReport>;
+  listComments(orgId: string, query: ListCommentsQuery): Promise<Page<CommentListItem>>;
+  getComment(orgId: string, commentId: string): Promise<Comment | null>;
+}
+//#endregion
+export { DEFAULT_SETTINGS, DiscussionServiceImpl, DiscussionServiceParams };
+//# sourceMappingURL=service.d.ts.map