purchasing-power-parity-advanced/README.md

An advanced PPP conversion calculator with optional flags and country names, and country code listing functions.

# purchasing-power-parity-advanced
An advanced Node.js module and CLI for converting currency amounts between countries using PPP (Purchasing Power Parity), with optional flags, country names, and country code lookup.

---

## Installation

```bash
# Install globally (CLI)
npm install -g purchasing-power-parity-advanced

# Or install locally in your project
npm install purchasing-power-parity-advanced
```

---

## CLI Usage

Once installed globally, use the `ppp-calculator` command:

```bash
ppp-calculator <ORIG_CODE> <AMOUNT> <TARGET1,TARGET2,...>
```

Example:

```bash
ppp-calculator USA 100 CAN,GBR,IND
```

Sample output:

```json
{
  "origin": {
    "code": "USA",
    "amount": 100,
    "flag": "🇺🇸",
    "currencyCode": "USD",
    "currencyName": "US Dollar",
    "currencySymbol": "$",
    "countryName": "United States"
  },
  "results": [
    {
      "code": "CAN",
      "amount": 114.23,
      "flag": "🇨🇦",
      "currencyCode": "CAD",
      "currencyName": "Canadian Dollar",
      "currencySymbol": "$",
      "countryName": "Canada"
    },
    …
  ]
}
```

> **Note:** CLI always includes flags and names. For more control, use the programmatic API.

---

## Programmatic API

Import and use in your Node.js code:

```js
const {
  convertPPP,
  listCountries,
  listCountryCodes
} = require('purchasing-power-parity-advanced');
```

### 1) listCountries()

Returns a sorted array of ISO3 country codes available for PPP conversion.

```js
(async () => {
  const codes = await listCountries();
  console.log(codes); // ['AFG','ALB','DZA',…,'USA',…]
})();
```

### 2) listCountryCodes()

Returns an array of all countries with ISO3, ISO2 codes and full names.

```js
const allCountries = listCountryCodes();
console.log(allCountries[0]);
// { iso3: 'AFG', iso2: 'AF', name: 'Afghanistan' }
```

### 3) convertPPP(originCode, amount, targetCodes, options?)

Convert an amount from one country to multiple target countries.

**Signature**:
```ts
async function convertPPP(
  originCode: string,       // ISO3 origin country code, e.g. 'USA'
  amount: number,           // amount in origin currency
  targetCodes: string[],    // array of ISO3 target codes, e.g. ['CAN','GBR']
  options?: {
    includeFlags?: boolean;   // default: true
    includeNames?: boolean;   // default: true
  }
): Promise<{
  origin: {
    code: string;
    amount: number;
    flag?: string;
    currencyCode: string | null;
    currencyName: string | null;
    currencySymbol: string | null;
    countryName?: string;
  };
  results: Array<{
    code: string;
    amount: number | null;
    flag?: string;
    currencyCode: string | null;
    currencyName: string | null;
    currencySymbol: string | null;
    countryName?: string;
  }>;
}>
```

**Example**:
```js
(async () => {
  // Basic conversion (flags + names enabled)
  let res = await convertPPP('USA', 100, ['CAN','GBR']);

  // Disable flags and names
  res = await convertPPP('USA', 100, ['CAN','GBR'], {
    includeFlags: false,
    includeNames: false
  });

  console.dir(res, { depth: null });
})();
```

---

## License

MIT