Reference

Swift API

Use this reference to look up a signature, then follow the linked task guide for integration. It covers the public SDK declarations, protocol requirements, enum cases, and public decoding/raw-value initializers. Each entry has an explicit anchor. Swift-generated protocol witnesses such as equality and hashing use their standard Swift behavior.

View Markdown

Choose an API

Configure a client and load your own UI.
Present community or support chat.
Install identity and submit private feedback.
Style views, override labels, or configure paywalls.
Queue writes, cache reads, or parse links.
Configure push and route notification taps.

Response structs without an explicit public value initializer are read from the client or a Decoder; do not rely on an internal memberwise initializer. Observable models and the paywall controller run on the main actor. Published properties documented with { get } are externally read-only; their $property projections expose observation, not permission to mutate.

ReadCommunity.swift

import AppNorth

func firstCommunityPage(client: AppNorthClient) async throws -> AppNorthPage<AppNorthIdea> {
    let boards = try await client.boards()
    return try await client.ideas(board: boards.first?.slug, sort: .top)
}

AppNorthTokenProviding

Supplies a stable anonymous token. A custom provider must be safe for concurrent access and return a token accepted by the server.

protocol AppNorthTokenProviding : Sendable

`token()`

func token() -> String

AppNorthAnonymousToken

Thread-safe anonymous voter token backed by UserDefaults. The default key is appnorth.voter; a valid legacy token is migrated. Removing stored data or using another installation can create a different token. This is not verified identity.

final class AppNorthAnonymousToken

`init(defaults:key:)`

init(defaults: UserDefaults = .standard, key: String = "appnorth.voter")

`token()`

func token() -> String

AppNorthViewModel

Main-actor observable community state. Optional read caching applies to initial load; recreate the model after account changes to discard previously loaded arrays.

@MainActor final class AppNorthViewModel

`boards`

@Published @MainActor var boards: [AppNorthBoard] { get }

`ideas`

@Published @MainActor var ideas: [AppNorthIdea] { get }

`isLoading`

@Published @MainActor var isLoading: Bool { get }

`error`

@Published @MainActor var error: AppNorthError? { get }

`showWatermark`

@Published @MainActor var showWatermark: Bool { get }

`selectedBoard`

@Published @MainActor var selectedBoard: String? { get set }

`sort`

@Published @MainActor var sort: AppNorthIdeaSort { get set }

`client`

@MainActor let client: AppNorthClient

`init(client:cache:)`

@MainActor init(client: AppNorthClient, cache: AppNorthReadCache? = nil)

`load()`

@MainActor func load() async

Loads fresh cached values if available, then boards and the first idea page; loads branding independently.

`reloadIdeas()`

@MainActor func reloadIdeas() async

Reloads the first idea page for the selected board and sort and stores successful results in the optional cache.

AppNorthView

Complete native community screen with its own navigation stack, board/sort controls, idea details, creation, and optional floating chat entry. Loads the first idea page.

@MainActor struct AppNorthView

`init(client:copy:theme:uiConfiguration:cache:paywalls:)`

@MainActor init(client: AppNorthClient, copy: AppNorthCopy = .init(), theme: AppNorthTheme = .init(), uiConfiguration: AppNorthUIConfiguration = .init(), cache: AppNorthReadCache? = nil, paywalls: AppNorthPaywalls? = nil)

`body`

@MainActor var body: some View { get }

The content and behavior of the view. When you implement a custom view, you must implement a computed body property to provide the content for your view. Return a view that's composed of built-in views that SwiftUI provides, plus other composite views that you've already defined: struct MyView: View { var body: some View { Text("Hello, World!") } } For more information about composing views and a view hierarchy, see doc:Declaring-a-Custom-View.

AppNorthScreenshotCapturing

Host-supplied capture adapter. Return a supported base64 image data URL; the SDK provides no automatic screen capture.

protocol AppNorthScreenshotCapturing : Sendable

`capture()`

func capture() async throws -> String

AppNorthScreenshotRedacting

Host-supplied redaction adapter. Return a changed, valid image data URL; unchanged output is rejected by the capture helper.

protocol AppNorthScreenshotRedacting : Sendable

`redact(_:)`

func redact(_ screenshot: String) async throws -> String

AppNorthChatEntry

A displayed chat row, including local delivery state. Obtain entries from AppNorthChatModel; there is no public memberwise initializer.

struct AppNorthChatEntry

`id`

var id: String

The stable identity of the entity associated with this instance.

`sender`

let sender: AppNorthChatMessage.Sender

`body`

let body: String

SwiftUI view content. Present the view itself rather than invoking this property directly.

`actionCard`

var actionCard: AppNorthActionCard?

`openedAt`

var openedAt: String?

`tappedAt`

var tappedAt: String?

First review-card tap recorded by the server; this does not confirm a submitted review.

`state`

var state: AppNorthChatEntry.State

`images`

var images: [AppNorthChatImage]

Photos shown with the optimistic or delivered bubble. Failed sends retain their photos for retry.

AppNorthChatEntry.State

Local delivery state: sending, sent, or failed. Failed entries can be retried with their original key.

enum State

`sent`

case sent

`sending`

case sending

`failed`

case failed

AppNorthChatModel

Main-actor conversation model with optimistic entries and retry handling. A custom owner must stop polling while hidden or inactive and discard the model on account changes. See support chat.

@MainActor final class AppNorthChatModel

`maximumLength`

@MainActor static let maximumLength: Int

`entries`

@Published @MainActor var entries: [AppNorthChatEntry] { get }

`isAvailable`

@Published @MainActor var isAvailable: Bool { get }

`hasLoaded`

@Published @MainActor var hasLoaded: Bool { get }

`lastLoadFailed`

@Published @MainActor var lastLoadFailed: Bool { get }

`init(client:paywalls:)`

@MainActor init(client: AppNorthClient, paywalls: AppNorthPaywalls? = nil)

`startPolling()`

@MainActor func startPolling()

Starts a refresh loop at five-second intervals; cancels any earlier polling task.

`stopPolling()`

@MainActor func stopPolling()

Cancels polling. Call when your custom chat screen hides or becomes inactive.

`refresh()`

@MainActor func refresh() async

Fetches and merges server messages, updating availability and failure state. Discards results for a changed identity scope.

`send(_:images:)`

@discardableResult @MainActor func send(_ text: String, images: [AppNorthChatImageUpload] = []) -> Bool

Trims text and caps it at 2,000 Swift characters. Returns true when a local entry was queued, not when delivery succeeds.

`retry(_:)`

@MainActor func retry(_ entry: AppNorthChatEntry)

Retries a failed entry with its original idempotency key.

AppNorthChatView

Native conversation content. Owns a model and visible/foreground polling; your app supplies presentation and dismissal. Accepts copy, theme, and an optional paywall controller.

@MainActor struct AppNorthChatView

`init(client:copy:theme:paywalls:)`

@MainActor init(client: AppNorthClient, copy: AppNorthCopy = .init(), theme: AppNorthTheme = .init(), paywalls: AppNorthPaywalls? = nil)

`body`

@MainActor var body: some View { get }

AppNorthHTTPTransport

Implement this protocol for a custom transport or deterministic tests. URLSession already conforms. Return both response bytes and the HTTP response; transport errors become AppNorthError.network.

protocol AppNorthHTTPTransport : Sendable

`data(for:)`

func data(for request: URLRequest) async throws -> (Data, URLResponse)

AppNorthClient

A Sendable HTTP client. Copies share the same in-memory identity store. Both initializers support an anonymous token provider, an optional credential, and an injectable clock. See custom UI.

struct AppNorthClient

`configuration`

let configuration: AppNorthConfiguration

`init(configuration:session:tokenProvider:identityCredential:clock:)`

init(configuration: AppNorthConfiguration, session: URLSession = .shared, tokenProvider: any AppNorthTokenProviding = AppNorthAnonymousToken(), identityCredential: AppNorthIdentityCredential? = nil, clock: @escaping @Sendable () -> Date = { Date() })

`init(configuration:transport:tokenProvider:identityCredential:clock:)`

init(configuration: AppNorthConfiguration, transport: any AppNorthHTTPTransport, tokenProvider: any AppNorthTokenProviding = AppNorthAnonymousToken(), identityCredential: AppNorthIdentityCredential? = nil, clock: @escaping @Sendable () -> Date = { Date() })

`setIdentityCredential(_:)`

func setIdentityCredential(_ credential: AppNorthIdentityCredential)

Replaces the in-memory credential for subsequent requests. Does not recreate screens or clear host storage.

`clearIdentityCredential()`

func clearIdentityCredential()

Removes the credential only. Dismiss and discard account-specific views and storage separately.

`hasValidIdentity(at:)`

func hasValidIdentity(at date: Date = Date()) -> Bool

Checks that a credential exists and has not expired at the supplied date; does not verify its signature.

`canParticipate(_:at:)`

func canParticipate(_ policy: AppNorthParticipation, at date: Date = Date()) -> Bool

Evaluates the policy against local credential expiry. The server makes the authorization decision.

`boards()`

func boards() async throws -> [AppNorthBoard]

Returns the project’s boards, statuses, and policies.

`widgetConfig()`

func widgetConfig() async throws -> AppNorthWidgetConfig

Loads public presentation configuration independently of community data.

`ideas(board:status:query:sort:cursor:limit:)`

func ideas(board: String? = nil, status: String? = nil, query: String? = nil, sort: AppNorthIdeaSort = .top, cursor: String? = nil, limit: Int = 20) async throws -> AppNorthPage<AppNorthIdea>

Returns one page. Limit defaults to 20 and is clamped to 1–50. Preserve filters when reusing the opaque cursor.

`idea(_:)`

func idea(_ handle: String) async throws -> AppNorthIdea

Loads one idea by ID or slug.

`comments(for:cursor:limit:)`

func comments(for handle: String, cursor: String? = nil, limit: Int = 20) async throws -> AppNorthPage<AppNorthComment>

Returns a paginated comment list for an idea ID or slug; limit is clamped to 1–50.

`createIdea(board:title:description:authorName:idempotencyKey:)`

func createIdea(board: String, title: String, description: String = "", authorName: String? = nil, idempotencyKey: String = UUID().uuidString) async throws -> AppNorthCreation<AppNorthIdea>

Creates an idea. Retain the same idempotency key and payload on retries; inspect the moderation flag.

`setVote(on:voted:)`

func setVote(on handle: String, voted: Bool) async throws -> AppNorthVote

Sets the desired vote state, returning the resulting state, count, and whether it changed.

`createComment(on:body:authorName:idempotencyKey:)`

func createComment(on handle: String, body: String, authorName: String? = nil, idempotencyKey: String = UUID().uuidString) async throws -> AppNorthCreation<AppNorthComment>

Creates a comment. Preserve key and payload on retries; inspect the moderation flag.

`createFeedback(_:idempotencyKey:)`

func createFeedback(_ input: AppNorthCreateFeedback, idempotencyKey: String = UUID().uuidString) async throws -> AppNorthFeedbackReceipt

Submits private feedback and returns its receipt. Reuse the same key only for the same user intention.

`feedbackThread(_:)`

func feedbackThread(_ id: String) async throws -> AppNorthFeedbackThread

Requires a signed credential and server-verified ownership. Returns only the report and public staff replies.

`chatStatus()`

func chatStatus() async throws -> AppNorthChatStatus

Reads availability and unread state without marking messages read.

`chatMessages(after:)`

func chatMessages(after: String? = nil) async throws -> AppNorthChatThread

Reads messages and marks team replies read. Pass a server message ID as after for newer messages.

`sendChatMessage(_:imageTokens:idempotencyKey:)`

func sendChatMessage(_ body: String, imageTokens: [String] = [], idempotencyKey: String = UUID().uuidString) async throws -> AppNorthChatMessage

Sends chat text and up to three uploaded image tokens. Text may be empty when images are attached. Reuse the key and tokens when retrying the same message.

`registerPushToken(_:environment:)`

func registerPushToken(_ token: Data, environment: AppNorthPushEnvironment) async throws

Registers the raw APNs device token for the current chat identity. Call after APNs supplies a token and again after an identity change. Pass the APNs environment matching your app's signing configuration. Empty tokens or tokens larger than 256 bytes throw AppNorthError.invalidConfiguration before a request is made.

`unregisterPushToken(_:environment:)`

func unregisterPushToken(_ token: Data, environment: AppNorthPushEnvironment) async throws

Removes the token registration using the current identity and the same environment used to register it. Await this before clearing the signed identity on logout. Token validation matches registration; request failures propagate so your app can retry.

`reportPaywalls(_:idempotencyKey:)`

func reportPaywalls(_ snapshot: AppNorthPaywallSnapshot, idempotencyKey: String = UUID().uuidString) async throws

Replaces the reporter’s device snapshot. Reuse the same key for a retry.

`markActionCardOpened(_:)`

func markActionCardOpened(_ messageId: String) async throws

Reports first display for review cards and first tap for offer cards with a deterministic card-open-<messageId> key. Does not report a purchase or a submitted review.

`markActionCardTapped(_:)`

func markActionCardTapped(_ messageId: String) async throws

Reports a review-card tap using the deterministic card-tap-<messageId> key. It does not invoke StoreKit or confirm that its prompt appeared.

`uploadChatImage(_:contentType:)`

func uploadChatImage(_ data: Data, contentType: String = "image/jpeg") async throws -> AppNorthChatImageUpload

Uploads up to 5 MB of JPEG, PNG or WebP through a signed storage PUT and completes server-side pixel validation and metadata removal. Custom UIs prepare their own resized pixels; the built-in iOS picker handles this automatically. Pass the returned imageToken in sendChatMessage(_:imageTokens:idempotencyKey:). At most three image tokens may accompany a message; its text may be empty. Keep the same tokens and idempotency key on retry. See Photos in chat.

AppNorthPushEnvironment

enum AppNorthPushEnvironment: String, Codable, Sendable

Choose the APNs environment matching your app's signing configuration; the SDK does not infer it.

`sandbox`

case sandbox

`production`

case production

AppNorth

@MainActor enum AppNorth

Optional push facade for one configured chat client at a time. Your app owns notification permission prompts, APNs registration, its notification-center delegate, and navigation. The SDK does not swizzle callbacks. See the push chat example.

`configurePush(client:environment:badgeHandler:routeHandler:)`

swift

@MainActor static func configurePush(
    client: AppNorthClient,
    environment: AppNorthPushEnvironment,
    badgeHandler: @escaping @MainActor (Int) -> Void,
    routeHandler: @escaping @MainActor (AppNorthLink) -> Void
)

Stores the same client used by chat, the APNs environment, and your callbacks. badgeHandler receives 0 or 1 to indicate unread chat replies, not a message count; combine it with any other badge sources in your app. routeHandler receives accepted chat destinations and must present your chat UI.

`registerPushToken(_:)`

@MainActor static func registerPushToken(_ token: Data) async throws

Forwards the raw token to the configured client's registerPushToken(_:environment:). Throws AppNorthError.invalidConfiguration if configurePush has not been called. Call again after changing the chat identity.

`unregisterPushToken(_:)`

@MainActor static func unregisterPushToken(_ token: Data) async throws

Forwards removal to the configured client and environment. Await before logout or disabling push; failures propagate for retry. Throws AppNorthError.invalidConfiguration without a configured client.

`handleNotificationTap(_:)`

@discardableResult @MainActor static func handleNotificationTap(_ userInfo: [AnyHashable: Any]) -> Bool

Pass the notification response's userInfo. Returns true and invokes routeHandler only when the appnorth payload has type: "chat", an appId equal to the configured client's configuration.appId, and a parseable chat URL using the appnorth scheme. Unconfigured, foreign-app, and malformed payloads return false without routing. It does not open a screen or authenticate the user.

`syncUnreadBadge()`

@discardableResult @MainActor static func syncUnreadBadge() async throws -> Int

Fetches chatStatus() and returns 1 only when chat is available and has unread replies; otherwise returns 0. Calls badgeHandler only if the identity scope and push configuration are still current. Request failures preserve the existing badge and propagate. Throws AppNorthError.invalidConfiguration without a configured client. Call on foreground and after reading with a custom UI; built-in chat also calls it after a successful read.

`resetPush()`

@MainActor static func resetPush()

Calls the current badge handler with 0 and releases the client and callbacks. This only resets local state: await unregisterPushToken(_:) before resetting and clearing identity to remove the server registration.

AppNorthColorPair

A light/dark SwiftUI color pair, or one color shared by both appearances.

struct AppNorthColorPair

`light`

var light: Color

`dark`

var dark: Color

`init(light:dark:)`

init(light: Color, dark: Color)

`init(_:)`

init(_ color: Color)

Uses one color in both appearances.

`color(in:)`

func color(in appearance: ColorScheme) -> Color

Selects the dark color for dark appearance and the light color otherwise.

AppNorthConfiguration

Validated server URL, public App ID, and allowed write origin. Use HTTPS in production and pass the server base URL without /api/v1. See installation.

struct AppNorthConfiguration

`apiURL`

let apiURL: URL

`appId`

let appId: String

`origin`

let origin: URL

`init(apiURL:appId:origin:)`

init(apiURL: URL, appId: String, origin: URL) throws

AppNorthError

Typed client failures. Server errors preserve the HTTP status, machine code, and optional field errors; see error handling.

enum AppNorthError

`invalidConfiguration(_:)`

case invalidConfiguration(String)

`invalidIdentityCredential(_:)`

case invalidIdentityCredential(String)

`invalidResponse`

case invalidResponse

`network(_:)`

case network(String)

`server(status:code:fields:)`

case server(status: Int, code: String, fields: [String : [String]]?)

`decoding(_:)`

case decoding(String)

`errorDescription`

var errorDescription: String? { get }

A localized message describing what error occurred.

AppNorthCopy

Mutable SDK labels. The default follows the host app language; unsupported languages fall back to English. Each string property below overrides the corresponding label. See language.

struct AppNorthCopy