@12-apps/payments-frontend 3.14.0 → 3.15.0

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.14.0",
+  "version": "3.15.0",
   "type": "module",
   "description": "Browser half of the vendor-agnostic payments platform: plug-and-play MUI components for the per-provider settings page (credential form from each provider's schema, masked hints, verify/enable) and the checkout page (PIX QR + polling, card tokenization, hosted-checkout redirect), plus the headless hooks and fetch clients they build on. Talks only to the host's payments HTTP surface — never to a provider directly. Microfrontend-ready: no app coupling, host injects theme and auth.",
   "exports": {
     ".": "./src/index.ts",
-    "./locales": "./src/locales.ts"
+    "./locales": "./src/locales.ts",
+    "./manifest": "./src/manifest/index.ts",
+    "./manifest/web": "./src/manifest/web.ts",
+    "./package.json": "./package.json"
   },
   "scripts": {
     "clean": "rm -rf node_modules coverage storybook-static",
@@ -18,7 +21,7 @@
     "storybook:build": "storybook build"
   },
   "dependencies": {
-    "@12-apps/payments-backend": "^4.19.0",
+    "@12-apps/payments-backend": "^4.19.1",
     "react-qr-code": "^2.2.0"
   },
   "peerDependencies": {

package/src/flows/create-payments-settings.tsx

@@ -0,0 +1,67 @@
+/**
+ * `createWebPaymentsSettings` — the MERCHANT half of this package, mounted
+ * rather than composed.
+ *
+ * `createPaymentFlows` already does this for the buyer: one call, one bound
+ * transport, and the host mounts what comes back. The owner's settings page
+ * had no equivalent, so every host imported `PaymentProviderSettings` and
+ * threaded the same `PaymentsSettingsClient` into it at the call site — the
+ * one object that is genuinely per-tenant and genuinely built once. This
+ * binds it, and nothing else.
+ *
+ * ## WHAT STAYS A PROP, and why
+ *
+ * **`copy`.** Every sentence this surface renders follows the READER's
+ * locale, which a host resolves per render. Binding the pack at factory time
+ * would pin the screen to whichever language was in effect when the host
+ * built it — a language switch that changes the chrome and leaves the
+ * settings page behind.
+ *
+ * **`prepareConnect`, `selectedProvider` / `onProviderChange`,
+ * `initialProvider`, `onChanged`.** The OAuth CSRF state is minted against
+ * the host's admin session; which provider is open may live in the host's
+ * URL. Both are the host's, per render, and a factory that froze them would
+ * make the page uncontrollable.
+ */
+
+import type { ComponentType, JSX } from "react";
+
+import {
+  PaymentProviderSettings,
+  type PaymentProviderSettingsProps,
+} from "../components/PaymentProviderSettings";
+import type { PaymentsSettingsClient } from "../client";
+
+/** What a host binds ONCE: the settings port. */
+export interface PaymentsSettingsWebConfig {
+  /**
+   * The host's settings transport — its origin, its tenancy, its auth.
+   * `createPaymentsSettingsClient` builds one; a host with its own
+   * authenticated fetch may implement the interface directly.
+   */
+  client: PaymentsSettingsClient;
+}
+
+/** The settings page's remaining props once the port is bound. */
+export type BoundPaymentsSettingsProps = Omit<PaymentProviderSettingsProps, "client">;
+
+/**
+ * The bound surface. `page` is a component TYPE, so a host must hold the
+ * object across renders — the wiring consumer's binder does that once per
+ * adoption.
+ */
+export interface PaymentsSettingsSurface {
+  /** The whole provider-settings page: list, connection, credentials, priority. */
+  page: ComponentType<BoundPaymentsSettingsProps>;
+}
+
+/** Build the owner's payment-settings surface for a host. */
+export function createWebPaymentsSettings(
+  config: PaymentsSettingsWebConfig,
+): PaymentsSettingsSurface {
+  const { client } = config;
+  const Page = (props: BoundPaymentsSettingsProps): JSX.Element => (
+    <PaymentProviderSettings {...props} client={client} />
+  );
+  return { page: Page };
+}

package/src/index.ts

@@ -301,6 +301,8 @@ export {
   PaymentProviderSettings,
   type PaymentProviderSettingsProps,
 } from './components/PaymentProviderSettings';
+export { createWebPaymentsSettings } from './flows/create-payments-settings';
+export type { BoundPaymentsSettingsProps, PaymentsSettingsSurface, PaymentsSettingsWebConfig } from './flows/create-payments-settings';
 
 // ---------------------------------------------------------------------------
 // The PLATFORM operations screens (FUT-479 / FUT-483, packaged by FUT-573) —

package/src/manifest/index.ts

@@ -0,0 +1,74 @@
+/**
+ * `@12-apps/payments-frontend/manifest` — the SHARED wiring manifests.
+ *
+ * UNTYPED pure data, unlike most sibling producer halves: the portability
+ * ruleset (`payments/no-host-imports`) allows no `@12-apps/wiring` import
+ * anywhere under `packages/payments/**`, type-only included — this package
+ * must vendor into a repo that has no wiring contract at all. The compliance
+ * run lives in the wiring suite's `payments-frontend-manifest.test.ts`
+ * instead, along a dependency edge that does exist, so a drift still fails a
+ * test run before any host sees it. That is exactly the arrangement
+ * `@12-apps/payments-backend`'s manifest already uses.
+ *
+ * TWO manifests, mirroring the backend's split for the same reason. The
+ * backend ships two route tables that must never merge — every library row is
+ * merchant-admin, every checkout row is the BUYER — and the browser half is
+ * the same product cut the same way:
+ *
+ * - **settings** is the OWNER's screen: which providers exist, which
+ *   credentials are stored, which one is tried first. It mounts in an admin
+ *   SPA, behind that host's admin session.
+ * - **checkout** is the SHOPPER's flow: methods, card entry, PIX, the hosted
+ *   hand-off and the return leg. It mounts in a storefront SPA, for an
+ *   anonymous visitor.
+ *
+ * One manifest would hand a host ONE surface config for two mounts that live
+ * in different applications, behind different gates, built from different
+ * ports — and would oblige the storefront to construct the owner's settings
+ * transport in order to render a checkout. Two make that impossible to
+ * express.
+ *
+ * ## THE NARROWINGS
+ *
+ * - **No `server` inventory on either.** There is no server half here; the
+ *   HTTP surfaces are `@12-apps/payments-backend`'s, declared in its own
+ *   manifest.
+ * - **No `db`, `permissions`, `mcp`, `env` or `e2e`.** This package stores
+ *   nothing, advertises no tools and reads no environment; every
+ *   authorization question is answered by the endpoints it talks to, and the
+ *   packaged journeys ship in the SIBLING `@12-apps/payments-e2e` (a
+ *   manifest must not declare an entry another package exports).
+ *
+ * `observability` names where a wiring host files each surface's browser
+ * reports. The package still binds no logger anywhere — it takes no
+ * observability dependency, by the same portability rule as above.
+ */
+
+/**
+ * The OWNER's provider-settings screen. Same identity as the package,
+ * because it is the half a host adopting "payments-frontend" means by
+ * default.
+ */
+export const paymentsFrontendManifest = {
+  name: '@12-apps/payments-frontend',
+  contract: 1,
+  observability: { namespace: 'payments' },
+  web: ['surface', 'areas'],
+} as const;
+
+/**
+ * The SHOPPER's checkout flow. Its own identity so a host adopts it into the
+ * storefront SPA alone — and so a version bump can never widen the admin
+ * mount with a buyer screen nobody re-reviewed.
+ *
+ * The namespace matches the backend's buyer surface (`payments-checkout`)
+ * rather than `payments`: a failed checkout is one incident across the two
+ * halves, and filing the browser side under the merchant namespace is what
+ * makes a shopper's dead end and the charge behind it look unrelated.
+ */
+export const paymentsCheckoutFrontendManifest = {
+  name: '@12-apps/payments-checkout-ui',
+  contract: 1,
+  observability: { namespace: 'payments-checkout' },
+  web: ['surface', 'areas'],
+} as const;

package/src/manifest/web.ts

@@ -0,0 +1,79 @@
+/**
+ * `@12-apps/payments-frontend/manifest/web` — the web capabilities.
+ *
+ * UNTYPED pure data — see `./index` for why this package may not import the
+ * wiring contract, and where its compliance run lives instead.
+ *
+ * Each `surface.create` IS the package's existing factory, unchanged:
+ * `createWebPaymentsSettings` for the owner's screen and `createPaymentFlows`
+ * for the buyer's. Both return component TYPES, so the consumer's binder
+ * builds them ONCE per adoption — which is the memoisation rule every hand
+ * wiring carries as a comment today, and which matters more here than
+ * anywhere: rebuilding `createPaymentFlows` per render would rebuild the
+ * checkout transport under a shopper mid-payment.
+ *
+ * ## WHAT STAYS SURFACE CONFIG, deliberately
+ *
+ * The design-system slots (`CheckoutComponentsProvider`'s button, input,
+ * stepper, alert…) and `CheckoutHostPorts` are the config a host hands
+ * `createPaymentFlows`, and they stay exactly that. They are not capabilities
+ * to declare: a slot table is one host's design system, and a port is one
+ * host's cart, scope and settlement. The contract's `surface` capability is
+ * precisely the shape that carries them — `create(config)` — so declaring
+ * the factory declares the whole seam without naming a single host's answer.
+ *
+ * Likewise the COPY packs. Every sentence both surfaces render is a required
+ * prop with no package default (FUT-760), because a default would be one
+ * product's Portuguese compiled into every other product's checkout. They
+ * stay per-render props rather than factory config for the reason the estate
+ * separates the two: copy follows the READER's locale, and freezing it at
+ * bind time pins the surface to whichever language was in effect when the
+ * host built it.
+ *
+ * ## THE AREAS
+ *
+ * Suggestions, structurally — the host composes, reorders, relabels and
+ * vetoes at its single call site. Each carries one honest fact:
+ *
+ * - the settings screen belongs in the ADMIN area, as a routed page with a
+ *   nav row (`testId: 'payments'` — the host maps its own icon and word);
+ * - the checkout belongs in the CLIENT area as a route with NO nav row. A
+ *   checkout is reached from a cart, never from a menu, and a nav entry
+ *   pointing at it is a link to an empty basket.
+ *
+ * No permission gates and no plan features on either: both are host
+ * vocabulary (this package depends on no RBAC and knows no plan catalog),
+ * and a package that guessed would be wrong for every host but the first.
+ */
+
+import { createPaymentFlows } from '../flows/create-payment-flows';
+import { createWebPaymentsSettings } from '../flows/create-payments-settings';
+
+/** The OWNER's provider-settings surface — one routed page in the admin SPA. */
+export const paymentsFrontendWebManifest = {
+  name: '@12-apps/payments-frontend',
+  surface: { create: createWebPaymentsSettings },
+  areas: [
+    {
+      area: 'admin',
+      routes: [{ path: 'config/payments', screen: 'page' }],
+      nav: [{ testId: 'payments', path: 'config/payments' }],
+    },
+  ],
+} as const;
+
+/**
+ * The SHOPPER's checkout surface. `screen: 'Checkout'` is the one-line mount
+ * `createPaymentFlows` returns; everything under `screens` is for a host
+ * composing its own pixels and is deliberately not routed here.
+ */
+export const paymentsCheckoutFrontendWebManifest = {
+  name: '@12-apps/payments-checkout-ui',
+  surface: { create: createPaymentFlows },
+  areas: [
+    {
+      area: 'client',
+      routes: [{ path: 'checkout', screen: 'Checkout' }],
+    },
+  ],
+} as const;