@startsimpli/auth 0.4.15 → 0.4.17

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

@@ -38,7 +38,49 @@ export {
   authFetch,
   hasPermission,
   hasGroup,
+  createMockAuthBackend,
+  createMemorySessionStorage,
+  createWebSessionStorage,
+  createRememberAwareSessionStorage,
+  createSecureSessionStorage,
+  SESSION_STORAGE_KEY,
 } from './client';
-export type { UseAuthReturn, UseRequireAuthReturn, UseRequireAuthOptions, UsePermissionsReturn } from './client';
+export type {
+  UseAuthReturn,
+  UseRequireAuthReturn,
+  UseRequireAuthOptions,
+  UsePermissionsReturn,
+  AuthBackend,
+  RegisterPayload,
+  MockAuthBackend,
+  MockAuthBackendOptions,
+  MockAccount,
+  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

@@ -51,6 +51,11 @@ export interface AuthUser {
   isStaff?: boolean;
   isActive?: boolean;
   name?: string | null;
+  // Role/permission membership. Mirrors the functional-API AuthUser so the
+  // session user works directly with hasGroup()/hasPermission(). Backends that
+  // model roles as string groups (incl. the mock backend) populate these.
+  groups?: string[];
+  permissions?: string[];
   // Company/team context (if applicable)
   companies?: Array<{
     id: string;
@@ -178,7 +183,6 @@ export interface PasswordResetRequest {
 export interface PasswordResetConfirm {
   token: string;
   password: string;
-  passwordConfirm: string;
 }
 
 /**

package/src/utils/api-error.ts

@@ -0,0 +1,54 @@
+/**
+ * Extract a human-readable message from a Django REST Framework error response body.
+ *
+ * Handles the shapes we've seen in practice:
+ *   { detail: "..." }                                 → the string
+ *   { detail: ["...", "..."] }                        → first string
+ *   { detail: { token: ["Invalid..."] } }             → first nested string
+ *   { email: ["already exists"] }                     → first field-level string
+ *   { non_field_errors: ["..."] }                     → first field-level string
+ *   { error: "CODE", detail: { field: ["..."] } }     → first nested string
+ *
+ * Pure and DOM-free, so it is shared by the web functional client (functions.ts)
+ * and the platform-neutral token-auth core (token-auth-core.ts).
+ *
+ * @internal Implementation detail of the auth package; do not rely on from outside.
+ */
+export function extractApiError(d: Record<string, unknown>, fallback: string): string {
+  const pluck = (val: unknown): string | null => {
+    if (typeof val === 'string') return val
+    if (Array.isArray(val) && val.length > 0) {
+      for (const item of val) {
+        const s = pluck(item)
+        if (s) return s
+      }
+    }
+    if (val && typeof val === 'object') {
+      for (const v of Object.values(val as Record<string, unknown>)) {
+        const s = pluck(v)
+        if (s) return s
+      }
+    }
+    return null
+  }
+
+  // Standard DRF: { detail: "..." }
+  const fromDetail = pluck(d.detail)
+  if (fromDetail) return fromDetail
+  // Some backend shapes use `error` as the human-readable message (e.g.
+  // our Django auth errors: { "error": "No active account...", "code": "unauthorized" }).
+  // Prefer this over field-level probing so we don't accidentally return a
+  // code like "unauthorized" from a sibling field.
+  const fromError = pluck(d.error)
+  if (fromError) return fromError
+  // Field-level: { email: ["already exists"] } or { non_field_errors: ["..."] }
+  // Skip known meta/code fields so `{ code: "unauthorized" }` doesn't leak
+  // an internal identifier as a user-facing message.
+  const META_KEYS = new Set(['detail', 'error', 'code', 'statusCode', 'status', 'timestamp'])
+  for (const [key, val] of Object.entries(d)) {
+    if (META_KEYS.has(key)) continue
+    const s = pluck(val)
+    if (s) return s
+  }
+  return fallback
+}

package/src/utils/central-auth.ts

@@ -0,0 +1,91 @@
+/**
+ * Helpers for redirecting to the central StartSimpli auth host
+ * (auth.startsimpli.com, see startsim-ul0).
+ *
+ * Per-app auth pages have been replaced by a single host that owns
+ * /signin, /signup, /forgot-password, /reset-password, /verify-email,
+ * /oauth/google/callback, /oauth/microsoft/callback, /completion, /error.
+ *
+ * Apps consume this helper to:
+ *   1. Build "Sign in" / "Create account" links with the `app` + `return_to`
+ *      query params preserved.
+ *   2. Configure AuthProvider's `loginPath` so session-expired bounces hit the
+ *      same host.
+ *
+ * Defaults to https://auth.startsimpli.com but can be overridden via the
+ * `NEXT_PUBLIC_AUTH_HOST` env var for staging / local dev.
+ */
+
+export const DEFAULT_CENTRAL_AUTH_HOST = 'https://auth.startsimpli.com';
+
+/** Flows owned by the central auth host. */
+export type CentralAuthFlow =
+  | 'signin'
+  | 'signup'
+  | 'forgot-password'
+  | 'reset-password'
+  | 'verify-email'
+  | 'completion'
+  | 'error';
+
+/**
+ * Resolve the central auth host. Reads `NEXT_PUBLIC_AUTH_HOST` when present
+ * so apps can point at a staging deploy without rebuilding the package.
+ */
+export function resolveCentralAuthHost(): string {
+  if (typeof process !== 'undefined' && process.env?.NEXT_PUBLIC_AUTH_HOST) {
+    return process.env.NEXT_PUBLIC_AUTH_HOST;
+  }
+  return DEFAULT_CENTRAL_AUTH_HOST;
+}
+
+export interface BuildCentralAuthUrlOptions {
+  /** Slug identifying the calling app (e.g. `vault`, `raise`, `market`). */
+  app: string;
+  /** Absolute URL the user should be returned to after the flow completes. */
+  returnTo?: string;
+  /** Override the host (otherwise resolved from env). */
+  host?: string;
+  /** Extra query params to tack on. */
+  extraParams?: Record<string, string>;
+}
+
+/**
+ * Build a URL into the central auth host, preserving `?app=` and
+ * `?return_to=` consistently. Use this for hand-rolled links AND for
+ * AuthProvider's `loginPath` config.
+ *
+ * Example:
+ *   buildCentralAuthUrl('signin', { app: 'vault', returnTo: 'https://vault.startsimpli.com/environments' })
+ *   // => 'https://auth.startsimpli.com/signin?app=vault&return_to=https%3A%2F%2F...'
+ */
+export function buildCentralAuthUrl(
+  flow: CentralAuthFlow,
+  options: BuildCentralAuthUrlOptions,
+): string {
+  const host = options.host ?? resolveCentralAuthHost();
+  const url = new URL(`/${flow}`, host);
+  url.searchParams.set('app', options.app);
+  if (options.returnTo) {
+    url.searchParams.set('return_to', options.returnTo);
+  }
+  if (options.extraParams) {
+    for (const [key, value] of Object.entries(options.extraParams)) {
+      url.searchParams.set(key, value);
+    }
+  }
+  return url.toString();
+}
+
+/**
+ * Convenience: redirect the browser to the central auth host's signin flow,
+ * preserving the current URL as `return_to`. Safe to call from client code.
+ */
+export function redirectToCentralSignin(app: string): void {
+  if (typeof window === 'undefined') return;
+  const url = buildCentralAuthUrl('signin', {
+    app,
+    returnTo: window.location.href,
+  });
+  window.location.href = url;
+}

package/src/utils/index.ts

@@ -1,3 +1,4 @@
 export * from './token';
 export * from './cookies';
+export * from './central-auth';
 export * from '../validation';