@gemmein/sdk 0.4.7 → 0.6.0

package/dist/index.cjs

@@ -1,8 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GemmeinServer = exports.CollectionClient = exports.StorageClient = exports.AccountClient = exports.PaymentsClient = exports.SubscriptionsClient = exports.FilesClient = exports.PurchasesClient = exports.AuthClient = exports.Gemmein = exports.BrowserTokenStore = exports.MemoryTokenStore = exports.GemmeinError = void 0;
+exports.GemmeinServer = exports.CollectionClient = exports.StorageClient = exports.AccountClient = exports.PaymentsClient = exports.SubscriptionsClient = exports.FilesClient = exports.PurchasesClient = exports.AuthClient = exports.Gemmein = exports.BrowserTokenStore = exports.MemoryTokenStore = exports.GemmeinError = exports.CLIENT_INFO = exports.SDK_VERSION = void 0;
 exports.gemmein = gemmein;
 exports.gemmeinServer = gemmeinServer;
+/** This build's version — the value `package.json` carries. Kept inline
+ *  because the package is one source file and this file is imported
+ *  straight from source by the security suite (no runtime file read, no
+ *  second module). `scripts/sync-version.mjs` rewrites the literal from
+ *  package.json before every build (`prebuild`), and a test pins the two
+ *  equal, so a bump can never ship with a stale header. */
+exports.SDK_VERSION = "0.6.0"; // synced from package.json — do not edit by hand
+/** W9.1 / CLIENT-INFO-1: every request the SDK makes to Gemmein carries
+ *  `x-client-info: gemmein-sdk/<version>`. The server records it on the
+ *  secret-key usage ledger ("last seen from gemmein-sdk/0.5.0"), so a
+ *  misbehaving integration can be attributed to an SDK version from day
+ *  one. It is a report, not a proof — any caller can set it. */
+exports.CLIENT_INFO = `gemmein-sdk/${exports.SDK_VERSION}`;
 class GemmeinError extends Error {
     constructor(input) {
         super(input.message);
@@ -164,7 +177,15 @@ class AuthClient {
             await this.config.tokenStore.set(result.token);
             return result;
         }
-        throw new Error("Gemmein auth response did not include a session token");
+        // W9.1: the one place the SDK threw a bare Error. Every refusal the SDK
+        // raises is a GemmeinError so `err.code` is always there to branch on;
+        // status 0 is the SDK's own convention for "no HTTP status applies"
+        // (see invalid_collection_name, missing_app_key).
+        throw new GemmeinError({
+            status: 0,
+            code: "invalid_response",
+            message: "Gemmein auth response did not include a session token"
+        });
     }
     async logout() {
         try {
@@ -764,7 +785,7 @@ class GemmeinServer {
         }
         const response = await fetch(new URL("/server/test-session", this.apiUrl), {
             method: "POST",
-            headers: { "x-app-key": this.secretKey, "content-type": "application/json" },
+            headers: { "x-app-key": this.secretKey, "x-client-info": exports.CLIENT_INFO, "content-type": "application/json" },
             body: JSON.stringify({ email }),
         });
         if (!response.ok) {
@@ -802,7 +823,7 @@ class GemmeinServer {
     async notify(personId, input) {
         const response = await fetch(new URL("/server/notify", this.apiUrl), {
             method: "POST",
-            headers: { "x-app-key": this.secretKey, "content-type": "application/json" },
+            headers: { "x-app-key": this.secretKey, "x-client-info": exports.CLIENT_INFO, "content-type": "application/json" },
             body: JSON.stringify({ personId, subject: input.subject, text: input.text, ...(input.kind ? { kind: input.kind } : {}), ...(input.key ? { key: input.key } : {}) }),
         });
         if (!response.ok) {
@@ -816,6 +837,155 @@ class GemmeinServer {
         }
         return response.json();
     }
+    /**
+     * THE GATE — your compute, our answer. Gemmein runs no code of yours;
+     * your own function runs anywhere and asks the only three questions it
+     * has: who is this person, what do they hold, change what they hold.
+     *
+     *   const { person, holdings } = await g.verifySession(token);
+     *   if (!holdings.access.includes("access:pro")) return deny();
+     *
+     * ONE call per request answers identity AND holdings — don't call it
+     * twice, and don't cache the answer past the request. Verify needs no
+     * capability on the key (the caller already holds the person's token)
+     * and never touches the session: no extension, no last-seen.
+     *
+     * Refusals (`err.code`): `session_invalid` (no session matches this
+     * token — the person signs in again; never reuse tokens across
+     * people) · `session_expired` · `session_revoked` (a newer sign-in,
+     * a sign-out, or the owner) — all three send the person back to
+     * sign-in · `person_suspended` (the owner suspended them; access is
+     * off until the owner reactivates them in the dashboard) ·
+     * `invalid_body` (token missing, not a string, or over 512 chars).
+     */
+    async verifySession(token) {
+        return this.gate("/server/verify-session", {
+            method: "POST",
+            body: JSON.stringify({ token }),
+        });
+    }
+    /**
+     * W9.2 — THE INVITE DOOR: create a person by email BEFORE they sign in.
+     * The envelope, the invoice, the client portal, the booking-winner
+     * email — all address someone who has never signed in and so has no
+     * id yet. This is the one server call that takes an email:
+     *
+     *   const { person, created } = await g.invitePerson("client@example.com");
+     *   await g.notify(person.id, { subject: "Your contract", text: "…" });
+     *
+     * Create-or-fetch, idempotent, case-insensitive: the first call makes
+     * the person (`created: true`, HTTP 201), every later call finds them
+     * (`created: false`, 200) — one id either way, the address returned
+     * lowercased. Their first sign-in lands on this account: records and
+     * files you addressed to `person.id` are already theirs. `person.invited`
+     * stays true until that sign-in; a suspended person is returned with
+     * `suspended: true`, never refused.
+     *
+     * Needs the key's "Create a person by email before they sign in" box
+     * ticked by your human. Refusals: `capability_required` (the box isn't
+     * ticked) · `invalid_email` (400 — must look like name@domain) ·
+     * `invite_capped` (429 — 500 invite calls per app per day, a fetch of an existing person counting too; the message says
+     * where to write to raise it; `err.resetAt` says when the window ends).
+     */
+    async invitePerson(email) {
+        return this.gate("/server/people", {
+            method: "POST",
+            body: JSON.stringify({ email }),
+        });
+    }
+    /**
+     * What one of YOUR people holds, by person id — for the paths where no
+     * token is in hand (a webhook of your own, a nightly job, an admin
+     * screen you built). A person id, NEVER an email address: ids come
+     * from `verifySession` or the dashboard.
+     *
+     * A suspended person is RETURNED, with `suspended: true`, alongside
+     * their holdings — your function may need to say so. The gate itself
+     * (`verifySession`) refuses them.
+     *
+     * Refusals: `capability_required` — this key can't look up people by
+     * id; ask your human to mint a key with "Look up a person's access by
+     * id" ticked, or use `verifySession` with the person's own token ·
+     * `person_not_found` (404 — no person with this id in this app and
+     * environment; existence is never leaked).
+     */
+    async holdings(personId) {
+        return this.gate(`/server/people/${encodeURIComponent(personId)}/holdings`);
+    }
+    /**
+     * Give a person access by hand — a trial, a promotion, an apology, a
+     * migration from your old system:
+     *
+     *   await g.grantAccess(personId, {
+     *     entitlement: "access:pro",     // or the plan's NAME, e.g. "Pro"
+     *     source: "trial",
+     *     expiresAt: "2026-10-01T00:00:00.000Z",
+     *     reason: "7-day trial from the onboarding flow",
+     *   });
+     *
+     * MANUAL sources only. Purchases and subscriptions come only from
+     * Stripe — a key cannot mint paid access, by design. `reason` is up to
+     * 200 characters, is never edited afterwards, and is what the owner
+     * reads in their logs; write it for them.
+     *
+     * `sourceId` is minted per call, so two calls make TWO grants (each
+     * with its own one reason) — call it once, and keep your own retry
+     * key if the caller can retry.
+     *
+     * Returns the new grant and the holdings AFTER it; the owner's audit
+     * row carries before→after and the key's name.
+     *
+     * Refusals: `capability_required` — this key can't grant access; ask
+     * your human to mint a key with "Grant and revoke access" ticked ·
+     * `invalid_source` (purchase/subscription refused) ·
+     * `invalid_entitlement` / `unknown_plan` (no plan or product by that
+     * name — the owner adds it on the Payments page) · `person_not_found`.
+     */
+    async grantAccess(personId, input) {
+        return this.gate(`/server/people/${encodeURIComponent(personId)}/grants`, {
+            method: "POST",
+            body: JSON.stringify({
+                entitlement: input.entitlement,
+                ...(input.source ? { source: input.source } : {}),
+                ...(input.expiresAt ? { expiresAt: input.expiresAt } : {}),
+                ...(input.reason ? { reason: input.reason } : {}),
+            }),
+        });
+    }
+    /**
+     * End one grant — the reversibility law in one call:
+     *
+     *   await g.revokeAccess(personId, grant.id, { reason: "trial ended" });
+     *
+     * A grant ends ONCE: `revokedAt` is set and never edited, so a second
+     * call is `409 already_revoked`, not a silent no-op. A key MAY end a
+     * grant that a payment created (the same as the owner's "end this
+     * access" button) — the payment itself is untouched, and the audit row
+     * says so.
+     *
+     * Returns the revoked grant and the holdings after it.
+     *
+     * Refusals: `capability_required` (same ticked box as granting) ·
+     * `grant_not_found` (404 — not this person's grant, in this app and
+     * environment; existence is never leaked) · `already_revoked` (409).
+     */
+    async revokeAccess(personId, grantId, input = {}) {
+        return this.gate(`/server/people/${encodeURIComponent(personId)}/grants/${encodeURIComponent(grantId)}/revoke`, { method: "POST", body: JSON.stringify({ ...(input.reason ? { reason: input.reason } : {}) }) });
+    }
+    // One request path for the four gate calls, so every refusal reaches
+    // the caller through the SAME typed error the rest of the SDK throws —
+    // `err.code` carries the server's own code, `err.message` its sentence
+    // (which always names the next action).
+    async gate(path, init = {}) {
+        const headers = { "x-app-key": this.secretKey, "x-client-info": exports.CLIENT_INFO };
+        if (init.body)
+            headers["content-type"] = "application/json";
+        const response = await fetch(new URL(path, this.apiUrl), { ...init, headers });
+        if (!response.ok) {
+            throw new GemmeinError({ status: response.status, ...(await readErrorBody(response)) });
+        }
+        return response.json();
+    }
 }
 exports.GemmeinServer = GemmeinServer;
 class ServerCollectionClient {
@@ -857,6 +1027,7 @@ class ServerCollectionClient {
     async request(suffix, init = {}) {
         const headers = {
             "x-app-key": this.secretKey,
+            "x-client-info": exports.CLIENT_INFO,
         };
         if (init.body) {
             headers["content-type"] = "application/json";
@@ -932,6 +1103,7 @@ async function runtimeHeaders(config, headers) {
     return {
         ...headers,
         "x-app-key": config.appKey,
+        "x-client-info": exports.CLIENT_INFO,
         ...(token ? { authorization: `Bearer ${token}` } : {})
     };
 }

package/dist/index.d.cts

@@ -114,6 +114,19 @@ export type AuthSession = {
         email: string;
     };
 };
+/** This build's version — the value `package.json` carries. Kept inline
+ *  because the package is one source file and this file is imported
+ *  straight from source by the security suite (no runtime file read, no
+ *  second module). `scripts/sync-version.mjs` rewrites the literal from
+ *  package.json before every build (`prebuild`), and a test pins the two
+ *  equal, so a bump can never ship with a stale header. */
+export declare const SDK_VERSION = "0.6.0";
+/** W9.1 / CLIENT-INFO-1: every request the SDK makes to Gemmein carries
+ *  `x-client-info: gemmein-sdk/<version>`. The server records it on the
+ *  secret-key usage ledger ("last seen from gemmein-sdk/0.5.0"), so a
+ *  misbehaving integration can be attributed to an SDK version from day
+ *  one. It is a report, not a proof — any caller can set it. */
+export declare const CLIENT_INFO = "gemmein-sdk/0.6.0";
 export declare class GemmeinError extends Error {
     readonly status: number;
     readonly code: string;
@@ -525,6 +538,56 @@ export type GemmeinServerOptions = {
     secretKey: string;
     apiUrl?: string;
 };
+/**
+ * Where a grant came from — the KIND only. The gate never returns the
+ * source's id, an amount, or anything from Stripe.
+ */
+export type GrantSource = "subscription" | "purchase" | "manual" | "trial" | "promotion" | "migration" | "relay";
+/**
+ * The sources a secret key may create by hand. `purchase` and
+ * `subscription` are deliberately absent: money-made access comes only
+ * from Stripe, and always will.
+ */
+export type ManualGrantSource = "manual" | "trial" | "promotion" | "migration";
+export type Grant = {
+    id: string;
+    /** `access:<slug>` — the plan's or product's own key. */
+    entitlement: string;
+    source: GrantSource;
+    startsAt: string;
+    expiresAt: string | null;
+    /** Present on the grant returned by `revokeAccess` — set once, never edited. */
+    revokedAt?: string | null;
+};
+/**
+ * What a person holds RIGHT NOW — never what they pay. `access` is the
+ * union of live grants' keys; `grants` lists those live grants (revoked
+ * and expired ones are gone, not flagged). `credits` is a reserved slot:
+ * it is `null` today because consumable credits are not shipped — don't
+ * design around them until this type says otherwise.
+ */
+export type Holdings = {
+    access: string[];
+    grants: Grant[];
+    credits: {
+        balance: number;
+    } | null;
+};
+export type GatePerson = {
+    id: string;
+    email: string;
+    role: string;
+};
+/**
+ * W9.2 — the person `invitePerson` returns. `invited` is true until they
+ * sign in for the first time; `suspended` is the owner's switch (a
+ * suspended person is returned, never refused — `verifySession` is what
+ * refuses them).
+ */
+export type InvitedPerson = GatePerson & {
+    invited: boolean;
+    suspended: boolean;
+};
 export declare class GemmeinServer {
     private readonly apiUrl;
     private readonly secretKey;
@@ -582,6 +645,146 @@ export declare class GemmeinServer {
         replyRail?: boolean;
         recorded?: boolean;
     }>;
+    /**
+     * THE GATE — your compute, our answer. Gemmein runs no code of yours;
+     * your own function runs anywhere and asks the only three questions it
+     * has: who is this person, what do they hold, change what they hold.
+     *
+     *   const { person, holdings } = await g.verifySession(token);
+     *   if (!holdings.access.includes("access:pro")) return deny();
+     *
+     * ONE call per request answers identity AND holdings — don't call it
+     * twice, and don't cache the answer past the request. Verify needs no
+     * capability on the key (the caller already holds the person's token)
+     * and never touches the session: no extension, no last-seen.
+     *
+     * Refusals (`err.code`): `session_invalid` (no session matches this
+     * token — the person signs in again; never reuse tokens across
+     * people) · `session_expired` · `session_revoked` (a newer sign-in,
+     * a sign-out, or the owner) — all three send the person back to
+     * sign-in · `person_suspended` (the owner suspended them; access is
+     * off until the owner reactivates them in the dashboard) ·
+     * `invalid_body` (token missing, not a string, or over 512 chars).
+     */
+    verifySession(token: string): Promise<{
+        ok: true;
+        person: GatePerson;
+        holdings: Holdings;
+    }>;
+    /**
+     * W9.2 — THE INVITE DOOR: create a person by email BEFORE they sign in.
+     * The envelope, the invoice, the client portal, the booking-winner
+     * email — all address someone who has never signed in and so has no
+     * id yet. This is the one server call that takes an email:
+     *
+     *   const { person, created } = await g.invitePerson("client@example.com");
+     *   await g.notify(person.id, { subject: "Your contract", text: "…" });
+     *
+     * Create-or-fetch, idempotent, case-insensitive: the first call makes
+     * the person (`created: true`, HTTP 201), every later call finds them
+     * (`created: false`, 200) — one id either way, the address returned
+     * lowercased. Their first sign-in lands on this account: records and
+     * files you addressed to `person.id` are already theirs. `person.invited`
+     * stays true until that sign-in; a suspended person is returned with
+     * `suspended: true`, never refused.
+     *
+     * Needs the key's "Create a person by email before they sign in" box
+     * ticked by your human. Refusals: `capability_required` (the box isn't
+     * ticked) · `invalid_email` (400 — must look like name@domain) ·
+     * `invite_capped` (429 — 500 invite calls per app per day, a fetch of an existing person counting too; the message says
+     * where to write to raise it; `err.resetAt` says when the window ends).
+     */
+    invitePerson(email: string): Promise<{
+        person: InvitedPerson;
+        created: boolean;
+    }>;
+    /**
+     * What one of YOUR people holds, by person id — for the paths where no
+     * token is in hand (a webhook of your own, a nightly job, an admin
+     * screen you built). A person id, NEVER an email address: ids come
+     * from `verifySession` or the dashboard.
+     *
+     * A suspended person is RETURNED, with `suspended: true`, alongside
+     * their holdings — your function may need to say so. The gate itself
+     * (`verifySession`) refuses them.
+     *
+     * Refusals: `capability_required` — this key can't look up people by
+     * id; ask your human to mint a key with "Look up a person's access by
+     * id" ticked, or use `verifySession` with the person's own token ·
+     * `person_not_found` (404 — no person with this id in this app and
+     * environment; existence is never leaked).
+     */
+    holdings(personId: string): Promise<{
+        ok: true;
+        person: GatePerson & {
+            suspended: boolean;
+        };
+        holdings: Holdings;
+    }>;
+    /**
+     * Give a person access by hand — a trial, a promotion, an apology, a
+     * migration from your old system:
+     *
+     *   await g.grantAccess(personId, {
+     *     entitlement: "access:pro",     // or the plan's NAME, e.g. "Pro"
+     *     source: "trial",
+     *     expiresAt: "2026-10-01T00:00:00.000Z",
+     *     reason: "7-day trial from the onboarding flow",
+     *   });
+     *
+     * MANUAL sources only. Purchases and subscriptions come only from
+     * Stripe — a key cannot mint paid access, by design. `reason` is up to
+     * 200 characters, is never edited afterwards, and is what the owner
+     * reads in their logs; write it for them.
+     *
+     * `sourceId` is minted per call, so two calls make TWO grants (each
+     * with its own one reason) — call it once, and keep your own retry
+     * key if the caller can retry.
+     *
+     * Returns the new grant and the holdings AFTER it; the owner's audit
+     * row carries before→after and the key's name.
+     *
+     * Refusals: `capability_required` — this key can't grant access; ask
+     * your human to mint a key with "Grant and revoke access" ticked ·
+     * `invalid_source` (purchase/subscription refused) ·
+     * `invalid_entitlement` / `unknown_plan` (no plan or product by that
+     * name — the owner adds it on the Payments page) · `person_not_found`.
+     */
+    grantAccess(personId: string, input: {
+        entitlement: string;
+        source?: ManualGrantSource;
+        expiresAt?: string;
+        reason?: string;
+    }): Promise<{
+        ok: true;
+        grant: Grant;
+        holdings: Holdings;
+    }>;
+    /**
+     * End one grant — the reversibility law in one call:
+     *
+     *   await g.revokeAccess(personId, grant.id, { reason: "trial ended" });
+     *
+     * A grant ends ONCE: `revokedAt` is set and never edited, so a second
+     * call is `409 already_revoked`, not a silent no-op. A key MAY end a
+     * grant that a payment created (the same as the owner's "end this
+     * access" button) — the payment itself is untouched, and the audit row
+     * says so.
+     *
+     * Returns the revoked grant and the holdings after it.
+     *
+     * Refusals: `capability_required` (same ticked box as granting) ·
+     * `grant_not_found` (404 — not this person's grant, in this app and
+     * environment; existence is never leaked) · `already_revoked` (409).
+     */
+    revokeAccess(personId: string, grantId: string, input?: {
+        reason?: string;
+    }): Promise<{
+        ok: true;
+        grant: Grant;
+        holdings: Holdings;
+    }>;
+    private gate;
 }
 declare class ServerCollectionClient {
     private readonly apiUrl;

package/dist/index.d.ts

@@ -114,6 +114,19 @@ export type AuthSession = {
         email: string;
     };
 };
+/** This build's version — the value `package.json` carries. Kept inline
+ *  because the package is one source file and this file is imported
+ *  straight from source by the security suite (no runtime file read, no
+ *  second module). `scripts/sync-version.mjs` rewrites the literal from
+ *  package.json before every build (`prebuild`), and a test pins the two
+ *  equal, so a bump can never ship with a stale header. */
+export declare const SDK_VERSION = "0.6.0";
+/** W9.1 / CLIENT-INFO-1: every request the SDK makes to Gemmein carries
+ *  `x-client-info: gemmein-sdk/<version>`. The server records it on the
+ *  secret-key usage ledger ("last seen from gemmein-sdk/0.5.0"), so a
+ *  misbehaving integration can be attributed to an SDK version from day
+ *  one. It is a report, not a proof — any caller can set it. */
+export declare const CLIENT_INFO = "gemmein-sdk/0.6.0";
 export declare class GemmeinError extends Error {
     readonly status: number;
     readonly code: string;
@@ -525,6 +538,56 @@ export type GemmeinServerOptions = {
     secretKey: string;
     apiUrl?: string;
 };
+/**
+ * Where a grant came from — the KIND only. The gate never returns the
+ * source's id, an amount, or anything from Stripe.
+ */
+export type GrantSource = "subscription" | "purchase" | "manual" | "trial" | "promotion" | "migration" | "relay";
+/**
+ * The sources a secret key may create by hand. `purchase` and
+ * `subscription` are deliberately absent: money-made access comes only
+ * from Stripe, and always will.
+ */
+export type ManualGrantSource = "manual" | "trial" | "promotion" | "migration";
+export type Grant = {
+    id: string;
+    /** `access:<slug>` — the plan's or product's own key. */
+    entitlement: string;
+    source: GrantSource;
+    startsAt: string;
+    expiresAt: string | null;
+    /** Present on the grant returned by `revokeAccess` — set once, never edited. */
+    revokedAt?: string | null;
+};
+/**
+ * What a person holds RIGHT NOW — never what they pay. `access` is the
+ * union of live grants' keys; `grants` lists those live grants (revoked
+ * and expired ones are gone, not flagged). `credits` is a reserved slot:
+ * it is `null` today because consumable credits are not shipped — don't
+ * design around them until this type says otherwise.
+ */
+export type Holdings = {
+    access: string[];
+    grants: Grant[];
+    credits: {
+        balance: number;
+    } | null;
+};
+export type GatePerson = {
+    id: string;
+    email: string;
+    role: string;
+};
+/**
+ * W9.2 — the person `invitePerson` returns. `invited` is true until they
+ * sign in for the first time; `suspended` is the owner's switch (a
+ * suspended person is returned, never refused — `verifySession` is what
+ * refuses them).
+ */
+export type InvitedPerson = GatePerson & {
+    invited: boolean;
+    suspended: boolean;
+};
 export declare class GemmeinServer {
     private readonly apiUrl;
     private readonly secretKey;
@@ -582,6 +645,146 @@ export declare class GemmeinServer {
         replyRail?: boolean;
         recorded?: boolean;
     }>;
+    /**
+     * THE GATE — your compute, our answer. Gemmein runs no code of yours;
+     * your own function runs anywhere and asks the only three questions it
+     * has: who is this person, what do they hold, change what they hold.
+     *
+     *   const { person, holdings } = await g.verifySession(token);
+     *   if (!holdings.access.includes("access:pro")) return deny();
+     *
+     * ONE call per request answers identity AND holdings — don't call it
+     * twice, and don't cache the answer past the request. Verify needs no
+     * capability on the key (the caller already holds the person's token)
+     * and never touches the session: no extension, no last-seen.
+     *
+     * Refusals (`err.code`): `session_invalid` (no session matches this
+     * token — the person signs in again; never reuse tokens across
+     * people) · `session_expired` · `session_revoked` (a newer sign-in,
+     * a sign-out, or the owner) — all three send the person back to
+     * sign-in · `person_suspended` (the owner suspended them; access is
+     * off until the owner reactivates them in the dashboard) ·
+     * `invalid_body` (token missing, not a string, or over 512 chars).
+     */
+    verifySession(token: string): Promise<{
+        ok: true;
+        person: GatePerson;
+        holdings: Holdings;
+    }>;
+    /**
+     * W9.2 — THE INVITE DOOR: create a person by email BEFORE they sign in.
+     * The envelope, the invoice, the client portal, the booking-winner
+     * email — all address someone who has never signed in and so has no
+     * id yet. This is the one server call that takes an email:
+     *
+     *   const { person, created } = await g.invitePerson("client@example.com");
+     *   await g.notify(person.id, { subject: "Your contract", text: "…" });
+     *
+     * Create-or-fetch, idempotent, case-insensitive: the first call makes
+     * the person (`created: true`, HTTP 201), every later call finds them
+     * (`created: false`, 200) — one id either way, the address returned
+     * lowercased. Their first sign-in lands on this account: records and
+     * files you addressed to `person.id` are already theirs. `person.invited`
+     * stays true until that sign-in; a suspended person is returned with
+     * `suspended: true`, never refused.
+     *
+     * Needs the key's "Create a person by email before they sign in" box
+     * ticked by your human. Refusals: `capability_required` (the box isn't
+     * ticked) · `invalid_email` (400 — must look like name@domain) ·
+     * `invite_capped` (429 — 500 invite calls per app per day, a fetch of an existing person counting too; the message says
+     * where to write to raise it; `err.resetAt` says when the window ends).
+     */
+    invitePerson(email: string): Promise<{
+        person: InvitedPerson;
+        created: boolean;
+    }>;
+    /**
+     * What one of YOUR people holds, by person id — for the paths where no
+     * token is in hand (a webhook of your own, a nightly job, an admin
+     * screen you built). A person id, NEVER an email address: ids come
+     * from `verifySession` or the dashboard.
+     *
+     * A suspended person is RETURNED, with `suspended: true`, alongside
+     * their holdings — your function may need to say so. The gate itself
+     * (`verifySession`) refuses them.
+     *
+     * Refusals: `capability_required` — this key can't look up people by
+     * id; ask your human to mint a key with "Look up a person's access by
+     * id" ticked, or use `verifySession` with the person's own token ·
+     * `person_not_found` (404 — no person with this id in this app and
+     * environment; existence is never leaked).
+     */
+    holdings(personId: string): Promise<{
+        ok: true;
+        person: GatePerson & {
+            suspended: boolean;
+        };
+        holdings: Holdings;
+    }>;
+    /**
+     * Give a person access by hand — a trial, a promotion, an apology, a
+     * migration from your old system:
+     *
+     *   await g.grantAccess(personId, {
+     *     entitlement: "access:pro",     // or the plan's NAME, e.g. "Pro"
+     *     source: "trial",
+     *     expiresAt: "2026-10-01T00:00:00.000Z",
+     *     reason: "7-day trial from the onboarding flow",
+     *   });
+     *
+     * MANUAL sources only. Purchases and subscriptions come only from
+     * Stripe — a key cannot mint paid access, by design. `reason` is up to
+     * 200 characters, is never edited afterwards, and is what the owner
+     * reads in their logs; write it for them.
+     *
+     * `sourceId` is minted per call, so two calls make TWO grants (each
+     * with its own one reason) — call it once, and keep your own retry
+     * key if the caller can retry.
+     *
+     * Returns the new grant and the holdings AFTER it; the owner's audit
+     * row carries before→after and the key's name.
+     *
+     * Refusals: `capability_required` — this key can't grant access; ask
+     * your human to mint a key with "Grant and revoke access" ticked ·
+     * `invalid_source` (purchase/subscription refused) ·
+     * `invalid_entitlement` / `unknown_plan` (no plan or product by that
+     * name — the owner adds it on the Payments page) · `person_not_found`.
+     */
+    grantAccess(personId: string, input: {
+        entitlement: string;
+        source?: ManualGrantSource;
+        expiresAt?: string;
+        reason?: string;
+    }): Promise<{
+        ok: true;
+        grant: Grant;
+        holdings: Holdings;
+    }>;
+    /**
+     * End one grant — the reversibility law in one call:
+     *
+     *   await g.revokeAccess(personId, grant.id, { reason: "trial ended" });
+     *
+     * A grant ends ONCE: `revokedAt` is set and never edited, so a second
+     * call is `409 already_revoked`, not a silent no-op. A key MAY end a
+     * grant that a payment created (the same as the owner's "end this
+     * access" button) — the payment itself is untouched, and the audit row
+     * says so.
+     *
+     * Returns the revoked grant and the holdings after it.
+     *
+     * Refusals: `capability_required` (same ticked box as granting) ·
+     * `grant_not_found` (404 — not this person's grant, in this app and
+     * environment; existence is never leaked) · `already_revoked` (409).
+     */
+    revokeAccess(personId: string, grantId: string, input?: {
+        reason?: string;
+    }): Promise<{
+        ok: true;
+        grant: Grant;
+        holdings: Holdings;
+    }>;
+    private gate;
 }
 declare class ServerCollectionClient {
     private readonly apiUrl;