@graph8/sdk 0.370.0 → 0.374.0

package/blocks/pickers/block.json

@@ -0,0 +1,103 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "pickers",
+  "title": "Pickers",
+  "summary": "No raw ids: signed-in member hook plus searchable team-member, contact and company pickers that report the id operations take.",
+  "features": [
+    "useCurrentMember: the signed-in teammate (user id, email, name) from GET /team-members/me",
+    "MemberPicker: searchable team-member select, paged",
+    "ContactPicker: searchable contact select (single or multiple), by name or work email, paged",
+    "CompanyPicker: searchable company select by name or domain, paged",
+    "SearchPicker + usePickerPages: the shell and paging engine to build another picker"
+  ],
+  "dependsOn": [
+    "foundation"
+  ],
+  "operations": [
+    "get_my_team_member_team_members_me_get",
+    "list_companies_companies_get",
+    "list_contacts_contacts_get",
+    "list_team_members_team_members_get"
+  ],
+  "components": [
+    {
+      "name": "SearchPicker",
+      "file": "components/search-picker.tsx",
+      "purpose": "The dropdown shell behind the pickers: trigger, search box, listbox, Show more, loading/empty/error states. Calls no API.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "MemberPicker",
+      "file": "components/member-picker.tsx",
+      "purpose": "Searchable team-member select (paged, fetched on open). Reports the user id operations take, so no screen asks a person to type one.",
+      "operations": [
+        "list_team_members_team_members_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "ContactPicker",
+      "file": "components/contact-picker.tsx",
+      "purpose": "Searchable contact select by name or work email (paged), single or multiple with chips. Reports the contact id, so no screen asks a person to type one.",
+      "operations": [
+        "list_contacts_contacts_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "CompanyPicker",
+      "file": "components/company-picker.tsx",
+      "purpose": "Searchable company select by name or domain (paged). Reports the company id, so no screen asks a person to type one.",
+      "operations": [
+        "list_companies_companies_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    }
+  ],
+  "hooks": [
+    {
+      "name": "useCurrentMember",
+      "file": "hooks/use-current-member.ts",
+      "purpose": "The signed-in team member (user id, email, name) from GET /team-members/me, shared by the dialer, CallContactButton and role/owner defaults. An organisation key has no person: `forbidden` is true and callers offer a MemberPicker.",
+      "operations": [
+        "get_my_team_member_team_members_me_get"
+      ]
+    },
+    {
+      "name": "usePickerPages",
+      "file": "hooks/use-picker-pages.ts",
+      "purpose": "Paging + debounced search engine behind ContactPicker and CompanyPicker: load more appends, a new search starts over, a stale response is dropped."
+    }
+  ],
+  "lib": [
+    {
+      "file": "lib/use-debounced.ts",
+      "purpose": "useDebounced: a value after it stops changing; the search box of every picker reads through it."
+    }
+  ],
+  "recipes": [],
+  "prerequisites": [],
+  "scopes": [
+    "companies:read",
+    "contacts:read",
+    "team:read"
+  ],
+  "defaults": [
+    {
+      "decision": "Which person a screen acts as when nobody passed a user id",
+      "default": "The signed-in team member (a personal API key). An organisation key has no person: ask with MemberPicker",
+      "askHuman": false
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "lucide-react": ">=0.400.0"
+  }
+}

package/blocks/pickers/components/company-picker.tsx

@@ -0,0 +1,90 @@
+"use client";
+
+/**
+ * CompanyPicker: choose a company by name instead of typing a company id. A searchable select over the organisation's
+ * companies; it reports the company (id, name, hint) so a screen can show who was chosen and send the id.
+ *
+ * SDK operations, in order:
+ *   1. GET /companies?name|domain&page&limit   (companies.listCompanies)   read - fetched only once the picker is opened
+ *
+ * Search: a company name (partial match); text that looks like a domain ("acme.com") is looked up as the domain.
+ * Paged with usePickerPages: 25 per page, "Show more" keeps the earlier pages, a new search starts over.
+ */
+import { useState } from "react";
+import { g8Get } from "@/g8/lib/g8-client";
+import { usePickerPages } from "../hooks/use-picker-pages";
+import { SearchPicker } from "./search-picker";
+
+export interface CompanyOption {
+  id: number;
+  name: string;
+  /** Domain and industry: what tells two companies with a similar name apart. */
+  hint?: string;
+}
+
+export interface CompanyPickerProps {
+  value?: CompanyOption | null;
+  onChange: (company: CompanyOption) => void;
+  /** Accessible name and trigger prefix. Default "Company". */
+  label?: string;
+  placeholder?: string;
+  disabled?: boolean;
+  /** Id of the trigger button, so a <label htmlFor> can name it. */
+  id?: string;
+  className?: string;
+}
+
+interface Row { id?: number | null; name?: string | null; domain?: string | null; industry?: string | null }
+
+const PAGE = 25;
+const DOMAIN = /^[^\s@/]+\.[a-z]{2,}$/i;
+
+/** A companies-list row as a selectable option; null without an id. */
+export function toCompanyOption(r: Row): CompanyOption | null {
+  if (r.id == null) return null;
+  const hint = [r.domain, r.industry].filter(Boolean).join(" · ");
+  return { id: r.id, name: r.name || r.domain || `Company ${r.id}`, hint: hint || undefined };
+}
+
+export function CompanyPicker({ value, onChange, label = "Company", placeholder, disabled, id, className }: CompanyPickerProps) {
+  const [open, setOpen] = useState(false);
+  const pages = usePickerPages<CompanyOption>(open, async (q, page, signal) => {
+    const filter = DOMAIN.test(q) ? { domain: q.toLowerCase() } : { name: q || undefined };
+    const env = await g8Get("/companies", { ...filter, page, limit: PAGE }, { signal });
+    const rows = ((env.data ?? []) as Row[]).map(toCompanyOption).filter((o): o is CompanyOption => o !== null);
+    const has = (env.pagination as { has_next?: boolean } | undefined)?.has_next;
+    return { rows, hasNext: has ?? rows.length >= PAGE };
+  });
+  const pick = (key: string) => {
+    const c = pages.rows.find((r) => String(r.id) === key);
+    if (!c) return;
+    setOpen(false);
+    pages.setSearch("");
+    onChange(c);
+  };
+  return (
+    <SearchPicker
+      label={label}
+      id={id}
+      className={className}
+      disabled={disabled}
+      placeholder={placeholder}
+      searchPlaceholder="Search by name or domain"
+      triggerContent={value ? <span>{value.name}</span> : undefined}
+      options={pages.rows.map((r) => ({ key: String(r.id), label: r.name, hint: r.hint }))}
+      selectedKeys={new Set(value ? [String(value.id)] : [])}
+      onSelect={pick}
+      search={pages.search}
+      onSearchChange={pages.setSearch}
+      open={open}
+      onOpenChange={setOpen}
+      loading={pages.loading}
+      error={pages.error}
+      onRetry={pages.refetch}
+      hasMore={pages.hasMore}
+      loadingMore={pages.loadingMore}
+      onLoadMore={pages.loadMore}
+      emptyText={pages.q ? "No company matches that search." : "No companies yet."}
+    />
+  );
+}

package/blocks/pickers/components/contact-picker.tsx

@@ -0,0 +1,131 @@
+"use client";
+
+/**
+ * ContactPicker: choose one or several contacts by name instead of typing contact ids. A searchable select over the
+ * organisation's contacts; it reports the contact (id, name, hint), so a screen can show who was chosen and send the id.
+ *
+ * SDK operations, in order:
+ *   1. GET /contacts?name|email&page&limit   (contacts.listContacts)   read - fetched only once the picker is opened
+ *
+ * Search: a first or last name (partial match); text containing "@" is looked up as a work email (exact match).
+ * Paged (usePickerPages): 25 contacts per page, "Show more" loads the next page and keeps the earlier ones; a new search
+ * starts over and an out-of-date response never lands. Locked emails and phones come back as "***" and are never shown.
+ * `multiple` keeps the panel open and shows the chosen contacts as removable chips.
+ */
+import { useState } from "react";
+import { X } from "lucide-react";
+import { g8Get } from "@/g8/lib/g8-client";
+import { usePickerPages } from "../hooks/use-picker-pages";
+import { SearchPicker } from "./search-picker";
+
+/** One selectable contact. */
+export interface ContactOption {
+  id: number;
+  name: string;
+  /** Job title and company, or the work email: what tells two people with the same name apart. */
+  hint?: string;
+}
+
+export interface ContactPickerProps {
+  /** Single mode: the chosen contact (controlled). */
+  value?: ContactOption | null;
+  /** Single mode: called with the contact the person chose. */
+  onChange?: (contact: ContactOption) => void;
+  /** Several contacts: tick as many as needed. Use `selected` and `onSelectedChange`. */
+  multiple?: boolean;
+  selected?: ContactOption[];
+  onSelectedChange?: (contacts: ContactOption[]) => void;
+  /** Accessible name and trigger prefix. Default "Contact". */
+  label?: string;
+  placeholder?: string;
+  disabled?: boolean;
+  /** Id of the trigger button, so a <label htmlFor> can name it. */
+  id?: string;
+  className?: string;
+}
+
+interface Row {
+  id?: number | null;
+  first_name?: string | null;
+  last_name?: string | null;
+  job_title?: string | null;
+  company_name?: string | null;
+  work_email?: string | null;
+}
+
+const PAGE = 25;
+const real = (v?: string | null): string => (v && !v.includes("*") ? v.trim() : "");
+
+/** A contacts-list row as a selectable option; null without an id. */
+export function toContactOption(r: Row): ContactOption | null {
+  if (r.id == null) return null;
+  const email = real(r.work_email);
+  const name = [real(r.first_name), real(r.last_name)].filter(Boolean).join(" ") || email || `Contact ${r.id}`;
+  const where = [real(r.job_title), real(r.company_name)].filter(Boolean).join(" at ");
+  return { id: r.id, name, hint: where || (email && email !== name ? email : undefined) };
+}
+
+export function ContactPicker(props: ContactPickerProps) {
+  const { value, onChange, multiple, selected = [], onSelectedChange, label = "Contact", placeholder, disabled, id, className } = props;
+  const [open, setOpen] = useState(false);
+  const pages = usePickerPages<ContactOption>(open, async (q, page, signal) => {
+    const filter = q.includes("@") ? { email: q } : { name: q || undefined };
+    const env = await g8Get("/contacts", { ...filter, page, limit: PAGE }, { signal });
+    const rows = ((env.data ?? []) as Row[]).map(toContactOption).filter((o): o is ContactOption => o !== null);
+    const has = (env.pagination as { has_next?: boolean } | undefined)?.has_next;
+    return { rows, hasNext: has ?? rows.length >= PAGE };
+  });
+  const { rows, q } = pages;
+  const byId = new Map(rows.map((r) => [String(r.id), r]));
+  const chosenKeys = new Set((multiple ? selected : value ? [value] : []).map((c) => String(c.id)));
+
+  const toggle = (key: string) => {
+    const c = byId.get(key) ?? [...selected, ...(value ? [value] : [])].find((x) => String(x.id) === key);
+    if (!c) return;
+    if (multiple) {
+      onSelectedChange?.(chosenKeys.has(key) ? selected.filter((x) => String(x.id) !== key) : [...selected, c]);
+      return;
+    }
+    setOpen(false);
+    pages.setSearch("");
+    onChange?.(c);
+  };
+  return (
+    <div className={`flex flex-col gap-2 ${className ?? ""}`}>
+      <SearchPicker
+        label={label}
+        id={id}
+        disabled={disabled}
+        placeholder={placeholder ?? (multiple ? "Add contacts" : undefined)}
+        searchPlaceholder="Search by name or work email"
+        triggerContent={!multiple && value ? <span>{value.name}</span> : undefined}
+        options={rows.map((r) => ({ key: String(r.id), label: r.name, hint: r.hint }))}
+        selectedKeys={chosenKeys}
+        onSelect={toggle}
+        search={pages.search}
+        onSearchChange={pages.setSearch}
+        open={open}
+        onOpenChange={setOpen}
+        loading={pages.loading}
+        error={pages.error}
+        onRetry={pages.refetch}
+        hasMore={pages.hasMore}
+        loadingMore={pages.loadingMore}
+        onLoadMore={pages.loadMore}
+        emptyText={q ? "No contact matches that search." : "No contacts yet."}
+      />
+      {multiple && selected.length > 0 ? (
+        <ul aria-label={`Chosen ${label.toLowerCase()}s`} className="flex flex-wrap gap-1">
+          {selected.map((c) => (
+            <li key={c.id} className="flex items-center gap-1 rounded-full border border-border bg-muted px-2 py-0.5 text-xs">
+              <span>{c.name}</span>
+              <button type="button" aria-label={`Remove ${c.name}`} className="text-muted-foreground hover:text-foreground" disabled={disabled} onClick={() => onSelectedChange?.(selected.filter((x) => x.id !== c.id))}>
+                <X className="size-3" aria-hidden />
+              </button>
+            </li>
+          ))}
+        </ul>
+      ) : null}
+    </div>
+  );
+}

package/blocks/pickers/components/member-picker.tsx

@@ -0,0 +1,99 @@
+"use client";
+
+/**
+ * MemberPicker: choose a teammate by name instead of typing a user id. A searchable select over the organisation's
+ * team; the value it reports is the user id the API operations take (a dialer rep, a record owner, a role holder).
+ *
+ * SDK operations, in order:
+ *   1. GET /team-members?search&status&limit   (teamMembers.listTeamMembers)   read - fetched only once the picker is opened
+ *
+ * Paged: it loads 25 people and "Show more" asks for the next 25 (the search box narrows by name or email). People
+ * without a user id (a roster row that never signed in) are left out, because no operation could take them.
+ * A 403 (a key that may not read the team) shows a plain note instead of an error panel; the caller keeps its own
+ * fallback, usually the signed-in member from `useCurrentMember`.
+ */
+import { useState } from "react";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useDebounced } from "../lib/use-debounced";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { memberRecordsOf, toMemberOption } from "../hooks/use-current-member";
+import type { MemberOption } from "../hooks/use-current-member";
+import { SearchPicker } from "./search-picker";
+
+export type { MemberOption } from "../hooks/use-current-member";
+
+export interface MemberPickerProps {
+  /** The selected user id (controlled). */
+  value?: string | null;
+  onChange: (member: MemberOption) => void;
+  /** What to show for `value` when that person is not on the loaded page (for example the current holder of a role). */
+  selectedName?: string | null;
+  /** Accessible name and trigger prefix. Default "Team member". */
+  label?: string;
+  placeholder?: string;
+  disabled?: boolean;
+  /** Id of the trigger button, so a <label htmlFor> can name it. */
+  id?: string;
+  className?: string;
+}
+
+const PAGE = 25;
+
+export function MemberPicker({ value, onChange, selectedName, label = "Team member", placeholder, disabled, id, className }: MemberPickerProps) {
+  const [open, setOpen] = useState(false);
+  const [search, setSearch] = useState("");
+  const [limit, setLimit] = useState(PAGE);
+  const [chosen, setChosen] = useState<MemberOption | null>(null);
+  const q = useDebounced(search.trim());
+  const query = useG8Query(
+    async (signal) => {
+      const env = await g8Get("/team-members", { search: q || undefined, status: "active", limit, offset: 0 }, { signal });
+      const records = memberRecordsOf(env);
+      // `raw` is what the API returned, before any filtering here: "Show more" asks for more when the page was full.
+      const active = records.filter((m) => !m.status || m.status === "active");
+      return { rows: active.map(toMemberOption).filter((o): o is MemberOption => o !== null), raw: records.length };
+    },
+    [q, limit],
+    { enabled: open },
+  );
+  const rows = query.data?.rows ?? [];
+  const status = (query.error as { status?: number } | undefined)?.status;
+  const forbidden = status === 403;
+  const shown = rows.find((m) => m.id === value) ?? (chosen?.id === value ? chosen : null);
+  const name = shown?.name ?? selectedName ?? value ?? null;
+
+  const pick = (id: string) => {
+    const member = rows.find((m) => m.id === id);
+    if (!member) return;
+    setChosen(member);
+    setOpen(false);
+    setSearch("");
+    onChange(member);
+  };
+  return (
+    <SearchPicker
+      label={label}
+      id={id}
+      className={className}
+      disabled={disabled}
+      placeholder={placeholder}
+      searchPlaceholder="Search by name or email"
+      triggerContent={name ? <span>{name}</span> : undefined}
+      options={rows.map((m) => ({ key: m.id, label: m.name, hint: m.email }))}
+      selectedKeys={new Set(value ? [value] : [])}
+      onSelect={pick}
+      search={search}
+      onSearchChange={(v) => { setSearch(v); setLimit(PAGE); }}
+      open={open}
+      onOpenChange={setOpen}
+      loading={query.loading}
+      error={forbidden ? undefined : query.error}
+      onRetry={() => void query.refetch()}
+      errorOverride={forbidden ? <p role="status" className="p-2 text-sm text-muted-foreground">This API key cannot read the team list.</p> : undefined}
+      hasMore={(query.data?.raw ?? 0) >= limit}
+      loadingMore={query.loading && rows.length > 0}
+      onLoadMore={() => setLimit((l) => l + PAGE)}
+      emptyText={q ? "Nobody matches that search." : "No team members yet."}
+    />
+  );
+}

package/blocks/pickers/components/search-picker.tsx

@@ -0,0 +1,98 @@
+"use client";
+
+/**
+ * SearchPicker: the dropdown shell behind MemberPicker and ContactPicker. A trigger button opens a panel with a search
+ * box, a listbox of options, a "Show more" pager and the loading / empty / error states. It owns no data: the caller
+ * passes the options and the search text, so any lookup (team members, contacts, ...) reuses one accessible widget.
+ *
+ * It calls no API itself. Closing: Escape, a click outside, or (single mode) choosing an option. In `multiple` mode the
+ * panel stays open so several options can be ticked.
+ */
+import { useEffect, useRef } from "react";
+import type { ReactNode } from "react";
+import { Check, ChevronDown } from "lucide-react";
+import { Button, Input } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+
+export interface SearchPickerOption {
+  key: string;
+  label: string;
+  /** A second muted line: a job title, an email. */
+  hint?: string | null;
+}
+
+export interface SearchPickerProps {
+  /** Accessible name of the whole control ("Team member", "Contact"). */
+  label: string;
+  /** What the closed trigger shows; defaults to the placeholder. */
+  triggerContent?: ReactNode;
+  placeholder?: string;
+  searchPlaceholder?: string;
+  options: SearchPickerOption[];
+  selectedKeys: ReadonlySet<string>;
+  onSelect: (key: string) => void;
+  search: string;
+  onSearchChange: (value: string) => void;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  loading?: boolean;
+  error?: unknown;
+  onRetry?: () => void;
+  hasMore?: boolean;
+  loadingMore?: boolean;
+  onLoadMore?: () => void;
+  /** Shown instead of the list when there is nothing to pick. */
+  emptyText?: string;
+  /** Replaces the error panel for an expected refusal (for example a 403 on the team list). */
+  errorOverride?: ReactNode;
+  disabled?: boolean;
+  /** Id of the trigger button, so a <label htmlFor> can name it. */
+  id?: string;
+  className?: string;
+}
+
+export function SearchPicker(props: SearchPickerProps) {
+  const { label, open, onOpenChange, options, selectedKeys, loading, error, disabled, className } = props;
+  const root = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    if (!open) return;
+    const away = (e: MouseEvent) => { if (root.current && !root.current.contains(e.target as Node)) onOpenChange(false); };
+    document.addEventListener("mousedown", away);
+    return () => document.removeEventListener("mousedown", away);
+  }, [open, onOpenChange]);
+
+  const empty = !loading && !error && options.length === 0;
+  return (
+    <div ref={root} className={`relative inline-block min-w-48 ${className ?? ""}`} onKeyDown={(e) => { if (e.key === "Escape" && open) { e.stopPropagation(); onOpenChange(false); } }}>
+      <Button id={props.id} type="button" variant="outline" size="sm" className="w-full justify-between" disabled={disabled} aria-label={label} aria-haspopup="listbox" aria-expanded={open} onClick={() => onOpenChange(!open)}>
+        <span className="truncate">{props.triggerContent ?? <span className="text-muted-foreground">{props.placeholder ?? `Choose ${label.toLowerCase()}`}</span>}</span>
+        <ChevronDown className="ml-2 size-4 shrink-0 text-muted-foreground" aria-hidden />
+      </Button>
+      {open ? (
+        <div className="absolute left-0 z-50 mt-1 flex w-72 max-w-[90vw] flex-col gap-2 rounded-md border border-border bg-background p-2 shadow-md">
+          <Input autoFocus aria-label={`Search ${label.toLowerCase()}`} placeholder={props.searchPlaceholder ?? "Search"} value={props.search} onChange={(e) => props.onSearchChange(e.target.value)} />
+          {props.errorOverride ?? (error ? <ApiError error={error} title={`Could not load ${label.toLowerCase()} options`} onRetry={props.onRetry} /> : null)}
+          <ul role="listbox" aria-label={label} className="max-h-56 overflow-y-auto">
+            {loading && options.length === 0 ? <li className="p-2 text-sm text-muted-foreground">Loading...</li> : null}
+            {empty ? <li className="p-2 text-sm text-muted-foreground">{props.emptyText ?? "Nothing matches."}</li> : null}
+            {options.map((o) => {
+              const on = selectedKeys.has(o.key);
+              return (
+                <li key={o.key} role="none">
+                  <button type="button" role="option" aria-selected={on} className={`flex w-full items-center gap-2 rounded-sm px-2 py-1.5 text-left text-sm hover:bg-accent ${on ? "bg-accent font-medium" : ""}`} onClick={() => props.onSelect(o.key)}>
+                    <span className="flex min-w-0 flex-1 flex-col">
+                      <span className="truncate">{o.label}</span>
+                      {o.hint ? <span className="truncate text-xs text-muted-foreground">{o.hint}</span> : null}
+                    </span>
+                    {on ? <Check className="size-4 shrink-0" aria-hidden /> : null}
+                  </button>
+                </li>
+              );
+            })}
+          </ul>
+          {props.hasMore ? <Button type="button" variant="ghost" size="sm" loading={props.loadingMore} onClick={props.onLoadMore}>Show more</Button> : null}
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/blocks/pickers/hooks/use-current-member.ts

@@ -0,0 +1,104 @@
+"use client";
+
+/**
+ * useCurrentMember: the signed-in team member, so no screen has to ask a person for their own user id.
+ *
+ * It is the ONE place that resolves "who am I" for a PERSONAL API key: the dialer's rep, a record owner default and
+ * CallContactButton all read it, so they cannot drift apart. An organisation key has no person: the API answers 403
+ * and `member` stays null (`forbidden: true`); callers then offer a MemberPicker instead of a text box.
+ *
+ * SDK operations, in order:
+ *   1. GET /team-members/me   (teamMembers.getMyTeamMember)   read - the roster record of the person who minted the key
+ *
+ * `userId` is the identity-provider user id (`propelauth_user_id`): the id the dialer's softphone credential, session
+ * drafts and record roles take. `email` is the matching rep email; both describe the same person.
+ */
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+
+/** A roster record as the team-members endpoints answer it (the API may return more). */
+export interface TeamMemberRecord {
+  id?: string | null;
+  name?: string | null;
+  first_name?: string | null;
+  last_name?: string | null;
+  email?: string | null;
+  propelauth_user_id?: string | null;
+  status?: string | null;
+  role?: string | null;
+}
+
+/** One selectable person. `id` is the identity-provider user id, the value every id-taking operation wants. */
+export interface MemberOption {
+  id: string;
+  name: string;
+  email?: string | null;
+}
+
+/** The API envelope's `data`, or the value itself when it was already unwrapped. */
+export function unwrapData<T>(env: unknown): T {
+  const o = env as { data?: unknown } | null | undefined;
+  return (o && typeof o === "object" && "data" in o ? o.data : env) as T;
+}
+
+/** A roster record as a selectable person; null when it has no user id (it cannot be a rep or an owner). */
+export function toMemberOption(m: TeamMemberRecord | null | undefined): MemberOption | null {
+  const id = m?.propelauth_user_id;
+  if (!m || !id) return null;
+  const full = [m.first_name, m.last_name].filter(Boolean).join(" ");
+  return { id, name: m.name || full || m.email || id, email: m.email };
+}
+
+/** The list endpoints answer a bare array, or an object with `items` / `team_members`. */
+export function memberRecordsOf(env: unknown): TeamMemberRecord[] {
+  const inner = unwrapData<unknown>(env);
+  if (Array.isArray(inner)) return inner as TeamMemberRecord[];
+  const o = inner as { items?: unknown; team_members?: unknown } | null;
+  const list = o?.items ?? o?.team_members;
+  return Array.isArray(list) ? (list as TeamMemberRecord[]) : [];
+}
+
+/** The signed-in member's record, or null. A 403 (organisation key) and a 404 both read as "no person". */
+export async function fetchCurrentMember(signal?: AbortSignal): Promise<TeamMemberRecord | null> {
+  return unwrapData<TeamMemberRecord | null>(await g8Get("/team-members/me", undefined, { signal })) ?? null;
+}
+
+export interface UseCurrentMemberOptions {
+  /** Set false to hold the request (for example when the caller already passed a `userId`). Default true. */
+  enabled?: boolean;
+}
+
+export interface CurrentMember {
+  /** The signed-in person as a selectable option; null for an organisation key, while loading, or on failure. */
+  member: MemberOption | null;
+  /** `propelauth_user_id`: what the dialer, softphone and role assignments take. */
+  userId?: string;
+  email?: string;
+  name?: string;
+  /** The raw roster record (role, status ...), for callers that need more than the id. */
+  record: TeamMemberRecord | null;
+  loading: boolean;
+  /** The key is an organisation key: it has no person, so ask with a MemberPicker. */
+  forbidden: boolean;
+  /** Any failure other than the expected 403/404 of an organisation key. */
+  error: unknown;
+}
+
+export function useCurrentMember(options: UseCurrentMemberOptions = {}): CurrentMember {
+  const enabled = options.enabled ?? true;
+  const q = useG8Query((signal) => fetchCurrentMember(signal), [], { enabled });
+  const status = (q.error as { status?: number } | undefined)?.status;
+  const refusal = status === 403 || status === 404;
+  const record = enabled ? (q.data ?? null) : null;
+  const member = toMemberOption(record);
+  return {
+    member,
+    userId: member?.id,
+    email: record?.email ?? undefined,
+    name: member?.name,
+    record,
+    loading: enabled && q.loading && !q.data,
+    forbidden: enabled && status === 403,
+    error: enabled && q.error && !refusal ? q.error : undefined,
+  };
+}