@gemmein/sdk 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,224 @@
+# Changelog — @gemmein/sdk
+
+All notable changes to the SDK are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
+semver. A change that asks something of your app has a note in
+[`migrations/`](./migrations/README.md) naming the version it arrived in
+and the version by which the action is required.
+
+The SDK and the local engine (`@gemmein/cli`) share a minor version from
+0.6.0 / 0.7.0 onward: a feature that lands in one lands in the other in
+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
+- `list({ limit })` is honoured or refused, never clamped: a `limit`
+  outside 1..100 answers 400 `invalid_limit` ("limit must be between 1 and
+  100"). The default stays 25 and the maximum 100. Apps that asked for more
+  than 100 and read the first page as the whole set now get the refusal —
+  page with `cursor`. See `migrations/list-limit-refusal.md`.
+- `verifyEmailCode` throws `GemmeinError` with code `invalid_response`
+  (status 0) when a 200 answer carries no session token, where it threw a
+  bare `Error` before. Every error the SDK raises is now a `GemmeinError`.
+- `engines.node` is `>=20`. Node 18 reached end of life in April 2025; the
+  SDK is built and tested on 20 and 22.
+
+### Added
+- Relays. One JSON file, `gemmein/relays/<name>.json`: a trigger (a
+  provider's signed webhook at `POST /hooks/<appId>/<name>`, a schedule, or a
+  record change) and one to ten of Gemmein's own verbs (write a record, grant
+  or revoke access, email the person, call your URL), run in order with
+  retries and a replay button in the dashboard. No SDK method: the surface is
+  the file and the dashboard. `REFERENCE.md` carries the definition, the
+  triggers, the actions, the `call_url` contract and its signature header,
+  the templates, the lifecycle and the codes; `llms.txt` carries the
+  GoCardless worked example. A `call_url` that writes back through the SDK
+  fires `data_change` like any write. Stripe stays built in; any provider that
+  signs its webhooks drives access the same way.
+- `GrantSource` gains `relay`: a grant a relay's `grant_access`
+  wrote. `holdings` and `verifySession` list it by kind like the other six;
+  `ManualGrantSource` is unchanged — no key can mint it.
+- `gemmeinServer(...).invitePerson(email)` creates a person by email before
+  they sign in, or returns the one that exists (`{ person, created }`, type
+  `InvitedPerson`). Behind the third key capability, "Create a person by
+  email before they sign in". Refusals: `invalid_email`, `invite_capped`
+  (500 accepted calls per app per day, raised on request). An invited person
+  shows as invited on the person page until their first sign-in and is not
+  counted in the people band (the billable unit) until then.
+- Every request carries `x-client-info: gemmein-sdk/<version>`. The Keys
+  page shows the SDK build behind a key's most recent call ("Last seen
+  from gemmein-sdk/0.6.0, as reported"). `SDK_VERSION` and `CLIENT_INFO`
+  are exported.
+- `CHANGELOG.md` and `migrations/` ship in the package.
+
+## [0.5.0] — 2026-09-03
+
+### Added
+- The server gate on `gemmeinServer(sk)`: `verifySession(token)`,
+  `holdings(personId)`, `grantAccess(personId, { entitlement, reason? })`,
+  `revokeAccess(personId, grantId, { reason? })`. Grant and revoke require
+  the key's `grantAccess` capability (minted on the Keys page).
+- Exported types `Holdings`, `Grant`, `GatePerson`, `GrantSource`,
+  `ManualGrantSource`.
+
+## [0.4.7] — 2026-09-02
+
+### Changed
+- Documentation-only release. The packaged `llms.txt` and `REFERENCE.md`
+  carry the W5 teaching: a promote run carries new fields as well as new
+  collections.
+
+## [0.4.6] — 2026-08-26
+
+### Changed
+- `reaffirm.mjs` runs the 16-probe harness; its teachings are rewritten.
+
+## [0.4.5] — 2026-08-26
+
+### Changed
+- Documentation-only release. `REFERENCE.md` catches up with documents,
+  `since`, `watch()`, `notify()`, the file laws and `purchases.mine()`.
+
+## [0.4.4] — 2026-08-26
+
+### Added
+- `upload(file, { for })` addresses a file to one person; the file-kind
+  (image or document) and file-class teaching.
+
+## [0.4.3] — 2026-08-25
+
+### Added
+- `gemmeinServer(sk).notify(personId, { subject, text, kind?, key? })`.
+
+### Changed
+- `watch()` stops on an auth-terminal answer instead of retrying it.
+
+## [0.4.2] — 2026-08-25
+
+### Added
+- `list({ since })` with `ListResult.deleted` and `ListResult.watermark`;
+  `watch()` on a collection.
+
+## [0.4.1] — 2026-08-22
+
+### Added
+- `GemmeinError.requires` (and `requiresAny`) on 403 `entitlement_required`,
+  on both the collection path and the runtime clients.
+
+## [0.4.0] — 2026-07-30
+
+### Changed
+- A product's file lives on the product card and the purchase is the
+  authorisation to read it.
+
+## [0.3.2] — 2026-07-29
+
+### Fixed
+- The wave-audit fixes for the 0.3 line.
+
+## [0.3.1] — 2026-07-29
+
+### Changed
+- Documentation: the guide teaches paid access.
+
+## [0.3.0] — 2026-07-29
+
+### Added
+- The file reference contract: records store references, files resolve
+  through the SDK.
+
+## [0.2.1] — 2026-07-22
+
+### Changed
+- Documentation-only refresh.
+
+## [0.2.0] — 2026-07-22
+
+### Changed
+- Two-layer shape: `g.collection(name)` plus the self-service primitives.
+
+## [0.1.0] — 2026-07-11
+
+### Added
+- First published release: built `dist`, persistent sessions, journey
+  signposts.