npm - @qrxcode/js - Versions diffs - 0.4.0 → 0.5.0 - Mend

@qrxcode/js 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md CHANGED Viewed

@@ -18,9 +18,14 @@ QRX works with:
 A normal QR code still contains a normal URL.
 QRX-compatible applications resolve the URL,
-discover machine-readable flows from the HTML `<head>`,
+discover machine-readable flows,
 and let the application decide what to do next.
+Discovery currently supports:
+- HTML `<link>` declarations
+- HTTP `Link` response headers
 This works especially well with podcast websites,
 because many podcast sites already expose one or multiple feeds.
@@ -100,7 +105,7 @@ Version `0.4.0` adds a new flow category:
 flowType: "qrx"
 ```
-A QRX flow is discovered from an explicit HTML `<link>` declaration:
+A QRX flow is discovered from an explicit HTML declaration:
 ```html
 <link
@@ -121,7 +126,7 @@ These are valid:
 ```html
 <link rel="qrx" type="application/qrx+json" href="/qrx.json">
-<link rel="qrx" type="text/html" href="/demo.html">
+<link rel="qrx" type="text/html" href="/qrx-demo.html">
 <link rel="qrx" type="application/json" href="/manifest.json">
 ```
@@ -142,6 +147,37 @@ declared flow.
 Applications decide what to do with discovered QRX flows.
+## New in 0.5.0
+Version `0.5.0` adds public HTTP `Link` header discovery.
+QRX can now discover flows from:
+* HTML `<link>` tags
+* HTTP `Link` response headers
+Example:
+```http
+Link: </qrx-demo/>; rel="qrx"; type="text/html"
+```
+HTTP `Link` header discovery lets a server expose QRX flows
+at the HTTP layer,
+without placing the QRX declaration inside the HTML source.
+HTTP header flows are returned before HTML flows.
+This is deterministic discovery order only.
+It is not ranking, priority, override, or deduplication.
+If the same flow appears in both HTTP headers and HTML,
+both flows are returned.
+QRX discovers recognized flows.
+Applications decide what to do with them.
 ## Install
 ```bash
@@ -164,6 +200,12 @@ console.log(result.flows);
 ```js
 [
+  {
+    flowType: "qrx",
+    rel: "qrx",
+    href: "https://example.com/qrx-demo/",
+    type: "text/html"
+  },
   {
     flowType: "feed",
     rel: "alternate",
@@ -233,7 +275,7 @@ const qrxFlows = selectFlowsByFlowType(
 ## Supported discovery methods
-Feed flow:
+Feed flow from HTML:
 ```html
 <link
@@ -242,21 +284,13 @@ Feed flow:
   href="/feed.xml">
 ```
-```html
-<link
-  rel="alternate"
-  type="application/atom+xml"
-  href="/atom.xml">
-```
+Feed flow from HTTP:
-```html
-<link
-  rel="alternate"
-  type="application/feed+json"
-  href="/feed.json">
+```http
+Link: </feed.xml>; rel="alternate"; type="application/rss+xml"
 ```
-QRX flow:
+QRX flow from HTML:
 ```html
 <link
@@ -265,6 +299,12 @@ QRX flow:
   href="/qrx.json">
 ```
+QRX flow from HTTP:
+```http
+Link: </qrx-demo/>; rel="qrx"; type="text/html"
+```
 ## Philosophy
 QRX does not change QR codes.

package/dist/index.cjs CHANGED Viewed

@@ -20,7 +20,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  detectFlowCandidate: () => detectFlowCandidate,
   detectFlows: () => detectFlows,
+  detectFlowsFromLinkHeader: () => detectFlowsFromLinkHeader,
   resolveQRX: () => resolveQRX,
   selectFlowsByFlowType: () => selectFlowsByFlowType
 });
@@ -33,45 +35,101 @@ var FEED_TYPES = /* @__PURE__ */ new Set([
   "application/feed+json"
 ]);
 function detectFlows(html, sourceUrl) {
-  const flows = [];
+  const candidates = extractHtmlLinkCandidates(html);
+  return candidates.map(
+    (candidate) => detectFlowCandidate(candidate, sourceUrl)
+  ).filter((flow) => flow !== null);
+}
+function detectFlowsFromLinkHeader(linkHeader, sourceUrl) {
+  if (!linkHeader) {
+    return [];
+  }
+  const candidates = extractHttpLinkCandidates(linkHeader);
+  return candidates.map(
+    (candidate) => detectFlowCandidate(candidate, sourceUrl)
+  ).filter((flow) => flow !== null);
+}
+function detectFlowCandidate(candidate, sourceUrl) {
+  const { rel, type, href } = candidate;
+  if (!rel || !href) {
+    return null;
+  }
+  const normalizedRel = rel.trim();
+  if (!normalizedRel) {
+    return null;
+  }
+  const resolvedHref = new URL(
+    href,
+    sourceUrl
+  ).toString();
+  if (normalizedRel === "qrx") {
+    if (!type) {
+      return null;
+    }
+    return {
+      flowType: "qrx",
+      rel: normalizedRel,
+      href: resolvedHref,
+      type: type.trim().toLowerCase()
+    };
+  }
+  if (!type) {
+    return null;
+  }
+  const normalizedType = type.trim().toLowerCase();
+  if (!hasRel(normalizedRel, "alternate")) {
+    return null;
+  }
+  if (!FEED_TYPES.has(normalizedType)) {
+    return null;
+  }
+  return {
+    flowType: "feed",
+    rel: normalizedRel,
+    href: resolvedHref,
+    type: normalizedType
+  };
+}
+function extractHtmlLinkCandidates(html) {
   const linkTagRegex = /<link\s+[^>]*>/gi;
   const tags = html.match(linkTagRegex) || [];
-  for (const tag of tags) {
-    const rel = getAttribute(tag, "rel");
-    const type = getAttribute(tag, "type");
-    const href = getAttribute(tag, "href");
-    if (!rel || !type || !href) {
-      continue;
-    }
-    const normalizedRel = rel.trim();
-    const normalizedType = type.trim().toLowerCase();
-    const resolvedHref = new URL(
-      href,
-      sourceUrl
-    ).toString();
-    if (normalizedRel === "qrx") {
-      flows.push({
-        flowType: "qrx",
-        rel: normalizedRel,
-        href: resolvedHref,
-        type: normalizedType
-      });
-      continue;
-    }
-    if (!hasRel(normalizedRel, "alternate")) {
-      continue;
+  return tags.map((tag) => ({
+    rel: getAttribute(tag, "rel"),
+    type: getAttribute(tag, "type"),
+    href: getAttribute(tag, "href")
+  }));
+}
+function extractHttpLinkCandidates(linkHeader) {
+  return splitLinkHeader(linkHeader).map(parseHttpLinkValue).filter(
+    (candidate) => candidate !== null
+  );
+}
+function parseHttpLinkValue(value) {
+  const hrefMatch = value.match(/^\s*<([^>]+)>/);
+  if (!hrefMatch) {
+    return null;
+  }
+  const candidate = {
+    href: hrefMatch[1],
+    rel: null,
+    type: null
+  };
+  const paramRegex = /;\s*([a-zA-Z][a-zA-Z0-9_-]*)\s*=\s*"([^"]*)"/g;
+  let match;
+  while ((match = paramRegex.exec(value)) !== null) {
+    const name = match[1].toLowerCase();
+    const paramValue = match[2];
+    if (name === "rel") {
+      candidate.rel = paramValue;
     }
-    if (!FEED_TYPES.has(normalizedType)) {
-      continue;
+    if (name === "type") {
+      candidate.type = paramValue;
     }
-    flows.push({
-      flowType: "feed",
-      rel: normalizedRel,
-      href: resolvedHref,
-      type: normalizedType
-    });
   }
-  return flows;
+  return candidate;
+}
+function splitLinkHeader(linkHeader) {
+  return linkHeader.split(/,\s*(?=<)/).map((part) => part.trim()).filter(Boolean);
 }
 function getAttribute(tag, attribute) {
   const regex = new RegExp(
@@ -88,13 +146,21 @@ function hasRel(rel, expected) {
 // src/resolve.ts
 async function resolveQRX(url) {
   const response = await fetch(url);
+  const sourceUrl = response.url;
+  const headerFlows = detectFlowsFromLinkHeader(
+    response.headers.get("link"),
+    sourceUrl
+  );
   const html = await response.text();
-  const flows = detectFlows(
+  const htmlFlows = detectFlows(
     html,
-    response.url
+    sourceUrl
   );
   return {
-    flows
+    flows: [
+      ...headerFlows,
+      ...htmlFlows
+    ]
   };
 }
@@ -108,7 +174,9 @@ function selectFlowsByFlowType(flows, preferredFlowTypes) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  detectFlowCandidate,
   detectFlows,
+  detectFlowsFromLinkHeader,
   resolveQRX,
   selectFlowsByFlowType
 });

package/dist/index.d.cts CHANGED Viewed

@@ -9,10 +9,17 @@ interface QRXResult {
     flows: Flow[];
 }
+interface LinkCandidate {
+    rel: string | null;
+    href: string | null;
+    type: string | null;
+}
 declare function detectFlows(html: string, sourceUrl: string): Flow[];
+declare function detectFlowsFromLinkHeader(linkHeader: string | null, sourceUrl: string): Flow[];
+declare function detectFlowCandidate(candidate: LinkCandidate, sourceUrl: string): Flow | null;
 declare function resolveQRX(url: string): Promise<QRXResult>;
 declare function selectFlowsByFlowType(flows: Flow[], preferredFlowTypes: FlowType[]): Flow[];
-export { type Flow, type FlowType, type QRXResult, detectFlows, resolveQRX, selectFlowsByFlowType };
+export { type Flow, type FlowType, type QRXResult, detectFlowCandidate, detectFlows, detectFlowsFromLinkHeader, resolveQRX, selectFlowsByFlowType };

package/dist/index.d.ts CHANGED Viewed

@@ -9,10 +9,17 @@ interface QRXResult {
     flows: Flow[];
 }
+interface LinkCandidate {
+    rel: string | null;
+    href: string | null;
+    type: string | null;
+}
 declare function detectFlows(html: string, sourceUrl: string): Flow[];
+declare function detectFlowsFromLinkHeader(linkHeader: string | null, sourceUrl: string): Flow[];
+declare function detectFlowCandidate(candidate: LinkCandidate, sourceUrl: string): Flow | null;
 declare function resolveQRX(url: string): Promise<QRXResult>;
 declare function selectFlowsByFlowType(flows: Flow[], preferredFlowTypes: FlowType[]): Flow[];
-export { type Flow, type FlowType, type QRXResult, detectFlows, resolveQRX, selectFlowsByFlowType };
+export { type Flow, type FlowType, type QRXResult, detectFlowCandidate, detectFlows, detectFlowsFromLinkHeader, resolveQRX, selectFlowsByFlowType };

package/dist/index.js CHANGED Viewed

@@ -5,45 +5,101 @@ var FEED_TYPES = /* @__PURE__ */ new Set([
   "application/feed+json"
 ]);
 function detectFlows(html, sourceUrl) {
-  const flows = [];
+  const candidates = extractHtmlLinkCandidates(html);
+  return candidates.map(
+    (candidate) => detectFlowCandidate(candidate, sourceUrl)
+  ).filter((flow) => flow !== null);
+}
+function detectFlowsFromLinkHeader(linkHeader, sourceUrl) {
+  if (!linkHeader) {
+    return [];
+  }
+  const candidates = extractHttpLinkCandidates(linkHeader);
+  return candidates.map(
+    (candidate) => detectFlowCandidate(candidate, sourceUrl)
+  ).filter((flow) => flow !== null);
+}
+function detectFlowCandidate(candidate, sourceUrl) {
+  const { rel, type, href } = candidate;
+  if (!rel || !href) {
+    return null;
+  }
+  const normalizedRel = rel.trim();
+  if (!normalizedRel) {
+    return null;
+  }
+  const resolvedHref = new URL(
+    href,
+    sourceUrl
+  ).toString();
+  if (normalizedRel === "qrx") {
+    if (!type) {
+      return null;
+    }
+    return {
+      flowType: "qrx",
+      rel: normalizedRel,
+      href: resolvedHref,
+      type: type.trim().toLowerCase()
+    };
+  }
+  if (!type) {
+    return null;
+  }
+  const normalizedType = type.trim().toLowerCase();
+  if (!hasRel(normalizedRel, "alternate")) {
+    return null;
+  }
+  if (!FEED_TYPES.has(normalizedType)) {
+    return null;
+  }
+  return {
+    flowType: "feed",
+    rel: normalizedRel,
+    href: resolvedHref,
+    type: normalizedType
+  };
+}
+function extractHtmlLinkCandidates(html) {
   const linkTagRegex = /<link\s+[^>]*>/gi;
   const tags = html.match(linkTagRegex) || [];
-  for (const tag of tags) {
-    const rel = getAttribute(tag, "rel");
-    const type = getAttribute(tag, "type");
-    const href = getAttribute(tag, "href");
-    if (!rel || !type || !href) {
-      continue;
-    }
-    const normalizedRel = rel.trim();
-    const normalizedType = type.trim().toLowerCase();
-    const resolvedHref = new URL(
-      href,
-      sourceUrl
-    ).toString();
-    if (normalizedRel === "qrx") {
-      flows.push({
-        flowType: "qrx",
-        rel: normalizedRel,
-        href: resolvedHref,
-        type: normalizedType
-      });
-      continue;
-    }
-    if (!hasRel(normalizedRel, "alternate")) {
-      continue;
+  return tags.map((tag) => ({
+    rel: getAttribute(tag, "rel"),
+    type: getAttribute(tag, "type"),
+    href: getAttribute(tag, "href")
+  }));
+}
+function extractHttpLinkCandidates(linkHeader) {
+  return splitLinkHeader(linkHeader).map(parseHttpLinkValue).filter(
+    (candidate) => candidate !== null
+  );
+}
+function parseHttpLinkValue(value) {
+  const hrefMatch = value.match(/^\s*<([^>]+)>/);
+  if (!hrefMatch) {
+    return null;
+  }
+  const candidate = {
+    href: hrefMatch[1],
+    rel: null,
+    type: null
+  };
+  const paramRegex = /;\s*([a-zA-Z][a-zA-Z0-9_-]*)\s*=\s*"([^"]*)"/g;
+  let match;
+  while ((match = paramRegex.exec(value)) !== null) {
+    const name = match[1].toLowerCase();
+    const paramValue = match[2];
+    if (name === "rel") {
+      candidate.rel = paramValue;
     }
-    if (!FEED_TYPES.has(normalizedType)) {
-      continue;
+    if (name === "type") {
+      candidate.type = paramValue;
     }
-    flows.push({
-      flowType: "feed",
-      rel: normalizedRel,
-      href: resolvedHref,
-      type: normalizedType
-    });
   }
-  return flows;
+  return candidate;
+}
+function splitLinkHeader(linkHeader) {
+  return linkHeader.split(/,\s*(?=<)/).map((part) => part.trim()).filter(Boolean);
 }
 function getAttribute(tag, attribute) {
   const regex = new RegExp(
@@ -60,13 +116,21 @@ function hasRel(rel, expected) {
 // src/resolve.ts
 async function resolveQRX(url) {
   const response = await fetch(url);
+  const sourceUrl = response.url;
+  const headerFlows = detectFlowsFromLinkHeader(
+    response.headers.get("link"),
+    sourceUrl
+  );
   const html = await response.text();
-  const flows = detectFlows(
+  const htmlFlows = detectFlows(
     html,
-    response.url
+    sourceUrl
   );
   return {
-    flows
+    flows: [
+      ...headerFlows,
+      ...htmlFlows
+    ]
   };
 }
@@ -79,7 +143,9 @@ function selectFlowsByFlowType(flows, preferredFlowTypes) {
   );
 }
 export {
+  detectFlowCandidate,
   detectFlows,
+  detectFlowsFromLinkHeader,
   resolveQRX,
   selectFlowsByFlowType
 };

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@qrxcode/js",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "QRX flow discovery SDK for JavaScript.",
   "homepage": "https://qrx.dev",
   "repository": {