HeraldClient (Swift)

Herald is controlled over a local HTTP API, and three small clients wrap it so your code does not build requests by hand: a Swift package for macOS apps, a Python module and a Node module. Each one finds the running Herald, adds the bearer token, sends the request and raises a clear error when Herald is not running. For shell scripts there is also the command line tool, and for agents the MCP server.

All three clients read the port and token from Herald's support folder, ~/Library/Application Support/Herald/, the same two files the API describes. They talk to 127.0.0.1 only. A client function is a thin wrapper: the request and reply fields are documented once, in the endpoint it names.

The Python and Node clients cover what most integrations need: send a notification, dismiss it, read History. For a manifest, a template or a preview from those languages, call the HTTP route yourself, as Registering a manifest shows.

Swift#

HeraldClient is a Swift package library with no dependencies. It has typed models for notifications, buttons, manifests and templates, an async client, and a small server that receives button callbacks. Use it from a macOS app or a command line tool.

Add it

Add the package to your Package.swift and depend on the HeraldClient product:

dependencies: [
    .package(url: "https://github.com/ivg-design/herald.git", branch: "main"),
],
targets: [
    .target(name: "MyApp", dependencies: [
        .product(name: "HeraldClient", package: "herald"),
    ]),
]

In an Xcode project, use File > Add Package Dependencies with the same address.

import HeraldClient

let herald = HeraldClient.shared
guard herald.isAvailable else { return }          // a cheap check; false when Herald is not running
let id = try await herald.notify(HeraldNotification(app: "example.bidbot", title: "Bid accepted"))

notify returns the notification id. HeraldClient.shared reads the default support folder. isAvailable is true when the token and port files exist and the health endpoint answers within a second.

Realistic example

Register the app with a callback address, send a notification with buttons, and receive the button presses:

import HeraldClient

let callbacks = HeraldCallbackServer(handler: { event in
    // event.action is the label of the button; event.payload is the JSON you attached to it.
    print("\(event.notificationId): \(event.action) \(String(describing: event.payload))")
})
try callbacks.start()

let herald = HeraldClient.shared
try await herald.register(HeraldAppRegistration(
    app: "example.bidbot", appName: "BidBot",
    callbackURL: callbacks.callbackURL,
    defaults: HeraldAppDefaults(sound: "Glass")))

let id = try await herald.notify(HeraldNotification(
    app: "example.bidbot", id: "bid-42", title: "Counter-offer from Acme",
    body: "They offer $3,900. Accept?",
    buttons: [
        HeraldButton(label: "Accept", callback: HeraldCallback(payload: .object(["decision": .string("accept")]))),
        HeraldButton(label: "Decline", style: "destructive",
                     callback: HeraldCallback(payload: .object(["decision": .string("decline")]))),
    ],
    snooze: true))

let recent = try await herald.history(app: "example.bidbot", limit: 10)
try await herald.dismiss(app: "example.bidbot", id: id)
callbacks.stop()

HeraldCallbackServer listens on a loopback port that the system picks, so callbacks.callbackURL is only known after start(). See Actions for the callback request.

How Herald reads the answer to a callback:

• Any 2xx answer means "the action happened", and Herald closes the banner.
• When your action can fail, create the server with HeraldCallbackServer(statusHandler:) and return 200 only after the action succeeded.
• A 4xx is final. 408, 429 and 5xx make Herald retry once.
• Herald waits at most 5 seconds for the answer.

Second instance

HeraldClient(supportDirectory:port:token:) points a client at another Herald, such as the second instance used for testing. The HERALD_SUPPORT_DIR environment variable has the same effect on HeraldClient.shared.

Errors

Calls throw HeraldError.

Functions

HeraldCallbackServer is the one part that is not a request: it is a listener for the callbacks Herald sends. See the callback request.