Swift Alerts SDK

The API Alerts Swift SDK sends push notifications, SMS, WhatsApp, email, and Slack alerts from your Swift code. Drop it into iOS, macOS, watchOS, tvOS, visionOS apps, or Vapor servers that need to notify you when something important happens. Minimal setup, async/await throughout, and zero boilerplate.

Installation

Add the package in Xcode via File → Add Package Dependencies:

https://github.com/apialerts/apialerts-swift

Or in Package.swift, add the package to dependencies and the product to your target:

dependencies: [
    .package(url: "https://github.com/apialerts/apialerts-swift", exact: "1.2.0")
],
targets: [
    .target(
        name: "YourTarget",
        dependencies: [
            .product(name: "APIAlerts", package: "apialerts-swift")
        ]
    )
]

Usage

Configure the singleton once at startup, then send from anywhere. For dependency injection, mocking, or multiple keys, use the instance client instead.

Fire and forget

import APIAlerts

APIAlerts.configure("your-api-key")

// Synchronous, returns immediately; delivery runs in a detached task.
// Never throws, drops errors silently unless debug is on
APIAlerts.send(Event(message: "Deploy complete"))

Wait for response

sendAsync never throws - switch on the Result.

let result = await APIAlerts.sendAsync(Event(
    message: "New user signed up",
    channel: "revenue",
    event: "user.signup",
    title: "New Signup",
    tags: ["growth", "organic"],
    link: "https://dashboard.example.com/users/123",
    data: ["plan": "pro", "source": "organic"]
))

switch result {
case .success(let sent):
    print("Sent to \(sent.workspace ?? "") (\(sent.channel ?? ""))")
case .failure(let error):
    print("Error: \(error.localizedDescription)")
}

Enable debug logging

APIAlerts.configure("your-api-key", debug: true)

Critical errors (missing API key, not yet configured) always log via os.Logger. Success and warning messages only log when debug is enabled.

Dependency injection

The singleton suits most apps. When you want injection, mocking, or multiple keys in one process, construct an ApiAlertsClient directly. It conforms to ApiAlertsClientProtocol, so hold the protocol type in your code and substitute a stub in tests.

import APIAlerts

struct DeployNotifier {
    let alerts: any ApiAlertsClientProtocol

    func notify() {
        alerts.send(Event(message: "Deploy complete"))
    }
}

let notifier = DeployNotifier(alerts: ApiAlertsClient("your-api-key"))

APIAlerts is a thin facade over a default ApiAlertsClient, so the singleton and instance client share the same behaviour. To test the real client, inject a URLSession (for example one backed by a mock URLProtocol):

let client = ApiAlertsClient("your-api-key", session: mockSession)

Multiple workspaces

Pass an apiKey to override the configured key for a single call:

APIAlerts.send(
    Event(message: "Cross-workspace event"),
    apiKey: "other-api-key"
)

Event Fields

Only message is required. All other fields are optional and omitted from the JSON payload when nil.

Field	Type	Required	Description
message	String	Yes	Notification text shown on the push lock screen.
channel	String?	No	Workspace channel; defaults to the workspace default.
event	String?	No	Routing key. Matched with Unix glob/fnmatch (ci.*, User *); dotted notation is a convention, not required.
title	String?	No	Short headline some destinations render separately.
tags	[String]?	No	Categorisation tags for filtering and search.
link	String?	No	URL attached to the notification; tapping the push opens it.
data	(any Encodable & Sendable)?	No	Arbitrary metadata for non-push destination templating.

Resources