vidspotai-shared 1.0.100 → 1.0.101-dev.0

package/lib/utils/mp4Duration.js

@@ -0,0 +1,164 @@
+"use strict";
+/**
+ * Dependency-free MP4 duration reader.
+ *
+ * WHY THIS EXISTS
+ * Billing prefers the DELIVERED clip length over the REQUESTED one (see
+ * `VideoStatusResult.durationSec`). Kling reports the delivered length in its
+ * status payload, so nothing has to be measured there. PixVerse does NOT — its
+ * `/video/result` response carries `create_time, id, modify_time,
+ * negative_prompt, outputHeight, outputWidth, prompt, resolution_ratio, seed,
+ * size, status, style, url` and nothing else (verified against the official
+ * docs 2026-07-24; `size` is BYTES, not seconds). So for PixVerse the only
+ * honest source of the delivered length is the file itself.
+ *
+ * We already download the finished clip into a Buffer before uploading it to
+ * Firebase, so the bytes are in hand at zero extra network cost. This module
+ * reads the length out of that Buffer by walking the MP4 box tree to `mvhd`,
+ * following the same precedent as `mp4IsComplete()` in google.service.ts:
+ * scan the bytes rather than shell out, because `packages/shared` has no
+ * ffmpeg/ffprobe dependency and must not gain one (it ships to Firebase
+ * Functions, where no such binary exists).
+ *
+ * CONTRACT: this function never throws and never guesses. Every malformed,
+ * truncated, fragmented or otherwise unreadable input returns `undefined`, and
+ * callers fall back to the requested duration — i.e. the pre-existing billing
+ * behaviour. A wrong number here would mis-bill a real user, so "I don't know"
+ * is always the correct answer when the bytes aren't unambiguous.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readMp4DurationSec = readMp4DurationSec;
+/** ISO/IEC 14496-12 box header: 4-byte big-endian size + 4-byte ASCII type. */
+const BOX_HEADER_BYTES = 8;
+/**
+ * A `duration` of all-ones means "unknown" in ISO/IEC 14496-12 — common in
+ * fragmented MP4 (fMP4), where the real length lives in the fragments rather
+ * than in `mvhd`. Treated as unreadable rather than as a huge number.
+ */
+const UNKNOWN_DURATION_32 = 0xffffffff;
+/**
+ * Built from a string, NOT from the numeric literal `0xffffffffffffffff` —
+ * that value is not exactly representable as a JS number and rounds up to
+ * 2^64, so `BigInt(0xffffffffffffffff)` would never equal the real 2^64-1
+ * marker and the check would silently never fire.
+ */
+const UNKNOWN_DURATION_64 = BigInt("0xffffffffffffffff");
+/**
+ * Sanity bound. Nothing this pipeline generates is longer than a few minutes;
+ * a multi-hour result means we misparsed (e.g. read a length field as a
+ * timescale). Reject rather than bill it.
+ */
+const MAX_PLAUSIBLE_DURATION_SEC = 3600;
+/**
+ * Locate a direct child box by type within `[start, end)` and return the byte
+ * range of its PAYLOAD. Returns null when absent or when the tree is malformed.
+ */
+function findBox(buf, type, start, end) {
+    let offset = start;
+    while (offset + BOX_HEADER_BYTES <= end) {
+        const size32 = buf.readUInt32BE(offset);
+        const boxType = buf.toString("ascii", offset + 4, offset + 8);
+        let headerSize = BOX_HEADER_BYTES;
+        let boxSize;
+        if (size32 === 1) {
+            // 64-bit "largesize" follows the type field.
+            if (offset + 16 > end)
+                return null;
+            const large = buf.readBigUInt64BE(offset + 8);
+            // Beyond Number.MAX_SAFE_INTEGER we can't index the Buffer anyway.
+            if (large > BigInt(Number.MAX_SAFE_INTEGER))
+                return null;
+            boxSize = Number(large);
+            headerSize = 16;
+        }
+        else if (size32 === 0) {
+            // Size 0 means "this box extends to the end of the enclosing range".
+            boxSize = end - offset;
+        }
+        else {
+            boxSize = size32;
+        }
+        // A box must at least contain its own header, and must not overrun.
+        if (boxSize < headerSize || offset + boxSize > end)
+            return null;
+        if (boxType === type) {
+            return {
+                payloadStart: offset + headerSize,
+                payloadEnd: offset + boxSize,
+            };
+        }
+        offset += boxSize;
+    }
+    return null;
+}
+/**
+ * Read the duration, in seconds, of an MP4/MOV held in memory.
+ *
+ * Returns `undefined` for anything it cannot read with confidence: non-MP4
+ * input, a truncated download (no `moov`), fragmented MP4 with an unknown
+ * `mvhd` duration, a zero/absent timescale, or an implausible result.
+ *
+ * @param buf Raw bytes of the complete file.
+ */
+function readMp4DurationSec(buf) {
+    try {
+        if (!Buffer.isBuffer(buf) || buf.length < BOX_HEADER_BYTES)
+            return undefined;
+        // `moov` holds the movie metadata. For non-faststart output it sits at the
+        // END of the file, which is exactly why a truncated download loses it.
+        const moov = findBox(buf, "moov", 0, buf.length);
+        if (!moov)
+            return undefined;
+        const mvhd = findBox(buf, "mvhd", moov.payloadStart, moov.payloadEnd);
+        if (!mvhd)
+            return undefined;
+        const { payloadStart, payloadEnd } = mvhd;
+        // mvhd payload: version(1) + flags(3), then version-dependent fields.
+        if (payloadStart + 4 > payloadEnd)
+            return undefined;
+        const version = buf.readUInt8(payloadStart);
+        let timescale;
+        let duration;
+        if (version === 1) {
+            // creation(8) + modification(8) + timescale(4) + duration(8) = 28 bytes
+            if (payloadStart + 4 + 28 > payloadEnd)
+                return undefined;
+            timescale = buf.readUInt32BE(payloadStart + 4 + 16);
+            const raw = buf.readBigUInt64BE(payloadStart + 4 + 20);
+            if (raw === UNKNOWN_DURATION_64)
+                return undefined;
+            if (raw > BigInt(Number.MAX_SAFE_INTEGER))
+                return undefined;
+            duration = Number(raw);
+        }
+        else if (version === 0) {
+            // creation(4) + modification(4) + timescale(4) + duration(4) = 16 bytes
+            if (payloadStart + 4 + 16 > payloadEnd)
+                return undefined;
+            timescale = buf.readUInt32BE(payloadStart + 4 + 8);
+            duration = buf.readUInt32BE(payloadStart + 4 + 12);
+            if (duration === UNKNOWN_DURATION_32)
+                return undefined;
+        }
+        else {
+            // Unknown mvhd version — the field layout is not knowable.
+            return undefined;
+        }
+        if (timescale <= 0)
+            return undefined;
+        // fMP4 commonly writes duration 0 here; the real length is in the fragments.
+        if (duration <= 0)
+            return undefined;
+        const seconds = duration / timescale;
+        if (!Number.isFinite(seconds))
+            return undefined;
+        if (seconds <= 0 || seconds > MAX_PLAUSIBLE_DURATION_SEC)
+            return undefined;
+        return seconds;
+    }
+    catch {
+        // Deliberately swallowed: an unreadable file must degrade to "unknown"
+        // (bill the requested duration), never break status polling.
+        return undefined;
+    }
+}

package/lib/utils/socialEntitlements.d.ts

@@ -0,0 +1,51 @@
+import type { IUserSubscription } from "../models/user.model";
+/**
+ * X8 Social Suite — per-plan entitlements (monetization gate, F1).
+ *
+ * The global `FEATURE_SOCIAL` flag is the *kill-switch* that mounts the whole
+ * `/v1/social` surface; this map is the *per-user plan gate* layered on top of
+ * it. Publishing/analytics/engage are a subscription feature (plan §7), NOT a
+ * credit feature — generation keeps burning credits, the Social Suite is gated
+ * by tier.
+ *
+ * v1 policy mirrors SOCIAL_SUITE_PLAN §7 and is intentionally table-driven so
+ * the tiering can be retuned in ONE place without touching any call site:
+ *   • Free  = the hook — connect ONE account, publish manually, 7-day analytics.
+ *   • Paid  = scheduling + calendar, AI growth layer, engage inbox, advanced
+ *             analytics (best-time + audience + full history), more accounts.
+ *
+ * To make the Social Suite fully paid-only (no free hook), set FREE.enabled to
+ * false and gate the router with `requireSocialCapability` accordingly — every
+ * consumer reads this map, so that one edit changes the whole product.
+ */
+export interface ISocialCapabilities {
+    /** May use the Social Suite at all (connect + manual publish + basic stats). */
+    enabled: boolean;
+    /** Max connected accounts across every provider. */
+    maxAccounts: number;
+    /** Schedule posts for the future / use the content calendar (B3). */
+    scheduling: boolean;
+    /** AI growth layer: caption/hashtag/title suggest, hook score, insights (E1/E4/E5). */
+    aiGrowth: boolean;
+    /** Engagement inbox: reply / moderate / AI reply drafts (Pillar D). */
+    inbox: boolean;
+    /** Best-time-to-post (C4) + audience demographics (C7). */
+    advancedAnalytics: boolean;
+    /** How far back the overview dashboard history is visible (days). */
+    analyticsWindowDays: number;
+}
+/** The gated boolean capabilities a route/middleware can require. */
+export type TSocialGatedCapability = "scheduling" | "aiGrowth" | "inbox" | "advancedAnalytics";
+/**
+ * Resolve the Social-Suite capabilities for a user's subscription.
+ *
+ * Reuses `isPaidSubscription` so a trial / canceled / expired / inactive sub —
+ * or a missing one — falls back to the FREE hook tier, exactly like the
+ * watermark predicate. Erring toward the lower tier on a status blip (e.g.
+ * webhook lag) is the safe default: it withholds a paid feature for a moment
+ * rather than leaking it, and self-heals on the next `/v1/user` sync.
+ */
+export declare function getSocialCapabilities(subscription: IUserSubscription | undefined | null): ISocialCapabilities;
+/** Whether a subscription includes a specific gated Social-Suite capability. */
+export declare function planAllowsSocialCapability(subscription: IUserSubscription | undefined | null, capability: TSocialGatedCapability): boolean;
+//# sourceMappingURL=socialEntitlements.d.ts.map

package/lib/utils/socialEntitlements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"socialEntitlements.d.ts","sourceRoot":"","sources":["../../src/utils/socialEntitlements.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAG9D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,mBAAmB;IAClC,gFAAgF;IAChF,OAAO,EAAE,OAAO,CAAC;IACjB,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,UAAU,EAAE,OAAO,CAAC;IACpB,uFAAuF;IACvF,QAAQ,EAAE,OAAO,CAAC;IAClB,uEAAuE;IACvE,KAAK,EAAE,OAAO,CAAC;IACf,2DAA2D;IAC3D,iBAAiB,EAAE,OAAO,CAAC;IAC3B,qEAAqE;IACrE,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,qEAAqE;AACrE,MAAM,MAAM,sBAAsB,GAC9B,YAAY,GACZ,UAAU,GACV,OAAO,GACP,mBAAmB,CAAC;AA4CxB;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,iBAAiB,GAAG,SAAS,GAAG,IAAI,GACjD,mBAAmB,CAIrB;AAED,gFAAgF;AAChF,wBAAgB,0BAA0B,CACxC,YAAY,EAAE,iBAAiB,GAAG,SAAS,GAAG,IAAI,EAClD,UAAU,EAAE,sBAAsB,GACjC,OAAO,CAET"}

package/lib/utils/socialEntitlements.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSocialCapabilities = getSocialCapabilities;
+exports.planAllowsSocialCapability = planAllowsSocialCapability;
+const types_1 = require("../globals/types");
+const renderTier_1 = require("./renderTier");
+const SOCIAL_CAPABILITIES = {
+    [types_1.ESUBSCRIPTION_PLANS.FREE]: {
+        enabled: true,
+        maxAccounts: 1,
+        scheduling: false,
+        aiGrowth: false,
+        inbox: false,
+        advancedAnalytics: false,
+        analyticsWindowDays: 7,
+    },
+    [types_1.ESUBSCRIPTION_PLANS.BASIC]: {
+        enabled: true,
+        maxAccounts: 5,
+        scheduling: true,
+        aiGrowth: true,
+        inbox: true,
+        advancedAnalytics: true,
+        analyticsWindowDays: 90,
+    },
+    [types_1.ESUBSCRIPTION_PLANS.PRO]: {
+        enabled: true,
+        maxAccounts: 25,
+        scheduling: true,
+        aiGrowth: true,
+        inbox: true,
+        advancedAnalytics: true,
+        analyticsWindowDays: 365,
+    },
+    [types_1.ESUBSCRIPTION_PLANS.BUSINESS]: {
+        enabled: true,
+        maxAccounts: 100,
+        scheduling: true,
+        aiGrowth: true,
+        inbox: true,
+        advancedAnalytics: true,
+        analyticsWindowDays: 365,
+    },
+};
+/** The tier everyone without an active paid plan falls back to (the free hook). */
+const FREE_CAPABILITIES = SOCIAL_CAPABILITIES[types_1.ESUBSCRIPTION_PLANS.FREE];
+/**
+ * Resolve the Social-Suite capabilities for a user's subscription.
+ *
+ * Reuses `isPaidSubscription` so a trial / canceled / expired / inactive sub —
+ * or a missing one — falls back to the FREE hook tier, exactly like the
+ * watermark predicate. Erring toward the lower tier on a status blip (e.g.
+ * webhook lag) is the safe default: it withholds a paid feature for a moment
+ * rather than leaking it, and self-heals on the next `/v1/user` sync.
+ */
+function getSocialCapabilities(subscription) {
+    if (!(0, renderTier_1.isPaidSubscription)(subscription))
+        return FREE_CAPABILITIES;
+    const plan = subscription?.planType;
+    return (plan && SOCIAL_CAPABILITIES[plan]) || FREE_CAPABILITIES;
+}
+/** Whether a subscription includes a specific gated Social-Suite capability. */
+function planAllowsSocialCapability(subscription, capability) {
+    return getSocialCapabilities(subscription)[capability] === true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vidspotai-shared",
-  "version": "1.0.100",
+  "version": "1.0.101-dev.0",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "exports": {