SDK reference

The complete surface of @gemmein/sdk: every method, signature, and return shape — with the GemmeinSwift signature beside each one, and everything @gemmein/sdk/expo adds. This exact reference also ships inside the package as REFERENCE.md.

Setup

import { gemmein, gemmeinServer, GemmeinError } from "@gemmein/sdk"

const g   = gemmein("pk_...")          // browser: public key, domain-locked, safe to ship
const srv = gemmeinServer("sk_...")    // server only — never in the browser (the SDK throws)

gemmein() accepts options { apiUrl?, tokenStore?, fetch?, visibility?, platform? }; gemmeinServer() takes { apiUrl? } only. gemmein() throws missing_app_key/invalid_app_key if the key is absent or an sk_.

The last three are what a non-browser runtime needs and a browser never passes. fetch is used for every request this client makes, in place of globalThis.fetch. visibility ({ isHidden(): boolean; onChange(cb: () => void): () => void }) is where watch() learns the app went to the background, in place of document.visibilityState; onChange returns its own unsubscribe. platform is appended to the x-client-info header — gemmein-sdk/<version> expo-ios — cleaned and capped to the 64 characters the usage ledger stores. On Expo, createExpoGemmein from @gemmein/sdk/expo fills all four in for a phone; the Swift package fills them in for Apple platforms. See Mobile.

Swift: GemmeinSwift

The same HTTP contract and the same method names, in Swift idiom, for iOS 17+ and macOS 14+, with no dependencies: .package(url: "https://github.com/gemmeinhq/gemmein-swift.git", from: "0.12.0").

import GemmeinSwift

let g = try Gemmein(appKey: "pk_live_...")   // KeychainTokenStore by default

try await g.auth.sendEmailCode(email)
_ = try await g.auth.verifyEmailCode(email: email, code: code)
let page = try await g.collection("notes").list(ListOptions(limit: 20))
let me = try await g.auth.currentUser()    // .storeAccountToken for RevenueCat

Licences: the SDK, the MCP server and the gemmein launcher are MIT. The engine the launcher downloads is proprietary — run and cache it freely for building against Gemmein; no redistribution. Full text at downloads.gemmein.com/engine/LICENSE.

init(appKey:apiURL:tokenStore:platform:session:). apiURL points at a local gemmein dev engine while you build; tokenStore defaults to KeychainTokenStore, and MemoryTokenStore is there for tests; platform defaults to this OS and is appended to x-client-info. An sk_ key is refused here, as in the browser — GemmeinServer ships in the package for Swift that runs on a server. The clients are the same names as the browser's: g.auth, g.collection(_:), g.files, g.subscriptions, g.payments, g.purchases, g.account, g.credits, g.ai, and GemmeinServer. Everything it throws is a GemmeinError carrying the server's own code and sentence, plus resetAt and requires.

Three shapes differ from JavaScript, and they are the three a first build trips on: g.credits.balance() answers a bare Int, not a { balance } wrapper; g.files.link(_:) answers a FileLink whose url is a String; and a record or AI body is [String: JSONValue], so a variable needs its case (["title": .string(typed)]) where a literal needs nothing. Each method's Swift signature sits beside its JavaScript twin in the sections below.

TokenStore is a protocol — func get() async -> String?, func set(_ token: String) async throws, func clear() async. KeychainTokenStore(appKey:) is the default and MemoryTokenStore(token:) is there for tests and for the app that catches secure_store_unavailable. Only set throws.

Expo: @gemmein/sdk/expo

The same package, a second entry point. It re-exports the whole core surface, so an Expo app imports from one place; the table is everything the entry adds. The peers install in the app, not in your monorepo: npx expo install expo-secure-store expo-file-system. Nothing is imported from Expo or React Native at module load, so the entry resolves in Node too. See Mobile.

import { createExpoGemmein } from "@gemmein/sdk/expo"
import { AppState, Platform } from "react-native"

export const g = createExpoGemmein({ appKey: "pk_live_..." }, { AppState, Platform })

SecureStoreModule, AppStateModule, PlatformModule and FileSystemModule are the exported types of those four slices — the little of each module this entry calls, and nothing more.

Auth: g.auth

Swift: g.auth

The same four methods, with Swift's argument labels. Everything that leaves the device is async throws and throws GemmeinError.

type AuthSession = { token, expiresAt, user: { id, email } }
type CurrentUser = { authenticated: true, userId, email, storeAccountToken? }   // note: userId, NOT id
                 | { authenticated: false }

storeAccountToken is the opaque per-person name to hand a store — RevenueCat's app user id, Apple's appAccountToken, Google's obfuscatedExternalAccountId. Minted on the first currentUser() call, stable for the life of the person, correlated to nothing, and gone when they are erased. Hand a store that, never userId and never the address. See Mobile.

authenticated: false does not say why. Signed out, suspended by the owner, and erased all read the same, so a moderated user's state never leaks to the client. One signed-out screen covers all three.

Account: g.account

Swift: g.account

The “delete my account” screen. Every app it applies to needs one (GDPR right to erasure; Apple 5.1.1(v) for apps with account creation). Server-side it's the full cascade: sessions revoked, records and files deleted, subscription row removed. Irreversible: put a real confirm in front of it.

Data: g.collection<T>(name)

Swift: g.collection(_:)

The same methods. Three shapes differ on purpose: a record body is [String: JSONValue] (a literal needs no ceremony — ["title": "Ran", "done": false] — a variable needs its case, ["title": .string(typed)]); upload takes Data, not a Blob; and watch is not async.

ListOptions(limit:sort:where:cursor:search:expand:since:) — every argument optional, sort is ListSort (.newest, .oldest, .updated), and where keeps the label where, binding a [String: JSONValue]. Your fields live under data, read as note.data["title"]?.string; everything else on a GemmeinRecord is server-derived and read-only.

type GemmeinRecord<T> = {
  id: string
  data: T                      // YOUR fields live here — record.data.title, never record.title
  createdAt: string
  updatedAt: string
  ownerUserId: string | null   // server-set; null for app-owned (receipts, dashboard-created)
  version: number              // +1 per update; pass as { ifVersion } to guard concurrent edits
  published: boolean           // top-level; only meaningful on public rules
  key?: string                 // the create-if-absent key, when one was used
  audienceUserId?: string      // recipient on addressed/direct (server-stamped)
  expand?: Record<string, GemmeinRecord | null>   // filled by { expand: [...] }
  existing?: true              // present when a keyed create returned YOUR existing record
}

type ListResult<T> = { records: GemmeinRecord<T>[], cursor?, hasMore,
                       deleted?, watermark? }  // deleted rides `since` reads (your scope only); watermark: on a delta read, the FINAL page's; paging a full sync, adopt the FIRST page's

sort: "newest" | "oldest" | "updated". where: a literal per field is an exact match; an object of operators (eq ne gt gte lt lte in nin contains startsWith exists) narrows it, up to 5 fields and 3 operators each, all AND (the grammar). expand: up to 3 link fields, only on community/shared/direct. Atomic counters go in value position: update(id, { stock: { decrement: 1, floor: 0 } }).

A field added to a sealed shape by a promote run (npx gemmein go-live, run again, or the dashboard's Go-live page) may carry a default: records that never wrote it read that value, expand targets and where see it too, and a written value wins — writing null clears it back to the default. search still matches stored text only. See Data & the rules.

Payments

Swift: g.subscriptions / g.payments / g.purchases

Nothing navigates: checkout and buy answer a url and the app opens it (openURL, SFSafariViewController).

Credits: g.credits

Swift: g.credits

AI: g.ai

Swift: g.ai

AiResponse stands where JS returns the fetch Response, and run / runText take the label inputs: — runText("summary", inputs: ["text": .string(body)]).

AiResponse carries status: Int, headers, ok: Bool, creditsRemaining: Int?, refunded: Bool, tool: String?, isFake: Bool, func data() async throws -> Data, and two streams — lines() and events(), both AsyncThrowingStream<String, Error>. AiProvider is .openai, .anthropic, .google.

Server: gemmeinServer(sk)

Swift: GemmeinServer

GemmeinServer ships in the package for Swift that runs on a server. It takes a secret key, and a secret key never belongs in an app bundle — Gemmein refuses one. There is no ok field on these answers: a refusal throws.

GatePerson { id: String, email: String, role: String, suspended: Bool?, invited: Bool? }; Holdings { access: [String], grants: [Grant], credits: Int? } — a bare Int? where JS nests { balance }.

// Gemmein hosts no compute. YOUR function — Vercel, a VPS, a cron box — asks the
// only three questions it has: who is this person, what do they hold, change it.
const { person, holdings } = await g.verifySession(token)
if (!holdings.access.includes("access:pro")) return deny()

type Holdings = {
  access: string[]                // the keys they hold NOW — ["access:pro"]
  grants: Grant[]                 // the LIVE grants behind them (revoked/expired are gone)
  credits: { balance: number } | null   // the balance now (engine 0.8.0+); null from an older local engine — see /credits
}

type Grant = {
  id: string
  entitlement: string           // "access:<slug>" — the plan's or product's own key
  source: "subscription" | "purchase" | "manual" | "trial" | "promotion" | "migration"
  startsAt: string
  expiresAt: string | null
  revokedAt?: string | null       // present on the grant revokeAccess returns
}

Holdings, not billing. The gate answers what a person holds, never what they pay: no subscription status, no amounts, no Stripe ids, and a grant's source kind only, never its sourceId. Gate on what they hold. A person id, never an email address. Looking someone up by id and granting are new power, so each sits behind a plain-English checkbox the owner ticks when minting the key; existing keys have both off, so nothing in production changes. Every /server/* call a resolved secret key makes, allowed or refused, lands in that key's usage ledger: the Secret keys page carries the summary (last used · 7-day calls · refusals), and the full day × route × outcome table lives in the key's own room. A refusal from a publishable pk_ key can't be attributed to a secret key, so it reaches only the request log. Grants and revokes write a full before→after row to the logs, attributed to the key by name. Refusals: session_invalid, session_expired, session_revoked, person_suspended, person_not_found, capability_required, invalid_source, invalid_entitlement, unknown_plan, grant_not_found, already_revoked, invalid_id and invalid_body, each with its action in the error table.

Keys & environments

Environments are fully isolated: different data, different users, different collections. Errors: see the full code table. Management (collections, domains, keys, payments config, logs) is dashboard-only and excluded from the SDK, so management credentials can never leak from app code.

The numbers

Everything the server enforces, in one place. Nothing here is a soft target: every limit below is enforced and returns the listed error code.