README

A polymorphic lead register for Laravel: a discovered potential customer with a status lifecycle. A lead is not a customer and never auto-converts; converting one into a customer is the host app's concern. Each lead is scoped to an owner (a workspace, organization, user) through whilesmart/eloquent-owner-access, can point at a polymorphic subject it is interested in (e.g. a product), and is deduplicated per owner at the database level.

Install

composer require whilesmart/eloquent-leads
php artisan migrate

Routes register automatically under the api prefix with auth:sanctum. Set LEADS_REGISTER_ROUTES=false to mount them yourself.

Owning model

Add the trait to whatever owns leads:

use Whilesmart\Leads\Traits\HasLeads;

class Workspace extends Model
{
    use HasLeads;
}

$workspace->leads()->create([
    'name' => 'Jane Doe',
    'channel' => 'referral',
    'source' => 'Acme Inc',
    'source_url' => 'https://acme.example/contact/jane',
    'contact_email' => 'jane@acme.example',
    'why' => 'Asked about the enterprise plan',
]);

Deduplication

A lead's dedupe_hash is a per-owner fingerprint of its strongest identity, in order: source_url, then handle, then contact_email, then contact_phone. Two leads for the same owner that share that identity produce the same hash, and a unique index on dedupe_hash lets the database reject the duplicate. A lead with no identifying value has a null hash and is never treated as a duplicate.

Endpoints

Status

LeadStatus: new, qualified, contacted, won, lost, dismissed. status is stored as a string and validated against the enum on write.