@qrxcode/js 0.2.0 → 0.4.0

package/README.md

@@ -29,9 +29,8 @@ and natural as following someone on social media.
 
 Examples of flows:
 
-- RSS feeds
-- Atom feeds
-- JSON feeds
+- Feed flows
+- QRX flows
 
 In QRX, a "flow" is a recognized machine-readable relationship
 that applications can discover and interact with.
@@ -42,41 +41,107 @@ QRX helps applications discover and work with them more naturally.
 
 Learn more at https://qrx.dev
 
-## Breaking change in 0.2.0
+## Breaking change in 0.3.0
 
-Version `0.2.0` introduces a breaking cleanup of the flow output model.
+Version `0.3.0` introduced a breaking cleanup of feed flow classification.
 
-Before `0.2.0`, flow objects looked like this:
+Before `0.3.0`, RSS, Atom, and JSON Feed were represented as separate
+QRX flow types:
 
 ```js
 {
-  type: "rss",
-  url: "https://example.com/feed.xml"
+  flowType: "rss",
+  rel: "alternate",
+  href: "https://example.com/feed.xml",
+  type: "application/rss+xml"
 }
 ````
 
-Starting from `0.2.0`, flow objects look like this:
+Starting from `0.3.0`, RSS, Atom, and JSON Feed are represented as the same
+QRX flow category:
 
 ```js
 {
-  flowType: "rss",
+  flowType: "feed",
   rel: "alternate",
   href: "https://example.com/feed.xml",
   type: "application/rss+xml"
 }
 ```
 
-Migration:
+The actual feed format remains in the original HTML/link media type:
+
+```js
+type: "application/rss+xml"
+type: "application/atom+xml"
+type: "application/feed+json"
+```
 
-* `flow.type` used to mean QRX flow classification.
-* QRX flow classification is now `flow.flowType`.
-* `flow.type` now means the original HTML/link media type.
-* `flow.url` is now `flow.href`.
+Core formula:
 
-QRX now separates QRX flow classification from original web metadata.
+```txt
+flowType = QRX category
+type = original web/media format
+```
+
+Migration:
+
+* `flow.flowType === "rss"` is now `flow.flowType === "feed" && flow.type === "application/rss+xml"`.
+* `flow.flowType === "atom"` is now `flow.flowType === "feed" && flow.type === "application/atom+xml"`.
+* `flow.flowType === "jsonfeed"` is now `flow.flowType === "feed" && flow.type === "application/feed+json"`.
 
 QRX discovers recognized flows. Applications decide what to do with them.
 
+## New in 0.4.0
+
+Version `0.4.0` adds a new flow category:
+
+```js
+flowType: "qrx"
+```
+
+A QRX flow is discovered from an explicit HTML `<link>` declaration:
+
+```html
+<link
+  rel="qrx"
+  type="application/qrx+json"
+  href="/qrx.json">
+```
+
+QRX flow discovery requires all of these:
+
+* `rel="qrx"`
+* `href`
+* explicit `type`
+
+For `qrx` flows, `rel` must be exactly `qrx`.
+
+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="application/json" href="/manifest.json">
+```
+
+These are not valid QRX flow declarations:
+
+```html
+<link rel="alternate qrx" type="application/qrx+json" href="/qrx.json">
+<link rel="qrx something" type="application/qrx+json" href="/qrx.json">
+<link rel="notqrx" type="application/qrx+json" href="/qrx.json">
+<link rel="qrx" href="/qrx.json">
+```
+
+The `type` value can be any explicit media type, not only
+`application/qrx+json`.
+
+The package does not fetch or parse QRX payloads. It only discovers the
+declared flow.
+
+Applications decide what to do with discovered QRX flows.
+
 ## Install
 
 ```bash
@@ -89,7 +154,7 @@ npm install @qrxcode/js
 import { resolveQRX } from "@qrxcode/js";
 
 const result = await resolveQRX(
-  "https://podnews.net"
+  "https://example.com"
 );
 
 console.log(result.flows);
@@ -100,28 +165,76 @@ console.log(result.flows);
 ```js
 [
   {
-    flowType: "rss",
+    flowType: "feed",
     rel: "alternate",
-    href: "https://podnews.net/rss",
+    href: "https://example.com/feed.xml",
     type: "application/rss+xml"
   },
   {
-    flowType: "jsonfeed",
-    rel: "alternate",
-    href: "https://podnews.net/feed.json",
-    type: "application/feed+json"
+    flowType: "qrx",
+    rel: "qrx",
+    href: "https://example.com/qrx.json",
+    type: "application/qrx+json"
   }
 ]
 ```
 
+## Selecting flows
+
+To select all feed flows:
+
+```js
+import {
+  resolveQRX,
+  selectFlowsByFlowType
+} from "@qrxcode/js";
+
+const result = await resolveQRX(
+  "https://example.com"
+);
+
+const feeds = selectFlowsByFlowType(
+  result.flows,
+  ["feed"]
+);
+```
+
+This returns RSS, Atom, and JSON Feed flows together.
+
+To select only RSS feeds, filter by the original media type:
+
+```js
+const rssFeeds = result.flows.filter(
+  (discoveredFlow) =>
+    discoveredFlow.flowType === "feed" &&
+    discoveredFlow.type === "application/rss+xml"
+);
+```
+
+To select QRX flows:
+
+```js
+const qrxFlows = selectFlowsByFlowType(
+  result.flows,
+  ["qrx"]
+);
+```
+
 ## Supported flow types
 
-* RSS
-* Atom
-* JSON Feed
+* feed
+* qrx
+
+## Supported feed formats
+
+* RSS: `application/rss+xml`
+* Atom: `application/atom+xml`
+* JSON Feed: `application/feed+json`
 
 ## Supported discovery methods
 
+Feed flow:
+
 ```html
 <link
   rel="alternate"
@@ -143,9 +256,22 @@ console.log(result.flows);
   href="/feed.json">
 ```
 
+QRX flow:
+
+```html
+<link
+  rel="qrx"
+  type="application/qrx+json"
+  href="/qrx.json">
+```
+
 ## Philosophy
 
 QRX does not change QR codes.
 
+QRX discovers recognized flows.
+
+Applications decide what to do with them.
+
 With QRX, sources can expose machine-readable flows,
 and applications can understand and interact with them naturally.

package/dist/index.cjs

@@ -27,11 +27,11 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/detect.ts
-var FLOW_TYPES = {
-  "application/rss+xml": "rss",
-  "application/atom+xml": "atom",
-  "application/feed+json": "jsonfeed"
-};
+var FEED_TYPES = /* @__PURE__ */ new Set([
+  "application/rss+xml",
+  "application/atom+xml",
+  "application/feed+json"
+]);
 function detectFlows(html, sourceUrl) {
   const flows = [];
   const linkTagRegex = /<link\s+[^>]*>/gi;
@@ -45,17 +45,29 @@ function detectFlows(html, sourceUrl) {
     }
     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;
     }
-    const flowType = FLOW_TYPES[normalizedType];
-    if (!flowType) {
+    if (!FEED_TYPES.has(normalizedType)) {
       continue;
     }
     flows.push({
-      flowType,
+      flowType: "feed",
       rel: normalizedRel,
-      href: new URL(href, sourceUrl).toString(),
+      href: resolvedHref,
       type: normalizedType
     });
   }

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-type FlowType = "rss" | "atom" | "jsonfeed";
+type FlowType = "feed" | "qrx";
 interface Flow {
     flowType: FlowType;
     rel: string;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-type FlowType = "rss" | "atom" | "jsonfeed";
+type FlowType = "feed" | "qrx";
 interface Flow {
     flowType: FlowType;
     rel: string;

package/dist/index.js

@@ -1,9 +1,9 @@
 // src/detect.ts
-var FLOW_TYPES = {
-  "application/rss+xml": "rss",
-  "application/atom+xml": "atom",
-  "application/feed+json": "jsonfeed"
-};
+var FEED_TYPES = /* @__PURE__ */ new Set([
+  "application/rss+xml",
+  "application/atom+xml",
+  "application/feed+json"
+]);
 function detectFlows(html, sourceUrl) {
   const flows = [];
   const linkTagRegex = /<link\s+[^>]*>/gi;
@@ -17,17 +17,29 @@ function detectFlows(html, sourceUrl) {
     }
     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;
     }
-    const flowType = FLOW_TYPES[normalizedType];
-    if (!flowType) {
+    if (!FEED_TYPES.has(normalizedType)) {
       continue;
     }
     flows.push({
-      flowType,
+      flowType: "feed",
       rel: normalizedRel,
-      href: new URL(href, sourceUrl).toString(),
+      href: resolvedHref,
       type: normalizedType
     });
   }

package/package.json

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