@evidinvest/aether-sdk 0.3.0

package/README.md

@@ -0,0 +1,61 @@
+# @evidinvest/aether-sdk
+
+Tiny typed HTTP client for the [Aether](https://aether.evidinvest.com) REST
+API — SEC filings, earnings-call transcripts, and EU financial regulation,
+every hit a ready-to-cite payload (exact source text + accession-numbered
+citation + sec.gov URL).
+
+## Install
+
+```bash
+pnpm add @evidinvest/aether-sdk   # or npm i / yarn add
+```
+
+## Use
+
+```ts
+import { AetherClient } from "@evidinvest/aether-sdk";
+
+const aether = new AetherClient({ apiKey: process.env.AETHER_API_KEY });
+
+// SEC filings (10-K/10-Q/8-K, prospectuses) + SE/JP/KR registries
+const filings = await aether.financialSearch({
+  query: "Apple revenue concentration risk",
+  limit: 5,
+});
+for (const c of filings.results) {
+  console.log(c.citation, "→", c.metadata?.source_url);
+  console.log(c.text.slice(0, 200));
+}
+
+// Earnings calls — speaker-attributed, point-in-time
+const calls = await aether.transcriptSearch({
+  query: "Blackwell demand",
+  ticker: "NVDA",
+  order: "earliest", // find the FIRST mention
+  limit: 5,
+});
+
+// EU regulation — MiFID II, MiCA, DORA, AML package (article-level)
+const reg = await aether.regulationSearch({
+  query: "stablecoin issuer own funds requirements",
+  limit: 5,
+});
+```
+
+Get an API key at https://aether.evidinvest.com/developer/keys (anonymous
+calls work but are rate-limited). Full request/response reference:
+[`docs/search.md`](../../docs/search.md).
+
+## Why this exists
+
+`@evidinvest/aether-mcp` already wraps the same API for MCP clients
+(ChatGPT, Claude, Cursor, Cline, …). This SDK is for everything else —
+plain Node scripts, Fastify/Next.js routes, workers, edge functions.
+
+It's intentionally minimal: one bearer-token-aware fetch wrapper, typed
+request/response shapes, no SDK-side retry/cache. Bring your own.
+
+## License
+
+Apache-2.0 — see [LICENSE](../../LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,154 @@
+/**
+ * @evidinvest/aether-sdk
+ *
+ * Thin typed HTTP client for the Aether REST API. The MCP wrapper in
+ * `@evidinvest/aether-mcp` uses the same endpoints via stdio; use this
+ * package directly when you want to call Aether from a plain Node app, a
+ * worker, a Next.js route handler, etc.
+ *
+ * Endpoints (same tools the MCP server exposes):
+ *   POST /v1/tools/financial_search   — SEC filings (10-K/10-Q/8-K, S-1…) + non-US registries
+ *   POST /v1/tools/transcript_search  — earnings-call transcripts + press exhibits
+ *   POST /v1/tools/regulation_search  — EU financial regulation (MiFID II, MiCA, DORA, AML)
+ *
+ * Auth is a bearer token — either a long-lived API key from
+ * https://aether.evidinvest.com/developer/keys or an OAuth access token
+ * from the device-code / authorization-code flow. The SDK doesn't manage
+ * token lifecycle; pass a fresh token in. Anonymous calls work but hit a
+ * low rate limit.
+ */
+export interface AetherClientOptions {
+    /**
+     * Bearer token. API key (`ak_…`) or OAuth access token. Required for
+     * authenticated quota; anonymous calls hit a low rate limit.
+     */
+    apiKey?: string;
+    /** Override the API base. Defaults to https://api.aether.evidinvest.com. */
+    baseUrl?: string;
+    /** Override fetch (e.g. node-fetch in older Node, MSW in tests). */
+    fetch?: typeof fetch;
+}
+export interface FinancialSearchInput {
+    /** Natural-language search query. */
+    query: string;
+    /**
+     * public_equity = single-company filing search; supply_chain =
+     * cross-company supplier/customer relationship evidence; auto (default) =
+     * detect from the query.
+     */
+    domain?: "public_equity" | "supply_chain" | "auto";
+    /** Max results (server caps at 50, default 10). */
+    limit?: number;
+    /** Optional metadata fields to project into each hit. */
+    fields?: string[];
+    /** Retrieval profile; default is the production winner. */
+    profile?: "bm25" | "hybrid" | "hybrid_rerank" | "hybrid_rerank_tickerprior";
+    /**
+     * "section" (default) returns the full SEC section the match belongs to;
+     * "chunk" returns only the matching ~500-token window; "both" returns both.
+     */
+    return_format?: "section" | "chunk" | "both";
+    /**
+     * Scope to non-US issuer jurisdictions (ISO-3166 alpha-2): ["SE"] Sweden /
+     * Bolagsverket, ["JP"] Japan / EDINET, ["KR"] Korea / DART. Omit to cover
+     * US SEC filings (the default).
+     */
+    jurisdiction?: string[];
+}
+/** One ready-to-cite evidence payload. */
+export interface AetherChunk {
+    id: string;
+    /** Exact section/chunk text from the primary source. */
+    text: string;
+    /** e.g. "sec/10-K/0000320193-25-000079". */
+    source: string;
+    /** e.g. "AAPL 10-K 2025-10-31 (Item 1A)". */
+    citation?: string;
+    /** Filing/call date, ISO YYYY-MM-DD. */
+    as_of_date?: string;
+    /** 0–1 retrieval confidence. */
+    confidence?: number;
+    /**
+     * cik, ticker, company_name, form_type, section, accession_number,
+     * source_url (sec.gov link), period_of_report, … (varies by tool).
+     */
+    metadata?: Record<string, unknown>;
+}
+export interface FinancialSearchOutput {
+    query: string;
+    domain: "public_equity" | "supply_chain" | "auto";
+    results: AetherChunk[];
+    total: number;
+    source: string;
+    latency_ms: number;
+}
+export interface TranscriptSearchInput {
+    query: string;
+    /** Uppercase symbol, e.g. "AAPL". */
+    ticker?: string;
+    /** e.g. 4 = last year of calls. */
+    lookback_quarters?: number;
+    /** "CEO" | "CFO" | "Analyst" | … */
+    speaker_role?: string;
+    limit?: number;
+    profile?: "bm25" | "hybrid";
+    /** Inclusive ISO date bounds on the call date (point-in-time retrieval). */
+    date_from?: string;
+    date_to?: string;
+    /** "earliest"/"latest" sort chronologically; "relevance" (default) by score. */
+    order?: "relevance" | "earliest" | "latest";
+    /** Provenance: "press_release" | "furnished_transcript" | "asr_call". */
+    source_type?: string;
+}
+export interface TranscriptSearchOutput {
+    query: string;
+    results: AetherChunk[];
+    total: number;
+    source: string;
+    latency_ms: number;
+}
+export interface RegulationSearchInput {
+    query: string;
+    /** Filter to act(s) by CELEX number, e.g. "32024R1624". */
+    celex?: string | string[];
+    /** "regulation" | "directive" | "rts" | "its" | "decision". */
+    doc_type?: string;
+    /** Single article label (Formex labels can be "12a"). */
+    article?: string;
+    /** "paragraph" | "article_intro" | "recital" | "table" | "annex". */
+    chunk_type?: string;
+    /** AML topic tag(s): "cdd" | "edd" | "pep" | "str_reporting" | … */
+    aml_topics?: string | string[];
+    /** Prefer EUR-Lex consolidated text over the original OJ text. */
+    prefer_consolidated?: boolean;
+    limit?: number;
+    profile?: "bm25" | "hybrid";
+}
+export interface RegulationSearchOutput {
+    query: string;
+    results: AetherChunk[];
+    total: number;
+    source: string;
+    latency_ms: number;
+}
+export declare class AetherError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(status: number, body: string, message?: string);
+}
+export declare class AetherClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    constructor(opts?: AetherClientOptions);
+    /** Search SEC filings (+ SE/JP/KR registries). */
+    financialSearch(input: FinancialSearchInput): Promise<FinancialSearchOutput>;
+    /** Search earnings-call transcripts and press exhibits. */
+    transcriptSearch(input: TranscriptSearchInput): Promise<TranscriptSearchOutput>;
+    /** Search EU financial regulation (MiFID II, MiCA, DORA, AML package). */
+    regulationSearch(input: RegulationSearchInput): Promise<RegulationSearchOutput>;
+    /** @deprecated Alias of {@link financialSearch}; kept for 0.x callers. */
+    search(input: FinancialSearchInput): Promise<FinancialSearchOutput>;
+    private request;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,74 @@
+/**
+ * @evidinvest/aether-sdk
+ *
+ * Thin typed HTTP client for the Aether REST API. The MCP wrapper in
+ * `@evidinvest/aether-mcp` uses the same endpoints via stdio; use this
+ * package directly when you want to call Aether from a plain Node app, a
+ * worker, a Next.js route handler, etc.
+ *
+ * Endpoints (same tools the MCP server exposes):
+ *   POST /v1/tools/financial_search   — SEC filings (10-K/10-Q/8-K, S-1…) + non-US registries
+ *   POST /v1/tools/transcript_search  — earnings-call transcripts + press exhibits
+ *   POST /v1/tools/regulation_search  — EU financial regulation (MiFID II, MiCA, DORA, AML)
+ *
+ * Auth is a bearer token — either a long-lived API key from
+ * https://aether.evidinvest.com/developer/keys or an OAuth access token
+ * from the device-code / authorization-code flow. The SDK doesn't manage
+ * token lifecycle; pass a fresh token in. Anonymous calls work but hit a
+ * low rate limit.
+ */
+// ---------------------------------------------------------------------------
+export class AetherError extends Error {
+    status;
+    body;
+    constructor(status, body, message) {
+        super(message ?? `Aether API error ${status}: ${body.slice(0, 200)}`);
+        this.status = status;
+        this.body = body;
+        this.name = "AetherError";
+    }
+}
+export class AetherClient {
+    baseUrl;
+    apiKey;
+    fetchImpl;
+    constructor(opts = {}) {
+        this.baseUrl = (opts.baseUrl ?? "https://api.aether.evidinvest.com").replace(/\/+$/, "");
+        this.apiKey = opts.apiKey;
+        this.fetchImpl = opts.fetch ?? globalThis.fetch;
+        if (!this.fetchImpl) {
+            throw new Error("Global fetch not found — pass `fetch` via AetherClientOptions or run on Node >= 20.");
+        }
+    }
+    /** Search SEC filings (+ SE/JP/KR registries). */
+    async financialSearch(input) {
+        return this.request("/v1/tools/financial_search", "POST", input);
+    }
+    /** Search earnings-call transcripts and press exhibits. */
+    async transcriptSearch(input) {
+        return this.request("/v1/tools/transcript_search", "POST", input);
+    }
+    /** Search EU financial regulation (MiFID II, MiCA, DORA, AML package). */
+    async regulationSearch(input) {
+        return this.request("/v1/tools/regulation_search", "POST", input);
+    }
+    /** @deprecated Alias of {@link financialSearch}; kept for 0.x callers. */
+    async search(input) {
+        return this.financialSearch(input);
+    }
+    async request(path, method, body) {
+        const headers = { "content-type": "application/json" };
+        if (this.apiKey)
+            headers.authorization = `Bearer ${this.apiKey}`;
+        const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            method,
+            headers,
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        if (!res.ok) {
+            throw new AetherError(res.status, await res.text());
+        }
+        return (await res.json());
+    }
+}
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@evidinvest/aether-sdk",
+  "version": "0.3.0",
+  "description": "Tiny TypeScript HTTP SDK for the Aether REST API — financial_search, marketplace, and account endpoints. Pairs with an API key or OAuth bearer token from https://aether.evidinvest.com.",
+  "keywords": [
+    "aether",
+    "sec-filings",
+    "earnings-transcripts",
+    "financial-search",
+    "sdk",
+    "client"
+  ],
+  "author": "EvidInvest / EBD-Sweden",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/EvidInvest/aether-developer/tree/main/clients/typescript",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EvidInvest/aether-developer.git",
+    "directory": "clients/typescript"
+  },
+  "bugs": {
+    "url": "https://github.com/EvidInvest/aether-developer/issues"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}