@brightweblabs/module-orgs 0.2.3 → 0.3.0

package/brightweb.module.json

@@ -12,7 +12,8 @@
       { "name": "orgs.organizations.read", "since": "0.1.0" },
       { "name": "orgs.organizations.write", "since": "0.1.0" },
       { "name": "orgs.membership.read", "since": "0.1.0" },
-      { "name": "orgs.membership.admin", "since": "0.1.0" }
+      { "name": "orgs.membership.admin", "since": "0.1.0" },
+      { "name": "orgs.invitations.admin", "since": "0.3.0" }
     ],
     "consumes": []
   },
@@ -20,7 +21,8 @@
     "orgs.organizations.read": { "specifier": ".", "symbol": "listOrganizations" },
     "orgs.organizations.write": { "specifier": ".", "symbol": "createOrganization" },
     "orgs.membership.read": { "specifier": ".", "symbol": "listOrganizationMembers" },
-    "orgs.membership.admin": { "specifier": ".", "symbol": "setOrganizationMemberRole" }
+    "orgs.membership.admin": { "specifier": ".", "symbol": "setOrganizationMemberRole" },
+    "orgs.invitations.admin": { "specifier": ".", "symbol": "inviteOrganizationMembers" }
   },
   "events": { "emits": [], "consumes": [] },
   "permissions": {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@brightweblabs/module-orgs",
   "private": false,
-  "version": "0.2.3",
+  "version": "0.3.0",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "files": [
@@ -21,7 +21,10 @@
     "./registration": "./src/registration.ts"
   },
   "dependencies": {
-    "@supabase/supabase-js": "^2.105.3",
-    "@brightweblabs/app-shell": "0.5.0"
+    "@supabase/supabase-js": "^2.110.8",
+    "server-only": "^0.0.1",
+    "@brightweblabs/app-shell": "0.6.0",
+    "@brightweblabs/core-auth": "0.4.0",
+    "@brightweblabs/infra": "0.3.2"
   }
 }

package/src/access.ts

@@ -0,0 +1,67 @@
+import type { User } from "@supabase/supabase-js";
+import { requireServerUserAccess } from "@brightweblabs/core-auth/server";
+import { requireServiceRoleClient } from "@brightweblabs/infra/server";
+import type { GlobalRole } from "@brightweblabs/core-auth/shared";
+
+type OrganizationBaseAccess = {
+  serviceSupabase: ReturnType<typeof requireServiceRoleClient>;
+  user: User;
+  role: GlobalRole;
+  profileId: string;
+};
+
+type OrganizationAccessError = {
+  ok: false;
+  status: number;
+  error: string;
+};
+
+async function resolveBaseOrganizationAccess(): Promise<OrganizationBaseAccess | OrganizationAccessError> {
+  const access = await requireServerUserAccess();
+  if (!access.ok) {
+    return access.status === 409
+      ? { ok: false, status: 403, error: "Perfil não encontrado." }
+      : access;
+  }
+  if (!access.role) return { ok: false, status: 403, error: "Acesso proibido." };
+
+  return {
+    serviceSupabase: requireServiceRoleClient(),
+    user: access.user,
+    role: access.role,
+    profileId: access.profileId,
+  };
+}
+
+function isAccessError(
+  access: OrganizationBaseAccess | OrganizationAccessError,
+): access is OrganizationAccessError {
+  return "ok" in access && access.ok === false;
+}
+
+export async function requireOrganizationsStaffAccess() {
+  const base = await resolveBaseOrganizationAccess();
+  if (isAccessError(base)) return base;
+  if (base.role !== "admin" && base.role !== "staff") {
+    return { ok: false, status: 403, error: "Acesso proibido." } as const;
+  }
+  return { ok: true, ...base } as const;
+}
+
+export async function requireOrganizationManageAccess(organizationId: string) {
+  const base = await resolveBaseOrganizationAccess();
+  if (isAccessError(base)) return base;
+  if (base.role === "admin" || base.role === "staff") {
+    return { ok: true, ...base, isOrgMember: true, isOrgAdmin: true } as const;
+  }
+
+  const { data, error } = await base.serviceSupabase
+    .from("organization_members")
+    .select("role")
+    .eq("organization_id", organizationId)
+    .eq("profile_id", base.profileId)
+    .maybeSingle<{ role: string }>();
+  if (error) return { ok: false, status: 500, error: error.message } as const;
+  if (data?.role !== "admin") return { ok: false, status: 403, error: "Acesso proibido." } as const;
+  return { ok: true, ...base, isOrgMember: true, isOrgAdmin: true } as const;
+}

package/src/data.ts

@@ -16,6 +16,8 @@ export type Organization = {
   website_url: string | null;
   address: string | null;
   taxIdentifierValue: string | null;
+  taxIdentifierKind: string | null;
+  taxIdentifierCountryCode: string | null;
   primary_contact_id: string | null;
   primary_contact?: OrganizationPrimaryContact | null;
   created_at: string;
@@ -42,6 +44,10 @@ export type CreateOrganizationInput = {
   budgetRange?: string | null;
   websiteUrl?: string | null;
   address?: string | null;
+  addressLine1?: string | null;
+  addressLine2?: string | null;
+  zipCode?: string | null;
+  country?: string | null;
   taxIdentifierValue?: string | null;
   primaryContactId?: string | null;
 };
@@ -67,6 +73,8 @@ type RawOrganization = {
   website_url: string | null;
   address: string | null;
   tax_identifier_value?: string | null;
+  tax_identifier_kind?: string | null;
+  tax_identifier_country_code?: string | null;
   primary_contact_id: string | null;
   primary_contact?: OrganizationPrimaryContact | OrganizationPrimaryContact[] | null;
   created_at: string;
@@ -74,6 +82,7 @@ type RawOrganization = {
 
 export const ORGANIZATIONS_DEFAULT_PAGE_SIZE = 20;
 export const ORGANIZATIONS_MAX_PAGE_SIZE = 100;
+const ORGANIZATION_ADDRESS_SEPARATOR = " · ";
 
 function normalizePage(page: number | undefined, fallback: number) {
   return Number.isFinite(page) && (page ?? 0) > 0 ? Math.floor(page as number) : fallback;
@@ -95,12 +104,41 @@ function normalizeOrganization(raw: RawOrganization): Organization {
     website_url: raw.website_url,
     address: raw.address,
     taxIdentifierValue: typeof raw.tax_identifier_value === "string" ? raw.tax_identifier_value : null,
+    taxIdentifierKind: typeof raw.tax_identifier_kind === "string" ? raw.tax_identifier_kind : null,
+    taxIdentifierCountryCode: typeof raw.tax_identifier_country_code === "string" ? raw.tax_identifier_country_code : null,
     primary_contact_id: raw.primary_contact_id,
     primary_contact: Array.isArray(primaryContact) ? primaryContact[0] ?? null : primaryContact ?? null,
     created_at: raw.created_at,
   };
 }
 
+function buildAddress(input: CreateOrganizationInput): string | null {
+  const addressLine1 = input.addressLine1 === undefined ? input.address : input.addressLine1;
+  const composed = [addressLine1, input.addressLine2, input.zipCode, input.country]
+    .map((part) => part?.trim() ?? "")
+    .filter(Boolean)
+    .join(ORGANIZATION_ADDRESS_SEPARATOR);
+  return composed || null;
+}
+
+function organizationWritePayload(input: CreateOrganizationInput) {
+  const taxIdentifierValue = input.taxIdentifierValue?.replace(/\D/g, "") || null;
+  return {
+    name: input.name.trim(),
+    industry: input.industry?.trim() || null,
+    company_size: input.companySize?.trim() || null,
+    budget_range: input.budgetRange?.trim() || null,
+    website_url: input.websiteUrl?.trim() || null,
+    address: buildAddress(input),
+    tax_identifier_value: taxIdentifierValue,
+    tax_identifier_kind: taxIdentifierValue ? "vat" : null,
+    tax_identifier_country_code: taxIdentifierValue ? "PT" : null,
+  };
+}
+
+const ORGANIZATION_SELECT =
+  "id, name, industry, company_size, budget_range, website_url, address, tax_identifier_value, tax_identifier_kind, tax_identifier_country_code, primary_contact_id, created_at, primary_contact:profiles!organizations_primary_contact_id_fkey(id, first_name, last_name, email)";
+
 export async function listOrganizations(
   supabase: SupabaseClient,
   params: OrganizationsListParams = {},
@@ -114,7 +152,7 @@ export async function listOrganizations(
   let query = supabase
     .from("organizations")
     .select(
-      "id, name, industry, company_size, budget_range, website_url, address, tax_identifier_value, primary_contact_id, created_at, primary_contact:profiles!organizations_primary_contact_id_fkey(id, first_name, last_name, email)",
+      ORGANIZATION_SELECT,
       { count: "exact" },
     )
     .order("created_at", { ascending: false })
@@ -147,18 +185,10 @@ export async function createOrganization(
   const { data, error } = await supabase
     .from("organizations")
     .insert({
-      name,
-      industry: input.industry?.trim() || null,
-      company_size: input.companySize?.trim() || null,
-      budget_range: input.budgetRange?.trim() || null,
-      website_url: input.websiteUrl?.trim() || null,
-      address: input.address?.trim() || null,
-      tax_identifier_value: input.taxIdentifierValue?.trim() || null,
+      ...organizationWritePayload(input),
       primary_contact_id: input.primaryContactId || null,
     })
-    .select(
-      "id, name, industry, company_size, budget_range, website_url, address, tax_identifier_value, primary_contact_id, created_at, primary_contact:profiles!organizations_primary_contact_id_fkey(id, first_name, last_name, email)",
-    )
+    .select(ORGANIZATION_SELECT)
     .single();
 
   if (error) throw new Error(error.message);
@@ -173,22 +203,17 @@ export async function updateOrganization(
   const name = input.name.trim();
   if (!name) throw new Error("Organization name is required.");
 
+  const payload: ReturnType<typeof organizationWritePayload> & { primary_contact_id?: string | null } =
+    organizationWritePayload(input);
+  if (input.primaryContactId !== undefined) {
+    payload.primary_contact_id = input.primaryContactId || null;
+  }
+
   const { data, error } = await supabase
     .from("organizations")
-    .update({
-      name,
-      industry: input.industry?.trim() || null,
-      company_size: input.companySize?.trim() || null,
-      budget_range: input.budgetRange?.trim() || null,
-      website_url: input.websiteUrl?.trim() || null,
-      address: input.address?.trim() || null,
-      tax_identifier_value: input.taxIdentifierValue?.trim() || null,
-      primary_contact_id: input.primaryContactId || null,
-    })
+    .update(payload)
     .eq("id", organizationId)
-    .select(
-      "id, name, industry, company_size, budget_range, website_url, address, tax_identifier_value, primary_contact_id, created_at, primary_contact:profiles!organizations_primary_contact_id_fkey(id, first_name, last_name, email)",
-    )
+    .select(ORGANIZATION_SELECT)
     .single();
 
   if (error) throw new Error(error.message);

package/src/handlers.ts

@@ -0,0 +1,42 @@
+import { requireOrganizationManageAccess, requireOrganizationsStaffAccess } from "./access";
+import { createOrganization, updateOrganization } from "./data";
+import {
+  inviteOrganizationMembers,
+  logOrganizationActivity,
+  listOrganizationInvitations,
+  listOrganizationMemberViews,
+  revokeOrganizationInvitation,
+} from "./invitations";
+import {
+  createOrganizationInvitationDeleteHandler,
+  createOrganizationInvitationsHandler,
+  createOrganizationPatchHandler,
+  createOrganizationsPostHandler,
+} from "./http";
+
+const writeDependencies = {
+  getCreateAccess: requireOrganizationsStaffAccess,
+  getManageAccess: requireOrganizationManageAccess,
+  createOrganization,
+  updateOrganization,
+  inviteMembers: inviteOrganizationMembers,
+  logActivity: logOrganizationActivity,
+};
+
+const invitationDependencies = {
+  getManageAccess: requireOrganizationManageAccess,
+  inviteMembers: inviteOrganizationMembers,
+  listInvitations: listOrganizationInvitations,
+  listMembers: listOrganizationMemberViews,
+  revokeInvitation: revokeOrganizationInvitation,
+  logActivity: logOrganizationActivity,
+};
+
+export const handleOrganizationsPostRequest = createOrganizationsPostHandler(writeDependencies);
+export const handleOrganizationPatchRequest = createOrganizationPatchHandler(writeDependencies);
+
+const invitationHandlers = createOrganizationInvitationsHandler(invitationDependencies);
+export const handleOrganizationInvitationsGetRequest = invitationHandlers.GET;
+export const handleOrganizationInvitationsPostRequest = invitationHandlers.POST;
+export const handleOrganizationInvitationDeleteRequest =
+  createOrganizationInvitationDeleteHandler(invitationDependencies);

package/src/http.ts

@@ -0,0 +1,248 @@
+import type { SupabaseClient } from "@supabase/supabase-js";
+import type { CreateOrganizationInput, OrganizationMemberRole } from "./data";
+import type {
+  OrganizationInviteDraft,
+  inviteOrganizationMembers,
+  logOrganizationActivity,
+  listOrganizationInvitations,
+  listOrganizationMemberViews,
+  revokeOrganizationInvitation,
+} from "./invitations";
+
+export function json(body: unknown, init?: ResponseInit) {
+  return new Response(JSON.stringify(body), {
+    ...init,
+    headers: { "content-type": "application/json; charset=utf-8", ...(init?.headers ?? {}) },
+  });
+}
+
+type OrganizationAccess =
+  | { ok: true; serviceSupabase: SupabaseClient; profileId: string }
+  | { ok: false; status: number; error: string };
+
+type OrganizationWriteDependencies = {
+  getCreateAccess(): Promise<OrganizationAccess>;
+  getManageAccess(organizationId: string): Promise<OrganizationAccess>;
+  createOrganization: (supabase: SupabaseClient, input: CreateOrganizationInput) => Promise<unknown>;
+  updateOrganization: (supabase: SupabaseClient, id: string, input: CreateOrganizationInput) => Promise<unknown>;
+  inviteMembers: typeof inviteOrganizationMembers;
+  logActivity: typeof logOrganizationActivity;
+};
+
+type OrganizationInvitationDependencies = {
+  getManageAccess(organizationId: string): Promise<OrganizationAccess>;
+  inviteMembers: typeof inviteOrganizationMembers;
+  listInvitations: typeof listOrganizationInvitations;
+  listMembers: typeof listOrganizationMemberViews;
+  revokeInvitation: typeof revokeOrganizationInvitation;
+  logActivity: typeof logOrganizationActivity;
+};
+
+async function readJsonObject(request: Request): Promise<Record<string, unknown> | null> {
+  try {
+    const value = await request.json();
+    return value && typeof value === "object" && !Array.isArray(value)
+      ? value as Record<string, unknown>
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function readOptionalString(body: Record<string, unknown>, key: string): string | null | undefined {
+  if (!Object.hasOwn(body, key)) return undefined;
+  const value = body[key];
+  if (typeof value !== "string") return null;
+  return value.trim() || null;
+}
+
+function parseInvites(raw: unknown): OrganizationInviteDraft[] {
+  if (!Array.isArray(raw)) return [];
+  return raw.flatMap((item) => {
+    if (!item || typeof item !== "object") return [];
+    const record = item as Record<string, unknown>;
+    const email = typeof record.email === "string" ? record.email.trim().toLowerCase() : "";
+    const role: OrganizationMemberRole = record.role === "admin" ? "admin" : "member";
+    return email && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email) ? [{ email, role }] : [];
+  });
+}
+
+function parseOrganizationInput(body: Record<string, unknown>): CreateOrganizationInput {
+  return {
+    name: typeof body.name === "string" ? body.name.trim() : "",
+    primaryContactId: readOptionalString(body, "primaryContactId"),
+    industry: readOptionalString(body, "industry"),
+    companySize: readOptionalString(body, "companySize"),
+    budgetRange: readOptionalString(body, "budgetRange"),
+    websiteUrl: readOptionalString(body, "websiteUrl"),
+    addressLine1: readOptionalString(body, "addressLine1"),
+    addressLine2: readOptionalString(body, "addressLine2"),
+    zipCode: readOptionalString(body, "zipCode"),
+    country: readOptionalString(body, "country"),
+    taxIdentifierValue:
+      readOptionalString(body, "taxIdentifierValue") ?? readOptionalString(body, "nif"),
+  };
+}
+
+function organizationError(error: unknown): Response {
+  const message = error instanceof Error ? error.message : "";
+  if (message.startsWith("Não foi possível enviar o email de convite.")) {
+    return json({ error: message }, { status: 502 });
+  }
+  return json({ error: message || "Erro interno do servidor." }, { status: 500 });
+}
+
+export function createOrganizationsPostHandler(dependencies: OrganizationWriteDependencies) {
+  return async function handleOrganizationsPostRequest(request: Request): Promise<Response> {
+    const access = await dependencies.getCreateAccess();
+    if (!access.ok) return json({ error: access.error }, { status: access.status });
+    const body = await readJsonObject(request);
+    if (!body) return json({ error: "Payload inválido." }, { status: 400 });
+    const input = parseOrganizationInput(body);
+    if (!input.name) return json({ error: "name é obrigatório." }, { status: 400 });
+    try {
+      const organization = await dependencies.createOrganization(access.serviceSupabase, input) as { id: string };
+      const result = await dependencies.inviteMembers(
+        access.serviceSupabase,
+        organization.id,
+        parseInvites(body.invitations),
+        access.profileId,
+      );
+      await dependencies.logActivity(access.serviceSupabase, {
+        actorProfileId: access.profileId,
+        organizationId: organization.id,
+        eventType: "crm_organization_created",
+        summary: "Organização CRM criada.",
+        payload: {
+          organization_id: organization.id,
+          pending_invitations: result.summary.pendingInvitations,
+          direct_assignments: result.summary.directAssignments,
+        },
+      });
+      return json({ data: { organization, invitations: result.invitations, inviteSummary: result.summary } }, { status: 201 });
+    } catch (error) {
+      return organizationError(error);
+    }
+  };
+}
+
+export function createOrganizationPatchHandler(dependencies: OrganizationWriteDependencies) {
+  return async function handleOrganizationPatchRequest(
+    request: Request,
+    context: { params: Promise<{ id: string }> },
+  ): Promise<Response> {
+    const { id } = await context.params;
+    if (!id) return json({ error: "id é obrigatório." }, { status: 400 });
+    const access = await dependencies.getManageAccess(id);
+    if (!access.ok) return json({ error: access.error }, { status: access.status });
+    const body = await readJsonObject(request);
+    if (!body) return json({ error: "Payload inválido." }, { status: 400 });
+    const input = parseOrganizationInput(body);
+    if (!input.name) return json({ error: "name é obrigatório." }, { status: 400 });
+    try {
+      const organization = await dependencies.updateOrganization(access.serviceSupabase, id, input) as { id: string };
+      const result = await dependencies.inviteMembers(
+        access.serviceSupabase,
+        id,
+        parseInvites(body.invitations),
+        access.profileId,
+      );
+      await dependencies.logActivity(access.serviceSupabase, {
+        actorProfileId: access.profileId,
+        organizationId: id,
+        eventType: "crm_organization_updated",
+        summary: "Organização CRM atualizada.",
+        payload: {
+          organization_id: id,
+          pending_invitations: result.summary.pendingInvitations,
+          direct_assignments: result.summary.directAssignments,
+          updated_existing_members: result.summary.updatedExistingMembers,
+        },
+      });
+      return json({ data: { organization, invitations: result.invitations, inviteSummary: result.summary } });
+    } catch (error) {
+      return organizationError(error);
+    }
+  };
+}
+
+export function createOrganizationInvitationsHandler(dependencies: OrganizationInvitationDependencies) {
+  return {
+    GET: async (_request: Request, context: { params: Promise<{ id: string }> }): Promise<Response> => {
+      const { id } = await context.params;
+      if (!id) return json({ error: "id é obrigatório." }, { status: 400 });
+      const access = await dependencies.getManageAccess(id);
+      if (!access.ok) return json({ error: access.error }, { status: access.status });
+      try {
+        const [members, invitations] = await Promise.all([
+          dependencies.listMembers(access.serviceSupabase, id),
+          dependencies.listInvitations(access.serviceSupabase, id, { status: "pending" }),
+        ]);
+        return json({ data: { members, invitations } });
+      } catch (error) {
+        return organizationError(error);
+      }
+    },
+    POST: async (request: Request, context: { params: Promise<{ id: string }> }): Promise<Response> => {
+      const { id } = await context.params;
+      if (!id) return json({ error: "id é obrigatório." }, { status: 400 });
+      const access = await dependencies.getManageAccess(id);
+      if (!access.ok) return json({ error: access.error }, { status: access.status });
+      const body = await readJsonObject(request);
+      if (!body) return json({ error: "Payload inválido." }, { status: 400 });
+      const invitations = parseInvites(body.invitations);
+      if (invitations.length === 0) {
+        return json({ error: "Nenhum convite válido foi enviado." }, { status: 400 });
+      }
+      try {
+        const result = await dependencies.inviteMembers(
+          access.serviceSupabase,
+          id,
+          invitations,
+          access.profileId,
+        );
+        await dependencies.logActivity(access.serviceSupabase, {
+          actorProfileId: access.profileId,
+          organizationId: id,
+          eventType: "crm_organization_invitations_created",
+          summary: "Convites da organização CRM criados.",
+          payload: {
+            organization_id: id,
+            invitations: result.invitations.length,
+            pending_invitations: result.summary.pendingInvitations,
+            direct_assignments: result.summary.directAssignments,
+            updated_existing_members: result.summary.updatedExistingMembers,
+          },
+        });
+        return json({ data: { invitations: result.invitations, inviteSummary: result.summary } }, { status: 201 });
+      } catch (error) {
+        return organizationError(error);
+      }
+    },
+  };
+}
+
+export function createOrganizationInvitationDeleteHandler(dependencies: OrganizationInvitationDependencies) {
+  return async function handleOrganizationInvitationDeleteRequest(
+    _request: Request,
+    context: { params: Promise<{ id: string; invitationId: string }> },
+  ): Promise<Response> {
+    const { id, invitationId } = await context.params;
+    if (!id || !invitationId) return json({ error: "id e invitationId são obrigatórios." }, { status: 400 });
+    const access = await dependencies.getManageAccess(id);
+    if (!access.ok) return json({ error: access.error }, { status: access.status });
+    try {
+      await dependencies.revokeInvitation(access.serviceSupabase, id, invitationId);
+      await dependencies.logActivity(access.serviceSupabase, {
+        actorProfileId: access.profileId,
+        organizationId: id,
+        eventType: "crm_organization_invitation_revoked",
+        summary: "Convite da organização CRM revogado.",
+        payload: { organization_id: id, invitation_id: invitationId },
+      });
+      return json({ data: { success: true } });
+    } catch (error) {
+      return organizationError(error);
+    }
+  };
+}

package/src/index.ts

@@ -15,3 +15,27 @@ export {
   type OrganizationsListResult,
   type UpdateOrganizationInput,
 } from "./data";
+export {
+  handleOrganizationInvitationDeleteRequest,
+  handleOrganizationInvitationsGetRequest,
+  handleOrganizationInvitationsPostRequest,
+  handleOrganizationPatchRequest,
+  handleOrganizationsPostRequest,
+} from "./handlers";
+export {
+  ORGANIZATION_INVITE_EMAIL_DELIVERY_ERROR,
+  acceptOrganizationInvitation,
+  getOrganizationInvitationDetails,
+  inviteOrganizationMembers,
+  listOrganizationInvitations,
+  listOrganizationMemberViews,
+  logOrganizationActivity,
+  registerUserFromOrganizationInvitation,
+  revokeOrganizationInvitation,
+  type EnsureCrmContact,
+  type OrganizationInvitation,
+  type OrganizationInvitationDetails,
+  type OrganizationInviteDraft,
+  type OrganizationInviteSummary,
+  type OrganizationMemberView,
+} from "./invitations";

package/src/invitations.ts

@@ -0,0 +1,517 @@
+import type { SupabaseClient } from "@supabase/supabase-js";
+import type { OrganizationMemberRole } from "./data";
+import { sendOrganizationInviteEmail } from "./invite-email";
+
+const INVITE_EXPIRY_DAYS = 14;
+export const ORGANIZATION_INVITE_EMAIL_DELIVERY_ERROR =
+  "Não foi possível enviar o email de convite. O convite não foi guardado. Verifique a configuração do Resend.";
+
+export type OrganizationInviteDraft = {
+  email: string;
+  role: OrganizationMemberRole;
+};
+
+export type OrganizationInvitation = {
+  id: string;
+  organizationId: string;
+  email: string;
+  role: OrganizationMemberRole;
+  status: "pending" | "accepted" | "revoked" | "expired";
+  createdAt: string;
+  expiresAt: string;
+  invitedByProfileId: string | null;
+  acceptedAt: string | null;
+  acceptedByProfileId: string | null;
+  acceptedContactId: string | null;
+  revokedAt: string | null;
+};
+
+export type OrganizationInvitationDetails = {
+  id: string;
+  organizationId: string;
+  organizationName: string;
+  invitedEmail: string;
+  role: OrganizationMemberRole;
+  status: OrganizationInvitation["status"];
+  expiresAt: string;
+};
+
+export type OrganizationInviteSummary = {
+  pendingInvitations: number;
+  directAssignments: number;
+  updatedExistingMembers: number;
+  unchangedExistingMembers: number;
+  failedEmailDeliveries: number;
+};
+
+export type OrganizationMemberView = {
+  id: string;
+  profileId: string;
+  role: OrganizationMemberRole;
+  joinedAt: string;
+  label: string;
+  email: string | null;
+};
+
+export type EnsureCrmContact = (
+  profileId: string,
+  options: { source: string; serviceClient: SupabaseClient },
+) => Promise<{ success: boolean; contactId?: string; error?: string }>;
+
+export async function logOrganizationActivity(
+  supabase: SupabaseClient,
+  input: {
+    actorProfileId: string | null;
+    organizationId: string;
+    eventType: string;
+    summary: string;
+    payload: Record<string, unknown>;
+  },
+): Promise<void> {
+  const { error } = await supabase.rpc("log_app_activity_event", {
+    p_domain: "crm",
+    p_event_type: input.eventType,
+    p_entity_table: "organizations",
+    p_entity_id: input.organizationId,
+    p_summary: input.summary,
+    p_payload: input.payload,
+    p_actor_profile_id: input.actorProfileId,
+  });
+  if (error) console.error("Error logging organization activity event:", error);
+}
+
+function normalizeEmail(value: string): string {
+  return value.trim().toLowerCase();
+}
+
+function normalizeStatus(value: unknown): OrganizationInvitation["status"] {
+  return value === "accepted" || value === "revoked" || value === "expired" ? value : "pending";
+}
+
+function normalizeInvitation(raw: Record<string, unknown>): OrganizationInvitation {
+  return {
+    id: String(raw.id),
+    organizationId: String(raw.organization_id),
+    email: typeof raw.invited_email === "string" ? normalizeEmail(raw.invited_email) : "",
+    role: raw.role === "admin" ? "admin" : "member",
+    status: normalizeStatus(raw.status),
+    createdAt: String(raw.created_at),
+    expiresAt: String(raw.expires_at),
+    invitedByProfileId: typeof raw.invited_by_profile_id === "string" ? raw.invited_by_profile_id : null,
+    acceptedAt: typeof raw.accepted_at === "string" ? raw.accepted_at : null,
+    acceptedByProfileId: typeof raw.accepted_by_profile_id === "string" ? raw.accepted_by_profile_id : null,
+    acceptedContactId: typeof raw.accepted_contact_id === "string" ? raw.accepted_contact_id : null,
+    revokedAt: typeof raw.revoked_at === "string" ? raw.revoked_at : null,
+  };
+}
+
+function isInvitationExpired(expiresAt: string): boolean {
+  const date = new Date(expiresAt);
+  return Number.isNaN(date.getTime()) || date.getTime() < Date.now();
+}
+
+function isExistingAccountError(error: { message?: string } | null): boolean {
+  const message = (error?.message ?? "").toLowerCase();
+  return message.includes("already") || message.includes("exists") || message.includes("registered");
+}
+
+async function syncOrganizationPrimaryContactFromAdmins(
+  supabase: SupabaseClient,
+  organizationId: string,
+): Promise<void> {
+  const { data, error } = await supabase
+    .from("organization_members")
+    .select("profile_id")
+    .eq("organization_id", organizationId)
+    .eq("role", "admin")
+    .order("joined_at", { ascending: true })
+    .limit(1);
+  if (error) throw new Error(error.message);
+  const { error: updateError } = await supabase
+    .from("organizations")
+    .update({ primary_contact_id: typeof data?.[0]?.profile_id === "string" ? data[0].profile_id : null })
+    .eq("id", organizationId);
+  if (updateError) throw new Error(updateError.message);
+}
+
+async function findAuthUserIdByEmail(supabase: SupabaseClient, email: string): Promise<string | null> {
+  const target = normalizeEmail(email);
+  const perPage = 1000;
+  for (let page = 1; page <= 20; page += 1) {
+    const { data, error } = await supabase.auth.admin.listUsers({ page, perPage });
+    if (error) throw new Error(error.message);
+    const match = data.users.find((user) => normalizeEmail(user.email ?? "") === target);
+    if (match?.id) return match.id;
+    if (data.users.length < perPage) return null;
+  }
+  return null;
+}
+
+async function ensureInvitationProfile(
+  supabase: SupabaseClient,
+  params: { userId: string; email: string; firstName: string; lastName: string },
+): Promise<{ id: string }> {
+  const { error: syncError } = await supabase.rpc("sync_profile_from_auth_identity", {
+    p_user_id: params.userId,
+    p_email: params.email,
+    p_metadata: { first_name: params.firstName || null, last_name: params.lastName || null },
+  });
+  if (syncError) throw new Error(syncError.message);
+  const { data, error } = await supabase
+    .from("profiles")
+    .select("id")
+    .eq("user_id", params.userId)
+    .maybeSingle<{ id: string }>();
+  if (error) throw new Error(error.message);
+  if (!data?.id) throw new Error("Não foi possível criar o perfil.");
+  return data;
+}
+
+export async function getOrganizationInvitationDetails(
+  supabase: SupabaseClient,
+  invitationId: string,
+): Promise<OrganizationInvitationDetails | null> {
+  const { data, error } = await supabase
+    .from("organization_invitations")
+    .select("id, organization_id, invited_email, role, status, expires_at, organizations(name)")
+    .eq("id", invitationId)
+    .maybeSingle();
+  if (error) throw new Error(error.message);
+  if (!data) return null;
+  const raw = data as unknown as Record<string, unknown>;
+  const organizationRaw = raw.organizations;
+  const organization = Array.isArray(organizationRaw) ? organizationRaw[0] ?? null : organizationRaw;
+  return {
+    id: String(raw.id),
+    organizationId: String(raw.organization_id),
+    organizationName:
+      organization && typeof organization === "object" && typeof (organization as { name?: unknown }).name === "string"
+        ? (organization as { name: string }).name
+        : "Organização",
+    invitedEmail: typeof raw.invited_email === "string" ? normalizeEmail(raw.invited_email) : "",
+    role: raw.role === "admin" ? "admin" : "member",
+    status: normalizeStatus(raw.status),
+    expiresAt: String(raw.expires_at),
+  };
+}
+
+export async function listOrganizationInvitations(
+  supabase: SupabaseClient,
+  organizationId: string,
+  options?: { status?: OrganizationInvitation["status"] },
+): Promise<OrganizationInvitation[]> {
+  let query = supabase
+    .from("organization_invitations")
+    .select("id, organization_id, invited_email, role, status, invited_by_profile_id, accepted_at, accepted_by_profile_id, accepted_contact_id, revoked_at, expires_at, created_at")
+    .eq("organization_id", organizationId)
+    .order("created_at", { ascending: false });
+  if (options?.status) query = query.eq("status", options.status);
+  const { data, error } = await query;
+  if (error) throw new Error(error.message);
+  return ((data ?? []) as Array<Record<string, unknown>>).map(normalizeInvitation);
+}
+
+export async function listOrganizationMemberViews(
+  supabase: SupabaseClient,
+  organizationId: string,
+): Promise<OrganizationMemberView[]> {
+  const { data, error } = await supabase
+    .from("organization_members")
+    .select("id, profile_id, role, joined_at, profile:profiles!organization_members_profile_id_fkey(first_name, last_name, email)")
+    .eq("organization_id", organizationId)
+    .order("joined_at", { ascending: true });
+  if (error) throw new Error(error.message);
+  return (data ?? []).flatMap((row) => {
+    if (typeof row.id !== "string" || typeof row.profile_id !== "string") return [];
+    const rawProfile = Array.isArray(row.profile) ? row.profile[0] ?? null : row.profile;
+    const profile = rawProfile as { first_name?: unknown; last_name?: unknown; email?: unknown } | null;
+    const first = typeof profile?.first_name === "string" ? profile.first_name.trim() : "";
+    const last = typeof profile?.last_name === "string" ? profile.last_name.trim() : "";
+    const email = typeof profile?.email === "string" ? profile.email : null;
+    return [{
+      id: row.id,
+      profileId: row.profile_id,
+      role: row.role === "admin" ? "admin" : "member",
+      joinedAt: typeof row.joined_at === "string" ? row.joined_at : new Date().toISOString(),
+      label: `${first} ${last}`.trim() || email || "Membro",
+      email,
+    }];
+  });
+}
+
+function dedupeInviteDrafts(invites: OrganizationInviteDraft[]): OrganizationInviteDraft[] {
+  const seen = new Set<string>();
+  return invites.flatMap((invite) => {
+    const email = normalizeEmail(invite.email);
+    if (!email || seen.has(email)) return [];
+    seen.add(email);
+    return [{ email, role: invite.role === "admin" ? "admin" : "member" }];
+  });
+}
+
+export async function inviteOrganizationMembers(
+  supabase: SupabaseClient,
+  organizationId: string,
+  invites: OrganizationInviteDraft[],
+  actorProfileId: string,
+): Promise<{ invitations: OrganizationInvitation[]; summary: OrganizationInviteSummary }> {
+  const normalized = dedupeInviteDrafts(invites);
+  const emptySummary = {
+    pendingInvitations: 0,
+    directAssignments: 0,
+    updatedExistingMembers: 0,
+    unchangedExistingMembers: 0,
+    failedEmailDeliveries: 0,
+  };
+  if (normalized.length === 0) return { invitations: [], summary: emptySummary };
+
+  const emails = normalized.map((invite) => invite.email);
+  const [{ data: existingMembers, error: memberError }, { data: profiles, error: profileError }] = await Promise.all([
+    supabase.from("organization_members").select("profile_id, role, profile:profiles!organization_members_profile_id_fkey(email)").eq("organization_id", organizationId),
+    supabase.from("profiles").select("id, email").in("email", emails),
+  ]);
+  if (memberError) throw new Error(memberError.message);
+  if (profileError) throw new Error(profileError.message);
+  const { data: organization, error: organizationError } = await supabase
+    .from("organizations")
+    .select("name")
+    .eq("id", organizationId)
+    .maybeSingle<{ name: string | null }>();
+  if (organizationError) throw new Error(organizationError.message);
+  const organizationName = organization?.name?.trim() || "Organização";
+
+  const memberByEmail = new Map<string, { profileId: string; role: OrganizationMemberRole }>();
+  for (const row of existingMembers ?? []) {
+    const rawProfile = Array.isArray(row.profile) ? row.profile[0] ?? null : row.profile;
+    const email = rawProfile && typeof rawProfile.email === "string" ? normalizeEmail(rawProfile.email) : "";
+    if (email && typeof row.profile_id === "string") {
+      memberByEmail.set(email, { profileId: row.profile_id, role: row.role === "admin" ? "admin" : "member" });
+    }
+  }
+  const profileByEmail = new Map<string, string>();
+  for (const profile of profiles ?? []) {
+    if (typeof profile.id === "string" && typeof profile.email === "string") {
+      profileByEmail.set(normalizeEmail(profile.email), profile.id);
+    }
+  }
+
+  const pendingRows: Array<Record<string, unknown>> = [];
+  let directAssignments = 0;
+  let updatedExistingMembers = 0;
+  let unchangedExistingMembers = 0;
+  for (const invite of normalized) {
+    const member = memberByEmail.get(invite.email);
+    if (member) {
+      if (member.role === invite.role) unchangedExistingMembers += 1;
+      else {
+        const { error } = await supabase.from("organization_members").update({ role: invite.role })
+          .eq("organization_id", organizationId).eq("profile_id", member.profileId);
+        if (error) throw new Error(error.message);
+        updatedExistingMembers += 1;
+      }
+      continue;
+    }
+    const profileId = profileByEmail.get(invite.email);
+    if (profileId) {
+      const { error } = await supabase.from("organization_members").upsert({
+        organization_id: organizationId,
+        profile_id: profileId,
+        role: invite.role,
+      }, { onConflict: "organization_id,profile_id" });
+      if (error) throw new Error(error.message);
+      directAssignments += 1;
+      continue;
+    }
+    pendingRows.push({
+      organization_id: organizationId,
+      invited_email: invite.email,
+      role: invite.role,
+      status: "pending",
+      invited_by_profile_id: actorProfileId,
+      expires_at: new Date(Date.now() + INVITE_EXPIRY_DAYS * 86_400_000).toISOString(),
+      accepted_at: null,
+      accepted_by_profile_id: null,
+      accepted_contact_id: null,
+      revoked_at: null,
+    });
+  }
+
+  if (directAssignments > 0 || updatedExistingMembers > 0) {
+    await syncOrganizationPrimaryContactFromAdmins(supabase, organizationId);
+  }
+  if (pendingRows.length > 0) {
+    const { error } = await supabase.from("organization_invitations").upsert(pendingRows, {
+      onConflict: "organization_id,invited_email",
+      ignoreDuplicates: false,
+    });
+    if (error) throw new Error(error.message);
+    const { data: inserted, error: selectError } = await supabase
+      .from("organization_invitations")
+      .select("id, invited_email, role")
+      .eq("organization_id", organizationId)
+      .in("invited_email", pendingRows.map((row) => String(row.invited_email)))
+      .eq("status", "pending");
+    if (selectError) throw new Error(selectError.message);
+    const deliveries = await Promise.all((inserted ?? []).map(async (invitation) => ({
+      id: String(invitation.id),
+      delivered: await sendOrganizationInviteEmail({
+        invitationId: String(invitation.id),
+        organizationName,
+        invitedEmail: String(invitation.invited_email),
+        role: invitation.role === "admin" ? "admin" : "member",
+      }),
+    })));
+    const failedIds = deliveries.filter((result) => !result.delivered).map((result) => result.id);
+    if (failedIds.length > 0) {
+      const { error: deleteError } = await supabase
+        .from("organization_invitations")
+        .delete()
+        .in("id", failedIds)
+        .eq("status", "pending");
+      if (deleteError) throw new Error(deleteError.message);
+      throw new Error(ORGANIZATION_INVITE_EMAIL_DELIVERY_ERROR);
+    }
+  }
+
+  return {
+    invitations: await listOrganizationInvitations(supabase, organizationId, { status: "pending" }),
+    summary: {
+      pendingInvitations: pendingRows.length,
+      directAssignments,
+      updatedExistingMembers,
+      unchangedExistingMembers,
+      failedEmailDeliveries: 0,
+    },
+  };
+}
+
+export async function revokeOrganizationInvitation(
+  supabase: SupabaseClient,
+  organizationId: string,
+  invitationId: string,
+): Promise<void> {
+  const { error } = await supabase.from("organization_invitations")
+    .update({ status: "revoked", revoked_at: new Date().toISOString() })
+    .eq("id", invitationId).eq("organization_id", organizationId).eq("status", "pending");
+  if (error) throw new Error(error.message);
+}
+
+export async function acceptOrganizationInvitation(
+  supabase: SupabaseClient,
+  params: {
+    invitationId: string;
+    profileId: string;
+    userEmail: string;
+    ensureCrmContactForProfile: EnsureCrmContact;
+  },
+): Promise<{ organizationId: string }> {
+  const email = normalizeEmail(params.userEmail);
+  const { data: invitation, error } = await supabase
+    .from("organization_invitations")
+    .select("id, organization_id, invited_email, role, status, expires_at")
+    .eq("id", params.invitationId)
+    .maybeSingle<{ id: string; organization_id: string; invited_email: string; role: string; status: string; expires_at: string }>();
+  if (error) throw new Error(error.message);
+  if (!invitation?.id) throw new Error("Convite não encontrado.");
+  if (normalizeEmail(invitation.invited_email) !== email) throw new Error("Este convite pertence a outro email.");
+  if (invitation.status !== "pending") throw new Error("Este convite já não está disponível.");
+  if (isInvitationExpired(invitation.expires_at)) {
+    const { error: expireError } = await supabase.from("organization_invitations")
+      .update({ status: "expired" }).eq("id", invitation.id);
+    if (expireError) throw new Error(expireError.message);
+    throw new Error("Este convite expirou.");
+  }
+
+  const acceptedContact = await params.ensureCrmContactForProfile(params.profileId, {
+    source: "organization_invitation_accept",
+    serviceClient: supabase,
+  });
+  if (!acceptedContact.success) {
+    throw new Error(acceptedContact.error ?? "Não foi possível associar o contacto CRM ao convite.");
+  }
+  const role: OrganizationMemberRole = invitation.role === "admin" ? "admin" : "member";
+  const { error: memberError } = await supabase.from("organization_members").upsert({
+    organization_id: invitation.organization_id,
+    profile_id: params.profileId,
+    role,
+  }, { onConflict: "organization_id,profile_id" });
+  if (memberError) throw new Error(memberError.message);
+  if (role === "admin") await syncOrganizationPrimaryContactFromAdmins(supabase, invitation.organization_id);
+  const { error: updateError } = await supabase.from("organization_invitations").update({
+    status: "accepted",
+    accepted_at: new Date().toISOString(),
+    accepted_by_profile_id: params.profileId,
+    accepted_contact_id: acceptedContact.contactId ?? null,
+  }).eq("id", invitation.id);
+  if (updateError) throw new Error(updateError.message);
+  await logOrganizationActivity(supabase, {
+    actorProfileId: params.profileId,
+    organizationId: invitation.organization_id,
+    eventType: "crm_organization_invitation_accepted",
+    summary: "Convite de organização aceite.",
+    payload: {
+      invitation_id: invitation.id,
+      organization_id: invitation.organization_id,
+      email,
+    },
+  });
+  return { organizationId: invitation.organization_id };
+}
+
+export async function registerUserFromOrganizationInvitation(
+  supabase: SupabaseClient,
+  params: {
+    invitationId: string;
+    firstName: string;
+    lastName: string;
+    password: string;
+    ensureCrmContactForProfile: EnsureCrmContact;
+  },
+): Promise<{ email: string; organizationId: string }> {
+  const invitation = await getOrganizationInvitationDetails(supabase, params.invitationId);
+  if (!invitation) throw new Error("INVITATION_NOT_FOUND");
+  if (invitation.status !== "pending") throw new Error("INVITATION_NOT_AVAILABLE");
+  if (isInvitationExpired(invitation.expiresAt)) {
+    const { error } = await supabase.from("organization_invitations")
+      .update({ status: "expired" }).eq("id", invitation.id).eq("status", "pending");
+    if (error) throw new Error(error.message);
+    throw new Error("INVITATION_EXPIRED");
+  }
+
+  const firstName = params.firstName.trim();
+  const lastName = params.lastName.trim();
+  const { data, error } = await supabase.auth.admin.createUser({
+    email: invitation.invitedEmail,
+    password: params.password,
+    email_confirm: true,
+    user_metadata: { first_name: firstName || null, last_name: lastName || null },
+  });
+  let userId = data.user?.id ?? null;
+  let createdUserId = userId;
+  if (error) {
+    if (!isExistingAccountError(error)) throw new Error(error.message);
+    userId = await findAuthUserIdByEmail(supabase, invitation.invitedEmail);
+    if (!userId) throw new Error("ACCOUNT_ALREADY_EXISTS");
+    createdUserId = null;
+  }
+  if (!userId) throw new Error("Não foi possível criar utilizador.");
+
+  try {
+    const profile = await ensureInvitationProfile(supabase, {
+      userId,
+      email: invitation.invitedEmail,
+      firstName,
+      lastName,
+    });
+    await acceptOrganizationInvitation(supabase, {
+      invitationId: invitation.id,
+      profileId: profile.id,
+      userEmail: invitation.invitedEmail,
+      ensureCrmContactForProfile: params.ensureCrmContactForProfile,
+    });
+  } catch (caught) {
+    if (createdUserId) await supabase.auth.admin.deleteUser(createdUserId);
+    throw caught;
+  }
+  return { email: invitation.invitedEmail, organizationId: invitation.organizationId };
+}

package/src/invite-email.ts

@@ -0,0 +1,66 @@
+import "server-only";
+
+import {
+  getTransactionalSender,
+  resendApiRequest,
+  ResendConfigError,
+} from "@brightweblabs/infra/server";
+import { getAuthBaseUrl } from "@brightweblabs/core-auth/shared";
+import type { OrganizationMemberRole } from "./data";
+
+type SendOrganizationInviteEmailParams = {
+  invitationId: string;
+  organizationName: string;
+  invitedEmail: string;
+  role: OrganizationMemberRole;
+};
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+function buildSignupUrl(invitationId: string): string {
+  return new URL(`invite/${invitationId}`, `${getAuthBaseUrl()}/`).toString();
+}
+
+export async function sendOrganizationInviteEmail(
+  params: SendOrganizationInviteEmailParams,
+): Promise<boolean> {
+  try {
+    const signupUrl = buildSignupUrl(params.invitationId);
+    const roleLabel = params.role === "admin" ? "Administrador" : "Membro";
+    const safeOrganization = escapeHtml(params.organizationName);
+    const safeUrl = escapeHtml(signupUrl);
+
+    await resendApiRequest<{ id?: string }>("/emails", {
+      method: "POST",
+      body: JSON.stringify({
+        from: getTransactionalSender(),
+        to: [params.invitedEmail],
+        subject: `Convite para a organização ${params.organizationName}`,
+        html: `<p>Foi convidado(a) para <strong>${safeOrganization}</strong> como ${roleLabel}.</p><p><a href="${safeUrl}">Aceitar convite</a></p>`,
+        text: `Convite para ${params.organizationName} (${roleLabel})\n\n${signupUrl}`,
+        tags: [
+          { name: "flow", value: "organization_invite" },
+          { name: "org_role", value: params.role },
+        ],
+      }),
+    });
+
+    return true;
+  } catch (error) {
+    if (!(error instanceof ResendConfigError)) {
+      console.error("Organization invite email failed", {
+        invitationId: params.invitationId,
+        invitedEmail: params.invitedEmail,
+        error,
+      });
+    }
+    return false;
+  }
+}