Skip to content

Open-source agentic AI Search Execution Platform. Track AI visibility, find opportunities, and let agents turn signals into prioritized actions and drafted fixes across ChatGPT, Claude, Gemini, Google AI Overviews, Google AI Mode, Perplexity, Grok, and Microsoft Copilot.

feat(content): recommend several assets per opportunity (#940)

Gökhan Geyik916896f45f02
diff --git a/server/src/lib/open-opportunities.js b/server/src/lib/open-opportunities.js
index 4e3549508..130a61342 100644
--- a/server/src/lib/open-opportunities.js
+++ b/server/src/lib/open-opportunities.js
@@ -4,7 +4,7 @@ const PAGE = 1000;
/**
* A brand's cluster opportunities, every status, as { id, title, status,
- * cluster_id, related_cluster_ids, opportunity_score, targetPages }. Paged: a
+ * cluster_id, related_cluster_ids, opportunity_score, targetPages, assets }. Paged: a
* large brand can hold more than PostgREST's 1,000-row default, and a short
* read would let a covered cluster be suggested again.
*/
@@ -14,7 +14,7 @@ export async function loadClusterOpportunities(brandId) {
const { data, error } = await supabaseAdmin
.from('content_opportunities')
.select(
- 'id, title, status, cluster_id, related_cluster_ids, opportunity_score, targetPages:source_data->targetPages',
+ 'id, title, status, cluster_id, related_cluster_ids, opportunity_score, targetPages:source_data->targetPages, assets:source_data->assets',
)
.eq('brand_id', brandId)
.not('cluster_id', 'is', null)
diff --git a/server/src/lib/opportunity-generator.js b/server/src/lib/opportunity-generator.js
index 0025f012d..02d9e6f10 100644
--- a/server/src/lib/opportunity-generator.js
+++ b/server/src/lib/opportunity-generator.js
@@ -25,7 +25,13 @@ import {
} from './opportunity-limits.js';
import { loadClusterOpportunities } from './open-opportunities.js';
import { loadClusters } from './prompt-clusters.js';
-import { DECISIONS, candidatePages, resolveDecision } from './page-matching.js';
+import {
+ ASSET_TYPES,
+ DECISIONS,
+ MAX_SUPPORTING_ASSETS,
+ buildAssets,
+ candidatePages,
+} from './page-matching.js';
/** Existing opportunities shown to the model for the cross-topic check. */
const EXISTING_SHOWN = 60;
@@ -54,6 +60,9 @@ Rules:
- consolidate: two or more listed pages are each mainly about this same need, close to duplicates, and split its signals. Merge them into one. Pages of different kinds (a head-to-head comparison and a general list, a glossary entry and a guide) are not duplicates: pick the page closest to the need and expand or optimize it instead.
- defend: the brand is already visible for this need and a listed page answers it. Keep it ahead of competitors.
Set pageIndexes to the bracketed P indexes of the pages the decision is about, and leave it empty for create. The title should say what to do with which page, for example "Expand the AI rank tracker comparison with Google AI Overviews coverage".
+- The opportunity is the primary asset above. Set assetType to what that content is.
+- Add supporting assets only when the data calls for them, up to ${MAX_SUPPORTING_ASSETS}, each a different piece of work. For example: a comparison page when people compare named products; a glossary or FAQ page for a definition the main content relies on; an earned third-party article when competitors are visible and the brand is not; a backlink when the brand's page exists but is not cited. Give each a short title saying what to make or do. Most opportunities need none or one.
+- Earned assets (third_party_article, backlink) live on other sites: set their channel to "earned", decision to "create" and pageIndexes to empty.
- Write for the brand's marketing team: do not use the words "cluster" or "prompt" in titles or descriptions.
- Refer to clusters and existing opportunities only through clusterIndex and sameAs. Never mention a bracketed index in a title or description.`;
@@ -77,6 +86,18 @@ function buildSchema(count) {
pageIndexes: z
.array(z.number())
.describe('The P indexes of the existing pages the decision is about'),
+ assetType: z.enum(ASSET_TYPES).describe('What the primary content is'),
+ supportingAssets: z
+ .array(
+ z.object({
+ type: z.enum(ASSET_TYPES),
+ channel: z.enum(['owned', 'earned']),
+ decision: z.enum(DECISIONS),
+ pageIndexes: z.array(z.number()),
+ title: z.string().describe('What to make or do, in a few words'),
+ }),
+ )
+ .describe('Further assets the data calls for; often empty'),
}),
)
.max(count),
@@ -316,8 +337,9 @@ Write every title and description in ${getLanguageName(brand.language)}.`;
components,
queries: basketSummary(ids, basketRows || []),
}),
- // The decision and its pages stay as first made.
+ // The decision, its pages and the assets stay as first made.
...(target.targetPages ? { targetPages: target.targetPages } : {}),
+ ...(target.assets ? { assets: target.assets } : {}),
},
updated_at: new Date().toISOString(),
})
@@ -330,11 +352,18 @@ Write every title and description in ${getLanguageName(brand.language)}.`;
}
const c = clusterById.get(cand.id);
- const { decision, pages } = resolveDecision(
- opp.decision,
- opp.pageIndexes,
+ const assets = buildAssets(
+ {
+ type: opp.assetType,
+ channel: opp.type,
+ decision: opp.decision,
+ pageIndexes: opp.pageIndexes,
+ title: opp.title,
+ },
+ opp.supportingAssets,
pagesFor.get(cand.id),
);
+ const [primary] = assets;
inserts.push({
brand_id: brandId,
cluster_id: c.id,
@@ -345,7 +374,7 @@ Write every title and description in ${getLanguageName(brand.language)}.`;
impact: opp.impact,
opportunity_score: cand.score,
status: 'new',
- decision,
+ decision: primary.decision,
source_data: {
...sourceData({
clusters: [c],
@@ -354,13 +383,8 @@ Write every title and description in ${getLanguageName(brand.language)}.`;
components: cand.components,
queries: basketSummary([c.id], basketRows || []),
}),
- targetPages: pages.map((p) => ({
- url: p.url,
- title: p.title || p.h1 || null,
- aiCitations: p.ai_citations,
- gaSessions: p.ga_sessions,
- lastmod: p.lastmod,
- })),
+ targetPages: primary.pages,
+ assets,
},
});
}
diff --git a/server/src/lib/page-matching.js b/server/src/lib/page-matching.js
index 082bc9343..3bc396473 100644
--- a/server/src/lib/page-matching.js
+++ b/server/src/lib/page-matching.js
@@ -98,3 +98,65 @@ export function resolveDecision(decision, pageIndexes, candidates) {
if (valid === 'consolidate' && pages.length < 2) return { decision: 'optimize', pages };
return { decision: valid, pages };
}
+
+/** What an asset is. Owned types are pages on the brand's site; earned ones live elsewhere. */
+export const ASSET_TYPES = [
+ 'blog_post',
+ 'pillar_guide',
+ 'landing_page',
+ 'comparison_page',
+ 'glossary_page',
+ 'faq_page',
+ 'product_page',
+ 'category_page',
+ 'third_party_article',
+ 'backlink',
+];
+
+/** Supporting assets an opportunity may add to its primary one. */
+export const MAX_SUPPORTING_ASSETS = 3;
+
+const toPage = (p) => ({
+ url: p.url,
+ title: p.title || p.h1 || null,
+ aiCitations: p.ai_citations,
+ gaSessions: p.ga_sessions,
+ lastmod: p.lastmod,
+});
+
+/**
+ * An opportunity's assets, primary first, each with a stable key, its type,
+ * channel, decision, title and the existing pages it works on. Earned assets
+ * live off the brand's site, so they are always new and carry no page. A
+ * supporting asset of an unknown type, or one repeating the primary's type
+ * and decision, is dropped; so is anything past MAX_SUPPORTING_ASSETS.
+ *
+ * @param {{type: string, channel: string, decision: string, title: string, pageIndexes: number[]}} primary
+ * @param {typeof primary[]} supporting
+ * @param {object[]} candidates - the cluster's candidate pages
+ */
+export function buildAssets(primary, supporting, candidates) {
+ const assets = [];
+ const seen = new Set();
+ for (const a of [primary, ...(supporting || []).slice(0, MAX_SUPPORTING_ASSETS)]) {
+ if (!a || (assets.length && !ASSET_TYPES.includes(a.type))) continue;
+ const channel = a.channel === 'earned' ? 'earned' : 'owned';
+ const { decision, pages } =
+ channel === 'earned'
+ ? { decision: 'create', pages: [] }
+ : resolveDecision(a.decision, a.pageIndexes, candidates);
+ const type = ASSET_TYPES.includes(a.type) ? a.type : 'blog_post';
+ const id = `${type}:${decision}:${pages.map((p) => p.url).join(',')}`;
+ if (seen.has(id)) continue;
+ seen.add(id);
+ assets.push({
+ key: `a${assets.length + 1}`,
+ type,
+ channel,
+ decision,
+ title: a.title,
+ pages: pages.map(toPage),
+ });
+ }
+ return assets;
+}
diff --git a/server/src/lib/page-matching.test.js b/server/src/lib/page-matching.test.js
index 295692eda..ca352d407 100644
--- a/server/src/lib/page-matching.test.js
+++ b/server/src/lib/page-matching.test.js
@@ -1,5 +1,5 @@
import { describe, expect, it } from 'vitest';
-import { candidatePages, resolveDecision, tokens } from './page-matching.js';
+import { buildAssets, candidatePages, resolveDecision, tokens } from './page-matching.js';
describe('tokens', () => {
it('keeps meaningful words, folds plain plurals and handles any script', () => {
@@ -68,3 +68,58 @@ describe('resolveDecision', () => {
expect(resolveDecision('rewrite', [0], candidates).decision).toBe('create');
});
});
+
+describe('buildAssets', () => {
+ const candidates = [
+ { url: 'https://example.com/list', title: 'Tool list', ai_citations: 3, ga_sessions: 9 },
+ { url: 'https://example.com/vs', title: 'A vs B', ai_citations: 0, ga_sessions: 1 },
+ ];
+
+ it('keeps the primary first and resolves each asset on its own', () => {
+ const assets = buildAssets(
+ { type: 'blog_post', channel: 'owned', decision: 'expand', pageIndexes: [0], title: 'Main' },
+ [
+ {
+ type: 'comparison_page',
+ channel: 'owned',
+ decision: 'optimize',
+ pageIndexes: [1],
+ title: 'Cmp',
+ },
+ { type: 'backlink', channel: 'earned', decision: 'optimize', pageIndexes: [0], title: 'L' },
+ ],
+ candidates,
+ );
+ expect(
+ assets.map((a) => [a.key, a.type, a.channel, a.decision, a.pages.map((p) => p.url)]),
+ ).toEqual([
+ ['a1', 'blog_post', 'owned', 'expand', ['https://example.com/list']],
+ ['a2', 'comparison_page', 'owned', 'optimize', ['https://example.com/vs']],
+ // Earned work lives on other sites: always new, no page of ours.
+ ['a3', 'backlink', 'earned', 'create', []],
+ ]);
+ expect(assets[0].pages[0]).toEqual({
+ url: 'https://example.com/list',
+ title: 'Tool list',
+ aiCitations: 3,
+ gaSessions: 9,
+ lastmod: undefined,
+ });
+ });
+
+ it('drops unknown types, repeats of the same work and anything past the cap', () => {
+ const extra = (type) => ({
+ type,
+ channel: 'owned',
+ decision: 'create',
+ pageIndexes: [],
+ title: type,
+ });
+ const assets = buildAssets(
+ { type: 'faq_page', channel: 'owned', decision: 'create', pageIndexes: [], title: 'FAQ' },
+ [extra('podcast'), extra('faq_page'), extra('glossary_page'), extra('landing_page')],
+ candidates,
+ );
+ expect(assets.map((a) => a.type)).toEqual(['faq_page', 'glossary_page']);
+ });
+});
diff --git a/web/messages/en.json b/web/messages/en.json
index e71c56331..520d1ec81 100644
--- a/web/messages/en.json
+++ b/web/messages/en.json
@@ -1713,7 +1713,9 @@
"intent": "Intent"
},
"targetTitle": "Your Site",
- "targetStats": "{citations, plural, one {# AI citation} other {# AI citations}} · {sessions, plural, one {# session} other {# sessions}} in the last 30 days"
+ "targetStats": "{citations, plural, one {# AI citation} other {# AI citations}} · {sessions, plural, one {# session} other {# sessions}} in the last 30 days",
+ "assetsTitle": "Recommended Assets",
+ "primaryAsset": "Primary"
},
"webhook": {
"title": "Webhook Settings",
@@ -1774,6 +1776,18 @@
"refresh": "A page on your site covers this but is out of date. Update it.",
"consolidate": "Several pages on your site target this and split its signals. Merge them into one.",
"defend": "You are already visible here. Keep this page ahead of competitors."
+ },
+ "assetType": {
+ "blog_post": "Blog post",
+ "pillar_guide": "Pillar guide",
+ "landing_page": "Landing page",
+ "comparison_page": "Comparison page",
+ "glossary_page": "Glossary page",
+ "faq_page": "FAQ page",
+ "product_page": "Product page",
+ "category_page": "Category page",
+ "third_party_article": "Third-party article",
+ "backlink": "Backlink"
}
},
"traffic": {
diff --git a/web/src/app/[locale]/(dashboard)/dashboard/content/[id]/page.tsx b/web/src/app/[locale]/(dashboard)/dashboard/content/[id]/page.tsx
index 0dc418117..3bc696f4c 100644
--- a/web/src/app/[locale]/(dashboard)/dashboard/content/[id]/page.tsx
+++ b/web/src/app/[locale]/(dashboard)/dashboard/content/[id]/page.tsx
@@ -37,6 +37,7 @@ import {
import type { ContentBrief, ContentOpportunity } from '@/types';
import { getPromptFanout, type FanoutSubQuery } from '@/lib/actions/fanout';
import {
+ AssetsCard,
OpportunityBasketCard,
ScoreBreakdown,
TargetPagesCard,
@@ -295,6 +296,7 @@ export default function ContentDetailPage() {
{opportunity.decision && (
<TargetPagesCard decision={opportunity.decision} sourceData={sd} />
)}
+ <AssetsCard sourceData={sd} />
<OpportunityBasketCard opportunityId={opportunity.id} />
</div>
<ScoreBreakdown sourceData={sd} />
diff --git a/web/src/components/content/opportunity-basket.tsx b/web/src/components/content/opportunity-basket.tsx
index 8619cd962..82d8a653a 100644
--- a/web/src/components/content/opportunity-basket.tsx
+++ b/web/src/components/content/opportunity-basket.tsx
@@ -2,7 +2,7 @@
import { useEffect, useState } from 'react';
import { useTranslations } from 'next-intl';
-import { ExternalLink, FileText, Layers, Search } from 'lucide-react';
+import { Boxes, ExternalLink, FileText, Layers, Search } from 'lucide-react';
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
import { Badge } from '@/components/ui/badge';
import { Button } from '@/components/ui/button';
@@ -230,3 +230,56 @@ export function TargetPagesCard({
</Card>
);
}
+
+/** Everything the opportunity asks for: the primary content first, then supporting work. */
+export function AssetsCard({ sourceData }: { sourceData: ContentOpportunitySourceData }) {
+ const t = useTranslations('content');
+ const assets = sourceData.assets ?? [];
+ if (assets.length < 2) return null;
+
+ return (
+ <Card>
+ <CardHeader className="pb-2">
+ <div className="flex items-center gap-2">
+ <Boxes className="h-4 w-4 text-primary" />
+ <CardTitle className="text-sm font-medium">{t('detail.assetsTitle')}</CardTitle>
+ </div>
+ </CardHeader>
+ <CardContent className="space-y-2">
+ {assets.map((a, i) => (
+ <div key={a.key} className="rounded-md border p-2.5 space-y-1.5">
+ <div className="flex flex-wrap items-center gap-1.5">
+ {i === 0 && (
+ <Badge variant="outline" className="text-[10px] border-primary/40 text-primary">
+ {t('detail.primaryAsset')}
+ </Badge>
+ )}
+ <Badge variant="outline" className="text-[10px]">
+ {t(`assetType.${a.type}`)}
+ </Badge>
+ <Badge variant="outline" className="text-[10px]">
+ {t(`type.${a.channel}`)}
+ </Badge>
+ <Badge variant="secondary" className="text-[10px]">
+ {t(`decision.${a.decision}`)}
+ </Badge>
+ </div>
+ <p className="text-sm">{a.title}</p>
+ {a.pages.map((p) => (
+ <a
+ key={p.url}
+ href={p.url}
+ target="_blank"
+ rel="noreferrer"
+ className="flex items-center gap-1.5 text-xs text-muted-foreground hover:underline"
+ >
+ <ExternalLink className="h-3 w-3 shrink-0" />
+ <span className="truncate">{p.title || p.url}</span>
+ </a>
+ ))}
+ </div>
+ ))}
+ </CardContent>
+ </Card>
+ );
+}
diff --git a/web/src/types/index.ts b/web/src/types/index.ts
index 0a904e477..7c9c3f99a 100644
--- a/web/src/types/index.ts
+++ b/web/src/types/index.ts
@@ -220,13 +220,37 @@ export interface ContentOpportunitySourceData {
intent: number;
};
windowDays?: number;
- targetPages?: {
- url: string;
- title: string | null;
- aiCitations: number;
- gaSessions: number;
- lastmod: string | null;
- }[];
+ targetPages?: OpportunityPage[];
+ assets?: OpportunityAsset[];
+}
+
+export interface OpportunityPage {
+ url: string;
+ title: string | null;
+ aiCitations: number;
+ gaSessions: number;
+ lastmod: string | null;
+}
+
+export type OpportunityAssetType =
+ | 'blog_post'
+ | 'pillar_guide'
+ | 'landing_page'
+ | 'comparison_page'
+ | 'glossary_page'
+ | 'faq_page'
+ | 'product_page'
+ | 'category_page'
+ | 'third_party_article'
+ | 'backlink';
+
+export interface OpportunityAsset {
+ key: string;
+ type: OpportunityAssetType;
+ channel: ContentOpportunityType;
+ decision: ContentOpportunityDecision;
+ title: string;
+ pages: OpportunityPage[];
}
export interface OpportunityBasket {