@vdaluz/astro-affiliate 0.5.1 → 0.7.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.5.1.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:
@@ -176,6 +190,15 @@ import { affiliate } from '../config/affiliate';
 
 Renders `target="_blank" rel="noopener noreferrer sponsored"` by default. Pass `class` to style it, or `channel` to target a per-channel tag/link (see [Per-channel tags](#per-channel-tags-reposts-syndication)) - falls back to the program's default when omitted or unconfigured for that channel.
 
+### Click tracking
+
+`<AffiliateLink>` renders `data-affiliate-key`, `data-affiliate-channel` (omitted when no `channel`
+prop is passed), and `data-affiliate-program` on the anchor. This package emits no click events
+itself - it's a data-attribute contract a consumer's own analytics wiring can read. See
+[`@vdaluz/astro-opt-in-analytics`'s README](https://github.com/vdaluz/astro-opt-in-analytics#affiliate-click-tracking)
+for `bindAffiliateClickTracking()`, which reads these attributes and reports an `affiliate-click`
+event once analytics consent is granted.
+
 ## Disclosure (`<AffiliateDisclosure>`)
 
 Render at the **top** of the post body, above any affiliate links (FTC: disclosure before links,

package/package.json

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

package/src/components/AffiliateLink.astro

@@ -12,9 +12,17 @@ interface Props {
 }
 
 const { config, affiliateKey, channel, class: className } = Astro.props;
-const { url } = resolveAffiliate(config, affiliateKey, channel);
+const { url, program } = resolveAffiliate(config, affiliateKey, channel);
 ---
 
-<a href={url} target="_blank" rel="noopener noreferrer sponsored" class={className}>
+<a
+  href={url}
+  target="_blank"
+  rel="noopener noreferrer sponsored"
+  class={className}
+  data-affiliate-key={affiliateKey}
+  data-affiliate-channel={channel}
+  data-affiliate-program={program}
+>
   <slot />
 </a>

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;
   };
 }