@nodaro/shared 2.3.0 → 2.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "Shared types, model catalog, wire contracts, and structural vocabularies for the Nodaro platform and SDK.",
   "type": "module",
   "license": "Apache-2.0",

package/src/__tests__/effective-tier.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect } from "vitest"
+import {
+  resolveStoredTier,
+  resolveEffectiveTier,
+  isPaygRetentionActive,
+  PAYG_RETENTION_DAYS,
+} from "../effective-tier.js"
+
+const DAY_MS = 24 * 60 * 60 * 1000
+const NOW = new Date("2026-08-12T12:00:00Z")
+const daysAgo = (n: number) => new Date(NOW.getTime() - n * DAY_MS)
+
+describe("resolveStoredTier", () => {
+  it("prefers tier, falls back to subscription_tier, then free", () => {
+    expect(resolveStoredTier({ tier: "pro", subscription_tier: "basic" })).toBe("pro")
+    expect(resolveStoredTier({ tier: null, subscription_tier: "basic" })).toBe("basic")
+    expect(resolveStoredTier({ tier: null, subscription_tier: null })).toBe("free")
+  })
+})
+
+describe("resolveEffectiveTier — the payg derivation matrix (design §9)", () => {
+  it("never-paid free user stays free", () => {
+    expect(
+      resolveEffectiveTier({ tier: "free", subscription_tier: null, lifetime_topup_credits: 0 })
+    ).toBe("free")
+  })
+
+  it("free user with NET lifetime > 0 derives payg — even at zero current balance", () => {
+    expect(
+      resolveEffectiveTier({ tier: "free", subscription_tier: null, lifetime_topup_credits: 3300 })
+    ).toBe("payg")
+  })
+
+  it("refunded-to-zero user drops back to free (NET lifetime)", () => {
+    expect(
+      resolveEffectiveTier({ tier: "free", subscription_tier: null, lifetime_topup_credits: 0 })
+    ).toBe("free")
+  })
+
+  it("#489 pre-subscribe carryover fixture: topup balance without purchase stays free", () => {
+    // Cancel-path carryover moves a pre-subscribe balance into topup_credits
+    // with NO purchase — lifetime stays 0, so the user must NOT derive payg.
+    expect(
+      resolveEffectiveTier({ tier: "free", subscription_tier: null, lifetime_topup_credits: 0 })
+    ).toBe("free")
+  })
+
+  it("every stored paid tier passes through untouched, regardless of lifetime", () => {
+    for (const t of ["basic", "standard", "pro", "business"]) {
+      expect(
+        resolveEffectiveTier({ tier: t, subscription_tier: null, lifetime_topup_credits: 9999 })
+      ).toBe(t)
+    }
+  })
+
+  it("subscription_tier-only legacy rows resolve through the stored fallback", () => {
+    expect(
+      resolveEffectiveTier({ tier: null, subscription_tier: "standard", lifetime_topup_credits: 500 })
+    ).toBe("standard")
+  })
+
+  it("null-tier never-paid rows resolve free; with lifetime they derive payg", () => {
+    expect(
+      resolveEffectiveTier({ tier: null, subscription_tier: null, lifetime_topup_credits: 0 })
+    ).toBe("free")
+    expect(
+      resolveEffectiveTier({ tier: null, subscription_tier: null, lifetime_topup_credits: 100 })
+    ).toBe("payg")
+  })
+})
+
+describe("isPaygRetentionActive — 90-day activity window boundaries", () => {
+  it("exports the 90-day constant", () => {
+    expect(PAYG_RETENTION_DAYS).toBe(90)
+  })
+
+  it("purchase activity: 89d active, 90d active (inclusive), 91d inactive", () => {
+    const base = { lifetimeTopupCredits: 100, lastSpendAt: null }
+    expect(isPaygRetentionActive({ ...base, lastTopupAt: daysAgo(89) }, NOW)).toBe(true)
+    expect(isPaygRetentionActive({ ...base, lastTopupAt: daysAgo(90) }, NOW)).toBe(true)
+    expect(isPaygRetentionActive({ ...base, lastTopupAt: daysAgo(91) }, NOW)).toBe(false)
+  })
+
+  it("spend activity counts on its own (usage_logs MAX, not balance polls)", () => {
+    const base = { lifetimeTopupCredits: 100, lastTopupAt: daysAgo(200) }
+    expect(isPaygRetentionActive({ ...base, lastSpendAt: daysAgo(10) }, NOW)).toBe(true)
+    expect(isPaygRetentionActive({ ...base, lastSpendAt: daysAgo(91) }, NOW)).toBe(false)
+  })
+
+  it("either source alone is sufficient; the most recent wins", () => {
+    expect(
+      isPaygRetentionActive(
+        { lifetimeTopupCredits: 100, lastTopupAt: daysAgo(120), lastSpendAt: daysAgo(5) },
+        NOW
+      )
+    ).toBe(true)
+  })
+
+  it("string timestamps (supabase rows) are accepted", () => {
+    expect(
+      isPaygRetentionActive(
+        { lifetimeTopupCredits: 100, lastTopupAt: daysAgo(5).toISOString(), lastSpendAt: null },
+        NOW
+      )
+    ).toBe(true)
+  })
+
+  it("all-null activity is inactive; never-paid users are never retention-active", () => {
+    expect(
+      isPaygRetentionActive({ lifetimeTopupCredits: 100, lastTopupAt: null, lastSpendAt: null }, NOW)
+    ).toBe(false)
+    expect(
+      isPaygRetentionActive({ lifetimeTopupCredits: 0, lastTopupAt: daysAgo(1), lastSpendAt: null }, NOW)
+    ).toBe(false)
+  })
+})

package/src/effective-tier.ts

@@ -0,0 +1,72 @@
+/**
+ * Effective-tier resolution — the payg derivation.
+ *
+ * "payg" is a DERIVED tier, never stored: a user whose stored tier resolves
+ * to "free" but who has NET lifetime top-up credits (granted − refunded,
+ * clamped ≥ 0 by every SQL writer) is treated as "payg" by entitlement
+ * checks. Stored tier stays untouched, so subscription webhooks never learn
+ * about payg and a cancel→free transition re-derives it automatically.
+ *
+ * Lives in @nodaro/shared because the pipeline tier maps already do, and
+ * both backend (credit gates, workers) and read surfaces need one source.
+ *
+ * The profile fields are REQUIRED (non-optional) on purpose: a call site
+ * whose SELECT forgot to fetch `lifetime_topup_credits` becomes a compile
+ * error instead of a silent `?? 0` that quietly deactivates payg — that is
+ * the failure mode this shape exists to prevent.
+ */
+
+/** Stored-tier resolution — mirrors SQL COALESCE(tier, subscription_tier, 'free'). */
+export function resolveStoredTier(p: {
+  tier: string | null
+  subscription_tier: string | null
+}): string {
+  return p.tier ?? p.subscription_tier ?? "free"
+}
+
+/**
+ * Effective tier: stored "free" with NET lifetime top-ups > 0 derives "payg".
+ * Every other stored tier passes through untouched.
+ */
+export function resolveEffectiveTier(p: {
+  tier: string | null
+  subscription_tier: string | null
+  lifetime_topup_credits: number
+}): string {
+  const stored = resolveStoredTier(p)
+  if (stored === "free" && p.lifetime_topup_credits > 0) return "payg"
+  return stored
+}
+
+/** Media-retention activity window for payg users (design 2026-07-05 §4.6). */
+export const PAYG_RETENTION_DAYS = 90
+
+/**
+ * Is this payg user inside their retention-activity window?
+ *
+ * Activity = credit SPEND (callers supply MAX(usage_logs.created_at) — never
+ * `last_daily_reset`, which read-only balance polls bump) OR a top-up
+ * PURCHASE (`last_topup_at`). Within PAYG_RETENTION_DAYS of either → the
+ * nightly reaper leaves their media alone; past it, the standard free-tier
+ * reaper rules apply. A user with no lifetime purchases is never
+ * retention-active (they are not payg).
+ */
+export function isPaygRetentionActive(
+  p: {
+    lifetimeTopupCredits: number
+    lastTopupAt: string | Date | null
+    lastSpendAt: string | Date | null
+  },
+  now: Date
+): boolean {
+  if (p.lifetimeTopupCredits <= 0) return false
+  const cutoff = now.getTime() - PAYG_RETENTION_DAYS * 24 * 60 * 60 * 1000
+  const at = (v: string | Date | null): number | null => {
+    if (v === null) return null
+    const t = v instanceof Date ? v.getTime() : new Date(v).getTime()
+    return Number.isFinite(t) ? t : null
+  }
+  const topup = at(p.lastTopupAt)
+  const spend = at(p.lastSpendAt)
+  return (topup !== null && topup >= cutoff) || (spend !== null && spend >= cutoff)
+}

package/src/index.ts

@@ -540,6 +540,13 @@ export type {
   SharedListing,
 } from "./community.js"
 
+export {
+  resolveStoredTier,
+  resolveEffectiveTier,
+  isPaygRetentionActive,
+  PAYG_RETENTION_DAYS,
+} from "./effective-tier.js"
+
 export {
   NODE_DEFAULT_TYPES,
   validateProviderForNodeType,

package/src/model-constants.ts

@@ -605,8 +605,13 @@ export const IMAGE_I2I_PROVIDERS = [
   "kontext-multi",
   // BFL Flux 2 Pro — runs through Replicate with safety_tolerance=5 (max for Pro)
   "flux-2-pro",
+  // BFL FLUX Fill Pro — dedicated masked inpainting via Replicate (white = edit area)
+  "flux-fill",
   // BFL Flux 2 Max — runs through Replicate with safety_tolerance=5, up to 8 refs
   "flux-2-max",
+  // BFL FLUX Fill Pro — dedicated inpainting via Replicate (image + mask + prompt,
+  // white = edit area). Second mask-capable i2i provider alongside ideogram-edit.
+  "flux-fill",
 ] as const
 
 /** Image editing providers (upscale, remove bg, etc.) */
@@ -1039,7 +1044,7 @@ export type VoiceDesignModel = typeof VOICE_DESIGN_MODELS[number]
 export const DEFAULT_VOICE_DESIGN_MODEL: VoiceDesignModel = "eleven_ttv_v3"
 
 /** I2I providers that support mask-based inpainting */
-export const I2I_MASK_SUPPORT = new Set(["ideogram-edit"])
+export const I2I_MASK_SUPPORT = new Set(["ideogram-edit", "flux-fill"])
 
 /**
  * Mask edit tier per image-gen provider (single source of truth for inpaint).

package/src/pipeline-defaults.ts

@@ -65,6 +65,7 @@ export function validateModeActivation(
 // Tier → max parallel pipelines (Architecture §5.4)
 export const TIER_PIPELINE_PARALLELISM: Record<string, number> = {
   free: 0,
+  payg: 1, // derived tier — pipeline entitlements copy basic's
   basic: 1,
   standard: 2,
   pro: 3,
@@ -80,6 +81,7 @@ export const TIER_PIPELINE_PARALLELISM: Record<string, number> = {
 // the user paid for, instead of the intended two-thirds.
 export const TIER_MAX_PIPELINE_COST_CREDITS: Record<string, number> = {
   free: 0,
+  payg: 3000, // derived tier — copies basic
   basic: 3000,
   standard: 8000,
   pro: 20000,