summer-engine 4.3.0 → 4.5.0

package/dist/core/capabilities/go-live.js

@@ -0,0 +1,408 @@
+import { createHash } from "node:crypto";
+import { resolveGatewayUrl } from "../config.js";
+import { appendStoreJsonLine } from "../store.js";
+import { createStore, defaultDependencies, listGamesOrThrow, storeToken } from "./publish-build.js";
+import { describeFailure, summarizeChecks } from "./store-checks.js";
+import { BuildToolError } from "./summer-bundle.js";
+/**
+ * summer_go_live: take a store game live for players over the same creator
+ * store routes Studio uses (PSE /api/creator-store/* -> /v1/management/*),
+ * then watch until players get it or a check fails.
+ *
+ *   GET  games/{g}, games/{g}/revisions, games/{g}/approval      the page and Summer's decision
+ *   GET  games/{g}/build-publications, store/versions             the uploads and their checks
+ *   GET  games/{g}/environments/env_production (+ releases/{id})  what players get now
+ *   POST build-publications/{p}:publish                           a preview Build, made ready for players
+ *   POST environments/env_production/release-drafts (+ :publish)  release the Build to players
+ *   POST revisions/{r}:publish (If-Match)                         publish the store page
+ *
+ * An agent credential may call the three :publish actions without an owner
+ * approval while the person's Agent permissions allow Publish (the platform
+ * default; summer-platform internal/management/agent_gate.go). The platform
+ * still runs every automated check, and today it holds a game's first launch
+ * for Summer's review; that hold is reported as Summer's, never as a step the
+ * creator waits on or fixes, because staff review is becoming a step after
+ * launch. Calling again continues: the same idempotency keys replay what was
+ * already asked, so nothing is requested twice.
+ */
+const ENVIRONMENT = "env_production";
+const DEFAULT_WAIT_SECONDS = 600;
+const POLL_MS = 10_000;
+/** Client platforms a bundle Build is released to (web ships as a store version). */
+const RELEASE_PLATFORMS = ["ios", "android", "macos", "windows"];
+const INTAKE_DONE = ["preview_ready", "published", "ready", "succeeded"];
+const SENT_BACK = ["CHANGES_REQUESTED", "REJECTED"];
+const PUBLISHABLE = ["DRAFT", "SUBMITTED", "VERIFYING", "APPROVED"];
+const seg = encodeURIComponent;
+/** The creator store proxy sends this header on as If-Match. */
+const REVISION_HEADER = "x-summer-revision";
+/** Text the store page must have before it can be published (summer-platform internal/creatorcatalog). */
+const PAGE_FIXES = {
+    name: "Give the page a title: store.update_listing title.",
+    description: "Write the short description: store.update_listing desktop.description.",
+    supportedPlatforms: "List the platforms players can play on: store.update_listing targets.",
+    contentRating: "Pick a content rating (everyone, everyone10Plus or teen): store.update_listing contentRating.",
+    contentDescriptors: "Answer the content descriptors, an empty list when none apply: store.update_listing contentDescriptors.",
+    mediaSlots: "An art slot holds the wrong kind or shape of image: fix it with store.set_art (the store-art skill has each slot's size).",
+    media: "An image or video is still being checked or was refused: wait a minute, then read store.get_listing and replace a refused one with store.set_art.",
+};
+const text = (value) => (typeof value === "string" && value.trim() ? value : null);
+function keyOf(gameId, ...parts) {
+    return createHash("sha256").update(["go-live", gameId, ...parts].join(":")).digest("hex");
+}
+async function optional(read) {
+    try {
+        return await read();
+    }
+    catch (error) {
+        if (error instanceof BuildToolError && (error.status === 404 || error.code === "store_not_found"))
+            return null;
+        throw error;
+    }
+}
+function pageOf(revision) {
+    if (!revision || typeof revision.revisionId !== "string")
+        return null;
+    const name = text(revision.presentation?.name) ?? text(revision.name);
+    const description = text(revision.presentation?.description) ?? text(revision.description);
+    const platforms = Array.isArray(revision.supportedPlatforms) ? revision.supportedPlatforms.filter((value) => typeof value === "string") : [];
+    const problems = [];
+    if (!name)
+        problems.push({ field: "name", fix: PAGE_FIXES.name });
+    if (!description)
+        problems.push({ field: "description", fix: PAGE_FIXES.description });
+    if (!platforms.length)
+        problems.push({ field: "supportedPlatforms", fix: PAGE_FIXES.supportedPlatforms });
+    if (!text(revision.contentRating))
+        problems.push({ field: "contentRating", fix: PAGE_FIXES.contentRating });
+    if (revision.contentDescriptors == null)
+        problems.push({ field: "contentDescriptors", fix: PAGE_FIXES.contentDescriptors });
+    return { revisionId: revision.revisionId, state: String(revision.state ?? ""), etag: Number(revision.etagRevision ?? 0), name, platforms, problems };
+}
+function newest(items, order) {
+    return items.reduce((best, item) => (!best || order(item) > order(best) ? item : best), null);
+}
+const time = (value) => (typeof value === "string" ? Date.parse(value) || 0 : 0);
+/** The players' side of a Build: on which platforms the active release serves it. */
+function livePlatformsOf(release, buildId) {
+    if (!release || !buildId || release.status !== "active" || !Array.isArray(release.targets))
+        return [];
+    return release.targets.filter((target) => target?.buildId === buildId).map((target) => String(target.target));
+}
+async function read(store, gameId, publicationId) {
+    const game = await store.call("GET", `games/${seg(gameId)}`);
+    const [revisions, approval, publications, versions, environment] = await Promise.all([
+        store.call("GET", `games/${seg(gameId)}/revisions?limit=20`),
+        optional(() => store.call("GET", `games/${seg(gameId)}/approval`)),
+        store.call("GET", `games/${seg(gameId)}/build-publications`),
+        optional(() => store.call("GET", `games/${seg(gameId)}/store/versions`)),
+        optional(() => store.call("GET", `games/${seg(gameId)}/environments/${ENVIRONMENT}`)),
+    ]);
+    const page = pageOf(newest(revisions.items ?? [], (item) => Number(item.sequence ?? 0)));
+    const release = environment?.activeReleaseId
+        ? await optional(() => store.call("GET", `games/${seg(gameId)}/environments/${ENVIRONMENT}/releases/${seg(String(environment.activeReleaseId))}`))
+        : null;
+    const exported = (publications.items ?? []).filter((item) => item?.source?.kind === "exported-game" || item?.source?.kind === undefined);
+    let chosen = null;
+    if (publicationId) {
+        chosen = await store.call("GET", `games/${seg(gameId)}/build-publications/${seg(publicationId)}`);
+    }
+    else {
+        const candidate = newest(exported.filter((item) => !["failed", "cancelled"].includes(item.state)), (item) => time(item.createdAt ?? item.updatedAt));
+        // The list may leave the client pack out: read the chosen one in full.
+        chosen = candidate ? await store.call("GET", `games/${seg(gameId)}/build-publications/${seg(String(candidate.id ?? candidate.publicationId))}`) : null;
+    }
+    let build = null;
+    if (chosen) {
+        const buildId = text(chosen.buildId);
+        const failed = chosen.state === "failed" || chosen.state === "cancelled";
+        build = {
+            publicationId: String(chosen.id ?? chosen.publicationId ?? publicationId),
+            buildId,
+            version: text(chosen.clientVersion) ?? text(chosen.version),
+            state: String(chosen.state ?? ""),
+            hosted: chosen.build?.executionMode ? chosen.build.executionMode === "hosted" : null,
+            checks: summarizeChecks(chosen),
+            livePlatforms: livePlatformsOf(release, buildId),
+            ...(failed ? { failure: describeFailure(text(chosen.errorCode), text(chosen.errorMessage)) } : {}),
+        };
+    }
+    const versionRows = (versions?.items ?? []).map((item) => ({
+        platform: String(item.platform ?? ""),
+        status: String(item.status ?? ""),
+        ...(text(item.rejectionReason) ? { reason: String(item.rejectionReason) } : {}),
+    }));
+    return { game, page, approval, build, environment, release, versions: versionRows };
+}
+/** What the platform is waiting on, said so an agent never tells a creator to wait for a review. */
+function summerHold(approval) {
+    const state = text(approval?.state) ?? "unknown";
+    return {
+        by: "summer",
+        approvalState: state,
+        message: "Every automated check passed. The platform still holds a game's first launch on Summer's side; there is nothing to fix and nothing to ask for. " +
+            "This request stays in place and goes live by itself once the platform releases it (Summer's review is becoming a step after launch).",
+    };
+}
+function sentBack(snapshot) {
+    const review = snapshot.approval?.latestReview;
+    if (!snapshot.page || !SENT_BACK.includes(snapshot.page.state))
+        return null;
+    return {
+        ok: true,
+        status: "needs_changes",
+        gameId: snapshot.game.id ?? null,
+        page: { revisionId: snapshot.page.revisionId, state: snapshot.page.state },
+        decision: review ? { decision: review.decision ?? null, decidedBy: review.decidedBy ?? null, feedback: text(review.feedback) } : null,
+        next: text(review?.feedback)
+            ? "Fix every point in decision.feedback with store.update_listing (it starts a new draft), then call summer_go_live again."
+            : "Summer sent the page back without written feedback: tell the owner and ask what to change; then edit with store.update_listing and call summer_go_live again.",
+    };
+}
+/** Which client platforms of the Build passed and may be released, and which did not. */
+function releasable(build) {
+    const passed = build.checks.checks.filter((check) => check.state === "passed" && RELEASE_PLATFORMS.includes(check.platform)).map((check) => check.platform);
+    return { targets: passed, held: build.checks.checks.filter((check) => check.state === "failed") };
+}
+function view(snapshot) {
+    const { page, build } = snapshot;
+    return {
+        game: { gameId: snapshot.game.id ?? null, name: text(snapshot.game.name) },
+        page: page ? { revisionId: page.revisionId, state: page.state, name: page.name, platforms: page.platforms, live: page.state === "PUBLISHED" } : null,
+        build: build
+            ? {
+                publicationId: build.publicationId,
+                version: build.version,
+                state: build.state,
+                checksState: build.failure ? "failed" : build.checks.state,
+                checks: build.checks.checks,
+                livePlatforms: build.livePlatforms,
+                ...(build.failure ? { failure: build.failure } : {}),
+            }
+            : null,
+        downloads: snapshot.versions,
+        approvalState: text(snapshot.approval?.state),
+    };
+}
+function isLive(snapshot) {
+    if (snapshot.page?.state !== "PUBLISHED")
+        return false;
+    if (!snapshot.build)
+        return true;
+    const { targets } = releasable(snapshot.build);
+    return targets.length > 0 && targets.every((platform) => snapshot.build.livePlatforms.includes(platform));
+}
+/** Refusals no publish call can get past: each is a fix for the creator. */
+function blockers(snapshot) {
+    const out = [];
+    if (!snapshot.page)
+        out.push({ field: "store page", fix: "This game has no store page yet: create it with games.create, or fill it with store.update_listing." });
+    for (const problem of snapshot.page?.problems ?? [])
+        out.push(problem);
+    const build = snapshot.build;
+    if (build?.failure)
+        out.push({ field: "build", ...build.failure });
+    if (build?.checks.packFailure)
+        out.push({ field: "build", ...build.checks.packFailure });
+    if (build && !build.failure && build.checks.state !== "checking" && releasable(build).targets.length === 0) {
+        out.push({ field: "build", code: "no_platform_passed", fix: "No phone or desktop platform of this Build passed its checks. Apply each check's fix, export again and upload with summer_publish_build." });
+        for (const check of releasable(build).held)
+            out.push({ field: `build ${check.platform}`, ...check });
+    }
+    for (const version of snapshot.versions.filter((row) => row.status === "rejected")) {
+        out.push({ field: `download ${version.platform}`, code: "store_version_rejected", ...(version.reason ? { message: version.reason } : {}), fix: "Fix what the reason names, export the download again and upload it with summer_publish_build." });
+    }
+    return out;
+}
+function permissionRefused() {
+    return {
+        ok: true,
+        status: "needs_permission",
+        next: "Nothing went live: the person's Agent permissions do not let this agent publish. Ask them to turn on Publish (Studio > Agent permissions) and call summer_go_live again, " +
+            "or send them the approval link store.publish returns.",
+    };
+}
+/** Make the Build ready for players and ask for its release; returns a hold when the platform declines. */
+async function releaseBuild(store, gameId, snapshot, deps, deadline) {
+    const build = snapshot.build;
+    const { targets } = releasable(build);
+    if (!build.buildId || !targets.length || targets.every((platform) => build.livePlatforms.includes(platform)))
+        return null;
+    const publicationPath = `games/${seg(gameId)}/build-publications/${seg(build.publicationId)}`;
+    let detail = await store.call("GET", `games/${seg(gameId)}/builds/${seg(build.buildId)}`);
+    if (detail.status === "preview_ready") {
+        try {
+            await store.call("POST", `${publicationPath}:publish`, { body: {}, key: keyOf(gameId, "prepare", build.publicationId) });
+        }
+        catch (error) {
+            if (error instanceof BuildToolError && error.status === 409 && error.code === "deployment_not_actionable")
+                return summerHold(snapshot.approval);
+            throw error;
+        }
+        while (detail.status !== "ready" && deps.now() < deadline) {
+            await deps.sleep(POLL_MS);
+            detail = await store.call("GET", `games/${seg(gameId)}/builds/${seg(build.buildId)}`);
+            if (detail.status === "failed")
+                throw new BuildToolError("build_failed", "Summer could not prepare this Build for players.", "Recovery: export again and upload with a new clientVersion.");
+        }
+        if (detail.status !== "ready")
+            return { by: "summer", message: "Summer is preparing the Build for players." };
+    }
+    const environment = snapshot.environment;
+    if (environment?.desiredReleaseId && environment.desiredReleaseId !== environment.activeReleaseId)
+        return null; // a release is already on its way
+    const pack = (await store.call("GET", publicationPath)).clientPackage ?? {};
+    const selection = {};
+    const hosted = (detail.executionMode ?? (build.hosted ? "hosted" : "standalone")) === "hosted";
+    if (hosted)
+        selection.server = { buildId: build.buildId, qualificationId: "" };
+    for (const platform of targets) {
+        const check = (pack.verifications ?? []).find((row) => row.platform === platform && row.state === "ready" && row.qualificationId);
+        if (check)
+            selection[platform] = { buildId: build.buildId, uploadId: String(pack.id), qualificationId: String(check.qualificationId) };
+    }
+    const base = `${environment?.revision ?? 0}:${environment?.activeReleaseId ?? ""}`;
+    const draft = await store.call("POST", `games/${seg(gameId)}/environments/${ENVIRONMENT}/release-drafts`, {
+        body: { title: build.version ?? "Release", notes: "", targets: selection },
+        key: keyOf(gameId, "draft", build.publicationId, base),
+    });
+    await store.call("POST", `games/${seg(gameId)}/environments/${ENVIRONMENT}/release-drafts/${seg(String(draft.id))}:publish`, {
+        body: { targets: Object.keys(selection), replaceTargets: true },
+        key: keyOf(gameId, "release", build.publicationId, base),
+        // The proxy forwards x-summer-revision as If-Match (it passes no other header but idempotency-key).
+        headers: { [REVISION_HEADER]: `"${draft.revision}"` },
+    });
+    return null;
+}
+/** Publish the store page revision; returns a result to answer with when the platform refuses it. */
+async function publishPage(store, gameId, snapshot) {
+    const page = snapshot.page;
+    if (!PUBLISHABLE.includes(page.state))
+        return null;
+    try {
+        await store.call("POST", `games/${seg(gameId)}/revisions/${seg(page.revisionId)}:publish`, {
+            body: {},
+            key: keyOf(gameId, "page", page.revisionId),
+            headers: { [REVISION_HEADER]: `"game-revision:${page.revisionId}:${page.etag}"` },
+        });
+    }
+    catch (error) {
+        if (!(error instanceof BuildToolError))
+            throw error;
+        // Already asked (a replay, or a request in flight): keep watching it.
+        if (error.status === 409 && ["publication_in_progress", "idempotency_conflict"].includes(error.code))
+            return null;
+        if (error.code === "owner_approval_required")
+            return permissionRefused();
+        if (error.code === "store_page_incomplete") {
+            const missing = Array.isArray(error.detail?.missing) ? error.detail.missing : [];
+            return {
+                ok: true,
+                status: "blocked",
+                gameId,
+                failures: missing.map((field) => ({ field, fix: PAGE_FIXES[field] ?? "Finish this field of the store page with store.update_listing." })),
+                next: "Fix each failure, then call summer_go_live again.",
+            };
+        }
+        if (error.code === "playable_release_required") {
+            return {
+                ok: true,
+                status: "blocked",
+                gameId,
+                failures: [{ field: "build", code: error.code, fix: "A released page needs a build players can play on a platform it lists: upload one with summer_publish_build (or set release stage coming_soon with store.update_listing), then call summer_go_live again." }],
+            };
+        }
+        throw error;
+    }
+    return null;
+}
+export async function goLive(input, overrides = {}) {
+    const deps = { ...defaultDependencies, ...overrides };
+    const gameId = input.gameId?.trim();
+    if (!gameId)
+        return listGamesOrThrow(deps);
+    const store = createStore(await resolveGatewayUrl(), await storeToken(deps), deps);
+    const deadline = deps.now() + Math.min(Math.max(input.waitSeconds ?? DEFAULT_WAIT_SECONDS, 0), 1800) * 1000;
+    let snapshot = await read(store, gameId, input.publicationId);
+    const back = sentBack(snapshot);
+    if (back)
+        return back;
+    if (isLive(snapshot))
+        return { ok: true, status: "live", ...view(snapshot), next: "Players get it now. Confirm it as a player on summer.games and in the Summer Games apps." };
+    const stops = blockers(snapshot);
+    if (stops.length)
+        return { ok: true, status: "blocked", ...view(snapshot), failures: stops, next: "Fix each failure, then call summer_go_live again." };
+    if (input.confirm !== true) {
+        return {
+            ok: true,
+            status: "confirmation_required",
+            ...view(snapshot),
+            next: "Show the user this exact game, store page and build (version and platforms). Only after they approve going live, call again with confirm=true. Nothing was published.",
+        };
+    }
+    const audit = { at: new Date(deps.now()).toISOString(), operation: "go_live", face: input.face, gameId, revisionId: snapshot.page.revisionId, publicationId: snapshot.build?.publicationId ?? null };
+    await appendStoreJsonLine("creator-audit.jsonl", { ...audit, outcome: "started" });
+    let hold = null;
+    try {
+        // The Build first: a released page needs a playable release (or one on its way).
+        while (snapshot.build && snapshot.build.checks.state === "checking" && deps.now() < deadline) {
+            await deps.sleep(POLL_MS);
+            snapshot = await read(store, gameId, snapshot.build.publicationId);
+        }
+        if (snapshot.build?.checks.state === "checking") {
+            return { ok: true, status: "waiting", waitingOn: "automated_checks", ...view(snapshot), next: "Summer's automated checks are still running. Call summer_go_live again with confirm=true to keep going; nothing is asked twice." };
+        }
+        const stopped = blockers(snapshot);
+        if (stopped.length)
+            return { ok: true, status: "blocked", ...view(snapshot), failures: stopped, next: "Fix each failure, then call summer_go_live again." };
+        if (snapshot.build)
+            hold = await releaseBuild(store, gameId, snapshot, deps, deadline);
+        const refused = await publishPage(store, gameId, snapshot);
+        if (refused)
+            return { ...view(snapshot), ...refused };
+    }
+    catch (error) {
+        if (error instanceof BuildToolError && error.code === "owner_approval_required")
+            return { ...view(snapshot), ...permissionRefused() };
+        await appendStoreJsonLine("creator-audit.jsonl", { ...audit, outcome: "failed", code: error instanceof BuildToolError ? error.code : "go_live_failed" });
+        throw error;
+    }
+    await appendStoreJsonLine("creator-audit.jsonl", { ...audit, outcome: "requested" });
+    // Watch until players get it, a check fails or the wait ends.
+    for (;;) {
+        snapshot = await read(store, gameId, snapshot.build?.publicationId);
+        const again = sentBack(snapshot);
+        if (again)
+            return again;
+        if (isLive(snapshot)) {
+            await appendStoreJsonLine("creator-audit.jsonl", { ...audit, outcome: "live" });
+            const held = snapshot.build ? releasable(snapshot.build).held : [];
+            return {
+                ok: true,
+                status: "live",
+                ...view(snapshot),
+                ...(held.length ? { notReleased: held } : {}),
+                next: held.length
+                    ? `Live. ${held.map((check) => check.platform).join(", ")} did not pass its checks and is not released: apply each fix and upload a new version.`
+                    : "Live: players get it now. Confirm it as a player on summer.games and in the Summer Games apps.",
+            };
+        }
+        const failed = blockers(snapshot);
+        if (failed.length)
+            return { ok: true, status: "blocked", ...view(snapshot), failures: failed, next: "Fix each failure, then call summer_go_live again." };
+        if (deps.now() >= deadline)
+            break;
+        await deps.sleep(POLL_MS);
+    }
+    const approved = text(snapshot.approval?.state) === "APPROVED";
+    return {
+        ok: true,
+        status: "waiting",
+        waitingOn: approved ? "activation" : "summer",
+        ...view(snapshot),
+        ...(approved ? {} : { hold: hold ?? summerHold(snapshot.approval) }),
+        next: approved
+            ? "The platform is activating it. Call summer_go_live again with confirm=true to keep watching; nothing is asked twice."
+            : "Nothing to fix. Call summer_go_live again with confirm=true to keep watching; it reports the moment players get it.",
+    };
+}

package/dist/core/capabilities/image-generation.d.ts

@@ -16,21 +16,21 @@ export declare const imageGenerationArgsSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     prompt: string;
     style: string;
-    width?: number | undefined;
-    height?: number | undefined;
-    options?: Record<string, any> | undefined;
     out?: string | undefined;
     model?: string | undefined;
+    options?: Record<string, any> | undefined;
+    width?: number | undefined;
+    height?: number | undefined;
     referenceImageUrl?: string | undefined;
     removeBackground?: boolean | undefined;
     aspectRatio?: "1:1" | "16:9" | "9:16" | "4:3" | "3:4" | "3:2" | "2:3" | "5:4" | "4:5" | "21:9" | undefined;
 }, {
     prompt: string;
-    width?: number | undefined;
-    height?: number | undefined;
-    options?: Record<string, any> | undefined;
     out?: string | undefined;
     model?: string | undefined;
+    options?: Record<string, any> | undefined;
+    width?: number | undefined;
+    height?: number | undefined;
     style?: string | undefined;
     referenceImageUrl?: string | undefined;
     removeBackground?: boolean | undefined;

package/dist/core/capabilities/item-manifest.d.ts

@@ -0,0 +1,92 @@
+/**
+ * summer.items.json: the Game's items, keyed by creator slug, next to
+ * summer.build.json in the project root and committed with the game.
+ *
+ * It names no Game, environment or platform id: the same file syncs to the
+ * staging Game and to the production Game, and the slug (the creator key the
+ * game's code uses, e.g. "emote_ponder") is what identifies an item in both.
+ * The gameId comes with each sync call, as with summer_publish_build.
+ *
+ *   {
+ *     "schema": "summer.items/v1",
+ *     "items": [
+ *       {
+ *         "slug": "emote_ponder",
+ *         "name": "Ponder",
+ *         "description": "Strike a thoughtful pose.",
+ *         "class": "COSMETIC",
+ *         "cosmetic": { "familyId": "emote", "variantKey": "ponder" },
+ *         "tags": ["emote"],
+ *         "ownership": "OWNED",
+ *         "priceSparks": 150,
+ *         "media": ["art/items/emote_ponder.png"]
+ *       }
+ *     ]
+ *   }
+ *
+ * The checks here are the platform's own create rules (management API
+ * item-definitions), so a file that passes is not refused for its shape.
+ */
+export declare const ITEMS_MANIFEST_FILE = "summer.items.json";
+export declare const ITEMS_MANIFEST_SCHEMA = "summer.items/v1";
+/** The platform's slug rule: 1-64 characters, lowercase, words joined by one ".", "_" or "-". */
+export declare const ITEM_SLUG: RegExp;
+export declare const ITEM_CLASSES: readonly ["STANDARD", "COSMETIC"];
+export declare const OWNERSHIP_MODES: readonly ["INSTANCE", "QUANTITY"];
+export declare const OWNERSHIP_POLICIES: readonly ["SOULBOUND", "OWNED", "MARKETABLE"];
+export declare const MEDIA_TYPES: Record<string, {
+    kind: "IMAGE" | "MODEL_3D";
+    contentType: string;
+    maxBytes: number;
+}>;
+export interface ManifestItem {
+    slug: string;
+    name: string;
+    description: string;
+    class: (typeof ITEM_CLASSES)[number];
+    cosmetic?: {
+        familyId: string;
+        variantKey: string;
+    };
+    tags: string[];
+    ownershipMode: (typeof OWNERSHIP_MODES)[number];
+    maxOwned?: number;
+    ownership: (typeof OWNERSHIP_POLICIES)[number];
+    consumable: boolean;
+    /** Lifetime mint limit; absent is unlimited. */
+    supply?: number;
+    /** Base price in Sparks. Absent: this file sets no price (a new item is not sold; an existing price stays). */
+    priceSparks?: number;
+    backgroundColor?: string;
+    /** Project-relative paths, in store order. */
+    media: string[];
+}
+export interface ItemsManifest {
+    path: string;
+    project: string;
+    items: ManifestItem[];
+}
+/** The platform behavior a manifest entry declares (item-definitions create body). */
+export declare function behaviorOf(item: ManifestItem): {
+    cosmetic?: {
+        familyId: string;
+        variantKey: string;
+    } | undefined;
+    rights: {
+        policy: "SOULBOUND" | "OWNED" | "MARKETABLE";
+        consumable: boolean;
+        directTransferAllowed: boolean;
+        giftingAfterOwnershipAllowed: boolean;
+        publicResalePolicyEligible: boolean;
+    };
+    issuance: {
+        serverMintAllowed: boolean;
+        supportGrantAllowed: boolean;
+    };
+    maxOwned?: number | undefined;
+    class: "STANDARD" | "COSMETIC";
+    ownershipMode: "INSTANCE" | "QUANTITY";
+};
+/** Parse and check a manifest document; every problem is reported at once. */
+export declare function parseItemsManifest(project: string, document: unknown, path?: string): ItemsManifest;
+export declare function readItemsManifest(project: string, file?: string): Promise<ItemsManifest>;