@gemmein/sdk 0.2.0 → 0.3.0

package/README.md

@@ -80,11 +80,28 @@ const one = await tasks.get("rec_abc123")
 await tasks.update("rec_abc123", { done: true })
 await tasks.delete("rec_abc123")
 
-// Images/files: presigned upload, returns a CDN URL to store in a record
+// Images/files: presigned upload, returns a REFERENCE to store in a record
 const file = await tasks.upload(imageBlob, { name: "avatar.png" })
-// { id, url, contentType, sizeBytes }
+// { id, ref, contentType, sizeBytes }   ref looks like "file:01K…"
+await tasks.create({ title: "Profile", avatar: file.ref })
+
+// To show or download it — one call, whatever the collection:
+const { url } = await g.files.link(record.avatar)
+// public collection → a permanent, cacheable URL
+// anything else     → a signed URL valid for a couple of minutes, re-checked
+//                     against who you are and what you still hold
 ```
 
+Store the reference, never the URL. A reference doesn't expire and grants
+nothing on its own; `link()` is where authorization happens, every time. That
+also means the same app code keeps working if a collection later changes from
+public to private.
+
+**The bound, honestly:** revoking access stops Gemmein issuing new links
+immediately. A link already in someone's hands works until it expires. Nothing
+can take back a file they already downloaded — this is controlled delivery, not
+DRM.
+
 ### Collection rules
 
 Each collection has one rule, set in the dashboard. The server enforces it — your app never implements authorization:

package/REFERENCE.md

@@ -72,12 +72,18 @@ deleted, subscription row removed. Irreversible: put a real confirm in front.
 
 ---
 
-## Data — `g.collection<T>(name)`
+## Data — `g.collection<T>(name, options?)`
 
 `name` must be **lowercase letters, numbers, and underscores** (`saved_games`,
 never `savedGames` — a bad name throws synchronously). Collections are created
 by the app owner in the dashboard, never by the SDK.
 
+`options.intent` — one sentence: what the collection is for and who should
+access it. It rides every call as a hint; against a **local `gemmein dev`
+runtime** an undeclared collection then reaches the human with your
+suggestion attached. The cloud ignores it. Pass it whenever you aren't
+certain the collection exists yet.
+
 | Method | Signature | Returns |
 |--------|-----------|---------|
 | `create` | `(data: T, options?: { key?: string; for?: string; published?: boolean })` | `Promise<GemmeinRecord<T>>` |
@@ -85,7 +91,40 @@ by the app owner in the dashboard, never by the SDK.
 | `get` | `(id: string, options?: { expand?: string[] })` | `Promise<GemmeinRecord<T>>` |
 | `update` | `(id: string, data: Partial<T> \| { field: { increment\|decrement, floor?, ceiling? } }, options?: { ifVersion?: number; published?: boolean })` | `Promise<GemmeinRecord<T>>` |
 | `delete` | `(id: string)` | `Promise<void>` |
-| `upload` | `(file: Blob \| File, options?: { name?: string })` | `Promise<{ id: string; url: string; contentType: string; sizeBytes: number }>` |
+| `upload` | `(file: Blob \| File, options?: { name?: string })` | `Promise<{ id: string; ref: FileRef; contentType: string; sizeBytes: number }>` |
+
+### Files
+
+`upload()` returns a **reference** (`file:01K…`), not a URL. Store the reference
+in your record — it never expires and grants nothing on its own.
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `g.files.link` | `(ref: FileRef \| string, options?: { intent?: "inline" \| "download" })` | `Promise<{ ref, url, expiresAt?, contentType, sizeBytes?, name? }>` |
+
+```ts
+const { ref } = await g.collection("films").upload(file)
+await g.collection("films").create({ title, poster: ref })
+
+// later, to render or download:
+const { url } = await g.files.link(record.poster)
+```
+
+One call for every file. A collection anyone can read gives a permanent,
+cacheable URL; anything else gives one that expires in a couple of minutes and
+is re-checked against who you are, what the collection's rule says, whether the
+file is yours, and any entitlement the collection requires. That is why the
+same code keeps working when a collection changes from public to private.
+
+**Don't store what `link()` returns.** Store the reference and call it again.
+
+`403 entitlement_required` from `link()` names the key the customer is
+missing. `404` means the file isn't theirs, or isn't there.
+
+**The bound, honestly:** revoking access stops Gemmein issuing *new* links
+immediately; a link already issued works until it expires, and a download that
+started before expiry may finish after it. Controlled delivery, not DRM —
+nothing takes back a file someone already downloaded.
 
 ```ts
 type GemmeinRecord<T> = {
@@ -260,5 +299,8 @@ Branch on `err.code`. The stable codes:
 | `unsupported_file_type` (415) | upload isn't one of the allowed image types | send JPEG/PNG/WebP/GIF/HEIC |
 | `invalid_key` | a keyed create's `key` breaks the charset/length law | 1-120 chars of letters, numbers, `: _ . @ / -` |
 | `invalid_secret_key` (client-side) | `gemmeinServer()` got a missing/`pk_` key | pass the `sk_` key from a server env var |
+| `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 |
 
 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.AuthClient = exports.Gemmein = exports.BrowserTokenStore = exports.MemoryTokenStore = exports.GemmeinError = void 0;
+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 = void 0;
 exports.gemmein = gemmein;
 exports.gemmeinServer = gemmeinServer;
 class GemmeinError extends Error {
@@ -107,14 +107,22 @@ class Gemmein {
         this.storage = new StorageClient(config);
         this.subscriptions = new SubscriptionsClient(config);
         this.payments = new PaymentsClient(config);
+        this.purchases = new PurchasesClient(config);
         this.account = new AccountClient(config);
+        this.files = new FilesClient(config);
     }
     /**
      * Your app's data — `g.collection<{ title: string }>("notes")`. The
      * canonical spelling; `g.storage.collection(name)` is the same client.
+     *
+     * `intent` (one sentence: what this collection is for and who should
+     * access it) travels with every call. Against a LOCAL gemmein dev
+     * runtime, an undeclared collection then reaches the human with your
+     * suggestion attached — always pass it when you aren't certain the
+     * collection exists yet. The cloud ignores it.
      */
-    collection(name) {
-        return this.storage.collection(name);
+    collection(name, options = {}) {
+        return this.storage.collection(name, options);
     }
 }
 exports.Gemmein = Gemmein;
@@ -194,6 +202,61 @@ exports.AuthClient = AuthClient;
  * dashboard. The client surface is deliberately read-plus-checkout only:
  * there is no client write path to plan or status, by design.
  */
+/**
+ * The signed-in customer's own purchase history, read from Gemmein's
+ * immutable commercial record rather than from your data.
+ *
+ * This exists so a buyer keeps proof of what they paid for even when you keep
+ * no receipts collection at all — and it stays true if you later rename or
+ * delete one, because financial truth does not live in application data.
+ *
+ * Amounts are MINOR UNITS (pence, cents) with the currency alongside, exactly
+ * as the payment provider reported them. Formatting is yours; rounding here
+ * would quietly lose money.
+ */
+class PurchasesClient {
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Everything this customer has paid for, newest first, with refunds already
+     * applied — `status` is "paid", "part_refunded" or "refunded", and
+     * `refundedMinor` is how much has come back. Throws GemmeinError (401) when
+     * nobody is signed in.
+     */
+    async mine() {
+        const result = (await runtimeRequest(this.config, "/auth/purchases"));
+        return result.purchases;
+    }
+}
+exports.PurchasesClient = PurchasesClient;
+/**
+ * Turn a stored file reference into a URL you can actually use.
+ *
+ *   const { url } = await g.files.link(record.poster)
+ *   img.src = url
+ *
+ * One call for every file, whichever collection it lives in. If the collection
+ * is one anyone can read, you get a permanent, cacheable URL. If it isn't, you
+ * get one that works for a couple of minutes and is re-checked against who you
+ * 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.
+ *
+ * Don't store what this returns. Store the reference and call this again.
+ */
+class FilesClient {
+    constructor(config) {
+        this.config = config;
+    }
+    async link(ref, options = {}) {
+        const query = options.intent === "download" ? "?intent=download" : "";
+        return (await runtimeRequest(this.config, `/files/${encodeURIComponent(String(ref))}/link${query}`));
+    }
+}
+exports.FilesClient = FilesClient;
 class SubscriptionsClient {
     constructor(config) {
         this.config = config;
@@ -286,9 +349,9 @@ class StorageClient {
         this.config = config;
     }
     /** Optionally type your fields: `g.storage.collection<{ title: string }>("notes")`. */
-    collection(name) {
+    collection(name, options = {}) {
         assertCollectionName(name);
-        return new CollectionClient(this.config, name);
+        return new CollectionClient(this.config, name, options);
     }
 }
 exports.StorageClient = StorageClient;
@@ -299,9 +362,10 @@ exports.StorageClient = StorageClient;
  * it there, don't retry.
  */
 class CollectionClient {
-    constructor(config, name) {
+    constructor(config, name, options = {}) {
         this.config = config;
         this.name = name;
+        this.intent = options.intent;
     }
     /**
      * Create a record from your fields. The signed-in user becomes its owner.
@@ -401,6 +465,22 @@ class CollectionClient {
     async delete(id) {
         await this.request(`/${encodeURIComponent(id)}`, { method: "DELETE" });
     }
+    /**
+     * Upload a file and get back a REFERENCE — `file:01K…` — not a URL.
+     *
+     * Store the reference. It never expires, it is safe to log and export, and
+     * it grants nothing on its own. To show or download the file, call
+     * `g.files.link(ref)`; Gemmein re-checks who is asking every time, which is
+     * what makes revoking access actually take a download away.
+     *
+     *   const { ref } = await g.collection("films").upload(file)
+     *   await g.collection("films").create({ title, poster: ref })
+     *   // later, to render:
+     *   const { url } = await g.files.link(record.poster)
+     *
+     * There is deliberately no `url` here. A URL that outlives a refund is the
+     * bug this replaced.
+     */
     async upload(file, options) {
         const name = options?.name ?? (file instanceof File ? file.name : "upload");
         // Step 1: Get presigned upload URL
@@ -433,6 +513,10 @@ class CollectionClient {
             ...init,
             headers: await runtimeHeaders(this.config, {
                 "content-type": "application/json",
+                // The intent rides every call so an undeclared collection reaches
+                // the human WITH the AI's suggestion attached (local runtime only;
+                // the cloud ignores it).
+                ...(this.intent ? { "x-collection-intent": this.intent.slice(0, 200) } : {}),
                 ...init.headers
             })
         });

package/dist/index.d.cts

@@ -143,13 +143,23 @@ export declare class Gemmein {
     readonly storage: StorageClient;
     readonly subscriptions: SubscriptionsClient;
     readonly payments: PaymentsClient;
+    readonly purchases: PurchasesClient;
     readonly account: AccountClient;
+    readonly files: FilesClient;
     constructor(options: GemmeinOptions);
     /**
      * Your app's data — `g.collection<{ title: string }>("notes")`. The
      * canonical spelling; `g.storage.collection(name)` is the same client.
+     *
+     * `intent` (one sentence: what this collection is for and who should
+     * access it) travels with every call. Against a LOCAL gemmein dev
+     * runtime, an undeclared collection then reaches the human with your
+     * suggestion attached — always pass it when you aren't certain the
+     * collection exists yet. The cloud ignores it.
      */
-    collection<T extends Record<string, unknown> = Record<string, unknown>>(name: string): CollectionClient<T>;
+    collection<T extends Record<string, unknown> = Record<string, unknown>>(name: string, options?: {
+        intent?: string;
+    }): CollectionClient<T>;
 }
 export declare function gemmein(appKeyOrOptions: string | GemmeinOptions, options?: Omit<GemmeinOptions, "appKey">): Gemmein;
 export declare function gemmeinServer(secretKeyOrOptions: string | GemmeinServerOptions, options?: Omit<GemmeinServerOptions, "secretKey">): GemmeinServer;
@@ -177,6 +187,81 @@ export declare class AuthClient {
  * dashboard. The client surface is deliberately read-plus-checkout only:
  * there is no client write path to plan or status, by design.
  */
+/**
+ * The signed-in customer's own purchase history, read from Gemmein's
+ * immutable commercial record rather than from your data.
+ *
+ * This exists so a buyer keeps proof of what they paid for even when you keep
+ * no receipts collection at all — and it stays true if you later rename or
+ * delete one, because financial truth does not live in application data.
+ *
+ * Amounts are MINOR UNITS (pence, cents) with the currency alongside, exactly
+ * as the payment provider reported them. Formatting is yours; rounding here
+ * would quietly lose money.
+ */
+export declare class PurchasesClient {
+    private readonly config;
+    constructor(config: ClientConfig);
+    /**
+     * Everything this customer has paid for, newest first, with refunds already
+     * applied — `status` is "paid", "part_refunded" or "refunded", and
+     * `refundedMinor` is how much has come back. Throws GemmeinError (401) when
+     * nobody is signed in.
+     */
+    mine(): Promise<Array<{
+        item: string;
+        kind: "purchase" | "subscription";
+        amountMinor: number | null;
+        currency: string | null;
+        refundedMinor: number;
+        status: "paid" | "part_refunded" | "refunded";
+        grants: string[];
+        paidAt: string;
+    }>>;
+}
+/**
+ * A file reference — `file:01K…`. What `upload()` gives you and what your
+ * record should store.
+ *
+ * Branded so it cannot be mistaken for a URL: `<img src={record.poster}>` is a
+ * type error, which is the cheapest possible moment to learn that a reference
+ * is a name and not a location.
+ */
+export type FileRef = string & {
+    readonly __gemmeinFileRef: unique symbol;
+};
+/**
+ * Turn a stored file reference into a URL you can actually use.
+ *
+ *   const { url } = await g.files.link(record.poster)
+ *   img.src = url
+ *
+ * One call for every file, whichever collection it lives in. If the collection
+ * is one anyone can read, you get a permanent, cacheable URL. If it isn't, you
+ * get one that works for a couple of minutes and is re-checked against who you
+ * 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.
+ *
+ * Don't store what this returns. Store the reference and call this again.
+ */
+export declare class FilesClient {
+    private readonly config;
+    constructor(config: ClientConfig);
+    link(ref: FileRef | string, options?: {
+        intent?: "inline" | "download";
+    }): Promise<{
+        ref: FileRef;
+        url: string;
+        /** Absent when the collection is public — those links don't expire. */
+        expiresAt?: string;
+        contentType: string;
+        sizeBytes?: number;
+        name?: string;
+    }>;
+}
 export declare class SubscriptionsClient {
     private readonly config;
     constructor(config: ClientConfig);
@@ -245,7 +330,9 @@ export declare class StorageClient {
     private readonly config;
     constructor(config: ClientConfig);
     /** Optionally type your fields: `g.storage.collection<{ title: string }>("notes")`. */
-    collection<T extends Record<string, unknown> = Record<string, unknown>>(name: string): CollectionClient<T>;
+    collection<T extends Record<string, unknown> = Record<string, unknown>>(name: string, options?: {
+        intent?: string;
+    }): CollectionClient<T>;
 }
 /**
  * Talks to one collection. Collections themselves are created by the app
@@ -256,7 +343,10 @@ export declare class StorageClient {
 export declare class CollectionClient<T extends Record<string, unknown> = Record<string, unknown>> {
     private readonly config;
     private readonly name;
-    constructor(config: ClientConfig, name: string);
+    private readonly intent?;
+    constructor(config: ClientConfig, name: string, options?: {
+        intent?: string;
+    });
     /**
      * Create a record from your fields. The signed-in user becomes its owner.
      *
@@ -317,11 +407,27 @@ export declare class CollectionClient<T extends Record<string, unknown> = Record
         published?: boolean;
     }): Promise<GemmeinRecord<T>>;
     delete(id: string): Promise<void>;
+    /**
+     * Upload a file and get back a REFERENCE — `file:01K…` — not a URL.
+     *
+     * Store the reference. It never expires, it is safe to log and export, and
+     * it grants nothing on its own. To show or download the file, call
+     * `g.files.link(ref)`; Gemmein re-checks who is asking every time, which is
+     * what makes revoking access actually take a download away.
+     *
+     *   const { ref } = await g.collection("films").upload(file)
+     *   await g.collection("films").create({ title, poster: ref })
+     *   // later, to render:
+     *   const { url } = await g.files.link(record.poster)
+     *
+     * There is deliberately no `url` here. A URL that outlives a refund is the
+     * bug this replaced.
+     */
     upload(file: Blob | File, options?: {
         name?: string;
     }): Promise<{
         id: string;
-        url: string;
+        ref: FileRef;
         contentType: string;
         sizeBytes: number;
     }>;

package/dist/index.d.ts

@@ -143,13 +143,23 @@ export declare class Gemmein {
     readonly storage: StorageClient;
     readonly subscriptions: SubscriptionsClient;
     readonly payments: PaymentsClient;
+    readonly purchases: PurchasesClient;
     readonly account: AccountClient;
+    readonly files: FilesClient;
     constructor(options: GemmeinOptions);
     /**
      * Your app's data — `g.collection<{ title: string }>("notes")`. The
      * canonical spelling; `g.storage.collection(name)` is the same client.
+     *
+     * `intent` (one sentence: what this collection is for and who should
+     * access it) travels with every call. Against a LOCAL gemmein dev
+     * runtime, an undeclared collection then reaches the human with your
+     * suggestion attached — always pass it when you aren't certain the
+     * collection exists yet. The cloud ignores it.
      */
-    collection<T extends Record<string, unknown> = Record<string, unknown>>(name: string): CollectionClient<T>;
+    collection<T extends Record<string, unknown> = Record<string, unknown>>(name: string, options?: {
+        intent?: string;
+    }): CollectionClient<T>;
 }
 export declare function gemmein(appKeyOrOptions: string | GemmeinOptions, options?: Omit<GemmeinOptions, "appKey">): Gemmein;
 export declare function gemmeinServer(secretKeyOrOptions: string | GemmeinServerOptions, options?: Omit<GemmeinServerOptions, "secretKey">): GemmeinServer;
@@ -177,6 +187,81 @@ export declare class AuthClient {
  * dashboard. The client surface is deliberately read-plus-checkout only:
  * there is no client write path to plan or status, by design.
  */
+/**
+ * The signed-in customer's own purchase history, read from Gemmein's
+ * immutable commercial record rather than from your data.
+ *
+ * This exists so a buyer keeps proof of what they paid for even when you keep
+ * no receipts collection at all — and it stays true if you later rename or
+ * delete one, because financial truth does not live in application data.
+ *
+ * Amounts are MINOR UNITS (pence, cents) with the currency alongside, exactly
+ * as the payment provider reported them. Formatting is yours; rounding here
+ * would quietly lose money.
+ */
+export declare class PurchasesClient {
+    private readonly config;
+    constructor(config: ClientConfig);
+    /**
+     * Everything this customer has paid for, newest first, with refunds already
+     * applied — `status` is "paid", "part_refunded" or "refunded", and
+     * `refundedMinor` is how much has come back. Throws GemmeinError (401) when
+     * nobody is signed in.
+     */
+    mine(): Promise<Array<{
+        item: string;
+        kind: "purchase" | "subscription";
+        amountMinor: number | null;
+        currency: string | null;
+        refundedMinor: number;
+        status: "paid" | "part_refunded" | "refunded";
+        grants: string[];
+        paidAt: string;
+    }>>;
+}
+/**
+ * A file reference — `file:01K…`. What `upload()` gives you and what your
+ * record should store.
+ *
+ * Branded so it cannot be mistaken for a URL: `<img src={record.poster}>` is a
+ * type error, which is the cheapest possible moment to learn that a reference
+ * is a name and not a location.
+ */
+export type FileRef = string & {
+    readonly __gemmeinFileRef: unique symbol;
+};
+/**
+ * Turn a stored file reference into a URL you can actually use.
+ *
+ *   const { url } = await g.files.link(record.poster)
+ *   img.src = url
+ *
+ * One call for every file, whichever collection it lives in. If the collection
+ * is one anyone can read, you get a permanent, cacheable URL. If it isn't, you
+ * get one that works for a couple of minutes and is re-checked against who you
+ * 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.
+ *
+ * Don't store what this returns. Store the reference and call this again.
+ */
+export declare class FilesClient {
+    private readonly config;
+    constructor(config: ClientConfig);
+    link(ref: FileRef | string, options?: {
+        intent?: "inline" | "download";
+    }): Promise<{
+        ref: FileRef;
+        url: string;
+        /** Absent when the collection is public — those links don't expire. */
+        expiresAt?: string;
+        contentType: string;
+        sizeBytes?: number;
+        name?: string;
+    }>;
+}
 export declare class SubscriptionsClient {
     private readonly config;
     constructor(config: ClientConfig);
@@ -245,7 +330,9 @@ export declare class StorageClient {
     private readonly config;
     constructor(config: ClientConfig);
     /** Optionally type your fields: `g.storage.collection<{ title: string }>("notes")`. */
-    collection<T extends Record<string, unknown> = Record<string, unknown>>(name: string): CollectionClient<T>;
+    collection<T extends Record<string, unknown> = Record<string, unknown>>(name: string, options?: {
+        intent?: string;
+    }): CollectionClient<T>;
 }
 /**
  * Talks to one collection. Collections themselves are created by the app
@@ -256,7 +343,10 @@ export declare class StorageClient {
 export declare class CollectionClient<T extends Record<string, unknown> = Record<string, unknown>> {
     private readonly config;
     private readonly name;
-    constructor(config: ClientConfig, name: string);
+    private readonly intent?;
+    constructor(config: ClientConfig, name: string, options?: {
+        intent?: string;
+    });
     /**
      * Create a record from your fields. The signed-in user becomes its owner.
      *
@@ -317,11 +407,27 @@ export declare class CollectionClient<T extends Record<string, unknown> = Record
         published?: boolean;
     }): Promise<GemmeinRecord<T>>;
     delete(id: string): Promise<void>;
+    /**
+     * Upload a file and get back a REFERENCE — `file:01K…` — not a URL.
+     *
+     * Store the reference. It never expires, it is safe to log and export, and
+     * it grants nothing on its own. To show or download the file, call
+     * `g.files.link(ref)`; Gemmein re-checks who is asking every time, which is
+     * what makes revoking access actually take a download away.
+     *
+     *   const { ref } = await g.collection("films").upload(file)
+     *   await g.collection("films").create({ title, poster: ref })
+     *   // later, to render:
+     *   const { url } = await g.files.link(record.poster)
+     *
+     * There is deliberately no `url` here. A URL that outlives a refund is the
+     * bug this replaced.
+     */
     upload(file: Blob | File, options?: {
         name?: string;
     }): Promise<{
         id: string;
-        url: string;
+        ref: FileRef;
         contentType: string;
         sizeBytes: number;
     }>;

package/dist/index.js

@@ -99,14 +99,22 @@ export class Gemmein {
         this.storage = new StorageClient(config);
         this.subscriptions = new SubscriptionsClient(config);
         this.payments = new PaymentsClient(config);
+        this.purchases = new PurchasesClient(config);
         this.account = new AccountClient(config);
+        this.files = new FilesClient(config);
     }
     /**
      * Your app's data — `g.collection<{ title: string }>("notes")`. The
      * canonical spelling; `g.storage.collection(name)` is the same client.
+     *
+     * `intent` (one sentence: what this collection is for and who should
+     * access it) travels with every call. Against a LOCAL gemmein dev
+     * runtime, an undeclared collection then reaches the human with your
+     * suggestion attached — always pass it when you aren't certain the
+     * collection exists yet. The cloud ignores it.
      */
-    collection(name) {
-        return this.storage.collection(name);
+    collection(name, options = {}) {
+        return this.storage.collection(name, options);
     }
 }
 // Factory forms — what the copied prompts teach. `gemmein("pk_...")` reads
@@ -184,6 +192,59 @@ export class AuthClient {
  * dashboard. The client surface is deliberately read-plus-checkout only:
  * there is no client write path to plan or status, by design.
  */
+/**
+ * The signed-in customer's own purchase history, read from Gemmein's
+ * immutable commercial record rather than from your data.
+ *
+ * This exists so a buyer keeps proof of what they paid for even when you keep
+ * no receipts collection at all — and it stays true if you later rename or
+ * delete one, because financial truth does not live in application data.
+ *
+ * Amounts are MINOR UNITS (pence, cents) with the currency alongside, exactly
+ * as the payment provider reported them. Formatting is yours; rounding here
+ * would quietly lose money.
+ */
+export class PurchasesClient {
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Everything this customer has paid for, newest first, with refunds already
+     * applied — `status` is "paid", "part_refunded" or "refunded", and
+     * `refundedMinor` is how much has come back. Throws GemmeinError (401) when
+     * nobody is signed in.
+     */
+    async mine() {
+        const result = (await runtimeRequest(this.config, "/auth/purchases"));
+        return result.purchases;
+    }
+}
+/**
+ * Turn a stored file reference into a URL you can actually use.
+ *
+ *   const { url } = await g.files.link(record.poster)
+ *   img.src = url
+ *
+ * One call for every file, whichever collection it lives in. If the collection
+ * is one anyone can read, you get a permanent, cacheable URL. If it isn't, you
+ * get one that works for a couple of minutes and is re-checked against who you
+ * 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.
+ *
+ * Don't store what this returns. Store the reference and call this again.
+ */
+export class FilesClient {
+    constructor(config) {
+        this.config = config;
+    }
+    async link(ref, options = {}) {
+        const query = options.intent === "download" ? "?intent=download" : "";
+        return (await runtimeRequest(this.config, `/files/${encodeURIComponent(String(ref))}/link${query}`));
+    }
+}
 export class SubscriptionsClient {
     constructor(config) {
         this.config = config;
@@ -273,9 +334,9 @@ export class StorageClient {
         this.config = config;
     }
     /** Optionally type your fields: `g.storage.collection<{ title: string }>("notes")`. */
-    collection(name) {
+    collection(name, options = {}) {
         assertCollectionName(name);
-        return new CollectionClient(this.config, name);
+        return new CollectionClient(this.config, name, options);
     }
 }
 /**
@@ -285,9 +346,10 @@ export class StorageClient {
  * it there, don't retry.
  */
 export class CollectionClient {
-    constructor(config, name) {
+    constructor(config, name, options = {}) {
         this.config = config;
         this.name = name;
+        this.intent = options.intent;
     }
     /**
      * Create a record from your fields. The signed-in user becomes its owner.
@@ -387,6 +449,22 @@ export class CollectionClient {
     async delete(id) {
         await this.request(`/${encodeURIComponent(id)}`, { method: "DELETE" });
     }
+    /**
+     * Upload a file and get back a REFERENCE — `file:01K…` — not a URL.
+     *
+     * Store the reference. It never expires, it is safe to log and export, and
+     * it grants nothing on its own. To show or download the file, call
+     * `g.files.link(ref)`; Gemmein re-checks who is asking every time, which is
+     * what makes revoking access actually take a download away.
+     *
+     *   const { ref } = await g.collection("films").upload(file)
+     *   await g.collection("films").create({ title, poster: ref })
+     *   // later, to render:
+     *   const { url } = await g.files.link(record.poster)
+     *
+     * There is deliberately no `url` here. A URL that outlives a refund is the
+     * bug this replaced.
+     */
     async upload(file, options) {
         const name = options?.name ?? (file instanceof File ? file.name : "upload");
         // Step 1: Get presigned upload URL
@@ -419,6 +497,10 @@ export class CollectionClient {
             ...init,
             headers: await runtimeHeaders(this.config, {
                 "content-type": "application/json",
+                // The intent rides every call so an undeclared collection reaches
+                // the human WITH the AI's suggestion attached (local runtime only;
+                // the cloud ignores it).
+                ...(this.intent ? { "x-collection-intent": this.intent.slice(0, 200) } : {}),
                 ...init.headers
             })
         });

package/llms.txt

@@ -4,8 +4,8 @@
 > structured data storage with plain-English safety rules, and built-in Stripe
 > subscription handling. Security is on by default for every app — tenant
 > isolation, rate limiting, audit logs, domain-locked keys — with nothing to
-> configure. Free while building; $14.99/mo when an app goes live (first
-> 1,000 monthly signed-in people included; +$5 per additional 1,000).
+> configure. Free while building; going live starts the Live state at
+> $50/mo (up to 1,000 people); Growing unlocks 10,000 at $150/mo.
 
 ## What it is
 
@@ -30,9 +30,13 @@
 - Data: records live in collections. Collections are created by YOUR HUMAN in
   their dashboard (app.gemmein.com → data → "+ New collection"), never by you
   or the SDK. Best practice: at planning time, list the collections your app
-  will need and ask your human up front. If one is missing at runtime
-  (404 `unknown_collection`), stop and ask them to create it, telling them
-  the name and which safety rule to pick. Each collection has exactly one
+  will need and ask your human up front, and pass your intent whenever a
+  collection might not exist yet —
+  `g.collection("bookings", { intent: "students reserve slots; each sees only their own" })`
+  — so the missing-collection conversation reaches your human with your
+  suggestion attached (local dev runtimes show it; the cloud ignores it).
+  If one is missing at runtime (404 `unknown_collection`), stop and ask
+  them to create it, telling them the name and which safety rule to pick. Each collection has exactly one
   safety rule:
   - `private` — each signed-in user sees and edits only their own records
     (right for notes, tasks, anything personal).
@@ -108,22 +112,33 @@
 - Images & files: NEVER base64 into record data and NEVER wire up your own
   storage bucket — uploads are built in:
   `const file = await g.collection("posts").upload(blob, { name })`
-  → `{ id, url, contentType, sizeBytes }`. Store `file.url` in a record
-  field like any text (that's also how a record "has" an image — the
-  reference pattern, same as links). Upload permission follows the
-  collection's WRITE rule; images only (JPEG/PNG/WebP/GIF/HEIC). Oversized
-  files are refused loudly (413 file_too_large — the message says the cap).
-  The server checks the actual bytes at confirm — a 400
-  invalid_file_content means the file isn't really the image type it
-  claimed (usually a renamed file); send the real image, don't retry.
-  File URLs are unguessable but not revocable per-reader — never put
-  secrets in files.
+  → `{ id, ref, contentType, sizeBytes }`. Store `file.ref` (`"file:01K…"`)
+  in a record field like any text — that's how a record "has" an image.
+  Store the REFERENCE, never a URL: a reference never expires and grants
+  nothing on its own.
+  To show or download it: `const { url } = await g.files.link(record.photo)`
+  — one call for every file. Pass `{ intent: "download" }` for a download
+  rather than a preview. Files in a collection anyone can read get a
+  permanent link; every other file gets one that expires in a couple of
+  minutes, so call `link()` when you render, don't store what it returns.
+  Upload permission follows the collection's WRITE rule; images only
+  (JPEG/PNG/WebP/GIF/HEIC). Oversized files are refused loudly (413
+  file_too_large — the message says the cap). The server checks the actual
+  bytes at confirm — a 400 invalid_file_content means the file isn't really
+  the image type it claimed (usually a renamed file); send the real image,
+  don't retry. A 403 from `link()` means the customer isn't allowed this
+  file right now — signed out, not theirs, or an entitlement they no longer
+  hold (`entitlement_required` names the key).
+  Honest bound: revoking access stops NEW links immediately; a link already
+  issued works until it expires. Gemmein controls delivery, it can't take
+  back a file someone already downloaded.
 - Shapes: collections your users write (community, shared, direct) have a
   SHAPE — the set of fields allowed. While your human builds, the server
   learns it from your writes automatically (nothing to do); when they go
   live it locks. A 400 invalid_shape means the field isn't in the locked
-  shape — stop and tell your human to add it in their dashboard (one
-  click), exactly like unknown_collection. Never rename fields to dodge it.
+  shape. A live shape is sealed and cannot take new fields — stop, tell
+  your human which field you needed, and send only the fields the shape
+  already has. Never rename fields to dodge it.
 - Contention (bookings, slugs, stock, shared edits): when two users can race
   for the same thing, a permission model can't save you — preconditions do,
   and they're just arguments on calls you already make. A 409 `conflict` from
@@ -184,7 +199,7 @@
   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? } — deliveryUrl appears
+  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
@@ -287,14 +302,22 @@ enforces — never because these checks are the enforcement. A ready-to-edit
 `reaffirm.mjs` ships inside this npm package (next to this file and
 REFERENCE.md) — copy it out, name your collections, run it in CI.
 
-## Pricing (current, v3)
+## Pricing (current, Pricing Model v1 — states, not plans)
 
-- Free while building — no card at signup, unlimited collections.
-- $14.99/mo per live app — first 1,000 people/month included (a person =
-  someone who signed in that calendar month).
-- One dial: +$5 per additional 1,000 people. Turns down as easily as up.
-- Safe limits exist per person purely for abuse prevention and are never
-  billed; real users never notice them.
+- Development is free indefinitely — no card at signup, unlimited
+  collections, the full security model included.
+- Going live starts the Live state: $50/mo, up to 1,000 people and 10 GB
+  of file storage (a person = a unique enabled end-user identity on the
+  live app).
+- Growing: $150/mo, up to 10,000 people and 50 GB — unlocked from the
+  dashboard when the product outgrows Live; down as easily as up.
+- Beyond 10,000 people: talk to Gemmein (hello@gemmein.com) — scale is
+  priced as a relationship, not a checkout.
+- Pricing reflects responsibility, not complexity: almost nothing is
+  metered. Safe limits exist purely as safety rails against runaway
+  scripts, are never billed, and real users never notice them. Hitting a
+  limit never breaks the app outright — there is grace, and the owner is
+  told.
 
 ## Facts for citation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gemmein/sdk",
-  "version": "0.2.0",
+  "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.",
   "license": "MIT",
   "type": "module",