@gemmein/sdk 0.0.1 → 0.2.0

package/dist/index.js

@@ -0,0 +1,611 @@
+export class GemmeinError extends Error {
+    constructor(input) {
+        super(input.message);
+        this.name = "GemmeinError";
+        this.status = input.status;
+        this.code = input.code;
+        this.resetAt = input.resetAt;
+    }
+}
+export class MemoryTokenStore {
+    get() {
+        return this.token;
+    }
+    set(token) {
+        this.token = token;
+    }
+    clear() {
+        this.token = undefined;
+    }
+}
+// Persists the session across page reloads — the default in browsers.
+// Sessions are long-lived server-side; a memory-only default would log
+// users out on every refresh. Keyed per app key so two Gemmein apps on
+// one origin never share a token. All storage access is guarded: private
+// modes and blocked storage degrade to "signed out", never to a crash.
+export class BrowserTokenStore {
+    constructor(appKey) {
+        this.key = `gemmein_session_${appKey.slice(0, 20)}`;
+    }
+    get() {
+        try {
+            return window.localStorage.getItem(this.key) ?? undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    set(token) {
+        try {
+            window.localStorage.setItem(this.key, token);
+        }
+        catch { /* storage blocked — session lives for this page only */ }
+    }
+    clear() {
+        try {
+            window.localStorage.removeItem(this.key);
+        }
+        catch { /* nothing to clear */ }
+    }
+}
+function defaultTokenStore(appKey) {
+    try {
+        if (typeof window !== "undefined" && window.localStorage)
+            return new BrowserTokenStore(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) {
+        // 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",
+                message: "Secret keys (sk_) must not be used in the client SDK — use gemmeinServer() instead"
+            });
+        }
+        // The signpost: an AI building without a key gets routed, not stuck.
+        if (!options?.appKey || !options.appKey.startsWith("pk_")) {
+            throw new GemmeinError({
+                status: 0,
+                code: "missing_app_key",
+                message: 'Gemmein needs your app key (it starts with "pk_"). Get one in 30 seconds: ' +
+                    "sign in at https://app.gemmein.com with an email code (free, no card) and " +
+                    'copy the key from the Setup page. Then: gemmein("pk_...")'
+            });
+        }
+        const config = {
+            apiUrl: options.apiUrl ?? "https://api.gemmein.com",
+            appKey: options.appKey,
+            tokenStore: options.tokenStore ?? defaultTokenStore(options.appKey)
+        };
+        this.auth = new AuthClient(config);
+        this.storage = new StorageClient(config);
+        this.subscriptions = new SubscriptionsClient(config);
+        this.payments = new PaymentsClient(config);
+        this.account = new AccountClient(config);
+    }
+    /**
+     * Your app's data — `g.collection<{ title: string }>("notes")`. The
+     * canonical spelling; `g.storage.collection(name)` is the same client.
+     */
+    collection(name) {
+        return this.storage.collection(name);
+    }
+}
+// Factory forms — what the copied prompts teach. `gemmein("pk_...")` reads
+// better in an AI prompt than a class instantiation, and both accept an
+// options object when more than a key is needed.
+// ROUND-8 FIND: `gemmein(key, { apiUrl })` is the call shape people (and
+// AIs) write naturally — silently dropping the second argument misrouted a
+// local app to production. Both forms are now first-class.
+export function gemmein(appKeyOrOptions, options) {
+    return new Gemmein(typeof appKeyOrOptions === "string"
+        ? { appKey: appKeyOrOptions, ...(options ?? {}) }
+        : appKeyOrOptions);
+}
+export function gemmeinServer(secretKeyOrOptions, options) {
+    return new GemmeinServer(typeof secretKeyOrOptions === "string"
+        ? { secretKey: secretKeyOrOptions, ...(options ?? {}) }
+        : secretKeyOrOptions);
+}
+export class AuthClient {
+    constructor(config) {
+        this.config = config;
+    }
+    async sendEmailCode(email) {
+        await this.request("/auth/email/start", {
+            method: "POST",
+            body: JSON.stringify({ email }),
+            headers: { "content-type": "application/json" }
+        });
+    }
+    async verifyEmailCode(input) {
+        const result = await this.request("/auth/email/verify", {
+            method: "POST",
+            body: JSON.stringify(input),
+            headers: { "content-type": "application/json" }
+        });
+        if (isSessionResponse(result)) {
+            await this.config.tokenStore.set(result.token);
+            return result;
+        }
+        throw new Error("Gemmein auth response did not include a session token");
+    }
+    async logout() {
+        try {
+            await this.request("/auth/logout", { method: "POST" });
+        }
+        finally {
+            // Even if the network call fails, the user asked to be signed out.
+            await this.config.tokenStore.clear();
+        }
+    }
+    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;
+    }
+    /**
+     * 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;
+    }
+    /**
+     * 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
+     * and a plan whose Payment Link the app owner has pasted in their
+     * dashboard; omit `plan` to buy the app's paid plan.
+     */
+    async checkout(plan) {
+        const query = plan ? `?plan=${encodeURIComponent(plan)}` : "";
+        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;
+    }
+    /**
+     * 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 buy(product, options) {
+        const params = new URLSearchParams({ product });
+        if (options?.item)
+            params.set("item", options.item);
+        const result = (await runtimeRequest(this.config, `/auth/pay?${params.toString()}`));
+        if (typeof window !== "undefined" && window.location) {
+            window.location.assign(result.url);
+        }
+        return result;
+    }
+}
+/** The signed-in user's own account — self-service, one deliberate power. */
+export class AccountClient {
+    constructor(config) {
+        this.config = 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) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "token" in value &&
+        typeof value.token === "string");
+}
+export class StorageClient {
+    constructor(config) {
+        this.config = config;
+    }
+    /** Optionally type your fields: `g.storage.collection<{ title: string }>("notes")`. */
+    collection(name) {
+        assertCollectionName(name);
+        return new CollectionClient(this.config, name);
+    }
+}
+/**
+ * Talks to one collection. Collections themselves are created by the app
+ * owner in their dashboard (app.gemmein.com → data) — a 404
+ * `unknown_collection` means it doesn't exist yet: ask the owner to create
+ * it there, don't retry.
+ */
+export class CollectionClient {
+    constructor(config, name) {
+        this.config = config;
+        this.name = name;
+    }
+    /**
+     * Create a record from your fields. The signed-in user becomes its owner.
+     *
+     * For anything two users can race for (a booking slot, a unique slug, a
+     * limited drop), pass a deterministic `key` derived from the thing that
+     * must be unique: `create(data, { key: "slot:2026-07-15T15:00" })`.
+     * The second writer gets a 409 GemmeinError `conflict` — that error IS
+     * the booking system working: catch it and tell the user it's taken.
+     * Your own retry with the same key returns the record you already made
+     * (`existing: true`) instead of a duplicate. Deleting a keyed record
+     * frees its key.
+     *
+     * On `addressed` and `direct` collections every create names its
+     * recipient: `create(data, { for: userId })` — the server stamps it,
+     * and only that user (plus the sender/owner) will ever read the record.
+     * Sending to a non-user is a 400 `invalid_audience`; a 403 `reply_only`
+     * means this collection only allows replies to people who wrote to you
+     * first — tell the user, don't retry.
+     *
+     * On the PUBLIC rules (public_read, community) pass `{ published: false }`
+     * to save a DRAFT the public can't see (the author still sees their own;
+     * the owner sees all). Publish later with
+     * `update(id, {}, { published: true })`. This is server-enforced — never
+     * fake drafts with a data field + client-side filtering: on a public
+     * collection the data still reaches everyone.
+     */
+    async create(data, options = {}) {
+        const query = new URLSearchParams();
+        if (options.key !== undefined)
+            query.set("key", options.key);
+        if (options.for !== undefined)
+            query.set("for", options.for);
+        if (options.published !== undefined)
+            query.set("published", String(options.published));
+        const qs = query.toString();
+        return this.request(qs ? `?${qs}` : "", {
+            method: "POST",
+            body: JSON.stringify(data)
+        });
+    }
+    /**
+     * List records this user is allowed to see under the collection's safety
+     * rule (the app owner sees everyone's). Returns `{ records, hasMore }` —
+     * an object, not a bare array.
+     */
+    async list(options = {}) {
+        const query = new URLSearchParams();
+        if (options.limit !== undefined)
+            query.set("limit", String(options.limit));
+        if (options.sort)
+            query.set("sort", options.sort);
+        if (options.where)
+            query.set("where", JSON.stringify(options.where));
+        if (options.cursor)
+            query.set("cursor", options.cursor);
+        if (options.search)
+            query.set("search", options.search);
+        if (options.expand && options.expand.length > 0)
+            query.set("expand", options.expand.join(","));
+        // NOT query.size — absent on Node <19.8 / older browsers, where
+        // `undefined > 0` would silently drop every filter.
+        const qs = query.toString();
+        return this.request(qs ? `?${qs}` : "");
+    }
+    async get(id, options = {}) {
+        const qs = options.expand && options.expand.length > 0 ? `?expand=${encodeURIComponent(options.expand.join(","))}` : "";
+        return this.request(`/${encodeURIComponent(id)}${qs}`);
+    }
+    /**
+     * Merge-updates `data` fields; returns the full updated record.
+     *
+     * Counters that users race for (stock, seats) must never be computed
+     * client-side — put an atomic op in value position and the server does
+     * the math on current state: `update(id, { stock: { decrement: 1,
+     * floor: 0 } })`. Breaching the floor/ceiling → 409 `conflict` ("out of
+     * stock" — the limit working, not a bug). An object is treated as an op
+     * ONLY when its keys are exactly increment|decrement (+ optional
+     * floor|ceiling), all numbers.
+     *
+     * When different people can edit the same record (CMS pages, shared
+     * docs), pass `{ ifVersion: record.version }` — a stale save gets a 409
+     * `conflict` instead of clobbering; re-read, reapply, retry.
+     */
+    async update(id, data, options = {}) {
+        const query = new URLSearchParams();
+        if (options.ifVersion !== undefined)
+            query.set("ifVersion", String(options.ifVersion));
+        if (options.published !== undefined)
+            query.set("published", String(options.published));
+        const qs = query.toString();
+        return this.request(`/${encodeURIComponent(id)}${qs ? `?${qs}` : ""}`, {
+            method: "PATCH",
+            body: JSON.stringify(data)
+        });
+    }
+    async delete(id) {
+        await this.request(`/${encodeURIComponent(id)}`, { method: "DELETE" });
+    }
+    async upload(file, options) {
+        const name = options?.name ?? (file instanceof File ? file.name : "upload");
+        // Step 1: Get presigned upload URL
+        const presign = await this.request("/upload", {
+            method: "POST",
+            body: JSON.stringify({ name, size: file.size, contentType: file.type }),
+        });
+        // Step 2: Upload directly to S3 via presigned POST
+        const form = new FormData();
+        for (const [key, value] of Object.entries(presign.fields)) {
+            form.append(key, value);
+        }
+        form.append("file", file); // Must be last — S3 presigned POST requirement
+        const s3Response = await fetch(presign.uploadUrl, { method: "POST", body: form });
+        if (!s3Response.ok) {
+            throw new GemmeinError({
+                status: s3Response.status,
+                code: "upload_failed",
+                message: `Upload failed: ${s3Response.status}`,
+            });
+        }
+        // Step 3: Confirm upload
+        const confirmed = await this.request(`/upload/${encodeURIComponent(presign.fileId)}/confirm`, {
+            method: "POST",
+        });
+        return confirmed;
+    }
+    async request(suffix, init = {}) {
+        const response = await fetch(new URL(`/storage/${encodeURIComponent(this.name)}${suffix}`, this.config.apiUrl), {
+            ...init,
+            headers: await runtimeHeaders(this.config, {
+                "content-type": "application/json",
+                ...init.headers
+            })
+        });
+        return handleResponse(response, this.config);
+    }
+}
+export class GemmeinServer {
+    constructor(options) {
+        // 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: 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";
+        this.secretKey = options.secretKey;
+    }
+    collection(name) {
+        assertCollectionName(name);
+        return new ServerCollectionClient(this.apiUrl, this.secretKey, name);
+    }
+    /**
+     * Mint a member session for a test email WITHOUT an OTP round-trip — so a CI
+     * self-test ("reaffirm") can sign in as N test users and prove your app's
+     * isolation boundaries hold (user B genuinely can't read user A's private
+     * records). DEV ENVIRONMENTS ONLY: throws `test_session_forbidden_live` on an
+     * `sk_live` key, and the server refuses it too. Never ship this in app code.
+     * Pass the returned `token` to `gemmein(pk, { tokenStore })` to act as that user.
+     */
+    async testSession(email) {
+        if (this.secretKey.startsWith("sk_live")) {
+            throw new GemmeinError({
+                status: 0,
+                code: "test_session_forbidden_live",
+                message: "test sessions are only available in a development environment — never with a live (sk_live) key",
+            });
+        }
+        const response = await fetch(new URL("/server/test-session", this.apiUrl), {
+            method: "POST",
+            headers: { "x-app-key": this.secretKey, "content-type": "application/json" },
+            body: JSON.stringify({ email }),
+        });
+        if (!response.ok) {
+            const body = await response.json().catch(() => ({ code: "request_failed", message: `Request failed: ${response.status}` }));
+            throw new GemmeinError({
+                status: response.status,
+                code: body.code ?? "request_failed",
+                message: body.message ?? `Request failed: ${response.status}`,
+            });
+        }
+        return response.json();
+    }
+}
+class ServerCollectionClient {
+    constructor(apiUrl, secretKey, name) {
+        this.apiUrl = apiUrl;
+        this.secretKey = secretKey;
+        this.name = name;
+    }
+    async get(id) {
+        return this.request(`/${encodeURIComponent(id)}`);
+    }
+    async list(options = {}) {
+        const query = new URLSearchParams();
+        if (options.limit !== undefined)
+            query.set("limit", String(options.limit));
+        if (options.sort)
+            query.set("sort", options.sort);
+        if (options.where)
+            query.set("where", JSON.stringify(options.where));
+        if (options.cursor)
+            query.set("cursor", options.cursor);
+        if (options.search)
+            query.set("search", options.search);
+        if (options.expand && options.expand.length > 0)
+            query.set("expand", options.expand.join(","));
+        // NOT query.size — absent on Node <19.8 / older browsers, where
+        // `undefined > 0` would silently drop every filter.
+        const qs = query.toString();
+        return this.request(qs ? `?${qs}` : "");
+    }
+    async update(id, data) {
+        return this.request(`/${encodeURIComponent(id)}`, {
+            method: "PATCH",
+            body: JSON.stringify(data),
+        });
+    }
+    async request(suffix, init = {}) {
+        const headers = {
+            "x-app-key": this.secretKey,
+        };
+        if (init.body) {
+            headers["content-type"] = "application/json";
+        }
+        const response = await fetch(new URL(`/storage/${encodeURIComponent(this.name)}${suffix}`, this.apiUrl), { ...init, headers });
+        if (response.status === 204)
+            return undefined;
+        if (!response.ok) {
+            const body = await response.json().catch(() => ({ code: "request_failed", message: `Request failed: ${response.status}` }));
+            throw new GemmeinError({
+                status: response.status,
+                code: body.code ?? "request_failed",
+                message: body.message ?? `Request failed: ${response.status}`,
+            });
+        }
+        return response.json();
+    }
+}
+async function handleResponse(response, config) {
+    if (response.status === 204)
+        return undefined;
+    if (!response.ok) {
+        const errorBody = await readErrorBody(response);
+        if (errorBody.code === "auth_expired") {
+            await config.tokenStore.clear();
+        }
+        // Signpost: a wrong/revoked key routes the builder (or their AI) to
+        // where a working key comes from, instead of dead-ending.
+        if (errorBody.code === "invalid_app_key" || errorBody.code === "missing_app_key") {
+            errorBody.message += " — get your app key from the Setup page at https://app.gemmein.com (sign in with an email code, free, no card)";
+        }
+        throw new GemmeinError({
+            status: response.status,
+            code: errorBody.code,
+            message: errorBody.message,
+            resetAt: errorBody.resetAt
+        });
+    }
+    return response.json();
+}
+async function readErrorBody(response) {
+    try {
+        const value = await response.json();
+        if (typeof value === "object" && value !== null) {
+            const code = typeof value.code === "string"
+                ? value.code
+                : typeof value.error === "string"
+                    ? value.error
+                    : "request_failed";
+            return {
+                code,
+                message: typeof value.message === "string"
+                    ? value.message
+                    : `Gemmein request failed: ${response.status}`,
+                resetAt: typeof value.resetAt === "string"
+                    ? value.resetAt
+                    : undefined
+            };
+        }
+    }
+    catch {
+        // Fall through to a stable typed error.
+    }
+    return {
+        code: "request_failed",
+        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 {
+        ...headers,
+        "x-app-key": config.appKey,
+        ...(token ? { authorization: `Bearer ${token}` } : {})
+    };
+}
+const COLLECTION_NAME_RE = /^[a-z][a-z0-9_]{1,62}$/;
+function assertCollectionName(name) {
+    if (!COLLECTION_NAME_RE.test(name)) {
+        throw new GemmeinError({
+            status: 0,
+            code: "invalid_collection_name",
+            message: `Collection name must be lowercase letters, numbers, and underscores (e.g. "tasks", "user_notes"). Got: "${name}"`
+        });
+    }
+}