Datatypes, not tables
AppEngine does not hand out a fixed set of tables. Every record has a datatype —
sf_product, reservation, customer, or one you define — and the same handful
of calls can address permitted datatypes. Sensitive account operations have dedicated APIs. That is the part worth understanding first: you are
not limited to the datatypes the platform ships with.
Video tutorials for this topic
Records come back as plain maps with the fields under data. The client does not
impose models, because your app knows its own shapes better than a generic
client can.
Reading
final page = await appmint.repository.find(
'sf_order',
filter: {'data.status': 'open'},
pageSize: 20,
sort: {'createdate': -1},
);
page.items; // List<Map<String, dynamic>>
page.total;
page.hasMore;
page.page; // 1-based; next request uses page: page.page + 1
page.pageSize;find defaults to page 1 and page size 50. The request body is
{query: filter, options: {page, pageSize, sort, sortType}}. Only the first
entry in sort is sent; multiple map entries do not produce a compound sort.
Numeric directions pass through; strings starting with asc become 1, other
strings become -1.
The parser accepts a list or a data/items list inside a map. total falls
back to the returned item count if absent, so hasMore cannot prove that an
unreported next page does not exist. It computes page * pageSize < total.
filter is passed through as-is, so it takes the query shape the server
understands, including operators:
filter: {'data.total': {r'$gt': 100}}One record by id:
final order = await appmint.repository.findById('sf_order', id);
final fields = order?['data']; // Map when the response is a record envelopeIt can return records that merely resemble the value you passed. Read what
comes back and confirm each record is the one you meant before acting on it —
and never pipe its results straight into delete. That mistake has destroyed
live records.
The wrapper returns null for a successful non-map findById response; HTTP
404 still throws. It does not URL-encode datatype, ID, attribute, or attribute
value segments. Use known URL-safe identifiers or encode individual segments
with Uri.encodeComponent before passing them to helpers.
Generic repository access remains subject to backend datatype and ownership
rules. Use /client-data/* for customer self-service and domain APIs for
business actions; the existence of a helper does not grant access or trigger
all of a domain service’s side effects.
Writing
final created = await appmint.repository.create('my_datatype', {'title': 'Hello'});
await appmint.repository.update('my_datatype', id, {'title': 'Replaced'});
await appmint.repository.updateFields('my_datatype', id, {
'data.title': 'Renamed',
'data.settings.theme': 'dark',
});
await appmint.repository.delete('my_datatype', id);create sends {datatype, isNew: true, data}. A nonempty map is returned as
received. An empty successful response throws AppmintException with
reason: 'duplicate_create' and statusCode: 200; do not render it as a saved
record. update wraps the supplied fields in {data: ...}, while
updateFields sends your map at the root. Both return an empty map for a
successful non-map response, so read back important changes by ID.
Two details matter for writes:
updateFields takes dot paths, not a nested map. Passing
{'data': {'settings': {'theme': 'dark'}}} replaces that whole branch and drops
its other keys, quietly.
Create is a PUT on the server, not a POST. The client handles that; you
only meet it if you call the endpoint yourself and get a 404.
Everything else
The package wraps the calls every app needs. Anything else is one line away, with headers and tokens still handled:
final profile = await appmint.http.get('/client-data/profile');
await appmint.http.put('/client-data/profile', body: {'firstName': 'Alex'});
final tickets = await appmint.http.get('/events/$eventId/tickets');Pass sendUserToken: false for a call that should go out with app
authentication alone. HTTP results are dynamic: JSON maps/lists remain their
actual shape, an empty body becomes null, and a non-JSON success body stays
a string. Validate a route’s response instead of casting every success to a map.
get accepts Map<String, String> query values. For a POST with query parameters,
use send:
final result = await appmint.http.send(
'POST',
'/crm/inbox/update',
query: {'send': 'true'},
body: messageRecord, // A valid message record for the CRM inbox contract.
);Do not append ?send=true to path: send rebuilds the URI query and removes
an inline query when no separate query map is supplied. The current CRM sample
contains this inline-query pattern; adapt it using send before relying on SMS
sending. Empty query values, literal null, and NaN are omitted. Browser GETs
also receive a _ts parameter to avoid stale browser cache results.
Multipart uploads
upload(path, bytes:, fileName:, fields:, field: 'file') POSTs one multipart
file and returns a map or {}. The target must explicitly support that form
field and any required metadata. A route-specific upload example is the chat
package’s sendAttachments, documented below.
Unlike normal requests, this helper does not retry, refresh on 401, emit
onCall, or wrap transport failures in AppmintNetworkException. It always
attaches the current user token if present. The send timeout is twice the
configured timeout; it is not a guarantee for fully consuming the streamed
response. Handle transport exceptions separately and reconcile uploads before
retrying.
Chat and attachments
appmint_flutter_chat is a separate package in the same repository. It does not
depend on the Flutter client; the host supplies a customer JWT callback:
import 'package:appmint_flutter_chat/appmint_flutter_chat.dart';
final chatConfig = AppmintChatConfig(
endpoint: appmint.config.baseUrl,
orgId: appmint.config.orgId,
user: AppmintChatUser(email: user.email, name: user.displayName),
token: () async => appmint.http.userToken,
onTokenExpired: () async {
final token = await appmint.auth.refreshSession();
if (token == null) await appmint.auth.signOut();
},
);
// In a Flutter route:
// AppmintSupportChatScreen(config: chatConfig)The screen creates, starts, and disposes its controller. With your own layout,
retain one AppmintChatController, await start(), render AppmintChatView,
and dispose the controller when leaving the account or organization. Render
connection, error, and canSend; a connected socket is not yet authenticated.
Do not pass the app token to chat.
The service connects to the /chat Socket.IO namespace with WebSocket transport.
The server emits authenticate; the client does not emit an authentication
message. Threads use customer::<lowercase-email>. Optional configId and
appId select the site’s chat setup; AppmintSiteChat.fromSite(site) reads these
from the site record. Optional loadSessionId/saveSessionId callbacks resume
the server-issued chat session; partition their storage by endpoint, org,
customer and chat config.
controller.sendAttachments accepts AppmintChatAttachment objects holding
List<int> bytes, name, and mimeType. Supply a picker through the screen’s
onPickAttachments; the package does not request camera/library permissions.
Chat upload uses multipart files on /chat/upload/:scope/:email, where
scope is configId or chatId, with the customer token in Authorization.
This is a different authentication contract from normal Appmint HTTP requests.
Uploaded path is durable; signed url may expire. Current service comments
report that history strips attachments; do not promise their persistence in the
history UI without checking your server.
Initial authenticate rejection with token_expired triggers one refresh and
restart in the controller. A later token_expired event calls the callback and
sets failure state but does not itself reconnect; expose controller.retry()
after successful renewal. Outgoing messages can become failed, and there is
no durable offline queue. See the chat example.
Watching what it does
appmint.http.onCall = (call) {
print('${call.method} ${call.path} → ${call.status} '
'(${call.took.inMilliseconds}ms) '
'app:${call.appAuthenticated} user:${call.sentUserToken}');
};AppmintCall carries no token values — only whether each was attached, which is
the genuinely confusing part of this API. The authentication example
puts this on screen beside the app.
onCall reports completed response paths, including app authentication. It is
not a complete wire trace: transport failures, uploads, and the initial 401
before renewal are not each emitted as separate events. Do not let an observer
throw. logRequests: true logs request information and error-body excerpts;
redact those before sharing.
Errors
Failures arrive as AppmintException, and message is safe to show — AppEngine
writes its refusals in plain language and the client passes them through rather
than replacing them.
| Type | Means |
|---|---|
AppmintException | The server answered and refused. statusCode, and reason where it gives one — invalid_code and challenge_expired need different cures |
AppmintAppAuthException | The app itself could not sign in. reason carries AppEngine's code (attestation_off, debug_token_invalid, cert_mismatch, secret_refused, …) or proof_unavailable / proof_failed from the device; see Phone apps without a secret. No request can succeed until it is fixed |
AppmintSessionExpiredException | The session is gone and could not be renewed. Send them back to sign-in |
AppmintNetworkException | No usable HTTP response was received; timeout/reset can leave a write’s outcome unknown |
Normal calls retry recognized transport errors up to transientRetries total
attempts, with 400 * attempt milliseconds between attempts (400, 800, 1200 ms
for the default four attempts). This applies to writes too. A 5xx is not
transport-retried; a 401 has the separate renewal path. For a non-idempotent
operation, use a client configured with transientRetries: 1 and reconcile a
lost response by reading the saved record or domain status. This setting does
not disable the separate 401 retry.
That last distinction matters: a 400 is an answer, and calling it a network error sends people to check their wifi instead of their password.
Related
Current AppEngine account-write restrictions
The13 October 2026 backend source rejects generic partial updates for user, customer, apikey, user_security and two_factor_backup. Generic user/customer deletion is also refused. Use the dedicated profile, staff-management or security API with its required permissions. A repository helper does not bypass those restrictions or reproduce notifications, audit and session cleanup performed by domain operations.
