@jskit-ai/payments-web 0.1.61 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+## 0.2.0 - 2026-10-29
+
+- Translation ready: every user-visible text is a message key with its English in `locales/en.json`, so an app translates it by supplying translation files only. With no translations, texts and behaviour are unchanged. See the guide "Translating a JSKIT app".
+
+### New message keys (43)
+
+All keys in `locales/en.json` (exported as `./locales/en.json`) are new in this version.
+
+<details><summary>Key list</summary>
+
+- `jskit.payments.account.region`
+- `jskit.payments.account.retryDetails`
+- `jskit.payments.account.availableCredits`
+- `jskit.payments.account.includedFeatures`
+- `jskit.payments.account.noPaidFeatures`
+- `jskit.payments.account.subscriptions`
+- `jskit.payments.account.periodEnd`
+- `jskit.payments.account.noSubscription`
+- `jskit.payments.account.manageBilling`
+- `jskit.payments.account.refreshDetails`
+- `jskit.payments.account.adminManages`
+- `jskit.payments.account.useManageBilling`
+- `jskit.payments.account.confirmationNote`
+- `jskit.payments.account.availablePlans`
+- `jskit.payments.account.renewalCredits`
+- `jskit.payments.account.choosePlan`
+- `jskit.payments.account.choosePlanNamed`
+- `jskit.payments.account.notAvailableForCheckout`
+- `jskit.payments.account.noPlans`
+- `jskit.payments.account.unavailable`
+- `jskit.payments.account.status.active`
+- `jskit.payments.account.status.trialing`
+- `jskit.payments.account.status.pastDue`
+- `jskit.payments.account.status.paused`
+- `jskit.payments.account.status.canceled`
+- `jskit.payments.account.status.unpaid`
+- `jskit.payments.account.status.incomplete`
+- `jskit.payments.account.status.incompleteExpired`
+- `jskit.payments.account.history.region`
+- `jskit.payments.account.history.viewTransactions`
+- `jskit.payments.account.history.viewSubscriptions`
+- `jskit.payments.account.history.retry`
+- `jskit.payments.account.history.unpaidNote`
+- `jskit.payments.account.history.records`
+- `jskit.payments.account.history.invoice`
+- `jskit.payments.account.history.transaction`
+- `jskit.payments.account.history.subscription`
+- `jskit.payments.account.history.statusAndDate`
+- `jskit.payments.account.history.total`
+- `jskit.payments.account.history.totalPending`
+- `jskit.payments.account.history.totalAndPaid`
+- `jskit.payments.account.history.empty`
+- `jskit.payments.account.history.nextPage`
+
+</details>

package/README.md

@@ -2,7 +2,8 @@
 
 `@jskit-ai/payments-web` supplies a Vue/Vuetify account component for generated or
 hand-written JavaScript applications. It has no Vibe64, Online, Genesis, provider
-SDK, credential, file-discovery or HTTP dependency. The application mounts it in
+SDK, credential, file-discovery or HTTP dependency; its only JSKIT peer is
+`@jskit-ai/kernel`, for the client text helper. The application mounts it in
 its existing billing page or semantic placement. It does not register routes or
 change shell navigation automatically. This worktree package is not yet published.
 
@@ -23,7 +24,12 @@ Import `PaymentAccount` from
 | `history` | One authorized `{collection, items, nextCursor}` provider page, or null |
 | `historyLoading` | History request pending; displays skeletons and disables page/collection requests |
 | `historyError` | Safe history read failure; hides stale rows and offers Retry |
-| `locale` | Optional locale for integer credit and UTC date formatting |
+| `locale` | Optional locale for integer credit and UTC date formatting; defaults to the app's active language |
+
+Every text the component renders is a `jskit.payments.account.*` message in
+`locales/en.json`. With the app's vue-i18n registered through JSKIT, it shows the
+user's language; without it, the English is shown as before. Plan names, price
+labels, feature names and the `loadError`/`historyError` texts are the app's own.
 
 Subscription records contain `id`, `planId`, `status`, and `periodEnd` in UTC
 milliseconds. `payments-core`'s authorized `checkout.account({actor, subjectId})`
@@ -126,8 +132,9 @@ insert a second error banner or duplicate that request state. Re-read on the
 return route; a success query parameter must never grant paid access.
 
 Laravel owns its native server and UI implementation. An Inertia/Vue application
-can choose this presentational component, but no JSKIT runtime is required for
-Laravel to implement the documented JSON account/plan display shape and actions.
+can choose this presentational component (installing its `@jskit-ai/kernel` peer
+for the text helper), but no JSKIT runtime is required for Laravel to implement
+the documented JSON account/plan display shape and actions.
 
 ## Evidence
 

package/locales/en.json

@@ -0,0 +1,55 @@
+{
+  "jskit": {
+    "payments": {
+      "account": {
+        "region": "Subscription and billing",
+        "retryDetails": "Retry billing details",
+        "availableCredits": "Available credits",
+        "includedFeatures": "Included features",
+        "noPaidFeatures": "No paid features active",
+        "subscriptions": "Subscriptions",
+        "periodEnd": "Period end: {date} (UTC)",
+        "noSubscription": "No subscription yet.",
+        "manageBilling": "Manage billing",
+        "refreshDetails": "Refresh billing details",
+        "adminManages": "A billing administrator can manage this account.",
+        "useManageBilling": "Use Manage billing to update your subscription or payment details.",
+        "confirmationNote": "Access and credits update after payment confirmation. Returning from checkout alone does not activate a plan.",
+        "availablePlans": "Available plans",
+        "renewalCredits": "{credits} credits per paid renewal; unused renewal credits expire at period end.",
+        "choosePlan": "Choose plan",
+        "choosePlanNamed": "Choose {plan}",
+        "notAvailableForCheckout": "Not available for checkout yet.",
+        "noPlans": "No plans are available yet.",
+        "unavailable": "Billing details are not available yet.",
+        "status": {
+          "active": "Active",
+          "trialing": "Trial",
+          "pastDue": "Payment overdue",
+          "paused": "Paused",
+          "canceled": "Canceled",
+          "unpaid": "Unpaid",
+          "incomplete": "Payment incomplete",
+          "incompleteExpired": "Payment expired"
+        },
+        "history": {
+          "region": "Billing history",
+          "viewTransactions": "View invoices and transactions",
+          "viewSubscriptions": "View subscription history",
+          "retry": "Retry billing history",
+          "unpaidNote": "Invoices and transactions include unpaid records. Their totals do not confirm payment.",
+          "records": "Provider billing records",
+          "invoice": "Invoice {id}",
+          "transaction": "Transaction {id}",
+          "subscription": "Subscription {id}",
+          "statusAndDate": "{status} · {date} (UTC)",
+          "total": "Total: {total}",
+          "totalPending": "Not available yet",
+          "totalAndPaid": "Total: {total} · Paid: {paid}",
+          "empty": "No billing records found.",
+          "nextPage": "Next billing page"
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@jskit-ai/payments-web",
-  "version": "0.1.61",
+  "version": "0.2.1",
   "type": "module",
   "description": "Application-owned billing views for JSKIT Vue applications.",
   "exports": {
-    "./client/components/PaymentAccount": "./src/client/components/PaymentAccount.vue"
+    "./client/components/PaymentAccount": "./src/client/components/PaymentAccount.vue",
+    "./locales/en.json": "./locales/en.json"
   },
   "peerDependencies": {
+    "@jskit-ai/kernel": "0.2.1",
     "vue": "^3.5.13",
     "vuetify": "^4.0.0"
   },

package/src/client/components/PaymentAccount.vue

@@ -1,5 +1,6 @@
 <script setup>
 import { computed } from "vue";
+import { useJskitText } from "../i18n.js";
 
 const props = defineProps({
   plans: { type: Array, default: () => [] },
@@ -19,13 +20,35 @@ const subscriptions = computed(() => props.account?.subscriptions ?? []);
 const hasSubscription = computed(() => subscriptions.value.some((item) =>
   !["canceled", "incomplete_expired"].includes(item.status)));
 const disabled = computed(() => props.pending || props.loading || Boolean(props.loadError) || !props.account || !props.canManage);
-const statuses = {
-  active: "Active", trialing: "Trial", past_due: "Payment overdue", paused: "Paused",
-  canceled: "Canceled", unpaid: "Unpaid", incomplete: "Payment incomplete",
-  incomplete_expired: "Payment expired"
+const jskitText = useJskitText();
+const { t } = jskitText;
+const statusKeys = {
+  active: "jskit.payments.account.status.active",
+  trialing: "jskit.payments.account.status.trialing",
+  past_due: "jskit.payments.account.status.pastDue",
+  paused: "jskit.payments.account.status.paused",
+  canceled: "jskit.payments.account.status.canceled",
+  unpaid: "jskit.payments.account.status.unpaid",
+  incomplete: "jskit.payments.account.status.incomplete",
+  incomplete_expired: "jskit.payments.account.status.incompleteExpired"
 };
-const number = (value) => new Intl.NumberFormat(props.locale).format(value);
-const date = (value) => new Intl.DateTimeFormat(props.locale, { dateStyle: "medium", timeZone: "UTC" }).format(value);
+const historyKindKeys = {
+  invoice: "jskit.payments.account.history.invoice",
+  transaction: "jskit.payments.account.history.transaction"
+};
+const historyTitle = (item) =>
+  t(Object.hasOwn(historyKindKeys, item.kind) ? historyKindKeys[item.kind] : "jskit.payments.account.history.subscription", { id: item.id });
+const historyTotal = (item) => {
+  const total = item.totalLabel ?? t("jskit.payments.account.history.totalPending");
+  return item.paidLabel
+    ? t("jskit.payments.account.history.totalAndPaid", { total, paid: item.paidLabel })
+    : t("jskit.payments.account.history.total", { total });
+};
+const statusLabel = (status) => Object.hasOwn(statusKeys, status) ? t(statusKeys[status]) : status;
+// An explicit locale prop wins; otherwise numbers and dates follow the app's language.
+const locale = () => props.locale ?? jskitText.locale;
+const number = (value) => new Intl.NumberFormat(locale()).format(value);
+const date = (value) => new Intl.DateTimeFormat(locale(), { dateStyle: "medium", timeZone: "UTC" }).format(value);
 const planName = (id) => props.plans.find((plan) => plan.id === id)?.name ?? id;
 function checkout(plan) {
   if (!disabled.value && !hasSubscription.value && plan.available === true) emit("checkout", plan.id);
@@ -36,68 +59,68 @@ function loadHistory(collection, after = null) {
 </script>
 
 <template>
-  <section class="payment-account" aria-label="Subscription and billing" :aria-busy="loading || pending">
+  <section class="payment-account" :aria-label="t('jskit.payments.account.region')" :aria-busy="loading || pending">
     <v-skeleton-loader v-if="loading && !account" type="article, list-item-two-line, actions" />
     <div v-else-if="loadError" role="alert">
       <p>{{ loadError }}</p>
-      <v-btn variant="tonal" :disabled="loading" @click="emit('refresh')">Retry billing details</v-btn>
+      <v-btn variant="tonal" :disabled="loading" @click="emit('refresh')">{{ t('jskit.payments.account.retryDetails') }}</v-btn>
     </div>
     <template v-else-if="account">
       <dl class="payment-account__summary">
-        <div><dt>Available credits</dt><dd>{{ number(account.balance) }}</dd></div>
-        <div><dt>Included features</dt><dd>{{ account.features.length ? account.features.join(', ') : 'No paid features active' }}</dd></div>
+        <div><dt>{{ t('jskit.payments.account.availableCredits') }}</dt><dd>{{ number(account.balance) }}</dd></div>
+        <div><dt>{{ t('jskit.payments.account.includedFeatures') }}</dt><dd>{{ account.features.length ? account.features.join(', ') : t('jskit.payments.account.noPaidFeatures') }}</dd></div>
       </dl>
-      <ul v-if="subscriptions.length" class="payment-account__subscriptions" aria-label="Subscriptions">
+      <ul v-if="subscriptions.length" class="payment-account__subscriptions" :aria-label="t('jskit.payments.account.subscriptions')">
         <li v-for="subscription in subscriptions" :key="subscription.id">
           <strong>{{ planName(subscription.planId) }}</strong>
-          <span>{{ statuses[subscription.status] ?? subscription.status }}</span>
-          <span v-if="subscription.periodEnd > 0">Period end: {{ date(subscription.periodEnd) }} (UTC)</span>
+          <span>{{ statusLabel(subscription.status) }}</span>
+          <span v-if="subscription.periodEnd > 0">{{ t('jskit.payments.account.periodEnd', { date: date(subscription.periodEnd) }) }}</span>
         </li>
       </ul>
-      <p v-else>No subscription yet.</p>
+      <p v-else>{{ t('jskit.payments.account.noSubscription') }}</p>
       <div class="payment-account__actions">
-        <v-btn v-if="account.hasCustomer" variant="tonal" :disabled="disabled" @click="emit('portal')">Manage billing</v-btn>
-        <v-btn variant="text" :disabled="loading || pending" @click="emit('refresh')">Refresh billing details</v-btn>
+        <v-btn v-if="account.hasCustomer" variant="tonal" :disabled="disabled" @click="emit('portal')">{{ t('jskit.payments.account.manageBilling') }}</v-btn>
+        <v-btn variant="text" :disabled="loading || pending" @click="emit('refresh')">{{ t('jskit.payments.account.refreshDetails') }}</v-btn>
       </div>
-      <p v-if="!canManage">A billing administrator can manage this account.</p>
-      <p v-else-if="hasSubscription">Use Manage billing to update your subscription or payment details.</p>
-      <p>Access and credits update after payment confirmation. Returning from checkout alone does not activate a plan.</p>
-      <ul v-if="plans.length" class="payment-account__plans" aria-label="Available plans">
+      <p v-if="!canManage">{{ t('jskit.payments.account.adminManages') }}</p>
+      <p v-else-if="hasSubscription">{{ t('jskit.payments.account.useManageBilling') }}</p>
+      <p>{{ t('jskit.payments.account.confirmationNote') }}</p>
+      <ul v-if="plans.length" class="payment-account__plans" :aria-label="t('jskit.payments.account.availablePlans')">
         <li v-for="plan in plans" :key="plan.id" class="payment-account__plan">
           <strong>{{ plan.name }}</strong>
           <p>{{ plan.priceLabel }}</p>
           <ul v-if="plan.features.length"><li v-for="feature in plan.features" :key="feature">{{ feature }}</li></ul>
-          <p>{{ number(plan.renewalCredits) }} credits per paid renewal; unused renewal credits expire at period end.</p>
-          <v-btn variant="flat" color="primary" :disabled="disabled || hasSubscription || plan.available !== true" :aria-label="`Choose ${plan.name}`" @click="checkout(plan)">Choose plan</v-btn>
-          <p v-if="plan.available !== true">Not available for checkout yet.</p>
+          <p>{{ t('jskit.payments.account.renewalCredits', { credits: number(plan.renewalCredits), count: plan.renewalCredits }) }}</p>
+          <v-btn variant="flat" color="primary" :disabled="disabled || hasSubscription || plan.available !== true" :aria-label="t('jskit.payments.account.choosePlanNamed', { plan: plan.name })" @click="checkout(plan)">{{ t('jskit.payments.account.choosePlan') }}</v-btn>
+          <p v-if="plan.available !== true">{{ t('jskit.payments.account.notAvailableForCheckout') }}</p>
         </li>
       </ul>
-      <p v-else>No plans are available yet.</p>
-      <section v-if="canReadHistory" aria-label="Billing history" :aria-busy="historyLoading">
+      <p v-else>{{ t('jskit.payments.account.noPlans') }}</p>
+      <section v-if="canReadHistory" :aria-label="t('jskit.payments.account.history.region')" :aria-busy="historyLoading">
         <div class="payment-account__actions">
-          <v-btn variant="tonal" :disabled="historyLoading || loading" @click="loadHistory('transactions')">View invoices and transactions</v-btn>
-          <v-btn variant="tonal" :disabled="historyLoading || loading" @click="loadHistory('subscriptions')">View subscription history</v-btn>
+          <v-btn variant="tonal" :disabled="historyLoading || loading" @click="loadHistory('transactions')">{{ t('jskit.payments.account.history.viewTransactions') }}</v-btn>
+          <v-btn variant="tonal" :disabled="historyLoading || loading" @click="loadHistory('subscriptions')">{{ t('jskit.payments.account.history.viewSubscriptions') }}</v-btn>
         </div>
         <v-skeleton-loader v-if="historyLoading" type="list-item-three-line, list-item-three-line" />
         <div v-else-if="historyError" role="alert">
           <p>{{ historyError }}</p>
-          <v-btn variant="text" @click="emit('retry-history')">Retry billing history</v-btn>
+          <v-btn variant="text" @click="emit('retry-history')">{{ t('jskit.payments.account.history.retry') }}</v-btn>
         </div>
         <template v-else-if="history">
-          <p v-if="history.collection === 'transactions'">Invoices and transactions include unpaid records. Their totals do not confirm payment.</p>
-          <v-list v-if="history.items.length" lines="three" aria-label="Provider billing records">
+          <p v-if="history.collection === 'transactions'">{{ t('jskit.payments.account.history.unpaidNote') }}</p>
+          <v-list v-if="history.items.length" lines="three" :aria-label="t('jskit.payments.account.history.records')">
             <v-list-item v-for="item in history.items" :key="item.id">
-              <v-list-item-title>{{ item.kind === 'invoice' ? 'Invoice' : item.kind === 'transaction' ? 'Transaction' : 'Subscription' }} {{ item.id }}</v-list-item-title>
-              <v-list-item-subtitle>{{ statuses[item.status] ?? item.status }} · {{ date(Date.parse(item.createdAt)) }} (UTC)</v-list-item-subtitle>
-              <p v-if="item.kind !== 'subscription'">Total: {{ item.totalLabel ?? 'Not available yet' }}<span v-if="item.paidLabel"> · Paid: {{ item.paidLabel }}</span></p>
+              <v-list-item-title>{{ historyTitle(item) }}</v-list-item-title>
+              <v-list-item-subtitle>{{ t('jskit.payments.account.history.statusAndDate', { status: statusLabel(item.status), date: date(Date.parse(item.createdAt)) }) }}</v-list-item-subtitle>
+              <p v-if="item.kind !== 'subscription'">{{ historyTotal(item) }}</p>
             </v-list-item>
           </v-list>
-          <p v-else>No billing records found.</p>
-          <v-btn v-if="history.nextCursor" variant="text" @click="loadHistory(history.collection, history.nextCursor)">Next billing page</v-btn>
+          <p v-else>{{ t('jskit.payments.account.history.empty') }}</p>
+          <v-btn v-if="history.nextCursor" variant="text" @click="loadHistory(history.collection, history.nextCursor)">{{ t('jskit.payments.account.history.nextPage') }}</v-btn>
         </template>
       </section>
     </template>
-    <p v-else>Billing details are not available yet.</p>
+    <p v-else>{{ t('jskit.payments.account.unavailable') }}</p>
   </section>
 </template>
 

package/src/client/i18n.js

@@ -0,0 +1,6 @@
+import { registerJskitMessages, useJskitText } from "@jskit-ai/kernel/client/i18n";
+import en from "../../locales/en.json" with { type: "json" };
+
+registerJskitMessages(en);
+
+export { useJskitText };

package/test/i18nCatalog.test.js

@@ -0,0 +1,16 @@
+import assert from "node:assert/strict";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { evaluateI18nCatalogContract } from "../../../tooling/test-support/i18nCatalogContract.mjs";
+
+const TEST_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(TEST_DIRECTORY, "..", "..", "..");
+
+test("payments-web English catalog matches its source", () => {
+  const { problems } = evaluateI18nCatalogContract({
+    repoRoot: REPO_ROOT,
+    packageDir: path.join(REPO_ROOT, "packages", "payments-web")
+  });
+  assert.deepEqual(problems, []);
+});

package/test/paymentAccount.test.js

@@ -14,7 +14,9 @@ test('billing component preserves read state and guards checkout while leaving a
   let app;
   try {
     const modulePath = `${directory}/component.mjs`;
-    await writeFile(modulePath, compiled.content);
+    // The compiled module lives in a temporary directory, so point its catalog import at the package.
+    const i18nModule = new URL('../src/client/i18n.js', import.meta.url).href;
+    await writeFile(modulePath, compiled.content.replace('"../i18n.js"', JSON.stringify(i18nModule)));
     const { default: PaymentAccount } = await import(pathToFileURL(modulePath));
     const node = (type, text = '') => ({ type, text, props: {}, children: [], parent: null });
     const renderer = createRenderer({