Swift

Reference

Every public type in the Swift package, every field on it, and the JSON each one came from.

Every value the server sends decodes into a model that is Codable, Sendable and Equatable. Anything with an id is Identifiable, so it goes straight into a ForEach. Page is the one exception: it is Sendable and Equatable, and it is assembled from the response rather than decoded whole.

Dates arrive as RFC 3339 in UTC and are decoded to Date. Fractional seconds are accepted. Nothing else reaches this wire: no date only strings, no local offsets.

An optional field is null on purpose, and the reason is always a project setting. A hidden count is null rather than a misleading zero.

VoteFirst

@MainActor public enum VoteFirst. The façade. Everything on it is static.

The calls, me() through send(), are in Calls. The views are in Screens.

public struct Diagnostics: Sendable, Equatable {
    public let project: String?
    public let isLoading: Bool
    public let failure: String?
    public let pendingWrites: Int
}

Worth printing when a board is empty and you want to know why.

VoteFirstClient

public actor VoteFirstClient. One project, one voter, one queue.

An actor because its state is the anonymous token, the resolved slug and the cached identity, and every screen touches all three at once. That is why every method on it is async, and not because every method makes a request.

public init(key: String,
            host: URL = VoteFirstClient.defaultHost,
            transport: Transport = URLSessionTransport(),
            tokenStore: TokenStore = defaultTokenStore()) throws

public init(project: String,
            key: String,
            host: URL = VoteFirstClient.defaultHost,
            transport: Transport = URLSessionTransport(),
            tokenStore: TokenStore = defaultTokenStore()) throws

Both throw VoteFirstError.secretCredentialRefused for a key without the vf_pk_ prefix. That is the only reason either one throws.

The client's method names differ from the façade's in seven places, because the façade reads like the route table and the client reads like a client.

Everything else is spelled the same on both.

Board

GET /api/v3/projects/{slug}, and the document everything else is drawn against.

Three questions it answers, as an extension rather than as raw fields, because each one has more than one setting behind it.

board.allowsVoting(on: feature)   // this project, this board, and this column
board.allowsComments              // the project allows them and this plan has them
board.allowsSuggestions           // the project takes them and the form is on

allowsVoting(on:) treats a feature on a board it does not describe as votable, because the server is the authority and guessing no would hide a working button.

Project

BoardEntry, BoardRef and BoardKind

A project has the roadmap, which every project has, and any custom boards it made public.

public struct BoardEntry {
    public var id: Int
    public var slug: String
    public var name: String
    public var kind: BoardKind
    public var columns: [Column]
}

The roadmap is always id 0, slug "roadmap", kind .roadmap. A custom board carries its own id and slug, and kind .custom.

BoardRef is the same thing without the columns, which is what a feature carries: id, slug, name, kind.

BoardKind is a string with two known values on it rather than an enum, so a kind added later does not fail the decode.

BoardKind.roadmap    // "roadmap"
BoardKind.custom     // "custom"

Column and ColumnRef

ColumnRef is what a feature carries: id, name, color.

A custom board decides voting for the whole board at once, so every column on it carries the same isVotable. The roadmap decides per column.

Tag

id and name. The ids are what FeatureQuery(tagIDs:) takes.

DisplaySettings

What the owner publishes. Every one of these is a Bool except the last.

Capabilities

What this caller may do, which is the project's settings folded with its plan.

canVote, canComment, canSuggest, canLike, all Bool, from can_vote and so on.

Use board.allowsVoting(on:) rather than these directly. It reads both these and the display settings, which is what the server does before it accepts a vote.

BoardTheme and ThemePalette

public struct BoardTheme {
    public var dark: ThemePalette
    public var light: ThemePalette
    public var font: String?
    public var radius: String?
}

public struct ThemePalette {
    public var background: String
    public var text: String
    public var textSecondary: String   // text_secondary
    public var accent: String
    public var cardBackground: String  // card_background
    public var border: String
}

Colours are CSS strings, #RGB, #RRGGBB or #RRGGBBAA. The radius is written the way CSS writes it, "8px". The built in views read all of it for you; a custom interface can too.

Feature

public var isDenial: Bool
public func applying(_ result: VoteResult) -> Feature

isDenial says whether the owner's answer turned this feature down, which the status alone cannot: archiving a declined feature reports it as archived and takes the refusal with it.

applying returns the same feature carrying the vote the server just recorded. A result for another id is ignored. A result with no count leaves the count alone.

FeatureRef and ReleaseRef are the two shorthands: an id with a heading, and an id with a name.

FeatureStatus

A string with six known values, not an enum, so a status added later does not fail the decode.

FeatureStatus.open        // "open"
FeatureStatus.planned     // "planned"
FeatureStatus.inProgress  // "in_progress"
FeatureStatus.done        // "done"
FeatureStatus.denied      // "denied"
FeatureStatus.archived    // "archived"
FeatureStatus.allCases    // the six, in that order

The column's own name is what a person should read. The status is what code should branch on, because an owner can rename a column and the status stays put.

Comment

public func applying(_ result: LikeResult) -> Comment

Release and ReleaseFeature

ReleaseFeature is id, heading, voteCount and changelogType. Only completed features appear in a release.

Message

message.action answers the label and the URL together, and only when both halves arrived and the address carries a scheme worth opening. MessageKind and MessagePresentation are raw value structs rather than enums, for the same reason BoardKind is: a value added later must not fail the whole decode.

MessageDismissed is messageID and dismissed, which is always true.

Identity

Write results

public struct VoteResult {
    public var featureID: Int    // feature_id
    public var hasVoted: Bool    // has_voted
    public var voteCount: Int?   // vote_count
    public var score: Int?       // score
}

public struct LikeResult {
    public var commentID: Int    // comment_id
    public var hasLiked: Bool    // has_liked
    public var likeCount: Int    // like_count
}

public struct CommentDeleted {
    public var featureID: Int      // feature_id
    public var deleted: Bool       // deleted
    public var commentCount: Int?  // comment_count
}

VoteResult.voteCount is nil in two cases and they mean the same thing to a caller: the project hides vote counts, or nothing changed because the vote was already in the state you asked for. Either way, the count you already have still stands.

FeatureQuery

public init(sort: Sort = .top,
            scope: Scope = .roadmap,
            column: Int? = nil,
            tagIDs: [Int] = [],
            statuses: [FeatureStatus] = [],
            search: String? = nil,
            page: Int = 1,
            perPage: Int = 20)

public func page(_ number: Int) -> FeatureQuery

What reaches the wire:

The sorts and the scopes are listed in Calls.

Page and PageMeta

public struct Page<Element> {
    public let items: [Element]
    public let meta: PageMeta
    public var hasMore: Bool
    public var nextPage: Int?
}

public struct PageMeta {
    public let page: Int
    public let perPage: Int    // per_page
    public let total: Int
    public let totalPages: Int // total_pages
    public let hasMore: Bool   // has_more
}

Errors

VoteFirstError, APIFailure and ErrorCode are in Errors, field by field.

Transport

public protocol Transport: Sendable {
    func send(_ request: URLRequest) async throws -> (Data, HTTPURLResponse)
}

The seam a test replaces. URLSessionTransport is the one that ships.

public init(memoryCapacity: Int = 4 * 1024 * 1024, diskCapacity: Int = 20 * 1024 * 1024)
public init(session: URLSession)

See Testing for the stub.

TokenStore

public protocol TokenStore: Sendable {
    func token(forProject project: String) -> String?
    func setToken(_ token: String?, forProject project: String)
}

PendingWrite

public struct PendingWrite: Codable, Sendable, Equatable, Identifiable {
    public let id: String
    public let method: String
    public let path: String
    public let body: Data?
    public let queuedAt: Date
    public var idempotencyKey: String { id }
}

The id is the idempotency key the write was first attempted with, which is what makes replaying it safe.

VoteFirstStorage

public static func directory(project: String) -> URL?
public static func cacheDirectory() -> URL?

Application support rather than user defaults, because reading user defaults is a required reason API and putting anything there would oblige your app to declare it. See Privacy.

Theme, Palette and Configuration

Theme is your overrides, Palette is what the views draw with once the overrides, the board's palette and the system colours have been laid over one another, and Configuration is the support address and the two links. All three are in Screens.

What is on disk

Under Application Support/VoteFirst/{project}/:

And Caches/VoteFirst/ for the HTTP cache.

{project} is your slug, or key-{digest} when the key named its own board. Everything but the cache is per project, which is why two projects in one app keep two voters.

Next