wirejs-module-payments-stripe 0.1.0

package/README.md

@@ -0,0 +1,10 @@
+Stripe payments module for `wirejs` apps.
+
+In your backend / api workspace:
+
+```ts
+import { Payments } from `wirejs-module-payments-stripe`;
+
+```
+
+In your front-end, choose an SSR path to 

package/dist/index.d.ts

@@ -0,0 +1,185 @@
+import { Endpoint, Resource, Setting } from 'wirejs-resources';
+import Stripe from 'stripe';
+export type CheckoutMode = 'subscription' | 'payment';
+export type Customer = {
+    id: string;
+};
+export type SubscriptionInterval = "day" | "week" | "month" | "year";
+export type Product = {
+    id: string;
+    name: string;
+    type: 'one_time' | 'recurring';
+    interval?: SubscriptionInterval;
+    currency: 'usd';
+    /**
+     * In cents
+     */
+    unitAmount: number;
+    metadata: Record<string, string>;
+};
+export type Price = {
+    product: string | {
+        id: string;
+    } | undefined;
+    recurring: {
+        interval: SubscriptionInterval;
+    } | null;
+    currency: string;
+    unit_amount: number | null;
+    metadata: Record<string, string>;
+};
+export type OneTimeProduct = Product & {
+    type: 'one_time';
+};
+export type SubscriptionProduct = Product & {
+    type: 'recurring';
+};
+export type LineItem<T extends CheckoutMode> = {
+    product: Product & (T extends 'subscription' ? SubscriptionProduct : OneTimeProduct);
+    quantity: number;
+};
+export type OneTimePurchaseLineItem = LineItem<'payment'>;
+export type SubscriptionLineItem = LineItem<'subscription'>;
+export type Transaction = {
+    /**
+     * Stripe ID.
+     */
+    id: string;
+    customerId: string;
+    type: 'payment' | 'refund';
+    /**
+     * cents, always positive
+     */
+    amount: number;
+    currency: string;
+    /**
+     * only used for refunds
+     */
+    relatedPaymentId?: string;
+    /**
+     * optional for refunds
+     */
+    reason?: string;
+    createdAt: string;
+    items?: Array<{
+        id: string;
+        description: string | null;
+        quantity: number | null;
+        amount: number;
+        productId?: string;
+    }>;
+};
+export type SubscriptionLine = {
+    /**
+     * Stripe Line Item ID
+     */
+    id: string;
+    /**
+     * Stripe Subscription ID
+     */
+    subscriptionId: string;
+    customerId: string;
+    /**
+     * Internal product/plan ID.
+     */
+    productId: string;
+    amount: number;
+    currency: 'usd';
+    interval: SubscriptionInterval;
+    quantity: number;
+    status: Stripe.Subscription['status'] | 'deleted';
+    currentPeriodStart: string;
+    currentPeriodEnd: string;
+    canceledAt?: string;
+    createdAt: string;
+    updatedAt: string;
+    metadata?: Record<string, string>;
+};
+export declare class PaymentService extends Resource {
+    devMode: Setting<{
+        readonly private: false;
+        readonly description: "If \"yes\", skips Stripe checkout and immediately records successful payments.";
+        readonly init: () => string;
+        readonly options: ["yes", "no"];
+    }>;
+    stripeKey: Setting<{
+        readonly private: true;
+        readonly description: "The API key issued by Stripe.";
+    }>;
+    stripeEndpointSecret: Setting<{
+        readonly private: true;
+        readonly description: "The verification secret issued by Stripe for this endpoint.";
+    }>;
+    private prices;
+    private transactions;
+    private subscriptionLines;
+    private customerInternalIdToExternalId;
+    private customerExternalIdToInternalId;
+    webhookEndpoint: Endpoint;
+    _stripe: undefined | Promise<Stripe | undefined>;
+    _endpointSecretData: undefined | Promise<string>;
+    constructor(scope: Resource | string, id: string);
+    /**
+     * Creates a raw Stripe client.
+     *
+     * @returns
+     */
+    getClient(): Promise<Stripe | undefined>;
+    getEndpointSecret(): Promise<string>;
+    private getPrice;
+    private getProductFromPrice;
+    private getStripeCustomer;
+    private getInternalCustomer;
+    private recordInvoicePayment;
+    private recordCheckoutPayment;
+    private recordCustomerSubscriptionLine;
+    private recordCustomerSubscription;
+    private recordLocalModeCheckout;
+    createCheckoutUrl<T extends OneTimePurchaseLineItem | SubscriptionLineItem>({ customer, lineItems, successUrl, cancelUrl }: {
+        customer: Customer;
+        lineItems: T[];
+        successUrl: URL | string;
+        cancelUrl: URL | string;
+    }): Promise<string | null>;
+    cancelSubscriptionLine(id: string): Promise<void>;
+    listPayments(internalCustomerId: string): Promise<{
+        id: string;
+        customerId: string;
+        type: "payment" | "refund";
+        amount: number;
+        currency: string;
+        relatedPaymentId?: string | undefined;
+        reason?: string | undefined;
+        createdAt: string;
+        items?: {
+            id: string;
+            description: string | null;
+            quantity: number | null;
+            amount: number;
+            productId?: string | undefined;
+        }[] | undefined;
+    }[]>;
+    listSubscriptions(internalCustomerId: string): Promise<{
+        id: string;
+        subscriptionId: string;
+        customerId: string;
+        productId: string;
+        amount: number;
+        currency: "usd";
+        interval: SubscriptionInterval;
+        quantity: number;
+        status: Stripe.Subscription["status"] | "deleted";
+        currentPeriodStart: string;
+        currentPeriodEnd: string;
+        canceledAt?: string | undefined;
+        createdAt: string;
+        updatedAt: string;
+        metadata?: {
+            [x: string]: string;
+        } | undefined;
+    }[]>;
+    /**
+     * Produces a handler for incoming webhooks from Stripe.
+     */
+    private handleStripeWebhook;
+}

package/dist/index.js

@@ -0,0 +1,466 @@
+import { DistributedTable, Endpoint, KeyValueStore, PassThruParser, Resource, Setting } from 'wirejs-resources';
+import Stripe from 'stripe';
+function httpNotFound(context, message) {
+    context.responseCode = 404;
+    return message ? `Not Found - ${message}` : 'Not found';
+}
+function sum(values) {
+    let t = 0;
+    for (const v of values)
+        t += v;
+    return t;
+}
+export class PaymentService extends Resource {
+    devMode = new Setting(this, 'dev-mode', {
+        private: false,
+        description: 'If "yes", skips Stripe checkout and immediately records successful payments.',
+        init: () => 'no',
+        options: ['yes', 'no'],
+    });
+    stripeKey = new Setting(this, 'stripe-key', {
+        private: true,
+        description: 'The API key issued by Stripe.'
+    });
+    stripeEndpointSecret = new Setting(this, 'stripe-endpoint-secret', {
+        private: true,
+        description: "The verification secret issued by Stripe for this endpoint."
+    });
+    prices = new Map();
+    transactions = new DistributedTable(this, 'transactions', {
+        parse: (PassThruParser),
+        key: {
+            partition: { field: 'id', type: 'string' },
+        },
+        indexes: [
+            {
+                partition: { field: 'customerId', type: 'string' },
+                sort: { field: 'createdAt', type: 'string' }
+            },
+        ]
+    });
+    subscriptionLines = new DistributedTable(this, 'subscriptions', {
+        parse: (PassThruParser),
+        key: {
+            partition: { field: 'id', type: 'string' }
+        },
+        indexes: [
+            {
+                partition: { field: 'customerId', type: 'string' },
+                sort: { field: 'status', type: 'string' }
+            },
+            {
+                partition: { field: 'subscriptionId', type: 'string' },
+                sort: { field: 'status', type: 'string' }
+            }
+        ]
+    });
+    customerInternalIdToExternalId = new KeyValueStore(this, 'customerInternalIdToExternalId');
+    customerExternalIdToInternalId = new KeyValueStore(this, 'customerExternalIdToInternalId');
+    webhookEndpoint = new Endpoint(this, 'webhook', {
+        handle: async (context) => this.handleStripeWebhook(context),
+        description: "The webhook Stripe needs to inform this software of payment and subscription changes."
+    });
+    _stripe = undefined;
+    _endpointSecretData = undefined;
+    constructor(scope, id) {
+        super(scope, id);
+    }
+    /**
+     * Creates a raw Stripe client.
+     *
+     * @returns
+     */
+    getClient() {
+        this._stripe = this._stripe || new Promise(resolve => {
+            this.stripeKey.read().then(key => {
+                if (!!key) {
+                    resolve(new Stripe(key.trim()));
+                }
+                else {
+                    resolve(undefined);
+                }
+            });
+        });
+        return this._stripe;
+    }
+    getEndpointSecret() {
+        this._endpointSecretData = this._endpointSecretData || new Promise(resolve => {
+            this.stripeEndpointSecret.read().then(v => resolve(v || ''));
+        });
+        return this._endpointSecretData;
+    }
+    getPrice(product) {
+        const interval = (product.type === 'recurring' && product.interval)
+            ? product.interval
+            : 'one_time';
+        const lookupKey = `${product.id}-${product.unitAmount}-${product.currency}-${interval}`;
+        if (!this.prices.has(product)) {
+            this.prices.set(product, new Promise(async (resolve) => {
+                const client = (await this.getClient());
+                const existing = await client.prices.list({
+                    active: true,
+                    lookup_keys: [lookupKey],
+                });
+                const existingPrice = existing.data[0];
+                if (existingPrice)
+                    return resolve(existingPrice);
+                try {
+                    await client.products.retrieve(product.id);
+                }
+                catch (error) {
+                    if (error.code !== 'resource_missing')
+                        throw error;
+                    await client.products.create({
+                        id: product.id,
+                        name: product.name
+                    });
+                }
+                const newPrice = await client.prices.create({
+                    currency: product.currency,
+                    unit_amount: product.unitAmount,
+                    lookup_key: lookupKey,
+                    recurring: (product.type === 'recurring' && product.interval) ? {
+                        interval: product.interval,
+                    } : undefined,
+                    metadata: product.metadata,
+                    product: product.id,
+                });
+                resolve(newPrice);
+            }));
+        }
+        return this.prices.get(product);
+    }
+    getProductFromPrice(price) {
+        let id;
+        let name;
+        if (typeof price.product === 'string') {
+            id = price.product;
+            name = id;
+        }
+        else {
+            id = price.product.id;
+            name = price.product.name;
+        }
+        if (!id)
+            throw new Error("Product ID missing.");
+        return {
+            id,
+            name,
+            type: price.recurring ? 'recurring' : 'one_time',
+            interval: price.recurring ? price.recurring.interval : undefined,
+            currency: price.currency,
+            unitAmount: price.unit_amount,
+            metadata: price.metadata
+        };
+    }
+    async getStripeCustomer(internalId) {
+        const existing = await this.customerInternalIdToExternalId.get(internalId);
+        if (existing)
+            return existing;
+        const client = await this.getClient();
+        const newCustomer = await client?.customers.create();
+        if (!newCustomer)
+            throw new Error("Could not create Stripe customer");
+        await this.customerInternalIdToExternalId.set(internalId, newCustomer.id);
+        await this.customerExternalIdToInternalId.set(newCustomer.id, internalId);
+        return newCustomer.id;
+    }
+    async getInternalCustomer(customer) {
+        const externalId = typeof customer === 'string' ? customer : customer.id;
+        const internalId = await this.customerExternalIdToInternalId.get(externalId);
+        if (!internalId)
+            throw new Error("No internal customer ID found for Stripe ID.");
+        return internalId;
+    }
+    async recordInvoicePayment(invoice) {
+        // Should always be populated, because we always attach customers at checkout.
+        const internalCustomerId = await this.getInternalCustomer(invoice.customer);
+        await this.transactions.save({
+            amount: invoice.amount_paid,
+            createdAt: new Date().toISOString(),
+            currency: invoice.currency,
+            customerId: internalCustomerId,
+            id: invoice.id,
+            type: 'payment',
+            items: invoice.lines.data.map(line => ({
+                id: line.id,
+                description: line.description,
+                quantity: line.quantity,
+                amount: line.amount,
+                productId: line.pricing?.price_details?.product
+            }))
+        });
+    }
+    async recordCheckoutPayment(session, items) {
+        const internalCustomerId = await this.getInternalCustomer(session.customer);
+        await this.transactions.save({
+            amount: session.amount_total,
+            createdAt: new Date().toISOString(),
+            currency: session.currency,
+            customerId: internalCustomerId,
+            id: session.id,
+            type: 'payment',
+            items: items.data.map(line => ({
+                id: line.id,
+                description: line.description,
+                quantity: line.quantity,
+                amount: line.amount_total,
+                productId: typeof line.price?.product === 'string'
+                    ? line.price.product
+                    : line.price?.product.id
+            }))
+        });
+    }
+    async recordCustomerSubscriptionLine(customerId, subscription, lineItem) {
+        const product = this.getProductFromPrice(lineItem.price);
+        const existing = await this.subscriptionLines.get({ id: lineItem.id });
+        await this.subscriptionLines.save({
+            id: lineItem.id,
+            subscriptionId: subscription.id,
+            customerId,
+            status: subscription.status,
+            productId: product.id,
+            amount: lineItem.price.unit_amount,
+            currency: lineItem.price.currency,
+            interval: lineItem.price.recurring?.interval,
+            quantity: lineItem.quantity,
+            currentPeriodStart: new Date(lineItem.current_period_start * 1000).toISOString(),
+            currentPeriodEnd: new Date(lineItem.current_period_end * 1000).toISOString(),
+            createdAt: existing?.createdAt || new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+        });
+    }
+    async recordCustomerSubscription(sub) {
+        const internalCustomerId = await this.getInternalCustomer(sub.customer);
+        const existingSubscriptionLines = await Array.fromAsync(this.subscriptionLines.query({
+            by: 'subscriptionId-status',
+            where: {
+                subscriptionId: { eq: sub.id },
+                status: { ne: 'deleted' }
+            }
+        }));
+        const existingSubLineIds = new Map();
+        for (const li of existingSubscriptionLines) {
+            existingSubLineIds.set(li.id, li);
+        }
+        for (const item of sub.items.data) {
+            await this.recordCustomerSubscriptionLine(internalCustomerId, sub, item);
+            existingSubLineIds.delete(item.id);
+        }
+        // any remaining "existing" lines were absent from the sub event and
+        // must therefore be canceled locally
+        for (const li of existingSubLineIds.values()) {
+            await this.subscriptionLines.save({
+                ...li,
+                status: 'deleted',
+                updatedAt: new Date().toISOString(),
+                canceledAt: new Date().toISOString(),
+            });
+        }
+    }
+    async recordLocalModeCheckout({ customer, lineItems, mode }) {
+        await this.transactions.save({
+            amount: sum(lineItems.map(li => li.product.unitAmount * li.quantity)),
+            createdAt: new Date().toISOString(),
+            currency: 'usd',
+            customerId: customer.id,
+            id: crypto.randomUUID(),
+            type: 'payment',
+            items: lineItems.map(li => ({
+                id: crypto.randomUUID(),
+                description: li.product.name,
+                quantity: li.quantity,
+                amount: li.product.unitAmount * li.quantity,
+                productId: li.product.id
+            }))
+        });
+        if (mode === 'subscription') {
+            const subscriptionId = crypto.randomUUID();
+            for (const li of lineItems) {
+                const now = new Date();
+                let currentPeriodEnd;
+                switch (li.product.interval) {
+                    case 'day':
+                        currentPeriodEnd = new Date(now);
+                        currentPeriodEnd.setDate(now.getDate() + 1);
+                        break;
+                    case 'week':
+                        currentPeriodEnd = new Date(now);
+                        currentPeriodEnd.setDate(now.getDate() + 7);
+                        break;
+                    case 'month':
+                        currentPeriodEnd = new Date(now);
+                        currentPeriodEnd.setMonth(now.getMonth() + 1);
+                        break;
+                    case 'year':
+                        currentPeriodEnd = new Date(now);
+                        currentPeriodEnd.setFullYear(now.getFullYear() + 1);
+                        break;
+                    default:
+                        currentPeriodEnd = new Date(now);
+                }
+                await this.subscriptionLines.save({
+                    id: crypto.randomUUID(),
+                    customerId: customer.id,
+                    createdAt: now.toISOString(),
+                    updatedAt: now.toISOString(),
+                    productId: li.product.id,
+                    amount: li.product.unitAmount,
+                    currency: li.product.currency,
+                    interval: li.product.interval,
+                    quantity: li.quantity,
+                    status: 'active',
+                    subscriptionId: subscriptionId,
+                    currentPeriodStart: now.toISOString(),
+                    currentPeriodEnd: currentPeriodEnd.toISOString()
+                });
+            }
+        }
+    }
+    async createCheckoutUrl({ customer, lineItems, successUrl, cancelUrl }) {
+        if (lineItems.length === 0) {
+            throw new Error("`lineItems` is empty.");
+        }
+        const billingType = lineItems[0].product.type;
+        if (!lineItems.every(li => li.product.type === billingType)) {
+            throw new Error("`lineItems` contains mixed `type` values.");
+        }
+        const mode = billingType === 'one_time' ? 'payment' : 'subscription';
+        if (await this.devMode.read() === 'yes') {
+            await this.recordLocalModeCheckout({ customer, lineItems, mode });
+            return new URL(successUrl).href;
+        }
+        const stripe = await this.getClient();
+        if (!stripe) {
+            throw new Error("Stripe client could not be created. Ensure Stripe settings are populated.");
+        }
+        const lines = [];
+        for (const item of lineItems) {
+            lines.push({
+                price: (await this.getPrice(item.product)).id,
+                quantity: item.quantity,
+                adjustable_quantity: {
+                    enabled: false
+                }
+            });
+        }
+        const stripeCustomerId = await this.getStripeCustomer(customer.id);
+        const session = await stripe.checkout.sessions.create({
+            mode,
+            customer: stripeCustomerId,
+            line_items: lines,
+            allow_promotion_codes: true,
+            success_url: new URL(successUrl).href,
+            cancel_url: new URL(cancelUrl).href
+        });
+        return session.url;
+    }
+    async cancelSubscriptionLine(id) {
+        const existingLine = await this.subscriptionLines.get({ id });
+        if (!existingLine) {
+            throw new Error(`Subscription Line doesn't exist: ${id}.`);
+        }
+        if (await this.devMode.read() === 'yes') {
+            await this.subscriptionLines.save({
+                ...existingLine,
+                status: 'deleted',
+                updatedAt: new Date().toISOString(),
+                canceledAt: new Date().toISOString(),
+            });
+        }
+        const stripe = await this.getClient();
+        if (!stripe) {
+            throw new Error("Stripe client could not be created. Ensure Stripe settings are populated.");
+        }
+        const allSubLines = await Array.fromAsync(this.subscriptionLines.query({
+            by: 'subscriptionId-status',
+            where: {
+                subscriptionId: { eq: existingLine.subscriptionId },
+                status: { ne: 'deleted ' }
+            }
+        }));
+        if (allSubLines.length > 1) {
+            await stripe.subscriptionItems.del(id);
+        }
+        else {
+            await stripe.subscriptions.cancel(existingLine.subscriptionId);
+        }
+    }
+    async listPayments(internalCustomerId) {
+        return Array.fromAsync(this.transactions.query({
+            by: 'customerId-createdAt',
+            where: {
+                customerId: { eq: internalCustomerId }
+            },
+        }));
+    }
+    async listSubscriptions(internalCustomerId) {
+        return Array.fromAsync(this.subscriptionLines.query({
+            by: 'customerId-status',
+            where: {
+                customerId: { eq: internalCustomerId }
+            }
+        }));
+    }
+    /**
+     * Produces a handler for incoming webhooks from Stripe.
+     */
+    async handleStripeWebhook(context) {
+        console.log('Stripe callback event');
+        const stripe = await this.getClient();
+        if (!stripe) {
+            throw new Error("Stripe client is not available.");
+        }
+        const endpointSecret = (await this.getEndpointSecret()).trim();
+        if (!endpointSecret) {
+            throw new Error("No Stripe endpoint secret configured.");
+        }
+        let stripeEvent;
+        const signature = context.requestHeaders['stripe-signature'];
+        try {
+            stripeEvent = stripe.webhooks.constructEvent(context.requestBody, signature, endpointSecret);
+            console.log("Stripe event validated");
+            console.log(stripeEvent);
+        }
+        catch (err) {
+            console.log(`STRIPE FAILURE: Webhook signature verification failed.`, err.message);
+            return httpNotFound(context);
+        }
+        // Handle the event
+        switch (stripeEvent.type) {
+            case "invoice.payment_succeeded": {
+                const invoice = stripeEvent.data.object;
+                await this.recordInvoicePayment(invoice);
+                break;
+            }
+            case "checkout.session.completed": {
+                const session = stripeEvent.data.object;
+                if (session.mode === 'payment') {
+                    const items = await stripe.checkout.sessions.listLineItems(session.id);
+                    await this.recordCheckoutPayment(session, items);
+                }
+                break;
+            }
+            case 'customer.subscription.trial_will_end':
+                // Then define and call a method to handle the subscription trial ending.
+                // handleSubscriptionTrialEnding(subscription);
+                // nothing to do here for now ... we don't offer trials.
+                break;
+            case 'customer.subscription.deleted':
+            case 'customer.subscription.paused':
+            case 'customer.subscription.updated':
+            case 'customer.subscription.created':
+            case 'customer.subscription.resumed': {
+                const sub = stripeEvent.data.object;
+                await this.recordCustomerSubscription(sub);
+                break;
+            }
+            default: {
+                // Unexpected event type
+                console.log(`Unhandled Stripe event type ${stripeEvent.type}.`);
+                return httpNotFound(context, "Unhandled Stripe event type ${stripeEvent.type}.");
+            }
+        }
+        return "ok";
+    }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+	"name": "wirejs-module-payments-stripe",
+	"version": "0.1.0",
+	"description": "Stripe payments module built for wirejs apps.",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"scripts": {
+		"build": "tsc"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/svidgen/create-wirejs-app.git",
+		"directory": "packages/wirejs-module-payments-stripe"
+	},
+	"author": "Jon Wire",
+	"license": "AGPL-3.0-only",
+	"bugs": {
+		"url": "https://github.com/svidgen/create-wirejs-app/issues"
+	},
+	"homepage": "https://github.com/svidgen/create-wirejs-app#readme",
+	"dependencies": {
+		"stripe": "^18.2.1",
+		"wirejs-dom": "^1.0.42",
+		"wirejs-resources": "^0.1.106"
+	},
+	"devDependencies": {
+		"typescript": "^5.7.3"
+	},
+	"files": [
+		"package.json",
+		"README.md",
+		"dist/*"
+	]
+}