@gemmein/sdk 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -12,6 +12,83 @@ the same release.
 
 ## [Unreleased]
 
+## [0.7.0] — 2026-09-04
+
+### Credits and the AI route
+
+Credits are a general consumable: a balance your customers hold and your
+product spends. A product carries `grantsCredits` (1..1,000,000) and each
+confirmed purchase adds that many to the buyer's balance, idempotent on the
+payment; a full refund claws back what is still unspent, floor zero. The
+browser reads the balance with `g.credits.balance()`; a server spends with
+`gemmeinServer(sk).spendCredits(personId, { amount?, reason, key? })` behind
+the fourth key capability, "Spend a person's credits" — one atomic
+decrement, refused whole below zero with `402 credits_exhausted` and the
+balance in the message, at-most-once on `key`. `Holdings.credits` is
+`{ balance }` from engine 0.8.0 (the type is unchanged; an older local engine
+still answers `null`). A relay adds with `grant_credits`; the owner comps
+from the person's page. Credits never expire and are never priced by token.
+
+The AI route lets a browser session call OpenAI, Anthropic or Google through
+Gemmein on the owner's own provider key, pasted once in the Keys room and
+write-only from then on. `g.ai.chat(body, { provider?, signal? })` spends one
+credit, forwards the provider's own request body as sent (minus `provider`,
+and for Google `model` and `stream`, which ride the URL) with the auth
+headers, `content-type` and `accept` added, and returns the fetch `Response`
+untouched — the provider's answer, 2xx or not, is yours to read; a stream
+stays a stream. `g.ai.text(body)` collects a non-stream answer to one string
+per provider and throws `provider_error` on a provider's own non-2xx. A
+credit is refunded only when the provider fails before its first byte
+(`x-gemmein-credit: refunded`); a stream that dies mid-way does not refund,
+and hanging up before the headers does not refund. A secret key is refused
+(`403 scope_denied`): a server calls the provider directly. The codes that
+join `GemmeinError`: `credits_exhausted`, `credits_ceiling`,
+`dedupe_conflict`, `invalid_amount`, `invalid_reason`, `invalid_key`,
+`person_not_found`, `capability_required`, `invalid_body`,
+`ai_not_configured`, `provider_required`, `model_not_allowed`, `ai_capped`,
+`payload_too_large`, `session_required`, `scope_denied`,
+`provider_unreachable`, and `provider_error` from `g.ai.text`. `REFERENCE.md`
+carries the Credits and AI chapters; `llms.txt` carries both capability
+cards. `gemmein dev` answers a fake provider without a key and its pay
+simulator honours the `grantsCredits` a product declares in
+`gemmein/payments.json` (`gemmein payments setup` asks for it).
+
+The ledger's laws, stated: a full refund claws back what that purchase's own
+ledger row granted, whatever the product says today; a balance carries at
+most 1,000,000,000 (`credits_ceiling`, nothing added past it); a server
+spend's `key` is scoped to the person, so one order id reused for two people
+charges both and a key that names a different movement is `dedupe_conflict`;
+the person's page shows the credits that person spent in the last 30 days; a
+provider that echoes the key in a refusal reaches the app as `***<hint>`.
+
+### Added
+- `g.credits.balance()` → `GET /auth/credits` → `{ balance }` (session required).
+- `g.ai.chat(body, { provider?, signal? })` → `POST /ai/chat`; answers the
+  fetch `Response` untouched (streaming intact) whenever the answer passed
+  the spend — the provider's own status and body, 2xx or not; Gemmein's
+  refusals throw `GemmeinError` with the engine's code — `credits_exhausted`
+  (402), `ai_not_configured` (409), `provider_required` (400),
+  `model_not_allowed` (403), `ai_capped` (429), `payload_too_large` (413),
+  `invalid_body` (400), `session_required` (401), `scope_denied` (403),
+  `provider_unreachable` (502).
+- `g.ai.text(body, options?)` — the non-streaming answer as a string
+  (OpenAI `choices[0].message.content`; Anthropic `content[].text`;
+  Google `candidates[0].content.parts[].text`); `invalid_response` when
+  no text came back; `provider_error` (the provider's status and message)
+  on a provider's own non-2xx.
+- `gemmeinServer(sk).spendCredits(personId, { amount?, reason, key? })` →
+  `POST /server/people/:id/credits/spend` → `{ ok, spent, deduped,
+  balance: { before, after }, event: { id, reason, actor } }` (a deduped
+  repeat answers `spent: 0` and the same event); needs the key's "Spend a
+  person's credits" capability; `402 credits_exhausted`.
+- `Holdings.credits` is filled (`{ balance }`) from engine 0.8.0 — the
+  type is unchanged.
+- Relays: `grant_credits { amount 1..10,000, reason? }` action, mirrored
+  in `@gemmein/mcp`'s offline validator.
+- Console: the Keys room's AI provider card (set · test · replace ·
+  remove), "Grants credits" on a product, CREDITS + Grant credits + the
+  ledger on a person, the Usage room's "AI calls" row.
+
 ## [0.6.0] — 2026-09-04
 
 ### Changed

package/REFERENCE.md

@@ -27,7 +27,7 @@ that passes `baseUrl` to reach a local or staging server quietly talks to
 production instead. Exposes read/update on collections without a signed-in user,
 `notify()` to email one of your app's own verified people (see **Notify**),
 the gate — `verifySession()` / `holdings()` / `grantAccess()` /
-`revokeAccess()` / `invitePerson()`, for code of yours running on your own
+`revokeAccess()` / `invitePerson()` / `spendCredits()`, for code of yours running on your own
 host (see **Server gate**) — plus `testSession()` for CI self-tests (dev
 environments only — see **Reaffirm**).
 
@@ -271,6 +271,154 @@ honestly, not hidden.)
 
 ---
 
+## Credits — `g.credits` / `gemmeinServer(sk).spendCredits`
+
+A balance your customers hold and your product spends: a pack they buy, a
+comp the owner gives, a call that costs one. Credits are a **quantity beside
+access**, never access itself — a locked collection still asks for the
+entitlement, whatever the balance. The ledger adds at every purchase, grant
+and refund, subtracts at every spend, and never goes below zero: a spend
+past the balance is refused whole (`402 credits_exhausted`, the balance in
+the message), never partly. No expiry. No per-token pricing.
+
+| Surface | Signature | Returns |
+|---------|-----------|---------|
+| `g.credits.balance` | `()` | `Promise<{ balance: number }>` — the signed-in person's balance now (`401 session_required` without a session) |
+| `gemmeinServer(sk).spendCredits` | `(personId, { amount?: number; reason: string; key?: string })` | `Promise<{ ok: true; spent: number; deduped: boolean; balance: { before: number; after: number }; event: { id, reason, actor } }>` — `amount` defaults to 1 (1..10,000); `reason` ≤ 200 chars is what the owner reads on the person's ledger; `key` makes the spend at-most-once per person (a repeat answers `deduped: true`, `spent: 0`, the same `event`, and moves nothing; one key reused for a second person charges that person). Needs **"Spend a person's credits"** ticked on the key (`403 capability_required` otherwise) |
+| `Holdings.credits` | — | `{ balance: number }` on `verifySession()` and `holdings()` from engine 0.8.0 (`null` from an older local engine) — one verify answers who, what they hold and how many |
+
+Where credits come from, and where they go:
+
+- **A product with `grantsCredits`** (the "Grants credits" field on the
+  Payments page, 1..1,000,000). Each confirmed purchase **adds** that many to
+  the buyer's balance — two packs make double, never a reset — idempotent on
+  the payment. A purchase by an email that has never signed in creates the
+  person and credits them. A **full** refund claws back what that purchase's
+  own ledger row granted — at most what is still unspent, floor 0 — whatever
+  the product says today; a partial refund moves nothing. The purchase, the
+  grant and the clawback are each one ledger line.
+- **The owner's dashboard** comps by hand from the person's page (≤100,000 per
+  action, a note required), and shows the balance, the newest 50 non-spend
+  ledger lines and the credits the person spent in the last 30 days.
+- **A relay** adds with `grant_credits { amount (1..10,000), reason? }` — see
+  **Relays**.
+- **Your server** spends with `spendCredits`; **the AI route** spends one per
+  call (see **AI**). Nothing spends from the browser.
+- Spend lines are kept 90 days on the cloud rail; purchases, grants and
+  clawbacks are kept. A balance carries at most 1,000,000,000. Account
+  erasure removes the person's balance and ledger.
+
+```ts
+// browser — show the balance
+const { balance } = await g.credits.balance()
+
+// server — one export costs one credit; the key makes a retry safe
+const r = await gemmeinServer(process.env.GEMMEIN_SECRET_KEY).spendCredits(person.id, {
+  amount: 1, reason: "export", key: `export:${jobId}`
+})
+// r = { ok: true, spent: 1, deduped: false, balance: { before: 12, after: 11 },
+//       event: { id: "cev_…", reason: "export", actor: "<the key's name>" } }
+// a retry with the same key: { …, spent: 0, deduped: true, event: the same one }
+// GemmeinError 402 credits_exhausted — "this person has 0 credits — the spend needs 1"
+```
+
+| code | status | meaning · do |
+|------|--------|--------------|
+| `credits_exhausted` | 402 | The balance is below the spend — the message carries the balance ("this person has {balance} credits — the spend needs {amount}"). Show the pack; never retry the same spend |
+| `session_required` | 401 | `g.credits.balance()` without a signed-in person — sign in first |
+| `capability_required` | 403 | `spendCredits` on a key without "Spend a person's credits" — mint one with it ticked |
+| `person_not_found` | 404 | No person with this id in this app and environment — ids come from `verifySession` or the dashboard |
+| `invalid_amount` | 400 | `amount` outside 1..10,000 (or not a whole number) |
+| `invalid_reason` | 400 | `reason` missing, not text, or over 200 chars |
+| `invalid_key` | 400 | `key` not text, empty, or over 200 chars |
+| `dedupe_conflict` | 409 | The `key` already names a different movement (another kind, or another person) — a key is one movement; reuse it only to retry that same one |
+| `credits_ceiling` | 409 | A credit that would carry the balance past 1,000,000,000 — nothing was added |
+
+`gemmein dev` keeps the same ledger in memory with snapshot and restore, and
+its pay simulator honours the `grantsCredits` a product declares in
+`gemmein/payments.json` (`gemmein payments setup` asks for it), so the
+buy-then-spend loop runs on your machine before a payment provider is
+connected.
+
+---
+
+## AI — `g.ai.chat` / `g.ai.text`
+
+Your app talks to **OpenAI, Anthropic or Google** through Gemmein, on the
+**owner's own provider key**, which never reaches the browser. The owner
+pastes the key once in the dashboard's Keys room; it is write-only from then
+on. A signed-in person's request costs **one credit**, spent before the
+request is forwarded; the provider bills the tokens on the owner's own
+account. The route forwards the provider's own request body as sent — minus
+the `provider` field, and for Google minus `model` and `stream`, which ride
+the URL — adds the provider's auth headers, `content-type` and `accept`, and
+passes the status and the bytes straight back — a stream stays a stream. It does not choose models, cache, summarise,
+moderate or reshape anything, and it is for the browser only: a server key is
+refused (`403 scope_denied`) — a server calls the provider directly.
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `ai.chat` | `(body: object, options?: { provider?: "openai" \| "anthropic" \| "google"; signal?: AbortSignal })` | `Promise<Response>` — the fetch `Response`, untouched: the provider's status, headers and body, streaming intact. A non-2xx from the provider is returned as-is (not thrown) — an answer carrying `x-gemmein-credits-remaining` passed the spend and is the provider's; a Gemmein refusal throws `GemmeinError` |
+| `ai.text` | `(body: object, options?)` | `Promise<string>` — a non-stream call collected to one string, whichever provider answered (openai `choices[0].message.content`; anthropic `content[].text` joined; google `candidates[0].content.parts[].text` joined); a provider's non-2xx throws `provider_error` with the provider's status and message |
+
+- `body` is exactly what the provider documents for its chat endpoint —
+  OpenAI chat completions, Anthropic messages, Google generateContent. Its
+  `model` field, when present, must match `^[A-Za-z0-9._:-]{1,80}$`; Google
+  needs it (it rides the URL); when the owner lists allowed models (up to
+  20 — the Keys room's test call uses the first), any other answers
+  `403 model_not_allowed`.
+- `provider` is optional when one key is configured and required when more
+  than one is (`400 provider_required`). No key at all is
+  `409 ai_not_configured`. `?provider=` and `?stream=1` on the URL do what
+  the body fields do.
+- Two response headers from Gemmein on every answer that passed the spend:
+  `x-gemmein-credits-remaining` (the balance after this call) and, on a
+  refund, `x-gemmein-credit: refunded`.
+- **The refund rule.** A credit is refunded only when the provider fails
+  before its first byte (a non-2xx, or `502 provider_unreachable`). A stream
+  that dies after the first byte is not refunded; hanging up early does not
+  refund. A provider that echoes the key in a refusal reaches the app as
+  `***<hint>`.
+- Limits: 20 calls per person per minute (`429 ai_capped`, `resetAt`), 256 KB
+  body (`413 payload_too_large`) nested at most 32 levels (`400 invalid_body`),
+  170 s in all and, on a stream, 10 s to the first response headers. Every
+  `/ai/chat` call counts toward the app's `api_requests` band like any other
+  request.
+
+```ts
+const res = await g.ai.chat({
+  model: "gpt-4o-mini", stream: true,
+  messages: [{ role: "user", content: text }]
+}, { provider: "openai" })
+for await (const chunk of res.body) render(chunk)      // the provider's SSE, byte for byte
+
+const answer = await g.ai.text({ model: "gpt-4o-mini", messages: [{ role: "user", content: text }] })
+```
+
+| code | status | meaning · do |
+|------|--------|--------------|
+| `credits_exhausted` | 402 | The person's balance is 0 — the message carries it. Show the pack |
+| `ai_not_configured` | 409 | No provider key on this app and environment — the owner pastes one in the Keys room |
+| `provider_required` | 400 | More than one provider key is set — pass `provider` |
+| `model_not_allowed` | 403 | The owner's allowlist names the models this app may call; the message lists them |
+| `ai_capped` | 429 | 20 calls per person per minute — wait for `resetAt` |
+| `payload_too_large` | 413 | The body is over 256 KB — shorten the conversation you send |
+| `invalid_body` | 400 | The body must be the provider's JSON request object, nested at most 32 levels |
+| `session_required` | 401 | No signed-in person — sign in first |
+| `scope_denied` | 403 | A secret key called the route — the route is for the browser; a server calls the provider directly |
+| `provider_unreachable` | 502 | The provider did not answer before the first byte — nothing was charged (the credit is refunded); retry |
+| `provider_error` | the provider's | `g.ai.text` only (client-side): the provider's own non-2xx, its message in `err.message` |
+| `ai_test_capped` | 429 | The Keys room's test call — one a minute per app |
+
+`gemmein dev` answers a fake provider without a key (header `x-gemmein-ai:
+fake`, an echo stream), so the loop runs locally; set
+`GEMMEIN_AI_KEY_OPENAI`, `GEMMEIN_AI_KEY_ANTHROPIC` or `GEMMEIN_AI_KEY_GOOGLE`
+in the local rail's environment for a real call. The owner's Usage room
+counts AI calls for the last 30 days: spent by the customers' credits, priced
+by the provider — Gemmein meters the calls, the provider bills the tokens.
+
+---
+
 ## Server gate — `gemmeinServer(sk).verifySession` / `holdings` / `grantAccess` / `revokeAccess` / `invitePerson`
 
 Gemmein hosts no compute. **Your own** function — Vercel, a VPS, a cron box,
@@ -290,7 +438,7 @@ signed in, it can create them by email first.
 type Holdings = {
   access: string[]                 // the keys they hold NOW — ["access:pro"]
   grants: Grant[]                  // the LIVE grants behind them (revoked/expired are gone)
-  credits: { balance: number } | null   // reserved — null today; credits are NOT shipped
+  credits: { balance: number } | null   // the balance now (engine 0.8.0+); null from an older local engine — see Credits
 }
 
 type Grant = {
@@ -313,12 +461,13 @@ type Grant = {
   (`relay` is the kind a relay's `grant_access` writes; see
   **Relays**). Gate
   on what a person *holds*, never on what they pay. Person id, never an email.
-- **Three capabilities, ticked by the human.** `verifySession` needs none.
+- **Four capabilities, ticked by the human.** `verifySession` needs none.
   `holdings` needs **"Look up a person's access by id"**; `grantAccess` and
   `revokeAccess` need **"Grant and revoke access"**; `invitePerson` needs
-  **"Create a person by email before they sign in"** — plain-English checkboxes
-  the owner ticks when minting the key. Existing keys have all three off, so
-  nothing in production changes.
+  **"Create a person by email before they sign in"**; `spendCredits` needs
+  **"Spend a person's credits"** — plain-English checkboxes the owner ticks
+  when minting the key. Existing keys have all four off, so nothing in
+  production changes.
 - **The invite door.** `invitePerson(email)` is how your server addresses
   someone who has never signed in — the envelope, the invoice, the client
   portal, the booking-winner email: create the person, hand them the file,
@@ -353,7 +502,7 @@ type Grant = {
 | `session_revoked` | 401 | A newer sign-in, a sign-out, or the owner ended it — send them back to sign-in |
 | `person_suspended` | 403 | The owner suspended this person — access is off until the owner reactivates them in the dashboard |
 | `person_not_found` | 404 | No person with this id in this app and environment — ids come from `verifySession` or the dashboard, never from an email. Existence is never leaked |
-| `capability_required` | 403 | The key's box isn't ticked — mint a key with "Look up a person's access by id" / "Grant and revoke access" / "Create a person by email before they sign in" ticked (purchase and subscription grants come from the built-in Stripe path; another provider's payment grants through a relay) |
+| `capability_required` | 403 | The key's box isn't ticked — mint a key with "Look up a person's access by id" / "Grant and revoke access" / "Create a person by email before they sign in" / "Spend a person's credits" ticked (purchase and subscription grants come from the built-in Stripe path; another provider's payment grants through a relay) |
 | `invalid_email` | 400 | `invitePerson`: the address must look like `name@domain` — trimmed, one `@`, a dotted domain, at most 254 characters, no whitespace |
 | `invite_capped` | 429 | `invitePerson`: this app has made 500 invite calls today — the limit is temporary; write to hello@gemmein.com to raise it. `err.resetAt` says when the window ends |
 | `invalid_source` | 400 | `purchase` / `subscription` asked for by hand — refused; those come from Stripe's signed webhook, and another provider's payment grants through a relay |
@@ -364,7 +513,7 @@ type Grant = {
 | `invalid_body` | 400 | One malformed field, whichever it is — `token` (missing, not a string, over 512 chars), `expiresAt` (unparseable or in the past), `reason` (not text, over 200 chars). Branch on the code, read the **message**: it names the field |
 | `scope_denied` | 403 | Not a secret key — the gate is server-only, never the browser |
 | `invalid_id` | 400 | A prototype name (`__proto__`, `constructor`, `prototype`) was sent as a person id or a grant id. Ids come from `verifySession()` or the dashboard — never from a name |
-| `unknown_route` | 404 | Not one of the gate's five routes — the message lists them all |
+| `unknown_route` | 404 | Not one of the gate's six routes — the message lists them all |
 | `method_not_allowed` | 405 | The right route, the wrong verb: `verifySession`, `grantAccess`, `revokeAccess` and `invitePerson` are POST, `holdings` is GET |
 
 ---
@@ -476,6 +625,7 @@ authorise on fields they cannot set, or from a receiver.
 |---|---|---|
 | `write_record` | `collection`, `data`, `to?: "person"` | keyed per event so a retry never duplicates; written through the same door as your app (plain-text and file laws apply); `to: "person"` addresses it to the event's person and is required on addressed and direct collections; the record is app-owned |
 | `grant_access` | `entitlement` (plan or product **name**, or `access:<slug>`), `expiresAt?` (`"30d"`, `"12h"`, `"2w"` or an ISO date), `reason?` (≤ 200, templated) | source `relay`, the seventh grant source; skipped when this event already granted |
+| `grant_credits` | `amount` (1..10,000), `reason?` (≤ 200, templated) | adds to the person's credit balance, once per event (a replay finds its own row); the ledger line reads "relay: <reason>"; a relay adds and never spends |
 | `revoke_access` | `entitlement` | ends every live grant of that entitlement the person holds; skipped when none |
 | `email_person` | `subject` (≤ 300), `text` (≤ 10,000), `kind?: "event" \| "account"` | rides `notify()`'s caps (200 per app per hour, 5 event sends per person per day) and the owner's sends switch; deduped per event |
 | `call_url` | `url` | https only, no template in the URL, no IP literal, never a gemmein.com host, no credentials in the URL; `gemmein dev` allows http to localhost |
@@ -662,11 +812,26 @@ Branch on `err.code`. The gate's own codes (`session_invalid`,
 | `invalid_expand` | `expand` on a field/rule with no link shape | join in memory instead (private/public_read/admin_write have no links) |
 | `scope_denied` | secret key used outside its dashboard-configured scope (or on auth/management routes) | scope the key to that collection, or use the right surface |
 | `unsupported_file_type` (415) | upload isn't an allowed type | images (JPEG/PNG/WebP/GIF/HEIC) or documents (PDF/ZIP/EPUB) |
-| `invalid_key` | a keyed create's `key` breaks the charset/length law | 1-120 chars of letters, numbers, `: _ . @ / -` |
+| `invalid_key` | a keyed create's `key` breaks the charset/length law — or `spendCredits`' `key` is not text of up to 200 chars | 1-120 chars of letters, numbers, `: _ . @ / -` (a create); text ≤ 200 (a spend) |
+| `invalid_amount` / `invalid_reason` (400) | `spendCredits`: `amount` outside 1..10,000, or `reason` missing / over 200 chars | fix the field the code names |
+| `dedupe_conflict` (409) | `spendCredits`: the `key` already names a different movement (another kind or another person) | a key is one movement — reuse it only to retry that same one |
+| `credits_ceiling` (409) | a credit would carry the balance past 1,000,000,000 (a comp, a pack, a relay grant) — nothing was added | the balance is at its most |
+| `invalid_body` (400) | on `g.ai.chat`: the body is not the provider's JSON request object, or is nested deeper than 32 levels | send the provider's own request object |
+| `provider_error` (client-side, the provider's status) | `g.ai.text`: the provider answered a non-2xx; `err.message` is the provider's own reason | read it — the credit was refunded when the provider failed before its first byte |
+| `ai_test_capped` (429) | the Keys room's test call — one a minute per app | wait a minute |
 | `invalid_secret_key` (client-side) | `gemmeinServer()` got a missing/`pk_` key | pass the `sk_` key from a server env var |
 | `invalid_response` (client-side, status 0) | the server answered 200 to `verifyEmailCode` without a session token — a proxy or mock in the path, not Gemmein | check `apiUrl` and anything rewriting responses; the call is safe to retry |
 | `authentication_required` (401) | checkout/subscription/pay without a signed-in user | sign the user in first |
 | `plan_has_no_link` (409) | the paid plan has no Payment Link pasted yet | ask the owner to paste it in their dashboard |
 | `account_suspended` (403) | the app owner's account is suspended (billing) | the owner fixes payment at app.gemmein.com |
+| `credits_exhausted` (402) | the person's balance is below the spend — the message carries the balance ("this person has {balance} credits — the spend needs {amount}") | show the pack; never retry the same spend |
+| `ai_not_configured` (409) | no provider key on this app and environment | the owner pastes one in the Keys room |
+| `provider_required` (400) | more than one provider key is set and the call named none | pass `provider` |
+| `model_not_allowed` (403) | the owner's allowlist does not name this model | use one the message lists |
+| `ai_capped` (429) | 20 AI calls per person per minute | wait for `resetAt` |
+| `payload_too_large` (413) | on `g.ai.chat`: the body is over 256 KB | shorten the conversation you send |
+| `session_required` (401) | `g.ai.chat` / `g.credits.balance` without a signed-in person | sign in first |
+| `scope_denied` (403) | on `g.ai.chat`: a secret key called the route | the route is for the browser — a server calls the provider directly |
+| `provider_unreachable` (502) | the provider did not answer before the first byte; the credit is refunded | retry |
 
 Keys: `pk_` (public, domain-locked, browser-safe) vs `sk_` (secret, server only).

package/dist/index.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GemmeinServer = exports.CollectionClient = exports.StorageClient = exports.AccountClient = exports.PaymentsClient = exports.SubscriptionsClient = exports.FilesClient = exports.PurchasesClient = exports.AuthClient = exports.Gemmein = exports.BrowserTokenStore = exports.MemoryTokenStore = exports.GemmeinError = exports.CLIENT_INFO = exports.SDK_VERSION = void 0;
+exports.GemmeinServer = exports.CollectionClient = exports.StorageClient = exports.AiClient = exports.CreditsClient = exports.AccountClient = exports.PaymentsClient = exports.SubscriptionsClient = exports.FilesClient = exports.PurchasesClient = exports.AuthClient = exports.Gemmein = exports.BrowserTokenStore = exports.MemoryTokenStore = exports.GemmeinError = exports.CLIENT_INFO = exports.SDK_VERSION = void 0;
 exports.gemmein = gemmein;
 exports.gemmeinServer = gemmeinServer;
 /** This build's version — the value `package.json` carries. Kept inline
@@ -9,7 +9,7 @@ exports.gemmeinServer = gemmeinServer;
  *  second module). `scripts/sync-version.mjs` rewrites the literal from
  *  package.json before every build (`prebuild`), and a test pins the two
  *  equal, so a bump can never ship with a stale header. */
-exports.SDK_VERSION = "0.6.0"; // synced from package.json — do not edit by hand
+exports.SDK_VERSION = "0.7.0"; // synced from package.json — do not edit by hand
 /** W9.1 / CLIENT-INFO-1: every request the SDK makes to Gemmein carries
  *  `x-client-info: gemmein-sdk/<version>`. The server records it on the
  *  secret-key usage ledger ("last seen from gemmein-sdk/0.5.0"), so a
@@ -124,6 +124,8 @@ class Gemmein {
         this.purchases = new PurchasesClient(config);
         this.account = new AccountClient(config);
         this.files = new FilesClient(config);
+        this.credits = new CreditsClient(config);
+        this.ai = new AiClient(config);
     }
     /**
      * Your app's data — `g.collection<{ title: string }>("notes")`. The
@@ -372,6 +374,169 @@ class AccountClient {
     }
 }
 exports.AccountClient = AccountClient;
+/** The signed-in person's own credits — so an app can draw its own meter. */
+class CreditsClient {
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * The balance RIGHT NOW, server-resolved — the number that refuses at
+     * zero, never client math. Session required (`session_required`, 401).
+     *
+     *   const { balance } = await g.credits.balance();
+     */
+    async balance() {
+        return runtimeRequest(this.config, "/auth/credits");
+    }
+}
+exports.CreditsClient = CreditsClient;
+/**
+ * The AI route. `chat` takes the provider's own request body — exactly what
+ * you would POST to OpenAI's /v1/chat/completions, Anthropic's /v1/messages
+ * or Google's generateContent — and answers with the fetch `Response`
+ * untouched, streaming intact (SSE stays SSE). Gemmein spends one credit,
+ * adds the owner's key, forwards, and passes status and bytes back.
+ * Response headers: `x-gemmein-credits-remaining` on every answer that
+ * passed the spend; `x-gemmein-credit: refunded` when the provider failed
+ * before its first byte.
+ */
+class AiClient {
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     *   const res = await g.ai.chat({ model: "gpt-4o-mini", messages, stream: true });
+     *   for await (const chunk of res.body) { … }
+     *
+     * Browser sessions only — a server key is refused (`scope_denied`, 403).
+     * Refusals, all `GemmeinError`: `session_required` (401) ·
+     * `credits_exhausted` (402 — the message carries the balance; show your
+     * own "buy more" door, which is a product checkout) · `ai_not_configured`
+     * (409 — the owner has set no key) · `provider_required` (400) ·
+     * `model_not_allowed` (403 — the owner's models list) · `ai_capped`
+     * (429 — 20 calls a minute per person; `err.resetAt`) ·
+     * `payload_too_large` (413 — 256 KB) · `provider_unreachable` (502,
+     * before the first byte, refunded). Those are GEMMEIN's refusals. The
+     * PROVIDER's own answer — 2xx or not — is returned as it came: an answer
+     * that carries `x-gemmein-credits-remaining` (or `x-gemmein-credit`)
+     * passed the spend, so its status and body are the provider's; read
+     * `res.ok` / `res.status` yourself (a provider 4xx before the first byte
+     * is refunded, header `x-gemmein-credit: refunded`).
+     */
+    async chat(body, options = {}) {
+        const payload = options.provider ? { provider: options.provider, ...body } : body;
+        const response = await fetch(new URL("/ai/chat", this.config.apiUrl), {
+            method: "POST",
+            body: JSON.stringify(payload),
+            headers: await runtimeHeaders(this.config, { "content-type": "application/json" }),
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+        if (!response.ok) {
+            if (isForwardedAnswer(response)) {
+                // Past the spend: the provider answered. `provider_unreachable` is
+                // the one Gemmein refusal written after the spend (it carries the
+                // refund header) — peek without consuming so it stays typed.
+                const peek = (await response.clone().json().catch(() => null));
+                if (peek?.code !== "provider_unreachable")
+                    return response;
+            }
+            const errorBody = await readErrorBody(response);
+            if (errorBody.code === "auth_expired")
+                await this.config.tokenStore.clear();
+            throw new GemmeinError({ status: response.status, ...errorBody });
+        }
+        return response;
+    }
+    /**
+     * The non-streaming convenience: one call, one string. Pass a body that
+     * does NOT stream (`stream` unset or false); the provider's JSON answer is
+     * read whole and the text is lifted out per provider — OpenAI
+     * `choices[0].message.content`, Anthropic `content[].text` joined,
+     * Google `candidates[0].content.parts[].text` joined. An answer with no
+     * text in any of those places throws `invalid_response` (status 0). A
+     * provider's own non-2xx throws `provider_error` with the provider's
+     * status and the provider's message (the owner's key masked to its
+     * hint if the provider echoed it).
+     *
+     *   const answer = await g.ai.text({ model: "claude-sonnet-4-5", max_tokens: 400, messages });
+     */
+    async text(body, options = {}) {
+        const response = await this.chat(body, options);
+        if (!response.ok) {
+            throw new GemmeinError({
+                status: response.status,
+                code: "provider_error",
+                message: await providerErrorMessage(response),
+            });
+        }
+        const data = (await response.json());
+        const text = extractAiText(data);
+        if (text === null) {
+            throw new GemmeinError({
+                status: 0,
+                code: "invalid_response",
+                message: "the provider answered without any text — for a streaming body use g.ai.chat() and read the stream",
+            });
+        }
+        return text;
+    }
+}
+exports.AiClient = AiClient;
+/** An answer that passed the spend: the engine stamps the balance (and, on
+ *  a refund, `x-gemmein-credit`) only after the credit moved — a refusal
+ *  before the spend carries neither. */
+function isForwardedAnswer(response) {
+    return response.headers.has("x-gemmein-credits-remaining") || response.headers.has("x-gemmein-credit");
+}
+/** The provider's own reason, whichever shape it used — OpenAI, Anthropic
+ *  and Google all nest it as `error.message`; anything else is the text. */
+async function providerErrorMessage(response) {
+    const text = await response.text().catch(() => "");
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed && typeof parsed === "object") {
+            const nested = typeof parsed.error === "object" && parsed.error !== null ? parsed.error.message : parsed.error;
+            const message = typeof nested === "string" ? nested : typeof parsed.message === "string" ? parsed.message : null;
+            if (message)
+                return message;
+        }
+    }
+    catch {
+        // not JSON — the text is the reason
+    }
+    return text.trim().slice(0, 500) || `the provider answered ${response.status}`;
+}
+/** The per-provider lift, by shape (a provider's answer is unmistakable). */
+function extractAiText(data) {
+    if (!data || typeof data !== "object")
+        return null;
+    const d = data;
+    // OpenAI: choices[0].message.content (a string, or content parts)
+    if (Array.isArray(d.choices)) {
+        const message = d.choices[0]?.message;
+        const content = message?.content;
+        if (typeof content === "string")
+            return content;
+        if (Array.isArray(content))
+            return joinTextParts(content);
+        return null;
+    }
+    // Anthropic: content[] blocks, the text ones joined
+    if (Array.isArray(d.content))
+        return joinTextParts(d.content);
+    // Google: candidates[0].content.parts[].text joined
+    if (Array.isArray(d.candidates)) {
+        const parts = d.candidates[0]?.content?.parts;
+        return Array.isArray(parts) ? joinTextParts(parts) : null;
+    }
+    return null;
+}
+function joinTextParts(parts) {
+    const texts = parts
+        .map((p) => (p && typeof p === "object" && typeof p.text === "string" ? p.text : null))
+        .filter((t) => t !== null);
+    return texts.length > 0 ? texts.join("") : null;
+}
 function isSessionResponse(value) {
     return (typeof value === "object" &&
         value !== null &&
@@ -952,6 +1117,43 @@ class GemmeinServer {
             }),
         });
     }
+    /**
+     * W9.3 — spend a person's credits from YOUR server, with a reason:
+     *
+     *   const { balance } = await g.spendCredits(personId, {
+     *     amount: 5,                       // default 1; 1..10,000 per call
+     *     reason: "render:4k",             // what the owner reads in the ledger
+     *     key: `render:${jobId}`,          // your retry key — a repeat is deduped
+     *   });
+     *   // { ok: true, spent: 5, deduped: false, balance: { before: 20, after: 15 },
+     *   //   event: { id: "cev_…", reason: "render:4k", actor: "<your key's name>" } }
+     *
+     * ONE conditional update, floored at 0: the spend succeeds whole or not at
+     * all, and `402 credits_exhausted` says "this person has {balance} credits
+     * — the spend needs {amount}". Pass `key` when the caller can retry — the
+     * same key answers the first spend again with `deduped: true`, `spent: 0`,
+     * the same `event` and the balance untouched. The key is scoped to the
+     * person: one order id reused for two people charges both. Credits come
+     * from a pack they bought, a comp in the back office, or a relay; a key
+     * cannot mint them.
+     *
+     * Needs the key's "Spend a person's credits" box ticked by your human.
+     * Refusals: `capability_required` (403 — "this key can't spend credits —
+     * mint a key with 'Spend a person's credits' ticked") ·
+     * `credits_exhausted` (402) · `person_not_found` (404) · `invalid_amount` /
+     * `invalid_reason` / `invalid_key` (400) · `dedupe_conflict` (409 — the
+     * key already names a different movement).
+     */
+    async spendCredits(personId, input) {
+        return this.gate(`/server/people/${encodeURIComponent(personId)}/credits/spend`, {
+            method: "POST",
+            body: JSON.stringify({
+                ...(input.amount !== undefined ? { amount: input.amount } : {}),
+                reason: input.reason,
+                ...(input.key !== undefined ? { key: input.key } : {}),
+            }),
+        });
+    }
     /**
      * End one grant — the reversibility law in one call:
      *