@gemmein/sdk 0.0.1 → 0.1.0

package/dist/index.js

@@ -0,0 +1,553 @@
+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();
+}
+export class Gemmein {
+    constructor(options) {
+        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);
+    }
+    /** 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);
+    }
+    /**
+     * 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.
+     */
+    pay(product, options) {
+        return this.auth.pay(product, options);
+    }
+}
+// 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 deleteAccount() {
+        const result = await this.request("/auth/delete-account", { method: "POST" });
+        await this.config.tokenStore.clear();
+        return result;
+    }
+    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"));
+        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
+     * 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 this.request(`/auth/checkout${query}`));
+        if (typeof window !== "undefined" && window.location) {
+            window.location.assign(result.url);
+        }
+        return result;
+    }
+    /**
+     * 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.
+     */
+    async pay(product, options) {
+        const params = new URLSearchParams({ product });
+        if (options?.item)
+            params.set("item", options.item);
+        const result = (await this.request(`/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");
+    }
+    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);
+    }
+}
+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) {
+        if (options.secretKey.startsWith("pk_")) {
+            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"
+            });
+        }
+        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}`
+    };
+}
+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}"`
+        });
+    }
+}