Sign-in and server calls

The working copy answers from the device. Some calls need the instance itself: signing in, reading an item's history, changing the instance's settings and registering types. Each needs a connection and is never queued. With the device offline, a call throws noConnection and sends nothing.

Sign inCopy anchor link

An app can use a key the person pastes in, or ask the owner to approve it. Authorization signs the app in with the owner's approval and keeps the sign-in in the keychain. The app never sees the owner's password, and the approval stands until the owner revokes it.

let auth = try Authorization(
    server: serverURL,
    client: .init(
        name: "Reading List",
        redirect: URL(string: "com.example.readinglist:/signed-in"),
        scopes: ["core.note:read", "core.note:write"]),
    service: "com.example.readinglist")

let credential: Credential
if let kept = try auth.credential() {
    credential = kept
} else {
    credential = try await auth.signIn(presentingFrom: window)
}
let server = try Server(url: serverURL, credential: credential)
let copy = try await WorkingCopy.open(store: storeURL, server: server)

• redirect is a private-use address whose scheme is a reverse domain name you control, with a path and no host. Claim the scheme in the app's CFBundleURLTypes.
• scopes are what the app asks for. The owner may approve fewer, and Credential.scopes says which. offline_access is added for you, so the sign-in lasts.
• The copy renews the sign-in whenever the server refuses its access token. Renewals run one at a time across every copy in the process, and across an app and its extensions that share a Keychain(accessGroup:).

Signing in again ends the grant of the sign-in it replaces for the same server, as signOut() does, so each sign-in leaves one approval among the owner's connected apps. A sign-in that reused the kept sign-in's registered client shares its grant, so only the old access token is revoked. The new sign-in is kept either way, and its Credential.replacedGrantStands is true when the server didn't confirm the replaced grant ended, such as when it couldn't be reached: tell the person to remove the old approval. A credential read with credential() always answers false.

A sign-in that doesn't finish throws a SignInError:

Once the server ends a sign-in, the copy's calls throw signedOut: sign in again. Authenticate explains the flow, and Approve an app what the owner approves.

Calls on the serverCopy anchor link

A Server makes these calls with the key or sign-in it holds. Each waits 20 seconds in all, renewing a sign-in included, then throws network. Pass timeout: to change it.

Pass expecting: the instanceID from config() when a change must reach the instance the person saw. Where another instance now answers at the address, the change throws instanceChanged and changes nothing.

Read an item's historyCopy anchor link

The working copy keeps no history, so a snapshot is read from the server. Each ItemSnapshot holds the item's version, type, tier, properties, occurredAt and sourceID before a write replaced them, the writer that made that write, and createdAt, when it did.

var page = try await server.snapshots(ofItem: id)
var history = page.snapshots
while let next = page.next {
    page = try await server.snapshots(ofItem: id, after: next)
    history += page.snapshots
}

• Stop only when next is nil. A page can be short, or empty, with more to follow.
• limit is 1 to 200. Without one, the server's default applies.
• A Writer has a kind: .browser, .app, .key, .local for the command on the server's machine, or .other for a kind the SDK doesn't know. writer is nil for a change the server made itself.
• An item in the bin, or of a type the key doesn't reach, throws notFound.

Change the settingsCopy anchor link

Each field of an InstanceConfigPatch is a SettingChange: .set(value), or .clear to return to the server's default. A field left nil isn't sent, so the instance keeps it. In an InstanceConfig, nil means the default applies. Change settings while it runs explains each setting.

let settings = try await server.config()
var patch = InstanceConfigPatch()
patch.trashRetentionDays = .set(60)
_ = try await server.updateConfig(patch, expecting: settings.instanceID)

The API clientCopy anchor link

Client from the MarfaAPI product makes the operations the working copy doesn't: registering, changing and deleting types, managing keys and webhooks, and reading statistics, occurrences and the audit log. It uses the same Server as the copy:

import MarfaAPI

let api = Client(server)
let title = Components.Schemas.FieldDefinition(_type: .string, required: true)
let entry = Components.Schemas.TypeDefinitionInput(
    fields: .init(additionalProperties: ["title": title]),
    id: "app.readinglist.entry")

_ = try await api.check(itemType: entry)
_ = try await api.register(itemType: entry)

Every other operation is a method named after its operation ID, such as listAuditLog(). A refusal throws a MarfaError, so read a success from the answer's ok case: try await api.listAuditLog().ok.body.json.

• The client has no call for one item or edge, for search or for events. Those go through the working copy, so each item has one path.
• A call waits 30 seconds for the answer to start, and again between the parts of a streamed body, then throws network. Pass Client(server, timeout:) a longer time for a call that answers only when its work is done, such as runHousekeeping.
• A refused access token is renewed once and the call sent again. Once the server ends the sign-in, calls throw signedOut.
• It never follows a redirect, so the credential reaches no other host.
• A delete of a type that an item, folder, view or webhook still names throws server with status 409 and the code type_in_use. Its message ends with the settings that name the type.

declareTypes(_:) registers an app's types when the copy fills, which suits an app that must start offline. Use register(itemType:) when the app needs the type on the instance now.

Move the items of a typeCopy anchor link

A type's ID never changes, so renaming a type means registering the new one, moving the items and deleting the old one. The move is a job on the instance. It gives every item of the type that the credential can see, in any state, the new type. Once none remains, it rewrites the folders, views and webhooks that name the old type.

let preview = try await api.previewMove(ofType: "app.deal", to: "app.contract")
let started = try await api.startMove(
    ofType: "app.deal", to: "app.contract", properties: ["stage": "signed"])
let job = try await api.follow(moveJob: started.id)
if job.status == .completed, job.result?.settingsRewritten == true {
    try await api.delete(itemType: "app.deal")
}

Check the job's status and result before you delete the old type. remaining counts the items left, and remainingHidden says whether the credential can't see some of them. settingsRewritten is true only when no item remains and no setting is blocked. To finish a move that left items behind, run it again.

A move throws server with the code type_move_blocked when a setting names the type in a way it can't rewrite, and moves nothing.

Draw a type's iconCopy anchor link

A type's icon is an Iconify ID from one of the two icon sets Marfa pins: lucide:book-open from Lucide, or simple-icons:github for a brand mark from Simple Icons. ItemType.icon holds the icon the type resolves to: the owner's choice for the type or its nearest parent, else the nearest author's. It's nil when no type in the chain sets one. Display hints explains.

The MarfaIcons product draws the ID:

import MarfaIcons

TypeIcon(type)                   // from an ItemType
TypeIcon(id: "lucide:book-open") // from an ID
Image(typeIcon: type.icon)       // where a view needs an Image

• A lucide: ID draws the SF Symbol that stands for it, or Lucide's own artwork, shipped in the package, where no symbol suits.
• Brand marks need the MarfaBrandIcons product. Call MarfaBrandIcons.register() once at launch, before any icon draws. Without it, an app ships none of the artwork.
• Every icon tints with foregroundStyle, follows light and dark appearance, and sizes with the surrounding font.
• A nil ID, or one the SDK can't draw, draws a fallback symbol and never fails, since a newer instance can send an ID this SDK doesn't know.

LucideIconSet.ids and MarfaBrandIcons.ids list every ID the instance accepts, for an app that lets the person choose.

Change a type's iconCopy anchor link

The owner can choose the icon of any type, including one Marfa ships. setTypeIcon(_:ofType:) returns the icon the type has now:

let entry = "app.readinglist.entry"
let icon = try await server.setTypeIcon("lucide:scale", ofType: entry)
// Show the author's icon again:
try await server.setTypeIcon(nil, ofType: entry)

• It needs schema.write and write on the type. Without them, it throws forbidden.
• An ID outside the pinned sets throws validation with the code invalid_schema.
• Other devices show the change within about two minutes, when their copy's catalog next reads the instance's types.