@gemmein/sdk 0.2.0 → 0.2.1

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>>` |
@@ -260,5 +266,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

@@ -112,9 +112,15 @@ class Gemmein {
     /**
      * 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;
@@ -286,9 +292,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 +305,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.
@@ -433,6 +440,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

@@ -148,8 +148,16 @@ export declare class Gemmein {
     /**
      * 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;
@@ -245,7 +253,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 +266,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.
      *

package/dist/index.d.ts

@@ -148,8 +148,16 @@ export declare class Gemmein {
     /**
      * 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;
@@ -245,7 +253,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 +266,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.
      *

package/dist/index.js

@@ -104,9 +104,15 @@ export class Gemmein {
     /**
      * 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
@@ -273,9 +279,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 +291,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.
@@ -419,6 +426,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).
@@ -184,7 +188,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 +291,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.2.1",
   "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",