# @hamradio/aprs

APRS (Automatic Packet Reporting System) utilities and parsers for TypeScript/JavaScript.

> For AX.25 frame parsing, see [@hamradio/ax25](https://www.npmjs.com/package/@hamradio/ax25).

This package provides lightweight parsing and helpers for APRS frames (APRS-IS style payloads). It exposes a small API for parsing frames, decoding payloads, working with APRS timestamps and addresses, and a few utility conversions.

## Install

Using npm:

```bash
npm install @hamradio/aprs
```

Or with yarn:

```bash
yarn add @hamradio/aprs
```

## Quick examples

Examples below show ESM / TypeScript usage. For CommonJS require() the same symbols are available from the package entrypoint.

### Import

```ts
import {
	Frame,
	Address,
	Timestamp,
	base91ToNumber,
	knotsToKmh,
} from '@hamradio/aprs';
```

### Parse a raw APRS frame and decode payload

```ts
const raw = 'NOCALL-1>APRS,WIDE1-1:@092345z/:*E";qZ=OMRC/A=088132Hello World!';

// Parse into a Frame instance
const frame = Frame.fromString(raw);

// Inspect routing and payload
console.log(frame.source.toString()); // e.g. NOCALL-1
console.log(frame.destination.toString()); // APRS
console.log(frame.path.map(p => p.toString()));

// Decode payload (returns a structured payload object or null)
const payload = frame.decode();
console.log(payload?.type); // e.g. 'position' | 'message' | 'status' | ...

// Or ask for sections (dissection) along with decoded payload
const res = frame.decode(true) as { payload: any | null; structure: any };
console.log(res.payload, res.structure);
```

### Message decoding

```ts
const msg = 'W1AW>APRS::KB1ABC-5 :Hello World';
const f = Frame.fromString(msg);
const decoded = f.decode();
if (decoded && decoded.type === 'message') {
	console.log(decoded.addressee); // KB1ABC-5
	console.log(decoded.text); // Hello World
}
```

### Work with addresses and timestamps

```ts
const a = Address.parse('WA1PLE-4*');
console.log(a.call, a.ssid, a.isRepeated);

const ts = new Timestamp(12, 45, 'HMS', { seconds: 30, zulu: true });
console.log(ts.toDate()); // JavaScript Date representing the timestamp
```

### Utility conversions

```ts
console.log(base91ToNumber('!!!!')); // decode base91 values used in some APRS payloads
console.log(knotsToKmh(10)); // convert speed
```

## API summary

- `Frame` — parse frames with `Frame.fromString()` / `Frame.parse()` and decode payloads with `frame.decode()`.
- `Address` — helpers to parse and format APRS addresses: `Address.parse()` / `Address.fromString()`.
- `Timestamp` — APRS timestamp wrapper with `toDate()` conversion.
- Utility functions: `base91ToNumber`, `knotsToKmh`, `kmhToKnots`, `feetToMeters`, `metersToFeet`, `celsiusToFahrenheit`, `fahrenheitToCelsius`.

## Development

Run tests with:

```bash
npm install
npm test
```

Build the distribution with:

```bash
npm run build
```

## Contributing

See the project repository for contribution guidelines and tests.

---

Project: @hamradio/aprs — APRS parsing utilities for TypeScript