dolfindevelopers

Gmail connections panel

ComponentPayablesSDK + UI

Bills from Gmail: Connect a mailbox, the connected mailboxes with their status, Sync, Backfill and Disconnect (asking first), and the selected mailbox's attachments that look like bills, filtered by state and paged, to Import (they become bills) or Dismiss. By default it runs the useGmail hooks and handles the return from Google; or pass your own connections or candidates (either selects data mode and fetches nothing).

Component: A piece you place inside your own screens: a table, a form, a card or a dialog. You decide the layout around it. Pages vs components

Choose your integration

Ready to connect to Dolfin. Loads data through SDK hooks, with appearance and behaviour you can customise. Requires DolfinProvider.

Loading preview…

Installation

Needs the Dolfin registry token. The CLI copies the source into your app.

Terminal
bunx --bun shadcn@4.23.0 add @dolfin/ap-gmail-connections-panel

Also installs: button, popover, base-info-hint, base-states, base-status-badge, base-theme, ui-ap-gmail-connections-panel.

Usage

screen.tsx
import { GmailConnectionsPanel } from "@/components/dolfin/ap/gmail-connections-panel";

// Place it anywhere inside your <DolfinProvider>.
<GmailConnectionsPanel />

Renders inside DolfinProvider (set it up once). By default it loads its own data through the SDK. Supplied-data examples show how to override that behavior.

API reference

PropTypeDescription
connectionsreadonly { id: string; emailAddress: string; status: components["schemas"]["GmailConnectionStatus"]; lastSyncedAt?: null | string; backfille…Your mailboxes. The panel's data is `connections` and `candidates`: passing either (or their `loading` or `error`) fetches nothing, and buttons show only with their callbacks.
loadingboolean
errorError
onRetry() => void
candidatesreadonly { id: string; gmailConnectionId: string; messageInternalDate: string; senderEmail?: null | string; subject?: null | string; fileNam…The selected mailbox's attachments. Passing them selects data mode too; without them, the attachments list hides.
candidatesLoadingboolean
candidatesErrorError
onCandidatesRetry() => void
selectedConnectionIdstringThe mailbox whose attachments show. Uncontrolled, the first mailbox until one is picked.
onSelectConnection(connectionId: string) => void
candidateState"Candidate" | "Imported" | "Dismissed" | "Failed" | "Filtered" | "All"Which attachments show. Uncontrolled, "To review" until another is picked.
onCandidateStateChange(state: GmailCandidateStateFilter) => void
pagenumberAttachment paging (1-based).
hasNextPageboolean
onPageChange(page: number) => void
onConnect() => voidShows Connect a mailbox. By default it sends the browser to Google and back to this page.
connectDisabledReasonstringYours wins (`""` = enabled); by id, `undefined` means the SDK's reason for the user's role.
onSync(connectionId: string) => void
onBackfill(connectionId: string) => void
onDisconnect(connectionId: string) => voidShows Disconnect. By id the SDK's own asks first; yours replaces it, confirmation included, and runs at once.
onImport(candidateId: string) => void
onDismiss(candidateId: string) => void
pendingIdstringThe mailbox or attachment being worked on.
pendingActionGmailAction
noticestring | number | bigint | boolean | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<ReactNode> | React.Re…A message above the mailboxes, such as the outcome of connecting. By default, the return from Google.
hideHeaderbooleanHides the title, description and Connect button (for a page that has its own header).
classNamestring

Customisation

Without editing the source, you can change:

Class names
className
Messages
ap.gmailbase.infoHint.moreAboutbase.states.retrybase.states.staleErrorcore.errors

Or edit the installed file directly: it is your code. See theming for colours and fonts.

Hooks

The SDK hooks this component uses. Use them directly from @dolfinai/react to build your own version.

useDolfinLocaleuseGmailActionsuseGmailCandidatesuseGmailConnectReturnuseGmailConnectionsuseMessagesusePermissions

Files

Written to your app by the install command:

  • components/dolfin/ap/gmail-connections-panel.tsx 202 lines
  • components/dolfin/ap/gmail-panel-parts.tsx 141 lines