Skip to Content
DocumentationAPI ReferenceEvents API

Events API

⚡ 10 min read

The Transcodes SDK provides an event system to subscribe to authentication state changes, token updates, and errors.

Event Methods

on()

Subscribes to an event. Returns an unsubscribe function.

transcodes.on<T extends TranscodesEventName>(
  event: T,
  callback: (payload: EventPayload<T>) => void
): () => void

The on() method returns a function that unsubscribes the listener when called. This is the recommended way to manage subscriptions.

Example:

// Subscribe and get unsubscribe function
const unsubscribe = transcodes.on('AUTH_STATE_CHANGED', (payload) => {
  console.log('Auth state:', payload.isAuthenticated);
});
 
// Later: unsubscribe
unsubscribe();

off()

Removes an event listener. Requires the same function reference that was passed to on().

transcodes.off<T extends TranscodesEventName>(
  event: T,
  callback: (payload: EventPayload<T>) => void
): void

Example:

// Store the handler reference
const handleAuthChange = (payload) => {
  console.log('Auth changed:', payload.isAuthenticated);
};
 
// Subscribe
transcodes.on('AUTH_STATE_CHANGED', handleAuthChange);
 
// Unsubscribe (same function reference required)
transcodes.off('AUTH_STATE_CHANGED', handleAuthChange);

Available Events

The SDK provides four events:

Event NameDescription
AUTH_STATE_CHANGEDAuthentication state changed (login/logout)
TOKEN_REFRESHEDAccess token was refreshed
TOKEN_EXPIREDToken expired
ERRORSDK error occurred

AUTH_STATE_CHANGED

Emitted when the authentication state changes (login, logout).

interface AuthStateChangedPayload {
  isAuthenticated: boolean;
  accessToken: string | null;
  expiresAt: number | null;
  user: User | null;
}

Example:

transcodes.on('AUTH_STATE_CHANGED', (payload) => {
  if (payload.isAuthenticated) {
    console.log('User logged in');
    console.log('Token expires at:', new Date(payload.expiresAt));
  } else {
    console.log('User logged out');
  }
});

TOKEN_REFRESHED

Emitted when the access token is automatically refreshed.

interface TokenRefreshedPayload {
  accessToken: string;
  expiresAt: number;
}

Example:

transcodes.on('TOKEN_REFRESHED', (payload) => {
  console.log('Token refreshed');
  console.log('New expiry:', new Date(payload.expiresAt));
 
  // Update your API client if needed
  apiClient.setToken(payload.accessToken);
});

TOKEN_EXPIRED

Emitted when the token expires and cannot be refreshed.

interface TokenExpiredPayload {
  expiredAt: number;
}

Example:

transcodes.on('TOKEN_EXPIRED', (payload) => {
  console.log('Token expired at:', new Date(payload.expiredAt));
 
  // Prompt user to log in again
  showNotification('Session expired. Please log in again.');
  window.location.href = '/login';
});

ERROR

Emitted when the SDK encounters an error.

interface ErrorPayload {
  code: string;
  message: string;
  context?: string;
}

Example:

transcodes.on('ERROR', (payload) => {
  console.error(`[${payload.context}] ${payload.code}: ${payload.message}`);
 
  // Send to error tracking service
  errorTracker.captureError({
    name: 'TranscodesError',
    code: payload.code,
    message: payload.message,
    context: payload.context,
  });
});

Usage Patterns

Subscribe to Multiple Events

// Store unsubscribe functions
const subscriptions = [];
 
// Subscribe to events
subscriptions.push(
  transcodes.on('AUTH_STATE_CHANGED', (payload) => {
    console.log('Auth state:', payload.isAuthenticated);
    if (payload.user) {
      console.log('User:', payload.user.email);
    }
  })
);
 
subscriptions.push(
  transcodes.on('TOKEN_EXPIRED', (payload) => {
    console.log('Token expired');
    window.location.href = '/login';
  })
);
 
subscriptions.push(
  transcodes.on('ERROR', (payload) => {
    console.error('Error:', payload.code, payload.message);
  })
);
 
// Later: cleanup all subscriptions
subscriptions.forEach((unsubscribe) => unsubscribe());

Best Practices

1. Always Cleanup Subscriptions

// Subscribe
const unsubscribe = transcodes.on('AUTH_STATE_CHANGED', handler);
 
// Later: cleanup when no longer needed
unsubscribe();

Failing to unsubscribe can cause memory leaks, especially in Single Page Applications.

2. Use the Returned Unsubscribe Function

// Recommended: use returned function
const unsubscribe = transcodes.on('AUTH_STATE_CHANGED', handler);
unsubscribe();
 
// Alternative: use off() with same reference
const handler = (payload) => {
  /* ... */
};
transcodes.on('AUTH_STATE_CHANGED', handler);
transcodes.off('AUTH_STATE_CHANGED', handler);

3. Subscribe to ERROR Events

// Always handle errors
transcodes.on('ERROR', (payload) => {
  console.error('Transcodes error:', payload);
  // Send to monitoring service
});

4. Avoid Heavy Operations in Handlers

// Bad: heavy operation in handler
transcodes.on('AUTH_STATE_CHANGED', async (payload) => {
  await heavyDatabaseOperation(); // Blocks other handlers
});
 
// Good: defer heavy operations
transcodes.on('AUTH_STATE_CHANGED', (payload) => {
  setTimeout(() => heavyDatabaseOperation(), 0);
});

Type Definitions

Event Names

type TranscodesEventName =
  | 'AUTH_STATE_CHANGED'
  | 'TOKEN_REFRESHED'
  | 'TOKEN_EXPIRED'
  | 'ERROR';

Event Payloads

interface TranscodesEventMap {
  AUTH_STATE_CHANGED: AuthStateChangedPayload;
  TOKEN_REFRESHED: TokenRefreshedPayload;
  TOKEN_EXPIRED: TokenExpiredPayload;
  ERROR: ErrorPayload;
}
 
interface AuthStateChangedPayload {
  isAuthenticated: boolean;
  accessToken: string | null;
  expiresAt: number | null;
  user: User | null;
}
 
interface TokenRefreshedPayload {
  accessToken: string;
  expiresAt: number;
}
 
interface TokenExpiredPayload {
  expiredAt: number;
}
 
interface ErrorPayload {
  code: string;
  message: string;
  context?: string;
}
Last updated on
User APIModal API