SDK reference

Every method, signature and return shape in @gemmein/sdk, with the GemmeinSwift signature for each one and everything @gemmein/sdk/expo adds. The same reference is included in 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 (for example gemmein-sdk/<version> expo-ios), cleaned and cut to 64 characters, the length a key's usage records keep. 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 API 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

init(appKey:apiURL:tokenStore:platform:session:). apiURL points at a local gemmein dev server 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; Swift that runs on a server uses GemmeinServer (below). 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, g.runs, 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 ones a first build most often gets wrong:

• g.credits.balance() returns a bare Int, where JavaScript returns a { balance } wrapper.
• g.files.link(_:) returns a FileLink whose url is a String.
• A record or AI body is [String: JSONValue]. A literal needs nothing (["title": "Ran", "done": false]); a variable needs its case (["title": .string(typed)]).

Each section below gives the JavaScript table first, then the Swift one.

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. Install the peers in the app itself (they do not go 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 for the parts of those four modules this entry calls.

Auth: g.auth

Swift: g.auth

The same eight 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 Device = { id, device, place, signedInAt, lastActiveAt, expiresAt, test, current }   // place: an approximate country or null, never an IP address or a city
type CurrentUser = { authenticated: true, userId, email, storeAccountToken? }   // note: userId, NOT id
                 | { authenticated: false, ended? }   // ended: "expired" | "revoked", only for a session that ran out or was ended

storeAccountToken is the opaque per-person name to give a store: RevenueCat's app user id, Apple's appAccountToken, Google's obfuscatedExternalAccountId. It is created on the first currentUser() call, stable for the life of the person, correlated to nothing, and gone when they are erased. Give the store this value. Never give it userId or the email address. See Mobile.

authenticated: false says why only through ended, and only for a session that ran out ("expired") or was ended ("revoked": signed out from this device or another, or by the owner, which is not said). Suspended by the owner and erased read like no session at all, so a moderated person's state never leaks to the client. One signed-out screen covers every case; ended only picks its sentence.

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 record removed, and a paid plan in Stripe set to cancel at the end of its period. Irreversible: put a confirmation step in front of it.

Data: g.collection<T>(name)

Swift: g.collection(_:)

The same methods, with the record body described in Swift above. upload takes Data where JavaScript takes a Blob, and watch is not async.

ListOptions(limit:sort:where:cursor:search:expand:since:) — every argument optional, sort is ListSort (.newest, .oldest, .updated, or .by("score", order: .asc) for a rankable number field, when each record carries rank). create takes showFrom: / showUntil: as Dates and update as a ShowBound: .at(date) or .clear. 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 safety 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
  showFrom?: string            // hidden from other readers before this instant (top-level, like published)
  showUntil?: string           // hidden from other readers from this instant on
  rank?: number                // on a ranked list ({ sort: { by } }): 1 + how many records rank better; ties share
}

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", or { by, order } for a rankable number field (order is "desc", the default, or "asc"; each record then carries rank; not with since). showFrom / showUntil on create and update take an ISO 8601 instant with a zone, or a Date; null clears one on update (show and hide times). 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 } }).

When you add a field to a live collection (run npx gemmein go-live again, or use the dashboard's Go live page), you can give it a default. Records that never wrote the field read the default, and expand targets and where see it too. A written value wins, and writing null resets it to the default. search still matches stored text only. See Data & safety rules.

People: g.people

Follows and blocks, kept on the server for every collection at once. Follows are one-way: anyone follows anyone, and friends are people who follow each other, worked out when asked and never stored. A block works both ways: neither person reads the other’s records in any collection while signed in (list, get, count, stats, search, expand, open fields, watch), any follow between them ends, and neither can follow or message the other (403 person_unavailable, the same sentence whoever blocked). Blocking beats following.

The feed is list({ author: "following" }), on shared, community, public_read and direct. A followers-only post is create(data, { visibility: "followers" }) on community and shared: the author, the author’s followers right now, the dashboard and your server read it, and never anyone signed out. Photos on it are uploaded with upload(file, { visibility: "followers" }) (Swift visibility: .followers); a followers-only post carries only its author’s followers files, else 400 file_is_public. It never tells anyone who blocked them, and it cannot hide a public post from someone signed out.

Profiles, private accounts and requests. relationship(id) answers the profile numbers counts: { followers, following } to any signed-in person. followersOf(id) and followingOf(id) list another person’s; a private account’s lists show only to the people it accepted (403 person_private). setPrivate(true) makes an account private: a follow becomes a request (requested: true), answered by accept(id) or decline(id), and a private person’s posts and files on community, shared, public_read and admin_write reach only them, the people they accepted, your dashboard and your server; a circle post still reaches its circle and a direct message its people. setPrivate(false) accepts every request waiting. A person switches at most 10 times an hour (3 in Development).

Swift: g.people

Bounds. A person follows at most 5,000 and blocks 1,000 (429 follow_limit and block_limit); 200 follow changes and 60 block changes an hour (429 too_many_changes, with resetAt). Cloud Development: 200 follows and 50 blocks per person, 30 and 20 changes an hour, 2,000 follows and 500 blocks per app (429 development_capped); npx gemmein dev takes Live’s bounds.

What happens if… someone unfollows: their followers-only posts leave that person’s reads at once, and a watcher resyncs. Two people block: both follows end and their records leave each other’s app. They unblock: they see each other again, and nobody follows until they follow again. A person deletes their account: every follow and block naming them goes. You go live: Live starts with no follows or blocks, because a promote carries collections and never people.

Circles: g.circles

A person’s own small groups: close friends, a team, a family. The person who creates a circle adds and removes its members; every member reads the circle’s posts and member list, and may leave. A circle post is create(data, { visibility: "circle:" + circle.id }) on community and shared (Swift visibility: .circle(circle.id)); its files are uploaded with the same visibility. Only the circle’s current members read it, and removing someone ends it at once. A member never adds or removes anyone (403 circle_creator_only); a circle you are not in reads as not found (404 circle_not_found); posting to one you are not in is 403 not_in_circle.

Swift: g.circles

Bounds. Members per circle by the account’s plan: 50, 250 on Run a business, 1,000 on Grow (429 circle_full); 100 circles per person (429 circle_limit); 300 circle changes an hour (429 too_many_changes); 500 follow requests a person has sent waiting and 1,000 waiting for them (429 request_limit). Cloud Development: 50 members, 10 circles, 60 changes, 50 and 100 requests, and 200 circles and 2,000 memberships per app (429 development_capped).

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:, as in 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.

Runs: g.runs

What an image, audio or video tool (kind generate or transcribe) answers with: a run that ends later, not an answer now. How runs reserve and settle credits is on AI tools. App sessions only: a secret key gets 403 scope_denied, no session 401 session_required.

Run carries id, tool, kind, status, progress (0 to 100, or null), key, reserved (the ceiling held at creation), held (what is still held now: reserved while open, 0 once ended), charged (null while open), units, unitCount, result: { files: [{ ref, contentType, sizeBytes, url, urlExpiresAt }], text }, data (your own pipeline's output, as sent), error, createdAt, updatedAt, endedAt and handoff (your own pipeline's delivery: { attempts, acknowledgedAt, lastError }, null for every other provider).

Swift: g.runs

The same five methods. watch takes a trailing onUpdate closure, and cancelling the calling Task stands where JS aborts a signal: it throws GemmeinError aborted with status 0.

Run has the same fields. status is a RunStatus (.queued, .running, .succeeded, .failed, .cancelled, .expired, .other(String), with isEnded); result is a RunResult { files: [RunResultFile], text: String? }; data is a JSONValue?; handoff is a RunHandoff?. A status added in a later Gemmein version arrives as .other(String), so a switch on RunStatus needs a default.

Relays: g.relays

A relay with an app_call trigger is one your app calls by name. It checks who is calling, takes the caller’s own credits (spend_credits), then does the rest. The app holds no key. The relay file, the refusals and what happens if are on A call from your app.

Swift: g.relays

Server: gemmeinServer(sk)

Swift: GemmeinServer

GemmeinServer is included 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. These answers carry the result alone, with no ok field: a refusal throws.

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

// Your own server code, on your own host (Vercel, a VPS, a cron box).
// It checks who the person is and what they hold, and can change their access.
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 lists what a person has access to. It carries no subscription status, amounts or Stripe ids, and each grant shows its source kind only, never its sourceId. Check access against what they hold, and identify people by id, never by email address.

Looking up a person by id and granting access each need a checkbox you tick when you create the key. Keys created before these options existed have both off.

Every /server/* call a resolved secret key makes, allowed or refused, is recorded against that key. The API keys page shows the summary (last used · 7-day calls · refusals), and the key's own page has the full day × route × outcome table. A refusal from a publishable pk_ key can't be attributed to a secret key, so it appears only in the request log. Grants and revokes write a full before→after entry to the logs, attributed to the key by name.

These calls can be refused with 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 code's action is in the error table.

Keys & environments

Environments are fully isolated: different data, different people, 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.

What happens if…

Limits

Every limit below is enforced by the server and returns the listed error code. Where a limit counts per IP, an IPv6 address counts by its /64.

Licences

The SDK, the MCP server and the gemmein launcher are MIT. The local runtime the launcher downloads is proprietary: run and cache it freely for building against Gemmein, and do not redistribute it. Full text at downloads.gemmein.com/engine/LICENSE.