@gemmein/sdk 0.2.1 → 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

@@ -91,7 +91,40 @@ certain the collection exists yet.
 | `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> = {

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,7 +107,9 @@ 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
@@ -200,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;
@@ -408,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

package/dist/index.d.cts

@@ -143,7 +143,9 @@ 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
@@ -185,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);
@@ -330,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,7 +143,9 @@ 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
@@ -185,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);
@@ -330,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,7 +99,9 @@ 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
@@ -190,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;
@@ -394,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

package/llms.txt

@@ -112,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gemmein/sdk",
-  "version": "0.2.1",
+  "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",