fix(enrichment): preserve open graph refresh url context

Author: Innei

apps/core/src/modules/enrichment/enrichment.service.ts

@@ -33,6 +33,13 @@ interface EnrichmentRefreshPayload extends Record<string, unknown> {
   provider: string
   externalId: string
   locale: string
+  url?: string
+}
+
+interface EnrichmentRefInput {
+  provider: string
+  externalId: string
+  url?: string
 }
 
 /**
@@ -64,8 +71,11 @@ export class EnrichmentService implements OnModuleInit {
       type: ENRICHMENT_REFRESH_TASK_TYPE,
       execute: async (payload: EnrichmentRefreshPayload) => {
         const locale = payload.locale ?? ''
+        const url = typeof payload.url === 'string' ? payload.url : undefined
         try {
-          await this.refresh(payload.provider, payload.externalId, locale)
+          await this.refresh(payload.provider, payload.externalId, locale, {
+            url,
+          })
         } catch (error) {
           // Record per-row failure so backoff kicks in on subsequent SWR
           // resolves; re-throw so the task queue marks the task failed.
@@ -217,6 +227,7 @@ export class EnrichmentService implements OnModuleInit {
     providerName: string,
     id: string,
     lang?: string,
+    opts?: { url?: string },
   ): Promise<EnrichmentResult> {
     const provider = this.providerRegistry.getByName(providerName)
     if (!provider) throw new Error(`Unknown provider: ${providerName}`)
@@ -226,6 +237,7 @@ export class EnrichmentService implements OnModuleInit {
 
     const result = await this.fetchAndPersist(provider, id, {
       locale: cacheLocale,
+      url: opts?.url,
     })
     await this.deleteFromRedis(result.url, cacheLocale)
     return result
@@ -294,7 +306,7 @@ export class EnrichmentService implements OnModuleInit {
    * should index via the same helper.
    */
   async hydrateRefs(
-    refs: ReadonlyArray<{ provider: string; externalId: string }>,
+    refs: ReadonlyArray<EnrichmentRefInput>,
     lang?: string,
   ): Promise<Record<string, EnrichmentResult>> {
     if (refs.length === 0) return {}
@@ -304,6 +316,7 @@ export class EnrichmentService implements OnModuleInit {
       provider: string
       externalId: string
       locale: string
+      url?: string
     }
     const byKey = new Map<string, RefEntry>()
     for (const r of refs) {
@@ -312,17 +325,28 @@ export class EnrichmentService implements OnModuleInit {
         ? this.resolveCacheLocale(provider, reqLocale)
         : ''
       const key = `${r.provider}\t${r.externalId}\t${locale}`
-      if (byKey.has(key)) continue
+      const existing = byKey.get(key)
+      if (existing) {
+        if (!existing.url && r.url) existing.url = r.url
+        continue
+      }
       byKey.set(key, {
         provider: r.provider,
         externalId: r.externalId,
         locale,
+        url: r.url,
       })
     }
     if (byKey.size === 0) return {}
 
     const refQueries = [...byKey.values()]
-    const rows = await this.repository.findManyByRefs(refQueries)
+    const rows = await this.repository.findManyByRefs(
+      refQueries.map(({ provider, externalId, locale }) => ({
+        provider,
+        externalId,
+        locale,
+      })),
+    )
     const now = new Date()
     const out: Record<string, EnrichmentResult> = {}
     const seenKeys = new Set<string>()
@@ -361,12 +385,18 @@ export class EnrichmentService implements OnModuleInit {
         if (!provider) continue
         config ??= await this.configsService.get('thirdPartyServiceIntegration')
         if (!this.isProviderReady(provider, config)) continue
+        if (provider.requiresUrlContext && !entry.url) continue
         const k = refKey(entry.provider, entry.externalId)
         if (entry.locale !== '' && !out[k]) {
           const fb = fallbackByKey.get(k)
           if (fb) out[k] = fb
         }
-        this.enqueueRefresh(entry.provider, entry.externalId, entry.locale)
+        this.enqueueRefresh(
+          entry.provider,
+          entry.externalId,
+          entry.locale,
+          entry.url,
+        )
       }
     }
     return out
@@ -400,6 +430,7 @@ export class EnrichmentService implements OnModuleInit {
       urlRefs.map((r) => ({
         provider: r.provider,
         externalId: r.externalId,
+        url: r.url,
       })),
       lang,
     )
@@ -604,6 +635,7 @@ export class EnrichmentService implements OnModuleInit {
     providerName: string,
     externalId: string,
     locale: string,
+    url?: string,
   ): void {
     const dedupKey = locale
       ? `${providerName}:${externalId}:${locale}`
@@ -617,6 +649,7 @@ export class EnrichmentService implements OnModuleInit {
           provider: providerName,
           externalId,
           locale,
+          ...(url ? { url } : {}),
         } satisfies EnrichmentRefreshPayload,
       })
       .catch((error) => {

apps/core/src/modules/enrichment/providers/open-graph/open-graph.provider.ts

@@ -40,6 +40,7 @@ export class OpenGraphProvider implements EnrichmentProvider {
   readonly priority = -100
   readonly defaultTtl = 86_400 * 7
   readonly featureGateConfigKey = 'openGraph'
+  readonly requiresUrlContext = true
 
   private readonly logger = new Logger(OpenGraphProvider.name)
 

apps/core/src/modules/enrichment/providers/provider.interface.ts

@@ -42,6 +42,11 @@ export interface EnrichmentProvider<TRaw = unknown> {
 
   readonly requiredConfigKeys?: string[]
   readonly featureGateConfigKey?: string
+  /**
+   * True when `externalId` alone is not enough to fetch upstream data.
+   * Ref-driven cold hydration must provide `ctx.url` for these providers.
+   */
+  readonly requiresUrlContext?: boolean
   /**
    * When true, the service layer maps the request `lang` into a per-locale
    * cache row and passes it to {@link fetch}. Default false.

apps/core/src/modules/recently/recently.service.ts

@@ -20,6 +20,9 @@ import { RecentlyRepository } from './recently.repository'
 import { RecentlyAttitudeEnum } from './recently.schema'
 import { RecentlyModel, type RecentlyRow } from './recently.types'
 
+const URL_REGEX = /https?:\/\/\S+/i
+const URL_TAIL_TRIM = /[!"'),.:;>?\]`}—…、。〉《》「」『』〕！），：；？]+$/
+
 /**
  * Minimal hydrated reference returned alongside a recently row when its
  * `refType`/`refId` point at a post/note/page/recently. Mirrors the small
@@ -355,12 +358,14 @@ export class RecentlyService {
   ): Promise<Array<T & { enrichment?: EnrichmentResult | null }>> {
     if (rows.length === 0) return []
 
-    const refs: Array<{ provider: string; externalId: string }> = []
+    const refs: Array<{ provider: string; externalId: string; url?: string }> =
+      []
     for (const row of rows) {
       if (row.enrichmentProvider && row.enrichmentExternalId) {
         refs.push({
           provider: row.enrichmentProvider,
           externalId: row.enrichmentExternalId,
+          url: this.resolveEnrichmentUrl(row),
         })
       }
     }
@@ -384,4 +389,35 @@ export class RecentlyService {
       return { ...row, enrichment: map[key] ?? null }
     })
   }
+
+  private resolveEnrichmentUrl(row: RecentlyRow): string | undefined {
+    if (!row.enrichmentProvider || !row.enrichmentExternalId) return undefined
+    const metadataUrl = (row.metadata as { url?: unknown } | null)?.url
+    const candidates = [
+      typeof metadataUrl === 'string' ? metadataUrl : undefined,
+      extractFirstUrl(row.content),
+    ].filter((url): url is string => !!url)
+
+    for (const url of candidates) {
+      const ref = this.enrichmentService.matchUrlToRef(url)
+      if (
+        ref?.provider === row.enrichmentProvider &&
+        ref.externalId === row.enrichmentExternalId
+      ) {
+        return url
+      }
+    }
+    return undefined
+  }
+}
+
+function extractFirstUrl(
+  content: string | null | undefined,
+): string | undefined {
+  if (!content) return undefined
+  const match = content.match(URL_REGEX)
+  if (!match) return undefined
+  let url = match[0]
+  while (URL_TAIL_TRIM.test(url)) url = url.replace(URL_TAIL_TRIM, '')
+  return url || undefined
 }

apps/core/test/src/modules/enrichment/enrichment.service.hydrate-refs.spec.ts

@@ -187,4 +187,26 @@ describe('EnrichmentService.hydrateRefs', () => {
     await service.hydrateRefs([{ provider: 'gh-repo', externalId: 'a/b' }])
     expect(repository.findManyByRefs).toHaveBeenCalledTimes(1)
   })
+
+  it('does not enqueue a cold refresh for URL-context providers without URL', async () => {
+    const taskQueueService = {
+      createTask: vi.fn(async () => ({ taskId: 't1', created: true })),
+    }
+    const { service } = makeService({
+      rows: new Map(),
+      taskQueueService,
+      providerRegistry: {
+        getByName: () => ({
+          name: 'open-graph',
+          requiresUrlContext: true,
+        }),
+      },
+    })
+
+    await service.hydrateRefs([
+      { provider: 'open-graph', externalId: 'opaque-hash' },
+    ])
+    await new Promise((r) => setImmediate(r))
+    expect(taskQueueService.createTask).not.toHaveBeenCalled()
+  })
 })

apps/core/test/src/modules/enrichment/enrichment.service.hydrate.spec.ts

@@ -92,6 +92,42 @@ describe('EnrichmentService.hydrateUrls', () => {
     expect(await svc.hydrateUrls(['https://github.com/a/b'])).toEqual({})
   })
 
+  it('passes URL context when a cache miss enqueues a cold refresh', async () => {
+    const url = 'https://example.com/article'
+    const taskQueueService = {
+      createTask: vi.fn(async () => ({ taskId: 't1', created: true })),
+    }
+    const svc = makeService({
+      matchUrlToRef: () => ({
+        provider: 'open-graph',
+        externalId: 'opaque-hash',
+      }),
+      rows: new Map(),
+      taskQueueService,
+    }) as any
+    svc.providerRegistry = {
+      getByName: () => ({
+        name: 'open-graph',
+        localeAware: false,
+      }),
+    }
+
+    expect(await (svc as EnrichmentService).hydrateUrls([url])).toEqual({})
+    await new Promise((r) => setImmediate(r))
+    expect(taskQueueService.createTask).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: 'enrichment:refresh',
+        dedupKey: 'open-graph:opaque-hash',
+        payload: {
+          provider: 'open-graph',
+          externalId: 'opaque-hash',
+          locale: '',
+          url,
+        },
+      }),
+    )
+  })
+
   it('returns the cached normalized result keyed by original URL', async () => {
     const url = 'https://github.com/vercel/next.js'
     const row = makeRow({
@@ -250,7 +286,12 @@ describe('EnrichmentService.hydrateUrls', () => {
     expect(taskQueueService.createTask).toHaveBeenCalledWith(
       expect.objectContaining({
         dedupKey: 'tmdb:movie/1:zh',
-        payload: { provider: 'tmdb', externalId: 'movie/1', locale: 'zh' },
+        payload: {
+          provider: 'tmdb',
+          externalId: 'movie/1',
+          locale: 'zh',
+          url,
+        },
       }),
     )
   })

apps/core/test/src/modules/enrichment/enrichment.service.spec.ts

@@ -79,6 +79,9 @@ function makeService(stubs: ServiceStubs = {}) {
         },
       }
     }),
+    getByName: vi.fn((name: string) =>
+      name === provider.name ? provider : undefined,
+    ),
   }
   const configsService = {
     get: vi.fn(async () => ({})),
@@ -252,6 +255,17 @@ describe('EnrichmentService.resolveCacheLocale', () => {
   })
 })
 
+describe('EnrichmentService.refresh', () => {
+  it('threads explicit URL context into provider fetch', async () => {
+    const url = 'https://example.com/post'
+    const { service, provider } = makeService({ dbRow: null })
+
+    await service.refresh('tmdb', 'movie/1', undefined, { url })
+
+    expect(provider.fetch).toHaveBeenCalledWith('movie/1', undefined, { url })
+  })
+})
+
 describe('EnrichmentService.resolve (locale)', () => {
   const url = 'https://www.themoviedb.org/movie/1'