feat: Align Basic/Build plans and add testnet faucet API

[Eengineer1]

Summary

• add Basic/Build plan capability mapping and keep the legacy test plan only as a fallback
• add authenticated POST /account/faucet access for Studio users with cap, balance, and request-more response details
• update subscription activation/migration docs and env examples for Basic/Build plan IDs
• add focused unit coverage for plan capabilities

Verification

• npm run build:app
• npm run test:unit -- tests/unit/admin/plan-capabilities.test.ts --runInBand

Notes

• No Stripe migration or price-shift scripts were run.
• Runtime env should set STRIPE_BASIC_PLAN_ID and STRIPE_BUILD_PLAN_ID; STRIPE_TEST_PLAN_ID remains a temporary fallback only.

[Copilot]

Pull request overview

This PR aligns subscription plan handling around new Basic/Build Stripe product IDs (keeping the legacy Test/Explorer ID as a temporary fallback), and introduces an authenticated POST /account/faucet endpoint for Studio users to request testnet funds up to a configured cap. It also updates operational docs/scripts and adds unit coverage for plan capability mapping.

Changes:

• Introduce centralized plan capability mapping (Basic vs Build) and apply it to default plan assignment + Logto role assignment.
• Add authenticated POST /account/faucet with cap/balance/request-more response details and reuse the same cap for automatic top-ups.
• Update Stripe migration docs/scripts/env examples for Basic/Build plan IDs and the new faucet cap configuration; add unit tests.

Reviewed changes

Copilot reviewed 17 out of 19 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
tests/unit/admin/plan-capabilities.test.ts	Adds unit tests for Basic plan ID fallback + capability checks.
src/types/environment.d.ts	Updates env typings for new faucet + Basic plan configuration variables.
src/types/constants.ts	Adds numeric env parsing and introduces faucet cap constants.
src/services/track/admin/account-submitter.ts	Assigns Basic as the default plan (via getBasicPlanId) when creating Stripe customers.
src/services/admin/plan-capabilities.ts	New plan capability mapping helpers (Basic vs Build).
src/middleware/auth/routes/api/account-auth.ts	Registers auth scope for POST /account/faucet.
src/middleware/auth/logto-helper.ts	Uses plan capabilities to decide which Logto roles to assign based on Stripe product.
src/helpers/faucet.ts	Allows callers to override faucet amount per request.
src/controllers/api/account.ts	Adds POST /account/faucet, updates auto-top-up logic to use upper cap, and loosens Logto role assignment success handling.
src/app.ts	Wires the new /account/faucet route and validator.
scripts/README.md	Updates migration docs to reference Basic plan terminology/IDs.
scripts/README-SUBSCRIPTION-MIGRATION.md	Updates references from Explorer to Basic plan.
scripts/README-SUBSCRIPTION-ACTIVATION.md	Updates semantics to migrate active/trialing without ending trials; refreshes Basic references.
scripts/MIGRATION-EXPLORER-PLAN.md	Renames guide content to Basic plan but retains filename.
scripts/find-subscriptions-to-activate.sql	Expands query to include active subscriptions for migration.
scripts/activate-subscriptions.sh	Updates migration behavior for active/trialing subscriptions (no trial_end=now, no prorations).
README.md	Documents new faucet cap config and new POST /account/faucet; adds Basic plan ID env var guidance.
package-lock.json	Bumps package version and updates lockfile metadata.
example.env	Adds Basic plan env var and new faucet cap variable; updates defaults.

Comments suppressed due to low confidence (1)

src/controllers/api/account.ts:837

• cheqToNcheq/ncheqToCheq (and the Number(...bigint) conversions passed into FaucetHelper.delegateTokens) can lose precision or overflow once amounts exceed Number.MAX_SAFE_INTEGER (e.g., if TESTNET_FAUCET_UPPER_CAP_CHEQ is misconfigured very high). To keep this exact, consider keeping amounts as bigint/decimal strings end-to-end and only formatting for display, rather than converting bigints to number.

function cheqToNcheq(amountCheq: number): bigint {
	return BigInt(Math.floor(amountCheq * 10 ** DEFAULT_DENOM_EXPONENT));
}

function ncheqToCheq(amountNcheq: bigint): number {
	return Number(amountNcheq) / 10 ** DEFAULT_DENOM_EXPONENT;
}

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Eengineer1]

Addressed the Copilot review threads in 75392d1:

• Treat STRIPE_TEST_PLAN_ID as a Basic alias during the migration window while keeping STRIPE_BASIC_PLAN_ID preferred for default assignment.
• Added unit coverage for the legacy Test/Explorer product retaining Testnet/Faucet capability only.
• Reworked account top-up math to use the ncheq balance instead of balances[0], and added a safe integer guard for faucet amounts.
• Added missing OpenAPI responses for 404, 502, and 503, and regenerated src/static/swagger-api.json.
• Updated migration docs to preserve trialing subscriptions' existing trial end dates.
• Added a defensive default-plan env guard and fixed the Logto comment typo.

Verification:

• npm run build:app
• npm run test:unit -- tests/unit/admin/plan-capabilities.test.ts --runInBand
• npm run build:swagger-api

[cheqd-bot]

🎉 This PR is included in version 3.17.0-develop.2 🎉

The release is available on:

• npm package (@beta dist-tag)
• GitHub release

Your semantic-release bot 📦🚀