feat: implement tvdb auth

Author: dvcol

src/models/tvdb/tvdb-client.model.ts

@@ -14,11 +14,13 @@ import {
  * @see [documentation]{@link https://thetvdb.github.io/v4-api/#/Login/post_login}
  */
 export type TvdbClientSettings = {
-  /** The domain name (i.e. https://api4.thetvdb.com/v4) */
+  /** The domain name (e.g. https://api4.thetvdb.com) */
   endpoint: string;
+  /** The api version (e.g. v4) */
+  version: string;
   /** The consumer client identifier */
   useragent: string;
-  /** The app secret  */
+  /** The app api key  */
   apiKey: string;
   /** token time-to-live (28 days) */
   tokenTTL: number;
@@ -27,8 +29,8 @@ export type TvdbClientSettings = {
 export type TvdbClientOptions = BaseOptions<TvdbClientSettings, TvdbApiResponse>;
 
 export type TvdbClientAuthentication = {
-  access_token?: string;
-  user_pin?: string;
+  accessToken?: string;
+  userPin?: string;
   expires?: number;
 };
 

src/models/tvdb/tvdb-search.model.ts

@@ -51,6 +51,7 @@ export type TvdbSearchQuery = {
 };
 
 export type TvdbSearch = {
+  objectID: string;
   aliases: string[];
   companies: string[];
   companyType: string;
@@ -64,7 +65,6 @@ export type TvdbSearch = {
   is_official: boolean;
   name_translated: string;
   network: string;
-  objectID: string;
   officialList: string;
   overview: string;
   /** Record of languages with their translations */

src/services/common/base-client.ts

@@ -122,20 +122,13 @@ export abstract class BaseClient<
   SettingsType extends RecursiveRecord = RecursiveRecord,
   AuthenticationType extends RecursiveRecord = RecursiveRecord,
 > {
-  protected _cache: CacheStore<ResponseType>;
-  protected _settings: SettingsType;
-  protected _authentication: ObservableState<AuthenticationType>;
-  protected _callListeners: Observable<QueryType>;
+  private readonly _settings: SettingsType;
+  private _cache: CacheStore<ResponseType>;
+  private _authentication: ObservableState<AuthenticationType>;
+  private _callListeners: Observable<QueryType>;
 
-  /**
-   * Clears the cache entry for the specified key.
-   * If no key is provided, clears the entire cache.
-   *
-   * @param key - The cache key.
-   */
-  clearCache(key?: string) {
-    if (key) return this._cache?.delete(key);
-    return this._cache?.clear();
+  protected get settings() {
+    return this._settings;
   }
 
   /**
@@ -192,6 +185,17 @@ export abstract class BaseClient<
     };
   }
 
+  /**
+   * Clears the cache entry for the specified key.
+   * If no key is provided, clears the entire cache.
+   *
+   * @param key - The cache key.
+   */
+  clearCache(key?: string) {
+    if (key) return this._cache?.delete(key);
+    return this._cache?.clear();
+  }
+
   /**
    * Binds BaseTraktClient _call instance to the endpoint instance and the call method of the endpoint
    *
@@ -421,26 +425,6 @@ export const parseUrl = <P extends RecursiveRecord = RecursiveRecord, O extends
   const [pathPart, queryPart] = template.url.split('?');
 
   let path = pathPart;
-  const queryParams: URLSearchParams = new URLSearchParams(queryPart);
-
-  if (queryPart) {
-    queryParams.forEach((value, key, parent) => {
-      const _value = params[key] ?? value;
-
-      // If a value is found we encode
-      if (_value !== undefined && _value !== '') {
-        queryParams.set(key, typeof _value === 'object' ? JSON.stringify(_value) : _value);
-      }
-      // If the parameter is required we raise error
-      else if (template.opts?.parameters?.query?.[key] === true) {
-        throw Error(`Missing mandatory query parameter: '${key}'`);
-      }
-      // else we remove the empty field from parameters
-      else {
-        parent.delete(key);
-      }
-    });
-  }
 
   // fill query path parameter i.e :variable
   if (pathPart.includes(':')) {
@@ -462,6 +446,20 @@ export const parseUrl = <P extends RecursiveRecord = RecursiveRecord, O extends
   }
 
   const url = new URL(path, endpoint);
-  url.search = queryParams.toString();
+
+  if (queryPart) {
+    new URLSearchParams(queryPart).forEach((value, key) => {
+      const _value = params[key] ?? value;
+
+      // If a value is found we encode
+      if (_value !== undefined && _value !== '') {
+        url.searchParams.set(key, typeof _value === 'object' ? JSON.stringify(_value) : _value);
+      }
+      // If the parameter is required we raise error
+      else if (template.opts?.parameters?.query?.[key] === true) {
+        throw Error(`Missing mandatory query parameter: '${key}'`);
+      }
+    });
+  }
   return url;
 };

src/services/trakt-client/clients/base-trakt-client.ts

@@ -144,10 +144,10 @@ export class BaseTraktClient
    */
   protected _parseHeaders<T extends TraktApiParams = TraktApiParams>(template: TraktApiTemplate<T>): HeadersInit {
     const headers: HeadersInit = {
-      [TraktApiHeaders.UserAgent]: this._settings.useragent,
+      [TraktApiHeaders.UserAgent]: this.settings.useragent,
       [TraktApiHeaders.ContentType]: BaseHeaderContentType.Json,
       [TraktApiHeaders.TraktApiVersion]: '2',
-      [TraktApiHeaders.TraktApiKey]: this._settings.client_id,
+      [TraktApiHeaders.TraktApiKey]: this.settings.client_id,
     };
 
     if (template.opts?.auth === true && !this.auth.access_token) {
@@ -174,7 +174,7 @@ export class BaseTraktClient
    * @throws {Error} Throws an error if mandatory parameters are missing or if a filter is not supported.
    */
   protected _parseUrl<T extends TraktApiParams = TraktApiParams>(template: TraktApiTemplate<T>, params: T): URL {
-    const url = parseUrl<T>(template, params, this._settings.endpoint);
+    const url = parseUrl<T>(template, params, this.settings.endpoint);
     const queryParams = url.searchParams;
 
     // Adds Filters query parameters

src/services/trakt-client/clients/trakt-client.ts

@@ -52,22 +52,21 @@ export class TraktClient extends BaseTraktClient {
   /**
    * Exchanges an authorization code or refresh token for an access token.
    *
-   * @private
-   *
    * @param request - The request object containing the code or refresh token.
    *
    * @returns A promise resolving to the updated Trakt authentication information.
    *
    * @throws Error Throws an error if the exchange fails or an error is received from the server.
    *
+   * @private
+   *
    * @see handleError
-   * @memberof TraktClient
    */
   private async _exchange(request: Pick<TraktAuthenticationCodeRequest, 'code'> | Pick<TraktAuthenticationRefreshRequest, 'refresh_token'>) {
     const _request: TraktAuthenticationBaseRequest = {
-      client_id: this._settings.client_id,
-      client_secret: this._settings.client_secret,
-      redirect_uri: this._settings.redirect_uri,
+      client_id: this.settings.client_id,
+      client_secret: this.settings.client_secret,
+      redirect_uri: this.settings.redirect_uri,
       grant_type: 'code' in request ? 'authorization_code' : 'refresh_token',
       ...request,
     };
@@ -98,24 +97,23 @@ export class TraktClient extends BaseTraktClient {
   /**
    * Revokes the current authentication by invalidating the access token.
    *
-   * @private
-   *
    * @paramrequest - Additional parameters for revoking authentication.
    *
    * @returns A promise resolving when the authentication is successfully revoked.
    *
    * @throws Error Throws an error if no access token is found.
    *
+   * @private
+   *
    * @see isResponseOk
-   * @memberof TraktClient
    */
   private async _revoke(request: Partial<TraktAuthenticationRevokeRequest> = {}) {
     if (!request && !this.auth.access_token) throw new Error('No access token found.');
 
     const _request: TraktAuthenticationRevokeRequest = {
       token: this.auth.access_token!,
-      client_id: this._settings.client_id,
-      client_secret: this._settings.client_secret,
+      client_id: this.settings.client_id,
+      client_secret: this.settings.client_secret,
       ...request,
     };
 
@@ -129,8 +127,6 @@ export class TraktClient extends BaseTraktClient {
   /**
    * Initiates device authentication and retrieves the device code.
    *
-   * @private
-   *
    * @template T - The type of the authentication information to be returned (string means auth token, null means codes).
    *
    * @param {T extends string | null} code - The device code (if polling) or null to initiate a new device authentication.
@@ -139,21 +135,22 @@ export class TraktClient extends BaseTraktClient {
    *
    * @throws Error Throws an error if the device authentication fails.
    *
+   * @private
+   *
    * @see handleError
-   * @memberof TraktClient
    */
   private async _device<T extends string | null>(code: T): Promise<T extends null ? TraktDeviceAuthentication : TraktAuthentication> {
     try {
       let response: TraktApiResponse<TraktAuthentication | TraktDeviceAuthentication>;
       if (code) {
         response = await this.authentication.device.token({
-          client_id: this._settings.client_id,
-          client_secret: this._settings.client_secret,
+          client_id: this.settings.client_id,
+          client_secret: this.settings.client_secret,
           code,
         });
       } else {
         response = await this.authentication.device.code({
-          client_id: this._settings.client_id,
+          client_id: this.settings.client_id,
         });
       }
       return (await response.json()) as T extends null ? TraktDeviceAuthentication : TraktAuthentication;
@@ -162,6 +159,18 @@ export class TraktClient extends BaseTraktClient {
     }
   }
 
+  /**
+   * Polls the device authentication endpoint to complete the authentication.
+   * If the timeout is reached, the polling is cancelled and an error is thrown.
+   * If the authentication is successful, the polling is cancelled and the authentication information is returned.
+   *
+   * @param poll - The device authentication information.
+   * @param timeout - The timeout in milliseconds.
+   *
+   * @returns A promise resolving to the authentication information if successful
+   *
+   * @private
+   */
   private async _devicePolling(poll: TraktDeviceAuthentication, timeout: number) {
     if (timeout <= Date.now()) {
       clearInterval(this.polling);
@@ -198,8 +207,6 @@ export class TraktClient extends BaseTraktClient {
    * The code should then be used in conjunction with the {@link pollWithDeviceCode} method to finish authentication.
    *
    * @returns A promise resolving to the device authentication information.
-   *
-   * @memberof TraktClient
    */
   getDeviceCode() {
     return this._device(null);
@@ -211,8 +218,6 @@ export class TraktClient extends BaseTraktClient {
    * @param  poll - The device authentication information.
    *
    * @returns  A promise resolving to the completed authentication information or `undefined`.
-   *
-   * @memberof TraktClient
    */
   pollWithDeviceCode(poll: TraktDeviceAuthentication) {
     if (this.polling) {
@@ -244,8 +249,6 @@ export class TraktClient extends BaseTraktClient {
    * @returns A promise resolving to the response from the Trakt website.
    *
    * @see [authorize]{@link https://trakt.docs.apiary.io/#reference/authentication-oauth/authorize}
-   *
-   * @memberof TraktClient
    */
   redirectToAuthentication(request: Pick<TraktAuthenticationAuthorizeRequest, 'state' | 'signup' | 'prompt'> & { redirect?: RequestRedirect } = {}) {
     this.updateAuth(auth => ({ ...auth, state: request.state ?? randomHex() }));
@@ -257,8 +260,8 @@ export class TraktClient extends BaseTraktClient {
     return this.authentication.oAuth.authorize(
       {
         response_type: 'code',
-        client_id: this._settings.client_id,
-        redirect_uri: this._settings.redirect_uri,
+        client_id: this.settings.client_id,
+        redirect_uri: this.settings.redirect_uri,
         state: this.auth.state,
         ...request,
       },
@@ -275,8 +278,6 @@ export class TraktClient extends BaseTraktClient {
    * @returns  A promise resolving to the Trakt authentication information.
    *
    * @throws Error Throws an error if the CSRF token is invalid.
-   *
-   * @memberof TraktClient
    */
   exchangeCodeForToken(code: string, state?: string) {
     if (state && state !== this.auth.state) throw Error('Invalid CSRF (State)');
@@ -289,8 +290,6 @@ export class TraktClient extends BaseTraktClient {
    * @returns  A promise resolving to the updated Trakt authentication information.
    *
    * @throws Error Throws an error if no refresh token is found.
-   *
-   * @memberof TraktClient
    */
   refreshToken() {
     if (!this.auth.refresh_token) {
@@ -305,8 +304,6 @@ export class TraktClient extends BaseTraktClient {
    * @returns  A promise resolving when the authentication is successfully revoked.
    *
    * @throws Error Throws an error if no access token is found.
-   *
-   * @memberof TraktClient
    */
   async revokeAuthentication(): Promise<void> {
     if (this.auth.access_token) {
@@ -322,8 +319,6 @@ export class TraktClient extends BaseTraktClient {
    * @param auth - The Trakt authentication information to import.
    *
    * @returns A promise resolving to the imported Trakt authentication information.
-   *
-   * @memberof TraktClient
    */
   async importAuthentication(auth: TraktClientAuthentication): Promise<TraktClientAuthentication> {
     this.updateAuth(auth);