MAGIK-934: Provider Interface Extension — enrichFromUrl() + URL Detection

[MAGIKBIT]

MAGIK-934: Provider Interface Extension — enrichFromUrl() + URL Detection

Epic: EPIC-025 (Multi-Source Profile Enrichment) — #113
Priority: P0
Estimate: 3 SP

Description

Extend the existing EnrichmentProviderInterface with two new methods to support URL-based enrichment, and add URL-to-provider routing logic in EnrichmentService.

Changes

1. Interface extension (Libraries/Enrichment/EnrichmentProviderInterface.php):

/**
 * Whether this provider can handle a given URL.
 */
public function canHandleUrl(string $url): bool;

/**
 * Enrich profile data from a URL (website, social profile, etc.).
 */
public function enrichFromUrl(string $url): EnrichmentResult;

2. Update existing providers with default no-op implementations:

• ApolloProvider → canHandleUrl() returns false, enrichFromUrl() returns fail
• HunterLogoProvider → same
• DemoProvider → same (extended in MAGIK-946)

3. URL routing in EnrichmentService:

public function enrichByUrl(string $url, string $targetClientId): EnrichmentResult
{
    foreach ($this->providers as $provider) {
        if ($provider->canHandleUrl($url)) {
            return $provider->enrichFromUrl($url);
        }
    }
    return EnrichmentResult::fail('none', 'url', 'No provider can handle this URL');
}

4. New route in Config/Routes.php:

$routes->post('enrichment/url', 'EnrichmentController::enrichByUrl');

5. Controller method in EnrichmentController:

public function enrichByUrl()
{
    // gate check, validate URL, call service, store as draft
}

Files Impacted

File	Action
Libraries/Enrichment/EnrichmentProviderInterface.php	Modify
Libraries/Enrichment/ApolloProvider.php	Modify (add stubs)
Libraries/Enrichment/HunterLogoProvider.php	Modify (add stubs)
Libraries/Enrichment/DemoProvider.php	Modify (add stubs)
Libraries/EnrichmentService.php	Modify (add enrichByUrl)
Controllers/EnrichmentController.php	Modify (add endpoint)
Config/Routes.php	Modify (add route)

Acceptance Criteria

• EnrichmentProviderInterface includes canHandleUrl() and enrichFromUrl()
• Existing providers compile with stub implementations
• POST /enrichment/url accepts a URL and routes to matching provider
• Returns 400 if no provider matches the URL
• Access gate enforced on new endpoint
• Unit tests for URL routing logic