@flovialabs/sdk 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 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.

package/README.md

@@ -10,11 +10,13 @@ TypeScript client and command-line tool for [Flovia](https://api.flovia.dev). It
 ## Install
 
 ```sh
-npm install @flovialabs/sdk
+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
@@ -28,7 +30,7 @@ Or pass it as `new FloviaClient({ apiKey })`. The client keeps the key private:
 ## Quick start
 
 ```ts
-import { FloviaClient, FloviaError, newOperationId } from "@flovialabs/sdk";
+import { FloviaClient, newOperationId } from "@flovialabs/sdk";
 
 const flovia = new FloviaClient(); // reads FLOVIA_KEY; base URL https://api.flovia.dev
 
@@ -37,7 +39,7 @@ 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({ since: "2026-10-10T00:00:00Z" });
+const usage = await flovia.usageToday(); // today, UTC
 
 // Any tool: list them, then call one
 const tools = await flovia.listTools();
@@ -45,15 +47,36 @@ const reply = await flovia.call("flovia_status");
 
 // A text generation (uses credits). Save the operation id before sending.
 const op = newOperationId();
-const g = await flovia.generate({ model: "gpt-6-luna", input: "Summarize this." }, { operationId: op });
-console.log(g.outputText);
+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"`), send the same request again with the **same** id. Flovia returns the saved answer with `replayed: true` and does not charge again. Never resend under a new id: that may run and charge twice.
+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
 
@@ -74,9 +97,9 @@ A refusal (`ok: false`) or a failed request throws `FloviaError`:
 
 These two codes are thrown on purpose. They need the person's own answer, and the SDK never answers for them.
 
-1. Show `error.reply.user_notice` (or, for consent, `error.reply.consent.question`) to the person, unchanged.
-2. Get the person's answer through your normal flow. For consent, send their own words to the `flovia_data_consent` tool.
-3. Repeat the same call with the same arguments. After `notice_first`, add `notice_shown: true`.
+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.
 
@@ -105,17 +128,20 @@ export FLOVIA_KEY=flv_...              # or: --key-file ~/.config/flovia/key
 npx flovia status
 npx flovia usage --days 3
 npx flovia tools
-npx flovia call flovia_usage_today '{"since":"2026-10-11T00:00:00Z"}'
-npx flovia generate --new-op "Summarize this."     # prints the operation id, then asks before sending
-npx flovia generate --op op_... --yes "Summarize this."   # same id: the saved answer, not charged again
+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.0 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.
 
-`usage` shows lookup counts by source and the server-provided totals. 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`.
+`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
@@ -123,7 +149,7 @@ These commands run after installing `@flovialabs/sdk` in the current project. Wi
 - 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 notice or question and stops. The person answers it themselves.
+- 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
 

package/dist/cli.js

@@ -124,6 +124,7 @@ 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"])}`);
@@ -150,6 +151,7 @@ export function renderUsage(u, today = false, now = Date.now()) {
     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"] : []) {
@@ -159,7 +161,7 @@ export function renderUsage(u, today = false, now = Date.now()) {
     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`);
+    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";
@@ -281,7 +283,7 @@ export async function run(argv, io) {
                 // 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). Resending the same --op returns the saved answer at no charge.\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)");
@@ -291,10 +293,11 @@ export async function run(argv, io) {
                     }
                 }
                 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[operation_id ${id}${g.replayed ? ", replayed: the saved answer, not charged again" : ""}${g.generationId ? `, generation ${g.generationId}` : ""}]\n`);
+                    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;
             }
         }

package/dist/client.d.ts

@@ -35,7 +35,8 @@ export declare class FloviaClient {
     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 returns the saved answer (replayed: true) at no charge. Never resent automatically, and never under a new 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;

package/dist/client.js

@@ -143,7 +143,8 @@ export class FloviaClient {
     }
     /**
      * POST /openai/v1/responses. operationId is required: save it with the request before calling. Sending the same request with the same id
-     * again returns the saved answer (replayed: true) at no charge. Never resent automatically, and never under a new 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flovialabs/sdk",
-  "version": "0.1.0",
+  "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",