# FINATA B2B Public API Client Samples

These samples are small reference clients for contract customers integrating the FINATA B2B Public API.

They intentionally avoid external dependencies:

- `finata_public_api_client.js` uses Node.js 18+ built-in `fetch`.
- `finata_public_api_client.py` uses Python standard-library `urllib`.

## Version

Current sample version: `2026.07.29`

Package metadata version: `0.1.0`

The public API path is versioned as `/api/v1`. FINATA prioritizes backward-compatible response additions. Field removals or meaning changes are handled as customer-notified changes, not silent sample updates.

## Package metadata

This directory includes packaging metadata for controlled customer delivery:

- `package.json` keeps the JavaScript sample private and adds local npm scripts.
- `pyproject.toml` exposes the Python sample through a `finata-public-api` console script when installed in a customer test environment.
- `CHANGELOG.md` records sample package changes separately from the public API version.

These files are preparation for private distribution only. Do not publish them to a public npm or PyPI registry without a separate release review.

Before sharing the samples with a customer, run the release guard from the repository root:

```powershell
node .\tools\build_b2b_public_api_sample_release.js
```

To create a controlled delivery directory outside Git:

```powershell
node .\tools\build_b2b_public_api_sample_release.js `
  --out "D:\FINATA\b2b-api-releases" `
  --write `
  --approve-customer-delivery `
  --approved-by "FINATA API Ops" `
  --approval-note "Contract customer delivery approved"
```

The `--approve-customer-delivery` flag is required for write mode. The release manifest records the approval metadata, but it must not contain raw API keys, key hashes, or service tokens.

## Security

Store the raw API key in an environment variable or secret manager. Do not commit the key, paste it into browser bundles, or send it in public logs.

```powershell
$env:FINATA_API_KEY='finata_live_...'
```

For support requests, share the key prefix, request time, endpoint, and HTTP status. Do not share the raw key.

## JavaScript

```powershell
node .\finata_public_api_client.js --ticker 005930 --resource activism
node .\finata_public_api_client.js --ticker 005930 --resource all
node .\finata_public_api_client.js --openapi
npm run metrics
npm run activism
```

Use as a module:

```javascript
const { FinataClient } = require('./finata_public_api_client');

const client = new FinataClient({ apiKey: process.env.FINATA_API_KEY });
const result = await client.activism('005930');
console.log(result.data.opportunity_score);
```

## Python

```powershell
python .\finata_public_api_client.py --ticker 005930 --resource metrics
python .\finata_public_api_client.py --ticker 005930 --resource all
python .\finata_public_api_client.py --openapi
```

Use as a module:

```python
import os
from finata_public_api_client import FinataClient

client = FinataClient(api_key=os.environ["FINATA_API_KEY"])
result = client.activism("005930")
print(result["data"]["opportunity_score"])
```

## Resources

All data resources require a contract API key.

```text
metrics
financials
ownership
governance
activism
```

The OpenAPI document is public:

```text
https://finata.co.kr/api/v1/openapi
```

FINATA API responses are candidate data for customer review workflows. They are not investment advice, proxy advisory, trading recommendations, legal findings, or real-time market data.

## Change log

- `2026-07-29`: Added private package metadata, a release guard, the public developer guide link, activism resource examples, and dependency-free JavaScript/Python clients.