v1.0.0

Author: markus-peltola

.gitignore

@@ -104,4 +104,4 @@ dist
 .tern-port
 
 nodemon.json
-test.js
+test.*

README.md

@@ -1,39 +1,48 @@
-# example-api-client
+# fivaldi-api-client
 
-**ExampleApiClient** is a third party [Example API](https://example.com/docs/) client for NodeJS. It is a wrapper around an API client that has been [automatically generated](https://www.npmjs.com/package/swagger-typescript-api) using the [OpenAPI schema](https://example.com/openapi.json) provided by Example.
+**Fivaldi Api Client** is a third party [Fivaldi API](https://manuals.fivaldi.net/customer/api/index.html) client for NodeJS. It is a wrapper around an API client that has been [automatically generated](https://www.npmjs.com/package/swagger-typescript-api) using the [OpenAPI schema](https://manuals.fivaldi.net/customer/api/swagger.yaml) provided by Fivaldi.
 
 ## Installation
 
 Add to project's package.json:
 
 ```
-npm install @rantalainen/example-api-client
+npm install @rantalainen/fivaldi-api-client
 ```
 
 ### Import
 
-```javascript
-import { ExampleApiClient } from '@rantalainen/example-api-client';
+```typescript
+import { FivaldiApiClient } from '@rantalainen/fivaldi-api-client';
 ```
 
 ## Setup client with options
 
-In order to obtain an API key, please contact Example Support. An API key is needed to access all API functions.
+In order to obtain partner ID and partner secret, please contact Fivaldi Support. Partner id and partner secret are needed to access API functions. More information from [Fivaldi docs](https://support.fivaldi.fi/support/solutions/articles/77000567542-fivaldi-api).
 
-```javascript
-const example = new ExampleApiClient(
+```typescript
+const fivaldi = new FivaldiApiClient(
   {
-    apiKey: 'api_key'
+    partnerId: 'yourPartnerId',
+    partnerSecret: 'yourPartnerSecret',
+    // Optional arguments related to rate limiting
+    replenishRate: 2,
+    burstCapacity: 10
   },
   {
-    baseURL: 'https://dev.example.com'
+    // Optional config options
+    baseURL: 'https://api.fivaldi.net/customer/api',
+    timeout: 120000,
+    keepAliveAgent: true,
+    dnsCache: true
   }
 );
 ```
 
-Available methods can be found in the [API documentation](https://example.com/docs/).
+Available methods can be found in the [API documentation](https://manuals.fivaldi.net/customer/api/swagger.yaml).
 
 ## Resources
 
-- Example: https://example.com/
-- Example Developer Guide: https://example.com/docs/
+- Fivaldi website: https://www.visma.fi/visma-fivaldi/
+- Fivaldi API Documentation: https://support.fivaldi.fi/support/solutions/articles/77000567542-fivaldi-api
+- Fivaldi API Documentation (swagger): https://manuals.fivaldi.net/customer/api/index.html

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rantalainen/fivaldi-api-client",
   "version": "1.0.0",
-  "description": "",
+  "description": "Third party Fivaldi API client for NodeJS",
   "main": "dist/index.js",
   "scripts": {
     "dev": "tsc --watch",
@@ -33,6 +33,6 @@
     "typescript": "^4.9.5"
   },
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   }
 }

src/index.ts

@@ -1,11 +1,11 @@
 import { Api, ApiConfig } from './api';
-import { AxiosRequestConfig } from 'axios';
-import { HttpsAgent } from 'agentkeepalive';
+import { addAuthHeaders } from './signature';
+import { RateLimiter } from './rate-limiter';
 import { FivaldiApiClientConfig, FivaldiApiClientOptions } from './interfaces';
-import { FileBuffer } from './file-buffer';
-import https from 'https';
+import { InternalAxiosRequestConfig } from 'axios';
+import { HttpsAgent } from 'agentkeepalive';
 import CacheableLookup from 'cacheable-lookup';
-import FormData from 'form-data';
+import https from 'https';
 
 // DNS cache to prevent ENOTFOUND and other such issues
 const dnsCache = new CacheableLookup();
@@ -25,10 +25,14 @@ export class FivaldiApiClient {
   options: FivaldiApiClientOptions;
   config: Omit<FivaldiApiClientConfig, 'keepAliveAgent' | 'dnsCache'>;
   readonly api: FivaldiApiClientInstance;
+  private rateLimiter: RateLimiter;
 
   constructor(options: FivaldiApiClientOptions, config: FivaldiApiClientConfig = {}) {
-    // Set default config
-    config.baseURL = config.baseURL || 'hhttps://api.fivaldi.net/customer/api';
+    // Set config or use default values
+    config.baseURL = config.baseURL || 'https://api.fivaldi.net/customer/api';
+    // Make sure that the base URL does not end with a slash
+    if (config.baseURL.endsWith('/')) config.baseURL = config.baseURL.slice(0, -1);
+
     config.timeout = config.timeout || 120000;
 
     if (!options.partnerId || !options.partnerSecret) {
@@ -64,65 +68,78 @@ export class FivaldiApiClient {
     this.options = options;
     this.config = config;
 
-    // Initialize Example Api Client Instance
+    // Initialize rate limiter with default values (will be updated from API responses)
+    this.rateLimiter = new RateLimiter(options.replenishRate, options.burstCapacity);
+
+    // Initialize Fivaldi Api Client Instance
     this.api = new FivaldiApiClientInstance({
-      ...this.config,
-      securityWorker: this.config.securityWorker || this.securityWorker
+      ...this.config
     });
-    this.api.setSecurityData(this);
+
+    // Install rate limiter interceptor
+    this.installRateLimiter();
 
     // Install axios error handler
     this.installErrorHandler();
+
+    // Install security worker
+    this.installRequestSigner();
+  }
+
+  // Create a rate limiter interceptor that waits for tokens before allowing requests
+  private installRateLimiter() {
+    this.api.instance.interceptors.request.use(async (axiosRequestConfig: InternalAxiosRequestConfig) => {
+      // Wait for rate limiter to allow the request
+      await this.rateLimiter.waitUntilAvailable();
+      return axiosRequestConfig;
+    });
+  }
+
+  // Create a custom security worker installer that adds the Authorization header to every request
+  private installRequestSigner() {
+    this.api.instance.interceptors.request.use(async (axiosRequestConfig: InternalAxiosRequestConfig) => {
+      // Call the auth function to get the auth headers
+      const authHeaders = await addAuthHeaders(this.options.partnerId, this.options.partnerSecret, axiosRequestConfig);
+      // Add auth headers to the request config
+      Object.entries(authHeaders).forEach(([key, value]) => {
+        axiosRequestConfig.headers.set(key, value);
+      });
+
+      return axiosRequestConfig;
+    });
   }
 
   private installErrorHandler() {
     this.api.instance.interceptors.response.use(
-      (response) => response,
+      (response) => {
+        // Update rate limiter from response headers
+        if (response.headers) {
+          this.rateLimiter.updateFromHeaders(response.headers as Record<string, string | number>);
+        }
+        return response;
+      },
       (error) => {
-        error.message = `HTTP error ${error.response.status} (${error.response.statusText}): ` + JSON.stringify(error.response.data);
+        // Update rate limiter from error response headers if available
+        if (error.response?.headers) {
+          this.rateLimiter.updateFromHeaders(error.response.headers as Record<string, string | number>);
+        }
+
+        if (error.response) {
+          error.message =
+            `Fivaldi HTTP error ${error.response.status} (${error.response.statusText}): ` + JSON.stringify(error.response.data);
+        }
+
         throw error;
       }
     );
   }
-
-  private async securityWorker(fivaldi: FivaldiApiClient) {
-    const axiosRequestConfig: AxiosRequestConfig = {};
-
-    axiosRequestConfig.headers = {
-      Authorization: ''
-    };
-
-    return axiosRequestConfig;
-  }
 }
 
 class FivaldiApiClientInstance extends Api<any> {
   constructor(config?: ApiConfig<any>) {
     super(config);
   }
 
-  // Override createFormData because FormData needs to be imported manually
-  protected createFormData(input: Record<string, unknown>): any {
-    return Object.keys(input || {}).reduce((formData, key) => {
-      const property = input[key];
-      const propertyContent: any[] = property instanceof Array ? property : [property];
-
-      for (const formItem of propertyContent) {
-        const isFileType = formItem instanceof FileBuffer;
-
-        if (isFileType) {
-          formData.append(key, formItem.buffer, {
-            filename: formItem.name,
-            contentType: formItem.type
-          });
-        } else {
-          formData.append(key, this.stringifyFormItem(formItem));
-        }
-      }
-
-      return formData;
-    }, new FormData());
-  }
-
+  // If you need to add custom methods or properties, do it here
   helpers = {};
 }

src/interfaces.ts

@@ -7,6 +7,10 @@ export interface FivaldiApiClientOptions {
   partnerId: string;
   /** Partner secret that you get from Fivaldi */
   partnerSecret: string;
+  /** Rate limit replenish rate. This will automatically update from the first response header. */
+  replenishRate?: number;
+  /** Rate limit burst capacity. This will automatically update from the first response header. */
+  burstCapacity?: number;
 }
 
 export interface FivaldiApiClientConfig extends ApiConfig<any> {

src/rate-limiter.ts

@@ -0,0 +1,77 @@
+export class RateLimiter {
+  /** Amount of current tokens */
+  private tokens: number;
+  /** Timestamp of the last refill */
+  private lastRefill: number;
+  /** Rate at which tokens are replenished (tokens per second) */
+  private replenishRate: number;
+  /** Maximum burst capacity (max tokens that can be used in one second) */
+  private burstCapacity: number;
+
+  /**
+   * Creates a new RateLimiter instance.
+   * @param replenishRate Rate at which tokens are replenished (tokens per second).
+   *                      This is updated from API headers after each request.
+   *                      Default is 2 tokens per second.
+   * @param burstCapacity Maximum burst capacity (max tokens that can be used in one second).
+   *                      This is updated from API headers after each request.
+   *                      Default is 10 tokens.
+   */
+  constructor(replenishRate = 2, burstCapacity = 10) {
+    this.replenishRate = replenishRate;
+    this.burstCapacity = burstCapacity;
+    this.tokens = burstCapacity; // start full
+    this.lastRefill = Date.now();
+  }
+
+  private refillTokens() {
+    const now = Date.now();
+    const elapsedSeconds = (now - this.lastRefill) / 1000;
+    const tokensToAdd = elapsedSeconds * this.replenishRate;
+
+    this.tokens = Math.min(this.tokens + tokensToAdd, this.burstCapacity);
+    this.lastRefill = now;
+  }
+
+  /**
+   * Waits until the rate limiter has enough tokens available to proceed.
+   * @returns A promise that resolves when the rate limiter has enough tokens available to proceed.
+   */
+  public async waitUntilAvailable(): Promise<void> {
+    while (true) {
+      this.refillTokens();
+
+      if (this.tokens >= 3) {
+        this.tokens -= 1;
+        return;
+      }
+
+      const timeToNextTokenMs = 1000 / this.replenishRate;
+      await new Promise((resolve) => setTimeout(resolve, timeToNextTokenMs));
+    }
+  }
+
+  /**
+   * Updates the rate limiter's settings based on the headers from the API response.
+   * @param headers Headers from the API response to update the rate limiter's settings.
+   */
+  public updateFromHeaders(headers: Record<string, string | number | undefined>) {
+    const newRate = parseFloat(headers['x-ratelimit-replenish-rate'] as string);
+    const newBurst = parseFloat(headers['x-ratelimit-burst-capacity'] as string);
+    const remaining = parseFloat(headers['x-ratelimit-remaining'] as string);
+
+    if (!isNaN(newRate) && newRate > 0) {
+      this.replenishRate = newRate;
+    }
+
+    if (!isNaN(newBurst) && newBurst > 0) {
+      this.burstCapacity = newBurst;
+    }
+
+    if (!isNaN(remaining)) {
+      this.tokens = Math.min(remaining, this.burstCapacity);
+    }
+
+    this.lastRefill = Date.now();
+  }
+}