ads-in-chat-answers 0.1.0

package/README.md

@@ -0,0 +1,117 @@
+# ads-in-chat-answers
+
+Sponsored placements for AI chat answers, in the style of the product ads
+that appear under an assistant's reply:
+
+- **Answer carousel** — an advertiser header, an always-visible **Ad** label,
+  a ⋯ menu (*Hide this ad*, *About this ad*, *Ask about this ad*, *Report this
+  ad*) and a scrolling row of product cards, rendered *after* the answer.
+- **Sponsored follow-up** — one row in the "Related" questions list, worded
+  only as **"Learn more about ‹topic›"** and labelled *Sponsored · Advertiser*.
+  It is never the first suggestion.
+- **Keyword auction** — campaigns are scored against the question (full
+  weight) and the answer (half weight); negative keywords veto; anything under
+  30% relevance is dropped whatever it bids; the rest rank by relevance × max
+  CPC and the winner pays a second price. One advertiser cannot take both
+  placements on the same answer.
+- **Advertiser panel** — describe the business, press *Generate keywords with
+  AI* (an LLM proposes keywords, negative keywords and a follow-up topic),
+  pick placements and products, set a bid and budget, and test any question
+  against the live auction before launching.
+
+The answer is generated before, and without knowledge of, any ad. Ads never
+appear inside the answer text.
+
+## Install
+
+```bash
+bun add ads-in-chat-answers
+```
+
+## Showing ads in a chat
+
+```tsx
+import { ChatAnswerAd, SponsoredFollowUps, selectChatAds } from 'ads-in-chat-answers';
+import 'ads-in-chat-answers/styles.css';
+
+const { answer, followUp } = selectChatAds(campaigns, { query, answer: text });
+
+<Answer text={text} />
+{answer && (
+  <ChatAnswerAd
+    selection={answer}
+    onImpression={logImpression}
+    onProductClick={(product, sel) => chargeClick(sel.campaign.id, sel.costPerClickCents)}
+    onReport={reportAd}
+  />
+)}
+<SponsoredFollowUps questions={related} sponsored={followUp} onSelect={(q, sel) => ask(q)} />
+```
+
+`selectChatAds` is pure — run it in the browser, a Worker or a route. Charge a
+click with `recordClick(campaign, cost)`; a campaign at its daily budget drops
+out of the auction.
+
+## Keyword generation (server)
+
+```ts
+import { createOpenAICompatibleComplete, handleAdsRequest } from 'ads-in-chat-answers/server';
+
+const complete = createOpenAICompatibleComplete({ apiKey: env.OPENROUTER_API_KEY }); // OpenRouter by default
+
+export default {
+  fetch: (request: Request) =>
+    handleAdsRequest(request, { complete, getCampaigns: () => loadCampaigns() }),
+};
+```
+
+| Route | Body | Returns |
+| --- | --- | --- |
+| `POST …/keywords` | `{ advertiser, description, website?, products?, existingKeywords? }` | `KeywordPlan` |
+| `POST …/select` | `{ query, answer? }` | `{ answer, followUp }` (only when `getCampaigns` is given) |
+
+Without a model, or when the model's reply isn't the requested JSON, the plan
+falls back to a deterministic heuristic (`source: "heuristic"`) instead of
+failing.
+
+## The advertiser panel
+
+```tsx
+<AdvertiserPanel
+  campaigns={campaigns}
+  stats={statsByCampaignId}
+  onSave={saveCampaign}
+  onDelete={deleteCampaign}
+  generateKeywords={(brief) => fetch('/api/ads/keywords', { method: 'POST', body: JSON.stringify(brief) }).then((r) => r.json())}
+/>
+```
+
+## Theming
+
+Every rule is scoped under `.qads-root` and every colour is a `--qads-*`
+custom property. Dark by default; light under `prefers-color-scheme: light`,
+`[data-theme="light"]` or `.light`.
+
+## Demo (Vercel)
+
+`demo/` is a chat UI with the placements, an auction inspector showing every
+campaign's score, and the advertiser panel. It runs offline with seed
+campaigns and canned answers; a model key makes the answers and keyword plans
+live.
+
+```bash
+cd demo && bun install && bun run dev       # http://localhost:5173, /api included
+```
+
+Deploy: import the repo in Vercel and set **Root Directory** to
+`packages/ads-in-chat-answers/demo` (keep "Include files outside the root
+directory" on — the demo builds the package from `../src`). Optional env vars:
+
+| Variable | Default |
+| --- | --- |
+| `LLM_API_KEY` (or `OPENROUTER_API_KEY` / `OPENAI_API_KEY`) | none — canned answers and heuristic keywords |
+| `LLM_BASE_URL` | `https://openrouter.ai/api/v1` |
+| `LLM_MODEL` | `openai/gpt-4o-mini` |
+
+The build writes Vercel's Build Output directly (`scripts/vercel-output.mjs`),
+bundling `server/*.js` into Edge functions at `/api/answer` and `/api/keywords`.

package/dist/components/AdvertiserPanel.d.ts

@@ -0,0 +1,25 @@
+import { type AdvertiserBrief } from '../keywords';
+import { type Campaign, type KeywordPlan } from '../types';
+export interface CampaignStats {
+    impressions: number;
+    clicks: number;
+    spendCents: number;
+}
+export interface AdvertiserPanelProps {
+    campaigns: Campaign[];
+    onSave: (campaign: Campaign) => void;
+    onDelete?: (id: string) => void;
+    /** Calls the keyword generator — usually `POST /keywords` on the server half. */
+    generateKeywords: (brief: AdvertiserBrief) => Promise<KeywordPlan>;
+    stats?: Record<string, CampaignStats>;
+    className?: string;
+}
+export declare function emptyCampaign(): Campaign;
+/** Why a draft cannot be saved yet, or null when it can. */
+export declare function validateCampaign(c: Campaign): string | null;
+/**
+ * Self-serve campaign builder: describe the business, let the model propose
+ * keywords, pick placements and products, set a bid and budget, and test any
+ * question against the live auction before saving.
+ */
+export declare function AdvertiserPanel({ campaigns, onSave, onDelete, generateKeywords, stats, className, }: AdvertiserPanelProps): import("react").JSX.Element;

package/dist/components/BrandMark.d.ts

@@ -0,0 +1,16 @@
+/** A stable hue per string, so a brand's fallback mark keeps its colour. */
+export declare function hueFor(text: string): number;
+/** The round logo in the ad header; the advertiser's initial when there is no logo. */
+export declare function BrandMark({ name, logoUrl, size }: {
+    name: string;
+    logoUrl?: string;
+    size?: number;
+}): import("react").JSX.Element;
+/**
+ * The product image, or a typographic cover drawn from the title when the
+ * advertiser gave none — a broken image in an ad looks worse than no ad.
+ */
+export declare function ProductImage({ title, imageUrl }: {
+    title: string;
+    imageUrl?: string;
+}): import("react").JSX.Element;

package/dist/components/ChatAnswerAd.d.ts

@@ -0,0 +1,27 @@
+import type { AdProduct, AdSelection } from '../types';
+export interface ChatAnswerAdProps {
+    selection: AdSelection;
+    /** Fired once when the ad first renders. */
+    onImpression?: (selection: AdSelection) => void;
+    /** A product card was clicked. The card is also a real link to `product.url`. */
+    onProductClick?: (product: AdProduct, selection: AdSelection) => void;
+    /** "Hide this ad". The component hides itself either way. */
+    onHide?: (selection: AdSelection) => void;
+    /** "Ask about this ad" — the host turns it into a chat question. */
+    onAsk?: (selection: AdSelection) => void;
+    /** "Report this ad". */
+    onReport?: (selection: AdSelection) => void;
+    /** Show the auction numbers in "About this ad" (for the advertiser demo). */
+    showAuctionDetails?: boolean;
+    className?: string;
+}
+/**
+ * The sponsored product carousel shown under an assistant answer: advertiser
+ * header, an always-visible "Ad" label, an overflow menu (hide, about, ask,
+ * report) and a horizontally scrolling row of product cards.
+ *
+ * It is rendered *after* the answer and visually separated from it — the ad
+ * never sits inside the answer text, so it cannot be mistaken for the
+ * assistant's recommendation.
+ */
+export declare function ChatAnswerAd({ selection, onImpression, onProductClick, onHide, onAsk, onReport, showAuctionDetails, className, }: ChatAnswerAdProps): import("react").JSX.Element;

package/dist/components/SponsoredFollowUps.d.ts

@@ -0,0 +1,24 @@
+import type { AdSelection } from '../types';
+export interface SponsoredFollowUpsProps {
+    /** The assistant's own follow-up questions. */
+    questions: string[];
+    /** The follow-up auction winner, if any. */
+    sponsored?: AdSelection | null;
+    /**
+     * Where the sponsored question goes in the list (default 1, second row).
+     * Never first: the top suggestion should be the most useful one, not the
+     * one that paid.
+     */
+    sponsoredIndex?: number;
+    /** A question was picked. `selection` is set for the sponsored one. */
+    onSelect: (question: string, selection?: AdSelection) => void;
+    /** Fired once when the sponsored question first renders. */
+    onImpression?: (selection: AdSelection) => void;
+    title?: string;
+    className?: string;
+}
+/**
+ * The "Related" list after an answer, with at most one sponsored row:
+ * "Learn more about <topic>", labelled Sponsored with the advertiser's name.
+ */
+export declare function SponsoredFollowUps({ questions, sponsored, sponsoredIndex, onSelect, onImpression, title, className, }: SponsoredFollowUpsProps): import("react").JSX.Element | null;