README

Paquete Laravel para integrar apps de Ometra HELA. El primer cliente incluido es para consumir la API de Auster desde otros modulos.

Instalacion

Instala el paquete desde Packagist:

composer require ometra/hela-sdk:dev-master

Laravel descubre automaticamente el service provider y el facade.

Configuracion

Publica el archivo de configuracion:

php artisan vendor:publish --tag=hela-sdk-config

Variables disponibles:

HELA_SDK_APP_NAME=heimdal
HELA_AUSTER_URL=https://auster.example.test
HELA_AUSTER_TOKEN=
HELA_SDK_TIMEOUT=30
HELA_SDK_RETRY_TIMES=0
HELA_SDK_RETRY_SLEEP=100

HELA_AUSTER_URL debe apuntar al host de Auster sin el sufijo /api. El token se envia como Authorization: Bearer, igual que espera el middleware App\Http\Middleware\Auth\API\ValidateAccessToken de Auster.

Para clients-api, Auster usa ValidateClientToken, que espera un bearer con formato {tipo}-{token}. SelfService trabaja con ClientUserToken, asi que el SDK no requiere un token global para esa seccion: llama clientsApiAsUser($token) y el SDK lo envia como USR-{token}. Si un flujo administrativo necesita un token de ClientsApiTokens, pasalo explicitamente con clientsApiAsClient($token) y se enviara como API-{token}.

Uso

use Ometra\HelaSdk\Facades\HelaSdk;

$offers = HelaSdk::auster()->offers(status: 'active');
$service = HelaSdk::auster()->serviceByMsisdn('525512345678');
$order = HelaSdk::auster()->order(100);

$firstOffer = $offers->first();
$price = $firstOffer?->publicPrice;

Los helpers tipados devuelven DTOs, no respuestas HTTP crudas:

• Listados: Ometra\HelaSdk\Dtos\DtoCollection
• Recursos: OfferDto, ServiceDto, OrderDto, UserProfileDto, etc.
• Acciones sin recurso principal: ApiResponseDto

Cada DTO conserva el payload original en attributes, expone toArray() y permite leer campos no tipados con get($key) o acceso magico ($dto->campo).

Tambien puedes hacer llamadas directas al API de Auster cuando el SDK todavia no tenga un helper especifico. Esas llamadas directas siguen devolviendo Illuminate\Http\Client\Response:

$response = HelaSdk::auster()->post('/api/log-event/example', [
    'payload' => ['status' => 'ok'],
]);

Atajos disponibles inicialmente:

• offers() y offer($id)
• portabilitiesByMsisdn($msisdn)
• serviceByMsisdn($msisdn), serviceSupplementaries($msisdn) y serviceReplacements($msisdn)
• validateActivationKey($data), validateSimCard($data) y activateService($data)
• createOrder($data), order($id), orderByMsisdn($msisdn), orderPayment($id), publishOrder($id), processOrder($id), cancelOrder($id) y addOrderPayment($id, $data)
• validatePayment($id) y cancelPayment($id)

Clients API de Auster

use Ometra\HelaSdk\Facades\HelaSdk;

$profile = HelaSdk::auster()->clientsApi()->clientProfile();
$services = HelaSdk::auster()->clientsApi()->services(filter: '525512345678');
$service = HelaSdk::auster()->clientsApi()->service('525512345678');

Las busquedas textuales en Auster usan el query param filter. Usa ese nombre en listados como catalogOffers(filter: 'Plan 20'), services(filter: '525512345678'), orders(filter: '5551234567'), simCards(filter: 'ICCID'), invoices(filter: 'folio') y cfdi(filter: 'UUID'). Los metodos siguen aceptando array $query = [] para compatibilidad y los named arguments tienen precedencia sobre ese arreglo.

Para llamar con un token de usuario devuelto por login:

$login = HelaSdk::auster()->clientsApi()->login([
    'email' => 'cliente@example.test',
    'password' => 'secret',
]);

$userProfile = HelaSdk::auster()
    ->clientsApiAsUser($login->token)
    ->userProfile();

Atajos disponibles para clients-api:

• login($data), signup($data), requestPasswordReset($data), validatePasswordResetToken($token), resetPassword($token, $data), logout() y logoutAll()
• clientProfile(), userProfile() y simCards($query)
• heartbeat($data)
• balance($query), invoices($query), invoice($id) y downloadInvoice($id)
• catalogOffers($query)
• cfdi($query), cfdiOrders(), requestCfdi($data) y downloadCfdi($uid, $format)
• orders($query), order($id) y createOrder($data)
• portabilities($query), portability($id), portabilityTransitories(), requestPortability($data) y deletePortability($id)
• services($query), service($msisdn), serviceProfile($msisdn), serviceBags($msisdn), replacementOptions($msisdn), activateOptions($msisdn), topupOptions($msisdn), renewOptions($msisdn), activateService($msisdn, $data), topupService($msisdn, $data), renewService($msisdn, $data), replaceOffer($msisdn, $data), replaceSimCard($msisdn, $data), updateServiceName($msisdn, $data), suspendService($msisdn), resumeService($msisdn), imeiLock($imei) y imeiUnlock($imei)
• users($query), user($uri), createUser($data), updateUser($uri, $data) y deleteUser($uri)

El servicio tambien se puede resolver desde el contenedor:

use Ometra\HelaSdk\HelaSdk;

$sdk = app(HelaSdk::class);
$sdk->auster()->offers();

Pruebas

composer test