@shipfox/client-invitations 4.0.0 → 6.0.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/client-invitations",
   "license": "MIT",
-  "version": "4.0.0",
+  "version": "6.0.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -10,10 +10,6 @@
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "imports": {
-    "#*": "./dist/*",
-    "#test/*": "./test/*"
-  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -31,13 +27,12 @@
   "dependencies": {
     "@swc/helpers": "^0.5.17",
     "@tanstack/react-query": "^5.101.0",
-    "@shipfox/api-workspaces-dto": "6.0.0",
-    "@shipfox/client-api": "4.0.0",
-    "@shipfox/api-auth-dto": "7.1.0",
-    "@shipfox/client-shell": "4.0.0",
-    "@shipfox/client-auth": "4.0.0",
-    "@shipfox/client-ui": "4.0.0",
-    "@shipfox/react-ui": "0.3.5"
+    "@shipfox/api-auth-dto": "9.0.1",
+    "@shipfox/api-workspaces-dto": "9.0.1",
+    "@shipfox/client-api": "6.0.1",
+    "@shipfox/client-ui": "6.0.1",
+    "@shipfox/react-ui": "0.3.6",
+    "@shipfox/client-shell": "6.0.1"
   },
   "peerDependencies": {
     "@tanstack/react-query": "^5.101.0",
@@ -45,6 +40,9 @@
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
+  "imports": {
+    "#*": "./dist/*"
+  },
   "scripts": {
     "build": "shipfox-swc",
     "check": "shipfox-biome-check",

package/src/complete-acceptance.ts

@@ -8,7 +8,7 @@ import type {NavigateOptions} from '@tanstack/react-router';
  * 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`.
+ * Call sites construct it via `useRefreshAuth()` from `@shipfox/client-shell/runtime`.
  */
 export async function completeInvitationAcceptance(params: {
   workspaceId: string;

package/src/core/invitation-acceptance.ts

@@ -0,0 +1,8 @@
+export interface InvitationAcceptance {
+  membership: {
+    id: string;
+    userId: string;
+    workspaceId: string;
+  };
+  alreadyMember: boolean;
+}

package/src/core/invitation-preview.ts

@@ -0,0 +1,18 @@
+export type InvitationPreview =
+  | {
+      status: 'pending';
+      workspaceId: string;
+      workspaceName: string;
+      email: string;
+      invitedByDisplay?: string;
+      expiresAt: string;
+    }
+  | {status: 'expired'; workspaceName: string; expiresAt: string}
+  | {status: 'already_used'; workspaceName: string}
+  | {status: 'invalid'};
+
+export function pendingInvitation(
+  preview: InvitationPreview | undefined,
+): Extract<InvitationPreview, {status: 'pending'}> | undefined {
+  return preview?.status === 'pending' ? preview : undefined;
+}

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

@@ -1,15 +1,14 @@
-import type {
-  AcceptInvitationBodyDto,
-  AcceptInvitationResponseDto,
-} from '@shipfox/api-workspaces-dto';
-import {apiRequest} from '@shipfox/client-api';
+import {acceptInvitationResponseSchema} from '@shipfox/api-workspaces-dto';
+import {checkedApiRequest} from '@shipfox/client-api';
 import {useMutation} from '@tanstack/react-query';
+import {toInvitationAcceptance} from './invitation-acceptance-mapper.js';
 
-async function acceptInvitation(body: AcceptInvitationBodyDto) {
-  return await apiRequest<AcceptInvitationResponseDto>('/invitations/accept', {
+async function acceptInvitation(command: {token: string}) {
+  const response = await checkedApiRequest(acceptInvitationResponseSchema, '/invitations/accept', {
     method: 'POST',
-    body,
+    body: command,
   });
+  return toInvitationAcceptance(response);
 }
 
 export function useAcceptInvitation() {

package/src/hooks/api/invitation-acceptance-mapper.test.ts

@@ -0,0 +1,23 @@
+import {toInvitationAcceptance} from './invitation-acceptance-mapper.js';
+
+describe('toInvitationAcceptance', () => {
+  test('maps the acceptance response into the invitation domain', () => {
+    const result = toInvitationAcceptance({
+      membership: {
+        id: '11111111-1111-4111-8111-111111111111',
+        user_id: '22222222-2222-4222-8222-222222222222',
+        workspace_id: '33333333-3333-4333-8333-333333333333',
+      },
+      already_member: true,
+    });
+
+    expect(result).toEqual({
+      membership: {
+        id: '11111111-1111-4111-8111-111111111111',
+        userId: '22222222-2222-4222-8222-222222222222',
+        workspaceId: '33333333-3333-4333-8333-333333333333',
+      },
+      alreadyMember: true,
+    });
+  });
+});

package/src/hooks/api/invitation-acceptance-mapper.ts

@@ -0,0 +1,13 @@
+import type {AcceptInvitationResponseDto} from '@shipfox/api-workspaces-dto';
+import type {InvitationAcceptance} from '#core/invitation-acceptance.js';
+
+export function toInvitationAcceptance(dto: AcceptInvitationResponseDto): InvitationAcceptance {
+  return {
+    membership: {
+      id: dto.membership.id,
+      userId: dto.membership.user_id,
+      workspaceId: dto.membership.workspace_id,
+    },
+    alreadyMember: dto.already_member,
+  };
+}

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

@@ -0,0 +1,36 @@
+import {describe, expect, it} from '@shipfox/vitest/vi';
+import {toInvitationPreview} from './invitation-preview-mapper.js';
+
+describe('toInvitationPreview', () => {
+  it.each([
+    [
+      {
+        status: 'pending' as const,
+        workspace_id: '11111111-1111-4111-8111-111111111111',
+        workspace_name: 'Acme',
+        email: 'member@example.com',
+        invited_by_display: 'Owner',
+        expires_at: '2026-08-01T00:00:00.000Z',
+      },
+      {
+        status: 'pending',
+        workspaceId: '11111111-1111-4111-8111-111111111111',
+        workspaceName: 'Acme',
+        email: 'member@example.com',
+        invitedByDisplay: 'Owner',
+        expiresAt: '2026-08-01T00:00:00.000Z',
+      },
+    ],
+    [
+      {status: 'expired' as const, workspace_name: 'Acme', expires_at: '2026-08-01T00:00:00.000Z'},
+      {status: 'expired', workspaceName: 'Acme', expiresAt: '2026-08-01T00:00:00.000Z'},
+    ],
+    [
+      {status: 'already_used' as const, workspace_name: 'Acme'},
+      {status: 'already_used', workspaceName: 'Acme'},
+    ],
+    [{status: 'invalid' as const}, {status: 'invalid'}],
+  ])('maps %s previews into the invitation domain', (dto, expected) => {
+    expect(toInvitationPreview(dto)).toEqual(expected);
+  });
+});

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

@@ -0,0 +1,22 @@
+import type {PreviewInvitationResponseDto} from '@shipfox/api-workspaces-dto';
+import type {InvitationPreview} from '#core/invitation-preview.js';
+
+export function toInvitationPreview(dto: PreviewInvitationResponseDto): InvitationPreview {
+  switch (dto.status) {
+    case 'pending':
+      return {
+        status: dto.status,
+        workspaceId: dto.workspace_id,
+        workspaceName: dto.workspace_name,
+        email: dto.email,
+        ...(dto.invited_by_display ? {invitedByDisplay: dto.invited_by_display} : {}),
+        expiresAt: dto.expires_at,
+      };
+    case 'expired':
+      return {status: dto.status, workspaceName: dto.workspace_name, expiresAt: dto.expires_at};
+    case 'already_used':
+      return {status: dto.status, workspaceName: dto.workspace_name};
+    case 'invalid':
+      return {status: dto.status};
+  }
+}

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

@@ -1,23 +1,38 @@
-import type {PreviewInvitationResponseDto} from '@shipfox/api-workspaces-dto';
-import {apiRequest} from '@shipfox/client-api';
-import {useQuery} from '@tanstack/react-query';
+import {previewInvitationResponseSchema} from '@shipfox/api-workspaces-dto';
+import {checkedApiRequest} from '@shipfox/client-api';
+import {type FetchQueryOptions, queryOptions, useQuery} from '@tanstack/react-query';
+import type {InvitationPreview} from '#core/invitation-preview.js';
+import {toInvitationPreview} from './invitation-preview-mapper.js';
 
 export const previewInvitationQueryKey = (token: string) =>
   ['invitations', 'preview', token] as const;
 
-async function previewInvitation(token: string): Promise<PreviewInvitationResponseDto> {
+type PreviewInvitationQueryOptions = FetchQueryOptions<
+  InvitationPreview,
+  Error,
+  InvitationPreview,
+  ReturnType<typeof previewInvitationQueryKey>
+>;
+
+async function previewInvitation(token: string): Promise<InvitationPreview> {
   const params = new URLSearchParams({token});
-  return await apiRequest<PreviewInvitationResponseDto>(
+  const response = await checkedApiRequest(
+    previewInvitationResponseSchema,
     `/invitations/preview?${params.toString()}`,
   );
+  return toInvitationPreview(response);
 }
 
-export function usePreviewInvitation(token: string | undefined) {
-  return useQuery({
-    queryKey: previewInvitationQueryKey(token ?? ''),
-    queryFn: () => previewInvitation(token as string),
+export function previewInvitationQueryOptions(token: string): PreviewInvitationQueryOptions {
+  return queryOptions({
+    queryKey: previewInvitationQueryKey(token),
+    queryFn: () => previewInvitation(token),
     enabled: Boolean(token),
     retry: false,
     staleTime: 30_000,
   });
 }
+
+export function usePreviewInvitation(token: string | undefined) {
+  return useQuery(previewInvitationQueryOptions(token ?? ''));
+}

package/src/index.ts

@@ -1,7 +1,10 @@
+export type {InvitationAcceptance} from '#core/invitation-acceptance.js';
+export {type InvitationPreview, pendingInvitation} from '#core/invitation-preview.js';
 export {completeInvitationAcceptance} from './complete-acceptance.js';
 export {useAcceptInvitation} from './hooks/api/accept-invitation.js';
 export {
   previewInvitationQueryKey,
+  previewInvitationQueryOptions,
   usePreviewInvitation,
 } from './hooks/api/preview-invitation.js';
 export {InvitationAcceptPage} from './pages/invitation-accept-page.js';

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

@@ -1,4 +1,9 @@
-import {AuthShell, useAuthState, useRefreshAuth} from '@shipfox/client-auth';
+import {
+  AuthShell,
+  useAuthState,
+  useRefreshAuth,
+  useRouteSearch,
+} from '@shipfox/client-shell/runtime';
 import {createSingleFlight} from '@shipfox/client-ui';
 import {Button} from '@shipfox/react-ui/button';
 import {Callout} from '@shipfox/react-ui/callout';
@@ -6,20 +11,19 @@ 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 {Link, useNavigate} 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';
+import {validateInvitationAcceptSearch} from '../routes/inputs.js';
 
 const invitationAccepts = createSingleFlight<string, void>();
 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 {token} = useRouteSearch(validateInvitationAcceptSearch);
   const navigate = useNavigate();
   const auth = useAuthState();
   const refreshAuth = useRefreshAuth();
@@ -53,7 +57,7 @@ export function InvitationAcceptPage() {
   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);
+      await completeAccept(result.membership.workspaceId, params.workspaceName);
     },
     [accept, completeAccept],
   );
@@ -74,7 +78,7 @@ export function InvitationAcceptPage() {
 
     hasKickedAccept.current = true;
     invitationAccepts
-      .run(token, async () => await runAccept({token, workspaceName: data.workspace_name}))
+      .run(token, async () => await runAccept({token, workspaceName: data.workspaceName}))
       .catch(() => {
         // The mutation surfaces its error via accept.error; the UI re-renders
         // into the auth-match-error state below.
@@ -137,7 +141,7 @@ export function InvitationAcceptPage() {
     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
+          This invitation expired on {formatDate(data.expiresAt)}. Ask your administrator to send a
           new one.
         </Callout>
         <GoHomeButton navigate={navigate} />
@@ -150,12 +154,12 @@ export function InvitationAcceptPage() {
       toast.info(`This invitation has already been accepted.`),
     );
     return (
-      <AuthShell title="Invitation already used" description={data.workspace_name}>
+      <AuthShell title="Invitation already used" description={data.workspaceName}>
         <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}.`}
+            ? `Open your dashboard to access ${data.workspaceName} if your account is a member.`
+            : `Log in to access ${data.workspaceName}.`}
         </Callout>
         {auth.isAuthenticated ? null : (
           <Button asChild className="w-full">
@@ -168,8 +172,8 @@ export function InvitationAcceptPage() {
   }
 
   const inviterLine =
-    data.invited_by_display != null
-      ? `Invited by ${data.invited_by_display} to join as ${data.email}.`
+    data.invitedByDisplay != null
+      ? `Invited by ${data.invitedByDisplay} to join as ${data.email}.`
       : `Invited to join as ${data.email}.`;
 
   if (!auth.isAuthenticated) {
@@ -177,7 +181,7 @@ export function InvitationAcceptPage() {
     const signupHref = `/auth/signup?redirect=${encodeURIComponent(redirect)}`;
     const loginHref = `/auth/login?redirect=${encodeURIComponent(redirect)}`;
     return (
-      <AuthShell title={data.workspace_name} description={inviterLine}>
+      <AuthShell title={data.workspaceName} description={inviterLine}>
         <div className="flex flex-col gap-16">
           <Button asChild className="w-full">
             <Link to={signupHref}>Create account</Link>
@@ -199,7 +203,7 @@ export function InvitationAcceptPage() {
     const redirect = `/invitations/accept?token=${encodeURIComponent(token)}`;
     const logoutHref = `/auth/logout?redirect=${encodeURIComponent(redirect)}`;
     return (
-      <AuthShell title={data.workspace_name} description={inviterLine}>
+      <AuthShell title={data.workspaceName} description={inviterLine}>
         <Callout role="alert" type="warning">
           You're signed in as {auth.user?.email}, but this invitation is for {data.email}.
         </Callout>
@@ -223,15 +227,15 @@ export function InvitationAcceptPage() {
   // result. Show either the pending state or the error state.
   if (accept.isError) {
     return (
-      <AuthShell title={data.workspace_name} description={inviterLine}>
+      <AuthShell title={data.workspaceName} description={inviterLine}>
         <Callout role="alert" type="error">
-          We couldn't add you to {data.workspace_name}. Try again in a moment.
+          We couldn't add you to {data.workspaceName}. Try again in a moment.
         </Callout>
         <Button
           className="w-full"
           isLoading={accept.isPending}
           onClick={() => {
-            runAccept({token, workspaceName: data.workspace_name}).catch(() => {
+            runAccept({token, workspaceName: data.workspaceName}).catch(() => {
               // The mutation state drives the rendered error; avoid an
               // unhandled rejection from the click handler.
             });
@@ -244,11 +248,11 @@ export function InvitationAcceptPage() {
   }
 
   return (
-    <AuthShell title={data.workspace_name} description={inviterLine}>
+    <AuthShell title={data.workspaceName} 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}…
+          Adding you to {data.workspaceName}…
         </Text>
       </div>
     </AuthShell>

package/src/routes/accept.tsx

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

package/src/routes/inputs.test.ts

@@ -0,0 +1,11 @@
+import {validateInvitationAcceptSearch} from './inputs.js';
+
+describe('invitation route inputs', () => {
+  it('accepts a token and drops missing or malformed values', () => {
+    expect(validateInvitationAcceptSearch({token: 'invite-token'})).toEqual({
+      token: 'invite-token',
+    });
+    expect(validateInvitationAcceptSearch({})).toEqual({});
+    expect(validateInvitationAcceptSearch({token: ['invite-token']})).toEqual({});
+  });
+});

package/src/routes/inputs.ts

@@ -0,0 +1,10 @@
+export interface InvitationAcceptSearch {
+  token?: string;
+}
+
+export function validateInvitationAcceptSearch(
+  input: Record<string, unknown>,
+): InvitationAcceptSearch {
+  const token = typeof input.token === 'string' && input.token.length > 0 ? input.token : undefined;
+  return token ? {token} : {};
+}