API Reference

Condensed reference for the TryMellon JavaScript SDK public API.

TryMellon

Main entry point. Create a client with your app configuration. Prefer TryMellon.create() so invalid config returns a Result instead of throwing.

import { TryMellon } from '@trymellon/js';

const clientResult = TryMellon.create({
  appId: 'YOUR_APP_ID',
  publishableKey: 'cli_xxxx',
});
if (!clientResult.ok) throw clientResult.error;
const client = clientResult.value;

TryMellonConfig

Static methods

Deprecated: new TryMellon(config) — throws on invalid config instead of returning a Result. Use TryMellon.create(config) instead.

register(options?)

Registers a new passkey for the user. Returns a Result with sessionToken on success.

const result = await client.register({ externalUserId: 'user_123' });

RegisterOptions

RegisterResult

authenticate(options?)

Authenticates the user with an existing passkey. Returns a Result with sessionToken on success.

const result = await client.authenticate({ externalUserId: 'user_123' });

AuthenticateOptions

AuthenticateResult

validateSession(sessionToken)

Client-side check: validates a session token against the API. Returns a Result indicating whether the session is valid. You must pass the token; the SDK does not read cookies. See Session validation.

const result = await client.validateSession(sessionToken);
if (result.ok && result.value.valid) {
  // Session is valid
}

SessionValidateResponse

Fields are camelCase in the SDK response. The raw REST API returns snake_case fields nested in a data envelope — see Backend validation for the raw HTTP contract.

getStatus()

Returns the client’s WebAuthn environment status. Use to decide whether to offer passkey or email fallback.

const status = await client.getStatus();

ClientStatus

on(event, callback)

Subscribe to SDK events (e.g. for loading spinners or analytics). Returns an unsubscribe function.

const unsub = client.on('success', (payload) => {
  console.log(payload.operation, payload.token);
});
// later: unsub();

Events: start, success, error, cancelled. See Events & Error handling.

fallback.email

Email OTP fallback when WebAuthn is not available.

See Fallback by email.

auth.crossDevice

Cross-device authentication (QR login). Desktop initiates, mobile approves.

See Cross-device auth.

enroll(options)

Enrolls a device or entity using a single-use ticket issued by your backend. Used for the Entity Enrollment (Keys & Padlock) flow.

const result = await client.enroll({ ticketId: 'ticket_xxx' });
if (result.ok) {
  console.log('Session token:', result.value.sessionToken);
}

Returns Result<{ sessionToken: string }, TryMellonError>. See Entity Enrollment.

getContextHash()

Returns the context hash bound to the current browser session. This hash ties an enrollment ticket to a specific client context — pass it when issuing a ticket from your backend so replay on a different origin fails.

const contextHash = client.getContextHash();
// Send to your backend when requesting a ticket

Returns string (64-char hex, SHA-256). Persisted in sessionStorage for the duration of the session.

bridge

Bridge flows for QR-based enrollment and authentication from a second device (e.g. mobile scanning a desktop QR).

See Cross-device auth and Entity Enrollment.

auth.recoverAccount(options)

Recovers an account using an email OTP and creates a new passkey. Requires server-side initiation first.

const result = await client.auth.recoverAccount({
  externalUserId: 'user_123',
  otp: '632145',
});

Returns Result<RecoverAccountResult, TryMellonError>. See Account Recovery.

version()

Returns the SDK version string.

console.log(client.version()); // e.g. '2.3.6'

SANDBOX_SESSION_TOKEN

Exported constant — the fixed token returned in sandbox mode. Use it in your backend to identify sandbox sessions during development.

import { SANDBOX_SESSION_TOKEN } from '@trymellon/js';

Utility exports

Helper functions exported from @trymellon/js:

Web Components

The SDK ships pre-built Web Components in @trymellon/js/ui. See Web Components for full documentation.

<script type="module">
  import '@trymellon/js/ui';
</script>
<trymellon-auth app-id="YOUR_APP_ID" publishable-key="cli_xxxx"></trymellon-auth>

Result type

All async methods that can fail return a Result<T, E>:

Check result.ok before accessing result.value; use !result.ok and result.error for error handling.

TryMellonError

Error codes: NOT_SUPPORTED, USER_CANCELLED, PASSKEY_NOT_FOUND, SESSION_EXPIRED, NETWORK_FAILURE, INVALID_ARGUMENT, TIMEOUT, ABORTED, CHALLENGE_MISMATCH, UNKNOWN_ERROR. See Events & Error handling.