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 extra meta members 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 failures NETWORK_ERROR; a non-2xx answer decodes {error: {code, message, details, requestId}}.
NmLiveEvent
One decoded live event: the JSON payload of a frame, with id, type and at read 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-stream format: id, event, data (multi-line), retry and 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/query accepts) into a row predicate: eq ne gt ge lt le, and or not, parentheses, in (…), contains(), startswith() and endswith() (case-insensitive). Anything else, or a field outside fields, throws NmApiException 400 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 by key.
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] and Last-Event-ID. eventTypes and tokenParam matter only on web.
nmPlatformClient({Duration? connectTimeout}) → Client
Native targets: an IOClient with connectTimeout.

Typedefs

NmSseMessage = ({String data, String event, String? id})
One text/event-stream frame.
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).