marketplaces/docs/PACKAGE-EXTRACTION.md

# @marketplaces/auth & @marketplaces/payment — build, version, publish, consume

See [ADR-0001](context/adrs/ADR-0001-extract-auth-and-payment-into-shared-marketplaces-packages.md) for why. This doc is the how — build, release, and infrastructure. For *consuming* the packages (install, providers, exported API), see [PACKAGES-USAGE.md](PACKAGES-USAGE.md).

## Current state

Live end to end. `marketplaces` has no local copy of either package — it installs `@marketplaces/auth@0.1.0` from a private Verdaccio registry on the dev server. `packages/` no longer exists in this repo.

## 1. Source repo

[sources.vitanova.network/sdarbinyan/vitanovaPackages](https://sources.vitanova.network/sdarbinyan/vitanovaPackages.git) — single monorepo (npm workspaces), `packages/auth` + `packages/payment`, `main` branch. This is where the package source lives and where CI publishes from.

## 2. Registry

Verdaccio, running in Docker on the dev server (`213.21.246.138`, container `verdaccio`, config/storage at `/srv/marketplaces/verdaccio/`). **Not publicly reachable** — the server firewall only allows 80/443/SSH, and opening 4873 or loosening the registry's `$authenticated` access policy are both security-relevant changes that need an explicit decision, not something done silently. Reach it today via SSH tunnel:

```bash
ssh -L 4873:127.0.0.1:4873 seto@213.21.246.138
```

Follow-up decision needed before CI can publish/consume without a human at the keyboard: either (a) reverse-proxy `/verdaccio/` or a subdomain through the existing nginx on 443 with TLS, or (b) open 4873 directly (not recommended — plain HTTP with credentials). Neither is done yet.

`@marketplaces/*` packages require an authenticated user to install (`access: $authenticated` in Verdaccio config) — deliberately not `$all`, since loosening that is itself a security-relevant config change. A registry user `marketplaces-ci` exists; get a token via `npm login --registry=http://127.0.0.1:4873/` (through the tunnel) and set it locally as a user-level `~/.npmrc` `_authToken` line, or export `NPM_TOKEN` and append it to `.npmrc` at CI runtime — never commit a token into this repo's `.npmrc`.

`marketplaces/.npmrc` maps the scope: `@marketplaces:registry=http://127.0.0.1:4873/` — update this once the registry has a real public/internal address.

## 3. Versioning

[Changesets](https://github.com/changesets/changesets) — built for "many packages, one repo, independent versions." A PR that changes `packages/auth` adds a changeset file (`npx changeset` from the vitanovaPackages repo root, picks package + bump type + writes a short description) alongside the code change.

## 4. Publishing (CI)

Two workflows in the vitanovaPackages repo:

- `ci.yml` — on PRs and non-main pushes: install, build, test, and reject the PR if it has no changeset.
- `release.yml` — on push to `main`: install, build, test, then `changesets/action` opens/updates a version-bump PR; merging that PR publishes.

`release.yml` needs repo secrets `NPM_REGISTRY_URL` and `NPM_TOKEN`. **Neither is set, because no CI runner can currently reach the registry** (§2). The workflow fails loudly at the auth step rather than silently skipping the publish — that's deliberate, so a broken release is visible instead of looking green.

Until it's resolved, publish manually through the tunnel:

```bash
npm login --registry=http://127.0.0.1:4873/ --scope=@marketplaces
npm run build
cd packages/auth && npm publish --registry http://127.0.0.1:4873/
```

## 5. Consuming from `marketplaces` (and other projects)

```bash
npm install @marketplaces/auth
```

```ts
import { AuthService, AdminAuthService, adminAuthGuard, ... } from '@marketplaces/auth';
```

Pinned to an exact version (`"0.1.0"`, no `^`/`~`) per ADR-0001's consequence about registry-outage blast radius — bump deliberately, not automatically.

[renovate.json](../renovate.json) at repo root opens a grouped PR whenever either package publishes a new version — review and merge it manually (`automerge: false`).

## 6. Migration cutover

**Auth: done.** `@marketplaces/auth@0.1.0` holds the real implementation — two independent modules, `telegram/` (live Telegram QR/session auth, customer + admin) and `ed25519/` (future challenge/response admin auth, backend not shipped). Environment coupling was replaced with `AUTH_API_URL`/`TELEGRAM_BOT_USERNAME` injection tokens, provided from `app.config.ts`; `environment.production` became Angular's `isDevMode()`. `AdminPermissionsService` and `requireAdminPermission` stayed in `marketplaces` (`core/admin-auth/`) since they read this app's mock Users domain, not a portable auth concern. All ~30 call sites import `@marketplaces/auth`. `npm run build`, `npm run arch:check:boundaries`, and `npm test` (103/103) all pass against the registry-installed package.

**Payment: not started.** `core/finance`/`core/pricing` still live in `marketplaces`, same process as above once prioritized. `@marketplaces/payment@0.1.0` is published (scaffold only) but not yet a `marketplaces` dependency.