@frigear-nu/payments 0.0.6 → 0.0.8

package/README.md

@@ -33,7 +33,7 @@ const { payment, url } = await createPayment({
 nitroApp.hooks.hook('payments:paid', ({ payment }) => { /* ... */ })
 ```
 
-Full documentation: `apps/docs/content/4.modules/24.payments.md`.
+Full documentation: `apps/docs/content/4.modules/13.payments.md`.
 
 ## Development
 

package/dist/module.d.mts

@@ -6,6 +6,7 @@ type ModuleOptions = {
     settings?: {
         /** Minutes a Checkout session stays open before it expires (Stripe allows 30 - 1440). Defaults to `30`. */
         checkoutExpiresInMinutes?: number;
+        mcp?: boolean;
     };
 };
 type PaymentsRuntimeConfig = {
@@ -54,6 +55,23 @@ type CreatePaymentResult = {
     payment: PaymentDto;
     url: string;
 };
+/** An invoice to store as a payment, see `recordInvoicePayment`. */
+type InvoicePaymentInput = {
+    userId: number;
+    invoiceId: string;
+    status: 'paid' | 'failed' | 'expired';
+    /** Total in the currency's minor unit. */
+    amount: number;
+    currency: string;
+    description: string | null;
+    /** Defaults to `subscription`. */
+    referenceType?: string;
+    /** What the invoice is for, e.g. the Stripe subscription id. */
+    referenceId: string | null;
+    paymentIntentId: string | null;
+    paidAt: Date | null;
+    createdAt?: Date;
+};
 type PaymentHookContext = {
     payment: PaymentDto;
 };
@@ -93,4 +111,4 @@ declare module 'nitropack' {
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 
 export { _default as default };
-export type { CheckoutBeforeContext, CreatePaymentInput, CreatePaymentResult, ModuleOptions, PaymentDto, PaymentHookContext, PaymentItem, PaymentReference, PaymentStatus, PaymentsRuntimeConfig, ResumeResponse };
+export type { CheckoutBeforeContext, CreatePaymentInput, CreatePaymentResult, InvoicePaymentInput, ModuleOptions, PaymentDto, PaymentHookContext, PaymentItem, PaymentReference, PaymentStatus, PaymentsRuntimeConfig, ResumeResponse };

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "@frigear-nu/payments",
   "configKey": "payments",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "unknown"

package/dist/module.mjs

@@ -1,12 +1,15 @@
-import { defineNuxtModule, createResolver, addServerHandler, addServerImportsDir, addImports } from '@nuxt/kit';
-import { registerModule, registerLocales, registerDatabaseTable, moduleApiUrl } from '@frigear-nu/module-kit/utils';
+import { defineNuxtModule, createResolver, addServerHandler, addServerImportsDir, addServerPlugin, addImports } from '@nuxt/kit';
+import { registerModule, registerTailwindSource, registerLocales, registerDatabaseTable, moduleApiUrl } from '@frigear-nu/module-kit/utils';
+import { addAuthScope } from '@frigear-nu/auth/utils';
+import { extendUsersAdmin } from '@frigear-nu/users/utils';
+import { addMcpDefinitions } from '@frigear-nu/mcp/utils';
 import { registerStripeEventHandler } from '@frigear-nu/stripe/utils';
 
 const MODULE_NAME = "@frigear-nu/payments";
 const module$1 = defineNuxtModule({
   meta: { name: MODULE_NAME, configKey: "payments" },
   defaults: {
-    settings: { checkoutExpiresInMinutes: 30 }
+    settings: { checkoutExpiresInMinutes: 30, mcp: false }
   },
   moduleDependencies: {
     "@nuxthub/core": {
@@ -14,12 +17,23 @@ const module$1 = defineNuxtModule({
       defaults: { kv: true }
     },
     "@frigear-nu/module-kit": { version: ">=0.0.1" },
+    "@frigear-nu/auth": { version: ">=0.0.1" },
     "@frigear-nu/users": { version: ">=0.0.1" },
-    "@frigear-nu/stripe": { version: ">=0.0.1" }
+    "@frigear-nu/stripe": { version: ">=0.0.1" },
+    "@frigear-nu/mcp": { version: ">=0.0.1" },
+    "@frigear-nu/widget": { version: ">=0.0.0", optional: true },
+    // The admin user tab and card are built from its components, so they are only added with it.
+    "@frigear-nu/admin": { version: ">=0.0.0", optional: true }
   },
   async setup(options, nuxt) {
     registerModule(MODULE_NAME, nuxt);
+    addAuthScope(
+      nuxt,
+      { name: "payments:read", description: "Read your payments" },
+      { name: "payments:write", description: "Resume your payments" }
+    );
     const resolver = createResolver(import.meta.url);
+    registerTailwindSource(nuxt, resolver.resolve("./runtime/app"));
     registerLocales(nuxt, resolver.resolve("./runtime/i18n/lang"));
     nuxt.options.runtimeConfig.payments = {
       checkoutExpiresInMinutes: options.settings?.checkoutExpiresInMinutes ?? 30
@@ -49,7 +63,26 @@ const module$1 = defineNuxtModule({
       method: "post",
       handler: resolver.resolve("./runtime/server/routes/payments/resume.post")
     });
+    await extendUsersAdmin(nuxt, {
+      routes: [{ method: "get", path: "payments", handler: resolver.resolve("./runtime/server/routes/admin/user-payments.get") }],
+      tab: {
+        id: "payments",
+        component: resolver.resolve("./runtime/app/tabs/Payments.vue"),
+        order: 20,
+        label: "Payments",
+        labelKey: "payments.admin.tab",
+        icon: "i-lucide-credit-card"
+      },
+      widget: {
+        id: "payments-last",
+        component: resolver.resolve("./runtime/app/widgets/AdminLastPayment.vue"),
+        order: 20,
+        span: 2
+      }
+    });
     addServerImportsDir(resolver.resolve("./runtime/server/utils"));
+    addServerPlugin(resolver.resolve("./runtime/server/plugins/invoice-payments"));
+    if (options.settings?.mcp === true) addMcpDefinitions(nuxt, resolver.resolve("./runtime/server/mcp"));
     addImports([
       { name: "usePayments", from: resolver.resolve("./runtime/app/composables/usePayments") }
     ]);

package/dist/runtime/app/tabs/Payments.d.vue.ts

@@ -0,0 +1,8 @@
+type __VLS_Props = {
+    user: {
+        id: number;
+    };
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/app/tabs/Payments.vue

@@ -0,0 +1,74 @@
+<script setup>
+import { formatMoney as formatMinorAmount } from "@frigear-nu/ui/money";
+defineOptions({ name: "UsersAdminPayments" });
+const props = defineProps({
+  user: { type: Object, required: true }
+});
+const t = useModuleT("payments.admin");
+const status = useModuleT("payments.status");
+const { data: payments, status: fetchStatus } = useLazyFetch(
+  () => `/api/admin/users/${props.user.id}/payments`,
+  { key: () => `admin-payments-${props.user.id}` }
+);
+const statusColors = {
+  paid: "success",
+  pending: "warning",
+  failed: "error",
+  expired: "neutral",
+  refunded: "neutral",
+  partially_refunded: "warning"
+};
+const statusLabel = (value) => status(value, value);
+const columns = computed(() => [
+  { accessorKey: "createdAt", header: t("date", "Date") },
+  { accessorKey: "description", header: t("description", "Description") },
+  { accessorKey: "amount", header: t("amount", "Amount") },
+  { accessorKey: "status", header: t("statusColumn", "Status") },
+  { accessorKey: "refundedAmount", header: t("refunded", "Refunded") },
+  { accessorKey: "referenceType", header: t("reference", "Reference") }
+]);
+const date = (value) => value ? new Date(value).toLocaleString() : "\u2013";
+</script>
+
+<template>
+  <AdminSection
+    :title="t('title', 'Payments')"
+  >
+    <template #flush>
+      <UTable
+        :data="payments ?? []"
+        :columns="columns"
+        :loading="fetchStatus === 'pending'"
+      >
+        <template #createdAt-cell="{ row }">
+          <span class="whitespace-nowrap">{{ date(row.original.paidAt ?? row.original.createdAt) }}</span>
+        </template>
+        <template #description-cell="{ row }">
+          {{ row.original.description ?? t("defaultDescription", "Payment") }}
+        </template>
+        <template #amount-cell="{ row }">
+          <span class="whitespace-nowrap">{{ formatMinorAmount(row.original.amount, row.original.currency) }}</span>
+        </template>
+        <template #status-cell="{ row }">
+          <UBadge
+            variant="subtle"
+            :color="statusColors[row.original.status] ?? 'neutral'"
+            :label="statusLabel(row.original.status)"
+          />
+        </template>
+        <template #refundedAmount-cell="{ row }">
+          <span class="whitespace-nowrap">{{ row.original.refundedAmount ? formatMinorAmount(row.original.refundedAmount, row.original.currency) : "\u2013" }}</span>
+        </template>
+        <template #referenceType-cell="{ row }">
+          <span class="text-muted">{{ row.original.referenceType ? `${row.original.referenceType} ${row.original.referenceId ?? ""}`.trim() : "\u2013" }}</span>
+        </template>
+        <template #empty>
+          <AdminEmpty
+            icon="i-lucide-credit-card"
+            :title="t('empty', 'No payments yet.')"
+          />
+        </template>
+      </UTable>
+    </template>
+  </AdminSection>
+</template>

package/dist/runtime/app/tabs/Payments.vue.d.ts

@@ -0,0 +1,8 @@
+type __VLS_Props = {
+    user: {
+        id: number;
+    };
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/app/widgets/AdminLastPayment.d.vue.ts

@@ -0,0 +1,8 @@
+type __VLS_Props = {
+    user: {
+        id: number;
+    };
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/app/widgets/AdminLastPayment.vue

@@ -0,0 +1,33 @@
+<script setup>
+import { formatMoney as formatMinorAmount } from "@frigear-nu/ui/money";
+defineOptions({ name: "UsersAdminLastPayment" });
+const props = defineProps({
+  user: { type: Object, required: true }
+});
+const t = useModuleT("payments.admin");
+const status = useModuleT("payments.status");
+const { data: payments, status: fetchStatus } = useLazyFetch(
+  () => `/api/admin/users/${props.user.id}/payments`,
+  { key: () => `admin-last-payment-${props.user.id}`, query: { limit: 1 } }
+);
+const last = computed(() => payments.value?.[0]);
+const date = (value) => value ? new Date(value).toLocaleDateString() : "\u2013";
+</script>
+
+<template>
+  <AdminStatCard
+    :label="t('lastPayment', 'Last payment')"
+    :empty="t('empty', 'No payments yet.')"
+    :loading="fetchStatus === 'pending' && !payments"
+  >
+    <template v-if="last">
+      <span class="text-highlighted font-medium">{{ formatMinorAmount(last.amount, last.currency) }}</span>
+      <UBadge
+        variant="subtle"
+        :color="last.status === 'paid' ? 'success' : 'neutral'"
+        :label="status(last.status, last.status)"
+      />
+      <span class="text-muted">{{ date(last.paidAt ?? last.createdAt) }}</span>
+    </template>
+  </AdminStatCard>
+</template>

package/dist/runtime/app/widgets/AdminLastPayment.vue.d.ts

@@ -0,0 +1,8 @@
+type __VLS_Props = {
+    user: {
+        id: number;
+    };
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/i18n/lang/da.json

@@ -8,6 +8,19 @@
       "refunded": "Refunderet",
       "partially_refunded": "Delvist refunderet"
     },
-    "defaultDescription": "Betaling"
+    "defaultDescription": "Betaling",
+    "admin": {
+      "tab": "Betalinger",
+      "title": "Betalinger",
+      "lastPayment": "Seneste betaling",
+      "empty": "Ingen betalinger endnu.",
+      "date": "Dato",
+      "description": "Beskrivelse",
+      "amount": "Beløb",
+      "statusColumn": "Status",
+      "refunded": "Refunderet",
+      "reference": "Reference",
+      "defaultDescription": "Betaling"
+    }
   }
 }

package/dist/runtime/i18n/lang/en.json

@@ -8,6 +8,19 @@
       "refunded": "Refunded",
       "partially_refunded": "Partially refunded"
     },
-    "defaultDescription": "Payment"
+    "defaultDescription": "Payment",
+    "admin": {
+      "tab": "Payments",
+      "title": "Payments",
+      "lastPayment": "Last payment",
+      "empty": "No payments yet.",
+      "date": "Date",
+      "description": "Description",
+      "amount": "Amount",
+      "statusColumn": "Status",
+      "refunded": "Refunded",
+      "reference": "Reference",
+      "defaultDescription": "Payment"
+    }
   }
 }

package/dist/runtime/server/db/schema.sqlite.d.ts

@@ -1,3 +1,4 @@
+import type { PaymentItem } from '../../../types.js';
 export declare const payments: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
     name: "payments";
     schema: undefined;
@@ -157,7 +158,26 @@ export declare const payments: import("drizzle-orm/sqlite-core").SQLiteTableWith
             columnType: "SQLiteText";
             data: string;
             driverParam: string;
-            notNull: true;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: undefined;
+        }>;
+        invoiceId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "invoiceId";
+            tableName: "payments";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
             hasDefault: false;
             isPrimaryKey: false;
             isAutoincrement: false;
@@ -224,6 +244,25 @@ export declare const payments: import("drizzle-orm/sqlite-core").SQLiteTableWith
         }, {}, {
             $type: Record<string, string>;
         }>;
+        items: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "items";
+            tableName: "payments";
+            dataType: "json";
+            columnType: "SQLiteTextJson";
+            data: PaymentItem[];
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: PaymentItem[];
+        }>;
         paidAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
             name: "paidAt";
             tableName: "payments";

package/dist/runtime/server/db/schema.sqlite.js

@@ -12,10 +12,15 @@ export const payments = sqliteTable("payments", {
   /** What the payment is for (e.g. `event_ticket`) and the id of that thing. */
   referenceType: text(),
   referenceId: text(),
-  checkoutSessionId: text().notNull().unique(),
+  /** `null` for payments recorded from a Stripe invoice (e.g. a membership renewal), which have no Checkout session. */
+  checkoutSessionId: text().unique(),
+  /** Stripe invoice id for payments recorded from an invoice (see `recordInvoicePayment`). */
+  invoiceId: text().unique(),
   paymentIntentId: text(),
   refundedAmount: integer().notNull().default(0),
   metadata: text({ mode: "json" }).$type(),
+  /** The line items the session was created from, so an expired session can be rebuilt. `null` for rows created before this column existed. */
+  items: text({ mode: "json" }).$type(),
   paidAt: integer({ mode: "timestamp" }),
   createdAt: integer({ mode: "timestamp" }).notNull().$defaultFn(() => /* @__PURE__ */ new Date()),
   updatedAt: integer({ mode: "timestamp" }).notNull().$defaultFn(() => /* @__PURE__ */ new Date()).$onUpdateFn(() => /* @__PURE__ */ new Date())

package/dist/runtime/server/mcp/tools/my-payments.d.ts

@@ -0,0 +1,2 @@
+declare const _default: any;
+export default _default;

package/dist/runtime/server/mcp/tools/my-payments.js

@@ -0,0 +1,8 @@
+import { z } from "zod";
+export default defineScopedMcpTool({
+  description: "List your own payments, newest first: tickets, memberships and other charges with amount, status, refunds and what each was for.",
+  scopes: ["payments:read"],
+  annotations: { readOnlyHint: true },
+  inputSchema: { limit: z.number().int().min(1).max(100).optional().describe("How many payments to return (default 50).") },
+  handler: async ({ limit }, { user }) => ({ payments: await listUserPayments(user.id, { limit: limit ?? 50 }) })
+});

package/dist/runtime/server/plugins/invoice-payments.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("nitropack/types").NitroAppPlugin;
+export default _default;

package/dist/runtime/server/plugins/invoice-payments.js

@@ -0,0 +1,7 @@
+import { defineNitroPlugin } from "nitropack/runtime";
+export default defineNitroPlugin((nitroApp) => {
+  const hooks = nitroApp.hooks;
+  hooks.hook("subscriptions:invoice", async ({ invoice }) => {
+    await recordInvoicePayment(invoice);
+  });
+});

package/dist/runtime/server/routes/admin/user-payments.get.d.ts

@@ -0,0 +1,2 @@
+declare const _default: any;
+export default _default;

package/dist/runtime/server/routes/admin/user-payments.get.js

@@ -0,0 +1,5 @@
+export default defineEventHandler(async (event) => {
+  const { target } = await loadUsersAdminTarget(event, "view");
+  const limit = Number(getQuery(event).limit);
+  return listUserPayments(target.id, { limit: Number.isInteger(limit) && limit > 0 ? Math.min(limit, 500) : 100 });
+});

package/dist/runtime/server/routes/payments/index.get.js

@@ -1,4 +1,4 @@
 export default defineEventHandler(async (event) => {
-  const { user } = await requireUserSession(event);
+  const user = await requireUser(event, { scopes: ["payments:read"] });
   return listUserPayments(user.id);
 });

package/dist/runtime/server/routes/payments/resume.post.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 const bodySchema = z.object({ paymentId: z.string().min(1) });
 export default defineEventHandler(async (event) => {
-  const { user } = await requireUserSession(event);
+  const user = await requireUser(event, { scopes: ["payments:write"] });
   const { paymentId } = await readValidatedBody(event, bodySchema.parse);
   return resumePayment(paymentId, user.id, event);
 });

package/dist/runtime/server/utils/payments.d.ts

@@ -1,6 +1,6 @@
 import { schema } from '@nuxthub/db';
 import type { H3Event } from 'h3';
-import type { CreatePaymentInput, CreatePaymentResult, PaymentDto } from '../../../types.js';
+import type { CreatePaymentInput, InvoicePaymentInput, CreatePaymentResult, PaymentDto } from '../../../types.js';
 type PaymentRow = typeof schema.payments.$inferSelect;
 export declare function toPaymentDto(row: PaymentRow): PaymentDto;
 /**
@@ -12,10 +12,14 @@ export declare function toPaymentDto(row: PaymentRow): PaymentDto;
 export declare function createPayment(input: CreatePaymentInput, event?: H3Event): Promise<CreatePaymentResult>;
 export declare function getPayment(id: string): Promise<PaymentDto | null>;
 export declare function getPaymentByReference(type: string, id: string): Promise<PaymentDto | null>;
-export declare function listUserPayments(userId: number): Promise<PaymentDto[]>;
+/** A user's payments, newest first; `limit` caps how many are returned. */
+export declare function listUserPayments(userId: number, options?: {
+    limit?: number;
+}): Promise<PaymentDto[]>;
 /**
  * Returns a checkout URL for a still-unpaid payment: the original session when it is open, otherwise
- * a fresh session for the same amount (the payment row follows the new session). Throws for payments
+ * a fresh session built from the stored items (the payment row follows the new session). The
+ * `payments:checkout:before` hook and return URL validation run again, as in `createPayment`. Throws for payments
  * that are already paid/refunded.
  */
 export declare function resumePayment(paymentId: string, userId: number, event?: H3Event): Promise<{
@@ -28,4 +32,12 @@ export declare function resumePayment(paymentId: string, userId: number, event?:
 export declare function refundPayment(paymentId: string, options?: {
     amount?: number;
 }): Promise<void>;
+/**
+ * Stores (or updates) the payment for a Stripe invoice, keyed by the invoice id, so recurring charges such as
+ * membership renewals show up next to one-time payments. Idempotent: a redelivered event changes nothing and a
+ * late `failed`/`expired` never overwrites a payment that is already paid or refunded. Fires the matching
+ * `payments:*` hook only when the status actually changed. Refunds arrive through the `charge.refunded` handler,
+ * which finds the row by `paymentIntentId`.
+ */
+export declare function recordInvoicePayment(input: InvoicePaymentInput): Promise<PaymentDto>;
 export {};

package/dist/runtime/server/utils/payments.js

@@ -1,6 +1,7 @@
 import { db, schema } from "@nuxthub/db";
-import { and, desc, eq } from "drizzle-orm";
-import { resolveSameOriginUrl, sumItems } from "../../utils/index.js";
+import { and, desc, eq, sql } from "drizzle-orm";
+import { resolveSameOriginUrl } from "@frigear-nu/stripe/utils";
+import { sumItems } from "../../utils/index.js";
 export function toPaymentDto(row) {
   return {
     id: row.id,
@@ -18,11 +19,46 @@ export function toPaymentDto(row) {
 }
 const newPaymentId = () => `pay_${crypto.randomUUID().replaceAll("-", "")}`;
 function safeReturnUrl(input, event, name) {
-  if (!event) return input;
+  if (!event) {
+    const absolute = URL.canParse(input) && ["http:", "https:"].includes(new URL(input).protocol);
+    if (!absolute) throw createError({ statusCode: 400, statusMessage: `${name} must be an absolute http(s) URL.` });
+    return input;
+  }
   const resolved = resolveSameOriginUrl(input, getRequestURL(event).origin);
   if (!resolved) throw createError({ statusCode: 400, statusMessage: `${name} must be a relative path or an URL on the same origin.` });
   return resolved;
 }
+function toLineItems(items, currency) {
+  return items.map((item) => ({
+    quantity: item.quantity ?? 1,
+    price_data: {
+      currency,
+      unit_amount: item.amount,
+      product_data: { name: item.name, ...item.description ? { description: item.description } : {} }
+    }
+  }));
+}
+async function buildCheckoutParams(source) {
+  const metadata = { ...source.metadata, paymentId: source.paymentId, userId: String(source.userId) };
+  const context = {
+    event: source.event,
+    userId: source.userId,
+    reference: source.reference,
+    params: {
+      mode: "payment",
+      customer: source.customer,
+      client_reference_id: String(source.userId),
+      line_items: toLineItems(source.items, source.currency),
+      success_url: safeReturnUrl(source.successUrl, source.event, "successUrl"),
+      cancel_url: safeReturnUrl(source.cancelUrl, source.event, "cancelUrl"),
+      expires_at: expiresAt(source.expiresInMinutes),
+      metadata,
+      payment_intent_data: { metadata }
+    }
+  };
+  await useNitroApp().hooks.callHook("payments:checkout:before", context);
+  return context.params;
+}
 function expiresAt(minutes) {
   const clamped = Math.min(Math.max(Math.round(minutes), 30), 1440);
   return Math.floor(Date.now() / 1e3) + clamped * 60;
@@ -39,32 +75,20 @@ export async function createPayment(input, event) {
   const stripe = useStripe();
   const customer = await ensureStripeCustomer(input.userId);
   const id = newPaymentId();
-  const metadata = { ...input.metadata, paymentId: id, userId: String(input.userId) };
-  const context = {
-    event,
+  const params = await buildCheckoutParams({
+    paymentId: id,
     userId: input.userId,
+    customer,
+    currency,
+    items: input.items,
     reference: input.reference,
-    params: {
-      mode: "payment",
-      customer,
-      client_reference_id: String(input.userId),
-      line_items: input.items.map((item) => ({
-        quantity: item.quantity ?? 1,
-        price_data: {
-          currency,
-          unit_amount: item.amount,
-          product_data: { name: item.name, ...item.description ? { description: item.description } : {} }
-        }
-      })),
-      success_url: safeReturnUrl(input.successUrl, event, "successUrl"),
-      cancel_url: safeReturnUrl(input.cancelUrl, event, "cancelUrl"),
-      expires_at: expiresAt(input.expiresInMinutes ?? config.checkoutExpiresInMinutes),
-      metadata,
-      payment_intent_data: { metadata }
-    }
-  };
-  await useNitroApp().hooks.callHook("payments:checkout:before", context);
-  const session = await stripe.checkout.sessions.create(context.params);
+    successUrl: input.successUrl,
+    cancelUrl: input.cancelUrl,
+    expiresInMinutes: input.expiresInMinutes ?? config.checkoutExpiresInMinutes,
+    metadata: input.metadata,
+    event
+  });
+  const session = await stripe.checkout.sessions.create(params);
   if (!session.url) throw createError({ statusCode: 502, statusMessage: "Stripe did not return a checkout URL." });
   try {
     const [row] = await db.insert(schema.payments).values({
@@ -76,7 +100,8 @@ export async function createPayment(input, event) {
       referenceType: input.reference?.type ?? null,
       referenceId: input.reference?.id ?? null,
       checkoutSessionId: session.id,
-      metadata: input.metadata ?? null
+      metadata: input.metadata ?? null,
+      items: input.items
     }).returning();
     return { payment: toPaymentDto(row), url: session.url };
   } catch (error) {
@@ -92,8 +117,9 @@ export async function getPaymentByReference(type, id) {
   const [row] = await db.select().from(schema.payments).where(and(eq(schema.payments.referenceType, type), eq(schema.payments.referenceId, id))).orderBy(desc(schema.payments.createdAt)).limit(1);
   return row ? toPaymentDto(row) : null;
 }
-export async function listUserPayments(userId) {
-  const rows = await db.select().from(schema.payments).where(eq(schema.payments.userId, userId)).orderBy(desc(schema.payments.createdAt));
+export async function listUserPayments(userId, options = {}) {
+  const query = db.select().from(schema.payments).where(eq(schema.payments.userId, userId)).orderBy(desc(sql`coalesce(${schema.payments.paidAt}, ${schema.payments.createdAt})`));
+  const rows = await (options.limit ? query.limit(options.limit) : query);
   return rows.map(toPaymentDto);
 }
 export async function resumePayment(paymentId, userId, event) {
@@ -103,33 +129,30 @@ export async function resumePayment(paymentId, userId, event) {
     throw createError({ statusCode: 409, statusMessage: "This payment is already paid." });
   }
   const stripe = useStripe();
+  if (!row.checkoutSessionId) throw createError({ statusCode: 409, statusMessage: "This payment cannot be resumed." });
   const session = await stripe.checkout.sessions.retrieve(row.checkoutSessionId);
   if (session.status === "open" && session.url) return { url: session.url };
   if (session.status === "complete") throw createError({ statusCode: 409, statusMessage: "This payment is already paid." });
-  const customer = await ensureStripeCustomer(userId);
-  const metadata = { ...row.metadata, paymentId: row.id, userId: String(userId) };
   const origin = event ? getRequestURL(event).origin : void 0;
   const successUrl = session.success_url ?? origin;
   const cancelUrl = session.cancel_url ?? origin;
   if (!successUrl || !cancelUrl) throw createError({ statusCode: 409, statusMessage: "Cannot resume this payment." });
-  const next = await stripe.checkout.sessions.create({
-    mode: "payment",
+  const items = row.items?.length ? row.items : [{ name: row.description ?? "Payment", amount: row.amount, currency: row.currency }];
+  const customer = await ensureStripeCustomer(userId);
+  const params = await buildCheckoutParams({
+    paymentId: row.id,
+    userId,
     customer,
-    client_reference_id: String(userId),
-    line_items: [{
-      quantity: 1,
-      price_data: {
-        currency: row.currency,
-        unit_amount: row.amount,
-        product_data: { name: row.description ?? "Payment" }
-      }
-    }],
-    success_url: successUrl,
-    cancel_url: cancelUrl,
-    expires_at: expiresAt(useRuntimeConfig().payments.checkoutExpiresInMinutes),
-    metadata,
-    payment_intent_data: { metadata }
+    currency: row.currency,
+    items,
+    reference: row.referenceType && row.referenceId ? { type: row.referenceType, id: row.referenceId } : void 0,
+    successUrl,
+    cancelUrl,
+    expiresInMinutes: useRuntimeConfig().payments.checkoutExpiresInMinutes,
+    metadata: row.metadata,
+    event
   });
+  const next = await stripe.checkout.sessions.create(params);
   if (!next.url) throw createError({ statusCode: 502, statusMessage: "Stripe did not return a checkout URL." });
   await db.update(schema.payments).set({ checkoutSessionId: next.id, status: "pending" }).where(eq(schema.payments.id, row.id));
   return { url: next.url };
@@ -148,3 +171,33 @@ export async function refundPayment(paymentId, options = {}) {
     ...options.amount !== void 0 ? { amount: options.amount } : {}
   });
 }
+const hookForInvoice = { paid: "payments:paid", failed: "payments:failed", expired: "payments:expired" };
+export async function recordInvoicePayment(input) {
+  const nitro = useNitroApp();
+  const [existing] = await db.select().from(schema.payments).where(eq(schema.payments.invoiceId, input.invoiceId)).limit(1);
+  if (existing) {
+    const settled = ["paid", "refunded", "partially_refunded"].includes(existing.status);
+    if (settled || existing.status === input.status) return toPaymentDto(existing);
+  }
+  const values = {
+    userId: input.userId,
+    status: input.status,
+    amount: input.amount,
+    currency: input.currency,
+    description: input.description,
+    referenceType: input.referenceType ?? "subscription",
+    referenceId: input.referenceId,
+    invoiceId: input.invoiceId,
+    paymentIntentId: input.paymentIntentId,
+    paidAt: input.status === "paid" ? input.paidAt ?? /* @__PURE__ */ new Date() : null
+  };
+  const [row] = existing ? await db.update(schema.payments).set(values).where(eq(schema.payments.id, existing.id)).returning() : await db.insert(schema.payments).values({ id: newPaymentId(), ...values, ...input.createdAt ? { createdAt: input.createdAt } : {} }).onConflictDoNothing({ target: schema.payments.invoiceId }).returning();
+  if (!row) {
+    const [current] = await db.select().from(schema.payments).where(eq(schema.payments.invoiceId, input.invoiceId)).limit(1);
+    if (!current) throw createError({ statusCode: 500, statusMessage: "Could not record the invoice payment." });
+    return toPaymentDto(current);
+  }
+  const dto = toPaymentDto(row);
+  if (input.status in hookForInvoice) await nitro.hooks.callHook(hookForInvoice[input.status], { payment: dto });
+  return dto;
+}

package/dist/runtime/utils/index.d.ts

@@ -2,5 +2,3 @@ import type { PaymentItem } from '../../types.js';
 export type { CheckoutBeforeContext, CreatePaymentInput, CreatePaymentResult, ModuleOptions, PaymentDto, PaymentHookContext, PaymentItem, PaymentReference, PaymentStatus, } from '../../types.js';
 /** Total of a list of items in minor units. */
 export declare function sumItems(items: PaymentItem[]): number;
-/** Resolves a relative path against `origin`, and only accepts absolute URLs on the same origin. */
-export declare function resolveSameOriginUrl(input: string, origin: string): string | null;

package/dist/runtime/utils/index.js

@@ -1,14 +1,3 @@
 export function sumItems(items) {
   return items.reduce((total, item) => total + item.amount * (item.quantity ?? 1), 0);
 }
-export function resolveSameOriginUrl(input, origin) {
-  if (input.startsWith("/")) {
-    if (input.startsWith("//") || input.startsWith("/\\")) return null;
-    return `${origin}${input}`;
-  }
-  try {
-    return new URL(input).origin === new URL(origin).origin ? input : null;
-  } catch {
-    return null;
-  }
-}

package/dist/types.d.mts

@@ -1,3 +1,3 @@
 export { default } from './module.mjs'
 
-export { type CheckoutBeforeContext, type CreatePaymentInput, type CreatePaymentResult, type ModuleOptions, type PaymentDto, type PaymentHookContext, type PaymentItem, type PaymentReference, type PaymentStatus, type PaymentsRuntimeConfig, type ResumeResponse } from './module.mjs'
+export { type CheckoutBeforeContext, type CreatePaymentInput, type CreatePaymentResult, type InvoicePaymentInput, type ModuleOptions, type PaymentDto, type PaymentHookContext, type PaymentItem, type PaymentReference, type PaymentStatus, type PaymentsRuntimeConfig, type ResumeResponse } from './module.mjs'

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@frigear-nu/payments",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "One-time payments (Stripe Checkout, refunds and payment lifecycle hooks) for the frigear ecosystem, built on @frigear-nu/stripe.",
+  "homepage": "https://docs.frigear.dev/modules/payments",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/frigear-nu/frigear-nu.git",
@@ -29,9 +30,12 @@
     "playground"
   ],
   "dependencies": {
-    "@frigear-nu/module-kit": "0.1.5",
-    "@frigear-nu/stripe": "0.0.6",
-    "@frigear-nu/users": "1.0.7",
+    "@frigear-nu/auth": "0.0.3",
+    "@frigear-nu/mcp": "0.0.3",
+    "@frigear-nu/module-kit": "0.1.7",
+    "@frigear-nu/stripe": "0.0.8",
+    "@frigear-nu/ui": "0.0.7",
+    "@frigear-nu/users": "1.0.9",
     "@libsql/client": "^0.18.0",
     "@nuxt/kit": "^4.6.0",
     "drizzle-kit": "^0.31.11",
@@ -42,15 +46,20 @@
     "zod": "^4.6.5"
   },
   "peerDependencies": {
+    "@frigear-nu/widget": "0.0.2",
     "@nuxt/ui": "^4.10.0",
     "@nuxthub/core": "^0.10.8"
   },
   "peerDependenciesMeta": {
+    "@frigear-nu/widget": {
+      "optional": true
+    },
     "@nuxt/ui": {
       "optional": true
     }
   },
   "devDependencies": {
+    "@frigear-nu/widget": "0.0.2",
     "@nuxt/devtools": "^3.4.2",
     "@nuxt/eslint-config": "^1.17.0",
     "@nuxt/module-builder": "^1.0.3",