@flow-industries/id 0.21.1 → 0.22.0

package/dist/sdk/types/settings.d.ts

@@ -0,0 +1,162 @@
+import type { RawValue } from "../json";
+import type { CosmeticItem, CosmeticMaterial, CosmeticSlot, EquipRegion, SettingsConflict } from "./cosmetics";
+export interface PaintDescriptor {
+    key: string;
+    group: string;
+    label: string;
+    description?: string;
+    type: "paint";
+    default: string;
+    options: {
+        value: string;
+        label: string;
+    }[];
+    /**
+     * The item this colour lands on, and the material on it that is recoloured.
+     * Both travel on the descriptor rather than being read back out of the key: a
+     * form grouping its pickers by item, and a renderer deciding which surface a
+     * colour applies to, each want one of them, and neither should be taking a
+     * key apart to get it.
+     */
+    cosmetic: string;
+    material: CosmeticMaterial;
+}
+export interface CosmeticOffer extends CosmeticItem {
+    /**
+     * Every equip region this item cannot share a body with — its own, plus
+     * everything they overlap. Another item is blocked by this one exactly when
+     * its `regions` intersect this list, so a client tests a set instead of
+     * re-implementing the rule.
+     */
+    conflicts: readonly EquipRegion[];
+    /**
+     * The colour pickers this item brings once it is worn: the SAME descriptors
+     * {@link SurfaceRegistry.derived} emits for it, from the same builder, so a
+     * client rendering its draft and a client reading the derived list for a
+     * saved loadout draw the same rows.
+     *
+     * An offer, not a setting. A colour is a setting the player HAS only while
+     * its item is equipped — that is what {@link sanitize} prunes on — and
+     * nothing here widens the stored blob or the write path.
+     */
+    paint: readonly PaintDescriptor[];
+}
+export type SettingDescriptor = {
+    key: string;
+    group: string;
+    label: string;
+    description?: string;
+    type: "number";
+    default: number;
+    min: number;
+    max: number;
+    step: number;
+} | {
+    key: string;
+    group: string;
+    label: string;
+    description?: string;
+    type: "boolean";
+    default: boolean;
+} | {
+    key: string;
+    group: string;
+    label: string;
+    description?: string;
+    type: "enum";
+    default: string;
+    options: {
+        value: string;
+        label: string;
+    }[];
+} | {
+    key: string;
+    group: string;
+    label: string;
+    description?: string;
+    /** Free text with a shape, for values no fixed option list can cover —
+     * a Discord snowflake, a channel id. `pattern` is a source string (not a
+     * RegExp) so the descriptor stays JSON-serializable for the schema
+     * endpoint the settings form reads. */
+    type: "text";
+    default: string;
+    maxLength: number;
+    pattern?: string;
+} | {
+    key: string;
+    group: string;
+    label: string;
+    description?: string;
+    /** One cosmetic slot: the stored value is a catalog cosmetic id, or ""
+     * for nothing equipped. `items` is the catalog projection the customizer
+     * reads off the schema endpoint so it can render a draft loadout with no
+     * catalog data of its own — which picks would collide, and which colour
+     * pickers a pick brings with it. UX only; the conflict rule is enforced
+     * on save, and a draft is never a claim about what may be saved.
+     *
+     * The default is an item id, not "": a player who has never dressed is
+     * wearing the starting outfit, and saying so here is what lets "" mean
+     * the one thing it should — a player who chose to wear nothing there. */
+    type: "cosmetic";
+    default: string;
+    slot: CosmeticSlot;
+    /**
+     * Whether an avatar may go with this slot empty. False is the slot a
+     * client offers a "None" chip for; true is one where `""` is refused on
+     * save. Projected here rather than restated in the customizer for the
+     * reason {@link CosmeticOffer.conflicts} is: the rule belongs to the
+     * slot, and a second hand-maintained copy of it goes quiet (AUTH-222).
+     */
+    required: boolean;
+    items: readonly CosmeticOffer[];
+} | PaintDescriptor;
+export type StoredSettings = Record<string, RawValue>;
+export type Settings = Record<string, number | boolean | string>;
+export interface SettingsMigration {
+    to: number;
+    up: (stored: StoredSettings) => StoredSettings;
+}
+export interface SurfaceRegistry {
+    /**
+     * Bumped only when a setting in this surface is renamed or retyped. A stored
+     * blob stamps the version it was last normalized to; {@link normalize} walks
+     * an old blob up to this version on read, preserving the user's chosen value
+     * instead of dropping it. Adding or removing a setting does NOT bump it.
+     */
+    version: number;
+    settings: readonly SettingDescriptor[];
+    /**
+     * The steps {@link normalize} walks an out-of-date blob up through, in
+     * ascending {@link SettingsMigration.to} order. A surface that has never
+     * renamed anything has none, and its blobs need no walk.
+     */
+    migrations?: readonly SettingsMigration[];
+    /**
+     * Enum defaults are drawn from the option list seeded by the user id instead
+     * of the descriptor default, so every unsaved user gets their own stable
+     * random pick — identical on every read and on every surface that reads it.
+     */
+    randomDefaults?: boolean;
+    /**
+     * Cross-field rule for the whole surface, evaluated on the MERGED blob by
+     * the one settings write path. Per-descriptor {@link sanitize} cannot
+     * express it: an equip-region collision is a relation between two keys, not
+     * a property of either. Living on the surface rather than in a route is what
+     * makes it impossible for a second write path to skip.
+     */
+    validate?: (settings: Settings) => SettingsConflict | null;
+    /**
+     * The settings this surface has only because of what is stored in it — the
+     * appearance surface's colour pickers for the cosmetics a player is
+     * currently wearing.
+     *
+     * Derived rather than fixed is the whole mechanism: a setting that exists
+     * only while its cosmetic is equipped is dropped by {@link sanitize} the
+     * moment the cosmetic is not, so unequipping an item takes its colour with
+     * it and re-equipping cannot resurrect a colour the player never chose.
+     *
+     * Reads the surface's FIXED settings only, never its own output, so the
+     * descriptor list is resolved in one pass and cannot recurse.
+     */
+    derived?: (settings: Settings) => readonly SettingDescriptor[];
+}

package/dist/sdk/types/xp.d.ts

@@ -212,3 +212,11 @@ export interface CurrentAction {
     since: string;
     subject?: string;
 }
+export interface ActionTimelineEvent {
+    kind: ActionEventKind;
+    at: Date;
+}
+export interface ActionDurations {
+    accruedSeconds: number;
+    focusedSeconds: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flow-industries/id",
-  "version": "0.21.1",
+  "version": "0.22.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -50,6 +50,10 @@
     "./start/server": {
       "types": "./dist/sdk/start/server.d.ts",
       "import": "./dist/sdk/start/server.js"
+    },
+    "./focus": {
+      "types": "./dist/sdk/client/focus.d.ts",
+      "import": "./dist/sdk/client/focus.js"
     }
   },
   "files": [
@@ -126,7 +130,7 @@
   ],
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1073.0",
-    "@flow-industries/ui": "^0.19.0",
+    "@flow-industries/ui": "^0.21.1",
     "@hono/otel": "^1.1.2",
     "@openobserve/browser-logs": "^0.3.1",
     "@openobserve/browser-rum": "^0.3.1",