@vfrey/vfrey 0.0.1 → 1.0.0-beta.1

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

@@ -0,0 +1,95 @@
+import { ConfigError } from "./errors.js";
+export function zonedParts(date, timeZone) {
+    const fmt = new Intl.DateTimeFormat("en-US", {
+        timeZone,
+        hourCycle: "h23",
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+    });
+    const map = {};
+    for (const part of fmt.formatToParts(date)) {
+        if (part.type !== "literal")
+            map[part.type] = part.value;
+    }
+    return {
+        year: Number(map.year),
+        month: Number(map.month),
+        day: Number(map.day),
+        hour: Number(map.hour === "24" ? "0" : map.hour),
+        minute: Number(map.minute),
+    };
+}
+export function localDayKey(date, timeZone) {
+    const parts = zonedParts(date, timeZone);
+    const month = String(parts.month).padStart(2, "0");
+    const day = String(parts.day).padStart(2, "0");
+    return `${parts.year}-${month}-${day}`;
+}
+function minutes(hour, minute) {
+    return hour * 60 + minute;
+}
+function parseWindow(value) {
+    const match = /^(\d{2}):(\d{2})-(\d{2}):(\d{2})$/.exec(value.trim());
+    if (!match)
+        throw new ConfigError("cadence_window", `Cadence window must look like 09:00-11:30, received ${value}`);
+    const [, h1, m1, h2, m2] = match.map(Number);
+    if (h1 > 23 || h2 > 24 || m1 > 59 || m2 > 59 || (h2 === 24 && m2 !== 0)) {
+        throw new ConfigError("cadence_window", `Cadence window ${value} has an hour or minute out of range`);
+    }
+    const start = minutes(h1, m1);
+    const end = minutes(h2, m2);
+    if (start >= end) {
+        throw new ConfigError("cadence_window", `Cadence window ${value} must end after it starts on the same day`);
+    }
+    return { start, end };
+}
+/** Throws ConfigError for a timezone Intl rejects, malformed windows, or non-sensible limits. */
+export function validateCadence(cadence) {
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone: cadence.timezone });
+    }
+    catch {
+        throw new ConfigError("cadence_timezone", `Cadence timezone ${JSON.stringify(cadence.timezone)} is not a valid IANA timezone`);
+    }
+    if (!Array.isArray(cadence.windows)) {
+        throw new ConfigError("cadence_window", "Cadence windows must be a list of HH:MM-HH:MM strings");
+    }
+    for (const windowValue of cadence.windows) {
+        if (typeof windowValue !== "string") {
+            throw new ConfigError("cadence_window", "Cadence windows must be a list of HH:MM-HH:MM strings");
+        }
+        parseWindow(windowValue);
+    }
+    if (!Number.isFinite(cadence.minHoursBetweenPosts) || cadence.minHoursBetweenPosts < 0) {
+        throw new ConfigError("cadence_limit", "minHoursBetweenPosts must be a number of hours, zero or more");
+    }
+    if (!Number.isInteger(cadence.maxPostsPerDay) || cadence.maxPostsPerDay < 1) {
+        throw new ConfigError("cadence_limit", "maxPostsPerDay must be a whole number, one or more");
+    }
+}
+export function cadenceDecision(input) {
+    const { cadence, now } = input;
+    if (input.postsOnLocalDay >= cadence.maxPostsPerDay) {
+        return { due: false, reason: "daily_cap" };
+    }
+    if (input.lastPublishedAt) {
+        const elapsedMs = now.getTime() - input.lastPublishedAt.getTime();
+        const minMs = cadence.minHoursBetweenPosts * 60 * 60 * 1000;
+        if (elapsedMs < minMs)
+            return { due: false, reason: "min_interval" };
+    }
+    if (cadence.windows.length > 0) {
+        const parts = zonedParts(now, cadence.timezone);
+        const nowMinutes = minutes(parts.hour, parts.minute);
+        const open = cadence.windows.some((windowValue) => {
+            const window = parseWindow(windowValue);
+            return nowMinutes >= window.start && nowMinutes < window.end;
+        });
+        if (!open)
+            return { due: false, reason: "outside_window" };
+    }
+    return { due: true, reason: "due" };
+}

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

@@ -0,0 +1,146 @@
+/**
+ * Spec 017 (Creators). Types only, plus one constant. No media URL (avatar, cover, video) lives
+ * in any of these. An unknown value is undefined, never 0. Phone numbers are never stored.
+ */
+import type { PostMetrics, SourceId } from "./topics.js";
+import type { Platform } from "./types.js";
+/** Platforms with creator profiles. Facebook has no provider yet. */
+export declare const CREATOR_PLATFORMS: readonly Platform[];
+/**
+ * A contact the creator's own bio presents as a business contact ("business:", "collab",
+ * "contact", "inquiries"). Nothing else is extracted. Never a phone number.
+ */
+export interface BusinessContact {
+    kind: "email" | "link";
+    value: string;
+    /** Always true: the value was read from the public bio. */
+    fromBio: true;
+}
+/** One observation of a creator's public profile. */
+export interface CreatorProfile {
+    platform: Platform;
+    /** The platform's own id (TikTok uid, Instagram id, YouTube channel id). */
+    id: string;
+    /** Public handle without the leading @. */
+    handle: string;
+    displayName?: string;
+    followers?: number;
+    following?: number;
+    totalLikes?: number;
+    postCount?: number;
+    verified?: boolean;
+    bio?: string;
+    businessContact?: BusinessContact;
+    /** ISO 8601. */
+    observedAt: string;
+    source: SourceId;
+    /** YouTube data must be refreshed or deleted by this time (observedAt + 30 days). */
+    refreshBy?: string;
+}
+/** Followers at a point in time, from stored CreatorProfile observations. */
+export interface FollowerSnapshot {
+    /** ISO 8601. */
+    observedAt: string;
+    followers?: number;
+}
+export interface FollowerGrowth {
+    /** Followers gained (negative when lost) over the window. */
+    abs: number;
+    /** abs / starting followers. Undefined when the start was 0. */
+    pct?: number;
+}
+/** What the engagement rate was divided by. Never mix the two when comparing creators. */
+export type EngagementBasis = "views" | "followers";
+export interface CreatorTopPost {
+    postId: string;
+    url: string;
+    caption: string;
+    postedAt: string;
+    metrics: PostMetrics;
+    durationSec?: number;
+}
+export interface CreatorFormat {
+    /** The top cluster terms. No LLM. */
+    name: string;
+    terms: string[];
+    postCount: number;
+    examplePostIds: string[];
+}
+export interface CreatorHook {
+    postId: string;
+    /** The first sentence of the caption. */
+    text: string;
+}
+export interface PostingTimes {
+    /** "creator-local" when a time zone was known, else "utc". */
+    basis: "creator-local" | "utc";
+    /** IANA zone name, or "UTC". */
+    timeZone: string;
+    /** Posts per hour of day, index 0 to 23. */
+    hours: number[];
+    /** Posts per weekday, index 0 (Sunday) to 6. */
+    weekdays: number[];
+    /** Hours with the highest median views, best first. Empty when views are unknown. */
+    bestHours: number[];
+    /** Weekdays with the highest median views, best first. Empty when views are unknown. */
+    bestWeekdays: number[];
+}
+export interface CreatorStats {
+    platform: Platform;
+    handle: string;
+    /** ISO 8601. */
+    computedAt: string;
+    /** Recent posts the numbers come from. */
+    sampleSize: number;
+    medianViews?: number;
+    /** (likes + comments + shares) / basis, as a fraction (0.05 is 5%). */
+    engagementRate?: number;
+    engagementBasis?: EngagementBasis;
+    /**
+     * Posts per week. "30d" means counted over the last 30 days. "sample" means the recent posts
+     * did not reach back 30 days, so the rate is over the span the sample covers (at least 7 days).
+     */
+    postsPerWeek?: number;
+    postsPerWeekBasis?: "30d" | "sample";
+    growth7d?: FollowerGrowth;
+    growth30d?: FollowerGrowth;
+    postingTimes?: PostingTimes;
+    medianLengthSec?: number;
+    topPosts: CreatorTopPost[];
+    formats: CreatorFormat[];
+    hooks: CreatorHook[];
+}
+/** One row of a creator search: enough to rank and pick, nothing more. */
+export interface CreatorSummary {
+    platform: Platform;
+    handle: string;
+    displayName?: string;
+    followers?: number;
+    verified?: boolean;
+    niche?: string;
+    postsPerWeek?: number;
+    engagementRate?: number;
+    engagementBasis?: EngagementBasis;
+    medianViews?: number;
+    growth30dPct?: number;
+    /** ISO 8601. */
+    observedAt: string;
+    source: SourceId;
+}
+export interface WatchlistItem {
+    id: string;
+    watchlistId: string;
+    platform: Platform;
+    handle: string;
+    note?: string;
+    /** ISO 8601. */
+    addedAt: string;
+}
+export interface Watchlist {
+    id: string;
+    orgId: string;
+    name: string;
+    /** ISO 8601. */
+    createdAt: string;
+    items?: WatchlistItem[];
+}

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

@@ -0,0 +1,2 @@
+/** Platforms with creator profiles. Facebook has no provider yet. */
+export const CREATOR_PLATFORMS = ["youtube", "tiktok", "instagram"];

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

@@ -0,0 +1,127 @@
+import type { DisclosureProof } from "./types.js";
+/**
+ * Compliance checklist. These are platform rules, not creative preferences.
+ * A video can be original and still fail here. A video can pass here and
+ * still fail the quality variation gates.
+ */
+export declare const COMPLIANCE_CHECKLIST: ({
+    id: string;
+    platform: "youtube";
+    field: string;
+    location: string;
+    rule: string;
+} | {
+    id: string;
+    platform: "tiktok";
+    field: string;
+    location: string;
+    rule: string;
+} | {
+    id: string;
+    platform: "instagram";
+    field: string;
+    location: string;
+    rule: string;
+} | {
+    id: string;
+    platform: "facebook";
+    field: string;
+    location: string;
+    rule: string;
+} | {
+    id: string;
+    platform: "all";
+    field: string;
+    location: string;
+    rule: string;
+})[];
+export declare function assertNotVerbatim(script: string, sourceText: string): void;
+export declare function assertNoAdvicePersona(script: string): void;
+export interface YouTubeMetadata {
+    snippet: {
+        title: string;
+        description: string;
+        tags: string[];
+        categoryId: string;
+        defaultLanguage: string;
+    };
+    status: {
+        privacyStatus: "public" | "private" | "unlisted";
+        selfDeclaredMadeForKids: boolean;
+        containsSyntheticMedia: true;
+        embeddable: boolean;
+    };
+}
+/** YouTube: title up to 100 characters, description up to 5000 bytes (UTF-8). */
+export declare const YOUTUBE_TITLE_CHARS = 100;
+export declare const YOUTUBE_DESCRIPTION_BYTES = 5000;
+/** YouTube rejects "<" and ">" in titles and descriptions. */
+export declare function stripAngleBrackets(value: string): string;
+export declare function buildYouTubeMetadata(input: {
+    title: string;
+    description: string;
+    tags: string[];
+    categoryId: string;
+    privacyStatus: "public" | "private" | "unlisted";
+    madeForKids: boolean;
+    language: string;
+}): {
+    body: YouTubeMetadata;
+    proof: DisclosureProof;
+};
+export interface TikTokInitBody {
+    post_info: {
+        title: string;
+        privacy_level: string;
+        disable_duet: boolean;
+        disable_comment: boolean;
+        disable_stitch: boolean;
+        video_cover_timestamp_ms: number;
+        brand_content_toggle: boolean;
+        brand_organic_toggle: boolean;
+        is_aigc: true;
+    };
+    source_info: {
+        source: "FILE_UPLOAD";
+        video_size: number;
+        chunk_size: number;
+        total_chunk_count: number;
+    };
+}
+export declare function buildTikTokInit(input: {
+    caption: string;
+    privacyLevel: string;
+    disableComment: boolean;
+    coverTimestampMs: number;
+    brandContent: boolean;
+    brandOrganic: boolean;
+    videoSize: number;
+    chunkSize: number;
+    totalChunkCount: number;
+    audited: boolean;
+    privacyOptions: string[];
+}): {
+    body: TikTokInitBody;
+    proof: DisclosureProof;
+};
+export declare function buildInstagramContainer(input: {
+    caption: string;
+    shareToFeed: boolean;
+}): {
+    form: Record<string, string>;
+    proof: DisclosureProof;
+};
+export declare function buildFacebookFinish(input: {
+    videoId: string;
+    title: string;
+    description: string;
+}): {
+    form: Record<string, string>;
+    proof: DisclosureProof;
+};
+export declare function clip(value: string, max: number): string;
+export declare function utf8Bytes(value: string): number;
+/** Clip to a UTF-8 byte budget without splitting a code point or surrogate pair. */
+export declare function clipBytes(value: string, maxBytes: number): string;
+export declare function utf16Length(value: string): number;
+export declare function clipUtf16(value: string, maxUnits: number): string;

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

@@ -0,0 +1,250 @@
+import { ComplianceError } from "./errors.js";
+import { claimsAdvicePersona } from "./advice-persona.js";
+import { longestSharedWordRun } from "./similarity.js";
+/**
+ * Compliance checklist. These are platform rules, not creative preferences.
+ * A video can be original and still fail here. A video can pass here and
+ * still fail the quality variation gates.
+ */
+export const COMPLIANCE_CHECKLIST = [
+    {
+        id: "youtube-synthetic",
+        platform: "youtube",
+        field: "status.containsSyntheticMedia",
+        location: "videos.insert body status.containsSyntheticMedia (part=snippet,status)",
+        rule: "Always true. YouTube Data API, videos.insert, documented on the video resource status.",
+    },
+    {
+        id: "tiktok-aigc",
+        platform: "tiktok",
+        field: "post_info.is_aigc",
+        location: "POST /v2/post/publish/video/init/ post_info.is_aigc",
+        rule: "Always true. TikTok labels the post with the creator-labeled AI-generated tag.",
+    },
+    {
+        id: "instagram-ai",
+        platform: "instagram",
+        field: "is_ai_generated",
+        location: "POST /{ig-user-id}/media is_ai_generated=true, before media_publish",
+        rule: "Always true on the media container. Instagram changelog, June 22, 2026. Carousels would set it on the container only. This pipeline publishes Reels.",
+    },
+    {
+        id: "facebook-ai",
+        platform: "facebook",
+        field: "is_ai_generated",
+        location: "POST /{page-id}/video_reels upload_phase=finish is_ai_generated=true",
+        rule: "Always true on the finish call. Page Video Reels documents is_ai_generated as the self-claim flag. If the platform rejects the field, the job blocks and does not publish without it.",
+    },
+    {
+        id: "verbatim-source",
+        platform: "all",
+        field: "script",
+        location: "generate stage, before render",
+        rule: "A 12-word run shared with the source excerpt is a compliance block (reused content and copyright), not a style nit.",
+    },
+    {
+        id: "advice-persona",
+        platform: "all",
+        field: "source score",
+        location: "source stage",
+        rule: "AI personas giving medical, legal, or financial advice are blocked. YouTube's monetization policy treats that category as ineligible.",
+    },
+];
+export function assertNotVerbatim(script, sourceText) {
+    const run = longestSharedWordRun(script, sourceText);
+    if (run >= 12) {
+        throw new ComplianceError("verbatim_source_overlap", `Script shares a ${run}-word run with the source. That is reused content, not a variation miss.`);
+    }
+}
+export function assertNoAdvicePersona(script) {
+    if (claimsAdvicePersona(script)) {
+        throw new ComplianceError("advice_persona", "Script presents an AI persona as a doctor, lawyer, or financial adviser.");
+    }
+}
+/** YouTube: title up to 100 characters, description up to 5000 bytes (UTF-8). */
+export const YOUTUBE_TITLE_CHARS = 100;
+export const YOUTUBE_DESCRIPTION_BYTES = 5000;
+/** YouTube rejects "<" and ">" in titles and descriptions. */
+export function stripAngleBrackets(value) {
+    return value.replace(/</g, "\u2039").replace(/>/g, "\u203a");
+}
+export function buildYouTubeMetadata(input) {
+    const body = {
+        snippet: {
+            title: clip(stripAngleBrackets(input.title), YOUTUBE_TITLE_CHARS),
+            description: clipBytes(stripAngleBrackets(input.description), YOUTUBE_DESCRIPTION_BYTES),
+            tags: clipTags(input.tags),
+            categoryId: input.categoryId,
+            defaultLanguage: input.language,
+        },
+        status: {
+            privacyStatus: input.privacyStatus,
+            selfDeclaredMadeForKids: input.madeForKids,
+            containsSyntheticMedia: true,
+            embeddable: true,
+        },
+    };
+    assertDisclosure("youtube", body.status.containsSyntheticMedia);
+    return {
+        body,
+        proof: {
+            platform: "youtube",
+            field: "status.containsSyntheticMedia",
+            value: true,
+            location: "videos.insert JSON body, part=snippet,status",
+        },
+    };
+}
+export function buildTikTokInit(input) {
+    if (!input.audited && input.privacyLevel !== "SELF_ONLY") {
+        throw new ComplianceError("tiktok_unaudited_public", "Unaudited TikTok clients can only post privately. Set privacyLevel to SELF_ONLY, or finish TikTok's Content Posting audit. The worker will not silently downgrade a public request.");
+    }
+    if (!input.privacyOptions.includes(input.privacyLevel)) {
+        throw new ComplianceError("tiktok_privacy_mismatch", `privacy_level ${input.privacyLevel} is not in creator options [${input.privacyOptions.join(", ")}]. Query creator info is mandatory, and the worker will not substitute a different level.`);
+    }
+    const body = {
+        post_info: {
+            title: clipUtf16(input.caption, 2200),
+            privacy_level: input.privacyLevel,
+            disable_duet: false,
+            disable_comment: input.disableComment,
+            disable_stitch: false,
+            video_cover_timestamp_ms: input.coverTimestampMs,
+            brand_content_toggle: input.brandContent,
+            brand_organic_toggle: input.brandOrganic,
+            is_aigc: true,
+        },
+        source_info: {
+            source: "FILE_UPLOAD",
+            video_size: input.videoSize,
+            chunk_size: input.chunkSize,
+            total_chunk_count: input.totalChunkCount,
+        },
+    };
+    assertDisclosure("tiktok", body.post_info.is_aigc);
+    return {
+        body,
+        proof: {
+            platform: "tiktok",
+            field: "post_info.is_aigc",
+            value: true,
+            location: "POST https://open.tiktokapis.com/v2/post/publish/video/init/",
+        },
+    };
+}
+export function buildInstagramContainer(input) {
+    const form = {
+        media_type: "REELS",
+        upload_type: "resumable",
+        caption: clip(input.caption, 2200),
+        share_to_feed: input.shareToFeed ? "true" : "false",
+        is_ai_generated: "true",
+    };
+    if (form.is_ai_generated !== "true") {
+        throw new ComplianceError("instagram_disclosure", "Instagram container lost is_ai_generated.");
+    }
+    return {
+        form,
+        proof: {
+            platform: "instagram",
+            field: "is_ai_generated",
+            value: true,
+            location: "POST /{ig-user-id}/media (container). media_publish does not carry the flag.",
+        },
+    };
+}
+export function buildFacebookFinish(input) {
+    const form = {
+        upload_phase: "finish",
+        video_id: input.videoId,
+        video_state: "PUBLISHED",
+        title: clip(input.title, 255),
+        description: clip(input.description, 5000),
+        is_ai_generated: "true",
+    };
+    if (form.is_ai_generated !== "true" || form.upload_phase !== "finish") {
+        throw new ComplianceError("facebook_disclosure", "Facebook finish call lost is_ai_generated.");
+    }
+    return {
+        form,
+        proof: {
+            platform: "facebook",
+            field: "is_ai_generated",
+            value: true,
+            location: "POST /{page-id}/video_reels upload_phase=finish",
+        },
+    };
+}
+function assertDisclosure(platform, value) {
+    if (value !== true) {
+        throw new ComplianceError(`${platform}_disclosure`, `${platform} synthetic-media flag was not true. Publish is refused.`);
+    }
+}
+export function clip(value, max) {
+    const trimmed = value.trim();
+    if (trimmed.length <= max)
+        return trimmed;
+    let end = Math.max(0, max - 1);
+    const last = trimmed.charCodeAt(end - 1);
+    if (end > 0 && last >= 0xd800 && last <= 0xdbff)
+        end -= 1;
+    return trimmed.slice(0, end).trimEnd() + "…";
+}
+export function utf8Bytes(value) {
+    return new TextEncoder().encode(value).length;
+}
+/** Clip to a UTF-8 byte budget without splitting a code point or surrogate pair. */
+export function clipBytes(value, maxBytes) {
+    const trimmed = value.trim();
+    if (utf8Bytes(trimmed) <= maxBytes)
+        return trimmed;
+    const ellipsis = "…";
+    const budget = maxBytes - utf8Bytes(ellipsis);
+    let used = 0;
+    let out = "";
+    for (const char of trimmed) {
+        const size = utf8Bytes(char);
+        if (used + size > budget)
+            break;
+        out += char;
+        used += size;
+    }
+    return out.trimEnd() + ellipsis;
+}
+export function utf16Length(value) {
+    let length = 0;
+    for (const char of value) {
+        const point = char.codePointAt(0) ?? 0;
+        length += point > 0xffff ? 2 : 1;
+    }
+    return length;
+}
+export function clipUtf16(value, maxUnits) {
+    let length = 0;
+    let out = "";
+    for (const char of value.trim()) {
+        const point = char.codePointAt(0) ?? 0;
+        const units = point > 0xffff ? 2 : 1;
+        if (length + units > maxUnits)
+            break;
+        out += char;
+        length += units;
+    }
+    return out;
+}
+function clipTags(tags) {
+    const cleaned = [];
+    let used = 0;
+    for (const tag of tags) {
+        const value = tag.replace(/^#/, "").trim();
+        if (!value)
+            continue;
+        if (used + value.length + 1 > 480)
+            break;
+        cleaned.push(value);
+        used += value.length + 1;
+        if (cleaned.length >= 15)
+            break;
+    }
+    return cleaned;
+}

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

@@ -0,0 +1,34 @@
+/**
+ * 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 type RiskClass = "quality" | "compliance" | "transport" | "config";
+export declare class AppError extends Error {
+    readonly code: string;
+    readonly retryable: boolean;
+    readonly risk: RiskClass;
+    constructor(message: string, code: string, retryable: boolean, risk: RiskClass);
+}
+export declare class QualityError extends AppError {
+    constructor(code: string, message: string);
+}
+export declare class ComplianceError extends AppError {
+    constructor(code: string, message: string);
+}
+export declare class RetryableError extends AppError {
+    readonly retryAfterMs: number | undefined;
+    constructor(code: string, message: string, retryAfterMs?: number);
+}
+export declare class ConfigError extends AppError {
+    constructor(code: string, message: string);
+}
+export declare function asAppError(error: unknown): AppError;