Network

An app's backend API layer, written as a local Swift package from one compact line an endpoint, shipped as a Granite agent package. A call says each endpoint the way a person would jot it down and each type in ModelsAgent's line; the package writes the typed client of that API into Packages/<Name>: a Sendable client whose base URL changes while the app runs, a transport and a mock, auth with tokens kept per host in the Keychain, requests with path, query, JSON and multipart bodies, a typed method an endpoint, the DTOs, paging as an AsyncSequence, errors and retries, RSS/Atom/JSON Feed when asked, and tests that run. Then it links the package into the project. Swift 6, iOS 17 and macOS 14, no dependencies.

It is one of the Rao Craft Agents: independent packages that, tagged in prompts along the life of a project, build an app of Loom's quality. network writes the clients Loom's kits are (a Lemmy-like API with a JWT and page paging, a Mastodon-like one paged by its Link header, feeds, an IPFS-like upload), from lines, for any API.

How an app finds it

NetworkAgent is a GraniteAgentPackage, and it carries a record in its binary:

@used @section("__DATA_CONST,__granite")
let networkRecord: GraniteRoster.Record = { GraniteRoster.record(NetworkAgent.self) }

In Craft, install it from the Agent Store or with craft agents add https://github.com/Rao-Craft-Agents/NetworkAgent.git, then say $network in a request:

$network the recipe API at api.recipes.example: sign in with email and password for a bearer token, the recipes
page by page, one recipe, create and delete one, and a photo upload

The model writes the lines; the call shows on Craft's agent map as network-1, and the files it names are built and tested with the turn.

What a call takes and answers

The answer is a NetworkResult: every file written (path, paths, absolute, the project file included when it was linked), the package's folder, the client type, its endpoint methods, the types, what it was linked into, and a sentence for anything else it did.

The line

POST /v1/session body(Credentials) -> Session as signIn stores token
GET /v1/recipes?page,per_page,course:Course -> RecipePage as recipes paged "the newest recipes first"
GET /v1/recipes/{id:Int} -> Recipe as recipe
DELETE /v1/recipes/{id:Int} as deleteRecipe
POST /v1/photos multipart(photo, caption:String?) -> Photo as Media.uploadPhoto
GET /v1/timeline?max_id,limit -> [Post] as timeline paged

• A method, a path and its query. {id} is a String path parameter, {id:Int} a typed one. The query is ?name,name:Type: each an optional argument of the method, a String unless typed (page, limit, per_page, offset are Int), required with a trailing !. The Swift name is the wire name in camelCase (community_id is communityID), and the wire name is what is sent.
• Then, in any order: body(Type) (JSON) or multipart(field, …) (a bare name is a file; name:[File] several; name:Type a text field, optional with ?), -> Type (Data is the bytes, String the text; none is a 204), as name or as Group.name, paged or paged(field), stores token or stores token(field), and a quoted doc.
• The group is the file an endpoint goes in (Endpoints/<Group>.swift): the name before the dot, else the path's first segment after api and a version, plural when a type has its name (Endpoints/Posts.swift beside Models/Post.swift).
• Every type a line names is a primitive or has an entity line. A line it cannot read, a type no line declares, a paged endpoint with no page or cursor, a token with nowhere to come from: each is refused with the reason, every one at once, and nothing is written.

How the package is made

No model is asked: the same lines make the same package every time.

Testing

swift test                     # the record, the schema, the lines, the files, the links, the record across calls
NETWORK_BUILD=1 swift test     # Lemmy-like, Mastodon-like, feeds and IPFS-like packages built, their own tests run,
                               # built for the iOS simulator; one linked into an Xcode project built for macOS and iOS

MIT licensed.