JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 9
  • Score
    100M100P100Q37946F

TrustLabs SDK for displaying trust verification badges

Package Exports

  • trustlabs-sdk
  • trustlabs-sdk/client

Readme

TrustLabs SDK

A JavaScript SDK for displaying trust verification badges on your website.

Installation

npm install trustlabs-sdk

Usage

Required setup: Server proxy via setProxy

You must configure a server proxy. API keys are always required and must only be used on the server (never in the browser).

// app/providers.tsx or a top-level client init
import { setProxy } from 'trustlabs-sdk';

setProxy(async (emails) => {
  const resp = await fetch('/api/trust-status', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ emails })
  });
  if (!resp.ok) throw new Error('Proxy error');
  return await resp.json(); // should be TrustStatus[]
});

Example Next.js route (app/api/trust-status/route.ts):

import { NextResponse } from 'next/server';

export async function POST(req: Request) {
  const { emails } = await req.json();
  const apiKey = process.env.TRUSTLABS_API_KEY; // server-only secret
  const params = emails.map(encodeURIComponent).join(',');
  const url = `https://api.trustlabs.pro/api/public/trust-status?emails=${params}`;
  const resp = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } });
  if (!resp.ok) return NextResponse.json({ error: 'Upstream error' }, { status: 502 });
  const data = await resp.json();
  return NextResponse.json(data.results);
}

Vanilla JS (ESM) with server proxy (required)

Use the ESM build in the browser and point the SDK to your own server route so no secrets are exposed.

<span class="user-email">user@example.com</span>

<script type="module">
  import { setProxy, renderTrustBadgeWithFetch } from 'https://unpkg.com/trustlabs-sdk/dist/sdk.esm.js';

  // Tell the SDK to use your server endpoint
  setProxy(async (emails) => {
    const resp = await fetch('/api/trust-status', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ emails })
    });
    if (!resp.ok) throw new Error('Proxy error');
    return await resp.json(); // Expect TrustStatus[]
  });

  await renderTrustBadgeWithFetch({
    targetEl: document.querySelector('.user-email'),
    emails: ['user@example.com']
  });
  // Place the email in its own <span>, the badge renders right after it
}</script>

Example Express route (must include Authorization header with your API key):

app.post('/api/trust-status', async (req, res) => {
  const { emails } = req.body;
  const apiKey = process.env.TRUSTLABS_API_KEY; // server-only secret
  const params = emails.map(encodeURIComponent).join(',');
  const url = `https://api.trustlabs.pro/api/public/trust-status?emails=${params}`;
  const upstream = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } });
  if (!upstream.ok) return res.status(502).json({ error: 'Upstream error' });
  const data = await upstream.json();
  res.json(data.results);
});

Note: Calls to https://api.trustlabs.pro without a valid API key will be rejected.

Placement requirement

  • Place the email in its own span and render the badge immediately after that span to ensure correct inline positioning and detection.

React (Next.js / React 19)

'use client';
import { TrustBadge } from 'trustlabs-sdk/client';

function Row({ email }) {
  return (
    <div>
      <span>{email}</span>
      <TrustBadge emails={[email]} />
    </div>
  );
}

Vanilla

<span class="user-email">user@example.com</span>
<script>
  await window.TrustLabsSDK.renderTrustBadgeWithFetch({
    targetEl: document.querySelector('.user-email'),
    emails: ['user@example.com']
  });
  // Or fetch + render separately using getTrustStatus + renderTrustBadge
}</script>

Vanilla JavaScript

Basic Usage (UMD) with required proxy

<span class="user-email">user@example.com</span>
<script src="https://unpkg.com/trustlabs-sdk/dist/sdk.min.js"></script>
<script>
  // Configure a proxy to your server (must add API key on server)
  window.TrustLabsSDK.setProxy(async (emails) => {
    const resp = await fetch('/api/trust-status', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ emails })
    });
    if (!resp.ok) throw new Error('Proxy error');
    return await resp.json(); // TrustStatus[]
  });

  // Fetch + render
  const trustData = await window.TrustLabsSDK.getTrustStatus(['user@example.com']);
  window.TrustLabsSDK.renderTrustBadge({
    targetEl: document.querySelector('.user-email'),
    trustData
  });
  // Place the email in its own <span>, the badge renders right after it
</script>

Automatic Rendering (UMD)

<span class="user-email">user@example.com</span>
<script src="https://unpkg.com/trustlabs-sdk/dist/sdk.min.js"></script>
<script>
  window.TrustLabsSDK.setProxy(async (emails) => {
    const resp = await fetch('/api/trust-status', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ emails })
    });
    if (!resp.ok) throw new Error('Proxy error');
    return await resp.json();
  });

  await window.TrustLabsSDK.renderTrustBadgeWithFetch({
    targetEl: document.querySelector('.user-email'),
    emails: ['user@example.com']
  });
</script>

React

// Next.js (React 19) client component usage
'use client';
import { TrustBadge } from 'trustlabs-sdk/client';

function UserProfile({ userEmail }) {
  return (
    <div>
      <span>{userEmail}</span>
      <TrustBadge 
        emails={[userEmail]}
        onError={(error) => console.error('Badge error:', error)}
        onLoad={(data) => console.log('Badge loaded:', data)}
      />
    </div>
  );
}

Advanced React Usage

// Next.js (React 19) client component usage
'use client';
import { TrustBadge } from 'trustlabs-sdk/client';

function UserList({ users }) {
  return (
    <div>
      {users.map(user => (
        <div key={user.id}>
          <span>{user.email}</span>
          <TrustBadge 
            emails={[user.email]}
            showTooltip={true}
            onError={(error) => {
              // Handle errors
              console.error(`Error loading badge for ${user.email}:`, error);
            }}
            onLoad={(data) => {
              // Handle successful load
              console.log(`Badge loaded for ${user.email}:`, data);
            }}
          />
        </div>
      ))}
    </div>
  );
}

API Reference

getTrustStatus(emails)

Fetches trust status for email addresses.

Parameters:

  • emails (string[]): Array of email addresses

Returns: Promise<TrustStatus[]>

Example:

const trustData = await getTrustStatus(['user@example.com']);
console.log(trustData);
// [{ email: 'user@example.com', verified: true, completed_at: '2024-01-15T10:30:00Z' }]

renderTrustBadge(options)

Renders trust badges using vanilla JavaScript.

Parameters:

  • options.targetEl (HTMLElement): Target element to insert badges after
  • options.trustData (TrustStatus[]): Trust status data

renderTrustBadgeWithFetch(options)

Automatically fetches and renders trust badges.

Parameters:

  • options.targetEl (HTMLElement): Target element to insert badges after
  • options.emails (string[]): Email addresses to check

React Component: TrustBadge

Props:

  • emails (string[]): Email addresses to check
  • showTooltip (boolean, optional): Show completion date tooltip (default: true)
  • onError (function, optional): Error callback
  • onLoad (function, optional): Success callback

Types

interface TrustStatus {
  email: string;
  verified: boolean;
  completed_at?: string;
}

interface TrustStatusResponse {
  results: TrustStatus[];
}

Styling

The SDK includes fixed default styles via badge.css. Style overrides via props or external class names are not supported.

Error Handling

The SDK handles various error scenarios:

  • Network errors
  • Invalid email formats
  • API rate limiting
  • Missing or malformed responses

All errors are logged to console and can be handled via callbacks in React or try/catch in vanilla JS.

Browser Support

  • Chrome 60+
  • Firefox 55+
  • Safari 12+
  • Edge 79+