sparta_worlds 0.6.0

package/server/dist/core/seed.js

@@ -0,0 +1,286 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { canonicalHash, sha256Hex } from "./canonical.js";
+const id = (prefix) => z.string().regex(new RegExp(`^${prefix}_[A-Za-z0-9_]+$`), `must look like ${prefix}_...`);
+export const SeedCustomerSchema = z
+    .object({
+    id: id("cus"),
+    name: z.string(),
+    email: z.string().email().nullable().default(null),
+    description: z.string().nullable().default(null),
+    phone: z.string().nullable().default(null),
+    balance: z.number().int().default(0),
+    metadata: z.record(z.string()).default({}),
+    created_offset: z.number().int().min(0).default(0),
+})
+    .strict();
+export const SeedProductSchema = z
+    .object({
+    id: id("prod"),
+    name: z.string(),
+    description: z.string().nullable().default(null),
+    active: z.boolean().default(true),
+    metadata: z.record(z.string()).default({}),
+})
+    .strict();
+export const SeedPriceSchema = z
+    .object({
+    id: id("price"),
+    product: id("prod"),
+    unit_amount: z.number().int().min(0),
+    currency: z.string().length(3).default("usd"),
+    nickname: z.string().nullable().default(null),
+    recurring: z
+        .object({
+        interval: z.enum(["day", "week", "month", "year"]),
+        interval_count: z.number().int().min(1).default(1),
+    })
+        .strict()
+        .nullable()
+        .default(null),
+    active: z.boolean().default(true),
+    metadata: z.record(z.string()).default({}),
+})
+    .strict();
+export const SeedInvoiceLineSchema = z
+    .object({
+    description: z.string().nullable().default(null),
+    amount: z.number().int(),
+    quantity: z.number().int().min(1).default(1),
+    price: id("price").optional(),
+})
+    .strict();
+export const SeedChargeSchema = z
+    .object({
+    id: id("ch"),
+    amount: z.number().int().min(1).optional(),
+    amount_refunded: z.number().int().min(0).optional(),
+    status: z.enum(["succeeded"]).default("succeeded"),
+})
+    .strict();
+export const SeedInvoiceSchema = z
+    .object({
+    id: id("in"),
+    customer: id("cus"),
+    currency: z.string().length(3).default("usd"),
+    status: z.enum(["draft", "open", "paid", "void", "uncollectible"]),
+    lines: z.array(SeedInvoiceLineSchema).min(1),
+    charges: z.array(SeedChargeSchema).default([]),
+    created_offset: z.number().int().min(0).default(0),
+    metadata: z.record(z.string()).default({}),
+})
+    .strict();
+export const SeedSubscriptionSchema = z
+    .object({
+    id: id("sub"),
+    customer: id("cus"),
+    price: id("price"),
+    quantity: z.number().int().min(1).default(1),
+    status: z.enum(["active"]).default("active"),
+    cancel_at_period_end: z.boolean().default(false),
+    current_period_start: z.number().int().optional(),
+    current_period_end: z.number().int().optional(),
+    created_offset: z.number().int().min(0).default(0),
+    metadata: z.record(z.string()).default({}),
+})
+    .strict();
+export const SeedTicketSchema = z
+    .object({
+    subject: z.string().min(1),
+    body: z.string().min(1),
+    status: z.enum(["new", "open", "pending", "hold", "solved", "closed"]).default("open"),
+    priority: z.enum(["low", "normal", "high", "urgent"]).default("normal"),
+    requester: z.object({ name: z.string().min(1), email: z.string().email() }).strict(),
+    tags: z.array(z.string()).default([]),
+    created_offset: z.number().int().min(0).default(0),
+})
+    .strict();
+export const SeedSchema = z
+    .object({
+    name: z.string().regex(/^[a-z0-9][a-z0-9-]*$/),
+    version: z.number().int().min(1),
+    epoch: z.number().int().min(0),
+    clock_mode: z.enum(["manual", "auto"]).default("manual"),
+    auto_tick_seconds: z.number().int().min(1).default(1),
+    data: z
+        .object({
+        customers: z.array(SeedCustomerSchema).default([]),
+        products: z.array(SeedProductSchema).default([]),
+        prices: z.array(SeedPriceSchema).default([]),
+        invoices: z.array(SeedInvoiceSchema).default([]),
+        subscriptions: z.array(SeedSubscriptionSchema).default([]),
+        tickets: z.array(SeedTicketSchema).default([]),
+    })
+        .strict(),
+})
+    .strict();
+export class SeedValidationError extends Error {
+    issues;
+    constructor(issues) {
+        super(`Seed validation failed:\n${issues.map((i) => `  - ${i.path}: ${i.message}`).join("\n")}`);
+        this.issues = issues;
+    }
+}
+export function parseSeed(doc) {
+    const parsed = SeedSchema.safeParse(doc);
+    if (!parsed.success) {
+        throw new SeedValidationError(parsed.error.issues.map((i) => ({ path: i.path.join(".") || "(root)", message: i.message })));
+    }
+    const seed = parsed.data;
+    const issues = [];
+    const dupCheck = (label, ids) => {
+        const seen = new Set();
+        for (const i of ids) {
+            if (seen.has(i))
+                issues.push({ path: label, message: `duplicate id '${i}'` });
+            seen.add(i);
+        }
+        return seen;
+    };
+    const customers = dupCheck("data.customers", seed.data.customers.map((c) => c.id));
+    const products = dupCheck("data.products", seed.data.products.map((p) => p.id));
+    const prices = dupCheck("data.prices", seed.data.prices.map((p) => p.id));
+    dupCheck("data.invoices", seed.data.invoices.map((i) => i.id));
+    dupCheck("data.subscriptions", seed.data.subscriptions.map((s) => s.id));
+    dupCheck("data.invoices[].charges", seed.data.invoices.flatMap((i) => i.charges.map((c) => c.id)));
+    seed.data.prices.forEach((p, idx) => {
+        if (!products.has(p.product))
+            issues.push({ path: `data.prices[${idx}].product`, message: `unknown product '${p.product}'` });
+    });
+    seed.data.invoices.forEach((inv, idx) => {
+        if (!customers.has(inv.customer))
+            issues.push({ path: `data.invoices[${idx}].customer`, message: `unknown customer '${inv.customer}'` });
+        inv.lines.forEach((line, lidx) => {
+            if (line.price && !prices.has(line.price)) {
+                issues.push({ path: `data.invoices[${idx}].lines[${lidx}].price`, message: `unknown price '${line.price}'` });
+            }
+        });
+        if (inv.charges.length > 0 && inv.status !== "paid") {
+            issues.push({
+                path: `data.invoices[${idx}].charges`,
+                message: `charges are only valid on paid invoices (status is '${inv.status}')`,
+            });
+        }
+        const total = inv.lines.reduce((n, line) => n + line.amount, 0);
+        inv.charges.forEach((ch, cidx) => {
+            const cap = ch.amount ?? total;
+            if (ch.amount_refunded !== undefined && ch.amount_refunded > cap) {
+                issues.push({
+                    path: `data.invoices[${idx}].charges[${cidx}].amount_refunded`,
+                    message: `exceeds the charge amount (${cap})`,
+                });
+            }
+        });
+    });
+    seed.data.subscriptions.forEach((sub, idx) => {
+        if (!customers.has(sub.customer))
+            issues.push({ path: `data.subscriptions[${idx}].customer`, message: `unknown customer '${sub.customer}'` });
+        if (!prices.has(sub.price))
+            issues.push({ path: `data.subscriptions[${idx}].price`, message: `unknown price '${sub.price}'` });
+        const price = seed.data.prices.find((p) => p.id === sub.price);
+        if (price && !price.recurring)
+            issues.push({ path: `data.subscriptions[${idx}].price`, message: `price '${sub.price}' is not recurring` });
+        if (sub.current_period_start !== undefined &&
+            sub.current_period_end !== undefined &&
+            sub.current_period_end <= sub.current_period_start) {
+            issues.push({
+                path: `data.subscriptions[${idx}]`,
+                message: `current_period_end must be after current_period_start`,
+            });
+        }
+    });
+    if (issues.length > 0)
+        throw new SeedValidationError(issues);
+    return seed;
+}
+export function seedHash(seed) {
+    return canonicalHash(seed);
+}
+function deepFreeze(value) {
+    if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const key of Object.keys(value)) {
+            deepFreeze(value[key]);
+        }
+    }
+    return value;
+}
+export function createSeedLibrary(seedsDir) {
+    const byFile = new Map();
+    function readable(files) {
+        const out = [];
+        for (const f of files) {
+            try {
+                const bytes = readFileSync(join(seedsDir, f));
+                out.push({ file: f, bytes, digest: sha256Hex(bytes) });
+            }
+            catch {
+            }
+        }
+        return out;
+    }
+    function parseEntry(file, bytes) {
+        try {
+            const seed = deepFreeze(parseSeed(JSON.parse(bytes.toString("utf8"))));
+            return { name: seed.name, file: join(seedsDir, file), seed, hash: seedHash(seed) };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    function load() {
+        const out = new Map();
+        if (!existsSync(seedsDir)) {
+            byFile.clear();
+            return out;
+        }
+        const files = readable(readdirSync(seedsDir)
+            .filter((f) => f.endsWith(".json"))
+            .sort());
+        const seen = new Set();
+        for (const { file, bytes, digest } of files) {
+            seen.add(file);
+            let cachedFile = byFile.get(file);
+            if (!cachedFile || cachedFile.digest !== digest) {
+                cachedFile = { digest, entry: parseEntry(file, bytes) };
+                byFile.set(file, cachedFile);
+            }
+            if (cachedFile.entry)
+                out.set(cachedFile.entry.name, cachedFile.entry);
+        }
+        for (const file of byFile.keys()) {
+            if (!seen.has(file))
+                byFile.delete(file);
+        }
+        return out;
+    }
+    return {
+        list: () => [...load().values()],
+        get: (name) => {
+            const entry = load().get(name);
+            return entry ? { seed: entry.seed, hash: entry.hash } : undefined;
+        },
+    };
+}
+export function createLayeredSeedLibrary(dirs) {
+    const layers = dirs.map((dir) => createSeedLibrary(dir));
+    return {
+        dirs,
+        list() {
+            const merged = new Map();
+            for (const layer of layers)
+                for (const entry of layer.list())
+                    merged.set(entry.name, entry);
+            return [...merged.values()].sort((a, b) => a.name.localeCompare(b.name));
+        },
+        get(name) {
+            for (let i = layers.length - 1; i >= 0; i--) {
+                const hit = layers[i].get(name);
+                if (hit)
+                    return hit;
+            }
+            return undefined;
+        },
+    };
+}

package/server/dist/core/seedExport.js

@@ -0,0 +1,169 @@
+import { parseSeed } from "./seed.js";
+function offset(clock, created) {
+    return Math.max(0, clock - created);
+}
+const dayOfMonth = (unixSeconds) => new Date(unixSeconds * 1000).getUTCDate();
+export function exportSeed(world, name) {
+    const clock = world.clock;
+    const byAge = (rows) => [...rows].sort((a, b) => a.created_seq - b.created_seq);
+    const lossy = {
+        refunds: world.listObjects("refunds").length,
+        payment_intents: world.listObjects("payment_intents").length,
+        invoiceitems_pending: 0,
+        standalone_charges: 0,
+        canceled_subscriptions: 0,
+        deleted_customers: world.db
+            .prepare("SELECT COUNT(*) AS n FROM objects WHERE resource = 'customers' AND deleted_seq IS NOT NULL")
+            .get().n,
+        events: world.listEvents().length,
+        notes: [],
+    };
+    const seedableEmail = (email) => email && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email) ? email : null;
+    const customers = byAge(world.listObjects("customers")).map((o) => ({
+        id: o.data.id,
+        name: o.data.name ?? "(unnamed)",
+        email: seedableEmail(o.data.email),
+        description: o.data.description,
+        phone: o.data.phone,
+        balance: o.data.balance,
+        metadata: o.data.metadata,
+        created_offset: offset(clock, o.data.created),
+    }));
+    const products = byAge(world.listObjects("products")).map((o) => ({
+        id: o.data.id,
+        name: o.data.name,
+        description: o.data.description,
+        active: o.data.active,
+        metadata: o.data.metadata,
+    }));
+    const exportedPriceIds = new Set();
+    const prices = byAge(world.listObjects("prices")).map((o) => {
+        exportedPriceIds.add(o.data.id);
+        const recurring = o.data.recurring;
+        return {
+            id: o.data.id,
+            product: o.data.product,
+            unit_amount: o.data.unit_amount,
+            currency: o.data.currency,
+            nickname: o.data.nickname,
+            recurring: recurring ? { interval: recurring.interval, interval_count: recurring.interval_count } : null,
+            active: o.data.active,
+            metadata: o.data.metadata,
+        };
+    });
+    const chargesByInvoice = new Map();
+    for (const o of byAge(world.listObjects("charges"))) {
+        if (o.data.status !== "succeeded")
+            continue;
+        const invoiceId = o.data.invoice;
+        if (!invoiceId) {
+            lossy.standalone_charges++;
+            continue;
+        }
+        let charges = chargesByInvoice.get(invoiceId);
+        if (!charges) {
+            charges = [];
+            chargesByInvoice.set(invoiceId, charges);
+        }
+        const refunded = o.data.amount_refunded ?? 0;
+        charges.push({
+            id: o.data.id,
+            amount: o.data.amount,
+            ...(refunded > 0 ? { amount_refunded: refunded } : {}),
+        });
+    }
+    const invoices = byAge(world.listObjects("invoices")).map((o) => {
+        const lines = o.data.lines.data.map((line) => {
+            const price = line.price;
+            const priceId = price && exportedPriceIds.has(price.id) ? price.id : undefined;
+            return {
+                description: line.description ?? null,
+                amount: line.amount,
+                quantity: line.quantity ?? 1,
+                ...(priceId ? { price: priceId } : {}),
+            };
+        });
+        const status = o.data.status;
+        return {
+            id: o.data.id,
+            customer: o.data.customer,
+            currency: o.data.currency,
+            status,
+            lines,
+            charges: status === "paid" ? (chargesByInvoice.get(o.data.id) ?? []) : [],
+            created_offset: offset(clock, o.data.created),
+            metadata: o.data.metadata,
+        };
+    });
+    lossy.invoiceitems_pending = world.listObjects("invoiceitems").filter((o) => o.data.invoice === null).length;
+    let anchorsNotRepresentable = 0;
+    const subscriptions = byAge(world.listObjects("subscriptions"))
+        .filter((o) => {
+        if (o.data.status !== "active") {
+            lossy.canceled_subscriptions++;
+            return false;
+        }
+        return true;
+    })
+        .map((o) => {
+        const item = o.data.items.data[0];
+        const anchor = o.data.billing_cycle_anchor;
+        if (typeof anchor === "number" && dayOfMonth(anchor) !== dayOfMonth(o.data.current_period_start)) {
+            anchorsNotRepresentable++;
+        }
+        return {
+            id: o.data.id,
+            customer: o.data.customer,
+            price: item.price.id,
+            quantity: item.quantity,
+            cancel_at_period_end: o.data.cancel_at_period_end,
+            current_period_start: o.data.current_period_start,
+            current_period_end: o.data.current_period_end,
+            created_offset: offset(clock, o.data.created),
+            metadata: o.data.metadata,
+        };
+    });
+    let ticketCommentsDropped = 0;
+    const tickets = byAge(world.listObjects("tickets")).map((o) => {
+        const comments = o.data.comments ?? [];
+        if (comments.length > 1)
+            ticketCommentsDropped += comments.length - 1;
+        const requester = o.data.requester;
+        return {
+            subject: o.data.subject,
+            body: comments[0]?.body ?? o.data.description,
+            status: o.data.status,
+            priority: o.data.priority,
+            requester: { name: requester.name, email: requester.email },
+            tags: o.data.tags,
+            created_offset: offset(clock, o.data.created),
+        };
+    });
+    const noteIf = (n, what) => {
+        if (n > 0)
+            lossy.notes.push(`${n} ${what} not representable in a seed — dropped`);
+    };
+    if (lossy.refunds > 0) {
+        lossy.notes.push(`${lossy.refunds} refund(s) are not seedable; their totals survive as each charge's amount_refunded`);
+    }
+    noteIf(lossy.payment_intents, "payment intent(s)");
+    noteIf(lossy.standalone_charges, "charge(s) not attached to an invoice");
+    noteIf(lossy.invoiceitems_pending, "pending invoice item(s)");
+    noteIf(lossy.canceled_subscriptions, "canceled subscription(s)");
+    noteIf(lossy.deleted_customers, "deleted customer(s)");
+    noteIf(ticketCommentsDropped, "ticket reply comment(s) (seeds keep the opening message only)");
+    noteIf(anchorsNotRepresentable, "subscription billing anchor day(s) that differ from the current period start (a reimport re-derives the anchor from that period, so later renewal dates move)");
+    noteIf(world.listObjects("customer_balance_transactions").length, "customer balance transaction(s) (the resulting balance survives on the customer; the history does not)");
+    if (lossy.events > 0)
+        lossy.notes.push(`${lossy.events} event(s) are run history, not state — dropped`);
+    const seedDoc = {
+        name,
+        version: 1,
+        epoch: clock,
+        clock_mode: world.clockMode,
+        auto_tick_seconds: world.autoTickSeconds,
+        data: { customers, products, prices, invoices, subscriptions, tickets },
+    };
+    const seed = parseSeed(seedDoc);
+    return { seedDoc, seed, lossy };
+}

package/server/dist/core/seedLoader.js

@@ -0,0 +1,156 @@
+import { ACCOUNT_DEFAULT_CURRENCY, chargeShape, customerShape, invoicePrefixFor, invoiceShape, lineItemShape, priceShape, productShape, refundShape, subscriptionShape, ticketShape, } from "../twin/build.js";
+import { stripeId } from "./prng.js";
+import { addInterval } from "./time.js";
+export function loadSeed(world, seed) {
+    const epoch = seed.epoch;
+    for (const p of seed.data.products) {
+        world.insertObject("products", productShape({
+            id: p.id,
+            created: epoch,
+            name: p.name,
+            description: p.description,
+            active: p.active,
+            metadata: p.metadata,
+        }));
+    }
+    const priceObjects = new Map();
+    for (const p of seed.data.prices) {
+        const obj = priceShape({
+            id: p.id,
+            created: epoch,
+            product: p.product,
+            unit_amount: p.unit_amount,
+            currency: p.currency,
+            nickname: p.nickname,
+            active: p.active,
+            recurring: p.recurring ? { interval: p.recurring.interval, interval_count: p.recurring.interval_count } : null,
+            metadata: p.metadata,
+        });
+        priceObjects.set(p.id, obj);
+        world.insertObject("prices", obj);
+    }
+    for (const c of seed.data.customers) {
+        world.insertObject("customers", customerShape({
+            id: c.id,
+            created: epoch - c.created_offset,
+            name: c.name,
+            email: c.email,
+            description: c.description,
+            phone: c.phone,
+            balance: c.balance,
+            currency: c.balance === 0 ? null : ACCOUNT_DEFAULT_CURRENCY,
+            metadata: c.metadata,
+        }));
+    }
+    for (const inv of seed.data.invoices) {
+        const created = epoch - inv.created_offset;
+        const lines = inv.lines.map((line, idx) => lineItemShape({
+            id: `il_${inv.id.slice(3)}_${idx}`,
+            amount: line.amount * 1,
+            currency: inv.currency,
+            description: line.description,
+            period: { start: created, end: created },
+            price: line.price ? (priceObjects.get(line.price) ?? null) : null,
+            quantity: line.quantity,
+            type: "invoiceitem",
+        }));
+        const obj = invoiceShape({
+            id: inv.id,
+            created,
+            customer: inv.customer,
+            currency: inv.currency,
+            lines,
+            metadata: inv.metadata,
+        });
+        if (inv.status !== "draft") {
+            const seqInCustomer = world.incrCounter(`invnum:${inv.customer}`);
+            obj.number = `${invoicePrefixFor(inv.customer)}-${String(seqInCustomer).padStart(4, "0")}`;
+            obj.status = "open";
+            obj.status_transitions.finalized_at = created;
+        }
+        if (inv.status === "void") {
+            obj.status = "void";
+            obj.status_transitions.voided_at = created;
+        }
+        else if (inv.status === "uncollectible") {
+            obj.status = "uncollectible";
+            obj.status_transitions.marked_uncollectible_at = created;
+            obj.attempted = true;
+            obj.attempt_count = 1;
+        }
+        else if (inv.status === "paid") {
+            obj.status = "paid";
+            obj.paid = true;
+            obj.attempted = true;
+            obj.attempt_count = 1;
+            obj.amount_paid = obj.total;
+            obj.amount_remaining = 0;
+            obj.status_transitions.paid_at = created;
+        }
+        obj.charge = inv.charges[0]?.id ?? null;
+        world.insertObject("invoices", obj);
+        inv.charges.forEach((ch, idx) => {
+            const chargeObj = chargeShape({
+                id: ch.id,
+                created: created + idx,
+                amount: ch.amount ?? obj.total,
+                currency: inv.currency,
+                customer: inv.customer,
+                invoice: inv.id,
+                status: "succeeded",
+                description: `Payment for invoice ${obj.number ?? inv.id}`,
+            });
+            const refunded = ch.amount_refunded ?? 0;
+            if (refunded > 0) {
+                chargeObj.amount_refunded = refunded;
+                chargeObj.refunded = refunded === chargeObj.amount;
+            }
+            world.insertObject("charges", chargeObj);
+            if (refunded > 0)
+                world.insertObject("refunds", refundShape({
+                    id: stripeId("re", `${world.seedHash}:seeded-refund:${ch.id}`, 0),
+                    created: created + idx,
+                    amount: refunded,
+                    currency: inv.currency,
+                    charge: ch.id,
+                    payment_intent: null,
+                    reason: null,
+                    metadata: {},
+                }));
+        });
+    }
+    for (const sub of seed.data.subscriptions) {
+        const created = epoch - sub.created_offset;
+        const priceDef = seed.data.prices.find((p) => p.id === sub.price);
+        const priceObj = priceObjects.get(sub.price);
+        const recurring = priceDef.recurring;
+        const periodStart = sub.current_period_start ?? created;
+        const periodEnd = sub.current_period_end ?? addInterval(periodStart, recurring.interval, recurring.interval_count);
+        world.insertObject("subscriptions", subscriptionShape({
+            id: sub.id,
+            created,
+            customer: sub.customer,
+            currency: priceDef.currency,
+            itemId: `si_${sub.id.slice(4)}`,
+            price: priceObj,
+            quantity: sub.quantity,
+            current_period_start: periodStart,
+            current_period_end: periodEnd,
+            cancel_at_period_end: sub.cancel_at_period_end,
+            metadata: sub.metadata,
+        }));
+    }
+    for (const t of seed.data.tickets) {
+        const ticket = ticketShape({
+            id: String(world.incrCounter("ticket_id")),
+            created: epoch - t.created_offset,
+            subject: t.subject,
+            description: t.body,
+            status: t.status,
+            priority: t.priority,
+            requester: t.requester,
+            tags: t.tags,
+        });
+        world.insertObject("tickets", ticket);
+    }
+}

package/server/dist/core/time.js

@@ -0,0 +1,45 @@
+export function addInterval(unixSeconds, interval, count, anchorDay) {
+    const d = new Date(unixSeconds * 1000);
+    switch (interval) {
+        case "day":
+            d.setUTCDate(d.getUTCDate() + count);
+            break;
+        case "week":
+            d.setUTCDate(d.getUTCDate() + 7 * count);
+            break;
+        case "month":
+            addMonths(d, count, anchorDay);
+            break;
+        case "year":
+            addMonths(d, 12 * count, anchorDay);
+            break;
+    }
+    return Math.floor(d.getTime() / 1000);
+}
+function addMonths(d, months, anchorDay) {
+    const day = isDayOfMonth(anchorDay) ? anchorDay : d.getUTCDate();
+    d.setUTCDate(1);
+    d.setUTCMonth(d.getUTCMonth() + months);
+    const lastDayOfTarget = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 0)).getUTCDate();
+    d.setUTCDate(Math.min(day, lastDayOfTarget));
+}
+function isDayOfMonth(day) {
+    return day !== undefined && Number.isInteger(day) && day >= 1 && day <= 31;
+}
+export function parseDuration(input) {
+    if (typeof input === "number") {
+        if (!Number.isFinite(input) || input <= 0)
+            throw new Error(`invalid duration: ${input}`);
+        return Math.floor(input);
+    }
+    const m = /^(\d+)\s*(s|m|h|d|w)?$/.exec(input.trim());
+    if (!m)
+        throw new Error(`invalid duration: '${input}' (expected e.g. 30d, 12h, 45m, 10s, or seconds)`);
+    const n = Number(m[1]);
+    const unit = m[2] ?? "s";
+    const mult = { s: 1, m: 60, h: 3600, d: 86400, w: 604800 }[unit];
+    const seconds = n * mult;
+    if (seconds <= 0)
+        throw new Error(`invalid duration: '${input}' (must be greater than zero)`);
+    return seconds;
+}