@gemmein/sdk 0.6.0 → 0.7.0

package/llms.txt

@@ -39,7 +39,10 @@ creating no accounts is the correct behavior until the verdict is in.
    safety rules (private, shared, admin_write, public_read, community,
    addressed, direct), subscriptions and one-off digital products (Stripe
    built in; any provider that signs its webhooks drives access through a
-   relay), image uploads and paid file delivery, entitlement-gated
+   relay), consumable credits (buy a pack, spend atomically, a zero
+   floor — see Credits), a chat call to OpenAI, Anthropic or Google on
+   the founder's own key at one credit per call (see The AI route),
+   image uploads and paid file delivery, entitlement-gated
    access, race-safe bookings/stock/counters, account-deletion cascade.
    Out of scope — each of these downgrades the verdict and must never be
    silently approximated:
@@ -50,9 +53,10 @@ creating no accounts is the correct behavior until the verdict is in.
      nothing in between — so an app whose CORE loop needs teams, roles
      or seats DOESN'T FIT
    - carts, quantities, physical goods, shipping, inventory
-   - credits or usage metering TODAY (paid access is yes-or-no; consumable
-     credits are planned, not shipped — don't design around them yet, and
-     never sell a "credit pack" until this file says the ledger exists)
+   - usage-based INVOICING (a bill after the fact, by token or by minute):
+     not shipped. Credits ARE — consumable credits: buy a pack, spend
+     atomically, a zero floor — see Credits; a "100 credit pack" is a
+     product with Grants credits = 100, and a model call is one credit
    - seats (owner-run: not coming)
    - hosted functions or cron: Gemmein runs no code of yours — but your
      own function anywhere asks Gemmein who a person is and what they
@@ -391,14 +395,15 @@ contents.
   what the person holds NOW: `access` (keys like "access:pro"), `grants`
   (each with its source KIND only — subscription | purchase | manual |
   trial | promotion | migration | relay — plus start and expiry), and `credits`,
-  a reserved slot that is always `null` today (consumable credits are NOT
-  shipped; don't design around them). Never subscription status, amounts
+  `{ balance }` — how many credits the person holds now (engine 0.8.0 and
+  later; `null` from an older local engine). Never subscription status, amounts
   or Stripe ids: gate on what a person HOLDS, never on billing. Person
   id, NEVER an email address. verifySession needs nothing extra; looking
   someone up by id and granting are new power, so they sit behind per-key
   checkboxes the HUMAN ticks when minting the key — ask your human to
   tick "Look up a person's access by id" / "Grant and revoke access" /
-  "Create a person by email before they sign in" (invitePerson). A
+  "Create a person by email before they sign in" (invitePerson) /
+  "Spend a person's credits" (spendCredits). A
   key grants MANUAL access only (manual | trial | promotion | migration):
   purchases and subscriptions come from the built-in Stripe path, and
   another provider's payment grants through a relay (source `relay`). Every /server/*
@@ -442,17 +447,20 @@ contents.
   writes the receipt, tells the person, passes the signal to your URL.
   Stripe stays built in; any provider that signs its webhooks drives
   access the same way.
-  Does: write a record · grant access · revoke access · email the person
-  the event is about · call your URL (a signed notice to a server YOU run).
+  Does: write a record · grant access · revoke access · grant credits ·
+  email the person the event is about · call your URL (a signed notice to
+  a server YOU run).
   Does not: run your code; call OpenAI or any third API for you (call_url
   carries Gemmein's body and signature, never your key or a request you
   shape); attach a person to a schedule (no "email everyone due tomorrow"
   yet); transform or compute data; act on more than one person per event
-  (a list is a broadcast); grant credits (planned, not shipped).
+  (a list is a broadcast); spend credits (a spend is your server's or the
+  AI route's — a relay only adds).
   Needs something else when: the work THINKS — a model call, a score, a
   transform, a third API — put that in your own function behind call_url;
   it receives a verified event with the person already resolved. The AI
-  route (planned) is where Gemmein will hold a provider key and call for you.
+  route is where Gemmein holds your provider key and makes a chat call for
+  a signed-in person at one credit each — see The AI route.
   Use a relay when: a provider other than Stripe signs a webhook that
   should change access or write a record (GoCardless, Paddle, Lemon
   Squeezy, a form or signature tool); a record change should tell the
@@ -504,6 +512,8 @@ contents.
   - grant_access { entitlement, expiresAt?, reason? } — source `relay`, the
     seventh grant source; "granted by relay <name>" on the person's page.
   - revoke_access { entitlement } — ends every live grant of it.
+  - grant_credits { amount (1..10,000), reason? } — adds to the person's
+    balance, once per event; the ledger line reads "relay: <reason>".
   - email_person { subject, text, kind? } — rides notify's caps.
   - call_url { url } — https, signed POST (`X-Gemmein-Signature`), 10 s; the
     same `id` on every retry and replay — your URL deduplicates on it.
@@ -675,11 +685,10 @@ contents.
   screen and send them to checkout; retry only after they hold one. Proof surfaces: `await g.purchases.mine()`
   (everything they paid for, refunds applied, with the `grants` each purchase
   carries) and `await g.subscriptions.mine()`.
-  NO credits or usage limits YET — access is yes-or-no today. Consumable
-  credits (buy a pack, spend atomically, a zero floor) are planned, not
-  shipped: until this file teaches them, a "100 credit pack" is NOT a
-  pattern (the webhook can only SET a number, so a second pack erases the
-  first). NO seats, by design — not coming.
+  Access is yes-or-no. A QUANTITY beside it is credits — buy a pack, spend
+  atomically, a zero floor (see Credits): a "100 credit pack" is a product
+  with Grants credits = 100, and the ledger ADDS at every purchase, so a
+  second pack makes 200. NO seats, by design — not coming.
 - Two FAMILIES of grant, and the line between them is law. Every grant is
   one key + one reason + a start + maybe an end, never edited (an extension
   is a NEW grant). PURCHASE-TIED (`subscription`, `purchase`): written only
@@ -740,6 +749,122 @@ contents.
   webhook. NO carts, NO quantities — one product per checkout by design; a
   cart is N checkouts or one bundled product. 404 unknown_product lists
   what the app actually sells — use those names.
+- Credits — a quantity beside access. See https://docs.gemmein.com/credits
+  What it is: a balance your customers hold and your product spends — a
+  pack they buy, a comp you give, a call that costs one.
+  Does: a product grants credits at purchase (its Grants credits field);
+  your server spends them with a reason; the AI route spends one per call;
+  a relay grants them; the owner's dashboard shows the balance and the
+  ledger and comps by hand. Every movement is one ledger line.
+  Does not: expire; go negative (floor 0 — a spend past the balance is
+  refused whole, never partly); price by token; open access (that is an
+  entitlement — a person with 500 credits and no plan is still refused by
+  a locked collection); count seats or quotas; spend from the browser.
+  Needs something else when: access should switch on with a plan (an
+  entitlement — see Paid ACCESS); you bill by usage after the fact (not
+  shipped — sell packs up front); the spend must happen in the browser
+  (it never does: your server, a relay or the AI route moves credits).
+  The case: "sell a 100-credit pack and let each chat cost one". The pack
+  is a product on the Payments page with Grants credits = 100 (the
+  product's `grantsCredits`); each purchase ADDS 100 to the buyer's
+  balance (two packs make 200), and a FULL refund claws back what is still
+  unspent, floor 0. The app reads the balance to show it:
+
+      const { balance } = await g.credits.balance()   // browser, signed in
+
+  Your server spends by person id, with a reason and a key, so a retry
+  never spends twice (the key needs "Spend a person's credits" ticked):
+
+      const r = await gemmeinServer(sk).spendCredits(person.id, {
+        amount: 1, reason: "export", key: `export:${jobId}`
+      })
+      // { ok: true, spent: 1, deduped: false, balance: { before: 12, after: 11 },
+      //   event: { id: "cev_…", reason: "export", actor: "<the key's name>" } }
+      // the same key again: spent: 0, deduped: true, the same event, nothing moved
+      // 402 credits_exhausted — "this person has 0 credits — the spend needs 1"
+
+  `holdings.credits` is `{ balance }` on verifySession and holdings, so one
+  verify answers who, what they hold AND how many. Numbers: no expiry ·
+  floor 0 · a balance carries at most 1,000,000,000 · a pack 1..1,000,000 ·
+  a server spend 1..10,000 per call · a comp ≤100,000 · a relay grant
+  1..10,000 · spend lines kept 90 days on the cloud rail (purchases, grants
+  and clawbacks are kept). Facts: a purchase by an email that has never
+  signed in creates the person and credits them; your `key` is scoped to
+  the person and namespaced (`srv:`), so one order id reused for two people
+  charges both and rotating the secret key never re-charges; a full refund
+  claws back what THAT purchase's ledger row granted, whatever the product
+  says today; the owner's page lists the newest 50 non-spend lines and the
+  credits the person spent in the last 30 days. Codes: `credits_exhausted`
+  (402 — carries the balance; show the pack, never retry the spend) ·
+  `capability_required` (403) · `person_not_found` (404) · `invalid_amount`
+  / `invalid_reason` / `invalid_key` (400) · `dedupe_conflict` (409 — the
+  key already names a different movement) · `credits_ceiling` (409 — the
+  balance would pass 1,000,000,000; nothing added).
+- The AI route — your app talks to OpenAI, Anthropic or Google through
+  Gemmein, on YOUR provider key, which never reaches the browser.
+  See https://docs.gemmein.com/ai
+  What it is: your human pastes their provider key once in the dashboard's
+  Keys room (write-only: never shown again, never in the app's code); a
+  signed-in person's chat request reaches the provider through Gemmein and
+  costs one credit.
+  Does: takes the provider's OWN request body from a signed-in person,
+  spends one credit, forwards the body as sent — minus the `provider`
+  field, and for Google minus `model` and `stream`, which ride the URL —
+  with the key, content-type and accept added, passes the provider's
+  status and bytes straight back (a stream stays a stream), and refunds
+  the credit only when the provider fails before its first byte.
+  Does not: choose models, cache, summarise, moderate, or reshape the
+  request or the answer; run from a server key (`sk_` is refused); reach
+  any host but the three; price by token (one credit per call, whatever
+  the length); refund a call that dies mid-stream, or one the caller
+  abandons before the headers (hanging up early does not refund).
+  Needs something else when: your SERVER makes the model call (call the
+  provider directly with your key; the gate still answers who they are and
+  what they hold); the call is not a chat call — embeddings, images, audio
+  (the provider directly, from your server); the provider is not on the
+  list (write to hello@gemmein.com).
+  The case: "a chat app where each message costs one credit and my OpenAI
+  key stays private". The body is exactly what the provider documents for
+  its chat endpoint; `g.ai.chat` returns the fetch Response untouched:
+
+      const res = await g.ai.chat({
+        model: "gpt-4o-mini", stream: true,
+        messages: [{ role: "user", content: text }]
+      }, { provider: "openai" })   // provider is optional when one key is set
+      // res.status and res.body are the provider's own (SSE stays SSE) —
+      // a provider 4xx/5xx comes back the same way: read res.ok; only
+      // Gemmein's own refusals throw
+      // res.headers: x-gemmein-credits-remaining: 41
+      //              x-gemmein-credit: refunded  (a failure before the first byte)
+
+  For a non-stream answer as one string, whichever provider answered (a
+  provider non-2xx throws `provider_error` with its status and message):
+
+      const answer = await g.ai.text({ model: "gpt-4o-mini",
+        messages: [{ role: "user", content: text }] })
+
+  Branch on `err.code`: credits_exhausted (402 — the message carries the
+  balance; show the pack) · ai_not_configured (409 — no key set; the owner
+  pastes one) · provider_required (400 — more than one key set; name
+  `provider`) · model_not_allowed (403 — the owner's allowlist names what
+  is allowed) · ai_capped (429 — 20 per person per minute; wait for
+  `resetAt`) · payload_too_large (413 — 256 KB) · invalid_body (400 — the
+  body must be the provider's JSON object, nested at most 32 levels) ·
+  session_required (401 — sign in first) · scope_denied (403 — a server
+  key; the route is for the browser) · provider_unreachable (502 — no
+  answer before the first byte; the credit is refunded; retry) ·
+  provider_error (`g.ai.text` only — the provider's own non-2xx, its
+  status and message). Numbers: 1 credit per call · 20/min/person · 256 KB
+  · 170 s in all, and on a stream 10 s to the first response headers.
+  Facts: `?provider=` and `?stream=1` on the URL do what the body fields
+  do; the owner may list up to 20 allowed models (the Keys room's test
+  call uses the first); every `/ai/chat` call counts toward the app's
+  api_requests band like any other request; a provider that echoes the key
+  in a refusal reaches you as `***<hint>`. The owner's Usage room counts
+  the calls; the provider bills the tokens on the owner's own account.
+  `gemmein dev` answers a fake provider without a key (header
+  `x-gemmein-ai: fake`), so the loop runs locally; set GEMMEIN_AI_KEY_OPENAI
+  / _ANTHROPIC / _GOOGLE there for a real call.
 - Drafts on PUBLIC collections (public_read, community): create with the
   OPTION `{ published: false }` → hidden from every reader except its
   author and the owner, server-enforced; publish with
@@ -789,7 +914,8 @@ contents.
   conversation and customer replies land; holding the billing band;
   running a relay: an inbound webhook from any provider that
   signs its calls, a schedule, or a record change → write a record,
-  grant or revoke access, email the person, or call your URL, with
+  grant or revoke access, grant credits, email the person, or call your
+  URL, with
   retries and a replay button (the definition is a file you write —
   see Relays — and the dashboard is where it is read, paused,
   replayed and its secrets rotated). None

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gemmein/sdk",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Gemmein SDK \u2014 passwordless auth, safe storage, and Stripe-driven record flips for AI-built apps. Small enough that one prompt teaches the whole API.",
   "license": "MIT",
   "type": "module",