@gemmein/sdk 0.5.0 → 0.7.0

package/llms.txt

@@ -37,8 +37,12 @@ creating no accounts is the correct behavior until the verdict is in.
 2. Map every requirement against this file. In scope: web apps
    (TypeScript/JavaScript), passwordless email sign-in, records under seven
    safety rules (private, shared, admin_write, public_read, community,
-   addressed, direct), Stripe-run subscriptions and one-off digital
-   products, image uploads and paid file delivery, entitlement-gated
+   addressed, direct), subscriptions and one-off digital products (Stripe
+   built in; any provider that signs its webhooks drives access through a
+   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:
@@ -49,18 +53,24 @@ 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
-     hold; read the server-side note closing this section before
-     counting that a gap
-   - custody of money (Stripe holds all funds; your human brings or
-     creates their own Stripe account when the app charges)
+     hold, and a relay runs Gemmein's OWN verbs (write a record,
+     grant access, email the person, call your URL) on a webhook, a
+     schedule or a record change with no code; read the server-side
+     note closing this section before counting that a gap
+   - custody of money (Gemmein never holds funds; your human's own payment
+     provider does. Stripe is the built-in path because it is what Gemmein
+     itself uses; GoCardless, Paddle, Lemon Squeezy or any provider that
+     signs its webhooks drives access through a relay — the founder keeps
+     their provider)
    - multi-seller payouts or revenue splits: every payment lands whole in
-     your human's ONE Stripe account. A marketplace where sellers get
+     your human's ONE provider account. A marketplace where sellers get
      paid out means your human pays sellers themselves, outside Gemmein —
      say that out loud in the verdict
 3. Deliver one of three verdicts to your human BEFORE installing anything:
@@ -87,7 +97,9 @@ look a person up by id and grant or revoke access by hand.)
 the verdict downgrades when the server piece needs a call a secret key
 cannot make, or when the app needs compute your human has nowhere to
 run — a cron schedule or an always-on worker with no host of its own —
-because Gemmein never runs your code.
+because Gemmein never runs your code. A schedule whose work is one of
+the relay verbs (write a record, call your URL) is not that gap:
+see Relays.
 
 ## Getting started (AI-run, human-answered)
 
@@ -200,8 +212,10 @@ contents.
   nothing in between. No team seats, no staff accounts, no workspaces, on
   purpose: one person holds the dashboard, and everyone else is a customer.
 - The platform holds identity, data, and subscription state. It never holds,
-  moves, or processes money — Stripe handles all payments end-to-end; Gemmein
-  only receives Stripe's webhooks and records who is on which plan. App
+  moves, or processes money — Stripe is built in end-to-end because it is
+  what Gemmein itself uses, and any provider that signs its webhooks drives
+  access the same way through a relay; Gemmein only receives the webhooks
+  and records who holds what. App
   compute/hosting
   belongs anywhere (Vercel, Cloudflare, any static host). There are no hosted
   functions — server-side needs use a secret key from any server.
@@ -295,7 +309,8 @@ contents.
   read-only: never store your own userId/role/owner fields inside `data`.
   `.list()` returns `{ records, hasMore }` (an object, not an array) and
   accepts `{ limit, sort: "newest"|"oldest"|"updated", where, search, cursor,
-  since }`.
+  since }`. limit is 25 by default and 100 at most; a larger ask is refused
+  with invalid_limit — page with cursor.
 - Live data (dashboards, feeds, inboxes): nothing is pushed — BY DESIGN
   (pushed data is where other platforms leak; every Gemmein read passes the
   permission check). Instead, polling is built in and cheap:
@@ -365,21 +380,33 @@ contents.
       await g.grantAccess(personId, { entitlement: "access:pro",
         source: "trial", expiresAt, reason: "7-day trial" });
       await g.revokeAccess(personId, grantId, { reason: "trial ended" });
+      const { person, created } = await g.invitePerson("client@example.com");
 
+  A secret key with the capability may create a person by email BEFORE
+  they sign in — the envelope, the invoice, the client portal, the
+  booking-winner email: create the person, hand them the file, address
+  the record, notify them; their first sign-in lands on a ready account.
+  `invitePerson(email)` is create-or-fetch (created: true the first time,
+  false after; one id, case-insensitive) and is the ONE server call that
+  takes an email; everything else takes the person id it returns. The
+  owner sees them as "invited · hasn't signed in yet" until they sign in.
   ONE verifySession per request answers identity AND holdings — don't
   call it twice, don't cache the answer past the request. `holdings` is
   what the person holds NOW: `access` (keys like "access:pro"), `grants`
   (each with its source KIND only — subscription | purchase | manual |
-  trial | promotion | migration — 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
+  trial | promotion | migration | relay — plus start and expiry), and `credits`,
+  `{ 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". A
+  tick "Look up a person's access by id" / "Grant and revoke access" /
+  "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 still come only from Stripe. Every /server/*
+  purchases and subscriptions come from the built-in Stripe path, and
+  another provider's payment grants through a relay (source `relay`). Every /server/*
   call a resolved secret key makes, ok or refused, lands in that key's
   usage ledger on the owner's Keys page (a rejected or publishable key
   can't be attributed, so it reaches only the request log); refusals also
@@ -408,6 +435,92 @@ contents.
                           verifySession or the dashboard, never a name
       invalid_body        one malformed field (token, expiresAt, reason)
                           — the message names which one and what it needs
+      invalid_email       invitePerson: must look like name@domain
+      invite_capped       invitePerson: 500 invite calls per app per day (a
+                          fetch of an existing person counts) — the message
+                          says where to write; resetAt says when
+- Relays — route, map, authorise, never compute.
+  What it is: a rule in one JSON file — when this happens, Gemmein does
+  these things, keeps a row per event, retries, and shows every run in the
+  owner's dashboard with a replay button. A relay takes a verified signal
+  and closes a circuit: GoCardless says paid, the relay opens access,
+  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 · 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); 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 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
+  person or open access; something should run on a clock and write a
+  record or ping your URL.
+  Not when: the work computes or reshapes data (that is your function);
+  one event should email many people (a broadcast, planned); a schedule
+  must address a person (not yet); you already use Stripe for the money —
+  the built-in Stripe path already grants access and writes receipts, and
+  a relay adds nothing there.
+  The GoCardless case end to end — a payment confirms, the payer gets Pro,
+  an email, and your function hears about it. The file is
+  `gemmein/relays/<name>.json`; the owner's dashboard shows it read-only
+  (Setup → Relays) with its receiver URL, its secrets (shown once), every
+  event with each action's result, and a replay button:
+
+      {
+        "name": "gocardless-paid",
+        "trigger": {
+          "kind": "receiver",
+          "verify": { "scheme": "hmac_sha256_header", "header": "Webhook-Signature" },
+          "map": {
+            "event_id": "events.0.id",
+            "event_type": "events.0.action",
+            "person_email": "events.0.details.customer_email"
+          },
+          "when": { "event_type": "confirmed" }
+        },
+        "actions": [
+          { "type": "grant_access", "entitlement": "Pro", "reason": "GoCardless payment {{mapped.event_id}}" },
+          { "type": "email_person", "subject": "Your payment is confirmed", "text": "Thanks. Pro is open on your account." },
+          { "type": "call_url", "url": "https://hooks.example.com/paid" }
+        ]
+      }
+
+  Triggers (exactly one per relay):
+  - receiver — a provider's signed webhook at `POST /hooks/<appId>/<name>`;
+    `verify` names the scheme (hmac_sha256_header | stripe | svix |
+    shared_token), `map` names dotted paths into the body (`event_id`
+    dedupes, `person_email` resolves the person, the rest ride as
+    `{{mapped.<name>}}`), `when` is an exact match on mapped fields.
+  - schedule — `every` 15m | 30m | 1h | 6h | 12h | 1d, `at: "HH:MM"` UTC
+    with 1d; one tick per period; no person, so person actions are refused.
+  - data_change — `collection`, `on` ⊆ created | updated | deleted, optional
+    `where` on the record's data; never for the runner's own writes.
+    Authorise on fields the signed-in user cannot set, or from a receiver.
+  Actions (1 to 10, run in order, each idempotent per event):
+  - write_record { collection, data, to?: "person" } — keyed per event.
+  - 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.
+  Full depth — every verify scheme, the map and when grammar, the call_url
+  contract and signature, every refusal code, the limits and both rails:
+  https://docs.gemmein.com/relays (the same chapter is REFERENCE.md
+  "## Relays", which the MCP `reference` tool serves).
 - Linking records (author on a post, product on an order): store the other
   record's id in a field (`authorProfileId: profile.id`) — in collections
   users write (community, shared, direct) the server learns it's a link;
@@ -572,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
@@ -637,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
@@ -683,7 +911,14 @@ contents.
   moderation and status flips on other users' records; scoping a secret
   key to collections and actions; verifying the sending and receiving
   domain; usage and logs; the Inbox, where every notify() send is a
-  conversation and customer replies land; holding the billing band. None
+  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, 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
   of them has an SDK equivalent, so an owner screen you build for one is
   a page that already exists, without the enforcement.
 - Secret keys (`sk_`) must never appear in browser code; app keys (`pk_`)

package/migrations/README.md

@@ -0,0 +1,35 @@
+# Migration notes — @gemmein/sdk
+
+One file per behaviour change that may ask something of an app already
+built on the SDK. `CHANGELOG.md` says what changed in each version; a note
+here says what, if anything, your app has to do about it, and by when.
+
+## Format
+
+Each note is a Markdown file named for the change (`list-limit-refusal.md`),
+and opens with two header lines:
+
+```
+Since: <version>                  — the SDK version the change arrived in
+Action required by: <version>     — the version by which an app must have
+                                    acted, or "none" when nothing is required
+```
+
+Then, in this order:
+
+1. **What changed** — the old behaviour and the new one, as facts.
+2. **Who is affected** — the call shapes that see a difference. An app that
+   never made those calls can stop reading.
+3. **What to do** — the smallest change that keeps the app correct, with
+   the code.
+4. **How to tell** — how the change shows up at runtime (the error code,
+   the message) so it can be recognised in logs.
+
+A note is never edited after the version it names ships; a later change to
+the same surface gets its own file.
+
+## Notes
+
+| File | Since | Action required by |
+|------|-------|--------------------|
+| [`list-limit-refusal.md`](./list-limit-refusal.md) | 0.6.0 | 0.6.0 |

package/migrations/list-limit-refusal.md

@@ -0,0 +1,42 @@
+# `list({ limit })` over 100 is refused
+
+```
+Since: 0.6.0
+Action required by: 0.6.0
+```
+
+## What changed
+
+Before 0.6.0 the server clamped a list `limit` above 100 to 100 and
+answered a normal page (`hasMore: true`). From 0.6.0 a `limit` outside 1..100
+is refused: the call throws `GemmeinError` with code `invalid_limit` and the
+message "limit must be between 1 and 100". The default (no `limit`) is 25 and
+the maximum is 100, as before. The same applies on the local engine
+(`gemmein dev`) from 0.7.0 — it runs the same server code.
+
+## Who is affected
+
+Apps that call `collection.list({ limit: N })` with `N > 100`, `N < 1`, or a
+non-integer `N`, on either the browser client or `gemmeinServer(sk)`.
+`watch()` is unaffected (it asks for 100). An app that passes no `limit`, or
+1..100, sees no difference.
+
+## What to do
+
+Ask for at most 100 and page with `cursor`:
+
+```ts
+const all = [];
+let cursor: string | undefined;
+do {
+  const page = await g.collection("orders").list({ limit: 100, cursor });
+  all.push(...page.records);
+  cursor = page.hasMore ? page.cursor : undefined;
+} while (cursor);
+```
+
+## How to tell
+
+A 400 with `code: "invalid_limit"` in the response, `err.code ===
+"invalid_limit"` in the SDK, and the row `invalid_limit` under the key's
+refusals on the Keys page when a secret key made the call.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gemmein/sdk",
-  "version": "0.5.0",
-  "description": "Gemmein SDK — passwordless auth, safe storage, and Stripe-driven record flips for AI-built apps. Small enough that one prompt teaches the whole API.",
+  "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",
   "main": "./dist/index.cjs",
@@ -22,11 +22,13 @@
     "dist",
     "llms.txt",
     "REFERENCE.md",
+    "CHANGELOG.md",
+    "migrations",
     "reaffirm.mjs"
   ],
   "sideEffects": false,
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "keywords": [
     "auth",
@@ -45,6 +47,8 @@
     "access": "public"
   },
   "scripts": {
+    "version:sync": "node scripts/sync-version.mjs",
+    "prebuild": "node scripts/sync-version.mjs",
     "build": "rm -rf dist && tsc -p tsconfig.build.json && tsc -p tsconfig.cjs.json && mv dist/cjs/index.js dist/index.cjs && rm -rf dist/cjs && cp dist/index.d.ts dist/index.d.cts",
     "prepack": "npm run build",
     "prepublishOnly": "npm run build"