@extractus/oembed-extractor

Extract oEmbed content from given URL.

Install

Deno

deno add jsr:@extractus/oembed-extractor

Node.js / Bun

pnpm add jsr:@extractus/oembed-extractor
# or
npx jsr add @extractus/oembed-extractor
# or
bunx jsr add @extractus/oembed-extractor

Alternatively, install from npm:

npm install @extractus/oembed-extractor
# or
bun add @extractus/oembed-extractor

Usage

import { extract } from "jsr:@extractus/oembed-extractor";

const data = await extract("https://www.youtube.com/watch?v=x2bqscVkGxk");
console.log(data);

APIs

• extract()
• findProvider()
• hasProvider()
• setProviderList()

extract()

Load and extract oEmbed data from a URL.

Syntax

extract(url: string): Promise<OembedData>
extract(url: string, params?: Params): Promise<OembedData>
extract(url: string, params?: Params, fetcher?: Fetcher): Promise<OembedData>

Example:

import { extract } from "jsr:@extractus/oembed-extractor";

try {
  const result = await extract("https://www.youtube.com/watch?v=x2bqscVkGxk");
  console.log(result);
} catch (err) {
  console.error(err);
}

The result is an OembedData object:

interface OembedData {
  type: "rich" | "video" | "photo" | "link";
  version: string;
  title?: string;
  author_name?: string;
  author_url?: string;
  provider_name?: string;
  provider_url?: string;
  cache_age?: string | number;
  thumbnail_url?: string;
  thumbnail_width?: number;
  thumbnail_height?: number;
  method?: string;
  [key: string]: unknown;
}

Parameters

url required

URL of a valid oEmbed resource, e.g. https://www.youtube.com/watch?v=x2bqscVkGxk

params optional

| Property | Type | Description | |---|---|---| | maxwidth | number | Max width of embed size | | maxheight | number | Max height of embed size | | theme | string | e.g. "dark" or "light" | | lang | string | e.g. "en", "fr", "vi" |

Note that some params are supported by some providers but not others. See the provider's oEmbed API docs for exact information.

fetcher optional

A custom fetch function with the signature (url: string) => Promise<Response>. Use this to customize HTTP behavior: proxy, headers, TLS, authentication, timeouts, etc.

Defaults to globalThis.fetch.

Deno (with proxy):

import { extract } from "@extractus/oembed-extractor";

const client = Deno.createHttpClient({
  proxy: { url: "http://proxy.example.com:8080" },
});
const myFetcher = (url: string) => fetch(url, { client });

const result = await extract("https://www.youtube.com/watch?v=x2bqscVkGxk", {}, myFetcher);

Node.js (with proxy via undici):

import { extract } from "@extractus/oembed-extractor";
import { fetch, ProxyAgent } from "undici";

const dispatcher = new ProxyAgent("http://proxy.example.com:8080");
const myFetcher = (url: string) => fetch(url, { dispatcher });

const result = await extract("https://www.youtube.com/watch?v=x2bqscVkGxk", {}, myFetcher);

Bun (with proxy):

import { extract } from "@extractus/oembed-extractor";

const myFetcher = (url: string) =>
  fetch(url, {
    proxy: "http://proxy.example.com:8080",
  });

const result = await extract("https://www.youtube.com/watch?v=x2bqscVkGxk", {}, myFetcher);

Custom headers:

const myFetcher = (url: string) =>
  fetch(url, {
    headers: {
      "user-agent": "MyBot/1.0",
      authorization: "Bearer token123",
    },
  });

const result = await extract(url, {}, myFetcher);

Request timeout:

const myFetcher = (url: string) =>
  fetch(url, {
    signal: AbortSignal.timeout(5000),
  });

const result = await extract(url, {}, myFetcher);

findProvider()

Find the provider that matches a given URL.

Syntax

findProvider(url: string): FindResult | null

Example:

import { findProvider } from "jsr:@extractus/oembed-extractor";

const provider = findProvider("https://www.youtube.com/watch?v=x2bqscVkGxk");
console.log(provider?.endpoint); // "https://www.youtube.com/oembed"

hasProvider()

Check if a URL is supported by any registered provider.

Syntax

hasProvider(url: string): boolean

Example:

import { hasProvider } from "jsr:@extractus/oembed-extractor";

hasProvider("https://www.youtube.com/watch?v=x2bqscVkGxk"); // true
hasProvider("https://example.com/unknown"); // false

setProviderList()

Replace the provider list with a custom set of providers, overriding the default.

Syntax

setProviderList(providers: Provider[]): number

Example:

import { setProviderList } from "jsr:@extractus/oembed-extractor";

const count = setProviderList([
  {
    provider_name: "Alpha",
    provider_url: "https://alpha.com",
    endpoints: [
      {
        schemes: ["https://store.alpha.com/*"],
        url: "https://api.alpha.com/oembed",
      },
    ],
  },
]);

Default list of resource providers is synchronized from oembed.com.

If you want to modify the providers list, please make a pull request on iamcal/oembed then create an issue/pr here to ask for sync.

Development

git clone https://github.com/extractus/oembed-extractor.git
cd oembed-extractor

# run tests
deno test --allow-all

# lint
deno lint

# build npm package
deno run -A ./scripts/build_npm.ts

# sync providers from oembed.com
deno task sync

License

The MIT License (MIT)

Support the project

This project is maintained in my spare time. If you find it helpful, there are a few simple ways to support its continued development:

• ⭐ Star this repository to help more people discover it.
• ☕ Buy me a coffee: https://paypal.me/ndaidong
• 🚀 Subscribe to the oEmbed Parser service on RapidAPI.

Every bit of support helps keep this project actively maintained. Thank you! ❤️