Magic Link SDK

TypeScript SDK for interacting with the Magic Link API.

Installation

npm install magic-link-sdk
# or
yarn add magic-link-sdk

Usage

Basic Setup

import { Client, PropertyScope } from 'magic-link-sdk';

const client = new Client({
  baseUrl: 'https://api.magic-link.io',
  tenantId: process.env.MAGIC_LINK_TENANT_ID,
  clientId: process.env.MAGIC_LINK_CLIENT_ID,
  clientSecret: process.env.MAGIC_LINK_CLIENT_SECRET,
  redirectUri: process.env.MAGIC_LINK_REDIRECT_URI,
  tenantApiKey: process.env.MAGIC_LINK_TENANT_API_KEY
});

Authentication

Get Authentication URL

const authUrl = client.getAuthenticationUrl({
  responseType: 'code',
  nonce: 'randomNonce',
  scope: 'openid profile email',
  state: 'randomState'
});

Exchange Authorization Code for Tokens

const tokens = await client.handleTokenExchange(authorizationCode);

Refresh Token

const newTokens = await client.handleTokenRefresh(refreshToken);

Token Validation

const decodedToken = await client.validateToken(jwtToken);

Property Management

Client-Scope Properties

// Get user properties
const properties = await client.getClientUserProperties(userId);

// Set a property
const result = await client.setUserClientProperties(userId, propertyId, value);

// Get property by key name
const property = await client.getUserPropertyByKey(userId, 'role');

// Set property by key name
const result = await client.setUserPropertyByKey(userId, 'role', 'student');

// Get all client properties (resolved with current values)
const allProperties = await client.getAllClientProperties(userId);

Tenant-Scope Properties

// Get user properties
const properties = await client.getTenantUserProperties(userId);

// Set a property
const result = await client.setUserTenantProperty(userId, propertyId, value);

// Get property by key name
const property = await client.getUserPropertyByKey(userId, 'department', PropertyScope.Tenant);

// Set property by key name
const result = await client.setUserPropertyByKey(userId, 'department', 'Engineering', PropertyScope.Tenant);

// Get all tenant properties (resolved with current values)
const allProperties = await client.getAllTenantProperties(userId);

Scope Discovery

Client Scopes

const scopes = await client.getClientAvailableScopes();

Tenant Scopes

const scopes = await client.getTenantAvailableScopes();

Configuration

Environment Variables

| Variable | Description | Required | |----------|-------------|----------| | MAGIC_LINK_BASE_URL | API base URL | Yes | | MAGIC_LINK_TENANT_ID | Tenant identifier | Yes | | MAGIC_LINK_CLIENT_ID | Client identifier | Yes | | MAGIC_LINK_CLIENT_SECRET | Client secret | Yes | | MAGIC_LINK_REDIRECT_URI | OAuth redirect URI | Yes | | MAGIC_LINK_TENANT_API_KEY | Tenant API key (for tenant operations) | No |

Creating .env File

Copy the example file and fill in your values:

cp .env.example .env

Development

Running Tests

# Run all tests
npm test

# Run specific test file
npm test -- flow.test.ts

Building

# Build for development
npm run build

# Watch mode
npm run build:watch

Linting

npm run lint

API Reference

Client Options

| Property | Type | Description | |----------|------|-------------| | baseUrl | string | API base URL | | tenantId | string | Tenant identifier | | clientId | string | Client identifier | | clientSecret | string | Client secret | | redirectUri | string | OAuth redirect URI | | tenantApiKey | string | Tenant API key (optional) |

PropertyScope Enum

enum PropertyScope {
  Tenant = 'tenant',
  Client = 'client'
}

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE file for details.

Property Entry (PropertyEntry)

Represents a property definition returned from the API:

interface PropertyEntry {
  id: string;          // Unique identifier for the property
  key: string;         // Human-readable property name (e.g., "role", "department")
  description: string; // Description of the property
  default: string | boolean;  // Default value for the property
  is_system: boolean;   // Whether this is a system-managed property
  property_scope: string; // Scope of the property ("tenant" or "client")
}

Scope Entry (ScopeEntry)

Represents a scope and its associated properties:

interface ScopeEntry {
  id: string;          // Unique identifier for the scope
  name: string;        // Display name of the scope
  description: string; // Description of the scope
  properties: PropertyEntry[];  // List of properties in this scope
}

Token Response (TokenResponse)

Response from the /api/auth/token endpoint:

interface TokenResponse {
  access_token: string;    // JWT access token
  refresh_token: string;   // JWT refresh token
  id_token: string;        // JWT identity token
  expiration: number;      // Unix timestamp when the token expires
}

User Property Entry (UserPropertyEntry)

Represents a user's property value:

interface UserPropertyEntry {
  property_id: string;  // ID of the property
  value: string;        // Current value of the property
}

Get Properties Response (GetPropertiesResponse)

Response from user property endpoints:

interface GetPropertiesResponse {
  properties: UserPropertyEntry[];  // List of user properties
}

Set Property Request (SetPropertyRequest)

Request body for setting a property value:

interface SetPropertyRequest {
  property_id: string;  // ID of the property to set
  value: string;        // New value for the property
}

Set Property Response (SetPropertyResponse)

Response from property set operations:

interface SetPropertyResponse {
  success: boolean;   // Whether the operation succeeded
  message?: string;   // Optional message (e.g., error details)
}