nomkit 0.0.0

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emmanuel Jonah Ajike
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/_virtual/_rolldown/runtime.js

@@ -0,0 +1,27 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+//#endregion
+export { __exportAll, __reExport };

package/dist/adapters/index.d.ts

@@ -0,0 +1,15 @@
+import { Pool } from "pg";
+import { PGlite } from "@electric-sql/pglite";
+
+//#region lib/adapters/index.d.ts
+type AdapterConfig = {
+  provider: "pg";
+  db: Pool;
+} | {
+  provider: "pglite";
+  db: PGlite;
+};
+type DatabaseConfig = string | Pool | AdapterConfig;
+declare function drizzleAdapter(args: AdapterConfig): AdapterConfig;
+//#endregion
+export { AdapterConfig, DatabaseConfig, drizzleAdapter };

package/dist/adapters/index.js

@@ -0,0 +1,6 @@
+//#region lib/adapters/index.ts
+function drizzleAdapter(args) {
+	return args;
+}
+//#endregion
+export { drizzleAdapter };

package/dist/cli/commands/push.d.ts

@@ -0,0 +1,6 @@
+import { Command } from "commander";
+
+//#region cli/commands/push.d.ts
+declare const pushCommand: Command;
+//#endregion
+export { pushCommand };

package/dist/cli/commands/push.js

@@ -0,0 +1,143 @@
+import { closeConnection, getDrizzle, hasPendingMigrations } from "../../core/pg_db/index.js";
+import { createCollection, diffCollection, hashCollection, queryLatestCollection } from "../lib/collection_sync.js";
+import { getNomKitConfig } from "../lib/config_loader.js";
+import { dbMigrate } from "../lib/migrations.js";
+import { z as z$1 } from "zod";
+import { access, constants } from "node:fs/promises";
+import path from "node:path";
+import { Command } from "commander";
+import ora from "ora";
+//#region cli/commands/push.ts
+const PushOptionsSchema = z$1.object({
+	preview: z$1.boolean().optional().default(false),
+	cwd: z$1.string(),
+	config: z$1.string(),
+	removeStale: z$1.boolean().optional().default(false)
+});
+const pushCommand = new Command("push").description("Push the current collection").option("-p, --preview", "Preview without making changes", false).option("--cwd <path>", "Working directory", process.cwd()).option("--config <path>", "Custom Nomkit config path").option("--remove-stale", "Removes collections that are no longer defined in config").action(async (rawOptions) => {
+	const startedAt = performance.now();
+	const schema = PushOptionsSchema.safeParse(rawOptions);
+	if (!schema.success) {
+		console.error(z$1.prettifyError(schema.error));
+		process.exit(1);
+	}
+	const options = schema.data;
+	const cwd = path.resolve(options.cwd);
+	if (options.preview) console.log("  Preview mode — no changes will be written\n");
+	const spinner = ora({ color: "cyan" });
+	const configPath = await findNomKitConfig(cwd, options.config);
+	if (!configPath) {
+		spinner.fail("No Nomkit config found. Add a `nomkit.ts` file or pass `--config <path>`.");
+		process.exit(1);
+	}
+	const config = await getNomKitConfig({
+		cwd,
+		configPath
+	});
+	try {
+		const db = getDrizzle(config.options.database);
+		spinner.start("Checking for pending migrations…");
+		if (await hasPendingMigrations(db)) {
+			spinner.text = "Applying database migrations…";
+			await dbMigrate(db);
+			spinner.succeed("Database migrations applied");
+		} else spinner.succeed("Database is up to date");
+		const collection = config.options.products;
+		const localCollection = hashCollection(collection);
+		const productIds = [];
+		const allFeatureIds = [];
+		collection.forEach((p) => {
+			productIds.push(p.id);
+			for (const feature of p.includes ?? []) allFeatureIds.push(feature.id);
+		});
+		spinner.start("Fetching remote collection…");
+		const [dbCollection] = await Promise.all([queryLatestCollection({
+			db,
+			productIds
+		})]);
+		spinner.succeed("Remote collection fetched");
+		spinner.start(options.preview ? "Previewing changes…" : "Pushing changes…");
+		if (!dbCollection || dbCollection.length === 0) {
+			const result = await createCollection({
+				db,
+				localCollection,
+				preview: options.preview
+			});
+			spinner.succeed(options.preview ? "Preview complete (no changes written)" : `Created ${result.actions.length} plan${result.actions.length === 1 ? "" : "s"}`);
+			console.log();
+			for (const action of result.actions) {
+				const features = action.featureCount === 1 ? "1 feature" : action.featureCount === 0 ? "no features" : `${action.featureCount} features`;
+				console.log(`  ✦ Created  ${action.productId}  v${action.version}  (${features})`);
+			}
+		} else {
+			const result = await diffCollection({
+				db,
+				localCollection,
+				dbCollection,
+				preview: options.preview
+			});
+			const created = result.actions.filter((a) => a.type === "created").length;
+			const updated = result.actions.filter((a) => a.type === "updated").length;
+			const skipped = result.actions.filter((a) => a.type === "skipped").length;
+			const summary = [
+				created && `${created} created`,
+				updated && `${updated} updated`,
+				skipped && `${skipped} skipped`
+			].filter(Boolean).join("  ·  ");
+			spinner.succeed(options.preview ? `Preview complete — ${summary}` : `Push complete — ${summary}`);
+			if (result.actions.length > 0) {
+				console.log();
+				for (const action of result.actions) {
+					if (action.type === "created") console.log(`  ✦ Created ${action.productId} v${action.version}`);
+					if (action.type === "updated") console.log(`  ↑ Updated ${action.productId} v${action.previousVersion} → v${action.version}`);
+					if (action.type === "skipped") console.log(`  — Skipped ${action.productId} (no changes)`);
+				}
+			}
+		}
+		const end = performance.now();
+		const elapsed = Math.ceil(end - startedAt);
+		console.log(`\n  Done in ${elapsed}ms\n`);
+	} catch (err) {
+		spinner.fail(err instanceof Error ? err.message : "Unexpected error");
+		console.error(err);
+		process.exit(1);
+	} finally {
+		await closeConnection(config.options.database);
+	}
+});
+async function fileExists(path) {
+	try {
+		await access(path, constants.F_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+async function findNomKitConfig(cwd, config = "") {
+	const CONFIG_FILENAMES = [
+		"nomkit.ts",
+		"nomkit.tsx",
+		"nomkit.js",
+		"nomkit.jsx",
+		"nomkit/index.ts",
+		"nomkit/index.tsx",
+		"nomkit/index.js",
+		"nomkit/index.jsx",
+		...[config]
+	];
+	const POSSIBLE_CONFIG_PATHS = [
+		"",
+		"nomkit",
+		"lib",
+		"src",
+		"src/lib",
+		"app"
+	].flatMap((dir) => CONFIG_FILENAMES.map((file) => dir === "" ? file : path.join(dir, file)));
+	for (const relativePath of POSSIBLE_CONFIG_PATHS) {
+		const absolutePath = path.join(cwd, relativePath);
+		if (await fileExists(absolutePath)) return absolutePath;
+	}
+	return null;
+}
+//#endregion
+export { pushCommand };

package/dist/cli/index.d.ts

@@ -0,0 +1,4 @@
+//#region cli/index.d.ts
+declare function getVersion(): string;
+//#endregion
+export { getVersion };

package/dist/cli/index.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { pushCommand } from "./commands/push.js";
+import { version } from "../package.js";
+import { Command } from "commander";
+//#region cli/index.ts
+function getVersion() {
+	return version;
+}
+const program = new Command();
+program.name("nomkit").description("Nomkit is an embedded subscription billing framework that lets developers define products, pricing, and feature entitlements in code, while using payment providers like Nomba for payment processing and automatically syncing billing data to the database.").version(getVersion(), "-v, --version", "display version number");
+program.addCommand(pushCommand);
+try {
+	program.parse();
+} catch (error) {
+	console.error(error);
+}
+//#endregion
+export { getVersion };

package/dist/cli/lib/collection_sync.d.ts

@@ -0,0 +1,107 @@
+import { NomkitDB } from "../../core/pg_db/index.js";
+import { FeatureOpts, MeteredOpts, NomKitOptions, Plan } from "../../index.js";
+
+//#region cli/lib/collection_sync.d.ts
+type Feature = FeatureOpts & MeteredOpts;
+type Hashed<T> = T & {
+  hash: string;
+};
+type LocalFeature = Hashed<Feature> & {
+  _planId: string;
+};
+type LocalProduct = Hashed<Omit<Plan, "includes">> & {
+  features: LocalFeature[];
+};
+type HashedLocalCollection = LocalProduct;
+declare function hashCollection(products: NomKitOptions["products"]): LocalProduct[];
+type DbCollection = {
+  internalId: string;
+  id: string;
+  label: string;
+  hash: string;
+  priceAmount: number | null;
+  priceInterval: string | null;
+  version: number;
+  createdAt: Date;
+  updatedAt: Date;
+  features: {
+    internalId: string;
+    hash: string;
+    createdAt: Date;
+    updatedAt: Date;
+    featureInternalId: string;
+    type: "boolean" | "metered";
+    limit: bigint | null;
+    resetInterval: string | null;
+    productId: string;
+    productVersion: number;
+    feature: {
+      internalId: string;
+      id: string;
+      label: string;
+      createdAt: Date;
+      updatedAt: Date;
+    } | null;
+  }[];
+};
+declare function queryLatestCollection({
+  db,
+  productIds
+}: {
+  db: NomkitDB;
+  productIds: string[];
+}): Promise<DbCollection[]>;
+interface CreateCollection {
+  db: NomkitDB;
+  localCollection: HashedLocalCollection[];
+  preview: boolean;
+}
+interface CreateResult {
+  actions: CreateAction[];
+  created: number;
+}
+type CreateAction = {
+  type: "created";
+  productId: string;
+  version: number;
+  featureCount: number;
+};
+declare function createCollection({
+  db,
+  localCollection,
+  preview
+}: CreateCollection): Promise<CreateResult>;
+type DiffAction = {
+  type: "created";
+  productId: string;
+  version: number;
+} | {
+  type: "updated";
+  productId: string;
+  version: number;
+  previousVersion: number;
+} | {
+  type: "skipped";
+  productId: string;
+  reason: "hash_match";
+};
+interface DiffResult {
+  actions: DiffAction[];
+  created: number;
+  updated: number;
+  skipped: number;
+}
+interface DiffOptions {
+  db: NomkitDB;
+  localCollection: HashedLocalCollection[];
+  dbCollection: DbCollection[];
+  preview: boolean;
+}
+declare function diffCollection({
+  db,
+  localCollection,
+  dbCollection,
+  preview
+}: DiffOptions): Promise<DiffResult>;
+//#endregion
+export { CreateAction, CreateResult, DiffAction, DiffResult, Feature, createCollection, diffCollection, hashCollection, queryLatestCollection };

package/dist/cli/lib/collection_sync.js

@@ -0,0 +1,158 @@
+import { features, productFeatures, products } from "../../core/pg_db/schema.js";
+import { hashFeature, hashPlan } from "./hash.js";
+import { sql } from "drizzle-orm";
+//#region cli/lib/collection_sync.ts
+const INITIAL_PRODUCT_VERSION = 1;
+function hashCollection(products) {
+	return products.map((product) => {
+		const productHash = hashPlan(product);
+		const { includes = [], ...rest } = product;
+		return {
+			id: rest.id,
+			label: rest.label,
+			hash: productHash,
+			price: rest.price,
+			features: includes.map((feature) => {
+				return {
+					id: feature.id,
+					label: feature.label,
+					limit: feature.limit,
+					reset: feature.reset,
+					type: feature.type,
+					hash: hashFeature(feature),
+					_planId: product.id
+				};
+			})
+		};
+	});
+}
+async function queryLatestCollection({ db, productIds }) {
+	return (await Promise.all(productIds.map((id) => {
+		return db.query.products.findFirst({
+			where: { id },
+			orderBy: (products, { desc }) => [desc(products.version)],
+			with: { features: { with: { feature: true } } }
+		});
+	}))).filter((r) => r !== void 0);
+}
+async function createCollection({ db, localCollection, preview = false }) {
+	const actions = localCollection.map((p) => ({
+		type: "created",
+		productId: p.id,
+		version: INITIAL_PRODUCT_VERSION,
+		featureCount: p.features.length
+	}));
+	if (!preview) {
+		const newProducts = localCollection.map((p) => buildProduct(p, INITIAL_PRODUCT_VERSION));
+		const newFeatures = localCollection.flatMap((p) => p.features).map((f) => ({
+			id: f.id,
+			label: f.label
+		}));
+		await db.transaction(async (tx) => {
+			const products$1 = await tx.insert(products).values(newProducts).returning();
+			const features$2 = await tx.insert(features).values(newFeatures).onConflictDoUpdate({
+				target: features.id,
+				set: {
+					internalId: sql`excluded.internal_id`,
+					id: sql`excluded.id`,
+					label: sql`excluded.label`
+				}
+			}).returning();
+			const newProductFeatures = localCollection.flatMap((p) => p.features).map((configFeature) => {
+				const product = products$1.find((p) => p.id === configFeature._planId);
+				if (!product) throw new Error(`Could not find product for feature: ${configFeature.id}`);
+				const feature = features$2.find((f) => f.id === configFeature.id && f.label === configFeature.label);
+				if (!feature) throw new Error(`Could not find feature: ${configFeature.id}`);
+				return buildProductFeature(configFeature, feature.internalId, product.id, product.version);
+			});
+			await tx.insert(productFeatures).values(newProductFeatures);
+		});
+	}
+	return {
+		actions,
+		created: actions.length
+	};
+}
+async function diffCollection({ db, localCollection, dbCollection, preview = false }) {
+	const actions = [];
+	for (const configProduct of localCollection) {
+		const dbProduct = dbCollection.find((p) => p.id === configProduct.id);
+		if (!dbProduct) {
+			const version = INITIAL_PRODUCT_VERSION;
+			actions.push({
+				type: "created",
+				productId: configProduct.id,
+				version
+			});
+			if (!preview) await db.transaction((tx) => upsertProductWithFeatures(tx, configProduct, version));
+		} else if (dbProduct.hash !== configProduct.hash) {
+			const previousVersion = dbProduct.version;
+			const version = previousVersion + 1;
+			actions.push({
+				type: "updated",
+				productId: configProduct.id,
+				version,
+				previousVersion
+			});
+			if (!preview) await db.transaction((tx) => upsertProductWithFeatures(tx, configProduct, version));
+		} else actions.push({
+			type: "skipped",
+			productId: configProduct.id,
+			reason: "hash_match"
+		});
+	}
+	return {
+		actions,
+		created: actions.filter((a) => a.type === "created").length,
+		updated: actions.filter((a) => a.type === "updated").length,
+		skipped: actions.filter((a) => a.type === "skipped").length
+	};
+}
+function buildProduct(configProduct, version) {
+	const product = {
+		id: configProduct.id,
+		label: configProduct.label,
+		hash: configProduct.hash,
+		version
+	};
+	if (configProduct.price) {
+		product.priceAmount = configProduct.price.amount;
+		product.priceInterval = configProduct.price.interval;
+	}
+	return product;
+}
+function buildProductFeature(configFeature, featureInternalId, productId, productVersion) {
+	const feature = {
+		type: configFeature.type,
+		hash: configFeature.hash,
+		productId,
+		productVersion,
+		featureInternalId
+	};
+	if (configFeature.type === "metered") {
+		feature.limit = BigInt(configFeature.limit);
+		feature.resetInterval = configFeature.reset;
+	}
+	return feature;
+}
+async function upsertProductWithFeatures(tx, configProduct, version) {
+	await tx.insert(products).values(buildProduct(configProduct, version));
+	if (configProduct.features.length === 0) return;
+	const features$1 = await tx.insert(features).values(configProduct.features.map((f) => ({
+		id: f.id,
+		label: f.label
+	}))).onConflictDoUpdate({
+		target: features.id,
+		set: {
+			id: sql`excluded.id`,
+			label: sql`excluded.label`
+		}
+	}).returning();
+	await tx.insert(productFeatures).values(configProduct.features.map((configFeature) => {
+		const feature = features$1.find((f) => f.id === configFeature.id);
+		if (!feature) throw new Error(`Could not find feature: ${configFeature.id}`);
+		return buildProductFeature(configFeature, feature.internalId, configProduct.id, version);
+	}));
+}
+//#endregion
+export { createCollection, diffCollection, hashCollection, queryLatestCollection };

package/dist/cli/lib/config_loader.d.ts

@@ -0,0 +1,15 @@
+import { NomKitOptions } from "../../index.js";
+
+//#region cli/lib/config_loader.d.ts
+declare function getNomKitConfig({
+  cwd,
+  configPath
+}: {
+  cwd: string;
+  configPath?: string;
+}): Promise<{
+  path: string;
+  options: NomKitOptions;
+}>;
+//#endregion
+export { getNomKitConfig };

package/dist/cli/lib/config_loader.js

@@ -0,0 +1,43 @@
+import path from "node:path";
+import dotenv from "dotenv";
+import { createJiti } from "jiti";
+//#region cli/lib/config_loader.ts
+function loadDotEnv(cwd) {
+	dotenv.config({
+		path: path.join(cwd, ".env"),
+		quiet: true
+	});
+	dotenv.config({
+		override: true,
+		path: path.join(cwd, ".env.local"),
+		quiet: true
+	});
+}
+async function loadModule(cwd, configPath) {
+	loadDotEnv(cwd);
+	return createJiti(configPath, {
+		interopDefault: false,
+		jsx: true,
+		moduleCache: false
+	}).import(configPath);
+}
+function getNomKit(module) {
+	if (!module || typeof module !== "object") return null;
+	const exports = module;
+	return [exports.nomkit, exports.default].find((value) => isNomKitLike(value)) ?? null;
+}
+function isNomKitLike(value) {
+	if (!value || typeof value !== "object") return false;
+	const nomkit = value;
+	return typeof nomkit?.handler === "function" && typeof nomkit?.api?.subscribe === "function" && "options" in nomkit;
+}
+async function getNomKitConfig({ cwd, configPath = "" }) {
+	const config = getNomKit(await loadModule(cwd, configPath));
+	if (!config) throw new Error(`Couldn't read your NomKit instance in ${configPath}. Export your NomKit instance as \`nomkit\` or default export the result of \`createNomkit(...)\`.`);
+	return {
+		path: configPath,
+		options: config.options
+	};
+}
+//#endregion
+export { getNomKitConfig };

package/dist/cli/lib/hash.d.ts

@@ -0,0 +1,22 @@
+import { Plan } from "../../index.js";
+import { Feature } from "./collection_sync.js";
+
+//#region cli/lib/hash.d.ts
+declare function stabilizeFeature(feature: Feature): {
+  id: string;
+  type: "boolean" | "metered";
+  limit: number;
+  reset: "week" | "month" | "year";
+};
+declare function stabilizePlan(plan: Plan<any>): {
+  id: string;
+  price?: {
+    amount: number;
+    interval: string;
+  };
+  features: Record<string, unknown>;
+};
+declare const hashFeature: (feature: Feature) => string;
+declare const hashPlan: (plan: Plan) => string;
+//#endregion
+export { hashFeature, hashPlan, stabilizeFeature, stabilizePlan };

package/dist/cli/lib/hash.js

@@ -0,0 +1,63 @@
+import z from "zod";
+import crypto from "node:crypto";
+//#region cli/lib/hash.ts
+function sortedStringify(obj) {
+	return JSON.stringify(obj, (_, value) => {
+		if (value && typeof value === "object" && !Array.isArray(value)) return Object.keys(value).sort().reduce((sorted, k) => {
+			sorted[k] = value[k];
+			return sorted;
+		}, {});
+		return value;
+	}, 0);
+}
+function hashString(data) {
+	return crypto.createHash("sha256").update(data).digest("hex");
+}
+function stabilizeFeature(feature) {
+	const { label, ...stableProperties } = feature;
+	return stableProperties;
+}
+function stabilizePlan(plan) {
+	const idAndLabel = {
+		id: z.string().min(1),
+		label: z.string().min(1)
+	};
+	const result = z.object({
+		...idAndLabel,
+		price: z.object({
+			amount: z.number().min(0),
+			interval: z.string().min(1)
+		}).optional(),
+		includes: z.array(z.discriminatedUnion("type", [z.object({
+			...idAndLabel,
+			type: z.literal("boolean")
+		}), z.object({
+			...idAndLabel,
+			type: z.literal("metered"),
+			limit: z.number(),
+			reset: z.string().min(1)
+		})])).optional()
+	}).strict().safeParse(plan);
+	if (!result.success) {
+		console.error(z.prettifyError(result.error));
+		throw new Error("Plan validation failed");
+	}
+	const features = {};
+	for (const feature of plan?.includes ?? []) {
+		const { id, ...stableProperties } = stabilizeFeature(feature);
+		features[feature.id] = stableProperties;
+	}
+	const { label, includes, ...stableProperties } = plan;
+	return {
+		features,
+		...stableProperties
+	};
+}
+const hashFeature = (feature) => {
+	return hashString(sortedStringify(stabilizeFeature(feature)));
+};
+const hashPlan = (plan) => {
+	return hashString(sortedStringify(stabilizePlan(plan)));
+};
+//#endregion
+export { hashFeature, hashPlan, stabilizeFeature, stabilizePlan };

package/dist/cli/lib/migrations.d.ts

@@ -0,0 +1,6 @@
+import { NomkitDB } from "../../core/pg_db/index.js";
+
+//#region cli/lib/migrations.d.ts
+declare function dbMigrate(db: NomkitDB): Promise<void>;
+//#endregion
+export { dbMigrate };

package/dist/cli/lib/migrations.js

@@ -0,0 +1,17 @@
+import { isPGlite, isPgPool, migratePGlite, migratePgNode } from "../../core/pg_db/index.js";
+//#region cli/lib/migrations.ts
+async function dbMigrate(db) {
+	const client = db.$client;
+	if (isPGlite(client)) {
+		try {
+			await migratePGlite(client);
+		} finally {}
+		return;
+	}
+	if (!isPgPool(client)) return;
+	try {
+		await migratePgNode(client);
+	} finally {}
+}
+//#endregion
+export { dbMigrate };