@halo-ads/types 0.1.0

package/README.md

@@ -0,0 +1,37 @@
+# @halo-ads/types
+
+> Shared TypeScript types for the Halo Ads SDK — zero runtime, import-only.
+
+This package is a pure type library. It exports no JavaScript at runtime; all exports are `interface`, `type`, and `enum` declarations.
+
+## Install
+
+```bash
+pnpm add @halo-ads/types
+```
+
+## Key types
+
+| Type | Description |
+|---|---|
+| `HaloConfig` | SDK initialisation options |
+| `Ad` | A resolved ad creative |
+| `AdFormat` | `banner \| card \| native \| carousel \| interstitial` |
+| `AdTheme` | CSS-variable-style theme tokens |
+| `AdRequest` / `AdResponse` | Fetch request/response shapes |
+| `TrackEventName` / `TrackEventPayload` | Analytics event envelope |
+| `UserProfile` | Client-side user profile (interests, device, geo) |
+| `IAdProvider` | Interface for swapping mock ↔ real API |
+| `HaloAdsInstance` | Full SDK surface interface |
+
+## Usage
+
+```ts
+import type { Ad, AdFormat, HaloConfig } from '@halo-ads/types';
+
+const config: HaloConfig = {
+  publisherId: 'pub_xxx',
+  apiKey: 'pk_live_...',
+  environment: 'production',
+};
+```

package/dist/index.d.mts

@@ -0,0 +1,124 @@
+interface HaloConfig {
+    /** Your publisher ID from the Halo Ads dashboard */
+    publisherId: string;
+    /** API key (pk_live_... or pk_test_...) */
+    apiKey?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Override the API base URL (for self-hosted / staging) */
+    apiBaseUrl?: string;
+    /** Ad environment */
+    environment?: 'production' | 'staging' | 'development';
+}
+type AdFormat = 'banner' | 'card' | 'native' | 'carousel' | 'interstitial';
+type AdCategory = 'sports' | 'finance' | 'travel' | 'food' | 'gaming' | 'technology' | 'fashion' | 'health' | 'entertainment' | 'other';
+interface Ad {
+    id: string;
+    title: string;
+    description: string;
+    /** URL to the ad creative image */
+    image: string;
+    /** Destination URL when clicked */
+    url: string;
+    category: AdCategory;
+    /** Call-to-action button label */
+    ctaText: string;
+    /** Advertiser name */
+    advertiser?: string;
+    /** Sponsored label override */
+    sponsoredLabel?: string;
+    /** Format hint for renderers */
+    format?: AdFormat;
+    /** Custom theme tokens */
+    theme?: AdTheme;
+}
+interface AdTheme {
+    primaryColor?: string;
+    backgroundColor?: string;
+    textColor?: string;
+    ctaBackground?: string;
+    ctaTextColor?: string;
+    borderRadius?: string;
+}
+interface AdRequest {
+    slot: string;
+    format?: AdFormat;
+    publisherId?: string;
+    /** Optional targeting hints */
+    targeting?: Record<string, string | string[]>;
+}
+interface AdResponse {
+    ad: Ad | null;
+    slot: string;
+    requestId: string;
+    fill: boolean;
+    timestamp: number;
+}
+interface RenderOptions {
+    /** CSS selector or HTMLElement */
+    container: string | HTMLElement;
+    slot: string;
+    format?: AdFormat;
+    theme?: AdTheme;
+    onImpression?: (ad: Ad) => void;
+    onClick?: (ad: Ad) => void;
+}
+type TrackEventName = 'page_view' | 'impression' | 'click' | 'view' | 'purchase' | 'conversion' | 'close' | string;
+interface TrackEventPayload {
+    adId?: string;
+    slot?: string;
+    value?: number;
+    currency?: string;
+    label?: string;
+    [key: string]: unknown;
+}
+interface AnalyticsEvent {
+    name: TrackEventName;
+    payload?: TrackEventPayload;
+    publisherId: string;
+    sessionId: string;
+    timestamp: number;
+    url: string;
+    userAgent: string;
+}
+interface UserProfile {
+    /** Inferred interests from ad interactions */
+    interests: string[];
+    /** Browser language */
+    language: string;
+    /** Inferred country (ISO 3166-1 alpha-2) */
+    country: string;
+    /** Device type */
+    device: 'mobile' | 'tablet' | 'desktop' | 'unknown';
+    /** Unique session ID */
+    sessionId: string;
+    /** Timestamp of first seen */
+    firstSeen: number;
+    /** Timestamp of last seen */
+    lastSeen: number;
+    /** Ad IDs already shown this session */
+    seenAdIds: string[];
+}
+interface IAdProvider {
+    fetchAd(request: AdRequest): Promise<AdResponse>;
+    fetchAds(requests: AdRequest[]): Promise<AdResponse[]>;
+}
+interface IAnalyticsProvider {
+    send(event: AnalyticsEvent): Promise<void>;
+}
+interface IProfileStore {
+    get(): UserProfile;
+    update(partial: Partial<UserProfile>): void;
+    clear(): void;
+}
+interface HaloAdsInstance {
+    init(config: HaloConfig): void;
+    track(name: TrackEventName, payload?: TrackEventPayload): void;
+    getAd(request: AdRequest): Promise<Ad | null>;
+    render(options: RenderOptions): Promise<void>;
+    getProfile(): UserProfile;
+    isInitialized(): boolean;
+    destroy(): void;
+}
+
+export type { Ad, AdCategory, AdFormat, AdRequest, AdResponse, AdTheme, AnalyticsEvent, HaloAdsInstance, HaloConfig, IAdProvider, IAnalyticsProvider, IProfileStore, RenderOptions, TrackEventName, TrackEventPayload, UserProfile };

package/dist/index.d.ts

@@ -0,0 +1,124 @@
+interface HaloConfig {
+    /** Your publisher ID from the Halo Ads dashboard */
+    publisherId: string;
+    /** API key (pk_live_... or pk_test_...) */
+    apiKey?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Override the API base URL (for self-hosted / staging) */
+    apiBaseUrl?: string;
+    /** Ad environment */
+    environment?: 'production' | 'staging' | 'development';
+}
+type AdFormat = 'banner' | 'card' | 'native' | 'carousel' | 'interstitial';
+type AdCategory = 'sports' | 'finance' | 'travel' | 'food' | 'gaming' | 'technology' | 'fashion' | 'health' | 'entertainment' | 'other';
+interface Ad {
+    id: string;
+    title: string;
+    description: string;
+    /** URL to the ad creative image */
+    image: string;
+    /** Destination URL when clicked */
+    url: string;
+    category: AdCategory;
+    /** Call-to-action button label */
+    ctaText: string;
+    /** Advertiser name */
+    advertiser?: string;
+    /** Sponsored label override */
+    sponsoredLabel?: string;
+    /** Format hint for renderers */
+    format?: AdFormat;
+    /** Custom theme tokens */
+    theme?: AdTheme;
+}
+interface AdTheme {
+    primaryColor?: string;
+    backgroundColor?: string;
+    textColor?: string;
+    ctaBackground?: string;
+    ctaTextColor?: string;
+    borderRadius?: string;
+}
+interface AdRequest {
+    slot: string;
+    format?: AdFormat;
+    publisherId?: string;
+    /** Optional targeting hints */
+    targeting?: Record<string, string | string[]>;
+}
+interface AdResponse {
+    ad: Ad | null;
+    slot: string;
+    requestId: string;
+    fill: boolean;
+    timestamp: number;
+}
+interface RenderOptions {
+    /** CSS selector or HTMLElement */
+    container: string | HTMLElement;
+    slot: string;
+    format?: AdFormat;
+    theme?: AdTheme;
+    onImpression?: (ad: Ad) => void;
+    onClick?: (ad: Ad) => void;
+}
+type TrackEventName = 'page_view' | 'impression' | 'click' | 'view' | 'purchase' | 'conversion' | 'close' | string;
+interface TrackEventPayload {
+    adId?: string;
+    slot?: string;
+    value?: number;
+    currency?: string;
+    label?: string;
+    [key: string]: unknown;
+}
+interface AnalyticsEvent {
+    name: TrackEventName;
+    payload?: TrackEventPayload;
+    publisherId: string;
+    sessionId: string;
+    timestamp: number;
+    url: string;
+    userAgent: string;
+}
+interface UserProfile {
+    /** Inferred interests from ad interactions */
+    interests: string[];
+    /** Browser language */
+    language: string;
+    /** Inferred country (ISO 3166-1 alpha-2) */
+    country: string;
+    /** Device type */
+    device: 'mobile' | 'tablet' | 'desktop' | 'unknown';
+    /** Unique session ID */
+    sessionId: string;
+    /** Timestamp of first seen */
+    firstSeen: number;
+    /** Timestamp of last seen */
+    lastSeen: number;
+    /** Ad IDs already shown this session */
+    seenAdIds: string[];
+}
+interface IAdProvider {
+    fetchAd(request: AdRequest): Promise<AdResponse>;
+    fetchAds(requests: AdRequest[]): Promise<AdResponse[]>;
+}
+interface IAnalyticsProvider {
+    send(event: AnalyticsEvent): Promise<void>;
+}
+interface IProfileStore {
+    get(): UserProfile;
+    update(partial: Partial<UserProfile>): void;
+    clear(): void;
+}
+interface HaloAdsInstance {
+    init(config: HaloConfig): void;
+    track(name: TrackEventName, payload?: TrackEventPayload): void;
+    getAd(request: AdRequest): Promise<Ad | null>;
+    render(options: RenderOptions): Promise<void>;
+    getProfile(): UserProfile;
+    isInitialized(): boolean;
+    destroy(): void;
+}
+
+export type { Ad, AdCategory, AdFormat, AdRequest, AdResponse, AdTheme, AnalyticsEvent, HaloAdsInstance, HaloConfig, IAdProvider, IAnalyticsProvider, IProfileStore, RenderOptions, TrackEventName, TrackEventPayload, UserProfile };

package/dist/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+module.exports = __toCommonJS(index_exports);

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@halo-ads/types",
+  "version": "0.1.0",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Shared TypeScript types for Halo Ads SDK — zero runtime, import-only",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "tsup": "^8.0.2",
+    "typescript": "^5.4.5"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}