@startsimpli/auth 0.4.16 → 0.4.17

package/src/hooks/__tests__/use-membership.test.tsx

@@ -0,0 +1,136 @@
+/** @vitest-environment jsdom */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { renderHook, waitFor, act } from '@testing-library/react';
+import { useMembership } from '../use-membership';
+
+// useMembership pulls auth from useAuth; mock the module so it sees a
+// stable authenticated user without spinning up the real AuthProvider.
+vi.mock('../../client/use-auth', () => ({
+  useAuth: () => ({
+    user: { id: 'u1', email: 'a@x.com', currentCompanyId: 'c1' },
+    session: null,
+    isLoading: false,
+    isAuthenticated: true,
+    login: vi.fn(),
+    logout: vi.fn(),
+    refreshUser: vi.fn(),
+    getAccessToken: vi.fn(),
+    register: vi.fn(),
+    signInWithGoogle: vi.fn(),
+    completeGoogleCallback: vi.fn(),
+    signInWithMicrosoft: vi.fn(),
+    completeMicrosoftCallback: vi.fn(),
+    hydrateSession: vi.fn(),
+  }),
+}));
+
+describe('useMembership', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('picks the OWNER membership when no currentCompanyId hint matches', async () => {
+    const fetchMyTeams = vi.fn().mockResolvedValue([
+      {
+        id: 'm1',
+        userId: 'u1',
+        teamId: 't1',
+        role: 'member',
+        joinedAt: '2025-01-01',
+        team: { id: 't1', slug: 'a', name: 'A', companyId: 'cX' },
+      },
+      {
+        id: 'm2',
+        userId: 'u1',
+        teamId: 't2',
+        role: 'owner',
+        joinedAt: '2025-01-02',
+        team: { id: 't2', slug: 'b', name: 'B', companyId: 'cY' },
+      },
+    ]);
+
+    const { result } = renderHook(() => useMembership({ fetchMyTeams }));
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.role).toBe('owner');
+    expect(result.current.isOwner).toBe(true);
+    expect(result.current.isAdmin).toBe(true);
+    expect(result.current.canInvite).toBe(true);
+    expect(result.current.currentTeam?.id).toBe('t2');
+  });
+
+  it('respects currentCompanyId on the AuthUser when picking', async () => {
+    const fetchMyTeams = vi.fn().mockResolvedValue([
+      {
+        id: 'm1',
+        userId: 'u1',
+        teamId: 't1',
+        role: 'admin',
+        joinedAt: '2025-01-01',
+        team: { id: 't1', slug: 'a', name: 'A', companyId: 'c1' },
+      },
+      {
+        id: 'm2',
+        userId: 'u1',
+        teamId: 't2',
+        role: 'owner',
+        joinedAt: '2025-01-02',
+        team: { id: 't2', slug: 'b', name: 'B', companyId: 'cZ' },
+      },
+    ]);
+
+    const { result } = renderHook(() => useMembership({ fetchMyTeams }));
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    // currentCompanyId is 'c1' on the mocked user, so we land on team t1.
+    expect(result.current.currentTeam?.id).toBe('t1');
+    expect(result.current.role).toBe('admin');
+  });
+
+  it('viewers cannot invite', async () => {
+    const fetchMyTeams = vi.fn().mockResolvedValue([
+      {
+        id: 'm1',
+        userId: 'u1',
+        teamId: 't1',
+        role: 'viewer',
+        joinedAt: '2025-01-01',
+        team: { id: 't1', slug: 'a', name: 'A', companyId: 'c1' },
+      },
+    ]);
+    const { result } = renderHook(() => useMembership({ fetchMyTeams }));
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.canInvite).toBe(false);
+    expect(result.current.isMemberOrAbove).toBe(false);
+  });
+
+  it('refresh re-runs the loader', async () => {
+    const fetchMyTeams = vi
+      .fn()
+      .mockResolvedValueOnce([])
+      .mockResolvedValueOnce([
+        {
+          id: 'm1',
+          userId: 'u1',
+          teamId: 't1',
+          role: 'owner',
+          joinedAt: '2025-01-01',
+          team: { id: 't1', slug: 'a', name: 'A', companyId: 'c1' },
+        },
+      ]);
+    const { result } = renderHook(() => useMembership({ fetchMyTeams }));
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.memberships).toEqual([]);
+    await act(async () => {
+      await result.current.refresh();
+    });
+    expect(result.current.memberships).toHaveLength(1);
+    expect(result.current.role).toBe('owner');
+  });
+
+  it('surfaces fetch errors via the error field', async () => {
+    const fetchMyTeams = vi.fn().mockRejectedValue(new Error('boom'));
+    const { result } = renderHook(() => useMembership({ fetchMyTeams }));
+    await waitFor(() => expect(result.current.error).not.toBeNull());
+    expect(result.current.error?.message).toBe('boom');
+  });
+});

package/src/hooks/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Team-management hooks shipped with @startsimpli/auth (startsim-o7s).
+ *
+ * Each hook is *injection-friendly* — the caller passes API methods (typically
+ * from @startsimpli/api). That keeps the auth package free of api dependencies
+ * while still owning the shared state shape for /settings/team UIs.
+ */
+
+export {
+  useMembership,
+  type UseMembershipOptions,
+  type UseMembershipReturn,
+  type MembershipCompany,
+  type MembershipTeam,
+  type MembershipRow,
+  type MembershipRole,
+} from './use-membership';
+
+export {
+  useInvitations,
+  type UseInvitationsOptions,
+  type UseInvitationsReturn,
+  type InvitationRow,
+  type BulkInviteEntry,
+  type BulkInviteResult,
+} from './use-invitations';
+
+export {
+  useDomainClaims,
+  type UseDomainClaimsOptions,
+  type UseDomainClaimsReturn,
+  type DomainClaimRow,
+  type DomainVerificationMethod,
+} from './use-domain-claims';

package/src/hooks/use-domain-claims.ts

@@ -0,0 +1,144 @@
+'use client';
+
+/**
+ * useDomainClaims — keeps the list of EmailDomainClaim rows fresh + exposes
+ * the verify-DNS / verify-email / revoke / create mutations.
+ *
+ * Injection-friendly: pass api.domainClaims.* methods so @startsimpli/auth
+ * stays decoupled from @startsimpli/api. startsim-o7s.
+ */
+
+import { useCallback, useEffect, useState } from 'react';
+
+export type DomainVerificationMethod = 'dns_txt' | 'email_attestation';
+
+/** Mirrors @startsimpli/api EmailDomainClaim but kept thin. */
+export interface DomainClaimRow {
+  id: string;
+  companyId: string;
+  domain: string;
+  verified: boolean;
+  verificationMethod?: DomainVerificationMethod | null;
+  verificationToken?: string | null;
+  verifiedAt?: string | null;
+  createdAt: string;
+}
+
+export interface UseDomainClaimsOptions {
+  fetchClaims: () => Promise<DomainClaimRow[]>;
+  createClaim: (input: { companyId: string; domain: string }) => Promise<DomainClaimRow>;
+  verifyDns: (id: string) => Promise<DomainClaimRow>;
+  initiateEmailVerification: (id: string) => Promise<{ detail: string }>;
+  submitEmailCode: (id: string, code: string) => Promise<DomainClaimRow>;
+  revokeClaim: (id: string) => Promise<void>;
+  autoFetch?: boolean;
+}
+
+export interface UseDomainClaimsReturn {
+  claims: DomainClaimRow[];
+  isLoading: boolean;
+  error: Error | null;
+  refresh: () => Promise<void>;
+  create: (input: { companyId: string; domain: string }) => Promise<DomainClaimRow>;
+  verifyDns: (id: string) => Promise<DomainClaimRow>;
+  initiateEmail: (id: string) => Promise<{ detail: string }>;
+  verifyEmail: (id: string, code: string) => Promise<DomainClaimRow>;
+  revoke: (id: string) => Promise<void>;
+}
+
+export function useDomainClaims(options: UseDomainClaimsOptions): UseDomainClaimsReturn {
+  const {
+    fetchClaims,
+    createClaim,
+    verifyDns: apiVerifyDns,
+    initiateEmailVerification,
+    submitEmailCode,
+    revokeClaim,
+    autoFetch = true,
+  } = options;
+
+  const [claims, setClaims] = useState<DomainClaimRow[]>([]);
+  const [isLoading, setIsLoading] = useState<boolean>(autoFetch);
+  const [error, setError] = useState<Error | null>(null);
+
+  const refresh = useCallback(async () => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      const fetched = await fetchClaims();
+      setClaims(fetched);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error(String(err)));
+    } finally {
+      setIsLoading(false);
+    }
+  }, [fetchClaims]);
+
+  useEffect(() => {
+    if (autoFetch) void refresh();
+  }, [autoFetch, refresh]);
+
+  const create = useCallback(
+    async (input: { companyId: string; domain: string }) => {
+      const row = await createClaim(input);
+      // Splice the new row in directly so the verification_token (creator-only)
+      // remains visible in the UI before any re-fetch hides it.
+      setClaims((prev) => [row, ...prev]);
+      return row;
+    },
+    [createClaim],
+  );
+
+  const replace = useCallback((id: string, next: DomainClaimRow) => {
+    setClaims((prev) => prev.map((c) => (c.id === id ? next : c)));
+  }, []);
+
+  const verifyDns = useCallback(
+    async (id: string) => {
+      const next = await apiVerifyDns(id);
+      replace(id, next);
+      return next;
+    },
+    [apiVerifyDns, replace],
+  );
+
+  const initiateEmail = useCallback(
+    async (id: string) => initiateEmailVerification(id),
+    [initiateEmailVerification],
+  );
+
+  const verifyEmail = useCallback(
+    async (id: string, code: string) => {
+      const next = await submitEmailCode(id, code);
+      replace(id, next);
+      return next;
+    },
+    [submitEmailCode, replace],
+  );
+
+  const revoke = useCallback(
+    async (id: string) => {
+      const snapshot = claims;
+      setClaims((prev) => prev.filter((c) => c.id !== id));
+      try {
+        await revokeClaim(id);
+      } catch (err) {
+        setClaims(snapshot);
+        throw err;
+      }
+    },
+    [claims, revokeClaim],
+  );
+
+  return {
+    claims,
+    isLoading,
+    error,
+    refresh,
+    create,
+    verifyDns,
+    initiateEmail,
+    verifyEmail,
+    revoke,
+  };
+}

package/src/hooks/use-invitations.ts

@@ -0,0 +1,138 @@
+'use client';
+
+/**
+ * useInvitations — keeps an in-memory view of the team invitations the
+ * current user can manage, plus mutation helpers for revoke + bulkInvite.
+ *
+ * Injection-friendly so the auth package stays decoupled from the api
+ * package; pass api.teamInvitations.list/revoke + api.teams.bulkInvite. startsim-o7s.
+ */
+
+import { useCallback, useEffect, useState } from 'react';
+import type { CompanyRole } from '../types';
+
+/** Mirrors @startsimpli/api TeamInvitation but kept thin so the hook is decoupled. */
+export interface InvitationRow {
+  id: string;
+  email: string;
+  teamId: string;
+  role: CompanyRole;
+  expiresAt: string;
+  acceptedAt?: string | null;
+  revokedAt?: string | null;
+  isExpired: boolean;
+  isAccepted: boolean;
+  createdAt: string;
+}
+
+export interface BulkInviteEntry {
+  email: string;
+  role: CompanyRole;
+}
+
+export interface BulkInviteResult {
+  invited: InvitationRow[];
+  skipped?: Array<{ email: string; reason: string }>;
+}
+
+export interface UseInvitationsOptions {
+  /**
+   * Required: list invitations (optionally scoped by teamId at call time
+   * via the rest of the caller's API surface).
+   */
+  fetchInvitations: () => Promise<InvitationRow[]>;
+  /** Revoke a single invitation. */
+  revokeInvitation: (id: string) => Promise<void>;
+  /** Bulk-invite to a team. */
+  bulkInviteToTeam: (
+    teamIdOrSlug: string,
+    invitations: BulkInviteEntry[],
+  ) => Promise<BulkInviteResult>;
+  /** Auto-fetch on mount? Defaults to true. */
+  autoFetch?: boolean;
+}
+
+export interface UseInvitationsReturn {
+  pending: InvitationRow[];
+  isLoading: boolean;
+  error: Error | null;
+  /** Force re-fetch. */
+  refresh: () => Promise<void>;
+  /** Revoke + optimistic prune from `pending`. */
+  revoke: (id: string) => Promise<void>;
+  /** Bulk-invite — re-fetches afterwards so `pending` includes the new rows. */
+  bulkInvite: (input: {
+    teamId: string;
+    invitations: BulkInviteEntry[];
+  }) => Promise<BulkInviteResult>;
+}
+
+export function useInvitations(options: UseInvitationsOptions): UseInvitationsReturn {
+  const {
+    fetchInvitations,
+    revokeInvitation,
+    bulkInviteToTeam,
+    autoFetch = true,
+  } = options;
+
+  const [rows, setRows] = useState<InvitationRow[]>([]);
+  const [isLoading, setIsLoading] = useState<boolean>(autoFetch);
+  const [error, setError] = useState<Error | null>(null);
+
+  const refresh = useCallback(async () => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      const fetched = await fetchInvitations();
+      setRows(fetched);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error(String(err)));
+    } finally {
+      setIsLoading(false);
+    }
+  }, [fetchInvitations]);
+
+  useEffect(() => {
+    if (autoFetch) void refresh();
+  }, [autoFetch, refresh]);
+
+  const revoke = useCallback(
+    async (id: string) => {
+      // Optimistic prune; on failure, revert.
+      const snapshot = rows;
+      setRows((prev) => prev.filter((r) => r.id !== id));
+      try {
+        await revokeInvitation(id);
+      } catch (err) {
+        setRows(snapshot);
+        throw err;
+      }
+    },
+    [revokeInvitation, rows],
+  );
+
+  const bulkInvite = useCallback(
+    async ({ teamId, invitations }: { teamId: string; invitations: BulkInviteEntry[] }) => {
+      const result = await bulkInviteToTeam(teamId, invitations);
+      // Re-fetch so the new rows show in pending (plus their backend-assigned ids).
+      await refresh();
+      return result;
+    },
+    [bulkInviteToTeam, refresh],
+  );
+
+  // Only invitations that are still actionable (not accepted, not revoked) and
+  // not yet expired count as "pending" for UI banners.
+  const pending = rows.filter(
+    (r) => !r.acceptedAt && !r.revokedAt && !r.isExpired,
+  );
+
+  return {
+    pending,
+    isLoading,
+    error,
+    refresh,
+    revoke,
+    bulkInvite,
+  };
+}

package/src/hooks/use-membership.ts

@@ -0,0 +1,192 @@
+'use client';
+
+/**
+ * useMembership — derive the current user's company + team membership
+ * context off whatever the backend hands the @startsimpli/api client.
+ *
+ * The hook is *injection-friendly*: the caller passes in the API methods
+ * (`fetchMyTeams`, `fetchTeam`, `fetchCompany`) so @startsimpli/auth stays
+ * decoupled from @startsimpli/api. Most apps will pass
+ *   api.teams.myTeams, api.teams.retrieve, api.companies.retrieve
+ * directly. startsim-o7s.
+ */
+
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useAuth } from '../client/use-auth';
+import { hasRolePermission } from '../types';
+import type { CompanyRole } from '../types';
+
+export type MembershipRole = CompanyRole;
+
+/** Minimal company-shape used by the hook (deduped from @startsimpli/api). */
+export interface MembershipCompany {
+  id: string;
+  slug: string;
+  name: string;
+}
+
+/** Minimal team-shape used by the hook. */
+export interface MembershipTeam {
+  id: string;
+  slug: string;
+  name: string;
+  companyId: string;
+}
+
+/** A row from `/team-members/my-teams/` — keeps just what the hook needs. */
+export interface MembershipRow {
+  id: string;
+  userId: string;
+  teamId: string;
+  role: MembershipRole;
+  joinedAt: string;
+  team?: MembershipTeam;
+}
+
+export interface UseMembershipOptions {
+  /** Required: returns the current user's team memberships. */
+  fetchMyTeams: () => Promise<MembershipRow[]>;
+  /** Optional: hydrate the active team if `team` isn't embedded in the row. */
+  fetchTeam?: (idOrSlug: string) => Promise<MembershipTeam>;
+  /** Optional: hydrate the active company. */
+  fetchCompany?: (idOrSlug: string) => Promise<MembershipCompany>;
+  /**
+   * Optional override that picks which team is "current". Defaults to:
+   *   1. AuthUser.currentCompanyId → the membership whose team belongs there
+   *   2. otherwise, the first OWNER membership
+   *   3. otherwise, the first row
+   */
+  pickCurrent?: (rows: MembershipRow[]) => MembershipRow | undefined;
+}
+
+export interface UseMembershipReturn {
+  company: MembershipCompany | null;
+  currentTeam: MembershipTeam | null;
+  role: MembershipRole | null;
+  isOwner: boolean;
+  isAdmin: boolean;
+  isMemberOrAbove: boolean;
+  canInvite: boolean;
+  /** All membership rows for this user. */
+  memberships: MembershipRow[];
+  isLoading: boolean;
+  error: Error | null;
+  /** Force re-fetch. */
+  refresh: () => Promise<void>;
+}
+
+const EMPTY: UseMembershipReturn = {
+  company: null,
+  currentTeam: null,
+  role: null,
+  isOwner: false,
+  isAdmin: false,
+  isMemberOrAbove: false,
+  canInvite: false,
+  memberships: [],
+  isLoading: false,
+  error: null,
+  refresh: async () => {},
+};
+
+export function useMembership(options: UseMembershipOptions): UseMembershipReturn {
+  const { fetchMyTeams, fetchTeam, fetchCompany, pickCurrent } = options;
+  const { user, isAuthenticated } = useAuth();
+
+  const [rows, setRows] = useState<MembershipRow[]>([]);
+  const [team, setTeam] = useState<MembershipTeam | null>(null);
+  const [company, setCompany] = useState<MembershipCompany | null>(null);
+  const [isLoading, setIsLoading] = useState<boolean>(isAuthenticated);
+  const [error, setError] = useState<Error | null>(null);
+
+  const currentCompanyHint = user?.currentCompanyId;
+
+  const refresh = useCallback(async () => {
+    if (!isAuthenticated) {
+      setRows([]);
+      setTeam(null);
+      setCompany(null);
+      setIsLoading(false);
+      return;
+    }
+    setIsLoading(true);
+    setError(null);
+    try {
+      const fetched = await fetchMyTeams();
+      setRows(fetched);
+
+      const picked =
+        pickCurrent?.(fetched) ??
+        defaultPickCurrent(fetched, currentCompanyHint);
+
+      if (!picked) {
+        setTeam(null);
+        setCompany(null);
+        return;
+      }
+
+      const teamObj = picked.team ?? (fetchTeam ? await fetchTeam(picked.teamId) : null);
+      setTeam(teamObj);
+
+      if (teamObj && fetchCompany) {
+        const companyObj = await fetchCompany(teamObj.companyId);
+        setCompany(companyObj);
+      }
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error(String(err)));
+    } finally {
+      setIsLoading(false);
+    }
+  }, [fetchMyTeams, fetchTeam, fetchCompany, pickCurrent, isAuthenticated, currentCompanyHint]);
+
+  useEffect(() => {
+    void refresh();
+  }, [refresh]);
+
+  return useMemo<UseMembershipReturn>(() => {
+    if (!isAuthenticated) return EMPTY;
+    const picked =
+      pickCurrent?.(rows) ?? defaultPickCurrent(rows, currentCompanyHint);
+    const role = picked?.role ?? null;
+    const isOwner = role === 'owner';
+    const isAdmin = !!role && hasRolePermission(role, 'admin');
+    const isMemberOrAbove = !!role && hasRolePermission(role, 'member');
+    return {
+      company,
+      currentTeam: team,
+      role,
+      isOwner,
+      isAdmin,
+      isMemberOrAbove,
+      // Owners + admins can invite; backend enforces same on bulk-invite.
+      canInvite: isAdmin,
+      memberships: rows,
+      isLoading,
+      error,
+      refresh,
+    };
+  }, [
+    isAuthenticated,
+    rows,
+    team,
+    company,
+    isLoading,
+    error,
+    refresh,
+    pickCurrent,
+    currentCompanyHint,
+  ]);
+}
+
+function defaultPickCurrent(
+  rows: MembershipRow[],
+  currentCompanyId?: string,
+): MembershipRow | undefined {
+  if (rows.length === 0) return undefined;
+  if (currentCompanyId) {
+    const hit = rows.find((r) => r.team?.companyId === currentCompanyId);
+    if (hit) return hit;
+  }
+  const owner = rows.find((r) => r.role === 'owner');
+  return owner ?? rows[0];
+}

package/src/index.ts

@@ -58,4 +58,29 @@ export type {
   SessionStorage,
 } from './client';
 
+// Team-management hooks (startsim-o7s) — useMembership / useInvitations /
+// useDomainClaims. Headless; caller passes the @startsimpli/api methods.
+export {
+  useMembership,
+  useInvitations,
+  useDomainClaims,
+} from './hooks';
+export type {
+  UseMembershipOptions,
+  UseMembershipReturn,
+  MembershipCompany,
+  MembershipTeam,
+  MembershipRow,
+  MembershipRole,
+  UseInvitationsOptions,
+  UseInvitationsReturn,
+  InvitationRow,
+  BulkInviteEntry,
+  BulkInviteResult,
+  UseDomainClaimsOptions,
+  UseDomainClaimsReturn,
+  DomainClaimRow,
+  DomainVerificationMethod,
+} from './hooks';
+
 // DO NOT export './server' here - it uses next/headers and must be imported explicitly via '@startsimpli/auth/server'

package/src/server/index.ts

@@ -18,3 +18,7 @@ export {
   withRole,
   type GuardResult,
 } from './guards';
+
+// Re-export token helpers so consumers (e.g. app middleware) don't have to
+// reach into `./utils` directly.
+export { isTokenExpired, decodeToken, getTokenExpiresAt } from '../utils/token';

package/src/types/index.ts

@@ -183,7 +183,6 @@ export interface PasswordResetRequest {
 export interface PasswordResetConfirm {
   token: string;
   password: string;
-  passwordConfirm: string;
 }
 
 /**