@vfrey/vfrey 0.0.1 → 1.0.0-beta.0

package/vendor/@vfrey/contracts/dist/domain/errors.js

@@ -0,0 +1,68 @@
+/**
+ * Quality failures and compliance failures are different stops.
+ *
+ * Quality: the video would be thin, generic, or too similar to the last one.
+ * These gates exist so a channel does not ship interchangeable templated videos.
+ * YouTube's inauthentic-content monetization policy is why the gates are strict.
+ * A quality rejection is not an API policy verdict, and passing is not a
+ * promise that YouTube will monetize the channel.
+ *
+ * Compliance: the platform requires a disclosure flag, an audit posture,
+ * a privacy choice the creator options allow, or the draft copies a source
+ * or presents an AI persona as a professional adviser. These do not retry.
+ */
+export class AppError extends Error {
+    code;
+    retryable;
+    risk;
+    constructor(message, code, retryable, risk) {
+        super(message);
+        this.name = new.target.name;
+        this.code = code;
+        this.retryable = retryable;
+        this.risk = risk;
+    }
+}
+export class QualityError extends AppError {
+    constructor(code, message) {
+        super(message, code, false, "quality");
+    }
+}
+export class ComplianceError extends AppError {
+    constructor(code, message) {
+        super(message, code, false, "compliance");
+    }
+}
+export class RetryableError extends AppError {
+    retryAfterMs;
+    constructor(code, message, retryAfterMs) {
+        super(message, code, true, "transport");
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+export class ConfigError extends AppError {
+    constructor(code, message) {
+        super(message, code, false, "config");
+    }
+}
+export function asAppError(error) {
+    if (error instanceof AppError)
+        return error;
+    const message = error instanceof Error ? error.message : String(error);
+    if (isConfigFault(error))
+        return new ConfigError("invalid_config", message);
+    return new RetryableError("unexpected", message);
+}
+/**
+ * A RangeError (bad timezone, out-of-range value) or TypeError (malformed
+ * config) will fail the same way on every retry. A fetch network failure is
+ * also a TypeError in Node ("fetch failed", with a cause) and stays retryable.
+ */
+function isConfigFault(error) {
+    if (error instanceof RangeError)
+        return true;
+    if (error instanceof TypeError) {
+        return error.message !== "fetch failed" && error.cause === undefined;
+    }
+    return false;
+}

package/vendor/@vfrey/contracts/dist/domain/redact.d.ts

@@ -0,0 +1 @@
+export declare function redact(value: string): string;

package/vendor/@vfrey/contracts/dist/domain/redact.js

@@ -0,0 +1,21 @@
+const BEARER = /Bearer\s+[A-Za-z0-9._~+/-]+=*/gi;
+const ACT = /\bact\.[A-Za-z0-9._~+/-]+/g;
+const YA29 = /\bya29\.[A-Za-z0-9._~+/-]+/g;
+const AUTH_SCHEME = /(\bauthorization["']?\s*[:=]\s*["']?)(?:basic|bearer|token|digest)\s+[^"',\s}]+/gi;
+const ASSIGNED = /((?:access[_-]?token|refresh[_-]?token|id[_-]?token|client[_-]?secret|api[_-]?key|credentials[_-]?key|authorization)["']?\s*[:=]\s*["']?)[^"',\s}]+/gi;
+const GOOGLE_KEY = /\bAIza[0-9A-Za-z_-]{20,}/g;
+const KEY_PARAM = /([?&]key=)[^&\s"']+/gi;
+const GOOGLE_REFRESH = /(?<![\w/])1\/\/[A-Za-z0-9._~-]{20,}/g;
+const SECRET_KEY = /\bsk-[A-Za-z0-9_-]{16,}/g;
+export function redact(value) {
+    return value
+        .replace(AUTH_SCHEME, "$1[redacted]")
+        .replace(BEARER, "Bearer [redacted]")
+        .replace(ACT, "act.[redacted]")
+        .replace(YA29, "ya29.[redacted]")
+        .replace(GOOGLE_KEY, "AIza[redacted]")
+        .replace(KEY_PARAM, "$1[redacted]")
+        .replace(GOOGLE_REFRESH, "1//[redacted]")
+        .replace(SECRET_KEY, "sk-[redacted]")
+        .replace(ASSIGNED, "$1[redacted]");
+}

package/vendor/@vfrey/contracts/dist/domain/revenue.d.ts

@@ -0,0 +1,13 @@
+export type RevenueStatus = "present" | "unavailable" | "forbidden";
+export interface RevenueReading {
+    estimatedRevenue: number | null;
+    revenueStatus: RevenueStatus;
+}
+/**
+ * A missing or forbidden revenue field stays null.
+ * Zero is recorded only when a 2xx response explicitly returns zero.
+ */
+export declare function interpretRevenue(input: {
+    value: number | null | undefined;
+    httpStatus: number;
+}): RevenueReading;

package/vendor/@vfrey/contracts/dist/domain/revenue.js

@@ -0,0 +1,16 @@
+/**
+ * A missing or forbidden revenue field stays null.
+ * Zero is recorded only when a 2xx response explicitly returns zero.
+ */
+export function interpretRevenue(input) {
+    if (input.httpStatus === 401 || input.httpStatus === 403) {
+        return { estimatedRevenue: null, revenueStatus: "forbidden" };
+    }
+    if (input.httpStatus < 200 || input.httpStatus > 299) {
+        return { estimatedRevenue: null, revenueStatus: "unavailable" };
+    }
+    if (typeof input.value !== "number" || !Number.isFinite(input.value)) {
+        return { estimatedRevenue: null, revenueStatus: "unavailable" };
+    }
+    return { estimatedRevenue: input.value, revenueStatus: "present" };
+}

package/vendor/@vfrey/contracts/dist/domain/safety.d.ts

@@ -0,0 +1,20 @@
+/** A link a reader could follow: scheme, www host, shortener, or a bare domain. */
+export declare function containsLink(text: string): boolean;
+export type ReplyTone = "genuine" | "oneliner" | "spicy";
+export interface ReplyDraft {
+    tone: ReplyTone;
+    text: string;
+}
+export declare function reviewReply(draft: ReplyDraft): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface CommentClass {
+    kind: "question" | "praise" | "criticism" | "spam" | "harmful" | "other";
+    reply: boolean;
+    tone: ReplyTone;
+}
+/** Deterministic routing before the model writes. Harmful and spam get no reply. */
+export declare function classifyComment(text: string, allowSpicy: boolean): CommentClass;

package/vendor/@vfrey/contracts/dist/domain/safety.js

@@ -0,0 +1,61 @@
+import { ADVICE_PERSONA } from "./advice-persona.js";
+/**
+ * Engagement safety is a compliance gate, not a style preference.
+ * "Spicy" is allowed to be sharp. It is not allowed to be abusive,
+ * deceptive, or to role-play a licensed adviser.
+ */
+const ABUSE = [
+    /\b(kill yourself|kys)\b/i,
+    /\b(nigger|faggot|retard)\b/i,
+    /\b(rape|rapist)\b/i,
+    /\b(bomb|shoot)\s+(the|a|their)\b/i,
+];
+/** Everything a reply may not say. Harmful-comment routing uses the abuse part of the same list. */
+const BLOCKED = [...ABUSE, ADVICE_PERSONA];
+const SHORTENERS = /\b(?:bit\.ly|t\.co|tinyurl\.com|goo\.gl|ow\.ly|is\.gd|buff\.ly|youtu\.be|lnkd\.in|rb\.gy|cutt\.ly|t\.me|wa\.me)\b/i;
+const BARE_DOMAIN = /\b[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*\.(?:com|net|org|io|co|me|ly|gl|gd|be|app|dev|ai|tv|xyz|info|biz|us|uk|de|fr|vn|ru|cn|link|site|online|shop|store|page|club|top|cc|ws)\b/i;
+/** A link a reader could follow: scheme, www host, shortener, or a bare domain. */
+export function containsLink(text) {
+    return (/(?:https?|ftp):\/\//i.test(text) ||
+        /\bwww\./i.test(text) ||
+        SHORTENERS.test(text) ||
+        BARE_DOMAIN.test(text) ||
+        /\b[a-z0-9-]+\.[a-z]{2,}\/\S/i.test(text));
+}
+export function reviewReply(draft) {
+    const text = draft.text.trim();
+    if (text.length < 2 || text.length > 500) {
+        return { ok: false, reason: "length" };
+    }
+    if (containsLink(text)) {
+        return { ok: false, reason: "links_blocked" };
+    }
+    for (const pattern of BLOCKED) {
+        if (pattern.test(text))
+            return { ok: false, reason: "blocked_language" };
+    }
+    if (draft.tone === "spicy" && /\b(idiot|moron|stupid|dumbass|shut up)\b/i.test(text)) {
+        return { ok: false, reason: "spicy_is_not_insult" };
+    }
+    return { ok: true };
+}
+/** Deterministic routing before the model writes. Harmful and spam get no reply. */
+export function classifyComment(text, allowSpicy) {
+    const value = text.toLowerCase();
+    if (ABUSE.some((pattern) => pattern.test(value))) {
+        return { kind: "harmful", reply: false, tone: "genuine" };
+    }
+    if (containsLink(value) || /(telegram|whatsapp|crypto giveaway|dm me)/i.test(value)) {
+        return { kind: "spam", reply: false, tone: "genuine" };
+    }
+    if (value.includes("?")) {
+        return { kind: "question", reply: true, tone: "genuine" };
+    }
+    if (/(love|great|helpful|thanks|thank you|fire)/i.test(value)) {
+        return { kind: "praise", reply: true, tone: "oneliner" };
+    }
+    if (/(wrong|bad take|disagree|actually|nope|mid|boring)/i.test(value)) {
+        return { kind: "criticism", reply: true, tone: allowSpicy ? "spicy" : "genuine" };
+    }
+    return { kind: "other", reply: false, tone: "genuine" };
+}

package/vendor/@vfrey/contracts/dist/domain/similarity.d.ts

@@ -0,0 +1,13 @@
+export declare function tokens(value: string): string[];
+/**
+ * Tokenizer for the verbatim-copy check. Unicode-aware, no length filter, so a
+ * copied run of short words, accented text, or unspaced CJK text is counted
+ * word for word. Each Han, Kana, or Hangul character is its own token.
+ */
+export declare function copyTokens(value: string): string[];
+export declare function significantTokens(value: string): string[];
+export declare function jaccard(a: string, b: string): number;
+/** Longest run of identical word tokens. Used to block verbatim source reuse. */
+export declare function longestSharedWordRun(a: string, b: string): number;
+export declare function sharedFourGram(a: string, b: string): boolean;
+export declare function sameSet(a: string[], b: string[]): boolean;

package/vendor/@vfrey/contracts/dist/domain/similarity.js

@@ -0,0 +1,100 @@
+const STOP = new Set([
+    "about", "after", "again", "being", "could", "every", "from", "have", "into",
+    "just", "like", "more", "most", "only", "other", "over", "some", "than",
+    "that", "their", "there", "these", "this", "those", "what", "when", "where",
+    "which", "while", "with", "would", "your", "because", "should", "video",
+]);
+export function tokens(value) {
+    return value
+        .toLowerCase()
+        .replace(/[#@]/g, " ")
+        .split(/[^a-z0-9]+/)
+        .filter((word) => word.length > 2);
+}
+const CJK = "\\p{scx=Han}\\p{scx=Hiragana}\\p{scx=Katakana}\\p{scx=Hangul}";
+const COPY_TOKEN = new RegExp(`[${CJK}]|(?:(?![${CJK}])[\\p{L}\\p{N}])+`, "gu");
+/**
+ * Tokenizer for the verbatim-copy check. Unicode-aware, no length filter, so a
+ * copied run of short words, accented text, or unspaced CJK text is counted
+ * word for word. Each Han, Kana, or Hangul character is its own token.
+ */
+export function copyTokens(value) {
+    return value.normalize("NFC").toLocaleLowerCase().match(COPY_TOKEN) ?? [];
+}
+export function significantTokens(value) {
+    return tokens(value).filter((word) => word.length > 4 && !STOP.has(word));
+}
+export function jaccard(a, b) {
+    const left = new Set(tokens(a));
+    const right = new Set(tokens(b));
+    if (left.size === 0 && right.size === 0)
+        return 1;
+    if (left.size === 0 || right.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const word of left) {
+        if (right.has(word))
+            intersection += 1;
+    }
+    const union = left.size + right.size - intersection;
+    return union === 0 ? 0 : intersection / union;
+}
+/** Longest run of identical word tokens. Used to block verbatim source reuse. */
+export function longestSharedWordRun(a, b) {
+    const left = copyTokens(a);
+    const right = copyTokens(b);
+    if (left.length === 0 || right.length === 0)
+        return 0;
+    const positions = new Map();
+    right.forEach((word, index) => {
+        const list = positions.get(word) ?? [];
+        list.push(index);
+        positions.set(word, list);
+    });
+    let best = 0;
+    for (let i = 0; i < left.length; i += 1) {
+        const starts = positions.get(left[i] ?? "");
+        if (!starts)
+            continue;
+        for (const j of starts) {
+            let length = 0;
+            while (i + length < left.length &&
+                j + length < right.length &&
+                left[i + length] === right[j + length]) {
+                length += 1;
+            }
+            if (length > best)
+                best = length;
+        }
+    }
+    return best;
+}
+export function sharedFourGram(a, b) {
+    const grams = (value) => {
+        const words = tokens(value);
+        const set = new Set();
+        for (let i = 0; i <= words.length - 4; i += 1) {
+            set.add(words.slice(i, i + 4).join(" "));
+        }
+        return set;
+    };
+    const left = grams(a);
+    for (const gram of grams(b)) {
+        if (left.has(gram))
+            return true;
+    }
+    return false;
+}
+export function sameSet(a, b) {
+    if (a.length === 0 || b.length === 0)
+        return false;
+    const left = new Set(a.map((item) => item.toLowerCase()));
+    const right = new Set(b.map((item) => item.toLowerCase()));
+    if (left.size !== right.size)
+        return false;
+    for (const item of left) {
+        if (!right.has(item))
+            return false;
+    }
+    return true;
+}

package/vendor/@vfrey/contracts/dist/domain/templates.d.ts

@@ -0,0 +1,18 @@
+import type { CaptionStyle, DurationBucket, Pacing, Palette, TemplateId } from "./types.js";
+export interface TemplateSpec {
+    id: TemplateId;
+    pacing: Pacing;
+    captionStyle: CaptionStyle;
+    durationTargetSec: number;
+    durationMinSec: number;
+    durationMaxSec: number;
+    bucket: DurationBucket;
+    coverTimestampMs: number;
+    palettes: Palette[];
+    /** What a reviewer should see that the other templates do not. */
+    visualLanguage: string;
+    structureNote: string;
+}
+export declare const TEMPLATES: Record<TemplateId, TemplateSpec>;
+export declare const TEMPLATE_IDS: TemplateId[];
+export declare function durationBucket(seconds: number): DurationBucket;

package/vendor/@vfrey/contracts/dist/domain/templates.js

@@ -0,0 +1,67 @@
+function palette(id, background, foreground, accent, muted, surface) {
+    return { id, background, foreground, accent, muted, surface };
+}
+export const TEMPLATES = {
+    KineticType: {
+        id: "KineticType",
+        pacing: "fast",
+        captionStyle: "slam",
+        durationTargetSec: 20,
+        durationMinSec: 16,
+        durationMaxSec: 24,
+        bucket: "short",
+        coverTimestampMs: 800,
+        visualLanguage: "Full-bleed type, hard cuts, one idea per frame, accent bar.",
+        structureNote: "Hook occupies the first frame. Later beats are short claims.",
+        palettes: [
+            palette("ink", "#0b0b0c", "#f5f5f0", "#ff3b00", "#8a8a84", "#161616"),
+            palette("cobalt", "#07111f", "#e7f0ff", "#3d8bfd", "#7f93ad", "#102033"),
+            palette("acid", "#10140a", "#f3f7e8", "#c6f135", "#8b9478", "#1a2212"),
+            palette("orchid", "#140910", "#ffe9f4", "#ff4fa3", "#b18498", "#241018"),
+        ],
+    },
+    EditorialSplit: {
+        id: "EditorialSplit",
+        pacing: "slow",
+        captionStyle: "lower-third",
+        durationTargetSec: 48,
+        durationMinSec: 42,
+        durationMaxSec: 56,
+        bucket: "long",
+        coverTimestampMs: 2500,
+        visualLanguage: "Paper ground, serif headline, split quote and body, slow reveal.",
+        structureNote: "A kicker, a pull quote, then narrative lines. No slam cuts.",
+        palettes: [
+            palette("paper", "#f3ecdf", "#1d1914", "#7a1f1f", "#7a7166", "#e7dccb"),
+            palette("newsprint", "#ecebe6", "#111111", "#0b3d2e", "#5e5e58", "#dedcd4"),
+            palette("dusk", "#efe4d6", "#24160f", "#b45309", "#8a7364", "#e4d3c0"),
+            palette("slate", "#e6e8ec", "#15181d", "#1d4e89", "#5c6570", "#d5dae1"),
+        ],
+    },
+    SignalBoard: {
+        id: "SignalBoard",
+        pacing: "medium",
+        captionStyle: "terminal",
+        durationTargetSec: 32,
+        durationMinSec: 26,
+        durationMaxSec: 38,
+        bucket: "mid",
+        coverTimestampMs: 1500,
+        visualLanguage: "Dark grid, monospace, indexed rail, evidence bars, terminal chips.",
+        structureNote: "Claim, measured evidence, implication. Captions sit in chips.",
+        palettes: [
+            palette("radar", "#061018", "#d6f5e3", "#1ee0a0", "#6f8f86", "#0c1c24"),
+            palette("amberterm", "#140e06", "#ffe7c2", "#ffb020", "#a88860", "#24180c"),
+            palette("ice", "#0a1018", "#e5f4ff", "#7dd3fc", "#7e93a6", "#121c28"),
+            palette("magma", "#12080c", "#ffe4e6", "#fb7185", "#a87884", "#241016"),
+        ],
+    },
+};
+export const TEMPLATE_IDS = Object.keys(TEMPLATES);
+export function durationBucket(seconds) {
+    if (seconds < 25)
+        return "short";
+    if (seconds <= 40)
+        return "mid";
+    return "long";
+}

package/vendor/@vfrey/contracts/dist/domain/tiktok-chunks.d.ts

@@ -0,0 +1,19 @@
+/**
+ * TikTok Content Posting media transfer, as documented August 4, 2026.
+ * https://developers.tiktok.com/doc/content-posting-api-media-transfer-guide
+ *
+ * The sample uses decimal byte sizes (10_000_000), and total_chunk_count is
+ * video_size / chunk_size rounded down. The final chunk absorbs the remainder
+ * and may be larger than chunk_size, up to 128 MB.
+ */
+export interface TikTokChunkPlan {
+    videoSize: number;
+    chunkSize: number;
+    totalChunkCount: number;
+    ranges: Array<{
+        first: number;
+        last: number;
+        size: number;
+    }>;
+}
+export declare function planTikTokChunks(videoSize: number): TikTokChunkPlan;

package/vendor/@vfrey/contracts/dist/domain/tiktok-chunks.js

@@ -0,0 +1,52 @@
+/**
+ * TikTok Content Posting media transfer, as documented August 4, 2026.
+ * https://developers.tiktok.com/doc/content-posting-api-media-transfer-guide
+ *
+ * The sample uses decimal byte sizes (10_000_000), and total_chunk_count is
+ * video_size / chunk_size rounded down. The final chunk absorbs the remainder
+ * and may be larger than chunk_size, up to 128 MB.
+ */
+const MIN_CHUNK = 5_000_000;
+const MAX_SINGLE = 64_000_000;
+const DEFAULT_CHUNK = 10_000_000;
+const MAX_FINAL = 128_000_000;
+const MAX_CHUNKS = 1000;
+export function planTikTokChunks(videoSize) {
+    if (!Number.isInteger(videoSize) || videoSize <= 0) {
+        throw new Error(`TikTok video_size must be a positive integer, received ${videoSize}`);
+    }
+    if (videoSize > 4_000_000_000) {
+        throw new Error("TikTok rejects videos larger than 4 GB");
+    }
+    let chunkSize;
+    let totalChunkCount;
+    if (videoSize <= MAX_SINGLE) {
+        chunkSize = videoSize;
+        totalChunkCount = 1;
+    }
+    else {
+        chunkSize = DEFAULT_CHUNK;
+        totalChunkCount = Math.floor(videoSize / chunkSize);
+        if (totalChunkCount < 1 || totalChunkCount > MAX_CHUNKS) {
+            throw new Error(`TikTok chunk count ${totalChunkCount} is outside 1..${MAX_CHUNKS}`);
+        }
+    }
+    const ranges = [];
+    for (let index = 0; index < totalChunkCount; index += 1) {
+        const first = index * chunkSize;
+        const last = index === totalChunkCount - 1 ? videoSize - 1 : first + chunkSize - 1;
+        const size = last - first + 1;
+        ranges.push({ first, last, size });
+    }
+    const finalSize = ranges[ranges.length - 1]?.size ?? 0;
+    if (videoSize >= MIN_CHUNK && ranges.some((range, index) => index < ranges.length - 1 && range.size < MIN_CHUNK)) {
+        throw new Error("Non-final TikTok chunk is below 5 MB");
+    }
+    if (finalSize > MAX_FINAL) {
+        throw new Error("Final TikTok chunk exceeds 128 MB");
+    }
+    if (videoSize > MAX_SINGLE && finalSize < MIN_CHUNK) {
+        throw new Error("Final TikTok chunk is below 5 MB");
+    }
+    return { videoSize, chunkSize, totalChunkCount, ranges };
+}

package/vendor/@vfrey/contracts/dist/domain/topics.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Spec 016 (vfrey Topics). Types only. No media URLs live in any of these:
+ * a provider's download link is dropped before a PostObservation is built.
+ */
+import type { Platform } from "./types.js";
+/** Where a post was seen. Reddit and RSS are topic sources, not publish targets. */
+export type ObservationPlatform = Platform | "reddit" | "rss";
+export type SourceId = "scrapecreators" | "ensembledata" | "youtube" | "reddit" | "rss";
+export declare const SOURCE_IDS: readonly SourceId[];
+/** An unknown value is undefined. It is never 0. */
+export interface PostMetrics {
+    views?: number;
+    likes?: number;
+    comments?: number;
+    shares?: number;
+}
+export interface PostObservation {
+    platform: ObservationPlatform;
+    postId: string;
+    url: string;
+    /** Public handle only. */
+    author: {
+        handle: string;
+        id?: string;
+    };
+    caption: string;
+    hashtags: string[];
+    sound?: string;
+    /** ISO 8601. */
+    postedAt: string;
+    /** ISO 8601. */
+    observedAt: string;
+    metrics: PostMetrics;
+    /** Video length in seconds, when the provider gives it (spec 017). Undefined when unknown. */
+    durationSec?: number;
+    source: SourceId;
+    /** YouTube data must be refreshed or deleted by this time (observedAt + 30 days). */
+    refreshBy?: string;
+}
+export interface Niche {
+    id: string;
+    name: string;
+    keywords: string[];
+    hashtags: string[];
+    platforms: ObservationPlatform[];
+    region?: string;
+}
+export interface TopicEvidence {
+    platform: ObservationPlatform;
+    url: string;
+    views?: number;
+    ageHours: number;
+    why: string;
+}
+export interface Topic {
+    id: string;
+    niche: string;
+    /** The top cluster terms. No LLM. */
+    title: string;
+    keywords: string[];
+    platforms: ObservationPlatform[];
+    score: number;
+    velocity: number;
+    evidence: TopicEvidence[];
+    firstSeen: string;
+    lastSeen: string;
+}
+/** One provider call in a collect run. */
+export interface CollectCall {
+    source: SourceId;
+    usd: number;
+    ok: boolean;
+    /** Set when this call served a request after the named source failed. */
+    fallbackFrom?: SourceId;
+    /** Why the earlier source was skipped, or why this call failed. */
+    reason?: string;
+}
+export declare function hasAnyMetric(metrics: PostMetrics): boolean;

package/vendor/@vfrey/contracts/dist/domain/topics.js

@@ -0,0 +1,4 @@
+export const SOURCE_IDS = ["scrapecreators", "ensembledata", "youtube", "reddit", "rss"];
+export function hasAnyMetric(metrics) {
+    return [metrics.views, metrics.likes, metrics.comments, metrics.shares].some((value) => typeof value === "number");
+}