xpt-shared-types 1.6.1 → 1.7.0

package/dist/index.d.ts

@@ -3,5 +3,6 @@ export * from './contracts';
 export * from './manual';
 export * from './bracket';
 export * from './gameCatalogue';
+export * from './stream';
 export * from './data/countriesList';
 export * from './data/gameGenres';

package/dist/index.js

@@ -25,6 +25,9 @@ __exportStar(require("./bracket"), exports);
 // Game/platform/account catalogue — the game -> platform -> account chain,
 // applied identically by the backend resolver and the client's pickers
 __exportStar(require("./gameCatalogue"), exports);
+// Stream links — one pasted URL parsed the same way by the backend that stores
+// the derived columns and the client that embeds the player
+__exportStar(require("./stream"), exports);
 // Data
 __exportStar(require("./data/countriesList"), exports);
 __exportStar(require("./data/gameGenres"), exports);

package/dist/stream.d.ts

@@ -0,0 +1,77 @@
+/**
+ * One pasted URL → the platform, the handle, and the player the live page
+ * embeds.
+ *
+ * A match carries three stream columns for one concept: `streamLink` (what the
+ * host pasted), and `streamHandle` + `streamPlatform` (what the live tile needs
+ * for a Twitch preview and what the live page needs to label a "watch on"
+ * button). The host types the link; the other two are derived here and never
+ * accepted from a client, so there is exactly one source of truth.
+ *
+ * An unrecognised host is still a valid stream link — it is filed as `other`
+ * with no handle, and the live page falls back to a "watch on" button, which
+ * already prefers `streamLink` when it is set.
+ *
+ * Lives here rather than in xpt-strapi because the client needs the identical
+ * parse: the host must be told, as they type, which platform their link
+ * resolved to and whether it will embed at all. Two implementations of the same
+ * URL grammar is two chances to disagree about what the backend just stored.
+ *
+ * `buildEmbedUrl` deliberately takes the **link**, not the stored handle. The
+ * handle is lossy: `youtube.com/@team` and `youtube.com/watch?v=abc` both
+ * flatten to one opaque string, yet one is a channel and the other is a video,
+ * and they take different embed URLs. Re-parsing the link is what lets the
+ * YouTube embed be correct at all.
+ *
+ * Pure on purpose: no Strapi, no DOM, no I/O, so the rules are unit-tested
+ * directly (see xpt-strapi `tests/unit/utils/streamLink.test.ts`).
+ */
+import type { MatchStreamPlatform } from './generated/enums';
+/** `Match.streamPlatform`. Aliased so call sites read as stream code. */
+export type StreamPlatform = MatchStreamPlatform;
+export interface StreamSource {
+    platform: StreamPlatform;
+    handle: string | null;
+}
+export declare const STREAM_LINK_MAX_LENGTH = 255;
+/** The URL parsed, or null when it is not an absolute http(s) URL. */
+export declare function parseStreamUrl(raw: string): URL | null;
+export declare function deriveStreamSource(raw: string): StreamSource | null;
+export interface StreamFields {
+    streamLink: string | null;
+    streamHandle: string | null;
+    streamPlatform: StreamPlatform | null;
+}
+/**
+ * The three stream columns for a pasted link, ready to write. Empty clears all
+ * three together — a stale handle with no link would keep a dead embed alive.
+ */
+export declare function streamFieldsFor(raw: unknown): {
+    ok: true;
+    value: StreamFields;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * The embeddable player URL for a stored stream link, or null when the link
+ * cannot be embedded and the viewer should be sent to the platform instead.
+ *
+ * `parentDomain` is Twitch's requirement: it must be the hostname of the page
+ * carrying the iframe, or Twitch refuses to play. Read it from
+ * `window.location.hostname` on the client rather than configuring it — the
+ * browser's own answer is correct by construction.
+ */
+export declare function buildEmbedUrl(streamLink: string | null | undefined, opts: {
+    parentDomain: string;
+}): string | null;
+/** The label for the button that leaves the site for the platform. */
+export declare const STREAM_PLATFORM_LABELS: Record<StreamPlatform, string>;
+/** How the platform is named in host-facing copy. */
+export declare const STREAM_PLATFORM_NAMES: Record<StreamPlatform, string>;
+/**
+ * Where "Watch on X" should point. The stored link is what the host pasted, so
+ * it wins whenever it is set; the handle is only a fallback for rows written
+ * before the link was kept.
+ */
+export declare function buildWatchUrl(streamLink: string | null | undefined, platform?: StreamPlatform | null, handle?: string | null): string | null;

package/dist/stream.js

@@ -0,0 +1,217 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STREAM_PLATFORM_NAMES = exports.STREAM_PLATFORM_LABELS = exports.STREAM_LINK_MAX_LENGTH = void 0;
+exports.parseStreamUrl = parseStreamUrl;
+exports.deriveStreamSource = deriveStreamSource;
+exports.streamFieldsFor = streamFieldsFor;
+exports.buildEmbedUrl = buildEmbedUrl;
+exports.buildWatchUrl = buildWatchUrl;
+exports.STREAM_LINK_MAX_LENGTH = 255;
+/** The URL parsed, or null when it is not an absolute http(s) URL. */
+function parseStreamUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw.trim());
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+        return null;
+    return url;
+}
+function hostOf(url) {
+    return url.hostname.toLowerCase().replace(/^www\./, '');
+}
+/** Path segments with the empties from leading and trailing slashes dropped. */
+function segmentsOf(url) {
+    return url.pathname
+        .split('/')
+        .filter(Boolean)
+        .map((segment) => decodeURIComponent(segment));
+}
+/**
+ * Twitch paths that are not a channel. A VOD or a directory page has no live
+ * preview, so it gets no handle rather than a wrong one.
+ */
+const TWITCH_NON_CHANNEL = new Set(['videos', 'directory', 'clip', 'p']);
+function deriveStreamSource(raw) {
+    var _a, _b, _c;
+    const url = parseStreamUrl(raw);
+    if (!url)
+        return null;
+    const host = hostOf(url);
+    const segments = segmentsOf(url);
+    const first = (_a = segments[0]) !== null && _a !== void 0 ? _a : null;
+    if (host === 'twitch.tv' || host.endsWith('.twitch.tv')) {
+        const handle = first && !TWITCH_NON_CHANNEL.has(first) ? first : null;
+        return { platform: 'twitch', handle };
+    }
+    if (host === 'kick.com') {
+        return { platform: 'kick', handle: first };
+    }
+    if (host === 'youtu.be') {
+        return { platform: 'youtube', handle: first };
+    }
+    if (host === 'youtube.com' || host.endsWith('.youtube.com')) {
+        // /@handle, /c/name, /channel/id and /user/name all carry the identifier
+        // the live page embeds; /watch and /live carry it one segment later or in
+        // the query instead.
+        if (first === null || first === void 0 ? void 0 : first.startsWith('@'))
+            return { platform: 'youtube', handle: first };
+        if (first === 'c' || first === 'channel' || first === 'user') {
+            return { platform: 'youtube', handle: (_b = segments[1]) !== null && _b !== void 0 ? _b : null };
+        }
+        if (first === 'watch') {
+            return { platform: 'youtube', handle: url.searchParams.get('v') };
+        }
+        if (first === 'live') {
+            return { platform: 'youtube', handle: (_c = segments[1]) !== null && _c !== void 0 ? _c : null };
+        }
+        return { platform: 'youtube', handle: first };
+    }
+    return { platform: 'other', handle: null };
+}
+/**
+ * The three stream columns for a pasted link, ready to write. Empty clears all
+ * three together — a stale handle with no link would keep a dead embed alive.
+ */
+function streamFieldsFor(raw) {
+    if (raw === null || raw === undefined || raw === '') {
+        return {
+            ok: true,
+            value: { streamLink: null, streamHandle: null, streamPlatform: null },
+        };
+    }
+    if (typeof raw !== 'string') {
+        return { ok: false, message: 'streamLink must be a string' };
+    }
+    const trimmed = raw.trim();
+    if (!trimmed) {
+        return {
+            ok: true,
+            value: { streamLink: null, streamHandle: null, streamPlatform: null },
+        };
+    }
+    if (trimmed.length > exports.STREAM_LINK_MAX_LENGTH) {
+        return {
+            ok: false,
+            message: `streamLink must be ${exports.STREAM_LINK_MAX_LENGTH} characters or fewer`,
+        };
+    }
+    const source = deriveStreamSource(trimmed);
+    if (!source) {
+        return { ok: false, message: 'streamLink must be a valid http(s) URL' };
+    }
+    return {
+        ok: true,
+        value: {
+            streamLink: trimmed,
+            streamHandle: source.handle,
+            streamPlatform: source.platform,
+        },
+    };
+}
+function youTubeRef(url) {
+    var _a, _b, _c;
+    const host = hostOf(url);
+    const segments = segmentsOf(url);
+    const first = (_a = segments[0]) !== null && _a !== void 0 ? _a : null;
+    if (host === 'youtu.be') {
+        return first ? { kind: 'video', id: first } : null;
+    }
+    if (first === 'watch') {
+        const id = url.searchParams.get('v');
+        return id ? { kind: 'video', id } : null;
+    }
+    if (first === 'live' || first === 'embed' || first === 'shorts') {
+        const id = (_b = segments[1]) !== null && _b !== void 0 ? _b : null;
+        return id ? { kind: 'video', id } : null;
+    }
+    if (first === 'channel') {
+        const id = (_c = segments[1]) !== null && _c !== void 0 ? _c : null;
+        return id ? { kind: 'channel', id } : null;
+    }
+    if ((first === null || first === void 0 ? void 0 : first.startsWith('@')) || first === 'c' || first === 'user') {
+        return { kind: 'vanity' };
+    }
+    return null;
+}
+/**
+ * The embeddable player URL for a stored stream link, or null when the link
+ * cannot be embedded and the viewer should be sent to the platform instead.
+ *
+ * `parentDomain` is Twitch's requirement: it must be the hostname of the page
+ * carrying the iframe, or Twitch refuses to play. Read it from
+ * `window.location.hostname` on the client rather than configuring it — the
+ * browser's own answer is correct by construction.
+ */
+function buildEmbedUrl(streamLink, opts) {
+    if (!streamLink)
+        return null;
+    const url = parseStreamUrl(streamLink);
+    if (!url)
+        return null;
+    const source = deriveStreamSource(streamLink);
+    if (!source)
+        return null;
+    switch (source.platform) {
+        case 'twitch':
+            if (!source.handle)
+                return null;
+            return `https://player.twitch.tv/?channel=${encodeURIComponent(source.handle)}&parent=${encodeURIComponent(opts.parentDomain)}&autoplay=false`;
+        case 'youtube': {
+            const ref = youTubeRef(url);
+            if (!ref)
+                return null;
+            if (ref.kind === 'video') {
+                return `https://www.youtube.com/embed/${encodeURIComponent(ref.id)}`;
+            }
+            if (ref.kind === 'channel') {
+                return `https://www.youtube.com/embed/live_stream?channel=${encodeURIComponent(ref.id)}`;
+            }
+            return null;
+        }
+        case 'kick':
+            if (!source.handle)
+                return null;
+            return `https://player.kick.com/${encodeURIComponent(source.handle)}`;
+        default:
+            return null;
+    }
+}
+/** The label for the button that leaves the site for the platform. */
+exports.STREAM_PLATFORM_LABELS = {
+    twitch: 'Watch on Twitch',
+    youtube: 'Watch on YouTube',
+    kick: 'Watch on Kick',
+    other: 'Watch Stream',
+};
+/** How the platform is named in host-facing copy. */
+exports.STREAM_PLATFORM_NAMES = {
+    twitch: 'Twitch',
+    youtube: 'YouTube',
+    kick: 'Kick',
+    other: 'Link',
+};
+/**
+ * Where "Watch on X" should point. The stored link is what the host pasted, so
+ * it wins whenever it is set; the handle is only a fallback for rows written
+ * before the link was kept.
+ */
+function buildWatchUrl(streamLink, platform, handle) {
+    if (streamLink)
+        return streamLink;
+    if (!handle)
+        return null;
+    switch (platform) {
+        case 'twitch':
+            return `https://twitch.tv/${handle}`;
+        case 'youtube':
+            return `https://youtube.com/${handle}`;
+        case 'kick':
+            return `https://kick.com/${handle}`;
+        default:
+            return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xpt-shared-types",
-  "version": "1.6.1",
+  "version": "1.7.0",
   "description": "Shared types and data for XPT projects",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/index.ts

@@ -14,6 +14,10 @@ export * from './bracket';
 // applied identically by the backend resolver and the client's pickers
 export * from './gameCatalogue';
 
+// Stream links — one pasted URL parsed the same way by the backend that stores
+// the derived columns and the client that embeds the player
+export * from './stream';
+
 // Data
 export * from './data/countriesList';
-export * from './data/gameGenres';
+export * from './data/gameGenres';

package/src/stream.ts

@@ -0,0 +1,289 @@
+/**
+ * One pasted URL → the platform, the handle, and the player the live page
+ * embeds.
+ *
+ * A match carries three stream columns for one concept: `streamLink` (what the
+ * host pasted), and `streamHandle` + `streamPlatform` (what the live tile needs
+ * for a Twitch preview and what the live page needs to label a "watch on"
+ * button). The host types the link; the other two are derived here and never
+ * accepted from a client, so there is exactly one source of truth.
+ *
+ * An unrecognised host is still a valid stream link — it is filed as `other`
+ * with no handle, and the live page falls back to a "watch on" button, which
+ * already prefers `streamLink` when it is set.
+ *
+ * Lives here rather than in xpt-strapi because the client needs the identical
+ * parse: the host must be told, as they type, which platform their link
+ * resolved to and whether it will embed at all. Two implementations of the same
+ * URL grammar is two chances to disagree about what the backend just stored.
+ *
+ * `buildEmbedUrl` deliberately takes the **link**, not the stored handle. The
+ * handle is lossy: `youtube.com/@team` and `youtube.com/watch?v=abc` both
+ * flatten to one opaque string, yet one is a channel and the other is a video,
+ * and they take different embed URLs. Re-parsing the link is what lets the
+ * YouTube embed be correct at all.
+ *
+ * Pure on purpose: no Strapi, no DOM, no I/O, so the rules are unit-tested
+ * directly (see xpt-strapi `tests/unit/utils/streamLink.test.ts`).
+ */
+import type { MatchStreamPlatform } from './generated/enums';
+
+/** `Match.streamPlatform`. Aliased so call sites read as stream code. */
+export type StreamPlatform = MatchStreamPlatform;
+
+export interface StreamSource {
+  platform: StreamPlatform;
+  handle: string | null;
+}
+
+export const STREAM_LINK_MAX_LENGTH = 255;
+
+/** The URL parsed, or null when it is not an absolute http(s) URL. */
+export function parseStreamUrl(raw: string): URL | null {
+  let url: URL;
+  try {
+    url = new URL(raw.trim());
+  } catch {
+    return null;
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') return null;
+  return url;
+}
+
+function hostOf(url: URL): string {
+  return url.hostname.toLowerCase().replace(/^www\./, '');
+}
+
+/** Path segments with the empties from leading and trailing slashes dropped. */
+function segmentsOf(url: URL): string[] {
+  return url.pathname
+    .split('/')
+    .filter(Boolean)
+    .map((segment) => decodeURIComponent(segment));
+}
+
+/**
+ * Twitch paths that are not a channel. A VOD or a directory page has no live
+ * preview, so it gets no handle rather than a wrong one.
+ */
+const TWITCH_NON_CHANNEL = new Set(['videos', 'directory', 'clip', 'p']);
+
+export function deriveStreamSource(raw: string): StreamSource | null {
+  const url = parseStreamUrl(raw);
+  if (!url) return null;
+
+  const host = hostOf(url);
+  const segments = segmentsOf(url);
+  const first = segments[0] ?? null;
+
+  if (host === 'twitch.tv' || host.endsWith('.twitch.tv')) {
+    const handle = first && !TWITCH_NON_CHANNEL.has(first) ? first : null;
+    return { platform: 'twitch', handle };
+  }
+
+  if (host === 'kick.com') {
+    return { platform: 'kick', handle: first };
+  }
+
+  if (host === 'youtu.be') {
+    return { platform: 'youtube', handle: first };
+  }
+
+  if (host === 'youtube.com' || host.endsWith('.youtube.com')) {
+    // /@handle, /c/name, /channel/id and /user/name all carry the identifier
+    // the live page embeds; /watch and /live carry it one segment later or in
+    // the query instead.
+    if (first?.startsWith('@')) return { platform: 'youtube', handle: first };
+    if (first === 'c' || first === 'channel' || first === 'user') {
+      return { platform: 'youtube', handle: segments[1] ?? null };
+    }
+    if (first === 'watch') {
+      return { platform: 'youtube', handle: url.searchParams.get('v') };
+    }
+    if (first === 'live') {
+      return { platform: 'youtube', handle: segments[1] ?? null };
+    }
+    return { platform: 'youtube', handle: first };
+  }
+
+  return { platform: 'other', handle: null };
+}
+
+export interface StreamFields {
+  streamLink: string | null;
+  streamHandle: string | null;
+  streamPlatform: StreamPlatform | null;
+}
+
+/**
+ * The three stream columns for a pasted link, ready to write. Empty clears all
+ * three together — a stale handle with no link would keep a dead embed alive.
+ */
+export function streamFieldsFor(
+  raw: unknown
+): { ok: true; value: StreamFields } | { ok: false; message: string } {
+  if (raw === null || raw === undefined || raw === '') {
+    return {
+      ok: true,
+      value: { streamLink: null, streamHandle: null, streamPlatform: null },
+    };
+  }
+  if (typeof raw !== 'string') {
+    return { ok: false, message: 'streamLink must be a string' };
+  }
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return {
+      ok: true,
+      value: { streamLink: null, streamHandle: null, streamPlatform: null },
+    };
+  }
+  if (trimmed.length > STREAM_LINK_MAX_LENGTH) {
+    return {
+      ok: false,
+      message: `streamLink must be ${STREAM_LINK_MAX_LENGTH} characters or fewer`,
+    };
+  }
+  const source = deriveStreamSource(trimmed);
+  if (!source) {
+    return { ok: false, message: 'streamLink must be a valid http(s) URL' };
+  }
+  return {
+    ok: true,
+    value: {
+      streamLink: trimmed,
+      streamHandle: source.handle,
+      streamPlatform: source.platform,
+    },
+  };
+}
+
+/**
+ * What kind of YouTube identifier a URL carries. A video can be embedded by id;
+ * a channel can be embedded through the `live_stream` player; a vanity handle
+ * (`/@name`, `/c/name`, `/user/name`) can be embedded by neither without a Data
+ * API lookup we do not make, so it embeds as nothing and the watch button
+ * carries the viewer instead.
+ */
+type YouTubeRef =
+  | { kind: 'video'; id: string }
+  | { kind: 'channel'; id: string }
+  | { kind: 'vanity' }
+  | null;
+
+function youTubeRef(url: URL): YouTubeRef {
+  const host = hostOf(url);
+  const segments = segmentsOf(url);
+  const first = segments[0] ?? null;
+
+  if (host === 'youtu.be') {
+    return first ? { kind: 'video', id: first } : null;
+  }
+
+  if (first === 'watch') {
+    const id = url.searchParams.get('v');
+    return id ? { kind: 'video', id } : null;
+  }
+  if (first === 'live' || first === 'embed' || first === 'shorts') {
+    const id = segments[1] ?? null;
+    return id ? { kind: 'video', id } : null;
+  }
+  if (first === 'channel') {
+    const id = segments[1] ?? null;
+    return id ? { kind: 'channel', id } : null;
+  }
+  if (first?.startsWith('@') || first === 'c' || first === 'user') {
+    return { kind: 'vanity' };
+  }
+  return null;
+}
+
+/**
+ * The embeddable player URL for a stored stream link, or null when the link
+ * cannot be embedded and the viewer should be sent to the platform instead.
+ *
+ * `parentDomain` is Twitch's requirement: it must be the hostname of the page
+ * carrying the iframe, or Twitch refuses to play. Read it from
+ * `window.location.hostname` on the client rather than configuring it — the
+ * browser's own answer is correct by construction.
+ */
+export function buildEmbedUrl(
+  streamLink: string | null | undefined,
+  opts: { parentDomain: string }
+): string | null {
+  if (!streamLink) return null;
+  const url = parseStreamUrl(streamLink);
+  if (!url) return null;
+
+  const source = deriveStreamSource(streamLink);
+  if (!source) return null;
+
+  switch (source.platform) {
+    case 'twitch':
+      if (!source.handle) return null;
+      return `https://player.twitch.tv/?channel=${encodeURIComponent(
+        source.handle
+      )}&parent=${encodeURIComponent(opts.parentDomain)}&autoplay=false`;
+
+    case 'youtube': {
+      const ref = youTubeRef(url);
+      if (!ref) return null;
+      if (ref.kind === 'video') {
+        return `https://www.youtube.com/embed/${encodeURIComponent(ref.id)}`;
+      }
+      if (ref.kind === 'channel') {
+        return `https://www.youtube.com/embed/live_stream?channel=${encodeURIComponent(
+          ref.id
+        )}`;
+      }
+      return null;
+    }
+
+    case 'kick':
+      if (!source.handle) return null;
+      return `https://player.kick.com/${encodeURIComponent(source.handle)}`;
+
+    default:
+      return null;
+  }
+}
+
+/** The label for the button that leaves the site for the platform. */
+export const STREAM_PLATFORM_LABELS: Record<StreamPlatform, string> = {
+  twitch: 'Watch on Twitch',
+  youtube: 'Watch on YouTube',
+  kick: 'Watch on Kick',
+  other: 'Watch Stream',
+};
+
+/** How the platform is named in host-facing copy. */
+export const STREAM_PLATFORM_NAMES: Record<StreamPlatform, string> = {
+  twitch: 'Twitch',
+  youtube: 'YouTube',
+  kick: 'Kick',
+  other: 'Link',
+};
+
+/**
+ * Where "Watch on X" should point. The stored link is what the host pasted, so
+ * it wins whenever it is set; the handle is only a fallback for rows written
+ * before the link was kept.
+ */
+export function buildWatchUrl(
+  streamLink: string | null | undefined,
+  platform?: StreamPlatform | null,
+  handle?: string | null
+): string | null {
+  if (streamLink) return streamLink;
+  if (!handle) return null;
+  switch (platform) {
+    case 'twitch':
+      return `https://twitch.tv/${handle}`;
+    case 'youtube':
+      return `https://youtube.com/${handle}`;
+    case 'kick':
+      return `https://kick.com/${handle}`;
+    default:
+      return null;
+  }
+}