Overview - Marfa

The Swift SDK is a Swift Package Manager library for Apple platforms. It exposes three client modes over the same API surface — a remote HTTP client, a pure-local on-device store, and a synced mode that queues writes locally and replays them against a server. Swift 6 concurrency throughout. Repository: withmarfa/swift-sdk. Pin to the major version that tracks your server. Platforms: iOS 26+, iPadOS 26+, macOS 26+, watchOS 26+, tvOS 26+, visionOS 26+. On-device storage uses SwiftData — no third-party runtime dependencies.

Install

In Package.swift:

dependencies: [
  .package(url: "https://github.com/withmarfa/swift-sdk.git", from: "x.y.z"),
]

Or in Xcode: File → Add Package Dependencies → https://github.com/withmarfa/swift-sdk.git.

Three client modes

One SDK, three factories. Pick the one that matches your app:

Remote
Pure-local
Synced

A thin typed HTTP client. Every call hits the server.

import MarfaSDK

let client = MarfaClient(
  url: URL(string: "https://marfa.example.com")!,
  apiKey: "marfa_k1_..."
)

let note = try await client.items.create(
  CreateItemInput(type: "core.note", properties: ["body": .string("Hello")])
)

Best for: server-first apps, scripts, CI, server-to-server integrations.

SwiftData-backed on-device store. No server, no API key. Same namespace surface — every call resolves against the local store.

let client = try await MarfaClient.local(path: "/path/to/store.sqlite")

let note = try await client.items.create(
  CreateItemInput(type: "core.note", properties: ["body": .string("Offline")])
)

Best for: offline-first apps, privacy-first apps, prototyping before adding a server.

Server-only namespaces — blobs, types, keys, webhooks — throw LocalModeUnsupportedError on a pure-local client. client.blobs.url(hash:) is the lone exception; it returns a constructed URL without touching the network.

For iCloud sync, build the container yourself with MarfaModelContainer.make(path:cloudKitDatabase: .automatic(containerIdentifier: "iCloud.example.app")) and pass it to MarfaClient.local(container:). The schema is CloudKit-compatible from day one.

Writes hit the local store first (optimistic) and replay against the server in the background. SSE keeps the local store fresh from the server.

let client = try await MarfaClient.synced(
  url: URL(string: "https://marfa.example.com")!,
  apiKey: "marfa_k1_...",
  storePath: "/path/to/store.sqlite"
)

await client.syncEngine?.start()

// Writes are instant and durable even offline
let note = try await client.items.create(
  CreateItemInput(type: "core.note", properties: ["body": .string("Hello")])
)

Best for: user-facing apps that need instant UI, offline tolerance, and multi-device consistency.

Two more factories cover common auth patterns:

MarfaClient.fromEnvironment() — reads MARFA_API_URL and MARFA_API_KEY. Returns nil if unset.
MarfaClient.fromKeychain(service:account:url:accessGroup:) — loads the API key from the system Keychain. Pair with client.saveToKeychain(service:account:accessGroup:) to persist one.

Configuration

ClientConfiguration controls retry, timeout, conflict strategy, and CDN routing:

var config = ClientConfiguration(url: url, apiKey: key)
config.conflictStrategy = .auto         // or .manual, .callback
config.timeoutInterval = 30
config.resourceTimeout = 120
config.cdnBaseURL = URL(string: "https://cdn.marfa.example.com")  // optional
config.debugLogging = true              // full-body logging at .private

let client = MarfaClient(configuration: config)

retryPolicy on the configuration controls retry behavior for transient errors — bounded exponential backoff with jitter.

Where next

The rest of the Swift SDK surface splits across five focused pages: Authentication for OAuth 2.1 and Keychain helpers, Data access for items / edges / metadata / extensions / blobs / search, Typed models for CoreNote and custom-type codegen, Sync engine for SwiftUI reactive queries and the SSE replay loop, and Errors and testing for conflict handling, error types, and MarfaSDKTestSupport.

​Install

​Three client modes

​Configuration

​Where next

Install

Three client modes

Configuration

Where next