Mero

The entry point to the SDK — an actor, so every instance member is awaited and token state is race-free.

import MeroKit

let mero = Mero(config: MeroConfig(
  baseURL: URL(string: "https://your-node.example")!,
  tokenStore: KeychainTokenStore()
))

Initializers

public init(config: MeroConfig)                          // uses URLSession.shared
public init(config: MeroConfig, session: URLSession)     // inject a custom session (tests)

Sub-client accessors

Computed properties that build a fresh value-type client over the shared transport:

Accessor	Type	Description
mero.auth	AuthApi	login, tokens, key management — reference
mero.admin	AdminApi	contexts, apps, namespaces, groups, blobs, TEE — reference
mero.rpc	RpcClient	execute WASM methods — reference
mero.http	any HttpClient	the transport in use (advanced)

Plus one method, not an accessor:

Method	Returns	Description
mero.events(contextIds:)	AsyncThrowingStream<ContextEvent, Error>	live SSE events — reference

Authentication

@discardableResult
func authenticate(_ credentials: Credentials? = nil) async throws -> TokenData

Authenticate with credentials (falls back to config.credentials; throws MeroError.noCredentials if neither is set). Builds a user_password TokenRequest with client name mero-swift-sdk and permissions ["admin"], calls auth.generateTokens, and persists the bundle.

Token state

var isAuthenticated: Bool                     // await mero.isAuthenticated
func currentTokenData() -> TokenData?         // current bundle (debug / handoff)
func setTokenData(_ data: TokenData)          // set directly; derives expiresAt from the JWT
func setTokenData(from callback: AuthCallbackResult)  // from a parsed SSO callback
func clearToken()                             // drop the bundle + clear the store
func logout()                                 // clearToken() + close()
func close()                                  // release long-lived actor resources

Note

All of the above are actor-isolated — call them with await (e.g. let ok = await mero.isAuthenticated).

Caution

close() (and logout()) do not stop an in-flight events(contextIds:) stream — the stream’s lifetime is owned by the Task you consume it in. Cancel that Task to close the SSE connection.

SSO statics

Synchronous, non-throwing, and also available as free helpers on SsoLogin:

static func parseAuthCallback(_ url: String) -> AuthCallbackResult?
static func buildAuthLoginUrl(nodeUrl: String, options: AuthLoginOptions) -> String

See authentication → hosted SSO.

Configuration types

MeroConfig

public struct MeroConfig: Sendable {
  public var baseURL: URL
  public var credentials: Credentials?
  public var timeout: TimeInterval          // default 10
  public var tokenStore: (any TokenStore)?  // nil → in-memory
  public init(baseURL: URL, credentials: Credentials? = nil,
              timeout: TimeInterval = 10, tokenStore: (any TokenStore)? = nil)
}

Credentials

public struct Credentials: Sendable, Equatable {
  public var username: String
  public var password: String
  public var bootstrapSecret: String?   // only for a fresh node's first login
  public init(username: String, password: String, bootstrapSecret: String? = nil)
}

TokenData

public struct TokenData: Codable, Sendable, Equatable {
  public var accessToken: String
  public var refreshToken: String
  public var expiresAt: Date   // informational; the SDK never refreshes proactively
}

On the wire these are access_token, refresh_token, and expires_at (epoch milliseconds). expiresAtFromJWT(_:fallback:) extracts exp from a JWT.

AuthCallbackResult / AuthLoginOptions

public struct AuthCallbackResult: Sendable, Equatable {
  public let accessToken, refreshToken, applicationId, contextId, contextIdentity, nodeUrl: String
}

public struct AuthLoginOptions: Sendable {
  public init(callbackUrl: String, mode: String, packageName: String? = nil,
              permissions: [String]? = nil, registryUrl: String? = nil,
              packageVersion: String? = nil)
}

Token stores

public protocol TokenStore: Sendable {
  func getTokens() -> TokenData?
  func setTokens(_ data: TokenData)
  func clear()
}

Built-in implementations:

// Secure, persisted — backed by the Keychain (Security framework)
public final class KeychainTokenStore: TokenStore {
  public init(service: String = "network.calimero.merokit",
              account: String = "mero-tokens",
              accessGroup: String? = nil,                        // shared Keychain group
              accessible: CFString = kSecAttrAccessibleAfterFirstUnlock)
}

// Ephemeral (the default when config.tokenStore is nil)
public final class MemoryTokenStore: TokenStore { public init() }

Sub-client references

• RpcClient — execute, migrateMyEntries, countMyPending.
• AdminApi — the full admin surface.
• AuthApi — the full auth surface.
• SSE events — SseClient, ContextEvent, mero.events(contextIds:).
• Capabilities — the member-capability bitmask helpers.
• MeroClient — the SwiftUI view-model (MeroKitUI).