PageBridge

URLMatcher

The URLMatcher connects GSC URLs to Sanity documents by extracting slugs from URL paths and finding matching content.

Constructor

import { URLMatcher } from '@pagebridge/core'

const matcher = new URLMatcher(sanityClient, {
  urlConfigs: [
    { contentType: 'post', slugField: 'slug', pathPrefix: '/blog' },
    { contentType: 'page', slugField: 'slug' }
  ],
  baseUrl: 'https://example.com'
})
typescript

URLMatcherConfig

interface ContentTypeUrlConfig {
  contentType: string      // Sanity document type to search
  slugField: string        // Field name containing the URL slug
  pathPrefix?: string      // URL path prefix (e.g., '/blog'). Omit for root-level URLs.
}

interface URLMatcherConfig {
  urlConfigs: ContentTypeUrlConfig[]  // Per-content-type URL configurations
  baseUrl: string                      // Site base URL
}
typescript

matchUrls(gscUrls)

Takes an array of GSC URLs and returns match results. Each result indicates whether a Sanity document was found and with what confidence.

const results = await matcher.matchUrls([
  'https://example.com/blog/getting-started',
  'https://example.com/blog/advanced-tips',
  'https://example.com/about'
])

// results: MatchResult[]
typescript

MatchResult

interface MatchResult {
  gscUrl: string
  sanityId: string | undefined
  confidence: 'exact' | 'normalized' | 'fuzzy' | 'none'
  matchedSlug?: string
  matchedContentType?: string           // The content type that matched (new)
  unmatchReason: UnmatchReason
  extractedSlug?: string
  diagnostics?: MatchDiagnostics
}

type UnmatchReason =
  | 'matched'
  | 'no_slug_extracted'
  | 'no_matching_document'
  | 'outside_path_prefix'

interface MatchDiagnostics {
  normalizedUrl: string
  pathAfterPrefix: string | null
  configuredPrefix: string | null
  availableSlugsCount: number
  similarSlugs: string[]
}
typescript

getAvailableSlugs()

Returns all slugs available in Sanity for the configured content types. Useful for debugging.

const slugs = await matcher.getAvailableSlugs()
// ['getting-started', 'advanced-tips', 'faq', ...]
typescript

See also