@mmzaini/starling-react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mahdi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+# Starling React
+
+Display account details and balances with React 18 or 19. This optional package
+contains no API client, authentication or network requests.
+
+```sh
+npm install @mmzaini/starling-react
+```
+
+```tsx
+import { AccountCard } from "@mmzaini/starling-react";
+import "@mmzaini/starling-react/styles.css";
+
+<AccountCard account={account} balance={balance} identifiers={identifiers} />;
+```
+
+The props accept the data returned by the SDK's `accounts.list()`,
+`accounts.getBalance({ accountUid })` and `accounts.getIdentifiers({ accountUid })`.
+Fetch that data on your server and pass only the authorized display data to the
+browser. The package also works with equivalent JSON from a Python backend.
+
+Identifiers are masked by default. Set `masked={false}` to reveal them, or control
+that prop from your own button. Visual masking is not access control: the full
+values are still in your application's memory. `hideBalance` hides the balance too.
+`status="loading"` and `status="error"` provide accessible states.
+
+Use `AccountDetails` and `Balance` separately for custom layouts:
+
+```tsx
+import { AccountDetails, Balance } from "@mmzaini/starling-react";
+
+<Balance amount={{ currency: "GBP", minorUnits: 12345 }} label="Available" />;
+<AccountDetails identifiers={identifiers} masked />;
+```
+
+`formatMoney({ currency, minorUnits }, locale)` formats integer minor units without
+floating-point division. It supports currency fraction digits, negative values and
+localized output. Unsafe integers are rejected; missing or invalid component amounts
+display an unavailable state. The default locale is `en-GB`, including during SSR.
+
+Styles are optional. Import the stylesheet once, or use the `starling-*` classes
+with your own CSS. `AccountCard` accepts `className`, `style`, `title` and footer
+`children`. It displays the effective balance and does not include balances in
+spaces. The components work with SSR and have no dependency on the TypeScript SDK.
+
+Run the example from this directory with `npm ci && npm run dev`. It uses dummy
+data and demonstrates masked details, loading and error states.
+
+For an example that fetches from Starling on the server, build the TypeScript SDK,
+set `STARLING_ACCESS_TOKEN` to a sandbox token, and run `npm run example:server`.
+Open `http://127.0.0.1:3001`. The server renders masked account details without
+passing credentials to React. It binds only to localhost; add your application's
+session authorization before deploying a similar route.
+
+Community maintained; not an official Starling Bank package. [SDK repository](https://github.com/MMZaini/starling-sdk).

package/dist/index.cjs

@@ -0,0 +1,94 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AccountCard: () => AccountCard,
+  AccountDetails: () => AccountDetails,
+  Balance: () => Balance,
+  formatMoney: () => formatMoney
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/money.ts
+function formatMoney(amount, locale = "en-GB") {
+  if (!Number.isSafeInteger(amount.minorUnits)) throw new RangeError("minorUnits must be a safe integer");
+  if (!/^[A-Z]{3}$/.test(amount.currency)) throw new RangeError("currency must be an uppercase ISO currency code");
+  const formatter = new Intl.NumberFormat(locale, { style: "currency", currency: amount.currency });
+  const digits = formatter.resolvedOptions().maximumFractionDigits;
+  if (digits === void 0) throw new RangeError("Could not determine the currency fraction digits");
+  const units = BigInt(amount.minorUnits);
+  const absolute = units < 0n ? -units : units;
+  const divisor = 10n ** BigInt(digits);
+  const whole = absolute / divisor;
+  const signedWhole = units < 0n ? whole === 0n ? -0 : -whole : whole;
+  const fraction = new Intl.NumberFormat(locale, { useGrouping: false, minimumIntegerDigits: Math.max(1, digits), maximumFractionDigits: 0 }).format(absolute % divisor);
+  return formatter.formatToParts(signedWhole).map((part) => part.type === "fraction" ? fraction : part.value).join("");
+}
+
+// src/components.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+function Balance({ amount, label = "Balance", locale = "en-GB", masked = false, className = "" }) {
+  let formatted;
+  if (amount && !masked) {
+    try {
+      formatted = formatMoney(amount, locale);
+    } catch (error) {
+      if (!(error instanceof RangeError)) throw error;
+    }
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: `starling-balance ${className}`, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { className: "starling-label", children: label }),
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { className: "starling-balance-value", "aria-label": masked ? `${label} hidden` : formatted ? `${label}: ${formatted}` : `${label} unavailable`, children: masked ? "\u2022\u2022\u2022\u2022" : formatted ?? "\u2014" })
+  ] });
+}
+function AccountDetails({ identifiers, masked = true, className = "" }) {
+  const rows = [
+    ["Account number", identifiers?.accountIdentifier],
+    ["Sort code", identifiers?.bankIdentifier],
+    ["IBAN", identifiers?.iban],
+    ["BIC", identifiers?.bic]
+  ].filter((row) => typeof row[1] === "string" && row[1].trim().length > 0);
+  if (!rows.length) return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { className: `starling-empty ${className}`, children: "Account details unavailable" });
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("dl", { className: `starling-details ${className}`, children: rows.map(([label, value]) => {
+    const compact = value.replace(/\s+/g, "");
+    const tail = compact.slice(-Math.min(4, Math.max(0, compact.length - 4)));
+    const visibleTail = compact.length > 4 ? tail : "";
+    const display = masked ? `\u2022\u2022\u2022\u2022${visibleTail}` : label === "Sort code" && /^\d{6}$/.test(compact) ? compact.match(/.{2}/g).join("-") : value;
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "starling-detail", children: [
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("dt", { children: label }),
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("dd", { "aria-label": masked ? `${label} hidden${visibleTail ? `, ending ${visibleTail}` : ""}` : void 0, children: display })
+    ] }, label);
+  }) });
+}
+function AccountCard({ account, balance, identifiers, title, status = "ready", masked = true, hideBalance = false, locale = "en-GB", children, className = "", style }) {
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("section", { className: `starling-card ${className}`, style, "aria-label": title ?? account?.name ?? "Account", "aria-busy": status === "loading", children: [
+    /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("header", { className: "starling-card-header", children: [
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("h2", { children: title ?? account?.name ?? "Account" }),
+      status === "ready" && account?.currency && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: "starling-currency", children: account.currency })
+    ] }),
+    status === "loading" ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { className: "starling-state", role: "status", children: "Loading account\u2026" }) : status === "error" ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { className: "starling-state", role: "alert", children: "Unable to load this account." }) : /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_jsx_runtime.Fragment, { children: [
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Balance, { amount: balance?.effectiveBalance, label: "Effective balance", locale, masked: hideBalance }),
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)(AccountDetails, { identifiers, masked }),
+      children && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("footer", { className: "starling-card-footer", children })
+    ] })
+  ] });
+}
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/money.ts","../src/components.tsx"],"sourcesContent":["export { AccountCard, AccountDetails, Balance } from \"./components.js\";\nexport type { AccountCardProps, AccountDetailsProps, AccountIdentifiers, BalanceProps } from \"./components.js\";\nexport { formatMoney } from \"./money.js\";\nexport type { Money } from \"./money.js\";\n","export interface Money {\n  currency: string;\n  minorUnits: number;\n}\n\n/** Format integer minor units without floating-point division or cent rounding. */\nexport function formatMoney(amount: Money, locale = \"en-GB\"): string {\n  if (!Number.isSafeInteger(amount.minorUnits)) throw new RangeError(\"minorUnits must be a safe integer\");\n  if (!/^[A-Z]{3}$/.test(amount.currency)) throw new RangeError(\"currency must be an uppercase ISO currency code\");\n  const formatter = new Intl.NumberFormat(locale, { style: \"currency\", currency: amount.currency });\n  const digits = formatter.resolvedOptions().maximumFractionDigits;\n  if (digits === undefined) throw new RangeError(\"Could not determine the currency fraction digits\");\n  const units = BigInt(amount.minorUnits);\n  const absolute = units < 0n ? -units : units;\n  const divisor = 10n ** BigInt(digits);\n  const whole = absolute / divisor;\n  const signedWhole = units < 0n ? (whole === 0n ? -0 : -whole) : whole;\n  const fraction = new Intl.NumberFormat(locale, { useGrouping: false, minimumIntegerDigits: Math.max(1, digits), maximumFractionDigits: 0 }).format(absolute % divisor);\n  return formatter.formatToParts(signedWhole).map((part) => part.type === \"fraction\" ? fraction : part.value).join(\"\");\n}\n","import type { CSSProperties, ReactNode } from \"react\";\nimport { formatMoney, type Money } from \"./money.js\";\n\nexport interface AccountIdentifiers {\n  accountIdentifier?: string;\n  bankIdentifier?: string;\n  iban?: string;\n  bic?: string;\n}\n\nexport interface BalanceProps {\n  amount?: Money | null;\n  label?: string;\n  locale?: string;\n  masked?: boolean;\n  className?: string;\n}\n\nexport function Balance({ amount, label = \"Balance\", locale = \"en-GB\", masked = false, className = \"\" }: BalanceProps) {\n  let formatted: string | undefined;\n  if (amount && !masked) {\n    try { formatted = formatMoney(amount, locale); }\n    catch (error) { if (!(error instanceof RangeError)) throw error; }\n  }\n  return <div className={`starling-balance ${className}`}>\n    <p className=\"starling-label\">{label}</p>\n    <p className=\"starling-balance-value\" aria-label={masked ? `${label} hidden` : formatted ? `${label}: ${formatted}` : `${label} unavailable`}>\n      {masked ? \"••••\" : formatted ?? \"—\"}\n    </p>\n  </div>;\n}\n\nexport interface AccountDetailsProps {\n  identifiers?: AccountIdentifiers | null;\n  /** Visual masking only. Full values must still be authorized for this user. */\n  masked?: boolean;\n  className?: string;\n}\n\nexport function AccountDetails({ identifiers, masked = true, className = \"\" }: AccountDetailsProps) {\n  const rows = [\n    [\"Account number\", identifiers?.accountIdentifier],\n    [\"Sort code\", identifiers?.bankIdentifier],\n    [\"IBAN\", identifiers?.iban],\n    [\"BIC\", identifiers?.bic],\n  ].filter((row): row is [string, string] => typeof row[1] === \"string\" && row[1].trim().length > 0);\n  if (!rows.length) return <p className={`starling-empty ${className}`}>Account details unavailable</p>;\n  return <dl className={`starling-details ${className}`}>\n    {rows.map(([label, value]) => {\n      const compact = value.replace(/\\s+/g, \"\");\n      const tail = compact.slice(-Math.min(4, Math.max(0, compact.length - 4)));\n      const visibleTail = compact.length > 4 ? tail : \"\";\n      const display = masked ? `••••${visibleTail}` : label === \"Sort code\" && /^\\d{6}$/.test(compact) ? compact.match(/.{2}/g)!.join(\"-\") : value;\n      return <div className=\"starling-detail\" key={label}>\n        <dt>{label}</dt>\n        <dd aria-label={masked ? `${label} hidden${visibleTail ? `, ending ${visibleTail}` : \"\"}` : undefined}>{display}</dd>\n      </div>;\n    })}\n  </dl>;\n}\n\nexport interface AccountCardProps {\n  account?: { name?: string; currency?: string } | null;\n  balance?: { effectiveBalance?: Money } | null;\n  identifiers?: AccountIdentifiers | null;\n  title?: string;\n  status?: \"ready\" | \"loading\" | \"error\";\n  masked?: boolean;\n  hideBalance?: boolean;\n  locale?: string;\n  children?: ReactNode;\n  className?: string;\n  style?: CSSProperties;\n}\n\n/** Display-only account summary. Fetch and authorize its data on your server. */\nexport function AccountCard({ account, balance, identifiers, title, status = \"ready\", masked = true, hideBalance = false, locale = \"en-GB\", children, className = \"\", style }: AccountCardProps) {\n  return <section className={`starling-card ${className}`} style={style} aria-label={title ?? account?.name ?? \"Account\"} aria-busy={status === \"loading\"}>\n    <header className=\"starling-card-header\">\n      <h2>{title ?? account?.name ?? \"Account\"}</h2>\n      {status === \"ready\" && account?.currency && <span className=\"starling-currency\">{account.currency}</span>}\n    </header>\n    {status === \"loading\" ? <p className=\"starling-state\" role=\"status\">Loading account…</p>\n      : status === \"error\" ? <p className=\"starling-state\" role=\"alert\">Unable to load this account.</p>\n        : <>\n          <Balance amount={balance?.effectiveBalance} label=\"Effective balance\" locale={locale} masked={hideBalance} />\n          <AccountDetails identifiers={identifiers} masked={masked} />\n          {children && <footer className=\"starling-card-footer\">{children}</footer>}\n        </>}\n  </section>;\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,53 @@
+import * as react from 'react';
+import { ReactNode, CSSProperties } from 'react';
+
+interface Money {
+    currency: string;
+    minorUnits: number;
+}
+/** Format integer minor units without floating-point division or cent rounding. */
+declare function formatMoney(amount: Money, locale?: string): string;
+
+interface AccountIdentifiers {
+    accountIdentifier?: string;
+    bankIdentifier?: string;
+    iban?: string;
+    bic?: string;
+}
+interface BalanceProps {
+    amount?: Money | null;
+    label?: string;
+    locale?: string;
+    masked?: boolean;
+    className?: string;
+}
+declare function Balance({ amount, label, locale, masked, className }: BalanceProps): react.JSX.Element;
+interface AccountDetailsProps {
+    identifiers?: AccountIdentifiers | null;
+    /** Visual masking only. Full values must still be authorized for this user. */
+    masked?: boolean;
+    className?: string;
+}
+declare function AccountDetails({ identifiers, masked, className }: AccountDetailsProps): react.JSX.Element;
+interface AccountCardProps {
+    account?: {
+        name?: string;
+        currency?: string;
+    } | null;
+    balance?: {
+        effectiveBalance?: Money;
+    } | null;
+    identifiers?: AccountIdentifiers | null;
+    title?: string;
+    status?: "ready" | "loading" | "error";
+    masked?: boolean;
+    hideBalance?: boolean;
+    locale?: string;
+    children?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}
+/** Display-only account summary. Fetch and authorize its data on your server. */
+declare function AccountCard({ account, balance, identifiers, title, status, masked, hideBalance, locale, children, className, style }: AccountCardProps): react.JSX.Element;
+
+export { AccountCard, type AccountCardProps, AccountDetails, type AccountDetailsProps, type AccountIdentifiers, Balance, type BalanceProps, type Money, formatMoney };

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+import * as react from 'react';
+import { ReactNode, CSSProperties } from 'react';
+
+interface Money {
+    currency: string;
+    minorUnits: number;
+}
+/** Format integer minor units without floating-point division or cent rounding. */
+declare function formatMoney(amount: Money, locale?: string): string;
+
+interface AccountIdentifiers {
+    accountIdentifier?: string;
+    bankIdentifier?: string;
+    iban?: string;
+    bic?: string;
+}
+interface BalanceProps {
+    amount?: Money | null;
+    label?: string;
+    locale?: string;
+    masked?: boolean;
+    className?: string;
+}
+declare function Balance({ amount, label, locale, masked, className }: BalanceProps): react.JSX.Element;
+interface AccountDetailsProps {
+    identifiers?: AccountIdentifiers | null;
+    /** Visual masking only. Full values must still be authorized for this user. */
+    masked?: boolean;
+    className?: string;
+}
+declare function AccountDetails({ identifiers, masked, className }: AccountDetailsProps): react.JSX.Element;
+interface AccountCardProps {
+    account?: {
+        name?: string;
+        currency?: string;
+    } | null;
+    balance?: {
+        effectiveBalance?: Money;
+    } | null;
+    identifiers?: AccountIdentifiers | null;
+    title?: string;
+    status?: "ready" | "loading" | "error";
+    masked?: boolean;
+    hideBalance?: boolean;
+    locale?: string;
+    children?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}
+/** Display-only account summary. Fetch and authorize its data on your server. */
+declare function AccountCard({ account, balance, identifiers, title, status, masked, hideBalance, locale, children, className, style }: AccountCardProps): react.JSX.Element;
+
+export { AccountCard, type AccountCardProps, AccountDetails, type AccountDetailsProps, type AccountIdentifiers, Balance, type BalanceProps, type Money, formatMoney };

package/dist/index.js

@@ -0,0 +1,71 @@
+// src/money.ts
+function formatMoney(amount, locale = "en-GB") {
+  if (!Number.isSafeInteger(amount.minorUnits)) throw new RangeError("minorUnits must be a safe integer");
+  if (!/^[A-Z]{3}$/.test(amount.currency)) throw new RangeError("currency must be an uppercase ISO currency code");
+  const formatter = new Intl.NumberFormat(locale, { style: "currency", currency: amount.currency });
+  const digits = formatter.resolvedOptions().maximumFractionDigits;
+  if (digits === void 0) throw new RangeError("Could not determine the currency fraction digits");
+  const units = BigInt(amount.minorUnits);
+  const absolute = units < 0n ? -units : units;
+  const divisor = 10n ** BigInt(digits);
+  const whole = absolute / divisor;
+  const signedWhole = units < 0n ? whole === 0n ? -0 : -whole : whole;
+  const fraction = new Intl.NumberFormat(locale, { useGrouping: false, minimumIntegerDigits: Math.max(1, digits), maximumFractionDigits: 0 }).format(absolute % divisor);
+  return formatter.formatToParts(signedWhole).map((part) => part.type === "fraction" ? fraction : part.value).join("");
+}
+
+// src/components.tsx
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+function Balance({ amount, label = "Balance", locale = "en-GB", masked = false, className = "" }) {
+  let formatted;
+  if (amount && !masked) {
+    try {
+      formatted = formatMoney(amount, locale);
+    } catch (error) {
+      if (!(error instanceof RangeError)) throw error;
+    }
+  }
+  return /* @__PURE__ */ jsxs("div", { className: `starling-balance ${className}`, children: [
+    /* @__PURE__ */ jsx("p", { className: "starling-label", children: label }),
+    /* @__PURE__ */ jsx("p", { className: "starling-balance-value", "aria-label": masked ? `${label} hidden` : formatted ? `${label}: ${formatted}` : `${label} unavailable`, children: masked ? "\u2022\u2022\u2022\u2022" : formatted ?? "\u2014" })
+  ] });
+}
+function AccountDetails({ identifiers, masked = true, className = "" }) {
+  const rows = [
+    ["Account number", identifiers?.accountIdentifier],
+    ["Sort code", identifiers?.bankIdentifier],
+    ["IBAN", identifiers?.iban],
+    ["BIC", identifiers?.bic]
+  ].filter((row) => typeof row[1] === "string" && row[1].trim().length > 0);
+  if (!rows.length) return /* @__PURE__ */ jsx("p", { className: `starling-empty ${className}`, children: "Account details unavailable" });
+  return /* @__PURE__ */ jsx("dl", { className: `starling-details ${className}`, children: rows.map(([label, value]) => {
+    const compact = value.replace(/\s+/g, "");
+    const tail = compact.slice(-Math.min(4, Math.max(0, compact.length - 4)));
+    const visibleTail = compact.length > 4 ? tail : "";
+    const display = masked ? `\u2022\u2022\u2022\u2022${visibleTail}` : label === "Sort code" && /^\d{6}$/.test(compact) ? compact.match(/.{2}/g).join("-") : value;
+    return /* @__PURE__ */ jsxs("div", { className: "starling-detail", children: [
+      /* @__PURE__ */ jsx("dt", { children: label }),
+      /* @__PURE__ */ jsx("dd", { "aria-label": masked ? `${label} hidden${visibleTail ? `, ending ${visibleTail}` : ""}` : void 0, children: display })
+    ] }, label);
+  }) });
+}
+function AccountCard({ account, balance, identifiers, title, status = "ready", masked = true, hideBalance = false, locale = "en-GB", children, className = "", style }) {
+  return /* @__PURE__ */ jsxs("section", { className: `starling-card ${className}`, style, "aria-label": title ?? account?.name ?? "Account", "aria-busy": status === "loading", children: [
+    /* @__PURE__ */ jsxs("header", { className: "starling-card-header", children: [
+      /* @__PURE__ */ jsx("h2", { children: title ?? account?.name ?? "Account" }),
+      status === "ready" && account?.currency && /* @__PURE__ */ jsx("span", { className: "starling-currency", children: account.currency })
+    ] }),
+    status === "loading" ? /* @__PURE__ */ jsx("p", { className: "starling-state", role: "status", children: "Loading account\u2026" }) : status === "error" ? /* @__PURE__ */ jsx("p", { className: "starling-state", role: "alert", children: "Unable to load this account." }) : /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsx(Balance, { amount: balance?.effectiveBalance, label: "Effective balance", locale, masked: hideBalance }),
+      /* @__PURE__ */ jsx(AccountDetails, { identifiers, masked }),
+      children && /* @__PURE__ */ jsx("footer", { className: "starling-card-footer", children })
+    ] })
+  ] });
+}
+export {
+  AccountCard,
+  AccountDetails,
+  Balance,
+  formatMoney
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/money.ts","../src/components.tsx"],"sourcesContent":["export interface Money {\n  currency: string;\n  minorUnits: number;\n}\n\n/** Format integer minor units without floating-point division or cent rounding. */\nexport function formatMoney(amount: Money, locale = \"en-GB\"): string {\n  if (!Number.isSafeInteger(amount.minorUnits)) throw new RangeError(\"minorUnits must be a safe integer\");\n  if (!/^[A-Z]{3}$/.test(amount.currency)) throw new RangeError(\"currency must be an uppercase ISO currency code\");\n  const formatter = new Intl.NumberFormat(locale, { style: \"currency\", currency: amount.currency });\n  const digits = formatter.resolvedOptions().maximumFractionDigits;\n  if (digits === undefined) throw new RangeError(\"Could not determine the currency fraction digits\");\n  const units = BigInt(amount.minorUnits);\n  const absolute = units < 0n ? -units : units;\n  const divisor = 10n ** BigInt(digits);\n  const whole = absolute / divisor;\n  const signedWhole = units < 0n ? (whole === 0n ? -0 : -whole) : whole;\n  const fraction = new Intl.NumberFormat(locale, { useGrouping: false, minimumIntegerDigits: Math.max(1, digits), maximumFractionDigits: 0 }).format(absolute % divisor);\n  return formatter.formatToParts(signedWhole).map((part) => part.type === \"fraction\" ? fraction : part.value).join(\"\");\n}\n","import type { CSSProperties, ReactNode } from \"react\";\nimport { formatMoney, type Money } from \"./money.js\";\n\nexport interface AccountIdentifiers {\n  accountIdentifier?: string;\n  bankIdentifier?: string;\n  iban?: string;\n  bic?: string;\n}\n\nexport interface BalanceProps {\n  amount?: Money | null;\n  label?: string;\n  locale?: string;\n  masked?: boolean;\n  className?: string;\n}\n\nexport function Balance({ amount, label = \"Balance\", locale = \"en-GB\", masked = false, className = \"\" }: BalanceProps) {\n  let formatted: string | undefined;\n  if (amount && !masked) {\n    try { formatted = formatMoney(amount, locale); }\n    catch (error) { if (!(error instanceof RangeError)) throw error; }\n  }\n  return <div className={`starling-balance ${className}`}>\n    <p className=\"starling-label\">{label}</p>\n    <p className=\"starling-balance-value\" aria-label={masked ? `${label} hidden` : formatted ? `${label}: ${formatted}` : `${label} unavailable`}>\n      {masked ? \"••••\" : formatted ?? \"—\"}\n    </p>\n  </div>;\n}\n\nexport interface AccountDetailsProps {\n  identifiers?: AccountIdentifiers | null;\n  /** Visual masking only. Full values must still be authorized for this user. */\n  masked?: boolean;\n  className?: string;\n}\n\nexport function AccountDetails({ identifiers, masked = true, className = \"\" }: AccountDetailsProps) {\n  const rows = [\n    [\"Account number\", identifiers?.accountIdentifier],\n    [\"Sort code\", identifiers?.bankIdentifier],\n    [\"IBAN\", identifiers?.iban],\n    [\"BIC\", identifiers?.bic],\n  ].filter((row): row is [string, string] => typeof row[1] === \"string\" && row[1].trim().length > 0);\n  if (!rows.length) return <p className={`starling-empty ${className}`}>Account details unavailable</p>;\n  return <dl className={`starling-details ${className}`}>\n    {rows.map(([label, value]) => {\n      const compact = value.replace(/\\s+/g, \"\");\n      const tail = compact.slice(-Math.min(4, Math.max(0, compact.length - 4)));\n      const visibleTail = compact.length > 4 ? tail : \"\";\n      const display = masked ? `••••${visibleTail}` : label === \"Sort code\" && /^\\d{6}$/.test(compact) ? compact.match(/.{2}/g)!.join(\"-\") : value;\n      return <div className=\"starling-detail\" key={label}>\n        <dt>{label}</dt>\n        <dd aria-label={masked ? `${label} hidden${visibleTail ? `, ending ${visibleTail}` : \"\"}` : undefined}>{display}</dd>\n      </div>;\n    })}\n  </dl>;\n}\n\nexport interface AccountCardProps {\n  account?: { name?: string; currency?: string } | null;\n  balance?: { effectiveBalance?: Money } | null;\n  identifiers?: AccountIdentifiers | null;\n  title?: string;\n  status?: \"ready\" | \"loading\" | \"error\";\n  masked?: boolean;\n  hideBalance?: boolean;\n  locale?: string;\n  children?: ReactNode;\n  className?: string;\n  style?: CSSProperties;\n}\n\n/** Display-only account summary. Fetch and authorize its data on your server. */\nexport function AccountCard({ account, balance, identifiers, title, status = \"ready\", masked = true, hideBalance = false, locale = \"en-GB\", children, className = \"\", style }: AccountCardProps) {\n  return <section className={`starling-card ${className}`} style={style} aria-label={title ?? account?.name ?? \"Account\"} aria-busy={status === \"loading\"}>\n    <header className=\"starling-card-header\">\n      <h2>{title ?? account?.name ?? \"Account\"}</h2>\n      {status === \"ready\" && account?.currency && <span className=\"starling-currency\">{account.currency}</span>}\n    </header>\n    {status === \"loading\" ? <p className=\"starling-state\" role=\"status\">Loading account…</p>\n      : status === \"error\" ? <p className=\"starling-state\" role=\"alert\">Unable to load this account.</p>\n        : <>\n          <Balance amount={balance?.effectiveBalance} label=\"Effective balance\" locale={locale} masked={hideBalance} />\n          <AccountDetails identifiers={identifiers} masked={masked} />\n          {children && <footer className=\"starling-card-footer\">{children}</footer>}\n        </>}\n  </section>;\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@mmzaini/starling-react",
+  "version": "0.1.0",
+  "description": "React components for displaying Starling account details and balances",
+  "license": "MIT",
+  "author": "MMZaini",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MMZaini/starling-sdk.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://github.com/MMZaini/starling-sdk/tree/main/packages/react",
+  "bugs": "https://github.com/MMZaini/starling-sdk/issues",
+  "keywords": ["starling", "starling-bank", "react", "components"],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
+      "require": { "types": "./dist/index.d.cts", "default": "./dist/index.cjs" }
+    },
+    "./styles.css": "./styles.css"
+  },
+  "files": ["dist", "styles.css", "README.md", "LICENSE"],
+  "sideEffects": ["*.css"],
+  "publishConfig": { "access": "public" },
+  "peerDependencies": { "react": "^18.3.1 || ^19.0.0" },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test tests/*.test.tsx",
+    "test:browser": "playwright test",
+    "dev": "vite example --host 127.0.0.1",
+    "example:server": "node --import tsx example/server.tsx",
+    "prepublishOnly": "npm run typecheck && npm run build"
+  },
+  "devDependencies": {
+    "@axe-core/playwright": "4.13.0",
+    "@playwright/test": "1.63.0",
+    "@types/node": "22.20.2",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "tsup": "8.5.1",
+    "tsx": "4.23.13",
+    "typescript": "5.9.3",
+    "vite": "8.3.0"
+  },
+  "overrides": { "esbuild": "^0.28.2" }
+}

package/styles.css

@@ -0,0 +1,28 @@
+.starling-card {
+  --starling-text: #192830;
+  --starling-muted: #526570;
+  --starling-border: #dce4e7;
+  --starling-surface: #fff;
+  --starling-accent: #006b65;
+  box-sizing: border-box;
+  color: var(--starling-text);
+  background: var(--starling-surface);
+  border: 1px solid var(--starling-border);
+  border-radius: 1rem;
+  padding: 1.5rem;
+  font-family: ui-sans-serif, system-ui, sans-serif;
+  min-width: 0;
+}
+.starling-card-header { display: flex; align-items: center; justify-content: space-between; gap: 1rem; }
+.starling-card-header h2 { margin: 0; font-size: 1.1rem; font-weight: 650; overflow-wrap: anywhere; }
+.starling-currency { color: var(--starling-accent, #006b65); background: #eaf5f3; padding: .3rem .55rem; border-radius: .4rem; font-size: .75rem; font-weight: 650; }
+.starling-balance { color: var(--starling-text, #192830); padding: 1.7rem 0; }
+.starling-label { color: var(--starling-muted, #526570); margin: 0 0 .4rem; font-size: .85rem; }
+.starling-balance-value { margin: 0; font-size: clamp(1.6rem, 5vw, 2rem); font-weight: 600; letter-spacing: -.04em; font-variant-numeric: tabular-nums; overflow-wrap: anywhere; }
+.starling-details { margin: 0; color: var(--starling-text, #192830); }
+.starling-detail { display: flex; justify-content: space-between; gap: 1.2rem; padding: .8rem 0; border-top: 1px solid var(--starling-border, #dce4e7); font-size: .875rem; }
+.starling-detail dt { color: var(--starling-muted, #526570); flex-shrink: 0; }
+.starling-detail dd { margin: 0; text-align: right; font-variant-numeric: tabular-nums; overflow-wrap: anywhere; min-width: 0; }
+.starling-empty, .starling-state { color: var(--starling-muted, #526570); font-size: .875rem; }
+.starling-state { padding: 2rem 0; }
+.starling-card-footer { border-top: 1px solid var(--starling-border); margin-top: .25rem; padding-top: 1.15rem; font-size: .875rem; }