@nodaro/shared 2.8.0 → 2.10.0

package/src/organizations/types.ts

@@ -0,0 +1,152 @@
+import { z } from "zod"
+
+/**
+ * Organizations — wire contract for the second tenancy axis
+ * (Organization -> Workspace -> Member).
+ *
+ * Lives in @nodaro/shared because SDK/MCP consumers need these enums, the
+ * request schemas the API validates, and the error codes it returns. This
+ * package carries the CONTRACT ONLY — no resolution logic, no presets, no
+ * vocabulary, no access rule. Those are server-side.
+ */
+
+/**
+ * Selects which workspace a request LISTS from and CREATES into. It never
+ * authorizes: reading, updating, deleting or running an identified object is
+ * decided by that object's own workspace, so a forgotten or forged header can
+ * neither widen access nor move a charge.
+ *
+ * Fastify lower-cases incoming header keys, hence the second constant — read
+ * `req.headers[WORKSPACE_HEADER_LOWER]`, send `WORKSPACE_HEADER`.
+ */
+export const WORKSPACE_HEADER = "X-Nodaro-Workspace"
+export const WORKSPACE_HEADER_LOWER = "x-nodaro-workspace"
+
+export const ORG_KINDS = ["school", "team"] as const
+export type OrgKind = (typeof ORG_KINDS)[number]
+
+export const ORG_ROLES = ["owner", "admin", "member"] as const
+export type OrgRole = (typeof ORG_ROLES)[number]
+
+export const WORKSPACE_ROLES = ["admin", "member"] as const
+export type WorkspaceRole = (typeof WORKSPACE_ROLES)[number]
+
+export const MEMBER_STATUSES = ["active", "suspended"] as const
+export type MemberStatus = (typeof MEMBER_STATUSES)[number]
+
+/** `pending` = created, awaiting platform-admin approval. */
+export const ORG_STATUSES = ["pending", "active", "suspended", "deleted"] as const
+export type OrgStatus = (typeof ORG_STATUSES)[number]
+
+/** An explicit per-workflow grant (works for personal workflows too). */
+export const COLLABORATOR_ROLES = ["editor", "viewer"] as const
+export type CollaboratorRole = (typeof COLLABORATOR_ROLES)[number]
+
+export const WORKFLOW_VISIBILITIES = ["private", "workspace"] as const
+export type WorkflowVisibility = (typeof WORKFLOW_VISIBILITIES)[number]
+
+/** What an identity may do with a workflow, strongest first. */
+export const ACCESS_LEVELS = ["own", "edit", "view", "none"] as const
+export type AccessLevel = (typeof ACCESS_LEVELS)[number]
+
+/** The access a setting may grant to a non-creator. */
+export const GRANTED_ACCESS = ["view", "edit"] as const
+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]
+
+/**
+ * Error codes the organization endpoints add to the standard envelope
+ * (`{ error: { code, message } }`). Clients dispatch on the code, never on
+ * the message text.
+ */
+export const ORG_ERROR_CODES = [
+  "not_a_member",
+  "insufficient_role",
+  "org_not_active",
+  "member_suspended",
+  "workspace_archived",
+  "personal_space_disabled",
+  "token_workspace_mismatch",
+  "run_requires_authenticated_member",
+  "budget_exceeded",
+  "member_cap_exceeded",
+  "model_not_allowed",
+  "invitation_expired",
+  "invitation_revoked",
+  "email_mismatch",
+  "join_code_invalid",
+  "domain_not_allowed",
+  "already_started",
+  "collab_unavailable",
+  // Organization, workspace and membership endpoints.
+  "terms_required",
+  "not_org_member",
+  "already_a_member",
+  "owner_cannot_leave",
+  "has_active_workspaces",
+  // Invitations and join codes.
+  "invitation_not_found",
+  "invitation_accepted",
+  "bulk_invite_cap_exceeded",
+] as const
+export type OrgErrorCode = (typeof ORG_ERROR_CODES)[number]
+
+/**
+ * The settings every organization kind has a default for. `organizations.
+ * settings` and `workspaces.settings` store PARTIAL overrides of this shape;
+ * `resolveEffectiveSettings` (./settings.ts) produces the full one.
+ */
+export const PresetSettingsSchema = z.object({
+  /** What org/workspace admins may do with a member's workflow. */
+  admin_access: z.enum(GRANTED_ACCESS),
+  default_workflow_visibility: z.enum(WORKFLOW_VISIBILITIES),
+  /** What a plain member may do with a `visibility = workspace` workflow. */
+  member_access_to_shared: z.enum(GRANTED_ACCESS),
+  members_can_create_projects: z.boolean(),
+  member_caps_enabled: z.boolean(),
+  /** Whether members keep a personal (non-workspace) space at all. */
+  personal_space_enabled: z.boolean(),
+  /** Whether a workspace admin may invite NEW people into the org. */
+  workspace_admins_can_invite: z.boolean(),
+  /** Whether an editor collaborator may invite further collaborators. */
+  collaborators_can_invite: z.boolean(),
+  /**
+   * When the organization is SUSPENDED, do its content rules still bind its
+   * members?
+   *
+   * Today this governs exactly one rule — `personal_space_enabled` — and that
+   * is not an accident: every other key above governs behaviour INSIDE a
+   * workspace, and a suspended organization grants no workspace context at
+   * all, so those are already moot.
+   *
+   * The name is general because an organization is deciding a principle here,
+   * not one checkbox's fate. Default `false`, which is today's behaviour: a
+   * suspended organization stops binding, and its members work independently
+   * until it resumes. An organization whose reason for disabling the personal
+   * space is contractual — the work made here belongs to the institution —
+   * turns this on, because an unpaid invoice does not void a contract.
+   */
+  policy_survives_suspension: z.boolean(),
+})
+export type PresetSettings = z.infer<typeof PresetSettingsSchema>
+export type PresetSettingKey = keyof PresetSettings
+export const PRESET_SETTING_KEYS = Object.freeze(
+  Object.keys(PresetSettingsSchema.shape) as readonly PresetSettingKey[],
+)
+
+/** `workspaces.settings` — per-workspace overrides only. */
+export const WorkspaceSettingsSchema = PresetSettingsSchema.partial()
+export type WorkspaceSettings = z.infer<typeof WorkspaceSettingsSchema>
+
+const EMAIL_DOMAIN_PATTERN = /^[a-z0-9-]+(\.[a-z0-9-]+)+$/
+
+/** `organizations.settings` — preset overrides plus org-only keys. */
+export const OrgSettingsSchema = PresetSettingsSchema.partial().extend({
+  /** Lower-case domains that join codes / domain auto-join accept. Empty = any. */
+  allowed_email_domains: z.array(z.string().regex(EMAIL_DOMAIN_PATTERN)).optional(),
+  /** Per-org relabelling of the kind vocabulary (./vocabulary.ts). */
+  vocabulary_overrides: z.record(z.string(), z.string()).optional(),
+})
+export type OrgSettings = z.infer<typeof OrgSettingsSchema>

package/src/organizations/views.ts

@@ -0,0 +1,220 @@
+import type {
+  MemberStatus,
+  OrgKind,
+  OrgRole,
+  OrgSettings,
+  OrgStatus,
+  WorkspaceRole,
+  WorkspaceSettings,
+} from "./types.js"
+
+/**
+ * What the organization endpoints RETURN.
+ *
+ * `types.ts` carries what a client must send and the codes it must dispatch
+ * on; this carries the other half of the same wire contract — the shapes that
+ * come back. It lives here for the same reason: the SDK, the CLI, the app and
+ * any third-party integration all read these, and a shape described in three
+ * places is a shape that drifts in two of them.
+ *
+ * CONTRACT ONLY, like its sibling. There is no resolution logic here, no
+ * access rule, no vocabulary — a view names fields, it does not decide who
+ * may see them. Fields the server omits for a caller without the standing to
+ * see them are OPTIONAL here rather than nullable: absent means "not for
+ * you", `null` means "genuinely unset", and a client that cannot tell those
+ * apart will render the wrong thing.
+ */
+
+export interface OrganizationView {
+  id: string
+  slug: string
+  name: string
+  kind: OrgKind
+  status: OrgStatus
+  ownerUserId: string
+  settings: OrgSettings
+  termsAcceptedAt: string | null
+  createdAt: string
+  updatedAt: string
+  /** The CALLER's role. Absent on a read that did not establish membership. */
+  role?: OrgRole
+  memberStatus?: MemberStatus
+}
+
+export interface OrgMemberView {
+  userId: string
+  role: OrgRole
+  status: MemberStatus
+  joinedAt: string
+  email: string | null
+  displayName: string | null
+  avatarUrl: string | null
+}
+
+export interface WorkspaceView {
+  id: string
+  orgId: string
+  name: string
+  slug: string
+  description: string | null
+  settings: WorkspaceSettings
+  defaultProjectId: string | null
+  archived: boolean
+  archivedAt: string | null
+  createdAt: string
+  updatedAt: string
+  /** The CALLER's role. Absent on a read that did not establish membership. */
+  role?: WorkspaceRole
+  memberStatus?: MemberStatus
+}
+
+export interface WorkspaceMemberView {
+  userId: string
+  role: WorkspaceRole
+  displayName: string | null
+  avatarUrl: string | null
+  addedAt: string
+  /** Workspace admins only — absent for a plain member's read. */
+  status?: MemberStatus
+  creditCap?: number | null
+}
+
+/** Where an invitation stands. `expired` is derived from `expiresAt`, not stored. */
+export type InvitationState = "open" | "accepted" | "revoked" | "expired"
+
+export interface InvitationView {
+  id: string
+  orgId: string
+  workspaceId: string | null
+  email: string
+  orgRole: OrgRole
+  workspaceRole: WorkspaceRole | null
+  invitedBy: string | null
+  state: InvitationState
+  expiresAt: string
+  acceptedAt: string | null
+  revokedAt: string | null
+  createdAt: string
+}
+
+/**
+ * One row per address a create/resend was asked for.
+ *
+ * `link` is present whenever the address was NOT emailed — an install with no
+ * mail provider, or a delivery that failed. A client MUST surface it: the
+ * invitation exists either way, and without the link nobody can reach it.
+ */
+export interface InvitationDelivery {
+  email: string
+  status: "sent" | "link_only" | "failed"
+  link?: string
+}
+
+/**
+ * What an invitee sees BEFORE signing in — the one organization read that
+ * needs no token. `email` comes back masked, so the invitee can recognise
+ * their own address without the link disclosing it to whoever holds it.
+ */
+export interface InvitationPreview {
+  orgName: string
+  kind: OrgKind
+  vocabulary: Record<string, string>
+  inviterName: string | null
+  workspaceName: string | null
+  email: string
+  expiresAt: string
+  state: InvitationState
+}
+
+export interface JoinCodeView {
+  code: string
+  enabled: boolean
+  rotatedAt: string
+  rotatedBy: string | null
+}
+
+/**
+ * What `GET /v1/me` reports about the caller's memberships.
+ *
+ * Deliberately a SUMMARY, not the full views above: this is the payload every
+ * client loads on every session start, and it answers one question — what am
+ * I a member of, and what may I call each thing. Names, roles, and the
+ * resolved vocabulary are here because a switcher cannot render without them;
+ * descriptions, timestamps and default projects are not, because a switcher
+ * never shows them and `GET /v1/orgs/:id` exists.
+ *
+ * The settings block is narrowed to the three keys a CLIENT can act on. The
+ * rest of an organization's settings are enforced server-side, and shipping
+ * them here would invite a client to enforce them badly.
+ */
+export interface OrganizationSummary {
+  id: string
+  slug: string
+  name: string
+  kind: OrgKind
+  status: OrgStatus
+  /** The caller's own role and standing — always present in this payload. */
+  role: OrgRole
+  memberStatus: MemberStatus
+  settings: {
+    personal_space_enabled: boolean
+    allowed_email_domains: string[]
+    vocabulary_overrides: Record<string, string>
+  }
+  /** Resolved labels, so no client hard-codes "Class" or "Team". */
+  vocabulary: Record<string, string>
+}
+
+export interface WorkspaceSummary {
+  id: string
+  orgId: string
+  name: string
+  slug: string
+  role: WorkspaceRole
+  memberStatus: MemberStatus
+  archived: boolean
+}
+
+/**
+ * The organizations block on `GET /v1/me`.
+ *
+ * THREE distinct states, and a client that collapses them is wrong in a way
+ * users feel: the fields ABSENT means this install has no organizations at
+ * all; present and empty means the account belongs to none; and
+ * `organizationsUnavailable` means the lookup FAILED — in which case a
+ * client must KEEP whatever selection it already had, because telling someone
+ * their school vanished during a cache blip is worse than a stale switcher.
+ */
+export interface MeOrganizations {
+  organizations?: OrganizationSummary[]
+  workspaces?: WorkspaceSummary[]
+  lastWorkspaceId?: string | null
+  organizationsUnavailable?: boolean
+}
+
+/**
+ * One recorded action in an organization's audit log.
+ *
+ * `action` is an OPEN vocabulary and a client must not exhaust it: new
+ * actions are added as the product grows, and a switch that throws on an
+ * unknown one turns a new feature into a broken page. Render what you
+ * recognise, fall back to the raw string for the rest.
+ *
+ * `actor` is null for anything the system did on nobody's behalf.
+ */
+export interface OrgAuditEntry {
+  id: string
+  workspaceId: string | null
+  action: string
+  targetType: string | null
+  targetId: string | null
+  details: Record<string, unknown>
+  createdAt: string
+  actor: { userId: string; displayName: string | null; email: string | null } | null
+}
+
+/** A cursor-paged read. The cursor is part of the answer, not a side channel. */
+export interface OrgPage<T> {
+  data: T[]
+  nextCursor: string | null
+}

package/src/producer-types.ts

@@ -79,6 +79,12 @@ export const VIDEO_PRODUCER_TYPES: ReadonlySet<string> = new Set([
   "cinematic-avatar",
   // Assemble Narrated Video: fits N (clip, voice) blocks into one MP4 → video.
   "assemble-narrated-video",
+  // Still to Video: one still image + one audio track → MP4 (local FFmpeg,
+  // no provider). Emits generatedVideoUrl like every other ffmpeg video node.
+  "still-to-video",
+  // Slideshow: 2-100 stills + one optional audio track → MP4 (local FFmpeg,
+  // no provider). Same contract; images arrive via the image-collage lane.
+  "slideshow",
 ])
 
 /**

package/src/smart-cut-windows.ts

@@ -1,19 +1,12 @@
 /**
- * Smart-cut best-pair SEARCH WINDOWS — the shared bound + clamp for
+ * Smart-cut SEARCH WINDOWS — the shared bound + clamp for
  * generate-video-pro's `smartCutFramesPrev` / `smartCutFramesNext`.
  *
- * What they do: the best-pair matcher (the mode the node calls "legacy-8x8")
- * PSNR-compares the last N frames of a segment against the first M of the
- * next, ends the previous clip ON the best match and starts the next right
- * AFTER its twin — so the duplicated frame plays once and motion stays
- * continuous. N and M are those windows. Absent → the engine's own 8/8
- * default, which is byte-identical to the behavior before they were
- * exposed.
- *
- * Why wider helps: a continuation can re-enact a longer stretch of the
- * previous tail than 8 frames covers, and a match outside the window is
- * simply never found — the boundary silently falls back to the fixed
- * freeze-trims. recast pins 24/24 for exactly this reason.
+ * They bound how much of each side of a boundary the engine considers when
+ * it places the cut: N frames from the end of a segment and M from the start
+ * of the next. Absent → the engine's own default, byte-identical to the
+ * behavior before they were exposed. A boundary the engine cannot resolve
+ * inside the window falls back to the fixed freeze-trims; recast pins 24/24.
  *
  * Why a shared clamp: the canvas node (single-node Run) and the orchestrator
  * (workflow Run) are two independent send paths into the same engine route,
@@ -23,10 +16,8 @@
  * and the two paths cannot drift apart.
  */
 
-/** Widest window the UI offers. The engine route itself accepts up to 48;
- *  24 is the product cap — it already covers a full second of re-enactment
- *  at 24fps, and every frame added past the real overlap only costs match
- *  time and invites a spurious pairing. */
+/** Widest window the UI offers (the engine route itself accepts up to 48).
+ *  Past this, added frames only cost search time and invite a false match. */
 export const SMART_CUT_WINDOW_MAX = 24
 /** Narrowest meaningful window — one frame each side. */
 export const SMART_CUT_WINDOW_MIN = 1

package/src/suno-track-sources.ts

@@ -0,0 +1,23 @@
+/**
+ * Node types whose output carries Suno chaining ids (`sunoTrackId` /
+ * `sunoTaskId`) for a downstream Suno node (extend / separate / replace /
+ * add-vocals / …) to chain off.
+ *
+ * One set for the three readers — the canvas resolver, the orchestrator
+ * resolver, and the config panels' "Inherited" hint (#819). They used to keep
+ * their own copies and drifted: the canvas read ids off a `suno-separate`
+ * (whose output is stems, not a track) while the orchestrator ignored it, so
+ * the same graph resolved on one path and not the other. Structural
+ * vocabulary only — node type names, no prompt content.
+ */
+export const SUNO_TRACK_SOURCE_TYPES: ReadonlySet<string> = new Set([
+  "suno-generate",
+  "suno-cover",
+  "suno-extend",
+  "suno-mashup",
+  "suno-replace-section",
+  "suno-add-instrumental",
+  "suno-add-vocals",
+  "suno-convert-wav",
+  "suno-upload-extend",
+])

package/src/surround.ts

@@ -1,48 +1,25 @@
 /**
- * Surround continuation — shared single source of truth.
+ * Surround continuation — the shared WIRE CONTRACT.
  *
  * The Location 360° "look-around" builds each ring view (45°, 90°, …) as an
- * image-to-image continuation of the previous view. The platform forces
- * geometric continuity by handing the model a half-done frame: one edge holds
- * the previous view's carried pixels, the rest is flat gray, and the model is
- * asked to paint the gray region.
+ * image-to-image continuation of the previous one.
  *
- * This module owns the bits that are pure and reused across the route Zod
- * schema, the SDK input type, and the worker: the direction enum, the carried
- * fraction defaults, and the fill prompt. The geometry math + sharp compositing
- * + color harmonization live backend-side (they need `sharp`).
+ * This module owns only what the route Zod schema, the SDK input type, and the
+ * worker all need to agree on: the direction enum and the carried-fraction
+ * defaults. The fill prompt lives in `@nodaro/prompts` (never published) and
+ * the compositing/harmonization engine is private.
  */
 
 /**
- * The carry/paint axis for a continuation.
- *
- * PAN (horizontal — half-carry continuation):
- * - `right` — turning right: the new frame's LEFT edge continues the previous
- *   view's RIGHT edge, so the carried band sits on the LEFT, painted on the RIGHT.
- * - `left` — turning left: the new frame's RIGHT edge continues the previous
- *   view's LEFT edge, so the carried band sits on the RIGHT, painted on the LEFT.
- *   (Mirror of `right`. Lets studio chain BOTH ways from a keyframe, capping
- *   chain depth so quality doesn't compound down a long one-way chain.)
- *
- * TILT (vertical — thin-strip, subject-driven re-render):
- * - `up` — tilting straight up: render the open SKY overhead. A thin strip of
- *   the establishing shot's TOP edge is carried into the new frame's BOTTOM for
- *   a soft horizon transition; the rest is painted as sky (NOT a mirrored
- *   landscape).
- * - `down` — tilting straight down: render the GROUND below. A thin strip of the
- *   BOTTOM edge is carried into the new frame's TOP.
+ * The camera move a continuation represents: `right` / `left` pan the view
+ * horizontally, `up` / `down` tilt it vertically.
  */
 export const SURROUND_DIRECTIONS = ["right", "left", "up", "down"] as const
 export type SurroundDirection = (typeof SURROUND_DIRECTIONS)[number]
 
-/** Half the frame is carried for a horizontal pan (matches studio's composite). */
+/** Default carried fraction for a horizontal pan. */
 export const DEFAULT_CARRIED_FRACTION = 0.5
-/**
- * Tilts carry only a thin horizon strip. Carrying half of a horizontal frame is
- * exactly what makes the model echo/mirror the landscape vertically instead of
- * rendering what's actually overhead/underfoot — so tilts keep the carry small
- * and let the tilt prompt drive the subject.
- */
+/** Default carried fraction for a vertical tilt. */
 export const TILT_CARRIED_FRACTION = 0.12
 
 /** True for the vertical tilt directions (up/down), false for the pans. */
@@ -54,60 +31,3 @@ export function isTiltDirection(direction: SurroundDirection): boolean {
 export function defaultCarriedFraction(direction: SurroundDirection): number {
   return isTiltDirection(direction) ? TILT_CARRIED_FRACTION : DEFAULT_CARRIED_FRACTION
 }
-
-/** Which edge of the NEW frame holds the carried pixels vs the painted region. */
-const EDGE: Record<SurroundDirection, { carried: string; painted: string }> = {
-  right: { carried: "left", painted: "right" },
-  left: { carried: "right", painted: "left" },
-  up: { carried: "bottom", painted: "top" },
-  down: { carried: "top", painted: "bottom" },
-}
-
-/** What a tilt must actually render (NOT a continuation of the landscape). */
-const TILT_SUBJECT: Record<"up" | "down", { word: string; subject: string; where: string }> = {
-  up: {
-    word: "up",
-    subject: "the open sky directly overhead — sky, clouds, or (for an interior) the canopy or ceiling",
-    where: "overhead",
-  },
-  down: {
-    word: "down",
-    subject: "the ground directly below — terrain, floor, or water surface",
-    where: "below",
-  },
-}
-
-/**
- * Build the fill prompt the model receives alongside the half-carry composite.
- *
- * `userPrompt` (an optional scene hint from the caller) is woven in front. PAN
- * directions get the seamless-continuation prompt (with the anti-golden-hour
- * negative that fights the documented warm-regrade drift). TILT directions get a
- * subject-forcing prompt — render the sky / ground overhead / below, explicitly
- * NOT a mirrored landscape — which is what stops the vertical echo.
- */
-export function buildSurroundFillPrompt(direction: SurroundDirection, userPrompt?: string): string {
-  const scene = userPrompt && userPrompt.trim() ? `${userPrompt.trim()}. ` : ""
-  const { carried, painted } = EDGE[direction]
-
-  if (direction === "up" || direction === "down") {
-    const t = TILT_SUBJECT[direction]
-    return (
-      `${scene}` +
-      `This is a camera tilted straight ${t.word} from the same scene. The ${carried} strip holds real, finished pixels from the edge of the horizon view; the ${painted} region is flat gray and MUST be painted as ${t.subject}. ` +
-      `Render what is genuinely ${t.where} — do NOT repeat, mirror, or continue the landscape, and do NOT draw a horizon line or distant scenery in the painted region. ` +
-      `CRITICAL: keep the ${carried} strip unchanged and match the scene's EXACT lighting, time of day, white balance, and color grade — the same light as the ${carried} strip; no golden hour, no sunset, no warm relight, no cinematic regrade. ` +
-      `Blend smoothly into the ${carried} strip with no visible seam. No people, no text, no labels, no watermarks.`
-    )
-  }
-
-  // pan (right / left)
-  return (
-    `${scene}` +
-    `This is a partial frame: the ${carried} portion contains real, finished pixels and the ${painted} portion is flat gray that MUST be painted in. ` +
-    `Paint ONLY the ${painted} gray region as a natural, seamless continuation of the ${carried} portion — same scene, same perspective, continuing the horizon, geometry, and content across the boundary with no break. ` +
-    `Keep the ${carried} portion completely unchanged. ` +
-    `CRITICAL: do NOT change the lighting, exposure, white balance, or time of day. Match the ${carried} portion's EXACT light, color temperature, and contrast across the whole frame — if it is flat overcast daylight, keep flat overcast daylight. No golden hour, no sunset, no warm relight, no cinematic regrade. ` +
-    `The seam between the ${carried} and ${painted} portions must be invisible. No people, no text, no labels, no watermarks.`
-  )
-}