FCE-2044 validate credentials at client creation (#271)

## Description

Adds credentials validation to the preferred way of creating the client.
There is also a separate checkCredentials method if someone needs to
create the client synchronously.

## Motivation and Context

The SDK client should fail fast when misconfigured.

## Documentation impact

- [ ] Documentation update required
- [x] Documentation updated [in another
PR](fishjam-cloud/documentation#259)
- [ ] No documentation update required

## Types of changes

- [ ] Bug fix (non-breaking change which fixes an issue)
- [x] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to
      not work as expected)

Author: czerwiukk

.github/workflows/static.yaml

@@ -39,17 +39,6 @@ jobs:
       - name: Check typing
         run: yarn typecheck
 
-      - name: Generate OpenAPI reference 📸
-        run: FISHJAM_ID="openapi" FISHJAM_MANAGEMENT_TOKEN="foo" yarn gen:openapi ref.yaml
-
-      - name: Compare OpenAPI reference 🔦
-        run: |
-          RM_PATH=examples/room-manager
-          if ! cmp --silent "$RM_PATH/openapi.yaml" "$RM_PATH/ref.yaml"; then
-            echo "OpenAPI spec is out of date. Please run 'yarn gen:openapi' and commit the changes."
-            exit 1
-          fi
-
       - name: Check TypeDoc generation
         run: yarn docs
 

examples/multimodal/src/index.ts

@@ -12,7 +12,7 @@ const fishjamConfig = {
   managementToken: process.env.FISHJAM_TOKEN,
 };
 
-const fishjam = new FishjamService(fishjamConfig);
+const fishjam = await FishjamService.create(fishjamConfig);
 
 new MultimodalService(fishjamConfig, process.env.GEMINI_API_KEY);
 

examples/multimodal/src/service/fishjam.ts

@@ -4,8 +4,13 @@ export class FishjamService {
   roomId?: RoomId;
   fishjam: FishjamClient;
 
-  constructor(config: FishjamConfig) {
-    this.fishjam = new FishjamClient(config);
+  private constructor(fishjam: FishjamClient) {
+    this.fishjam = fishjam;
+  }
+
+  static async create(config: FishjamConfig): Promise<FishjamService> {
+    const fishjam = await FishjamClient.create(config);
+    return new FishjamService(fishjam);
   }
 
   async createPeer() {

examples/room-manager/src/plugins/fishjam.ts

@@ -34,7 +34,7 @@ export const fishjamPlugin = fastifyPlugin(async (fastify: FastifyInstance): Pro
     throw new Error('The `fishjamPlugin` plugin has already been registered.');
   }
 
-  const fishjamClient = new FishjamClient({
+  const fishjamClient = await FishjamClient.create({
     fishjamId: fastify.config.FISHJAM_ID,
     managementToken: fastify.config.FISHJAM_MANAGEMENT_TOKEN,
   });

examples/selective-subscription/backend/src/index.ts

@@ -4,7 +4,7 @@ import { peerController } from './controllers/peers';
 import { notificationsController } from './controllers/notifications';
 import { FishjamService } from './service/fishjam';
 
-const fishjam = new FishjamService({
+const fishjam = await FishjamService.create({
   fishjamId: process.env.FISHJAM_ID!,
   managementToken: process.env.FISHJAM_TOKEN!,
 });

examples/selective-subscription/backend/src/service/fishjam.ts

@@ -12,9 +12,9 @@ export class FishjamService extends EventTarget {
   roomId?: RoomId;
   fishjam: FishjamClient;
 
-  constructor(config: FishjamConfig) {
+  private constructor(fishjam: FishjamClient, config: FishjamConfig) {
     super();
-    this.fishjam = new FishjamClient(config);
+    this.fishjam = fishjam;
     const notifier = new FishjamWSNotifier(
       config,
       () => {},
@@ -27,6 +27,11 @@ export class FishjamService extends EventTarget {
     notifier.on('trackRemoved', (msg) => this.emit('trackRemoved', msg));
   }
 
+  static async create(config: FishjamConfig): Promise<FishjamService> {
+    const fishjam = await FishjamClient.create(config);
+    return new FishjamService(fishjam, config);
+  }
+
   async createPeer() {
     try {
       return await this.makePeer();

examples/transcription/src/index.ts

@@ -12,7 +12,7 @@ const fishjamConfig = {
   managementToken: process.env.FISHJAM_TOKEN,
 };
 
-const fishjam = new FishjamService(fishjamConfig);
+const fishjam = await FishjamService.create(fishjamConfig);
 
 new TranscriptionService(fishjamConfig, process.env.GEMINI_API_KEY);
 

examples/transcription/src/service/fishjam.ts

@@ -4,8 +4,13 @@ export class FishjamService {
   roomId?: RoomId;
   fishjam: FishjamClient;
 
-  constructor(config: FishjamConfig) {
-    this.fishjam = new FishjamClient(config);
+  private constructor(fishjam: FishjamClient) {
+    this.fishjam = fishjam;
+  }
+
+  static async create(config: FishjamConfig): Promise<FishjamService> {
+    const fishjam = await FishjamClient.create(config);
+    return new FishjamService(fishjam);
   }
 
   async createPeer() {

packages/js-server-sdk/src/client.ts

@@ -12,6 +12,7 @@ import {
 } from '@fishjam-cloud/fishjam-openapi';
 import type { AgentCallbacks, FishjamConfig, PeerId, Room, RoomId, Peer } from './types';
 import { mapException } from './exceptions/mapper';
+import { InvalidFishjamCredentialsException } from './exceptions';
 import { getFishjamUrl } from './utils';
 import { FishjamAgent, TrackId } from './agent';
 import packageJson from '../package.json';
@@ -32,6 +33,10 @@ export class FishjamClient {
   /**
    * Create new instance of Fishjam Client.
    *
+   * Does not verify credentials against the backend — use
+   * {@link FishjamClient.create} or call
+   * {@link FishjamClient.checkCredentials} afterwards for that.
+   *
    * Example usage:
    * ```
    * const fishjamClient = new FishjamClient({
@@ -62,6 +67,47 @@ export class FishjamClient {
     this.fishjamConfig = config;
   }
 
+  /**
+   * Async factory: constructs a client and verifies credentials against
+   * the backend.
+   *
+   * Throws {@link InvalidFishjamCredentialsException} when the
+   * `fishjamId` / `managementToken` pair is rejected by the backend.
+   *
+   * Example:
+   * ```
+   * const client = await FishjamClient.create({
+   *   fishjamId: process.env.FISHJAM_ID!,
+   *   managementToken: process.env.FISHJAM_MANAGEMENT_TOKEN!,
+   * });
+   * ```
+   */
+  static async create(config: FishjamConfig): Promise<FishjamClient> {
+    const client = new FishjamClient(config);
+    await client.checkCredentials();
+    return client;
+  }
+
+  /**
+   * Verifies the configured credentials by making a single lightweight
+   * call to the Fishjam backend. Resolves on success, throws
+   * {@link InvalidFishjamCredentialsException} on 401/404 from the backend,
+   * otherwise rethrows the standard mapped exception.
+   */
+  async checkCredentials(): Promise<void> {
+    try {
+      await this.roomApi.getAllRooms();
+    } catch (error) {
+      if (axios.isAxiosError(error)) {
+        const status = error.response?.status;
+        if (status === 401 || status === 404) {
+          throw new InvalidFishjamCredentialsException(error);
+        }
+      }
+      throw mapException(error);
+    }
+  }
+
   private handleDeprecationHeader(headers: RawAxiosResponseHeaders): void {
     try {
       const deprecationHeader = headers['x-fishjam-api-deprecated'];

packages/js-server-sdk/src/exceptions/index.ts

@@ -28,6 +28,8 @@ export class RoomNotFoundException extends FishjamBaseException {}
 
 export class FishjamNotFoundException extends FishjamBaseException {}
 
+export class InvalidFishjamCredentialsException extends FishjamBaseException {}
+
 export class PeerNotFoundException extends FishjamBaseException {}
 
 export class ServiceUnavailableException extends FishjamBaseException {}