@nodaro/shared 3.21.0 → 3.24.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.
- package/dist/index.cjs +2291 -195
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +1929 -75
- package/dist/index.d.ts +1929 -75
- package/dist/index.js +2123 -196
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
- package/src/__tests__/add-captions-plan.test.ts +33 -0
- package/src/__tests__/caption-plan-parse.test.ts +23 -0
- package/src/__tests__/caption-segment-schema.test.ts +30 -0
- package/src/__tests__/collections.test.ts +253 -0
- package/src/__tests__/dialogue-capabilities.test.ts +157 -0
- package/src/__tests__/edit-plan-review.test.ts +70 -0
- package/src/__tests__/edl-clocks.test.ts +97 -0
- package/src/__tests__/edl.test.ts +34 -0
- package/src/__tests__/execution-outcome.test.ts +44 -0
- package/src/__tests__/fan-out-meta.test.ts +23 -0
- package/src/__tests__/fan-out-rows.test.ts +36 -0
- package/src/__tests__/fan-out-url-item.test.ts +44 -0
- package/src/__tests__/fixtures/speaker-tracks.fixtures.json +622 -0
- package/src/__tests__/input-field-extra-keys.test.ts +34 -0
- package/src/__tests__/list-consumers-fan-in.test.ts +40 -0
- package/src/__tests__/model-tree.test.ts +7 -0
- package/src/__tests__/node-pass-through.test.ts +23 -0
- package/src/__tests__/node-runtime-keys.test.ts +1 -0
- package/src/__tests__/picker-restrictions.test.ts +36 -0
- package/src/__tests__/preview-gate.test.ts +305 -0
- package/src/__tests__/render-basis.test.ts +176 -0
- package/src/__tests__/render-nodes.test.ts +73 -0
- package/src/__tests__/render-output.test.ts +392 -0
- package/src/__tests__/run-continuation.test.ts +32 -0
- package/src/__tests__/speaker-tracks.test.ts +474 -0
- package/src/__tests__/speech-pricing.test.ts +69 -0
- package/src/__tests__/telegram-channel.test.ts +91 -0
- package/src/__tests__/tts-capabilities.test.ts +81 -4
- package/src/__tests__/tts-neighbour-text.test.ts +19 -0
- package/src/__tests__/ugc-call-body.test.ts +38 -0
- package/src/__tests__/ugc-run-state.test.ts +68 -0
- package/src/__tests__/video-character-refs.test.ts +213 -0
- package/src/__tests__/video-overlay-layer-plan.test.ts +94 -0
- package/src/add-captions-plan.ts +50 -0
- package/src/caption-plan.ts +45 -0
- package/src/caption-segment-schema.ts +82 -0
- package/src/collections.ts +482 -0
- package/src/competitors.ts +77 -0
- package/src/credit-estimators/index.ts +9 -0
- package/src/credit-estimators/speech.ts +51 -0
- package/src/dialogue-capabilities.ts +48 -0
- package/src/edit-plan-contract.ts +20 -9
- package/src/edit-plan-review.ts +40 -1
- package/src/edl.ts +27 -1
- package/src/execution-outcome.ts +41 -0
- package/src/fan-out-meta.ts +23 -0
- package/src/fan-out-rows.ts +74 -5
- package/src/gemini-omni-voices.ts +59 -0
- package/src/handle-aliases.ts +298 -0
- package/src/i18n/camera-motions.pt-BR.ts +14 -14
- package/src/i18n/transitions.pt-BR.ts +13 -13
- package/src/index.ts +180 -1
- package/src/model-catalog.ts +122 -13
- package/src/model-constants.ts +24 -4
- package/src/model-tree.ts +5 -1
- package/src/node-execution-state.ts +13 -0
- package/src/node-mappable-fields.ts +7 -1
- package/src/node-pass-through.ts +37 -0
- package/src/node-runtime-keys.ts +14 -0
- package/src/picker-restrictions.ts +49 -0
- package/src/presentation-types.ts +26 -2
- package/src/presentation-utils.ts +25 -7
- package/src/preview-gate.ts +279 -0
- package/src/producer-types.ts +58 -0
- package/src/render-final.ts +20 -0
- package/src/render-nodes.ts +92 -0
- package/src/render-output.ts +565 -0
- package/src/run-continuation.ts +39 -0
- package/src/speaker-tracks.ts +638 -0
- package/src/telegram-channel.ts +140 -0
- package/src/transcribe-preflight.ts +8 -4
- package/src/tts-capabilities.ts +19 -5
- package/src/tts-neighbour-text.ts +46 -0
- package/src/ugc-call-body.ts +86 -0
- package/src/ugc-run-state.ts +64 -0
- package/src/video-character-refs.ts +233 -0
- package/src/video-overlay.ts +78 -21
|
@@ -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,482 @@
|
|
|
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
|
+
* A Save to Collection field held to the record route's limit — the ONE rule
|
|
215
|
+
* both engines apply to a field whose `{Node}` references resolved to more
|
|
216
|
+
* than was typed: a title, text or duplicate key is cut to whole characters
|
|
217
|
+
* (as the store cuts an item's), and a link over the limit is not sent at all
|
|
218
|
+
* (a cut link is a wrong link; the item's own link then wins).
|
|
219
|
+
*/
|
|
220
|
+
export function fitCollectionField(key: "title" | "text" | "link" | "dedupeKey", value: string): string | undefined {
|
|
221
|
+
switch (key) {
|
|
222
|
+
case "title":
|
|
223
|
+
return clampChars(value, COLLECTION_RECORD_TITLE_MAX)
|
|
224
|
+
case "text":
|
|
225
|
+
return clampChars(value, COLLECTION_RECORD_TEXT_MAX)
|
|
226
|
+
case "dedupeKey":
|
|
227
|
+
return clampChars(value, COLLECTION_DEDUPE_KEY_MAX)
|
|
228
|
+
case "link":
|
|
229
|
+
return value.length <= COLLECTION_RECORD_URL_MAX ? value : undefined
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
/**
|
|
234
|
+
* The key a collection deduplicates on: trimmed, inner whitespace collapsed,
|
|
235
|
+
* lower-cased, at most 300 characters; null when there is nothing to key on.
|
|
236
|
+
*/
|
|
237
|
+
export function normalizeDedupeKey(raw: unknown): string | null {
|
|
238
|
+
if (typeof raw === "number" && Number.isFinite(raw)) raw = String(raw)
|
|
239
|
+
if (typeof raw !== "string") return null
|
|
240
|
+
const compact = raw.trim().replace(/\s+/g, " ")
|
|
241
|
+
// A link keeps its path's case: a short link or a video id is case-sensitive
|
|
242
|
+
// (bit.ly/AbC and bit.ly/abc are two pages). Only its scheme and host are
|
|
243
|
+
// case-insensitive, and the URL parser folds exactly those.
|
|
244
|
+
const key = clampChars(looksLikeLink(compact) ? canonicalUrl(compact) : compact.toLowerCase(), COLLECTION_DEDUPE_KEY_MAX).trim()
|
|
245
|
+
return key.length > 0 ? key : null
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
// A boolean wrapper: the type guard would narrow the string to `never` in the else branch.
|
|
249
|
+
const looksLikeLink = (s: string): boolean => isCollectionUrl(s)
|
|
250
|
+
|
|
251
|
+
/**
|
|
252
|
+
* How many records one write may evict past the cap. A cap that drops at once
|
|
253
|
+
* (a lapsed subscription, billing briefly reading "free") then trims a big
|
|
254
|
+
* collection a little per write instead of deleting most of it in one go.
|
|
255
|
+
*/
|
|
256
|
+
export const COLLECTION_EVICT_MAX_PER_WRITE = 100
|
|
257
|
+
|
|
258
|
+
function canonicalUrl(url: string): string {
|
|
259
|
+
try {
|
|
260
|
+
return new URL(url).href
|
|
261
|
+
} catch {
|
|
262
|
+
return url
|
|
263
|
+
}
|
|
264
|
+
}
|
|
265
|
+
|
|
266
|
+
export function isCollectionMedia(v: unknown): v is CollectionMedia {
|
|
267
|
+
return (
|
|
268
|
+
isRecord(v) &&
|
|
269
|
+
(COLLECTION_MEDIA_TYPES as readonly string[]).includes(v.type as string) &&
|
|
270
|
+
isHttpUrl(v.url) &&
|
|
271
|
+
(v.posterUrl === undefined || v.posterUrl === null || isHttpUrl(v.posterUrl))
|
|
272
|
+
)
|
|
273
|
+
}
|
|
274
|
+
|
|
275
|
+
/** The media list as stored: known kinds with http(s) links, no repeats, at most 20. */
|
|
276
|
+
export function normalizeCollectionMedia(value: unknown): CollectionMedia[] {
|
|
277
|
+
if (!Array.isArray(value)) return []
|
|
278
|
+
const seen = new Set<string>()
|
|
279
|
+
const out: CollectionMedia[] = []
|
|
280
|
+
for (const item of value) {
|
|
281
|
+
if (out.length >= COLLECTION_RECORD_MEDIA_MAX) break
|
|
282
|
+
if (!isCollectionMedia(item) || seen.has(item.url)) continue
|
|
283
|
+
seen.add(item.url)
|
|
284
|
+
out.push({ type: item.type, url: item.url, ...(item.posterUrl ? { posterUrl: item.posterUrl } : {}) })
|
|
285
|
+
}
|
|
286
|
+
return out
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
/** The extra fields as stored: scalar values only, at most 50 keys and 16 KB. */
|
|
290
|
+
export function normalizeCollectionFields(value: unknown): Record<string, CollectionFieldValue> {
|
|
291
|
+
if (!isRecord(value)) return {}
|
|
292
|
+
const out: Record<string, CollectionFieldValue> = {}
|
|
293
|
+
let bytes = 2
|
|
294
|
+
let count = 0
|
|
295
|
+
for (const [key, v] of Object.entries(value)) {
|
|
296
|
+
if (count >= COLLECTION_RECORD_FIELDS_MAX) break
|
|
297
|
+
if (!isScalar(v) || key.length === 0 || key.length > 100) continue
|
|
298
|
+
const entry = JSON.stringify(key) + ":" + JSON.stringify(v) + ","
|
|
299
|
+
if (bytes + entry.length > COLLECTION_RECORD_FIELDS_BYTES_MAX) break
|
|
300
|
+
out[key] = v
|
|
301
|
+
bytes += entry.length
|
|
302
|
+
count += 1
|
|
303
|
+
}
|
|
304
|
+
return out
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
/**
|
|
308
|
+
* A record's one-line name: its title, else the first line of its text, else
|
|
309
|
+
* its link. Tolerates a partial record (a hand-written node result in workflow
|
|
310
|
+
* JSON): a missing field reads as empty rather than throwing on the canvas.
|
|
311
|
+
*/
|
|
312
|
+
export function collectionRecordHeadline(record: Partial<Pick<CollectionRecord, "title" | "text" | "url">>): string {
|
|
313
|
+
const title = (typeof record.title === "string" ? record.title : "").trim()
|
|
314
|
+
if (title) return clampChars(title, COLLECTION_HEADLINE_MAX)
|
|
315
|
+
const line = (typeof record.text === "string" ? record.text : "")
|
|
316
|
+
.split(/\r?\n/)
|
|
317
|
+
.map((l) => l.trim())
|
|
318
|
+
.find((l) => l.length > 0)
|
|
319
|
+
if (line) return line.length > COLLECTION_HEADLINE_MAX ? `${clampChars(line, COLLECTION_HEADLINE_MAX - 1)}…` : line
|
|
320
|
+
return typeof record.url === "string" ? record.url : ""
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
/**
|
|
324
|
+
* ONE digest for a collection's records — what the Read Collection node's
|
|
325
|
+
* `text` handle, MCP `read_collection` and the CLI print. `headlines`: one line
|
|
326
|
+
* per record (headline · date · link); `full`: the whole text of each record
|
|
327
|
+
* under its headline, separated by a rule.
|
|
328
|
+
*/
|
|
329
|
+
export function collectionRecordsDigest(
|
|
330
|
+
records: ReadonlyArray<Partial<Pick<CollectionRecord, "title" | "text" | "url" | "createdAt">> | null | undefined>,
|
|
331
|
+
format: CollectionDigestFormat = "headlines",
|
|
332
|
+
): string {
|
|
333
|
+
// Tolerates a partial or null record (a hand-written node result in
|
|
334
|
+
// workflow JSON): the engines rebuild this digest from saved data.
|
|
335
|
+
const rows = records.filter((r): r is Partial<Pick<CollectionRecord, "title" | "text" | "url" | "createdAt">> => typeof r === "object" && r !== null)
|
|
336
|
+
const str = (v: unknown): string => (typeof v === "string" ? v : "")
|
|
337
|
+
if (format === "full") {
|
|
338
|
+
return rows
|
|
339
|
+
.map((r) => {
|
|
340
|
+
const head = collectionRecordHeadline(r)
|
|
341
|
+
const body = str(r.text).trim()
|
|
342
|
+
const lines = [head ? `### ${head}` : "", body && body !== head ? body : "", str(r.url)].filter((l) => l.length > 0)
|
|
343
|
+
return lines.join("\n")
|
|
344
|
+
})
|
|
345
|
+
.filter((block) => block.length > 0)
|
|
346
|
+
.join(COLLECTION_DIGEST_SEPARATOR)
|
|
347
|
+
}
|
|
348
|
+
return rows
|
|
349
|
+
.map((r) => {
|
|
350
|
+
const parts = [collectionRecordHeadline(r)]
|
|
351
|
+
const created = str(r.createdAt)
|
|
352
|
+
if (created) parts.push(created.slice(0, 10))
|
|
353
|
+
const url = str(r.url)
|
|
354
|
+
if (url && url !== parts[0]) parts.push(url)
|
|
355
|
+
return `- ${parts.filter((p) => p.length > 0).join(" · ")}`
|
|
356
|
+
})
|
|
357
|
+
.join("\n")
|
|
358
|
+
}
|
|
359
|
+
|
|
360
|
+
/** What `ingestRecordFromJson` reads out of an item: the record's fields, before explicit overrides. */
|
|
361
|
+
export interface IngestedRecord {
|
|
362
|
+
readonly title: string
|
|
363
|
+
readonly text: string
|
|
364
|
+
readonly url: string | null
|
|
365
|
+
readonly media: CollectionMedia[]
|
|
366
|
+
readonly fields: Record<string, CollectionFieldValue>
|
|
367
|
+
readonly dedupeKey: string | null
|
|
368
|
+
}
|
|
369
|
+
|
|
370
|
+
const TITLE_KEYS = ["title", "headline", "name", "subject"] as const
|
|
371
|
+
const TEXT_KEYS = ["text", "body", "caption", "description", "content", "summary", "dek"] as const
|
|
372
|
+
const URL_KEYS = ["url", "postUrl", "link", "href", "permalink"] as const
|
|
373
|
+
/**
|
|
374
|
+
* Keys a record is told apart by when it has no link. `id` comes last and only
|
|
375
|
+
* as a non-numeric string: an LLM writing `{ "id": 1, … }` per article, or a
|
|
376
|
+
* scraper's ordinal, numbers each RUN's items from 1 — a key that would mark
|
|
377
|
+
* every later run's first item a duplicate of the first run's.
|
|
378
|
+
*/
|
|
379
|
+
const DEDUPE_KEYS = ["slug", "postId", "externalId", "id"] as const
|
|
380
|
+
const isDedupeValue = (key: string, v: unknown): boolean =>
|
|
381
|
+
key === "id"
|
|
382
|
+
? typeof v === "string" && v.trim().length > 0 && !/^\d+$/.test(v.trim())
|
|
383
|
+
: (typeof v === "string" && v.trim().length > 0) || (typeof v === "number" && Number.isFinite(v))
|
|
384
|
+
const IMAGE_KEYS = ["imageUrl", "thumbnailUrl", "image", "thumbnail"] as const
|
|
385
|
+
const VIDEO_KEYS = ["videoUrl", "video"] as const
|
|
386
|
+
const AUDIO_KEYS = ["audioUrl", "audio"] as const
|
|
387
|
+
const MEDIA_SHAPED_KEYS = new Set<string>(["media", ...IMAGE_KEYS, ...VIDEO_KEYS, ...AUDIO_KEYS])
|
|
388
|
+
|
|
389
|
+
function firstString(item: Record<string, unknown>, keys: readonly string[]): string | undefined {
|
|
390
|
+
for (const key of keys) {
|
|
391
|
+
const v = str(item[key])
|
|
392
|
+
if (v !== undefined) return v
|
|
393
|
+
}
|
|
394
|
+
return undefined
|
|
395
|
+
}
|
|
396
|
+
|
|
397
|
+
/** The first link key whose value IS a link (`{ url: "t.me/x", postUrl: "https://t.me/x" }` reads the second). */
|
|
398
|
+
function firstUrl(item: Record<string, unknown>, keys: readonly string[]): string | null {
|
|
399
|
+
for (const key of keys) {
|
|
400
|
+
const v = item[key]
|
|
401
|
+
if (typeof v === "string" && isHttpUrl(v.trim())) return v.trim()
|
|
402
|
+
}
|
|
403
|
+
return null
|
|
404
|
+
}
|
|
405
|
+
|
|
406
|
+
/** Every medium an item carries, in page order, each link once, at most 20 — one pass, whatever the item's size. */
|
|
407
|
+
function mediaFromItem(item: Record<string, unknown>): CollectionMedia[] {
|
|
408
|
+
const seen = new Set<string>()
|
|
409
|
+
const out: CollectionMedia[] = []
|
|
410
|
+
const push = (m: CollectionMedia): boolean => {
|
|
411
|
+
if (out.length >= COLLECTION_RECORD_MEDIA_MAX) return false
|
|
412
|
+
if (!seen.has(m.url)) {
|
|
413
|
+
seen.add(m.url)
|
|
414
|
+
out.push(m)
|
|
415
|
+
}
|
|
416
|
+
return true
|
|
417
|
+
}
|
|
418
|
+
if (Array.isArray(item.media)) {
|
|
419
|
+
for (const entry of item.media) {
|
|
420
|
+
if (out.length >= COLLECTION_RECORD_MEDIA_MAX) break
|
|
421
|
+
if (!isRecord(entry)) continue
|
|
422
|
+
const type = entry.type === "photo" ? "image" : entry.type
|
|
423
|
+
const poster = isHttpUrl(entry.posterUrl) ? entry.posterUrl : undefined
|
|
424
|
+
if (type === "video" && !isHttpUrl(entry.url) && poster) {
|
|
425
|
+
// A video the platform embeds nowhere: its poster is all there is to keep.
|
|
426
|
+
push({ type: "image", url: poster })
|
|
427
|
+
continue
|
|
428
|
+
}
|
|
429
|
+
if (isCollectionMedia({ ...entry, type })) push({ type: type as CollectionMediaType, url: entry.url as string, ...(poster ? { posterUrl: poster } : {}) })
|
|
430
|
+
}
|
|
431
|
+
} else if (isRecord(item.media)) {
|
|
432
|
+
// A Social Search post: `media: { kind, thumbnailUrl, videoUrl }`.
|
|
433
|
+
const m = item.media
|
|
434
|
+
if (isHttpUrl(m.videoUrl)) push({ type: "video", url: m.videoUrl, ...(isHttpUrl(m.thumbnailUrl) ? { posterUrl: m.thumbnailUrl } : {}) })
|
|
435
|
+
else if (isHttpUrl(m.thumbnailUrl)) push({ type: "image", url: m.thumbnailUrl })
|
|
436
|
+
}
|
|
437
|
+
for (const key of IMAGE_KEYS) if (isHttpUrl(item[key]) && !push({ type: "image", url: item[key] as string })) break
|
|
438
|
+
for (const key of VIDEO_KEYS) if (isHttpUrl(item[key]) && !push({ type: "video", url: item[key] as string })) break
|
|
439
|
+
for (const key of AUDIO_KEYS) if (isHttpUrl(item[key]) && !push({ type: "audio", url: item[key] as string })) break
|
|
440
|
+
return out
|
|
441
|
+
}
|
|
442
|
+
|
|
443
|
+
/**
|
|
444
|
+
* A record read out of any JSON item — a Telegram post, a Social Search
|
|
445
|
+
* result, an LLM's object, a plain string. Title ← title / headline / name;
|
|
446
|
+
* text ← text / body / caption / description; link ← the first of url /
|
|
447
|
+
* postUrl / link that IS an http(s) link; media ← `media[]` and the image /
|
|
448
|
+
* video / audio link keys; the dedupe key ← the link, else slug / id / postId;
|
|
449
|
+
* every other scalar lands in `fields` (a nested object's `name`, such as a
|
|
450
|
+
* forwarded-from, lands as that name). One pass over the item: its size is
|
|
451
|
+
* the caller's body limit, never a loop of its own.
|
|
452
|
+
*/
|
|
453
|
+
export function ingestRecordFromJson(item: unknown): IngestedRecord {
|
|
454
|
+
if (!isRecord(item)) {
|
|
455
|
+
const text = typeof item === "string" ? item : item === undefined || item === null ? "" : JSON.stringify(item)
|
|
456
|
+
return { title: "", text: clampChars(text, COLLECTION_RECORD_TEXT_MAX), url: null, media: [], fields: {}, dedupeKey: null }
|
|
457
|
+
}
|
|
458
|
+
const title = clampChars((firstString(item, TITLE_KEYS) ?? "").trim(), COLLECTION_RECORD_TITLE_MAX)
|
|
459
|
+
const text = clampChars(firstString(item, TEXT_KEYS) ?? "", COLLECTION_RECORD_TEXT_MAX)
|
|
460
|
+
const url = firstUrl(item, URL_KEYS)
|
|
461
|
+
const media = mediaFromItem(item)
|
|
462
|
+
const taken = new Set<string>([...TITLE_KEYS, ...TEXT_KEYS, ...URL_KEYS, ...MEDIA_SHAPED_KEYS])
|
|
463
|
+
const fields: Record<string, unknown> = {}
|
|
464
|
+
let kept = 0
|
|
465
|
+
for (const [key, v] of Object.entries(item)) {
|
|
466
|
+
if (kept >= COLLECTION_RECORD_FIELDS_MAX) break
|
|
467
|
+
if (taken.has(key)) continue
|
|
468
|
+
if (isScalar(v)) fields[key] = v
|
|
469
|
+
else if (isRecord(v) && typeof v.name === "string" && v.name.trim()) fields[key] = v.name
|
|
470
|
+
else continue
|
|
471
|
+
kept += 1
|
|
472
|
+
}
|
|
473
|
+
const dedupeSource = url ?? DEDUPE_KEYS.filter((k) => isDedupeValue(k, item[k])).map((k) => item[k])[0]
|
|
474
|
+
return {
|
|
475
|
+
title,
|
|
476
|
+
text,
|
|
477
|
+
url,
|
|
478
|
+
media,
|
|
479
|
+
fields: normalizeCollectionFields(fields),
|
|
480
|
+
dedupeKey: normalizeDedupeKey(dedupeSource),
|
|
481
|
+
}
|
|
482
|
+
}
|
package/src/competitors.ts
CHANGED
|
@@ -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"
|