Hermes API Authentication Client

A TypeScript/JavaScript client library for authenticating with the Hermes Business Customer Authentication API, implementing OAuth 2.0 with support for Password Grant, Authorization Code Grant, and Refresh Token flows.

Installation

bun install

Features

• OAuth 2.0 Grant Types:
  • Password Grant
  • Authorization Code Grant
  • Refresh Token Grant
• Automatic Token Management:
  • Token refresh on expiry
  • Configurable expiry buffer
  • Persistent token storage (browser)
• API Client with Auth Middleware:
  • Automatic Authorization header injection
  • Automatic token refresh and request retry
• JWT Token Utilities:
  • Token decoding
  • Expiry checking
  • User info extraction

Quick Start

Password Grant Flow

import{HermesAuthClient,HermesApiClient}from'hermes-api';constauthClient=newHermesAuthClient({clientId: 'your-client-id',clientSecret: 'your-client-secret',// OptionalauthBaseUrl: 'https://authme.myhermes.de',// Production});// AuthenticateconsttokenResponse=awaitauthClient.authenticateWithPassword('username','password');// Create API client for authenticated requestsconstapiClient=newHermesApiClient(authClient,'https://your-api.myhermes.de');// Make authenticated API callsconstdata=awaitapiClient.get('/api/endpoint');

Authorization Code Grant Flow

// Step 1: Get authorization URLconstauthUrl=authClient.getAuthorizationUrl('https://your-app.com/callback','optional-state-string');// Redirect user to authUrl// Step 2: Exchange code for tokensconsttokenResponse=awaitauthClient.exchangeAuthorizationCode('authorization-code-from-redirect','https://your-app.com/callback');

Automatic Token Refresh

The API client automatically handles token refresh:

// Token will be refreshed automatically if expiredconstdata=awaitapiClient.get('/api/protected-endpoint');

Shipment Tracking

Track Hermes shipments using the HSI API:

import{HermesShipmentApi}from'hermes-api';// Create shipment API instanceconstshipmentApi=newHermesShipmentApi(apiClient);// Get shipment informationconstshipmentInfo=awaitshipmentApi.getShipmentInfo('1234567890123456');console.log('Status:',shipmentInfo.statusLangText);console.log('Expected Delivery:',shipmentInfo.voraussichtlicherZustelltag);// Check if deliveredconstisDelivered=awaitshipmentApi.isShipmentDelivered('1234567890123456');// Get tracking historyconsthistory=awaitshipmentApi.getTrackingHistory('1234567890123456');// Get proof of deliveryconstpod=awaitshipmentApi.getProofOfDelivery('1234567890123456');

API Reference

HermesAuthClient

• authenticateWithPassword(username, password) - Password grant authentication
• exchangeAuthorizationCode(code, redirectUri) - Exchange auth code for tokens
• refreshAccessToken(refreshToken?) - Refresh access token
• getAuthorizationUrl(redirectUri, state?) - Get OAuth authorization URL
• getAccessToken() - Get current access token (auto-refresh if expired)
• getAuthorizationHeader() - Get Bearer token header value
• isAuthenticated() - Check if authenticated with valid token
• logout() - Clear stored tokens

HermesApiClient

• get(endpoint, options?) - GET request
• post(endpoint, data?, options?) - POST request
• put(endpoint, data?, options?) - PUT request
• delete(endpoint, options?) - DELETE request
• patch(endpoint, data?, options?) - PATCH request

HermesShipmentApi

• getShipmentInfo(trackingNumber) - Get complete shipment information
• getMultipleShipmentInfo(trackingNumbers[]) - Get info for multiple shipments
• getShipmentStatus(trackingNumber) - Get current status text
• isShipmentDelivered(trackingNumber) - Check if delivered
• getEstimatedDeliveryDate(trackingNumber) - Get expected delivery date
• getTrackingHistory(trackingNumber) - Get full tracking history
• getProofOfDelivery(trackingNumber) - Get proof of delivery details
• getRecipientInfo(trackingNumber) - Get recipient information
• getEcoInfo(trackingNumber) - Get ecological impact information
• getReturnInfo(trackingNumber) - Get return label information

TokenManager

• saveToken(token) - Save token to localStorage
• getToken() - Retrieve saved token
• clearToken() - Remove saved token
• decodeToken(token) - Decode JWT without verification
• isTokenExpired(token) - Check token expiry
• getTokenTimeToLive(token) - Get seconds until expiry
• extractUserInfo(token) - Extract user claims from token

Configuration

Auth Endpoints

• Production: https://authme.myhermes.de
• Integration: https://authme-int.myhermes.de

Token Information

• Access tokens are valid for 1 hour
• Tokens are JWT format with max size of 8KB
• Automatic refresh occurs 5 minutes before expiry

Examples

• examples/usage.ts - Authentication and API usage examples
• examples/shipment-tracking.ts - Shipment tracking examples

Development

This project uses Bun runtime.

# Install dependencies
bun install
# Run examples
bun run examples/usage.ts