@vdaluz/astro-affiliate 1.0.0 → 1.1.0

package/README.md

@@ -149,9 +149,10 @@ fails with a clear error - there's no way to ship an affiliate link without its
 The plugin also writes the post's own catalog keys, in document order with duplicates removed,
 to `affiliateKeys` in the page's frontmatter - useful for a consumer that wants to know "which
 catalog items did this post actually link to" without re-parsing markdown (e.g. to seed a
-related-products widget from a post's own links before falling back to other sources). It's
-`undefined`, not an empty array, on a post with no affiliate links - read it as
-`affiliateKeys ?? []`. Access it via Astro's `remarkPluginFrontmatter`:
+related-products widget from a post's own links before falling back to other sources - see
+[Affiliate cards](#affiliate-cards-resolveaffiliatecards) for a ready-made resolver that does
+exactly this). It's `undefined`, not an empty array, on a post with no affiliate links - read it
+as `affiliateKeys ?? []`. Access it via Astro's `remarkPluginFrontmatter`:
 
 ```astro
 ---
@@ -208,7 +209,8 @@ see [Per-app glue](#per-app-glue) for the token variables this assumes.
 
 ### Localized disclosure text
 
-A program's `disclosure` accepts either a plain string or a `Localized` value - `{ default: string, [locale]: string }` - for sites publishing in more than one language:
+A program's `disclosure` accepts either a plain string or a `Localized` value (import it as a
+type: `import type { Localized } from '@vdaluz/astro-affiliate'`) - `{ default: string, [locale]: string }` - for sites publishing in more than one language:
 
 ```ts
 programs: {
@@ -229,6 +231,74 @@ Pass `locale` to `<AffiliateDisclosure>` to select the matching entry; it falls
 <AffiliateDisclosure config={affiliate} affiliates={affiliates} locale={locale} />
 ```
 
+### Disclosure text outside `.astro` (RSS, exports, plain text)
+
+`<AffiliateDisclosure>` only works inside an `.astro` page. For anything that needs the same
+disclosure text as plain strings - an RSS item description, a channel-export pipeline, a
+plain-text newsletter - call `resolveDisclosures` directly:
+
+```ts
+import { resolveDisclosures } from '@vdaluz/astro-affiliate';
+import { affiliate } from '../config/affiliate';
+
+const disclosures = resolveDisclosures(affiliate, entry.data.affiliates ?? [], locale);
+```
+
+It returns the resolved text for each program name in order (see [Localized disclosure
+text](#localized-disclosure-text) for how `locale` selects between entries), and throws if any
+name isn't a program declared in `config.programs` - the same guarantee `<AffiliateDisclosure>`
+relies on internally, so a plain-text consumer can't silently drop a disclosure for a typo'd
+program name.
+
+## Affiliate cards (`resolveAffiliateCards`)
+
+A related-affiliate-products widget for the end of a post. `resolveAffiliateCards` is a plain
+data function - the package ships no rendering component for it, so each consuming app owns its
+own card display component (see [Per-app glue](#per-app-glue)):
+
+```astro
+---
+import { resolveAffiliateCards } from '@vdaluz/astro-affiliate';
+import { getAffiliateCardDisplay, getGenericKeys } from '../config/affiliate-cards';
+import AffiliateCards from '../components/AffiliateCards.astro';
+
+const { remarkPluginFrontmatter } = await render(entry);
+const affiliateCardEntries = resolveAffiliateCards({
+  postKeys: remarkPluginFrontmatter.affiliateKeys ?? [],
+  postCategory: entry.data.category,
+  postSlug: stripLocalePrefix(entry.id),
+  display: getAffiliateCardDisplay(locale),
+  generic: getGenericKeys(entry.data.category),
+});
+---
+
+<AffiliateCards entries={affiliateCardEntries} />
+```
+
+Resolves up to 3 entries per post, in priority order:
+
+1. The post's own `affiliate:` links (from `affiliateKeys`, see [Markdown
+   links](#markdown-links-remarkaffiliate)), in document order - never randomized, since these
+   are real editorial choices.
+2. Category-matched entries from `display` (matched on `postCategories`), shuffled with a PRNG
+   seeded from `postSlug`, filling every remaining slot except the last one.
+3. The last remaining slot: leftover category matches from (2) plus the `generic` always-eligible
+   defaults, pooled together and shuffled with the same seeded PRNG. This applies even when the
+   category pool alone could have filled every remaining slot - a category with several matches
+   can still yield a generic default in the mix, by design.
+
+Deduplicates by key across all three tiers, so a post inlining a key that's also a category match
+or generic default only shows it once.
+
+`postSlug` seeds the shuffle deterministically - the same post always resolves to the same card
+set across rebuilds, so it must be **locale-independent** (strip any locale prefix, e.g.
+`stripLocalePrefix(entry.id)`) or the same post's translations will land on different combinations
+instead of sharing one.
+
+`display` (a `Record<string, AffiliateCardDisplay>` keyed by catalog key) and `generic` (an array
+of always-eligible catalog keys) are both required, not defaulted - the package stays data-free by
+design, since a shared package should never bake in a consumer's own catalog/display data.
+
 ## Per-app glue
 
 This is a component library, not a drop-in catalog. Each consuming app owns:
@@ -239,11 +309,27 @@ This is a component library, not a drop-in catalog. Each consuming app owns:
 - Token CSS variables referenced by the default disclosure styling: `muted`. See
   [`@vdaluz/astro-blog`'s `tokens.example.css`](https://github.com/vdaluz/astro-blog) for the
   full token set these sites already share.
+- Its own card display map and rendering component for [Affiliate
+  cards](#affiliate-cards-resolveaffiliatecards) - `resolveAffiliateCards` returns data only.
 
 ## Contributing
 
 Issues welcome. PRs by discussion - open an issue first for anything beyond a typo or docs fix.
 
+### Releasing
+
+Maintainer-only. Releases are tag-triggered and published to npm via GitHub Actions (Trusted
+Publishing / OIDC, no token secret):
+
+1. Test before tagging: `npm pack`, install the tarball into a scratch Astro app (or a consumer
+   locally), `astro check && astro build`.
+2. Bump `version` in `package.json`, commit.
+3. Tag `vX.Y.Z` and push the tag. Pushing the tag runs `.github/workflows/publish.yml`, which
+   type-checks, tests, verifies the tag matches `package.json`'s version, and only then runs
+   `npm publish`.
+4. Confirm the version is live: `npm view @vdaluz/astro-affiliate version`. Consumers bump their
+   own semver pin once it's confirmed live - see this package's CHANGELOG.md for what changed.
+
 ## Consumers
 
 - [vdaluz.com](https://vdaluz.com)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vdaluz/astro-affiliate",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "FTC-compliant affiliate-link catalog resolver and disclosure components - proven in production on vdaluz.com and imperfectsystems.com.",
   "keywords": [
     "astro",

package/src/index.ts

@@ -2,6 +2,7 @@ export { defineAffiliateConfig } from './lib/config.ts';
 export { resolveAffiliate } from './lib/resolve.ts';
 export { buildChannelRewriteMap, rewriteAffiliateLinksForChannel } from './lib/channel-rewrite.ts';
 export { resolveAffiliateCards } from './lib/affiliate-cards.ts';
+export { resolveDisclosures } from './lib/disclosures.ts';
 export type {
   AffiliateConfig,
   AffiliateProgram,
@@ -12,6 +13,7 @@ export type {
   CatalogEntryLink,
   ResolvedAffiliate,
 } from './lib/types.ts';
+export type { Localized } from './lib/i18n.ts';
 export type {
   AffiliateCardDisplay,
   AffiliateCardEntry,

package/src/lib/affiliate-cards.ts

@@ -21,9 +21,8 @@ export interface ResolveAffiliateCardsInput {
   postSlug: string;
   /** Display data for every catalog key eligible to appear as a card, keyed
    * by the same catalog key used in the consumer's affiliate.ts. Required,
-   * not defaulted - this package stays data-free by design (see AST-36's
-   * cancellation for why a shared package should never bake in a consumer's
-   * own catalog/display data). */
+   * not defaulted - this package stays data-free by design, since a shared
+   * package should never bake in a consumer's own catalog/display data. */
   display: Record<string, AffiliateCardDisplay>;
   /** Always-eligible last-resort fill tier, as catalog keys into `display`. */
   generic: string[];

package/src/lib/channel-rewrite.ts

@@ -31,16 +31,30 @@ export function buildChannelRewriteMap(config: AffiliateConfig, channel: string)
   return map;
 }
 
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
 /**
  * Rewrites already-rendered content (e.g. a prerendered post's HTML) to swap
- * default-channel affiliate URLs for a specific channel's URLs. Exact
- * string replacement per catalog entry, not a generic regex over "tag=" or
- * similar - safe against matching unrelated content.
+ * default-channel affiliate URLs for a specific channel's URLs. Exact string
+ * matching per catalog entry (each default URL escaped into a regex
+ * alternative), not a generic regex over "tag=" or similar - safe against
+ * matching unrelated content.
+ *
+ * A single regex pass, not one split/join per entry: sequential passes
+ * re-scan each other's output, so a shorter default URL that happens to be a
+ * prefix of another entry's default OR channel URL would corrupt an already-
+ * rewritten result on a later pass. One pass never re-scans a replacement.
+ * Alternatives are ordered longest-first because regex alternation is
+ * first-match-wins at a given position, not longest-match-wins - without the
+ * ordering a shorter prefix could still win the match before the longer
+ * alternative gets a chance.
  */
 export function rewriteAffiliateLinksForChannel(content: string, config: AffiliateConfig, channel: string): string {
   const map = buildChannelRewriteMap(config, channel);
-  return Object.entries(map).reduce(
-    (result, [defaultUrl, channelUrl]) => result.split(defaultUrl).join(channelUrl),
-    content
-  );
+  const defaultUrls = Object.keys(map).sort((a, b) => b.length - a.length);
+  if (defaultUrls.length === 0) return content;
+  const pattern = new RegExp(defaultUrls.map(escapeRegExp).join('|'), 'g');
+  return content.replace(pattern, (matched) => map[matched]);
 }

package/src/lib/remark.ts

@@ -22,7 +22,11 @@ interface VFileWithAstroFrontmatter {
 }
 
 function collectAffiliateLinkNodes(node: MdastNode, out: MdastNode[]) {
-  if (node.type === 'link' && typeof node.url === 'string' && node.url.startsWith(AFFILIATE_PREFIX)) {
+  if (
+    (node.type === 'link' || node.type === 'definition') &&
+    typeof node.url === 'string' &&
+    node.url.startsWith(AFFILIATE_PREFIX)
+  ) {
     out.push(node);
   }
   if (node.children) {
@@ -30,6 +34,26 @@ function collectAffiliateLinkNodes(node: MdastNode, out: MdastNode[]) {
   }
 }
 
+/**
+ * Last-resort guard: after rewriting every node `collectAffiliateLinkNodes`
+ * found, walk the whole tree once more for any node that still carries an
+ * `affiliate:`-prefixed `url` - a node type the collector doesn't know about
+ * (e.g. an image `![alt](affiliate:key)`). Unresolvable is a build failure
+ * here just like an unknown catalog key, so this must run even when the
+ * collector found nothing - that zero-nodes-collected case is exactly the
+ * shape of the reference-link bug this plugin exists to prevent.
+ */
+function assertNoRemainingAffiliateUrls(node: MdastNode) {
+  if (typeof node.url === 'string' && node.url.startsWith(AFFILIATE_PREFIX)) {
+    throw new Error(
+      `Unrewritten affiliate link "${node.url}" remains in the tree on a "${node.type}" node - collectAffiliateLinkNodes doesn't handle this node type yet.`
+    );
+  }
+  if (node.children) {
+    for (const child of node.children) assertNoRemainingAffiliateUrls(child);
+  }
+}
+
 /**
  * Remark plugin: rewrites `[text](affiliate:catalogKey)` links to their real
  * resolved URL at build time, and enforces FTC compliance by construction -
@@ -41,6 +65,8 @@ function collectAffiliateLinkNodes(node: MdastNode, out: MdastNode[]) {
  * duplicates removed, to `affiliateKeys` in the page's frontmatter (via
  * `remarkPluginFrontmatter`) - undefined, not an empty array, on a post with
  * no affiliate links, so a consumer should read it as `affiliateKeys ?? []`.
+ * For a reference-style link (`[text][ref]`), "document order" follows the
+ * position of the `[ref]: affiliate:key` definition, not the in-prose usage.
  *
  *   import { remarkAffiliate } from '@vdaluz/astro-affiliate/remark';
  *
@@ -52,7 +78,11 @@ export function remarkAffiliate(config: AffiliateConfig) {
   return (tree: MdastNode, file: VFileWithAstroFrontmatter) => {
     const linkNodes: MdastNode[] = [];
     collectAffiliateLinkNodes(tree, linkNodes);
-    if (linkNodes.length === 0) return;
+
+    if (linkNodes.length === 0) {
+      assertNoRemainingAffiliateUrls(tree);
+      return;
+    }
 
     const declaredAffiliates = file.data?.astro?.frontmatter?.affiliates ?? [];
     const usedPrograms = new Set<string>();
@@ -78,5 +108,7 @@ export function remarkAffiliate(config: AffiliateConfig) {
     file.data.astro ??= {};
     file.data.astro.frontmatter ??= {};
     file.data.astro.frontmatter.affiliateKeys = usedKeys;
+
+    assertNoRemainingAffiliateUrls(tree);
   };
 }