@gemmein/sdk 0.3.0 → 0.3.2

package/dist/index.cjs

@@ -242,8 +242,13 @@ exports.PurchasesClient = PurchasesClient;
  * are, what the collection's rule says, whether the file is yours, and whether
  * you still hold whatever the collection requires.
  *
- * That is why the same app code keeps working when a collection later changes
- * from public to private — and why a refund actually takes a download away.
+ * That is why the same app code keeps working across collections, and why a
+ * refund takes away a download the buyer had not yet resolved. Two honest
+ * bounds: an already-issued link keeps working until it expires (minutes),
+ * and a file uploaded while its collection was public keeps its permanent
+ * URL even if the rule is later tightened — new uploads seal, old ones are
+ * moved only by an owner reseal. Sell access with the rule set from the
+ * start, not tightened afterwards.
  *
  * Don't store what this returns. Store the reference and call this again.
  */

package/dist/index.d.cts

@@ -242,8 +242,13 @@ export type FileRef = string & {
  * are, what the collection's rule says, whether the file is yours, and whether
  * you still hold whatever the collection requires.
  *
- * That is why the same app code keeps working when a collection later changes
- * from public to private — and why a refund actually takes a download away.
+ * That is why the same app code keeps working across collections, and why a
+ * refund takes away a download the buyer had not yet resolved. Two honest
+ * bounds: an already-issued link keeps working until it expires (minutes),
+ * and a file uploaded while its collection was public keeps its permanent
+ * URL even if the rule is later tightened — new uploads seal, old ones are
+ * moved only by an owner reseal. Sell access with the rule set from the
+ * start, not tightened afterwards.
  *
  * Don't store what this returns. Store the reference and call this again.
  */

package/dist/index.d.ts

@@ -242,8 +242,13 @@ export type FileRef = string & {
  * are, what the collection's rule says, whether the file is yours, and whether
  * you still hold whatever the collection requires.
  *
- * That is why the same app code keeps working when a collection later changes
- * from public to private — and why a refund actually takes a download away.
+ * That is why the same app code keeps working across collections, and why a
+ * refund takes away a download the buyer had not yet resolved. Two honest
+ * bounds: an already-issued link keeps working until it expires (minutes),
+ * and a file uploaded while its collection was public keeps its permanent
+ * URL even if the rule is later tightened — new uploads seal, old ones are
+ * moved only by an owner reseal. Sell access with the rule set from the
+ * start, not tightened afterwards.
  *
  * Don't store what this returns. Store the reference and call this again.
  */

package/dist/index.js

@@ -231,8 +231,13 @@ export class PurchasesClient {
  * are, what the collection's rule says, whether the file is yours, and whether
  * you still hold whatever the collection requires.
  *
- * That is why the same app code keeps working when a collection later changes
- * from public to private — and why a refund actually takes a download away.
+ * That is why the same app code keeps working across collections, and why a
+ * refund takes away a download the buyer had not yet resolved. Two honest
+ * bounds: an already-issued link keeps working until it expires (minutes),
+ * and a file uploaded while its collection was public keeps its permanent
+ * URL even if the rule is later tightened — new uploads seal, old ones are
+ * moved only by an owner reseal. Sell access with the rule set from the
+ * start, not tightened afterwards.
  *
  * Don't store what this returns. Store the reference and call this again.
  */

package/llms.txt

@@ -185,28 +185,47 @@
   arriving out of order resolve to the newest. The app reads
   `await g.subscriptions.mine()` → `{ plan, status }` or null, and gates features
   with `sub?.plan === "pro"`.
-- Selling THINGS (one-off purchases — a poster, a beat, an ebook): plans are
-  for subscriptions; products are for things. The builder adds products
-  (name + Stripe Payment Link) on the same Payments page and picks a
-  receipts collection (rule `addressed`). The app calls
-  `await g.payments.buy("poster")` — or, when one product covers many items (license
+- Paid ACCESS (entitlements): a collection can require a key — your human
+  sets `requires: "access:pro"` in the "Unlocked by" row on its Collections
+  card — and the engine refuses customers without it, under all seven
+  rules. (Server secret keys and the owner's console are exempt by design;
+  link/expand silently hide gated records rather than naming them.) Keys
+  are granted by money: a plan or product lists what it unlocks (e.g.
+  `access:pro, access:exports`), the paid webhook grants those keys, and a
+  FULL refund or a cancellation revokes exactly what it granted — nothing
+  else. A partial refund leaves access in place.
+  Owners also grant and revoke by hand (trials, comps, support). Effective
+  access is the UNION of a customer's live grants. A signed-in customer
+  without the key gets `403 entitlement_required` naming it — show your
+  upgrade screen and send them to checkout; never retry. 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, NO usage limits, NO seats — access is yes-or-no by design.
+- Selling THINGS (one-off purchases — a beat, an ebook, a course; DIGITAL
+  access only — physical goods, shipping, inventory and carts are out of
+  scope, said out loud): plans are for subscriptions; products are for
+  things. The builder adds products (name + Stripe Payment Link) on the
+  same Payments page. The app calls
+  `await g.payments.buy("beat")` — or, when one product covers many items (license
   tiers over a catalog), names the item:
-  `await g.payments.buy("premium license", { item: "beat_37" })` (display text on
-  the receipt; the PRICE always comes from the product's Payment Link, so
-  the item note can never change what's paid). The completed payment writes
-  a receipt record ADDRESSED to the buyer: only they and the owner read it.
-  Gate downloads/fulfilment on the receipt, never on the redirect coming
-  back — redirects can be faked, receipts come from Stripe's signed
-  webhook. Receipts carry
-  { product, item?, status: "paid"|"refunded", amountTotal (minor units,
-  as Stripe said), currency, paidAt, deliveryUrl?, paymentRef } — deliveryUrl appears
-  when the builder attached a delivery link to the product (that's how
-  digital goods deliver themselves; never put a secret download URL in a
-  public collection). Fulfilment status changes ("shipped") are the owner
-  editing the receipt in their dashboard; your app just re-reads it.
-  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.
+  `await g.payments.buy("premium license", { item: "beat_37" })` (display text
+  only; the PRICE always comes from the product's Payment Link, so the
+  item note can never change what's paid). Gemmein records every completed
+  payment itself — `await g.purchases.mine()` is the buyer's proof:
+  { item, kind, status: "paid"|"part_refunded"|"refunded", amountMinor,
+  currency, refundedMinor, grants, paidAt }. A receipts collection (rule
+  `addressed`) is OPTIONAL for proof — but TODAY it is REQUIRED for file
+  delivery: the file reference only reaches the buyer on the receipt
+  record (its `deliveryFile` field, a `file:` ref — resolve it per reader
+  with `g.files.link`, which re-checks access on every mint). Selling a
+  file? Configure a receipts collection, or the buyer has no way to reach
+  their download. External `deliveryUrl` is a plain handover: Gemmein
+  controls who is TOLD, not who can use it. Gate fulfilment on
+  the purchase or the entitlement it granted, never on the redirect coming
+  back — redirects can be faked; the record comes from Stripe's signed
+  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.
 - 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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gemmein/sdk",
-  "version": "0.3.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.",
+  "version": "0.3.2",
+  "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.",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.cjs",