Dart and Flutter Alerts SDK

The API Alerts Dart SDK sends alerts from your Dart code through API Alerts. Drop it into Flutter apps, Dart backend services, command-line tools, or any Dart codebase that needs to notify you when something important happens. Minimal setup, fire-and-forget by default with optional response handling, and zero infrastructure.

Installation

dependencies:
  apialerts: 1.0.0

Quick Start

import 'package:apialerts/apialerts.dart';

void main() {
  ApiAlerts.configure('your-api-key');
  ApiAlerts.send(const Event(message: 'Deploy complete'));
}

Usage

The SDK exposes a singleton (ApiAlerts) for most use cases and an instance-based client (ApiAlertsClient) when you need multiple clients.

Fire and forget

ApiAlerts.configure('your-api-key');

// Never throws. Safe to call anywhere.
ApiAlerts.send(const Event(message: 'Deploy complete'));

Wait for response

sendAsync never throws. Check result.success to handle success or failure.

final result = await ApiAlerts.sendAsync(const 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'},
));

if (result.success) {
  print('Sent to ${result.workspace} (${result.channel})');
  for (final w in result.warnings) {
    print('Warning: $w');
  }
} else {
  print('Error: ${result.error}');
}

Dependency injection

The ApiAlerts singleton is the quickest way to send. When you want DI, mocking in tests, or multiple keys side by side, construct an ApiAlertsClient directly. ApiAlerts is a thin facade over a default ApiAlertsClient, so the two never drift.

import 'package:apialerts/apialerts.dart';

final client = ApiAlertsClient('your-api-key');
client.send(const Event(message: 'Deploy complete'));

Register it with a service locator such as get_it and depend on the type; supply your own implementation in tests.

Multiple workspaces

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

final result = await ApiAlerts.sendAsync(
  const Event(message: 'Cross-workspace event'),
  apiKey: 'other-api-key',
);

Event Fields

Field	Type	Required	Description
message	String	Yes	Main notification message
channel	String?	No	Target channel name
event	String?	No	Event key for routing
title	String?	No	Short title
tags	List<String>?	No	Categorisation tags
link	String?	No	URL attached to the notification
data	Map<String, dynamic>?	No	Arbitrary key-value metadata

Platform support

Runs on Android, iOS, web, macOS, Windows, and Linux.

• Android: add the INTERNET permission to android/app/src/main/AndroidManifest.xml. Flutter only adds it for debug builds, so release builds fail without it:

  <uses-permission android:name="android.permission.INTERNET"/>

• macOS: add com.apple.security.network.client to macos/Runner/DebugProfile.entitlements and Release.entitlements so requests pass the app sandbox.

• Web: works in the browser, but your API key ships in the app bundle and is visible to anyone who inspects it. Only use a key you are comfortable exposing client-side.

• iOS, Windows, Linux: no extra configuration.