@the_ro_show/agent-ads-sdk 0.15.1 → 0.16.0

package/README.md

@@ -5,12 +5,24 @@
 
 Monetize your AI application with contextual advertising. AttentionMarket matches user intent with relevant sponsored content, enabling you to generate revenue from every conversation.
 
+## 📚 Documentation
+
+**Full documentation with REST API reference, mobile integration guides, and examples:**
+### → [https://rtrivedi.github.io/agent-ads-sdk/](https://rtrivedi.github.io/agent-ads-sdk/)
+
 ## Installation
 
 ```bash
 npm install @the_ro_show/agent-ads-sdk
 ```
 
+### For Non-Node.js Platforms
+
+See our [REST API Reference](https://rtrivedi.github.io/agent-ads-sdk/docs/api-reference) for direct HTTP integration in any language:
+- Python, Go, Ruby, PHP
+- iOS/Swift, Android/Kotlin
+- Direct cURL/HTTP
+
 ## Quick Start
 
 ```typescript
@@ -85,16 +97,18 @@ const ad = await client.decideFromContext({
 });
 ```
 
-### Performance Impact
+### Expected Performance Impact
 
-Smart context improves key metrics:
+Smart context is projected to improve key metrics:
 
-| Feature | CTR Improvement | Revenue Impact |
-|---------|----------------|----------------|
-| Intent Detection | +35% | +42% |
-| Interest Matching | +28% | +31% |
-| Session Tracking | +15% | +18% |
-| Combined | **+65%** | **+78%** |
+| Feature | Expected CTR Improvement | Expected Revenue Impact |
+|---------|-------------------------|------------------------|
+| Intent Detection | +30-40% | +35-45% |
+| Interest Matching | +20-30% | +25-35% |
+| Session Tracking | +10-20% | +15-25% |
+| Combined | **+50-70%** | **+60-80%** |
+
+*Note: These are projected improvements based on early testing. Actual results may vary.*
 
 ### Best Practices
 
@@ -162,8 +176,9 @@ const client = new AttentionMarketClient({
 
 ```typescript
 const client = new AttentionMarketClient({
-  apiKey: 'am_live_YOUR_KEY',        // Required
+  apiKey: 'am_live_YOUR_KEY',        // Required: Your AttentionMarket API key
   agentId: 'agt_YOUR_AGENT_ID',      // Required for decideFromContext()
+  supabaseAnonKey: 'YOUR_ANON_KEY',  // Required: Get from dashboard
   // baseUrl defaults to production Supabase endpoint
   // Only override if self-hosting or using different environment
   timeoutMs: 4000,                   // Optional: request timeout in milliseconds
@@ -171,6 +186,8 @@ const client = new AttentionMarketClient({
 });
 ```
 
+**Note:** You need both `apiKey` (AttentionMarket) and `supabaseAnonKey` (infrastructure) for authentication. Get both from your [developer dashboard](https://api.attentionmarket.ai).
+
 ## Core Concepts
 
 ### Placements
@@ -528,28 +545,20 @@ const ad = await client.decideFromContext({
 
 ### Click Tracking
 
-Clicks are automatically tracked when users visit `click_url`. For manual tracking:
+Clicks are automatically and securely tracked when users visit the `click_url`.
 
-```typescript
-await client.trackClick({
-  agent_id: 'agt_YOUR_AGENT_ID',
-  request_id: ad.request_id,
-  decision_id: ad.decision_id,
-  unit_id: ad._ad.unit_id,
-  tracking_token: ad.tracking_token,
-  href: ad.click_url,
-  click_context: "User clicked 'Get a Quote' button"
-});
-```
-
-Simplified tracking from ad object:
+**Important:** Always use the provided `click_url` or `tracking_url` for click tracking. These URLs contain HMAC-signed tokens that prevent click fraud and ensure accurate attribution.
 
 ```typescript
-await client.trackClickFromAd(ad, {
-  click_context: "User clicked on sponsored suggestion"
-});
+// When user clicks the ad, redirect them to:
+window.location.href = ad.click_url;
+
+// Or in a chat/messaging context, share:
+const shareableLink = ad.tracking_url;
 ```
 
+Manual click tracking has been removed for security reasons. All clicks must go through the redirect URLs to ensure fraud prevention and accurate tracking.
+
 ### Conversion Tracking
 
 Track conversions (purchases, signups, etc.) to improve advertiser ROI and your quality score:
@@ -625,6 +634,36 @@ Use test API keys (`am_test_...`) for development and testing. Test keys:
 
 Switch to live keys (`am_live_...`) when deploying to production.
 
+## 🌍 REST API for Mobile & Other Platforms
+
+For non-Node.js platforms, use our REST API directly:
+
+### iOS/Swift Example
+```swift
+// See full guide: https://rtrivedi.github.io/agent-ads-sdk/docs/mobile-integration
+let url = URL(string: "https://peruwnbrqkvmrldhpoom.supabase.co/functions/v1/decide")!
+var request = URLRequest(url: url)
+request.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")
+request.setValue(supabaseAnonKey, forHTTPHeaderField: "apikey")
+// ... see docs for complete example
+```
+
+### Python Example
+```python
+# See full guide: https://rtrivedi.github.io/agent-ads-sdk/docs/api-reference
+import requests
+response = requests.post(
+    "https://peruwnbrqkvmrldhpoom.supabase.co/functions/v1/decide",
+    headers={
+        "Authorization": f"Bearer {api_key}",
+        "apikey": supabase_anon_key
+    },
+    json={"user_message": "I need insurance"}
+)
+```
+
+**📖 Full REST API Documentation:** [https://rtrivedi.github.io/agent-ads-sdk/docs/api-reference](https://rtrivedi.github.io/agent-ads-sdk/docs/api-reference)
+
 ## 🤖 Claude Code Integration
 
 Building with Claude Code? We've created ready-to-use prompts for seamless integration.

package/dist/index.d.mts

@@ -773,24 +773,6 @@ interface CreateImpressionEventParams {
  * @returns EventIngestRequest ready to pass to client.track()
  */
 declare function createImpressionEvent(params: CreateImpressionEventParams): EventIngestRequest;
-interface CreateClickEventParams {
-    agent_id: string;
-    request_id: string;
-    decision_id: string;
-    unit_id: string;
-    tracking_token: string;
-    href: string;
-    click_context: string;
-    occurred_at?: string;
-    metadata?: Record<string, unknown>;
-}
-/**
- * Helper to create a click event payload.
- *
- * @param params - Event parameters (snake_case to match API)
- * @returns EventIngestRequest ready to pass to client.track()
- */
-declare function createClickEvent(params: CreateClickEventParams): EventIngestRequest;
 /**
  * Options for URL sanitization
  */
@@ -922,35 +904,6 @@ declare class AttentionMarketClient {
     trackImpression(params: Omit<CreateImpressionEventParams, 'occurred_at'> & {
         occurred_at?: string;
     }): Promise<EventIngestResponse>;
-    /**
-     * Convenience method to track a click event.
-     * Creates a click event using createClickEvent() and calls track().
-     */
-    trackClick(params: Omit<CreateClickEventParams, 'occurred_at'> & {
-        occurred_at?: string;
-    }): Promise<EventIngestResponse>;
-    /**
-     * Ultra-simple method to track a click from an ad returned by decideFromContext().
-     * Automatically extracts all required fields from the ad object.
-     *
-     * @param ad - The ad object returned by decideFromContext()
-     * @param options - Just click_context (what you showed the user)
-     *
-     * @example
-     * ```typescript
-     * const ad = await client.decideFromContext({ userMessage: "I need car insurance" });
-     * if (ad) {
-     *   await client.trackClickFromAd(ad, {
-     *     click_context: "Progressive: Get 20% off - Compare quotes"
-     *   });
-     * }
-     * ```
-     */
-    trackClickFromAd(ad: AdResponse, options: {
-        click_context: string;
-        metadata?: Record<string, unknown>;
-        occurred_at?: string;
-    }): Promise<EventIngestResponse>;
     /**
      * Send feedback on an ad's performance to earn conversion-validated bonuses.
      *
@@ -1584,4 +1537,4 @@ declare function getVertical(taxonomy: string): string | null;
  */
 declare function suggestTaxonomies(query: string): string[];
 
-export { type APIError, APIRequestError, type AdResponse, type AdScore, type AdUnit, type AgentSignupRequest, type AgentSignupResponse, AttentionMarketClient, AttentionMarketError, type Constraints, type Context, type CreateClickEventParams, type CreateImpressionEventParams, type CreateOpportunityParams, type DecideFromContextRequest, type DecideRequest, type DecideResponse, type Disclosure, type EventIngestRequest, type EventIngestResponse, type EventType, type FormattedAd, type Intent, MockAttentionMarketClient, type MockClientConfig, type NaturalFormatOptions, NetworkError, type OfferResponse, type Opportunity, type ParsedTaxonomy, type Placement, type PlacementType, type PolicyResponse, type Privacy, type RequestOfferFromContextParams, type RequestOfferParams, type SDKConfig, type SanitizeURLOptions, type SponsoredSuggestion, type SponsoredTool, type TaxonomyIntent, TimeoutError, type ToolCall, type Tracking, buildTaxonomy, createClickEvent, createImpressionEvent, createOpportunity, detectIntent, escapeHTML, formatInlineMention, formatNatural, generateTimestamp, generateUUID, getBaseTaxonomy, getVertical, isValidTaxonomy, matchesTaxonomy, parseTaxonomy, sanitizeURL, suggestTaxonomies, validateAdFits };
+export { type APIError, APIRequestError, type AdResponse, type AdScore, type AdUnit, type AgentSignupRequest, type AgentSignupResponse, AttentionMarketClient, AttentionMarketError, type Constraints, type Context, type CreateImpressionEventParams, type CreateOpportunityParams, type DecideFromContextRequest, type DecideRequest, type DecideResponse, type Disclosure, type EventIngestRequest, type EventIngestResponse, type EventType, type FormattedAd, type Intent, MockAttentionMarketClient, type MockClientConfig, type NaturalFormatOptions, NetworkError, type OfferResponse, type Opportunity, type ParsedTaxonomy, type Placement, type PlacementType, type PolicyResponse, type Privacy, type RequestOfferFromContextParams, type RequestOfferParams, type SDKConfig, type SanitizeURLOptions, type SponsoredSuggestion, type SponsoredTool, type TaxonomyIntent, TimeoutError, type ToolCall, type Tracking, buildTaxonomy, createImpressionEvent, createOpportunity, detectIntent, escapeHTML, formatInlineMention, formatNatural, generateTimestamp, generateUUID, getBaseTaxonomy, getVertical, isValidTaxonomy, matchesTaxonomy, parseTaxonomy, sanitizeURL, suggestTaxonomies, validateAdFits };

package/dist/index.d.ts

@@ -773,24 +773,6 @@ interface CreateImpressionEventParams {
  * @returns EventIngestRequest ready to pass to client.track()
  */
 declare function createImpressionEvent(params: CreateImpressionEventParams): EventIngestRequest;
-interface CreateClickEventParams {
-    agent_id: string;
-    request_id: string;
-    decision_id: string;
-    unit_id: string;
-    tracking_token: string;
-    href: string;
-    click_context: string;
-    occurred_at?: string;
-    metadata?: Record<string, unknown>;
-}
-/**
- * Helper to create a click event payload.
- *
- * @param params - Event parameters (snake_case to match API)
- * @returns EventIngestRequest ready to pass to client.track()
- */
-declare function createClickEvent(params: CreateClickEventParams): EventIngestRequest;
 /**
  * Options for URL sanitization
  */
@@ -922,35 +904,6 @@ declare class AttentionMarketClient {
     trackImpression(params: Omit<CreateImpressionEventParams, 'occurred_at'> & {
         occurred_at?: string;
     }): Promise<EventIngestResponse>;
-    /**
-     * Convenience method to track a click event.
-     * Creates a click event using createClickEvent() and calls track().
-     */
-    trackClick(params: Omit<CreateClickEventParams, 'occurred_at'> & {
-        occurred_at?: string;
-    }): Promise<EventIngestResponse>;
-    /**
-     * Ultra-simple method to track a click from an ad returned by decideFromContext().
-     * Automatically extracts all required fields from the ad object.
-     *
-     * @param ad - The ad object returned by decideFromContext()
-     * @param options - Just click_context (what you showed the user)
-     *
-     * @example
-     * ```typescript
-     * const ad = await client.decideFromContext({ userMessage: "I need car insurance" });
-     * if (ad) {
-     *   await client.trackClickFromAd(ad, {
-     *     click_context: "Progressive: Get 20% off - Compare quotes"
-     *   });
-     * }
-     * ```
-     */
-    trackClickFromAd(ad: AdResponse, options: {
-        click_context: string;
-        metadata?: Record<string, unknown>;
-        occurred_at?: string;
-    }): Promise<EventIngestResponse>;
     /**
      * Send feedback on an ad's performance to earn conversion-validated bonuses.
      *
@@ -1584,4 +1537,4 @@ declare function getVertical(taxonomy: string): string | null;
  */
 declare function suggestTaxonomies(query: string): string[];
 
-export { type APIError, APIRequestError, type AdResponse, type AdScore, type AdUnit, type AgentSignupRequest, type AgentSignupResponse, AttentionMarketClient, AttentionMarketError, type Constraints, type Context, type CreateClickEventParams, type CreateImpressionEventParams, type CreateOpportunityParams, type DecideFromContextRequest, type DecideRequest, type DecideResponse, type Disclosure, type EventIngestRequest, type EventIngestResponse, type EventType, type FormattedAd, type Intent, MockAttentionMarketClient, type MockClientConfig, type NaturalFormatOptions, NetworkError, type OfferResponse, type Opportunity, type ParsedTaxonomy, type Placement, type PlacementType, type PolicyResponse, type Privacy, type RequestOfferFromContextParams, type RequestOfferParams, type SDKConfig, type SanitizeURLOptions, type SponsoredSuggestion, type SponsoredTool, type TaxonomyIntent, TimeoutError, type ToolCall, type Tracking, buildTaxonomy, createClickEvent, createImpressionEvent, createOpportunity, detectIntent, escapeHTML, formatInlineMention, formatNatural, generateTimestamp, generateUUID, getBaseTaxonomy, getVertical, isValidTaxonomy, matchesTaxonomy, parseTaxonomy, sanitizeURL, suggestTaxonomies, validateAdFits };
+export { type APIError, APIRequestError, type AdResponse, type AdScore, type AdUnit, type AgentSignupRequest, type AgentSignupResponse, AttentionMarketClient, AttentionMarketError, type Constraints, type Context, type CreateImpressionEventParams, type CreateOpportunityParams, type DecideFromContextRequest, type DecideRequest, type DecideResponse, type Disclosure, type EventIngestRequest, type EventIngestResponse, type EventType, type FormattedAd, type Intent, MockAttentionMarketClient, type MockClientConfig, type NaturalFormatOptions, NetworkError, type OfferResponse, type Opportunity, type ParsedTaxonomy, type Placement, type PlacementType, type PolicyResponse, type Privacy, type RequestOfferFromContextParams, type RequestOfferParams, type SDKConfig, type SanitizeURLOptions, type SponsoredSuggestion, type SponsoredTool, type TaxonomyIntent, TimeoutError, type ToolCall, type Tracking, buildTaxonomy, createImpressionEvent, createOpportunity, detectIntent, escapeHTML, formatInlineMention, formatNatural, generateTimestamp, generateUUID, getBaseTaxonomy, getVertical, isValidTaxonomy, matchesTaxonomy, parseTaxonomy, sanitizeURL, suggestTaxonomies, validateAdFits };

package/dist/index.js

@@ -27,7 +27,6 @@ __export(index_exports, {
   NetworkError: () => NetworkError,
   TimeoutError: () => TimeoutError,
   buildTaxonomy: () => buildTaxonomy,
-  createClickEvent: () => createClickEvent,
   createImpressionEvent: () => createImpressionEvent,
   createOpportunity: () => createOpportunity,
   detectIntent: () => detectIntent,
@@ -247,31 +246,6 @@ function createImpressionEvent(params) {
   }
   return event;
 }
-function createClickEvent(params) {
-  const event = {
-    event_id: generateUUID(),
-    occurred_at: params.occurred_at ?? generateTimestamp(),
-    agent_id: params.agent_id,
-    request_id: params.request_id,
-    decision_id: params.decision_id,
-    unit_id: params.unit_id,
-    event_type: "click",
-    tracking_token: params.tracking_token
-  };
-  if (params.metadata !== void 0) {
-    event.metadata = {
-      ...params.metadata,
-      href: params.href,
-      click_context: params.click_context
-    };
-  } else {
-    event.metadata = {
-      href: params.href,
-      click_context: params.click_context
-    };
-  }
-  return event;
-}
 var HTML_ESCAPES = {
   "&": "&",
   "<": "&lt;",
@@ -897,52 +871,6 @@ var AttentionMarketClient = class {
     const event = createImpressionEvent(params);
     return await this.track(event);
   }
-  /**
-   * Convenience method to track a click event.
-   * Creates a click event using createClickEvent() and calls track().
-   */
-  async trackClick(params) {
-    const event = createClickEvent(params);
-    return await this.track(event);
-  }
-  /**
-   * Ultra-simple method to track a click from an ad returned by decideFromContext().
-   * Automatically extracts all required fields from the ad object.
-   *
-   * @param ad - The ad object returned by decideFromContext()
-   * @param options - Just click_context (what you showed the user)
-   *
-   * @example
-   * ```typescript
-   * const ad = await client.decideFromContext({ userMessage: "I need car insurance" });
-   * if (ad) {
-   *   await client.trackClickFromAd(ad, {
-   *     click_context: "Progressive: Get 20% off - Compare quotes"
-   *   });
-   * }
-   * ```
-   */
-  async trackClickFromAd(ad, options) {
-    if (!this.agentId) {
-      throw new Error("agentId is required for trackClickFromAd(). Set it in the constructor.");
-    }
-    const trackParams = {
-      agent_id: this.agentId,
-      request_id: ad.request_id,
-      decision_id: ad.decision_id,
-      unit_id: ad._ad.unit_id,
-      tracking_token: ad.tracking_token,
-      href: ad.click_url,
-      click_context: options.click_context
-    };
-    if (options.metadata) {
-      trackParams.metadata = options.metadata;
-    }
-    if (options.occurred_at) {
-      trackParams.occurred_at = options.occurred_at;
-    }
-    return await this.trackClick(trackParams);
-  }
   /**
    * Send feedback on an ad's performance to earn conversion-validated bonuses.
    *
@@ -2057,7 +1985,6 @@ function suggestTaxonomies(query) {
   NetworkError,
   TimeoutError,
   buildTaxonomy,
-  createClickEvent,
   createImpressionEvent,
   createOpportunity,
   detectIntent,