Extract shared API client pieces from services into packages

[TaprootFreak]

Context

DFXswiss/services contains several thin API layers (types + useApi/call wrappers) that are customer/product API contracts, not widget- or staff-UI. Those belong in this monorepo (@dfx.swiss/core + @dfx.swiss/react) so other consumers can reuse them without depending on services.

Staff/compliance, RealUnit tenant, dashboard, and widget shell stay in services.

Goal

Move (or re-export) the shared wire contract into packages, then switch services to the published package APIs and drop the local duplicates.

Scope — extract into packages

1. Virtual / personal IBAN (create) — high priority

Source (services)	src/hooks/virtual-iban.hook.ts, src/dto/virtual-iban.dto.ts
Target	@dfx.swiss/core (URL + types + optional BuyApi method) and @dfx.swiss/react (hook, e.g. useVirtualIban / extend useBuy)
API	POST buy/personalIban
Already in packages	PersonalIbanProvider, isPersonalIban / buy quote fields (BuyPaymentInfo.personalIbanProvider)
Gap	Create endpoint client + VirtualIban / CreateVirtualIban DTOs

Also consider pure domain helpers from services/src/util/personal-iban.ts (normalize provider, request mapping). Keep widget/URL param handling (personal-iban query, web-component) in services.

---

2. Recommendation (customer API) — high priority

Source (services)	src/hooks/recommendation.hook.ts, src/dto/recommendation.dto.ts
Target	core: URLs + types; react: useRecommendation
API	GET/POST recommendation, PUT recommendation/:id/confirm, PUT recommendation/:id/reject
Already in packages	Auth already accepts recommendationCode
Note	Customer-facing only. Staff recommendation graph (support/recommendation-graph/…) stays in services compliance.

---

3. Payment Link pay-flow contract — medium priority

packages already covers Payment Link CRUD (PaymentLinksApi, usePaymentRoutes, PaymentLink, PaymentLinkPayment, PaymentStandardType, …).

Missing from packages, still only in services:

Source (services)	src/dto/payment-link.dto.ts (and related call sites in payment-link contexts)
Target	core definitions (+ optional client methods); re-export from react
Candidates	PaymentStandard, PaymentLinkPayTerminal, PaymentLinkPayRequest, Quote, TransferInfo / TransferMethod, C2BPaymentMethod, RecipientInfo (pay-flow shape), wait/history URL helpers if stable
Related endpoints used only in services today	e.g. paymentLink/standard, paymentLink/payment, paymentLink/payment/wait, paymentLink/history (verify against current API before freezing)

Do not move: POS UI orchestration, MetaMask pay UI, polling timers, merchant session storage — those stay in services.

---

4. Custody / Safe API client — medium priority

Source (services)	src/hooks/safe.hook.ts, src/dto/safe.dto.ts, src/dto/order.dto.ts
Target	core: CustodyApi (or similar) + types; react: useCustody / useSafe
API (customer)	custody, custody/account, balances/history/order, confirm order, …
Already in packages	JWT role Custody
Do not move	Staff admin paths (custody/admin/orders, approve) — those stay under services compliance

---

5. Blockchain helper API — optional / lower priority

Source (services)	src/hooks/blockchain-balance.hook.ts, src/hooks/blockchain-transaction.hook.ts
Target	core client + react hooks
API	POST blockchain/balances, POST blockchain/transaction, POST blockchain/broadcast

Useful for any wallet-integrated consumer; not required if only services uses them long-term.

---

Explicitly out of scope (stay in services)

• Staff / compliance: compliance.hook.ts, MROS, recall, Scorechain, call queues, AML review/reset, KYC admin
• Internal financial dashboard (dashboard/*)
• RealUnit (customer + compliance + support tenant APIs)
• Support staff dashboard (support/issue/list, clerks, statistics, templates) — customer chat is already in packages (useSupportChat / SupportApi)
• Widget shell: app-handling.context, web component, screens, i18n, charts, wallet adapters, PDF builders

---

Suggested delivery order

1. Virtual/personal IBAN create + DTOs
2. Recommendation customer API
3. Payment Link pay-request types (+ any missing stable endpoints)
4. Custody/Safe customer client
5. Blockchain helpers (optional)

Each step: implement in packages → publish (beta then stable per release process) → bump @dfx.swiss/react / @dfx.swiss/core in services → delete local duplicates.

---

Acceptance criteria

• Types and URL constants for each in-scope item live in @dfx.swiss/core (and are re-exported from @dfx.swiss/react where hooks exist today)
• React hooks exist for customer-facing calls where services currently uses local hooks
• services uses the published packages; local dto/hook copies for in-scope items are removed
• No staff/compliance/RealUnit/dashboard code is moved into packages
• packages CONTRIBUTING: no hand-bumped versions in feature PRs (Lerna publish workflow)
• Breaking changes called out for downstream consumers

References

• packages CONSUMERS: e.g. DFXswiss/services (pinned npm deps)
• Local analysis: services has ~188 files importing @dfx.swiss/react, but many extra API paths only via local useApi() wrappers
• Related existing packages surface: buy (PersonalIbanProvider), payment links CRUD, support customer chat, bank receive-IBAN check

[TaprootFreak]

All five steps are implemented and up for review. Each package PR has a matching consumer PR in
services, which stays draft until the package it depends on is published.

Step	packages	services
1 — Virtual / personal IBAN	#199	DFXswiss/app#1239
2 — Recommendation	#200	DFXswiss/app#1240
3 — Payment Link pay-flow	#201	DFXswiss/app#1242
4 — Custody / Safe	#202	DFXswiss/app#1243
5 — Blockchain helpers	#203	DFXswiss/app#1241

All five package PRs are green and conflict-free. They all touch the same barrel files, so whichever
merges second will need a trivial rebase; building all five together locally was clean.

Verifying the endpoints first was the point

The issue asked to check the endpoints against the current API before freezing them. That turned up
differences in every single step — these were in the local copies, and moving them unchanged would
have published them:

• paymentLink/history ignores linkId. A caller passing it gets the account's entire history
  instead of one link's. The parameter is not in the client.
• TransferMethod did not cover TaprootAsset, which Config.payment.manualMethods appends to
  every single transfer-amount list and which is in no blockchain enum.
• The custody order service handles five of the nine order types. EQUITY_MINT, EQUITY_REDEEM,
  SAVING_DEPOSIT and SAVING_WITHDRAWAL have no case and no default — paymentInfo stays null and
  the next line throws a 500. They remain in the enum (the history reports them) but cannot be
  requested.
• An equity-paired swap is priced without a transaction request and answers with id: undefined,
  so CustodyOrderPaymentInfo.id is optional.
• paymentLink/payment/wait returns the whole payment link, not a bare status; a history entry is
  a payment link with payments[], not a pay request, and its payment ids are numbers.
• Fields that were simply missing: acceptsPayments (virtual IBAN), isOwner and
  interest/interestValue (custody), frontendUrl/webhookUrl (payment link), five merchant
  fields (recipient). expirationDate on a recommendation is optional — the API omits it for mail
  invitations.

Two type-level consequences worth naming, both of which the consumer PRs had to act on:

• The custody token on createOrder/confirmOrder is required. It used to be optional, and the
  HTTP client falls back to the session token when none is passed — precisely what that call must not
  do. services now fails before the request instead of after it.
• CreateCustodyOrder is a union over the order type, so a send without a destination, a withdrawal
  without an IBAN, or a request carrying both amounts or neither no longer typechecks. All three were
  reachable from the Safe screen.

Deviations from the issue

• Both personal IBAN endpoints are covered, not only create — the list endpoint is the same
  contract, and freezing half of it leaves consumers writing a wrapper anyway.
• paymentLink/standard does exist, served by its own controller rather than the payment link
  one, which is easy to miss.
• No React hook for the pay flow. The loop, timers and merchant session handling are consumer
  state; what is worth sharing are the wire types and the URL and query building, and those are here.
• Only the provider-generic selector helpers moved out of util/personal-iban.ts. The error copy,
  the currency/payment-method applicability rule and the check against a specific bank and
  account-holder name stayed put: they encode product state that can change without a contract
  change, and a published SDK asserting them would start lying the day it does.
• Custody account management and access grants take a persisted id. The reading endpoints accept
  the legacy marker, PUT :id and the grant list/update/revoke do not — with grantAccess as the one
  exception that does. toCustodyAccountId(account) resolves the legacy account's null id.

Acceptance criteria

Met: types and URL constants in @dfx.swiss/core, re-exported from @dfx.swiss/react; React hooks
for the customer-facing calls; no staff, compliance, RealUnit or dashboard code moved; no hand-bumped
versions, changelogs or lockfile pins; breaking changes called out (PaymentLink gained a required
frontendUrl — reading code is unaffected, code building a PaymentLink literal is not).

Open until publish: "services uses the published packages". The consumer PRs are written and verified
locally against a build of these branches — tsc clean, lint clean, full suite passing with no new
failures — but their pins cannot be raised until these merge and publish.