@sendity/client 0.3.3

Framework-agnostic Custom Element for Sendity channel-control authentication. The package registers <sendity-auth> and contains its complete UI, state machine, QR generation, realtime/polling transport, session handoff, and Shadow DOM styles.

Install

npm install @sendity/[email protected]

Import the package once in the frontend entry point and render the element:

import '@sendity/client'

<sendity-auth public-key="pk_live_..."></sendity-auth>

server-url defaults to the hosted https://sendity.io/api endpoint.

Runtime lifecycle

The client uses one card and one drawer for every UI state: loading, waiting, warning, error, expired, and verified.

1. Before its first API request, the element renders representative prompt and drawer combinations into an invisible measurement stage.
2. The largest result becomes the fixed shell height. A ResizeObserver repeats the measurement when the host width changes.
3. The client creates or resumes an AuthRequest, renders the server-owned verification action, and generates its QR code from the unchanged server URL.
4. transport="auto" subscribes to realtime events and falls back to polling when setup, connection, or private-channel subscription fails. transport="push" reports those failures as the Error state.
5. Verification rejection keeps the active challenge and enters Warning. Expiry keeps the old code visible and offers a new AuthRequest.
6. .verification.received or a polled status: "received" enters the processing form of Verified; .authenticated closes the drawer and triggers the same-origin session handoff or public browser event.

Temporary AuthRequest credentials are scoped by server and public key and stored only in sessionStorage.

Realtime uses the WebSocket-only Pusher worker runtime. The browser bundle contains no third-party dependency loader and never downloads executable JavaScript from a CDN. auto mode still falls back to the built-in polling implementation when WebSocket setup or connectivity fails.

Attributes

| Attribute | Required | Description | |---|---:|---| | public-key | yes | Public Sendity application key. It is optional only in demo-mode. | | server-url | no | API root; defaults to https://sendity.io/api. | | lang | no | Language hint. The bundled fallback copy is English; hosts localize the component through translations. | | translations | no | JSON object with optional lang, dir, ui, and templates overrides. Hosts such as WordPress supply locale-pack translations without rebuilding this package. Unknown keys, invalid JSON, oversized payloads, and non-string values are ignored. | | transport | no | auto (default), polling, or push. | | authenticated-event-delay-ms | no | Delay before handoff/authenticated events; defaults to 2000. | | variant | no | card (default) or modal. | | position | no | Vertical expansion alignment: top (card default), center, or bottom. For modals it also controls dialog placement, with center as the modal default. | | modal-position | no | Deprecated alias for modal position. | | open | no | Opens a modal variant. The open(), close(), and toggle() methods are equivalent controls. | | no-close-on-backdrop | no | Prevents modal backdrop clicks from closing the element. | | no-close-on-escape | no | Prevents Escape from closing the modal. | | data-theme | no | light or dark; otherwise the OS preference and a surrounding .dark class are respected. |

Server response contract

Create and status responses provide one server-owned verification action:

{
  "verification_action": {
    "channel": "email",
    "recipient": "[email protected]",
    "url": "mailto:[email protected]?subject=SDY-ABC-123&body=Send%20this%20email%2C%20then%20return%20to%20example.com."
  }
}

A Phone/RCS action retains the SMS fallback recipient and RCS service identifier:

{
  "verification_action": {
    "channel": "phone",
    "recipient": "+4915888620026",
    "rcs_recipient": "[email protected]",
    "url": "sms:+4915888620026?service_id=sendity_agent%40rbm.goog&body=SDY-ABC-123%20-%20send%20this%2C%20then%20return%20to%20example.com."
  }
}

• channel is email or phone.
• recipient is the human-readable email or SMS/fallback destination rendered in the prompt.
• A Phone action may additionally contain rcs_recipient, the server-provided Twilio/Google RBM agent or service identifier. The Client keeps it in the action link but renders only the mobile number as recipient.
• url is the complete server-owned action URL, including subject/body, RCS service_id, and fallback parameters where applicable. The client uses it byte-for-byte for the action button and QR code and never reconstructs or modifies it.
• verification_endpoints and verify_urls are not part of the 0.3 response contract.
• broadcasting enables the Reverb/Pusher-compatible private channel.
• session_handoff_url may enable a same-origin handoff. The client rejects cross-origin handoff URLs and redirect responses.

Events

The element emits bubbling, composed CustomEvents:

• sendity:ready
• sendity:challenge-created
• sendity:state-change
• sendity:transport-fallback
• sendity:verification-rejected
• sendity:expired
• sendity:session-authenticated
• sendity:authenticated
• sendity:error
• sendity:opened
• sendity:closed

sendity:authenticated includes signedResult only when no session handoff is used. After a successful handoff, public event details omit the signed token and include handoff: "completed".

Visual system

All component CSS is inlined in the Shadow DOM. Consumers do not load Tailwind or a second stylesheet. The component has one shared token contract for every state:

sendity-auth {
  --sendity-backdrop-blur: 10px;
  --sendity-card-background-color: #f5f5f4;
  --sendity-card-background-opacity: 80%;
  --sendity-icon-background-color: #fafaf9;
  --sendity-icon-background-opacity: 80%;
  --sendity-border-color: rgb(0 0 0 / .075);
  --sendity-drawer-background-color: #292524;
  --sendity-foreground-color: #1c1917;
  --sendity-muted-foreground-color: #44403c;
  --sendity-drawer-foreground-color: #e7e5e4;
  --sendity-ui-primary: #10b981;
  --sendity-ui-neutral: #292524;
  --sendity-ui-success: #10b981;
  --sendity-ui-error: #f43f5e;
  --sendity-border-radius: 1rem;
  --sendity-button-border-radius: .56rem;
  --sendity-button-inset-shadow: inset 0 1px 0 rgb(255 255 255 / .18), inset 0 -1px 0 rgb(0 0 0 / .055);
  --sendity-button-foreground-color: #fff;
  --sendity-button-shadow: 0 1px 2px rgb(28 25 23 / .13);
  --sendity-drop-shadow: 0 22px 34px rgb(28 25 23 / .18), 0 8px 14px rgb(28 25 23 / .10);
}

Card radius is clamped to .25rem–2rem; button radius is clamped to 0–2rem. The card border and icon/prompt divider always use the same --sendity-border-color.

The host is fluid up to 26rem. At 345px and above, Waiting and Warning reveal the QR code; narrower layouts retain the state icon and app action. The QR is black on transparent in light mode and white on transparent in dark mode.

Local state lab

npm install
npm run dev -- --host 127.0.0.1

Open http://127.0.0.1:5173/. The state lab drives the production renderer without API, WebSocket, polling, handoff, or app-opening requests. Its preview-only attributes are:

• demo-mode
• demo-state="loading|waiting|warning|error|expired|verified"
• demo-channel="email|phone"
• demo-drawer="closed|instruction|ready|countdown|processing"

Verification

npm test
npm run build