artemis_timatic 0.0.12

A Dart/Flutter client for Timatic-powered APIs — handles authentication, token management, and provides strongly-typed methods to query locations, parameters, accepted values, and submit Timatic docum [...]

artemis_timatic

A lightweight, strongly-typed Dart/Flutter client for your Timatic-powered API.
Handles auth tokens for you and exposes simple methods to fetch locations, parameters, accepted values, and to submit the main Timatic document request.

• ✅ Null-safe
• ✅ Built on dio
• ✅ Token auto-injected after login
• ✅ Json-serializable models
• ✅ Friendly typed errors

---

Installation

Add to your app’s pubspec.yaml:

dependencies:
  artemis_timatic: ^0.1.0

If you’re testing locally:

dependencies:
  artemis_timatic:
    path: ../artemis_timatic

Or from git:

dependencies:
  artemis_timatic:
    git:
      url: https://github.com/your-org/artemis_timatic.git
      ref: main

Consumers do not need to run code generation. That’s done in this package.

---

Quick Start

import 'package:artemis_timatic/timatic.dart';
import 'package:artemis_timatic/src/models/auth_request.dart'; // or export in root if you prefer

void main() async {
  // 1) Create client + API
  final client = TimaticClient(
    TimaticClientOptions(baseUrl: 'https://your-api.example.com'),
  );
  final api = TimaticApi(client);

  // 2) Login — pass app/device/network as raw JSON maps
  await api.login(LoginRequest(
    username: 'superadmin',
    password: '••••••••',
    app: {"name": "DCS One", "id": "1e5rt71e"},
    device: {"type": 2, "model": "MacBookPro"}, // anything your API expects
    network: {"type": 0, "ip": "192.168.1.5"},
  ));
  // Token is now stored and auto-attached to all future requests.

  // 3) Call endpoints
  final airports = await api.listLocationsByType(LocationType.AIRPORT, name: 'Istanbul');

  final params = await api.getParameters(codes: ['pets']);

  final accepted = await api.getAcceptedValues(
    countryCode: 'TR',
    parameter: 'docIssueCountry',
    ruleSetTypes: ['REQDOC'],
  );

  final resp = await api.submitDocumentRequest(
    DocumentRequest(
      documentDetails: [
        DocumentDetail(
          documentCode: 'OFFICIALPASSPORT',
          documentExpiryDate: '2024-01-31',
          documentIssueCountry: 'AFG',
        ),
      ],
      itineraryDetails: ItineraryDetails(
        segments: [
          ItinerarySegment(
            arrival: ItinPoint(
              date: '2023-12-28',
              time: '08:54',
              dateTime: '2023-12-28T08:54:05',
              point: 'AAH',
              type: LocationType.AIRPORT,
            ),
            departure: ItinPoint(
              date: '2023-12-28',
              time: '08:54',
              dateTime: '2023-12-28T08:54:05',
              point: 'IST',
              type: LocationType.AIRPORT,
            ),
            processingEntity: 'ABOMIS DOC CHECK',
          ),
        ],
      ),
      passengerDetails: PassengerDetails(
        birthDate: '2023-12-13',
        nationality: 'ALB',
      ),
    ),
  );

  print('Transaction: ${resp.transactionId}  Result: ${resp.evaluationResult}');
}

---

What’s Included

Auth & Token Handling

• api.login(LoginRequest) posts your credentials and raw app/device/network maps.
• The returned token is stored inside TimaticClient.
• All subsequent requests automatically add:

  Authorization: Bearer <token>
  

• You can read/override if needed:

  client.setAuthToken('new-token');
  print(client.authToken);
  

Endpoints

// Locations
Future<List<Location>> listLocationsByType(
  LocationType type, { String? code, String? name });

Future<List<Location>> searchLocations({
  List<LocationType>? types, String? code, String? name });

// Parameters
Future<ParametersEnvelope> getParameters({
  required List<String> codes, String? name });

// Accepted Values
Future<AcceptedValuesEnvelope> getAcceptedValues({
  required String countryCode,
  required String parameter,
  List<String>? ruleSetTypes });

// Main Timatic Request
Future<DocumentResponse> submitDocumentRequest(DocumentRequest body);

Key Models (selection)

• LoginRequest (uses raw Map<String,dynamic> for app, device, network)
• Location, LocationType
• ParametersEnvelope, ParameterItem, ParameterValue
• AcceptedValuesEnvelope, AcceptedRuleSet, AcceptedParameter, AcceptedValue
• DocumentRequest, DocumentDetail, ItineraryDetails, ItinerarySegment, ItinPoint, PassengerDetails
• DocumentResponse, EvalResult, SegmentResult, RuleSetEvaluation, Regulation, RichTextBlock

---

Errors

All methods throw typed errors so you can handle them precisely:

• TimaticError – base error
• TimaticNetworkError – networking/HTTP issues (has statusCode)
• TimaticParsingError – unexpected JSON shapes

Example:

try {
  final resp = await api.submitDocumentRequest(req);
} on TimaticNetworkError catch (e) {
  // e.statusCode, e.message
} on TimaticParsingError catch (e) {
  // backend changed response shape?
} on TimaticError catch (e) {
  // general fallback
}

---

Configuration

final client = TimaticClient(TimaticClientOptions(
  baseUrl: 'https://your-api',
  apiKey: null,                  // if your gateway needs it (sent as X-API-Key)
  headers: {'X-Custom': '1'},
  connectTimeout: Duration(seconds: 10),
  sendTimeout: Duration(seconds: 20),
  receiveTimeout: Duration(seconds: 20),
));

If your auth header isn’t standard Bearer, change the interceptor in TimaticClient.

---

HTML Texts

Some regulations include HTML in RichTextBlock.text.
Render it in your app with your favorite HTML widget, or strip tags if you need plain text.

---

Contributing (for maintainers)

This package uses json_serializable.

Install dev deps and generate code:

dart pub get
dart run build_runner build --delete-conflicting-outputs

Internal dependencies (already in this package’s pubspec.yaml):

dependencies:
  dio: ^5.7.0
  json_annotation: ^4.9.0

dev_dependencies:
  build_runner: ^2.4.11
  json_serializable: ^6.9.0
  flutter_lints: ^4.0.0

---

Roadmap

• ❌ Optional token persistence (e.g., SharedPreferences) so login survives app restarts
• ❌ Auto-relogin/refresh on 401
• ❌ More typed enums for rule set types / applicability flags
• ❌ Helpers to sanitize or summarize HTML advisories

---

License

MIT (or your preferred license). Add a LICENSE file at the repo root.

---

Support

Issues & PRs welcome. For private API questions, share example payloads and we’ll update models/endpoints quickly.

---

Happy shipping ✈️