@vdaluz/astro-affiliate 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Victor Da Luz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,249 @@
+# @vdaluz/astro-affiliate
+
+[![CI](https://github.com/vdaluz/astro-affiliate/actions/workflows/ci.yml/badge.svg)](https://github.com/vdaluz/astro-affiliate/actions/workflows/ci.yml)
+
+Affiliate links need FTC-compliant disclosure, per-channel tracking tags for reposts and syndication, and a way to keep the two in sync so a disclosure can't silently drift from the links it's supposed to cover. `@vdaluz/astro-affiliate` is a catalog resolver and disclosure component pair that enforces that link: the remark plugin fails the build if a post uses an affiliate link without declaring its program in frontmatter. Ships raw `.astro` and `.ts` - the consuming app's Astro/Vite compiles them (no prebuild step). Machinery only: the package carries no affiliate data itself, each site supplies its own catalog, tracking tags, and disclosure text via config. Proven in production on [vdaluz.com](https://vdaluz.com) and [imperfectsystems.com](https://imperfectsystems.com) - see [Consumers](#consumers).
+
+## Install
+
+Pinned https tarball from a tag (no registry needed):
+
+```jsonc
+// package.json
+"dependencies": {
+  "@vdaluz/astro-affiliate": "https://github.com/vdaluz/astro-affiliate/archive/refs/tags/v0.4.0.tar.gz"
+}
+```
+
+> **Why a tarball, not `github:vdaluz/astro-affiliate#v0.2.0`?** npm canonicalizes GitHub
+> shorthand (and even an explicit `git+https://` URL) to `git+ssh://` in the lockfile.
+> CI runners (e.g. Cloudflare Pages/Workers) have no SSH key, so `npm ci` would fail to
+> clone it. The `/archive/refs/tags/<tag>.tar.gz` URL is anonymous https with an integrity
+> hash in the lockfile, it just works in CI. Bump the tag in the URL to upgrade. This is the
+> only supported install path; there's no npm registry package (tag-tarball works for anyone,
+> no registry auth needed).
+
+Peer dependency: `astro` >= 6.
+
+## Define your config
+
+Two top-level pieces: `programs` (disclosure text + how to resolve a program's links) and
+`catalog` (a single flat list of every item, each pointing at the program that resolves it).
+
+```ts
+// src/config/affiliate.ts
+import { defineAffiliateConfig } from '@vdaluz/astro-affiliate';
+
+export const affiliate = defineAffiliateConfig({
+  programs: {
+    amazon: {
+      kind: 'amazon',
+      tag: 'vdaluz-20',
+      disclosure: 'As an Amazon Associate, I earn from qualifying purchases.',
+    },
+    proton: {
+      kind: 'links',
+      disclosure: 'As a Proton Partner, I earn from qualifying purchases.',
+      links: { pass: 'https://go.getproton.me/SH2FI' },
+    },
+  },
+  catalog: {
+    atomicHabits: { program: 'amazon', asin: 'B07RFSSYBH' },
+    protonPass: { program: 'proton', link: 'pass' },
+  },
+});
+```
+
+Two program kinds:
+
+- **`amazon`** - supply a site tag once; catalog entries reference it with just an ASIN. The URL
+  is constructed as `https://<domain>/dp/<ASIN>/ref=nosim?tag=<tag>`, where `domain` defaults to
+  `www.amazon.com`. For a locale-specific marketplace (e.g. Brazil), declare a second `amazon`-kind
+  program with its own `domain` and `tag`, and point locale-specific catalog entries at it:
+
+  ```ts
+  programs: {
+    amazon: { kind: 'amazon', tag: 'vdaluz-20', disclosure: '...' },
+    amazonBr: { kind: 'amazon', domain: 'www.amazon.com.br', tag: 'vdaluz-br-20', disclosure: '...' },
+  },
+  catalog: {
+    atomicHabits: { program: 'amazon', asin: 'B07RFSSYBH' },
+    atomicHabitsBr: { program: 'amazonBr', asin: 'B07RFSSYBH' },
+  },
+  ```
+- **`links`** - a flat link-key-to-URL map on the program; catalog entries reference one of those
+  keys.
+
+Catalog keys are flat and unprefixed (`atomicHabits`, not `amazon.atomicHabits`) - that's what
+markdown links and `<AffiliateLink>` use directly. Each entry accepts an optional `category`
+string, ignored by resolution, for a consuming app's own filtering (e.g. a gear page listing only
+`category: 'gear'` entries).
+
+## Per-channel tags (reposts, syndication)
+
+A program can declare a different tag/link for a named channel - e.g. a distinct Amazon tracking
+ID for content republished to Medium, so Associates reporting can tell channel traffic apart from
+the canonical site (Amazon's own tracking IDs exist for exactly this: up to 100 per account,
+independently reportable):
+
+```ts
+programs: {
+  amazon: {
+    kind: 'amazon',
+    tag: 'vdaluz-20',
+    channelTags: { medium: 'vdaluz-medium-20' },
+    disclosure: '...',
+  },
+  proton: {
+    kind: 'links',
+    disclosure: '...',
+    links: { pass: 'https://go.getproton.me/SH2FI' },
+    channelLinks: { medium: { pass: 'https://go.getproton.me/MEDIUM' } },
+  },
+},
+```
+
+A channel not listed in `channelTags`/`channelLinks` falls back to the program's default - passing
+an unconfigured channel is a no-op, not an error.
+
+Two ways to consume a channel, depending on where the affiliate link lives:
+
+- **`resolveAffiliate(config, key, channel)`** - pass the channel directly when resolving at
+  request/render time (e.g. inside a non-prerendered `.astro` page or component).
+- **`rewriteAffiliateLinksForChannel(content, config, channel)`** - for content whose affiliate
+  links were already resolved to the default channel at build time (markdown `affiliate:key` links
+  compiled once via `remarkAffiliate`, baked into a prerendered page). Retargets the rendered
+  output after the fact - via a middleware, an edge function, or whatever else drives the specific
+  repost flow - by exact string substitution of each catalog entry's default URL, not a generic
+  regex, so it can't accidentally touch unrelated content. `buildChannelRewriteMap(config, channel)`
+  exposes the underlying default-URL -> channel-URL map directly, for callers that want to do their
+  own substitution.
+
+## Markdown links (`remarkAffiliate`)
+
+Wire the plugin into `astro.config.mjs`:
+
+```js
+import { remarkAffiliate } from '@vdaluz/astro-affiliate/remark';
+import { affiliate } from './src/config/affiliate';
+
+export default defineConfig({
+  markdown: {
+    remarkPlugins: [[remarkAffiliate, affiliate]],
+  },
+});
+```
+
+> **Use the `[plugin, options]` tuple, not `remarkAffiliate(affiliate)` pre-invoked.** Astro/unified
+> calls the plugin function itself with the options; passing an already-invoked transformer means
+> unified calls *that* with no arguments as if it were the attacher, which silently no-ops instead
+> of rewriting anything - the build stays green with `affiliate:key` links left untouched in the
+> output. Always verify by checking rendered HTML for the real resolved URL, not just a passing
+> build.
+
+Then in a post's markdown body:
+
+```md
+---
+title: My post
+affiliates: [amazon]
+---
+
+I use [Atomic Habits](affiliate:atomicHabits) to stay on track.
+```
+
+`affiliate:atomicHabits` is rewritten to the real resolved URL at build time. An unknown key
+fails the build. **Compliance by construction:** every program actually used by `affiliate:`
+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.
+
+## `.astro` pages (`<AffiliateLink>`)
+
+For gear pages or other non-markdown content:
+
+```astro
+---
+import AffiliateLink from '@vdaluz/astro-affiliate/AffiliateLink.astro';
+import { affiliate } from '../config/affiliate';
+---
+
+<AffiliateLink config={affiliate} affiliateKey="atomicHabits">
+  Atomic Habits
+</AffiliateLink>
+```
+
+Renders `target="_blank" rel="noopener noreferrer sponsored"` by default. Pass `class` to style it.
+
+## Disclosure (`<AffiliateDisclosure>`)
+
+Render at the **top** of the post body, above any affiliate links (FTC: disclosure before links,
+above the fold):
+
+```astro
+---
+import AffiliateDisclosure from '@vdaluz/astro-affiliate/AffiliateDisclosure.astro';
+import { affiliate } from '../config/affiliate';
+
+const { affiliates = [] } = entry.data;
+---
+
+<AffiliateDisclosure config={affiliate} affiliates={affiliates} />
+```
+
+Renders one paragraph joining the disclosure text for every program in `affiliates`, or nothing
+if the array is empty. Default styling is `text-sm text-muted italic`; pass `class` to override,
+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:
+
+```ts
+programs: {
+  amazon: {
+    kind: 'amazon',
+    tag: 'vdaluz-20',
+    disclosure: {
+      default: 'As an Amazon Associate, I earn from qualifying purchases.',
+      es: 'Como Afiliado de Amazon, obtengo ingresos por las compras que califican.',
+    },
+  },
+},
+```
+
+Pass `locale` to `<AffiliateDisclosure>` to select the matching entry; it falls back to `default` when the given locale has no entry, or when `disclosure` is a plain string:
+
+```astro
+<AffiliateDisclosure config={affiliate} affiliates={affiliates} locale={locale} />
+```
+
+## Per-app glue
+
+This is a component library, not a drop-in catalog. Each consuming app owns:
+
+- Its own `affiliate` config (programs, catalog, tags, disclosure text). Nothing is shared across
+  sites.
+- The `affiliates:` field in its content collection schema (add `affiliates: z.array(z.string()).optional()`).
+- 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.
+
+## Release process
+
+Tag-pinned tarballs, no registry:
+
+1. Test before tagging: `npm pack`, install the tarball into a scratch Astro app (or one of the
+   consumers locally), `astro check && astro build`.
+2. Bump `version` in `package.json`, commit.
+3. Tag `vX.Y.Z` and push the tag. **The tag must be public before any consumer CI references
+   it**, the tarball URL 404s otherwise.
+4. Bump the tag in each consumer's `package.json` dependency URL.
+
+## Contributing
+
+Issues welcome. PRs by discussion - open an issue first for anything beyond a typo or docs fix.
+
+## Consumers
+
+- [vdaluz.com](https://vdaluz.com)
+- [imperfectsystems.com](https://imperfectsystems.com)

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@vdaluz/astro-affiliate",
+  "version": "0.5.0",
+  "description": "FTC-compliant affiliate-link catalog resolver and disclosure components - proven in production on vdaluz.com and imperfectsystems.com.",
+  "keywords": [
+    "astro",
+    "astro-component",
+    "affiliate-marketing",
+    "ftc-disclosure",
+    "amazon-associates"
+  ],
+  "homepage": "https://github.com/vdaluz/astro-affiliate#readme",
+  "bugs": {
+    "url": "https://github.com/vdaluz/astro-affiliate/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vdaluz/astro-affiliate.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "check": "astro check",
+    "test": "node --test"
+  },
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./remark": "./src/lib/remark.ts",
+    "./AffiliateLink.astro": "./src/components/AffiliateLink.astro",
+    "./AffiliateDisclosure.astro": "./src/components/AffiliateDisclosure.astro"
+  },
+  "peerDependencies": {
+    "astro": ">=6.0.0"
+  },
+  "devDependencies": {
+    "@astrojs/check": "^0.9.9",
+    "@types/node": "^26.1.1",
+    "astro": "^7.1.3",
+    "typescript": "^6.0.3"
+  }
+}

package/src/components/AffiliateDisclosure.astro

@@ -0,0 +1,22 @@
+---
+import type { AffiliateConfig } from '../lib/types';
+import { resolveDisclosures } from '../lib/disclosures';
+
+interface Props {
+  config: AffiliateConfig;
+  /** Post's `affiliates:` frontmatter array. */
+  affiliates: string[];
+  class?: string;
+  locale?: string;
+}
+
+const { config, affiliates, class: className, locale } = Astro.props;
+
+const disclosures = resolveDisclosures(config, affiliates, locale);
+---
+
+{
+  disclosures.length > 0 && (
+    <p class={className ?? 'text-sm text-muted italic'}>{disclosures.join(' ')}</p>
+  )
+}

package/src/components/AffiliateLink.astro

@@ -0,0 +1,18 @@
+---
+import type { AffiliateConfig } from '../lib/types';
+import { resolveAffiliate } from '../lib/resolve';
+
+interface Props {
+  config: AffiliateConfig;
+  /** Flat catalog key, e.g. 'atomicHabits'. */
+  affiliateKey: string;
+  class?: string;
+}
+
+const { config, affiliateKey, class: className } = Astro.props;
+const { url } = resolveAffiliate(config, affiliateKey);
+---
+
+<a href={url} target="_blank" rel="noopener noreferrer sponsored" class={className}>
+  <slot />
+</a>

package/src/index.ts

@@ -0,0 +1,13 @@
+export { defineAffiliateConfig } from './lib/config.ts';
+export { resolveAffiliate } from './lib/resolve.ts';
+export { buildChannelRewriteMap, rewriteAffiliateLinksForChannel } from './lib/channel-rewrite.ts';
+export type {
+  AffiliateConfig,
+  AffiliateProgram,
+  AffiliateProgramAmazon,
+  AffiliateProgramLinks,
+  CatalogEntry,
+  CatalogEntryAmazon,
+  CatalogEntryLink,
+  ResolvedAffiliate,
+} from './lib/types.ts';

package/src/lib/channel-rewrite.ts

@@ -0,0 +1,46 @@
+import type { AffiliateConfig } from './types.ts';
+import { resolveAffiliate } from './resolve.ts';
+
+/**
+ * Maps each catalog entry's default-resolved URL to its channel-specific URL,
+ * for every entry where the channel actually differs from default. Markdown
+ * `affiliate:key` links are resolved once at Astro build time via
+ * `remarkAffiliate`, so a repost target (Medium, or any future channel) can't
+ * get its own tag through a second compile - this map lets already-rendered
+ * content be retargeted after the fact instead.
+ *
+ * Rendered HTML escapes `&` as `&` in href attributes, so a default URL
+ * with an ampersand (any URL with more than one query param) never matches
+ * the raw map key in prerendered output. Add the HTML-escaped variant of
+ * each such entry too, mapped to the escaped channel URL, so substitution
+ * against real rendered HTML works regardless of query param count.
+ */
+export function buildChannelRewriteMap(config: AffiliateConfig, channel: string): Record<string, string> {
+  const map: Record<string, string> = {};
+  for (const key of Object.keys(config.catalog)) {
+    const defaultResolved = resolveAffiliate(config, key);
+    const channelResolved = resolveAffiliate(config, key, channel);
+    if (defaultResolved.url !== channelResolved.url) {
+      map[defaultResolved.url] = channelResolved.url;
+      const escapedDefault = defaultResolved.url.replace(/&/g, '&amp;');
+      if (escapedDefault !== defaultResolved.url) {
+        map[escapedDefault] = channelResolved.url.replace(/&/g, '&amp;');
+      }
+    }
+  }
+  return map;
+}
+
+/**
+ * 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.
+ */
+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
+  );
+}

package/src/lib/config.ts

@@ -0,0 +1,30 @@
+import type { AffiliateConfig } from './types.ts';
+
+/**
+ * Identity function for authoring a site's affiliate config with type checking
+ * and editor autocomplete. Use in the consuming app's affiliate config:
+ *
+ *   import { defineAffiliateConfig } from '@vdaluz/astro-affiliate';
+ *
+ *   export const affiliate = defineAffiliateConfig({
+ *     programs: {
+ *       amazon: {
+ *         kind: 'amazon',
+ *         tag: 'vdaluz-20',
+ *         disclosure: 'As an Amazon Associate, I earn from qualifying purchases.',
+ *       },
+ *       proton: {
+ *         kind: 'links',
+ *         disclosure: 'As a Proton Partner, I earn from qualifying purchases.',
+ *         links: { pass: 'https://go.getproton.me/SH2FI' },
+ *       },
+ *     },
+ *     catalog: {
+ *       atomicHabits: { program: 'amazon', asin: 'B07RFSSYBH' },
+ *       protonPass: { program: 'proton', link: 'pass' },
+ *     },
+ *   });
+ */
+export function defineAffiliateConfig(config: AffiliateConfig): AffiliateConfig {
+  return config;
+}

package/src/lib/disclosures.ts

@@ -0,0 +1,20 @@
+import type { AffiliateConfig } from './types.ts';
+import { resolveLocalized } from './i18n.ts';
+
+/**
+ * Resolves a post's `affiliates:` frontmatter names to their disclosure text.
+ * Throws on an unknown program name instead of silently omitting its
+ * disclosure - a typo'd/renamed program must fail the build, not ship a
+ * page that uses the program without disclosing it.
+ */
+export function resolveDisclosures(config: AffiliateConfig, affiliates: string[], locale?: string): string[] {
+  return affiliates.map((name) => {
+    const program = config.programs[name];
+    if (!program) {
+      throw new Error(
+        `Unknown affiliate program "${name}" in "affiliates:" frontmatter. Known programs: ${Object.keys(config.programs).join(', ') || '(none configured)'}.`
+      );
+    }
+    return resolveLocalized(program.disclosure, locale);
+  });
+}

package/src/lib/i18n.ts

@@ -0,0 +1,6 @@
+export type Localized = string | ({ default: string } & Record<string, string>);
+
+export function resolveLocalized(text: Localized, locale?: string): string {
+  if (typeof text === 'string') return text;
+  return (locale && text[locale]) || text.default;
+}

package/src/lib/remark.ts

@@ -0,0 +1,69 @@
+import type { AffiliateConfig } from './types.ts';
+import { resolveAffiliate } from './resolve.ts';
+
+const AFFILIATE_PREFIX = 'affiliate:';
+
+/** Minimal shape this plugin cares about - avoids a mdast-util-* type dependency. */
+interface MdastNode {
+  type: string;
+  url?: string;
+  children?: MdastNode[];
+}
+
+interface VFileWithAstroFrontmatter {
+  data?: {
+    astro?: {
+      frontmatter?: {
+        affiliates?: string[];
+      };
+    };
+  };
+}
+
+function collectAffiliateLinkNodes(node: MdastNode, out: MdastNode[]) {
+  if (node.type === 'link' && typeof node.url === 'string' && node.url.startsWith(AFFILIATE_PREFIX)) {
+    out.push(node);
+  }
+  if (node.children) {
+    for (const child of node.children) collectAffiliateLinkNodes(child, out);
+  }
+}
+
+/**
+ * Remark plugin: rewrites `[text](affiliate:catalogKey)` links to their real
+ * resolved URL at build time, and enforces FTC compliance by construction -
+ * every program actually used by a post must be declared in that post's
+ * `affiliates:` frontmatter (so `<AffiliateDisclosure>` knows to render it).
+ * An unknown key, or a used program missing from frontmatter, fails the build.
+ *
+ *   import { remarkAffiliate } from '@vdaluz/astro-affiliate/remark';
+ *
+ *   export default defineConfig({
+ *     markdown: { remarkPlugins: [[remarkAffiliate, affiliate]] },
+ *   });
+ */
+export function remarkAffiliate(config: AffiliateConfig) {
+  return (tree: MdastNode, file: VFileWithAstroFrontmatter) => {
+    const linkNodes: MdastNode[] = [];
+    collectAffiliateLinkNodes(tree, linkNodes);
+    if (linkNodes.length === 0) return;
+
+    const declaredAffiliates = file.data?.astro?.frontmatter?.affiliates ?? [];
+    const usedPrograms = new Set<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);
+    }
+
+    for (const program of usedPrograms) {
+      if (!declaredAffiliates.includes(program)) {
+        throw new Error(
+          `Post uses an "${program}" affiliate link but doesn't declare "affiliates: [${program}, ...]" in its frontmatter. Add it so the disclosure renders.`
+        );
+      }
+    }
+  };
+}

package/src/lib/resolve.ts

@@ -0,0 +1,58 @@
+import type { AffiliateConfig, ResolvedAffiliate } from './types.ts';
+
+/**
+ * Resolves a flat catalog key (e.g. 'atomicHabits', 'protonPass') against a
+ * site's affiliate config into a real URL. Throws on an unknown key, an
+ * unknown program, or a catalog entry/program kind mismatch - an unresolvable
+ * affiliate link is a build failure, not a silently broken link.
+ *
+ * `channel` selects a per-channel tag/link override (e.g. a distinct Amazon
+ * tracking ID for Medium reposts) if the program declares one via
+ * `channelTags`/`channelLinks` - falls back to the default `tag`/`links` entry
+ * for any channel not listed, so passing an unconfigured channel is a no-op,
+ * not an error.
+ */
+export function resolveAffiliate(config: AffiliateConfig, key: string, channel?: string): ResolvedAffiliate {
+  const entry = config.catalog[key];
+  if (!entry) {
+    throw new Error(
+      `Unknown affiliate catalog key "${key}". Known keys: ${Object.keys(config.catalog).join(', ') || '(none configured)'}.`
+    );
+  }
+
+  const program = config.programs[entry.program];
+  if (!program) {
+    throw new Error(`Catalog key "${key}" references unknown program "${entry.program}".`);
+  }
+
+  if ('asin' in entry) {
+    if (program.kind !== 'amazon') {
+      throw new Error(
+        `Catalog key "${key}" has an "asin" field, but program "${entry.program}" is kind "${program.kind}", not "amazon".`
+      );
+    }
+    const tag = (channel && program.channelTags?.[channel]) || program.tag;
+    const domain = program.domain ?? 'www.amazon.com';
+    return {
+      url: `https://${domain}/dp/${entry.asin}/ref=nosim?tag=${tag}`,
+      program: entry.program,
+    };
+  }
+
+  if ('link' in entry) {
+    if (program.kind !== 'links') {
+      throw new Error(
+        `Catalog key "${key}" has a "link" field, but program "${entry.program}" is kind "${program.kind}", not "links".`
+      );
+    }
+    const url = (channel && program.channelLinks?.[channel]?.[entry.link]) || program.links[entry.link];
+    if (!url) {
+      throw new Error(
+        `Catalog key "${key}" references unknown link "${entry.link}" in program "${entry.program}".`
+      );
+    }
+    return { url, program: entry.program };
+  }
+
+  throw new Error(`Catalog key "${key}" has neither "asin" nor "link".`);
+}

package/src/lib/types.ts

@@ -0,0 +1,76 @@
+import type { Localized } from './i18n.ts';
+
+/**
+ * Amazon Associates program. `resolveAffiliate` constructs the manual-link URL
+ * from `domain`, `tag`, and a catalog entry's ASIN: `https://<domain>/dp/<ASIN>/ref=nosim?tag=<tag>`.
+ */
+export interface AffiliateProgramAmazon {
+  kind: 'amazon';
+  /** Associates tracking ID for this site, e.g. 'vdaluz-20'. */
+  tag: string;
+  /**
+   * Amazon marketplace domain. Defaults to 'www.amazon.com'. Set for a
+   * locale-specific marketplace (e.g. 'www.amazon.com.br') that needs its own
+   * Associates tag - declare a second 'amazon'-kind program with that domain
+   * and tag, and catalog entries referencing it.
+   */
+  domain?: string;
+  /**
+   * Optional per-channel tracking ID overrides (e.g. `{ medium: 'vdaluz-medium-20' }`
+   * for a distinct tag on Medium reposts). A channel not listed here falls back to `tag`.
+   */
+  channelTags?: Record<string, string>;
+  /** FTC disclosure text rendered by <AffiliateDisclosure> for this program. */
+  disclosure: Localized;
+}
+
+/** A flat link-key -> URL program (Proton, AdGuard, future one-off referral links). */
+export interface AffiliateProgramLinks {
+  kind: 'links';
+  disclosure: Localized;
+  links: Record<string, string>;
+  /**
+   * Optional per-channel URL overrides, keyed by channel then link key. A
+   * channel/link-key combination not listed here falls back to `links`.
+   */
+  channelLinks?: Record<string, Record<string, string>>;
+}
+
+export type AffiliateProgram = AffiliateProgramAmazon | AffiliateProgramLinks;
+
+export interface CatalogEntryAmazon {
+  /** Name of a 'amazon'-kind program in `programs`. */
+  program: string;
+  asin: string;
+  /** Free-form grouping for site-side filtering (e.g. a /gear page), not used by resolution. */
+  category?: string;
+}
+
+export interface CatalogEntryLink {
+  /** Name of a 'links'-kind program in `programs`. */
+  program: string;
+  /** Key into that program's `links` map. */
+  link: string;
+  /** Free-form grouping for site-side filtering (e.g. a /gear page), not used by resolution. */
+  category?: string;
+}
+
+export type CatalogEntry = CatalogEntryAmazon | CatalogEntryLink;
+
+/**
+ * Per-site affiliate config. `programs` holds disclosure text and per-program
+ * resolution settings (site tag, or a link map); `catalog` is a single flat,
+ * unprefixed-key list of every item, each pointing at the program that resolves
+ * it. Catalog keys are what posts use in `affiliate:key` markdown links and
+ * what `resolveAffiliate`/`<AffiliateLink>` expect.
+ */
+export interface AffiliateConfig {
+  programs: Record<string, AffiliateProgram>;
+  catalog: Record<string, CatalogEntry>;
+}
+
+export interface ResolvedAffiliate {
+  url: string;
+  /** Program name the key resolved under, e.g. 'amazon'. */
+  program: string;
+}