TypeScript HTTP API wrapper library for Simbrief API
npm install simbrief-apiA TypeScript HTTP API wrapper library for the SimBrief API. This library provides a type-safe, class-based interface for querying SimBrief flight planning data, including airframes and user flight plans with additional functionality coming soon.
- Type-safe API calls with generic response types
- Environment variable support via dotenv
- Configurable base URL, timeout, and headers
- SimBrief-specific endpoints for airframes and flight plans
- Extensible error handling with custom ApiError class
- Clean class-based API
- Full TypeScript support with exported types
``bash`
npm install simbrief-api
- axios - HTTP client librarydotenv
- - Environment variable management
`typescript
import SimBriefApi from 'simbrief-api';
// Create a client instance
const api = new SimBriefApi();
// Fetch airframes data
const airframesResponse = await api.getAirframes();
console.log(airframesResponse.data); // Type-safe airframes data
// Fetch user flight plan
const flightPlanResponse = await api.getUserFlightPlan('username123');
console.log(flightPlanResponse.data); // Type-safe flight plan data
`
Create a .env file in your project root:
`env`
API_BASE_URL=https://www.simbrief.com/api
API_TIMEOUT=5000
The client will automatically load these values:
`typescript
import SimBriefApi from 'simbrief-api';
// Configuration from .env will be used automatically
const api = new SimBriefApi();
`
`typescript
import SimBriefApi from 'simbrief-api';
const api = new SimBriefApi({
baseURL: 'https://www.simbrief.com/api',
timeout: 10000,
headers: {
'Content-Type': 'application/json',
'X-Custom-Header': 'value',
},
});
`
- getAirframes() - Fetch all available airframes from SimBriefgetUserFlightPlan(username: string)
- - Fetch a user's flight plan by username
The library throws ApiError instances for API failures:
`typescript
import SimBriefApi, { ApiError } from 'simbrief-api';
const api = new SimBriefApi();
try {
const response = await api.getUserFlightPlan('username123');
} catch (error) {
if (error instanceof ApiError) {
console.error('Status:', error.status);
console.error('Message:', error.message);
console.error('Data:', error.data);
console.error('Headers:', error.headers);
}
}
`
Configuration interface for the API client:
`typescript`
type SimBriefApiConfig = {
baseURL?: string;
timeout?: number;
headers?: Record
}
Request-specific options (used internally):
`typescript`
type RequestOptions = {
method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
params?: Record
data?: any;
headers?: Record
timeout?: number;
}
Generic response wrapper:
`typescript`
type ApiResponse
data: T;
status: number;
headers: Record
originalResponse?: AxiosResponse
}
Error class for API failures:
`typescript`
class ApiError extends Error {
status?: number;
data?: any;
headers?: Record
originalError?: any;
}
Type definition for airframes data returned by getAirframes():
`typescript`
type Airframes = {
[aircraftCode: string]: AirframeAircraft;
// Example: A320, B738, etc.
}
Type definition for flight plan data returned by getUserFlightPlan():
`typescript`
type UserFlightPlan = {
fetch: Fetch;
params: Params;
general: General;
origin: Origin;
destination: Destination;
// ... and many more fields
}
The library exports configuration utilities:
`typescript
import { getConfigFromEnv, mergeConfig } from 'simbrief-api';
// Get configuration from environment variables
const envConfig = getConfigFromEnv();
// Merge configuration with defaults
const config = mergeConfig({
baseURL: 'https://www.simbrief.com/api',
});
`
`typescript
import SimBriefApi from 'simbrief-api';
const api = new SimBriefApi({
baseURL: 'https://www.simbrief.com/api',
});
const response = await api.getAirframes();
// Access specific aircraft data
const a320 = response.data.A320;
const b738 = response.data.B738;
console.log(A320: ${a320.aircraft_name});B738: ${b738.aircraft_name}
console.log();`
`typescript
import SimBriefApi from 'simbrief-api';
const api = new SimBriefApi({
baseURL: 'https://www.simbrief.com/api',
});
const response = await api.getUserFlightPlan('myusername');
const flightPlan = response.data;
console.log(Origin: ${flightPlan.origin?.icao_code});Destination: ${flightPlan.destination?.icao_code}
console.log();Aircraft: ${flightPlan.general?.aircraft}
console.log();Flight Number: ${flightPlan.general?.flight_number}
console.log();`
`bashInstall dependencies
npm install
Testing
The library includes comprehensive unit tests using Mocha and Chai. Tests are located in
src/*/.spec.ts files.`bash
Run all tests
npm testRun tests in watch mode
npm run test:watchDebug tests
npm run test:debug
`CI/CD
This project uses GitHub Actions for continuous integration and deployment. The workflow includes:
$3
- Test Workflow (
.github/workflows/test.yml):
- Runs on every push and pull request
- Tests on Node.js versions 18.x and 20.x
- Installs dependencies, runs tests, and verifies build
- Ensures code quality before merging$3
- Publish Workflow (
.github/workflows/publish.yml):
- Triggers when a version tag is pushed (e.g., v1.0.0, v2.1.3)
- Runs tests and builds the project
- Automatically publishes to npm
- Creates a GitHub release$3
To enable automatic publishing to npm, you need to:
1. Create an NPM access token:
- Go to https://www.npmjs.com/settings/YOUR_USERNAME/tokens
- Click "Generate New Token"
- Select "Automation" token type
- Copy the token (you won't see it again)
2. Add the token to GitHub Secrets:
- Go to your repository on GitHub
- Navigate to Settings → Secrets and variables → Actions
- Click "New repository secret"
- Name:
NPM_TOKEN
- Value: Paste your NPM access token
- Click "Add secret"$3
To publish a new version to npm:
1. Update the version in
package.json (or it will be updated automatically from the tag)2. Create and push a version tag:
`bash
git tag v1.0.0
git push origin v1.0.0
` Or create an annotated tag:
`bash
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0
`3. The workflow will automatically:
- Run all tests
- Build the project
- Extract version from the tag
- Update
package.json version (if needed)
- Publish to npm
- Create a GitHub release$3
Version tags must follow the semantic versioning format:
-
v1.0.0 (major.minor.patch)
- v2.1.3
- v0.1.0The workflow will automatically extract the version number (removing the
v` prefix) and use it for publishing.MIT