Partner Account Entities in the Beacon Ecosystem

This guide explains the data structures and operational roles of the Account, User, Domain, and Login entities within the Social Signal Beacon ecosystem. Partners use these entities via the Partner API to provision client accounts in one shot or manage specific child resources fine-grained.

---

1. Account Entity (Composite Aggregate)

The Account entity (PartnerAccount) is the primary composite resource representing a partner's client account. It unites the root client identity (_id), business profile (company), associated login credentials (logins), tracking domain configurations (domains), and aggregate KPI metrics (metrics) into a single hydrated object.

Canonical Schema (PartnerAccount)

Field	Type	Description
_id	string	Account ID: The unique identifier for the client account (e.g., SDLR_D10000). Maps 1-to-1 to User ID.
pid	string	Partner ID: The reselling partner who owns this account.
company	string (optional)	Name of the client business.
status	enum	Lifecycle status (pending, active, suspended, archived).
logins	array[PartnerLogin] (optional)	List of login credentials mapped to this account (when ?expand=logins is requested).
domains	array[PartnerDomain] (optional)	List of domain configurations registered under this account (when ?expand=domains is requested).
metrics	PartnerSummaryMetrics (optional)	Combined traffic, lead match, and credit balance summary across all account domains (when ?expand=metrics is requested).

---

2. User Entity

The User entity represents a partner's client account. It functions as the root container for identity, overall subscription plan state, API keys, and fallback event handling logic.

Canonical Schema (PartnerUser)

Field	Type	Description
_id	string	User Client ID: The unique identifier for the user account (e.g., user_123).
pid	string	Partner ID: The reselling partner who owns/provisioned this client.
email	string	Primary contact and authentication email for the user.
company	string (optional)	Name of the client's business/dealership.
status	enum	Lifecycle state: pending, active, suspended, or archived.
domains	array[string]	List of active domains registered to this user account.
defaultVisitFlow	object (optional)	Fallback programmatic Hono flow template to run on visitor traffic.
defaultLeadFlow	object (optional)	Fallback flow template to execute when a lead match is resolved.

Operational Role in Beacon

• Quota & Billing: Houses the billing parameters and holds credit pools.
• Logical Fallbacks: If a domain does not specify custom pipelines (visitFlow/leadFlow), the system falls back to the User's defaultVisitFlow and defaultLeadFlow configuration.
• Access Control: Contains the API key used by the client for direct integrations.

---

2. Domain Entity

The Domain entity represents a single website hostname registered under a client User. It controls script enablement, visit matching criteria, credit allocations, and third-party CRM integration coordinates.

Canonical Schema (PartnerDomain)

Field	Type	Default	Description
_id	string	-	User Client ID: Links the domain configuration back to the parent User record.
domain	string	-	Domain Name: Clean host URL (e.g., dealername.com, parsed of subpaths/protocols).
pid	string	-	Partner ID matching the parent user.
enablement	boolean	false	Indicates whether beacon script event tracking is active.
status	enum	active	Lifecycle status: pending, active, suspended, or archived.
collectLeads	boolean	false	Read-only flag: Indicates if lead matching is currently authorized and running.
instantCredits	integer	0	One-time credits allocated for identity lookup operations (only values of 0 or 10 are accepted; other values default to 0).
weeklyCredits	integer	0	Recurring credits automatically refilled each week.
monthlyCredits	integer	0	Recurring credits automatically refilled each month (must be one of: 0, 75, 250, 1000, 2500).
minVisitsToMatch	integer	2	Minimum visitor visit-count threshold to trigger lead matching.
visitFlow	object	null	Programmatic flow template executed immediately on a new visitor hit.
leadFlow	object	null	Programmatic flow template executed once a visitor's identity is resolved (matched).
metadata	object	{}	Key-value settings for third-party endpoints (e.g. CRM credentials).

Operational Role in Beacon

• Traffic Validation: When the script makes a request to the edge endpoint /api/v2/beacon/event, the gateway verifies the domain is active and has enablement: true.
• Visit Filtering: The minVisitsToMatch setting filters out casual single-page bounces. The visitor profile must register at least this many visits before the edge initiates a lead resolution query.
• Credit Ingress: Resolving a lead consumes credits. The lookup checks the domain's combined credit balances (instantCredits + recurring balances) before initiating the match.
• Delivery Integration: The leadFlow defines where resolved leads are sent (e.g., pushed to CRM webhooks, dispatched to Slack, or emailed).

---

3. Login Credential Entity

The Login Credential entity (PartnerLogin) maps email addresses and salted passwords to specific User Client IDs (_id). It controls access credentials for partner sub-users logging into dashboard interfaces.

Canonical Schema (PartnerLogin)

Field	Type	Description
email	string	Primary login email address.
_id	string	Target User Client ID under the partner account.
pid	string	Partner ID: The reselling partner who owns this user.
type	enum	Identity role type (user, partner, admin). Defaults to user.

---

4. Interaction Flow Overview

The diagram below details how the User, Domain, and Beacon services interact during visitor event processing:

sequenceDiagram
    autonumber
    actor Visitor as Eyeball/Visitor
    participant Edge as Edge Gateway (ssedge)
    participant KV as BRecord Cache (KV)
    participant Engine as FlowRunner (ssmono)
    participant CRM as Partner CRM / Email

    Visitor->>Edge: Hits website (sends Beacon Event)
    Edge->>KV: Look up Domain (enablement & status)
    KV-->>Edge: Returns Domain configuration
    Edge->>KV: Look up Parent User (status & credentials)
    KV-->>Edge: Returns User record

    alt Validation Fails (Disabled/Suspended)
        Edge-->>Visitor: 204 No Content (Drop Silent)
    else Validation Succeeds
        Edge->>KV: Log Visit & Increment Visit Count
        alt Visits < minVisitsToMatch
            Edge-->>Visitor: 200 OK (Awaiting Threshold)
        else Visits >= minVisitsToMatch
            Edge->>Engine: Trigger Lead Resolution (consume credit)
            Engine->>Engine: Run Domain.leadFlow (or User.defaultLeadFlow)
            Engine->>CRM: Deliver formatted lead payload
            Edge-->>Visitor: 200 OK (Lead Pushed)
        end
    end