@nodaro/shared 3.20.0 → 3.23.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 (86) hide show
  1. package/dist/index.cjs +2287 -195
  2. package/dist/index.cjs.map +1 -1
  3. package/dist/index.d.cts +1938 -82
  4. package/dist/index.d.ts +1938 -82
  5. package/dist/index.js +2119 -196
  6. package/dist/index.js.map +1 -1
  7. package/package.json +1 -1
  8. package/src/__tests__/add-captions-plan.test.ts +33 -0
  9. package/src/__tests__/caption-plan-parse.test.ts +23 -0
  10. package/src/__tests__/caption-segment-schema.test.ts +30 -0
  11. package/src/__tests__/collections.test.ts +253 -0
  12. package/src/__tests__/default-tts-provider.test.ts +46 -0
  13. package/src/__tests__/dialogue-capabilities.test.ts +157 -0
  14. package/src/__tests__/edit-plan-review.test.ts +70 -0
  15. package/src/__tests__/edl-clocks.test.ts +97 -0
  16. package/src/__tests__/edl.test.ts +34 -0
  17. package/src/__tests__/execution-outcome.test.ts +44 -0
  18. package/src/__tests__/fan-out-meta.test.ts +23 -0
  19. package/src/__tests__/fan-out-rows.test.ts +36 -0
  20. package/src/__tests__/fan-out-url-item.test.ts +44 -0
  21. package/src/__tests__/fixtures/speaker-tracks.fixtures.json +622 -0
  22. package/src/__tests__/input-field-extra-keys.test.ts +34 -0
  23. package/src/__tests__/list-consumers-fan-in.test.ts +40 -0
  24. package/src/__tests__/model-tree.test.ts +7 -0
  25. package/src/__tests__/node-pass-through.test.ts +23 -0
  26. package/src/__tests__/node-runtime-keys.test.ts +1 -0
  27. package/src/__tests__/picker-restrictions.test.ts +36 -0
  28. package/src/__tests__/preview-gate.test.ts +305 -0
  29. package/src/__tests__/render-basis.test.ts +176 -0
  30. package/src/__tests__/render-nodes.test.ts +73 -0
  31. package/src/__tests__/render-output.test.ts +392 -0
  32. package/src/__tests__/run-continuation.test.ts +32 -0
  33. package/src/__tests__/speaker-tracks.test.ts +474 -0
  34. package/src/__tests__/speech-pricing.test.ts +69 -0
  35. package/src/__tests__/telegram-channel.test.ts +91 -0
  36. package/src/__tests__/tts-capabilities.test.ts +83 -5
  37. package/src/__tests__/tts-neighbour-text.test.ts +19 -0
  38. package/src/__tests__/ugc-call-body.test.ts +38 -0
  39. package/src/__tests__/ugc-run-state.test.ts +68 -0
  40. package/src/__tests__/video-character-refs.test.ts +213 -0
  41. package/src/__tests__/video-overlay-layer-plan.test.ts +94 -0
  42. package/src/add-captions-plan.ts +50 -0
  43. package/src/caption-plan.ts +45 -0
  44. package/src/caption-segment-schema.ts +82 -0
  45. package/src/collections.ts +462 -0
  46. package/src/competitors.ts +77 -0
  47. package/src/credit-estimators/index.ts +9 -0
  48. package/src/credit-estimators/speech.ts +51 -0
  49. package/src/dialogue-capabilities.ts +48 -0
  50. package/src/edit-plan-contract.ts +20 -9
  51. package/src/edit-plan-review.ts +40 -1
  52. package/src/edl.ts +27 -1
  53. package/src/execution-outcome.ts +41 -0
  54. package/src/fan-out-meta.ts +23 -0
  55. package/src/fan-out-rows.ts +74 -5
  56. package/src/gemini-omni-voices.ts +59 -0
  57. package/src/handle-aliases.ts +295 -0
  58. package/src/i18n/camera-motions.pt-BR.ts +14 -14
  59. package/src/i18n/transitions.pt-BR.ts +13 -13
  60. package/src/index.ts +180 -1
  61. package/src/model-catalog.ts +125 -15
  62. package/src/model-constants.ts +37 -4
  63. package/src/model-tree.ts +5 -1
  64. package/src/node-execution-state.ts +13 -0
  65. package/src/node-mappable-fields.ts +7 -1
  66. package/src/node-pass-through.ts +37 -0
  67. package/src/node-runtime-keys.ts +14 -0
  68. package/src/picker-restrictions.ts +49 -0
  69. package/src/presentation-types.ts +26 -2
  70. package/src/presentation-utils.ts +25 -7
  71. package/src/preview-gate.ts +279 -0
  72. package/src/producer-types.ts +58 -0
  73. package/src/render-final.ts +20 -0
  74. package/src/render-nodes.ts +92 -0
  75. package/src/render-output.ts +565 -0
  76. package/src/run-continuation.ts +39 -0
  77. package/src/speaker-tracks.ts +638 -0
  78. package/src/telegram-channel.ts +140 -0
  79. package/src/transcribe-preflight.ts +8 -4
  80. package/src/tts-capabilities.ts +19 -5
  81. package/src/tts-neighbour-text.ts +46 -0
  82. package/src/ugc-call-body.ts +86 -0
  83. package/src/ugc-run-state.ts +64 -0
  84. package/src/video-character-refs.ts +233 -0
  85. package/src/video-overlay.ts +78 -21
  86. package/src/voices.ts +11 -7
@@ -0,0 +1,82 @@
1
+ import { z } from "zod"
2
+ import {
3
+ ALL_CAPTION_STYLES,
4
+ CAPTION_LOOK_IDS,
5
+ CAPTION_MAX_WORDS_PER_LINE_MAX,
6
+ CAPTION_MAX_WORDS_PER_LINE_MIN,
7
+ } from "./caption-styles.js"
8
+ import { SUPPORTED_FONT_NAMES } from "./supported-fonts.js"
9
+
10
+ /**
11
+ * The add-captions SEGMENT contract — one definition for the route's Zod, the
12
+ * provider's overlap check and both workflow engines' pre-reservation check of a
13
+ * caption plan's segments (a DAG payload never passes the route's validation).
14
+ * Moved here from backend/src/routes/add-captions.ts so the copies can never differ.
15
+ */
16
+
17
+ /** Caption font weight: 100..900 on the 100 grid. */
18
+ export const captionFontWeightSchema = z.number().int().min(100).max(900).multipleOf(100)
19
+
20
+ /** A text caption source must carry a visible glyph (whitespace synthesises to zero words). */
21
+ export const nonBlankCaptionText = z.string().min(1).refine((t) => /\S/.test(t), { message: "text must contain a non-whitespace character" })
22
+
23
+ /** One word-timed caption entry. */
24
+ export const captionInputSchema = z.object({
25
+ text: z.string(),
26
+ // startMs/endMs are the visibility window and drive the highlight; timestampMs
27
+ // is the word timestamp used by tiktok-words token timing; confidence is
28
+ // metadata, ignored by rendering. timestampMs/confidence default to null.
29
+ startMs: z.number().min(0),
30
+ endMs: z.number().min(0),
31
+ timestampMs: z.number().min(0).nullable().default(null),
32
+ confidence: z.number().min(0).max(1).nullable().default(null),
33
+ })
34
+
35
+ /**
36
+ * One caption SEGMENT: a time range, optional levers (each inherits the top-level
37
+ * value when omitted) and optional own words (`text` or `captions[]`; falls back
38
+ * to the shared transcript filtered to the range). A segmented render is entirely
39
+ * Remotion, so any `style` (incl. subtitle) and any look lever is valid on a segment.
40
+ */
41
+ export const captionSegmentInputSchema = z.object({
42
+ startMs: z.number().min(0),
43
+ endMs: z.number().min(0),
44
+ style: z.enum(ALL_CAPTION_STYLES).optional(),
45
+ position: z.enum(["bottom", "top", "center"]).optional(),
46
+ fontSize: z.number().min(12).max(200).optional(),
47
+ color: z.string().optional(),
48
+ backgroundColor: z.string().optional(),
49
+ // A named look preset (outline/clean); explicit levers below override it.
50
+ look: z.enum(CAPTION_LOOK_IDS).optional(),
51
+ fontFamily: z.enum(SUPPORTED_FONT_NAMES).optional(),
52
+ fontWeight: captionFontWeightSchema.optional(),
53
+ strokeColor: z.string().optional(),
54
+ strokeWidth: z.number().min(0).max(40).optional(),
55
+ highlightColor: z.string().optional(),
56
+ uppercase: z.boolean().optional(),
57
+ positionY: z.number().min(0).max(100).optional(),
58
+ animate: z.boolean().optional(),
59
+ maxWordsPerLine: z.number().int().min(CAPTION_MAX_WORDS_PER_LINE_MIN).max(CAPTION_MAX_WORDS_PER_LINE_MAX).optional(),
60
+ text: nonBlankCaptionText.optional(),
61
+ captions: z.array(captionInputSchema).optional(),
62
+ }).refine((s) => s.endMs > s.startMs, { message: "segment endMs must be greater than startMs" })
63
+
64
+ export type CaptionSegmentInput = z.infer<typeof captionSegmentInputSchema>
65
+
66
+ /** Every field a segment may carry, in schema order. */
67
+ export const CAPTION_SEGMENT_SCHEMA_KEYS: readonly string[] = Object.keys(captionSegmentInputSchema.shape)
68
+
69
+ /**
70
+ * Segments must be sorted and non-overlapping. Returns the first offending pair
71
+ * as the route's 400 text; null when none overlap (abutting is fine).
72
+ * `startMs < endMs` per segment is enforced by the schema; this is the cross-segment rule.
73
+ */
74
+ export function findSegmentOverlap(segments: readonly { startMs: number; endMs: number }[]): string | null {
75
+ const sorted = [...segments].sort((a, b) => a.startMs - b.startMs)
76
+ for (let i = 1; i < sorted.length; i++) {
77
+ if (sorted[i]!.startMs < sorted[i - 1]!.endMs) {
78
+ return `segments overlap: [${sorted[i - 1]!.startMs}, ${sorted[i - 1]!.endMs}) and [${sorted[i]!.startMs}, ${sorted[i]!.endMs})`
79
+ }
80
+ }
81
+ return null
82
+ }
@@ -0,0 +1,462 @@
1
+ /**
2
+ * Collections — where a workflow's records live (decided 2026-10-05).
3
+ *
4
+ * A collection belongs to one person and holds records: a title, a text, a
5
+ * link, the links of its pictures / videos / sounds, a small bag of extra
6
+ * fields and where the record came from. Text and links only — never files;
7
+ * a media link from a platform expires on its own schedule, so a consumer
8
+ * that needs the picture later copies it (an upload node), the collection
9
+ * keeps the link as given.
10
+ *
11
+ * Why public: `Collection` / `CollectionRecord` are what `/v1/collections`
12
+ * returns and the SDK's `collections` resource types; the caps are what the
13
+ * page and the API quote; the digest and the ingest map are the ONE rule the
14
+ * read node, MCP and the CLI render records with.
15
+ */
16
+
17
+ export const COLLECTION_NAME_MAX = 80
18
+ export const COLLECTION_DESCRIPTION_MAX = 500
19
+ export const COLLECTION_RECORD_TITLE_MAX = 500
20
+ export const COLLECTION_RECORD_TEXT_MAX = 20_000
21
+ export const COLLECTION_RECORD_URL_MAX = 2_000
22
+ export const COLLECTION_RECORD_MEDIA_MAX = 20
23
+ export const COLLECTION_RECORD_FIELDS_MAX = 50
24
+ export const COLLECTION_RECORD_FIELDS_BYTES_MAX = 16 * 1024
25
+ export const COLLECTION_DEDUPE_KEY_MAX = 300
26
+ export const COLLECTION_IDEMPOTENCY_KEY_MAX = 200
27
+ /** Records per page of `GET /v1/collections/:id/records`. */
28
+ export const COLLECTIONS_PAGE_MAX = 100
29
+ export const COLLECTIONS_PAGE_DEFAULT = 50
30
+ /** The longest a headline (a record's one-line name) gets. */
31
+ export const COLLECTION_HEADLINE_MAX = 120
32
+
33
+ export const COLLECTION_MEDIA_TYPES = ["image", "video", "audio", "link"] as const
34
+ export type CollectionMediaType = (typeof COLLECTION_MEDIA_TYPES)[number]
35
+
36
+ export interface CollectionMedia {
37
+ readonly type: CollectionMediaType
38
+ /** The file's link, as given (never fetched, never copied). */
39
+ readonly url: string
40
+ /** A video's poster frame, when known. */
41
+ readonly posterUrl?: string
42
+ }
43
+
44
+ /** How many collections a person may have, and how many records each may hold. */
45
+ export interface CollectionCaps {
46
+ readonly collections: number
47
+ readonly records: number
48
+ }
49
+
50
+ /**
51
+ * Caps by effective tier (decided 2026-10-05: open to free accounts; past the
52
+ * records cap the OLDEST records are evicted, never the write refused — a
53
+ * scheduled pipeline must not stall silently). `payg` is a derived tier whose
54
+ * entitlements are basic's; `enterprise` reads as business.
55
+ *
56
+ * A tier this table does not know has NO caps here (`collectionCapsForTier`
57
+ * answers undefined): the API then holds the account to no cap rather than to
58
+ * free's, because the cap is enforced by DELETING records — a new tier or a
59
+ * misspelt one must never cost a paying account its records. Add the tier.
60
+ */
61
+ export const COLLECTION_TIER_CAPS: Readonly<Record<string, CollectionCaps>> = {
62
+ free: { collections: 3, records: 500 },
63
+ payg: { collections: 10, records: 5_000 },
64
+ basic: { collections: 10, records: 5_000 },
65
+ standard: { collections: 30, records: 20_000 },
66
+ pro: { collections: 100, records: 100_000 },
67
+ business: { collections: 300, records: 250_000 },
68
+ enterprise: { collections: 300, records: 250_000 },
69
+ }
70
+
71
+ export function collectionCapsForTier(tier: string | null | undefined): CollectionCaps | undefined {
72
+ return tier ? COLLECTION_TIER_CAPS[tier] : undefined
73
+ }
74
+
75
+ export interface Collection {
76
+ readonly id: string
77
+ readonly name: string
78
+ readonly description: string
79
+ readonly recordCount: number
80
+ readonly createdAt: string
81
+ readonly updatedAt: string
82
+ }
83
+
84
+ /** Where a record came from — a node in a run, or a direct write. */
85
+ export interface CollectionRecordSource {
86
+ readonly via?: "api" | "mcp" | "node" | "ui"
87
+ readonly nodeType?: string
88
+ readonly workflowId?: string
89
+ readonly executionId?: string
90
+ readonly nodeId?: string
91
+ }
92
+
93
+ export type CollectionFieldValue = string | number | boolean
94
+
95
+ export interface CollectionRecord {
96
+ readonly id: string
97
+ readonly collectionId: string
98
+ readonly title: string
99
+ readonly text: string
100
+ readonly url: string | null
101
+ readonly media: readonly CollectionMedia[]
102
+ readonly fields: Readonly<Record<string, CollectionFieldValue>>
103
+ /** The normalized key the collection deduplicates on (defaults to the link); null when the record has none. */
104
+ readonly dedupeKey: string | null
105
+ readonly source: CollectionRecordSource
106
+ readonly createdAt: string
107
+ }
108
+
109
+ /** The caller's limits as the API quotes them: `null` is "no limit" (a
110
+ * self-hosted server with no ceiling configured, or a tier the caps table
111
+ * does not know). */
112
+ export interface CollectionLimits {
113
+ readonly collections: number | null
114
+ readonly records: number | null
115
+ }
116
+
117
+ /** The answer of `GET /v1/collections`. `available` is false on a server whose
118
+ * database does not have collections yet (the data is then empty). */
119
+ export interface ListCollectionsResult {
120
+ readonly data: readonly Collection[]
121
+ readonly available: boolean
122
+ /** The caller's limits, so a client never carries its own copy of the tier table. */
123
+ readonly caps: CollectionLimits
124
+ }
125
+
126
+ export type CreateCollectionInput = {
127
+ readonly name: string
128
+ readonly description?: string
129
+ }
130
+
131
+ export type UpdateCollectionInput = {
132
+ readonly name?: string
133
+ readonly description?: string
134
+ }
135
+
136
+ /** Query of `GET /v1/collections/:id/records`. */
137
+ export type ListCollectionRecordsParams = {
138
+ /** Words to find in the title, the text or the link. */
139
+ readonly q?: string
140
+ /** Only records saved at or after this ISO timestamp (date and time). */
141
+ readonly since?: string
142
+ /** The `nextCursor` of the previous page. */
143
+ readonly cursor?: string
144
+ /** 1–100, default 50. */
145
+ readonly limit?: number
146
+ }
147
+
148
+ export interface ListCollectionRecordsResult {
149
+ readonly data: readonly CollectionRecord[]
150
+ readonly nextCursor: string | null
151
+ }
152
+
153
+ /** The body of `POST /v1/collections/:id/records`. An explicit field wins over
154
+ * what `item` (any JSON — a feed post, a search result, an LLM's object) maps to. */
155
+ export type AddCollectionRecordInput = {
156
+ readonly title?: string
157
+ readonly text?: string
158
+ readonly url?: string
159
+ readonly media?: readonly CollectionMedia[]
160
+ readonly fields?: Readonly<Record<string, CollectionFieldValue>>
161
+ readonly dedupeKey?: string
162
+ readonly source?: CollectionRecordSource
163
+ readonly item?: unknown
164
+ }
165
+
166
+ export type CollectionWriteOutcome = "inserted" | "duplicate" | "replayed"
167
+
168
+ export interface AddCollectionRecordResult {
169
+ readonly record: CollectionRecord
170
+ readonly outcome: CollectionWriteOutcome
171
+ /** Records evicted past the collection's cap by this write. */
172
+ readonly evicted: number
173
+ }
174
+
175
+ export type CollectionExportFormat = "csv" | "json"
176
+ export type CollectionDigestFormat = "headlines" | "full"
177
+ export const COLLECTION_DIGEST_SEPARATOR = "\n\n---\n\n"
178
+
179
+ /** The Read Collection node: how far back it may look (720 hours = 30 days; `days` × 24 is held to the same ceiling) and how many records one run emits. */
180
+ export const COLLECTION_READ_WINDOW_HOURS_MAX = 720
181
+ export const COLLECTION_READ_LIMIT_MAX = 200
182
+ export type CollectionReadWindowUnit = "hours" | "days"
183
+ export type CollectionReadOrder = "newest" | "oldest"
184
+
185
+ /** The start of a Read Collection window, as an ISO timestamp — `amount` × `unit` back from `now`, held to the ceiling. */
186
+ export function collectionReadSince(amount: number, unit: CollectionReadWindowUnit, now = Date.now()): string {
187
+ const hours = Math.min(COLLECTION_READ_WINDOW_HOURS_MAX, Math.max(1, Math.floor(Number.isFinite(amount) ? amount : 24)) * (unit === "days" ? 24 : 1))
188
+ return new Date(now - hours * 3_600_000).toISOString()
189
+ }
190
+
191
+ const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
192
+ const str = (v: unknown): string | undefined => (typeof v === "string" && v.trim().length > 0 ? v : undefined)
193
+ const isScalar = (v: unknown): v is CollectionFieldValue =>
194
+ typeof v === "string" || (typeof v === "number" && Number.isFinite(v)) || typeof v === "boolean"
195
+
196
+ /** A link a record may hold: `http(s)`, no whitespace, at most 2,000 characters. */
197
+ export function isCollectionUrl(v: unknown): v is string {
198
+ return typeof v === "string" && /^https?:\/\/\S+$/i.test(v) && v.length <= COLLECTION_RECORD_URL_MAX
199
+ }
200
+ const isHttpUrl = isCollectionUrl
201
+
202
+ /**
203
+ * The first `max` characters of a text, counted as Postgres counts them
204
+ * (`char_length`: code points), so a cut never splits a surrogate pair into a
205
+ * lone half the database refuses.
206
+ */
207
+ export function clampChars(text: string, max: number): string {
208
+ if (text.length <= max) return text
209
+ const points = Array.from(text)
210
+ return points.length <= max ? text : points.slice(0, max).join("")
211
+ }
212
+
213
+ /**
214
+ * The key a collection deduplicates on: trimmed, inner whitespace collapsed,
215
+ * lower-cased, at most 300 characters; null when there is nothing to key on.
216
+ */
217
+ export function normalizeDedupeKey(raw: unknown): string | null {
218
+ if (typeof raw === "number" && Number.isFinite(raw)) raw = String(raw)
219
+ if (typeof raw !== "string") return null
220
+ const compact = raw.trim().replace(/\s+/g, " ")
221
+ // A link keeps its path's case: a short link or a video id is case-sensitive
222
+ // (bit.ly/AbC and bit.ly/abc are two pages). Only its scheme and host are
223
+ // case-insensitive, and the URL parser folds exactly those.
224
+ const key = clampChars(looksLikeLink(compact) ? canonicalUrl(compact) : compact.toLowerCase(), COLLECTION_DEDUPE_KEY_MAX).trim()
225
+ return key.length > 0 ? key : null
226
+ }
227
+
228
+ // A boolean wrapper: the type guard would narrow the string to `never` in the else branch.
229
+ const looksLikeLink = (s: string): boolean => isCollectionUrl(s)
230
+
231
+ /**
232
+ * How many records one write may evict past the cap. A cap that drops at once
233
+ * (a lapsed subscription, billing briefly reading "free") then trims a big
234
+ * collection a little per write instead of deleting most of it in one go.
235
+ */
236
+ export const COLLECTION_EVICT_MAX_PER_WRITE = 100
237
+
238
+ function canonicalUrl(url: string): string {
239
+ try {
240
+ return new URL(url).href
241
+ } catch {
242
+ return url
243
+ }
244
+ }
245
+
246
+ export function isCollectionMedia(v: unknown): v is CollectionMedia {
247
+ return (
248
+ isRecord(v) &&
249
+ (COLLECTION_MEDIA_TYPES as readonly string[]).includes(v.type as string) &&
250
+ isHttpUrl(v.url) &&
251
+ (v.posterUrl === undefined || v.posterUrl === null || isHttpUrl(v.posterUrl))
252
+ )
253
+ }
254
+
255
+ /** The media list as stored: known kinds with http(s) links, no repeats, at most 20. */
256
+ export function normalizeCollectionMedia(value: unknown): CollectionMedia[] {
257
+ if (!Array.isArray(value)) return []
258
+ const seen = new Set<string>()
259
+ const out: CollectionMedia[] = []
260
+ for (const item of value) {
261
+ if (out.length >= COLLECTION_RECORD_MEDIA_MAX) break
262
+ if (!isCollectionMedia(item) || seen.has(item.url)) continue
263
+ seen.add(item.url)
264
+ out.push({ type: item.type, url: item.url, ...(item.posterUrl ? { posterUrl: item.posterUrl } : {}) })
265
+ }
266
+ return out
267
+ }
268
+
269
+ /** The extra fields as stored: scalar values only, at most 50 keys and 16 KB. */
270
+ export function normalizeCollectionFields(value: unknown): Record<string, CollectionFieldValue> {
271
+ if (!isRecord(value)) return {}
272
+ const out: Record<string, CollectionFieldValue> = {}
273
+ let bytes = 2
274
+ let count = 0
275
+ for (const [key, v] of Object.entries(value)) {
276
+ if (count >= COLLECTION_RECORD_FIELDS_MAX) break
277
+ if (!isScalar(v) || key.length === 0 || key.length > 100) continue
278
+ const entry = JSON.stringify(key) + ":" + JSON.stringify(v) + ","
279
+ if (bytes + entry.length > COLLECTION_RECORD_FIELDS_BYTES_MAX) break
280
+ out[key] = v
281
+ bytes += entry.length
282
+ count += 1
283
+ }
284
+ return out
285
+ }
286
+
287
+ /**
288
+ * A record's one-line name: its title, else the first line of its text, else
289
+ * its link. Tolerates a partial record (a hand-written node result in workflow
290
+ * JSON): a missing field reads as empty rather than throwing on the canvas.
291
+ */
292
+ export function collectionRecordHeadline(record: Partial<Pick<CollectionRecord, "title" | "text" | "url">>): string {
293
+ const title = (typeof record.title === "string" ? record.title : "").trim()
294
+ if (title) return clampChars(title, COLLECTION_HEADLINE_MAX)
295
+ const line = (typeof record.text === "string" ? record.text : "")
296
+ .split(/\r?\n/)
297
+ .map((l) => l.trim())
298
+ .find((l) => l.length > 0)
299
+ if (line) return line.length > COLLECTION_HEADLINE_MAX ? `${clampChars(line, COLLECTION_HEADLINE_MAX - 1)}…` : line
300
+ return typeof record.url === "string" ? record.url : ""
301
+ }
302
+
303
+ /**
304
+ * ONE digest for a collection's records — what the Read Collection node's
305
+ * `text` handle, MCP `read_collection` and the CLI print. `headlines`: one line
306
+ * per record (headline · date · link); `full`: the whole text of each record
307
+ * under its headline, separated by a rule.
308
+ */
309
+ export function collectionRecordsDigest(
310
+ records: ReadonlyArray<Partial<Pick<CollectionRecord, "title" | "text" | "url" | "createdAt">> | null | undefined>,
311
+ format: CollectionDigestFormat = "headlines",
312
+ ): string {
313
+ // Tolerates a partial or null record (a hand-written node result in
314
+ // workflow JSON): the engines rebuild this digest from saved data.
315
+ const rows = records.filter((r): r is Partial<Pick<CollectionRecord, "title" | "text" | "url" | "createdAt">> => typeof r === "object" && r !== null)
316
+ const str = (v: unknown): string => (typeof v === "string" ? v : "")
317
+ if (format === "full") {
318
+ return rows
319
+ .map((r) => {
320
+ const head = collectionRecordHeadline(r)
321
+ const body = str(r.text).trim()
322
+ const lines = [head ? `### ${head}` : "", body && body !== head ? body : "", str(r.url)].filter((l) => l.length > 0)
323
+ return lines.join("\n")
324
+ })
325
+ .filter((block) => block.length > 0)
326
+ .join(COLLECTION_DIGEST_SEPARATOR)
327
+ }
328
+ return rows
329
+ .map((r) => {
330
+ const parts = [collectionRecordHeadline(r)]
331
+ const created = str(r.createdAt)
332
+ if (created) parts.push(created.slice(0, 10))
333
+ const url = str(r.url)
334
+ if (url && url !== parts[0]) parts.push(url)
335
+ return `- ${parts.filter((p) => p.length > 0).join(" · ")}`
336
+ })
337
+ .join("\n")
338
+ }
339
+
340
+ /** What `ingestRecordFromJson` reads out of an item: the record's fields, before explicit overrides. */
341
+ export interface IngestedRecord {
342
+ readonly title: string
343
+ readonly text: string
344
+ readonly url: string | null
345
+ readonly media: CollectionMedia[]
346
+ readonly fields: Record<string, CollectionFieldValue>
347
+ readonly dedupeKey: string | null
348
+ }
349
+
350
+ const TITLE_KEYS = ["title", "headline", "name", "subject"] as const
351
+ const TEXT_KEYS = ["text", "body", "caption", "description", "content", "summary", "dek"] as const
352
+ const URL_KEYS = ["url", "postUrl", "link", "href", "permalink"] as const
353
+ /**
354
+ * Keys a record is told apart by when it has no link. `id` comes last and only
355
+ * as a non-numeric string: an LLM writing `{ "id": 1, … }` per article, or a
356
+ * scraper's ordinal, numbers each RUN's items from 1 — a key that would mark
357
+ * every later run's first item a duplicate of the first run's.
358
+ */
359
+ const DEDUPE_KEYS = ["slug", "postId", "externalId", "id"] as const
360
+ const isDedupeValue = (key: string, v: unknown): boolean =>
361
+ key === "id"
362
+ ? typeof v === "string" && v.trim().length > 0 && !/^\d+$/.test(v.trim())
363
+ : (typeof v === "string" && v.trim().length > 0) || (typeof v === "number" && Number.isFinite(v))
364
+ const IMAGE_KEYS = ["imageUrl", "thumbnailUrl", "image", "thumbnail"] as const
365
+ const VIDEO_KEYS = ["videoUrl", "video"] as const
366
+ const AUDIO_KEYS = ["audioUrl", "audio"] as const
367
+ const MEDIA_SHAPED_KEYS = new Set<string>(["media", ...IMAGE_KEYS, ...VIDEO_KEYS, ...AUDIO_KEYS])
368
+
369
+ function firstString(item: Record<string, unknown>, keys: readonly string[]): string | undefined {
370
+ for (const key of keys) {
371
+ const v = str(item[key])
372
+ if (v !== undefined) return v
373
+ }
374
+ return undefined
375
+ }
376
+
377
+ /** The first link key whose value IS a link (`{ url: "t.me/x", postUrl: "https://t.me/x" }` reads the second). */
378
+ function firstUrl(item: Record<string, unknown>, keys: readonly string[]): string | null {
379
+ for (const key of keys) {
380
+ const v = item[key]
381
+ if (typeof v === "string" && isHttpUrl(v.trim())) return v.trim()
382
+ }
383
+ return null
384
+ }
385
+
386
+ /** Every medium an item carries, in page order, each link once, at most 20 — one pass, whatever the item's size. */
387
+ function mediaFromItem(item: Record<string, unknown>): CollectionMedia[] {
388
+ const seen = new Set<string>()
389
+ const out: CollectionMedia[] = []
390
+ const push = (m: CollectionMedia): boolean => {
391
+ if (out.length >= COLLECTION_RECORD_MEDIA_MAX) return false
392
+ if (!seen.has(m.url)) {
393
+ seen.add(m.url)
394
+ out.push(m)
395
+ }
396
+ return true
397
+ }
398
+ if (Array.isArray(item.media)) {
399
+ for (const entry of item.media) {
400
+ if (out.length >= COLLECTION_RECORD_MEDIA_MAX) break
401
+ if (!isRecord(entry)) continue
402
+ const type = entry.type === "photo" ? "image" : entry.type
403
+ const poster = isHttpUrl(entry.posterUrl) ? entry.posterUrl : undefined
404
+ if (type === "video" && !isHttpUrl(entry.url) && poster) {
405
+ // A video the platform embeds nowhere: its poster is all there is to keep.
406
+ push({ type: "image", url: poster })
407
+ continue
408
+ }
409
+ if (isCollectionMedia({ ...entry, type })) push({ type: type as CollectionMediaType, url: entry.url as string, ...(poster ? { posterUrl: poster } : {}) })
410
+ }
411
+ } else if (isRecord(item.media)) {
412
+ // A Social Search post: `media: { kind, thumbnailUrl, videoUrl }`.
413
+ const m = item.media
414
+ if (isHttpUrl(m.videoUrl)) push({ type: "video", url: m.videoUrl, ...(isHttpUrl(m.thumbnailUrl) ? { posterUrl: m.thumbnailUrl } : {}) })
415
+ else if (isHttpUrl(m.thumbnailUrl)) push({ type: "image", url: m.thumbnailUrl })
416
+ }
417
+ for (const key of IMAGE_KEYS) if (isHttpUrl(item[key]) && !push({ type: "image", url: item[key] as string })) break
418
+ for (const key of VIDEO_KEYS) if (isHttpUrl(item[key]) && !push({ type: "video", url: item[key] as string })) break
419
+ for (const key of AUDIO_KEYS) if (isHttpUrl(item[key]) && !push({ type: "audio", url: item[key] as string })) break
420
+ return out
421
+ }
422
+
423
+ /**
424
+ * A record read out of any JSON item — a Telegram post, a Social Search
425
+ * result, an LLM's object, a plain string. Title ← title / headline / name;
426
+ * text ← text / body / caption / description; link ← the first of url /
427
+ * postUrl / link that IS an http(s) link; media ← `media[]` and the image /
428
+ * video / audio link keys; the dedupe key ← the link, else slug / id / postId;
429
+ * every other scalar lands in `fields` (a nested object's `name`, such as a
430
+ * forwarded-from, lands as that name). One pass over the item: its size is
431
+ * the caller's body limit, never a loop of its own.
432
+ */
433
+ export function ingestRecordFromJson(item: unknown): IngestedRecord {
434
+ if (!isRecord(item)) {
435
+ const text = typeof item === "string" ? item : item === undefined || item === null ? "" : JSON.stringify(item)
436
+ return { title: "", text: clampChars(text, COLLECTION_RECORD_TEXT_MAX), url: null, media: [], fields: {}, dedupeKey: null }
437
+ }
438
+ const title = clampChars((firstString(item, TITLE_KEYS) ?? "").trim(), COLLECTION_RECORD_TITLE_MAX)
439
+ const text = clampChars(firstString(item, TEXT_KEYS) ?? "", COLLECTION_RECORD_TEXT_MAX)
440
+ const url = firstUrl(item, URL_KEYS)
441
+ const media = mediaFromItem(item)
442
+ const taken = new Set<string>([...TITLE_KEYS, ...TEXT_KEYS, ...URL_KEYS, ...MEDIA_SHAPED_KEYS])
443
+ const fields: Record<string, unknown> = {}
444
+ let kept = 0
445
+ for (const [key, v] of Object.entries(item)) {
446
+ if (kept >= COLLECTION_RECORD_FIELDS_MAX) break
447
+ if (taken.has(key)) continue
448
+ if (isScalar(v)) fields[key] = v
449
+ else if (isRecord(v) && typeof v.name === "string" && v.name.trim()) fields[key] = v.name
450
+ else continue
451
+ kept += 1
452
+ }
453
+ const dedupeSource = url ?? DEDUPE_KEYS.filter((k) => isDedupeValue(k, item[k])).map((k) => item[k])[0]
454
+ return {
455
+ title,
456
+ text,
457
+ url,
458
+ media,
459
+ fields: normalizeCollectionFields(fields),
460
+ dedupeKey: normalizeDedupeKey(dedupeSource),
461
+ }
462
+ }
@@ -83,6 +83,8 @@ export interface CompetitorPlatformTally {
83
83
  readonly unit: "views" | "points" | "likes" | null
84
84
  /** What its best posts there share most strongly; null when nothing stands out, or until its next scan. */
85
85
  readonly top: BrandLesson | null
86
+ /** The account's followers at this scan; null when the platform gives none (YouTube, Reddit) or no post of its own was read. Absent from an older server. */
87
+ readonly followers?: number | null
86
88
  }
87
89
 
88
90
  /** A brand's latest scan, platform by platform. */
@@ -162,6 +164,81 @@ export interface CompetitorScan {
162
164
  readonly cards: readonly ActionCard[]
163
165
  }
164
166
 
167
+ /** `GET /v1/competitors`. */
168
+ export interface CompetitorListResult {
169
+ readonly data: readonly TrackedCompetitor[]
170
+ /** How many months of scans your plan keeps (older scans are deleted at a brand's next scan). Absent from an older server. */
171
+ readonly historyMonths?: number
172
+ }
173
+
174
+ /** One platform as one scan found and read it. Numbers a scan stored before they were kept answer null. */
175
+ export interface CompetitorHistoryPlatform {
176
+ readonly platform: SocialPlatform
177
+ readonly own: number | null
178
+ readonly about: number | null
179
+ /** The account's followers at that scan; null when the platform gives none. */
180
+ readonly followers: number | null
181
+ /** The brand's usual reach there as learned at that scan, in `unit`. */
182
+ readonly usual: number | null
183
+ readonly unit: "views" | "points" | "likes" | null
184
+ }
185
+
186
+ export interface CompetitorHistoryPoint {
187
+ readonly id: string
188
+ readonly at: string
189
+ readonly platforms: readonly CompetitorHistoryPlatform[]
190
+ }
191
+
192
+ /** `GET /v1/competitors/:id/history`: the brand's scans, oldest first. */
193
+ export interface CompetitorHistory {
194
+ readonly scans: readonly CompetitorHistoryPoint[]
195
+ }
196
+
197
+ /** The followers a scan read, and when. */
198
+ export interface CompetitorPeriodFollowers {
199
+ readonly value: number
200
+ readonly at: string
201
+ }
202
+
203
+ /** A brand on one platform over a period. */
204
+ export interface CompetitorPeriodPlatform {
205
+ readonly platform: SocialPlatform
206
+ /** The brand's own posts published in the period, and the posts about it. */
207
+ readonly own: number
208
+ readonly about: number
209
+ /** The median reach of its own posts in the period; null below three posts. */
210
+ readonly usual: number | null
211
+ readonly unit: "views" | "points" | "likes" | null
212
+ /** From the newest scan inside the period; null when no scan read them. */
213
+ readonly followers: CompetitorPeriodFollowers | null
214
+ /** Followers gained (or lost) since the newest scan before the period; null when either side is unknown. */
215
+ readonly change: number | null
216
+ /** What worked there in the period (the lessons need eight posts). */
217
+ readonly lessons: readonly BrandLesson[]
218
+ /** Its best posts of the period there, best first, at most four. */
219
+ readonly best: readonly string[]
220
+ }
221
+
222
+ export interface CompetitorPeriod {
223
+ readonly from: string
224
+ readonly to: string
225
+ readonly platforms: readonly CompetitorPeriodPlatform[]
226
+ }
227
+
228
+ /** `GET /v1/competitors/:id/compare`: ISO datetimes; a period is at most a year; `vsFrom` and `vsTo` go together. */
229
+ export interface CompetitorCompareInput {
230
+ readonly from: string
231
+ readonly to: string
232
+ readonly vsFrom?: string
233
+ readonly vsTo?: string
234
+ }
235
+
236
+ /** One or two periods, and the posts they name. */
237
+ export interface CompetitorCompareResult {
238
+ readonly periods: readonly CompetitorPeriod[]
239
+ readonly posts: Readonly<Record<string, CompetitorPost>>
240
+ }
241
+
165
242
  /** `GET /v1/competitors/:id`. */
166
243
  export interface CompetitorDetail extends TrackedCompetitor {
167
244
  readonly latestScan: CompetitorScan | null
@@ -41,3 +41,12 @@ export {
41
41
  LTX_RETAKE_MIN_DURATION_SEC,
42
42
  ltxRetakeDurationSec,
43
43
  } from "./ltx-retake.js"
44
+
45
+ export {
46
+ SPEECH_PRICE_UNIT_CHARS,
47
+ SPEECH_FLOOR_UNITS,
48
+ SPEECH_UNIT_CREDIT_SUFFIX,
49
+ speechUnitCreditId,
50
+ speechPriceUnits,
51
+ speechCredits,
52
+ } from "./speech.js"