alepha 0.19.2 → 0.19.4

package/src/api/invitations/controllers/InvitationController.ts

@@ -0,0 +1,84 @@
+import { $inject, t } from "alepha";
+import { $secure } from "alepha/security";
+import { $action, okSchema } from "alepha/server";
+import { createInvitationSchema } from "../schemas/createInvitationSchema.ts";
+import { invitationResourceSchema } from "../schemas/invitationResourceSchema.ts";
+import { invitationWithResourceInfoSchema } from "../schemas/invitationWithResourceInfoSchema.ts";
+import { myInvitationsQuerySchema } from "../schemas/myInvitationsQuerySchema.ts";
+import { InvitationService } from "../services/InvitationService.ts";
+
+export class InvitationController {
+  protected readonly url = "/invitations";
+  protected readonly group = "invitations";
+  protected readonly invitationService = $inject(InvitationService);
+
+  /**
+   * Create a new invitation.
+   */
+  public readonly createInvitation = $action({
+    method: "POST",
+    path: this.url,
+    group: this.group,
+    use: [$secure({ permissions: ["invitation:create"] })],
+    description: "Create a new invitation",
+    schema: {
+      body: createInvitationSchema,
+      response: invitationResourceSchema,
+    },
+    handler: ({ body, user }) => this.invitationService.create(body, user),
+  });
+
+  /**
+   * List invitations for the current user.
+   */
+  public readonly getMyInvitations = $action({
+    path: `${this.url}/mine`,
+    group: this.group,
+    use: [$secure()],
+    description: "List invitations for the current user",
+    schema: {
+      query: myInvitationsQuerySchema,
+      response: t.array(invitationWithResourceInfoSchema),
+    },
+    handler: ({ query, user }) =>
+      this.invitationService.findByEmail(user.email!, query),
+  });
+
+  /**
+   * Accept an invitation.
+   */
+  public readonly acceptInvitation = $action({
+    method: "POST",
+    path: `${this.url}/:id/accept`,
+    group: this.group,
+    use: [$secure()],
+    description: "Accept an invitation",
+    schema: {
+      params: t.object({ id: t.uuid() }),
+      response: okSchema,
+    },
+    handler: async ({ params, user }) => {
+      await this.invitationService.accept(params.id, user);
+      return { ok: true };
+    },
+  });
+
+  /**
+   * Decline an invitation.
+   */
+  public readonly declineInvitation = $action({
+    method: "POST",
+    path: `${this.url}/:id/decline`,
+    group: this.group,
+    use: [$secure()],
+    description: "Decline an invitation",
+    schema: {
+      params: t.object({ id: t.uuid() }),
+      response: okSchema,
+    },
+    handler: async ({ params, user }) => {
+      await this.invitationService.decline(params.id, user);
+      return { ok: true };
+    },
+  });
+}

package/src/api/invitations/entities/invitations.ts

@@ -0,0 +1,33 @@
+import { type Static, t } from "alepha";
+import { users } from "alepha/api/users";
+import { $entity, db } from "alepha/orm";
+
+export const invitations = $entity({
+  name: "invitations",
+  schema: t.object({
+    id: db.primaryKey(t.uuid()),
+    version: db.version(),
+    createdAt: db.createdAt(),
+    updatedAt: db.updatedAt(),
+    invitedBy: db.ref(t.uuid(), () => users.cols.id, { onDelete: "cascade" }),
+    email: t.string({ format: "email" }),
+    resourceType: t.text({ minLength: 1, maxLength: 100 }),
+    resourceId: t.text({ minLength: 1, maxLength: 255 }),
+    status: t.enum(["pending", "accepted", "declined", "expired", "revoked"]),
+    roles: t.optional(t.array(t.text())),
+    metadata: t.optional(t.record(t.text(), t.any())),
+    token: t.text(),
+    expiresAt: t.datetime(),
+    resolvedAt: t.optional(t.datetime()),
+    resolvedBy: t.optional(db.ref(t.uuid(), () => users.cols.id)),
+  }),
+  indexes: [
+    { columns: ["email", "status"] },
+    { columns: ["resourceType", "resourceId", "email", "status"] },
+    { columns: ["invitedBy"] },
+    { columns: ["expiresAt"] },
+    { columns: ["token"], unique: true },
+  ],
+});
+
+export type InvitationEntity = Static<typeof invitations.schema>;

package/src/api/invitations/index.ts

@@ -0,0 +1,65 @@
+import { $module } from "alepha";
+import { AdminInvitationController } from "./controllers/AdminInvitationController.ts";
+import { InvitationController } from "./controllers/InvitationController.ts";
+import { InvitationJobs } from "./jobs/InvitationJobs.ts";
+import { InvitationService } from "./services/InvitationService.ts";
+
+export * from "./controllers/AdminInvitationController.ts";
+export * from "./controllers/InvitationController.ts";
+export * from "./entities/invitations.ts";
+export * from "./jobs/InvitationJobs.ts";
+export * from "./providers/InvitationProvider.ts";
+export * from "./schemas/createInvitationSchema.ts";
+export * from "./schemas/invitationConfigAtom.ts";
+export * from "./schemas/invitationQuerySchema.ts";
+export * from "./schemas/invitationResourceSchema.ts";
+export * from "./schemas/invitationWithResourceInfoSchema.ts";
+export * from "./schemas/myInvitationsQuerySchema.ts";
+export * from "./services/InvitationService.ts";
+
+declare module "alepha" {
+  interface Hooks {
+    "invitation:created": {
+      invitation: import("./entities/invitations.ts").InvitationEntity;
+      token: string;
+      inviter: { id: string; email?: string };
+    };
+    "invitation:accepted": {
+      invitation: import("./entities/invitations.ts").InvitationEntity;
+      acceptedBy: { id: string; email?: string };
+    };
+    "invitation:declined": {
+      invitation: import("./entities/invitations.ts").InvitationEntity;
+      declinedBy: { id: string; email?: string };
+    };
+    "invitation:expired": {
+      invitation: import("./entities/invitations.ts").InvitationEntity;
+    };
+    "invitation:revoked": {
+      invitation: import("./entities/invitations.ts").InvitationEntity;
+      revokedBy: { id: string };
+    };
+  }
+}
+
+/**
+ * Invitation management module — create, accept, decline, revoke, and expire invitations.
+ *
+ * @module alepha.api.invitations
+ */
+export const AlephaApiInvitations = $module({
+  name: "alepha.api.invitations",
+  services: [
+    InvitationService,
+    InvitationJobs,
+    InvitationController,
+    AdminInvitationController,
+  ],
+  register: (alepha) => {
+    alepha
+      .with(InvitationService)
+      .with(InvitationJobs)
+      .with(InvitationController)
+      .with(AdminInvitationController);
+  },
+});

package/src/api/invitations/jobs/InvitationJobs.ts

@@ -0,0 +1,37 @@
+import { $inject } from "alepha";
+import { $job } from "alepha/api/jobs";
+import { $logger } from "alepha/logger";
+import { InvitationService } from "../services/InvitationService.ts";
+
+export class InvitationJobs {
+  protected readonly log = $logger();
+  protected readonly invitationService = $inject(InvitationService);
+
+  /**
+   * Expire pending invitations that have passed their expiration date.
+   */
+  public readonly expireInvitations = $job({
+    cron: "0 * * * *",
+    lock: true,
+    handler: async () => {
+      const count = await this.invitationService.expirePending();
+      if (count > 0) {
+        this.log.info(`Expired ${count} invitations`);
+      }
+    },
+  });
+
+  /**
+   * Purge old resolved invitations.
+   */
+  public readonly purgeInvitations = $job({
+    cron: "0 3 * * *",
+    lock: true,
+    handler: async () => {
+      const count = await this.invitationService.purgeResolved();
+      if (count > 0) {
+        this.log.info(`Purged ${count} old invitations`);
+      }
+    },
+  });
+}

package/src/api/invitations/providers/InvitationProvider.ts

@@ -0,0 +1,45 @@
+import type { InvitationEntity } from "../entities/invitations.ts";
+
+/**
+ * Abstract provider that apps implement to customize invitation behavior
+ * per resource type.
+ */
+export abstract class InvitationProvider {
+  /**
+   * Validate that the resource exists and the inviter has permission to invite.
+   * Throw BadRequestError/ForbiddenError to reject.
+   */
+  abstract validateResource(
+    resourceType: string,
+    resourceId: string,
+    inviter: { id: string; email?: string },
+  ): Promise<void>;
+
+  /**
+   * Check if the email is already a member of the resource.
+   * Return true to reject the invitation as duplicate membership.
+   */
+  abstract isMember(
+    resourceType: string,
+    resourceId: string,
+    email: string,
+    userId?: string,
+  ): Promise<boolean>;
+
+  /**
+   * Called when an invitation is accepted.
+   * Create membership records, assign roles, etc.
+   */
+  abstract onAccept(
+    invitation: InvitationEntity,
+    acceptedBy: { id: string; email?: string },
+  ): Promise<void>;
+
+  /**
+   * Return display info for the resource (used in API responses).
+   */
+  abstract getResourceInfo(
+    resourceType: string,
+    resourceId: string,
+  ): Promise<{ name: string; description?: string; url?: string }>;
+}

package/src/api/invitations/schemas/createInvitationSchema.ts

@@ -0,0 +1,12 @@
+import type { Static } from "alepha";
+import { t } from "alepha";
+
+export const createInvitationSchema = t.object({
+  email: t.string({ format: "email" }),
+  resourceType: t.text({ minLength: 1, maxLength: 100 }),
+  resourceId: t.text({ minLength: 1, maxLength: 255 }),
+  roles: t.optional(t.array(t.text())),
+  metadata: t.optional(t.record(t.text(), t.any())),
+});
+
+export type CreateInvitation = Static<typeof createInvitationSchema>;

package/src/api/invitations/schemas/invitationConfigAtom.ts

@@ -0,0 +1,20 @@
+import { $atom, t } from "alepha";
+
+export const invitationConfigAtom = $atom({
+  name: "alepha.api.invitations.config",
+  schema: t.object({
+    expirationDays: t.integer({ minimum: 1, maximum: 90 }),
+    maxPendingPerResource: t.integer({ minimum: 1, maximum: 500 }),
+    maxPendingPerInviter: t.integer({
+      minimum: 1,
+      maximum: 1000,
+    }),
+    purgeDays: t.integer({ minimum: 0, maximum: 365 }),
+  }),
+  default: {
+    expirationDays: 7,
+    maxPendingPerResource: 50,
+    maxPendingPerInviter: 100,
+    purgeDays: 90,
+  },
+});

package/src/api/invitations/schemas/invitationQuerySchema.ts

@@ -0,0 +1,15 @@
+import type { Static } from "alepha";
+import { t } from "alepha";
+import { pageQuerySchema } from "alepha/orm";
+
+export const invitationQuerySchema = t.extend(pageQuerySchema, {
+  email: t.optional(t.text({ description: "Filter by invited email" })),
+  resourceType: t.optional(t.text({ description: "Filter by resource type" })),
+  resourceId: t.optional(t.text({ description: "Filter by resource ID" })),
+  status: t.optional(
+    t.enum(["pending", "accepted", "declined", "expired", "revoked"]),
+  ),
+  invitedBy: t.optional(t.uuid()),
+});
+
+export type InvitationQuery = Static<typeof invitationQuerySchema>;

package/src/api/invitations/schemas/invitationResourceSchema.ts

@@ -0,0 +1,6 @@
+import type { Static } from "alepha";
+import { invitations } from "../entities/invitations.ts";
+
+export const invitationResourceSchema = invitations.schema;
+
+export type InvitationResource = Static<typeof invitationResourceSchema>;

package/src/api/invitations/schemas/invitationWithResourceInfoSchema.ts

@@ -0,0 +1,22 @@
+import type { Static } from "alepha";
+import { t } from "alepha";
+
+export const invitationWithResourceInfoSchema = t.object({
+  id: t.uuid(),
+  email: t.string({ format: "email" }),
+  resourceType: t.text(),
+  resourceId: t.text(),
+  resourceName: t.text(),
+  resourceUrl: t.optional(t.text()),
+  invitedBy: t.uuid(),
+  inviterName: t.optional(t.text()),
+  inviterEmail: t.optional(t.string({ format: "email" })),
+  roles: t.optional(t.array(t.text())),
+  status: t.enum(["pending", "accepted", "declined", "expired", "revoked"]),
+  createdAt: t.datetime(),
+  expiresAt: t.datetime(),
+});
+
+export type InvitationWithResourceInfo = Static<
+  typeof invitationWithResourceInfoSchema
+>;

package/src/api/invitations/schemas/myInvitationsQuerySchema.ts

@@ -0,0 +1,10 @@
+import type { Static } from "alepha";
+import { t } from "alepha";
+
+export const myInvitationsQuerySchema = t.object({
+  status: t.optional(
+    t.enum(["pending", "accepted", "declined", "expired", "revoked"]),
+  ),
+});
+
+export type MyInvitationsQuery = Static<typeof myInvitationsQuerySchema>;