transport library

The transport under every sApp connection profile, for building another profile over the same core: operation types, URI building with the extra query, header parameters and idempotency keys, retries, and SuperrouteException for refused answers (status 400 or more, or result: false).

Apps use package:sapp/sapp.dart; this library is for packages that add a connection profile, so that they reuse this behaviour instead of copying it.

Classes

Operation
One operation of a generated API: its method, path template, authentication, query names, body kind and the header parameters it declares (Idempotency-Key, X-Guest-Order-Token, …).
OperationFile
A file sent with a multipart operation (photos, signatures).

Enums

OperationAuth
How an operation authenticates (docs/PLATFORM-APP-SDK-DESIGN.md §8, §9).
OperationBody
How an operation's body is sent.

Constants

extraQueryKey → const String
The key of the parameter map that carries a call's extra query: names the spec does not declare, appended after the declared ones and never replacing one.
protectedHeaders → const Set<String>
Headers the SDK sets itself; a header argument never replaces them.
sdkVersion → const String

Functions

buildOperationRequest(Uri uri, Operation operation, Map<String, String> headers, Map<String, Object?>? body, List<OperationFile>? files) → BaseRequest
The request of one attempt: a JSON, form or multipart body as the operation declares.
buildOperationUri(String baseUrl, Operation operation, Map<String, Object?> params, {String pathPrefix = ''}) → Uri
The URI of one call: the path template filled from params, the declared query and then the extra query. The path replaces baseUrl's own path; pathPrefix (/api) goes before it.
decodeAnswer(Response response) → Object?
The answer's body as parsed JSON, the text when it is not JSON, or null when empty.
isRefusedAnswer(int status, Object? decoded) → bool
A refused call: status 400 or more, or a JSON object answering result: false (even with a 2xx status).
operationCallHeaders(Operation operation, Map<String, Object?> params) → Map<String, String>
The header parameters of one call, worked out once so every attempt of the call sends the same values: an operation that declares Idempotency-Key gets a fresh key when the caller gave none.
parseRetryAfter(String? value, {DateTime? now}) → int?
A Retry-After value in whole seconds: a non-negative integer as it is, an HTTP-date as the seconds from now until it (rounded up, at least 0), anything else (or none) null.
sendWithRetries(Client client, BaseRequest build(), {required int retries, required bool retryable}) → Future<Response>
Repeatable calls are retried on a lost connection, 502–504 and 429 with Retry-After. Writes are never retried.
superrouteErrorFrom(int status, Object? body, String? requestId, {Map<String, String> headers = const {}}) → SuperrouteException
The SuperrouteException of a refused answer: its code, message, field errors, reasons, data, request id (the body's request_id, else requestId, else the X-Request-Id of headers), headers and Retry-After.
superrouteErrorFromResponse(Response response, Object? decoded) → SuperrouteException
The SuperrouteException of a refused response whose body was decoded to decoded: status, body, headers, Retry-After and request id.
withCallHeaders(Map<String, String> headers, Map<String, String> extra) → Map<String, String>
Adds extra to headers without replacing a header the SDK set (compared without regard to case).

Typedefs

OperationCall = Future Function(Operation operation, Map<String, Object?> params, {Map<String, Object?>? body, List<OperationFile>? files})
What a generated API calls for each operation: the path, query and header values (and the extra query under extraQueryKey), and the body.

Exceptions / Errors

SuperrouteException
Every failed call. status is the HTTP status (0 when the request never got an answer), code the server's error code (invalid_token, insufficient_scope, access_denied, a platform app code such as APP_ACCESS_DENIED, …).