oEmbed Client

This is a client library for fetching oEmbed information for media URLs from providers like YouTube, Twitter, and Instagram. It handles sending requests to oEmbed services and processing their JSON responses.

Note: This library only supports JSON responses and does not support XML.

中文版請見: oEmbed Client Documentation (Traditional Chinese)

> Acknowledgements:
> This project has adopted and refactored parts of the code and concepts from @extractus/oembed-extractor. Without the contributions of that project's authors, this project would have been difficult to complete. Special thanks to them!

> Sponsor:
> This project is sponsored by Havppen: Create your exclusive "online course platform" and monetize your knowledge now!

Installation

``bash
npm install @andrash/oembed-client


or

yarn add @andrash/oembed-client

or

pnpm add @andrash/oembed-client
`

Usage

$3

The OembedClient does not automatically load any default list of oEmbed service providers. You must first create a provider configuration list to pass to the OembedClient upon initialization.

Here is an example of how to define your provider configurations:

`typescript
// filepath: oembed-providers.ts
import { ProviderConfig } from "@andrash/oembed-client";

export const OEMBED_PROVIDER_CONFIGS: ProviderConfig[] = [
// Basic example
{
name: "YouTube",
url: "https://www.youtube.com/",
endpoints: [
{
patterns: [
"https://.youtube.com/watch",
"https://.youtube.com/v/",
"https://youtu.be/*",
"https://.youtube.com/playlist?list=",
"https://youtube.com/playlist?list=*",
"https://.youtube.com/shorts",
"https://youtube.com/shorts*",
"https://.youtube.com/embed/",
"https://.youtube.com/live",
"https://youtube.com/live*",
],
url: "https://www.youtube.com/oembed",
},
],
},
// Advanced example: oEmbed service requiring an access token
{
name: "Example",
url: "https://example.com",
endpoints: [
{
patterns: ["http://example.com//p/", "http://www.example.com//p/"],
url: "https://graph.example.com/oembed",
queryParams: {
// Some oEmbed services (like Facebook, Instagram, Threads) require an access token to authenticate requests. You can add the relevant query parameters here.
access_token: process.env.EXAMPLE_OEMBED_ACCESS_TOKEN,
// You can also add other custom query parameters...
},
headers: {
// Some oEmbed services may require authorization information in the headers.
Authorization: Bearer ${process.env.EXAMPLE_OEMBED_ACCESS_TOKEN},
// You can also add other custom headers...
},
},
],
},

// Other oEmbed service endpoints...
];
`

You can copy the example provider list file from this package at oembed-provider.config.ts. It includes many common oEmbed providers and can be modified to suit your needs.

$3

Create an OembedClient instance, passing your provider configuration list to the constructor:

`typescript
import { OembedClient } from "@andrash/oembed-client";
import { OEMBED_PROVIDER_CONFIGS } from "./oembed-providers";

const oembedClient = new OembedClient(OEMBED_PROVIDER_CONFIGS);
`

$3

Use the findEndpoint() method to get the correct provider endpoint for a given URL. Then, call the extract() method on the endpoint to fetch the oEmbed data.

`typescript
const url = "https://www.youtube.com/watch?v=dQw4w9WgXcQ";
const endpoint = oembedClient.findEndpoint(url);

if (endpoint) {
try {
const oembedData = await endpoint.extract(url, {
// You can pass extra parameters here, such as maxwidth and maxheight.
// These will be merged with any queryParams in your provider config.
// If a parameter exists in both, the value passed here takes precedence.
maxwidth: 600,
maxheight: 400,
});
console.log(oembedData);
} catch (error) {
console.error("Error fetching oEmbed data:", error);
}
} else {
console.log("No matching oEmbed provider found for the URL.");
}
``

That's it!

You are now ready to use the oEmbed Client to fetch oEmbed data from various providers!