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';

const authClient = new HermesAuthClient({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret', // Optional
  authBaseUrl: 'https://authme.myhermes.de', // Production
});

// Authenticate
const tokenResponse = await authClient.authenticateWithPassword(
  'username',
  'password'
);

// Create API client for authenticated requests
const apiClient = new HermesApiClient(
  authClient,
  'https://your-api.myhermes.de'
);

// Make authenticated API calls
const data = await apiClient.get('/api/endpoint');

Authorization Code Grant Flow

// Step 1: Get authorization URL
const authUrl = authClient.getAuthorizationUrl(
  'https://your-app.com/callback',
  'optional-state-string'
);
// Redirect user to authUrl

// Step 2: Exchange code for tokens
const tokenResponse = await authClient.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 expired
const data = await apiClient.get('/api/protected-endpoint');

Shipment Tracking

Track Hermes shipments using the HSI API:

import { HermesShipmentApi } from 'hermes-api';

// Create shipment API instance
const shipmentApi = new HermesShipmentApi(apiClient);

// Get shipment information
const shipmentInfo = await shipmentApi.getShipmentInfo('1234567890123456');
console.log('Status:', shipmentInfo.statusLangText);
console.log('Expected Delivery:', shipmentInfo.voraussichtlicherZustelltag);

// Check if delivered
const isDelivered = await shipmentApi.isShipmentDelivered('1234567890123456');

// Get tracking history
const history = await shipmentApi.getTrackingHistory('1234567890123456');

// Get proof of delivery
const pod = await shipmentApi.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