marketplaces/docs/PACKAGE-EXTRACTION.md

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

See ADR-0001 for why. This doc is the how.

Current state

packages/ here is now just a reference copy (package.json/tsconfig.json, no CI) — the real source, CI, and versioning live in the pushed vitanovaPackages repo (§1). No app code has moved yet — src/app/core/auth, src/app/core/admin-auth, src/app/core/finance, src/app/core/pricing are still the live implementation in marketplaces.

1. Target repo

Pushed: sources.vitanova.network/sdarbinyan/vitanovaPackages — single monorepo (npm workspaces) hosting both packages/auth and packages/payment, main branch, initial scaffold commit 5567154. The packages/* scaffold here in marketplaces stays as the pre-push staging copy; the pushed repo is now the source of truth for the package source itself.

2. Versioning

Both packages live in one monorepo (vitanovaPackages, npm workspaces), so versioning uses Changesets, not per-package semantic-release — Changesets is built for exactly this "many packages, one repo, independent versions" shape. A PR that changes packages/auth adds a changeset file (npx changeset from repo root, picks package + bump type + writes a short description) alongside the code change.

3. Publishing (CI)

vitanovaPackages/.github/workflows/release.yml: on push to main, installs, builds, tests, then changesets/action:

• if unreleased changesets exist, opens/updates a "Version Packages" PR that bumps package.json versions and writes changelogs,
• once that PR is merged, the next push to main publishes the bumped package(s) to the registry.

Requires two repo secrets: NPM_TOKEN (publish token) and GITHUB_TOKEN (auto-provided on GitHub Actions; use the Gitea/Forgejo equivalent if this host isn't GitHub-Actions-native — check with whoever administers sources.vitanova.network).

Registry choice — pick one before first publish:

• npm private scope (@marketplaces org on npmjs.com) — simplest, works with the workflow as-is.
• GitHub Packages — swap registry-url in the workflow to https://npm.pkg.github.com.
• Self-hosted (Verdaccio) on the dev server — point registry-url at the server's registry endpoint; requires the registry to be stood up on 213.21.246.138 first (not done yet).

4. Consuming from marketplaces (and other projects)

Once published:

npm install @marketplaces/auth @marketplaces/payment

import { ... } from '@marketplaces/auth';

Pin exact versions (no ^/~ ranges) per ADR-0001's consequence about registry-outage blast radius — bump deliberately, not automatically, on this side.

renovate.json at repo root opens a grouped PR whenever either package publishes a new version — review and merge it manually (automerge: false), it does not land unattended.

5. Migration cutover

Auth: done. @marketplaces/auth now 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 now import @marketplaces/auth; the old src/app/core/auth, src/app/core/admin-auth/admin-auth.service.ts (+ interceptor, ed25519 files), src/app/services/auth.service.ts, src/app/services/telegram-session-api.service.ts, and src/app/models/auth.model.ts/admin-auth.model.ts are deleted. npm run build, npm run arch:check:boundaries, and npm test (103/103) all pass. Wired as a file:packages/auth dependency until the registry (§3) is live — swap to a real semver range once published.

Payment: not started. core/finance/core/pricing still live in marketplaces, same process as above once prioritized.