@shipfox/client-invitations 0.2.0

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "@shipfox/client-invitations",
+  "license": "MIT",
+  "version": "0.2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
+    "directory": "libs/client/invitations"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "imports": {
+    "#*": {
+      "types": "./src/*",
+      "workspace-source": "./src/*",
+      "development": "./src/*",
+      "default": "./dist/*"
+    },
+    "#test/*": "./test/*"
+  },
+  "exports": {
+    ".": {
+      "development": {
+        "types": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
+      "default": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./feature": {
+      "development": {
+        "types": "./src/feature.ts",
+        "default": "./src/feature.ts"
+      },
+      "default": {
+        "types": "./dist/feature.d.ts",
+        "default": "./dist/feature.js"
+      }
+    },
+    "./routes/*": {
+      "development": {
+        "types": "./src/routes/*.tsx",
+        "default": "./src/routes/*.tsx"
+      },
+      "default": {
+        "types": "./dist/routes/*.d.ts",
+        "default": "./dist/routes/*.js"
+      }
+    }
+  },
+  "dependencies": {
+    "@swc/helpers": "^0.5.17",
+    "@tanstack/react-query": "^5.101.0",
+    "@shipfox/client-api": "0.2.0",
+    "@shipfox/api-workspaces-dto": "2.0.0",
+    "@shipfox/client-shell": "0.2.0",
+    "@shipfox/api-auth-dto": "2.0.0",
+    "@shipfox/react-ui": "0.3.1",
+    "@shipfox/client-auth": "0.2.0"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.101.0",
+    "@tanstack/react-router": "^1.170.16",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "^5.101.0",
+    "@tanstack/react-router": "^1.170.16",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^19.1.11",
+    "@types/react-dom": "^19.1.7",
+    "jsdom": "^29.0.0",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
+    "@shipfox/client-test-setup": "0.0.2",
+    "@shipfox/biome": "1.8.1",
+    "@shipfox/swc": "1.2.5",
+    "@shipfox/typescript": "1.1.6",
+    "@shipfox/ts-config": "1.3.8",
+    "@shipfox/vite": "1.2.4",
+    "@shipfox/vitest": "1.2.2"
+  },
+  "scripts": {
+    "build": "shipfox-swc",
+    "check": "shipfox-biome-check",
+    "check:fix": "shipfox-biome-check --write",
+    "test": "shipfox-vitest-run",
+    "test:watch": "shipfox-vitest-watch",
+    "type": "shipfox-tsc-check",
+    "type:emit": "shipfox-tsc-emit"
+  }
+}

package/src/complete-acceptance.test.ts

@@ -0,0 +1,55 @@
+import {toast} from '@shipfox/react-ui/toast';
+import {beforeEach, describe, expect, it, vi} from '@shipfox/vitest/vi';
+
+import {completeInvitationAcceptance} from './complete-acceptance.js';
+
+describe('completeInvitationAcceptance', () => {
+  beforeEach(() => {
+    vi.spyOn(toast, 'success').mockImplementation(() => 'toast-id');
+  });
+
+  it('refreshes auth before navigating to the joined workspace', async () => {
+    const calls: string[] = [];
+    const refreshAuth = vi.fn(() => {
+      calls.push('refreshAuth');
+      return Promise.resolve();
+    });
+    const navigate = vi.fn(() => {
+      calls.push('navigate');
+      return Promise.resolve();
+    });
+
+    await completeInvitationAcceptance({
+      navigate,
+      refreshAuth,
+      workspaceId: 'workspace-1',
+      workspaceName: 'Acme',
+    });
+
+    expect(refreshAuth).toHaveBeenCalledTimes(1);
+    expect(toast.success).toHaveBeenCalledWith('You joined Acme.');
+    expect(navigate).toHaveBeenCalledWith({
+      params: {wid: 'workspace-1'},
+      to: '/workspaces/$wid',
+    });
+    expect(calls).toEqual(['refreshAuth', 'navigate']);
+  });
+
+  it('still navigates when auth refresh fails', async () => {
+    const refreshAuth = vi.fn(() => Promise.reject(new Error('refresh failed')));
+    const navigate = vi.fn();
+
+    await completeInvitationAcceptance({
+      navigate,
+      refreshAuth,
+      workspaceId: 'workspace-1',
+      workspaceName: 'Acme',
+    });
+
+    expect(toast.success).toHaveBeenCalledWith('You joined Acme.');
+    expect(navigate).toHaveBeenCalledWith({
+      params: {wid: 'workspace-1'},
+      to: '/workspaces/$wid',
+    });
+  });
+});

package/src/complete-acceptance.ts

@@ -0,0 +1,33 @@
+import {toast} from '@shipfox/react-ui/toast';
+import type {NavigateOptions} from '@tanstack/react-router';
+
+/**
+ * Final step of every successful invitation accept path (existing-user match,
+ * signup-with-invitation success, login-then-accept). Refreshes the auth
+ * session so the JWT carries the new membership before navigating, then
+ * routes the user into the workspace home.
+ *
+ * `refreshAuth` is passed in so this helper stays a plain function (no hook).
+ * Call sites construct it via `useRefreshAuth()` from `@shipfox/client-auth`.
+ */
+export async function completeInvitationAcceptance(params: {
+  workspaceId: string;
+  workspaceName: string;
+  refreshAuth: () => Promise<unknown>;
+  navigate: (opts: NavigateOptions) => Promise<void> | void;
+}): Promise<void> {
+  // Access tokens embed memberships at issue time, so refresh before AuthGuard
+  // reads the accepted workspace.
+  try {
+    await params.refreshAuth();
+  } catch {
+    // Even if refresh fails the membership is real in the DB; surface the
+    // success toast and let the user re-auth if their session has fully
+    // expired. The next API call will redirect to login as usual.
+  }
+  toast.success(`You joined ${params.workspaceName}.`);
+  await params.navigate({
+    to: '/workspaces/$wid',
+    params: {wid: params.workspaceId},
+  });
+}

package/src/feature.ts

@@ -0,0 +1,12 @@
+import {defineClientFeature} from '@shipfox/client-shell';
+
+export const invitationsFeature = defineClientFeature({
+  id: 'shipfox.invitations',
+  routes: [
+    {
+      path: '/invitations/accept',
+      parent: 'root',
+      impl: '@shipfox/client-invitations/routes/accept',
+    },
+  ],
+});

package/src/hooks/api/accept-invitation.ts

@@ -0,0 +1,17 @@
+import type {
+  AcceptInvitationBodyDto,
+  AcceptInvitationResponseDto,
+} from '@shipfox/api-workspaces-dto';
+import {apiRequest} from '@shipfox/client-api';
+import {useMutation} from '@tanstack/react-query';
+
+async function acceptInvitation(body: AcceptInvitationBodyDto) {
+  return await apiRequest<AcceptInvitationResponseDto>('/invitations/accept', {
+    method: 'POST',
+    body,
+  });
+}
+
+export function useAcceptInvitation() {
+  return useMutation({mutationFn: acceptInvitation});
+}

package/src/hooks/api/preview-invitation.ts

@@ -0,0 +1,23 @@
+import type {PreviewInvitationResponseDto} from '@shipfox/api-workspaces-dto';
+import {apiRequest} from '@shipfox/client-api';
+import {useQuery} from '@tanstack/react-query';
+
+export const previewInvitationQueryKey = (token: string) =>
+  ['invitations', 'preview', token] as const;
+
+async function previewInvitation(token: string): Promise<PreviewInvitationResponseDto> {
+  const params = new URLSearchParams({token});
+  return await apiRequest<PreviewInvitationResponseDto>(
+    `/invitations/preview?${params.toString()}`,
+  );
+}
+
+export function usePreviewInvitation(token: string | undefined) {
+  return useQuery({
+    queryKey: previewInvitationQueryKey(token ?? ''),
+    queryFn: () => previewInvitation(token as string),
+    enabled: Boolean(token),
+    retry: false,
+    staleTime: 30_000,
+  });
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export {completeInvitationAcceptance} from './complete-acceptance.js';
+export {useAcceptInvitation} from './hooks/api/accept-invitation.js';
+export {
+  previewInvitationQueryKey,
+  usePreviewInvitation,
+} from './hooks/api/preview-invitation.js';
+export {InvitationAcceptPage} from './pages/invitation-accept-page.js';

package/src/pages/invitation-accept-page.tsx

@@ -0,0 +1,298 @@
+import {AuthShell, useAuthState, useRefreshAuth} from '@shipfox/client-auth';
+import {Button} from '@shipfox/react-ui/button';
+import {Callout} from '@shipfox/react-ui/callout';
+import {ShipfoxLoader} from '@shipfox/react-ui/loader';
+import {toast} from '@shipfox/react-ui/toast';
+import {Text} from '@shipfox/react-ui/typography';
+import {formatDate} from '@shipfox/react-ui/utils';
+import {Link, useNavigate, useSearch} from '@tanstack/react-router';
+import {useCallback, useEffect, useRef} from 'react';
+import {completeInvitationAcceptance} from '#complete-acceptance.js';
+import {useAcceptInvitation} from '#hooks/api/accept-invitation.js';
+import {usePreviewInvitation} from '#hooks/api/preview-invitation.js';
+
+// Module-scoped guard so React StrictMode's double-mount in dev does not
+// fire the accept mutation twice for the same token.
+const inFlightAccepts = new Set<string>();
+const toastedTerminals = new Set<string>();
+const TOASTED_TERMINALS_MAX = 32;
+
+export function InvitationAcceptPage() {
+  const search = useSearch({strict: false}) as {token?: unknown};
+  const token =
+    typeof search.token === 'string' && search.token.length > 0 ? search.token : undefined;
+  const navigate = useNavigate();
+  const auth = useAuthState();
+  const refreshAuth = useRefreshAuth();
+  const preview = usePreviewInvitation(token);
+  const accept = useAcceptInvitation();
+  const hasKickedAccept = useRef(false);
+
+  useEffect(() => {
+    if (!token) {
+      toast.error('This invitation link is missing a token.');
+      const timeout = window.setTimeout(() => {
+        navigate({to: '/', replace: true});
+      }, 2000);
+      return () => window.clearTimeout(timeout);
+    }
+    return undefined;
+  }, [navigate, token]);
+
+  const completeAccept = useCallback(
+    async (workspaceId: string, workspaceName: string) => {
+      await completeInvitationAcceptance({
+        workspaceId,
+        workspaceName,
+        refreshAuth,
+        navigate,
+      });
+    },
+    [navigate, refreshAuth],
+  );
+
+  const runAccept = useCallback(
+    async (params: {token: string; workspaceName: string}) => {
+      const result = await accept.mutateAsync({token: params.token});
+      await completeAccept(result.membership.workspace_id, params.workspaceName);
+    },
+    [accept, completeAccept],
+  );
+
+  // Auto-accept when authenticated and emails match (also handles already_used
+  // for the canonical authenticated path: backend returns already_member=true).
+  useEffect(() => {
+    if (!token) return;
+    if (auth.isLoading) return;
+    if (hasKickedAccept.current) return;
+    if (inFlightAccepts.has(token)) return;
+    const data = preview.data;
+    if (!data) return;
+    if (data.status !== 'pending') return;
+    if (!auth.isAuthenticated) return;
+
+    const authedEmail = auth.user?.email?.toLowerCase();
+    if (authedEmail !== data.email.toLowerCase()) return;
+
+    hasKickedAccept.current = true;
+    inFlightAccepts.add(token);
+
+    runAccept({token, workspaceName: data.workspace_name})
+      .catch(() => {
+        // The mutation surfaces its error via accept.error; the UI re-renders
+        // into the auth-match-error state below.
+      })
+      .finally(() => {
+        inFlightAccepts.delete(token);
+      });
+  }, [auth.isAuthenticated, auth.isLoading, auth.user?.email, preview.data, runAccept, token]);
+
+  if (!token) {
+    return (
+      <AuthShell title="Invalid link" description="This invitation link is incomplete.">
+        <Callout role="alert" type="error">
+          This invitation link is missing a token. Ask your administrator to resend it.
+        </Callout>
+        <Text size="sm" className="text-center text-foreground-neutral-muted" aria-live="polite">
+          Redirecting to the dashboard…
+        </Text>
+      </AuthShell>
+    );
+  }
+
+  if (preview.isLoading) {
+    return (
+      <AuthShell title="Loading invitation" description="One moment please.">
+        <CenteredLoader />
+      </AuthShell>
+    );
+  }
+
+  if (preview.isError) {
+    return (
+      <AuthShell title="Couldn't load invitation" description="Try again in a moment.">
+        <Callout role="alert" type="error">
+          We couldn't reach the server. Check your connection and retry.
+        </Callout>
+        <Button className="w-full" onClick={() => preview.refetch()}>
+          Try again
+        </Button>
+      </AuthShell>
+    );
+  }
+
+  const data = preview.data;
+  if (!data) {
+    return null;
+  }
+
+  if (data.status === 'invalid') {
+    notifyOnce(`invalid:${token}`, () => toast.error('This invitation link is no longer valid.'));
+    return (
+      <AuthShell title="Invalid invitation" description="The link you used didn't work.">
+        <Callout role="alert" type="error">
+          This invitation link is not valid. Ask your administrator to send a new one.
+        </Callout>
+        <GoHomeButton navigate={navigate} />
+      </AuthShell>
+    );
+  }
+
+  if (data.status === 'expired') {
+    notifyOnce(`expired:${token}`, () => toast.error('This invitation has expired.'));
+    return (
+      <AuthShell title="Invitation expired" description="The link is no longer accepting joins.">
+        <Callout role="alert" type="error">
+          This invitation expired on {formatDate(data.expires_at)}. Ask your administrator to send a
+          new one.
+        </Callout>
+        <GoHomeButton navigate={navigate} />
+      </AuthShell>
+    );
+  }
+
+  if (data.status === 'already_used') {
+    notifyOnce(`already-used:${token}`, () =>
+      toast.info(`This invitation has already been accepted.`),
+    );
+    return (
+      <AuthShell title="Invitation already used" description={data.workspace_name}>
+        <Callout role="alert" type="info">
+          This invitation has already been accepted.{' '}
+          {auth.isAuthenticated
+            ? `Open your dashboard to access ${data.workspace_name} if your account is a member.`
+            : `Log in to access ${data.workspace_name}.`}
+        </Callout>
+        {auth.isAuthenticated ? null : (
+          <Button asChild className="w-full">
+            <Link to="/auth/login">Log in</Link>
+          </Button>
+        )}
+        <GoHomeButton navigate={navigate} secondary />
+      </AuthShell>
+    );
+  }
+
+  const inviterLine =
+    data.invited_by_display != null
+      ? `Invited by ${data.invited_by_display} to join as ${data.email}.`
+      : `Invited to join as ${data.email}.`;
+
+  if (!auth.isAuthenticated) {
+    const redirect = `/invitations/accept?token=${encodeURIComponent(token)}`;
+    const signupHref = `/auth/signup?redirect=${encodeURIComponent(redirect)}`;
+    const loginHref = `/auth/login?redirect=${encodeURIComponent(redirect)}`;
+    return (
+      <AuthShell title={data.workspace_name} description={inviterLine}>
+        <div className="flex flex-col gap-16">
+          <Button asChild className="w-full">
+            <Link to={signupHref}>Create account</Link>
+          </Button>
+          <Button asChild className="w-full" variant="secondary">
+            <Link to={loginHref}>I already have an account</Link>
+          </Button>
+        </div>
+        <Text size="xs" className="text-center text-foreground-neutral-muted">
+          Not {data.email}? Contact your administrator.
+        </Text>
+      </AuthShell>
+    );
+  }
+
+  const viewerEmail = auth.user?.email?.toLowerCase();
+  const inviteeEmail = data.email.toLowerCase();
+  if (viewerEmail !== inviteeEmail) {
+    const redirect = `/invitations/accept?token=${encodeURIComponent(token)}`;
+    const logoutHref = `/auth/logout?redirect=${encodeURIComponent(redirect)}`;
+    return (
+      <AuthShell title={data.workspace_name} description={inviterLine}>
+        <Callout role="alert" type="warning">
+          You're signed in as {auth.user?.email}, but this invitation is for {data.email}.
+        </Callout>
+        <div className="flex flex-col gap-16">
+          <Button asChild className="w-full">
+            <Link to={logoutHref}>Log out and continue</Link>
+          </Button>
+          <Button
+            className="w-full"
+            variant="secondary"
+            onClick={() => navigate({to: '/', replace: true})}
+          >
+            Cancel
+          </Button>
+        </div>
+      </AuthShell>
+    );
+  }
+
+  // Authenticated + matches — auto-accept is in flight or about to render its
+  // result. Show either the pending state or the error state.
+  if (accept.isError) {
+    return (
+      <AuthShell title={data.workspace_name} description={inviterLine}>
+        <Callout role="alert" type="error">
+          We couldn't add you to {data.workspace_name}. Try again in a moment.
+        </Callout>
+        <Button
+          className="w-full"
+          isLoading={accept.isPending}
+          onClick={() => {
+            runAccept({token, workspaceName: data.workspace_name}).catch(() => {
+              // The mutation state drives the rendered error; avoid an
+              // unhandled rejection from the click handler.
+            });
+          }}
+        >
+          Try again
+        </Button>
+      </AuthShell>
+    );
+  }
+
+  return (
+    <AuthShell title={data.workspace_name} description={inviterLine}>
+      <div className="flex flex-col items-center gap-12" aria-live="polite">
+        <ShipfoxLoader />
+        <Text size="sm" className="text-foreground-neutral-subtle">
+          Adding you to {data.workspace_name}…
+        </Text>
+      </div>
+    </AuthShell>
+  );
+}
+
+function CenteredLoader() {
+  return (
+    <div className="flex justify-center py-16" aria-busy="true">
+      <ShipfoxLoader />
+    </div>
+  );
+}
+
+function GoHomeButton({
+  navigate,
+  secondary,
+}: {
+  navigate: ReturnType<typeof useNavigate>;
+  secondary?: boolean;
+}) {
+  return (
+    <Button
+      className="w-full"
+      variant={secondary ? 'secondary' : 'primary'}
+      onClick={() => navigate({to: '/', replace: true})}
+    >
+      Go to dashboard
+    </Button>
+  );
+}
+
+function notifyOnce(key: string, fn: () => void): void {
+  if (toastedTerminals.has(key)) return;
+  if (toastedTerminals.size >= TOASTED_TERMINALS_MAX) {
+    const oldest = toastedTerminals.values().next().value;
+    if (oldest !== undefined) toastedTerminals.delete(oldest);
+  }
+  toastedTerminals.add(key);
+  fn();
+}

package/src/routes/accept.tsx

@@ -0,0 +1,4 @@
+import {defineRoute} from '@shipfox/client-shell/runtime';
+import {InvitationAcceptPage} from '#pages/invitation-accept-page.js';
+
+export default defineRoute({component: InvitationAcceptPage});

package/test/setup.ts

@@ -0,0 +1,3 @@
+import {installClientDomTestEnv} from '@shipfox/client-test-setup';
+
+installClientDomTestEnv();

package/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+  "extends": "@shipfox/ts-config/react",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"],
+  "exclude": ["**/*.test.tsx", "**/*.test.ts"]
+}