vitanovaPackages/README.md

# vitanovaPackages

Shared client packages consumed by `marketplaces` and other projects.

- `packages/auth` — `@marketplaces/auth`. Real implementation. Two independent mechanisms: `telegram/` (live QR/session auth, customer + admin) and `ed25519/` (challenge/response admin auth, backend not shipped yet).
- `packages/payment` — `@marketplaces/payment`. Scaffold only, no implementation yet.

Consumer documentation lives in the `marketplaces` repo: `docs/PACKAGES-USAGE.md`. Rationale: `docs/context/adrs/ADR-0001-extract-auth-and-payment-into-shared-marketplaces-packages.md`.

## Installing (no registry, no token)

Each package is published to a **release branch** where the repo root *is* the package, so npm can install it straight over git:

```json
{
  "dependencies": {
    "@marketplaces/auth": "git+https://sources.vitanova.network/sdarbinyan/vitanovaPackages.git#release/auth",
    "@marketplaces/payment": "git+https://sources.vitanova.network/sdarbinyan/vitanovaPackages.git#release/payment"
  }
}
```

No npm registry, no auth token, no SSH tunnel, no CI secret. Anonymous git read is all that's required — a fresh clone plus `npm install` works on any machine and any CI runner.

`release/auth` and `release/payment` are **generated**. Never commit to them by hand; they are force-pushed on every release.

## Layout

npm workspaces monorepo. Each package builds standalone with `tsc` to `dist/`.

```bash
npm ci
npm run build     # all workspaces
npm test          # all workspaces
```

Angular and rxjs are `peerDependencies`, so the consuming app supplies exactly one copy at runtime.

## Making a change

1. Edit under `packages/<name>/src`, export from `index.ts`.
2. `npx changeset` — pick the package and bump type, write one line. CI rejects PRs without one.
3. Open a PR against `main`. `ci.yml` builds, tests, and verifies the changeset exists.
4. On merge, `release.yml` rebuilds and force-pushes the release branches, and opens a "Version Packages" PR if there are unreleased changesets. Merging that PR bumps versions and triggers another release.
5. In the consuming project, run `npm update @marketplaces/auth` (git deps track the branch tip, so pin to a tag or commit SHA instead of the branch if you need reproducible installs).

### Pinning

Branch refs move. For reproducible builds, pin to a commit:

```
git+https://sources.vitanova.network/sdarbinyan/vitanovaPackages.git#<commit-sha>
```

`marketplaces` currently tracks `#release/auth` (branch tip) — deliberate while the package churns, worth pinning once it stabilises.

## Workflow syntax

`ci.yml` / `release.yml` are GitHub Actions. Gitea/Forgejo Actions are compatible. Other CI needs translating — the steps are just: install, build, test, force-push a branch.

## A private npm registry also exists

A Verdaccio instance runs on the dev server (`213.21.246.138:4873`, Docker container `verdaccio`, storage `/srv/marketplaces/verdaccio/`) and holds `@marketplaces/auth@0.1.0` and `@marketplaces/payment@0.1.0`. It is **not** the path anything uses today — it is only reachable from the server itself or through an SSH tunnel, which is exactly why the git-branch approach above exists. Keep it or delete it; nothing depends on it.