@frigear-nu/payments 0.0.0-stage → 0.0.2

package/README.md

@@ -1,3 +1,43 @@
-# Temporary Holding Version
+# @frigear-nu/payments
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+One-time Stripe payments for the frigear ecosystem: Checkout sessions with inline prices, a `payments` table, refunds and
+Nitro lifecycle hooks (`payments:paid`, `payments:failed`, `payments:expired`, `payments:refunded`). Built on
+[`@frigear-nu/stripe`](../stripe); it has no webhook of its own and only reacts to the verified Stripe events that module
+dispatches.
+
+## Quick Setup
+
+Requires `@nuxthub/core` with `hub.kv: true`, `@frigear-nu/users` and `@frigear-nu/stripe`.
+
+```ts
+export default defineNuxtConfig({
+  modules: ['@frigear-nu/users', '@frigear-nu/stripe', '@frigear-nu/payments'],
+})
+```
+
+Generate and commit a migration for the `payments` table in your app (see the repository `AGENTS.md`).
+
+## Usage
+
+```ts
+// In a route handler
+const { payment, url } = await createPayment({
+  userId: user.id,
+  items: [{ name: 'Ticket', amount: 15000, currency: 'DKK' }],
+  reference: { type: 'event_ticket', id: ticketId },
+  successUrl: '/thanks',
+  cancelUrl: '/cancelled',
+}, event)
+
+// Anywhere in Nitro
+nitroApp.hooks.hook('payments:paid', ({ payment }) => { /* ... */ })
+```
+
+Full documentation: `apps/docs/content/4.modules/24.payments.md`.
+
+## Development
+
+```bash
+pnpm --filter @frigear-nu/payments test
+pnpm --filter @frigear-nu/payments lint
+```

package/dist/module.d.mts

@@ -0,0 +1,96 @@
+import * as _nuxt_schema from '@nuxt/schema';
+import Stripe from 'stripe';
+import { H3Event } from 'h3';
+
+type ModuleOptions = {
+    settings?: {
+        /** Minutes a Checkout session stays open before it expires (Stripe allows 30 - 1440). Defaults to `30`. */
+        checkoutExpiresInMinutes?: number;
+    };
+};
+type PaymentsRuntimeConfig = {
+    checkoutExpiresInMinutes: number;
+};
+type PaymentStatus = 'pending' | 'paid' | 'failed' | 'expired' | 'refunded' | 'partially_refunded';
+type PaymentItem = {
+    name: string;
+    description?: string;
+    /** Unit amount in the currency's minor unit (e.g. cents / øre). */
+    amount: number;
+    /** Three letter ISO currency code. */
+    currency: string;
+    quantity?: number;
+};
+type PaymentReference = {
+    /** What the payment is for, e.g. `event_ticket`. Used by consumers to filter lifecycle hooks. */
+    type: string;
+    id: string;
+};
+type PaymentDto = {
+    id: string;
+    userId: number;
+    status: PaymentStatus;
+    amount: number;
+    currency: string;
+    description: string | null;
+    referenceType: string | null;
+    referenceId: string | null;
+    refundedAmount: number;
+    paidAt: string | null;
+    createdAt: string;
+};
+type CreatePaymentInput = {
+    userId: number;
+    items: PaymentItem[];
+    reference?: PaymentReference;
+    /** Absolute URL, or a path on the current origin. */
+    successUrl: string;
+    cancelUrl: string;
+    description?: string;
+    expiresInMinutes?: number;
+    metadata?: Record<string, string>;
+};
+type CreatePaymentResult = {
+    payment: PaymentDto;
+    url: string;
+};
+type PaymentHookContext = {
+    payment: PaymentDto;
+};
+type CheckoutBeforeContext = {
+    event?: H3Event;
+    userId: number;
+    reference?: PaymentReference;
+    /** Mutable: adjust the Checkout session params before they are sent to Stripe. */
+    params: Stripe.Checkout.SessionCreateParams;
+};
+type ResumeResponse = {
+    url: string;
+};
+
+declare module '@nuxt/schema' {
+    interface NuxtConfig {
+        payments?: ModuleOptions;
+    }
+    interface RuntimeConfig {
+        payments: PaymentsRuntimeConfig;
+    }
+}
+declare module 'nitropack' {
+    interface NitroRuntimeHooks {
+        /** Policy hook: throw to deny a checkout, or adjust `ctx.params` before it reaches Stripe. */
+        'payments:checkout:before': (ctx: CheckoutBeforeContext) => void | Promise<void>;
+        /** A payment became `paid` (fired once, from the verified Stripe event). */
+        'payments:paid': (ctx: PaymentHookContext) => void | Promise<void>;
+        /** An asynchronous payment method failed. */
+        'payments:failed': (ctx: PaymentHookContext) => void | Promise<void>;
+        /** The Checkout session expired without payment. */
+        'payments:expired': (ctx: PaymentHookContext) => void | Promise<void>;
+        /** The payment was (partially) refunded; inspect `payment.status` / `payment.refundedAmount`. */
+        'payments:refunded': (ctx: PaymentHookContext) => void | Promise<void>;
+    }
+}
+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 };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "@frigear-nu/payments",
+  "configKey": "payments",
+  "version": "0.0.2",
+  "builder": {
+    "@nuxt/module-builder": "1.0.3",
+    "unbuild": "unknown"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,59 @@
+import { defineNuxtModule, createResolver, addServerHandler, addServerImportsDir, addImports } from '@nuxt/kit';
+import { registerModule, registerLocales, registerDatabaseTable, moduleApiUrl } from '@frigear-nu/module-kit/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 }
+  },
+  moduleDependencies: {
+    "@nuxthub/core": {
+      version: ">=0.10",
+      defaults: { kv: true }
+    },
+    "@frigear-nu/module-kit": { version: ">=0.0.1" },
+    "@frigear-nu/users": { version: ">=0.0.1" },
+    "@frigear-nu/stripe": { version: ">=0.0.1" }
+  },
+  async setup(options, nuxt) {
+    registerModule(MODULE_NAME, nuxt);
+    const resolver = createResolver(import.meta.url);
+    registerLocales(nuxt, resolver.resolve("./runtime/i18n/lang"));
+    nuxt.options.runtimeConfig.payments = {
+      checkoutExpiresInMinutes: options.settings?.checkoutExpiresInMinutes ?? 30
+    };
+    await registerDatabaseTable(nuxt, {
+      name: "payments",
+      resolver,
+      schema: (dialect) => `./runtime/server/db/schema.${dialect}`
+    });
+    registerStripeEventHandler(nuxt, {
+      events: [
+        "checkout.session.completed",
+        "checkout.session.async_payment_succeeded",
+        "checkout.session.async_payment_failed",
+        "checkout.session.expired",
+        "charge.refunded"
+      ],
+      handler: resolver.resolve("./runtime/server/stripe/payment-events")
+    });
+    addServerHandler({
+      route: moduleApiUrl("payments"),
+      method: "get",
+      handler: resolver.resolve("./runtime/server/routes/payments/index.get")
+    });
+    addServerHandler({
+      route: moduleApiUrl("payments", "resume"),
+      method: "post",
+      handler: resolver.resolve("./runtime/server/routes/payments/resume.post")
+    });
+    addServerImportsDir(resolver.resolve("./runtime/server/utils"));
+    addImports([
+      { name: "usePayments", from: resolver.resolve("./runtime/app/composables/usePayments") }
+    ]);
+  }
+});
+
+export { module$1 as default };

package/dist/runtime/app/composables/index.d.ts

@@ -0,0 +1 @@
+export { usePayments } from './usePayments.js';

package/dist/runtime/app/composables/index.js

@@ -0,0 +1 @@
+export { usePayments } from "./usePayments.js";

package/dist/runtime/app/composables/usePayments.d.ts

@@ -0,0 +1,7 @@
+/** The signed-in user's payments, plus a helper to resume an unpaid one. */
+export declare function usePayments(): {
+    payments: any;
+    refresh: any;
+    status: any;
+    resume: (paymentId: string) => Promise<void>;
+};

package/dist/runtime/app/composables/usePayments.js

@@ -0,0 +1,14 @@
+export function usePayments() {
+  const { loggedIn } = useUserSession();
+  const { data, refresh, status } = useFetch("/api/payments", {
+    key: "payments:mine",
+    immediate: loggedIn.value,
+    watch: false,
+    default: () => []
+  });
+  async function resume(paymentId) {
+    const { url } = await $fetch("/api/payments/resume", { method: "POST", body: { paymentId } });
+    await navigateTo(url, { external: true });
+  }
+  return { payments: data, refresh, status, resume };
+}

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

@@ -0,0 +1,13 @@
+{
+  "payments": {
+    "status": {
+      "pending": "Afventer",
+      "paid": "Betalt",
+      "failed": "Fejlet",
+      "expired": "Udløbet",
+      "refunded": "Refunderet",
+      "partially_refunded": "Delvist refunderet"
+    },
+    "defaultDescription": "Betaling"
+  }
+}

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

@@ -0,0 +1,13 @@
+{
+  "payments": {
+    "status": {
+      "pending": "Pending",
+      "paid": "Paid",
+      "failed": "Failed",
+      "expired": "Expired",
+      "refunded": "Refunded",
+      "partially_refunded": "Partially refunded"
+    },
+    "defaultDescription": "Payment"
+  }
+}

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

@@ -0,0 +1,280 @@
+export declare const payments: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "payments";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "id";
+            tableName: "payments";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: undefined;
+        }>;
+        userId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "userId";
+            tableName: "payments";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        status: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "status";
+            tableName: "payments";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: undefined;
+        }>;
+        amount: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "amount";
+            tableName: "payments";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        currency: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "currency";
+            tableName: "payments";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: undefined;
+        }>;
+        description: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "description";
+            tableName: "payments";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: undefined;
+        }>;
+        referenceType: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "referenceType";
+            tableName: "payments";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: undefined;
+        }>;
+        referenceId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "referenceId";
+            tableName: "payments";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: undefined;
+        }>;
+        checkoutSessionId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "checkoutSessionId";
+            tableName: "payments";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: undefined;
+        }>;
+        paymentIntentId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "paymentIntentId";
+            tableName: "payments";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: undefined;
+        }>;
+        refundedAmount: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "refundedAmount";
+            tableName: "payments";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        metadata: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "metadata";
+            tableName: "payments";
+            dataType: "json";
+            columnType: "SQLiteTextJson";
+            data: Record<string, string>;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: Record<string, string>;
+        }>;
+        paidAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "paidAt";
+            tableName: "payments";
+            dataType: "date";
+            columnType: "SQLiteTimestamp";
+            data: Date;
+            driverParam: number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "createdAt";
+            tableName: "payments";
+            dataType: "date";
+            columnType: "SQLiteTimestamp";
+            data: Date;
+            driverParam: number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: true;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        updatedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "updatedAt";
+            tableName: "payments";
+            dataType: "date";
+            columnType: "SQLiteTimestamp";
+            data: Date;
+            driverParam: number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: true;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "sqlite";
+}>;

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

@@ -0,0 +1,26 @@
+import { sqliteTable, text, integer, index } from "drizzle-orm/sqlite-core";
+export const payments = sqliteTable("payments", {
+  /** `pay_` + random id. */
+  id: text().primaryKey(),
+  userId: integer().notNull(),
+  /** `pending | paid | failed | expired | refunded | partially_refunded`. */
+  status: text().notNull().default("pending"),
+  /** Total in the currency's minor unit. */
+  amount: integer().notNull(),
+  currency: text().notNull(),
+  description: text(),
+  /** What the payment is for (e.g. `event_ticket`) and the id of that thing. */
+  referenceType: text(),
+  referenceId: text(),
+  checkoutSessionId: text().notNull().unique(),
+  paymentIntentId: text(),
+  refundedAmount: integer().notNull().default(0),
+  metadata: 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())
+}, (t) => [
+  index("payment_user_idx").on(t.userId),
+  index("payment_reference_idx").on(t.referenceType, t.referenceId),
+  index("payment_intent_idx").on(t.paymentIntentId)
+]);

package/dist/runtime/server/routes/payments/index.get.d.ts

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

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

@@ -0,0 +1,4 @@
+export default defineEventHandler(async (event) => {
+  const { user } = await requireUserSession(event);
+  return listUserPayments(user.id);
+});

package/dist/runtime/server/routes/payments/resume.post.d.ts

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

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

@@ -0,0 +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 { paymentId } = await readValidatedBody(event, bodySchema.parse);
+  return resumePayment(paymentId, user.id, event);
+});

package/dist/runtime/server/stripe/payment-events.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("@frigear-nu/stripe/types").StripeEventHandler;
+export default _default;

package/dist/runtime/server/stripe/payment-events.js

@@ -0,0 +1,59 @@
+import { db, schema } from "@nuxthub/db";
+import { eq } from "drizzle-orm";
+import { defineStripeEventHandler } from "@frigear-nu/stripe/utils";
+import { toPaymentDto } from "../utils/payments.js";
+const hookFor = {
+  paid: "payments:paid",
+  failed: "payments:failed",
+  expired: "payments:expired",
+  refunded: "payments:refunded"
+};
+export default defineStripeEventHandler(async (event) => {
+  const nitro = useNitroApp();
+  async function transition(where, next, extra, allowedFrom, hook) {
+    const [row] = await db.select().from(schema.payments).where(where).limit(1);
+    if (!row) return;
+    if (row.status === next && hook !== "refunded") return;
+    if (!allowedFrom.includes(row.status)) return;
+    const [updated] = await db.update(schema.payments).set({ status: next, ...extra }).where(eq(schema.payments.id, row.id)).returning();
+    if (updated) await nitro.hooks.callHook(hookFor[hook], { payment: toPaymentDto(updated) });
+  }
+  switch (event.type) {
+    case "checkout.session.completed":
+    case "checkout.session.async_payment_succeeded": {
+      const session = event.data.object;
+      if (session.payment_status !== "paid") return;
+      await transition(
+        eq(schema.payments.checkoutSessionId, session.id),
+        "paid",
+        { paidAt: /* @__PURE__ */ new Date(), paymentIntentId: typeof session.payment_intent === "string" ? session.payment_intent : session.payment_intent?.id ?? null },
+        ["pending", "failed", "expired"],
+        "paid"
+      );
+      return;
+    }
+    case "checkout.session.async_payment_failed": {
+      await transition(eq(schema.payments.checkoutSessionId, event.data.object.id), "failed", {}, ["pending"], "failed");
+      return;
+    }
+    case "checkout.session.expired": {
+      await transition(eq(schema.payments.checkoutSessionId, event.data.object.id), "expired", {}, ["pending"], "expired");
+      return;
+    }
+    case "charge.refunded": {
+      const charge = event.data.object;
+      const intent = typeof charge.payment_intent === "string" ? charge.payment_intent : charge.payment_intent?.id;
+      if (!intent) return;
+      const full = charge.amount_refunded >= charge.amount;
+      const [row] = await db.select().from(schema.payments).where(eq(schema.payments.paymentIntentId, intent)).limit(1);
+      if (!row || row.refundedAmount === charge.amount_refunded) return;
+      await transition(
+        eq(schema.payments.paymentIntentId, intent),
+        full ? "refunded" : "partially_refunded",
+        { refundedAmount: charge.amount_refunded },
+        ["paid", "partially_refunded"],
+        "refunded"
+      );
+    }
+  }
+});

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

@@ -0,0 +1,31 @@
+import { schema } from '@nuxthub/db';
+import type { H3Event } from 'h3';
+import type { CreatePaymentInput, CreatePaymentResult, PaymentDto } from '../../../types.js';
+type PaymentRow = typeof schema.payments.$inferSelect;
+export declare function toPaymentDto(row: PaymentRow): PaymentDto;
+/**
+ * Creates a Stripe Checkout session (`mode: 'payment'`, inline `price_data`) and a `pending` payment
+ * row. The row only turns `paid` when Stripe tells us so (see `payments:paid`).
+ *
+ * Pass the request `event` to have the return URLs restricted to the current origin.
+ */
+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[]>;
+/**
+ * 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
+ * that are already paid/refunded.
+ */
+export declare function resumePayment(paymentId: string, userId: number, event?: H3Event): Promise<{
+    url: string;
+}>;
+/**
+ * Refunds a paid payment (fully, or `amount` minor units). The status change is applied by the
+ * `charge.refunded` Stripe event, so the `payments:refunded` hook fires once from one place.
+ */
+export declare function refundPayment(paymentId: string, options?: {
+    amount?: number;
+}): Promise<void>;
+export {};

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

@@ -0,0 +1,150 @@
+import { db, schema } from "@nuxthub/db";
+import { and, desc, eq } from "drizzle-orm";
+import { resolveSameOriginUrl, sumItems } from "../../utils/index.js";
+export function toPaymentDto(row) {
+  return {
+    id: row.id,
+    userId: row.userId,
+    status: row.status,
+    amount: row.amount,
+    currency: row.currency,
+    description: row.description,
+    referenceType: row.referenceType,
+    referenceId: row.referenceId,
+    refundedAmount: row.refundedAmount,
+    paidAt: row.paidAt?.toISOString() ?? null,
+    createdAt: row.createdAt.toISOString()
+  };
+}
+const newPaymentId = () => `pay_${crypto.randomUUID().replaceAll("-", "")}`;
+function safeReturnUrl(input, event, name) {
+  if (!event) 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 expiresAt(minutes) {
+  const clamped = Math.min(Math.max(Math.round(minutes), 30), 1440);
+  return Math.floor(Date.now() / 1e3) + clamped * 60;
+}
+export async function createPayment(input, event) {
+  if (input.items.length === 0) throw createError({ statusCode: 400, statusMessage: "A payment needs at least one item." });
+  const currency = input.items[0].currency.toLowerCase();
+  if (input.items.some((item) => item.currency.toLowerCase() !== currency)) {
+    throw createError({ statusCode: 400, statusMessage: "All items in a payment must share one currency." });
+  }
+  const amount = sumItems(input.items);
+  if (amount <= 0) throw createError({ statusCode: 400, statusMessage: "The payment amount must be greater than zero." });
+  const config = useRuntimeConfig().payments;
+  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,
+    userId: input.userId,
+    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);
+  if (!session.url) throw createError({ statusCode: 502, statusMessage: "Stripe did not return a checkout URL." });
+  try {
+    const [row] = await db.insert(schema.payments).values({
+      id,
+      userId: input.userId,
+      amount,
+      currency,
+      description: input.description ?? null,
+      referenceType: input.reference?.type ?? null,
+      referenceId: input.reference?.id ?? null,
+      checkoutSessionId: session.id,
+      metadata: input.metadata ?? null
+    }).returning();
+    return { payment: toPaymentDto(row), url: session.url };
+  } catch (error) {
+    await stripe.checkout.sessions.expire(session.id).catch(() => void 0);
+    throw error;
+  }
+}
+export async function getPayment(id) {
+  const [row] = await db.select().from(schema.payments).where(eq(schema.payments.id, id)).limit(1);
+  return row ? toPaymentDto(row) : null;
+}
+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));
+  return rows.map(toPaymentDto);
+}
+export async function resumePayment(paymentId, userId, event) {
+  const [row] = await db.select().from(schema.payments).where(and(eq(schema.payments.id, paymentId), eq(schema.payments.userId, userId))).limit(1);
+  if (!row) throw createError({ statusCode: 404, statusMessage: "Payment not found." });
+  if (row.status === "paid" || row.status === "refunded" || row.status === "partially_refunded") {
+    throw createError({ statusCode: 409, statusMessage: "This payment is already paid." });
+  }
+  const stripe = useStripe();
+  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",
+    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 }
+  });
+  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 };
+}
+export async function refundPayment(paymentId, options = {}) {
+  const [row] = await db.select().from(schema.payments).where(eq(schema.payments.id, paymentId)).limit(1);
+  if (!row) throw createError({ statusCode: 404, statusMessage: "Payment not found." });
+  if (!row.paymentIntentId || row.status !== "paid" && row.status !== "partially_refunded") {
+    throw createError({ statusCode: 409, statusMessage: "Only paid payments can be refunded." });
+  }
+  if (options.amount !== void 0 && (options.amount <= 0 || options.amount > row.amount - row.refundedAmount)) {
+    throw createError({ statusCode: 400, statusMessage: "Invalid refund amount." });
+  }
+  await useStripe().refunds.create({
+    payment_intent: row.paymentIntentId,
+    ...options.amount !== void 0 ? { amount: options.amount } : {}
+  });
+}

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

@@ -0,0 +1,6 @@
+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

@@ -0,0 +1,14 @@
+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

@@ -0,0 +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'

package/package.json

@@ -1,6 +1,89 @@
 {
   "name": "@frigear-nu/payments",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.2",
+  "description": "One-time payments (Stripe Checkout, refunds and payment lifecycle hooks) for the frigear ecosystem, built on @frigear-nu/stripe.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/frigear-nu/frigear-nu.git",
+    "directory": "packages/payments"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/module.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs",
+      "default": "./dist/module.mjs"
+    },
+    "./utils": {
+      "types": "./dist/runtime/utils/index.d.ts",
+      "import": "./dist/runtime/utils/index.js",
+      "default": "./dist/runtime/utils/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "workspaces": [
+    "playground"
+  ],
+  "dependencies": {
+    "@frigear-nu/module-kit": "0.1.0",
+    "@frigear-nu/stripe": "0.0.2",
+    "@frigear-nu/users": "1.0.2",
+    "@libsql/client": "^0.18.0",
+    "@nuxt/kit": "^4.6.0",
+    "drizzle-kit": "^0.31.11",
+    "drizzle-orm": "^0.45.3",
+    "h3": "^1.15.11",
+    "stripe": "^23.0.0",
+    "unstorage": "^1.17.5",
+    "zod": "^4.6.5"
+  },
+  "peerDependencies": {
+    "@nuxt/ui": "^4.10.0",
+    "@nuxthub/core": "^0.10.8"
+  },
+  "peerDependenciesMeta": {
+    "@nuxt/ui": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@nuxt/devtools": "^3.4.2",
+    "@nuxt/eslint-config": "^1.17.0",
+    "@nuxt/module-builder": "^1.0.3",
+    "@nuxt/schema": "^4.6.0",
+    "@nuxt/test-utils": "^4.3.2",
+    "@nuxt/ui": "^4.11.0",
+    "@nuxthub/core": "^0.10.8",
+    "@types/node": "latest",
+    "changelogen": "^0.6.2",
+    "eslint": "^10.10.0",
+    "nuxt": "^4.6.0",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.1",
+    "vue-tsc": "^3.3.11"
+  },
+  "scripts": {
+    "postinstall": "nuxt-module-build build --stub && nuxt prepare",
+    "build": "nuxt-module-build build",
+    "dev": "npm run dev:prepare && nuxt dev playground",
+    "dev:build": "nuxt build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt prepare playground",
+    "release": "npm run lint && npm run test && npm run prepack && changelogen --release && npm publish && git push --follow-tags",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
+  },
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  }
 }