# meridian-euid (TypeScript)

Non-normative TypeScript reference implementation of the [Meridian EUID specification](../../SPEC.md).

## Requirements

- Node.js 18+
- TypeScript 5+

## Installation

```bash
npm install
npm run build
```

## API Usage

### Functions

```typescript
import { validate, isValid, computeCheckCharacter, encode, parse } from 'meridian-euid';

// validate() - returns input on success, throws on failure
const euid = validate('TX-1C', { environment: 'production' });

// isValid() - returns true/false
if (isValid('TX-1C', { environment: 'production' })) {
  console.log('Valid!');
}

// encode() - encode integer as EUID
const prod = encode(12345, 'DNA');                       // 'DNA-C1SJ'
const sand = encode(123, 'TAP', { sandbox: 'X' });      // 'X:TAP-3VX'

// parse() - parse EUID into components
const result = parse('DNA-C1SJ');
// { sandbox: null, category: 'DNA', body: 'C1S', checksum: 'J', integer: 12345 }

// computeCheckCharacter() - compute check character for payload
const check = computeCheckCharacter('TX1'); // Returns 'C'

// Sandbox validation with prefix restriction
validate('X:TAP-3VX', {
  environment: 'sandbox',
  allowedSandboxPrefixes: new Set(['X']),
});
```

### Function Signatures

```typescript
function validate(
  euid: string,
  options: {
    environment: 'production' | 'sandbox';
    allowedSandboxPrefixes?: ReadonlySet<string>;
  }
): string;

function isValid(
  euid: string,
  options: {
    environment: 'production' | 'sandbox';
    allowedSandboxPrefixes?: ReadonlySet<string>;
  }
): boolean;

function encode(
  integer: number,
  category: string,
  options?: { sandbox?: string }
): string;

function parse(euid: string): {
  sandbox: string | null;
  category: string;
  body: string;
  checksum: string;
  integer: number;
};

function computeCheckCharacter(payload: string): string;
```

### Errors

```typescript
import {
  EuidError,
  EuidFormatError,
  EuidChecksumError,
  EuidSandboxPrefixError,
} from 'meridian-euid';
```

| Error | Thrown when |
|-------|-------------|
| `EuidFormatError` | Regex or canonical form failure |
| `EuidChecksumError` | Checksum mismatch or forbidden `*` |
| `EuidSandboxPrefixError` | Sandbox prefix not in allowed set |

All errors extend `EuidError`.

## Running Tests

```bash
# Build and run tests
npm run build
npm test
```

Tests use shared test vectors from [`test-vectors/v2.json`](../../test-vectors/v2.json).

## Project Structure

```
typescript/
├── src/
│   ├── index.ts       # Public exports
│   ├── euid.ts        # Core validation logic
│   ├── mod32.ts       # Checksum algorithm (SPEC v2)
│   └── errors.ts      # Error classes
├── dist/              # Compiled JavaScript (generated)
├── test/
│   └── vectors.test.js
├── package.json
└── tsconfig.json
```

## Related Documentation

- [SPEC.md](../../SPEC.md) — Normative specification
- [Test Vectors](../../test-vectors/README.md) — Shared test cases
- [Python Implementation](../python/README.md) — Python version with CLI
