npm package: @finket/finketcurrencies
Description: finket currency code library from ISO 4217
Author: fkt
Latest version: 1.0.0

# @finket/finketcurrencies

A lightweight Node.js library for retrieving ISO 4217 currency data.  
Provides intuitive methods to access currency details by their alphabetic code ("USD", "ARS") or numeric code ("840", "032").  
Perfect for financial applications, internationalization, and currency-related tasks.

## Features

- Access currency info: code, number, name, minor unit exponent, countries.
- Search by ISO 4217 alphabetic or numeric codes (case-insensitive).
- Minimal dependencies for lightweight footprint.
- Robust input validation.
- Easy integration into Node.js projects.

## Installation

```bash
npm install @finket/finketcurrencies
```

> For private registries (e.g., AWS CodeArtifact), configure your `.npmrc` or authenticate before installing. See [Private Registry](#private-registry).

## Usage

The library offers two main methods: `findByCode` and `findByNumber`.  
You can retrieve full details for any ISO 4217 currency.

### Example 1: Finding Currencies by Alphabetic Code

```javascript
const { findByCode } = require("@finket/finketcurrencies");

// Find USD
const usd = findByCode("USD");
console.log(usd);

// Find ARS
const ars = findByCode("ARS");
console.log(ars);
```

**Expected Output:**

```json
{
  "code": "USD",
  "number": "840",
  "name": "US Dollar",
  "exponent": 2,
  "countries": ["UNITED STATES"]
}
{
  "code": "ARS",
  "number": "032",
  "name": "Argentine Peso",
  "exponent": 2,
  "countries": ["ARGENTINA"]
}
```

### Example 2: Finding Currencies by Numeric Code

```javascript
const { findByNumber } = require("@finket/finketcurrencies");

// Find by numeric code
const usd = findByNumber("840");
const ars = findByNumber(32); // numeric input also allowed

console.log(usd);
console.log(ars);
```

### Example 3: Processing Multiple Currencies

```javascript
const { findByCode } = require("@finket/finketcurrencies");

const codes = ["USD", "ARS", "EUR"];
codes.forEach(code => {
  const currency = findByCode(code);
  if (currency) {
    console.log(`${currency.name} (${currency.code}): ${currency.countries.join(", ")}`);
  } else {
    console.log(`Currency not found: ${code}`);
  }
});
```

**Expected Output (partial):**

```
US Dollar (USD): UNITED STATES
Argentine Peso (ARS): ARGENTINA
Euro (EUR): ÅLAND ISLANDS, EUROPEAN UNION, ...
```

## API Reference

### findByCode(code)

Retrieves a currency by its ISO 4217 alphabetic code.

- **Parameters:**  
  `code` (`string`): Alphabetic code (e.g., "USD"). Case-insensitive.
- **Returns:**  
  A currency object or `null` if not found.
- **Throws:**  
  Error if `code` is not a valid non-empty string.

---

### findByNumber(number)

Retrieves a currency by its ISO 4217 numeric code.

- **Parameters:**  
  `number` (`string | number`): Numeric code (e.g., "840" or `840`).
- **Returns:**  
  A currency object or `null` if not found.
- **Throws:**  
  Error if `number` is not provided.

---

### Currency Object Structure

Each currency object contains:

| Field     | Type     | Example     |
|-----------|----------|-------------|
| code      | `string` | "USD"        |
| number    | `string` | "840"        |
| name      | `string` | "US Dollar"  |
| exponent  | `number` | 2            |
| countries | `string[]` | ["UNITED STATES"] |

---

## Requirements

- Node.js **v14** or higher
- Dependency: [`csv-parse`](https://www.npmjs.com/package/csv-parse) (`^5.5.6`)

## Private Registry

If you're using a private registry like AWS CodeArtifact:

```bash
aws codeartifact login --tool npm --domain finket --domain-owner 194122164712 --repository finket --region us-east-1
npm install @finket/finketcurrencies
```

Contact your registry administrator for more details.

## Contributing

Contributions are welcome! 🚀

1. Fork the repo.
2. Create your branch: `git checkout -b feature/your-feature`
3. Commit your changes: `git commit -m "Add feature"`
4. Push to the branch: `git push origin feature/your-feature`
5. Open a pull request.

> Please ensure your code includes tests and follows project standards.

## Issues

Report bugs or request features by [opening an issue](https://github.com/your-repo/finketcurrencies/issues).

## License

This project is licensed under the MIT License.  
See the [LICENSE](LICENSE) file for details.

## Acknowledgments

- Currency data based on ISO 4217 official standard.
- CSV parsing powered by the [`csv-parse`](https://www.npmjs.com/package/csv-parse) library.