@pylonsync/functions 0.3.360 → 0.3.362

package/dist/ssr-runtime.d.ts

@@ -226,6 +226,9 @@ export interface SsrMetadata {
     openGraph?: {
         title?: string;
         description?: string;
+        /** `og:image`. A root-relative path (`/og.png`) is resolved against
+         *  the request origin before it's emitted — crawlers require an
+         *  absolute URL and Twitter drops the card without one. */
         image?: string;
         /** `og:image:secure_url` — set automatically to the https image URL. */
         imageSecureUrl?: string;
@@ -236,7 +239,7 @@ export interface SsrMetadata {
         imageHeight?: number;
         imageAlt?: string;
         /** Additional images beyond the primary `image` (each emits its own
-         *  `og:image` + dimensions). Provide absolute URLs. */
+         *  `og:image` + dimensions). Relative URLs are absolutized. */
         images?: OgImage[];
         url?: string;
         type?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.3.360",
+  "version": "0.3.362",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",

package/src/ssr-runtime.test.ts

@@ -392,6 +392,89 @@ describe("opengraph-image file convention", () => {
   });
 });
 
+/**
+ * Relative social URLs. Facebook and Slack resolve them; Twitter drops
+ * the image and ships a grey box, so a card looks fine everywhere the
+ * author checked and broken where it mattered.
+ */
+describe("absolutizing author-supplied social URLs", () => {
+  const withOrigin = <T,>(fn: () => T): T => {
+    const prev = process.env.PYLON_PUBLIC_URL;
+    process.env.PYLON_PUBLIC_URL = "https://www.example.com";
+    try {
+      return fn();
+    } finally {
+      if (prev === undefined) delete process.env.PYLON_PUBLIC_URL;
+      else process.env.PYLON_PUBLIC_URL = prev;
+    }
+  };
+  const apply = (md: any, url = "/") =>
+    withOrigin(() =>
+      applyAutoSocialImages("app/page", { host: "www.example.com" }, md, url),
+    );
+
+  test("a root-relative og:image becomes absolute", () => {
+    const md = apply({
+      openGraph: { image: "/marketing/og.png" },
+      twitter: { card: "summary_large_image", image: "/marketing/og.png" },
+    });
+    expect(md?.openGraph?.image).toBe("https://www.example.com/marketing/og.png");
+    expect(md?.twitter?.image).toBe("https://www.example.com/marketing/og.png");
+  });
+
+  test("an https origin also fills og:image:secure_url", () => {
+    const md = apply({ openGraph: { image: "/og.png" } });
+    expect(md?.openGraph?.imageSecureUrl).toBe("https://www.example.com/og.png");
+  });
+
+  test("an absolute URL is left exactly as authored", () => {
+    const md = apply({
+      openGraph: { image: "https://cdn.other.test/a.png" },
+      twitter: { image: "https://cdn.other.test/a.png" },
+    });
+    expect(md?.openGraph?.image).toBe("https://cdn.other.test/a.png");
+    expect(md?.twitter?.image).toBe("https://cdn.other.test/a.png");
+  });
+
+  test("a data: URL is left alone", () => {
+    const md = apply({ openGraph: { image: "data:image/png;base64,iVBOR" } });
+    expect(md?.openGraph?.image).toBe("data:image/png;base64,iVBOR");
+  });
+
+  test("a protocol-relative URL picks up the origin's scheme", () => {
+    const md = apply({ openGraph: { image: "//cdn.other.test/a.png" } });
+    expect(md?.openGraph?.image).toBe("https://cdn.other.test/a.png");
+  });
+
+  test("a path-relative URL resolves against the request path", () => {
+    const md = apply({ openGraph: { image: "og.png" } }, "/blog/post-1");
+    expect(md?.openGraph?.image).toBe("https://www.example.com/blog/og.png");
+  });
+
+  test("og:url and canonical are absolutized too", () => {
+    const md = apply({
+      canonical: "/pricing",
+      openGraph: { image: "/og.png", url: "/pricing" },
+    });
+    expect(md?.canonical).toBe("https://www.example.com/pricing");
+    expect(md?.openGraph?.url).toBe("https://www.example.com/pricing");
+  });
+
+  test("every entry in an images list is absolutized", () => {
+    const md = apply({
+      openGraph: { images: [{ url: "/a.png" }, { url: "https://x.test/b.png" }] },
+    });
+    expect(md?.openGraph?.images?.[0]?.url).toBe("https://www.example.com/a.png");
+    expect(md?.openGraph?.images?.[1]?.url).toBe("https://x.test/b.png");
+  });
+
+  test("metadata with no social URLs is untouched", () => {
+    const md = apply({ title: "Hi" });
+    expect(md?.title).toBe("Hi");
+    expect(md?.openGraph).toBeUndefined();
+  });
+});
+
 describe("icon / apple-icon / favicon file convention", () => {
   test("auto-wires <link rel=icon> + apple-touch-icon (relative URL + sizes)", () => {
     const dir = makeApp();

package/src/ssr-runtime.ts

@@ -496,6 +496,9 @@ export interface SsrMetadata {
   openGraph?: {
     title?: string;
     description?: string;
+    /** `og:image`. A root-relative path (`/og.png`) is resolved against
+     *  the request origin before it's emitted — crawlers require an
+     *  absolute URL and Twitter drops the card without one. */
     image?: string;
     /** `og:image:secure_url` — set automatically to the https image URL. */
     imageSecureUrl?: string;
@@ -506,7 +509,7 @@ export interface SsrMetadata {
     imageHeight?: number;
     imageAlt?: string;
     /** Additional images beyond the primary `image` (each emits its own
-     *  `og:image` + dimensions). Provide absolute URLs. */
+     *  `og:image` + dimensions). Relative URLs are absolutized. */
     images?: OgImage[];
     url?: string;
     type?: string;
@@ -1134,12 +1137,103 @@ export function applyAutoIcons(
   return out;
 }
 
+/**
+ * Resolve a possibly-relative URL against the request's absolute origin.
+ *
+ * Returns the input unchanged when it's already absolute (`https:`,
+ * `data:`, …), when there's no trustworthy origin to resolve against, or
+ * when it doesn't parse. A protocol-relative `//cdn/x.png` picks up the
+ * origin's scheme, which is what makes it valid to a crawler.
+ */
+function absolutizeUrl(
+  value: string,
+  origin: string,
+  requestPath: string,
+): string {
+  if (!value || !origin) return value;
+  // Already absolute — an explicit CDN or a fully-qualified URL.
+  if (/^[a-z][a-z0-9+.-]*:/i.test(value)) return value;
+  try {
+    const base = requestPath ? new URL(requestPath, origin).href : origin;
+    return new URL(value, base).href;
+  } catch {
+    return value;
+  }
+}
+
+/**
+ * Make every crawler-facing URL in a page's metadata absolute.
+ *
+ * Covers `og:image` (single + list), `og:url`, `twitter:image`, and the
+ * canonical link — the tags where a relative value is accepted by some
+ * consumers and silently dropped by others.
+ */
+function absolutizeMetadataUrls(
+  metadata: SsrMetadata | undefined,
+  headers: Record<string, string> | undefined,
+  requestUrl?: string,
+): SsrMetadata | undefined {
+  if (!metadata) return metadata;
+  const origin = resolveRequestOrigin(headers);
+  if (!origin) return metadata;
+  const path = (requestUrl ?? "/").split("?")[0] || "/";
+  const abs = (v: string | undefined): string | undefined =>
+    v == null ? v : absolutizeUrl(v, origin, path);
+
+  const out: SsrMetadata = { ...metadata };
+  const og = out.openGraph;
+  if (og) {
+    const nextOg = { ...og };
+    if (nextOg.image) {
+      nextOg.image = abs(nextOg.image);
+      // og:image:secure_url must be the https form. If the author gave a
+      // relative path and the origin is https, the absolute URL *is* it.
+      if (!nextOg.imageSecureUrl && nextOg.image?.startsWith("https:")) {
+        nextOg.imageSecureUrl = nextOg.image;
+      } else if (nextOg.imageSecureUrl) {
+        nextOg.imageSecureUrl = abs(nextOg.imageSecureUrl);
+      }
+    }
+    if (Array.isArray(nextOg.images)) {
+      nextOg.images = nextOg.images.map((img) =>
+        img?.url
+          ? {
+              ...img,
+              url: abs(img.url) as string,
+              ...(img.secureUrl ? { secureUrl: abs(img.secureUrl) } : {}),
+            }
+          : img,
+      );
+    }
+    if (nextOg.url) nextOg.url = abs(nextOg.url);
+    out.openGraph = nextOg;
+  }
+  if (out.twitter?.image) {
+    out.twitter = { ...out.twitter, image: abs(out.twitter.image) };
+  }
+  if (out.canonical) out.canonical = abs(out.canonical);
+  if (out.alternates?.canonical) {
+    out.alternates = {
+      ...out.alternates,
+      canonical: abs(out.alternates.canonical),
+    };
+  }
+  return out;
+}
+
 export function applyAutoSocialImages(
   component: string,
   headers: Record<string, string> | undefined,
   metadata: SsrMetadata | undefined,
   requestUrl?: string,
 ): SsrMetadata | undefined {
+  // A relative image is the single most common way a share card breaks:
+  // the page ships `og:image="/og.png"`, Facebook and Slack resolve it,
+  // Twitter does not, and the post goes out with an empty grey box. The
+  // origin is already resolved here for the auto-injected images, so
+  // resolve the author's URLs against it too.
+  metadata = absolutizeMetadataUrls(metadata, headers, requestUrl);
+
   const hasOg = !!metadata?.openGraph?.image;
   const hasTw = !!metadata?.twitter?.image;
   if (hasOg && hasTw) return metadata;