Client

import { Client } from "@muhkoo/connect";

const client = new Client(options);

new Client(options)

Option	Type	Required	Default	Description
apiKey	string	recommended	—	App key (mk_…). Sent as X-Muhkoo-Key.
baseUrl	string	no	https://api.muhkoo.dev	Absolute accelerator URL. Trailing slash optional.
circuits	{ wasmUrl: string; zkeyUrl: string; wasmSha256?: string; zkeySha256?: string }	no	${baseUrl}/circuits/build/preimagePoK_js/preimagePoK.wasm and ${baseUrl}/circuits/build/preimagePoK_0001.zkey, with pinned SHA-256 digests	ZK circuit assets for login proofs. The default pins the digests so the assets cannot be swapped by the server they are meant to convince.
sessionStore	SessionStore	no	LocalStorageSessionStore in browsers, MemorySessionStore where localStorage is unavailable	Session-token persistence.
fetch	typeof fetch	no	globalThis.fetch	Custom fetch.
logLevel	string	no	—	SDK log verbosity (passed to the SDK logger’s setLevel).
offline	{ enabled?, store?, cacheShards?, maxQueueBytes? }	no	auto (on in browsers)	Offline cache + sync. On by default in browsers, no-op elsewhere.
accessToken	string	no	—	Machine credential (mk_<env>_at_…). Rides the same X-Muhkoo-Key header as apiKey and takes precedence over it — see access tokens.
authBaseUrl	string	no	https://auth.muhkoo.dev	Override the hosted sign-in origin (staging/dev only).
functionsHostSuffix	string	no	fns.muhkoo.dev	Override where client.functions resolves function URLs.
p2p	{ enabled?, workerFactory?, iceServers?, maxPeers?, debug? }	no	off	Peer-to-peer shard exchange between members of a Space — see storage.

All options are optional — new Client() targets the hosted accelerator.

Namespaces

Property	Type	Description
client.auth	AuthNamespace	Authentication — see client.auth.
client.kv	KvNamespace	Encrypted key/value — see client.kv.
client.db	DbNamespace	Scalable app database — see client.db.
client.storage	StorageNamespace	File storage — see client.storage.
client.vfs	VfsNamespace	The user’s filesystem: directories, paths, versions — see client.vfs.
client.message	MessageNamespace	Realtime pub/sub — see client.message.
client.space	SpaceNamespace	Group channels — see client.space.
client.offline	OfflineManager	Offline cache, status & snapshots — see client.offline.
client.agents	AgentsNamespace	Programmable Agents — see client.agents.
client.functions	FunctionsNamespace	Serverless functions — see client.functions.
client.accessTokens	AccessTokensNamespace	Scoped machine credentials — see access tokens.
client.app	AppNamespace	What the signed-in user may do in this app — see client.app.
client.vcs	VcsNamespace	Version control over the VFS: commits, branches, merges, per project.
client.trust	{ persistent; unpin(username); resetSpacePins(spaceId) }	Pinned member identities shared by every Space. unpin(username) forgets a pinned user; resetSpacePins(spaceId) clears a Space’s pins and log heads.

Properties

Property	Type	Description
client.user	{ username: string; commitment: string } | null	The signed-in user (sync read).
client.isAuthenticated	boolean	Whether a session token is active (sync read).
client.baseUrl	string	The normalized accelerator URL.

client.app

access(): Promise<AppAccess>

interface AppAccess {
  paidAccountsOnly: boolean;   // the owner turned on "Paid Muhkoo accounts only"
  allowed: boolean;            // may the signed-in user add data now?
  reason?: "user_plan_required" | "user_payment_past_due" | "owner_payment_past_due";
  upgradeUrl?: string;         // absolute portal URL to send the user to
}

Asks GET /api/app/access whether the signed-in user may add data in this app. Call it after sign-in, and again when the user returns from the portal. reason and upgradeUrl are set only when allowed is false (upgradeUrl only for user_plan_required and user_payment_past_due). Each allowed: true answer also sends any writes the offline queue kept after a payment refusal. Needs a session; throws HttpError otherwise (401 without a session, 404 against an accelerator without the route). A refused write throws PaymentRequiredError.

Session recovery

When a token-gated request comes back 401 (the session went stale), the client silently re-authenticates if it still holds the user’s identity (i.e. they logged in this session and never reloaded), then retries the request — so a transient expiry self-heals without surfacing an error.

Method	Signature	Description
client.recoverSession()	() => Promise<boolean>	Attempt a silent re-auth now. Concurrent calls share one attempt. Resolves true on success. Call proactively if you like (e.g. on visibilitychange).
client.onSessionExpired(handler)	(() => void) => () => void	Fires when recovery isn’t possible — typically after a reload that kept only a now-stale token. This is your cue to route the user to the login screen. Returns an unsubscribe fn.

const off = client.onSessionExpired(() => router.push("/login"));

SessionStore

interface StoredSession {
  token: string;
  username: string;
  commitment: string;
}

interface SessionStore {
  load(): StoredSession | null | Promise<StoredSession | null>;
  save(session: StoredSession): void | Promise<void>;
  clear(): void | Promise<void>;
}

The SDK ships LocalStorageSessionStore (browser; the default there, with an optional key prefix, muhkoo.session. by default) and MemorySessionStore (the fallback in Node, Workers and SSR, or when localStorage throws). Provide your own to persist elsewhere — see Installation.