nativemind_api_client library
Pure-Dart API client of the NativeMind framework: the operation table of a registry-driven API, an HTTP transport
with one silent token refresh, the {data, meta} / {error} envelopes, table paging, an offline action queue, live
events over SSE by topic, and OData filters compiled to predicates (for local demo backends and caches).
Classes
- NmAccessTokens
- Supplies the bearer token and renews it once when a request comes back 401.
- NmActionQueue
- The offline action queue: mutations made without a connection are kept in order and sent when flush runs (on reconnect, on resume, on a timer). One flush runs at a time; store updates are serialised.
- NmApiClient
- A client of a registry-driven API: one call per operation id. call's input holds path, query and body fields together, as the API merges them. Implemented over HTTP (NmHttpApiClient) or by a local demo / fake.
- NmApiEnvelope
-
A decoded API response: the
{data, meta}envelope, the status and the response headers (lower-case names). Products read extrametamembers through extensions. - NmApiOperation
-
One API operation of a registry-driven backend: method, path template and access flags. Products generate a
Map<String, NmApiOperation>from their registry (e.g.@nativemind108/api). - NmFlushResult
- What one flush did.
- NmHttpApiClient
-
An NmApiClient over HTTP. The operation table gives method and path; defaultHeaders (e.g. an app id header) and
the bearer token from tokens are added; a 401 on a non-public operation triggers one NmAccessTokens.renew and one
retry. Timeouts become
TIMEOUT, other transport failuresNETWORK_ERROR; a non-2xx answer decodes{error: {code, message, details, requestId}}. - NmLiveEvent
-
One decoded live event: the JSON payload of a frame, with
id,typeandatread from it (or from the frame). - NmMemoryQueueStore
- A queue store in memory (tests, web without persistence).
- NmODataField
- A filterable field: how to read it from a row, and whether it sorts.
- NmQueueBatch
- Consecutive queued items of one operation go as one call with the items under field (at most max).
- NmQueuedAction
- A mutation recorded offline (or waiting for a batch): sent later, in order.
- NmQueueStore
- Where the queue survives restarts (the app supplies device storage; tests use memory).
- NmSseParser
-
Incremental parser of the
text/event-streamformat:id,event,data(multi-line),retryand comments; CRLF and CR line endings are accepted. -
NmTablePage<
T> - One page of a table: rows, total count, page and size, and the envelope it came from.
- NmTableQuery
- Query of a table route: filter, sort, numbered page and size.
- NmTopicEventStream
-
Live updates over one SSE connection for the current topic set. Topics are reference-counted: the connection is
re-opened when the set changes, after drops (with
Last-Event-ID), and on reconnect (after a token renewal). JSON frames become NmLiveEvents; heartbeats and non-JSON frames are ignored.
Extensions
- NmApiPaging on NmApiClient
- Paging over NmApiClient.
Constants
- nmCookieRefresh → const bool
- Whether the refresh token travels in an HttpOnly cookie (web) instead of the body (native).
- nmUnsupportedFilterCode → const String
- Code of the errors thrown by nmODataFilter and nmODataOrderBy (status 400).
Functions
-
nmDefaultRetryable(
NmApiException e) → bool - Network errors, 5xx, 401, 408 and 429 keep an action queued; other errors drop it.
-
nmMatchAll(
NmLiveEvent event, String topic) → bool - Delivers every event to every topic.
-
nmODataFilter(
String filter, Map< String, NmODataField> fields) → bool Function(Map<String, dynamic> row) -
Compiles an OData-style filter (the subset
@nativemind108/queryaccepts) into a row predicate:eq ne gt ge lt le,and or not, parentheses,in (…),contains(),startswith()andendswith()(case-insensitive). Anything else, or a field outsidefields, throws NmApiException400 UNSUPPORTED_FILTER. -
nmODataOrderBy(
String orderBy, Map< String, NmODataField> fields, String key(Map<String, dynamic> row)) → int Function(Map<String, dynamic> a, Map<String, dynamic> b) -
Compiles
Field [asc|desc], …into a comparator: nulls last, ties broken bykey. -
nmOpenSse(
Uri url, {String? token, String? lastEventId, List< String> eventTypes = const ['message'], String tokenParam = 'access_token'}) → Stream<NmSseMessage> -
Native targets: a streamed GET with
Authorization: Bearer [token]andLast-Event-ID.eventTypesandtokenParammatter only on web. -
nmPlatformClient(
{Duration? connectTimeout}) → Client -
Native targets: an
IOClientwithconnectTimeout.
Typedefs
- NmSseMessage = ({String data, String event, String? id})
-
One
text/event-streamframe. -
NmSseOpener
= Stream<
NmSseMessage> Function(Uri url, {String? lastEventId, String? token}) - Opens a raw SSE connection (default nmOpenSse; tests pass a fake).
Exceptions / Errors
- NmApiException
-
An API error (
{error: {code, message, details, requestId}}) or a network failure (NETWORK_ERROR,TIMEOUT).