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, errors, and admin-side member revocations

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 five events:

Event NameDescription
AUTH_STATE_CHANGEDAuthentication state changed (login/logout)
TOKEN_REFRESHEDAccess token was refreshed
TOKEN_EXPIREDToken expired
ERRORSDK error occurred
MEMBER_REVOKEDCurrent member was suspended/revoked by an admin (session already wiped)

AUTH_STATE_CHANGED

Emitted when the authentication state changes (login, logout)

interface AuthStateChangedPayload {
  isAuthenticated: boolean;
  accessToken: string | null;
  expiresAt: number | null;
  member: Member | null;
}

Example:

transcodes.on('AUTH_STATE_CHANGED', (payload) => {
  if (payload.isAuthenticated) {
    console.log('Member signed in');
    console.log('Token expires at:', new Date(payload.expiresAt));
  } else {
    console.log('Member signed 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,
  });
});

MEMBER_REVOKED

Emitted when the server reports that the current member has been suspended or revoked by an admin. By the time this event fires, the SDK has already cleared the local session — your handler does not need to call signOut() or clear tokens manually. It only needs to surface a notice and route the user out.

interface MemberRevokedPayload {
  /** User-facing message to display */
  message: string;
  /** Machine-readable reason for programmatic handling */
  reason: 'member_revoked';
}

This event fires asynchronously when the server detects the revocation (typically on the next API call or token refresh). Subscribe at app startup so the redirect happens regardless of which screen the user is currently on.

Example:

transcodes.on('MEMBER_REVOKED', ({ message, reason }) => {
  // reason === 'member_revoked'
 
  // 1. Show the user-facing message (toast / banner / alert)
  showNotification(message);
 
  // 2. Send the user back to the sign-in screen
  window.location.href = '/login?reason=member_revoked';
});

React example with cleanup:

useEffect(() => {
  const unsubscribe = transcodes.on('MEMBER_REVOKED', ({ message }) => {
    toast.error(message);
    router.push('/login?reason=member_revoked');
  });
 
  return () => unsubscribe();
}, []);

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.member) {
      console.log('Member:', payload.member.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'
  | 'MEMBER_REVOKED';

Event Payloads

interface TranscodesEventMap {
  AUTH_STATE_CHANGED: AuthStateChangedPayload;
  TOKEN_REFRESHED: TokenRefreshedPayload;
  TOKEN_EXPIRED: TokenExpiredPayload;
  ERROR: ErrorPayload;
  MEMBER_REVOKED: MemberRevokedPayload;
}
 
interface AuthStateChangedPayload {
  isAuthenticated: boolean;
  accessToken: string | null;
  expiresAt: number | null;
  member: Member | null;
}
 
interface TokenRefreshedPayload {
  accessToken: string;
  expiresAt: number;
}
 
interface TokenExpiredPayload {
  expiredAt: number;
}
 
interface ErrorPayload {
  code: string;
  message: string;
  context?: string;
}
 
interface MemberRevokedPayload {
  message: string;
  reason: 'member_revoked';
}
Last updated on
Member APIModal API