@flovialabs/sdk 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.1.1
+
+- CLI generation output shows the response status and incomplete reason. A delivered partial answer still exits 0; no continuation is generated automatically.
+- CLI status shows bought balance; usage shows server-provided bought totals and the generation subtotal without adding them twice. Free usage stays in percentages.
+- Corrected consent, replay lifetime, onboarding and copyable usage examples in the README.
+
+## 0.1.0
+
+First release. Flovia is in alpha; APIs may change.
+
+- `FloviaClient`: `status()`, `usageToday()`, `listTools()`, `call(tool, args)` over MCP (HTTP), and `generate()` for OpenAI-compatible text generation with a required operation id.
+- `FloviaError` with `code`, `nextStep`, `executed`, `retryAfterSeconds`, `operationId` and the full `reply`.
+- Optional one-time resend of rate-limited tool calls (`retryRateLimited`).
+- The `flovia` CLI: `status`, `usage`, `tools`, `call`, `generate`.
+- Lost or malformed replies preserve the operation ID and unknown execution state. Keys require HTTPS outside loopback and raw transport errors are not exposed; CLI stdin preserves split UTF-8 characters.
+- ESM with type declarations; no runtime dependencies. Node 20 or later, or Bun.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flovia Labs
+
+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

@@ -1,3 +1,156 @@
-# Temporary Holding Version
+# @flovialabs/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+TypeScript client and command-line tool for [Flovia](https://api.flovia.dev). It calls Flovia's tools over MCP (HTTP) and its OpenAI-compatible text generation.
+
+> **Flovia is in alpha; APIs may change.** Pin the version you use.
+
+- ESM with type declarations, no runtime dependencies (it uses `fetch` only).
+- Node.js 20 or later, or Bun.
+
+## Install
+
+```sh
+npm install --save-exact @flovialabs/sdk@0.1.1
+```
+
+## Your key
+
+You need an invitation to [register and receive a Flovia key](https://api.flovia.dev/join). Keep the key private; it is shown once. Follow the [connection guide](https://api.flovia.dev/) to confirm your email and start the free allowance. Contact [Flovia support](https://flovia.dev/contact) if you need access or lose your key. Installing this package does not create an account or start an allowance.
+
+Set your Flovia key (`flv_...`) in the environment:
+
+```sh
+export FLOVIA_KEY=flv_...
+```
+
+Or pass it as `new FloviaClient({ apiKey })`. The client keeps the key private: it does not appear in logs, error messages or `console.log(client)`. The SDK sends no telemetry.
+
+`baseUrl` requires HTTPS. Plain HTTP is allowed only for loopback development (`localhost`, `127.0.0.1`, `[::1]`). Raw transport diagnostics are not attached to errors because they may contain request headers.
+
+## Quick start
+
+```ts
+import { FloviaClient, newOperationId } from "@flovialabs/sdk";
+
+const flovia = new FloviaClient(); // reads FLOVIA_KEY; base URL https://api.flovia.dev
+
+// Your free windows, services and the contract version
+const status = await flovia.status();
+console.log(status.five_hour.used_pct, status.week.used_pct);
+
+// Your lookups today (or since a time within the last 7 days)
+const usage = await flovia.usageToday(); // today, UTC
+
+// Any tool: list them, then call one
+const tools = await flovia.listTools();
+const reply = await flovia.call("flovia_status");
+
+// A text generation (uses credits). Save the operation id before sending.
+const op = newOperationId();
+const request = { model: "gpt-6-luna" as const, input: "Explain a DEX aggregator in one sentence." };
+// Persist { op, request } in your application's private storage before the next line.
+const g = await flovia.generate(request, { operationId: op });
+console.log(g.response.status, g.response.incomplete_details, g.outputText);
+```
+
+### First data lookup
+
+`listTools()` returns the tools offered to your account and their `inputSchema`. A catalog call sends nothing to the data provider. For example, list CoinGecko paths, then make one price lookup:
+
+```ts
+await flovia.call("flovia_coingecko", {
+  path: "list", request_text: "Which prices can I read?", purpose: "choose a supported path",
+});
+const priceRequest = {
+  path: "/simple/price", query: { ids: "bitcoin", vs_currencies: "usd", include_last_updated_at: true },
+  request_text: "What is Bitcoin's USD price?", purpose: "check a price with its update time",
+  conversation_id: "sdk-price-example", operation_id: newOperationId(),
+};
+// Save priceRequest before sending; this lookup uses the shared allowance.
+const price = await flovia.call("flovia_coingecko", priceRequest);
+```
+
+If either call asks for a notice or consent, stop and follow the human-answer flow below. Read the returned source time, coverage and missing-value notes; a successful lookup is not a guarantee that it answers your question. Flovia exposes selected read-only paths, methods and public HTML hosts, not every feature of the upstream plans. Use the live catalog for the supported subset. OpenAI supports text generation with `gpt-6-luna`; it does not fetch other providers or offer image/audio generation.
+
+### Operation ids and replay
+
+`generate()` requires an operation id (8-128 characters of `A-Z a-z 0-9 _ . : -`). Create one with `newOperationId()` and store it with the request **before** sending.
+
+If the reply is lost (timeout, network error, `executed: "unknown"`), keep the request and **same** id. A completed or incomplete answer can normally be reopened for about **15 minutes** with the unchanged request, `replayed: true` and no additional charge. Follow `nextStep` for `operation_pending` or `upstream_unknown`; the answer may not yet be available. After `answer_expired` or `operation_retired`, Flovia cannot return the saved text. Never start a new id to recover a lost answer: that may run and charge twice. A genuinely new generation requires the person's decision to spend again.
+
+## Errors
+
+A refusal (`ok: false`) or a failed request throws `FloviaError`:
+
+| field | meaning |
+| --- | --- |
+| `code` | a public code such as `rate_limited` or `window_5h` (`PUBLIC_CODES` lists them), or `http_<status>` |
+| `message` | what happened |
+| `nextStep` | what to do next |
+| `executed` | `"yes"`, `"no"` or `"unknown"`: whether the request ran. On `"unknown"`, keep the same operation id |
+| `retryAfterSeconds` | how long to wait, when given |
+| `status` | the HTTP status, when there is one |
+| `operationId` | the operation id of the request |
+| `reply` | the full reply body |
+
+### `notice_first` and `data_consent_needed`: a human must answer
+
+These two codes are thrown on purpose. They need the person's own answer, and the SDK never answers for them.
+
+1. Show the full `error.reply.user_notice` unchanged. For `data_consent_needed`, also show `error.reply.consent.question`; the short question does not replace the notice.
+2. For `data_consent_needed`, get the person's own answer through your normal flow. Call `flovia_data_consent` with `answer` (`"y"` or `"n"` from that answer), `consent_version` from `error.reply.consent.version`, and `user_words` containing their actual words. Do not substitute the current SDK version or a generated answer. `notice_first` alone does not ask for a consent answer or supply a consent version.
+3. For `data_consent_needed`, repeat the unchanged call only after their `y` is accepted; with `n`, stop. For `notice_first`, repeat the same call after showing the notice, adding `notice_shown: true`.
+
+Do not answer these automatically from code or from an agent.
+
+## Retries
+
+- Generations are never resent automatically.
+- With `new FloviaClient({ retryRateLimited: true })`, a tool call refused with `rate_limited`, `too_many_in_parallel` or `reservation_changed` and `executed: "no"` is resent once, unchanged, after `retry_after_seconds` (at least 1 s, at most 60 s). Off by default.
+- Anything with `executed: "unknown"` is not resent.
+
+## Timeouts
+
+Each request times out after 300 seconds by default (a long generation can take minutes). Change it with `timeoutMs`. A timeout throws `FloviaError` with code `timeout` and `executed: "unknown"`.
+
+A lost or unreadable reply is also `executed: "unknown"`, even after HTTP 200. Keep the saved operation ID and request; do not start another operation to recover the answer. A retired operation is never treated as proof that nothing ran.
+
+## Contract version
+
+`status()` compares the server's `contract_version` with the one this SDK was written for (`EXPECTED_CONTRACT_VERSION`) and warns once with `console.warn` when they differ. Replace the warning with `onContractMismatch`.
+
+## CLI
+
+The package installs a `flovia` command.
+
+```sh
+export FLOVIA_KEY=flv_...              # or: --key-file ~/.config/flovia/key
+npx flovia status
+npx flovia usage --days 3
+npx flovia tools
+npx flovia tools --json              # includes each tool's inputSchema
+npx flovia call flovia_usage_today '{}'
+npx flovia generate --op sdk-example-0001 --max-output 300 "Explain a DEX aggregator."
+# Only to reopen that exact request within about 15 minutes (not a new generation):
+npx flovia generate --op sdk-example-0001 --max-output 300 --yes "Explain a DEX aggregator."
+npx flovia help
+```
+These commands run after installing `@flovialabs/sdk` in the current project. Without a local installation, specify the package: `npx --package=@flovialabs/sdk@0.1.1 flovia --help`. Use a unique operation id for each new request; `sdk-example-0001` is only an example. Save the id, prompt and options before sending, and keep them unchanged for replay.
+
+`status` shows bought balance. `usage` shows lookup counts, free percentages and server-provided bought totals; its generation subtotal is already included in the period total. Missing amounts show `-`, not zero. It does not add rounded endpoint percentages. To continue a listing, copy the printed command with its exact `--since` and `--cursor`; do not combine `--days` with `--cursor`.
+
+- Every command takes `--json` (the raw reply), `--base-url URL`, `--timeout SECONDS` and `--key-file PATH`.
+- `generate` uses credits. It needs `--op ID` or `--new-op`, and asks for confirmation on a terminal; add `--yes` in scripts.
+- `generate` prints the response status and incomplete reason. `incomplete` / `max_output_tokens` means the delivered text stopped at the output limit, not that a continuation ran. Exit 0 means the response was delivered, not that the text is complete or correct. `--json` retains the full public response.
+- Exit codes: 0 ok, 1 an error from Flovia, 2 a usage error.
+
+### Safety
+
+- The key is read only from `FLOVIA_KEY` or a key file, never from a command-line argument (other users can see arguments in `ps`). It is never printed.
+- A key file readable by other users gets a warning; use `chmod 600`.
+- `--base-url` must be `https`, so the key is never sent unencrypted. Plain `http` is allowed only for `localhost`, `127.0.0.1` and `[::1]`.
+- On `notice_first` or `data_consent_needed` the CLI shows the full notice and, when present, the question, then stops. The person answers it themselves; `--yes` confirms spending, not data consent.
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { FloviaError, type StatusReply, type UsageTodayReply } from "./index.js";
+export interface Io {
+    env: Record<string, string | undefined>;
+    out: (s: string) => void;
+    err: (s: string) => void;
+    readFile: (path: string) => Promise<string>;
+    /** The file's permission bits, to warn when a key file is readable by others. */
+    fileMode?: (path: string) => Promise<number>;
+    readStdin: () => Promise<string>;
+    /** A yes/no question on a terminal; null when there is none (piped or CI). */
+    confirm: ((question: string) => boolean | Promise<boolean>) | null;
+    fetch?: (request: Request) => Promise<Response>;
+    now?: () => number;
+}
+export declare function help(command?: string): string;
+export interface Parsed {
+    command: string;
+    flags: Map<string, string | true>;
+    positional: string[];
+}
+export declare function parse(argv: string[]): Parsed;
+/** "Oct 18 07:21 UTC", with the year when it is not this UTC year; anything that is not a time is shown as it came. */
+export declare function when(v: unknown, now?: number): string;
+export declare function renderStatus(s: StatusReply, expected: string | null, now?: number): string;
+export declare function renderUsage(u: UsageTodayReply, today?: boolean, now?: number): string;
+/** A refusal or failure: code, next_step, executed; a handshake's notice or question is shown for the person, never answered here. */
+export declare function renderError(e: FloviaError): string;
+export declare function run(argv: string[], io: Io): Promise<number>;
+/** Decode UTF-8 across chunks, including a character split between reads. */
+export declare function readStdin(input: NodeJS.ReadableStream): Promise<string>;

package/dist/cli.js

@@ -0,0 +1,352 @@
+#!/usr/bin/env node
+/**
+ * flovia: a small CLI over the SDK's public client, for people to check their status and usage and try calls with their own key.
+ * The key comes from FLOVIA_KEY or --key-file only (never argv, which ps shows), and is never printed. Exit 2: usage error; 1: a relay error.
+ */
+import { readFile, stat } from "node:fs/promises";
+import { realpathSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+import { FloviaClient, FloviaError, newOperationId } from "./index.js";
+const GLOBAL = "[--json] [--base-url URL] [--timeout SECONDS] [--key-file PATH]";
+const COMMANDS = {
+    status: { usage: "status", about: "free windows, services, contract version and recent updates", flags: {} },
+    usage: { usage: "usage [--since ISO | --days N] [--cursor C]", about: "lookups and generations (today, or since a time within 7 days)", flags: { "--since": true, "--days": true, "--cursor": true } },
+    tools: { usage: "tools", about: "the tools this key is offered", flags: {} },
+    call: { usage: "call <tool> ['<json args>']", about: "call any tool and print its reply", flags: {} },
+    generate: { usage: "generate (--op ID | --new-op) [--max-output N] [--yes] <prompt | ->", about: "a text generation (uses credits)", flags: { "--op": true, "--new-op": false, "--max-output": true, "--yes": false } },
+    help: { usage: "help [command]", about: "this help", flags: {} },
+};
+const GLOBAL_FLAGS = { "--json": false, "--base-url": true, "--timeout": true, "--key-file": true, "--help": false, "-h": false };
+class Usage extends Error {
+}
+function distance(a, b) {
+    let row = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+        const next = [i];
+        for (let j = 1; j <= b.length; j++)
+            next[j] = Math.min((row[j] ?? 0) + 1, (next[j - 1] ?? 0) + 1, (row[j - 1] ?? 0) + (a[i - 1] === b[j - 1] ? 0 : 1));
+        row = next;
+    }
+    return row[b.length] ?? 0;
+}
+const near = (word, options) => options.find((k) => distance(k, word) <= 2 || k.startsWith(word));
+const didYouMean = (word, options, quote = "") => { const n = near(word, options); return n === undefined ? "" : `; did you mean ${quote}${n}${quote}?`; };
+export function help(command) {
+    const c = command === undefined ? undefined : COMMANDS[command];
+    if (c !== undefined)
+        return `Usage: flovia ${c.usage} ${GLOBAL}\n  ${c.about}\n`;
+    return ["Usage: flovia <command> " + GLOBAL, "",
+        ...Object.values(COMMANDS).map((x) => `  ${x.usage.padEnd(68)} ${x.about}`), "",
+        "The key is read from FLOVIA_KEY, or from the file given with --key-file. It is never accepted as an argument.",
+        "Default base URL: https://api.flovia.dev. Exit codes: 0 ok, 1 relay error, 2 usage error.", ""].join("\n");
+}
+export function parse(argv) {
+    const [command, ...rest] = argv;
+    if (command === undefined || command === "--help" || command === "-h")
+        return { command: "help", flags: new Map(), positional: [] };
+    const spec = COMMANDS[command];
+    if (spec === undefined)
+        throw new Usage(`unknown command "${command}"${didYouMean(command, Object.keys(COMMANDS), '"')} Run: flovia help`);
+    const known = { ...GLOBAL_FLAGS, ...spec.flags }, flags = new Map(), positional = [];
+    for (let i = 0; i < rest.length; i++) {
+        const a = rest[i] ?? "";
+        if (a === "-" || !a.startsWith("-")) {
+            positional.push(a);
+            continue;
+        }
+        const eq = a.indexOf("="), name = eq > 0 ? a.slice(0, eq) : a;
+        if (!(name in known))
+            throw new Usage(`${command}: unknown option ${name}${didYouMean(name, Object.keys(known))} Usage: flovia ${spec.usage}`);
+        if (!known[name]) {
+            if (eq > 0)
+                throw new Usage(`${command}: ${name} takes no value`);
+            flags.set(name, true);
+            continue;
+        }
+        const value = eq > 0 ? a.slice(eq + 1) : rest[++i];
+        if (value === undefined)
+            throw new Usage(`${command}: ${name} needs a value. Usage: flovia ${spec.usage}`);
+        flags.set(name, value);
+    }
+    if (flags.has("--help") || flags.has("-h"))
+        return { command: "help", flags: new Map(), positional: [command] };
+    return { command, flags, positional };
+}
+const str = (v) => typeof v === "string" ? v : undefined;
+function positiveInt(name, v, max = Number.MAX_SAFE_INTEGER) {
+    if (v === undefined)
+        return undefined;
+    const n = Number(v);
+    if (!Number.isInteger(n) || n < 1 || n > max)
+        throw new Usage(`${name} must be a whole number from 1 to ${max}`);
+    return n;
+}
+/** The key from --key-file (trimmed) or FLOVIA_KEY. Its text never goes into a message. */
+async function readKey(p, io) {
+    const file = str(p.flags.get("--key-file"));
+    if (file !== undefined) {
+        let text;
+        try {
+            text = await io.readFile(file);
+        }
+        catch {
+            throw new Usage(`--key-file: cannot read ${file}`);
+        }
+        const key = text.trim();
+        if (key === "")
+            throw new Usage(`--key-file: ${file} is empty`);
+        const mode = await io.fileMode?.(file).catch(() => null);
+        if (typeof mode === "number" && (mode & 0o077) !== 0)
+            io.err(`warning: ${file} is readable by other users (mode ${(mode & 0o777).toString(8)}); run: chmod 600 ${file}\n`);
+        return key;
+    }
+    const key = io.env["FLOVIA_KEY"]?.trim();
+    if (!key)
+        throw new Usage("No key: set FLOVIA_KEY or pass --key-file PATH (the key is never accepted as an argument).");
+    return key;
+}
+const pct = (v) => typeof v === "number" ? `${v}%` : "-";
+const table = (rows) => {
+    const widths = rows[0]?.map((_, i) => Math.max(...rows.map((r) => (r[i] ?? "").length))) ?? [];
+    return rows.map((r) => r.map((c, i) => i === r.length - 1 ? c : c.padEnd(widths[i] ?? 0)).join("  ")).join("\n") + "\n";
+};
+/** "Oct 18 07:21 UTC", with the year when it is not this UTC year; anything that is not a time is shown as it came. */
+export function when(v, now = Date.now()) {
+    const d = new Date(String(v));
+    if (v === null || v === undefined || Number.isNaN(d.getTime()))
+        return String(v);
+    const [, day, mon, year, hm] = d.toUTCString().split(" ");
+    return `${mon} ${day}${d.getUTCFullYear() === new Date(now).getUTCFullYear() ? "" : ` ${year}`} ${hm?.slice(0, 5)} UTC`;
+}
+const obj = (v) => v !== null && typeof v === "object" ? v : {};
+export function renderStatus(s, expected, now = Date.now()) {
+    const lines = [`Flovia ${s.stage}, contract ${s.contract_version}${expected === null ? "" : `  (warning: this CLI expects ${expected})`}`];
+    for (const [label, w] of [["5-hour window", s.five_hour], ["week", s.week]])
+        lines.push(`${label.padEnd(14)} ${pct(w?.used_pct)} used${w?.resets_at ? `, resets ${when(w.resets_at, now)}` : label === "5-hour window" ? ", not started" : ""}`);
+    lines.push(`bought balance  ${String(s["purchased_balance_display"] ?? "-")}`);
+    const pending = obj(s["free_pending"]);
+    if (pending["next_step"])
+        lines.push(`free use not started: ${String(pending["next_step"])}`);
+    const stopped = obj(s["stopped"]);
+    if (stopped["message"])
+        lines.push(`key stopped: ${String(stopped["message"])}`);
+    const services = Object.entries(obj(s["services"])).map(([name, v]) => { const x = obj(v); return `${name} ${String(x["state"] ?? "?")}${x["until"] ? ` until ${when(x["until"], now)}` : ""}`; });
+    lines.push(`services       ${services.length ? services.join(", ") : "-"}`);
+    lines.push(`turned off     ${s.services_off.length ? s.services_off.join(", ") : "none"}`);
+    const consent = obj(s["data_consent"]);
+    if (consent["needed"] === true)
+        lines.push("data consent   needed: lookups wait for the person's own y/n (answer through the normal flow, not this CLI)");
+    const updates = Array.isArray(s["recent_updates"]) ? s["recent_updates"] : [];
+    for (const u of updates.slice(0, 2)) {
+        const x = obj(u), first = Array.isArray(x["lines"]) ? String(x["lines"][0] ?? "") : "";
+        lines.push(`update ${String(x["version"])} (${String(x["date"])}): ${first}`);
+    }
+    if (updates.length > 2)
+        lines.push(`+${updates.length - 2} more (--json)`);
+    return lines.join("\n") + "\n";
+}
+export function renderUsage(u, today = false, now = Date.now()) {
+    const lines = [`since ${when(u["since"], now)} until ${when(u["until"], now)}${today ? "  (today, UTC; use --days 7 for the week)" : ""}`];
+    const week = obj(u["free_week"]);
+    lines.push(`free week: ${pct(week["used_pct"])} used${week["resets_at"] ? `, resets ${when(week["resets_at"], now)}` : ""}`);
+    lines.push(`total in this period: ${String(obj(u["total"])["free_display"] ?? "-")} of the free week, ${String(u["count"] ?? 0)} lookups`);
+    lines.push(`bought credits used: ${String(obj(u["total"])["bought_display"] ?? "-")} total (includes generations)`);
+    // Endpoint percentages are rounded (0 can mean <1%); only counts can be summed by source.
+    const bySource = new Map();
+    for (const e of Array.isArray(u["by_endpoint"]) ? u["by_endpoint"] : []) {
+        const x = obj(e), name = String(x["provider"]);
+        bySource.set(name, (bySource.get(name) ?? 0) + Number(x["count"] ?? 0));
+    }
+    if (bySource.size)
+        lines.push("", table([["source", "lookups"], ...[...bySource].map(([n, count]) => [n, String(count)])]).trimEnd());
+    const g = obj(u["generations"]);
+    lines.push("", `generations: ${String(g["operations"] ?? 0)} (completed ${String(g["completed"] ?? 0)}, incomplete ${String(g["incomplete"] ?? 0)}, unknown ${String(g["unknown"] ?? 0)}), ${String(g["free_display"] ?? "-")} of the free week, bought ${String(g["bought_display"] ?? "-")} (included in total)`);
+    if (u.has_more)
+        lines.push("", `more lookups: rerun flovia usage with the same --key-file and --base-url options, adding --since ${String(u["since"])} --cursor ${String(u.next_cursor)}`);
+    return lines.join("\n") + "\n";
+}
+/** A refusal or failure: code, next_step, executed; a handshake's notice or question is shown for the person, never answered here. */
+export function renderError(e) {
+    const lines = [`error: ${e.code}: ${e.message}`];
+    if (e.nextStep)
+        lines.push(`next_step: ${e.nextStep}`);
+    lines.push(`executed: ${e.executed}`);
+    if (e.retryAfterSeconds !== null)
+        lines.push(`retry_after_seconds: ${e.retryAfterSeconds}`);
+    if (e.operationId)
+        lines.push(`operation_id: ${e.operationId}${e.executed === "unknown" ? " (resend with this same id; never a new one)" : ""}`);
+    const reply = obj(e.reply);
+    if (e.code === "notice_first" || e.code === "data_consent_needed") {
+        if (reply["user_notice"])
+            lines.push("", "Notice for the person:", String(reply["user_notice"]));
+        const question = obj(reply["consent"])["question"];
+        if (question)
+            lines.push("", `Question for the person: ${String(question)}`);
+        lines.push("", "The person must answer this themselves through the normal flow (their agent and Flovia). This CLI does not answer it.");
+    }
+    return lines.join("\n") + "\n";
+}
+export async function run(argv, io) {
+    let key = null;
+    // Belt and braces: whatever is printed passes through here, so the key cannot appear even if a reply or error echoed it.
+    const scrub = (s) => key === null ? s : s.replaceAll(key, "[key]");
+    const out = (s) => io.out(scrub(s)), err = (s) => io.err(scrub(s));
+    let p;
+    try {
+        p = parse(argv);
+        if (p.command === "help") {
+            out(help(p.positional[0]));
+            return 0;
+        }
+        key = await readKey(p, io);
+    }
+    catch (e) {
+        if (e instanceof Usage) {
+            err(`${e.message}\n`);
+            return 2;
+        }
+        throw e;
+    }
+    const json = p.flags.has("--json"), print = (v) => out(JSON.stringify(v, null, 2) + "\n");
+    let mismatch = null;
+    try {
+        const timeout = positiveInt("--timeout", str(p.flags.get("--timeout")));
+        const baseUrl = str(p.flags.get("--base-url"));
+        const client = new FloviaClient({ apiKey: key, ...(baseUrl !== undefined ? { baseUrl } : {}), ...(timeout ? { timeoutMs: timeout * 1000 } : {}),
+            ...(io.fetch ? { fetch: io.fetch } : {}), onContractMismatch: (expected) => { mismatch = expected; } });
+        switch (p.command) {
+            case "status": {
+                const s = await client.status();
+                if (json)
+                    print(s);
+                else
+                    out(renderStatus(s, mismatch, (io.now ?? Date.now)()));
+                if (json && mismatch !== null)
+                    err(`warning: contract ${s.contract_version} differs from this CLI's ${String(mismatch)}\n`);
+                return 0;
+            }
+            case "usage": {
+                const since = str(p.flags.get("--since")), days = positiveInt("--days", str(p.flags.get("--days")), 7), cursor = str(p.flags.get("--cursor"));
+                if (since !== undefined && days !== undefined)
+                    throw new Usage("usage: pass --since or --days, not both");
+                if (cursor !== undefined && days !== undefined)
+                    throw new Usage("usage: with --cursor, use the previous reply's exact --since, not --days");
+                if (since !== undefined && Number.isNaN(Date.parse(since)))
+                    throw new Usage("--since must be an ISO 8601 time");
+                // A minute's margin so --days 7 stays inside the relay's 7 days by the time it arrives.
+                const from = days === undefined ? since : new Date((io.now ?? Date.now)() - days * 86_400_000 + 60_000).toISOString();
+                const u = await client.usageToday({ ...(from ? { since: from } : {}), ...(cursor ? { cursor } : {}) });
+                if (json)
+                    print(u);
+                else
+                    out(renderUsage(u, from === undefined && cursor === undefined, (io.now ?? Date.now)()));
+                return 0;
+            }
+            case "tools": {
+                const tools = await client.listTools();
+                if (json)
+                    print(tools);
+                else
+                    out(table(tools.map((t) => [t.name, (t.description ?? "").split(/(?<=\.)\s/)[0] ?? ""])));
+                return 0;
+            }
+            case "call": {
+                const [tool, raw, extra] = p.positional;
+                if (tool === undefined || extra !== undefined)
+                    throw new Usage(`Usage: flovia ${COMMANDS["call"]?.usage}`);
+                let args = {};
+                if (raw !== undefined)
+                    try {
+                        args = JSON.parse(raw);
+                    }
+                    catch {
+                        throw new Usage("call: the arguments must be one JSON object, e.g. '{\"since\":\"2026-10-10T00:00:00Z\"}'");
+                    }
+                if (args === null || typeof args !== "object" || Array.isArray(args))
+                    throw new Usage("call: the arguments must be a JSON object");
+                print(await client.call(tool, args));
+                return 0;
+            }
+            case "generate": {
+                const op = str(p.flags.get("--op")), fresh = p.flags.has("--new-op");
+                if ((op === undefined) === !fresh)
+                    throw new Usage("generate: pass --op ID (to resend, the same id) or --new-op (to make one); exactly one of them");
+                const [text, extra] = p.positional;
+                if (text === undefined || extra !== undefined)
+                    throw new Usage(`Usage: flovia ${COMMANDS["generate"]?.usage}`);
+                const input = text === "-" ? await io.readStdin() : text;
+                if (input.trim() === "")
+                    throw new Usage("generate: the prompt is empty");
+                const max = positiveInt("--max-output", str(p.flags.get("--max-output")));
+                const id = op ?? newOperationId();
+                // The id is shown before anything is sent, so a lost reply can be reopened with it (never resent under a new one).
+                if (fresh)
+                    err(`operation_id: ${id}\nSave it. To resend or reopen this request, use: --op ${id}\n`);
+                err("This generation uses Flovia credits (free windows first, then bought credits). The same --op and unchanged request can reopen a saved answer for about 15 minutes at no charge. Pending, unknown or expired answers must not be replaced with a new id.\n");
+                if (!p.flags.has("--yes")) {
+                    if (io.confirm === null || text === "-")
+                        throw new Usage("generate: add --yes to send (no terminal to confirm on)");
+                    if (!(await io.confirm("Send it?"))) {
+                        err("Not sent.\n");
+                        return 2;
+                    }
+                }
+                const g = await client.generate({ model: "gpt-6-luna", input, ...(max ? { max_output_tokens: max } : {}) }, { operationId: id });
+                const reason = obj(g.response["incomplete_details"])["reason"];
+                if (json)
+                    print(g);
+                else
+                    out(`${g.outputText}\n\n[status: ${String(g.response["status"] ?? "unknown")}${reason ? `, reason: ${String(reason)}` : ""}, operation_id ${id}${g.replayed ? ", replayed: the saved answer, not charged again" : ""}${g.generationId ? `, generation ${g.generationId}` : ""}]\n`);
+                return 0;
+            }
+        }
+        return 2;
+    }
+    catch (e) {
+        if (e instanceof Usage) {
+            err(`${e.message}\n`);
+            return 2;
+        }
+        if (e instanceof FloviaError) {
+            if (json && e.reply)
+                print(e.reply);
+            err(renderError(e));
+            return e.code === "invalid_base_url" ? 2 : 1;
+        }
+        err(`error: ${e instanceof Error ? e.message : String(e)}\n`);
+        return 1;
+    }
+}
+/** Decode UTF-8 across chunks, including a character split between reads. */
+export async function readStdin(input) {
+    input.setEncoding("utf8");
+    let text = "";
+    for await (const chunk of input)
+        text += String(chunk);
+    return text;
+}
+/** Run only as the program (also through npm's bin symlink), not when imported. Node and Bun alike. */
+const isMain = (() => { try {
+    return realpathSync(process.argv[1] ?? "") === realpathSync(fileURLToPath(import.meta.url));
+}
+catch {
+    return false;
+} })();
+if (isMain) {
+    const tty = process.stdin.isTTY === true;
+    const confirm = async (q) => {
+        const rl = createInterface({ input: process.stdin, output: process.stderr });
+        try {
+            return /^y(es)?$/i.test((await rl.question(`${q} [y/N] `)).trim());
+        }
+        finally {
+            rl.close();
+        }
+    };
+    process.exitCode = await run(process.argv.slice(2), {
+        env: process.env, out: (s) => process.stdout.write(s), err: (s) => process.stderr.write(s),
+        readFile: (path) => readFile(path, "utf8"), fileMode: async (path) => (await stat(path)).mode, readStdin: () => readStdin(process.stdin),
+        confirm: tty ? confirm : null,
+    });
+}

package/dist/client.d.ts

@@ -0,0 +1,45 @@
+import { type Generation, type GenerationRequest, type StatusReply, type ToolReply, type UsageTodayArgs, type UsageTodayReply } from "./types.js";
+export interface FloviaClientOptions {
+    /** A Flovia key (flv_...). Defaults to the FLOVIA_KEY environment variable. Never logged. */
+    apiKey?: string;
+    /** Defaults to https://api.flovia.dev. */
+    baseUrl?: string;
+    /** Per request, in milliseconds. Defaults to 300 s: a long generation takes minutes. */
+    timeoutMs?: number;
+    fetch?: (request: Request) => Promise<Response>;
+    /**
+     * Resend a tool call once, unchanged (same operation_id), after rate_limited, too_many_in_parallel or reservation_changed with executed
+     * "no", when the wait is at most 60 s; it waits at least 1 s. Off by default. Generations are never resent automatically.
+     */
+    retryRateLimited?: boolean;
+    /** Called once when flovia_status reports another contract version. Defaults to console.warn. */
+    onContractMismatch?: (expected: string, actual: string) => void;
+}
+export interface ToolInfo {
+    name: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+}
+/** A new operation_id. Save it with the request before sending, so a lost reply can be reopened with the same id. */
+export declare const newOperationId: () => string;
+export declare class FloviaClient {
+    #private;
+    constructor(options?: FloviaClientOptions);
+    /** tools/list: the tools this key is offered, with their input schemas. */
+    listTools(): Promise<ToolInfo[]>;
+    /** tools/call for any tool. A reply with ok: false throws FloviaError (handshakes such as notice_first too; see error.reply). */
+    call<R extends ToolReply = ToolReply>(tool: string, args?: Record<string, unknown>): Promise<R>;
+    /** flovia_status. Warns once when the relay's contract_version is not the one this SDK expects. */
+    status(): Promise<StatusReply>;
+    /** flovia_usage_today: the user's lookups (today, or since a time within 7 days). */
+    usageToday(args?: UsageTodayArgs): Promise<UsageTodayReply>;
+    /**
+     * POST /openai/v1/responses. operationId is required: save it with the request before calling. Sending the same request with the same id
+     * again can return the saved answer (replayed: true) for about 15 minutes at no charge. Pending, unknown and expired answers
+     * are not proof that nothing ran. Never resent automatically, and never under a new id to recover an answer.
+     */
+    generate(request: GenerationRequest, options: {
+        operationId: string;
+        conversationId?: string;
+    }): Promise<Generation>;
+}

package/dist/client.js

@@ -0,0 +1,185 @@
+import { FloviaError } from "./errors.js";
+import { EXPECTED_CONTRACT_VERSION } from "./types.js";
+/** The relay's operation_id shape: 8-128 of A-Z a-z 0-9 _ . : - */
+const OPERATION_ID = /^[A-Za-z0-9_.:-]{8,128}$/;
+const RESEND_CODES = new Set(["rate_limited", "too_many_in_parallel", "reservation_changed"]);
+const MAX_RESEND_WAIT_S = 60;
+/** A new operation_id. Save it with the request before sending, so a lost reply can be reopened with the same id. */
+export const newOperationId = () => `op_${crypto.randomUUID()}`;
+const envKey = () => globalThis.process?.env?.["FLOVIA_KEY"];
+const seconds = (v) => {
+    const n = typeof v === "string" && v.trim() !== "" ? Number(v) : v;
+    return typeof n === "number" && Number.isFinite(n) && n >= 0 ? n : null;
+};
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const SAME_OPERATION = "Resend with the same operation_id; do not use a new one.";
+/** A lost or unreadable reply cannot prove that the operation did not run. */
+async function readReply(r, operationId, sse = false) {
+    try {
+        const text = (await r.text()).trimStart();
+        const payload = sse && !text.startsWith("{") ? text.split(/\r?\n/).filter((l) => l.startsWith("data:"))
+            .map((l) => l.slice(5).replace(/^ /, "")).join("\n") : text;
+        const body = JSON.parse(payload);
+        if (body === null || typeof body !== "object" || Array.isArray(body))
+            throw new Error("invalid reply");
+        return body;
+    }
+    catch (cause) {
+        const timeout = cause instanceof Error && cause.name === "TimeoutError";
+        throw new FloviaError({ code: timeout ? "timeout" : `http_${r.status}`, status: r.status, executed: "unknown", operationId,
+            message: timeout ? "Timed out while reading the reply." : `Unexpected reply (HTTP ${r.status}).`, nextStep: operationId ? SAME_OPERATION : null });
+    }
+}
+export class FloviaClient {
+    #key;
+    #base;
+    #timeoutMs;
+    #fetch;
+    #resend;
+    #onMismatch;
+    #warned = false;
+    #id = 0;
+    constructor(options = {}) {
+        const key = options.apiKey ?? envKey();
+        if (!key)
+            throw new FloviaError({ code: "missing_api_key", message: "Pass apiKey or set FLOVIA_KEY.", executed: "no" });
+        this.#key = key;
+        const base = options.baseUrl ?? "https://api.flovia.dev";
+        let url;
+        try {
+            url = new URL(base);
+        }
+        catch {
+            throw new FloviaError({ code: "invalid_base_url", executed: "no", message: "baseUrl / --base-url must be a valid URL." });
+        }
+        const local = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+        if (url.protocol !== "https:" && !(url.protocol === "http:" && local))
+            throw new FloviaError({ code: "invalid_base_url", executed: "no", message: "baseUrl / --base-url must be https (plain http only for localhost, 127.0.0.1 or [::1])." });
+        this.#base = base.replace(/\/+$/, "");
+        this.#timeoutMs = options.timeoutMs ?? 300_000;
+        this.#fetch = options.fetch ?? ((r) => fetch(r));
+        this.#resend = options.retryRateLimited ?? false;
+        // eslint-disable-next-line no-console -- versions only, never the key
+        this.#onMismatch = options.onContractMismatch ?? ((expected, actual) => console.warn(`Flovia contract ${actual} differs from the SDK's ${expected}; check flovia_status recent_updates.`));
+    }
+    /** One HTTP request. A network failure or timeout is executed "unknown": the relay may have received it. */
+    async #send(path, body, headers = {}, operationId = null) {
+        const request = new Request(this.#base + path, { method: "POST", body: JSON.stringify(body), signal: AbortSignal.timeout(this.#timeoutMs),
+            headers: { Authorization: `Bearer ${this.#key}`, "Content-Type": "application/json", ...headers } });
+        let r;
+        try {
+            r = await this.#fetch(request);
+        }
+        catch (cause) {
+            const timeout = cause instanceof Error && cause.name === "TimeoutError";
+            // Transport diagnostics may contain request headers, so never attach their raw cause.
+            throw new FloviaError({ code: timeout ? "timeout" : "network_error", executed: "unknown", operationId,
+                message: timeout ? `No reply within ${this.#timeoutMs} ms.` : "The request did not complete.",
+                nextStep: operationId ? SAME_OPERATION : null });
+        }
+        if (r.status === 401)
+            throw new FloviaError({ code: "unauthorized", status: 401, executed: "no", message: "The Flovia key was not accepted." });
+        return r;
+    }
+    async #rpc(method, params, operationId = null) {
+        const r = await this.#send("/mcp", { jsonrpc: "2.0", id: ++this.#id, method, ...(params ? { params } : {}) }, { Accept: "application/json, text/event-stream", "MCP-Protocol-Version": "2025-06-18" }, operationId);
+        const message = await readReply(r, operationId, true);
+        if (message.error !== undefined || message.result === null || typeof message.result !== "object" || Array.isArray(message.result))
+            throw new FloviaError({ code: "mcp_error", status: r.status, executed: "unknown", operationId,
+                message: String(message.error?.message ?? "No result."), nextStep: operationId ? SAME_OPERATION : null });
+        return message.result;
+    }
+    /** tools/list: the tools this key is offered, with their input schemas. */
+    async listTools() {
+        return (await this.#rpc("tools/list")).tools;
+    }
+    /** tools/call for any tool. A reply with ok: false throws FloviaError (handshakes such as notice_first too; see error.reply). */
+    async call(tool, args = {}) {
+        const operationId = typeof args["operation_id"] === "string" ? args["operation_id"] : null;
+        for (let attempt = 0;; attempt++) {
+            const result = await this.#rpc("tools/call", { name: tool, arguments: args }, operationId);
+            const text = result.content?.[0]?.text;
+            let reply;
+            try {
+                reply = JSON.parse(String(text));
+                if (reply === null || typeof reply !== "object" || Array.isArray(reply) || (reply.ok === false &&
+                    (reply.explanation === null || typeof reply.explanation !== "object")))
+                    throw new Error("invalid tool reply");
+                if (reply.ok === false) {
+                    const e = reply.explanation;
+                    if (Array.isArray(e) || typeof e?.code !== "string" || typeof e.meaning !== "string" || typeof e.next_step !== "string" ||
+                        !["yes", "no", "unknown"].includes(e.executed))
+                        throw new Error("invalid explanation");
+                }
+            }
+            catch {
+                throw new FloviaError({ code: "tool_error", executed: "unknown", operationId, nextStep: operationId ? SAME_OPERATION : null,
+                    message: result.isError ? "The tool failed." : "The tool reply is not JSON." });
+            }
+            const e = reply.explanation;
+            if (reply.ok !== false || e === undefined)
+                return reply;
+            const wait = seconds(reply.retry_after_seconds);
+            // Only a refusal that surely did not run; at least 1 s apart, so a missing or 0 wait never resends at once.
+            if (this.#resend && attempt === 0 && e.executed === "no" && RESEND_CODES.has(e.code) && (wait ?? 0) <= MAX_RESEND_WAIT_S) {
+                await sleep(Math.max(1, wait ?? 0) * 1000);
+                continue;
+            }
+            throw new FloviaError({ code: e.code, message: e.meaning, nextStep: e.next_step, executed: e.executed, retryAfterSeconds: wait, operationId, reply });
+        }
+    }
+    /** flovia_status. Warns once when the relay's contract_version is not the one this SDK expects. */
+    async status() {
+        const s = await this.call("flovia_status");
+        if (!this.#warned && s.contract_version !== EXPECTED_CONTRACT_VERSION) {
+            this.#warned = true;
+            this.#onMismatch(EXPECTED_CONTRACT_VERSION, s.contract_version);
+        }
+        return s;
+    }
+    /** flovia_usage_today: the user's lookups (today, or since a time within 7 days). */
+    usageToday(args = {}) {
+        return this.call("flovia_usage_today", { ...args });
+    }
+    /**
+     * POST /openai/v1/responses. operationId is required: save it with the request before calling. Sending the same request with the same id
+     * again can return the saved answer (replayed: true) for about 15 minutes at no charge. Pending, unknown and expired answers
+     * are not proof that nothing ran. Never resent automatically, and never under a new id to recover an answer.
+     */
+    async generate(request, options) {
+        const op = options.operationId;
+        if (!OPERATION_ID.test(op))
+            throw new FloviaError({ code: "invalid_operation_id", executed: "no", message: "operationId must be 8-128 of A-Z a-z 0-9 _ . : -" });
+        const r = await this.#send("/openai/v1/responses", request, { "Flovia-Operation-Id": op, ...(options.conversationId ? { "Flovia-Conversation-Id": options.conversationId } : {}) }, op);
+        const body = await readReply(r, op);
+        if (r.status === 200 && !Array.isArray(body["output"]))
+            throw new FloviaError({ code: "http_200", status: 200, executed: "unknown", operationId: op, message: "Unexpected generation reply (HTTP 200).", nextStep: SAME_OPERATION });
+        if (r.status === 200)
+            return { response: body, outputText: outputText(body), generationId: r.headers.get("Flovia-Generation-Id"),
+                replayed: r.headers.get("Flovia-Replayed") === "1", receivedAt: r.headers.get("Flovia-Received-At"), conversationId: r.headers.get("Flovia-Conversation-Id") };
+        const err = body["error"], explanation = body["explanation"];
+        const code = typeof err === "string" ? err : String(err?.code ?? `http_${r.status}`);
+        const message = String(err?.message ?? body["message"] ?? `HTTP ${r.status}`);
+        const executed = explanation?.executed ?? generationExecuted(code);
+        throw new FloviaError({ code, message, status: r.status, operationId: op, reply: body,
+            executed, nextStep: explanation?.next_step ?? (executed === "unknown" ? SAME_OPERATION : null),
+            retryAfterSeconds: seconds(r.headers.get("Retry-After")) ?? seconds(body["retry_after_seconds"]) });
+    }
+}
+/** Whether a refused generation ran, from its public code (the same reading flovia_openai gives over MCP). */
+function generationExecuted(code) {
+    if (["answer_unavailable", "answer_expired", "answer_delivery_denied"].includes(code))
+        return "yes";
+    if (["generation_unknown", "generation_pending", "record_unavailable", "operation_retired"].includes(code) || /^http_5\d\d$/.test(code))
+        return "unknown";
+    return "no";
+}
+/** The output_text parts of output[].content[], in order. */
+function outputText(body) {
+    const output = Array.isArray(body["output"]) ? body["output"] : [];
+    return output.flatMap((item) => {
+        const content = item?.content;
+        return Array.isArray(content) ? content : [];
+    }).filter((c) => c?.type === "output_text" && typeof c.text === "string")
+        .map((c) => c.text).join("");
+}

package/dist/errors.d.ts

@@ -0,0 +1,27 @@
+import type { Executed, ToolReply } from "./types.js";
+/**
+ * A Flovia refusal or a failed request. code is the relay's public code (or an HTTP generation code such as generation_pending).
+ * executed "unknown": keep the same operation_id; never send the request again under a new one. The message never carries the key.
+ */
+export declare class FloviaError extends Error {
+    readonly name = "FloviaError";
+    readonly code: string;
+    readonly nextStep: string | null;
+    readonly executed: Executed;
+    readonly status: number | null;
+    readonly retryAfterSeconds: number | null;
+    readonly operationId: string | null;
+    /** The full reply body, for fields such as user_notice or consent.question. */
+    readonly reply: ToolReply | null;
+    constructor(init: {
+        code: string;
+        message: string;
+        nextStep?: string | null;
+        executed: Executed;
+        status?: number | null;
+        retryAfterSeconds?: number | null;
+        operationId?: string | null;
+        reply?: ToolReply | null;
+        cause?: unknown;
+    });
+}

package/dist/errors.js

@@ -0,0 +1,25 @@
+/**
+ * A Flovia refusal or a failed request. code is the relay's public code (or an HTTP generation code such as generation_pending).
+ * executed "unknown": keep the same operation_id; never send the request again under a new one. The message never carries the key.
+ */
+export class FloviaError extends Error {
+    name = "FloviaError";
+    code;
+    nextStep;
+    executed;
+    status;
+    retryAfterSeconds;
+    operationId;
+    /** The full reply body, for fields such as user_notice or consent.question. */
+    reply;
+    constructor(init) {
+        super(init.message, init.cause === undefined ? undefined : { cause: init.cause });
+        this.code = init.code;
+        this.nextStep = init.nextStep ?? null;
+        this.executed = init.executed;
+        this.status = init.status ?? null;
+        this.retryAfterSeconds = init.retryAfterSeconds ?? null;
+        this.operationId = init.operationId ?? null;
+        this.reply = init.reply ?? null;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { FloviaClient, newOperationId, type FloviaClientOptions, type ToolInfo } from "./client.js";
+export { FloviaError } from "./errors.js";
+export * from "./types.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { FloviaClient, newOperationId } from "./client.js";
+export { FloviaError } from "./errors.js";
+export * from "./types.js";

package/dist/types.d.ts

@@ -0,0 +1,78 @@
+/** The relay's tool contract this SDK was written against (flovia_status.contract_version). */
+export declare const EXPECTED_CONTRACT_VERSION = "2026-10-07.116";
+/** Every public explanation.code (the relay's contract). A provider's own HTTP error is `http_<status>`. */
+export declare const PUBLIC_CODES: readonly ["key_disabled", "key_stopped", "consent_missing", "data_consent_mismatch", "data_consent_needed", "notice_first", "endpoint_unknown", "endpoint_disabled", "read_only", "not_relayed", "key_in_query", "secret_in_input", "invalid_body", "body_too_large", "answer_too_large", "answer_precision_unsafe", "answer_not_relayed", "request_text_too_long", "over_max_credits", "cost_confirmation_needed", "window_5h", "window_week", "over_week", "free_limited", "free_needs_email", "global_cap", "flovia_paused", "free_paused", "rate_limited", "too_many_in_parallel", "reservation_changed", "operation_conflict", "operation_pending", "upstream_unknown", "upstream_unavailable", "replay_response_unavailable", "rpc_error", "unknown_lookup", "invalid_cursor", "since_too_old", "since_in_future", "feedback_too_long", "feedback_limit", "not_configured", "service_off"];
+export type FloviaCode = (typeof PUBLIC_CODES)[number] | `http_${number}`;
+/** Whether the request ran upstream: "unknown" means keep the same operation_id and never send a replacement. */
+export type Executed = "yes" | "no" | "unknown";
+/** A refusal's explanation, as every tool returns it with ok: false. */
+export interface Explanation {
+    by: string;
+    code: FloviaCode;
+    executed: Executed;
+    meaning: string;
+    next_step: string;
+    audience?: "agent" | "user";
+}
+/** Any tool reply. Fields beyond these depend on the tool; read them from the relay's documentation. */
+export interface ToolReply {
+    ok?: boolean;
+    explanation?: Explanation;
+    retry_after_seconds?: number;
+    resets_at?: string;
+    [field: string]: unknown;
+}
+export interface Window {
+    used_pct: number;
+    resets_at: string | null;
+}
+export type StatusArgs = Record<string, never>;
+export interface StatusReply extends ToolReply {
+    contract_version: string;
+    stage: string;
+    five_hour: Window;
+    week: Window;
+    services_off: string[];
+}
+export interface UsageTodayArgs {
+    /** ISO 8601 time, at most 7 days ago. */
+    since?: string;
+    /** The previous next_cursor, unchanged, with the same since and conversation. */
+    cursor?: string;
+    /** Only this conversation's lookups. */
+    conversation?: string;
+}
+export interface UsageTodayReply extends ToolReply {
+    has_more?: boolean;
+    next_cursor?: string | null;
+}
+/** POST /openai/v1/responses: an OpenAI Responses request, text only. Unknown fields are refused. */
+export interface GenerationRequest {
+    model: "gpt-6-luna";
+    input: string;
+    max_output_tokens?: number;
+    reasoning?: {
+        effort: "none" | "low";
+    };
+    stream?: false;
+    store?: false;
+    service_tier?: "default";
+    text?: {
+        format: {
+            type: "json_object";
+        };
+    };
+}
+export interface Generation {
+    /** The OpenAI Response object (public fields only). */
+    response: Record<string, unknown> & {
+        output?: unknown[];
+    };
+    /** The output_text parts joined, for convenience. */
+    outputText: string;
+    generationId: string | null;
+    /** true: the saved answer for this operation_id came back; nothing was generated or charged again. */
+    replayed: boolean;
+    receivedAt: string | null;
+    conversationId: string | null;
+}

package/dist/types.js

@@ -0,0 +1,12 @@
+/** The relay's tool contract this SDK was written against (flovia_status.contract_version). */
+export const EXPECTED_CONTRACT_VERSION = "2026-10-07.116";
+/** Every public explanation.code (the relay's contract). A provider's own HTTP error is `http_<status>`. */
+export const PUBLIC_CODES = [
+    "key_disabled", "key_stopped", "consent_missing", "data_consent_mismatch", "data_consent_needed", "notice_first",
+    "endpoint_unknown", "endpoint_disabled", "read_only", "not_relayed", "key_in_query", "secret_in_input", "invalid_body", "body_too_large",
+    "answer_too_large", "answer_precision_unsafe", "answer_not_relayed", "request_text_too_long",
+    "over_max_credits", "cost_confirmation_needed", "window_5h", "window_week", "over_week", "free_limited", "free_needs_email", "global_cap",
+    "flovia_paused", "free_paused", "rate_limited", "too_many_in_parallel", "reservation_changed",
+    "operation_conflict", "operation_pending", "upstream_unknown", "upstream_unavailable", "replay_response_unavailable", "rpc_error",
+    "unknown_lookup", "invalid_cursor", "since_too_old", "since_in_future", "feedback_too_long", "feedback_limit", "not_configured", "service_off",
+];

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@flovialabs/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "type": "module",
+  "description": "TypeScript client and CLI for Flovia: MCP tools over HTTP and OpenAI-compatible generation. Zero dependencies.",
+  "license": "MIT",
+  "homepage": "https://api.flovia.dev",
+  "keywords": [
+    "flovia",
+    "mcp",
+    "model-context-protocol",
+    "api",
+    "client",
+    "sdk",
+    "cli",
+    "openai"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "flovia": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "lint": "oxlint --deny-warnings src test",
+    "test": "bun test",
+    "check": "bun run typecheck && bun run lint && bun run test",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepack": "bun run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}