tn-financial-data 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 moonshot6666
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# tn-financial-data
+
+Hosted US equity financial data for agents.
+
+`tn-financial-data` is the published agent-facing surface for the hosted API:
+
+- `tn-financial-data query ...`
+- `tn-financial-data skill ...`
+- `tn-financial-data describe opencli`
+- a typed TypeScript client from `tn-financial-data`
+
+The package does not bundle your API key.
+The installed package does not read project-local `.env` files. Pass credentials with CLI flags or environment variables in the invoking process.
+
+## Requires API Access
+
+Installing the package is not enough for live reads.
+
+- You need a valid `TN_FINANCIAL_DATA_API_KEY` or `--api-key <key>`
+- `skill install` only installs the packaged skill bundle; it does not provision API access
+- the agent or CLI process itself must see the API key in its runtime environment
+- the default hosted base URL is `https://api.truenorth-financial.ai/v1`
+
+This package is the hosted agent-facing surface only. The repo's website, local playground, self-hosting runtime, and local TradingView prototype tooling are intentionally outside the npm contract.
+
+## Features
+
+- Company facts, financials, prices, news, insider trades, ownership, and global rates through one hosted API
+- Agent-friendly CLI with JSON output and self-description via `tn-financial-data describe opencli`
+- Packaged skill bundle for Claude and OpenCode installs
+- Typed TypeScript client from the root package export
+- Stable production default at `https://api.truenorth-financial.ai/v1`
+
+## Installation
+
+```bash
+npm install -g tn-financial-data
+
+export TN_FINANCIAL_DATA_API_KEY=<your-api-key>
+tn-financial-data query available-tickers
+```
+
+Live reads accept:
+
+- `--api-key <key>`
+- `TN_FINANCIAL_DATA_API_KEY`
+- `TN_FINANCIAL_DATA_API_KEYS`
+
+Optional base URL override:
+
+- `TN_FINANCIAL_DATA_API_BASE_URL`
+
+The published CLI reads those values from the current process environment only.
+
+Production default:
+
+```text
+https://api.truenorth-financial.ai/v1
+```
+
+## Quick Start
+
+```bash
+tn-financial-data query available-tickers
+tn-financial-data query company --ticker AAPL
+tn-financial-data query general-overview --ticker AAPL --period quarterly --financial-limit 4 --news-limit 5
+tn-financial-data skill install --tool claude
+tn-financial-data describe opencli
+```
+
+Ownership semantics:
+
+- `institutional-ownership` is issuer-centric: ticker to holders
+- `investor-portfolio` is investor-centric: filer to holdings via SEC 13F
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `tn-financial-data query ...` | Hosted reads over the stable API contract |
+| `tn-financial-data skill install` | Install the packaged skill bundle |
+| `tn-financial-data skill print` | Print the packaged skill or adapter metadata |
+| `tn-financial-data describe opencli` | Emit machine-readable CLI metadata for agents |
+
+Common query examples:
+
+```bash
+tn-financial-data query financials --ticker AAPL --period annual --statement all
+tn-financial-data query financial-metrics --ticker AAPL --period annual --limit 4
+tn-financial-data query earnings --ticker AAPL --period quarterly --limit 8
+tn-financial-data query quarterly-highlights --ticker AAPL
+tn-financial-data query prices --ticker AAPL --interval day --start-date 2025-01-01 --end-date 2025-01-31
+tn-financial-data query institutional-ownership --ticker AAPL --limit 20
+tn-financial-data query investor-portfolio --investor vanguard --limit 20
+tn-financial-data query global-rates --series ecb_refi,boe_sonia --limit 10
+tn-financial-data query screen --filter "trailing_pe < 25" --filter "recommendation_key = buy" --limit 10
+```
+
+## Skill Usage
+
+Install the packaged skill bundle:
+
+```bash
+tn-financial-data skill install --tool opencode
+tn-financial-data skill install --tool claude
+```
+
+OpenCode quick start after install:
+
+```bash
+export TN_FINANCIAL_DATA_API_KEY=<your-api-key>
+opencode run "Use tn-financial-data to summarize AAPL."
+```
+
+If you want to test against a non-default deployment, pass the base URL in the same process environment:
+
+```bash
+export TN_FINANCIAL_DATA_API_BASE_URL=https://your-host.example.com/v1
+opencode run "Use tn-financial-data to list available tickers."
+```
+
+Print the packaged skill or adapter metadata:
+
+```bash
+tn-financial-data skill print
+tn-financial-data skill print --adapter openai
+```
+
+Describe the CLI for tool-aware runtimes:
+
+```bash
+tn-financial-data describe opencli
+```
+
+Installing the skill bundle does not provision API access. Agents still need the same runtime credential for live reads.
+For OpenCode, that means the `opencode` process itself must see `TN_FINANCIAL_DATA_API_KEY` in its environment.
+
+## Agent Integration
+
+Agents only need two surfaces:
+
+```bash
+tn-financial-data describe opencli
+tn-financial-data query <resource> [options]
+```
+
+`describe opencli` exposes the command surface in a machine-readable form for tool-aware runtimes.
+
+## TypeScript Client
+
+```ts
+import { TnFinancialData } from "tn-financial-data";
+
+const client = new TnFinancialData({
+  apiKey: process.env.TN_FINANCIAL_DATA_API_KEY!,
+});
+
+const company = await client.getCompanyFacts({ ticker: "AAPL" });
+console.log(company.company_facts.name);
+```
+
+## Package Scope
+
+The published npm package is intentionally limited to agent-facing surfaces. Repository-specific website, local playground, and self-hosting workflows live in the GitHub repository, not in the npm contract.