@businessdash/sdk 0.9.60 → 0.9.80

package/src/seed-core/index.ts

@@ -0,0 +1,735 @@
+/**
+ * `@businessdash/sdk/seed` — define a schema, push it, and seed data, from any
+ * framework's build step.
+ *
+ * ## Why this exists alongside the CLI
+ *
+ * `businessdash sync-data-model` and friends already do this, and they are the
+ * right tool at a terminal. They are the wrong tool everywhere else: a Nuxt
+ * module, a SvelteKit prerender hook, an Angular builder, a Vite plugin, a
+ * Next `instrumentation.ts` or a CI step that already has the credentials
+ * loaded cannot shell out to an interactive command and read its output.
+ *
+ * So the same operations are exposed as plain async functions. Nothing here is
+ * framework-specific, because seeding happens at BUILD time — there is no
+ * reactivity to bridge, only an integration point per framework, and every
+ * framework has one that can call a function.
+ *
+ * The CLI imports this module rather than the other way round, so there is one
+ * implementation of the transport, the auth header and the error handling.
+ *
+ * ## What can and cannot be seeded
+ *
+ * The package API decides this, not the SDK:
+ *
+ * | Target                | Seedable | Endpoint |
+ * |-----------------------|----------|----------|
+ * | Custom-database schema| yes      | `data-model/plan` + `draft-schema` |
+ * | Custom-database records| yes     | `data-model/records` |
+ * | Static collections    | yes      | `collections`, `collections/{slug}/rows` |
+ * | Coupons               | yes      | `coupons` |
+ * | Products (+ variants) | yes      | `storefront/products` |
+ * | Blog posts            | yes      | `blog/posts` |
+ *
+ * Products and blog posts were absent from the first version of this module
+ * because the package API had no create route for either — the dashboard could
+ * do it and the SDK could not. Both routes now exist, so a site can be seeded
+ * whole: schema, records, collections, catalogue, content and coupons.
+ *
+ * ## Pushing a schema does not apply it
+ *
+ * `pushDataModel` writes the DRAFT slot and returns the plan describing what
+ * promoting it would do. Promotion is a separate, deliberate step in the
+ * dashboard. That is the platform's design and this module does not route
+ * around it: an automated deploy that silently altered a live customer
+ * database would be the wrong default.
+ *
+ * @module
+ */
+
+import type { CollectionDefinition } from "../data-model-schema.js";
+
+/** Where to seed, and with what credentials. */
+export type SeedTarget = {
+	/** Package API key. Needs the data-model and storefront write scopes. */
+	apiKey: string;
+	/** Site id, from Site Builder → Developer. */
+	siteId: string;
+	/** Package-API base URL, e.g. `https://businessdash.us/api/package/v1`. */
+	baseUrl: string;
+};
+
+/** A single change promoting a draft schema would make. */
+export type MigrationPlanChange = {
+	class: "safe" | "backfill" | "destructive" | "exposure";
+	kind: string;
+	object: string;
+	field?: string;
+	option?: string;
+	summary: string;
+};
+
+export type MigrationPlan = {
+	changes: MigrationPlanChange[];
+	[key: string]: unknown;
+};
+
+function normalizeBaseUrl(raw: string): string {
+	return raw.replace(/\/+$/, "");
+}
+
+/**
+ * One request to the package API, shared by every function here AND by the CLI.
+ *
+ * Errors carry the server's own message when it sent one. A seeder that failed
+ * with `HTTP 403` and nothing else would send someone hunting through their
+ * own code for a problem the API already described.
+ */
+export async function callPackageApi(
+	target: SeedTarget,
+	input: {
+		path: string;
+		method: "GET" | "POST" | "PATCH";
+		body?: unknown;
+	},
+): Promise<Record<string, unknown>> {
+	const url = `${normalizeBaseUrl(target.baseUrl)}/${input.path}`;
+	const res = await fetch(url, {
+		method: input.method,
+		headers: {
+			"content-type": "application/json",
+			authorization: `Bearer ${target.apiKey}`,
+		},
+		...(input.body !== undefined ? { body: JSON.stringify(input.body) } : {}),
+	});
+
+	const text = await res.text();
+	let parsed: Record<string, unknown> | null = null;
+	try {
+		parsed = JSON.parse(text) as Record<string, unknown>;
+	} catch {
+		parsed = null;
+	}
+
+	if (!res.ok) {
+		const message =
+			typeof parsed?.message === "string"
+				? parsed.message
+				: `HTTP ${res.status} ${res.statusText} — ${text.slice(0, 240)}`;
+		throw new Error(`${input.method} ${input.path}: ${message}`);
+	}
+	if (!parsed) {
+		throw new Error(
+			`${input.method} ${input.path}: server replied ${res.status} but the body wasn't JSON — first 240 chars: ${text.slice(0, 240)}`,
+		);
+	}
+	return parsed;
+}
+
+/** Data-model routes are all under the site's data-model namespace. */
+function dataModelPath(target: SeedTarget, suffix: string): string {
+	return `sites/${encodeURIComponent(target.siteId)}/data-model/${suffix}`;
+}
+
+/** A schema artifact — the output of `createSchema(...).toJSONSchema()`. */
+export type DataModelArtifact = Record<string, unknown>;
+
+export type PushDataModelResult = {
+	/** What promoting this draft WOULD do. Read it before promoting. */
+	plan: MigrationPlan;
+	/** Draft version now in the slot, or the existing one when unchanged. */
+	version: number | null;
+	/** True when the draft already matched — nothing was written. */
+	noop: boolean;
+	/** True when `dryRun` was set: the plan was computed, nothing uploaded. */
+	planOnly: boolean;
+};
+
+export type PushDataModelOptions = {
+	/**
+	 * Compute the plan and stop. Use this in CI on a pull request: it tells you
+	 * what a deploy would change without changing anything.
+	 */
+	dryRun?: boolean;
+	/** Ask the plan to include dropping objects/fields absent from the schema. */
+	prune?: boolean;
+	/** Free-text note stored with the draft. */
+	note?: string | null;
+	/** Optional checksum; the server uses it to detect an unchanged draft. */
+	checksum?: string;
+};
+
+/**
+ * Plan, then push a schema into the DRAFT slot.
+ *
+ * The plan is always computed, even when pushing, because a push whose
+ * consequences nobody looked at is how a destructive migration reaches a live
+ * database. The returned `plan.changes` carry a `class` — `safe`, `backfill`,
+ * `destructive` or `exposure` — which is what a CI gate should branch on.
+ */
+export async function pushDataModel(
+	target: SeedTarget,
+	schema: DataModelArtifact,
+	options: PushDataModelOptions = {},
+): Promise<PushDataModelResult> {
+	const planRes = await callPackageApi(target, {
+		path: dataModelPath(target, "plan"),
+		method: "POST",
+		body: { schema, prune: options.prune ?? false },
+	});
+	const plan = (planRes.plan ?? { changes: [] }) as MigrationPlan;
+
+	if (options.dryRun) {
+		return { plan, version: null, noop: false, planOnly: true };
+	}
+
+	const res = await callPackageApi(target, {
+		path: dataModelPath(target, "draft-schema"),
+		method: "POST",
+		body: {
+			schema,
+			...(options.checksum ? { checksum: options.checksum } : {}),
+			note: options.note ?? null,
+		},
+	});
+
+	return {
+		plan,
+		version: typeof res.version === "number" ? res.version : null,
+		noop: res.noop === true,
+		planOnly: false,
+	};
+}
+
+/** Does this plan contain anything that would lose or expose data? */
+export function planHasDangerousChanges(plan: MigrationPlan): boolean {
+	return (plan.changes ?? []).some(
+		(c) => c.class === "destructive" || c.class === "exposure",
+	);
+}
+
+/** Records keyed by collection name, as the data-model records route expects. */
+export type SeedRecords = Record<
+	string,
+	ReadonlyArray<Record<string, unknown>>
+>;
+
+export type SeedRecordsResult = {
+	/** How many rows were written per collection, as the server reported. */
+	written: Record<string, number>;
+};
+
+/**
+ * Seed rows into the CUSTOM DATABASE (the metadata engine).
+ *
+ * This is not the same store as `seedCollectionRows` below. The custom database
+ * is the schema you defined and promoted; static collections are a simpler
+ * key/value-ish store on the site. Mixing them up is easy and the failure is
+ * silent — the rows land somewhere real, just not where they were wanted — so
+ * the two functions are named for the store rather than for the verb.
+ */
+export async function seedRecords(
+	target: SeedTarget,
+	records: SeedRecords,
+): Promise<SeedRecordsResult> {
+	const res = await callPackageApi(target, {
+		path: dataModelPath(target, "records"),
+		method: "POST",
+		body: { records },
+	});
+	const written = (res.written ?? {}) as Record<string, number>;
+	return { written };
+}
+
+export type StaticCollectionDefinition = {
+	name: string;
+	slug?: string;
+	description?: string;
+	fields?: ReadonlyArray<Record<string, unknown>>;
+};
+
+/** Create a STATIC collection on the site. Idempotent by slug server-side. */
+export async function seedCollection(
+	target: SeedTarget,
+	definition: StaticCollectionDefinition,
+): Promise<Record<string, unknown>> {
+	return callPackageApi(target, {
+		path: `sites/${encodeURIComponent(target.siteId)}/collections`,
+		method: "POST",
+		body: definition,
+	});
+}
+
+/**
+ * Insert rows into a static collection.
+ *
+ * Rows go one request each because the route takes one row — batching would
+ * mean inventing a bulk endpoint that does not exist. `concurrency` keeps a
+ * large seed from opening hundreds of sockets at once.
+ */
+export async function seedCollectionRows(
+	target: SeedTarget,
+	slug: string,
+	rows: ReadonlyArray<{ rowId?: string; data: Record<string, unknown> }>,
+	options: { concurrency?: number } = {},
+): Promise<{ written: number }> {
+	const concurrency = Math.max(1, options.concurrency ?? 4);
+	const path = `sites/${encodeURIComponent(target.siteId)}/collections/${encodeURIComponent(slug)}/rows`;
+
+	let written = 0;
+	for (let i = 0; i < rows.length; i += concurrency) {
+		const batch = rows.slice(i, i + concurrency);
+		await Promise.all(
+			batch.map(async (row) => {
+				await callPackageApi(target, { path, method: "POST", body: row });
+				written += 1;
+			}),
+		);
+	}
+	return { written };
+}
+
+export type SeedCrossVariantOption = {
+	value: string;
+	price: number;
+	stock?: number | null;
+	isLive?: boolean;
+	pricingBehavior?: "price" | "note" | null;
+};
+
+export type SeedCrossVariantTitle = {
+	title: string;
+	selectionMode?: "single" | "multiple" | null;
+	minSelected?: number | null;
+	maxSelected?: number | null;
+	options?: SeedCrossVariantOption[];
+};
+
+export type SeedProductVariant = {
+	name: string;
+	description?: string | null;
+	price?: number | null;
+	/** Unit COST in integer cents, for margin analytics. */
+	costCents?: number | null;
+	stock?: number | null;
+	isDigital?: boolean;
+	isPhysical?: boolean;
+	isLive?: boolean;
+	attributes?: Record<string, unknown> | null;
+	weightInGrams?: number | null;
+	requiresShipping?: boolean;
+	flatRateShippingCents?: number | null;
+	crossVariantTitles?: SeedCrossVariantTitle[];
+};
+
+export type SeedProduct = {
+	name: string;
+	description?: string | null;
+	categoryId?: string | null;
+	storefront?: "web" | "physical" | "all" | null;
+	/** Defaults FALSE — seeding must not publish a half-built catalogue. */
+	isLive?: boolean;
+	available?: boolean | null;
+	images?: string[] | null;
+	manufacturer?: string | null;
+	/** INTEGER, not text — the column is an integer. */
+	modelNumber?: number | null;
+	quantity?: number | null;
+	type?: string | null;
+	variants?: SeedProductVariant[];
+	crossVariantTitles?: SeedCrossVariantTitle[];
+};
+
+export type SeedProductResult = {
+	name: string;
+	id: string;
+	variantCount: number;
+	crossVariantCount: number;
+};
+
+/**
+ * Create products, each with its variants and cross-variants.
+ *
+ * The whole tree goes in ONE request per product, because the route writes it
+ * in a transaction — a seed that created a product and then failed partway
+ * through its variants would leave a catalogue nobody could trust.
+ *
+ * Products land unpublished unless `isLive` says otherwise, and are NOT pushed
+ * to Stripe: that is a separate deliberate call, because it mints objects in an
+ * account the org is billed against.
+ */
+export async function seedProducts(
+	target: SeedTarget,
+	products: readonly SeedProduct[],
+): Promise<SeedProductResult[]> {
+	const results: SeedProductResult[] = [];
+	for (const product of products) {
+		const res = await callPackageApi(target, {
+			path: "storefront/products",
+			method: "POST",
+			body: product,
+		});
+		results.push({
+			name: product.name,
+			id: String(res.id ?? ""),
+			variantCount: Number(res.variantCount ?? 0),
+			crossVariantCount: Number(res.crossVariantCount ?? 0),
+		});
+	}
+	return results;
+}
+
+export type SeedBlogPost = {
+	title: string;
+	/** Lowercase words separated by single hyphens. Unique per org. */
+	slug: string;
+	content: string;
+	excerpt?: string | null;
+	featuredImageUrl?: string | null;
+	accessLevel?: "public" | "members" | "subscribers";
+	tags?: string[];
+	commentResponseType?: "admin" | "all" | "none";
+	authorEmail?: string | null;
+	categoryId?: string | null;
+	/** Defaults FALSE — seeding must not publish drafts to a live blog. */
+	publishNow?: boolean;
+};
+
+export type SeedBlogPostResult = {
+	slug: string;
+	created: boolean;
+	published: boolean;
+	message?: string;
+};
+
+/**
+ * Create blog posts.
+ *
+ * An existing slug is REPORTED rather than thrown, on the same reasoning as
+ * coupons: re-running a seed must be safe, and a conflict on the third post
+ * must not abandon the remaining seven.
+ */
+export async function seedBlogPosts(
+	target: SeedTarget,
+	posts: readonly SeedBlogPost[],
+): Promise<SeedBlogPostResult[]> {
+	const results: SeedBlogPostResult[] = [];
+	for (const post of posts) {
+		try {
+			const res = await callPackageApi(target, {
+				path: "blog/posts",
+				method: "POST",
+				body: post,
+			});
+			results.push({
+				slug: post.slug,
+				created: true,
+				published: res.published === true,
+			});
+		} catch (cause) {
+			const message = cause instanceof Error ? cause.message : String(cause);
+			if (/already exists|conflict/i.test(message)) {
+				results.push({
+					slug: post.slug,
+					created: false,
+					published: false,
+					message: "already exists — left alone",
+				});
+				continue;
+			}
+			throw cause;
+		}
+	}
+	return results;
+}
+
+export type SeedCoupon = {
+	code: string;
+	discountType: "percent" | "amount";
+	/** `percent` takes 1–100; `amount` takes a MAJOR-unit amount (10 = $10). */
+	value: number;
+	validFrom?: Date | string;
+	validUntil?: Date | string | null;
+	maxUses?: number | null;
+	isActive?: boolean;
+	duration?: "once" | "forever" | "repeating";
+	durationInMonths?: number | null;
+	appliesTo?: "order" | "shipping" | "both";
+};
+
+export type SeedCouponResult = {
+	code: string;
+	created: boolean;
+	/** False when the coupon exists locally but the Stripe mirror failed. */
+	stripeSynced: boolean;
+	/** Why it was skipped or failed, when it was. */
+	message?: string;
+};
+
+/**
+ * Create coupons in the org's own Stripe account as well as locally.
+ *
+ * An existing code is REPORTED, not treated as a failure: re-running a seed
+ * should be safe, and a 409 on the third of ten coupons must not abandon the
+ * remaining seven. Anything else still throws — a bad key or a malformed
+ * coupon is a real problem and swallowing it would leave a half-seeded store
+ * looking successful.
+ */
+export async function seedCoupons(
+	target: SeedTarget,
+	coupons: readonly SeedCoupon[],
+): Promise<SeedCouponResult[]> {
+	const results: SeedCouponResult[] = [];
+	for (const coupon of coupons) {
+		try {
+			const res = await callPackageApi(target, {
+				path: "coupons",
+				method: "POST",
+				body: {
+					...coupon,
+					...(coupon.validFrom
+						? {
+								validFrom:
+									coupon.validFrom instanceof Date
+										? coupon.validFrom.toISOString()
+										: coupon.validFrom,
+							}
+						: {}),
+					...(coupon.validUntil
+						? {
+								validUntil:
+									coupon.validUntil instanceof Date
+										? coupon.validUntil.toISOString()
+										: coupon.validUntil,
+							}
+						: {}),
+				},
+			});
+			results.push({
+				code: coupon.code,
+				created: true,
+				stripeSynced: res.stripeSynced === true,
+				...(typeof res.stripeError === "string" && res.stripeError
+					? { message: res.stripeError }
+					: {}),
+			});
+		} catch (cause) {
+			const message = cause instanceof Error ? cause.message : String(cause);
+			// The route answers 409 for a code that already exists.
+			if (/already exists|conflict/i.test(message)) {
+				results.push({
+					code: coupon.code,
+					created: false,
+					stripeSynced: false,
+					message: "already exists — left alone",
+				});
+				continue;
+			}
+			throw cause;
+		}
+	}
+	return results;
+}
+
+/**
+ * A whole seed, declared in one object.
+ *
+ * The shape a `businessdash.seed.ts` exports. Every field is optional so a
+ * project can seed only what it has.
+ */
+export type SeedDefinition = {
+	/** The schema artifact, or a `createSchema(...)` result. */
+	dataModel?: DataModelArtifact | { toJSONSchema(): DataModelArtifact };
+	dataModelOptions?: PushDataModelOptions;
+	/** Rows for the custom database, keyed by collection name. */
+	records?: SeedRecords;
+	/** Static collections to create, each with optional rows. */
+	collections?: ReadonlyArray<
+		StaticCollectionDefinition & {
+			rows?: ReadonlyArray<{ rowId?: string; data: Record<string, unknown> }>;
+		}
+	>;
+	/** Products, each with its variants and cross-variants. */
+	products?: readonly SeedProduct[];
+	posts?: readonly SeedBlogPost[];
+	coupons?: readonly SeedCoupon[];
+};
+
+export type SeedRunResult = {
+	dataModel?: PushDataModelResult;
+	records?: SeedRecordsResult;
+	collections?: Array<{ slug: string; rowsWritten: number }>;
+	products?: SeedProductResult[];
+	posts?: SeedBlogPostResult[];
+	coupons?: SeedCouponResult[];
+};
+
+export type RunSeedOptions = {
+	/** Called with human-readable progress. Wire it to your build's logger. */
+	onProgress?: (message: string) => void;
+	/**
+	 * Refuse to push a schema whose plan contains destructive or exposing
+	 * changes. Defaults to TRUE, because the common case for this function is
+	 * an automated deploy, and an automated deploy should not be the thing that
+	 * drops a customer's column.
+	 */
+	failOnDangerousPlan?: boolean;
+};
+
+/**
+ * Run a whole seed, in dependency order: schema first, then the records that
+ * depend on it, then static collections, then products, posts and coupons.
+ *
+ * Order matters and is not configurable — seeding records into a collection
+ * whose schema has not been promoted yet fails in a way that reads as a
+ * permissions problem.
+ */
+export async function runSeed(
+	target: SeedTarget,
+	seed: SeedDefinition,
+	options: RunSeedOptions = {},
+): Promise<SeedRunResult> {
+	const log = options.onProgress ?? (() => {});
+	const failOnDangerous = options.failOnDangerousPlan ?? true;
+	const result: SeedRunResult = {};
+
+	if (seed.dataModel) {
+		// `DataModelArtifact` is a Record, so `"toJSONSchema" in x` narrows the
+		// union to the record branch rather than the schema branch — the property
+		// check has to be on the VALUE being callable, not on the key existing.
+		const candidate = seed.dataModel as {
+			toJSONSchema?: () => DataModelArtifact;
+		};
+		const artifact =
+			typeof candidate.toJSONSchema === "function"
+				? candidate.toJSONSchema()
+				: (seed.dataModel as DataModelArtifact);
+		log("Pushing data model…");
+		const pushed = await pushDataModel(target, artifact, seed.dataModelOptions);
+		result.dataModel = pushed;
+
+		if (failOnDangerous && planHasDangerousChanges(pushed.plan)) {
+			const summary = pushed.plan.changes
+				.filter((c) => c.class === "destructive" || c.class === "exposure")
+				.map((c) => `  ${c.class}: ${c.summary}`)
+				.join("\n");
+			throw new Error(
+				`The schema plan contains changes that would lose or expose data:\n${summary}\n\nThe draft was ${pushed.planOnly ? "not uploaded" : "uploaded but NOT promoted"}. Review and promote it deliberately, or pass \`failOnDangerousPlan: false\` if you have already decided.`,
+			);
+		}
+		log(
+			pushed.planOnly
+				? "Plan only — nothing uploaded."
+				: pushed.noop
+					? "Data model unchanged."
+					: `Draft v${pushed.version} uploaded (promote it in the dashboard to apply).`,
+		);
+	}
+
+	if (seed.records) {
+		log("Seeding custom-database records…");
+		result.records = await seedRecords(target, seed.records);
+		const total = Object.values(result.records.written).reduce(
+			(a, b) => a + b,
+			0,
+		);
+		log(`Wrote ${total} record(s).`);
+	}
+
+	if (seed.collections?.length) {
+		result.collections = [];
+		for (const definition of seed.collections) {
+			const { rows, ...collectionInput } = definition;
+			log(`Creating static collection "${collectionInput.name}"…`);
+			const created = await seedCollection(target, collectionInput);
+			const slug =
+				(typeof created.slug === "string" ? created.slug : undefined) ??
+				collectionInput.slug ??
+				collectionInput.name;
+			let rowsWritten = 0;
+			if (rows?.length) {
+				rowsWritten = (await seedCollectionRows(target, slug, rows)).written;
+				log(`  ${rowsWritten} row(s).`);
+			}
+			result.collections.push({ slug, rowsWritten });
+		}
+	}
+
+	if (seed.products?.length) {
+		log(`Seeding ${seed.products.length} product(s)…`);
+		result.products = await seedProducts(target, seed.products);
+		const variants = result.products.reduce((a, p) => a + p.variantCount, 0);
+		log(`${result.products.length} product(s), ${variants} variant(s).`);
+	}
+
+	if (seed.posts?.length) {
+		log(`Seeding ${seed.posts.length} blog post(s)…`);
+		result.posts = await seedBlogPosts(target, seed.posts);
+		const created = result.posts.filter((p) => p.created).length;
+		log(
+			`${created} created, ${result.posts.length - created} already existed.`,
+		);
+	}
+
+	if (seed.coupons?.length) {
+		log(`Seeding ${seed.coupons.length} coupon(s)…`);
+		result.coupons = await seedCoupons(target, seed.coupons);
+		const created = result.coupons.filter((c) => c.created).length;
+		log(
+			`${created} created, ${result.coupons.length - created} already existed.`,
+		);
+	}
+
+	return result;
+}
+
+/**
+ * Read a seed target from environment variables.
+ *
+ * The names match what the CLI already reads, so a project that has the CLI
+ * working needs no new configuration to call these functions from a build step.
+ */
+export function seedTargetFromEnv(
+	env: Record<string, string | undefined> = typeof process === "undefined"
+		? {}
+		: process.env,
+): SeedTarget {
+	// BIAB_API_KEY first, because that is the name the CLI reads and the name
+	// every starter's .env.example sets. Reading a different name would mean a
+	// project whose CLI works fine still fails here, with an error naming a
+	// variable the consumer has never seen.
+	const apiKey =
+		env.BIAB_API_KEY ?? env.BUSINESSDASH_API_KEY ?? env.BIAB_PACKAGE_API_KEY;
+	const siteId = env.BIAB_SITE_ID ?? env.BUSINESSDASH_SITE_ID;
+	const baseUrl =
+		env.BIAB_PACKAGE_API_BASE_URL ??
+		env.BUSINESSDASH_API_BASE_URL ??
+		env.NEXT_PUBLIC_BIAB_PACKAGE_API_BASE_URL;
+
+	const missing = [
+		!apiKey && "BIAB_API_KEY",
+		!siteId && "BIAB_SITE_ID",
+		!baseUrl && "BIAB_PACKAGE_API_BASE_URL",
+	].filter(Boolean);
+
+	if (missing.length > 0) {
+		throw new Error(
+			`Missing ${missing.join(", ")}. Seeding needs a package API key, a site id and the API base URL — the same three the CLI reads from .env.local.`,
+		);
+	}
+	return {
+		apiKey: apiKey as string,
+		siteId: siteId as string,
+		baseUrl: baseUrl as string,
+	};
+}
+
+/**
+ * Type-only helper for a `businessdash.seed.ts`, so a config file gets
+ * completion and checking without importing anything at runtime.
+ */
+export function defineSeed(seed: SeedDefinition): SeedDefinition {
+	return seed;
+}
+
+export type { CollectionDefinition };