pragma_path_api_client

Documentación detallada del paquete Dart/Flutter pragma_path_api_client.

Este paquete proporciona utilidades y una capa de cliente para interactuar con una Fake Store API (API de ejemplo) y expone notifiers y helpers para consumir dicha API desde una aplicación Flutter.

---

Resumen

pragma_path_api_client es un paquete cliente que sigue una arquitectura por capas (core, data, domain, presentation). Proporciona:

• Cliente HTTP minimalista y adaptador (core/network).
• Modelos y mappers para productos, carritos y usuarios (data/mappers, models).
• Casos de uso y entidades en la capa domain.
• Notifiers y un punto de entrada público FackeStoreApiClient para obtener ProductsNotifier, CartsNotifier y UsersNotifier desde la capa de presentación (útil en Flutter apps).

---

Características principales

• API-friendly: devuelve resultados envueltos en Either<Failure, T> para un manejo de errores funcional.
• Separación clara de responsabilidades (inspirado en Clean Architecture).
• Integración con riverpod para estado y dartz para tipos funcionales.
• App de ejemplo incluida en example/ que demuestra las operaciones básicas.

---

Requisitos

• Dart SDK: ^3.9.2
• Flutter: sigue la restricción en pubspec.yaml (revisar antes de publicar).
• Dependencias principales: riverpod, http, dartz, logger.

Nota: verifica la versión de Flutter que usas localmente. Si tu objetivo es publicar el package para usuarios de Flutter 3.x, actualiza el constraint en pubspec.yaml a flutter: ">=3.0.0" (ver sección "Sugerencias para pubspec").

---

Instalación

Añade en el pubspec.yaml de tu proyecto consumidor:

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

O si el paquete ya está publicado en pub.dev:

dependencies:
  pragma_path_api_client: ^0.0.1

Luego:

flutter pub get

---

Uso rápido (ejemplo)

Importa el punto de entrada público y utiliza los notifiers expuestos por la librería. Los notifiers implementan métodos async para cargar datos.

import 'package:pragma_path_api_client/pragma_path_api_client.dart';

// Obtener el notifier de productos
final productsNotifier = FackeStoreApiClient.productsNotifier();

// Cargar todos los productos
final products = await productsNotifier.loadAllProducts();

// Obtener un producto por id
final product = await productsNotifier.loadProductById(1);

Observación: los métodos del Notifier devuelven tipos nulos (Product? o List<Product>?) en la implementación actual del ejemplo; maneja null en tu código según sea necesario.

---

API pública (resumen)

Los puntos de entrada más relevantes para consumidores del paquete son:

• FackeStoreApiClient (en lib/pragma_path_api_client.dart)
  • productsNotifier() → devuelve ProductsNotifier.
  • cartsNotifier() → devuelve CartsNotifier.
  • usersNotifier() → devuelve UsersNotifier.

Además, el paquete exporta el contenido de core/network (clientes HTTP) y los modelos en domain/entities para que puedas usarlos en tu app.

Para una referencia completa de la API, revisa los comentarios /// dentro de los archivos en lib/ (ya añadidos a las clases centrales).

---

Ejemplo

La carpeta example/ contiene una app Flutter que demuestra las operaciones más comunes (obtener productos, crear producto, obtener carritos y usuarios). Ejecuta la app de ejemplo con:

cd example
flutter pub get
flutter run

---

Buenas prácticas al usar el paquete

• Maneja los Failure y valores nulos devueltos por los notifiers.
• Para tests, inyecta un HttpMethod mock en HttpClientImpl (la implementación permite delegación), o mockea los notifiers en la capa de presentación.
• Añade timeouts y reintentos en la capa cliente si tus escenarios lo requieren.

Contribuciones

Se agradecen PRs. Por favor:

1. Abre un issue describiendo el cambio o bug.
2. Crea una rama con un nombre claro.
3. Añade tests cuando sea apropiado.
4. Mantén el estilo y usa dart format.

---

Licencia

Este proyecto está licenciado bajo la licencia MIT. El texto completo de la licencia se encuentra en el archivo LICENSE del repositorio. La licencia incluye la atribución al autor:

MIT License

Copyright (c) 2025 Jhony Rentería Rodríguez

Puedes usar, copiar y modificar el código conforme a los términos de la licencia MIT; revisa el archivo LICENSE para los detalles completos.