lucqait_sdk_geodata_service 0.2.1

Flutter/Dart client SDK for LUCQA ms-geo-data-service. Typed HTTP client, domain error hierarchy (9 subclasses), multi-tenant support, and exponential retry.

lucqait_sdk_geodata_service

Flutter/Dart client SDK for LUCQA ms-geo-data-service.

Provides a typed HTTP client with automatic Bearer auth injection, exponential retry on 5xx errors, and a domain error hierarchy that mirrors the backend contract 1:1 — so you can use on EntityNotFoundError instead of parsing status codes.

Status: 0.1.x — Core module (client + errors + tenant). GIS helpers and Riverpod state layer coming in upcoming releases.

Features

• Typed errors — 9 sealed subclasses of LucqaApiError mapped from backend error codes (ENTITY_NOT_FOUND, VALIDATION_ERROR with field-level messages, UNAUTHORIZED, etc.).
• Automatic retry — exponential backoff on 5xx (2^n × 200 ms, configurable via maxRetries).
• Multi-tenant — getSchema callback + tenantPath() helper inject the tenant schema into every path.
• Auth — getToken async callback called per request; onUnauthorized hook for redirect/refresh flows.

Installation

dependencies:
  lucqait_sdk_geodata_service: ^0.1.0

Usage

import 'package:lucqait_sdk_geodata_service/core.dart';

final client = LucqaClient.create(LucqaClientOptions(
  baseUrl: 'https://api.lucqa.com',
  getToken: () async => await secureStorage.read(key: 'jwt'),
  getSchema: () => currentTenantSchema,
  onUnauthorized: () => router.go('/login'),
));

// Typed error handling
try {
  final res = await client.request(
    (dio) => dio.get('/api/v1/${client.options.getSchema!()}/regiones'),
  );
  final regiones = res.data;
} on EntityNotFoundError catch (e) {
  print('Not found: ${e.message}');
} on ValidationError catch (e) {
  print('Fields: ${e.fields}'); // {'nombre': 'no puede estar vacío'}
} on UnauthorizedError {
  // onUnauthorized callback already fired
}

Tenant path helper

// Validates the schema name against the same regex enforced by the backend.
final path = tenantPath('/api/v1/{tenant}/regiones', 'tenant_demo');
// => '/api/v1/tenant_demo/regiones'

Error hierarchy

Class	Backend code	HTTP
EntityNotFoundError	ENTITY_NOT_FOUND	404
EntityAlreadyExistsError	ENTITY_ALREADY_EXISTS	409
BusinessRuleViolationError	BUSINESS_RULE_VIOLATION	422
InvalidTenantError	INVALID_TENANT	400
ExternalServiceError	EXTERNAL_SERVICE_ERROR	502
RateLimitExceededError	RATE_LIMIT_EXCEEDED	429
ValidationError	VALIDATION_ERROR	400
UnauthorizedError	UNAUTHORIZED	401
AccessDeniedError	ACCESS_DENIED	403
UnknownLucqaError	(fallback)	any

Additional information

• Issues / feedback: github.com/lucqa-it/sdk-geodata-flutter/issues
• TypeScript counterpart: @lucqait/sdk-geodata-service