The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
import 'dart:async';
import 'dart:convert';
import 'dart:typed_data';
import 'package:dio/dio.dart';
import '../auth/auth_session.dart';
import '../core/config.dart';
import '../core/models.dart';
import '../logging/app_log.dart';
import '../logging/http_log.dart';
import '../notify/push_channel.dart' show PushAddress;
import '../notify/push_tokens.dart' show PushTokenApi;
import '../swarm/swarm_outgoing_files.dart';
import '../swarm/swarm_request.dart' show SuperTabFailure;
import '../viewer/device_ack.dart';
import '../viewer/device_log.dart';
import '../viewer/device_log_sync.dart'
show DeviceLogAppendAnswer, DeviceLogFetched;
import 'access_token_source.dart';
import 'bearer_auth_interceptor.dart';
import 'multipart_body.dart';
/// Authenticated control-plane REST client for the phone.
class ApiClient implements PushTokenApi {
Future<Map<String, dynamic>> productUsageReport(
Map<String, dynamic> report,
) async {
final response = await _dio.post(
'/api/product-usage/report',
data: report,
options: Options(
receiveTimeout: const Duration(seconds: 5),
sendTimeout: const Duration(seconds: 5),
),
);
return Map<String, dynamic>.from(unwrapApiResponse(response) as Map);
}
Future<void> productUsageFeedback(String answer, String receipt) async {
final response = await _dio.post(
'/api/product-usage/feedback',
data: {'answer': answer, 'id': receipt},
);
final result = unwrapApiResponse(response);
if (result is! Map || result['accepted'] != true) {
throw StateError('Feedback was not accepted');
}
}
Future<Map<String, dynamic>> productUsageSettings({bool? enabled}) async {
final response = enabled == null
? await _dio.get(
'/api/product-usage/settings',
options: Options(receiveTimeout: const Duration(seconds: 5)),
)
: await _dio.post(
'/api/product-usage/settings',
data: {'enabled': enabled},
);
return Map<String, dynamic>.from(unwrapApiResponse(response) as Map);
}
final AppConfig config;
final AuthSession session;
final AccessTokenSource? auth;
/// An in-process transport for tests; authentication and serialization still run.
final HttpClientAdapter? httpClientAdapter;
late final Dio _dio = _buildDio();
ApiClient({
required this.config,
required this.session,
this.auth,
this.httpClientAdapter,
});
Dio _buildDio() {
// In-memory subclasses override requests; every real API call requires auth.
final source =
auth ?? (throw StateError('API calls require an access token source'));
final dio = attachHttpLog(
Dio(
BaseOptions(
baseUrl: config.apiBaseUrl,
connectTimeout: const Duration(seconds: 15),
receiveTimeout: const Duration(seconds: 30),
// Let the API wrapper turn HTTP failures into short, user-facing
// ApiExceptions. Transport failures still surface as DioExceptions.
validateStatus: (status) =>
status != null && status >= 200 && status < 600,
),
),
);
dio.interceptors.add(
BearerAuthInterceptor(source, dio, autonomousEnv: config.autonomousEnv),
);
final adapter = httpClientAdapter;
if (adapter != null) dio.httpClientAdapter = adapter;
return dio;
}
// -- auth --
Future<Map<String, dynamic>?> me() async {
final res = await _dio.get('/api/auth/me');
return unwrapApiResponse(res) as Map<String, dynamic>?;
}
/// Saves the signed-in person's own account name (`PATCH /api/auth/me`, task #2655, the route #2917 added) and
/// answers the profile as [me] does. The backend checks the name and says why it refused in words; one from before
/// the route answers 404.
Future<Map<String, dynamic>?> updateMe({required String name}) async {
final res = await _dio.patch('/api/auth/me', data: {'name': name});
return unwrapApiResponse(res) as Map<String, dynamic>?;
}
// -- machines --
Future<List<Machine>> machines() async {
final res = await _dio.get('/api/machines');
final data = unwrapApiResponse(res) as Map<String, dynamic>;
final list = data['machines'] as List<dynamic>? ?? [];
return list
.map((e) => Machine.fromJson(e as Map<String, dynamic>))
.toList();
}
Future<String?> renameMachine({
required String machineId,
required String name,
}) async {
final res = await _dio.patch(
'/api/machines/$machineId',
data: {'name': name},
options: Options(headers: {'x-adapter-local': '1'}),
);
final data = unwrapApiResponse(res) as Map<String, dynamic>;
return data['name'] as String?;
}
Future<void> deleteMachine({required String machineId}) async {
final res = await _dio.delete(
'/api/machines/$machineId',
options: Options(headers: {'x-adapter-local': '1'}),
);
unwrapApiResponse(res);
}
// -- where to push to this phone (notify/push_tokens.dart) --
@override
Future<void> registerPushToken(PushAddress address) async {
final res = await _dio.post('/api/push-devices', data: _pushBody(address));
unwrapApiResponse(res);
}
@override
Future<void> forgetPushToken(PushAddress address) async {
// In the body, not the path: a path lands in access logs.
final res = await _dio.post(
'/api/push-devices/drop',
data: _pushBody(address),
);
unwrapApiResponse(res);
}
/// The server's body is strict (`routes/pushDevices.ts`): these two keys, nothing else.
static Map<String, String> _pushBody(PushAddress address) => {
'platform': address.platform,
'token': address.token,
};
// -- the account's device key log (viewer/device_log_sync.dart) --
/// `GET /api/device-keys?since=` — the log from [since]; null when there is none to read (an older
/// backend, signed out, or unreachable).
///
/// [self]: this app's own key, which the backend counts as used just now (an older one ignores it).
Future<DeviceLogFetched?> deviceKeys(int since, {String? self}) async {
try {
final res = await _dio.get(
'/api/device-keys',
queryParameters: {'since': since, 'self': ?self},
);
if (res.statusCode != 200) return null;
final data = unwrapApiResponse(res);
if (data is! Map) return null;
final acct = data['acct'],
head = DevLogHead.fromJson(data['head']),
entries = data['entries'];
if (acct is! String || head == null || entries is! List) return null;
return (acct: acct, head: head, entries: entries.cast<Object?>());
} catch (_) {
return null;
}
}
/// `POST /api/device-keys` — append one entry this phone signed. Null when the backend could not
/// be reached; a refusal comes back as its code (`STALE_HEAD` with the current head).
Future<DeviceLogAppendAnswer?> appendDeviceKey(DevLogEntry entry) async {
try {
final res = await _dio.post(
'/api/device-keys',
data: {'entry': entry.toJson()},
);
final body = res.data;
if (body is! Map) return null;
final data = body['data'];
final head = data is Map ? DevLogHead.fromJson(data['head']) : null;
if (res.statusCode == 200) return (head: head, error: null);
final error = body['error'];
final code = error is Map && error['code'] is String
? error['code'] as String
: 'HTTP_${res.statusCode}';
return (head: head, error: code);
} catch (_) {
return null;
}
}
/// `GET /api/device-keys/acks?since=` — the acknowledgements ("It's mine" said on another device,
/// `viewer/device_ack.dart`) of keys added after entry [since], unchecked: the device log judges each.
/// Null when there are none to read (a backend from before them, signed out, or unreachable). A short
/// deadline: while it runs, the read of the log that asked holds back its "New device" notices.
Future<List<Object?>?> deviceAcks(int since) async {
try {
final res = await _dio.get(
'/api/device-keys/acks',
queryParameters: {'since': since},
options: Options(receiveTimeout: const Duration(seconds: 5)),
);
if (res.statusCode != 200) return null;
final data = unwrapApiResponse(res);
final acks = data is Map ? data['acks'] : null;
return acks is List ? acks.cast<Object?>() : null;
} catch (_) {
return null;
}
}
/// `POST /api/device-keys/acks` — share this phone's "It's mine" for a device with the account's
/// other devices. False when the backend did not keep it (or predates it).
Future<bool> postDeviceAck(DevAck ack) async {
try {
final res = await _dio.post(
'/api/device-keys/acks',
data: {'ack': ack.toJson()},
);
return res.statusCode == 200;
} catch (_) {
return false;
}
}
/// `GET /api/device-keys/seen` — when each key last opened a session, `{pub: ms}`; empty when it
/// cannot be read. A hint for offering to remove apps not used in a long while.
Future<Map<String, int>> deviceKeysSeen() async {
try {
final res = await _dio.get('/api/device-keys/seen');
if (res.statusCode != 200) return const {};
final data = unwrapApiResponse(res);
final seen = data is Map ? data['seen'] : null;
return {
if (seen is Map)
for (final e in seen.entries)
if (e.key is String && e.value is int)
e.key as String: e.value as int,
};
} catch (_) {
return const {};
}
}
// -- signing a computer in by its QR (backend routes/qrSignIn.ts) --
/// What is asking to sign in: `{label, kind, country?, ipHint?, sameNetwork, status}`.
Future<Map<String, dynamic>> signInLookup(String code) async {
final res = await _dio.post('/api/auth/qr/lookup', data: {'code': code});
return Map<String, dynamic>.from(unwrapApiResponse(res) as Map);
}
Future<void> approveSignIn(String code) async {
unwrapApiResponse(
await _dio.post('/api/auth/qr/approve', data: {'code': code}),
);
}
Future<void> denySignIn(String code) async {
unwrapApiResponse(
await _dio.post('/api/auth/qr/deny', data: {'code': code}),
);
}
/// A sign-in already approved for this account, for a device with no screen to show a QR on:
/// `{ticket, expiresIn}`. Handed to the device over its setup hotspot; it spends it once it is
/// on the person's Wi-Fi (`harness login --ticket`).
Future<Map<String, dynamic>> boxTicket() async {
final res = await _dio.post('/api/auth/box/ticket', data: const {});
return Map<String, dynamic>.from(unwrapApiResponse(res) as Map);
}
// -- the desk: the account's tabs, the same on every computer --
/// `{revision, tabs}` as the backend holds it (its `routes/desk.ts`); null on
/// a backend that predates the desk (404) or a session it will not take
/// (401) — the phone then has no tabs to show and swipes the whole account,
/// as it did before the desk existed.
Future<Map<String, dynamic>?> desk() async {
final res = await _dio.get('/api/desk');
if (res.statusCode == 404 || res.statusCode == 401) return null;
return unwrapApiResponse(res) as Map<String, dynamic>?;
}
/// Apply [ops] to the desk; answers the desk as it is afterwards. Null under
/// the same two conditions as [desk].
Future<Map<String, dynamic>?> deskOps(List<Map<String, dynamic>> ops) async {
final res = await _dio.post(
'/api/desk/ops',
data: {'ops': ops},
options: Options(headers: {'x-adapter-local': '1'}),
);
if (res.statusCode == 404 || res.statusCode == 401) return null;
return unwrapApiResponse(res) as Map<String, dynamic>?;
}
// -- the zoo: the account's daemons and eggs (daemons/README.md), its own document --
/// `{revision, zoo}` (the backend's `routes/zoo.ts`); null on a backend that
/// predates the zoo (404) or a session it will not take (401) — the phone
/// then draws no daemon at all.
Future<Map<String, dynamic>?> zoo() async {
final res = await _dio.get('/api/zoo');
if (res.statusCode == 404 || res.statusCode == 401) return null;
return unwrapApiResponse(res) as Map<String, dynamic>?;
}
/// Apply [ops] in order; answers `{revision, zoo, hatched, grants,
/// levelUps}`. Null under the same two conditions as [zoo].
Future<Map<String, dynamic>?> zooOps(List<Map<String, dynamic>> ops) async {
final res = await _dio.post(
'/api/zoo/ops',
data: {'ops': ops},
options: Options(headers: {'x-adapter-local': '1'}),
);
if (res.statusCode == 404 || res.statusCode == 401) return null;
return unwrapApiResponse(res) as Map<String, dynamic>?;
}
// -- voice (backend only: the viewer's own SSO session signs it) --
/// The words in one WAV recording, in [lang] — `POST /api/voice/stt`, the
/// endpoint the dial's recordings reach through the CLI, called here with the
/// token this viewer already holds.
///
/// [lang] must be one the backend serves (`VOICE_WAV_LANGS` in the backend's
/// `lib/deepgramWav.ts`); anything else is transcribed as English there.
Future<String> transcribeVoice(Uint8List wav, {required String lang}) async {
final body = multipartFileBody(
field: 'file',
filename: 'voice.wav',
fileContentType: 'audio/wav',
file: wav,
boundary: 'harness-${DateTime.now().microsecondsSinceEpoch}',
);
final res = await _dio.post(
'/api/voice/stt',
queryParameters: {'lang': lang},
data: body.bytes,
options: Options(
contentType: body.contentType,
// A take can run five minutes — megabytes on a phone connection — and
// the backend waits on the transcription provider before it answers.
sendTimeout: const Duration(minutes: 2),
receiveTimeout: const Duration(minutes: 2),
),
);
final data = unwrapApiResponse(res) as Map<String, dynamic>;
return (data['transcript'] as String? ?? '').trim();
}
// -- Swarm requests (the viewer's own session signs them) --
/// One read of the Swarm ([path], `/api/super-tabs…`), straight from the
/// backend with this viewer's own sign-in, as the web build reads it
/// (docs/specs/2026-10-30-web-swarm-direct.md). Answers the backend's value,
/// read as `backend()` in cli/src/superTabs/wire.ts reads it, so it is the
/// value a machine would have forwarded. A refusal throws a [SuperTabFailure]
/// carrying the backend's code and status; no answer at all throws what the
/// transport threw.
Future<Object?> swarmRead(String path) async {
final response = await _dio.get<dynamic>(path);
return _swarmValue(response);
}
/// A Swarm write signed by this phone. Keep [body], including its operation
/// ID, unchanged through bearer refresh and caller retries. The caller cancels
/// it on account change, preventing a refresh from replaying for a new account.
/// Never forward a command or its bearer to a redirect or another origin.
Future<Object?> swarmWrite(
String path, {
Map<String, dynamic>? body,
CancelToken? cancel,
}) async {
final uri = Uri.parse(path);
if (uri.hasScheme ||
uri.hasAuthority ||
!uri.path.startsWith('/api/super-tabs/') ||
uri.pathSegments.any((segment) => segment == '.' || segment == '..') ||
uri.hasQuery ||
uri.hasFragment) {
throw ArgumentError.value(path, 'path', 'Expected a Swarm backend path');
}
final response = await _dio.post<dynamic>(
path,
data: body,
cancelToken: cancel,
options: Options(followRedirects: false),
);
return _swarmValue(response);
}
static Object? _swarmValue(Response<dynamic> response) {
final status = response.statusCode ?? 0;
var body = response.data;
if (body is String) {
try {
body = jsonDecode(body);
} on FormatException {
// A proxy's page, not the backend's answer: refused below by its status.
}
}
if (status == 426) {
throw const SuperTabFailure(
'UPDATE_REQUIRED',
'Update Harness to keep using this Swarm.',
statusCode: 426,
);
}
final envelope = body is Map ? body : const <String, Object?>{};
if (status < 200 || status >= 300 || envelope['success'] != true) {
final error = envelope['error'];
final code = error is Map ? error['code'] : envelope['code'];
final message = error is Map ? error['message'] : envelope['message'];
throw SuperTabFailure(
code is String && code.isNotEmpty ? code : 'BACKEND_UNAVAILABLE',
message is String && message.isNotEmpty
? message
: 'Could not reach this Swarm.',
statusCode: status,
);
}
return envelope['data'];
}
// -- Swarm chat files (backend only: the viewer's own SSO session signs it) --
/// Sends one file for a message in [conversationId] of Swarm [tabId] and
/// answers the backend's `{attachment: {...}}`.
///
/// A file of up to [swarmFormAttachmentMaxBytes] goes as the form Desktop
/// sends, `POST /api/super-tabs/:tabId/attachments`. A larger one, up to
/// [swarmAttachmentMaxBytes], goes in three steps, since a proxy in front of
/// the backend may refuse a body that large: the backend is asked for a link
/// (`POST …/attachments/uploads`), the file goes straight to storage by it,
/// read from disk as it goes ([_putToStorage]), and the backend is told it is
/// there (`POST …/attachments/uploads/:id/complete`), which answers the same
/// attachment. A larger file still is refused before anything is sent.
///
/// Straight to the backend with the token this viewer holds, unlike every
/// other Swarm command, which one of the account's machines forwards
/// (`AppNotifier.swarmRequest`): the backend takes a chat file only from the
/// client itself, and a machine forwards only JSON. [onProgress] is told the
/// part sent, from 0 to 1. A refusal throws a [SuperTabFailure] carrying the
/// backend's code, worded as Desktop's `superTabUploadRefusal`. [cancel]
/// stops whichever step is under way and takes no other; so does
/// [stillWanted] failing between steps.
Future<Map<String, dynamic>> uploadSwarmAttachment({
required String tabId,
required String conversationId,
required String name,
required String mime,
required SwarmOutgoingFile file,
required CancelToken cancel,
required void Function(double sent) onProgress,
bool Function()? stillWanted,
}) async {
if (file.size > swarmAttachmentMaxBytes) {
throw const SuperTabFailure(
'ATTACHMENT_TOO_LARGE',
_swarmAttachmentTooLarge,
statusCode: 413,
);
}
final tab = Uri.encodeComponent(tabId);
if (file.size <= swarmFormAttachmentMaxBytes) {
final body = multipartFileBody(
fields: {'conversationId': conversationId},
field: 'file',
filename: name,
fileContentType: mime,
file: await file.readAll(),
boundary: 'harness-${DateTime.now().microsecondsSinceEpoch}',
);
final res = await _dio.post(
'/api/super-tabs/$tab/attachments',
data: body.bytes,
cancelToken: cancel,
onSendProgress: (sent, total) {
if (total > 0) onProgress(sent / total);
},
options: Options(
contentType: body.contentType,
// Ten megabytes on a phone connection; the chat's own watchdog gives
// up on an upload that stops moving.
sendTimeout: const Duration(minutes: 5),
receiveTimeout: const Duration(minutes: 1),
),
);
return _swarmFileAnswer(res);
}
void stillGoing() {
if (cancel.cancelError case final cancelled?) throw cancelled;
if (stillWanted != null && !stillWanted()) {
throw DioException.requestCancelled(
requestOptions: RequestOptions(),
reason: 'no longer wanted',
);
}
}
final asked = await _dio.post(
'/api/super-tabs/$tab/attachments/uploads',
data: {
'conversationId': conversationId,
'name': name,
'mime': mime,
'size': file.size,
},
cancelToken: cancel,
options: Options(receiveTimeout: const Duration(minutes: 1)),
);
final upload = _swarmUploadLink(_swarmFileAnswer(asked)['upload']);
stillGoing();
await _putToStorage(upload, file, name, cancel, onProgress);
stillGoing();
final done = await _dio.post(
'/api/super-tabs/$tab/attachments/uploads/'
'${Uri.encodeComponent(upload.id)}/complete',
data: const <String, Object?>{},
cancelToken: cancel,
options: Options(receiveTimeout: const Duration(minutes: 1)),
);
return _swarmFileAnswer(done);
}
/// A client for storage links alone: no token, and no log line, since the
/// link itself is the credential. Tests share the backend's transport.
late final Dio _storage = () {
final dio = Dio(
BaseOptions(
connectTimeout: const Duration(seconds: 15),
// No send timeout: in Dio it bounds the whole body, and a few hundred
// megabytes may take longer; the chat's watchdog gives up on one that
// stops moving.
receiveTimeout: const Duration(minutes: 1),
validateStatus: (status) => status != null,
),
);
final adapter = httpClientAdapter;
if (adapter != null) dio.httpClientAdapter = adapter;
return dio;
}();
/// Sends [file] to storage by [upload]'s link: exactly the headers the
/// backend signed, its length, and nothing of this viewer's. A refusal, or a
/// transfer that breaks, says which file did not go up — never the link.
Future<void> _putToStorage(
_SwarmUploadLink upload,
SwarmOutgoingFile file,
String name,
CancelToken cancel,
void Function(double sent) onProgress,
) async {
// A token of its own, so that what the caller's token carries when it is
// cancelled is the backend's request, never the link.
final put = CancelToken();
final cancelled = cancel.whenCancel.then((_) => put.cancel('given up'));
unawaited(cancelled);
final failed = SuperTabFailure(
'UPLOAD_FAILED',
'Could not upload $name. Try again.',
);
final int status;
try {
final res = await _storage.request<void>(
upload.url,
data: file.openRead(),
cancelToken: put,
onSendProgress: (sent, total) {
if (total > 0) onProgress(sent / total);
},
options: Options(
method: upload.method,
headers: {
...upload.headers,
Headers.contentLengthHeader: '${file.size}',
},
responseType: ResponseType.plain,
),
);
status = res.statusCode ?? 0;
} on DioException catch (error) {
if (error.type == DioExceptionType.cancel) {
// Dropped on its way back up: the caller only learns it stopped.
throw DioException.requestCancelled(
requestOptions: RequestOptions(),
reason: 'given up',
);
}
appLog.warn('api', 'chat file to storage → failed (${error.type.name})');
throw failed;
}
if (status < 200 || status >= 300) {
appLog.warn('api', 'chat file to storage → $status');
throw SuperTabFailure(failed.code, failed.message, statusCode: status);
}
appLog.debug('api', 'chat file to storage → $status');
}
// -- Swarm avatars (backend only: the computer a Swarm call goes through carries text) --
/// Uploads [png] as an avatar picture of the Swarm [tabId] and answers the
/// upload's id — `POST /api/super-tabs/:tabId/avatars` (backend
/// superTabs/profile.ts); a `member.avatar` command then makes it the
/// person's.
Future<String> uploadSwarmAvatar(String tabId, Uint8List png) async {
final body = multipartFileBody(
field: 'file',
filename: 'avatar.png',
fileContentType: 'image/png',
file: png,
boundary: 'harness-${DateTime.now().microsecondsSinceEpoch}',
);
final res = await _dio.post(
'/api/super-tabs/${Uri.encodeComponent(tabId)}/avatars',
data: body.bytes,
options: Options(contentType: body.contentType),
);
final data = unwrapApiResponse(res) as Map<String, dynamic>;
return (data['avatar'] as Map<String, dynamic>)['id'] as String;
}
}
/// What the backend says of a file past [swarmAttachmentMaxBytes].
const _swarmAttachmentTooLarge = 'Files can be up to $swarmAttachmentMaxLabel.';
/// The backend's answer to a chat file call: its `data`, or a
/// [SuperTabFailure] with its code and words, Desktop's when it gave none.
Map<String, dynamic> _swarmFileAnswer(Response<dynamic> res) {
final data = res.data;
if (res.statusCode == 200 && data is Map && data['success'] == true) {
final answer = data['data'];
if (answer is Map) return Map<String, dynamic>.from(answer);
}
final error = data is Map ? data['error'] : null;
final code = error is Map ? error['code'] as String? : null;
final message = error is Map ? error['message'] as String? : null;
throw SuperTabFailure(
code ?? 'UPLOAD_FAILED',
message ??
switch (code) {
'FORBIDDEN' => 'You can’t send files in this conversation.',
'ATTACHMENT_TOO_LARGE' => _swarmAttachmentTooLarge,
'UPLOAD_INCOMPLETE' =>
'The file did not finish uploading. Try again.',
'ATTACHMENT_UNAVAILABLE' =>
'Attach this file again before sending it.',
_ => 'Could not upload the file. Try again.',
},
statusCode: res.statusCode ?? 0,
);
}
/// Where the backend says a large chat file goes, and how.
typedef _SwarmUploadLink = ({
String id,
String url,
String method,
Map<String, String> headers,
});
/// [raw] as a link to send a file to: an id, an https link and its headers, or
/// a failed upload — a file is never sent anywhere less.
_SwarmUploadLink _swarmUploadLink(Object? raw) {
const failed = SuperTabFailure(
'UPLOAD_FAILED',
'Could not upload the file. Try again.',
);
if (raw is! Map) throw failed;
final id = raw['id'], url = raw['url'], method = raw['method'] ?? 'PUT';
final headers = raw['headers'] ?? const <String, Object?>{};
final uri = url is String ? Uri.tryParse(url) : null;
if (id is! String ||
id.isEmpty ||
uri == null ||
uri.scheme != 'https' ||
uri.host.isEmpty ||
method is! String ||
headers is! Map ||
headers.values.any((value) => value is! String)) {
throw failed;
}
return (
id: id,
url: url as String,
method: method.toUpperCase(),
headers: {
for (final MapEntry(:key, :value) in headers.entries)
'$key': value as String,
},
);
}
class ApiException implements Exception {
final String message;
final int? status;
ApiException(this.message, {this.status});
@override
String toString() => message;
}
/// Unwraps the backend's `{success, data, error}` envelope, which both legs
/// speak: the CLI's loopback server mirrors it, and the viewer's own auth calls
/// (`viewer/direct_auth_api.dart`) read it straight from the backend.
dynamic unwrapApiResponse(Response res) {
final body = res.data;
if (body is Map && body['success'] == true) {
return body['data'];
}
final error = body is Map ? body['error'] : null;
final serverMessage = error is Map ? error['message'] : null;
throw ApiException(
serverMessage is String && serverMessage.isNotEmpty
? serverMessage
: 'Request failed (${res.statusCode})',
status: res.statusCode,
);
}
/// A short explanation of a failed request to the Harness backend.
String describeApiError(Object error) {
if (error is ApiException) return error.message;
if (error is DioException) {
switch (error.type) {
case DioExceptionType.connectionError:
return 'could not reach Harness. Check your connection and try again.';
case DioExceptionType.connectionTimeout:
case DioExceptionType.sendTimeout:
case DioExceptionType.receiveTimeout:
final limit = error.requestOptions.receiveTimeout?.inSeconds;
return 'Harness did not answer'
'${limit == null ? '' : ' within ${limit}s'}. Try again in a moment.';
case DioExceptionType.badResponse:
return 'Harness answered '
'${error.response?.statusCode ?? 'with an error'}.';
case DioExceptionType.badCertificate:
case DioExceptionType.cancel:
case DioExceptionType.transformTimeout:
case DioExceptionType.unknown:
return error.message ?? error.error?.toString() ?? 'request failed';
}
}
return '$error';
}