API integration

#!/usr/bin/env bash
# Usage: tool/api_sync.sh [docs|staging|local|<url>]   (default: docs)
set -euo pipefail
case "${1:-docs}" in
  docs)    URL="${DOCS_BASE_URL:?set DOCS_BASE_URL to the docs site origin}/openapi/hoco-v1.json" ;;
  staging) URL="https://api-staging.hoco.dz/openapi.json" ;;
  local)   URL="http://localhost:3100/openapi.json" ;;
  *)       URL="$1" ;;
esac
DIR=packages/hoco_api/openapi
curl -fsSL "$URL" -o "$DIR/hoco-v1.next.json"
VERSION=$(node -p "require('./$DIR/hoco-v1.next.json').info.version")
mv "$DIR/hoco-v1.next.json" "$DIR/hoco-v1.json"
echo "$VERSION" > "$DIR/CONTRACT_VERSION"
melos run api:gen
git --no-pager diff --stat -- packages/hoco_api
echo "Pinned contract $VERSION. Fix compile errors, run tests, commit: chore(api): contract $VERSION"

swagger_parser:
  schema_path: openapi/hoco-v1.json
  output_directory: lib/src/generated
  name: hoco_api
  language: dart
  json_serializer: freezed          # models as freezed classes with fromJson
  root_client: true
  root_client_name: HocoApiClient   # one entry point exposing every tag client
  put_clients_in_folder: true
  enums_to_json: true
  unknown_enum_value: true          # unknown server values decode to a fallback instead of throwing
  mark_files_as_generated: true
  skipped_parameters:               # added by interceptors, not by callers
    - X-App-Version
    - X-App-Platform
    - X-Device-Id
    - Accept-Language

@Riverpod(keepAlive: true)
HocoApiClient hocoApi(Ref ref) => HocoApiClient(ref.watch(dioProvider), baseUrl: Env.apiBaseUrl);
// usage in a repository: ref.watch(hocoApiProvider).cart.cartCheckout(idempotencyKey: key, body: request)

melos run mock
# = npx --yes @stoplight/prism-cli@5 mock packages/hoco_api/openapi/hoco-v1.json --host 0.0.0.0 --port 4010
# random data generated from the schemas instead of the examples:
npx --yes @stoplight/prism-cli@5 mock -d packages/hoco_api/openapi/hoco-v1.json --port 4010

# a specific status or example, e.g. the minimum-amount refusal of checkout:
curl -s -X POST http://localhost:4010/cart/checkout \
  -H "Authorization: Bearer test" -H "Idempotency-Key: 0192f4b8-7c1e-7a10-9f00-5b6d2c8e1a01" \
  -H "Content-Type: application/json" -H "Prefer: code=422" -d '{}'

/// dev only: env/hybrid.json sets API_BASE_URL=staging and MOCK_BASE_URL=http://10.0.2.2:4010;
/// paths whose prefix is listed in MOCK_PREFIXES go to Prism.
final class HybridRoutingInterceptor extends Interceptor {
  HybridRoutingInterceptor(this.mockBaseUrl, this.mockPrefixes);
  final String mockBaseUrl;
  final List<String> mockPrefixes; // e.g. ['/sync', '/delegate/location-pings', '/returns']

  @override
  void onRequest(RequestOptions options, RequestInterceptorHandler handler) {
    if (mockPrefixes.any(options.path.startsWith)) options.baseUrl = mockBaseUrl;
    handler.next(options);
  }
}

Dio buildApiDio({required ClientInfo info, required SessionStore session, required AppGate gate}) {
  final dio = Dio(BaseOptions(
    baseUrl: Env.apiBaseUrl,
    connectTimeout: const Duration(seconds: 10),
    sendTimeout: const Duration(seconds: 20),
    receiveTimeout: const Duration(seconds: 20),
    contentType: Headers.jsonContentType,
  ));
  dio.interceptors.addAll([
    ClientHeadersInterceptor(info),      // 1 Accept-Language, X-App-Version, X-App-Platform, X-Device-Id
    AuthInterceptor(session),            // 2 Bearer when a session exists; 401 → session expired
    IdempotencyInterceptor(),            // 3 a key on every mutation that has none
    RetryInterceptor(dio),               // 4 safe retries only
    GateInterceptor(gate),               // 5 426 → forced update, 503 MAINTENANCE → maintenance
    if (!Env.isProd) LogInterceptor(requestHeader: false, responseBody: false),
  ]);
  dio.addSentry();                       // sentry_dio: breadcrumbs and spans
  return dio;
}

final class IdempotencyKeyHolder {
  IdempotencyKeyHolder({required String Function() newKey}) : _newKey = newKey;
  final String Function() _newKey;
  Object? _payload;
  String? _key;

  /// Same payload (by value) → same key; different payload → new key.
  String keyFor(Object payload) {
    if (_key == null || payload != _payload) {
      _payload = payload;
      _key = _newKey();
    }
    return _key!;
  }

  void reset() => _key = _payload = null; // after success
}

final class ServerEvent {
  const ServerEvent({required this.id, required this.type, required this.data});
  final String? id;
  final String type;   // order.status_changed, order.modified, assisted_order.awaiting_confirmation,
                       // return.status_changed, ticket.replied, ticket.resolved, notification.created, resync
  final String data;   // JSON
}

final class EventStreamClient {
  EventStreamClient(this._sseDio); // same headers and auth interceptors, no receiveTimeout
  final Dio _sseDio;

  Stream<ServerEvent> connect({String? lastEventId, CancelToken? cancel}) async* {
    final response = await _sseDio.get<ResponseBody>(
      '/events',
      cancelToken: cancel,
      options: Options(
        responseType: ResponseType.stream,
        headers: {
          'Accept': 'text/event-stream',
          'Cache-Control': 'no-cache',
          if (lastEventId != null) 'Last-Event-ID': lastEventId,
        },
      ),
    );
    final lines = response.data!.stream
        .cast<List<int>>()
        .transform(utf8.decoder)
        .transform(const LineSplitter())
        .timeout(const Duration(seconds: 60)); // the server sends a heartbeat every 25 s
    String? id;
    String? type;
    final data = StringBuffer();
    await for (final line in lines) {
      if (line.isEmpty) {
        if (data.isNotEmpty) yield ServerEvent(id: id, type: type ?? 'message', data: data.toString());
        type = null;
        data.clear();
      } else if (line.startsWith(':')) {
        continue; // heartbeat comment
      } else if (line.startsWith('id:')) {
        id = line.substring(3).trim();
      } else if (line.startsWith('event:')) {
        type = line.substring(6).trim();
      } else if (line.startsWith('data:')) {
        if (data.isNotEmpty) data.write('\n');
        data.write(line.substring(5).trimLeft());
      }
    }
  }
}

final class CursorPage<T> {
  const CursorPage(this.items, this.nextCursor);
  final List<T> items;
  final String? nextCursor;
  bool get hasMore => nextCursor != null;
}

@riverpod
class OrdersList extends _$OrdersList {
  String? _cursor;
  bool _loadingMore = false;

  @override
  Future<List<OrderSummary>> build(OrderFilter filter) async {
    final page = await ref.watch(ordersRepositoryProvider).list(filter, limit: 20);
    _cursor = page.nextCursor;
    return page.items;
  }

  bool get hasMore => _cursor != null;

  Future<void> loadMore() async {
    if (_cursor == null || _loadingMore || !state.hasValue) return;
    _loadingMore = true;
    try {
      final page = await ref.read(ordersRepositoryProvider).list(filter, cursor: _cursor, limit: 20);
      if (!ref.mounted) return;
      _cursor = page.nextCursor;
      state = AsyncData([...state.requireValue, ...page.items]);
    } finally {
      _loadingMore = false;
    }
  }
}

/// Integer centimes of DZD (125000 = 1 250,00 DA). Never a double.
extension type const Money(int centimes) {
  Money operator +(Money other) => Money(centimes + other.centimes);
  Money operator -(Money other) => Money(centimes - other.centimes);
  Money times(int quantity) => Money(centimes * quantity);
}

/// "1 250 DA", or "1 250,50 DA" when there are centimes. Division happens for display only.
String formatDa(Money amount, {String locale = 'fr'}) {
  final whole = amount.centimes % 100 == 0;
  final f = NumberFormat.decimalPatternDigits(locale: locale, decimalDigits: whole ? 0 : 2);
  return '${f.format(amount.centimes / 100)} DA';
}

/// A price the caller may see — null for a guest (shown as a lock).
@freezed
abstract class Price with _$Price {
  const factory Price({required Money ht, required Money ttc, required int vatRateBasisPoints}) = _Price;
}

/// The only stock information outside the back-office (STK-07).
enum Availability { inStock, outOfStock, unknown }

abstract final class BusinessTime {
  static const _offset = Duration(hours: 1); // Africa/Algiers: UTC+1, no daylight saving
  /// Wall-clock fields in Algiers, for formatting only (never call toLocal(): the phone's zone may be wrong).
  static DateTime wall(DateTime utc) => utc.toUtc().add(_offset);
  /// The business day (YYYY-MM-DD) an instant belongs to — tours, objectives, reports.
  static String day(DateTime utc) => DateFormat('yyyy-MM-dd').format(wall(utc));
}

/// Mirrors normalizeDzPhone of @hoco/shared in hoco — same test vectors in both repositories.
String? toE164(String input) {
  final s = input.replaceAll(RegExp(r'[\s.\-()]'), '');
  final national = switch (s) {
    _ when s.startsWith('+213') => s.substring(4),
    _ when s.startsWith('00213') => s.substring(5),
    _ when s.startsWith('0') => s.substring(1),
    _ => null,
  };
  if (national == null || !RegExp(r'^[2-9]\d{7,8}$').hasMatch(national)) return null;
  return '+213$national';
}

bool isMobile(String e164) => RegExp(r'^\+213[567]\d{8}$').hasMatch(e164); // OTP and WhatsApp need one

/// +213555123456 → 0555 12 34 56
String displayPhone(String e164) {
  final n = e164.substring(4);
  return n.length == 9
      ? '0${n.substring(0, 3)} ${n.substring(3, 5)} ${n.substring(5, 7)} ${n.substring(7)}'
      : '0$n';
}

final class UploadService {
  UploadService(this._files, this._storageDio); // _storageDio: bare Dio, no API interceptors
  final FilesClient _files;
  final Dio _storageDio;

  Future<FileRef> upload(PreparedFile file, {required FilePurpose purpose, required UploadKeys keys}) async {
    final request = CreateUploadRequest(
      purpose: purpose,
      fileName: file.name,
      mimeType: file.mimeType,
      size: file.length,
      checksumSha256: file.sha256Base64,
    );
    var ticket = await _files.filesCreateUpload(idempotencyKey: keys.create, body: request);
    try {
      await _put(ticket, file);
    } on DioException catch (e) {
      if (e.response?.statusCode != 403) rethrow;
      // URL expired (10 minutes): same key → same fileId with a freshly signed URL
      ticket = await _files.filesCreateUpload(idempotencyKey: keys.create, body: request);
      await _put(ticket, file);
    }
    return _files.filesCompleteUpload(fileId: ticket.fileId, idempotencyKey: keys.complete);
  }

  Future<void> _put(UploadTicket ticket, PreparedFile file) => _storageDio.put<void>(
        ticket.uploadUrl,
        data: file.openRead(),
        options: Options(headers: {...ticket.headers, Headers.contentLengthHeader: file.length}),
      );
}