paykitjs 0.0.1-alpha.1

package/dist/types/schema.js

@@ -0,0 +1,192 @@
+import * as z from "zod";
+import { createHash } from "node:crypto";
+//#region src/types/schema.ts
+const payKitFeatureSymbol = Symbol.for("paykit.feature");
+const payKitFeatureIncludeSymbol = Symbol.for("paykit.feature_include");
+const payKitPlanSymbol = Symbol.for("paykit.plan");
+const entityIdSchema = z.string().min(1, "Id must not be empty").max(64, "Id must be 64 characters or fewer").regex(/^[a-z0-9_-]+$/, "Id must be lowercase alphanumeric with dashes or underscores");
+const planNameSchema = z.string().min(1, "Plan name must not be empty");
+const planGroupSchema = z.string().min(1, "Plan group must not be empty").max(64);
+const priceSchema = z.object({
+	amount: z.number().positive("Price amount must be positive").max(999999.99, "Price amount must not exceed $999,999.99"),
+	interval: z.enum(["month", "year"])
+});
+const meteredFeatureConfigSchema = z.object({
+	limit: z.number().int().positive("Feature limit must be a positive integer"),
+	reset: z.enum([
+		"day",
+		"week",
+		"month",
+		"year"
+	])
+});
+function formatValidationError(entityType, id, messages) {
+	return /* @__PURE__ */ new Error(`Invalid ${entityType} "${id}":\n${messages.map((message) => `  - ${message}`).join("\n")}`);
+}
+function deriveNameFromId(id) {
+	return id.split(/[-_]/u).filter(Boolean).map((part) => part[0]?.toUpperCase() + part.slice(1)).join(" ");
+}
+function defineHiddenBrand(target, symbol) {
+	Object.defineProperty(target, symbol, {
+		configurable: false,
+		enumerable: false,
+		value: true,
+		writable: false
+	});
+}
+function isPayKitFeatureInclude(value) {
+	return value !== null && typeof value === "object" && value[payKitFeatureIncludeSymbol] === true;
+}
+function isPayKitPlan(value) {
+	return value !== null && typeof value === "object" && value[payKitPlanSymbol] === true;
+}
+function feature(definition) {
+	const parsedId = entityIdSchema.safeParse(definition.id);
+	if (!parsedId.success) throw formatValidationError("feature", typeof definition.id === "string" ? definition.id : "<unknown>", parsedId.error.issues.map((issue) => issue.message));
+	const featureType = definition.type === "boolean" || definition.type === "metered" ? definition.type : null;
+	if (!featureType) throw formatValidationError("feature", parsedId.data, ["Feature type must be boolean or metered"]);
+	const featureDefinition = Object.freeze({
+		id: parsedId.data,
+		type: featureType
+	});
+	const featureFactory = ((config) => {
+		if (featureDefinition.type === "boolean") {
+			if (config !== void 0) throw formatValidationError("feature include", featureDefinition.id, [`Boolean feature "${featureDefinition.id}" does not accept config`]);
+			const include = {
+				config: void 0,
+				feature: featureDefinition
+			};
+			defineHiddenBrand(include, payKitFeatureIncludeSymbol);
+			return Object.freeze(include);
+		}
+		const parsedConfig = meteredFeatureConfigSchema.safeParse(config);
+		if (!parsedConfig.success) throw formatValidationError("feature include", featureDefinition.id, parsedConfig.error.issues.map((issue) => issue.message));
+		const include = {
+			config: parsedConfig.data,
+			feature: featureDefinition
+		};
+		defineHiddenBrand(include, payKitFeatureIncludeSymbol);
+		return Object.freeze(include);
+	});
+	Object.defineProperties(featureFactory, {
+		id: {
+			configurable: false,
+			enumerable: true,
+			value: featureDefinition.id,
+			writable: false
+		},
+		type: {
+			configurable: false,
+			enumerable: true,
+			value: featureDefinition.type,
+			writable: false
+		}
+	});
+	defineHiddenBrand(featureFactory, payKitFeatureSymbol);
+	return featureFactory;
+}
+function plan(config) {
+	const result = z.object({
+		default: z.boolean().optional(),
+		group: planGroupSchema.optional(),
+		id: entityIdSchema,
+		includes: z.array(z.unknown()).optional(),
+		name: planNameSchema.optional(),
+		price: priceSchema.optional()
+	}).safeParse(config);
+	if (!result.success) throw formatValidationError("plan", typeof config?.id === "string" ? config.id : "<unknown>", result.error.issues.map((issue) => issue.message));
+	const parsed = result.data;
+	const includes = parsed.includes ?? [];
+	if (includes.find((include) => !isPayKitFeatureInclude(include))) throw formatValidationError("plan", parsed.id, ["Includes must contain values returned by feature(...)"]);
+	if (parsed.default && !parsed.group) throw formatValidationError("plan", parsed.id, ["Default plans must define a \"group\""]);
+	const builtPlan = {
+		...parsed,
+		includes
+	};
+	defineHiddenBrand(builtPlan, payKitPlanSymbol);
+	return Object.freeze(builtPlan);
+}
+function computePlanHash(plan) {
+	const payload = JSON.stringify({
+		group: plan.group,
+		isDefault: plan.isDefault,
+		priceAmount: plan.priceAmount,
+		priceInterval: plan.priceInterval,
+		features: plan.includes.map((f) => ({
+			id: f.id,
+			limit: f.limit,
+			resetInterval: f.resetInterval,
+			config: f.config
+		}))
+	});
+	return createHash("sha256").update(payload).digest("hex").slice(0, 16);
+}
+function normalizeSchema(plans) {
+	if (!plans) return {
+		features: [],
+		plans: [],
+		planMap: /* @__PURE__ */ new Map()
+	};
+	const exportedPlans = Array.isArray(plans) ? plans.filter(isPayKitPlan) : Object.values(plans).filter(isPayKitPlan);
+	const features = /* @__PURE__ */ new Map();
+	const defaultPlansByGroup = /* @__PURE__ */ new Map();
+	const plansById = /* @__PURE__ */ new Map();
+	for (const exportedPlan of exportedPlans) {
+		if (plansById.has(exportedPlan.id)) throw new Error(`Duplicate plan id "${exportedPlan.id}" found in plans exports.`);
+		const group = exportedPlan.group ?? "";
+		const isDefault = exportedPlan.default ?? false;
+		if (isDefault) {
+			const existingDefaultPlanId = defaultPlansByGroup.get(group);
+			if (existingDefaultPlanId) throw new Error(`Group "${group}" has multiple default plans: "${existingDefaultPlanId}" and "${exportedPlan.id}".`);
+			defaultPlansByGroup.set(group, exportedPlan.id);
+		}
+		const sortedIncludes = [...exportedPlan.includes.map((include) => {
+			const existingFeature = features.get(include.feature.id);
+			if (existingFeature && existingFeature.type !== include.feature.type) throw new Error(`Feature "${include.feature.id}" is declared with conflicting types: "${existingFeature.type}" and "${include.feature.type}".`);
+			features.set(include.feature.id, {
+				id: include.feature.id,
+				type: include.feature.type
+			});
+			if (include.feature.type === "metered") {
+				const config = include.config;
+				if (!config) throw new Error(`Metered feature "${include.feature.id}" requires config.`);
+				return {
+					config,
+					id: include.feature.id,
+					limit: config.limit,
+					resetInterval: config.reset,
+					type: include.feature.type
+				};
+			}
+			return {
+				config: null,
+				id: include.feature.id,
+				limit: null,
+				resetInterval: null,
+				type: include.feature.type
+			};
+		})].sort((left, right) => left.id.localeCompare(right.id));
+		const planData = {
+			group,
+			id: exportedPlan.id,
+			includes: sortedIncludes,
+			isDefault,
+			name: exportedPlan.name ?? deriveNameFromId(exportedPlan.id),
+			priceAmount: exportedPlan.price ? Math.round(exportedPlan.price.amount * 100) : null,
+			priceInterval: exportedPlan.price?.interval ?? null,
+			trialDays: null
+		};
+		plansById.set(exportedPlan.id, {
+			...planData,
+			hash: computePlanHash(planData)
+		});
+	}
+	const sortedPlans = [...plansById.values()].sort((left, right) => left.id.localeCompare(right.id));
+	return {
+		features: [...features.values()].sort((left, right) => left.id.localeCompare(right.id)),
+		plans: sortedPlans,
+		planMap: plansById
+	};
+}
+//#endregion
+export { feature, normalizeSchema, plan };

package/dist/utilities/dependencies/check-dependencies.js

@@ -0,0 +1,16 @@
+import { getDependencies } from "./get-dependencies.js";
+import picocolors from "picocolors";
+//#region src/utilities/dependencies/check-dependencies.ts
+async function checkDependencies(dependencies, targetVersionDependency) {
+	const { resolved } = await getDependencies(process.cwd(), dependencies);
+	const foundVersions = {};
+	for (const [pkg, { version }] of resolved) if (!(version in foundVersions)) foundVersions[version] = pkg;
+	if (Object.keys(foundVersions).length <= 1) return;
+	const targetVersion = resolved.get(targetVersionDependency)?.version;
+	const mismatched = targetVersion ? Object.entries(foundVersions).filter(([version]) => version !== targetVersion) : Object.entries(foundVersions);
+	const lines = mismatched.map(([version, pkg]) => targetVersion ? `  ${pkg}@${version} (expected ${targetVersion})` : `  ${pkg}@${version}`);
+	const fixPkgs = mismatched.map(([_, pkg]) => targetVersion ? `${pkg}@${targetVersion}` : pkg).join(" ");
+	console.warn(`${picocolors.red("[paykit]")} Mismatching dependency versions:\n${lines.join("\n")}\n  Run ${picocolors.bold(`pnpm install ${fixPkgs}`)} to fix.`);
+}
+//#endregion
+export { checkDependencies };

package/dist/utilities/dependencies/get-dependencies.js

@@ -0,0 +1,68 @@
+import { createRequire } from "node:module";
+import fs from "node:fs";
+import path from "node:path";
+//#region src/utilities/dependencies/get-dependencies.ts
+function resolveFrom(fromDirectory, moduleId) {
+	try {
+		fromDirectory = fs.realpathSync(fromDirectory);
+	} catch {
+		fromDirectory = path.resolve(fromDirectory);
+	}
+	const fromFile = path.join(fromDirectory, "noop.js");
+	const Module = createRequire(import.meta.url)("module");
+	try {
+		return Module._resolveFilename(moduleId, {
+			id: fromFile,
+			filename: fromFile,
+			paths: Module._nodeModulePaths(fromDirectory)
+		});
+	} catch {
+		return;
+	}
+}
+function findPackageJson(startDir) {
+	const { root } = path.parse(startDir);
+	let dir = startDir;
+	while (dir !== root) {
+		const candidate = path.join(dir, "package.json");
+		try {
+			fs.accessSync(candidate);
+			return candidate;
+		} catch {
+			dir = path.dirname(dir);
+		}
+	}
+	return null;
+}
+async function getDependencies(baseDir, packages) {
+	const resolved = /* @__PURE__ */ new Map();
+	const missing = [];
+	await Promise.all(packages.map(async (pkg) => {
+		try {
+			const pkgEntryPath = resolveFrom(baseDir, pkg);
+			if (!pkgEntryPath) {
+				missing.push(pkg);
+				return;
+			}
+			const realPath = fs.realpathSync(pkgEntryPath);
+			const packageJsonPath = findPackageJson(path.dirname(realPath));
+			if (!packageJsonPath) {
+				missing.push(pkg);
+				return;
+			}
+			const packageJson = JSON.parse(await fs.promises.readFile(packageJsonPath, "utf-8"));
+			resolved.set(pkg, {
+				path: packageJsonPath,
+				version: packageJson.version
+			});
+		} catch {
+			missing.push(pkg);
+		}
+	}));
+	return {
+		missing,
+		resolved
+	};
+}
+//#endregion
+export { getDependencies };

package/dist/utilities/dependencies/index.js

@@ -0,0 +1,8 @@
+import { checkDependencies } from "./check-dependencies.js";
+import { PAYKIT_PACKAGE_LIST } from "./paykit-package-list.js";
+//#region src/utilities/dependencies/index.ts
+function checkPayKitDependencies() {
+	return checkDependencies([...PAYKIT_PACKAGE_LIST], "paykitjs");
+}
+//#endregion
+export { checkPayKitDependencies };

package/dist/utilities/dependencies/paykit-package-list.js

@@ -0,0 +1,8 @@
+//#region src/utilities/dependencies/paykit-package-list.ts
+const PAYKIT_PACKAGE_LIST = [
+	"paykitjs",
+	"@paykitjs/stripe",
+	"@paykitjs/dash"
+];
+//#endregion
+export { PAYKIT_PACKAGE_LIST };

package/dist/webhook/webhook.api.js

@@ -0,0 +1,29 @@
+import { PAYKIT_ERROR_CODES, PayKitError } from "../core/errors.js";
+import { definePayKitMethod } from "../api/define-route.js";
+import { handleWebhook } from "./webhook.service.js";
+//#region src/webhook/webhook.api.ts
+function headersToRecord(headers) {
+	const result = {};
+	headers.forEach((value, key) => {
+		result[key] = value;
+	});
+	return result;
+}
+/** Applies an incoming provider webhook payload. */
+const receiveWebhook = definePayKitMethod({ route: {
+	disableBody: true,
+	method: "POST",
+	path: "/webhook/:providerId",
+	requireHeaders: true,
+	requireRequest: true,
+	resolveInput: async (ctx) => ({
+		body: await ctx.request.text(),
+		headers: headersToRecord(ctx.headers ?? new Headers())
+	})
+} }, async (ctx) => {
+	const providerId = ctx.params.providerId;
+	if (providerId && providerId !== ctx.paykit.provider.id) throw PayKitError.from("BAD_REQUEST", PAYKIT_ERROR_CODES.PROVIDER_WEBHOOK_INVALID, "Webhook provider does not match this PayKit instance");
+	return handleWebhook(ctx.paykit, ctx.input);
+});
+//#endregion
+export { receiveWebhook };

package/dist/webhook/webhook.service.js

@@ -0,0 +1,143 @@
+import { webhookEvent } from "../database/schema.js";
+import { generateId } from "../core/utils.js";
+import { applyInvoiceWebhookAction } from "../invoice/invoice.service.js";
+import { applyPaymentMethodWebhookAction } from "../payment-method/payment-method.service.js";
+import { applySubscriptionWebhookAction, handleSubscribeCheckoutCompleted, prepareSubscribeCheckoutCompleted } from "../subscription/subscription.service.js";
+import { applyCustomerWebhookAction, emitCustomerUpdated } from "../customer/customer.service.js";
+import { getTraceId } from "../core/logger.js";
+import { applyPaymentWebhookAction } from "../payment/payment.service.js";
+import { and, eq, sql } from "drizzle-orm";
+//#region src/webhook/webhook.service.ts
+async function beginWebhookEvent(ctx, input) {
+	try {
+		await ctx.database.insert(webhookEvent).values({
+			error: null,
+			id: generateId("evt"),
+			payload: input.payload,
+			processedAt: null,
+			providerEventId: input.providerEventId,
+			providerId: ctx.provider.id,
+			receivedAt: /* @__PURE__ */ new Date(),
+			status: "processing",
+			traceId: getTraceId(),
+			type: input.type
+		});
+		return true;
+	} catch (error) {
+		if ((error.code ?? error.cause?.code) !== "23505") throw error;
+		return (await ctx.database.update(webhookEvent).set({
+			error: null,
+			processedAt: null,
+			status: "processing"
+		}).where(and(eq(webhookEvent.providerId, ctx.provider.id), eq(webhookEvent.providerEventId, input.providerEventId), sql`(${webhookEvent.status} = 'failed' OR (${webhookEvent.status} = 'processing' AND ${webhookEvent.receivedAt} < now() - interval '5 minutes'))`)).returning({ id: webhookEvent.id })).length > 0;
+	}
+}
+async function finishWebhookEvent(ctx, input) {
+	await ctx.database.update(webhookEvent).set({
+		error: input.error ?? null,
+		processedAt: /* @__PURE__ */ new Date(),
+		status: input.status
+	}).where(and(eq(webhookEvent.providerId, ctx.provider.id), eq(webhookEvent.providerEventId, input.providerEventId)));
+}
+function getProviderEventId(event, index, parentEventId) {
+	const providerEventId = event.payload.providerEventId;
+	if (typeof providerEventId === "string" && providerEventId.length > 0) return providerEventId;
+	return `${parentEventId ?? "unknown"}:${event.name}:${index}`;
+}
+function getParentProviderEventId(events) {
+	for (const event of events) {
+		const payload = event.payload;
+		if (typeof payload.providerEventId === "string" && payload.providerEventId.length > 0) return payload.providerEventId;
+	}
+	return null;
+}
+async function applyAction(ctx, action) {
+	switch (action.type) {
+		case "customer.upsert":
+		case "customer.delete": return applyCustomerWebhookAction(ctx.database, action);
+		case "payment_method.upsert":
+		case "payment_method.delete": return applyPaymentMethodWebhookAction(ctx, action);
+		case "payment.upsert": return applyPaymentWebhookAction(ctx, action);
+		case "subscription.upsert":
+		case "subscription.delete": return applySubscriptionWebhookAction(ctx, action);
+		case "invoice.upsert": return applyInvoiceWebhookAction(ctx, action);
+	}
+}
+async function processWebhookEvent(ctx, event, providerEventId, startTime) {
+	if (!await beginWebhookEvent(ctx, {
+		payload: event.payload,
+		providerEventId,
+		type: event.name
+	})) {
+		ctx.logger.info({
+			event: event.name,
+			providerEventId
+		}, "webhook skipped (duplicate)");
+		return;
+	}
+	try {
+		const checkoutCompletion = event.name === "checkout.completed" ? await prepareSubscribeCheckoutCompleted(ctx, event) : null;
+		const customerIds = await ctx.database.transaction(async (tx) => {
+			const txCtx = {
+				...ctx,
+				database: tx
+			};
+			const ids = /* @__PURE__ */ new Set();
+			if (checkoutCompletion) {
+				const customerId = await handleSubscribeCheckoutCompleted(txCtx, checkoutCompletion);
+				if (customerId) ids.add(customerId);
+			}
+			for (const action of event.actions ?? []) {
+				ctx.logger.info({ actionType: action.type }, "applying action");
+				const customerId = await applyAction(txCtx, action);
+				if (customerId) ids.add(customerId);
+			}
+			return ids;
+		});
+		for (const customerId of customerIds) await emitCustomerUpdated(ctx, customerId);
+		const duration = Date.now() - startTime;
+		ctx.logger.info({
+			event: event.name,
+			duration
+		}, "webhook processed");
+		await finishWebhookEvent(ctx, {
+			providerEventId,
+			status: "processed"
+		});
+	} catch (error) {
+		const duration = Date.now() - startTime;
+		const errorDetail = error instanceof Error ? error.stack ?? error.message : String(error);
+		ctx.logger.error({
+			event: event.name,
+			duration,
+			err: error
+		}, "webhook failed");
+		await finishWebhookEvent(ctx, {
+			error: errorDetail,
+			providerEventId,
+			status: "failed"
+		});
+		throw error;
+	}
+}
+async function handleWebhook(ctx, input) {
+	return ctx.logger.trace.run("wh", async () => {
+		const startTime = Date.now();
+		const events = await ctx.stripe.handleWebhook({
+			body: input.body,
+			headers: input.headers
+		});
+		const parentEventId = getParentProviderEventId(events);
+		for (const [index, event] of events.entries()) {
+			const providerEventId = getProviderEventId(event, index, parentEventId);
+			ctx.logger.info({
+				event: event.name,
+				providerEventId
+			}, "webhook received");
+			await processWebhookEvent(ctx, event, providerEventId, startTime);
+		}
+		return { received: true };
+	});
+}
+//#endregion
+export { handleWebhook };

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "paykitjs",
+  "version": "0.0.1-alpha.1",
+  "description": "TypeScript-first payments orchestration framework for modern SaaS",
+  "keywords": [
+    "creem",
+    "orchestration",
+    "paddle",
+    "payments",
+    "paypal",
+    "polar",
+    "stripe",
+    "subscriptions",
+    "typescript"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/getpaykit/paykit.git"
+  },
+  "bin": {
+    "paykitjs": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./handlers/next": {
+      "types": "./dist/handlers/next.d.ts",
+      "default": "./dist/handlers/next.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
+    },
+    "./database": {
+      "types": "./dist/database/schema.d.ts",
+      "default": "./dist/database/schema.js"
+    }
+  },
+  "dependencies": {
+    "@better-fetch/fetch": "^1.1.21",
+    "@clack/prompts": "^1.1.0",
+    "better-call": "^2.0.2",
+    "commander": "^12.1.0",
+    "dotenv": "^17.3.1",
+    "drizzle-orm": "^0.45.1",
+    "jiti": "^2.6.1",
+    "pg": "^8.20.0",
+    "picocolors": "^1.1.1",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.1.3",
+    "posthog-node": "^5.28.8",
+    "stripe": "^19.1.0",
+    "typescript": "^5.9.2",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/pg": "^8.18.0",
+    "drizzle-kit": "^0.31.5",
+    "tsdown": "^0.21.1",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsdown --config tsdown.config.ts",
+    "typecheck": "tsc --build",
+    "db:generate": "drizzle-kit generate --config src/database/drizzle.config.ts"
+  }
+}