@nodaro/shared 2.18.0 → 2.20.0

package/src/organizations/types.ts

@@ -56,6 +56,16 @@ export type GrantedAccess = (typeof GRANTED_ACCESS)[number]
 export const SUBMISSION_STATUSES = ["submitted", "in_review", "returned", "approved"] as const
 export type SubmissionStatus = (typeof SUBMISSION_STATUSES)[number]
 
+/**
+ * How a usage report is bucketed. `workspace` is org-scope only; `none`
+ * = flat rows. A runtime list, like `ORG_ROLES`, so the plugin route's Zod is
+ * `z.enum(USAGE_GROUP_BYS)` and the migration guard asserts the SQL
+ * `NOT IN (...)` list equals this minus `none` — one vocabulary, never three
+ * hand-copies that drift.
+ */
+export const USAGE_GROUP_BYS = ["workspace", "member", "model", "day", "none"] as const
+export type UsageGroupBy = (typeof USAGE_GROUP_BYS)[number]
+
 /**
  * Error codes the organization endpoints add to the standard envelope
  * (`{ error: { code, message } }`). Clients dispatch on the code, never on
@@ -80,6 +90,8 @@ export const ORG_ERROR_CODES = [
   "domain_not_allowed",
   "already_started",
   "collab_unavailable",
+  // A CSV usage export whose write-ahead audit row could not be written (503).
+  "audit_unavailable",
   // Organization, workspace and membership endpoints.
   "terms_required",
   "not_org_member",

package/src/organizations/views.ts

@@ -4,6 +4,7 @@ import type {
   OrgRole,
   OrgSettings,
   OrgStatus,
+  UsageGroupBy,
   WorkspaceRole,
   WorkspaceSettings,
 } from "./types.js"
@@ -218,3 +219,116 @@ export interface OrgPage<T> {
   data: T[]
   nextCursor: string | null
 }
+
+/**
+ * Usage reporting. What `GET /v1/orgs/:id/usage` and
+ * `GET /v1/workspaces/:id/usage` return. No cost/USD field appears anywhere —
+ * a report shows CREDITS a class or team spent, never the platform's own rates
+ * (pricing-leak class, guarded by organizations-types.test.ts and the
+ * migration guard).
+ */
+
+/** One bucket of a usage report. Exactly one of workspace/member/model/day is set. */
+export interface UsageReportRow {
+  key: string
+  workspace: { id: string; name: string | null; slug: string | null; archived: boolean } | null
+  member: { userId: string; displayName: string | null; email: string | null } | null
+  model: string | null
+  /** `YYYY-MM-DD` in the report's `tz`. */
+  day: string | null
+  runCount: number
+  appRunCount: number
+  /** Settled where known, the held reservation otherwise. = settledCredits + inFlightCredits. */
+  credits: number
+  settledCredits: number
+  inFlightCredits: number
+  inFlightRuns: number
+}
+
+/**
+ * A platform-absorbed line for one workspace, split by ORIGIN (never attributed
+ * to a member). Two ledgers share the `org_usage_variance` source: a
+ * `metered_overrun` (a metered run's overrun beyond the budget — it HAS a
+ * settled usage_logs counterpart) and an `app_markup` shortfall (an
+ * approved-app markup the budget could not cover — it has NO usage_logs row).
+ * `other` is a future/unrecognised origin.
+ */
+export interface UsageVarianceRow {
+  workspace: { id: string; name: string | null; slug: string | null } | null
+  kind: "metered_overrun" | "app_markup" | "other"
+  credits: number
+  rowCount: number
+}
+
+/**
+ * Totals over the WHOLE window — every usage_logs row in [from, to] after the
+ * scope / userId / workspaceId narrowing — never over the returned `rows`.
+ * Unaffected by `truncated`; equals a `groupBy=day` report's column-wise sum.
+ */
+export interface UsageReportTotals {
+  runCount: number
+  credits: number
+  settledCredits: number
+  inFlightCredits: number
+  /** Metered-overrun variance in the window — a run's overrun the platform absorbed. */
+  platformAbsorbedCredits: number
+  /** Approved-app markup shortfall the platform absorbed. It has NO usage_logs run, so it is not in the figures above. */
+  appMarkupAbsorbedCredits: number
+  /**
+   * settledCredits − platformAbsorbedCredits: the METERED settlement that
+   * reached the workspace budget(s). App markup charged to a budget (migration
+   * 352) is not a usage_logs row and is not included here; when a markup
+   * shortfall is absorbed this figure under-reports and may go negative — it is
+   * NOT `workspace_budgets.spent_credits`.
+   */
+  chargedToBudget: number
+}
+
+export interface UsageReport {
+  scope: "org" | "workspace"
+  scopeId: string
+  from: string
+  to: string
+  tz: string
+  groupBy: Exclude<UsageGroupBy, "none">
+  /** Present when a member's self-view or an admin's `?userId=` narrowed the report. */
+  userId: string | null
+  /** Present when an org report was narrowed to one workspace. */
+  workspaceId: string | null
+  rows: UsageReportRow[]
+  variance: UsageVarianceRow[]
+  totals: UsageReportTotals
+  /**
+   * True when more than 5000 buckets existed and the tail of `rows` was dropped
+   * — narrow the window. Only `rows` is incomplete; `totals` and `variance`
+   * cover the whole window regardless.
+   */
+  truncated: boolean
+}
+
+/** One usage_logs row as an organization sees it. No cost fields, ever. */
+export interface UsageLogEntry {
+  id: string
+  createdAt: string
+  workspace: { id: string; name: string | null; slug: string | null } | null
+  member: { userId: string; displayName: string | null; email: string | null } | null
+  jobId: string | null
+  model: string
+  status: "reserved" | "committed"
+  creditsReserved: number
+  creditsSettled: number | null
+  credits: number
+  isAppRun: boolean
+}
+
+/** Query parameters shared by both usage routes (dates inclusive, IANA tz). */
+export interface UsageQuery {
+  from?: string
+  to?: string
+  tz?: string
+  groupBy?: UsageGroupBy
+  workspaceId?: string
+  userId?: string
+  cursor?: string
+  limit?: number
+}

package/src/video-analysis.ts

@@ -633,3 +633,48 @@ export function inferMusicVideo(analysis: {
     }),
   )
 }
+
+// ---------------------------------------------------------------------------
+// The analysis as a BRIEF — the compact projection an LLM is handed
+// ---------------------------------------------------------------------------
+
+/** Top-level keys the analyzer derives AFTER the model's pass (merge
+ *  diagnostics, folded cast looks). A reader drafting FROM the analysis — a
+ *  production plan, a script — needs none of them. */
+const DERIVED_ANALYSIS_TOP_KEYS: ReadonlySet<string> = new Set(["warnings", "variationFolds"])
+
+/** Per-scene keys the validator computes from `visual` and the slot list. */
+const DERIVED_ANALYSIS_SCENE_KEYS: ReadonlySet<string> = new Set(["visualResolved", "slotRefs", "oversized"])
+
+const asRecord = (v: unknown): Record<string, unknown> | null =>
+  typeof v === "object" && v !== null && !Array.isArray(v) ? (v as Record<string, unknown>) : null
+
+/**
+ * The analysis with its server-derived fields removed — the form an LLM is
+ * handed when the analysis IS the brief (Nodaro Studio's Director and its
+ * job-id loader). Drops `warnings` and `variationFolds` at the top and
+ * `visualResolved`, `slotRefs`, `oversized` on every scene; keeps
+ * `refImageUrl` (a downstream cast image) and everything else. Never mutates;
+ * a non-object input comes back as-is.
+ *
+ * ONE strip list, shared by the worker that composes the brief server-side
+ * (`llm-structured` jobs with a `videoUrl`) and the client that loads a
+ * finished analysis into a textarea, so the two can never drift.
+ */
+export function stripDerivedAnalysisFields(json: unknown): unknown {
+  const doc = asRecord(json)
+  if (!doc) return json
+  const out: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(doc)) {
+    if (DERIVED_ANALYSIS_TOP_KEYS.has(key)) continue
+    out[key] =
+      key === "scenes" && Array.isArray(value)
+        ? value.map((scene) => {
+            const s = asRecord(scene)
+            if (!s) return scene
+            return Object.fromEntries(Object.entries(s).filter(([k]) => !DERIVED_ANALYSIS_SCENE_KEYS.has(k)))
+          })
+        : value
+  }
+  return out
+}

package/src/video-ui-defaults.ts

@@ -0,0 +1,66 @@
+/**
+ * UI-default fills for the unified video nodes — the ONE source of truth shared
+ * by the backend DAG payload builder, the config-panel fail-safe snaps and the
+ * node's hover/run strip.
+ *
+ * Several config panels RENDER a default without persisting it to node data, so
+ * an untouched node submits `aspectRatio` / `resolution` undefined and the
+ * enqueued job row (and the /v1/jobs echo) then disagrees with what actually
+ * renders. Worse, the panels' generic snap writes `resolutions[0]` for a stale
+ * value, which is the CHEAPEST tier under the repo's ascending-resolution
+ * convention — not necessarily the tier the model renders and bills.
+ *
+ * These helpers were local to `backend/src/services/workflow-engine/payload-builder.ts`
+ * until the Wan 3.0 launch gave the platform its first provider whose declared
+ * billing default differs from `resolutions[0]`; three surfaces then had to
+ * agree, so they live here.
+ *
+ * The resolution fill is per-family ON PURPOSE. Wan 3.0 reads its DECLARED
+ * billing default (PRICING_DEFAULT_RESOLUTION = 720p) because its catalog list
+ * is ascending, so an index-0 fill would write 480p — a tier both `runWan3`
+ * (which renders 720P) and the credit identifier (which bills the 720p row)
+ * disagree with. The Seedance family keeps its historical first-catalog-tier
+ * fill, deliberately: switching it to PRICING_DEFAULT_RESOLUTION would reprice
+ * live seedance-2-5 runs, whose declared default (720p) differs from the 480p
+ * this has always filled. That 480p-fill vs 720p-billing-default divergence on
+ * seedance-2-5 is a KNOWN pre-existing gap, out of scope here — do not "align"
+ * the branches without repricing it deliberately.
+ */
+
+import {
+  PRICING_DEFAULT_RESOLUTION,
+  isSeedance2Provider,
+  isMinimaxH3Provider,
+  isWan3Provider,
+  isGeminiOmniProvider,
+} from "./model-constants.js"
+import { MODEL_CATALOG } from "./model-catalog.js"
+
+/** `adaptive` is the aspect default for Seedance 2, MiniMax H3 and Wan 3.0. */
+export function uiAspectRatioFill(provider: string): string | undefined {
+  return isSeedance2Provider(provider) || isMinimaxH3Provider(provider) || isWan3Provider(provider)
+    ? "adaptive"
+    : undefined
+}
+
+/** See the file docstring — per-family on purpose; never a generic
+ *  PRICING_DEFAULT_RESOLUTION read (that would reprice seedance-2-5). */
+export function uiResolutionFill(provider: string): string | undefined {
+  if (isWan3Provider(provider)) return PRICING_DEFAULT_RESOLUTION[provider]
+  if (isSeedance2Provider(provider)) return MODEL_CATALOG[provider]?.resolutions?.[0]
+  return undefined
+}
+
+/**
+ * Duration the node RENDERS and BILLS when `data.duration` is unset, for the
+ * families whose credit identifier declares a duration fallback that is NOT
+ * `durations[0]`. Wan 3.0's bare identifier is the 5s tier while its ladder
+ * starts at 2s; the Gemini Omni family's is the 8s tier while its ladder starts
+ * at 4s. Everyone else falls back to the first listed duration, so this returns
+ * undefined and the caller keeps `durations[0]`.
+ */
+export function uiDurationFill(provider: string): number | undefined {
+  if (isWan3Provider(provider)) return 5
+  if (isGeminiOmniProvider(provider)) return 8
+  return undefined
+}