@halo-ads/core 0.1.0

package/README.md

@@ -0,0 +1,59 @@
+# @halo-ads/core
+
+> Framework-agnostic Halo Ads SDK core — ad fetching, DOM rendering, event tracking, and user profiling.
+
+## Install
+
+```bash
+pnpm add @halo-ads/core
+```
+
+## Key exports
+
+| Export | Description |
+|---|---|
+| `HaloAds` | Main singleton — `init`, `getAd`, `render`, `track`, `getProfile` |
+| `AdClient` | Raw HTTP client for `/v1/decide` |
+| `AdLoader` | Slot-based ad loading with fill/no-fill logic |
+| `Analytics` | Event batching & flush |
+| `EventTracker` | Impression / click tracking |
+| `DOMRenderer` | Renders ad HTML into a container |
+| `Recommendation` | Client-side ad scoring (context affinity) |
+| `ProfileStore` | Persists user profile to `localStorage` |
+| `MockAdProvider` / `MOCK_ADS` | Drop-in mock for testing without an API |
+
+## Usage
+
+```ts
+import { HaloAds, MockAdProvider } from '@halo-ads/core';
+
+// Use real API
+HaloAds.init({ publisherId: 'pub_xxx', apiKey: 'pk_live_...' });
+
+// Or use mock for local dev / testing
+HaloAds.init({ publisherId: 'pub_test' });
+// (core auto-selects MockAdProvider in development when no apiKey is set)
+
+const ad = await HaloAds.getAd({ slot: 'sl_banner', format: 'banner' });
+
+await HaloAds.render({
+  container: '#ad-slot',
+  slot: 'sl_banner',
+  format: 'banner',
+  onImpression: (ad) => console.log('seen:', ad.id),
+  onClick:      (ad) => console.log('clicked:', ad.id),
+});
+```
+
+## Architecture
+
+```
+HaloAds (singleton)
+  ├── AdClient          → POST /v1/decide
+  ├── AdLoader          → manages slot state, fill/no-fill, caching
+  ├── Analytics         → batches TrackEvents, flushes on interval/unload
+  ├── EventTracker      → wraps Analytics with impression/click helpers
+  ├── DOMRenderer       → injects ad HTML, handles theme tokens
+  ├── Recommendation    → scores ads client-side against context_vector
+  └── ProfileStore      → read/write UserProfile in localStorage
+```

package/dist/index.d.mts

@@ -0,0 +1,178 @@
+import { IAnalyticsProvider, HaloConfig, TrackEventName, TrackEventPayload, AnalyticsEvent, IProfileStore, UserProfile, Ad, HaloAdsInstance, AdRequest, RenderOptions, IAdProvider, AdResponse } from '@halo-ads/types';
+export { Ad, AdCategory, AdFormat, AdRequest, AdResponse, AdTheme, AnalyticsEvent, HaloAdsInstance, HaloConfig, IAdProvider, IAnalyticsProvider, IProfileStore, RenderOptions, TrackEventName, TrackEventPayload, UserProfile } from '@halo-ads/types';
+
+declare class Analytics {
+    private config;
+    private sessionId;
+    private provider;
+    constructor(provider?: IAnalyticsProvider);
+    configure(config: HaloConfig, sessionId: string): void;
+    track(name: TrackEventName, payload?: TrackEventPayload): void;
+}
+declare class ConsoleAnalyticsProvider implements IAnalyticsProvider {
+    send(event: AnalyticsEvent): Promise<void>;
+}
+
+declare class ProfileStore implements IProfileStore {
+    private profile;
+    private storageAvailable;
+    constructor();
+    private load;
+    private save;
+    get(): UserProfile;
+    update(partial: Partial<UserProfile>): void;
+    /** Add an ad ID to the seen list (for frequency capping) */
+    markAdSeen(adId: string): void;
+    /** Add an interest if not already present */
+    addInterest(interest: string): void;
+    clear(): void;
+}
+
+declare class EventTracker {
+    private analytics;
+    private profileStore;
+    private trackedImpressions;
+    private debug;
+    constructor(analytics: Analytics, profileStore: ProfileStore, debug?: boolean);
+    trackImpression(ad: Ad, slot: string): void;
+    trackClick(ad: Ad, slot: string): void;
+    trackView(ad: Ad, slot: string): void;
+    /** Set up IntersectionObserver to auto-track impressions */
+    observeElement(element: HTMLElement, ad: Ad, slot: string): () => void;
+}
+
+declare class HaloAdsSDK implements HaloAdsInstance {
+    private config;
+    private profileStore;
+    private analytics;
+    private tracker;
+    private client;
+    private loader;
+    private renderer;
+    private recommendation;
+    /**
+     * Initialize the Halo Ads SDK.
+     * Must be called before any other methods.
+     *
+     * @example
+     * HaloAds.init({
+     *   publisherId: "pub_001",
+     *   apiKey: "pk_test_...",
+     *   debug: true
+     * });
+     */
+    init(config: HaloConfig): void;
+    /**
+     * Track an analytics event.
+     *
+     * @example
+     * HaloAds.track("page_view")
+     * HaloAds.track("click", { adId: "ad_001" })
+     * HaloAds.track("purchase", { value: 49.99 })
+     */
+    track(name: TrackEventName, payload?: TrackEventPayload): void;
+    /**
+     * Fetch an ad for a slot.
+     *
+     * @example
+     * const ad = await HaloAds.getAd({ slot: "hero" })
+     */
+    getAd(request: AdRequest): Promise<Ad | null>;
+    /**
+     * Render an ad into a DOM container.
+     * Works like Google Adsense — just point at a container.
+     *
+     * @example
+     * HaloAds.render({ container: "#banner", slot: "hero" })
+     */
+    render(options: RenderOptions): Promise<void>;
+    /**
+     * Get the current user profile.
+     */
+    getProfile(): UserProfile;
+    /**
+     * Get recommended ads based on user profile.
+     */
+    getRecommended(limit?: number): Ad[];
+    /**
+     * Whether the SDK has been initialized.
+     */
+    isInitialized(): boolean;
+    /**
+     * Destroy the SDK instance (useful for testing / cleanup).
+     */
+    destroy(): void;
+    /** @internal */
+    _getTracker(): EventTracker;
+    /** @internal */
+    _getProfileStore(): ProfileStore;
+    private assertInitialized;
+}
+declare const HaloAds: HaloAdsSDK;
+
+declare class AdClient {
+    private provider;
+    private publisherId;
+    private debug;
+    constructor(provider: IAdProvider, publisherId: string, debug?: boolean);
+    fetchAd(slot: string, options?: Partial<AdRequest>): Promise<Ad | null>;
+    fetchMultiple(slots: string[], options?: Partial<AdRequest>): Promise<Record<string, Ad | null>>;
+}
+
+declare class AdLoader {
+    private client;
+    private cache;
+    private debug;
+    private loading;
+    constructor(client: AdClient, debug?: boolean);
+    private isCacheValid;
+    private getCategoryHint;
+    load(slot: string, options?: Partial<AdRequest>): Promise<Ad | null>;
+    /** Clear cache for a slot (force refresh on next load) */
+    invalidate(slot?: string): void;
+}
+
+declare class Recommendation {
+    /**
+     * Rank ads by user interest score.
+     * Categories matching user interests are scored higher.
+     * Future: embed-based cosine similarity against interest vectors.
+     */
+    rankAds(ads: Ad[], profile: UserProfile): Ad[];
+    /**
+     * Get recommended ads for a user.
+     * Returns ranked list excluding recently seen (if possible).
+     */
+    getRecommended(profile: UserProfile, limit?: number): Ad[];
+}
+
+declare class DOMRenderer {
+    private tracker;
+    private debug;
+    private activeCount;
+    private timers;
+    constructor(tracker: EventTracker, debug?: boolean);
+    private resolveContainer;
+    private closePopup;
+    render(ad: Ad, options: RenderOptions): Promise<void>;
+    clear(container: string | HTMLElement): void;
+}
+
+declare const MOCK_ADS: Ad[];
+declare class MockAdProvider implements IAdProvider {
+    private ads;
+    /**
+     * Simulate network latency for a realistic dev experience.
+     */
+    private delay;
+    /**
+     * Pick an ad for a given request. In a real implementation this
+     * would call POST /v1/decide with targeting parameters.
+     */
+    fetchAd(request: AdRequest): Promise<AdResponse>;
+    fetchAds(requests: AdRequest[]): Promise<AdResponse[]>;
+    /** Exposed for testing / preview */
+    getAllAds(): Ad[];
+}
+
+export { AdClient, AdLoader, Analytics, ConsoleAnalyticsProvider, DOMRenderer, EventTracker, HaloAds, MOCK_ADS, MockAdProvider, ProfileStore, Recommendation };

package/dist/index.d.ts

@@ -0,0 +1,178 @@
+import { IAnalyticsProvider, HaloConfig, TrackEventName, TrackEventPayload, AnalyticsEvent, IProfileStore, UserProfile, Ad, HaloAdsInstance, AdRequest, RenderOptions, IAdProvider, AdResponse } from '@halo-ads/types';
+export { Ad, AdCategory, AdFormat, AdRequest, AdResponse, AdTheme, AnalyticsEvent, HaloAdsInstance, HaloConfig, IAdProvider, IAnalyticsProvider, IProfileStore, RenderOptions, TrackEventName, TrackEventPayload, UserProfile } from '@halo-ads/types';
+
+declare class Analytics {
+    private config;
+    private sessionId;
+    private provider;
+    constructor(provider?: IAnalyticsProvider);
+    configure(config: HaloConfig, sessionId: string): void;
+    track(name: TrackEventName, payload?: TrackEventPayload): void;
+}
+declare class ConsoleAnalyticsProvider implements IAnalyticsProvider {
+    send(event: AnalyticsEvent): Promise<void>;
+}
+
+declare class ProfileStore implements IProfileStore {
+    private profile;
+    private storageAvailable;
+    constructor();
+    private load;
+    private save;
+    get(): UserProfile;
+    update(partial: Partial<UserProfile>): void;
+    /** Add an ad ID to the seen list (for frequency capping) */
+    markAdSeen(adId: string): void;
+    /** Add an interest if not already present */
+    addInterest(interest: string): void;
+    clear(): void;
+}
+
+declare class EventTracker {
+    private analytics;
+    private profileStore;
+    private trackedImpressions;
+    private debug;
+    constructor(analytics: Analytics, profileStore: ProfileStore, debug?: boolean);
+    trackImpression(ad: Ad, slot: string): void;
+    trackClick(ad: Ad, slot: string): void;
+    trackView(ad: Ad, slot: string): void;
+    /** Set up IntersectionObserver to auto-track impressions */
+    observeElement(element: HTMLElement, ad: Ad, slot: string): () => void;
+}
+
+declare class HaloAdsSDK implements HaloAdsInstance {
+    private config;
+    private profileStore;
+    private analytics;
+    private tracker;
+    private client;
+    private loader;
+    private renderer;
+    private recommendation;
+    /**
+     * Initialize the Halo Ads SDK.
+     * Must be called before any other methods.
+     *
+     * @example
+     * HaloAds.init({
+     *   publisherId: "pub_001",
+     *   apiKey: "pk_test_...",
+     *   debug: true
+     * });
+     */
+    init(config: HaloConfig): void;
+    /**
+     * Track an analytics event.
+     *
+     * @example
+     * HaloAds.track("page_view")
+     * HaloAds.track("click", { adId: "ad_001" })
+     * HaloAds.track("purchase", { value: 49.99 })
+     */
+    track(name: TrackEventName, payload?: TrackEventPayload): void;
+    /**
+     * Fetch an ad for a slot.
+     *
+     * @example
+     * const ad = await HaloAds.getAd({ slot: "hero" })
+     */
+    getAd(request: AdRequest): Promise<Ad | null>;
+    /**
+     * Render an ad into a DOM container.
+     * Works like Google Adsense — just point at a container.
+     *
+     * @example
+     * HaloAds.render({ container: "#banner", slot: "hero" })
+     */
+    render(options: RenderOptions): Promise<void>;
+    /**
+     * Get the current user profile.
+     */
+    getProfile(): UserProfile;
+    /**
+     * Get recommended ads based on user profile.
+     */
+    getRecommended(limit?: number): Ad[];
+    /**
+     * Whether the SDK has been initialized.
+     */
+    isInitialized(): boolean;
+    /**
+     * Destroy the SDK instance (useful for testing / cleanup).
+     */
+    destroy(): void;
+    /** @internal */
+    _getTracker(): EventTracker;
+    /** @internal */
+    _getProfileStore(): ProfileStore;
+    private assertInitialized;
+}
+declare const HaloAds: HaloAdsSDK;
+
+declare class AdClient {
+    private provider;
+    private publisherId;
+    private debug;
+    constructor(provider: IAdProvider, publisherId: string, debug?: boolean);
+    fetchAd(slot: string, options?: Partial<AdRequest>): Promise<Ad | null>;
+    fetchMultiple(slots: string[], options?: Partial<AdRequest>): Promise<Record<string, Ad | null>>;
+}
+
+declare class AdLoader {
+    private client;
+    private cache;
+    private debug;
+    private loading;
+    constructor(client: AdClient, debug?: boolean);
+    private isCacheValid;
+    private getCategoryHint;
+    load(slot: string, options?: Partial<AdRequest>): Promise<Ad | null>;
+    /** Clear cache for a slot (force refresh on next load) */
+    invalidate(slot?: string): void;
+}
+
+declare class Recommendation {
+    /**
+     * Rank ads by user interest score.
+     * Categories matching user interests are scored higher.
+     * Future: embed-based cosine similarity against interest vectors.
+     */
+    rankAds(ads: Ad[], profile: UserProfile): Ad[];
+    /**
+     * Get recommended ads for a user.
+     * Returns ranked list excluding recently seen (if possible).
+     */
+    getRecommended(profile: UserProfile, limit?: number): Ad[];
+}
+
+declare class DOMRenderer {
+    private tracker;
+    private debug;
+    private activeCount;
+    private timers;
+    constructor(tracker: EventTracker, debug?: boolean);
+    private resolveContainer;
+    private closePopup;
+    render(ad: Ad, options: RenderOptions): Promise<void>;
+    clear(container: string | HTMLElement): void;
+}
+
+declare const MOCK_ADS: Ad[];
+declare class MockAdProvider implements IAdProvider {
+    private ads;
+    /**
+     * Simulate network latency for a realistic dev experience.
+     */
+    private delay;
+    /**
+     * Pick an ad for a given request. In a real implementation this
+     * would call POST /v1/decide with targeting parameters.
+     */
+    fetchAd(request: AdRequest): Promise<AdResponse>;
+    fetchAds(requests: AdRequest[]): Promise<AdResponse[]>;
+    /** Exposed for testing / preview */
+    getAllAds(): Ad[];
+}
+
+export { AdClient, AdLoader, Analytics, ConsoleAnalyticsProvider, DOMRenderer, EventTracker, HaloAds, MOCK_ADS, MockAdProvider, ProfileStore, Recommendation };