DTO specs, StellarService contract-mock harness, ticket lifecycle diagrams and full API reference

[Majormaxx]

Closes #226
Closes #227
Closes #228
Closes #229

Stacked on #369, which repairs main so the gates can run at all; the first eight commits here are that PR and this diff shrinks to the last three once it merges. If you would rather merge this one first, it carries the repair with it.

#226 DTO specs

confirm-transfer-ticket.dto.spec.ts, confirm-list-for-resale.dto.spec.ts and confirm-purchase-primary.dto.spec.ts, in the style of the existing confirm-issue-ticket.dto.spec.ts. Each runs class-validator with the global pipe's whitelist / forbidNonWhitelisted options and covers: the accepted payload, every optional field at its boundaries (a 39-digit price, a 64-character seat, 3- and 32-character promo codes), each rejected field with several bad inputs (it.each), an unknown property, and several bad fields reported together. 57 cases.

#227 Contract-mock harness for StellarService

• test/mocks/soroban-rpc.mock.ts: an rpc.Server double (getAccount resolves at sequence 1, prepareTransaction returns the built transaction) with canned sendTransaction / getTransaction / simulateTransaction responses, and ticketScVal / eventScVal fixtures that encode the contract's Ticket and Event structs as verify_ticket and get_event return them (snake_case symbol map, u64 ids, i128 prices, address owner, status as a bare symbol or { tag }).
• test/helpers/stellar-harness.ts: createStellarHarness() boots the real StellarService from an in-memory config for testnet, futurenet or mainnet and swaps the double in; decodeInvokeHostFunction() takes an envelope back apart into source, fee, network passphrase, contract id, function name, native args and XDR arg types; signAsWallet() signs like a wallet.
• src/stellar/stellar.service.spec.ts (29 tests): every build*Tx method decodes to the expected contract function, argument values and XDR types (scvAddress, scvU64, scvI128, scvString, scvU32) with the caller as source and no signatures; the returned envelope is the one prepareTransaction produced; the 300-second timebound; the passphrase mapping for all three networks and proof that a futurenet envelope hashes differently under the testnet passphrase; submitSignedTransaction relaying a wallet-signed envelope with the same hash and one signature, decoding the u64 return value, and failing on a rejected submission, an on-chain failure, a missing return value and a 15-poll timeout (fake timers); verifyTicket / getEvent simulating from the platform signer and decoding both status encodings plus the unknown-status fallback; simulation errors; the circuit breaker opening after three RPC failures.

docs/TESTING.md explains the pieces and how to add a case.

#228 Ticket lifecycle diagrams

docs/ARCHITECTURE.md gains a "Ticket lifecycle" section: a participant table, the conventions every flow shares (idempotency, re-checks at confirm, 15-second polling, Postgres writes only after the chain confirms), and mermaid sequence diagrams for issue, purchase (including promo-code pricing and redemption), transfer, resale (list, buy, cancel in one diagram, plus the off-chain price update and expiry sweep), check-in (verify with stale fallback, staff JWT and scanner-device paths), a short revoke section, and a state diagram of Ticket.status transitions. Every step is taken from TicketsService and StellarService, not from the README. All six blocks parse with mermaid 11.17.2; please eyeball them on the rendered file tab.

#229 API reference with examples

docs/API.md now documents all 73 routes: conventions first (versioning, auth, validation pipe behaviour, BigInt-as-string, status codes, Idempotency-Key, the build / confirm pair, the four error shapes), then each route with its purpose, auth requirement, a field table taken from the DTO decorators (rules, bounds, defaults), a copy-pasteable curl, and the JSON the service returns (Prisma rows with their real columns, { unsignedXdr } for build calls, the enriched resale listing with royaltyFee / sellerProceeds, { device, token } for scanner devices, { entry, position } for the waitlist, and so on). Example public keys are valid strkeys; the resale cursor is a real base64url("createdAt|id").

Evidence (Node 22.23.3)

gate	result
npx tsc --noEmit	0 errors
npx eslint "src/**/*.ts"	0 errors (new test files linted too)
npx jest --coverage	74 suites, 668 tests, coverage 75.7 / 66.8 / 78.8 / 75.9 (up from 72.5 / 64.6 / 71.6 / 72.6 after #369)
npm run build, npm run docs:check, npm run audit:check	ok

Noticed, not changed

scripts/generate-api-collection.js does not follow extends, so the generated Bruno bodies for every confirm-* request lack signedXdr and txHash. docs/API.md documents the real bodies; fixing the generator changes eleven .bru files and is better as its own PR.

[drips-wave]

@Majormaxx Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[netlify]

✅ Deploy Preview for stellarticketsbackend ready!

Name	Link
🔨 Latest commit	1e84973
🔍 Latest deploy log	https://app.netlify.com/projects/stellarticketsbackend/deploys/6ab96f8032937d0008255e89
😎 Deploy Preview	https://deploy-preview-370--stellarticketsbackend.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.