@nodaro/shared 3.23.0 → 3.25.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/dist/index.cjs +625 -151
  2. package/dist/index.cjs.map +1 -1
  3. package/dist/index.d.cts +389 -48
  4. package/dist/index.d.ts +389 -48
  5. package/dist/index.js +582 -152
  6. package/dist/index.js.map +1 -1
  7. package/package.json +1 -1
  8. package/src/__tests__/credit-identifiers.test.ts +19 -6
  9. package/src/__tests__/dialogue-capabilities.test.ts +3 -2
  10. package/src/__tests__/edit-plan-minute-ids.test.ts +82 -0
  11. package/src/__tests__/json-kinds.test.ts +179 -0
  12. package/src/__tests__/presentation-utils.test.ts +1 -0
  13. package/src/__tests__/preview-gate.test.ts +2 -2
  14. package/src/__tests__/pricing-default-duration.test.ts +56 -15
  15. package/src/__tests__/private-host.test.ts +24 -0
  16. package/src/__tests__/render-nodes.test.ts +22 -3
  17. package/src/__tests__/tts-capabilities.test.ts +61 -1
  18. package/src/__tests__/video-link-input.test.ts +148 -0
  19. package/src/__tests__/video-link-needs.test.ts +67 -0
  20. package/src/__tests__/video-request-normalize.test.ts +18 -3
  21. package/src/collections.ts +20 -0
  22. package/src/credit-identifiers.ts +48 -37
  23. package/src/edit-plan-contract.ts +67 -1
  24. package/src/fan-out-rows.ts +2 -2
  25. package/src/handle-aliases.ts +29 -26
  26. package/src/index.ts +46 -1
  27. package/src/json-kinds.ts +188 -0
  28. package/src/model-catalog.ts +121 -8
  29. package/src/model-constants.ts +68 -42
  30. package/src/node-default-mappings.ts +1 -0
  31. package/src/pipeline-types.ts +13 -2
  32. package/src/presentation-utils.ts +8 -1
  33. package/src/private-host.ts +91 -0
  34. package/src/producer-types.ts +3 -0
  35. package/src/render-nodes.ts +12 -1
  36. package/src/scene-node-types.ts +17 -5
  37. package/src/social-post-readers.ts +37 -0
  38. package/src/video-link.ts +238 -0
  39. package/src/voices.ts +16 -9
@@ -50,7 +50,7 @@ const PipelineModelStageEnum = z.enum(PIPELINE_MODEL_STAGES)
50
50
  export const PIPELINE_PINNABLE_IMAGE_MODELS = [
51
51
  "nano-banana",
52
52
  "nano-banana-pro",
53
- "nano-banana-2",
53
+ "nano-banana-2-1",
54
54
  "flux",
55
55
  "gpt-image",
56
56
  "gpt-image-2",
@@ -59,6 +59,17 @@ export const PIPELINE_PINNABLE_IMAGE_MODELS = [
59
59
  ] as const
60
60
  export type PipelinePinnableImageModel = (typeof PIPELINE_PINNABLE_IMAGE_MODELS)[number]
61
61
 
62
+ // Image models no longer OFFERED as a pin but still honoured when a saved
63
+ // pipeline names one: Nano Banana 2.1 replaced Nano Banana 2 in the picker
64
+ // (decided 2026-10-08), and a pipeline pinned to NB2 before that keeps its pin.
65
+ export const PIPELINE_LEGACY_PINNED_IMAGE_MODELS = ["nano-banana-2"] as const
66
+
67
+ /** Every image model a pipeline's config may name: the offered pins plus the legacy ones. */
68
+ export const PIPELINE_ACCEPTED_IMAGE_MODELS = [
69
+ ...PIPELINE_PINNABLE_IMAGE_MODELS,
70
+ ...PIPELINE_LEGACY_PINNED_IMAGE_MODELS,
71
+ ] as const
72
+
62
73
  export const PIPELINE_PINNABLE_VIDEO_MODELS = [
63
74
  "kling-turbo",
64
75
  "kling",
@@ -91,7 +102,7 @@ export const PIPELINE_PINNABLE_SCRIPT_LLMS = [
91
102
  ] as const
92
103
  export type PipelinePinnableScriptLlm = (typeof PIPELINE_PINNABLE_SCRIPT_LLMS)[number]
93
104
 
94
- const ImageModelEnum = z.enum(PIPELINE_PINNABLE_IMAGE_MODELS)
105
+ const ImageModelEnum = z.enum(PIPELINE_ACCEPTED_IMAGE_MODELS)
95
106
  const VideoModelEnum = z.enum(PIPELINE_PINNABLE_VIDEO_MODELS)
96
107
  const ScriptLlmEnum = z.enum(PIPELINE_PINNABLE_SCRIPT_LLMS)
97
108
 
@@ -8,6 +8,7 @@ import type { PresentationItem } from "./presentation-types.js"
8
8
  import { AUDIO_PRODUCER_TYPES, VIDEO_PRODUCER_TYPES } from "./producer-types.js"
9
9
  import { canonicalizeOverrideKeys } from "./exposed-field-keys.js"
10
10
  import { RENDER_NODE_TYPE_IDS } from "./render-nodes.js"
11
+ import { dropStaleVideoLinkFields } from "./video-link.js"
11
12
 
12
13
  // ---------------------------------------------------------------------------
13
14
  // Node type sets
@@ -35,6 +36,7 @@ export const INPUT_NODE_TYPES = new Set([
35
36
  "action-fx",
36
37
  "temporal",
37
38
  "reference-audio",
39
+ "youtube-video",
38
40
  ])
39
41
 
40
42
  const TRIGGER_NODE_TYPES = new Set([
@@ -346,6 +348,8 @@ export const INPUT_FIELD_MAP: Record<string, InputFieldSchema> = {
346
348
  "upload-video": { key: "url", type: "video-url" },
347
349
  "upload-audio": { key: "url", type: "audio-url" },
348
350
  "reference-audio": { key: "extractedAudioUrl", type: "audio-url" },
351
+ // A LINK, not an upload (rule: `videoLinkInputProblem`, video-link.ts); still a `video-url` media input.
352
+ "youtube-video": { key: "youtubeUrl", type: "video-url" },
349
353
  // --- Classic parameters ---
350
354
  "provider": { key: "provider", type: "select" },
351
355
  "style-guide": { key: "text", type: "text" }, // reads data.text (was wrongly "styleGuide")
@@ -450,7 +454,10 @@ export function mergeNodeInputOverrides(
450
454
  data: Record<string, unknown>,
451
455
  overrides: Record<string, unknown>,
452
456
  ): Record<string, unknown> {
453
- const merged: Record<string, unknown> = { ...data, ...canonicalizeOverrideKeys(nodeType, overrides) }
457
+ const incoming = canonicalizeOverrideKeys(nodeType, overrides)
458
+ // A Video URL node on a new link sheds what was fetched for the old one.
459
+ const base = nodeType === "youtube-video" ? dropStaleVideoLinkFields(data, incoming) : data
460
+ const merged: Record<string, unknown> = { ...base, ...incoming }
454
461
  const schema = nodeType ? INPUT_FIELD_MAP[nodeType] : undefined
455
462
  if (
456
463
  schema &&
@@ -0,0 +1,91 @@
1
+ /**
2
+ * Which hosts a server-side fetch must never be pointed at: loopback, private,
3
+ * link-local, cloud-metadata, multicast and reserved addresses. Pure and
4
+ * dependency-free, so the server's SSRF gates (`safeFetch`, `safeUrlSchema`) and
5
+ * the app runner's link card judge a host with the SAME rule — a link the card
6
+ * accepts is not one the server then refuses for its address.
7
+ *
8
+ * Literal hosts only. A name that RESOLVES to a private address is caught where
9
+ * the connection is made (`safeFetch` re-validates the resolved IP); nothing
10
+ * here does DNS.
11
+ */
12
+
13
+ /**
14
+ * True if the IP belongs to a range we refuse to connect to from server-side
15
+ * fetches. Covers IPv4 loopback/private/link-local/cloud-metadata/multicast
16
+ * and the equivalent IPv6 classes (including IPv4-mapped IPv6 embeddings).
17
+ */
18
+ export function isPrivateOrReservedIP(ip: string): boolean {
19
+ const v4 = ip.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/)
20
+ if (v4) {
21
+ const a = Number(v4[1])
22
+ const b = Number(v4[2])
23
+ if (a === 0) return true // 0.0.0.0/8 "this network"
24
+ if (a === 127) return true // 127.0.0.0/8 loopback
25
+ if (a === 10) return true // 10.0.0.0/8 private
26
+ if (a === 172 && b >= 16 && b <= 31) return true // 172.16.0.0/12 private
27
+ if (a === 192 && b === 168) return true // 192.168.0.0/16 private
28
+ if (a === 169 && b === 254) return true // 169.254.0.0/16 link-local + AWS/GCP metadata
29
+ if (a === 100 && b >= 64 && b <= 127) return true // 100.64.0.0/10 CGN
30
+ if (a === 198 && (b === 18 || b === 19)) return true // 198.18.0.0/15 benchmarking
31
+ if (a >= 224) return true // 224.0.0.0/4 multicast + 240.0.0.0/4 reserved + 255.255.255.255
32
+ return false
33
+ }
34
+ // IPv6. Hostnames from URL parsing come without brackets.
35
+ const lower = ip.toLowerCase()
36
+ if (lower === "::" || lower === "::1") return true // unspecified / loopback
37
+ if (lower.startsWith("fe80:") || lower.startsWith("fe80::")) return true // link-local fe80::/10
38
+ if (/^f[cd]/.test(lower)) return true // unique-local fc00::/7
39
+ if (lower.startsWith("ff")) return true // multicast ff00::/8
40
+ if (lower.startsWith("::ffff:")) {
41
+ // IPv4-mapped IPv6. WHATWG URL parsing normalises the dotted-quad tail
42
+ // into two hex quads (`::ffff:127.0.0.1` → `::ffff:7f00:1`), so handle
43
+ // both forms.
44
+ const tail = lower.slice(7)
45
+ if (tail.includes(".")) {
46
+ return isPrivateOrReservedIP(tail)
47
+ }
48
+ const parts = tail.split(":")
49
+ if (parts.length === 2) {
50
+ const hi = parseInt(parts[0] || "0", 16)
51
+ const lo = parseInt(parts[1] || "0", 16)
52
+ if (Number.isFinite(hi) && Number.isFinite(lo)) {
53
+ const ipv4 = `${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`
54
+ return isPrivateOrReservedIP(ipv4)
55
+ }
56
+ }
57
+ // Unrecognisable mapped form — fail closed, treat as reserved.
58
+ return true
59
+ }
60
+ if (lower.startsWith("::") && lower !== "::" && lower !== "::1") {
61
+ // IPv4-compatible IPv6 (deprecated ::/96): the low 32 bits are an IPv4.
62
+ // WHATWG URL parsing presents `::127.0.0.1` as EITHER a dotted tail or two
63
+ // hex quads (`::7f00:1`), exactly like the ::ffff: case above — handle both,
64
+ // or the canonical hex form silently fails open.
65
+ const tail = lower.slice(2)
66
+ if (/^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(tail)) {
67
+ return isPrivateOrReservedIP(tail)
68
+ }
69
+ const parts = tail.split(":")
70
+ if (parts.length === 2 && /^[0-9a-f]{1,4}$/.test(parts[0]) && /^[0-9a-f]{1,4}$/.test(parts[1])) {
71
+ const hi = parseInt(parts[0], 16)
72
+ const lo = parseInt(parts[1], 16)
73
+ if (Number.isFinite(hi) && Number.isFinite(lo)) {
74
+ return isPrivateOrReservedIP(`${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`)
75
+ }
76
+ }
77
+ }
78
+ return false
79
+ }
80
+
81
+ /**
82
+ * True when a URL hostname (as `new URL(...).hostname` gives it, IPv6 still in
83
+ * brackets) names this machine or a private/reserved IP literal. WHATWG parsing
84
+ * has already folded decimal, octal and hex IPv4 spellings (`2130706433`,
85
+ * `0x7f.1`) into dotted form, so those are caught as IP literals.
86
+ */
87
+ export function isLocalOrPrivateHostname(hostname: string): boolean {
88
+ const host = hostname.toLowerCase().replace(/^\[|\]$/g, "").replace(/\.$/, "")
89
+ if (host === "localhost" || host.endsWith(".localhost")) return true
90
+ return isPrivateOrReservedIP(host)
91
+ }
@@ -54,6 +54,9 @@ export const VIDEO_PRODUCER_TYPES: ReadonlySet<string> = new Set([
54
54
  // doesn't reject face-swap → video-consumer edges that the orchestrator
55
55
  // would happily route at runtime.
56
56
  "face-swap",
57
+ // Speaker View (C3.2): an EDL rendered with its speakers framed — one VIDEO
58
+ // out (no audio-only render). Registered in RENDER_NODE_TYPES as well.
59
+ "speaker-view",
57
60
  "video-retake",
58
61
  // video-sfx: adds an SFX track to a video → emits a video URL. Belongs here so
59
62
  // canvas handle validation accepts video-sfx → video-consumer edges and the
@@ -15,7 +15,7 @@
15
15
  * (by quality or otherwise — only its credit id changes), so the same key
16
16
  * answers for `node.type` and for `jobs.job_type`.
17
17
  */
18
- import { applyEdlCreditId } from "./credit-identifiers.js"
18
+ import { applyEdlCreditId, speakerViewCreditId } from "./credit-identifiers.js"
19
19
  import type { RenderMedium } from "./render-output.js"
20
20
 
21
21
  /** Where a render's player maps the output clock back to the master clock
@@ -60,6 +60,17 @@ export const RENDER_NODE_TYPES: Readonly<Record<string, RenderNodeDescriptor>> =
60
60
  latestBatch: true,
61
61
  jsonKind: "transcript",
62
62
  }),
63
+ // Speaker View (C3.2): video only; its `json` is the EDL as it drew it (the
64
+ // turns split, the layouts written), so a player maps the output clock
65
+ // through THAT, and Add Captions never takes it for a Transcript.
66
+ "speaker-view": descriptor({
67
+ mediumOf: () => "video",
68
+ creditId: (quality) => speakerViewCreditId(quality),
69
+ clockMapFrom: "output-json",
70
+ ownerOnlyListing: true,
71
+ latestBatch: true,
72
+ jsonKind: "edl",
73
+ }),
63
74
  })
64
75
 
65
76
  /** Every render node type, in registry order. */
@@ -20,6 +20,16 @@ export const TransitionTypeSchema = z.enum([
20
20
  ])
21
21
  export type TransitionType = z.infer<typeof TransitionTypeSchema>
22
22
 
23
+ /**
24
+ * Tags a ShotSpec field that only a render or the user writes — measured
25
+ * audio, the Editor LLM's cut, the dialogue no-cut zone, an accepted
26
+ * match-cut break — and never the plan. Fields named for a url or an asset id
27
+ * need no tag (their name already says so). A custom registry, not `.meta()`,
28
+ * so the tag never appears in a JSON schema rendered from ShotSpecSchema.
29
+ */
30
+ export const sceneRenderStateRegistry = z.registry<{ render_state: true }>()
31
+ const RENDER_STATE = { render_state: true } as const
32
+
23
33
  /**
24
34
  * ShotSpec — one shot inside a SceneNodeData.
25
35
  * Mirrors Architecture §6.9.1 + v4.1 Method-2/3/5/7/8/10 field additions.
@@ -130,7 +140,7 @@ export const ShotSpecSchema = z.object({
130
140
  // Phase 1D.1 Method 7 — set true when the user accepts a MatchCutCritic
131
141
  // 'break' verdict for this shot's pair. Stage 6 reads this to know the
132
142
  // break is resolved and the scene can advance to Stage 7.
133
- accepted_match_cut_break: z.boolean().optional(),
143
+ accepted_match_cut_break: z.boolean().optional().register(sceneRenderStateRegistry, RENDER_STATE),
134
144
 
135
145
  // ─── Phase 1C.2 — dialogue + editor cut metadata ───────────────────────────
136
146
  // All optional; planning-time ShotSpec carries none of these. Populated by
@@ -139,12 +149,12 @@ export const ShotSpecSchema = z.object({
139
149
  // True when `dialogue_line` is non-null AND the speech generator produced
140
150
  // an audio track. The Editor LLM uses this to gate cut-in / cut-out into
141
151
  // the dialogue_no_cut_zone (Method 5.13.1 — never trim a syllable).
142
- has_dialogue: z.boolean().default(false),
152
+ has_dialogue: z.boolean().default(false).register(sceneRenderStateRegistry, RENDER_STATE),
143
153
 
144
154
  // Measured length of the per-shot speech audio (Stage 7 step 4 writes this).
145
155
  // Separate from `duration_seconds` (the planning intent) — the actual
146
156
  // recording can run longer/shorter than the spec.
147
- actual_audio_duration_sec: z.number().optional(),
157
+ actual_audio_duration_sec: z.number().optional().register(sceneRenderStateRegistry, RENDER_STATE),
148
158
 
149
159
  // Inclusive [start, end] window (seconds, relative to the shot's video clip)
150
160
  // during which the Editor LLM MUST NOT cut. Computed from
@@ -153,7 +163,8 @@ export const ShotSpecSchema = z.object({
153
163
  dialogue_no_cut_zone: z
154
164
  .object({ start: z.number(), end: z.number() })
155
165
  .nullable()
156
- .optional(),
166
+ .optional()
167
+ .register(sceneRenderStateRegistry, RENDER_STATE),
157
168
 
158
169
  // Editor LLM output (Phase 1C.2). Populated by the Editor LLM stage; the
159
170
  // silent-cut-preview sub-gate may patch it via user-applied overrides.
@@ -166,7 +177,8 @@ export const ShotSpecSchema = z.object({
166
177
  transition_duration_sec: z.number().min(0).max(2).optional(),
167
178
  beat_snap_seconds: z.number().nullable().optional(),
168
179
  })
169
- .optional(),
180
+ .optional()
181
+ .register(sceneRenderStateRegistry, RENDER_STATE),
170
182
  })
171
183
  export type ShotSpec = z.infer<typeof ShotSpecSchema>
172
184
 
@@ -0,0 +1,37 @@
1
+ /**
2
+ * Read Inspiration and Read Competitor — the nodes that read posts the person
3
+ * already has (the Inspiration library; a tracked brand's scans) and emit them
4
+ * the way Social Search does: `json` the posts (`SocialPost[]`), `text` their
5
+ * digest (`socialPostsDigest`), one list item per post. Both engines' output
6
+ * branches read this ONE list, so a new reader is routed like the rest.
7
+ *
8
+ * The routes behind them (`/v1/inspiration-read`, `/v1/competitor-read`) are
9
+ * free: they read what the account already holds.
10
+ */
11
+
12
+ export const INSPIRATION_READ_NODE_TYPE = "inspiration-read" as const
13
+ export const COMPETITOR_READ_NODE_TYPE = "competitor-read" as const
14
+
15
+ export const SOCIAL_POST_READER_NODE_TYPES: ReadonlySet<string> = new Set([INSPIRATION_READ_NODE_TYPE, COMPETITOR_READ_NODE_TYPE])
16
+
17
+ export function isSocialPostReaderNodeType(type: unknown): boolean {
18
+ return typeof type === "string" && SOCIAL_POST_READER_NODE_TYPES.has(type)
19
+ }
20
+
21
+ /** The most posts one run reads. */
22
+ export const SOCIAL_READ_LIMIT_MAX = 100
23
+ export const SOCIAL_READ_DEFAULT_LIMIT = 20
24
+ /** A window in hours reaches back at most 30 days; in days, at most a year (Competitors keep at most twelve months of scans). */
25
+ export const SOCIAL_READ_WINDOW_HOURS_MAX = 720
26
+ export const SOCIAL_READ_WINDOW_DAYS_MAX = 365
27
+
28
+ /** `window`: the last N hours or days. `day`: one calendar day in the node's timezone. */
29
+ export const SOCIAL_READ_PERIODS = ["window", "day"] as const
30
+ export type SocialReadPeriod = (typeof SOCIAL_READ_PERIODS)[number]
31
+
32
+ /** Which of a brand's posts Read Competitor reads: its own, posts about it, or both. */
33
+ export const COMPETITOR_READ_ROLES = ["own", "about", "all"] as const
34
+ export type CompetitorReadRole = (typeof COMPETITOR_READ_ROLES)[number]
35
+
36
+ /** A calendar day as the node stores it. */
37
+ export const SOCIAL_READ_DAY_PATTERN = /^\d{4}-\d{2}-\d{2}$/
package/src/video-link.ts CHANGED
@@ -113,6 +113,98 @@ export const VIDEO_LINK_TOLERANT_CONSUMER_TYPES: ReadonlySet<string> = new Set([
113
113
  "content-recipe",
114
114
  ])
115
115
 
116
+ /**
117
+ * The tolerant consumers that DO read something fetched from the link — the
118
+ * separately-fetched audio track (`downloadedAudioUrl`): Transcribe and Suno
119
+ * Cover. The rest of the tolerant set (Dubbing, Content Recipe) read only the
120
+ * page link and need nothing fetched. A subset of the tolerant set by
121
+ * construction (guard test).
122
+ */
123
+ export const VIDEO_LINK_AUDIO_CONSUMER_TYPES: ReadonlySet<string> = new Set(["suno-cover", "transcribe"])
124
+
125
+ /**
126
+ * What a run must FETCH for a Video URL node holding a post link:
127
+ * - `file`: some node in the run watches the video — download the video;
128
+ * - `audio`: every reader is tolerant and at least one takes the audio track —
129
+ * fetch the track only, never the video (and never ask for a part of it);
130
+ * - `none`: every reader takes the page link alone — fetch nothing.
131
+ */
132
+ export type VideoLinkNeed = "file" | "audio" | "none"
133
+
134
+ /** The need of a node read by consumers of these types. No consumer reads nothing. */
135
+ export function videoLinkNeedOf(consumerTypes: Iterable<string>): VideoLinkNeed {
136
+ let audio = false
137
+ for (const type of consumerTypes) {
138
+ if (!VIDEO_LINK_TOLERANT_CONSUMER_TYPES.has(type)) return "file"
139
+ if (VIDEO_LINK_AUDIO_CONSUMER_TYPES.has(type)) audio = true
140
+ }
141
+ return audio ? "audio" : "none"
142
+ }
143
+
144
+ /** The node shape the graph readers need — open on purpose, both engines' nodes fit. */
145
+ export interface VideoLinkGraphNode {
146
+ readonly id: string
147
+ readonly type?: string
148
+ readonly data?: unknown
149
+ }
150
+
151
+ export interface VideoLinkGraphEdge {
152
+ readonly source: string
153
+ readonly target: string
154
+ }
155
+
156
+ /**
157
+ * The need of every Video URL node that feeds the run, by node id — ONE reading
158
+ * of the graph for the editor's pre-run gate, the app runner's card and the
159
+ * server's pre-run fetch, so the three cannot disagree on what a run needs.
160
+ *
161
+ * `scopeIds` are the nodes about to run (`null` = every node: an app runs its
162
+ * whole graph). The run is those nodes plus everything they read from, at any
163
+ * depth; a link that feeds nothing in it is absent (a long video parked on the
164
+ * canvas must never block an unrelated run). Skipped nodes are not part of the
165
+ * run and pull nothing in.
166
+ */
167
+ export function videoLinkRunNeeds(
168
+ scopeIds: readonly string[] | null,
169
+ nodes: readonly VideoLinkGraphNode[],
170
+ edges: readonly VideoLinkGraphEdge[],
171
+ ): Map<string, VideoLinkNeed> {
172
+ const byId = new Map(nodes.map((n) => [n.id, n] as const))
173
+ const isSkipped = (id: string) => (byId.get(id)?.data as { skipped?: unknown } | undefined)?.skipped === true
174
+
175
+ const sourcesOf = new Map<string, string[]>()
176
+ for (const edge of edges) {
177
+ const list = sourcesOf.get(edge.target)
178
+ if (list) list.push(edge.source)
179
+ else sourcesOf.set(edge.target, [edge.source])
180
+ }
181
+
182
+ // Everything the run touches: the nodes about to run plus all they read from.
183
+ const inRun = new Set<string>()
184
+ const queue = (scopeIds ?? nodes.map((n) => n.id)).filter((id) => !isSkipped(id))
185
+ for (const id of queue) inRun.add(id)
186
+ while (queue.length > 0) {
187
+ const current = queue.pop()!
188
+ for (const source of sourcesOf.get(current) ?? []) {
189
+ if (inRun.has(source)) continue
190
+ inRun.add(source)
191
+ queue.push(source)
192
+ }
193
+ }
194
+
195
+ const consumers = new Map<string, string[]>()
196
+ for (const edge of edges) {
197
+ if (byId.get(edge.source)?.type !== "youtube-video" || !inRun.has(edge.target)) continue
198
+ const list = consumers.get(edge.source)
199
+ const type = byId.get(edge.target)?.type ?? ""
200
+ if (list) list.push(type)
201
+ else consumers.set(edge.source, [type])
202
+ }
203
+ const needs = new Map<string, VideoLinkNeed>()
204
+ for (const [id, types] of consumers) needs.set(id, videoLinkNeedOf(types))
205
+ return needs
206
+ }
207
+
116
208
  /**
117
209
  * The fields of a Video URL node's data that decide what it emits. Open-ended
118
210
  * on purpose: both engines hand over the node's whole `data` bag, and a closed
@@ -177,3 +269,149 @@ export function videoLinkNeedsDownload(data: VideoLinkNodeFields): boolean {
177
269
  if (!url || !isSocialVideoUrl(url)) return false
178
270
  return videoLinkDownloadedFile(data) === undefined
179
271
  }
272
+
273
+ // ---------------------------------------------------------------------------
274
+ // The link as an APP INPUT (a published app, MCP `run_app`, the SDK)
275
+ // ---------------------------------------------------------------------------
276
+
277
+ /**
278
+ * File extensions accepted as DIRECT video-file links (pathname suffix match).
279
+ * Mirrors save-to-storage's video auto-detect set.
280
+ */
281
+ export const DIRECT_VIDEO_EXTENSIONS = [".mp4", ".webm", ".mov", ".avi"] as const
282
+
283
+ /**
284
+ * True for a DIRECT video-file link: http(s) whose PATHNAME ends in a video
285
+ * extension — `https://cdn.nodaro.ai/uploads/videos/<id>.mp4` and any other
286
+ * cdn-style link. Query and fragment are ignored (signed CDN links keep the
287
+ * extension in the path); an extension that appears only in the query does
288
+ * not qualify. Host-agnostic BY DESIGN, which is exactly why admission is not
289
+ * sufficient on its own: the download route pre-resolves these hosts before it
290
+ * fetches (`resolvesOnlyToPublicAddresses`), and every other reader goes
291
+ * through the SSRF-guarded fetch.
292
+ *
293
+ * A link carrying a backslash or a control character is refused first
294
+ * (`hasUrlParserHazard`): the route pre-resolves the WHATWG host, and the
295
+ * download tool would fetch whatever host ITS parser reads.
296
+ */
297
+ export function isDirectVideoFileUrl(url: string): boolean {
298
+ if (hasUrlParserHazard(url)) return false
299
+ try {
300
+ const parsed = new URL(url)
301
+ if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return false
302
+ const path = parsed.pathname.toLowerCase()
303
+ return DIRECT_VIDEO_EXTENSIONS.some((ext) => path.endsWith(ext))
304
+ } catch {
305
+ return false
306
+ }
307
+ }
308
+
309
+ /**
310
+ * A YouTube video shorter than this downloads whole the moment the link lands;
311
+ * a longer one (or one whose length could not be read) waits for a part to be
312
+ * chosen. The same 4 minutes Recast and Studio use — a two-hour talk nobody
313
+ * asked for never gets fetched by accident. One number for the canvas node, the
314
+ * app runner's card and the server's pre-run fetch.
315
+ */
316
+ export const AUTO_DOWNLOAD_MAX_SEC = 240
317
+
318
+ /** YouTube's quality cap ("up to N rows"). Other hosts have no ladder worth capping. */
319
+ export const YOUTUBE_MAX_HEIGHT = 1080
320
+
321
+ /** The longest link an app input accepts. A real video link is a few hundred characters. */
322
+ export const MAX_VIDEO_LINK_INPUT_CHARS = 2048
323
+
324
+ export type VideoLinkInputProblem = "empty" | "invalid"
325
+
326
+ /**
327
+ * The ONE rule for what a Video URL app input may hold — the canvas node's own
328
+ * (decided 2026-10-08): a link to a supported social host (downloaded before
329
+ * the nodes that need the file run), or any other http(s) link (passed through
330
+ * as it is, never downloaded; the nodes that read it fetch it through the
331
+ * SSRF-guarded fetch). The app runner's card, the run-request lock and MCP
332
+ * `get_app_inputs` all read it, so a link the card accepts is a link the
333
+ * server accepts, and the reverse.
334
+ *
335
+ * Structural only: the server layers its SSRF guard on top (`safeUrlSchema`),
336
+ * and the card refuses a literal local / private host. A link carrying a
337
+ * backslash or a control character is refused (`hasUrlParserHazard`).
338
+ * `null` = fine; leading and trailing spaces are not a problem (the card trims
339
+ * before it sends).
340
+ */
341
+ export function videoLinkInputProblem(value: unknown): VideoLinkInputProblem | null {
342
+ if (value === undefined || value === null) return "empty"
343
+ if (typeof value !== "string") return "invalid"
344
+ const link = value.trim()
345
+ if (link === "") return "empty"
346
+ if (link.length > MAX_VIDEO_LINK_INPUT_CHARS) return "invalid"
347
+ return isSocialVideoUrl(link) || isHttpLink(link) ? null : "invalid"
348
+ }
349
+
350
+ function isHttpLink(link: string): boolean {
351
+ if (hasUrlParserHazard(link)) return false
352
+ try {
353
+ const parsed = new URL(link)
354
+ return (parsed.protocol === "http:" || parsed.protocol === "https:") && parsed.hostname !== ""
355
+ } catch {
356
+ return false
357
+ }
358
+ }
359
+
360
+ /**
361
+ * The fields of a Video URL node's data that belong to ONE link: the file and
362
+ * audio track fetched from it, the progress of that fetch, and what was read
363
+ * from the link (its id, title, picture, length). Every one of them describes
364
+ * the link it was made for.
365
+ *
366
+ * A run-time override that swaps the link (`dropStaleVideoLinkFields`) drops
367
+ * these first, because the creator's published node carries all of them and a
368
+ * shallow merge would leave them standing under the caller's link — the audio
369
+ * track in particular has no binding to its link (`downloadedAudioUrl` is read
370
+ * straight off the node by Transcribe and Suno Cover), so a caller's episode
371
+ * would be transcribed from the creator's sample. The editor's own
372
+ * link-change reset (`CLEARED_DOWNLOAD` in `lib/video-link-ingest.ts`) is
373
+ * guarded to be inside this list.
374
+ */
375
+ export const VIDEO_LINK_DERIVED_FIELDS = [
376
+ "videoId",
377
+ "title",
378
+ "thumbnailUrl",
379
+ "downloadedVideoUrl",
380
+ "downloadedThumbnailUrl",
381
+ "downloadedFromUrl",
382
+ "downloadedSection",
383
+ "downloadStatus",
384
+ "downloadError",
385
+ "downloadErrorCode",
386
+ "downloadId",
387
+ "downloadIdUrl",
388
+ "downloadMode",
389
+ "downloadAllowSilent",
390
+ "downloadPercent",
391
+ "downloadPhase",
392
+ "sectionStartSec",
393
+ "sectionEndSec",
394
+ "needsRangeChoice",
395
+ "videoDurationSec",
396
+ "downloadedAudioUrl",
397
+ "audioDownloadStatus",
398
+ "audioDownloadError",
399
+ ] as const
400
+
401
+ /**
402
+ * The saved Video URL node data without what belonged to its previous link,
403
+ * when `incoming` (the run's override for the node) points it at a different
404
+ * one. A field the override brings itself is kept (the merge applies it after
405
+ * this). Returns the SAME object when the link is not being changed; never
406
+ * mutates.
407
+ */
408
+ export function dropStaleVideoLinkFields(
409
+ data: Record<string, unknown>,
410
+ incoming: Record<string, unknown>,
411
+ ): Record<string, unknown> {
412
+ if (!("youtubeUrl" in incoming)) return data
413
+ if (trimmed(incoming.youtubeUrl) === trimmed(data.youtubeUrl)) return data
414
+ const out: Record<string, unknown> = { ...data }
415
+ for (const key of VIDEO_LINK_DERIVED_FIELDS) delete out[key]
416
+ return out
417
+ }
package/src/voices.ts CHANGED
@@ -24,10 +24,13 @@ export interface Voice {
24
24
  export interface SharedVoice extends Voice {
25
25
  /**
26
26
  * The best of our TTS providers whose underlying ElevenLabs model the
27
- * voice lists in `verified_languages` (v4 preferred when verified, then v3,
28
- * which renders any voice unmodified, then the cheapest v2 model: turbo
29
- * preferred, else multilingual). Only the base model id `eleven_v4` counts
30
- * toward v4; its `eleven_v4_…` variants do not. Models the deployment does
27
+ * voice lists in `verified_languages`, in the order `elevenlabs-v4` (when
28
+ * verified for the base model `eleven_v4`), then `elevenlabs-v3`, which
29
+ * renders any voice unmodified, then `elevenlabs-v4-turbo` (verified for the
30
+ * exact id `eleven_v4_turbo`), then the cheapest v2 model: `elevenlabs-turbo`
31
+ * preferred, else `elevenlabs-multilingual`. Only those two exact ids count
32
+ * in the v4 family; the other `eleven_v4_…` variants (`_hq`, `_exp`, …) are
33
+ * not models of ours and count toward nothing. Models the deployment does
31
34
  * not offer are never recommended.
32
35
  * Clients without a provider picker should send it as the `provider` on
33
36
  * text-to-speech so generation uses a model the voice is actually verified
@@ -38,11 +41,15 @@ export interface SharedVoice extends Voice {
38
41
  recommendedProvider?: TtsProvider
39
42
  /**
40
43
  * Every TTS provider the voice is verified on and the deployment offers
41
- * (subset of `elevenlabs-v4` / `elevenlabs-v3` / `elevenlabs-turbo` /
42
- * `elevenlabs-multilingual`, v4 first when present, then v3, turbo,
43
- * multilingual); absent whenever `recommendedProvider` is. Clients WITH a provider picker should only snap the
44
- * provider when the current choice is NOT in this set — most voices verify
45
- * more than one, and an explicit user choice within the set must win.
44
+ * (a subset of {@link TtsProvider}, in the order `elevenlabs-v4`,
45
+ * `elevenlabs-v3`, `elevenlabs-v4-turbo`, `elevenlabs-turbo`,
46
+ * `elevenlabs-multilingual` — the same order `recommendedProvider` is picked
47
+ * from, so it is always the first entry); absent whenever
48
+ * `recommendedProvider` is. Clients WITH a provider picker should only snap
49
+ * the provider when the current choice is NOT in this set — most voices
50
+ * verify more than one, and an explicit user choice within the set must win.
51
+ * Do not switch over a closed list of members: a speech model added later
52
+ * joins this set the release it ships.
46
53
  */
47
54
  verifiedProviders?: TtsProvider[]
48
55
  }