@open-kingdom/shared-backend-feature-user-management 0.0.2-14 → 0.0.2-16

package/README.md

@@ -1,11 +1,281 @@
-# feature-user-management
+# `@open-kingdom/shared-backend-feature-user-management`
 
-This library was generated with [Nx](https://nx.dev).
+A NestJS dynamic module providing REST endpoints and services for user listing/deletion and the complete invitation lifecycle (create, list, cancel, validate, accept). Integrates with `data-access-users` for persistence and `feature-email` for invitation delivery.
 
-## Building
+---
 
-Run `nx build feature-user-management` to build the library.
+## Exports
 
-## Running unit tests
+| Export                        | Kind                 | Description                                                                                                                                     |
+| ----------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `FeatureUserManagementModule` | `class`              | Dynamic NestJS module. Call `.forRoot(options)` to configure.                                                                                   |
+| `UserManagementService`       | `class`              | User listing and deletion with self-deletion guard.                                                                                             |
+| `InvitationsService`          | `class`              | Full invitation lifecycle (invite, validate, accept, list, cancel).                                                                             |
+| `UserManagementModuleOptions` | `interface`          | Type-only. Argument type for `.forRoot()`.                                                                                                      |
+| `USER_MANAGEMENT_OPTIONS`     | `string`             | DI token for module options. Value: `'USER_MANAGEMENT_OPTIONS'`.                                                                                |
+| `EMAIL_SENDER`                | `string`             | DI token aliasing `EmailService` as `EmailSender`. Value: `'EMAIL_SENDER'`.                                                                     |
+| `INVITATION_STATUS`           | `const`              | Status constants object with keys `PENDING`, `ACCEPTED`, and `EXPIRED` mapping to the string values `'pending'`, `'accepted'`, and `'expired'`. |
+| `Role`                        | `type`               | Union of `'guest'`, `'user'`, and `'admin'`.                                                                                                    |
+| `InvitationStatus`            | `type`               | Union of `'pending'`, `'accepted'`, and `'expired'`.                                                                                            |
+| `AuthenticatedRequest`        | `interface`          | Express `Request` extended with `user: { id: number; email: string }`.                                                                          |
+| `EmailSender`                 | `interface`          | Contract for the email dependency. Satisfied by `EmailService` from `feature-email`.                                                            |
+| `ValidationResult`            | `interface`          | Return type of `InvitationsService.validate()`.                                                                                                 |
+| `invitations`                 | `BetterSQLite3Table` | Drizzle table definition for the `invitations` table.                                                                                           |
+| `Invitation`                  | `type`               | Inferred from `invitations.$inferSelect`.                                                                                                       |
+| `NewInvitation`               | `type`               | Inferred from `invitations.$inferInsert`.                                                                                                       |
+| `InvitationsTableName`        | `string`             | Literal `'invitations'`.                                                                                                                        |
+| `userRoles`                   | `BetterSQLite3Table` | Drizzle table definition for the `user_roles` table.                                                                                            |
+| `UserRole`                    | `type`               | Inferred from `userRoles.$inferSelect`.                                                                                                         |
+| `NewUserRole`                 | `type`               | Inferred from `userRoles.$inferInsert`.                                                                                                         |
+| `UserRolesTableName`          | `string`             | Literal `'user_roles'`.                                                                                                                         |
+| `InviteUserDto`               | `class`              | Request DTO for `POST /invitations/invite`.                                                                                                     |
+| `AcceptInvitationDto`         | `class`              | Request DTO for `POST /invitations/accept`.                                                                                                     |
+| `InvitationResponse`          | `type`               | `Omit<Invitation, 'token'>` — the token is never returned to clients.                                                                           |
+| `UserWithoutPassword`         | `type`               | `Omit<User, 'password'>` — the password is never returned to clients.                                                                           |
 
-Run `nx test feature-user-management` to execute the unit tests via [Jest](https://jestjs.io).
+---
+
+## Type Definitions
+
+### `UserManagementModuleOptions`
+
+| Property                | Type     | Required | Default | Description                                                                                                                |
+| ----------------------- | -------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `invitationTokenSecret` | `string` | Yes      | —       | HMAC-SHA256 secret for signing invitation tokens. Compromise allows forged tokens.                                         |
+| `invitationExpiryDays`  | `number` | No       | `7`     | Number of days an invitation token remains valid after creation.                                                           |
+| `frontendBaseUrl`       | `string` | Yes      | —       | Base URL of the frontend application. Invitation links use the format `{frontendBaseUrl}/accept-invitation?token={token}`. |
+
+### `Role` and `InvitationStatus`
+
+`Role` is a string union of `'guest'`, `'user'`, and `'admin'`. `InvitationStatus` is a string union of `'pending'`, `'accepted'`, and `'expired'`. The `INVITATION_STATUS` constant object provides these string values as named properties for use without string literals.
+
+### `ValidationResult`
+
+| Property | Type                  | Description                                                          |
+| -------- | --------------------- | -------------------------------------------------------------------- |
+| `valid`  | `boolean`             | Whether the token is valid and unexpired.                            |
+| `email`  | `string \| undefined` | Present when `valid` is `true`. The invitee's email address.         |
+| `role`   | `Role \| undefined`   | Present when `valid` is `true`. The role assigned to the invitation. |
+
+### `EmailSender` Interface
+
+The `EmailSender` interface is the contract this module uses for its email dependency. It requires a `send` method that accepts an object with `to` (string), `subject` (string), and `body` (string) and returns a `Promise` resolving to an object with `success` (boolean) and an optional `error` (string). This is satisfied by `EmailService` from `feature-email`.
+
+### `invitations` Table Schema
+
+| Column        | Type      | Constraints                   | Description                                                  |
+| ------------- | --------- | ----------------------------- | ------------------------------------------------------------ |
+| `id`          | `integer` | Primary key, auto-increment   | Unique invitation identifier                                 |
+| `email`       | `text`    | Not null                      | Invitee email address                                        |
+| `token`       | `text`    | Not null, unique              | HMAC-SHA256 hex token; never returned to clients via the API |
+| `tokenExpiry` | `integer` | Not null                      | Unix timestamp (ms) of expiry                                |
+| `invitedBy`   | `integer` | Not null, FK → `users.id`     | ID of the user who sent the invitation                       |
+| `invitedAt`   | `integer` | Not null                      | Unix timestamp (ms) of creation                              |
+| `role`        | `text`    | Not null, default `'guest'`   | Role to assign on acceptance                                 |
+| `status`      | `text`    | Not null, default `'pending'` | Current invitation status                                    |
+
+### `user_roles` Table Schema
+
+| Column       | Type      | Constraints                 | Description                                |
+| ------------ | --------- | --------------------------- | ------------------------------------------ |
+| `id`         | `integer` | Primary key, auto-increment | Unique role assignment identifier          |
+| `userId`     | `integer` | Not null, FK → `users.id`   | The user this role is assigned to          |
+| `role`       | `text`    | Not null, default `'guest'` | The assigned role                          |
+| `assignedAt` | `integer` | Not null                    | Unix timestamp (ms) of assignment          |
+| `assignedBy` | `integer` | Nullable, FK → `users.id`   | The user who made the assignment; nullable |
+
+### `InviteUserDto`
+
+| Property | Type                           | Required | Description                                          |
+| -------- | ------------------------------ | -------- | ---------------------------------------------------- |
+| `email`  | `string`                       | Yes      | Email address of the invitee.                        |
+| `role`   | `'guest' \| 'user' \| 'admin'` | No       | Role to assign on acceptance. Defaults to `'guest'`. |
+
+### `AcceptInvitationDto`
+
+| Property    | Type     | Required | Description                                                    |
+| ----------- | -------- | -------- | -------------------------------------------------------------- |
+| `token`     | `string` | Yes      | Token from the invitation link.                                |
+| `password`  | `string` | Yes      | Plaintext password for the new account (minimum 8 characters). |
+| `firstName` | `string` | No       | Optional first name for the new account.                       |
+| `lastName`  | `string` | No       | Optional last name for the new account.                        |
+
+---
+
+## Module Registration
+
+```typescript
+// app.module.ts
+import { Module } from '@nestjs/common';
+import { FeatureUserManagementModule } from '@open-kingdom/shared-backend-feature-user-management';
+
+@Module({
+  imports: [
+    // DatabaseSetupModule.register(...) must be registered globally first.
+    // EmailModule.forRoot(...) must be registered globally first.
+    FeatureUserManagementModule.forRoot({
+      invitationTokenSecret: process.env['INVITATION_SECRET']!,
+      invitationExpiryDays: 7,
+      frontendBaseUrl: process.env['FRONTEND_URL']!,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+---
+
+## Configuration Options
+
+| Option                  | Type     | Default      | Description                                                                                                                               |
+| ----------------------- | -------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `invitationTokenSecret` | `string` | — (required) | HMAC-SHA256 secret for token generation. Keep secret; compromise allows forged invitation tokens.                                         |
+| `invitationExpiryDays`  | `number` | `7`          | Number of days an invitation token remains valid after creation.                                                                          |
+| `frontendBaseUrl`       | `string` | — (required) | Base URL of the frontend application. Invitation emails contain a link in the format `{frontendBaseUrl}/accept-invitation?token={token}`. |
+
+---
+
+## What `forRoot()` Registers
+
+| Component                                 | Role                                                                       |
+| ----------------------------------------- | -------------------------------------------------------------------------- |
+| `OpenKingdomDataAccessBackendUsersModule` | imported; provides `UsersService`                                          |
+| `USER_MANAGEMENT_OPTIONS`                 | value provider for `UserManagementModuleOptions`                           |
+| `EMAIL_SENDER`                            | `useExisting: EmailService` — aliases the globally provided `EmailService` |
+| `InvitationsService`                      | invitation lifecycle management                                            |
+| `UserManagementService`                   | user listing and deletion                                                  |
+| `InvitationsController`                   | registers invitation routes                                                |
+| `UsersController`                         | registers user routes                                                      |
+
+Exported from the module: `InvitationsService`, `UserManagementService`.
+
+---
+
+## REST Endpoints
+
+All authenticated endpoints require a JWT Bearer token. The `UsersController` applies `AuthGuard('jwt')` at the controller level. The `InvitationsController` applies `AuthGuard('jwt')` per-route.
+
+### Users
+
+| Method   | Path         | Auth     | Description                                                                                                                   |
+| -------- | ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `GET`    | `/users`     | Required | List all users (passwords excluded).                                                                                          |
+| `GET`    | `/users/:id` | Required | Get a single user by ID.                                                                                                      |
+| `DELETE` | `/users/:id` | Required | Delete a user. Throws `403 Forbidden` if `:id` matches the requester's own ID. Throws `404 Not Found` if user does not exist. |
+
+### Invitations
+
+| Method   | Path                           | Auth     | Description                                                                                                     |
+| -------- | ------------------------------ | -------- | --------------------------------------------------------------------------------------------------------------- |
+| `GET`    | `/invitations`                 | Required | List pending and expired invitations (accepted ones excluded). Stale invitations are auto-expired on retrieval. |
+| `POST`   | `/invitations/invite`          | Required | Create and send an invitation. Returns `InvitationResponse` (token excluded).                                   |
+| `GET`    | `/invitations/validate/:token` | None     | Validate a token. Returns `ValidationResult`.                                                                   |
+| `POST`   | `/invitations/accept`          | None     | Accept an invitation and create a user account. Returns the new user (password excluded).                       |
+| `DELETE` | `/invitations/:id`             | Required | Cancel and permanently delete an invitation record.                                                             |
+
+### Request/Response Shapes
+
+**`POST /invitations/invite`** accepts a body with `email` (string, required) and `role` (optional, defaults to `'guest'`). On success (`201`) it returns an `InvitationResponse` object containing `id`, `email`, `tokenExpiry` (Unix ms), `invitedBy` (user ID), `invitedAt` (Unix ms), `role`, and `status`. The `token` field is never included in the response.
+
+Error responses for `POST /invitations/invite`:
+
+- `400 Bad Request` — a user with that email already exists, or a non-expired pending invitation already exists for that email.
+- `502 Bad Gateway` — email delivery failed; the invitation record is rolled back.
+
+**`GET /invitations/validate/:token`** returns `{ valid: true, email: "...", role: "..." }` for a valid token, or `{ valid: false }` for an unknown, expired, or already-accepted token.
+
+**`POST /invitations/accept`** accepts a body with `token` (string, required), `password` (string, required, min 8 chars), and optional `firstName` and `lastName`. On success (`201`) it returns the newly created user object with `id`, `firstName`, `lastName`, and `email` — the password is never included.
+
+---
+
+## UserManagementService API
+
+| Method     | Parameters                        | Returns                          | Description                                                                                                             |
+| ---------- | --------------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `findAll`  | —                                 | `Promise<UserWithoutPassword[]>` | Returns all users with password excluded.                                                                               |
+| `findById` | `id: number`                      | `Promise<UserWithoutPassword>`   | Returns a user by ID. Throws `NotFoundException` if not found.                                                          |
+| `delete`   | `id: number, requesterId: number` | `Promise<void>`                  | Deletes a user. Throws `ForbiddenException` if `id === requesterId`. Throws `NotFoundException` if user does not exist. |
+
+---
+
+## InvitationsService API
+
+| Method     | Parameters                                                               | Returns                         | Description                                                                                                                                                                                                                                                      |
+| ---------- | ------------------------------------------------------------------------ | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `invite`   | `email: string, role: Role, invitedById: number`                         | `Promise<InvitationResponse>`   | Creates an invitation, sends an email, and returns `InvitationResponse` (no token). Throws `BadRequestException` if a user or pending invitation already exists for the email. Throws `BadGatewayException` if email delivery fails (invitation is rolled back). |
+| `validate` | `token: string`                                                          | `Promise<ValidationResult>`     | Validates a token. Returns `{ valid: false }` for unknown, expired, or already-accepted tokens.                                                                                                                                                                  |
+| `accept`   | `token: string, password: string, firstName?: string, lastName?: string` | `Promise<User>`                 | Validates the token, creates a user via `UsersService.create()`, and marks the invitation as accepted. Throws `BadRequestException` for invalid or expired tokens.                                                                                               |
+| `findAll`  | —                                                                        | `Promise<InvitationResponse[]>` | Lists all non-accepted invitations. Stale pending invitations are auto-expired before returning.                                                                                                                                                                 |
+| `cancel`   | `id: number`                                                             | `Promise<void>`                 | Permanently deletes an invitation record. Throws `NotFoundException` if not found.                                                                                                                                                                               |
+
+### Token Generation
+
+Invitation tokens are HMAC-SHA256 hex strings. The signed payload combines the invitee's email, the expiry timestamp, and 16 random bytes. Tokens are stored in the database and delivered only via email — they are never returned by any API response.
+
+---
+
+## Drizzle Schema Inclusion
+
+The `invitations` and `userRoles` table definitions must be included in the schema passed to `DatabaseSetupModule.register()`:
+
+```typescript
+import { invitations, userRoles } from '@open-kingdom/shared-backend-feature-user-management';
+import { users } from '@open-kingdom/shared-backend-data-access-users';
+
+DatabaseSetupModule.register({
+  schema: { users, invitations, userRoles },
+  filename: 'app.db',
+});
+```
+
+---
+
+## Full Application Registration Pattern
+
+```typescript
+// app.module.ts
+import { Module } from '@nestjs/common';
+import { APP_GUARD } from '@nestjs/core';
+import { DatabaseSetupModule } from '@open-kingdom/shared-backend-data-access-database-setup';
+import { OpenKingdomFeatureBackendAuthModule, JwtAuthGuard } from '@open-kingdom/shared-backend-feature-authentication';
+import { EmailModule } from '@open-kingdom/shared-backend-feature-email';
+import { FeatureUserManagementModule } from '@open-kingdom/shared-backend-feature-user-management';
+import { users } from '@open-kingdom/shared-backend-data-access-users';
+import { invitations, userRoles } from '@open-kingdom/shared-backend-feature-user-management';
+
+@Module({
+  imports: [
+    DatabaseSetupModule.register({
+      schema: { users, invitations, userRoles },
+      filename: process.env['DB_FILENAME'] ?? 'app.db',
+      pragmas: { journal_mode: 'WAL', foreign_keys: 'ON' },
+    }),
+    OpenKingdomFeatureBackendAuthModule.forRoot({
+      jwtSecret: process.env['JWT_SECRET']!,
+    }),
+    EmailModule.forRoot({
+      provider: 'gmail',
+      config: {
+        clientEmail: process.env['GMAIL_CLIENT_EMAIL']!,
+        privateKey: process.env['GMAIL_PRIVATE_KEY']!,
+        impersonateEmail: process.env['GMAIL_IMPERSONATE_EMAIL']!,
+      },
+    }),
+    FeatureUserManagementModule.forRoot({
+      invitationTokenSecret: process.env['INVITATION_SECRET']!,
+      frontendBaseUrl: process.env['FRONTEND_URL']!,
+      invitationExpiryDays: 7,
+    }),
+  ],
+  providers: [{ provide: APP_GUARD, useClass: JwtAuthGuard }],
+})
+export class AppModule {}
+```
+
+---
+
+## Testing
+
+```bash
+nx test @open-kingdom/shared-backend-feature-user-management
+```

package/dist/lib/controllers/invitations.controller.d.ts

@@ -4,6 +4,7 @@ import type { AuthenticatedRequest } from '../types';
 export declare class InvitationsController {
     private readonly invitationsService;
     constructor(invitationsService: InvitationsService);
+    findAll(): Promise<import("../services").InvitationResponse[]>;
     invite(dto: InviteUserDto, req: AuthenticatedRequest): Promise<import("../services").InvitationResponse>;
     validate(token: string): Promise<import("../types").ValidationResult>;
     accept(dto: AcceptInvitationDto): Promise<{
@@ -12,5 +13,8 @@ export declare class InvitationsController {
         firstName: string | null;
         lastName: string | null;
     }>;
+    cancel(id: number): Promise<{
+        message: string;
+    }>;
 }
 //# sourceMappingURL=invitations.controller.d.ts.map

package/dist/lib/controllers/invitations.controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"invitations.controller.d.ts","sourceRoot":"","sources":["../../../src/lib/controllers/invitations.controller.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AAC5D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAErD,qBAEa,qBAAqB;IACpB,OAAO,CAAC,QAAQ,CAAC,kBAAkB;gBAAlB,kBAAkB,EAAE,kBAAkB;IAoB7D,MAAM,CACF,GAAG,EAAE,aAAa,EACf,GAAG,EAAE,oBAAoB;IA8BhC,QAAQ,CAAiB,KAAK,EAAE,MAAM;IAiBtC,MAAM,CAAS,GAAG,EAAE,mBAAmB;;;;;;CAW9C"}
+{"version":3,"file":"invitations.controller.d.ts","sourceRoot":"","sources":["../../../src/lib/controllers/invitations.controller.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AAC5D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAErD,qBAEa,qBAAqB;IACpB,OAAO,CAAC,QAAQ,CAAC,kBAAkB;gBAAlB,kBAAkB,EAAE,kBAAkB;IAiB7D,OAAO;IA0BP,MAAM,CACF,GAAG,EAAE,aAAa,EACf,GAAG,EAAE,oBAAoB;IA8BhC,QAAQ,CAAiB,KAAK,EAAE,MAAM;IAiBtC,MAAM,CAAS,GAAG,EAAE,mBAAmB;;;;;;IA8BvC,MAAM,CAA4B,EAAE,EAAE,MAAM;;;CAInD"}

package/dist/lib/controllers/invitations.controller.js

@@ -11,6 +11,9 @@ let InvitationsController = class InvitationsController {
     constructor(invitationsService) {
         this.invitationsService = invitationsService;
     }
+    async findAll() {
+        return this.invitationsService.findAll();
+    }
     async invite(dto, req) {
         return this.invitationsService.invite(dto.email, dto.role ?? 'guest', req.user.id);
     }
@@ -22,8 +25,31 @@ let InvitationsController = class InvitationsController {
         const { password: _password, ...userWithoutPassword } = user;
         return userWithoutPassword;
     }
+    async cancel(id) {
+        await this.invitationsService.cancel(id);
+        return { message: 'Invitation cancelled successfully' };
+    }
 };
 exports.InvitationsController = InvitationsController;
+tslib_1.__decorate([
+    (0, common_1.Get)(),
+    (0, swagger_1.ApiBearerAuth)('JWT-auth'),
+    (0, common_1.UseGuards)((0, passport_1.AuthGuard)('jwt')),
+    (0, swagger_1.ApiOperation)({
+        summary: 'List pending and expired invitations',
+        description: 'Returns pending and expired invitations. Accepted invitations are excluded. Expired invitations are auto-updated.',
+    }),
+    (0, swagger_1.ApiResponse)({
+        status: 200,
+        description: 'List of invitations',
+    }),
+    (0, swagger_1.ApiUnauthorizedResponse)({
+        description: 'Unauthorized - Invalid or missing JWT token',
+    }),
+    tslib_1.__metadata("design:type", Function),
+    tslib_1.__metadata("design:paramtypes", []),
+    tslib_1.__metadata("design:returntype", Promise)
+], InvitationsController.prototype, "findAll", null);
 tslib_1.__decorate([
     (0, common_1.Post)('invite'),
     (0, swagger_1.ApiBearerAuth)('JWT-auth'),
@@ -40,6 +66,10 @@ tslib_1.__decorate([
     (0, swagger_1.ApiBadRequestResponse)({
         description: 'User already exists or pending invitation exists',
     }),
+    (0, swagger_1.ApiResponse)({
+        status: 502,
+        description: 'Email delivery failed — invitation rolled back',
+    }),
     (0, swagger_1.ApiUnauthorizedResponse)({
         description: 'Unauthorized - Invalid or missing JWT token',
     }),
@@ -95,6 +125,29 @@ tslib_1.__decorate([
     tslib_1.__metadata("design:paramtypes", [dto_1.AcceptInvitationDto]),
     tslib_1.__metadata("design:returntype", Promise)
 ], InvitationsController.prototype, "accept", null);
+tslib_1.__decorate([
+    (0, common_1.Delete)(':id'),
+    (0, swagger_1.ApiBearerAuth)('JWT-auth'),
+    (0, common_1.UseGuards)((0, passport_1.AuthGuard)('jwt')),
+    (0, swagger_1.ApiOperation)({
+        summary: 'Cancel an invitation',
+        description: 'Cancel and delete an invitation regardless of its current status.',
+    }),
+    (0, swagger_1.ApiResponse)({
+        status: 200,
+        description: 'Invitation cancelled successfully',
+    }),
+    (0, swagger_1.ApiNotFoundResponse)({
+        description: 'Invitation not found',
+    }),
+    (0, swagger_1.ApiUnauthorizedResponse)({
+        description: 'Unauthorized - Invalid or missing JWT token',
+    }),
+    tslib_1.__param(0, (0, common_1.Param)('id', common_1.ParseIntPipe)),
+    tslib_1.__metadata("design:type", Function),
+    tslib_1.__metadata("design:paramtypes", [Number]),
+    tslib_1.__metadata("design:returntype", Promise)
+], InvitationsController.prototype, "cancel", null);
 exports.InvitationsController = InvitationsController = tslib_1.__decorate([
     (0, swagger_1.ApiTags)('Invitations'),
     (0, common_1.Controller)('invitations'),

package/dist/lib/services/invitations.service.d.ts

@@ -17,8 +17,12 @@ export declare class InvitationsService {
     invite(email: string, role: Role, invitedById: number): Promise<InvitationResponse>;
     validate(token: string): Promise<ValidationResult>;
     accept(token: string, password: string, firstName?: string, lastName?: string): Promise<User>;
+    findAll(): Promise<InvitationResponse[]>;
+    cancel(id: number): Promise<void>;
     private ensureUserDoesNotExist;
     private ensureNoPendingInvitation;
+    private findInvitationOrFail;
+    private expireStaleInvitations;
     private isExpired;
     private findByToken;
     private markAsExpired;

package/dist/lib/services/invitations.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"invitations.service.d.ts","sourceRoot":"","sources":["../../../src/lib/services/invitations.service.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAKnE,OAAO,EACL,YAAY,EACZ,IAAI,EACJ,KAAK,EACL,cAAc,EACf,MAAM,gDAAgD,CAAC;AACxD,OAAO,EACL,WAAW,EACX,UAAU,EACV,oBAAoB,EACrB,MAAM,+BAA+B,CAAC;AAUvC,OAAO,KAAK,EACV,2BAA2B,EAC3B,WAAW,EACX,IAAI,EACJ,gBAAgB,EACjB,MAAM,UAAU,CAAC;AAElB,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;AAE3D,KAAK,MAAM,GAAG;IACZ,CAAC,cAAc,CAAC,EAAE,OAAO,KAAK,CAAC;IAC/B,CAAC,oBAAoB,CAAC,EAAE,OAAO,WAAW,CAAC;CAC5C,CAAC;AAKF,qBACa,kBAAkB;IAIX,OAAO,CAAC,QAAQ,CAAC,EAAE;IAEnC,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,YAAY;IACK,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAPjE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuC;gBAG3B,EAAE,EAAE,qBAAqB,CAAC,MAAM,CAAC,EAEjD,OAAO,EAAE,2BAA2B,EACpC,YAAY,EAAE,YAAY,EACQ,WAAW,CAAC,EAAE,WAAW,YAAA;IAGxE,MAAM,CACV,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,IAAI,EACV,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,kBAAkB,CAAC;IAqCxB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAmBlD,MAAM,CACV,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC;YAmBF,sBAAsB;YAQtB,yBAAyB;IAevC,OAAO,CAAC,SAAS;YAIH,WAAW;YAMX,aAAa;YAOb,cAAc;IAO5B,OAAO,KAAK,UAAU,GAErB;IAED,OAAO,CAAC,aAAa;YAUP,mBAAmB;CAyBlC"}
+{"version":3,"file":"invitations.service.d.ts","sourceRoot":"","sources":["../../../src/lib/services/invitations.service.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAKnE,OAAO,EACL,YAAY,EACZ,IAAI,EACJ,KAAK,EACL,cAAc,EACf,MAAM,gDAAgD,CAAC;AACxD,OAAO,EACL,WAAW,EACX,UAAU,EACV,oBAAoB,EACrB,MAAM,+BAA+B,CAAC;AAUvC,OAAO,KAAK,EACV,2BAA2B,EAC3B,WAAW,EACX,IAAI,EACJ,gBAAgB,EACjB,MAAM,UAAU,CAAC;AAElB,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;AAE3D,KAAK,MAAM,GAAG;IACZ,CAAC,cAAc,CAAC,EAAE,OAAO,KAAK,CAAC;IAC/B,CAAC,oBAAoB,CAAC,EAAE,OAAO,WAAW,CAAC;CAC5C,CAAC;AAKF,qBACa,kBAAkB;IAIX,OAAO,CAAC,QAAQ,CAAC,EAAE;IAEnC,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,YAAY;IACK,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAPjE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuC;gBAG3B,EAAE,EAAE,qBAAqB,CAAC,MAAM,CAAC,EAEjD,OAAO,EAAE,2BAA2B,EACpC,YAAY,EAAE,YAAY,EACQ,WAAW,CAAC,EAAE,WAAW,YAAA;IAGxE,MAAM,CACV,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,IAAI,EACV,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,kBAAkB,CAAC;IAuCxB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAmBlD,MAAM,CACV,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC;IAmBV,OAAO,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC;IASxC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAKzB,sBAAsB;YAQtB,yBAAyB;YAezB,oBAAoB;YAYpB,sBAAsB;IAYpC,OAAO,CAAC,SAAS;YAIH,WAAW;YAMX,aAAa;YAOb,cAAc;IAO5B,OAAO,KAAK,UAAU,GAErB;IAED,OAAO,CAAC,aAAa;YAUP,mBAAmB;CA8BlC"}

package/dist/lib/services/invitations.service.js

@@ -40,9 +40,9 @@ let InvitationsService = InvitationsService_1 = class InvitationsService {
             await this.sendInvitationEmail(email, token);
         }
         catch (error) {
-            this.logger.error(`Failed to send invitation email to ${email}, rolling back invitation`, error);
+            this.logger.error(`Failed to send invitation email to ${email}: ${error instanceof Error ? error.message : 'Unknown error'}`, error instanceof Error ? error.stack : undefined);
             await this.db.delete(invitations_schema_1.invitations).where((0, drizzle_orm_1.eq)(invitations_schema_1.invitations.token, token));
-            throw new common_1.BadRequestException('Failed to send invitation email. Please try again.');
+            throw new common_1.BadGatewayException('Invitation could not be sent - email delivery failed');
         }
         // Never return token - it's only sent via email
         const { token: _token, ...invitationWithoutToken } = invitation;
@@ -77,6 +77,17 @@ let InvitationsService = InvitationsService_1 = class InvitationsService {
         await this.markAsAccepted(token);
         return user;
     }
+    async findAll() {
+        const records = await this.db.query.invitations.findMany();
+        await this.expireStaleInvitations(records);
+        return records
+            .filter((r) => r.status !== types_1.INVITATION_STATUS.ACCEPTED)
+            .map(({ token: _, ...rest }) => rest);
+    }
+    async cancel(id) {
+        await this.findInvitationOrFail(id);
+        await this.db.delete(invitations_schema_1.invitations).where((0, drizzle_orm_1.eq)(invitations_schema_1.invitations.id, id));
+    }
     async ensureUserDoesNotExist(email) {
         const existingUser = await this.usersService.findOne(email);
         if (existingUser) {
@@ -92,6 +103,24 @@ let InvitationsService = InvitationsService_1 = class InvitationsService {
             throw new common_1.BadRequestException('A pending invitation already exists for this email');
         }
     }
+    async findInvitationOrFail(id) {
+        const invitation = await this.db.query.invitations.findFirst({
+            where: (0, drizzle_orm_1.eq)(invitations_schema_1.invitations.id, id),
+        });
+        if (!invitation) {
+            throw new common_1.NotFoundException('Invitation not found');
+        }
+        return invitation;
+    }
+    async expireStaleInvitations(records) {
+        for (const record of records) {
+            if (record.status === types_1.INVITATION_STATUS.PENDING &&
+                this.isExpired(record.tokenExpiry)) {
+                await this.markAsExpired(record.id);
+                record.status = types_1.INVITATION_STATUS.EXPIRED;
+            }
+        }
+    }
     isExpired(tokenExpiry) {
         return tokenExpiry < Date.now();
     }
@@ -130,7 +159,7 @@ let InvitationsService = InvitationsService_1 = class InvitationsService {
             this.logger.warn('EmailSender not configured - skipping invitation email');
             return;
         }
-        await this.emailSender.send({
+        const result = await this.emailSender.send({
             to: email,
             subject: templates_1.INVITATION_EMAIL_SUBJECT,
             body: (0, templates_1.buildInvitationEmailBody)({
@@ -138,6 +167,9 @@ let InvitationsService = InvitationsService_1 = class InvitationsService {
                 expiryDays: this.expiryDays,
             }),
         });
+        if (!result.success) {
+            throw new Error(result.error || 'Email delivery failed');
+        }
         this.logger.log(`Invitation email sent to ${email}`);
     }
 };

package/dist/lib/types.d.ts

@@ -31,6 +31,7 @@ export interface EmailSender {
         body: string;
     }): Promise<{
         success: boolean;
+        error?: string;
     }>;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/lib/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lib/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAGvC,eAAO,MAAM,uBAAuB,4BAA4B,CAAC;AACjE,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAG3C,MAAM,WAAW,2BAA2B;IAC1C,qBAAqB,EAAE,MAAM,CAAC;IAC9B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,eAAe,EAAE,MAAM,CAAC;CACzB;AAGD,MAAM,WAAW,oBAAqB,SAAQ,OAAO;IACnD,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CACrC;AAGD,MAAM,MAAM,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AAE9C,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;AAElE,eAAO,MAAM,iBAAiB;;;;CAIpB,CAAC;AAEX,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,IAAI,CAAC;CACb;AAGD,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,OAAO,EAAE;QACZ,EAAE,EAAE,MAAM,CAAC;QACX,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;KACd,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACnC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lib/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAGvC,eAAO,MAAM,uBAAuB,4BAA4B,CAAC;AACjE,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAG3C,MAAM,WAAW,2BAA2B;IAC1C,qBAAqB,EAAE,MAAM,CAAC;IAC9B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,eAAe,EAAE,MAAM,CAAC;CACzB;AAGD,MAAM,WAAW,oBAAqB,SAAQ,OAAO;IACnD,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CACrC;AAGD,MAAM,MAAM,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AAE9C,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;AAElE,eAAO,MAAM,iBAAiB;;;;CAIpB,CAAC;AAEX,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,IAAI,CAAC;CACb;AAGD,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,OAAO,EAAE;QACZ,EAAE,EAAE,MAAM,CAAC;QACX,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;KACd,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACnD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-kingdom/shared-backend-feature-user-management",
-  "version": "0.0.2-14",
+  "version": "0.0.2-16",
   "publishConfig": {
     "access": "public"
   },
@@ -17,6 +17,7 @@
     }
   },
   "files": [
+    "README.md",
     "dist",
     "!**/*.tsbuildinfo"
   ],
@@ -32,9 +33,9 @@
     "@nestjs/common": "^11.0.0",
     "@nestjs/passport": "^11.0.5",
     "@nestjs/swagger": "^11.2.3",
-    "@open-kingdom/shared-backend-data-access-users": "0.0.2-14",
-    "@open-kingdom/shared-backend-feature-email": "0.0.2-14",
-    "@open-kingdom/shared-poly-util-constants": "0.0.2-14",
+    "@open-kingdom/shared-backend-data-access-users": "0.0.2-16",
+    "@open-kingdom/shared-backend-feature-email": "0.0.2-16",
+    "@open-kingdom/shared-poly-util-constants": "0.0.2-16",
     "drizzle-orm": "^0.44.5",
     "express": "5.2.1"
   }