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.

Libraries

aba_files: The v4 aba files family: its endpoints, bound class, path templates and views.
account_emails: The v4 account emails family: its endpoints, bound class, path templates and views.
account_groups: The v4 account groups family: its endpoints, bound class, path templates and views.
accounting_codes: The v4 accounting codes family: its endpoints, bound class, path templates and views.
action_scripts: The v4 action scripts family: its endpoints, bound class, path templates and views.
additional_codes: The v4 additional codes family: its endpoints, bound class, path templates and views.
alert_responsibilities: The v4 alert responsibilities family: its endpoints, bound class, path templates and views.
alert_responsibility: The v4 alert responsibility family: its endpoints, bound class, path templates and views.
alerts: The v4 alerts family: its endpoints, bound class, path templates and views.
applications: The v4 applications family: its endpoints, bound class, path templates and views.
approval_profiles: The v4 approval profiles family: its endpoints, bound class, path templates and views.
approval_user_groups: The v4 approval user groups family: its endpoints, bound class, path templates and views.
approvals: The v4 approvals family: its endpoints, bound class, path templates and views.
attribute_attachments: The v4 attribute attachments family: its endpoints, bound class, path templates and views.
billing_periods: The v4 billing periods family: its endpoints, bound class, path templates and views.
bookings: The v4 bookings family: its endpoints, bound class, path templates and views.
charging_periods: The v4 charging periods family: its endpoints, bound class, path templates and views.
communication_profiles: The v4 communication profiles family: its endpoints, bound class, path templates and views.
communications: The v4 communications family: its endpoints, bound class, path templates and views.
countries: The v4 countries family: its endpoints, bound class, path templates and views.
credit_note_applications: The v4 credit note applications family: its endpoints, bound class, path templates and views.
credit_notes: The v4 credit notes family: its endpoints, bound class, path templates and views.
custom_attributes: The v4 custom attributes family: its endpoints, bound class, path templates and views.
custom_components: The v4 custom components family: its endpoints, bound class, path templates and views.
custom_events: The v4 custom events family: its endpoints, bound class, path templates and views.
custom_features: The v4 custom features family: its endpoints, bound class, path templates and views.
custom_fields: The v4 custom fields family: its endpoints, bound class, path templates and views.
custom_forms: The v4 custom forms family: its endpoints, bound class, path templates and views.
day_of_month: The v4 day of month family: its endpoints, bound class, path templates and views.
departments: The v4 departments family: its endpoints, bound class, path templates and views.
designations: The v4 designations family: its endpoints, bound class, path templates and views.
document_templates: The v4 document templates family: its endpoints, bound class, path templates and views.
email_templates: The v4 email templates family: its endpoints, bound class, path templates and views.
employees: The v4 employees family: its endpoints, bound class, path templates and views.
events: The v4 events family: its endpoints, bound class, path templates and views.
express: The v4 express family: its endpoints, bound class, path templates and views.
exsited: Dart client library for the Exsited v4 REST API: payloads go out as written, and the API's response comes back unchanged. This library carries the core and the accounts and items families; each other family is its own library, imported with a prefix (import 'package:exsited/payments.dart' as payments;), because 15 top-level names are declared by more than one family and export can neither rename nor prefix them.
external_databases: The v4 external databases family: its endpoints, bound class, path templates and views.
fulfillment_profiles: The v4 fulfillment profiles family: its endpoints, bound class, path templates and views.
fulfillment_terms: The v4 fulfillment terms family: its endpoints, bound class, path templates and views.
gift_certificates: The v4 gift certificates family: its endpoints, bound class, path templates and views.
integration_connections: The v4 integration connections family: its endpoints, bound class, path templates and views.
inventory_adjustments: The v4 inventory adjustments family: its endpoints, bound class, path templates and views.
invoice_terms: The v4 invoice terms family: its endpoints, bound class, path templates and views.
invoices: The v4 invoices family: its endpoints, bound class, path templates and views.
item_fulfillments: The v4 item fulfillments family: its endpoints, bound class, path templates and views.
item_receipts: The v4 item receipts family: its endpoints, bound class, path templates and views.
labours: The v4 labours family: its endpoints, bound class, path templates and views.
milestones: The v4 milestones family: its endpoints, bound class, path templates and views.
note_attachments: The v4 note attachments family: its endpoints, bound class, path templates and views.
note_groups: The v4 note groups family: its endpoints, bound class, path templates and views.
operator_groups: The v4 operator groups family: its endpoints, bound class, path templates and views.
operators: The v4 operators family: its endpoints, bound class, path templates and views.
orders: The v4 orders family: its endpoints, bound class, path templates and views.
organisation: The v4 organisation family: its endpoints, bound class, path templates and views.
organisations: The v4 organisations family: its endpoints, bound class, path templates and views.
payments: The v4 payments family: its endpoints, bound class, path templates and views.
portals: The v4 portals family: its endpoints, bound class, path templates and views.
pricing_periods: The v4 pricing periods family: its endpoints, bound class, path templates and views.
proforma_invoices: The v4 proforma invoices family: its endpoints, bound class, path templates and views.
purchase_credit_note_applications: The v4 purchase credit note applications family: its endpoints, bound class, path templates and views.
purchase_credit_notes: The v4 purchase credit notes family: its endpoints, bound class, path templates and views.
purchase_express: The v4 purchase express family: its endpoints, bound class, path templates and views.
purchase_invoices: The v4 purchase invoices family: its endpoints, bound class, path templates and views.
purchase_orders: The v4 purchase orders family: its endpoints, bound class, path templates and views.
purchase_payments: The v4 purchase payments family: its endpoints, bound class, path templates and views.
purchase_refunds: The v4 purchase refunds family: its endpoints, bound class, path templates and views.
quote_orders: The v4 quote orders family: its endpoints, bound class, path templates and views.
receive_terms: The v4 receive terms family: its endpoints, bound class, path templates and views.
reconciliations: The v4 reconciliations family: its endpoints, bound class, path templates and views.
refunds: The v4 refunds family: its endpoints, bound class, path templates and views.
rental_assets: The v4 rental assets family: its endpoints, bound class, path templates and views.
reports: The v4 reports family: its endpoints, bound class, path templates and views.
return_merchandise_authorisations: The v4 return merchandise authorisations family: its endpoints, bound class, path templates and views.
return_vendor_authorizations: The v4 return vendor authorizations family: its endpoints, bound class, path templates and views.
roles: The v4 roles family: its endpoints, bound class, path templates and views.
sales_reps: The v4 sales reps family: its endpoints, bound class, path templates and views.
salutations: The v4 salutations family: its endpoints, bound class, path templates and views.
settings: The v4 settings family: its endpoints, bound class, path templates and views.
settings_workflows: The v4 settings workflows family: its endpoints, bound class, path templates and views.
shipping_packages: The v4 shipping packages family: its endpoints, bound class, path templates and views.
shipping_rules: The v4 shipping rules family: its endpoints, bound class, path templates and views.
system_events: The v4 system events family: its endpoints, bound class, path templates and views.
tasks: The v4 tasks family: its endpoints, bound class, path templates and views.
teams: The v4 teams family: its endpoints, bound class, path templates and views.
time_periods: The v4 time periods family: its endpoints, bound class, path templates and views.
timesheets: The v4 timesheets family: its endpoints, bound class, path templates and views.
uom: The v4 uom family: its endpoints, bound class, path templates and views.
usages: The v4 usages family: its endpoints, bound class, path templates and views.
user_settings: The v4 user settings family: its endpoints, bound class, path templates and views.
webhooks: The v4 webhooks family: its endpoints, bound class, path templates and views.
workflows: The v4 workflows family: its endpoints, bound class, path templates and views.
zones: The v4 zones family: its endpoints, bound class, path templates and views.