@sockethub/platform-metadata 1.0.1-beta.0 → 1.0.1-beta.2

package/README.md

@@ -67,7 +67,15 @@ The platform returns an ActivityStream object with extracted metadata:
     ],
     "url": "https://example.com/canonical-url",
     "favicon": "https://example.com/favicon.ico",
-    "charset": "utf-8"
+    "charset": "utf-8",
+    "event": {
+      "name": "Tech Talks",
+      "startDate": "2026-11-09T18:00:00-06:00",
+      "endDate": "2026-11-09T20:00:00-06:00",
+      "location": "Civic Center, 1218 West Ave, Austin, TX",
+      "url": "https://example.com/canonical-url",
+      "status": "scheduled"
+    }
   }
 }
 ```
@@ -83,6 +91,13 @@ The platform extracts the following metadata when available:
 * **Canonical URLs**: Resolved and canonical page URLs
 * **Media**: Images with dimensions and type information; for X/Twitter posts,
   a `video` object (direct media URL, poster `thumbnail`, dimensions, duration)
+* **Events**: When the page embeds a schema.org `Event` (or subtype) as
+  JSON-LD — Luma, Meetup, Eventbrite and most ticketing sites — an `event`
+  object carries `name`, `startDate` (ISO 8601 as published, possibly
+  date-only), and optionally `endDate`, `location` (place name and address
+  flattened to one string, or the virtual location URL), `url`, and `status`
+  (`scheduled`, `cancelled`, `postponed`, `rescheduled`). Only present when
+  both a name and a start date are declared.
 
 ## Site-Specific Handling
 
@@ -101,8 +116,20 @@ so those URLs are resolved through preview services built for this purpose:
   self-text, and direct `i.redd.it` image are mapped into the preview; text posts
   intentionally have no image. oEmbed remains a title-only failure fallback.
   See `compatUserAgent` below.
-* **Facebook** remains best-effort: post text usually comes through, but
-  media requires authentication and no public preview service exists.
+* **Facebook** remains best-effort: post text usually comes through. The
+  video or photo thumbnail is taken from the post's Open Graph image, then
+  its Twitter card image, and finally the image rendered by Facebook's public
+  embed plugin (`/plugins/video.php` or `/plugins/post.php`), which Facebook
+  serves to third parties when it withholds Open Graph media from a
+  datacenter address. Full media still requires authentication. Facebook
+  publishes no site name, so `actor.name` and `object.name` fall back to
+  `Facebook`.
+* **Facebook engagement prefixes**: video titles and image alt text often
+  start with a localized view or reaction count, such as
+  `2.2M views · 21K reactions | …` or `347K views | …`. When the prefix is
+  recognized it is stripped from `object.title` and from each image `alt`. A
+  title that merely starts with a small plain number, such as
+  `10 Goals | Author`, is kept.
 
 ### `userAgent`
 
@@ -151,9 +178,14 @@ Because the server fetches whatever URL a client supplies as `actor.id`, metadat
 requests are hardened against server-side request forgery (SSRF) and resource
 exhaustion. The fetch runs through a guarded connection layer that:
 
+* rejects URL schemes other than `http` and `https`;
 * refuses to connect to loopback, private, link-local, carrier-grade NAT, or
-  cloud-metadata addresses (e.g. `169.254.169.254`), in every IPv4/IPv6 spelling,
-  validated at connection time so it also covers redirect hops;
+  cloud-metadata addresses (e.g. `169.254.169.254`), validated at connection
+  time so it also covers redirect hops. IPv4-mapped, IPv4-compatible, and
+  well-known NAT64 (`64:ff9b::/96`) embeddings are judged as the embedded IPv4
+  address. The local-use NAT64 prefix `64:ff9b:1::/48` is refused entirely.
+  The ranges are listed under
+  [Outbound URL guard](../../docs/configuration.md#outbound-url-guard);
 * caps the response body size.
 
 ### `allowPrivateAddresses`

package/dist/event.d.ts

@@ -0,0 +1,17 @@
+/** Scheduling facts from a page's schema.org `Event` JSON-LD. */
+export interface PageEvent {
+    name: string;
+    startDate: string;
+    endDate?: string;
+    location?: string;
+    url?: string;
+    status?: "scheduled" | "cancelled" | "postponed" | "rescheduled";
+}
+/**
+ * Pick the first schema.org `Event` (or subtype such as `MusicEvent`) out of
+ * the page's JSON-LD blocks and reduce it to the scheduling facts a client
+ * needs to build a calendar entry. Nodes may be bare objects, arrays, or
+ * `@graph` wrappers. Returns undefined when no node carries a name and a
+ * start date — a half-filled block is worth nothing to a calendar.
+ */
+export declare function schemaOrgEvent(jsonLD: unknown): PageEvent | undefined;

package/dist/index.d.ts

@@ -122,6 +122,31 @@ export default class Metadata implements PlatformInterface {
                             charset: {
                                 type: string;
                             };
+                            event: {
+                                type: string;
+                                required: string[];
+                                additionalProperties: boolean;
+                                properties: {
+                                    name: {
+                                        type: string;
+                                    };
+                                    startDate: {
+                                        type: string;
+                                    };
+                                    endDate: {
+                                        type: string;
+                                    };
+                                    location: {
+                                        type: string;
+                                    };
+                                    url: {
+                                        type: string;
+                                    };
+                                    status: {
+                                        enum: string[];
+                                    };
+                                };
+                            };
                         };
                     };
                     ogImage: {
@@ -168,6 +193,12 @@ export default class Metadata implements PlatformInterface {
     private fetchDirectImage;
     /** Fetch and validate YouTube's official preview metadata. */
     private fetchYouTubeEmbed;
+    /**
+     * Last-resort thumbnail for a Facebook post whose page carried no
+     * Open Graph image: the media image rendered by Facebook's public embed
+     * plugin, which is served to third parties without a login wall.
+     */
+    private fetchFacebookEmbedImage;
     private fetchTweet;
     private fetchReddit;
     /**