@gemmein/sdk 0.1.0 → 0.2.1

package/dist/index.d.cts

@@ -125,34 +125,39 @@ export declare class BrowserTokenStore implements TokenStore {
     set(token: string): void;
     clear(): void;
 }
+/**
+ * The client — two layers:
+ *
+ *  - `g.collection("notes")` — YOUR app's collections. Records, files,
+ *    safety rules. This is where your app's own data model lives.
+ *  - Business primitives Gemmein runs for you: `g.auth` (sign-in),
+ *    `g.subscriptions` (who's on which plan), `g.payments` (one-off
+ *    purchases), `g.account` (the user's own account). These are
+ *    SELF-SERVICE surfaces for the signed-in user — reads and Stripe
+ *    hand-offs, never admin powers. Managing other people's users,
+ *    subscriptions, or records happens in the owner's dashboard
+ *    (app.gemmein.com), on purpose.
+ */
 export declare class Gemmein {
     readonly auth: AuthClient;
     readonly storage: StorageClient;
+    readonly subscriptions: SubscriptionsClient;
+    readonly payments: PaymentsClient;
+    readonly account: AccountClient;
     constructor(options: GemmeinOptions);
-    /** The signed-in user's subscription — `(await g.subscription())?.plan === "pro"`. */
-    subscription(): Promise<{
-        plan: string;
-        status: "active" | "cancelled";
-    } | null>;
-    /** Send the signed-in user to Stripe checkout for a plan — `g.checkout("pro")`. Redirects in browsers. */
-    checkout(plan?: string): Promise<{
-        url: string;
-        plan: string;
-    }>;
     /**
-     * Buy a one-off product — `g.pay("poster")`. Redirects in browsers. NOT
-     * for plans/subscriptions (that's `g.checkout`). The optional `item` note
-     * names WHAT is being bought when one product covers many things (e.g. a
-     * license tier across a catalog): `g.pay("premium license", { item: "beat_37" })`
-     * — it lands on the buyer's receipt record for the owner to fulfil.
+     * 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.
      */
-    pay(product: string, options?: {
-        item?: string;
-    }): Promise<{
-        url: string;
-        product: string;
-        item?: string;
-    }>;
+    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;
@@ -170,14 +175,33 @@ export declare class AuthClient {
         code: string;
     }): Promise<AuthSession>;
     logout(): Promise<void>;
-    deleteAccount(): Promise<unknown>;
-    subscription(): Promise<{
+    currentUser(): Promise<CurrentUser>;
+    private request;
+}
+/**
+ * SUBS: the subscription primitive, self-service side. Gemmein keeps
+ * exactly one subscription per customer — created by the payment itself,
+ * updated by Stripe's signed webhooks, overridable by the owner in their
+ * dashboard. The client surface is deliberately read-plus-checkout only:
+ * there is no client write path to plan or status, by design.
+ */
+export declare class SubscriptionsClient {
+    private readonly config;
+    constructor(config: ClientConfig);
+    /**
+     * The signed-in user's subscription — gate features with
+     * `(await g.subscriptions.mine())?.plan === "pro"`. Null when payments
+     * are off or this user has never paid; throws GemmeinError (401) when
+     * nobody is signed in — a data route, not the never-throw current-user
+     * contract.
+     */
+    mine(): Promise<{
         plan: string;
         status: "active" | "cancelled";
     } | null>;
     /**
-     * SUBS-2: start a Stripe checkout for a plan — Gemmein mints the URL with
-     * the signed-in buyer and the plan already wired in (never build checkout
+     * Start a Stripe checkout for a plan — Gemmein mints the URL with the
+     * signed-in buyer and the plan already wired in (never build checkout
      * URLs yourself; raw emails get silently dropped by Stripe's URL rules).
      * In a browser this redirects immediately; it also resolves with the URL
      * (for non-browser callers or custom handling). Requires a signed-in user
@@ -188,27 +212,50 @@ export declare class AuthClient {
         url: string;
         plan: string;
     }>;
+}
+/** The one-off purchase primitive — things, not plans (plans are `g.subscriptions`). */
+export declare class PaymentsClient {
+    private readonly config;
+    constructor(config: ClientConfig);
     /**
-     * PAY-1: buy a one-off product — same contract as checkout() but for
-     * things, not plans. A completed payment writes a receipt record addressed
-     * to the buyer in the owner's receipts collection; gate downloads/fulfilment
-     * on that receipt, never on the redirect coming back.
+     * Buy a one-off product — `g.payments.buy("poster")`. Redirects in
+     * browsers, and resolves with the URL. The optional `item` note names
+     * WHAT is being bought when one product covers many things (e.g. a
+     * license tier across a catalog):
+     * `g.payments.buy("premium license", { item: "beat_37" })`.
+     * A completed payment writes a receipt record addressed to the buyer in
+     * the owner's receipts collection; gate downloads/fulfilment on that
+     * receipt, never on the redirect coming back.
      */
-    pay(product: string, options?: {
+    buy(product: string, options?: {
         item?: string;
     }): Promise<{
         url: string;
         product: string;
         item?: string;
     }>;
-    currentUser(): Promise<CurrentUser>;
-    private request;
+}
+/** The signed-in user's own account — self-service, one deliberate power. */
+export declare class AccountClient {
+    private readonly config;
+    constructor(config: ClientConfig);
+    /**
+     * Self-service erasure — the "delete my account" screen. Every app it
+     * APPLIES to needs one (GDPR right to erasure; Apple 5.1.1(v) requires it
+     * for any app with account creation). Server-side this is the full
+     * cascade: sessions revoked, the user's records and files deleted, their
+     * subscription row removed. Irreversible — put a real confirm in front
+     * of it.
+     */
+    delete(): Promise<unknown>;
 }
 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
@@ -219,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

@@ -125,34 +125,39 @@ export declare class BrowserTokenStore implements TokenStore {
     set(token: string): void;
     clear(): void;
 }
+/**
+ * The client — two layers:
+ *
+ *  - `g.collection("notes")` — YOUR app's collections. Records, files,
+ *    safety rules. This is where your app's own data model lives.
+ *  - Business primitives Gemmein runs for you: `g.auth` (sign-in),
+ *    `g.subscriptions` (who's on which plan), `g.payments` (one-off
+ *    purchases), `g.account` (the user's own account). These are
+ *    SELF-SERVICE surfaces for the signed-in user — reads and Stripe
+ *    hand-offs, never admin powers. Managing other people's users,
+ *    subscriptions, or records happens in the owner's dashboard
+ *    (app.gemmein.com), on purpose.
+ */
 export declare class Gemmein {
     readonly auth: AuthClient;
     readonly storage: StorageClient;
+    readonly subscriptions: SubscriptionsClient;
+    readonly payments: PaymentsClient;
+    readonly account: AccountClient;
     constructor(options: GemmeinOptions);
-    /** The signed-in user's subscription — `(await g.subscription())?.plan === "pro"`. */
-    subscription(): Promise<{
-        plan: string;
-        status: "active" | "cancelled";
-    } | null>;
-    /** Send the signed-in user to Stripe checkout for a plan — `g.checkout("pro")`. Redirects in browsers. */
-    checkout(plan?: string): Promise<{
-        url: string;
-        plan: string;
-    }>;
     /**
-     * Buy a one-off product — `g.pay("poster")`. Redirects in browsers. NOT
-     * for plans/subscriptions (that's `g.checkout`). The optional `item` note
-     * names WHAT is being bought when one product covers many things (e.g. a
-     * license tier across a catalog): `g.pay("premium license", { item: "beat_37" })`
-     * — it lands on the buyer's receipt record for the owner to fulfil.
+     * 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.
      */
-    pay(product: string, options?: {
-        item?: string;
-    }): Promise<{
-        url: string;
-        product: string;
-        item?: string;
-    }>;
+    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;
@@ -170,14 +175,33 @@ export declare class AuthClient {
         code: string;
     }): Promise<AuthSession>;
     logout(): Promise<void>;
-    deleteAccount(): Promise<unknown>;
-    subscription(): Promise<{
+    currentUser(): Promise<CurrentUser>;
+    private request;
+}
+/**
+ * SUBS: the subscription primitive, self-service side. Gemmein keeps
+ * exactly one subscription per customer — created by the payment itself,
+ * updated by Stripe's signed webhooks, overridable by the owner in their
+ * dashboard. The client surface is deliberately read-plus-checkout only:
+ * there is no client write path to plan or status, by design.
+ */
+export declare class SubscriptionsClient {
+    private readonly config;
+    constructor(config: ClientConfig);
+    /**
+     * The signed-in user's subscription — gate features with
+     * `(await g.subscriptions.mine())?.plan === "pro"`. Null when payments
+     * are off or this user has never paid; throws GemmeinError (401) when
+     * nobody is signed in — a data route, not the never-throw current-user
+     * contract.
+     */
+    mine(): Promise<{
         plan: string;
         status: "active" | "cancelled";
     } | null>;
     /**
-     * SUBS-2: start a Stripe checkout for a plan — Gemmein mints the URL with
-     * the signed-in buyer and the plan already wired in (never build checkout
+     * Start a Stripe checkout for a plan — Gemmein mints the URL with the
+     * signed-in buyer and the plan already wired in (never build checkout
      * URLs yourself; raw emails get silently dropped by Stripe's URL rules).
      * In a browser this redirects immediately; it also resolves with the URL
      * (for non-browser callers or custom handling). Requires a signed-in user
@@ -188,27 +212,50 @@ export declare class AuthClient {
         url: string;
         plan: string;
     }>;
+}
+/** The one-off purchase primitive — things, not plans (plans are `g.subscriptions`). */
+export declare class PaymentsClient {
+    private readonly config;
+    constructor(config: ClientConfig);
     /**
-     * PAY-1: buy a one-off product — same contract as checkout() but for
-     * things, not plans. A completed payment writes a receipt record addressed
-     * to the buyer in the owner's receipts collection; gate downloads/fulfilment
-     * on that receipt, never on the redirect coming back.
+     * Buy a one-off product — `g.payments.buy("poster")`. Redirects in
+     * browsers, and resolves with the URL. The optional `item` note names
+     * WHAT is being bought when one product covers many things (e.g. a
+     * license tier across a catalog):
+     * `g.payments.buy("premium license", { item: "beat_37" })`.
+     * A completed payment writes a receipt record addressed to the buyer in
+     * the owner's receipts collection; gate downloads/fulfilment on that
+     * receipt, never on the redirect coming back.
      */
-    pay(product: string, options?: {
+    buy(product: string, options?: {
         item?: string;
     }): Promise<{
         url: string;
         product: string;
         item?: string;
     }>;
-    currentUser(): Promise<CurrentUser>;
-    private request;
+}
+/** The signed-in user's own account — self-service, one deliberate power. */
+export declare class AccountClient {
+    private readonly config;
+    constructor(config: ClientConfig);
+    /**
+     * Self-service erasure — the "delete my account" screen. Every app it
+     * APPLIES to needs one (GDPR right to erasure; Apple 5.1.1(v) requires it
+     * for any app with account creation). Server-side this is the full
+     * cascade: sessions revoked, the user's records and files deleted, their
+     * subscription row removed. Irreversible — put a real confirm in front
+     * of it.
+     */
+    delete(): Promise<unknown>;
 }
 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
@@ -219,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

@@ -56,9 +56,24 @@ function defaultTokenStore(appKey) {
     catch { /* SSR / Node / storage blocked */ }
     return new MemoryTokenStore();
 }
+/**
+ * The client — two layers:
+ *
+ *  - `g.collection("notes")` — YOUR app's collections. Records, files,
+ *    safety rules. This is where your app's own data model lives.
+ *  - Business primitives Gemmein runs for you: `g.auth` (sign-in),
+ *    `g.subscriptions` (who's on which plan), `g.payments` (one-off
+ *    purchases), `g.account` (the user's own account). These are
+ *    SELF-SERVICE surfaces for the signed-in user — reads and Stripe
+ *    hand-offs, never admin powers. Managing other people's users,
+ *    subscriptions, or records happens in the owner's dashboard
+ *    (app.gemmein.com), on purpose.
+ */
 export class Gemmein {
     constructor(options) {
-        if (options.appKey?.startsWith("sk_")) {
+        // A missing key must land on the signpost below, not a TypeError —
+        // gemmein(undefined) is exactly the "env var didn't load" case.
+        if (options?.appKey?.startsWith("sk_")) {
             throw new GemmeinError({
                 status: 0,
                 code: "invalid_app_key",
@@ -66,7 +81,7 @@ export class Gemmein {
             });
         }
         // The signpost: an AI building without a key gets routed, not stuck.
-        if (!options.appKey || !options.appKey.startsWith("pk_")) {
+        if (!options?.appKey || !options.appKey.startsWith("pk_")) {
             throw new GemmeinError({
                 status: 0,
                 code: "missing_app_key",
@@ -82,24 +97,22 @@ export class Gemmein {
         };
         this.auth = new AuthClient(config);
         this.storage = new StorageClient(config);
-    }
-    /** The signed-in user's subscription — `(await g.subscription())?.plan === "pro"`. */
-    subscription() {
-        return this.auth.subscription();
-    }
-    /** Send the signed-in user to Stripe checkout for a plan — `g.checkout("pro")`. Redirects in browsers. */
-    checkout(plan) {
-        return this.auth.checkout(plan);
+        this.subscriptions = new SubscriptionsClient(config);
+        this.payments = new PaymentsClient(config);
+        this.account = new AccountClient(config);
     }
     /**
-     * Buy a one-off product — `g.pay("poster")`. Redirects in browsers. NOT
-     * for plans/subscriptions (that's `g.checkout`). The optional `item` note
-     * names WHAT is being bought when one product covers many things (e.g. a
-     * license tier across a catalog): `g.pay("premium license", { item: "beat_37" })`
-     * — it lands on the buyer's receipt record for the owner to fulfil.
+     * 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.
      */
-    pay(product, options) {
-        return this.auth.pay(product, options);
+    collection(name, options = {}) {
+        return this.storage.collection(name, options);
     }
 }
 // Factory forms — what the copied prompts teach. `gemmein("pk_...")` reads
@@ -150,24 +163,51 @@ export class AuthClient {
             await this.config.tokenStore.clear();
         }
     }
-    async deleteAccount() {
-        const result = await this.request("/auth/delete-account", { method: "POST" });
-        await this.config.tokenStore.clear();
-        return result;
+    async currentUser() {
+        // Contract: "who am I?" never throws for session state — the server
+        // answers 200 {authenticated:false} for a token it won't honour right
+        // now, same as no token. We deliberately do NOT clear the stored token
+        // here: authenticated:false also covers a SUSPENDED user, whose session
+        // is intact and restored on unsuspend — clearing it would make a
+        // reversible suspension permanently sign them out. A genuinely expired
+        // token is harmless to keep (the next data-plane call 401s and the app
+        // re-auths); logout() and g.account.delete() are the deliberate clears.
+        //
+        // Moderation note: authenticated:false is deliberately SILENT about the
+        // why — signed out, suspended, and erased all read the same here, so a
+        // moderated user's state is never leaked to the client. Build the
+        // signed-out screen for all three.
+        return this.request("/auth/current-user");
+    }
+    request(path, init = {}) {
+        return runtimeRequest(this.config, path, init);
+    }
+}
+/**
+ * SUBS: the subscription primitive, self-service side. Gemmein keeps
+ * exactly one subscription per customer — created by the payment itself,
+ * updated by Stripe's signed webhooks, overridable by the owner in their
+ * dashboard. The client surface is deliberately read-plus-checkout only:
+ * there is no client write path to plan or status, by design.
+ */
+export class SubscriptionsClient {
+    constructor(config) {
+        this.config = config;
     }
-    async subscription() {
-        // SUBS-1: Gemmein manages the subscription record — one per customer,
-        // created by the payment itself. Read-only: gate features with
-        // `sub?.plan === "pro"`. Null when payments are off or this user has
-        // never paid; throws GemmeinError (401) when nobody is signed in — a
-        // data route, not the never-throw current-user contract. There is no
-        // client write path, by design.
-        const result = (await this.request("/auth/subscription"));
+    /**
+     * The signed-in user's subscription — gate features with
+     * `(await g.subscriptions.mine())?.plan === "pro"`. Null when payments
+     * are off or this user has never paid; throws GemmeinError (401) when
+     * nobody is signed in — a data route, not the never-throw current-user
+     * contract.
+     */
+    async mine() {
+        const result = (await runtimeRequest(this.config, "/auth/subscription"));
         return result.subscription;
     }
     /**
-     * SUBS-2: start a Stripe checkout for a plan — Gemmein mints the URL with
-     * the signed-in buyer and the plan already wired in (never build checkout
+     * Start a Stripe checkout for a plan — Gemmein mints the URL with the
+     * signed-in buyer and the plan already wired in (never build checkout
      * URLs yourself; raw emails get silently dropped by Stripe's URL rules).
      * In a browser this redirects immediately; it also resolves with the URL
      * (for non-browser callers or custom handling). Requires a signed-in user
@@ -176,45 +216,56 @@ export class AuthClient {
      */
     async checkout(plan) {
         const query = plan ? `?plan=${encodeURIComponent(plan)}` : "";
-        const result = (await this.request(`/auth/checkout${query}`));
+        const result = (await runtimeRequest(this.config, `/auth/checkout${query}`));
         if (typeof window !== "undefined" && window.location) {
             window.location.assign(result.url);
         }
         return result;
     }
+}
+/** The one-off purchase primitive — things, not plans (plans are `g.subscriptions`). */
+export class PaymentsClient {
+    constructor(config) {
+        this.config = config;
+    }
     /**
-     * PAY-1: buy a one-off product — same contract as checkout() but for
-     * things, not plans. A completed payment writes a receipt record addressed
-     * to the buyer in the owner's receipts collection; gate downloads/fulfilment
-     * on that receipt, never on the redirect coming back.
+     * Buy a one-off product — `g.payments.buy("poster")`. Redirects in
+     * browsers, and resolves with the URL. The optional `item` note names
+     * WHAT is being bought when one product covers many things (e.g. a
+     * license tier across a catalog):
+     * `g.payments.buy("premium license", { item: "beat_37" })`.
+     * A completed payment writes a receipt record addressed to the buyer in
+     * the owner's receipts collection; gate downloads/fulfilment on that
+     * receipt, never on the redirect coming back.
      */
-    async pay(product, options) {
+    async buy(product, options) {
         const params = new URLSearchParams({ product });
         if (options?.item)
             params.set("item", options.item);
-        const result = (await this.request(`/auth/pay?${params.toString()}`));
+        const result = (await runtimeRequest(this.config, `/auth/pay?${params.toString()}`));
         if (typeof window !== "undefined" && window.location) {
             window.location.assign(result.url);
         }
         return result;
     }
-    async currentUser() {
-        // Contract: "who am I?" never throws for session state — the server
-        // answers 200 {authenticated:false} for a token it won't honour right
-        // now, same as no token. We deliberately do NOT clear the stored token
-        // here: authenticated:false also covers a SUSPENDED user, whose session
-        // is intact and restored on unsuspend — clearing it would make a
-        // reversible suspension permanently sign them out. A genuinely expired
-        // token is harmless to keep (the next data-plane call 401s and the app
-        // re-auths); logout() and deleteAccount() are the deliberate clears.
-        return this.request("/auth/current-user");
+}
+/** The signed-in user's own account — self-service, one deliberate power. */
+export class AccountClient {
+    constructor(config) {
+        this.config = config;
     }
-    async request(path, init = {}) {
-        const response = await fetch(new URL(path, this.config.apiUrl), {
-            ...init,
-            headers: await runtimeHeaders(this.config, init.headers)
-        });
-        return handleResponse(response, this.config);
+    /**
+     * Self-service erasure — the "delete my account" screen. Every app it
+     * APPLIES to needs one (GDPR right to erasure; Apple 5.1.1(v) requires it
+     * for any app with account creation). Server-side this is the full
+     * cascade: sessions revoked, the user's records and files deleted, their
+     * subscription row removed. Irreversible — put a real confirm in front
+     * of it.
+     */
+    async delete() {
+        const result = await runtimeRequest(this.config, "/auth/delete-account", { method: "POST" });
+        await this.config.tokenStore.clear();
+        return result;
     }
 }
 function isSessionResponse(value) {
@@ -228,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);
     }
 }
 /**
@@ -240,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.
@@ -374,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
             })
         });
@@ -382,11 +438,15 @@ export class CollectionClient {
 }
 export class GemmeinServer {
     constructor(options) {
-        if (options.secretKey.startsWith("pk_")) {
+        // Same signpost law as the client: a missing key (env var didn't load)
+        // must be a typed error, never a TypeError.
+        if (!options?.secretKey || !options.secretKey.startsWith("sk_")) {
             throw new GemmeinError({
                 status: 0,
                 code: "invalid_secret_key",
-                message: "Public keys (pk_) must not be used with GemmeinServer — use the Gemmein client SDK instead"
+                message: options?.secretKey?.startsWith("pk_")
+                    ? "Public keys (pk_) must not be used with GemmeinServer — use the Gemmein client SDK instead"
+                    : 'GemmeinServer needs a secret key (it starts with "sk_") — create one in the dashboard at https://app.gemmein.com and pass it from a server env var'
             });
         }
         this.apiUrl = options.apiUrl ?? "https://api.gemmein.com";
@@ -533,6 +593,15 @@ async function readErrorBody(response) {
         message: `Gemmein request failed: ${response.status}`
     };
 }
+// One request path for every runtime client (auth, subscriptions,
+// payments, account) — same headers, same error handling, same signposts.
+async function runtimeRequest(config, path, init = {}) {
+    const response = await fetch(new URL(path, config.apiUrl), {
+        ...init,
+        headers: await runtimeHeaders(config, init.headers)
+    });
+    return handleResponse(response, config);
+}
 async function runtimeHeaders(config, headers) {
     const token = await config.tokenStore.get();
     return {