@carmaclouds/core 2.3.1

package/src/ir/index.ts

@@ -0,0 +1,10 @@
+/**
+ * System-agnostic IR for DiceCloud characters. See REBUILD.md.
+ */
+export * from './types';
+export { normalize } from './normalize';
+export { deriveDnd, DND_ABILITIES } from './views/dnd5e';
+export type { Dnd5eView, AbilityView, PoolView, HitDicePool } from './views/dnd5e';
+export { IR_VERSION, toIRRow } from './persistence';
+export type { IRRow } from './persistence';
+export { upsertCharacterIR } from './sync';

package/src/ir/normalize.ts

@@ -0,0 +1,245 @@
+/**
+ * normalize(raw) -> IRCharacter
+ *
+ * Pure transform from a raw DiceCloud API response into the system-agnostic IR.
+ * No D&D assumptions: every attribute is carried with its type/reset, every
+ * action/spell keeps its real uses + consumed resources.
+ */
+import type {
+  IRAction,
+  IRAttribute,
+  IRCharacter,
+  IRConsumes,
+  IRDamage,
+  IRItem,
+  IRSkill,
+  RawDiceCloud,
+  ResetPeriod,
+} from './types';
+
+const DND_ABILITIES = [
+  'strength', 'dexterity', 'constitution', 'intelligence', 'wisdom', 'charisma',
+];
+
+/**
+ * Best-effort system hint (never load-bearing). PF2e also uses the six abilities,
+ * so we additionally require D&D-5e-specific signals: a single proficiencyBonus
+ * variable and a class-based hit-dice attribute.
+ */
+function detectSystem(byVar: Record<string, IRAttribute>): 'dnd5e' | 'generic' {
+  const hasAbilities = DND_ABILITIES.every((ab) => byVar[ab]);
+  const hasProfBonus = !!byVar['proficiencyBonus'];
+  const hasHitDice = Object.values(byVar).some((a) => a.type === 'hitDice');
+  return hasAbilities && hasProfBonus && hasHitDice ? 'dnd5e' : 'generic';
+}
+
+/** Coerce a DiceCloud value (number, calculation object, or string) to a number. */
+function numOf(v: any): number {
+  if (v == null) return 0;
+  if (typeof v === 'number') return Number.isFinite(v) ? v : 0;
+  if (typeof v === 'object') return numOf(v.value ?? v.total ?? 0);
+  const n = Number(v);
+  return Number.isFinite(n) ? n : 0;
+}
+
+/** True when a DiceCloud calculation/value is actually present (not just absent). */
+function has(v: any): boolean {
+  return v != null && !(typeof v === 'object' && v.value == null && v.total == null);
+}
+
+/** Pull display text out of a DiceCloud description ({ text } | { value } | string). */
+function textOf(d: any): string | undefined {
+  if (!d) return undefined;
+  if (typeof d === 'string') return d || undefined;
+  return d.text ?? d.value ?? undefined;
+}
+
+function resetOf(p: any): ResetPeriod {
+  return p.reset ?? null;
+}
+
+/** Whether a property has been soft-deleted (truly gone). */
+function isRemoved(p: any): boolean {
+  return !p || p.removed === true;
+}
+
+/**
+ * Whether a property is currently active. Deactivated properties (e.g. an
+ * unprepared spell, a toggled-off feature) are still imported - we carry this
+ * flag so adapters can grey them out rather than dropping data.
+ */
+function activeOf(p: any): boolean {
+  return !p.inactive && !p.deactivatedBySelf && !p.deactivatedByAncestor;
+}
+
+function normalizeAttribute(p: any): IRAttribute {
+  const value = numOf(p.value);
+  const total = numOf(p.total);
+  const damage = numOf(p.damage);
+
+  const attr: IRAttribute = {
+    id: p._id,
+    name: p.name ?? p.variableName ?? '',
+    variableName: p.variableName ?? '',
+    type: p.attributeType ?? 'stat',
+    value,
+    total,
+    damage,
+    reset: resetOf(p),
+    active: activeOf(p),
+    tags: Array.isArray(p.tags) ? p.tags : [],
+    description: textOf(p.description),
+  };
+
+  if (p.attributeType === 'ability') {
+    attr.modifier = has(p.modifier) ? numOf(p.modifier) : Math.floor((value - 10) / 2);
+  }
+  if (p.attributeType === 'hitDice' && p.hitDiceSize) {
+    attr.hitDiceSize = String(p.hitDiceSize);
+  }
+  if (p.attributeType === 'spellSlot' && has(p.spellSlotLevel)) {
+    attr.spellSlotLevel = numOf(p.spellSlotLevel);
+  }
+  return attr;
+}
+
+function normalizeSkill(p: any): IRSkill {
+  return {
+    id: p._id,
+    name: p.name ?? p.variableName ?? '',
+    variableName: p.variableName ?? '',
+    skillType: p.skillType ?? 'skill',
+    value: numOf(p.value),
+    ability: p.ability || undefined,
+    proficiency: numOf(p.proficiency),
+    active: activeOf(p),
+    tags: Array.isArray(p.tags) ? p.tags : [],
+  };
+}
+
+function normalizeItem(p: any): IRItem {
+  return {
+    id: p._id,
+    name: p.name ?? '',
+    plural: p.plural || undefined,
+    quantity: p.quantity != null ? numOf(p.quantity) : 1,
+    equipped: !!p.equipped,
+    weight: has(p.weight) ? numOf(p.weight) : undefined,
+    value: has(p.value) ? numOf(p.value) : undefined,
+    description: textOf(p.description),
+    tags: Array.isArray(p.tags) ? p.tags : [],
+  };
+}
+
+function consumesOf(p: any): IRConsumes[] {
+  const consumed = p.resources?.attributesConsumed;
+  if (!Array.isArray(consumed)) return [];
+  return consumed.map((c: any): IRConsumes => ({
+    variableName: c.variableName || undefined,
+    propertyId: c._id || c.variableId || undefined,
+    amount: numOf(c.quantity ?? c.amount ?? 1),
+  }));
+}
+
+function normalizeAction(p: any, damageByParent: Record<string, any[]>): IRAction {
+  const kind: IRAction['kind'] =
+    p.type === 'spell' ? 'spell' : p.type === 'feature' ? 'feature' : 'action';
+
+  const damage = (damageByParent[p._id] ?? [])
+    .map((d): IRDamage => ({
+      formula: d.amount?.calculation ?? String(d.amount?.value ?? ''),
+      type: d.damageType || undefined,
+    }))
+    .filter((d) => d.formula);
+
+  const action: IRAction = {
+    id: p._id,
+    name: p.name ?? '',
+    kind,
+    active: activeOf(p),
+    consumes: consumesOf(p),
+    damage,
+    tags: Array.isArray(p.tags) ? p.tags : [],
+    description: textOf(p.description),
+  };
+
+  const max = numOf(p.uses);
+  if (has(p.uses) && max > 0) {
+    const current = has(p.usesLeft) ? numOf(p.usesLeft) : Math.max(0, max - numOf(p.usesUsed));
+    action.uses = { current, max, reset: resetOf(p) };
+  }
+
+  if (has(p.attackRoll)) {
+    action.attack = { bonus: numOf(p.attackRoll) };
+  }
+
+  if (kind === 'spell') {
+    action.spell = {
+      level: numOf(p.level),
+      school: p.school || undefined,
+      castingTime: p.castingTime || undefined,
+      range: p.range || undefined,
+      duration: p.duration || undefined,
+      components: p.components || undefined,
+      concentration: p.components?.concentration ?? undefined,
+      ritual: p.components?.ritual ?? undefined,
+    };
+  }
+
+  return action;
+}
+
+/** Whether a property should appear in `actions` (things that do something). */
+function isActionLike(p: any): boolean {
+  if (p.type === 'action' || p.type === 'spell') return true;
+  // Include only features that have a limited-use pool (e.g. Channel Divinity).
+  if (p.type === 'feature') return has(p.uses) && numOf(p.uses) > 0;
+  return false;
+}
+
+export function normalize(raw: RawDiceCloud): IRCharacter {
+  // Accept both the REST API shape ({ creatures[], creatureProperties[] }) and the
+  // extension's internal shape ({ creature, properties[] }).
+  const creature = raw?.creatures?.[0] ?? raw?.creature ?? {};
+  const allProps = raw?.creatureProperties ?? raw?.properties ?? [];
+  const props = allProps.filter((p) => !isRemoved(p));
+
+  const attributes = props
+    .filter((p) => p.type === 'attribute')
+    .map(normalizeAttribute);
+
+  const skills = props
+    .filter((p) => p.type === 'skill')
+    .map(normalizeSkill);
+
+  // Damage is stored as child `damage` properties pointing at their action/spell.
+  const damageByParent: Record<string, any[]> = {};
+  for (const p of props) {
+    if (p.type === 'damage' && p.parent?.id) {
+      (damageByParent[p.parent.id] ??= []).push(p);
+    }
+  }
+
+  const actions = props.filter(isActionLike).map((p) => normalizeAction(p, damageByParent));
+
+  const inventory = props
+    .filter((p) => p.type === 'item')
+    .map(normalizeItem);
+
+  const byVar: Record<string, IRAttribute> = {};
+  for (const a of attributes) {
+    if (a.variableName) byVar[a.variableName] = a;
+  }
+
+  return {
+    id: creature._id ?? '',
+    name: creature.name ?? '',
+    portrait: creature.picture || creature.avatarPicture || undefined,
+    systemHint: detectSystem(byVar),
+    attributes,
+    skills,
+    actions,
+    inventory,
+    byVar,
+  };
+}

package/src/ir/persistence.ts

@@ -0,0 +1,37 @@
+/**
+ * Persistence shape for the clouds_character_ir table (see the matching SQL
+ * migration). The IR is already plain JSON, so this just frames the upsert row
+ * and stamps the schema version.
+ */
+import type { IRCharacter, RawDiceCloud } from './types';
+
+/** Bump when the IR shape changes in a way consumers must migrate for. */
+export const IR_VERSION = 1;
+
+export interface IRRow {
+  dicecloud_character_id: string;
+  character_name: string;
+  system_hint: string;
+  ir: IRCharacter;
+  ir_version: number;
+  raw?: RawDiceCloud;
+}
+
+/**
+ * Build the row to upsert into clouds_character_ir.
+ *
+ *   supabase.from('clouds_character_ir')
+ *     .upsert(toIRRow(normalize(raw), raw), { onConflict: 'dicecloud_character_id' })
+ *
+ * Pass `raw` to keep a re-normalizable snapshot; omit it to store IR only.
+ */
+export function toIRRow(ir: IRCharacter, raw?: RawDiceCloud): IRRow {
+  return {
+    dicecloud_character_id: ir.id,
+    character_name: ir.name,
+    system_hint: ir.systemHint,
+    ir,
+    ir_version: IR_VERSION,
+    ...(raw ? { raw } : {}),
+  };
+}

package/src/ir/sync.ts

@@ -0,0 +1,49 @@
+/**
+ * Write the system-agnostic IR to Supabase. Called from each sync path alongside
+ * the existing clouds_characters write, so the rebuild's data flows into its own
+ * table without disturbing the legacy path. See REBUILD.md.
+ *
+ * Uses the Supabase REST API via fetch so it works everywhere the extension runs
+ * (background service worker, content scripts, popups) regardless of whether a
+ * supabase-js client is in scope.
+ */
+import { normalize } from './normalize';
+import { toIRRow } from './persistence';
+import type { IRCharacter, RawDiceCloud } from './types';
+
+export interface SupabaseRestTarget {
+  url: string;
+  anonKey: string;
+}
+
+/**
+ * Normalize raw DiceCloud data and upsert it into clouds_character_ir.
+ * Returns the IR. Throws on a real upsert error; callers should treat IR sync as
+ * non-fatal (wrap in try/catch) so it never blocks the legacy sync.
+ */
+export async function upsertCharacterIR(
+  raw: RawDiceCloud,
+  target: SupabaseRestTarget,
+): Promise<IRCharacter> {
+  const ir = normalize(raw);
+  if (!ir.id) throw new Error('upsertCharacterIR: normalized IR has no character id');
+
+  const res = await fetch(
+    `${target.url}/rest/v1/clouds_character_ir?on_conflict=dicecloud_character_id`,
+    {
+      method: 'POST',
+      headers: {
+        apikey: target.anonKey,
+        Authorization: `Bearer ${target.anonKey}`,
+        'Content-Type': 'application/json',
+        Prefer: 'resolution=merge-duplicates,return=minimal',
+      },
+      body: JSON.stringify(toIRRow(ir)),
+    },
+  );
+
+  if (!res.ok) {
+    throw new Error(`clouds_character_ir upsert failed: ${res.status} ${await res.text()}`);
+  }
+  return ir;
+}

package/src/ir/types.ts

@@ -0,0 +1,161 @@
+/**
+ * System-agnostic intermediate representation (IR) for a DiceCloud character.
+ *
+ * The IR mirrors DiceCloud's own generic stat engine instead of a fixed D&D 5e
+ * shape: every attribute is carried with its type and reset period, every action/
+ * spell references the resources it actually consumes. D&D conveniences (the six
+ * abilities, skills, spell-slot levels) are derived from this by `views/dnd5e`,
+ * never baked in here.
+ *
+ * See REBUILD.md for the design rationale.
+ */
+
+/** DiceCloud attributeType, kept open so unknown/custom systems still round-trip. */
+export type AttributeType =
+  | 'ability'
+  | 'stat'
+  | 'modifier'
+  | 'hitDice'
+  | 'healthBar'
+  | 'resource'
+  | 'spellSlot'
+  | 'utility'
+  | (string & {});
+
+/** How a use/charge pool refreshes. Open set; DiceCloud commonly uses the rest kinds. */
+export type ResetPeriod = 'shortRest' | 'longRest' | (string & {}) | null;
+
+/** A single attribute of any type. HP, hit dice, spell slots, ki, sanity, glory... */
+export interface IRAttribute {
+  id: string;
+  name: string;
+  variableName: string;
+  type: AttributeType;
+  /** Current effective value (for damageable attrs this is total - damage). */
+  value: number;
+  /** Max / total. */
+  total: number;
+  /** Amount consumed/reduced (healthBar, resource). */
+  damage: number;
+  /** Derived ability modifier, when the attribute is an ability score. */
+  modifier?: number;
+  reset: ResetPeriod;
+  /** False when the property is toggled/deactivated (e.g. an unprepared spell). Still imported. */
+  active: boolean;
+  /** e.g. 'd6' for hitDice attributes. */
+  hitDiceSize?: string;
+  /** Slot level for spellSlot attributes. */
+  spellSlotLevel?: number;
+  tags: string[];
+  description?: string;
+}
+
+/**
+ * A trained/rollable proficiency. DiceCloud models D&D skills, saves, tool/language/
+ * armor/weapon proficiencies - and custom things like 13th Age backgrounds - all as
+ * `skill` properties distinguished by skillType.
+ */
+export interface IRSkill {
+  id: string;
+  name: string;
+  variableName: string;
+  /** 'skill' | 'save' | 'check' | 'language' | 'armor' | 'weapon' | custom. */
+  skillType: string;
+  /** Computed roll bonus. */
+  value: number;
+  /** Linked ability variableName, when any. */
+  ability?: string;
+  /** Proficiency multiplier (0, 0.5, 1, 2). */
+  proficiency: number;
+  active: boolean;
+  tags: string[];
+}
+
+export interface IRItem {
+  id: string;
+  name: string;
+  plural?: string;
+  quantity: number;
+  equipped: boolean;
+  weight?: number;
+  value?: number;
+  description?: string;
+  tags: string[];
+}
+
+export interface IRUses {
+  current: number;
+  max: number;
+  reset: ResetPeriod;
+}
+
+/** A resource an action/spell spends when used. */
+export interface IRConsumes {
+  variableName?: string;
+  propertyId?: string;
+  amount: number;
+}
+
+export interface IRDamage {
+  formula: string;
+  type?: string;
+}
+
+export interface IRSpellMeta {
+  level: number;
+  school?: string;
+  castingTime?: string;
+  range?: string;
+  duration?: string;
+  components?: Record<string, boolean>;
+  concentration?: boolean;
+  ritual?: boolean;
+}
+
+/** Anything that "does something": an action, a spell, or an activatable feature. */
+export interface IRAction {
+  id: string;
+  name: string;
+  kind: 'action' | 'spell' | 'feature';
+  /** False when toggled/deactivated (e.g. an unprepared spell). Still imported. */
+  active: boolean;
+  /** Limited-use pool, with reset period (the "2 charges, recharge on long rest" case). */
+  uses?: IRUses;
+  /** Resources spent on use, by DiceCloud variableName / property id. */
+  consumes: IRConsumes[];
+  attack?: { bonus: number };
+  damage: IRDamage[];
+  spell?: IRSpellMeta;
+  description?: string;
+  tags: string[];
+}
+
+/** The normalized character. Generic first; D&D is a derived view on top. */
+export interface IRCharacter {
+  id: string;
+  name: string;
+  portrait?: string;
+  /** Best-effort hint, never load-bearing. */
+  systemHint: 'dnd5e' | 'generic' | (string & {});
+  attributes: IRAttribute[];
+  skills: IRSkill[];
+  actions: IRAction[];
+  inventory: IRItem[];
+  /** variableName -> attribute, for fast lookup by adapters and the D&D view. */
+  byVar: Record<string, IRAttribute>;
+}
+
+/**
+ * Raw DiceCloud data we normalize from. Two shapes occur in the wild:
+ *  - REST `/api/creature/{id}`: { creatures[], creatureProperties[], creatureVariables[] }
+ *  - the extension's internal store: { creature, properties[], variables }
+ * normalize() accepts either.
+ */
+export interface RawDiceCloud {
+  creatures?: any[];
+  creatureProperties?: any[];
+  creatureVariables?: any[];
+  creature?: any;
+  properties?: any[];
+  variables?: any;
+}

package/src/ir/views/dnd5e.ts

@@ -0,0 +1,94 @@
+/**
+ * D&D 5e view derived from the system-agnostic IR.
+ *
+ * This is a *projection*, not the source of truth: it picks the six abilities,
+ * skills, saves, HP, hit dice and spell-slot levels out of the generic IR so
+ * existing D&D adapters keep their familiar shape. Non-D&D characters simply
+ * produce a sparse view and render from the generic IR instead.
+ */
+import type { IRAttribute, IRCharacter } from '../types';
+
+export const DND_ABILITIES = [
+  'strength', 'dexterity', 'constitution', 'intelligence', 'wisdom', 'charisma',
+] as const;
+
+export interface AbilityView {
+  score: number;
+  modifier: number;
+}
+
+export interface PoolView {
+  current: number;
+  max: number;
+}
+
+export interface HitDicePool extends PoolView {
+  size?: string;
+}
+
+export interface Dnd5eView {
+  abilities: Record<string, AbilityView>;
+  /** Save bonus keyed by ability variableName. */
+  saves: Record<string, number>;
+  /** Skill bonus keyed by skill variableName. */
+  skills: Record<string, number>;
+  hitPoints: PoolView & { temp: number };
+  hitDice: HitDicePool[];
+  /** Spell slots keyed by level (1-9). */
+  spellSlots: Record<number, PoolView>;
+  proficiencyBonus: number;
+  armorClass: number;
+  speed: number;
+  initiative: number;
+}
+
+const valOf = (a?: IRAttribute): number => a?.value ?? 0;
+
+/** Current/max for a damageable attribute (HP, slots): current = total - damage. */
+function pool(a?: IRAttribute): PoolView {
+  if (!a) return { current: 0, max: 0 };
+  return { current: a.total - a.damage, max: a.total };
+}
+
+export function deriveDnd(ir: IRCharacter): Dnd5eView {
+  const { byVar } = ir;
+
+  const abilities: Record<string, AbilityView> = {};
+  for (const ab of DND_ABILITIES) {
+    const a = byVar[ab];
+    if (a) abilities[ab] = { score: a.value, modifier: a.modifier ?? Math.floor((a.value - 10) / 2) };
+  }
+
+  const saves: Record<string, number> = {};
+  const skills: Record<string, number> = {};
+  for (const s of ir.skills) {
+    if (s.skillType === 'save') saves[s.ability || s.variableName] = s.value;
+    else if (s.skillType === 'skill') skills[s.variableName] = s.value;
+  }
+
+  const hitDice = ir.attributes
+    .filter((a) => a.type === 'hitDice')
+    .map((a): HitDicePool => ({ current: a.value, max: a.total, size: a.hitDiceSize }));
+
+  const spellSlots: Record<number, PoolView> = {};
+  for (const a of ir.attributes) {
+    if (a.type === 'spellSlot' && a.spellSlotLevel) {
+      spellSlots[a.spellSlotLevel] = pool(a);
+    }
+  }
+
+  const hp = pool(byVar['hitPoints']);
+
+  return {
+    abilities,
+    saves,
+    skills,
+    hitPoints: { ...hp, temp: valOf(byVar['tempHP'] || byVar['temporaryHitPoints']) },
+    hitDice,
+    spellSlots,
+    proficiencyBonus: valOf(byVar['proficiencyBonus']),
+    armorClass: valOf(byVar['armorClass']),
+    speed: valOf(byVar['speed']),
+    initiative: valOf(byVar['initiative']),
+  };
+}