exsited 4.0.1

Dart SDK for the Exsited v4 REST API: every endpoint as a function, JSON in and JSON out.

exsited

Dart client for the Exsited v4 REST API. Every endpoint is a function (also available as a method on the client), requests go out exactly as you write them, and the API's answer comes back unchanged as a map, a JSON string or an optional typed view. It handles OAuth2 token requests and caching, retries with backoff, proxies and custom CA bundles, a typed error hierarchy, and redaction of secrets in logs.

Requirements

• Dart 3.5 or newer (the Flutter SDK bundles Dart, so Flutter projects work too)
• An Exsited instance and an API client: its base URL, client id, client secret and redirect URI

Install

dart pub add exsited

or in pubspec.yaml:

dependencies:
  exsited: ^4.0.1

Credentials

Build an AuthConfig from wherever your credentials live and pass it to the client. The SDK does not read credentials from the environment on its own, so load them yourself, for example from environment variables:

import 'dart:io';
import 'package:exsited/exsited.dart';

AuthConfig loadAuth() => AuthConfig(
      clientName: 'default',
      baseUrl: Platform.environment['EXSITED_BASE_URL']!,
      clientId: Platform.environment['EXSITED_CLIENT_ID']!,
      clientSecret: Platform.environment['EXSITED_CLIENT_SECRET']!,
      redirectUri: Platform.environment['EXSITED_REDIRECT_URI']!,
    );

or directly in code:

final auth = AuthConfig(
  clientName: 'default',
  baseUrl: 'https://your-instance.example.com',
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  redirectUri: 'https://your-app.example/callback',
);

clientSecret is a server credential. Do not embed it in a mobile or web app that you ship to users; use the SDK from a server, a backend, or a command line tool.

First call

import 'package:exsited/exsited.dart';

Future<void> main() async {
  final client = ExsitedClient(SdkConfig(
    AuthConfig(
      clientName: 'default',
      baseUrl: 'https://your-instance.example.com',
      clientId: 'your-client-id',
      clientSecret: 'your-client-secret',
      redirectUri: 'https://your-app.example/callback',
    ),
    raiseOnError: true,
  ));

  try {
    final response = await client.accounts.getAccount('your-account-id');
    print(response.map);       // the body as it arrived
    print(response.dto?.name); // the typed view
  } finally {
    client.close();
  }
}

Only the accounts and items families are exported by package:exsited/exsited.dart. Every other family is its own library, imported with a prefix:

import 'package:exsited/payments.dart' as payments;

final response = await payments.getPayment(client, 'your-payment-id');

The same call is also a method on the client: client.payments.getPayment('your-payment-id').

Errors

By default a failed call comes back as a response. With raiseOnError: true, on the config or on a single call, it throws an SdkError instead. SdkConfigError, SdkUsageError, SdkAuthError, SdkTokenCacheError and SdkTokenLockError extend it, and the server's messages are available from getErrorMessages().

Pagination

iterRecords walks a listing record by record and iterPages page by page, following cursor or offset pagination as the listing uses:

await for (final account in iterRecords(client, AccountsUrls.accounts,
    queryParams: {filterParam('status'): 'ACTIVE'})) {
  print((account! as Map)['id']);
}

Documentation

Endpoint reference and guides: https://exsited.mintlify.app

License

MIT. See LICENSE.