@lastshotlabs/slingshot-embeds
npm install @lastshotlabs/slingshot-embeds
Functions
Section titled “Functions”createEmbedsPlugin
Section titled “createEmbedsPlugin”Create the slingshot-embeds plugin for URL unfurling.
Returns a stateless plugin that exposes a POST /embeds/unfurl endpoint
(mount path is configurable). The endpoint accepts { url: string },
validates the URL against SSRF rules and domain lists, fetches the page
server-side, parses OG/meta tags, and returns structured metadata.
Results are cached in-memory with a configurable TTL.
function createEmbedsPlugin(rawConfig?: unknown): SlingshotPluginSource: packages/slingshot-embeds/src/plugin.ts
parseOgMetadata
Section titled “parseOgMetadata”Parse Open Graph and fallback metadata from an HTML string.
Extracts metadata from the <head> section only (stops at </head> or <body).
Checks OG tags first, falls back to Twitter card tags, then standard HTML tags.
Relative URLs for image and favicon are resolved against pageUrl when provided.
function parseOgMetadata(html: string, pageUrl?: string): Partial<UnfurlResult>Source: packages/slingshot-embeds/src/lib/htmlParser.ts
unfurl
Section titled “unfurl”Fetch a URL and extract structured OG/meta metadata.
Sends a GET request with a bot user-agent, checks that the response is HTML,
enforces a byte-size limit on the body, then parses OG tags from the <head>.
Redirects are followed manually — each hop’s hostname is resolved via DNS and checked against private/reserved IP ranges before the next request is issued. This prevents DNS rebinding attacks where a redirect leads to an internal host.
async function unfurl(url: string, config: { timeoutMs: number; maxResponseBytes: number; maxRedirects?: number },): Promise<UnfurlResult>Source: packages/slingshot-embeds/src/lib/unfurl.ts
validateUrl
Section titled “validateUrl”Validate a user-supplied URL for safe server-side fetching.
Ensures the URL uses http/https, is not targeting private/reserved IPs, and passes domain allow/block list checks.
function validateUrl(url: string, config: { allowedDomains?: string[]; blockedDomains?: string[] },): ValidateUrlResultSource: packages/slingshot-embeds/src/lib/ssrfGuard.ts
Constants
Section titled “Constants”embedsPluginConfigSchema
Section titled “embedsPluginConfigSchema”Zod schema for EmbedsPluginConfig.
Validates and provides defaults for all embeds plugin configuration options.
Source: packages/slingshot-embeds/src/types.ts
Interfaces
Section titled “Interfaces”UnfurlResult
Section titled “UnfurlResult”Structured metadata extracted from a URL via OG/meta tag parsing.
All fields except url are optional because a target page may not
include any metadata tags.
Source: packages/slingshot-embeds/src/types.ts
EmbedsPluginConfig
Section titled “EmbedsPluginConfig”Configuration for the slingshot-embeds plugin.
All fields are optional and have sensible defaults. See embedsPluginConfigSchema
for validation rules and default values.
Source: packages/slingshot-embeds/src/types.ts