@fin.cx/opendata 4.3.0 → 4.4.0

package/ts/cpi/interfaces.ts

@@ -0,0 +1,137 @@
+/** A calendar month, `YYYY-MM`. */
+export type TIsoMonth = string;
+
+/** A calendar year, `YYYY`. */
+export type TIsoYear = string;
+
+/** The period of an index value: a month (`YYYY-MM`) or a year (`YYYY`, the annual average). */
+export type TCpiPeriod = TIsoMonth | TIsoYear;
+
+/** Which price index a value belongs to: `de-vpi`, the Verbraucherpreisindex für Deutschland of the Statistisches Bundesamt. */
+export type TCpiIndex = 'de-vpi';
+
+export type TCpiFrequency = 'monthly' | 'annual';
+
+/**
+ * - `final`: the value as published, final until the next change of the base year;
+ * - `estimated`: a value the source marks as an estimate (the Bundesbank's `OBS_STATUS` `E`, for the
+ *   latest month at times). It is no published index value and is never used in a calculation.
+ */
+export type TCpiValueStatus = 'final' | 'estimated';
+
+/** One index value as its source states it. */
+export interface ICpiValue {
+  index: TCpiIndex;
+  period: TCpiPeriod;
+  /**
+   * The value as a decimal with a point and exactly the digits published, trailing zeros included
+   * (`'100.0'`, `'113.5'`). Never a float.
+   */
+  value: string;
+  /** the base the value is stated on, as the source writes it: `'2020=100'` */
+  base: string;
+  status: TCpiValueStatus;
+}
+
+/** A source's answer as it arrived: its HTTP status and its body as text. */
+export interface ICpiServiceAnswer {
+  httpStatus: number;
+  text: string;
+}
+
+/**
+ * Where a series comes from and how it must be credited. The figures are those of the Statistisches
+ * Bundesamt (Destatis) under the Datenlizenz Deutschland – Namensnennung – Version 2.0.
+ */
+export interface ICpiSourceNote {
+  source: 'bundesbank';
+  /** who delivered the figures: `'Deutsche Bundesbank'` */
+  provider: string;
+  /** whose figures they are: `'Statistisches Bundesamt (Destatis)'` */
+  dataOrigin: string;
+  /** the series' title as the answer gives it */
+  title: string;
+  /** the series key as the answer gives it, its base included: `'BBDP1.M.DE.N.VPI.C.A00000.I20.A'` */
+  key: string;
+  /** the request the figures were read from */
+  uri: string;
+  licence: string;
+  licenceUri: string;
+  /** the source note to show wherever the figures are shown */
+  attribution: string;
+}
+
+/** A range of index values of one series and one base, as one answer gave them. */
+export interface ICpiSeries {
+  index: TCpiIndex;
+  frequency: TCpiFrequency;
+  /** `'2020=100'` */
+  base: string;
+  /** `2020` */
+  baseYear: number;
+  /** the published values, oldest first */
+  values: ICpiValue[];
+  /** the values the source marks as estimates, oldest first; kept apart so that no calculation takes one */
+  estimates: ICpiValue[];
+  source: ICpiSourceNote;
+  answer: ICpiServiceAnswer;
+}
+
+/** One published value with where it comes from and the answer it was read from. */
+export interface ICpiReading extends ICpiValue {
+  source: ICpiSourceNote;
+  answer: ICpiServiceAnswer;
+}
+
+/** The thresholds of a percent rule: the reference value times (1 ± percent / 100), rounded to its digits. */
+export interface ICpiThresholds {
+  index: TCpiIndex;
+  base: string;
+  /** the percentage asked for, as given */
+  percent: string;
+  upper: string;
+  lower: string;
+}
+
+export interface ICpiReachOptions {
+  /** `up`: the upper threshold, `down`: the lower one, `either`: whichever comes first */
+  direction: 'up' | 'down' | 'either';
+  /** `reached`: the threshold itself counts; `exceeded`: only a value beyond it counts */
+  reach: 'reached' | 'exceeded';
+}
+
+export interface ICpiScaleOptions {
+  /**
+   * - `index_ratio` (default): amount × new index / old index, as the Statistisches Bundesamt writes it;
+   * - `rounded_percent`: amount × (100 + the change in percent rounded to one decimal) / 100.
+   */
+  basis?: 'index_ratio' | 'rounded_percent';
+}
+
+/** A `fetch` as the WHATWG standard defines it; injectable for tests and for a fetch that reaches only public addresses. */
+export type TCpiFetch = (input: string, init: RequestInit) => Promise<Response>;
+
+export interface ICpiClientOptions {
+  /** default: the runtime's `fetch` */
+  fetch?: TCpiFetch;
+  /** default: the official address (`bundesbankCpiBaseUrl`); a test's own server otherwise */
+  baseUrl?: string;
+  /** how long one request may take, the answer included; default `defaultCpiTimeoutMs` */
+  timeoutMs?: number;
+  /** sent as `User-Agent` where given */
+  userAgent?: string;
+}
+
+export interface ICpiMonthlyInput {
+  from: TIsoMonth;
+  /** default: whatever the source has published after `from` */
+  to?: TIsoMonth;
+  signal?: AbortSignal;
+}
+
+export interface ICpiAnnualInput {
+  from: TIsoYear;
+  /** default: whatever the source has published after `from` */
+  to?: TIsoYear;
+  signal?: AbortSignal;
+}

package/ts/cpi/request.ts

@@ -0,0 +1,49 @@
+import { CpiError } from './classes.cpierror.js';
+import { defaultCpiTimeoutMs } from './constants.js';
+import type { ICpiClientOptions, ICpiServiceAnswer, TCpiFetch } from './interfaces.js';
+
+/** The time a client gives one request: its option, or the default; anything else than a positive whole number of milliseconds is refused. */
+export const timeoutOf = (optionsArg: ICpiClientOptions): number => {
+  const timeout = optionsArg.timeoutMs ?? defaultCpiTimeoutMs;
+  if (!Number.isSafeInteger(timeout) || timeout <= 0) {
+    throw new CpiError('invalid_input', `the time limit is a positive whole number of milliseconds, got ${String(optionsArg.timeoutMs)}`);
+  }
+  return timeout;
+};
+
+/**
+ * Sends one `GET` for CSV and reads the answer whole, within the client's time. The caller's signal
+ * ends it as `aborted`, the time as `timeout`, and a request that could not be sent or answered as
+ * `unreachable`; nothing is retried. The timer ends with the request, answered or not.
+ */
+export const getText = async (
+  optionsArg: ICpiClientOptions,
+  urlArg: string,
+  signalArg: AbortSignal | undefined,
+): Promise<ICpiServiceAnswer> => {
+  const fetchFn: TCpiFetch = optionsArg.fetch ?? ((inputArg, initArg) => fetch(inputArg, initArg));
+  if (signalArg?.aborted) {
+    throw new CpiError('aborted', 'the request was ended by its caller', { service: 'bundesbank' }, { cause: signalArg.reason });
+  }
+  const timeout = new AbortController();
+  const timer = setTimeout(() => timeout.abort(new Error('the client\'s time ran out')), timeoutOf(optionsArg));
+  const signal = signalArg ? AbortSignal.any([signalArg, timeout.signal]) : timeout.signal;
+  try {
+    const response = await fetchFn(urlArg, {
+      method: 'GET',
+      headers: { accept: 'text/csv', ...(optionsArg.userAgent ? { 'user-agent': optionsArg.userAgent } : {}) },
+      signal,
+    });
+    return { httpStatus: response.status, text: await response.text() };
+  } catch (error) {
+    if (signalArg?.aborted) {
+      throw new CpiError('aborted', 'the request was ended by its caller', { service: 'bundesbank' }, { cause: error });
+    }
+    if (timeout.signal.aborted) {
+      throw new CpiError('timeout', 'the source did not answer in time', { service: 'bundesbank' }, { cause: error });
+    }
+    throw new CpiError('unreachable', 'the source could not be reached', { service: 'bundesbank' }, { cause: error });
+  } finally {
+    clearTimeout(timer);
+  }
+};

package/ts/plugins.ts

@@ -6,9 +6,8 @@ export {
 }
 
 // @push.rocks scope
-import * as qenv from '@push.rocks/qenv';
-import * as smartdelay from '@push.rocks/smartdelay';
 import * as smartpath from '@push.rocks/smartpath';
+import * as smartpromise from '@push.rocks/smartpromise';
 import * as smartrequest from '@push.rocks/smartrequest';
 
 const getErrorMessage = (error: unknown) => {
@@ -21,8 +20,7 @@ const getErrorMessage = (error: unknown) => {
 
 export {
   getErrorMessage,
-  qenv,
-  smartdelay,
   smartpath,
+  smartpromise,
   smartrequest,
 }

package/ts/stocks/classes.baseproviderservice.ts

@@ -224,7 +224,7 @@ export abstract class BaseProviderService<TProvider extends IBaseProvider, TData
         if (attempt < maxAttempts) {
           const delay = (config.retryDelay || 1000) * attempt;
           console.log(`Retry attempt ${attempt} after ${delay}ms`);
-          await plugins.smartdelay.delayFor(delay);
+          await plugins.smartpromise.delayFor(delay);
         }
       }
     }

package/ts/stocks/classes.fundamentalsservice.ts

@@ -321,7 +321,7 @@ export class FundamentalsService implements IFundamentalsProviderRegistry {
         if (attempt < maxAttempts) {
           const delay = (config.retryDelay || 1000) * attempt;
           console.log(`Retry attempt ${attempt} after ${delay}ms`);
-          await plugins.smartdelay.delayFor(delay);
+          await plugins.smartpromise.delayFor(delay);
         }
       }
     }

package/ts/stocks/classes.stockdataservice.ts

@@ -494,7 +494,7 @@ export class StockDataService {
         if (attempt < maxAttempts) {
           const delay = (config.retryDelay || 1000) * attempt;
           console.log(`Retry attempt ${attempt} after ${delay}ms`);
-          await plugins.smartdelay.delayFor(delay);
+          await plugins.smartpromise.delayFor(delay);
         }
       }
     }

package/ts/stocks/classes.stockservice.ts

@@ -449,7 +449,7 @@ export class StockPriceService implements IProviderRegistry {
         if (attempt < maxAttempts) {
           const delay = (config.retryDelay || 1000) * attempt;
           console.log(`Retry attempt ${attempt} after ${delay}ms`);
-          await plugins.smartdelay.delayFor(delay);
+          await plugins.smartpromise.delayFor(delay);
         }
       }
     }

package/ts/stocks/providers/provider.coingecko.ts

@@ -48,7 +48,7 @@ class RateLimiter {
     if (this.requestTimes.length >= this.maxRequestsPerMinute) {
       const oldestRequest = this.requestTimes[0];
       const waitTime = 60000 - (now - oldestRequest) + 100; // +100ms buffer
-      await plugins.smartdelay.delayFor(waitTime);
+      await plugins.smartpromise.delayFor(waitTime);
       return this.waitForSlot(); // Recursively check again
     }
 
@@ -773,7 +773,7 @@ export class CoinGeckoProvider implements IStockProvider {
           );
 
           if (attempt < maxRetries - 1) {
-            await plugins.smartdelay.delayFor(error.waitTime);
+            await plugins.smartpromise.delayFor(error.waitTime);
             continue;
           } else {
             this.logger.error(`Max retries (${maxRetries}) exceeded for ${operationName} due to rate limiting`);

package/ts/stocks/providers/provider.secedgar.ts

@@ -36,7 +36,7 @@ class RateLimiter {
     if (this.requestTimes.length >= this.maxRequestsPerSecond) {
       const oldestRequest = this.requestTimes[0];
       const waitTime = 1000 - (now - oldestRequest) + 10; // +10ms buffer
-      await plugins.smartdelay.delayFor(waitTime);
+      await plugins.smartpromise.delayFor(waitTime);
       return this.waitForSlot(); // Recursively check again
     }