[aicayzer]

Summary

The Swift SDK gains a client for the operations only the instance can do, in withmarfa/marfa-swift#372. This documents it: the Swift SDK page gets the MarfaAPI product and a "Call the server directly" section, "Define a type" gets a Swift tab for each step, and How Marfa works no longer says the core sends every Swift request. Merge it after the Swift SDK release that ships withmarfa/marfa-swift#372.

Part of withmarfa/marfa-swift#366.

Changes

• Swift SDK. The products table adds MarfaAPI. A new section shows Client(server), the typed type calls with links to their operations, how the other operations are named and read, what the client leaves out (any call that creates, gets, changes or deletes one item or edge, search and event calls, bulk changes, connector operations, and those for the owner's session alone) and that it still reads versions, statistics and occurrences, and how it behaves: noConnection when offline, a 30-second wait for the instance to send more that Client(server, timeout:) changes, one renewal of an expired access token, signedOut after the sign-in ends, and no redirects. It says when to use declareTypes(_:) and when register(itemType:). Handle errors adds noConnection and names Client.
• Define a type. Swift tabs for register, normalize, replace and delete, using MarfaAPI.
• How Marfa works. One sentence: the Swift SDK sends server-only operations straight to the API.

Testing

• pnpm test: 39 files, 700 tests pass, including the content lint, which resolves every new operation link.
• Every Swift example on both pages was run as written against a server booted from marfa's pinned commit, through a scratch test in the marfa-swift branch (since deleted): check and register of app.readinglist.entry, listAuditLog().ok.body.json, then decoding the guide's receipt.json into TypeDefinitionInput and TypeDefinitionUpdate, register (version 0), normalize (registered_type present), replace, delete, and a second delete refused not_found.
• Not run: pnpm build and pnpm types:check; CI runs them.

Notes for reviewers

• docs(swift-sdk): add the server catalog, replaceRefused, addFile and the plain http notice #625 and docs(swift-sdk): say a held stream refills a stale copy #626 also change swift-sdk.mdx, in other sections. Whichever merges later rebases.
• The Swift SDK changelog entry comes with the release, as for every Swift SDK release.
• Review depth: a read for accuracy against feat(package): add a client for calls only the server can do marfa-swift#372.

Checklist

• The title is a scoped Conventional Commit.
• New behavior has a test that was seen failing first, or no test was needed and the reason is above.
• Docs, comments and the contract still say what is true after this change.

[aicayzer]

Replaced by #633, which carries this change merged with the other Swift SDK 0.0.32 pull requests into one page.