@vdaluz/astro-affiliate 0.6.0 → 0.8.0

package/README.md

@@ -15,7 +15,7 @@ Alternatively, a pinned https tarball from a tag works too, with no registry inv
 ```jsonc
 // package.json
 "dependencies": {
-  "@vdaluz/astro-affiliate": "https://github.com/vdaluz/astro-affiliate/archive/refs/tags/v0.6.0.tar.gz"
+  "@vdaluz/astro-affiliate": "https://github.com/vdaluz/astro-affiliate/archive/refs/tags/v0.7.0.tar.gz"
 }
 ```
 
@@ -159,6 +159,20 @@ fails the build. **Compliance by construction:** every program actually used by
 links in a post must be declared in that post's `affiliates:` frontmatter array, or the build
 fails with a clear error - there's no way to ship an affiliate link without its disclosure.
 
+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`:
+
+```astro
+---
+const { remarkPluginFrontmatter } = await render(entry);
+const usedKeys = remarkPluginFrontmatter.affiliateKeys ?? [];
+---
+```
+
 ## `.astro` pages (`<AffiliateLink>`)
 
 For gear pages or other non-markdown content:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vdaluz/astro-affiliate",
-  "version": "0.6.0",
+  "version": "0.8.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

@@ -1,6 +1,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 type {
   AffiliateConfig,
   AffiliateProgram,
@@ -11,3 +12,8 @@ export type {
   CatalogEntryLink,
   ResolvedAffiliate,
 } from './lib/types.ts';
+export type {
+  AffiliateCardDisplay,
+  AffiliateCardEntry,
+  ResolveAffiliateCardsInput,
+} from './lib/affiliate-cards.ts';

package/src/lib/affiliate-cards.ts

@@ -0,0 +1,136 @@
+export interface AffiliateCardDisplay {
+  name: string;
+  blurb: string;
+  /** Root-relative image path. Optional - a card with no image just renders without one. */
+  image?: string;
+  postCategories?: string[];
+}
+
+export interface AffiliateCardEntry {
+  key: string;
+  display: AffiliateCardDisplay;
+}
+
+export interface ResolveAffiliateCardsInput {
+  /** The post's own affiliate:key links, in document order (see remarkAffiliate's affiliateKeys). */
+  postKeys: string[];
+  postCategory: string;
+  /** Locale-independent post identifier - seeds the deterministic shuffle so a
+   * post shows the same cards on every rebuild and in every locale, while
+   * different posts land on different combinations. */
+  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). */
+  display: Record<string, AffiliateCardDisplay>;
+  /** Always-eligible last-resort fill tier, as catalog keys into `display`. */
+  generic: string[];
+}
+
+const MAX_CARDS = 3;
+
+function hashString(value: string): number {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < value.length; i++) {
+    hash ^= value.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return hash >>> 0;
+}
+
+/** mulberry32 - small deterministic PRNG seeded from a 32-bit int. */
+function mulberry32(seed: number): () => number {
+  let state = seed;
+  return () => {
+    state |= 0;
+    state = (state + 0x6d2b79f5) | 0;
+    let t = Math.imul(state ^ (state >>> 15), 1 | state);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+function shuffle<T>(items: T[], rng: () => number): T[] {
+  const result = [...items];
+  for (let i = result.length - 1; i > 0; i--) {
+    const j = Math.floor(rng() * (i + 1));
+    [result[i], result[j]] = [result[j], result[i]];
+  }
+  return result;
+}
+
+/**
+ * Resolves exactly up to MAX_CARDS entries for a post, in priority order:
+ *
+ * 1. The post's own inline links, in document order (first MAX_CARDS if it has
+ *    more than that) - never randomized, these are real editorial choices.
+ * 2. Category-matched catalog items, shuffled with a PRNG seeded from postSlug,
+ *    filling every remaining slot except the last one.
+ * 3. The last remaining slot: any category-matched items left over 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 still yields
+ *    a generic default in the mix sometimes, by design.
+ *
+ * Deduplicates by catalog key across all tiers, so a post inlining a key that's
+ * also a category match or generic default only shows it once.
+ *
+ * The shuffle is deterministic per postSlug: the same post always resolves to
+ * the same card set across rebuilds and locales, but different posts in the
+ * same category land on different combinations.
+ *
+ * Side-effect-free and consumer-config-free by design - the piece meant to be
+ * shared across every site that wants this behavior, with display/generic
+ * data supplied by each consumer's own config.
+ */
+export function resolveAffiliateCards({
+  postKeys,
+  postCategory,
+  postSlug,
+  display,
+  generic,
+}: ResolveAffiliateCardsInput): AffiliateCardEntry[] {
+  const seen = new Set<string>();
+  const result: AffiliateCardEntry[] = [];
+  const rng = mulberry32(hashString(postSlug));
+
+  function tryAdd(key: string) {
+    if (result.length >= MAX_CARDS || seen.has(key)) return;
+    const entry = display[key];
+    if (!entry) return;
+    seen.add(key);
+    result.push({ key, display: entry });
+  }
+
+  for (const key of postKeys) {
+    if (result.length >= MAX_CARDS) break;
+    tryAdd(key);
+  }
+
+  if (result.length < MAX_CARDS) {
+    const categoryCandidates = shuffle(
+      Object.entries(display)
+        .filter(([key, entry]) => !seen.has(key) && entry.postCategories?.includes(postCategory))
+        .map(([key]) => key),
+      rng
+    );
+
+    const slotsRemaining = MAX_CARDS - result.length;
+    const categoryOnlySlots = Math.max(0, slotsRemaining - 1);
+    for (const key of categoryCandidates.slice(0, categoryOnlySlots)) tryAdd(key);
+
+    if (result.length < MAX_CARDS) {
+      const leftoverCategoryCandidates = categoryCandidates.slice(categoryOnlySlots);
+      const genericCandidates = generic.filter((key) => !seen.has(key));
+      const finalPool = shuffle([...leftoverCategoryCandidates, ...genericCandidates], rng);
+      for (const key of finalPool) {
+        if (result.length >= MAX_CARDS) break;
+        tryAdd(key);
+      }
+    }
+  }
+
+  return result;
+}

package/src/lib/remark.ts

@@ -15,6 +15,7 @@ interface VFileWithAstroFrontmatter {
     astro?: {
       frontmatter?: {
         affiliates?: string[];
+        affiliateKeys?: string[];
       };
     };
   };
@@ -36,6 +37,11 @@ function collectAffiliateLinkNodes(node: MdastNode, out: MdastNode[]) {
  * `affiliates:` frontmatter (so `<AffiliateDisclosure>` knows to render it).
  * An unknown key, or a used program missing from frontmatter, fails the build.
  *
+ * Also writes the post's own affiliate catalog keys, in document order with
+ * 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 ?? []`.
+ *
  *   import { remarkAffiliate } from '@vdaluz/astro-affiliate/remark';
  *
  *   export default defineConfig({
@@ -50,12 +56,14 @@ export function remarkAffiliate(config: AffiliateConfig) {
 
     const declaredAffiliates = file.data?.astro?.frontmatter?.affiliates ?? [];
     const usedPrograms = new Set<string>();
+    const usedKeys: string[] = [];
 
     for (const node of linkNodes) {
       const key = node.url!.slice(AFFILIATE_PREFIX.length);
       const { url, program } = resolveAffiliate(config, key);
       node.url = url;
       usedPrograms.add(program);
+      if (!usedKeys.includes(key)) usedKeys.push(key);
     }
 
     for (const program of usedPrograms) {
@@ -65,5 +73,10 @@ export function remarkAffiliate(config: AffiliateConfig) {
         );
       }
     }
+
+    file.data ??= {};
+    file.data.astro ??= {};
+    file.data.astro.frontmatter ??= {};
+    file.data.astro.frontmatter.affiliateKeys = usedKeys;
   };
 }