The IdpClient provides a complete API for authentication, session management, and organization operations. It uses WebSocket connections via TypedSocket for real-time, type-safe communication with the IdP server.

Installation

npm install @idp.global/idpclient
# or
pnpm add @idp.global/idpclient

Quick Start

import { IdpClient } from '@idp.global/idpclient';

// Initialize the client
const idpClient = new IdpClient('https://idp.global');

// Enable WebSocket connection
await idpClient.enableTypedSocket();

// Check login status
const isLoggedIn = await idpClient.determineLoginStatus();

if (isLoggedIn) {
  const userInfo = await idpClient.whoIs();
  console.log('Logged in as:', userInfo.user.data.name);
}

Core Features

Authentication

const response = await idpClient.requests.loginWithUserNameAndPassword.fire({
  username: 'user@example.com',
  password: 'securepassword',
});

if (response.refreshToken) {
  await idpClient.refreshJwt(response.refreshToken);
  console.log('Login successful!');
} else if (response.twoFaNeeded) {
  console.log('2FA verification required');
}

// Request magic link
await idpClient.requests.loginWithEmail.fire({
  email: 'user@example.com',
});

// After clicking the email link
const result = await idpClient.requests.loginWithEmailAfterToken.fire({
  email: 'user@example.com',
  token: 'token-from-email-link',
});

if (result.refreshToken) {
  await idpClient.refreshJwt(result.refreshToken);
}

const result = await idpClient.requests.loginWithApiToken.fire({
  apiToken: 'your-api-token',
});

if (result.jwt) {
  await idpClient.setJwt(result.jwt);
}

Session Management

// Get current JWT
const jwt = await idpClient.getJwt();

// Get parsed JWT data
const jwtData = await idpClient.getJwtData();
console.log('User ID:', jwtData.id);

// Refresh JWT (automatic housekeeping)
await idpClient.performJwtHousekeeping();

// Manual refresh
await idpClient.refreshJwt();

// Logout
await idpClient.logout();

User Information

// Get current user details
const whoIsResponse = await idpClient.whoIs();
console.log('Name:', whoIsResponse.user.data.name);
console.log('Email:', whoIsResponse.user.data.email);

// Get user data
const userData = await idpClient.requests.getUserData.fire({
  jwt: await idpClient.getJwt(),
  userId: jwtData.id,
});

// Update user data
await idpClient.requests.setUserData.fire({
  jwt: await idpClient.getJwt(),
  userId: jwtData.id,
  name: 'New Name',
});

Organization Management

// Get user's organizations and roles
const orgsAndRoles = await idpClient.getRolesAndOrganizations();
console.log('Organizations:', orgsAndRoles.organizations);
console.log('Roles:', orgsAndRoles.roles);

// Create a new organization
const result = await idpClient.createOrganization(
  'My Company',       // name
  'my-company',       // slug
  'manifest'          // mode: 'checkAvailability' or 'manifest'
);

if (result.resultingOrganization) {
  console.log('Created:', result.resultingOrganization.id);
}

// Get organization details
const orgDetails = await idpClient.requests.getOrganizationById.fire({
  jwt: await idpClient.getJwt(),
  organizationId: 'org-id',
});

Member & Invitation Management

// Get organization members
const members = await idpClient.requests.getOrgMembers.fire({
  jwt: await idpClient.getJwt(),
  organizationId: 'org-id',
});

// Invite a new member
await idpClient.requests.createInvitation.fire({
  jwt: await idpClient.getJwt(),
  organizationId: 'org-id',
  email: 'newmember@example.com',
  roles: ['member'],
});

// Bulk invite members
await idpClient.requests.bulkCreateInvitations.fire({
  jwt: await idpClient.getJwt(),
  organizationId: 'org-id',
  invitations: [
    { email: 'user1@example.com', roles: ['member'] },
    { email: 'user2@example.com', roles: ['admin'] },
  ],
});

// Accept an invitation
await idpClient.requests.acceptInvitation.fire({
  jwt: await idpClient.getJwt(),
  invitationToken: 'token-from-invite-email',
});

// Remove a member
await idpClient.requests.removeMember.fire({
  jwt: await idpClient.getJwt(),
  organizationId: 'org-id',
  userId: 'user-id',
});

// Transfer ownership
await idpClient.requests.transferOwnership.fire({
  jwt: await idpClient.getJwt(),
  organizationId: 'org-id',
  newOwnerId: 'new-owner-user-id',
});

Password Management

// Request password reset
await idpClient.requests.resetPassword.fire({
  email: 'user@example.com',
});

// Set new password (with token from email)
await idpClient.requests.setNewPassword.fire({
  email: 'user@example.com',
  tokenArg: 'reset-token',
  newPassword: 'newsecurepassword',
});

// Change password (when logged in)
await idpClient.requests.setNewPassword.fire({
  email: 'user@example.com',
  oldPassword: 'currentpassword',
  newPassword: 'newsecurepassword',
});

Session & Device Management

// Get active sessions
const sessions = await idpClient.requests.getUserSessions.fire({
  jwt: await idpClient.getJwt(),
  userId: jwtData.id,
});

// Revoke a session
await idpClient.requests.revokeSession.fire({
  jwt: await idpClient.getJwt(),
  sessionId: 'session-id',
});

// Get device ID
const deviceInfo = await idpClient.requests.obtainDeviceId.fire({});

// Attach device to session
await idpClient.requests.attachDeviceId.fire({
  jwt: await idpClient.getJwt(),
  deviceId: deviceInfo.deviceId.id,
});

Cross-Domain Authentication

// Get transfer token for SSO between apps
const transferToken = await idpClient.getTransferToken();

// Switch to another app with authentication
await idpClient.getTransferTokenAndSwitchToLocation('https://app.example.com/');

// Process incoming transfer token (in target app)
const success = await idpClient.processTransferToken();
if (success) {
  console.log('Cross-domain login successful');
}

Billing Integration

// Get billing plan for an organization
const billingPlan = await idpClient.requests.getBillingPlan.fire({
  jwt: await idpClient.getJwt(),
  organizationId: 'org-id',
});

// Get Paddle configuration
const paddleConfig = await idpClient.requests.getPaddleConfig.fire({
  jwt: await idpClient.getJwt(),
});

// Update payment method
await idpClient.updatePaddleCheckoutId('org-id', 'checkout-id');

Admin Operations (Global Admins Only)

// Check if user is global admin
const isAdmin = await idpClient.requests.checkGlobalAdmin.fire({
  jwt: await idpClient.getJwt(),
});

// Get platform statistics
const stats = await idpClient.requests.getGlobalAppStats.fire({
  jwt: await idpClient.getJwt(),
});

// Create a global app
await idpClient.requests.createGlobalApp.fire({
  jwt: await idpClient.getJwt(),
  name: 'My App',
  description: 'App description',
});

// Suspend a user
await idpClient.requests.suspendUser.fire({
  jwt: await idpClient.getJwt(),
  userId: 'user-id',
});

Reactive Subscriptions

The client provides RxJS subjects for reactive updates:

// Subscribe to login status changes
idpClient.statusObservable.subscribe((status) => {
  console.log('Login status changed:', status);
});

// Subscribe to roles updates
idpClient.rolesReplaySubject.subscribe((roles) => {
  console.log('Roles updated:', roles);
});

// Subscribe to organizations updates
idpClient.organizationsReplaySubject.subscribe((orgs) => {
  console.log('Organizations updated:', orgs);
});

API Reference

IdpClient Class

Method	Description
`enableTypedSocket()`	Initialize WebSocket connection
`determineLoginStatus(requireLogin?)`	Check if user is logged in
`getJwt()`	Get stored JWT string
`getJwtData()`	Get parsed JWT data
`setJwt(jwt)`	Store JWT
`deleteJwt()`	Remove stored JWT
`refreshJwt(refreshToken?)`	Refresh the JWT
`performJwtHousekeeping()`	Auto-refresh JWT if needed
`logout()`	End session and redirect
`whoIs()`	Get current user info
`getRolesAndOrganizations()`	Get user's orgs and roles
`createOrganization(name, slug, mode)`	Create new organization
`getTransferToken(appData?)`	Get SSO transfer token
`processTransferToken()`	Process incoming transfer token
`stop()`	Close WebSocket connection

IdpRequests Class

Access via idpClient.requests.*:

Authentication: loginWithUserNameAndPassword, loginWithEmail, loginWithEmailAfterToken, loginWithApiToken, resetPassword, setNewPassword

User: getUserData, setUserData, getUserSessions, revokeSession, getUserActivity

Organization: getOrganizationById, updateOrganization, createInvitation, bulkCreateInvitations, getOrgMembers, getOrgInvitations, acceptInvitation, cancelInvitation, resendInvitation, removeMember, updateMemberRoles, transferOwnership

Billing: getBillingPlan, getPaddleConfig

Admin: checkGlobalAdmin, getGlobalAppStats, createGlobalApp, updateGlobalApp, deleteGlobalApp, suspendUser, deleteSuspendedUser

License

MIT - See the main repository for full license details.

readme.md

@idp.global/idpclient

Overview