@molecule/api-feed-rss 1.0.1 → 1.0.3

package/LICENSE

@@ -1,3 +1,4 @@
+
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
@@ -34,21 +35,33 @@
 
       "Work" shall mean the work of authorship, whether in Source or
       Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work.
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
 
       "Derivative Works" shall mean any work, whether in Source or Object
       form, that is based on (or derived from) the Work and for which the
       editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship.
-
-      "Contribution" shall mean any work of authorship, including the
-      original version of the Work and any modifications or additions
-      to that Work, that is intentionally submitted to the Licensor for
-      inclusion in the Work by the copyright owner or by an individual or
-      Legal Entity authorized to submit on behalf of the copyright owner.
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
 
       "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by the Licensor and
+      on behalf of whom a Contribution has been received by Licensor and
       subsequently incorporated within the Work.
 
    2. Grant of Copyright License. Subject to the terms and conditions of
@@ -61,8 +74,18 @@
    3. Grant of Patent License. Subject to the terms and conditions of
       this License, each Contributor hereby grants to You a perpetual,
       worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      patent license to make, have made, use, offer to sell, sell, import,
-      and otherwise transfer the Work.
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
 
    4. Redistribution. You may reproduce and distribute copies of the
       Work or Derivative Works thereof in any medium, with or without
@@ -84,23 +107,87 @@
       (d) If the Work includes a "NOTICE" text file as part of its
           distribution, then any Derivative Works that You distribute must
           include a readable copy of the attribution notices contained
-          within such NOTICE file.
-
-   5. Submission of Contributions.
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
 
    6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor.
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
 
    7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
-
-   8. Limitation of Liability. In no event and under no legal theory shall
-      any Contributor be liable to You for damages.
-
-   9. Accepting Warranty or Additional Liability.
-
-   Copyright 2026 Molecule Dev, Inc.
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/README.md

@@ -3,15 +3,11 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-08-04T00:36:30.162Z
+Generated: 2026-10-16T23:29:38.981Z
 -->
 
 # @molecule/api-feed-rss
 
-> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
-> It is written to be read by coding agents as much as by people, and is generated from this
-> package's source — edit `src/index.ts` JSDoc, not this file.
-
 RSS / Atom / JSON Feed **producer** for molecule.dev — pure-function
 serializers that turn a single normalized {@link Feed} structure into
 a valid RSS 2.0, Atom 1.0, or JSON Feed 1.1 document.
@@ -27,6 +23,10 @@ Apps that use this:
 - `news-aggregator` — re-publish curated cross-source feeds.
 - `podcast` — RSS 2.0 with the iTunes namespace (set `feed.itunes`).
 
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
 ## Quick Start
 
 One serializer per call
@@ -132,72 +132,78 @@ interface CreateFeedHandlerOptions {
 }
 ```
 
-#### `Feed`
+#### `FeedRequest`
 
-Feed-level metadata + items, format-agnostic input shape consumed by
-every serializer.
+Minimal request shape consumed by the generated handler.
 
 ```typescript
-interface Feed {
-  /** Channel / feed title. Required. */
-  title: string
-
-  /** Canonical website URL (NOT the feed self-link). Required. */
-  link: string
+interface FeedRequest {
+  /**
+   * URL extension portion — `'rss'`, `'atom'`, `'json'`, or any custom key
+   * the caller wired in {@link CreateFeedHandlerOptions.extensions}.
+   *
+   * Callers compute this from the request URL (e.g.
+   * `req.path.split('.').pop()` for Express).
+   */
+  extension: string
 
-  /** Long-form description / subtitle / tagline. Required by RSS 2.0. */
-  description: string
+  /** Optional `If-None-Match` ETag value, for 304 short-circuiting. */
+  ifNoneMatch?: string
+}
+```
 
-  /** Self-referential URL of the feed document. Recommended for Atom + JSON Feed. */
-  feedUrl?: string
+#### `FeedResponse`
 
-  /** RFC 5646 / BCP 47 language tag (e.g. `en`, `en-US`). */
-  language?: string
+Minimal response shape returned by the handler. Framework adapters map
+this onto their native response API (`res.status().set().send()` for
+Express, `new Response(body, { status, headers })` for fetch, etc.).
 
-  /** ISO 8601 / `Date` of the feed's last update. Defaults to "now" for Atom. */
-  updatedAt?: string | Date
+```typescript
+interface FeedResponse {
+  /** HTTP status code: `200` / `304` / `404` / `503`. */
+  status: number
 
-  /** Channel author(s). */
-  authors?: FeedAuthor[]
+  /** Headers — always includes `Content-Type` on `200`. */
+  headers: Record<string, string>
 
-  /** Copyright / rights statement. */
-  copyright?: string
+  /** Body — empty string on `304` / `404` / errors. */
+  body: string
+}
+```
 
-  /** Channel image / logo / icon URL. */
-  imageUrl?: string
+#### `FeedItemItunes`
 
-  /** Channel-level categories (RSS only). */
-  categories?: string[]
+Optional iTunes podcast metadata for an item.
 
-  /**
-   * Channel-level iTunes podcast metadata. Presence of this field switches
-   * the RSS 2.0 serializer into "podcast mode" — it declares
-   * `xmlns:itunes` and emits per-item `<itunes:*>` elements.
-   */
-  itunes?: FeedChannelItunes
+When supplied AND the channel-level {@link Feed.itunes} block is also
+present, the RSS 2.0 serializer emits the iTunes podcast namespace
+(`xmlns:itunes="http://www.itunes.com/dtds/podcast-1.0.dtd"`) and per-item
+`<itunes:duration>`, `<itunes:author>`, `<itunes:explicit>`,
+`<itunes:image>`, `<itunes:episode>`, `<itunes:season>`, `<itunes:summary>`
+elements.
 
-  /** Items in display order. The serializer does not re-sort by date. */
-  items: FeedItem[]
-}
-```
+```typescript
+interface FeedItemItunes {
+  /** Episode duration in seconds. Serialized as HH:MM:SS. */
+  durationSeconds?: number
 
-#### `FeedAuthor`
+  /** Episode artwork URL. Emitted as `<itunes:image href="...">`. */
+  imageUrl?: string
 
-Author of a feed or item.
+  /** Author display name (overrides item-level `<itunes:author>`). */
+  author?: string
 
-```typescript
-interface FeedAuthor {
-  /** Display name. Required for Atom; optional everywhere else. */
-  name: string
+  /** Whether the episode contains explicit material. */
+  explicit?: boolean
 
-  /** Author email address. Optional. */
-  email?: string
+  /** Episode number within the season / series. */
+  episode?: number
 
-  /** Author profile / homepage URL. Optional. */
-  url?: string
+  /** Season number. */
+  season?: number
 
-  /** Avatar URL (JSON Feed only). */
-  avatarUrl?: string
+  /** Plain-text episode summary (`<itunes:summary>`). */
+  summary?: string
 }
 ```
 
@@ -242,6 +248,52 @@ interface FeedChannelItunes {
 }
 ```
 
+#### `FeedItemEnclosure`
+
+Media enclosure (podcast audio, video, image, etc.).
+
+```typescript
+interface FeedItemEnclosure {
+  /** Direct URL to the media resource. Required. */
+  url: string
+
+  /**
+   * MIME type. Required by RSS 2.0 spec — defaults to
+   * `application/octet-stream` when omitted.
+   */
+  type?: string
+
+  /** Length in bytes. Required by RSS 2.0 spec — defaults to `0` when omitted. */
+  length?: number
+
+  /** Display title or alt text. JSON Feed only. */
+  title?: string
+
+  /** Duration in seconds. Used by JSON Feed `attachments[].duration_in_seconds`. */
+  durationSeconds?: number
+}
+```
+
+#### `FeedAuthor`
+
+Author of a feed or item.
+
+```typescript
+interface FeedAuthor {
+  /** Display name. Required for Atom; optional everywhere else. */
+  name: string
+
+  /** Author email address. Optional. */
+  email?: string
+
+  /** Author profile / homepage URL. Optional. */
+  url?: string
+
+  /** Avatar URL (JSON Feed only). */
+  avatarUrl?: string
+}
+```
+
 #### `FeedItem`
 
 A single feed item / entry / post.
@@ -299,104 +351,65 @@ interface FeedItem {
 }
 ```
 
-#### `FeedItemEnclosure`
+#### `Feed`
 
-Media enclosure (podcast audio, video, image, etc.).
+Feed-level metadata + items, format-agnostic input shape consumed by
+every serializer.
 
 ```typescript
-interface FeedItemEnclosure {
-  /** Direct URL to the media resource. Required. */
-  url: string
-
-  /**
-   * MIME type. Required by RSS 2.0 spec — defaults to
-   * `application/octet-stream` when omitted.
-   */
-  type?: string
+interface Feed {
+  /** Channel / feed title. Required. */
+  title: string
 
-  /** Length in bytes. Required by RSS 2.0 spec — defaults to `0` when omitted. */
-  length?: number
+  /** Canonical website URL (NOT the feed self-link). Required. */
+  link: string
 
-  /** Display title or alt text. JSON Feed only. */
-  title?: string
+  /** Long-form description / subtitle / tagline. Required by RSS 2.0. */
+  description: string
 
-  /** Duration in seconds. Used by JSON Feed `attachments[].duration_in_seconds`. */
-  durationSeconds?: number
-}
-```
+  /** Self-referential URL of the feed document. Recommended for Atom + JSON Feed. */
+  feedUrl?: string
 
-#### `FeedItemItunes`
+  /** RFC 5646 / BCP 47 language tag (e.g. `en`, `en-US`). */
+  language?: string
 
-Optional iTunes podcast metadata for an item.
+  /** ISO 8601 / `Date` of the feed's last update. Defaults to "now" for Atom. */
+  updatedAt?: string | Date
 
-When supplied AND the channel-level {@link Feed.itunes} block is also
-present, the RSS 2.0 serializer emits the iTunes podcast namespace
-(`xmlns:itunes="http://www.itunes.com/dtds/podcast-1.0.dtd"`) and per-item
-`<itunes:duration>`, `<itunes:author>`, `<itunes:explicit>`,
-`<itunes:image>`, `<itunes:episode>`, `<itunes:season>`, `<itunes:summary>`
-elements.
+  /** Channel author(s). */
+  authors?: FeedAuthor[]
 
-```typescript
-interface FeedItemItunes {
-  /** Episode duration in seconds. Serialized as HH:MM:SS. */
-  durationSeconds?: number
+  /** Copyright / rights statement. */
+  copyright?: string
 
-  /** Episode artwork URL. Emitted as `<itunes:image href="...">`. */
+  /** Channel image / logo / icon URL. */
   imageUrl?: string
 
-  /** Author display name (overrides item-level `<itunes:author>`). */
-  author?: string
-
-  /** Whether the episode contains explicit material. */
-  explicit?: boolean
-
-  /** Episode number within the season / series. */
-  episode?: number
-
-  /** Season number. */
-  season?: number
-
-  /** Plain-text episode summary (`<itunes:summary>`). */
-  summary?: string
-}
-```
-
-#### `FeedRequest`
-
-Minimal request shape consumed by the generated handler.
+  /** Channel-level categories (RSS only). */
+  categories?: string[]
 
-```typescript
-interface FeedRequest {
   /**
-   * URL extension portion — `'rss'`, `'atom'`, `'json'`, or any custom key
-   * the caller wired in {@link CreateFeedHandlerOptions.extensions}.
-   *
-   * Callers compute this from the request URL (e.g.
-   * `req.path.split('.').pop()` for Express).
+   * Channel-level iTunes podcast metadata. Presence of this field switches
+   * the RSS 2.0 serializer into "podcast mode" — it declares
+   * `xmlns:itunes` and emits per-item `<itunes:*>` elements.
    */
-  extension: string
+  itunes?: FeedChannelItunes
 
-  /** Optional `If-None-Match` ETag value, for 304 short-circuiting. */
-  ifNoneMatch?: string
+  /** Items in display order. The serializer does not re-sort by date. */
+  items: FeedItem[]
 }
 ```
 
-#### `FeedResponse`
+#### `SerializeRss2Options`
 
-Minimal response shape returned by the handler. Framework adapters map
-this onto their native response API (`res.status().set().send()` for
-Express, `new Response(body, { status, headers })` for fetch, etc.).
+Options controlling {@link serializeRss2}.
 
 ```typescript
-interface FeedResponse {
-  /** HTTP status code: `200` / `304` / `404` / `503`. */
-  status: number
-
-  /** Headers — always includes `Content-Type` on `200`. */
-  headers: Record<string, string>
-
-  /** Body — empty string on `304` / `404` / errors. */
-  body: string
+interface SerializeRss2Options {
+  /** XML declaration. Defaults to `<?xml version="1.0" encoding="UTF-8"?>`. */
+  xmlDeclaration?: string
+  /** Pretty-print with 2-space indentation. Defaults to `true`. */
+  pretty?: boolean
 }
 ```
 
@@ -424,19 +437,6 @@ interface SerializeJsonFeedOptions {
 }
 ```
 
-#### `SerializeRss2Options`
-
-Options controlling {@link serializeRss2}.
-
-```typescript
-interface SerializeRss2Options {
-  /** XML declaration. Defaults to `<?xml version="1.0" encoding="UTF-8"?>`. */
-  xmlDeclaration?: string
-  /** Pretty-print with 2-space indentation. Defaults to `true`. */
-  pretty?: boolean
-}
-```
-
 ### Types
 
 #### `FeedOutputFormat`
@@ -460,49 +460,65 @@ Error raised when the {@link Feed} input fails minimum-viability checks
 (missing required `title` / `link` / `description`, missing item `id` or
 `title`, etc.).
 
+```typescript
+class FeedSerializeError extends Error {
+  /** Output format hint at the point of failure, if known. */
+  format?: FeedOutputFormat
+
+  constructor(message: string, format?: FeedOutputFormat) {
+    super(message)
+    this.name = 'FeedSerializeError'
+    this.format = format
+  }
+}
+```
+
 ### Functions
 
-#### `assertFeedShape(feed, format)`
+#### `escapeXml(value)`
 
-Validate {@link Feed} input has the minimum required fields for the
-given output format.
+Escape a string for inclusion in an XML text node or attribute value.
+
+Maps the five XML predefined entities:
+
+- `&` → `&amp;`
+- `<` → `&lt;`
+- `>` → `&gt;`
+- `"` → `&quot;`
+- `'` → `&apos;`
+
+Also strips XML 1.0 illegal control characters (`U+0000`–`U+0008`,
+`U+000B`, `U+000C`, `U+000E`–`U+001F`). `\t`, `\n`, `\r` are preserved.
 
 ```typescript
-function assertFeedShape(feed: Feed, format: FeedOutputFormat): void
+function escapeXml(value: string | number | boolean | null | undefined): string
 ```
 
-- `feed` — Feed input.
-- `format` — Target serialization format.
-
-#### `createFeedHandler(options)`
+- `value` — Raw string. `undefined` / `null` collapse to `''`.
 
-Create a framework-agnostic feed HTTP handler with built-in TTL caching.
+**Returns:** Escaped string safe for any XML position.
 
-The returned handler accepts a {@link FeedRequest} and returns a
-{@link FeedResponse}. It serves three formats by default — RSS 2.0,
-Atom 1.0, JSON Feed — keyed by URL extension.
+#### `wrapCdata(value)`
 
-**Caching** — feed payloads are cached per-format for `cacheTtlMs`
-(default 1 minute). Each cache entry carries an ETag computed from the
-payload hash; matching `If-None-Match` triggers a `304` response.
+Wrap an HTML payload in a `<![CDATA[ ... ]]>` section, splitting any
+accidental closing-marker (`]]>`) inside the payload across two CDATA
+sections so the result remains valid XML.
 
-**Error handling** — if `loadFeed` throws, the handler returns `503`
-with body `''`. The error is forwarded to `onError` if provided.
+Use for `<description>` / `<content:encoded>` / Atom `<content type="html">`
+where the body is HTML and we want to avoid double-escaping.
 
-**No XSS surface** — all interpolation runs through the underlying
-serializers (`serializeRss2` / `serializeAtom1` / `serializeJsonFeed`),
-which escape every user-supplied field. The handler itself never
-concatenates request data into the response body.
+Also strips XML 1.0 illegal control characters before wrapping (`\t`,
+`\n`, `\r` preserved). The CDATA payload still cannot contain raw
+`<![CDATA[` openers, but those are not produced by typical HTML and
+any literal occurrence is treated as ordinary text by browsers.
 
 ```typescript
-function createFeedHandler(
-  options: CreateFeedHandlerOptions,
-): (req: FeedRequest) => Promise<FeedResponse>
+function wrapCdata(value: string | null | undefined): string
 ```
 
-- `options` — See {@link CreateFeedHandlerOptions}.
+- `value` — Raw HTML / text. `undefined` / `null` collapse to `''`.
 
-**Returns:** Async handler function `(req: FeedRequest) => Promise<FeedResponse>`.
+**Returns:** A complete CDATA section, e.g. `<![CDATA[<p>x</p>]]>`.
 
 #### `escapeAttr(value)`
 
@@ -535,54 +551,35 @@ function escapeUrl(value: string | null | undefined): string
 
 **Returns:** Escaped URL or `'about:blank'` for disallowed schemes.
 
-#### `escapeXml(value)`
-
-Escape a string for inclusion in an XML text node or attribute value.
-
-Maps the five XML predefined entities:
-
-- `&` → `&amp;`
-- `<` → `&lt;`
-- `>` → `&gt;`
-- `"` → `&quot;`
-- `'` → `&apos;`
-
-Also strips XML 1.0 illegal control characters (`U+0000`–`U+0008`,
-`U+000B`, `U+000C`, `U+000E`–`U+001F`). `\t`, `\n`, `\r` are preserved.
-
-```typescript
-function escapeXml(value: string | number | boolean | null | undefined): string
-```
-
-- `value` — Raw string. `undefined` / `null` collapse to `''`.
-
-**Returns:** Escaped string safe for any XML position.
-
-#### `indent(body, pad)`
-
-Indent each newline of `body` by `pad` spaces. Used for pretty-printing.
+#### `createFeedHandler(options)`
 
-```typescript
-function indent(body: string, pad: number): string
-```
+Create a framework-agnostic feed HTTP handler with built-in TTL caching.
 
-- `body` — Multi-line text. Empty input returns empty string.
-- `pad` — Number of spaces to prepend to each line.
+The returned handler accepts a {@link FeedRequest} and returns a
+{@link FeedResponse}. It serves three formats by default — RSS 2.0,
+Atom 1.0, JSON Feed — keyed by URL extension.
 
-**Returns:** Indented text.
+**Caching** — feed payloads are cached per-format for `cacheTtlMs`
+(default 1 minute). Each cache entry carries an ETag computed from the
+payload hash; matching `If-None-Match` triggers a `304` response.
 
-#### `looksLikeHttpUrl(value)`
+**Error handling** — if `loadFeed` throws, the handler returns `503`
+with body `''`. The error is forwarded to `onError` if provided.
 
-Whether a string looks like an HTTP(S) URL — used to set
-`<guid isPermaLink>` and to fall back to `link` for `<id>` synthesis.
+**No XSS surface** — all interpolation runs through the underlying
+serializers (`serializeRss2` / `serializeAtom1` / `serializeJsonFeed`),
+which escape every user-supplied field. The handler itself never
+concatenates request data into the response body.
 
 ```typescript
-function looksLikeHttpUrl(value: string | null | undefined): boolean
+function createFeedHandler(
+  options: CreateFeedHandlerOptions,
+): (req: FeedRequest) => Promise<FeedResponse>
 ```
 
-- `value` — Candidate string.
+- `options` — See {@link CreateFeedHandlerOptions}.
 
-**Returns:** `true` if the value parses as `http:` or `https:` URL.
+**Returns:** Async handler function `(req: FeedRequest) => Promise<FeedResponse>`.
 
 #### `serializeAtom1(feed, options)`
 
@@ -670,20 +667,6 @@ function serializeRss2(feed: Feed, options?: SerializeRss2Options): string
 
 **Returns:** Complete RSS 2.0 XML document string.
 
-#### `toHhMmSs(seconds)`
-
-Format a duration in seconds as `HH:MM:SS`, used for `<itunes:duration>`.
-
-Returns `undefined` for non-finite or negative input.
-
-```typescript
-function toHhMmSs(seconds: number | null | undefined): string | undefined
-```
-
-- `seconds` — Whole or fractional seconds.
-
-**Returns:** `HH:MM:SS` string or `undefined`.
-
 #### `toIso(value)`
 
 Coerce a `Date` / ISO string / arbitrary string into an ISO 8601 string.
@@ -716,27 +699,57 @@ function toRfc822(value: string | Date | null | undefined): string | undefined
 
 **Returns:** RFC 822 timestamp (`Mon, 28 Apr 2026 15:00:00 GMT`) or `undefined`.
 
-#### `wrapCdata(value)`
+#### `toHhMmSs(seconds)`
 
-Wrap an HTML payload in a `<![CDATA[ ... ]]>` section, splitting any
-accidental closing-marker (`]]>`) inside the payload across two CDATA
-sections so the result remains valid XML.
+Format a duration in seconds as `HH:MM:SS`, used for `<itunes:duration>`.
 
-Use for `<description>` / `<content:encoded>` / Atom `<content type="html">`
-where the body is HTML and we want to avoid double-escaping.
+Returns `undefined` for non-finite or negative input.
 
-Also strips XML 1.0 illegal control characters before wrapping (`\t`,
-`\n`, `\r` preserved). The CDATA payload still cannot contain raw
-`<![CDATA[` openers, but those are not produced by typical HTML and
-any literal occurrence is treated as ordinary text by browsers.
+```typescript
+function toHhMmSs(seconds: number | null | undefined): string | undefined
+```
+
+- `seconds` — Whole or fractional seconds.
+
+**Returns:** `HH:MM:SS` string or `undefined`.
+
+#### `assertFeedShape(feed, format)`
+
+Validate {@link Feed} input has the minimum required fields for the
+given output format.
 
 ```typescript
-function wrapCdata(value: string | null | undefined): string
+function assertFeedShape(feed: Feed, format: FeedOutputFormat): void
 ```
 
-- `value` — Raw HTML / text. `undefined` / `null` collapse to `''`.
+- `feed` — Feed input.
+- `format` — Target serialization format.
 
-**Returns:** A complete CDATA section, e.g. `<![CDATA[<p>x</p>]]>`.
+#### `indent(body, pad)`
+
+Indent each newline of `body` by `pad` spaces. Used for pretty-printing.
+
+```typescript
+function indent(body: string, pad: number): string
+```
+
+- `body` — Multi-line text. Empty input returns empty string.
+- `pad` — Number of spaces to prepend to each line.
+
+**Returns:** Indented text.
+
+#### `looksLikeHttpUrl(value)`
+
+Whether a string looks like an HTTP(S) URL — used to set
+`<guid isPermaLink>` and to fall back to `link` for `<id>` synthesis.
+
+```typescript
+function looksLikeHttpUrl(value: string | null | undefined): boolean
+```
+
+- `value` — Candidate string.
+
+**Returns:** `true` if the value parses as `http:` or `https:` URL.
 
 ### Constants
 

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@molecule/api-feed-rss",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "RSS/Atom/JSON Feed producer — pure-function serializers for RSS 2.0, Atom 1.0, JSON Feed 1.1; emits valid XML/JSON with full XML escaping and CDATA wrapping. Includes optional HTTP handler factory.",
+  "homepage": "https://www.molecule.dev/packages/api-feed-rss",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -37,9 +38,9 @@
     "directory": "packages/api/utilities/feed-rss"
   },
   "devDependencies": {
-    "@molecule/api-feed-rss-parser": "1.0.1",
-    "@types/node": "26.1.2",
+    "@molecule/api-feed-rss-parser": "1.0.3",
+    "@types/node": "26.6.5",
     "typescript": "6.0.3",
-    "vitest": "4.1.10"
+    "vitest": "4.1.12"
   }
 }