useInviteLinks

Location: src/hooks/useInviteLinks.js

Overview

This file exports four items for the invite-only signup system:

• useInviteLinks -- manage the current user's invite links (create, revoke, list)
• useInviteLookup -- look up an invite code to validate it (for the signup flow)
• useInviteOnSignup -- consume an invite code during the registration process
• getInviteUrl -- utility function to build a shareable invite URL

Each user can have up to 10 active invite links at a time.

---

useInviteLinks

Signature

function useInviteLinks(): {
  invites: InviteRow[],
  activeInvites: InviteRow[],
  usedInvites: InviteRow[],
  loading: boolean,
  error: string | null,
  createInvite: (note?: string | null, intendedFor?: string | null) => Promise<{ success: boolean, data?: InviteRow, error?: string }>,
  revokeInvite: (inviteId: string) => Promise<{ success: boolean, error?: string }>,
  refetch: () => Promise<void>,
  canCreateMore: boolean,
  activeCount: number,
  maxInvites: number
}

Parameters

None. Automatically resolves the current authenticated user via the get_my_invite_links RPC function.

Return Value

Property	Type	Description
invites	InviteRow[]	All invite links for the current user (active, used, revoked, expired).
activeInvites	InviteRow[]	Only active, non-expired invites.
usedInvites	InviteRow[]	Invites that have been used by someone signing up.
loading	boolean	true while the fetch is in progress.
error	string | null	Error message if the fetch failed.
createInvite	(note?, intendedFor?) => Promise	Create a new invite link. note is an optional personal note (e.g. "For my friend Sarah"). intendedFor is an optional name of the intended recipient. Calls the create_invite_link RPC.
revokeInvite	(inviteId) => Promise	Revoke an active invite link. Calls the revoke_invite_link RPC.
refetch	() => Promise<void>	Re-fetch all invites.
canCreateMore	boolean	true if the user has fewer than 10 active invites.
activeCount	number	Number of currently active invites.
maxInvites	number	Maximum allowed active invites (currently 10).

Usage

function InviteManager() {
  const { activeInvites, loading, createInvite, revokeInvite, canCreateMore } = useInviteLinks();

  const handleCreate = async () => {
    const { success, error } = await createInvite('For my friend');
    if (!success) console.error(error);
  };

  if (loading) return <Skeleton />;

  return (
    <div>
      <button onClick={handleCreate} disabled={!canCreateMore}>
        Create Invite Link
      </button>
      {activeInvites.map(invite => (
        <div key={invite.id}>
          <code>{getInviteUrl(invite.code)}</code>
          <button onClick={() => revokeInvite(invite.id)}>Revoke</button>
        </div>
      ))}
    </div>
  );
}

---

useInviteLookup

Signature

function useInviteLookup(
  code?: string | null
): {
  invite: InviteLookupResult | null,
  loading: boolean,
  error: string | null,
  isValid: boolean,
  lookupInvite: (inviteCode: string) => Promise<void>
}

Parameters

Parameter	Type	Required	Description
code	string | null	No	An invite code to automatically look up when the value changes.

Return Value

Property	Type	Description
invite	InviteLookupResult | null	The lookup result if the code is valid, or null if invalid/not found.
loading	boolean	true while the lookup is in progress.
error	string | null	Error message if the code is invalid, expired, or not found.
isValid	boolean	true if the invite code is valid and can be used.
lookupInvite	(inviteCode: string) => Promise<void>	Manually trigger a lookup for a specific code.

Usage

function JoinPage({ inviteCode }) {
  const { invite, isValid, loading, error } = useInviteLookup(inviteCode);

  if (loading) return <Skeleton />;
  if (!isValid) return <p>Invalid invite: {error}</p>;

  return <p>You were invited by {invite.inviter_name}!</p>;
}

---

useInviteOnSignup

Signature

function useInviteOnSignup(): {
  useInvite: (code: string, newUserId: string) => Promise<{ success: boolean, error?: string }>,
  processing: boolean,
  error: string | null
}

Parameters

None.

Return Value

Property	Type	Description
useInvite	(code, newUserId) => Promise	Consume an invite code during signup. Links the new user to the inviter. Calls the use_invite RPC.
processing	boolean	true while the invite is being consumed.
error	string | null	Error message if the operation failed.

---

getInviteUrl

Signature

function getInviteUrl(code: string): string

A pure utility function (not a hook) that builds a full invite URL from a code.

Parameter	Type	Required	Description
code	string	Yes	The invite code.

Returns a URL in the format {origin}/join/{code}. Falls back to https://commonplace.app if window.location.origin is unavailable.

---

Last updated: 2026-02-07