bcbp-lib

Zero-dependency TypeScript library for parsing BCBP (Bar Coded Boarding Pass) strings per IATA Resolution 792 v7 (2018).

Decodes the positional fixed-width data embedded in PDF417, Aztec, QR, and DataMatrix barcodes found on airline boarding passes.

Installation

npm install bcbp-lib

Usage

import { parse } from 'bcbp-lib';

const result = parse('M1GREENE/JOHANNA      ECGDGCB TPAYYZAC 1661 365Y025C0103 391>8320 O6001BAC ...');

console.log(result.passengerName);  // "GREENE/JOHANNA"
console.log(result.legs[0].fromAirport);  // "TPA"
console.log(result.legs[0].toAirport);    // "YYZ"
console.log(result.legs[0].flightDate);   // "2026-12-31"

CommonJS

const { parse } = require('bcbp-lib');

Output

The parse() function returns a flat, easy-to-consume object:

{
  "formatCode": "M",
  "numberOfLegs": 1,
  "passengerName": "GREENE/JOHANNA",
  "electronicTicketIndicator": "E",
  "versionNumber": 8,
  "passengerDescription": "0",
  "sourceOfCheckIn": null,
  "sourceOfBoardingPassIssuance": "O",
  "dateOfBoardingPassIssuance": 6001,
  "documentType": "B",
  "boardingPassIssuerAirline": "AC",
  "baggageTagLicensePlate1": null,
  "baggageTagLicensePlate2": null,
  "baggageTagLicensePlate3": null,
  "legs": [
    {
      "pnrCode": "CGDGCB",
      "fromAirport": "TPA",
      "toAirport": "YYZ",
      "operatingCarrier": "AC",
      "flightNumber": "1661",
      "flightDate": "2026-12-31",
      "compartmentCode": "Y",
      "seatNumber": "025C",
      "checkInSequenceNumber": "0103",
      "passengerStatus": "3",
      "airlineNumericCode": "014",
      "documentSerialNumber": "2315129393",
      "selecteeIndicator": "0",
      "internationalDocVerification": null,
      "marketingCarrier": "AC",
      "frequentFlyerAirline": null,
      "frequentFlyerNumber": null,
      "idAdIndicator": null,
      "freeBaggageAllowance": null,
      "fastTrack": "N",
      "airlineIndividualUse": null,
      "airlineUse": "*30601000K09     ADOCAC 814MLV     N"
    }
  ],
  "securityData": null
}

Fields that are absent or blank in the barcode are returned as null.

Legs

Each entry in the legs array contains the flight-specific data for that segment. BCBP supports up to 4 legs per boarding pass.

Flight Date

The BCBP format encodes the flight date as a julian day (1-366). The library automatically resolves this to an ISO date string (YYYY-MM-DD) using the boarding pass issue date for year context when available, falling back to the current year otherwise.

Security Data

When present, the securityData object contains:

{
  "type": "1",
  "data": "GIWVC5EH7JNT684FVNJ91W2QA4DVN5J8K4F0L"
}

Automatic Alignment Correction

Real-world boarding pass barcodes sometimes have incorrect padding in the passenger name field (which should be exactly 20 characters, right-padded with spaces). When the padding is off by even one character, every downstream field shifts and produces garbage data.

bcbp-lib automatically detects and corrects this. Before parsing, it tries multiple name field lengths (18-22 characters) and scores each alignment against known field constraints:

• Airport codes must be alphabetic (A-Z)
• Compartment code must be a letter
• E-ticket indicator should be E or L
• Hex size fields must be valid hexadecimal
• The > version marker should appear at the expected position

The alignment with the highest score wins. If the standard 20-character length already scores best, the input is left unchanged.

// This string is missing 1 padding space in the name field
const bcbp = 'M1VALINASROA/MARIANA EAYUSMB MEXTPAAM 1740 037Y026E0075 162>5322RR...';

const result = parse(bcbp);
console.log(result.passengerName);        // "VALINASROA/MARIANA" (correct)
console.log(result.legs[0].fromAirport);  // "MEX" (correct, not "EXT")

Error Handling

The parser throws BcbpParseError for structurally invalid input:

• Empty or too-short strings
• Wrong format code (must be M)
• Invalid leg count (must be 1-4)
• Invalid hexadecimal in structural size fields

Conditional and optional fields that are truncated or missing are returned as null without throwing.

import { parse, BcbpParseError } from 'bcbp-lib';

try {
  const result = parse(input);
} catch (e) {
  if (e instanceof BcbpParseError) {
    console.error(e.message);   // includes position info
    console.error(e.position);  // character offset in the input
  }
}

API

parse(input: string): BcbpResult

Parses a BCBP string and returns the decoded result. Single function, no configuration.

Types

All types are exported for use in TypeScript:

import type { BcbpResult, BcbpLeg, BcbpSecurityData } from 'bcbp-lib';

Contributing

Setup

git clone https://github.com/your-username/bcbp-lib.git
cd bcbp-lib
npm install

Development

npm run build    # compile ESM + CJS
npm test         # run tests
npm run test:watch  # run tests in watch mode

Project Structure

src/
  index.ts     Public exports
  types.ts     TypeScript interfaces
  parser.ts    Core parse logic
  cursor.ts    Cursor-based string reader
  fields.ts    Field parsing helpers (string, int, hex)
  align.ts     Automatic alignment correction
  errors.ts    BcbpParseError class
tests/
  parser.test.ts   Parser tests
  cursor.test.ts   Cursor unit tests
  fixtures.ts      Test BCBP strings

Guidelines

• Run npm test before submitting a pull request
• Add test cases for any new functionality
• If adding a new field or section, update types.ts and the corresponding parse logic in parser.ts
• When adding real-world BCBP test strings, redact any personally identifiable information
• Keep the library zero-dependency — dev dependencies (vitest, typescript) are fine

Testing with Real Boarding Passes

You can test with real BCBP strings by scanning the barcode on a boarding pass with any barcode reader app. The raw string can be passed directly to parse().

License

MIT