Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 31 additions & 8 deletions docs/API_PRODUCT_SUBSCRIPTION_PLAN.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# API Product Subscription — making API Products enforceable

Written 2026-09-02, revised 2026-09-02 after checking every code reference against the repo.
Track progress here by marking items done in place. **Status: Phases 0 to 3 coded and green on 2026-09-02 (`ApiProductSubscriptionTest` 9 scenarios, `RateLimitsTest` 12, `CacheKeyFormatTest` 5). Not yet committed. Phase 4 is other repos.**
Track progress here by marking items done in place. **Status: Phases 0 to 3 coded and green on 2026-09-02 (`ApiProductSubscriptionTest` 9 scenarios, `RateLimitsTest` 12, `CacheKeyFormatTest` 5), committed as "Product Subscriptions". Phase 4 (other repos): OBP-Stripe, Portal and API Manager done on 2026-11-17, not yet tested against a real OBP-API and Stripe; Portal usage panel waits for owner-gated usage endpoints; OBP-Billing not started.**
Background: `../../commands/NMB_legal_2026/FROM_CLAUDE_plans_evolution_OBP_Stripe_OBP_Billing.md`
(relative to this repo; the `commands` directory sits next to `OBP-API-Simon` in `workspace_2024`).

Expand Down Expand Up @@ -245,7 +245,7 @@ Four actors. Ownership means `Consumer.createdByUserId == caller.userId`, exactl
|---|---|---|
| **developer** | owns the consumer; no role | subscribe own consumer; read own subscriptions and their attributes; set status `cancelled` on own subscription. Nothing else. |
| **bank admin** | `…AtOneBank` roles at the product's bank | everything at that bank: subscribe any consumer, read all, any status transition, delete, write attributes. Typical use: approve `requested` → `active`, suspend, reinstate. |
| **billing adapter** | service account with `…AtOneBank` roles at every bank it serves (one Stripe or Invoice Ninja instance may serve several) | status transitions and attribute writes at those banks. In practice only `active`, `past_due`, `cancelled`. |
| **billing adapter** | a Platform App acting as itself (client credentials), with `…AtOneBank` Scopes at every bank it serves (one Stripe or Invoice Ninja instance may serve several) | status transitions and attribute writes at those banks. In practice only `active`, `past_due`, `cancelled`. |
| **support / auditor** | `CanGetApiProductSubscriptionAtOneBank` | read only. |

Roles:
Expand Down Expand Up @@ -365,14 +365,37 @@ Requires Phase 1.

## Phase 4 — Adapters (other repos, listed for completeness)

- [ ] OBP-Stripe: read products with `BILLING_SYSTEM=stripe` from `GET /obp/v6.0.0/api-products`,
sync to Stripe Products/Prices (lookup_key = `bank_id:api_product_code`), create the OBP
subscription before checkout, put `api_product_subscription_id` in checkout and subscription
metadata, store `STRIPE_SUBSCRIPTION_ID` as a subscription attribute, and on webhooks PUT status
only. Delete the `CanCreateBank` and user-attribute provisioning code.
- [x] OBP-Stripe (2026-11-17, rewritten; see its README): a Platform App, no DirectLogin. It
reads products with `BILLING_SYSTEM=stripe` (`GET /obp/v6.0.0/api-products`, then each product for
its attributes) and keeps a monthly Stripe Price per product under lookup_key
`bank_id:api_product_code` (a changed amount creates a new Price and archives the old one). The
Portal creates the subscription; for a `stripe` product it stays `requested` and the Portal sends
the developer to OBP-Stripe `/checkout?api_product_subscription_id=ID`, which checks ownership
through `GET /my/api-product-subscriptions/ID` and starts Stripe Checkout with the subscription's
ids in the Checkout and Stripe subscription metadata. Webhooks and a 5-minute sync apply the Stripe
subscription's state by PUT status only: `active`/`trialing` → `active` (from `requested` or
`past_due`), `past_due` → `past_due`, `unpaid` → `suspended`, `canceled` → `cancelled`. It never
reinstates `suspended` (an admin may have suspended it). A subscription cancelled or deleted in OBP
is cancelled in Stripe. It stores `STRIPE_SUBSCRIPTION_ID` as a subscription attribute and
`STRIPE_CUSTOMER_ID` as the payer's non-personal user attribute. Scopes it declares:
`CanGetNonPersonalUserAttributes`, `CanCreateNonPersonalUserAttribute` (system);
`CanGetApiProductSubscriptionAtOneBank`, `CanUpdateApiProductSubscriptionStatusAtOneBank`,
`CanCreateApiProductSubscriptionAttributeAtOneBank` at each bank with a Stripe product; optional
`CanGetApiProduct` at each bank with products. The `CanCreateBank` and user-attribute provisioning
code is gone. Dockerfile and `k8s/` manifests added.
- [ ] OBP-Billing: invoice per active subscription with `BILLING_SYSTEM=invoice_ninja`
(monthly amount + overage from aggregate metrics); add the overdue loop that PUTs `past_due` / `active`.
- [ ] Portal: catalogue from `GET /api-products`, product detail page, usage panel from
- [x] Portal and API Manager (2026-11-17): the Portal subscribes, and for a `stripe` product sends
the developer to `PUBLIC_SUBSCRIPTIONS_URL/checkout?api_product_subscription_id=ID` (OBP-Stripe);
`requested` Stripe subscriptions get Pay, `active`/`past_due` get Manage billing. The old
account-application checkout route and `STRIPE_CHECKOUT_URL` are gone. The API Manager product page
lists subscriptions with Approve / Suspend / Reinstate / Cancel / Delete and an Enrol form for
`SELF_SUBSCRIBE=false` products; the consumer page lists a consumer's subscriptions.
- [ ] Portal usage panel: blocked. `call-counters` and `active-rate-limits` exist only as v6.0.0
`/management/consumers/CONSUMER_ID/...` with `CanGetRateLimits`, which a fintech must not need.
Needs owner-gated `GET /my/consumers/CONSUMER_ID/call-counters` and `.../active-rate-limits`
(v7.0.0, no Role, 404 for a consumer the caller does not own).
- [x] Portal (the original item; catalogue and product pages exist, the usage panel is tracked above): catalogue from `GET /api-products`, product detail page, usage panel from
`call-counters` and `active-rate-limits`. The fintech never needs a role; the product's
attributes pick the button:

Expand Down
29 changes: 26 additions & 3 deletions ideas/ASSET_REGISTRY.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,24 @@
# Draft v4: Asset Registry

**Status**: partly implemented. The registry exists, is seeded, and decides which currency codes are accepted and their decimal places, giving the same answers as the built-in list it replaced. The only changes callers can see so far are two attribute types (`DECIMAL`, `BOOLEAN`) and an amount too large to store being refused instead of wrapped. The progress section below lists what is built and what is next; section 12 records how the questions it raised were settled.
**Status (2026-11-18)**: partly implemented. Steps 1 to 9 are built and committed; the last commit was on 2026-10-29. Nothing has been started since, and no decision is waiting: every open question was settled on 2026-10-20 (section 12).

What callers can do now:
- read the registry with no login (`GET /assets`, `GET /assets/ASSET_CODE` and the reverse chain lookup);
- register an asset with Create Asset: a bank registers an asset it issues, such as a `STABLECOIN`, and `SYS` registers a `CRYPTO` asset. The new code is accepted in `currency` fields at once;
- send currency codes in any letter case;
- expect an amount with more decimal places than its currency allows to be refused with 400, not cut off.

What a bank still cannot do, in the order proposed:
1. **Use a new asset on every node at once.** Each node keeps the registry in memory, and Create Asset clears only its own copy (`AssetLookup.invalidate`). On a deployment with several nodes, the others refuse the new code until they restart.
2. **Freeze or suspend an asset.** The status endpoint and status history (§6, §8) are not built, so an issuer cannot stop its coin being used.
3. **Hold token amounts exactly.** Amounts are still stored as `Long` minor units (§5). At 18 decimal places a `Long` holds only about 9.2 units, so a token with many decimal places cannot be held in useful amounts.
4. **Update or delete an asset** (§8).
5. **Rely on correct precision for every code.** Some ISO codes and every crypto asset still have the built-in decimal places (§7 Part B). Run the step 2 report against a copy of production data first.
6. **Use `ADA` and `ETH` alone.** `lovelace` and `wei` are still separate codes (§7 Part C).

Minting and burning on a chain is not part of this work. It belongs to the bank node (the TEuro repository).

The progress section below gives the detail of each step.

**Changes in v4 (2026-10-05)**: adds the progress section. `chain_scheme` names the network as well as the chain (§2); questions 10 and 11 are new. Records what the implementation settled or exposed: the seed has no switch (question 6), Mapper cannot declare the partial unique indexes (§2), the 4–10 character rule for non-seeded codes is not enforced yet (§3), the test setup empties the registry between tests (§11), and the unused `MappedCurrency` table (§11). Code references are brought up to date.

Expand Down Expand Up @@ -61,8 +79,13 @@ The work is ordered so that each step changes nothing a caller can see until the
| 6 | `isValidCurrencyISOCode` and `currencyDecimalPlaces` read from the registry (§4) | Done (`b4ac8c374`) |
| 7 | Case-insensitive codes (§4): codes upper-cased in requests by `ResourceDocMiddleware`, compared ignoring case | Done (`8763728f6`) |
| 8 | Rejecting excess decimals (§4): 400 (OBP-10068) from `ResourceDocMiddleware`, crypto assets exempt until §7 | Done (`91289dbf0`) |
| 9 | Create Asset, `POST /banks/BANK_ID/assets` (§8) | Done, not committed |
| Later | the other write endpoints (§8), amount storage (§5, §7 Part A), precision corrections (§7 Part B), folding `lovelace` and `wei` (§7 Part C, §10) | Each changes behaviour; the open questions they waited on are settled (§12) |
| 9 | Create Asset, `POST /banks/BANK_ID/assets` (§8) | Done (`fc8587455`; rules checked before conflicts in `c3fca5107`) |
| 10 | Registry cache that expires on every node after a write (step 6) | Not started; needed now that Create Asset writes |
| 11 | Update Asset Status and Get Asset Status History (§6, §8) | Not started |
| 12 | Amount storage as exact decimals (§5, §7 Part A) | Not started |
| 13 | Update Asset and Delete Asset (§8) | Not started |
| 14 | Precision corrections (§7 Part B) | Not started; run the step 2 report on real data first |
| 15 | Folding `lovelace` and `wei` into `ADA` and `ETH` (§7 Part C, §10) | Not started |

**Step 1.** `CurrencyHandlingTest` is a pure unit test (no server, no database). It asserts correct behaviour only. The three known defects are written as the correct expectation inside `pendingUntilFixed`, so they report as pending now and fail, demanding the wrapper's removal, once fixed:
- codes are not accepted in every letter case;
Expand Down
Loading
Loading