@gemmein/sdk 0.0.1 → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,374 @@
+export type GemmeinOptions = {
+    appKey: string;
+    apiUrl?: string;
+    tokenStore?: TokenStore;
+};
+export type TokenStore = {
+    get(): string | undefined | Promise<string | undefined>;
+    set(token: string): void | Promise<void>;
+    clear(): void | Promise<void>;
+};
+/**
+ * A stored record. Your app's fields ALWAYS live under `data`
+ * (`record.data.title`, never `record.title`). Everything else is
+ * server-derived and read-only — never store your own userId/role/owner
+ * fields inside `data`; the server already knows who owns what.
+ */
+export type GemmeinRecord<T extends Record<string, unknown> = Record<string, unknown>> = {
+    id: string;
+    /** Your fields, exactly as you created them. */
+    data: T;
+    createdAt: string;
+    updatedAt: string;
+    /**
+     * Who owns this record — set by the server from the signed-in session.
+     * `null` for app-owned records that no user session created: purchase
+     * receipts (written by the payment webhook), and records the owner adds
+     * from the dashboard without assigning a user. Guard before using it.
+     */
+    ownerUserId: string | null;
+    collectionId: string;
+    appId: string;
+    environmentId: string;
+    /**
+     * Monotonic edit counter (+1 per update). When different people can edit
+     * the same record, pass the version you read back as
+     * `update(id, data, { ifVersion: record.version })` — a stale save gets a
+     * 409 `conflict` instead of silently clobbering someone else's edit.
+     */
+    version: number;
+    /** The create-if-absent key this record was created with, when one was used. */
+    key?: string;
+    /**
+     * The recipient (addressed/direct collections) — set by the server from
+     * the create's `{ for: userId }`, never from data. On addressed
+     * collections users read only records addressed to them; on direct, the
+     * author and the recipient read.
+     */
+    audienceUserId?: string;
+    /**
+     * Draft state on the public rules (public_read, community) — server
+     * column, set via create/update OPTIONS ({ published: false }), never a
+     * data field. Non-authors only ever receive published records, so you'll
+     * only see false on your own drafts (or as the owner).
+     */
+    published: boolean;
+    /** Linked records you asked to expand (`list({ expand: ["authorId"] })`),
+     * per field — only what you could read directly; unreadable or deleted
+     * targets are null (render as "[deleted]"). */
+    expand?: Record<string, GemmeinRecord | null>;
+    /** Present (true) only when a keyed create was YOUR OWN retry — you got the record you already made. */
+    existing?: boolean;
+};
+/** One page of records. When `hasMore` is true, pass `cursor` to `list()` for the next page. */
+export type ListResult<T extends Record<string, unknown> = Record<string, unknown>> = {
+    records: GemmeinRecord<T>[];
+    cursor?: string;
+    hasMore: boolean;
+};
+export type ListOptions = {
+    limit?: number;
+    sort?: "newest" | "oldest" | "updated";
+    /** Exact-match filter on your `data` fields, e.g. `{ done: false }`. */
+    where?: Record<string, unknown>;
+    /** Opaque page cursor from a previous `ListResult`. */
+    cursor?: string;
+    /** Free-text search across your `data` fields. */
+    search?: string;
+    /** SHAPE-1: link fields to embed (up to 3) — each expanded record is only
+     * what YOU could have read directly; unreadable/deleted targets are null. */
+    expand?: string[];
+};
+/**
+ * Answer to "who is signed in right now?". `authenticated: false` simply
+ * means "no one" — this call never throws for session state, so it's safe
+ * unguarded on page load.
+ */
+export type CurrentUser = {
+    authenticated: true;
+    userId: string;
+    email: string;
+} | {
+    authenticated: false;
+    userId?: undefined;
+    email?: undefined;
+};
+export type AuthSession = {
+    token: string;
+    expiresAt: string;
+    user: {
+        id: string;
+        email: string;
+    };
+};
+export declare class GemmeinError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly resetAt?: string;
+    constructor(input: {
+        status: number;
+        code: string;
+        message: string;
+        resetAt?: string;
+    });
+}
+export declare class MemoryTokenStore implements TokenStore {
+    private token?;
+    get(): string | undefined;
+    set(token: string): void;
+    clear(): void;
+}
+export declare class BrowserTokenStore implements TokenStore {
+    private readonly key;
+    constructor(appKey: string);
+    get(): string | undefined;
+    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);
+    /**
+     * Your app's data — `g.collection<{ title: string }>("notes")`. The
+     * canonical spelling; `g.storage.collection(name)` is the same client.
+     */
+    collection<T extends Record<string, unknown> = Record<string, unknown>>(name: 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;
+type ClientConfig = {
+    apiUrl: string;
+    appKey: string;
+    tokenStore: TokenStore;
+};
+export declare class AuthClient {
+    private readonly config;
+    constructor(config: ClientConfig);
+    sendEmailCode(email: string): Promise<void>;
+    verifyEmailCode(input: {
+        email: string;
+        code: string;
+    }): Promise<AuthSession>;
+    logout(): Promise<void>;
+    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>;
+    /**
+     * 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.
+     */
+    checkout(plan?: string): Promise<{
+        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);
+    /**
+     * 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.
+     */
+    buy(product: string, options?: {
+        item?: string;
+    }): Promise<{
+        url: string;
+        product: string;
+        item?: string;
+    }>;
+}
+/** 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>;
+}
+/**
+ * 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 declare class CollectionClient<T extends Record<string, unknown> = Record<string, unknown>> {
+    private readonly config;
+    private readonly name;
+    constructor(config: ClientConfig, name: string);
+    /**
+     * 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.
+     */
+    create(data: T, options?: {
+        key?: string;
+        for?: string;
+        published?: boolean;
+    }): Promise<GemmeinRecord<T>>;
+    /**
+     * 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.
+     */
+    list(options?: ListOptions): Promise<ListResult<T>>;
+    get(id: string, options?: {
+        expand?: string[];
+    }): Promise<GemmeinRecord<T>>;
+    /**
+     * 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.
+     */
+    update(id: string, data: Partial<T> | Record<string, unknown>, options?: {
+        ifVersion?: number;
+        published?: boolean;
+    }): Promise<GemmeinRecord<T>>;
+    delete(id: string): Promise<void>;
+    upload(file: Blob | File, options?: {
+        name?: string;
+    }): Promise<{
+        id: string;
+        url: string;
+        contentType: string;
+        sizeBytes: number;
+    }>;
+    private request;
+}
+export type GemmeinServerOptions = {
+    secretKey: string;
+    apiUrl?: string;
+};
+export declare class GemmeinServer {
+    private readonly apiUrl;
+    private readonly secretKey;
+    constructor(options: GemmeinServerOptions);
+    collection(name: string): ServerCollectionClient;
+    /**
+     * 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.
+     */
+    testSession(email: string): Promise<{
+        token: string;
+        expiresAt: string;
+        user: {
+            id: string;
+            email: string;
+            role: string;
+        };
+    }>;
+}
+declare class ServerCollectionClient {
+    private readonly apiUrl;
+    private readonly secretKey;
+    private readonly name;
+    constructor(apiUrl: string, secretKey: string, name: string);
+    get(id: string): Promise<unknown>;
+    list(options?: {
+        limit?: number;
+        sort?: "newest" | "oldest" | "updated";
+        where?: Record<string, unknown>;
+        cursor?: string;
+        search?: string;
+        expand?: string[];
+    }): Promise<unknown>;
+    update(id: string, data: Record<string, unknown>): Promise<unknown>;
+    private request;
+}
+export {};