@social-embed/lib - npm Package Compare versions

Comparing version 0.1.0-next.9 to 0.1.0-next.10

dist/index.d.ts

@@ -0,5 +1,10 @@
+import { EmbedProvider } from './provider';
+import { EmbedProviderRegistry } from './registry';
 export * from './providers';
-export { Provider } from './constants';
-export type { ProviderKey, ProviderType } from './types';
-export { ProviderIdFunctionMap, ProviderIdUrlFunctionMap, getProviderFromUrl, convertUrlToEmbedUrl, } from './utils';
+export { getProviderFromUrl, convertUrlToEmbedUrl, } from './utils';
+export declare const defaultProviders: EmbedProvider[];
+/**
+ * Create a default registry and register all built-in providers.
+ */
+export declare const defaultRegistry: EmbedProviderRegistry;
 //# sourceMappingURL=index.d.ts.map

dist/lib.js

@@ -1,117 +0,385 @@
-const S = (t) => {
+const D = (e) => {
   try {
-    return !!new URL(t);
+    return !!new URL(e);
   } catch {
     return !1;
   }
-}, d = /^(?:(?:https?):)?(?:\/\/)?(?:www\.)?(?:youtube(?:-nocookie)?.com|youtu.be)(?:\/watch\?v)?[=/]([a-zA-Z0-9_-]{11})(?:\\?|=|&|$)/, a = (t) => {
-  var o;
-  return t ? ((o = t.match(d)) == null ? void 0 : o[1]) ?? "" : "";
-}, p = (t) => `https://www.youtube.com/embed/${t}`, y = /^(?:(?:https?):)?(?:\/\/)?(?:www\.)?(?:(?:dailymotion\.com(?:\/embed)?\/video)|dai\.ly)\/([a-zA-Z0-9]+)(?:_[\w_-]+)?(?:\?playlist=[a-zA-Z0-9]+)?$/, w = (t) => {
-  var o;
-  return ((o = t.match(y)) == null ? void 0 : o[1]) ?? "";
-}, l = (t) => `https://www.dailymotion.com/embed/video/${t}`, u = /^(?:(?:https?):)?(?:\/\/)?(?:embed\.|open\.)(?:spotify\.com\/)(?:(album|track|playlist)\/|\?uri=spotify:track:)([-\w]{22})(?:\?si=[_-\w]{22})?$/, f = /spotify:(?:(album|track|playlist):|\?uri=spotify:track:)([-\w]{22})/, h = (t) => {
-  const [, o, i] = t.match(u) || t.match(f) || [];
-  return [i, o];
-}, b = (t, ...o) => `https://open.spotify.com/embed/${typeof o[0] == "string" ? o[0] : ""}/${t}`, g = /(?:(?:https?):)?(?:\/\/)?(?:www\.|player\.)?vimeo\.com\/(?:channels\/(?:\w+\/)?|groups\/(?:[^/]*)\/videos\/|video\/|)(\d+)(?:|\/\?)/, U = (t) => {
-  var o;
-  return ((o = t.match(g)) == null ? void 0 : o[1]) ?? "";
-}, z = (t) => `https://player.vimeo.com/video/${t}`, E = /^(?:(?:https?):)?(?:\/\/)?(?:www\.)?edpuzzle.com[=/]media\/([-\w]+)/, I = (t) => {
-  var o;
-  if (t) {
-    if ((t == null ? void 0 : t.length) > 1e3)
+}, s = /^(?:(?:https?):)?(?:\/\/)?(?:www\.)?(?:youtube(?:-nocookie)?.com|youtu.be)(?:\/watch\?v)?[=/]([a-zA-Z0-9_-]{11})(?:\\?|=|&|$)/, U = (e) => {
+  var r;
+  return e ? ((r = e.match(s)) == null ? void 0 : r[1]) ?? "" : "";
+}, w = (e) => `https://www.youtube.com/embed/${e}`, f = {
+  /** @inheritdoc */
+  name: "YouTube",
+  /**
+   * Determines if a given URL is recognized as a YouTube link.
+   *
+   * @param url - The string to evaluate.
+   * @returns `true` if the URL matches YouTube patterns; otherwise `false`.
+   */
+  canParseUrl(e) {
+    return s.test(e);
+  },
+  /**
+   * Extracts the 11-char YouTube ID from a recognized YouTube URL.
+   *
+   * @param url - The potential YouTube link.
+   * @returns The extracted video ID or an empty string if none found.
+   */
+  getIdFromUrl(e) {
+    return U(e);
+  },
+  /**
+   * Builds a full YouTube embed URL (e.g. `https://www.youtube.com/embed/<id>`).
+   *
+   * @param id - The 11-char YouTube video ID.
+   * @returns A fully embeddable `<iframe>` URL for YouTube.
+   */
+  getEmbedUrlFromId(e) {
+    return w(e);
+  }
+}, i = /^(?:(?:https?):)?(?:\/\/)?(?:www\.)?(?:(?:dailymotion\.com(?:\/embed)?\/video)|dai\.ly)\/([a-zA-Z0-9]+)(?:_[\w_-]+)?(?:\?playlist=[a-zA-Z0-9]+)?$/, y = (e) => {
+  var r;
+  return ((r = e.match(i)) == null ? void 0 : r[1]) ?? "";
+}, h = (e) => `https://www.dailymotion.com/embed/video/${e}`, b = {
+  /** @inheritdoc */
+  name: "DailyMotion",
+  /**
+   * Checks whether a given URL matches the DailyMotion pattern.
+   *
+   * @param url - The URL to test for DailyMotion compatibility.
+   * @returns `true` if the URL belongs to DailyMotion, otherwise `false`.
+   */
+  canParseUrl(e) {
+    return i.test(e);
+  },
+  /**
+   * Extracts the ID from a recognized DailyMotion URL.
+   *
+   * @param url - The DailyMotion URL string.
+   * @returns The video ID found in the URL.
+   */
+  getIdFromUrl(e) {
+    return y(e);
+  },
+  /**
+   * Builds an embed URL for a given DailyMotion ID.
+   *
+   * @param id - The DailyMotion video ID.
+   * @returns A fully embeddable iframe URL for DailyMotion.
+   */
+  getEmbedUrlFromId(e) {
+    return h(e);
+  }
+}, n = [
+  "track",
+  "album",
+  "playlist",
+  "artist",
+  "show",
+  "episode"
+], d = new RegExp(
+  `^(?:(?:https?):)?(?:\\/\\/)?(?:embed\\.|open\\.)?spotify\\.com\\/(?:(${n.join(
+    "|"
+  )})\\/)([-\\w]{22})(?:\\?si=[_\\-\\w]{22})?`
+), m = new RegExp(
+  `^spotify:(?:(${n.join("|")}):)([-\\w]{22})`
+);
+function v(e) {
+  const r = e.match(d) || e.match(m);
+  if (!r)
+    return ["", ""];
+  const t = r[1] ?? "";
+  return [r[2] ?? "", t];
+}
+function I(e, ...r) {
+  const t = typeof r[0] == "string" ? r[0] : "";
+  return `https://open.spotify.com/embed/${n.includes(t) ? t : "track"}/${e}`;
+}
+const F = {
+  /** @inheritdoc */
+  name: "Spotify",
+  /**
+   * Determines if the given URL or URI matches a recognized Spotify pattern.
+   *
+   * @param url - A string that could point to a Spotify resource.
+   * @returns `true` if the pattern matches, otherwise `false`.
+   */
+  canParseUrl(e) {
+    return d.test(e) || m.test(e);
+  },
+  /**
+   * Extracts the ID and type from a recognized Spotify URL or `spotify:` URI.
+   *
+   * @param url - The Spotify link.
+   * @returns `[id, type]` if matched, otherwise `["", ""]`.
+   */
+  getIdFromUrl(e) {
+    return v(e);
+  },
+  /**
+   * Builds an embeddable Spotify URL from an ID plus optional arguments (e.g. type).
+   *
+   * @param id - The 22-char Spotify ID.
+   * @param args - The first arg may be the content type (`track`, `album`, `playlist`, etc.).
+   * @returns The final embed URL, e.g. `"https://open.spotify.com/embed/track/<id>"`.
+   */
+  getEmbedUrlFromId(e, ...r) {
+    return I(e, ...r);
+  }
+}, c = /(?:(?:https?):)?(?:\/\/)?(?:www\.|player\.)?vimeo\.com\/(?:channels\/(?:\w+\/)?|groups\/(?:[^/]*)\/videos\/|video\/|)(\d+)(?:|\/\?)/, P = (e) => {
+  var r;
+  return ((r = e.match(c)) == null ? void 0 : r[1]) ?? "";
+}, E = (e) => `https://player.vimeo.com/video/${e}`, z = {
+  /** @inheritdoc */
+  name: "Vimeo",
+  /**
+   * Determines if the given URL matches the Vimeo pattern.
+   *
+   * @param url - The URL string to test.
+   * @returns `true` if the URL is recognized as Vimeo; otherwise `false`.
+   */
+  canParseUrl(e) {
+    return c.test(e);
+  },
+  /**
+   * Extracts the Vimeo video ID from a recognized URL.
+   *
+   * @param url - The Vimeo URL.
+   * @returns The numeric video ID.
+   */
+  getIdFromUrl(e) {
+    return P(e);
+  },
+  /**
+   * Builds an embeddable Vimeo URL from a numeric video ID.
+   *
+   * @param id - The numeric Vimeo ID.
+   * @returns A fully embeddable URL for use in `<iframe src="...">`.
+   */
+  getEmbedUrlFromId(e) {
+    return E(e);
+  }
+}, a = /^(?:(?:https?):)?(?:\/\/)?(?:www\.)?edpuzzle.com[=/]media\/([-\w]+)/, R = (e) => {
+  var r;
+  if (e) {
+    if ((e == null ? void 0 : e.length) > 1e3)
       throw new Error("URL too long");
-    return ((o = t.match(E)) == null ? void 0 : o[1]) ?? "";
+    return ((r = e.match(a)) == null ? void 0 : r[1]) ?? "";
   }
   return "";
-}, F = (t) => `https://edpuzzle.com/embed/media/${t}`, T = /^(?:(?:https?):)?(?:\/\/)?(?:www|fast|support\.)?(?:wistia.com|wi.st)[=/](?:medias|embed)\/([-\w]+)/, s = (t) => {
-  var o;
-  if (t) {
-    if ((t == null ? void 0 : t.length) > 1e3)
+}, T = (e) => `https://edpuzzle.com/embed/media/${e}`, $ = {
+  /** @inheritdoc */
+  name: "EdPuzzle",
+  /**
+   * Checks if the given URL belongs to EdPuzzle.
+   *
+   * @param url - A string potentially matching EdPuzzle.
+   * @returns `true` if EdPuzzle is recognized; otherwise `false`.
+   */
+  canParseUrl(e) {
+    return a.test(e);
+  },
+  /**
+   * Extracts the EdPuzzle ID from the recognized EdPuzzle URL.
+   *
+   * @param url - The EdPuzzle media URL.
+   * @returns The extracted EdPuzzle ID.
+   */
+  getIdFromUrl(e) {
+    return R(e);
+  },
+  /**
+   * Builds an embeddable EdPuzzle URL from the given media ID.
+   *
+   * @param id - The EdPuzzle media ID.
+   * @returns A full embed URL (e.g. `https://edpuzzle.com/embed/media/<id>`).
+   */
+  getEmbedUrlFromId(e) {
+    return T(e);
+  }
+}, l = /^(?:(?:https?):)?(?:\/\/)?(?:www|fast|support\.)?(?:wistia.com|wi.st)[=/](?:medias|embed)\/([-\w]+)/, x = (e) => {
+  var r;
+  if (e) {
+    if (e.length > 1e3)
       throw new Error("URL too long");
-    return ((o = t.match(T)) == null ? void 0 : o[1]) ?? "";
+    return ((r = e.match(l)) == null ? void 0 : r[1]) ?? "";
   }
   return "";
-}, v = (t) => `https://fast.wistia.net/embed/iframe/${t}`, R = /^(?:(?:https?):)?(?:\/\/)?(?:www\.)?loom.com[=/]share\/([-\w]+)/, c = (t) => {
-  var o;
-  if (t) {
-    if ((t == null ? void 0 : t.length) > 1e3)
+}, A = (e) => `https://fast.wistia.net/embed/iframe/${e}`, L = {
+  /** @inheritdoc */
+  name: "Wistia",
+  /**
+   * Checks if a URL is recognized as a Wistia link by testing the pattern {@link wistiaUrlRegex}.
+   *
+   * @param url - The string to test.
+   * @returns `true` if it matches Wistia patterns, otherwise `false`.
+   */
+  canParseUrl(e) {
+    return l.test(e);
+  },
+  /**
+   * Extracts the Wistia media ID from a recognized Wistia URL.
+   *
+   * @param url - The shared Wistia link.
+   * @returns The extracted Wistia ID (e.g. `"26sk4lmiix"`).
+   */
+  getIdFromUrl(e) {
+    return x(e);
+  },
+  /**
+   * Constructs a Wistia embed URL given a media ID.
+   *
+   * @param id - The Wistia media ID.
+   * @returns An `<iframe>`-friendly URL (e.g. `https://fast.wistia.net/embed/iframe/<id>`).
+   */
+  getEmbedUrlFromId(e) {
+    return A(e);
+  }
+}, u = /^(?:(?:https?):)?(?:\/\/)?(?:www\.)?loom.com[=/]share\/([-\w]+)/, S = (e) => {
+  var r;
+  if (e) {
+    if (e.length > 1e3)
       throw new Error("URL too long");
-    return ((o = t.match(R)) == null ? void 0 : o[1]) ?? "";
+    return ((r = e.match(u)) == null ? void 0 : r[1]) ?? "";
   }
   return "";
-}, L = (t) => `https://www.loom.com/embed/${t}`;
-var e = /* @__PURE__ */ ((t) => (t.YouTube = "YouTube", t.Spotify = "Spotify", t.Vimeo = "Vimeo", t.DailyMotion = "DailyMotion", t.EdPuzzle = "EdPuzzle", t.Loom = "Loom", t.Wistia = "Wistia", t))(e || {});
-const $ = (t) => {
-  if (t) {
-    if (t.match(/dailymotion/))
-      return e.DailyMotion;
-    if (t.match(/spotify/))
-      return e.Spotify;
-    if (t.match(/vimeo/))
-      return e.Vimeo;
-    if (t.match(/youtu\.?be/))
-      return e.YouTube;
-    if (t.match(/edpuzzle.com/))
-      return e.EdPuzzle;
-    if (s(t))
-      return e.Wistia;
-    if (c(t))
-      return e.Loom;
+}, M = (e) => `https://www.loom.com/embed/${e}`, Y = {
+  /** @inheritdoc */
+  name: "Loom",
+  /**
+   * Returns `true` if the provided URL matches the Loom share pattern.
+   *
+   * @param url - The URL to test for Loom compatibility.
+   * @returns `true` if Loom recognized; otherwise `false`.
+   */
+  canParseUrl(e) {
+    return u.test(e);
+  },
+  /**
+   * Extracts the Loom video ID from a recognized Loom URL.
+   *
+   * @param url - The shared Loom link.
+   * @returns The parsed Loom video ID.
+   */
+  getIdFromUrl(e) {
+    return S(e);
+  },
+  /**
+   * Builds an embeddable Loom URL from a given Loom video ID.
+   *
+   * @param id - The Loom ID (e.g. `"e883f70b219a49f6ba7fbeac71a72604"`).
+   * @returns The final embed URL (e.g. `https://www.loom.com/embed/<id>`).
+   */
+  getEmbedUrlFromId(e) {
+    return M(e);
   }
-}, M = {
-  [e.DailyMotion]: w,
-  [e.Spotify]: h,
-  [e.Vimeo]: U,
-  [e.YouTube]: a,
-  [e.EdPuzzle]: I,
-  [e.Loom]: c,
-  [e.Wistia]: s
-}, x = {
-  [e.DailyMotion]: l,
-  [e.Spotify]: b,
-  [e.Vimeo]: z,
-  [e.YouTube]: p,
-  [e.EdPuzzle]: F,
-  [e.Loom]: L,
-  [e.Wistia]: v
-}, V = (t) => {
-  const o = $(t);
-  if (!o) return "";
-  const i = M[o], n = x[o], r = i(t);
-  if (Array.isArray(r)) {
-    const m = r.shift();
-    return m ? n(m, ...r) : "";
+};
+function V(e) {
+  if (e)
+    return p.findProviderByUrl(e);
+}
+function W(e) {
+  const r = V(e);
+  if (!r) return "";
+  const t = r.getIdFromUrl(e);
+  if (Array.isArray(t)) {
+    const [o, ...g] = t;
+    return o ? r.getEmbedUrlFromId(o, ...g) : "";
   }
-  return n(r);
-};
+  return r.getEmbedUrlFromId(t);
+}
+class _ {
+  /**
+   * Creates an instance of {@link EmbedProviderRegistry}.
+   */
+  constructor() {
+    this.providers = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Registers a provider.
+   *
+   * @remarks
+   * If a provider with the same name is already present, it will be overwritten.
+   *
+   * @param provider - The {@link EmbedProvider} instance to register.
+   */
+  register(r) {
+    this.providers.set(r.name, r);
+  }
+  /**
+   * Lists all registered providers.
+   *
+   * @returns An array of all currently registered {@link EmbedProvider} instances.
+   */
+  listProviders() {
+    return Array.from(this.providers.values());
+  }
+  /**
+   * Retrieves a provider by name.
+   *
+   * @param name - A provider’s `name` property.
+   * @returns The matching {@link EmbedProvider}, or `undefined` if not found.
+   */
+  getProviderByName(r) {
+    return this.providers.get(r);
+  }
+  /**
+   * Finds the first provider that can parse the given URL.
+   *
+   * @param url - The URL to analyze.
+   * @returns The matching {@link EmbedProvider}, or `undefined` if no provider recognizes it.
+   */
+  findProviderByUrl(r) {
+    for (const t of this.providers.values())
+      if (t.canParseUrl(r))
+        return t;
+  }
+}
+const B = [
+  b,
+  $,
+  Y,
+  F,
+  z,
+  L,
+  f
+], p = new _();
+for (const e of B)
+  p.register(e);
 export {
-  e as Provider,
-  M as ProviderIdFunctionMap,
-  x as ProviderIdUrlFunctionMap,
-  V as convertUrlToEmbedUrl,
-  y as dailyMotionUrlRegex,
-  E as edPuzzleUrlRegex,
-  l as getDailyMotionEmbedFromId,
-  w as getDailyMotionIdFromUrl,
-  F as getEdPuzzleEmbedUrlFromId,
-  I as getEdPuzzleIdFromUrl,
-  L as getLoomEmbedUrlFromId,
-  c as getLoomIdFromUrl,
-  $ as getProviderFromUrl,
-  b as getSpotifyEmbedUrlFromIdAndType,
-  h as getSpotifyIdAndTypeFromUrl,
-  z as getVimeoEmbedUrlFromId,
-  U as getVimeoIdFromUrl,
-  v as getWistiaEmbedUrlFromId,
-  s as getWistiaIdFromUrl,
-  p as getYouTubeEmbedUrlFromId,
-  a as getYouTubeIdFromUrl,
-  S as isValidUrl,
-  R as loomUrlRegex,
-  f as spotifySymbolRegex,
-  u as spotifyUrlRegex,
-  g as vimeoUrlRegex,
-  T as wistiaUrlRegex,
-  d as youTubeUrlRegex
+  b as DailyMotionProvider,
+  $ as EdPuzzleProvider,
+  Y as LoomProvider,
+  n as SPOTIFY_TYPES,
+  F as SpotifyProvider,
+  z as VimeoProvider,
+  L as WistiaProvider,
+  f as YouTubeProvider,
+  W as convertUrlToEmbedUrl,
+  i as dailyMotionUrlRegex,
+  B as defaultProviders,
+  p as defaultRegistry,
+  a as edPuzzleUrlRegex,
+  h as getDailyMotionEmbedFromId,
+  y as getDailyMotionIdFromUrl,
+  T as getEdPuzzleEmbedUrlFromId,
+  R as getEdPuzzleIdFromUrl,
+  M as getLoomEmbedUrlFromId,
+  S as getLoomIdFromUrl,
+  V as getProviderFromUrl,
+  I as getSpotifyEmbedUrlFromIdAndType,
+  v as getSpotifyIdAndTypeFromUrl,
+  E as getVimeoEmbedUrlFromId,
+  P as getVimeoIdFromUrl,
+  A as getWistiaEmbedUrlFromId,
+  x as getWistiaIdFromUrl,
+  w as getYouTubeEmbedUrlFromId,
+  U as getYouTubeIdFromUrl,
+  D as isValidUrl,
+  u as loomUrlRegex,
+  m as spotifySymbolRegex,
+  d as spotifyUrlRegex,
+  c as vimeoUrlRegex,
+  l as wistiaUrlRegex,
+  s as youTubeUrlRegex
 };

dist/providers/dailymotion.d.ts

@@ -0,4 +1,53 @@
+import { EmbedProvider } from '../provider';
+/**
+ * A regular expression for matching DailyMotion video links.
+ *
+ * @remarks
+ * This pattern handles optional protocols (`http`/`https`), optional `www.`, and
+ * either `dailymotion.com/video/` (which may also have `/embed` in it) or `dai.ly/`.
+ * It also supports an optional `?playlist=<id>` segment.
+ *
+ * **Credit**: [Stack Overflow](https://stackoverflow.com/a/50644701) (2021-03-14: Support `?playlist`)
+ *
+ * @example
+ * ```
+ * // Matches e.g. "https://www.dailymotion.com/video/x7znrd0"
+ * // Also matches "dailymotion.com/embed/video/x7znrd0"
+ * ```
+ */
 export declare const dailyMotionUrlRegex: RegExp;
+/**
+ * Extracts a DailyMotion video ID from a given URL string.
+ *
+ * @param url - The URL that may match DailyMotion patterns.
+ * @returns The extracted DailyMotion video ID, or an empty string if none found.
+ *
+ * @example
+ * ```ts
+ * const dmId = getDailyMotionIdFromUrl("https://www.dailymotion.com/video/x7znrd0");
+ * console.log(dmId); // "x7znrd0"
+ * ```
+ */
 export declare const getDailyMotionIdFromUrl: (url: string) => string;
+/**
+ * Constructs an embeddable DailyMotion URL from the given ID.
+ *
+ * @param id - The DailyMotion video ID.
+ * @returns A URL suitable for embedding in an `<iframe>`.
+ *
+ * @example
+ * ```ts
+ * console.log(getDailyMotionEmbedFromId("x7znrd0"));
+ * // "https://www.dailymotion.com/embed/video/x7znrd0"
+ * ```
+ */
 export declare const getDailyMotionEmbedFromId: (id: string) => string;
+/**
+ * A provider implementation for detecting and building embed URLs for DailyMotion videos.
+ *
+ * @remarks
+ * This object satisfies the {@link EmbedProvider} interface, allowing usage in a registry or
+ * with `convertUrlToEmbedUrl()`.
+ */
+export declare const DailyMotionProvider: EmbedProvider;
 //# sourceMappingURL=dailymotion.d.ts.map

dist/providers/edpuzzle.d.ts

@@ -0,3 +1,4 @@
+import { EmbedProvider } from '../provider';
 /**
- * Detection and parsing for Edpuzzle URLs
+ * Detection and parsing for Edpuzzle URLs.
  *
@@ -9,17 +10,45 @@ * [Edpuzzle's official embed docs](https://support.edpuzzle.com/hc/en-us/articles/360007260632-Can-I-embed-an-assignment-into-an-LMS-blog-or-website-)
 /**
- * Matches ID from URLs matching: https://edpuzzle.com/media/606b413369971e424ec6021e
+ * A regex pattern that matches an Edpuzzle media ID from a URL.
+ *
+ * @remarks
+ * Matches IDs from URLs like:
+ * `https://edpuzzle.com/media/606b413369971e424ec6021e`
+ * `https://www.edpuzzle.com/media/606b413369971e424ec6021e`
  */
 export declare const edPuzzleUrlRegex: RegExp;
 /**
- * Return ID from shared link.
+ * Returns the EdPuzzle media ID from a given URL string.
  *
- * @param url  Shared URL link.
+ * @param url - The shared EdPuzzle URL link (can be `undefined`).
+ * @returns The extracted EdPuzzle ID if found, or an empty string otherwise.
+ * @throws If `url` length exceeds 1000 characters (for security/performance reasons).
+ *
+ * @example
+ * ```ts
+ * const id = getEdPuzzleIdFromUrl("https://edpuzzle.com/media/606b413369971e424ec6021e");
+ * console.log(id); // "606b413369971e424ec6021e"
+ * ```
  */
 export declare const getEdPuzzleIdFromUrl: (url: string | undefined) => string;
 /**
- * Return embed-friendly URL from ID.
+ * Constructs a standard EdPuzzle embed URL from a given EdPuzzle media ID.
  *
- * @param edPuzzleId ID of embed
+ * @param edPuzzleId - The EdPuzzle ID to embed.
+ * @returns An embeddable URL: `https://edpuzzle.com/embed/media/<edPuzzleId>`
+ *
+ * @example
+ * ```ts
+ * console.log(getEdPuzzleEmbedUrlFromId("606b413369971e424ec6021e"));
+ * // "https://edpuzzle.com/embed/media/606b413369971e424ec6021e"
+ * ```
  */
 export declare const getEdPuzzleEmbedUrlFromId: (id: string) => string;
+/**
+ * A provider implementation for EdPuzzle, following the {@link EmbedProvider} interface.
+ *
+ * @remarks
+ * It exports `canParseUrl`, `getIdFromUrl`, and `getEmbedUrlFromId` for
+ * EdPuzzle-based media. Useful with `convertUrlToEmbedUrl` or custom logic.
+ */
+export declare const EdPuzzleProvider: EmbedProvider;
 //# sourceMappingURL=edpuzzle.d.ts.map

dist/providers/loom.d.ts

@@ -0,1 +1,2 @@
+import { EmbedProvider } from '../provider';
 /**
@@ -9,17 +10,51 @@ * Detecting and parsing for Loom URLs.
 /**
- * Matches ID from URLs matching: https://www.loom.com/share/e883f70b219a49f6ba7fbeac71a72604
+ * Matches an ID from Loom URLs that look like:
+ * `https://www.loom.com/share/e883f70b219a49f6ba7fbeac71a72604`
+ *
+ * @remarks
+ * This pattern allows for:
+ * - Optional protocol (e.g. `https://`)
+ * - Optional `www.`
+ * - `loom.com/share/`
+ * - A capture group of letters, digits, dashes, or underscores.
+ *
+ * @example
+ * ```ts
+ * // Matches:
+ * //   https://loom.com/share/e883f70b219a49f6ba7fbeac71a72604
+ * //   https://www.loom.com/share/e883f70b219a49f6ba7fbeac71a72604
+ * ```
  */
 export declare const loomUrlRegex: RegExp;
 /**
- * Return ID from shared link.
+ * Returns the Loom video ID from a shared link.
  *
- * @param url  Shared URL link.
+ * @param url - A Loom share URL (or `undefined`).
+ * @returns The extracted Loom video ID if found, otherwise an empty string.
+ * @throws If `url` length exceeds 1000 characters (a safety guard).
+ *
+ * @example
+ * ```ts
+ * const loomId = getLoomIdFromUrl("loom.com/share/e883f70b219a49f6ba7fbeac71a72604");
+ * console.log(loomId); // "e883f70b219a49f6ba7fbeac71a72604"
+ * ```
  */
 export declare const getLoomIdFromUrl: (url: string | undefined) => string;
 /**
- * Return embed-friendly URL from ID.
+ * Constructs an embeddable Loom URL from a Loom video ID.
  *
- * @param loomId ID of embed
+ * @param loomId - The Loom video ID to embed.
+ * @returns A URL suitable for use in an `<iframe src="...">`.
+ *
+ * @example
+ * ```ts
+ * console.log(getLoomEmbedUrlFromId("e883f70b219a49f6ba7fbeac71a72604"));
+ * // "https://www.loom.com/embed/e883f70b219a49f6ba7fbeac71a72604"
+ * ```
  */
 export declare const getLoomEmbedUrlFromId: (id: string) => string;
+/**
+ * A provider implementation for Loom, adhering to the {@link EmbedProvider} interface.
+ */
+export declare const LoomProvider: EmbedProvider;
 //# sourceMappingURL=loom.d.ts.map

dist/providers/spotify.d.ts

@@ -0,5 +1,97 @@
+import { EmbedProvider } from '../provider';
+/**
+ * A list of supported Spotify content types recognized by the library:
+ * - track
+ * - album
+ * - playlist
+ * - artist
+ * - show (podcast)
+ * - episode (podcast episode)
+ *
+ * @remarks
+ * These values are used to parse and build embeddable Spotify URLs for each specific content type.
+ */
+export declare const SPOTIFY_TYPES: readonly ["track", "album", "playlist", "artist", "show", "episode"];
+/**
+ * A regex that matches open or embed-style Spotify URLs.
+ *
+ * @example
+ * - `https://open.spotify.com/track/1w4etUoKfql47wtTFq031f`
+ * - `https://open.spotify.com/album/1DFixLWuPkv3KT3TnV35m3`
+ * - `https://open.spotify.com/show/5YEXv3C5fnMA3lFzNim4Ya`
+ * - `https://open.spotify.com/embed/episode/4XplJhQEj1Qp6QzrbA5sYk`
+ *
+ * @remarks
+ * - Derived from [a gist by TrevorJTClarke](https://gist.github.com/TrevorJTClarke/a14c37db3c11ee23a700).
+ *   Thank you, **@TrevorJTClarke**!
+ *
+ * **Pattern Explanation**:
+ * 1. Optional protocol (`https?`)
+ * 2. Optional `embed.` or `open.` subdomain
+ * 3. Must have `"spotify.com/"`
+ * 4. Captures one of the recognized `SPOTIFY_TYPES`
+ * 5. Followed by a 22-character ID
+ * 6. Optionally captures a `?si=` param
+ */
 export declare const spotifyUrlRegex: RegExp;
+/**
+ * A regex that matches Spotify URIs, such as:
+ * - `spotify:track:1w4etUoKfql47wtTFq031f`
+ * - `spotify:album:1DFixLWuPkv3KT3TnV35m3`
+ * - `spotify:artist:1Xyo4u8uXC1ZmMpatF05PJ`
+ * - `spotify:show:5YEXv3C5fnMA3lFzNim4Ya`
+ * - `spotify:episode:4XplJhQEj1Qp6QzrbA5sYk`
+ *
+ * @remarks
+ * Captures both the content type and the 22-character ID.
+ */
 export declare const spotifySymbolRegex: RegExp;
-export declare const getSpotifyIdAndTypeFromUrl: (url: string) => [string, string];
-export declare const getSpotifyEmbedUrlFromIdAndType: (id: string, ...args: unknown[]) => string;
+/**
+ * Extracts the Spotify ID and type from a given Spotify URL or URI.
+ *
+ * @param url - A Spotify web URL or `spotify:` URI.
+ * @returns A tuple `[id, type]`, where `id` is the 22-char ID and `type` is one of `track`, `album`, `playlist`, `artist`, `show`, or `episode`.
+ * @example
+ * ```ts
+ * // For "https://open.spotify.com/track/1w4etUoKfql47wtTFq031f"
+ * // => ["1w4etUoKfql47wtTFq031f", "track"]
+ *
+ * // For "spotify:album:1DFixLWuPkv3KT3TnV35m3"
+ * // => ["1DFixLWuPkv3KT3TnV35m3", "album"]
+ * ```
+ *
+ * @remarks
+ * Returns `["", ""]` if there's no valid match.
+ */
+export declare function getSpotifyIdAndTypeFromUrl(url: string): [string, string];
+/**
+ * Constructs an embeddable Spotify URL from an ID and optional content type.
+ *
+ * @param id - The 22-character Spotify ID (e.g. track/album/playlist ID).
+ * @param args - The first element in `args` may be the content type. If not provided or invalid, defaults to `"track"`.
+ * @returns A valid embed URL, e.g. `"https://open.spotify.com/embed/track/12345"`.
+ *
+ * @remarks
+ * - If a recognized `SpotifyType` isn't passed, defaults to `track`.
+ * - The function is often used inside the {@link SpotifyProvider}.
+ *
+ * @example
+ * ```ts
+ * // Normally you'd pass [id, type] as args:
+ * console.log(getSpotifyEmbedUrlFromIdAndType("7ouMYWpwJ422jRcDASZB7P", "track"));
+ * // => "https://open.spotify.com/embed/track/7ouMYWpwJ422jRcDASZB7P"
+ * ```
+ */
+export declare function getSpotifyEmbedUrlFromIdAndType(id: string, ...args: unknown[]): string;
+/**
+ * A provider object implementing the {@link EmbedProvider} interface for Spotify.
+ *
+ * @remarks
+ * - `canParseUrl()` checks both web and `spotify:` URIs.
+ * - `getIdFromUrl()` returns `[id, type]`.
+ * - `getEmbedUrlFromId()` calls {@link getSpotifyEmbedUrlFromIdAndType}.
+ *
+ * This provider allows handling any recognized Spotify media (tracks, albums, playlists, artists, shows, episodes).
+ */
+export declare const SpotifyProvider: EmbedProvider;
 //# sourceMappingURL=spotify.d.ts.map

dist/providers/vimeo.d.ts

@@ -0,4 +1,49 @@
+import { EmbedProvider } from '../provider';
+/**
+ * A regex pattern that matches Vimeo video URLs.
+ *
+ * @remarks
+ * Credit: [Stack Overflow](https://stackoverflow.com/a/50777192) (2021-03-14: modified / fixed to ignore unused groups).
+ * This pattern handles optional protocols (`https?://`), optional subdomains (`www.`, `player.`), and various Vimeo URL structures:
+ * - `vimeo.com/channels/…`
+ * - `vimeo.com/groups/…/videos/…`
+ * - `vimeo.com/video/…`
+ * - `vimeo.com/…`
+ */
 export declare const vimeoUrlRegex: RegExp;
+/**
+ * Extracts the numeric Vimeo video ID from a given URL.
+ *
+ * @param url - The Vimeo URL string.
+ * @returns The extracted numeric ID, or an empty string if no match is found.
+ *
+ * @example
+ * ```ts
+ * const vimeoId = getVimeoIdFromUrl("https://vimeo.com/channels/staffpicks/134668506");
+ * console.log(vimeoId); // "134668506"
+ * ```
+ */
 export declare const getVimeoIdFromUrl: (url: string) => string;
+/**
+ * Constructs an embeddable Vimeo URL from the given numeric video ID.
+ *
+ * @param id - The numeric Vimeo ID.
+ * @returns A URL suitable for embedding in an `<iframe>`.
+ *
+ * @example
+ * ```ts
+ * const embedUrl = getVimeoEmbedUrlFromId("134668506");
+ * console.log(embedUrl); // "https://player.vimeo.com/video/134668506"
+ * ```
+ */
 export declare const getVimeoEmbedUrlFromId: (id: string) => string;
+/**
+ * A provider implementation for Vimeo, conforming to the {@link EmbedProvider} interface.
+ *
+ * @remarks
+ * - `canParseUrl()` uses {@link vimeoUrlRegex} to detect Vimeo URLs.
+ * - `getIdFromUrl()` extracts the numeric ID from recognized Vimeo links.
+ * - `getEmbedUrlFromId()` builds an embeddable `<iframe>` URL for Vimeo.
+ */
+export declare const VimeoProvider: EmbedProvider;
 //# sourceMappingURL=vimeo.d.ts.map

dist/providers/wistia.d.ts

@@ -0,1 +1,2 @@
+import { EmbedProvider } from '../provider';
 /**
@@ -10,23 +11,45 @@ * Detecting and parsing for Wistia URLs.
 /**
- * Matches ID from URLs matching:
- * - https://support.wistia.com/medias/26sk4lmiix
- * - https://support.wistia.com/embed/26sk4lmiix
+ * Regex pattern to match Wistia media IDs from URL formats such as:
  *
- * While these are not used, these are mentions on [Wistia's embed construction](https://wistia.com/support/developers/construct-an-embed-code) docs:
- * - https://support.wi.st/embed/26sk4lmiix
- * - https://support.wi.st/medias/26sk4lmiix
+ * - `https://support.wistia.com/medias/26sk4lmiix`
+ * - `https://support.wistia.com/embed/26sk4lmiix`
+ *
+ * @remarks
+ * While the library doesn’t explicitly handle them, [Wistia's embed docs](https://wistia.com/support/developers/construct-an-embed-code)
+ * also mention variants like:
+ * - `https://support.wi.st/embed/26sk4lmiix`
+ * - `https://support.wi.st/medias/26sk4lmiix`
  */
 export declare const wistiaUrlRegex: RegExp;
 /**
- * Return ID from shared link.
+ * Extracts the Wistia media ID from a given URL string.
  *
- * @param url  Shared URL link.
+ * @param url - The shared Wistia link (can be `undefined`).
+ * @returns The extracted Wistia media ID, or an empty string if none found.
+ * @throws If `url` length is >1000 (a safeguard).
+ *
+ * @example
+ * ```ts
+ * const wistiaId = getWistiaIdFromUrl("https://support.wistia.com/medias/26sk4lmiix");
+ * console.log(wistiaId); // "26sk4lmiix"
+ * ```
  */
 export declare const getWistiaIdFromUrl: (url: string | undefined) => string;
 /**
- * Return embed-friendly URL from ID.
+ * Constructs a Wistia embed URL from a media ID.
  *
- * @param wistiaId ID of embed
+ * @param wistiaId - The Wistia ID.
+ * @returns A URL suitable for embedding in an `<iframe>`.
+ *
+ * @example
+ * ```ts
+ * console.log(getWistiaEmbedUrlFromId("26sk4lmiix"));
+ * // "https://fast.wistia.net/embed/iframe/26sk4lmiix"
+ * ```
  */
 export declare const getWistiaEmbedUrlFromId: (id: string) => string;
+/**
+ * A provider implementation for Wistia, following the {@link EmbedProvider} interface.
+ */
+export declare const WistiaProvider: EmbedProvider;
 //# sourceMappingURL=wistia.d.ts.map

dist/providers/youtube.d.ts

@@ -0,7 +1,57 @@
+import { EmbedProvider } from '../provider';
 /**
- * Regex matcher for YouTube URLs
+ * Regex matcher for YouTube URLs.
+ *
+ * @remarks
+ * This pattern captures the 11-character YouTube video ID from multiple formats:
+ * - `https://www.youtube.com/watch?v=...`
+ * - `https://youtu.be/...`
+ * - Variants with or without `www.` / `-nocookie`
+ *
+ * **Credit**: [Stack Overflow](https://stackoverflow.com/a/42442074)
  */
 export declare const youTubeUrlRegex: RegExp;
+/**
+ * Extracts an 11-character YouTube video ID from a given URL string.
+ *
+ * @param url - The string potentially representing a YouTube link (can be `undefined`).
+ * @returns The extracted video ID, or an empty string if no match is found.
+ *
+ * @example
+ * ```ts
+ * // With a watch URL:
+ * const videoId = getYouTubeIdFromUrl("https://www.youtube.com/watch?v=FTQbiNvZqaY");
+ * console.log(videoId); // "FTQbiNvZqaY"
+ *
+ * // With a shortlink:
+ * const shortId = getYouTubeIdFromUrl("https://youtu.be/FTQbiNvZqaY");
+ * console.log(shortId); // "FTQbiNvZqaY"
+ * ```
+ *
+ * @remarks
+ * If `url` is `undefined` or not a valid YouTube link, returns an empty string.
+ */
 export declare const getYouTubeIdFromUrl: (url: string | undefined) => string;
+/**
+ * Constructs a YouTube embed URL from a 11-character video ID.
+ *
+ * @param id - The YouTube video ID.
+ * @returns An embeddable URL in the form `https://www.youtube.com/embed/<id>`.
+ *
+ * @example
+ * ```ts
+ * console.log(getYouTubeEmbedUrlFromId("FTQbiNvZqaY"));
+ * // "https://www.youtube.com/embed/FTQbiNvZqaY"
+ * ```
+ */
 export declare const getYouTubeEmbedUrlFromId: (id: string | undefined) => string;
+/**
+ * A provider implementation for YouTube, satisfying the {@link EmbedProvider} interface.
+ *
+ * @remarks
+ * - `canParseUrl()` detects if a URL belongs to YouTube using {@link youTubeUrlRegex}.
+ * - `getIdFromUrl()` extracts the YouTube video ID (11 chars).
+ * - `getEmbedUrlFromId()` builds a playable embed URL.
+ */
+export declare const YouTubeProvider: EmbedProvider;
 //# sourceMappingURL=youtube.d.ts.map

dist/utils.d.ts

@@ -1,15 +0,2 @@
-import { Provider } from './constants';
-import { ValueOfProvider } from './types';
-export declare const getProviderFromUrl: (url: string) => Provider | undefined;
-export declare const ProviderIdFunctionMap: {
-    [P in ValueOfProvider]: (url: string) => string | string[];
-};
-type ProviderIdFn = {
-    [P in ValueOfProvider]: (id: string, ...args: unknown[]) => string;
-};
-export declare const ProviderIdUrlFunctionMap: ProviderIdFn;
-/**
- * Converts URL variations from sites to their "embed-friendly" URL.
- */
-export declare const convertUrlToEmbedUrl: (url: string) => string;
+import { EmbedProvider } from './provider';
 export declare const isString: (val: unknown) => val is string;
@@ -23,3 +10,23 @@ export declare const isRegExp: (val: unknown) => val is RegExp;
 export declare const matcher: (regex: RegExp | string) => ((value: string) => boolean);
-export {};
+/**
+ * Returns the first registered provider that can handle a given URL.
+ *
+ * @remarks
+ * Internally calls {@link EmbedProviderRegistry.findProviderByUrl}.
+ * Returns `undefined` if no known provider matches.
+ *
+ * @param url - The URL to check.
+ */
+export declare function getProviderFromUrl(url: string): EmbedProvider | undefined;
+/**
+ * Converts a recognized media URL to an embeddable iframe-friendly URL.
+ *
+ * @remarks
+ * - If the URL is recognized, calls the provider’s `getIdFromUrl()` and `getEmbedUrlFromId()`.
+ * - If no provider is found, returns an empty string.
+ *
+ * @param url - The user-supplied media URL (e.g., a YouTube link).
+ * @returns The embeddable URL string (e.g., `https://www.youtube.com/embed/...`) or an empty string.
+ */
+export declare function convertUrlToEmbedUrl(url: string): string;
 //# sourceMappingURL=utils.d.ts.map

package.json

 {
   "name": "@social-embed/lib",
   "description": "URL detection and parsing for embed providers (YouTube, other OEmbed compatible providers),",
-  "version": "0.1.0-next.9",
+  "version": "0.1.0-next.10",
   "main": "dist/lib.umd.cjs",
@@ -41,3 +41,3 @@ "module": "dist/lib.js",
     "typescript": "^5.7.2",
-    "vite": "^6.0.6",
+    "vite": "^6.0.7",
     "vite-plugin-dts": "^4.4.0",
@@ -51,2 +51,3 @@ "vitest": "^2.1.8"
     "clean": "rimraf dist",
+    "check": "tsc --noEmit",
     "vite": "vite",
@@ -53,0 +54,0 @@ "start": "pnpm vite",

README.md

@@ -1,44 +0,137 @@
-# [`@social-embed/lib`](https://social-embed.git-pull.com/) · [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/social-embed/social-embed/blob/master/LICENSE) [![npm version](https://img.shields.io/npm/v/@social-embed/lib.svg?style=flat)](https://www.npmjs.com/package/@social-embed/lib)
+# `@social-embed/lib` · [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/social-embed/social-embed/blob/master/LICENSE) [![npm version](https://img.shields.io/npm/v/@social-embed/lib.svg?style=flat)](https://www.npmjs.com/package/@social-embed/lib)
 
-## Start
+A lightweight, browser-friendly utility that parses common media URLs (YouTube, Vimeo, Spotify, etc.) and converts them into embeddable links or extracts relevant IDs.
 
-Install the package:
+## Installation
 
+**NPM:**
+
 ```bash
 npm i @social-embed/lib
-# or
+```
+
+**yarn:**
+
+```bash
 yarn add @social-embed/lib
 ```
 
-Then import and use it like so:
+**pnpm:**
 
+```bash
+pnpm add @social-embed/lib
+```
+
+### Using a CDN
+
+If your environment supports ESM or direct URL imports, you can pull from a CDN:
+
+**unpkg**:
+
 ```typescript
-import { convertUrlToEmbedUrl, getYouTubeIdFromUrl } from "@social-embed/lib";
+import { getYouTubeIdFromUrl } from "https://www.unpkg.com/@social-embed/lib?module";
+```
 
+**skypack**:
+
+```typescript
+import { getYouTubeIdFromUrl } from "https://cdn.skypack.dev/@social-embed/lib";
+```
+
+---
+
+## Usage
+
+Below is a simple TypeScript example demonstrating some core functions:
+
+```typescript
+import {
+  convertUrlToEmbedUrl,
+  getYouTubeIdFromUrl,
+  getDailyMotionIdFromUrl,
+  getDailyMotionEmbedFromId,
+} from "@social-embed/lib";
+
+// 1. Convert any recognized media URL into its embeddable form
 console.log(
   convertUrlToEmbedUrl("https://www.youtube.com/watch?v=Bd8_vO5zrjo"),
 );
-// output: https://www.youtube.com/embed/Bd8_vO5zrjo
+// Output: "https://www.youtube.com/embed/Bd8_vO5zrjo"
 
-console.log(getYouTubeIdFromUrl("https://www.youtube.com/watch?v=Bd8_vO5zrjo"));
-// output: Bd8_vO5zrjo
+// 2. Extract YouTube video ID
+console.log(getYouTubeIdFromUrl("https://youtu.be/Bd8_vO5zrjo"));
+// Output: "Bd8_vO5zrjo"
+
+// 3. DailyMotion usage
+console.log(
+  getDailyMotionIdFromUrl("https://www.dailymotion.com/video/x7znrd0"),
+);
+// Output: "x7znrd0"
+
+console.log(getDailyMotionEmbedFromId("x7znrd0"));
+// Output: "https://www.dailymotion.com/embed/video/x7znrd0"
 ```
 
-If your environment supports ESM or direct URLs, you can also import the library like this:
+### More Examples
 
+**Spotify**
+
 ```typescript
-// unpkg
-import { getYouTubeIdFromUrl } from "https://www.unpkg.com/@social-embed/lib?module";
+console.log(convertUrlToEmbedUrl("spotify:album:1DFixLWuPkv3KT3TnV35m3"));
+// "https://open.spotify.com/embed/album/1DFixLWuPkv3KT3TnV35m3"
+```
 
-// skypack
-import { getYouTubeIdFromUrl } from "https://cdn.skypack.dev/@social-embed/lib";
+**Vimeo**
+
+```typescript
+console.log(convertUrlToEmbedUrl("vimeo.com/channels/staffpicks/134668506"));
+// "https://player.vimeo.com/video/134668506"
 ```
 
-## Try
+**Loom**
 
-- [CodePen], [CodePen Console]
-- [JSFiddle]
+```typescript
+console.log(
+  convertUrlToEmbedUrl("loom.com/share/e883f70b219a49f6ba7fbeac71a72604"),
+);
+// "https://www.loom.com/embed/e883f70b219a49f6ba7fbeac71a72604"
+```
 
+**EdPuzzle**
+
+```typescript
+console.log(
+  convertUrlToEmbedUrl("edpuzzle.com/media/606b413369971e424ec6021e"),
+);
+// "https://edpuzzle.com/embed/media/606b413369971e424ec6021e"
+```
+
+**Wistia**
+
+```typescript
+console.log(
+  convertUrlToEmbedUrl("https://support.wistia.com/medias/26sk4lmiix"),
+);
+// "https://fast.wistia.net/embed/iframe/26sk4lmiix"
+```
+
+### Validate Any URL
+
+```typescript
+import { isValidUrl } from "@social-embed/lib";
+
+console.log(isValidUrl("https://apple.com")); // true
+console.log(isValidUrl("notaurl")); // false
+```
+
+---
+
+## Try It Out
+
+- [CodePen][codepen]
+- [CodePen Console][codepen console]
+- [JSFiddle][jsfiddle]
+
 [codepen]: https://codepen.io/attachment/pen/VwPPrNq
 [codepen console]: https://codepen.io/attachment/pen/poRRpdp?editors=0010
 [jsfiddle]: https://jsfiddle.net/gitpull/pcLagbsm/

New alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

46637

increased by118.24%

Number of package files

37

increased by19.35%

Lines of code

960

increased by250.36%

Number of lines in readme file

138

increased by206.67%

Worsened metrics

Number of medium supply chain risk alerts

1

increased byInfinity%

No dependency changes