@allratestoday/sdk 1.2.1 → 1.3.0

package/dist/index.js

@@ -25,25 +25,53 @@ __export(index_exports, {
   default: () => index_default
 });
 module.exports = __toCommonJS(index_exports);
-var BASE_URL = "https://allratestoday.com";
+var DEFAULT_BASE_URL = "https://allratestoday.com";
+var DEFAULT_TIMEOUT = 1e4;
+var AllRatesTodayError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.name = "AllRatesTodayError";
+    this.status = status;
+  }
+};
 var AllRatesToday = class {
   /**
    * Create an AllRatesToday client.
-   * @param options - API key is required. Register for free at https://allratestoday.com/register
+   *
+   * ```ts
+   * const client = new AllRatesToday({ apiKey: 'art_live_...' });
+   * ```
+   *
+   * @param options - Configuration. Get a free API key at https://allratestoday.com/register
    */
   constructor(options = {}) {
     this.apiKey = options.apiKey;
-    this.baseUrl = options.baseUrl || BASE_URL;
-    this.timeout = options.timeout || 1e4;
+    this.baseUrl = options.baseUrl || DEFAULT_BASE_URL;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT;
+  }
+  // -------------------------------------------------------------------------
+  // Internal
+  // -------------------------------------------------------------------------
+  resolveKey(override) {
+    const key = override || this.apiKey;
+    if (!key) {
+      throw new AllRatesTodayError(
+        "API key is required. Register for free at https://allratestoday.com/register"
+      );
+    }
+    return key;
   }
-  async request(path, params = {}) {
+  async request(path, params = {}, keyOverride) {
     const url = new URL(path, this.baseUrl);
     for (const [key, value] of Object.entries(params)) {
-      if (value) url.searchParams.set(key, value);
+      if (value !== void 0 && value !== "") {
+        url.searchParams.set(key, value);
+      }
     }
     const headers = {};
-    if (this.apiKey) {
-      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    const apiKey = keyOverride || this.apiKey;
+    if (apiKey) {
+      headers["Authorization"] = `Bearer ${apiKey}`;
     }
     const response = await fetch(url.toString(), {
       headers,
@@ -58,38 +86,229 @@ var AllRatesToday = class {
     }
     return response.json();
   }
+  formatDate(date) {
+    if (date instanceof Date) {
+      return date.toISOString().split("T")[0];
+    }
+    return date;
+  }
+  // -------------------------------------------------------------------------
+  // Public API
+  // -------------------------------------------------------------------------
+  /**
+   * Get the latest exchange rates.
+   *
+   * ```ts
+   * // All rates from USD
+   * const data = await client.latest();
+   *
+   * // Specific symbols with EUR base
+   * const data = await client.latest({ base: 'EUR', symbols: ['USD', 'GBP', 'JPY'] });
+   * ```
+   */
+  async latest(options = {}) {
+    const key = this.resolveKey(options.apiKey);
+    const params = {};
+    params.source = options.base || "USD";
+    if (options.symbols?.length) {
+      params.target = options.symbols.join(",");
+    }
+    const raw = await this.request(
+      "/api/v1/rates",
+      params,
+      key
+    );
+    const ratesArray = Array.isArray(raw) ? raw : [raw];
+    const rates = {};
+    let date = "";
+    for (const r of ratesArray) {
+      rates[r.target] = r.rate;
+      if (r.time) date = r.time;
+    }
+    return { base: params.source, date, rates };
+  }
+  /**
+   * Get exchange rates for a specific historical date.
+   *
+   * ```ts
+   * // Using a string
+   * const data = await client.forDate('2026-01-15');
+   *
+   * // Using a Date object
+   * const data = await client.forDate(new Date('2026-01-15'));
+   *
+   * // With options
+   * const data = await client.forDate('2026-01-15', { base: 'EUR', symbols: ['USD', 'GBP'] });
+   * ```
+   */
+  async forDate(date, options = {}) {
+    const key = this.resolveKey(options.apiKey);
+    const dateStr = this.formatDate(date);
+    const params = {
+      source: options.base || "USD",
+      from: dateStr,
+      to: dateStr
+    };
+    if (options.symbols?.length) {
+      params.target = options.symbols.join(",");
+    }
+    const raw = await this.request(
+      "/api/historical-rates",
+      params,
+      key
+    );
+    const rates = {};
+    if (raw.rates?.length) {
+      for (const r of raw.rates) {
+        rates[raw.target] = r.rate;
+      }
+    }
+    if (raw.current) {
+      rates[raw.target] = raw.current.rate;
+    }
+    return { base: params.source, date: dateStr, rates };
+  }
+  /**
+   * Get exchange rate time series between two dates.
+   *
+   * ```ts
+   * const data = await client.timeSeries('2026-01-01', '2026-03-31', {
+   *   base: 'USD',
+   *   symbols: ['EUR', 'GBP'],
+   * });
+   *
+   * // Access rates by date
+   * console.log(data.rates['2026-01-15']); // { EUR: 0.92, GBP: 0.78 }
+   * ```
+   */
+  async timeSeries(startDate, endDate, options = {}) {
+    const key = this.resolveKey(options.apiKey);
+    const start = this.formatDate(startDate);
+    const end = this.formatDate(endDate);
+    const source = options.base || "USD";
+    const params = {
+      source,
+      from: start,
+      to: end
+    };
+    if (options.symbols?.length) {
+      params.target = options.symbols.join(",");
+    }
+    const raw = await this.request(
+      "/api/historical-rates",
+      params,
+      key
+    );
+    const rates = {};
+    if (raw.rates) {
+      for (const point of raw.rates) {
+        const dateKey = point.time.split("T")[0];
+        if (!rates[dateKey]) rates[dateKey] = {};
+        rates[dateKey][raw.target] = point.rate;
+      }
+    }
+    return { base: source, startDate: start, endDate: end, rates };
+  }
+  /**
+   * Get all supported currency symbols.
+   *
+   * ```ts
+   * const { symbols } = await client.symbols();
+   * console.log(symbols);
+   * // { USD: 'United States Dollar', EUR: 'Euro', GBP: 'British Pound', ... }
+   *
+   * // Build a currency dropdown
+   * const options = Object.entries(symbols).map(([code, name]) => ({ code, name }));
+   * ```
+   */
+  async symbols(options = {}) {
+    const key = this.resolveKey(options.apiKey);
+    return this.request("/api/v1/symbols", {}, key);
+  }
   /**
-   * Get exchange rate between two currencies (requires API key)
+   * Get exchange rate between two currencies.
+   *
+   * ```ts
+   * const rate = await client.getRate('USD', 'EUR');
+   * console.log(`1 USD = ${rate.rate} EUR`);
+   *
+   * // With amount
+   * const rate = await client.getRate('USD', 'EUR', 1000);
+   * console.log(`$1,000 = €${rate.to.amount}`);
+   * ```
    */
-  async getRate(from, to, amount) {
-    if (!this.apiKey) throw new AllRatesTodayError("API key required. Register for free at https://allratestoday.com/register");
+  async getRate(from, to, amount, options = {}) {
+    const key = this.resolveKey(options.apiKey);
     const params = { source: from, target: to };
     if (amount !== void 0) params.amount = String(amount);
-    return this.request("/api/v1/rates", params);
+    return this.request("/api/v1/rates", params, key);
   }
   /**
-   * Get authenticated exchange rate (requires API key)
+   * Get authenticated exchange rates with metadata.
+   *
+   * ```ts
+   * const rates = await client.getRates('USD', 'EUR');
+   * rates.forEach(r => console.log(`${r.source}/${r.target}: ${r.rate} at ${r.time}`));
+   * ```
    */
-  async getRates(source, target) {
-    if (!this.apiKey) throw new AllRatesTodayError("API key required for authenticated requests");
-    return this.request("/api/v1/rates", { source, target });
+  async getRates(source, target, options = {}) {
+    const key = this.resolveKey(options.apiKey);
+    return this.request("/api/v1/rates", { source, target }, key);
   }
   /**
-   * Get historical rates (requires API key)
+   * Get historical rates by period.
+   *
+   * ```ts
+   * const history = await client.getHistoricalRates('USD', 'EUR', '30d');
+   * history.rates.forEach(point => {
+   *   console.log(`${point.time}: ${point.rate}`);
+   * });
+   * ```
    */
-  async getHistoricalRates(source, target, period = "7d") {
-    if (!this.apiKey) throw new AllRatesTodayError("API key required for historical rates");
-    return this.request("/api/historical-rates", {
-      source,
-      target,
-      period
-    });
+  async getHistoricalRates(source, target, period = "7d", options = {}) {
+    const key = this.resolveKey(options.apiKey);
+    return this.request(
+      "/api/historical-rates",
+      { source, target, period },
+      key
+    );
   }
   /**
-   * Convert an amount from one currency to another
+   * Convert an amount between two currencies.
+   *
+   * ```ts
+   * // Current rate
+   * const result = await client.convert('USD', 'EUR', 1000);
+   * console.log(`$1,000 = €${result.result}`);
+   *
+   * // Historical conversion
+   * const result = await client.convert('USD', 'EUR', 1000, { date: '2026-01-15' });
+   * console.log(`Rate on Jan 15: ${result.rate}`);
+   * ```
    */
-  async convert(from, to, amount) {
-    const data = await this.getRate(from, to, amount);
+  async convert(from, to, amount, options = {}) {
+    const key = this.resolveKey(options.apiKey);
+    if (options.date) {
+      const dateStr = this.formatDate(options.date);
+      const params = {
+        source: from,
+        target: to,
+        from: dateStr,
+        to: dateStr
+      };
+      const raw = await this.request(
+        "/api/historical-rates",
+        params,
+        key
+      );
+      const rate = raw.current?.rate ?? raw.rates?.[0]?.rate ?? 0;
+      return { from, to, amount, result: Number((amount * rate).toFixed(6)), rate, date: dateStr };
+    }
+    const data = await this.request(
+      "/api/v1/rates",
+      { source: from, target: to, amount: String(amount) },
+      key
+    );
     return {
       from,
       to,
@@ -99,13 +318,6 @@ var AllRatesToday = class {
     };
   }
 };
-var AllRatesTodayError = class extends Error {
-  constructor(message, status) {
-    super(message);
-    this.name = "AllRatesTodayError";
-    this.status = status;
-  }
-};
 var index_default = AllRatesToday;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.mjs

@@ -1,23 +1,51 @@
 // src/index.ts
-var BASE_URL = "https://allratestoday.com";
+var DEFAULT_BASE_URL = "https://allratestoday.com";
+var DEFAULT_TIMEOUT = 1e4;
+var AllRatesTodayError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.name = "AllRatesTodayError";
+    this.status = status;
+  }
+};
 var AllRatesToday = class {
   /**
    * Create an AllRatesToday client.
-   * @param options - API key is required. Register for free at https://allratestoday.com/register
+   *
+   * ```ts
+   * const client = new AllRatesToday({ apiKey: 'art_live_...' });
+   * ```
+   *
+   * @param options - Configuration. Get a free API key at https://allratestoday.com/register
    */
   constructor(options = {}) {
     this.apiKey = options.apiKey;
-    this.baseUrl = options.baseUrl || BASE_URL;
-    this.timeout = options.timeout || 1e4;
+    this.baseUrl = options.baseUrl || DEFAULT_BASE_URL;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT;
+  }
+  // -------------------------------------------------------------------------
+  // Internal
+  // -------------------------------------------------------------------------
+  resolveKey(override) {
+    const key = override || this.apiKey;
+    if (!key) {
+      throw new AllRatesTodayError(
+        "API key is required. Register for free at https://allratestoday.com/register"
+      );
+    }
+    return key;
   }
-  async request(path, params = {}) {
+  async request(path, params = {}, keyOverride) {
     const url = new URL(path, this.baseUrl);
     for (const [key, value] of Object.entries(params)) {
-      if (value) url.searchParams.set(key, value);
+      if (value !== void 0 && value !== "") {
+        url.searchParams.set(key, value);
+      }
     }
     const headers = {};
-    if (this.apiKey) {
-      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    const apiKey = keyOverride || this.apiKey;
+    if (apiKey) {
+      headers["Authorization"] = `Bearer ${apiKey}`;
     }
     const response = await fetch(url.toString(), {
       headers,
@@ -32,38 +60,229 @@ var AllRatesToday = class {
     }
     return response.json();
   }
+  formatDate(date) {
+    if (date instanceof Date) {
+      return date.toISOString().split("T")[0];
+    }
+    return date;
+  }
+  // -------------------------------------------------------------------------
+  // Public API
+  // -------------------------------------------------------------------------
+  /**
+   * Get the latest exchange rates.
+   *
+   * ```ts
+   * // All rates from USD
+   * const data = await client.latest();
+   *
+   * // Specific symbols with EUR base
+   * const data = await client.latest({ base: 'EUR', symbols: ['USD', 'GBP', 'JPY'] });
+   * ```
+   */
+  async latest(options = {}) {
+    const key = this.resolveKey(options.apiKey);
+    const params = {};
+    params.source = options.base || "USD";
+    if (options.symbols?.length) {
+      params.target = options.symbols.join(",");
+    }
+    const raw = await this.request(
+      "/api/v1/rates",
+      params,
+      key
+    );
+    const ratesArray = Array.isArray(raw) ? raw : [raw];
+    const rates = {};
+    let date = "";
+    for (const r of ratesArray) {
+      rates[r.target] = r.rate;
+      if (r.time) date = r.time;
+    }
+    return { base: params.source, date, rates };
+  }
+  /**
+   * Get exchange rates for a specific historical date.
+   *
+   * ```ts
+   * // Using a string
+   * const data = await client.forDate('2026-01-15');
+   *
+   * // Using a Date object
+   * const data = await client.forDate(new Date('2026-01-15'));
+   *
+   * // With options
+   * const data = await client.forDate('2026-01-15', { base: 'EUR', symbols: ['USD', 'GBP'] });
+   * ```
+   */
+  async forDate(date, options = {}) {
+    const key = this.resolveKey(options.apiKey);
+    const dateStr = this.formatDate(date);
+    const params = {
+      source: options.base || "USD",
+      from: dateStr,
+      to: dateStr
+    };
+    if (options.symbols?.length) {
+      params.target = options.symbols.join(",");
+    }
+    const raw = await this.request(
+      "/api/historical-rates",
+      params,
+      key
+    );
+    const rates = {};
+    if (raw.rates?.length) {
+      for (const r of raw.rates) {
+        rates[raw.target] = r.rate;
+      }
+    }
+    if (raw.current) {
+      rates[raw.target] = raw.current.rate;
+    }
+    return { base: params.source, date: dateStr, rates };
+  }
+  /**
+   * Get exchange rate time series between two dates.
+   *
+   * ```ts
+   * const data = await client.timeSeries('2026-01-01', '2026-03-31', {
+   *   base: 'USD',
+   *   symbols: ['EUR', 'GBP'],
+   * });
+   *
+   * // Access rates by date
+   * console.log(data.rates['2026-01-15']); // { EUR: 0.92, GBP: 0.78 }
+   * ```
+   */
+  async timeSeries(startDate, endDate, options = {}) {
+    const key = this.resolveKey(options.apiKey);
+    const start = this.formatDate(startDate);
+    const end = this.formatDate(endDate);
+    const source = options.base || "USD";
+    const params = {
+      source,
+      from: start,
+      to: end
+    };
+    if (options.symbols?.length) {
+      params.target = options.symbols.join(",");
+    }
+    const raw = await this.request(
+      "/api/historical-rates",
+      params,
+      key
+    );
+    const rates = {};
+    if (raw.rates) {
+      for (const point of raw.rates) {
+        const dateKey = point.time.split("T")[0];
+        if (!rates[dateKey]) rates[dateKey] = {};
+        rates[dateKey][raw.target] = point.rate;
+      }
+    }
+    return { base: source, startDate: start, endDate: end, rates };
+  }
+  /**
+   * Get all supported currency symbols.
+   *
+   * ```ts
+   * const { symbols } = await client.symbols();
+   * console.log(symbols);
+   * // { USD: 'United States Dollar', EUR: 'Euro', GBP: 'British Pound', ... }
+   *
+   * // Build a currency dropdown
+   * const options = Object.entries(symbols).map(([code, name]) => ({ code, name }));
+   * ```
+   */
+  async symbols(options = {}) {
+    const key = this.resolveKey(options.apiKey);
+    return this.request("/api/v1/symbols", {}, key);
+  }
   /**
-   * Get exchange rate between two currencies (requires API key)
+   * Get exchange rate between two currencies.
+   *
+   * ```ts
+   * const rate = await client.getRate('USD', 'EUR');
+   * console.log(`1 USD = ${rate.rate} EUR`);
+   *
+   * // With amount
+   * const rate = await client.getRate('USD', 'EUR', 1000);
+   * console.log(`$1,000 = €${rate.to.amount}`);
+   * ```
    */
-  async getRate(from, to, amount) {
-    if (!this.apiKey) throw new AllRatesTodayError("API key required. Register for free at https://allratestoday.com/register");
+  async getRate(from, to, amount, options = {}) {
+    const key = this.resolveKey(options.apiKey);
     const params = { source: from, target: to };
     if (amount !== void 0) params.amount = String(amount);
-    return this.request("/api/v1/rates", params);
+    return this.request("/api/v1/rates", params, key);
   }
   /**
-   * Get authenticated exchange rate (requires API key)
+   * Get authenticated exchange rates with metadata.
+   *
+   * ```ts
+   * const rates = await client.getRates('USD', 'EUR');
+   * rates.forEach(r => console.log(`${r.source}/${r.target}: ${r.rate} at ${r.time}`));
+   * ```
    */
-  async getRates(source, target) {
-    if (!this.apiKey) throw new AllRatesTodayError("API key required for authenticated requests");
-    return this.request("/api/v1/rates", { source, target });
+  async getRates(source, target, options = {}) {
+    const key = this.resolveKey(options.apiKey);
+    return this.request("/api/v1/rates", { source, target }, key);
   }
   /**
-   * Get historical rates (requires API key)
+   * Get historical rates by period.
+   *
+   * ```ts
+   * const history = await client.getHistoricalRates('USD', 'EUR', '30d');
+   * history.rates.forEach(point => {
+   *   console.log(`${point.time}: ${point.rate}`);
+   * });
+   * ```
    */
-  async getHistoricalRates(source, target, period = "7d") {
-    if (!this.apiKey) throw new AllRatesTodayError("API key required for historical rates");
-    return this.request("/api/historical-rates", {
-      source,
-      target,
-      period
-    });
+  async getHistoricalRates(source, target, period = "7d", options = {}) {
+    const key = this.resolveKey(options.apiKey);
+    return this.request(
+      "/api/historical-rates",
+      { source, target, period },
+      key
+    );
   }
   /**
-   * Convert an amount from one currency to another
+   * Convert an amount between two currencies.
+   *
+   * ```ts
+   * // Current rate
+   * const result = await client.convert('USD', 'EUR', 1000);
+   * console.log(`$1,000 = €${result.result}`);
+   *
+   * // Historical conversion
+   * const result = await client.convert('USD', 'EUR', 1000, { date: '2026-01-15' });
+   * console.log(`Rate on Jan 15: ${result.rate}`);
+   * ```
    */
-  async convert(from, to, amount) {
-    const data = await this.getRate(from, to, amount);
+  async convert(from, to, amount, options = {}) {
+    const key = this.resolveKey(options.apiKey);
+    if (options.date) {
+      const dateStr = this.formatDate(options.date);
+      const params = {
+        source: from,
+        target: to,
+        from: dateStr,
+        to: dateStr
+      };
+      const raw = await this.request(
+        "/api/historical-rates",
+        params,
+        key
+      );
+      const rate = raw.current?.rate ?? raw.rates?.[0]?.rate ?? 0;
+      return { from, to, amount, result: Number((amount * rate).toFixed(6)), rate, date: dateStr };
+    }
+    const data = await this.request(
+      "/api/v1/rates",
+      { source: from, target: to, amount: String(amount) },
+      key
+    );
     return {
       from,
       to,
@@ -73,13 +292,6 @@ var AllRatesToday = class {
     };
   }
 };
-var AllRatesTodayError = class extends Error {
-  constructor(message, status) {
-    super(message);
-    this.name = "AllRatesTodayError";
-    this.status = status;
-  }
-};
 var index_default = AllRatesToday;
 export {
   AllRatesToday,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@allratestoday/sdk",
-  "version": "1.2.1",
-  "description": "Official JavaScript/TypeScript SDK for AllRatesToday exchange rate API",
+  "version": "1.3.0",
+  "description": "The most elegant way to access real-time mid-market exchange rates in Node.js and browsers. 160+ currencies, Reuters/Refinitiv data, zero dependencies.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",