SDK

Integrate Anon migrations with the @anon-dot-com/frontend package

Anon Frontend SDK

The @anon-dot-com/frontend package provides a lightweight JavaScript library for embedding the Anon Enterprise Data Migration platform directly into your web application. This SDK handles user authentication, migration status checking, and provides seamless integration through a secure iframe modal.

Overview

The SDK creates a responsive iframe modal that displays the Anon migration interface within any web application. It provides event-driven communication and handles the complete migration lifecycle using a secure token-based authentication flow.

The SDK uses a two-step authentication process: your backend generates a link token using your API key, and the frontend exchanges it for an access token that’s stored securely in the browser.

Installation

This is a private npm package that requires authentication to install.

Configure npm Authentication

Create or update your .npmrc file in your project root with the authentication token:

@anon-dot-com:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_ACCESS_TOKEN

Contact your Anon point-of-contact to obtain the access token for your .npmrc configuration.

Install the Package

Once your .npmrc is configured, you can install the package using your preferred package manager:

npm

npm install @anon-dot-com/frontend

Never commit your .npmrc file with the access token to version control. Add .npmrc to your .gitignore file to prevent accidental exposure of credentials.

Quick Start

Basic Integration

The SDK provides two main methods for integrating the migration modal:

Initialize Existing Migration

import { init } from '@anon-dot-com/frontend';

// Initialize the Anon Link (finds existing migration)
await init({
  onEvent: (event) => {
    console.log('Migration event:', event);
  }
});

Advanced Configuration

Configure the modal with additional options for more control over the migration process:

import { startModal } from '@anon-dot-com/frontend';

// Get link token from your backend
const linkToken = await fetch('/api/anon/link-token', {
  method: 'POST'
}).then(res => res.json()).then(data => data.link_token);

await startModal({
  userId: '[e-mail]',
  linkToken: linkToken,
  sourceProviders: ['gusto', 'rippling'], // Pre-configure source providers
  target: '#migration-container', // Custom target element
  baseURL: 'https://worker.anon.com', // Optional: Override base URL
  onEvent: (event) => {
    switch (event.event.type) {
      case 'migration_modal.completed':
        console.log('Migration completed:', event.event.data);
        break;
      case 'migration_modal.failed':
        console.log('Migration failed:', event.event.data);
        break;
    }
  }
});

Global Script Usage

If you’re not using a module bundler, include the library as a global script:

<script src="https://cdn.jsdelivr.net/npm/@anon-dot-com/frontend/index.umd.js"></script>
<script>
  // First get link token from your backend
  fetch('/api/anon/link-token', { method: 'POST' })
    .then(res => res.json())
    .then(data => {
      // Initialize the Anon Link (finds existing migration)
      window.Anon.init({
        onEvent: (event) => {
          console.log('Migration event:', event);
        }
      });
    });
</script>

API Reference

Methods

init(options: AnonInitOptions)

Initializes the SDK and finds any existing migration for the user. This method checks localStorage for previous migration options and attempts to continue an existing migration if found.

Parameters:

• options: Configuration object of type AnonInitOptions

Returns:

• Promise that resolves with migration metadata if an existing migration is found, or undefined

startModal(options: AnonLinkOptions)

Creates a new modal link for the user and immediately shows the iframe modal. This method requires a link token obtained from your backend.

Parameters:

• options: Configuration object of type AnonLinkOptions

Returns:

• Promise that resolves when the modal is started

Configuration Options

AnonInitOptions

The AnonInitOptions interface accepts the following properties:

Property	Type	Required	Description
onEvent	(event: EventData) => void	No	Callback for migration events
target	string	No	CSS selector for target element (defaults to “body”)
baseURL	string	No	Base URL for API requests (defaults to “https://worker.anon.com”)

AnonLinkOptions

The AnonLinkOptions interface extends AnonInitOptions and accepts additional properties:

Property	Type	Required	Description
userId	string	Yes	User identifier (UUID or email address)
linkToken	string	Yes	Link token obtained from your backend’s /api/v1/link-token endpoint
sourceProviders	string[]	No	Pre-configured source providers for migration

Event Structure

The onEvent callback receives events with the following structure:

type AnonEventData = {
  source: 'anon_modal';
  event: {
    type: string;
    data: any;
  };
};

Common event types include migration_modal.completed, migration_modal.failed, and migration_modal.cancelled.

Authentication Flow

The SDK uses a secure two-step authentication process:

1. Link Token Generation: Your backend calls the Anon API to create a link token
2. Access Token Exchange: The frontend exchanges the link token for a browser-safe access token

Step 1: Backend Link Token Generation

Your backend must implement an endpoint that generates link tokens:

Next.js

// /api/anon/link-token/route.ts
export async function POST() {
  const response = await fetch('https://worker.anon.com/api/v1/link-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.ANON_API_KEY}`,
      'Content-Type': 'application/json'
    }
  });

  const data = await response.json();
  return Response.json(data);
}

Express.js

app.post('/api/anon/link-token', async (req, res) => {
  const response = await fetch('https://worker.anon.com/api/v1/link-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.ANON_API_KEY}`,
      'Content-Type': 'application/json'
    }
  });

  const data = await response.json();
  res.json(data);
});

Step 2: Frontend Access Token Exchange

The SDK automatically handles the access token exchange when you call startModal() with a link token. The access token is stored in localStorage and used for subsequent API calls.

Link tokens are short-lived (60 seconds) and single-use. Access tokens are longer-lived (1 hour) and stored securely in the browser.

Migration Persistence

The SDK automatically persists migration state in the browser’s localStorage. When you call init(), it checks for any existing migration options and attempts to continue where the user left off.

import { init, startModal } from '@anon-dot-com/frontend';

// On page load, check for existing migration
const existingMigration = await init({
  onEvent: (event) => console.log('Migration event:', event)
});

if (!existingMigration) {
  // No existing migration found, user can start a new one
  document.getElementById('start-migration').addEventListener('click', async () => {
    const linkToken = await fetch('/api/anon/link-token', { method: 'POST' })
      .then(res => res.json())
      .then(data => data.link_token);
    
    await startModal({
      userId: '[e-mail]',
      linkToken: linkToken
    });
  });
}

Architecture Flow

The following diagram illustrates the new authentication flow:

Backend Requirements

Required Endpoints

Your backend needs to implement the following endpoint:

Endpoint	Method	Purpose
/api/anon/link-token	POST	Generate a link token for frontend authentication

Security Considerations

• Store your Anon API key securely in environment variables
• Implement proper authentication/authorization for the link token endpoint
• Consider rate limiting the link token endpoint to prevent abuse
• Link tokens are short-lived (60 seconds) and single-use for security

Never expose your Anon API key in client-side code. The new token-based flow eliminates the need for a catch-all proxy while maintaining security.

Migration from Previous Versions

If you’re migrating from a previous version that used loadModal() and proxy URLs:

Before (v0.x)

await loadModal({
  userId: '[e-mail]',
  proxyUrl: 'https://your-backend.com/anon-proxy'
});

After (v1.x)

// Initialize existing migrations
await init();

// Start new migrations
const linkToken = await fetch('/api/anon/link-token', { method: 'POST' })
  .then(res => res.json()).then(data => data.link_token);

await startModal({
  userId: '[e-mail]',
  linkToken: linkToken
});

Breaking Changes

• loadModal() has been replaced with init() for resuming existing migrations
• proxyUrl is no longer required; the SDK communicates directly with Anon APIs
• linkToken is now required for startModal()
• New /api/v1/link-token endpoint required on your backend

Next Steps

Embedding the Modal

Learn more about iframe integration best practices

Webhooks

Set up webhooks to receive migration status updates

API Reference

Explore the complete Anon API documentation

Messages

Handle migration events and messages