@recordtimelabel/core 0.4.7 → 0.5.0

package/src/domain/twitch-vod.js

@@ -0,0 +1,303 @@
+import {fingerprintCanonicalJson} from './hash.js';
+import {buildRecordTimeLabelGroupIndex} from './group-identity.js';
+import {
+  DEFAULT_UNKNOWN_TITLE,
+  collectNonVirtualRecords,
+  extractTwitchVodIdFromUrl,
+  getFirstMatchingUrlValue,
+  getRecordUrls,
+  normalizeId,
+  normalizeRecordPlatform,
+  normalizeText,
+  parseElapsedSeconds
+} from './shared.js';
+import {parseUtcMillis} from './time.js';
+
+const TITLE_BRACKET_PATTERN = /\[[^\]]*\]|\([^)]*\)|\{[^}]*\}/g;
+const NON_WORD_PATTERN = /[^\p{L}\p{N}\s]/gu;
+const MINUTE_MS = 60 * 1000;
+const HOUR_MS = 60 * MINUTE_MS;
+const RECORD_AFTER_START_GRACE_MS = 10 * MINUTE_MS;
+const STREAM_START_GRACE_MS = 45 * MINUTE_MS;
+const ELAPSED_START_TOLERANCE_MS = 45 * MINUTE_MS;
+const MAX_REASONABLE_STREAM_MS = 48 * HOUR_MS;
+
+const getVodStartMs = (vod = {}) => parseUtcMillis(vod.publishedAt || vod.createdAt);
+
+const getNextVodStartMs = (value) => (
+  typeof value === 'number' && Number.isFinite(value) && value > 0
+    ? value
+    : parseUtcMillis(value)
+);
+
+export const normalizeVodTitleForMatch = (value) => String(value || '')
+  .toLowerCase()
+  .normalize('NFKC')
+  .replace(TITLE_BRACKET_PATTERN, ' ')
+  .replace(NON_WORD_PATTERN, ' ')
+  .replace(/\s+/g, ' ')
+  .trim();
+
+export const calculateVodTitleSimilarity = (expectedTitle, candidateTitle) => {
+  const expected = normalizeVodTitleForMatch(expectedTitle);
+  const candidate = normalizeVodTitleForMatch(candidateTitle);
+  if (!expected || !candidate) return 0;
+  if (expected === candidate) return 1;
+  if (expected.includes(candidate) || candidate.includes(expected)) return 0.9;
+
+  const expectedTokens = new Set(expected.split(' ').filter(Boolean));
+  const candidateTokens = new Set(candidate.split(' ').filter(Boolean));
+  if (expectedTokens.size === 0 || candidateTokens.size === 0) return 0;
+
+  let intersection = 0;
+  expectedTokens.forEach((token) => {
+    if (candidateTokens.has(token)) intersection += 1;
+  });
+  const union = new Set([...expectedTokens, ...candidateTokens]).size;
+  return union > 0 ? intersection / union : 0;
+};
+
+export const scoreTwitchVodCandidate = (vod = {}, context = {}) => {
+  const recordMs = parseUtcMillis(context.recordTimestamp);
+  const streamStartMs = parseUtcMillis(context.streamCreatedAt || context.streamStartedAt);
+  const elapsedSeconds = parseElapsedSeconds(context.recordLiveTimeSeconds);
+  const targetSeconds = parseElapsedSeconds(context.recordTargetTimeSeconds) ?? elapsedSeconds;
+  const vodStartMs = getVodStartMs(vod);
+  const nextVodStartMs = getNextVodStartMs(context.nextVodStartMs || context.nextVodStartAt);
+
+  if (!vod?.id || vodStartMs === null) return null;
+
+  const expectedStartMs = recordMs !== null && elapsedSeconds !== null
+    ? recordMs - (elapsedSeconds * 1000)
+    : null;
+  const lengthSeconds = parseElapsedSeconds(vod.lengthSeconds);
+  const hasStableAnchor = Boolean(streamStartMs !== null || expectedStartMs !== null);
+  const matchedBy = [];
+  let score = 0;
+  const streamAnchorMs = expectedStartMs !== null ? expectedStartMs : streamStartMs;
+  const targetAbsoluteMs = targetSeconds !== null && streamAnchorMs !== null
+    ? streamAnchorMs + (targetSeconds * 1000)
+    : recordMs;
+  const lengthEndMs = lengthSeconds !== null ? vodStartMs + (lengthSeconds * 1000) : null;
+  const inferredEndMs = nextVodStartMs !== null &&
+    nextVodStartMs > vodStartMs &&
+    nextVodStartMs - vodStartMs <= MAX_REASONABLE_STREAM_MS
+    ? nextVodStartMs
+    : null;
+  const vodEndMs = lengthEndMs || inferredEndMs;
+
+  if (targetAbsoluteMs !== null) {
+    if (targetAbsoluteMs < vodStartMs - RECORD_AFTER_START_GRACE_MS) return null;
+    if (vodEndMs !== null && targetAbsoluteMs >= vodEndMs + RECORD_AFTER_START_GRACE_MS) return null;
+    if (vodEndMs !== null) {
+      score += 80;
+      matchedBy.push('target-window');
+    }
+  }
+
+  if (expectedStartMs !== null) {
+    const startDelta = Math.abs(vodStartMs - expectedStartMs);
+    if (startDelta <= ELAPSED_START_TOLERANCE_MS) {
+      const closeness = 1 - (startDelta / ELAPSED_START_TOLERANCE_MS);
+      score += 85 + (closeness * 15);
+      matchedBy.push('elapsed-start');
+    }
+  }
+
+  if (streamStartMs !== null && recordMs !== null) {
+    const startsInsideStreamWindow =
+      vodStartMs >= streamStartMs - STREAM_START_GRACE_MS &&
+      vodStartMs <= recordMs + RECORD_AFTER_START_GRACE_MS;
+    if (startsInsideStreamWindow) {
+      const streamSpan = Math.max(recordMs - streamStartMs, 1);
+      const positionPenalty = Math.min(Math.max(vodStartMs - streamStartMs, 0) / streamSpan, 1) * 15;
+      score += 70 - positionPenalty;
+      matchedBy.push('stream-window');
+    }
+  }
+
+  if (recordMs !== null && vodEndMs !== null) {
+    const containsRecord =
+      recordMs >= vodStartMs - RECORD_AFTER_START_GRACE_MS &&
+      recordMs <= vodEndMs + RECORD_AFTER_START_GRACE_MS;
+    if (containsRecord) {
+      score += 60;
+      matchedBy.push('duration-window');
+    }
+  }
+
+  if (!hasStableAnchor && recordMs !== null) {
+    const recordOffsetMs = recordMs - vodStartMs;
+    if (recordOffsetMs >= -RECORD_AFTER_START_GRACE_MS && recordOffsetMs <= MAX_REASONABLE_STREAM_MS) {
+      const closeness = 1 - Math.min(Math.max(recordOffsetMs, 0) / MAX_REASONABLE_STREAM_MS, 1);
+      score += 30 + (closeness * 20);
+      matchedBy.push('legacy-time-window');
+    }
+  }
+
+  if (matchedBy.length === 0) return null;
+
+  const titleSimilarity = calculateVodTitleSimilarity(context.expectedTitle, vod.title || '');
+  score += titleSimilarity * 10;
+  if (score < (hasStableAnchor ? 55 : 25)) return null;
+
+  const vodTimeOffsetSeconds = targetSeconds !== null && matchedBy.includes('elapsed-start')
+    ? targetSeconds
+    : targetSeconds !== null && streamAnchorMs !== null
+      ? Math.max(0, Math.floor(targetSeconds - ((vodStartMs - streamAnchorMs) / 1000)))
+      : (recordMs !== null
+        ? Math.max(0, Math.floor((recordMs - vodStartMs) / 1000))
+        : targetSeconds);
+
+  return {
+    vod,
+    score,
+    matchedBy,
+    titleSimilarity,
+    vodStartAt: new Date(vodStartMs).toISOString(),
+    vodTimeOffsetSeconds
+  };
+};
+
+export const selectBestMatchingTwitchVod = (items = [], context = {}) => {
+  const normalizedItems = (Array.isArray(items) ? items : [])
+    .map((item) => item?.node || item)
+    .map((vod) => ({vod, startMs: getVodStartMs(vod)}))
+    .filter((entry) => entry.vod?.id && entry.startMs !== null)
+    .sort((a, b) => a.startMs - b.startMs);
+
+  return normalizedItems
+    .map((entry, index) => scoreTwitchVodCandidate(entry.vod, {
+      ...context,
+      nextVodStartMs: normalizedItems[index + 1]?.startMs ?? null
+    }))
+    .filter(Boolean)
+    .sort((a, b) => b.score - a.score)[0] || null;
+};
+
+const valuesEqual = (left, right) => {
+  if (Array.isArray(left) || Array.isArray(right)) {
+    if (!Array.isArray(left) || !Array.isArray(right) || left.length !== right.length) return false;
+    return left.every((value, index) => valuesEqual(value, right[index]));
+  }
+  return left === right;
+};
+
+const recordHasConflictingIdentity = (record, source) => {
+  const recordStreamId = normalizeText(record?.streamId);
+  const sourceStreamId = normalizeText(source?.streamId);
+  if (recordStreamId && sourceStreamId && recordStreamId !== sourceStreamId) return true;
+  const recordVodId = normalizeText(record?.vodId) || getFirstMatchingUrlValue(record, extractTwitchVodIdFromUrl);
+  const sourceVodId = normalizeText(source?.vodId) || getFirstMatchingUrlValue(source, extractTwitchVodIdFromUrl);
+  if (recordVodId && sourceVodId && recordVodId !== sourceVodId) return true;
+  return false;
+};
+
+export const buildRecordTimeLabelVodPatchOperationId = (recordId, patch = {}) => (
+  `record.update:${normalizeId(recordId)}:vod-patch:${fingerprintCanonicalJson(patch || {})}`
+);
+
+export const buildKnownTwitchVodRecordPatches = ({
+  records = [],
+  groupIndex = null,
+  fallbackPlatform,
+  unknownTitle = DEFAULT_UNKNOWN_TITLE
+} = {}) => {
+  const safeRecords = collectNonVirtualRecords(records);
+  const index = groupIndex || buildRecordTimeLabelGroupIndex({
+    records: safeRecords,
+    fallbackPlatform,
+    unknownTitle
+  });
+  const conflictGroupIds = new Set(index.diagnostics?.conflictGroupIds || []);
+  const sourceByGroupId = {};
+
+  safeRecords.forEach((record) => {
+    if (normalizeRecordPlatform(record, fallbackPlatform) !== 'twitch' || record?.hasVod !== true) return;
+    const recordId = normalizeId(record?.id);
+    const groupId = index.groupIdByRecordId[recordId];
+    if (!groupId || conflictGroupIds.has(groupId)) return;
+    const vodId = normalizeText(record?.vodId) || getFirstMatchingUrlValue(record, extractTwitchVodIdFromUrl);
+    if (!vodId) return;
+    const current = sourceByGroupId[groupId];
+    const currentScore = current
+      ? Number(Boolean(current.vodStartAt || current.vodPublishedAt)) +
+        Number(Number.isFinite(Number(current.vodTimeOffsetSeconds)))
+      : -1;
+    const nextScore = Number(Boolean(record.vodStartAt || record.vodPublishedAt)) +
+      Number(Number.isFinite(Number(record.vodTimeOffsetSeconds)));
+    if (!current || nextScore > currentScore) sourceByGroupId[groupId] = record;
+  });
+
+  const patches = [];
+  safeRecords.forEach((record) => {
+    const recordId = normalizeId(record?.id);
+    if (!recordId || normalizeRecordPlatform(record, fallbackPlatform) !== 'twitch' || record.hasVod === true) {
+      return;
+    }
+    const groupId = index.groupIdByRecordId[recordId];
+    if (!groupId || conflictGroupIds.has(groupId)) return;
+    const source = sourceByGroupId[groupId];
+    if (!source || recordHasConflictingIdentity(record, source)) return;
+    const vodId = normalizeText(source.vodId) || getFirstMatchingUrlValue(source, extractTwitchVodIdFromUrl);
+    if (!vodId) return;
+
+    const vodStartAt = source.vodStartAt || source.vodPublishedAt || null;
+    const vodStartMs = parseUtcMillis(vodStartAt);
+    const recordCreatedAtMs = parseUtcMillis(record.createdAt);
+    const configuredOffsetSeconds = Number.isFinite(Number(record.timeOffsetSeconds))
+      ? Math.max(0, Number(record.timeOffsetSeconds))
+      : 0;
+    const timestampOffsetSeconds = vodStartMs !== null && recordCreatedAtMs !== null &&
+      recordCreatedAtMs >= vodStartMs
+      ? Math.max(0, Math.floor((recordCreatedAtMs - vodStartMs) / 1000) - configuredOffsetSeconds)
+      : null;
+    const fallbackOffsetSeconds = parseElapsedSeconds(record.liveTime || record.originalLiveTime);
+    const vodTimeOffsetSeconds = timestampOffsetSeconds ?? fallbackOffsetSeconds;
+    const sourceVideoUrl = getRecordUrls(source).find((url) => extractTwitchVodIdFromUrl(url) === vodId) ||
+      `https://www.twitch.tv/videos/${vodId}`;
+    const vodMatchedBy = Array.from(new Set([
+      ...(Array.isArray(source.vodMatchedBy) ? source.vodMatchedBy : []),
+      'sibling-record'
+    ]));
+    const candidate = {
+      hasVod: true,
+      videoUrl: sourceVideoUrl,
+      vodId,
+      vodPublishedAt: source.vodPublishedAt || vodStartAt,
+      vodStartAt,
+      vodTitle: source.vodTitle || '',
+      vodLookupVersion: 2,
+      vodMatchedBy
+    };
+    if (Number.isFinite(vodTimeOffsetSeconds)) candidate.vodTimeOffsetSeconds = vodTimeOffsetSeconds;
+    if (Number.isFinite(Number(source.vodMatchConfidence))) {
+      candidate.vodMatchConfidence = Number(source.vodMatchConfidence);
+    }
+    if (source.downloadUrl) {
+      candidate.downloadUrl = source.downloadUrl;
+      candidate.isDirectM3u8 = source.isDirectM3u8 || false;
+      candidate.m3u8Type = source.m3u8Type || null;
+    }
+
+    const patch = {};
+    Object.entries(candidate).forEach(([field, value]) => {
+      if (!valuesEqual(record[field], value)) patch[field] = value;
+    });
+    if (Object.keys(patch).length === 0) return;
+    patches.push({
+      recordId,
+      patch,
+      operationId: buildRecordTimeLabelVodPatchOperationId(recordId, patch)
+    });
+  });
+
+  return {
+    patches,
+    diagnostics: {
+      sourceGroupCount: Object.keys(sourceByGroupId).length,
+      patchCount: patches.length,
+      skippedConflictGroupCount: conflictGroupIds.size
+    }
+  };
+};

package/src/domain.js

@@ -0,0 +1,45 @@
+export const RECORD_TIMELABEL_DOMAIN_CAPABILITIES = Object.freeze([
+  'group-identity-v1',
+  'twitch-vod-matching-v1',
+  'legacy-import-v1',
+  'channel-folder-planning-v1'
+]);
+
+export {
+  RECORD_GROUP_IDENTITY_VERSION,
+  buildLegacyRecordTimeLabelGroupId,
+  buildRecordTimeLabelGroupIndex,
+  buildRecordTimeLabelGroupMetadata,
+  buildRecordTimeLabelGroupReorderOperationId,
+  buildRecordTimeLabelStandaloneGroupId,
+  canonicalizeRecordTimeLabelGroupView
+} from './domain/group-identity.js';
+
+export {
+  extractTwitchVodIdFromUrl,
+  extractYouTubeVideoIdFromUrl
+} from './domain/shared.js';
+
+export {
+  buildKnownTwitchVodRecordPatches,
+  buildRecordTimeLabelVodPatchOperationId,
+  calculateVodTitleSimilarity,
+  normalizeVodTitleForMatch,
+  scoreTwitchVodCandidate,
+  selectBestMatchingTwitchVod
+} from './domain/twitch-vod.js';
+
+export {
+  normalizeLegacyRecordTimeLabelImport,
+  remapLegacyRecordTimeLabelFolderAliases
+} from './domain/legacy.js';
+
+export {
+  buildRecordTimeLabelChannelFolderPlan,
+  collectRecordTimeLabelChannelCandidates,
+  extractChannelHandleFromUrl,
+  findBestRecordTimeLabelChannelFolder,
+  getChannelMatchKey,
+  isPendingChannelFolderId,
+  isValidChannelName
+} from './domain/channel-folder.js';

package/src/index.js

@@ -31,7 +31,63 @@ const REQUIRED_FOLDERS = [
   { id: DEFAULT_FOLDER_ID, name: 'Uncategorized' }
 ];
 
-export const RECORD_TIMELABEL_CORE_VERSION = '0.4.7';
+import {
+  RECORD_GROUP_IDENTITY_VERSION,
+  RECORD_TIMELABEL_DOMAIN_CAPABILITIES,
+  buildKnownTwitchVodRecordPatches,
+  buildLegacyRecordTimeLabelGroupId,
+  buildRecordTimeLabelChannelFolderPlan,
+  buildRecordTimeLabelGroupIndex,
+  buildRecordTimeLabelGroupMetadata,
+  buildRecordTimeLabelGroupReorderOperationId,
+  buildRecordTimeLabelStandaloneGroupId,
+  buildRecordTimeLabelVodPatchOperationId,
+  calculateVodTitleSimilarity,
+  canonicalizeRecordTimeLabelGroupView,
+  collectRecordTimeLabelChannelCandidates,
+  extractChannelHandleFromUrl,
+  extractTwitchVodIdFromUrl,
+  extractYouTubeVideoIdFromUrl,
+  findBestRecordTimeLabelChannelFolder,
+  getChannelMatchKey,
+  isPendingChannelFolderId,
+  isValidChannelName,
+  normalizeLegacyRecordTimeLabelImport,
+  normalizeVodTitleForMatch,
+  remapLegacyRecordTimeLabelFolderAliases,
+  scoreTwitchVodCandidate,
+  selectBestMatchingTwitchVod
+} from './domain.js';
+
+export {
+  RECORD_GROUP_IDENTITY_VERSION,
+  RECORD_TIMELABEL_DOMAIN_CAPABILITIES,
+  buildKnownTwitchVodRecordPatches,
+  buildLegacyRecordTimeLabelGroupId,
+  buildRecordTimeLabelChannelFolderPlan,
+  buildRecordTimeLabelGroupIndex,
+  buildRecordTimeLabelGroupMetadata,
+  buildRecordTimeLabelGroupReorderOperationId,
+  buildRecordTimeLabelStandaloneGroupId,
+  buildRecordTimeLabelVodPatchOperationId,
+  calculateVodTitleSimilarity,
+  canonicalizeRecordTimeLabelGroupView,
+  collectRecordTimeLabelChannelCandidates,
+  extractChannelHandleFromUrl,
+  extractTwitchVodIdFromUrl,
+  extractYouTubeVideoIdFromUrl,
+  findBestRecordTimeLabelChannelFolder,
+  getChannelMatchKey,
+  isPendingChannelFolderId,
+  isValidChannelName,
+  normalizeLegacyRecordTimeLabelImport,
+  normalizeVodTitleForMatch,
+  remapLegacyRecordTimeLabelFolderAliases,
+  scoreTwitchVodCandidate,
+  selectBestMatchingTwitchVod
+};
+
+export const RECORD_TIMELABEL_CORE_VERSION = '0.5.0';
 export const RTL_SYNC_PROTOCOL_VERSION = 2;
 export const RECORD_TIMELABEL_DURABLE_ENGINE_CAPABILITIES = Object.freeze([
   'fifo-retry-fence',
@@ -5289,6 +5345,8 @@ export const buildOperationsFromSnapshotDiff = ({
 
 export default {
   RECORD_TIMELABEL_CORE_VERSION,
+  RECORD_GROUP_IDENTITY_VERSION,
+  RECORD_TIMELABEL_DOMAIN_CAPABILITIES,
   RECORD_TIMELABEL_DURABLE_ENGINE_CAPABILITIES,
   RECORD_TIMELABEL_CAPABILITY_LIFECYCLE_GENERATION_FENCE,
   RECORD_TIMELABEL_CAPABILITY_OPERATION_CONFLICT_QUARANTINE,