@headless-lms/core 0.2.0 → 0.3.0

package/dist/entitlements/ports.d.ts

@@ -1,34 +1,147 @@
 import { Page } from "../types/shared.js";
-import { Entitlement, EntitlementsQuery, GrantEntitlementInput } from "../types/schemas/entitlements.js";
+import { ContentType, Space } from "../types/schemas/content.js";
+import { Role } from "../types/schemas/organizations.js";
+import { Entitlement, EntitlementsQuery, GrantEntitlementInput, SpaceMember, SpaceMemberSource, SpaceMemberStatus } from "../types/schemas/entitlements.js";
 import { OutboxAppender, UnitOfWork } from "../shared/ports.js";
+import { Actor } from "../shared/actor.js";
+import { SpaceRowLock } from "../content/ports.js";
+import "../content/index.js";
 import "./model.js";
+import "../organizations/index.js";
 //#region src/entitlements/ports.d.ts
-interface EntitlementsService {
+interface GrantTarget {
+  contentId: string | null;
+  bundleId: string | null;
+}
+type SpaceAccessRule = 'all_members' | 'by_request' | 'by_invite';
+interface OpenableSpace {
+  id: string;
+  communityId: string;
+  accessRule: SpaceAccessRule;
+}
+interface CommunityAccessReader {
+  isCommunityMember(orgId: string, actor: Actor, communityId: string): Promise<boolean>;
+  canOpenSpace(orgId: string, actor: Actor, spaceId: string): Promise<boolean>;
+  canOpen(orgId: string, actor: Actor, space: OpenableSpace): Promise<boolean>;
+  openSpaceIds(orgId: string, actor: Actor, communityId: string): Promise<string[]>;
+  openSpacesFor(orgId: string, actor: Actor, communityId: string): Promise<Space[]>;
+  spaceStandings(orgId: string, actor: Actor, communityId: string): Promise<Record<string, SpaceMember['status']>>;
+  communityMembersAmong(orgId: string, communityId: string, orgUserIds: string[]): Promise<string[]>;
+  spaceOpenersAmong(orgId: string, spaceId: string, orgUserIds: string[]): Promise<string[]>;
+  spaceOpeners(orgId: string, spaceId: string): Promise<string[]>;
+}
+type EntitlementNotice = {
+  kind: 'expired';
+  entitlementId: string;
+  expiresAt: Date;
+} | {
+  kind: 'ending_soon';
+  entitlementId: string;
+  communityId: string;
+  expiresAt: Date;
+};
+interface EndingGrant {
+  grant: Entitlement;
+  communityId: string;
+}
+interface EndingGrantKey {
+  entitlementId: string;
+  communityId: string;
+}
+interface AccessFacts {
+  orgUserId: string;
+  role: Role;
+  member: boolean;
+  activeInSpace: boolean;
+}
+interface GrantKey {
+  orgUserId: string;
+  contentId?: string | null;
+  bundleId?: string | null;
+}
+interface SpaceMembersQuery {
+  page: number;
+  pageSize: number;
+  statuses?: SpaceMemberStatus[];
+}
+interface InsertSpaceMemberInput {
+  communityId: string;
+  spaceId: string;
+  orgUserId: string;
+  status: SpaceMemberStatus;
+  source: SpaceMemberSource;
+}
+interface EntitlementsService extends CommunityAccessReader {
   list(orgId: string, query: EntitlementsQuery): Promise<Page<Entitlement>>;
   grant(orgId: string, input: GrantEntitlementInput): Promise<Entitlement>;
+  ensureGrant(orgId: string, input: GrantEntitlementInput): Promise<Entitlement>;
   setStatus(orgId: string, id: string, status: 'active' | 'revoked'): Promise<Entitlement | null>;
-  /** Whether this org user currently holds active access to the course.
-   *  The authority for course access — a reporting read must never be used to
-   *  infer it. */
-  hasCourseAccess(orgId: string, orgUserId: string, courseId: string): Promise<boolean>;
+  /** Whether this org user can open the content right now, through a grant to
+   *  it or to a bundle holding it. The only access check — nothing else may
+   *  derive access from grants. */
+  hasAccess(orgId: string, orgUserId: string, contentId: string): Promise<boolean>;
+  /** Ids of the content this org user can open right now, optionally of one type. */
+  listAccessibleContent(orgId: string, orgUserId: string, type?: ContentType): Promise<string[]>;
+  requestJoin(orgId: string, actor: Actor, communityId: string, spaceId: string): Promise<SpaceMember>;
+  invite(orgId: string, actor: Actor, communityId: string, spaceId: string, orgUserId: string): Promise<SpaceMember>;
+  addSpaceMember(orgId: string, actor: Actor, communityId: string, spaceId: string, orgUserId: string): Promise<SpaceMember>;
+  accept(orgId: string, actor: Actor, communityId: string, spaceId: string): Promise<SpaceMember>;
+  approve(orgId: string, actor: Actor, communityId: string, spaceId: string, orgUserId: string): Promise<SpaceMember>;
+  decline(orgId: string, actor: Actor, communityId: string, spaceId: string, orgUserId: string): Promise<SpaceMember>;
+  refuse(orgId: string, actor: Actor, communityId: string, spaceId: string): Promise<SpaceMember>;
+  leave(orgId: string, actor: Actor, communityId: string, spaceId: string): Promise<SpaceMember>;
+  remove(orgId: string, actor: Actor, communityId: string, spaceId: string, orgUserId: string): Promise<SpaceMember>;
+  listSpaceMembers(orgId: string, actor: Actor, communityId: string, spaceId: string, query: {
+    page: number;
+    pageSize: number;
+  }): Promise<Page<SpaceMember>>;
+  expireDue(orgId: string, now: Date): Promise<void>;
+  hasDueNotices(orgId: string, now: Date): Promise<boolean>;
+  communitiesOpenedBy(orgId: string, grant: GrantTarget): Promise<string[]>;
+  communityModeratorIds(orgId: string, communityId: string): Promise<string[]>;
+  communityIdsOpenedFor(orgId: string, orgUserId: string): Promise<string[]>;
+  countActiveSpaceMembers(orgId: string, spaceId: string): Promise<number>;
 }
 interface EntitlementsRepository {
   list(orgId: string, query: EntitlementsQuery): Promise<Page<Entitlement>>;
   insert(orgId: string, input: GrantEntitlementInput): Promise<Entitlement>;
+  insertIfAbsent(orgId: string, input: GrantEntitlementInput): Promise<Entitlement | null>;
+  lockGrant(orgId: string, key: GrantKey): Promise<Entitlement | null>;
+  setExpiresAt(orgId: string, id: string, expiresAt: Date | null): Promise<Entitlement | null>;
   setStatus(orgId: string, id: string, status: 'active' | 'revoked'): Promise<Entitlement | null>;
-  /** Whether this org user currently holds active access to the course.
-   *  The authority for course access — a reporting read must never be used to
-   *  infer it. */
-  hasCourseAccess(orgId: string, orgUserId: string, courseId: string): Promise<boolean>;
+  hasAccess(orgId: string, orgUserId: string, contentId: string): Promise<boolean>;
+  listAccessibleContent(orgId: string, orgUserId: string, type?: ContentType): Promise<string[]>;
+  hasCommunityAccess(orgId: string, orgUserId: string, communityId: string): Promise<boolean>;
+  communitiesOpenedBy(orgId: string, grant: GrantTarget): Promise<string[]>;
+  accessAmong(orgId: string, communityId: string, spaceId: string | null, orgUserIds: string[]): Promise<AccessFacts[]>;
+  findSpaceMember(orgId: string, spaceId: string, orgUserId: string): Promise<SpaceMember | null>;
+  listSpaceMembersFor(orgId: string, orgUserId: string, communityId: string): Promise<SpaceMember[]>;
+  lockSpaceMember(orgId: string, spaceId: string, orgUserId: string): Promise<SpaceMember | null>;
+  listSpaceMembers(orgId: string, spaceId: string, query: SpaceMembersQuery): Promise<Page<SpaceMember>>;
+  insertSpaceMember(orgId: string, input: InsertSpaceMemberInput): Promise<SpaceMember>;
+  updateSpaceMemberStatus(orgId: string, id: string, status: SpaceMemberStatus): Promise<SpaceMember | null>;
+  deleteSpaceMember(orgId: string, id: string): Promise<void>;
+  countActiveSpaceMembers(orgId: string, spaceId: string): Promise<number>;
+  activeSpaceIds(orgId: string, orgUserId: string, communityId: string): Promise<string[]>;
+  /** Expired grants with no expiry notice, in id order, after `afterId` when given. */
+  listGrantsExpiredBy(orgId: string, now: Date, limit: number, afterId?: string): Promise<Entitlement[]>;
+  /** Grants ending in the window with no notice, in (grant id, community id) order, after `afterKey`. */
+  listGrantsEndingBetween(orgId: string, after: Date, until: Date, limit: number, afterKey?: EndingGrantKey): Promise<EndingGrant[]>;
+  hasDueNotices(orgId: string, now: Date, until: Date): Promise<boolean>;
+  claimNotice(orgId: string, notice: EntitlementNotice, now: Date): Promise<boolean>;
+  communityModeratorIds(orgId: string, communityId: string): Promise<string[]>;
+  communityMemberIds(orgId: string, communityId: string): Promise<string[]>;
+  communityIdsOpenedFor(orgId: string, orgUserId: string): Promise<string[]>;
 }
 /** Tx-scoped port bundle for this context's mutating use cases — every member
  *  is bound to the UnitOfWork's transaction, so the write and the event append
  *  commit or roll back as one. */
 interface EntitlementsTxScope {
   entitlements: EntitlementsRepository;
+  spaces: SpaceRowLock;
   outbox: OutboxAppender;
 }
 type EntitlementsUnitOfWork = UnitOfWork<EntitlementsTxScope>;
 //#endregion
-export { EntitlementsRepository, EntitlementsService, EntitlementsTxScope, EntitlementsUnitOfWork };
+export { AccessFacts, CommunityAccessReader, EndingGrant, EndingGrantKey, EntitlementNotice, EntitlementsRepository, EntitlementsService, EntitlementsTxScope, EntitlementsUnitOfWork, GrantKey, GrantTarget, InsertSpaceMemberInput, OpenableSpace, SpaceAccessRule, SpaceMembersQuery };
 //# sourceMappingURL=ports.d.ts.map

package/dist/entitlements/rules.d.ts

@@ -0,0 +1,12 @@
+import { Role } from "../types/schemas/organizations.js";
+import { SpaceMemberStatus } from "../types/schemas/entitlements.js";
+import "./model.js";
+import "../organizations/index.js";
+import { SpaceAccessRule } from "./ports.js";
+//#region src/entitlements/rules.d.ts
+declare function opensSpace(role: Role, member: boolean, accessRule: SpaceAccessRule, activeInSpace: boolean): boolean;
+declare function seesSpace(role: Role, accessRule: SpaceAccessRule, status: SpaceMemberStatus | undefined): boolean;
+declare function laterExpiry(a: Date | null, b: Date | null): Date | null;
+//#endregion
+export { laterExpiry, opensSpace, seesSpace };
+//# sourceMappingURL=rules.d.ts.map

package/dist/entitlements/rules.js

@@ -0,0 +1,17 @@
+import { canModerate } from "../organizations/roles.js";
+//#region src/entitlements/rules.ts
+function opensSpace(role, member, accessRule, activeInSpace) {
+	if (!member) return false;
+	return canModerate(role) || accessRule === "all_members" || activeInSpace;
+}
+function seesSpace(role, accessRule, status) {
+	return canModerate(role) || accessRule !== "by_invite" || status !== void 0 && status !== "revoked";
+}
+function laterExpiry(a, b) {
+	if (a === null || b === null) return null;
+	return a.getTime() >= b.getTime() ? a : b;
+}
+//#endregion
+export { laterExpiry, opensSpace, seesSpace };
+
+//# sourceMappingURL=rules.js.map

package/dist/entitlements/rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.js","names":[],"sources":["../../src/entitlements/rules.ts"],"sourcesContent":["import { canModerate, type Role } from '../organizations/index.js';\nimport type { SpaceAccessRule } from './ports.js';\nimport type { SpaceMemberStatus } from './model.js';\n\nexport function opensSpace(\n  role: Role,\n  member: boolean,\n  accessRule: SpaceAccessRule,\n  activeInSpace: boolean,\n): boolean {\n  if (!member) {\n    return false;\n  }\n  return canModerate(role) || accessRule === 'all_members' || activeInSpace;\n}\n\nexport function seesSpace(\n  role: Role,\n  accessRule: SpaceAccessRule,\n  status: SpaceMemberStatus | undefined,\n): boolean {\n  return (\n    canModerate(role) ||\n    accessRule !== 'by_invite' ||\n    (status !== undefined && status !== 'revoked')\n  );\n}\n\nexport function laterExpiry(a: Date | null, b: Date | null): Date | null {\n  if (a === null || b === null) {\n    return null;\n  }\n  return a.getTime() >= b.getTime() ? a : b;\n}\n"],"mappings":";;AAIA,SAAgB,WACd,MACA,QACA,YACA,eACS;CACT,IAAI,CAAC,QACH,OAAO;CAET,OAAO,YAAY,IAAI,KAAK,eAAe,iBAAiB;AAC9D;AAEA,SAAgB,UACd,MACA,YACA,QACS;CACT,OACE,YAAY,IAAI,KAChB,eAAe,eACd,WAAW,KAAA,KAAa,WAAW;AAExC;AAEA,SAAgB,YAAY,GAAgB,GAA6B;CACvE,IAAI,MAAM,QAAQ,MAAM,MACtB,OAAO;CAET,OAAO,EAAE,QAAQ,KAAK,EAAE,QAAQ,IAAI,IAAI;AAC1C"}

package/dist/entitlements/service.d.ts

@@ -1,26 +1,77 @@
 import { Page } from "../types/shared.js";
 import { Logger } from "../types/ports.js";
-import { Entitlement, EntitlementsQuery, GrantEntitlementInput } from "../types/schemas/entitlements.js";
+import { ContentType, Space } from "../types/schemas/content.js";
+import { Entitlement, EntitlementsQuery, GrantEntitlementInput, SpaceMember } from "../types/schemas/entitlements.js";
 import "../shared/ports.js";
+import { Actor } from "../shared/actor.js";
+import { CommunityReader } from "../content/ports.js";
+import "../content/index.js";
 import "./model.js";
-import { EntitlementsRepository, EntitlementsService, EntitlementsUnitOfWork } from "./ports.js";
+import { EntitlementsRepository, EntitlementsService, EntitlementsUnitOfWork, GrantTarget, OpenableSpace } from "./ports.js";
 //#region src/entitlements/service.d.ts
 type EntitlementsServiceParams = {
   /** Read-only access (list) — runs outside any transaction. */
   repo: EntitlementsRepository;
+  content: CommunityReader;
   /** Atomic write scope: tx-bound repo + outbox appender. */
   uow: EntitlementsUnitOfWork;
   logger?: Logger;
 };
 declare class EntitlementsServiceImpl implements EntitlementsService {
   private readonly repo;
+  private readonly content;
   private readonly uow;
   private readonly logger;
   constructor(params: EntitlementsServiceParams);
   list(orgId: string, query: EntitlementsQuery): Promise<Page<Entitlement>>;
   grant(orgId: string, input: GrantEntitlementInput): Promise<Entitlement>;
+  ensureGrant(orgId: string, input: GrantEntitlementInput): Promise<Entitlement>;
   setStatus(orgId: string, id: string, status: 'active' | 'revoked'): Promise<Entitlement | null>;
-  hasCourseAccess(orgId: string, orgUserId: string, courseId: string): Promise<boolean>;
+  hasAccess(orgId: string, orgUserId: string, contentId: string): Promise<boolean>;
+  listAccessibleContent(orgId: string, orgUserId: string, type?: ContentType): Promise<string[]>;
+  isCommunityMember(orgId: string, actor: Actor, communityId: string): Promise<boolean>;
+  canOpenSpace(orgId: string, actor: Actor, spaceId: string): Promise<boolean>;
+  canOpen(orgId: string, actor: Actor, space: OpenableSpace): Promise<boolean>;
+  spaceStandings(orgId: string, actor: Actor, communityId: string): Promise<Record<string, SpaceMember['status']>>;
+  openSpacesFor(orgId: string, actor: Actor, communityId: string): Promise<Space[]>;
+  openSpaceIds(orgId: string, actor: Actor, communityId: string): Promise<string[]>;
+  communityMembersAmong(orgId: string, communityId: string, orgUserIds: string[]): Promise<string[]>;
+  spaceOpenersAmong(orgId: string, spaceId: string, orgUserIds: string[]): Promise<string[]>;
+  spaceOpeners(orgId: string, spaceId: string): Promise<string[]>;
+  communitiesOpenedBy(orgId: string, grant: GrantTarget): Promise<string[]>;
+  communityModeratorIds(orgId: string, communityId: string): Promise<string[]>;
+  communityIdsOpenedFor(orgId: string, orgUserId: string): Promise<string[]>;
+  countActiveSpaceMembers(orgId: string, spaceId: string): Promise<number>;
+  requestJoin(orgId: string, actor: Actor, communityId: string, spaceId: string): Promise<SpaceMember>;
+  invite(orgId: string, actor: Actor, communityId: string, spaceId: string, orgUserId: string): Promise<SpaceMember>;
+  addSpaceMember(orgId: string, actor: Actor, communityId: string, spaceId: string, orgUserId: string): Promise<SpaceMember>;
+  accept(orgId: string, actor: Actor, communityId: string, spaceId: string): Promise<SpaceMember>;
+  approve(orgId: string, actor: Actor, communityId: string, spaceId: string, orgUserId: string): Promise<SpaceMember>;
+  decline(orgId: string, actor: Actor, communityId: string, spaceId: string, orgUserId: string): Promise<SpaceMember>;
+  refuse(orgId: string, actor: Actor, communityId: string, spaceId: string): Promise<SpaceMember>;
+  leave(orgId: string, actor: Actor, communityId: string, spaceId: string): Promise<SpaceMember>;
+  remove(orgId: string, actor: Actor, communityId: string, spaceId: string, orgUserId: string): Promise<SpaceMember>;
+  listSpaceMembers(orgId: string, actor: Actor, communityId: string, spaceId: string, query: {
+    page: number;
+    pageSize: number;
+  }): Promise<Page<SpaceMember>>;
+  hasDueNotices(orgId: string, now: Date): Promise<boolean>;
+  expireDue(orgId: string, now: Date): Promise<void>;
+  private requireSpaceIn;
+  private requireVisibleSpaceIn;
+  private assertHasMembers;
+  private assertRule;
+  private assertHolder;
+  private assertGrant;
+  private assertHolds;
+  private assertCanManage;
+  private accessOf;
+  private createMember;
+  private insertMember;
+  private activate;
+  private deleteMember;
+  private lockSpace;
+  private assertRoom;
 }
 //#endregion
 export { EntitlementsServiceImpl, EntitlementsServiceParams };