@helix3/helix-cli 0.1.13-helix3.69 → 0.1.13-helix3.71

package/dist/achievement.d.ts

@@ -0,0 +1,123 @@
+/** 2–80 chars, lowercase letters/digits/`_`/`-`, starting alphanumeric. */
+export declare const ACHIEVEMENT_KEY_PATTERN: RegExp;
+/**
+ * WHO may award the badge — the trust marker a player and the platform UI read.
+ * `platform` is first-party code only; it is in the list because the backend
+ * accepts it, not because a world should use it (see `assertUnlockModeForWorld`).
+ */
+export declare const ACHIEVEMENT_UNLOCK_MODES: readonly ["room", "criteria", "platform"];
+export type AchievementUnlockMode = (typeof ACHIEVEMENT_UNLOCK_MODES)[number];
+export declare const ACHIEVEMENT_CRITERIA_SIGNALS: readonly ["datastore", "iwp", "analytics", "playtime"];
+export type AchievementCriteriaSignal = (typeof ACHIEVEMENT_CRITERIA_SIGNALS)[number];
+export declare const ACHIEVEMENT_CRITERIA_OPS: readonly ["gte", "lte", "eq"];
+export type AchievementCriteriaOp = (typeof ACHIEVEMENT_CRITERIA_OPS)[number];
+export declare const ACHIEVEMENT_CRITERIA_METRICS: readonly ["count", "lix"];
+export type AchievementCriteriaMetric = (typeof ACHIEVEMENT_CRITERIA_METRICS)[number];
+/**
+ * The only two documents a `datastore` criteria may read, and WHICH ONE IS THE
+ * TRUST DECISION: `mp:player:{userId}` is the room's flushed persistent
+ * playerVars (room-only writable ⇒ server-authoritative), `player:{userId}` is
+ * the player's own client-written save (forgeable by its owner, accepted
+ * deliberately — it is how a single-player world unlocks anything).
+ */
+export declare const DATA_STORE_CRITERIA_KEY_TEMPLATES: readonly ["player:{userId}", "mp:player:{userId}"];
+export type DataStoreCriteriaKeyTemplate = (typeof DATA_STORE_CRITERIA_KEY_TEMPLATES)[number];
+/** A `datastore` criteria's `field`: a dot-path of letters, digits and underscores. */
+export declare const DATA_STORE_CRITERIA_FIELD_PATTERN: RegExp;
+/** Backend caps (`ACHIEVEMENT_ICON_MAX_BYTES` / `ACHIEVEMENT_MESH_MAX_BYTES` defaults). */
+export declare const ACHIEVEMENT_ICON_MAX_BYTES: number;
+export declare const ACHIEVEMENT_TROPHY_MAX_BYTES: number;
+/** Smallest square an icon can be and still read as a graphic on a plaque. */
+export declare const MIN_ICON_EDGE = 16;
+/**
+ * Per-channel standard deviation below which the backend treats an image as one
+ * flat colour. Not zero — a real icon that has been through lossy encoding
+ * carries a little noise.
+ */
+export declare const MIN_ICON_STDDEV = 1;
+export declare const isAchievementKey: (value: unknown) => value is string;
+/** Content type for the required `image` part — the 2D badge graphic. */
+export declare function iconContentTypeFromExtension(file: string): string;
+/**
+ * What the backend's `assertValidAchievementIcon` checks, mirrored so a
+ * placeholder fails in a second instead of after an upload + a moderation pass.
+ * The two rejections are the two placeholders creators actually send: an image
+ * too small to read, and a single flat colour. Deliberately NOT a quality
+ * judgement — a two-tone glyph or a flat logo on a plate passes.
+ */
+export declare function assertIconLooksReal(bytes: Uint8Array, file: string): Promise<void>;
+export type AchievementCriteria = {
+    signal: AchievementCriteriaSignal;
+    op: AchievementCriteriaOp;
+    value: number;
+    eventName?: string;
+    key?: DataStoreCriteriaKeyTemplate;
+    field?: string;
+    metric?: AchievementCriteriaMetric;
+};
+export type AchievementCriteriaInput = {
+    signal?: string;
+    op?: string;
+    value?: number;
+    eventName?: string;
+    key?: string;
+    field?: string;
+    metric?: string;
+};
+/** True when any criteria field was supplied — i.e. the caller means `criteria`. */
+export declare function hasCriteriaInput(input: AchievementCriteriaInput | undefined): boolean;
+/**
+ * Validate + normalize the criteria the way the backend's `normalizeCriteria`
+ * does, and throw the same failures. Returns the exact object sent as the
+ * multipart `criteria` JSON string — no key the caller did not set.
+ */
+export declare function buildAchievementCriteria(input: AchievementCriteriaInput): AchievementCriteria;
+/** One-line human summary of a stored criteria — the `list` column and the register echo. */
+export declare function formatAchievementCriteria(criteria: AchievementCriteria | null | undefined): string;
+export type AchievementRegistrationInput = {
+    key: string;
+    name: string;
+    description?: string;
+    points?: number;
+    hidden?: boolean;
+    unlockMode?: string;
+    criteria?: AchievementCriteriaInput;
+};
+export type AchievementRegistrationFields = {
+    key: string;
+    name: string;
+    description?: string;
+    points?: number;
+    hidden?: boolean;
+    unlockMode: AchievementUnlockMode;
+    criteria?: AchievementCriteria;
+};
+export type AchievementRegistrationPlan = {
+    fields: AchievementRegistrationFields;
+    warnings: string[];
+};
+/**
+ * Resolve the trust marker. The backend's DTO defaults to `platform` because the
+ * ADMIN path (worldId omitted) is the one that needs it; for a WORLD
+ * registration `platform` is a mislabel — nothing in a world is first-party
+ * code. So this CLI always sends an explicit mode: `criteria` when a condition
+ * was declared, otherwise `room`, the only thing a world can actually award
+ * (the `awardAchievement` rule effect).
+ */
+export declare function resolveUnlockMode(explicit: string | undefined, hasCriteria: boolean): AchievementUnlockMode;
+/**
+ * Build the multipart text fields, applying every local rule first. Keys the
+ * caller did not set are OMITTED rather than sent empty — an empty description
+ * and no description are the same row, and sending "" would overwrite nothing
+ * while looking like intent.
+ */
+export declare function buildAchievementRegistration(input: AchievementRegistrationInput): AchievementRegistrationPlan;
+export type AchievementUpdateInput = {
+    name?: string;
+    description?: string;
+    points?: number;
+    hidden?: boolean;
+    active?: boolean;
+};
+/** Validate a PATCH body locally and refuse an empty one (a no-op round trip that reads as success). */
+export declare function buildAchievementUpdate(input: AchievementUpdateInput): AchievementUpdateInput;

package/dist/achievement.js

@@ -0,0 +1,400 @@
+"use strict";
+// Pure, network-free helpers behind `helix achievement …` — the registration
+// vocabulary (key charset, unlock modes, the closed criteria grammar), the icon
+// sniffing, and the multipart field builder. Split from the HTTP flow in lib.ts
+// for the same reason item.ts is: every rule below is testable without mocking a
+// server, and every one of them costs a round trip if it only fails remotely.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAchievementKey = exports.MIN_ICON_STDDEV = exports.MIN_ICON_EDGE = exports.ACHIEVEMENT_TROPHY_MAX_BYTES = exports.ACHIEVEMENT_ICON_MAX_BYTES = exports.DATA_STORE_CRITERIA_FIELD_PATTERN = exports.DATA_STORE_CRITERIA_KEY_TEMPLATES = exports.ACHIEVEMENT_CRITERIA_METRICS = exports.ACHIEVEMENT_CRITERIA_OPS = exports.ACHIEVEMENT_CRITERIA_SIGNALS = exports.ACHIEVEMENT_UNLOCK_MODES = exports.ACHIEVEMENT_KEY_PATTERN = void 0;
+exports.iconContentTypeFromExtension = iconContentTypeFromExtension;
+exports.assertIconLooksReal = assertIconLooksReal;
+exports.hasCriteriaInput = hasCriteriaInput;
+exports.buildAchievementCriteria = buildAchievementCriteria;
+exports.formatAchievementCriteria = formatAchievementCriteria;
+exports.resolveUnlockMode = resolveUnlockMode;
+exports.buildAchievementRegistration = buildAchievementRegistration;
+exports.buildAchievementUpdate = buildAchievementUpdate;
+// ---------------------------------------------------------------------------
+// The registration vocabulary
+// ---------------------------------------------------------------------------
+//
+// !! MIRROR — KEEP IN LOCKSTEP WITH THE BACKEND !!
+//
+//   AUTHORITY: helix-backend-api → src/achievements/dtos/achievement.dtos.ts
+//              (`KEY_PATTERN`, `CreateAchievementRequestDto`) and
+//              src/database/enums/achievement-unlock-mode.enum.ts +
+//              achievement-criteria.enum.ts. The DSL side mirrors the SAME key
+//              charset in helix-manifest/schema/manifest-v0.3.schema.json
+//              (`awardAchievement.key`) — three copies, one charset.
+//
+// This is a LOCAL FAST PATH, never the authority. It exists so a malformed key
+// or an incoherent criteria fails before an 8 MB icon is uploaded and pushed
+// through moderation — nothing more. Two properties keep a stale copy harmless:
+// the CLI never invents a value (every flag is matched EXACTLY against these
+// lists), and the server is always the last word — its 400 enumerates the real
+// vocabulary and is surfaced verbatim (ApiError.render()). `achievement.spec.ts`
+// pins the lists, so any edit is a reviewed diff rather than silent drift.
+/** 2–80 chars, lowercase letters/digits/`_`/`-`, starting alphanumeric. */
+exports.ACHIEVEMENT_KEY_PATTERN = /^[a-z0-9][a-z0-9_-]{1,79}$/;
+/**
+ * WHO may award the badge — the trust marker a player and the platform UI read.
+ * `platform` is first-party code only; it is in the list because the backend
+ * accepts it, not because a world should use it (see `assertUnlockModeForWorld`).
+ */
+exports.ACHIEVEMENT_UNLOCK_MODES = ['room', 'criteria', 'platform'];
+exports.ACHIEVEMENT_CRITERIA_SIGNALS = ['datastore', 'iwp', 'analytics', 'playtime'];
+exports.ACHIEVEMENT_CRITERIA_OPS = ['gte', 'lte', 'eq'];
+exports.ACHIEVEMENT_CRITERIA_METRICS = ['count', 'lix'];
+/**
+ * The only two documents a `datastore` criteria may read, and WHICH ONE IS THE
+ * TRUST DECISION: `mp:player:{userId}` is the room's flushed persistent
+ * playerVars (room-only writable ⇒ server-authoritative), `player:{userId}` is
+ * the player's own client-written save (forgeable by its owner, accepted
+ * deliberately — it is how a single-player world unlocks anything).
+ */
+exports.DATA_STORE_CRITERIA_KEY_TEMPLATES = ['player:{userId}', 'mp:player:{userId}'];
+/** A `datastore` criteria's `field`: a dot-path of letters, digits and underscores. */
+exports.DATA_STORE_CRITERIA_FIELD_PATTERN = /^[A-Za-z0-9_]+(\.[A-Za-z0-9_]+)*$/;
+/** Backend caps (`ACHIEVEMENT_ICON_MAX_BYTES` / `ACHIEVEMENT_MESH_MAX_BYTES` defaults). */
+exports.ACHIEVEMENT_ICON_MAX_BYTES = 8 * 1024 * 1024;
+exports.ACHIEVEMENT_TROPHY_MAX_BYTES = 16 * 1024 * 1024;
+/** Smallest square an icon can be and still read as a graphic on a plaque. */
+exports.MIN_ICON_EDGE = 16;
+/**
+ * Per-channel standard deviation below which the backend treats an image as one
+ * flat colour. Not zero — a real icon that has been through lossy encoding
+ * carries a little noise.
+ */
+exports.MIN_ICON_STDDEV = 1;
+const isAchievementKey = (value) => typeof value === 'string' && exports.ACHIEVEMENT_KEY_PATTERN.test(value);
+exports.isAchievementKey = isAchievementKey;
+// ---------------------------------------------------------------------------
+// Icon + trophy file sniffing
+// ---------------------------------------------------------------------------
+// The backend sniffs the BYTES (magic numbers) rather than trusting the label,
+// and accepts every raster format `sniffAssetKind` knows. The extension map here
+// only picks the content-type for the multipart part.
+const ICON_CONTENT_TYPES = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.webp': 'image/webp',
+    '.gif': 'image/gif',
+    '.avif': 'image/avif',
+    '.heic': 'image/heic',
+    '.heif': 'image/heif',
+};
+const lowerExtension = (file) => {
+    const base = file.slice(Math.max(file.lastIndexOf('/'), file.lastIndexOf('\\')) + 1);
+    const dot = base.lastIndexOf('.');
+    return dot <= 0 ? '' : base.slice(dot).toLowerCase();
+};
+/** Content type for the required `image` part — the 2D badge graphic. */
+function iconContentTypeFromExtension(file) {
+    const contentType = ICON_CONTENT_TYPES[lowerExtension(file)];
+    if (!contentType) {
+        throw new Error(`unsupported achievement icon type "${lowerExtension(file) || file}" — use png, jpg/jpeg, webp, gif, avif or heic`);
+    }
+    return contentType;
+}
+/**
+ * What the backend's `assertValidAchievementIcon` checks, mirrored so a
+ * placeholder fails in a second instead of after an upload + a moderation pass.
+ * The two rejections are the two placeholders creators actually send: an image
+ * too small to read, and a single flat colour. Deliberately NOT a quality
+ * judgement — a two-tone glyph or a flat logo on a plate passes.
+ */
+async function assertIconLooksReal(bytes, file) {
+    if (bytes.byteLength === 0)
+        throw new Error(`"${file}" is empty`);
+    const sharp = (await Promise.resolve().then(() => __importStar(require('sharp')))).default;
+    let meta;
+    let stats;
+    try {
+        const pipeline = sharp(Buffer.from(bytes));
+        meta = await pipeline.metadata();
+        stats = await pipeline.stats();
+    }
+    catch (err) {
+        throw new Error(`"${file}" could not be decoded as an image (${err instanceof Error ? err.message : String(err)}) — ` +
+            'an achievement needs a real 2D graphic.');
+    }
+    const width = meta.width ?? 0;
+    const height = meta.height ?? 0;
+    if (width < exports.MIN_ICON_EDGE || height < exports.MIN_ICON_EDGE) {
+        throw new Error(`"${file}" is ${width || '?'}x${height || '?'}; an achievement icon must be at least ${exports.MIN_ICON_EDGE}x${exports.MIN_ICON_EDGE}. ` +
+            'Placeholder images are rejected — upload the real artwork.');
+    }
+    // A fully transparent image is blank whatever its colour channels say, so an
+    // alpha-bearing icon is judged on its visible pixels: flatten onto mid grey
+    // (a colour no flat icon is likely to coincide with) and re-measure.
+    if (meta.hasAlpha) {
+        try {
+            const flattened = await sharp(Buffer.from(bytes))
+                .flatten({ background: { r: 128, g: 128, b: 128 } })
+                .png()
+                .toBuffer();
+            stats = await sharp(flattened).stats();
+        }
+        catch {
+            // Fall through to the un-flattened stats rather than fail on a flatten
+            // quirk — the flat-opaque case is still caught below.
+        }
+    }
+    const channels = (stats.channels ?? []).filter(
+    // A constant alpha channel means "every pixel opaque", which is normal, not
+    // evidence of blankness.
+    (_c, i) => !(meta.hasAlpha && i === (stats.channels?.length ?? 0) - 1));
+    const maxStdev = channels.reduce((acc, c) => Math.max(acc, c.stdev ?? 0), 0);
+    if (channels.length > 0 && maxStdev < exports.MIN_ICON_STDDEV) {
+        throw new Error(`"${file}" is a single flat colour with no visible graphic — upload the real 2D artwork for this achievement.`);
+    }
+}
+/** True when any criteria field was supplied — i.e. the caller means `criteria`. */
+function hasCriteriaInput(input) {
+    if (!input)
+        return false;
+    return Object.values(input).some((v) => v !== undefined && v !== '');
+}
+const list = (values) => values.join(', ');
+/**
+ * Validate + normalize the criteria the way the backend's `normalizeCriteria`
+ * does, and throw the same failures. Returns the exact object sent as the
+ * multipart `criteria` JSON string — no key the caller did not set.
+ */
+function buildAchievementCriteria(input) {
+    const signal = input.signal;
+    if (!signal) {
+        throw new Error(`a criteria achievement needs --signal (one of ${list(exports.ACHIEVEMENT_CRITERIA_SIGNALS)})`);
+    }
+    if (!exports.ACHIEVEMENT_CRITERIA_SIGNALS.includes(signal)) {
+        throw new Error(`unknown --signal "${signal}" — supported signals: ${list(exports.ACHIEVEMENT_CRITERIA_SIGNALS)}`);
+    }
+    // The server requires `op`; it has no default of its own to override, and
+    // "reach N" is what nearly every badge means, so defaulting here is a
+    // convenience rather than a guess at server behaviour. It is echoed back in
+    // the register output so a `lte` badge that meant `gte` is visible.
+    const op = input.op ?? 'gte';
+    if (!exports.ACHIEVEMENT_CRITERIA_OPS.includes(op)) {
+        throw new Error(`unknown --op "${op}" — supported ops: ${list(exports.ACHIEVEMENT_CRITERIA_OPS)}`);
+    }
+    if (input.value === undefined)
+        throw new Error('a criteria achievement needs --value (the threshold to compare against)');
+    if (!Number.isFinite(input.value) || input.value < 0) {
+        throw new Error(`--value must be a number >= 0 (got ${input.value})`);
+    }
+    const criteria = {
+        signal: signal,
+        op: op,
+        value: input.value,
+    };
+    if (signal === 'analytics') {
+        if (!input.eventName) {
+            throw new Error('the "analytics" signal needs --event <platform analytics event> (e.g. world_entered) — ' +
+                'a world cannot mint its own event name for criteria; the server rejects an unknown one by name.');
+        }
+        criteria.eventName = input.eventName;
+    }
+    else if (input.eventName) {
+        throw new Error(`--event only applies to the "analytics" signal (--signal is "${signal}")`);
+    }
+    if (signal === 'datastore') {
+        if (!input.key) {
+            throw new Error(`the "datastore" signal needs --criteria-key, one of the two per-user documents: ${exports.DATA_STORE_CRITERIA_KEY_TEMPLATES.map((t) => `"${t}"`).join(' or ')}`);
+        }
+        if (!exports.DATA_STORE_CRITERIA_KEY_TEMPLATES.includes(input.key)) {
+            throw new Error(`unknown --criteria-key "${input.key}" — it must be exactly ${exports.DATA_STORE_CRITERIA_KEY_TEMPLATES.map((t) => `"${t}"`).join(' or ')} ` +
+                '(a numeric sub-key is no longer writable by a session, so `field` selects the value).');
+        }
+        if (!input.field) {
+            throw new Error('the "datastore" signal needs --criteria-field: the dot-path to the number inside that document ' +
+                '(e.g. "stats.summits"; for mp:player:{userId} it names the persistent playerVar directly).');
+        }
+        if (!exports.DATA_STORE_CRITERIA_FIELD_PATTERN.test(input.field)) {
+            throw new Error(`--criteria-field "${input.field}" must be a dot-path of letters, digits and underscores (e.g. "stats.summits")`);
+        }
+        criteria.key = input.key;
+        criteria.field = input.field;
+    }
+    else {
+        if (input.key)
+            throw new Error(`--criteria-key only applies to the "datastore" signal (--signal is "${signal}")`);
+        if (input.field)
+            throw new Error(`--criteria-field only applies to the "datastore" signal (--signal is "${signal}")`);
+    }
+    if (signal === 'iwp') {
+        const metric = input.metric ?? 'count';
+        if (!exports.ACHIEVEMENT_CRITERIA_METRICS.includes(metric)) {
+            throw new Error(`unknown --metric "${metric}" — supported metrics: ${list(exports.ACHIEVEMENT_CRITERIA_METRICS)}`);
+        }
+        criteria.metric = metric;
+    }
+    else if (input.metric) {
+        throw new Error(`--metric only applies to the "iwp" signal (--signal is "${signal}")`);
+    }
+    return criteria;
+}
+/** One-line human summary of a stored criteria — the `list` column and the register echo. */
+function formatAchievementCriteria(criteria) {
+    if (!criteria)
+        return '';
+    const cmp = `${criteria.op} ${criteria.value}`;
+    switch (criteria.signal) {
+        case 'datastore':
+            return `datastore ${criteria.key}.${criteria.field} ${cmp}`;
+        case 'iwp':
+            return `iwp ${criteria.metric ?? 'count'} ${cmp}`;
+        case 'analytics':
+            return `analytics ${criteria.eventName} ${cmp}`;
+        default:
+            return `${criteria.signal} ${cmp}`;
+    }
+}
+/**
+ * Resolve the trust marker. The backend's DTO defaults to `platform` because the
+ * ADMIN path (worldId omitted) is the one that needs it; for a WORLD
+ * registration `platform` is a mislabel — nothing in a world is first-party
+ * code. So this CLI always sends an explicit mode: `criteria` when a condition
+ * was declared, otherwise `room`, the only thing a world can actually award
+ * (the `awardAchievement` rule effect).
+ */
+function resolveUnlockMode(explicit, hasCriteria) {
+    if (explicit !== undefined) {
+        if (!exports.ACHIEVEMENT_UNLOCK_MODES.includes(explicit)) {
+            throw new Error(`unknown --unlock-mode "${explicit}" — supported modes: ${list(exports.ACHIEVEMENT_UNLOCK_MODES)}`);
+        }
+        const mode = explicit;
+        if (mode === 'criteria' && !hasCriteria) {
+            throw new Error('--unlock-mode criteria needs the condition too — pass --signal/--value (and the signal\'s own flag).');
+        }
+        if (mode !== 'criteria' && hasCriteria) {
+            throw new Error(`criteria flags were given, but --unlock-mode is "${mode}" — the backend only reads a criteria when the mode is "criteria".`);
+        }
+        return mode;
+    }
+    return hasCriteria ? 'criteria' : 'room';
+}
+/**
+ * Build the multipart text fields, applying every local rule first. Keys the
+ * caller did not set are OMITTED rather than sent empty — an empty description
+ * and no description are the same row, and sending "" would overwrite nothing
+ * while looking like intent.
+ */
+function buildAchievementRegistration(input) {
+    const warnings = [];
+    const key = input.key?.trim().toLowerCase() ?? '';
+    if (!key)
+        throw new Error('--key is required (the stable slug your rules and criteria name)');
+    if (!(0, exports.isAchievementKey)(key)) {
+        throw new Error(`--key "${key}" must be 2-80 chars of lowercase letters, digits, "_" or "-", starting alphanumeric. ` +
+            'It is the identifier `awardAchievement` names, so treat it as a schema: renaming one needs a fresh registration.');
+    }
+    if (key !== input.key?.trim())
+        warnings.push(`key lowercased to "${key}" — the registry stores it lowercase.`);
+    const name = input.name?.trim() ?? '';
+    if (!name)
+        throw new Error('--name is required (the badge title players see)');
+    if (name.length > 100)
+        throw new Error(`--name is ${name.length} characters; the limit is 100`);
+    const description = input.description?.trim();
+    if (description !== undefined && description.length > 2000) {
+        throw new Error(`--description is ${description.length} characters; the limit is 2000`);
+    }
+    if (input.points !== undefined) {
+        if (!Number.isInteger(input.points) || input.points < 0 || input.points > 1000) {
+            throw new Error(`--points must be a whole number between 0 and 1000 (got ${input.points})`);
+        }
+    }
+    const hasCriteria = hasCriteriaInput(input.criteria);
+    const unlockMode = resolveUnlockMode(input.unlockMode, hasCriteria);
+    const criteria = hasCriteria ? buildAchievementCriteria(input.criteria) : undefined;
+    if (unlockMode === 'platform') {
+        warnings.push('unlockMode "platform" means FIRST-PARTY code awards it — nothing in your world can. ' +
+            'Use "room" (an awardAchievement rule) or "criteria" (the backend measures it) unless you know why you want this.');
+    }
+    if (unlockMode === 'room') {
+        warnings.push(`register first, publish second: a rule awarding "${key}" is a silent no-op until this registration exists.`);
+    }
+    if (criteria?.key === 'player:{userId}') {
+        warnings.push('criteria on "player:{userId}" reads the PLAYER\'s own save — they can write it, so this badge is self-reported. ' +
+            'Use "mp:player:{userId}" (the room\'s flushed persistent playerVars) for anything that must be trustworthy.');
+    }
+    return {
+        fields: {
+            key,
+            name,
+            ...(description ? { description } : {}),
+            ...(input.points !== undefined ? { points: input.points } : {}),
+            ...(input.hidden !== undefined ? { hidden: input.hidden } : {}),
+            unlockMode,
+            ...(criteria ? { criteria } : {}),
+        },
+        warnings,
+    };
+}
+/** Validate a PATCH body locally and refuse an empty one (a no-op round trip that reads as success). */
+function buildAchievementUpdate(input) {
+    const patch = {};
+    if (input.name !== undefined) {
+        const name = input.name.trim();
+        if (!name)
+            throw new Error('--name cannot be empty');
+        if (name.length > 100)
+            throw new Error(`--name is ${name.length} characters; the limit is 100`);
+        patch.name = name;
+    }
+    if (input.description !== undefined) {
+        const description = input.description.trim();
+        if (description.length > 2000)
+            throw new Error(`--description is ${description.length} characters; the limit is 2000`);
+        patch.description = description;
+    }
+    if (input.points !== undefined) {
+        if (!Number.isInteger(input.points) || input.points < 0 || input.points > 1000) {
+            throw new Error(`--points must be a whole number between 0 and 1000 (got ${input.points})`);
+        }
+        patch.points = input.points;
+    }
+    if (input.hidden !== undefined)
+        patch.hidden = input.hidden;
+    if (input.active !== undefined)
+        patch.active = input.active;
+    if (Object.keys(patch).length === 0) {
+        throw new Error('nothing to update — pass at least one of --name, --description, --points, --hidden, --active');
+    }
+    return patch;
+}
+//# sourceMappingURL=achievement.js.map

package/dist/achievement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"achievement.js","sourceRoot":"","sources":["../src/achievement.ts"],"names":[],"mappings":"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"}

package/dist/api.d.ts

@@ -19,6 +19,7 @@ export declare class HelixApi {
     request<T>(method: string, path: string, body?: unknown): Promise<T>;
     requestItem<T>(method: string, path: string, body?: unknown): Promise<T>;
     postMultipart<T>(path: string, form: FormData): Promise<T>;
+    sendMultipart<T>(method: string, path: string, form: FormData): Promise<T>;
     static forCredentials(creds: CliCredentials): HelixApi;
 }
 export declare function uploadToTicket(url: string, body: Buffer, contentType: string, cacheControl?: string): Promise<void>;

package/dist/api.js

@@ -66,8 +66,13 @@ class HelixApi {
     // Blob (globals since Node 18, same undici that already backs `fetch` above),
     // so multipart needs no dependency.
     async postMultipart(path, form) {
+        return this.sendMultipart('POST', path, form);
+    }
+    // The same transport for the multipart endpoints that REPLACE rather than
+    // create (achievement icon/trophy are PUTs).
+    async sendMultipart(method, path, form) {
         const res = await fetch(`${this.baseUrl}${path}`, {
-            method: 'POST',
+            method,
             headers: this.token ? { authorization: `Bearer ${this.token}` } : {},
             body: form,
         });

package/dist/api.js.map

@@ -1 +1 @@
-{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}