@ysk-kit/cli 1.0.0

package/templates/capabilities/team/apps/api/src/modules/organizations/application/organization-service.ts

@@ -0,0 +1,272 @@
+import { hashPassword, hashRefresh, newRefreshToken } from '@ysk-kit/auth';
+import type {
+  AcceptInviteCommand,
+  CreateOrganizationCommand,
+  InviteMemberCommand,
+  MembershipDto,
+  OrganizationDto,
+  OrgInviteDto,
+  UpdateOrganizationCommand,
+} from '@ysk-kit/contracts';
+import { orgRoleCan } from '@ysk-kit/contracts';
+import { AppError } from '@ysk-kit/domain-kernel';
+import type { IJobQueue } from '@ysk-kit/jobs';
+import type { IAuditLogger } from '../../audit-log/domain/audit-logger';
+import type { IUserRepository } from '../../identity/domain/user-repository';
+import type { IOrganizationRepository } from '../domain/organization-repository';
+
+const INVITE_TTL_MS = 1000 * 60 * 60 * 24 * 7;
+
+const toOrgDto = (row: { id: string; name: string; createdAt: Date }): OrganizationDto => ({
+  id: row.id,
+  name: row.name,
+  createdAt: row.createdAt.toISOString(),
+});
+
+const toInviteDto = (row: {
+  id: string;
+  organizationId: string;
+  email: string;
+  role: OrgInviteDto['role'];
+  createdAt: Date;
+  expiresAt: Date;
+}): OrgInviteDto => ({
+  id: row.id,
+  organizationId: row.organizationId,
+  email: row.email,
+  role: row.role,
+  createdAt: row.createdAt.toISOString(),
+  expiresAt: row.expiresAt.toISOString(),
+});
+
+const displayNameFromEmail = (email: string): string => {
+  const local = email.split('@')[0] ?? 'user';
+  return local.slice(0, 80) || 'user';
+};
+
+export type OrganizationServiceDeps = {
+  orgs: IOrganizationRepository;
+  users: IUserRepository;
+  jobs: IJobQueue;
+  audit: IAuditLogger;
+  webPublicUrl: string;
+  now?: () => Date;
+};
+
+export const createOrganizationService = (deps: OrganizationServiceDeps) => {
+  const now = () => deps.now?.() ?? new Date();
+
+  const requireOrg = async (organizationId: string) => {
+    const org = await deps.orgs.findById(organizationId);
+    if (!org) throw new AppError('NOT_FOUND');
+    return org;
+  };
+
+  const requireMember = async (organizationId: string, userId: string) => {
+    await requireOrg(organizationId);
+    const membership = await deps.orgs.findMembership(organizationId, userId);
+    if (!membership) throw new AppError('FORBIDDEN');
+    return membership;
+  };
+
+  const hydrateMember = async (row: {
+    id: string;
+    organizationId: string;
+    userId: string;
+    role: MembershipDto['role'];
+    createdAt: Date;
+  }): Promise<MembershipDto> => {
+    const user = await deps.users.findById(row.userId);
+    return {
+      id: row.id,
+      organizationId: row.organizationId,
+      userId: row.userId,
+      email: user?.email ?? null,
+      displayName: user?.displayName ?? 'user',
+      role: row.role,
+      createdAt: row.createdAt.toISOString(),
+    };
+  };
+
+  return {
+    create: async (actorId: string, body: CreateOrganizationCommand): Promise<OrganizationDto> => {
+      const org = await deps.orgs.createWithOwner({ name: body.name, ownerUserId: actorId });
+      await deps.audit.record({
+        actorId,
+        action: 'org.create',
+        resourceType: 'organization',
+        resourceId: org.id,
+      });
+      return toOrgDto(org);
+    },
+
+    listMine: (actorId: string) =>
+      deps.orgs.listForUser(actorId).then((rows) => rows.map(toOrgDto)),
+
+    get: async (actorId: string, organizationId: string): Promise<OrganizationDto> => {
+      const org = await requireOrg(organizationId);
+      await requireMember(organizationId, actorId);
+      return toOrgDto(org);
+    },
+
+    update: async (
+      actorId: string,
+      organizationId: string,
+      body: UpdateOrganizationCommand,
+    ): Promise<OrganizationDto> => {
+      const membership = await requireMember(organizationId, actorId);
+      if (!orgRoleCan(membership.role, 'org.update')) throw new AppError('FORBIDDEN');
+      const org = await deps.orgs.updateName(organizationId, body.name);
+      return toOrgDto(org);
+    },
+
+    members: async (actorId: string, organizationId: string): Promise<MembershipDto[]> => {
+      await requireMember(organizationId, actorId);
+      const rows = await deps.orgs.listMembers(organizationId);
+      return Promise.all(rows.map(hydrateMember));
+    },
+
+    invite: async (
+      actorId: string,
+      organizationId: string,
+      body: InviteMemberCommand,
+    ): Promise<OrgInviteDto> => {
+      const membership = await requireMember(organizationId, actorId);
+      if (!orgRoleCan(membership.role, 'org.invite')) throw new AppError('FORBIDDEN');
+      const org = await requireOrg(organizationId);
+      const email = body.email.trim().toLowerCase();
+      const existingUser = await deps.users.findByEmail(email);
+      if (existingUser) {
+        if (existingUser.status === 'SUSPENDED' || existingUser.status === 'DELETED') {
+          throw new AppError('CONFLICT', 'Account cannot be invited');
+        }
+        const already = await deps.orgs.findMembership(organizationId, existingUser.id);
+        if (already) throw new AppError('CONFLICT', 'Already a member');
+      }
+      const token = newRefreshToken();
+      const invite = await deps.orgs.upsertPendingInvite({
+        organizationId,
+        email,
+        role: body.role,
+        tokenHash: hashRefresh(token),
+        expiresAt: new Date(now().getTime() + INVITE_TTL_MS),
+        invitedById: actorId,
+      });
+      let user = existingUser;
+      if (!user) {
+        user = await deps.users.create({
+          email,
+          displayName: displayNameFromEmail(email),
+          role: 'USER',
+          status: 'INVITED',
+        });
+      }
+      await deps.jobs.enqueue('email.send', {
+        to: email,
+        template: 'org.invite',
+        locale: 'zh-HK',
+        vars: {
+          organizationName: org.name,
+          inviteUrl: `${deps.webPublicUrl}/invite?token=${token}`,
+        },
+      });
+      await deps.jobs.enqueue('notification.create', {
+        userId: user.id,
+        type: 'org.invited',
+        title: '組織邀請',
+        body: `你被邀請加入 ${org.name}。`,
+      });
+      await deps.audit.record({
+        actorId,
+        action: 'org.invite',
+        resourceType: 'organization',
+        resourceId: organizationId,
+      });
+      return toInviteDto(invite);
+    },
+
+    invites: async (actorId: string, organizationId: string): Promise<OrgInviteDto[]> => {
+      const membership = await requireMember(organizationId, actorId);
+      if (!orgRoleCan(membership.role, 'org.invite')) throw new AppError('FORBIDDEN');
+      const rows = await deps.orgs.listPendingInvites(organizationId);
+      return rows.map(toInviteDto);
+    },
+
+    revokeInvite: async (actorId: string, organizationId: string, inviteId: string) => {
+      const membership = await requireMember(organizationId, actorId);
+      if (!orgRoleCan(membership.role, 'org.invite')) throw new AppError('FORBIDDEN');
+      const ok = await deps.orgs.deleteInvite(inviteId, organizationId);
+      if (!ok) throw new AppError('NOT_FOUND');
+      return { removed: true as const };
+    },
+
+    removeMember: async (actorId: string, organizationId: string, userId: string) => {
+      const membership = await requireMember(organizationId, actorId);
+      if (!orgRoleCan(membership.role, 'org.member.remove')) throw new AppError('FORBIDDEN');
+      const target = await deps.orgs.findMembership(organizationId, userId);
+      if (!target) throw new AppError('NOT_FOUND');
+      if (target.role === 'OWNER' && membership.role !== 'OWNER') {
+        throw new AppError('FORBIDDEN');
+      }
+      if (target.role === 'OWNER' && (await deps.orgs.countOwners(organizationId)) <= 1) {
+        throw new AppError('FORBIDDEN', 'Cannot remove the last owner');
+      }
+      await deps.orgs.removeMembership(organizationId, userId);
+      await deps.audit.record({
+        actorId,
+        action: 'org.member.remove',
+        resourceType: 'user',
+        resourceId: userId,
+      });
+      return { removed: true as const };
+    },
+
+    leave: async (actorId: string, organizationId: string) => {
+      const membership = await requireMember(organizationId, actorId);
+      if (membership.role === 'OWNER' && (await deps.orgs.countOwners(organizationId)) <= 1) {
+        throw new AppError('FORBIDDEN', 'Cannot leave as the last owner');
+      }
+      await deps.orgs.removeMembership(organizationId, actorId);
+      return { left: true as const };
+    },
+
+    acceptInvite: async (body: AcceptInviteCommand) => {
+      const invite = await deps.orgs.findInviteByTokenHash(hashRefresh(body.token));
+      if (!invite || invite.acceptedAt || invite.expiresAt < now()) {
+        throw new AppError('UNAUTHENTICATED', 'Invalid or expired token');
+      }
+      let user = await deps.users.findByEmail(invite.email);
+      if (user && (user.status === 'SUSPENDED' || user.status === 'DELETED')) {
+        throw new AppError('CONFLICT', 'Account cannot join');
+      }
+      if (!user) {
+        if (!body.password) throw new AppError('VALIDATION_FAILED', 'Password is required');
+        user = await deps.users.create({
+          email: invite.email,
+          displayName: body.displayName ?? displayNameFromEmail(invite.email),
+          role: 'USER',
+          status: 'ACTIVE',
+          passwordHash: await hashPassword(body.password),
+        });
+      } else if (user.status === 'INVITED') {
+        if (!body.password) throw new AppError('VALIDATION_FAILED', 'Password is required');
+        user.passwordHash = await hashPassword(body.password);
+        user.status = 'ACTIVE';
+        if (body.displayName) user.displayName = body.displayName;
+        await deps.users.save(user);
+      }
+      const already = await deps.orgs.findMembership(invite.organizationId, user.id);
+      if (!already) {
+        await deps.orgs.addMembership({
+          organizationId: invite.organizationId,
+          userId: user.id,
+          role: invite.role,
+        });
+      }
+      await deps.orgs.markInviteAccepted(invite.id, now());
+      return { accepted: true as const };
+    },
+  };
+};
+
+export type OrganizationService = ReturnType<typeof createOrganizationService>;

package/templates/capabilities/team/apps/api/src/modules/organizations/domain/organization-repository.ts

@@ -0,0 +1,58 @@
+import type { InviteOrgRole, OrgRole } from '@ysk-kit/contracts';
+
+export type OrganizationRecord = {
+  id: string;
+  name: string;
+  stripeCustomerId: string | null;
+  createdAt: Date;
+};
+
+export type MembershipRecord = {
+  id: string;
+  organizationId: string;
+  userId: string;
+  role: OrgRole;
+  createdAt: Date;
+};
+
+export type OrgInviteRecord = {
+  id: string;
+  organizationId: string;
+  email: string;
+  role: InviteOrgRole;
+  tokenHash: string;
+  expiresAt: Date;
+  acceptedAt: Date | null;
+  invitedById: string;
+  createdAt: Date;
+};
+
+export interface IOrganizationRepository {
+  createWithOwner(input: { name: string; ownerUserId: string }): Promise<OrganizationRecord>;
+  findById(id: string): Promise<OrganizationRecord | null>;
+  listForUser(userId: string): Promise<OrganizationRecord[]>;
+  updateName(id: string, name: string): Promise<OrganizationRecord>;
+  setStripeCustomerId(id: string, customerId: string): Promise<OrganizationRecord>;
+  findMembership(organizationId: string, userId: string): Promise<MembershipRecord | null>;
+  listMembers(organizationId: string): Promise<MembershipRecord[]>;
+  addMembership(input: {
+    organizationId: string;
+    userId: string;
+    role: OrgRole;
+  }): Promise<MembershipRecord>;
+  removeMembership(organizationId: string, userId: string): Promise<boolean>;
+  countOwners(organizationId: string): Promise<number>;
+  upsertPendingInvite(input: {
+    organizationId: string;
+    email: string;
+    role: InviteOrgRole;
+    tokenHash: string;
+    expiresAt: Date;
+    invitedById: string;
+  }): Promise<OrgInviteRecord>;
+  findPendingInviteByEmail(organizationId: string, email: string): Promise<OrgInviteRecord | null>;
+  findInviteByTokenHash(tokenHash: string): Promise<OrgInviteRecord | null>;
+  listPendingInvites(organizationId: string): Promise<OrgInviteRecord[]>;
+  markInviteAccepted(id: string, at: Date): Promise<void>;
+  deleteInvite(id: string, organizationId: string): Promise<boolean>;
+}

package/templates/capabilities/team/apps/api/src/modules/organizations/infra/memory-organization-repository.ts

@@ -0,0 +1,141 @@
+import type {
+  IOrganizationRepository,
+  MembershipRecord,
+  OrganizationRecord,
+  OrgInviteRecord,
+} from '../domain/organization-repository';
+
+export const createMemoryOrganizationRepository = (): IOrganizationRepository => {
+  const orgs: OrganizationRecord[] = [];
+  const members: MembershipRecord[] = [];
+  const invites: OrgInviteRecord[] = [];
+
+  return {
+    async createWithOwner(input) {
+      const org: OrganizationRecord = {
+        id: crypto.randomUUID(),
+        name: input.name,
+        stripeCustomerId: null,
+        createdAt: new Date(),
+      };
+      orgs.unshift(org);
+      members.push({
+        id: crypto.randomUUID(),
+        organizationId: org.id,
+        userId: input.ownerUserId,
+        role: 'OWNER',
+        createdAt: new Date(),
+      });
+      return org;
+    },
+    async findById(id) {
+      return orgs.find((row) => row.id === id) ?? null;
+    },
+    async listForUser(userId) {
+      const orgIds = new Set(
+        members.filter((row) => row.userId === userId).map((row) => row.organizationId),
+      );
+      return orgs.filter((org) => orgIds.has(org.id));
+    },
+    async updateName(id, name) {
+      const org = orgs.find((row) => row.id === id);
+      if (!org) throw new Error(`organization ${id} missing`);
+      org.name = name;
+      return org;
+    },
+    async setStripeCustomerId(id, customerId) {
+      const org = orgs.find((row) => row.id === id);
+      if (!org) throw new Error(`organization ${id} missing`);
+      org.stripeCustomerId = customerId;
+      return org;
+    },
+    async findMembership(organizationId, userId) {
+      return (
+        members.find((row) => row.organizationId === organizationId && row.userId === userId) ??
+        null
+      );
+    },
+    async listMembers(organizationId) {
+      return members.filter((row) => row.organizationId === organizationId);
+    },
+    async addMembership(input) {
+      const existing = members.find(
+        (row) => row.organizationId === input.organizationId && row.userId === input.userId,
+      );
+      if (existing) return existing;
+      const row: MembershipRecord = { id: crypto.randomUUID(), createdAt: new Date(), ...input };
+      members.push(row);
+      return row;
+    },
+    async removeMembership(organizationId, userId) {
+      const index = members.findIndex(
+        (row) => row.organizationId === organizationId && row.userId === userId,
+      );
+      if (index < 0) return false;
+      members.splice(index, 1);
+      return true;
+    },
+    async countOwners(organizationId) {
+      return members.filter((row) => row.organizationId === organizationId && row.role === 'OWNER')
+        .length;
+    },
+    async upsertPendingInvite(input) {
+      const email = input.email.toLowerCase();
+      const existing = invites.find(
+        (row) =>
+          row.organizationId === input.organizationId &&
+          row.email === email &&
+          row.acceptedAt === null,
+      );
+      if (existing) {
+        existing.role = input.role;
+        existing.tokenHash = input.tokenHash;
+        existing.expiresAt = input.expiresAt;
+        existing.invitedById = input.invitedById;
+        return existing;
+      }
+      const row: OrgInviteRecord = {
+        id: crypto.randomUUID(),
+        createdAt: new Date(),
+        acceptedAt: null,
+        ...input,
+        email,
+      };
+      invites.push(row);
+      return row;
+    },
+    async findPendingInviteByEmail(organizationId, email) {
+      const normalized = email.toLowerCase();
+      return (
+        invites.find(
+          (row) =>
+            row.organizationId === organizationId &&
+            row.email === normalized &&
+            row.acceptedAt === null,
+        ) ?? null
+      );
+    },
+    async findInviteByTokenHash(tokenHash) {
+      return invites.find((row) => row.tokenHash === tokenHash) ?? null;
+    },
+    async listPendingInvites(organizationId) {
+      return invites.filter(
+        (row) => row.organizationId === organizationId && row.acceptedAt === null,
+      );
+    },
+    async markInviteAccepted(id, at) {
+      const row = invites.find((item) => item.id === id);
+      if (row) row.acceptedAt = at;
+    },
+    async deleteInvite(id, organizationId) {
+      const index = invites.findIndex(
+        (row) => row.id === id && row.organizationId === organizationId && row.acceptedAt === null,
+      );
+      if (index < 0) return false;
+      invites.splice(index, 1);
+      return true;
+    },
+  };
+};
+
+export type MemoryOrganizationRepository = ReturnType<typeof createMemoryOrganizationRepository>;

package/templates/capabilities/team/apps/api/src/modules/organizations/infra/organization-router.ts

@@ -0,0 +1,130 @@
+import { type HttpHandler, mountContract } from '@ysk-kit/api-express';
+import type { AccessClaims } from '@ysk-kit/auth';
+import {
+  type AcceptInviteCommand,
+  appContract,
+  type CreateOrganizationCommand,
+  type InviteMemberCommand,
+  type UpdateOrganizationCommand,
+} from '@ysk-kit/contracts';
+import { AppError } from '@ysk-kit/domain-kernel';
+import type { Express } from 'express';
+import type { OrganizationService } from '../application/organization-service';
+
+const orgId = (params: unknown): string => (params as { organizationId: string }).organizationId;
+
+const actor = (auth: AccessClaims | undefined): AccessClaims => {
+  if (!auth) throw new AppError('UNAUTHENTICATED');
+  return auth;
+};
+
+export const organizationHandlers = (
+  service: OrganizationService,
+): Record<string, HttpHandler> => ({
+  create: {
+    auth: 'required',
+    handle: async ({ body, auth }) => ({
+      status: 201,
+      body: {
+        ok: true,
+        data: await service.create(actor(auth).sub, body as CreateOrganizationCommand),
+      },
+    }),
+  },
+  list: {
+    auth: 'required',
+    handle: async ({ auth }) => ({
+      status: 200,
+      body: { ok: true, data: await service.listMine(actor(auth).sub) },
+    }),
+  },
+  acceptInvite: {
+    handle: async ({ body }) => ({
+      status: 200,
+      body: { ok: true, data: await service.acceptInvite(body as AcceptInviteCommand) },
+    }),
+  },
+  get: {
+    auth: 'required',
+    handle: async ({ params, auth }) => ({
+      status: 200,
+      body: { ok: true, data: await service.get(actor(auth).sub, orgId(params)) },
+    }),
+  },
+  update: {
+    auth: 'required',
+    handle: async ({ params, body, auth }) => ({
+      status: 200,
+      body: {
+        ok: true,
+        data: await service.update(
+          actor(auth).sub,
+          orgId(params),
+          body as UpdateOrganizationCommand,
+        ),
+      },
+    }),
+  },
+  members: {
+    auth: 'required',
+    handle: async ({ params, auth }) => ({
+      status: 200,
+      body: { ok: true, data: await service.members(actor(auth).sub, orgId(params)) },
+    }),
+  },
+  invite: {
+    auth: 'required',
+    handle: async ({ params, body, auth }) => ({
+      status: 200,
+      body: {
+        ok: true,
+        data: await service.invite(actor(auth).sub, orgId(params), body as InviteMemberCommand),
+      },
+    }),
+  },
+  invites: {
+    auth: 'required',
+    handle: async ({ params, auth }) => ({
+      status: 200,
+      body: { ok: true, data: await service.invites(actor(auth).sub, orgId(params)) },
+    }),
+  },
+  revokeInvite: {
+    auth: 'required',
+    handle: async ({ params, auth }) => ({
+      status: 200,
+      body: {
+        ok: true,
+        data: await service.revokeInvite(
+          actor(auth).sub,
+          orgId(params),
+          (params as { id: string }).id,
+        ),
+      },
+    }),
+  },
+  removeMember: {
+    auth: 'required',
+    handle: async ({ params, auth }) => {
+      const p = params as { organizationId: string; userId: string };
+      return {
+        status: 200,
+        body: {
+          ok: true,
+          data: await service.removeMember(actor(auth).sub, p.organizationId, p.userId),
+        },
+      };
+    },
+  },
+  leave: {
+    auth: 'required',
+    handle: async ({ params, auth }) => ({
+      status: 200,
+      body: { ok: true, data: await service.leave(actor(auth).sub, orgId(params)) },
+    }),
+  },
+});
+
+export const registerOrganizationRoutes = (app: Express, service: OrganizationService): void => {
+  mountContract(app, appContract.organizations, organizationHandlers(service));
+};