Identity Provider SDK - Core

A TypeScript/JavaScript SDK for interacting with the Auth API service.

Features

• Multiple Authentication Methods
  • Social providers (Google, Microsoft)
  • SAML-based SSO
  • Email and password
• Organization Management
  • Multi-tenant support
  • Role-based access control (RBAC)
  • Team management
  • Member invitations
• JWT Token Validation

Installation

npm install @meistrari/auth-core

Quick Start

import { AuthClient } from '@meistrari/auth-core'

// Initialize the client
const authClient = new AuthClient('https://auth.example.com')

// Sign in with email and password
await authClient.session.signInWithEmailAndPassword({
    email: '[email protected]',
    password: 'SecurePassword123!'
})

// List user's organizations
const organizations = await authClient.organization.listOrganizations()
console.log('Organizations:', organizations)

API Reference

AuthClient

The main entry point for the SDK. Provides access to session and organization services.

Constructor

new AuthClient(apiUrl: string, headers?: Record<string, string>)

Parameters:

• apiUrl - The base URL of the Auth API
• headers (optional) - Custom headers to include in all requests

Example:

const authClient = new AuthClient('https://auth.example.com', {
    'X-Custom-Header': 'value'
})

Session Management

Access via authClient.session

signInWithEmailAndPassword

Authenticates a user with email and password credentials.

await authClient.session.signInWithEmailAndPassword({
    email: '[email protected]',
    password: 'password123'
})

signInWithSocialProvider

Initiates social authentication flow with Google or Microsoft.

await authClient.session.signInWithSocialProvider({
    provider: 'google', // or 'microsoft'
    callbackURL: 'https://app.example.com/callback',
    errorCallbackURL: 'https://app.example.com/error', // optional
})

The error callback URL receives an error query parameter with the error status text.

signInWithSaml

Initiates SAML-based Single Sign-On authentication flow.

await authClient.session.signInWithSaml({
    email: '[email protected]',
    callbackURL: 'https://app.example.com/callback',
    errorCallbackURL: 'https://app.example.com/error', // optional
})

The error callback URL receives an error query parameter with the error status text.

signOut

Signs out the currently authenticated user.

// Simple sign out
await authClient.session.signOut()

// Sign out with callback
await authClient.session.signOut(() => {
    console.log('User signed out')
    window.location.href = '/login'
})

requestPasswordReset

Initiates a password reset request.

await authClient.session.requestPasswordReset(
    '[email protected]',
    'https://app.example.com/reset-password'
)

resetPassword

Completes the password reset process.

await authClient.session.resetPassword(
    'reset-token-from-email',
    'NewSecurePassword123!'
)

Organization Management

Access via authClient.organization

listOrganizations

Lists all organizations accessible to the current user.

const organizations = await authClient.organization.listOrganizations()

getOrganization

Retrieves a single organization with teams, invites and members.

const organization = await authClient.organization.getOrganization('org-123')

setActiveOrganization

Sets the active organization for the current user session.

await authClient.organization.setActiveOrganization('org-123')

updateOrganization

Updates an organization's details.

const updated = await authClient.organization.updateOrganization({
    name: 'New Organization Name',
    logo: 'https://example.com/logo.png',
    settings: {
        disableStorage: true,
        dataRetentionHours: 24
    }
})

Member Management

listMembers

Lists members of the active organization.

const members = await authClient.organization.listMembers({
    limit: 10,
    offset: 0
})

getActiveMember

Gets the currently active organization member for the authenticated user.

const activeMember = await authClient.organization.getActiveMember()
console.log(`Role: ${activeMember.role}`)

inviteUserToOrganization

Invites a user to join the active organization.

import { Roles } from '@meistrari/auth-core'

await authClient.organization.inviteUserToOrganization({
    userEmail: '[email protected]',
    role: Roles.ORG_MEMBER,
    teamId: 'team-123' // optional
})

acceptInvitation

Accepts an organization invitation.

await authClient.organization.acceptInvitation('invitation-123')

cancelInvitation

Cancels a pending invitation.

await authClient.organization.cancelInvitation('invitation-123')

removeUserFromOrganization

Removes a user from the active organization.

// Remove by member ID
await authClient.organization.removeUserFromOrganization({
    memberId: 'member-123'
})

// Remove by email
await authClient.organization.removeUserFromOrganization({
    userEmail: '[email protected]'
})

updateMemberRole

Updates the role of an organization member.

import { Roles } from '@meistrari/auth-core'

await authClient.organization.updateMemberRole({
    memberId: 'member-123',
    role: Roles.ORG_ADMIN
})

Team Management

listTeams

Lists all teams in the active organization.

const teams = await authClient.organization.listTeams()

createTeam

Creates a new team.

const team = await authClient.organization.createTeam({
    name: 'Engineering Team'
})

updateTeam

Updates a team's details.

const updated = await authClient.organization.updateTeam('team-123', {
    name: 'Updated Team Name'
})

deleteTeam

Deletes a team.

await authClient.organization.deleteTeam('team-123')

listTeamMembers

Lists all members of a specific team.

const members = await authClient.organization.listTeamMembers('team-123')

addTeamMember

Adds a user to a team.

await authClient.organization.addTeamMember('team-123', 'user-456')

removeTeamMember

Removes a user from a team.

await authClient.organization.removeTeamMember('team-123', 'user-456')

Token Validation

Standalone utility functions for JWT token validation.

isTokenExpired

Checks if a JWT token has expired.

import { isTokenExpired } from '@meistrari/auth-core'

const token = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'
if (isTokenExpired(token)) {
    console.log('Token has expired')
}

validateToken

Validates a JWT token by checking expiration and verifying signature.

import { validateToken } from '@meistrari/auth-core'

const token = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'
const isValid = await validateToken(token, 'https://auth.example.com')

if (isValid) {
    console.log('Token is valid')
}

Roles and Permissions

The SDK provides predefined organization roles with specific permissions:

import { Roles } from '@meistrari/auth-core'

// Available roles
Roles.ORG_ADMIN // Full access: org updates, team/member management, invitations
Roles.ORG_MEMBER // Basic member access
Roles.ORG_REVIEWER // Read-only reviewer access

Error Handling

The SDK provides typed error classes for better error handling:

BaseError

Base class for all SDK errors with a code property.

import { BaseError } from '@meistrari/auth-core'

try {
    // SDK operation
}
catch (error) {
    if (error instanceof BaseError) {
        console.log(`Error code: ${error.code}`)
        console.log(`Error message: ${error.message}`)
    }
}

Specific Error Classes

• InvalidSocialProvider - Invalid social provider specified
• InvalidCallbackURL - Malformed callback URL
• EmailRequired - Email parameter required but not provided
• APIError (BetterFetchError) - API request failed

import {
    InvalidSocialProvider,
    InvalidCallbackURL,
    EmailRequired,
    APIError
} from '@meistrari/auth-core'

try {
    await authClient.session.signInWithSocialProvider({
        provider: 'invalid' as any,
        callbackURL: 'https://app.example.com/callback'
    })
}
catch (error) {
    if (error instanceof InvalidSocialProvider) {
        console.log('Invalid provider specified')
    }
}

Type Definitions

The SDK exports TypeScript types for all data structures:

import type {
    User,
    Session,
    Organization,
    Member,
    Invitation,
    Team,
    TeamMember,
    Role
} from '@meistrari/auth-core'