@the_ro_show/agent-ads-sdk 0.4.2 → 0.5.0

package/dist/index.d.mts

@@ -197,11 +197,189 @@ interface APIError {
 interface SDKConfig {
     apiKey: string;
     agentId?: string;
+    appId?: string;
     supabaseAnonKey?: string;
     baseUrl?: string;
     timeoutMs?: number;
     maxRetries?: number;
 }
+/**
+ * Request an offer using explicit intent-key matching.
+ *
+ * This is the deterministic, high-confidence API for when you KNOW what
+ * the user wants. Use intentKey for exact matching instead of semantic search.
+ *
+ * @example
+ * ```typescript
+ * const offer = await client.requestOffer({
+ *   placementId: 'chat_suggestion',
+ *   intentKey: 'coffee.purchase.nearby',
+ *   context: {
+ *     geo: { city: 'NYC', country: 'US' }
+ *   }
+ * });
+ * ```
+ */
+interface RequestOfferParams {
+    /** Placement identifier (e.g., 'chat_suggestion', 'inline_card') */
+    placementId: string;
+    /**
+     * Intent key for matching (e.g., 'coffee', 'coffee.purchase', 'legal.estate_planning')
+     * Uses hierarchical matching: tries exact match, then walks up taxonomy.
+     */
+    intentKey: string;
+    /**
+     * PREVIEW: Source agent for revenue share tracking (optional)
+     *
+     * When another agent refers traffic to you, they can include their
+     * agent_id to track referrals. When revenue share is enabled (future),
+     * the source agent will receive the specified percentage.
+     *
+     * @experimental Revenue share not active yet - logs for analytics only
+     */
+    sourceAgentId?: string;
+    /**
+     * PREVIEW: Revenue share percentage for source agent (0-50)
+     * Only applies if sourceAgentId is provided.
+     *
+     * @experimental Revenue share not active yet
+     */
+    revenueSharePct?: number;
+    /** Context for targeting and personalization */
+    context?: {
+        /** Geographic context */
+        geo?: {
+            country?: string;
+            region?: string;
+            city?: string;
+            lat?: number;
+            lng?: number;
+        };
+        /** Locale for language/region targeting */
+        locale?: string;
+        /**
+         * Optional semantic context for fallback matching.
+         * If exact intent-key match fails, system will try semantic matching
+         * using this context within the intent-key category.
+         */
+        semanticContext?: string;
+        /**
+         * User context identifier for deduplication (optional)
+         * Use a session hash or similar - NO PII
+         */
+        userContextId?: string;
+    };
+    /** Constraints for filtering offers */
+    constraints?: {
+        /** Minimum CPC in micros (e.g., 1000000 = $1.00) */
+        minCpcMicros?: number;
+        /** Block specific campaigns from being returned */
+        blockCampaignIds?: string[];
+    };
+}
+/**
+ * Request an offer using semantic context matching.
+ *
+ * This is the fuzzy, discovery API for when you're NOT certain what
+ * the user wants. Pass conversation context and let semantic search
+ * figure out the best match.
+ *
+ * @example
+ * ```typescript
+ * const offer = await client.requestOfferFromContext({
+ *   placementId: 'chat_suggestion',
+ *   userMessage: "I'm so tired, long day...",
+ *   conversationHistory: ["How was work?", "Exhausting"],
+ *   context: { geo: { city: 'NYC' } }
+ * });
+ * ```
+ */
+interface RequestOfferFromContextParams {
+    /** Placement identifier */
+    placementId: string;
+    /** User's current message */
+    userMessage: string;
+    /**
+     * Optional conversation history for context.
+     * SDK automatically limits to last 5 messages.
+     */
+    conversationHistory?: string[];
+    /**
+     * PREVIEW: Source agent for revenue share tracking (optional)
+     * @experimental Revenue share not active yet
+     */
+    sourceAgentId?: string;
+    /**
+     * PREVIEW: Revenue share percentage (0-50)
+     * @experimental Revenue share not active yet
+     */
+    revenueSharePct?: number;
+    /** Context for targeting */
+    context?: {
+        geo?: {
+            country?: string;
+            region?: string;
+            city?: string;
+        };
+        locale?: string;
+        userContextId?: string;
+    };
+    /** Optional category hint as fallback */
+    suggestedCategory?: string;
+}
+/**
+ * Offer response (intent-key or semantic matching)
+ */
+interface OfferResponse {
+    /** Unique offer identifier */
+    offer_id: string;
+    /** Request that generated this offer */
+    request_id: string;
+    /** Impression identifier for tracking */
+    impression_id: string;
+    /** Campaign that won the auction */
+    campaign_id: string;
+    /** Creative content */
+    creative: {
+        title: string;
+        body: string;
+        cta: string;
+    };
+    /** Click URL for tracking */
+    click_url: string;
+    /** Direct landing URL (no tracking) */
+    direct_url: string;
+    /** Disclosure information */
+    disclosure: {
+        label: string;
+        sponsor_name: string;
+    };
+    /**
+     * Tracking token for manual impression/click tracking.
+     * Only needed if you use direct_url instead of click_url.
+     */
+    tracking_token: string;
+    /** Match metadata */
+    match_info: {
+        /** How was this matched: 'intent_key' | 'semantic' | 'hybrid' */
+        match_method: 'intent_key' | 'semantic' | 'hybrid';
+        /** For semantic matches: similarity score (0-1) */
+        similarity?: number;
+        /** Intent key that matched (may differ from request if hierarchical) */
+        matched_intent_key?: string;
+    };
+    /**
+     * Revenue share information (preview)
+     * @experimental Not active yet
+     */
+    revenue_share?: {
+        status: 'preview' | 'active';
+        source_agent_id?: string;
+        source_agent_pct?: number;
+    };
+    /** Time-to-live in milliseconds */
+    ttl_ms: number;
+}
 
 /**
  * Utility functions for the AttentionMarket SDK.
@@ -357,6 +535,7 @@ declare function sanitizeURL(url: string | null | undefined, options?: SanitizeU
 declare class AttentionMarketClient {
     private http;
     private agentId;
+    private appId;
     constructor(config: SDKConfig);
     /**
      * Validate SDK configuration for security
@@ -422,6 +601,91 @@ declare class AttentionMarketClient {
     static signupAgent(request: AgentSignupRequest, options?: {
         baseUrl?: string;
     }): Promise<AgentSignupResponse>;
+    /**
+     * Validate intent-key format.
+     * Format: vertical.category[.subcategory][.intent]
+     * Examples: "coffee", "coffee.purchase", "legal.estate_planning.wills"
+     */
+    private validateIntentKey;
+    /**
+     * Validate placement ID is not empty
+     */
+    private validatePlacementId;
+    /**
+     * Validate revenue share percentage (0-50)
+     */
+    private validateRevenueShare;
+    /**
+     * Normalize and validate locale string
+     */
+    private normalizeLocale;
+    /**
+     * Request an offer using explicit intent-key matching.
+     *
+     * Use this API when you have HIGH CONFIDENCE about user intent.
+     * Intent-keys enable deterministic matching and agent-to-agent coordination.
+     *
+     * **Current Limitations:**
+     * - Backend uses semantic matching (intentKey mapped to taxonomy field)
+     * - `campaign_id` not yet available from backend (returns `unit_id` as placeholder)
+     * - `click_url` equals `direct_url` (click redirector not implemented)
+     * - Revenue share tracked but payouts not active (preview mode)
+     *
+     * @example
+     * ```typescript
+     * // User explicitly said "order coffee for delivery"
+     * const offer = await client.requestOffer({
+     *   placementId: 'order_card',
+     *   intentKey: 'coffee.purchase.delivery',
+     *   context: { geo: { city: 'SF', country: 'US' } }
+     * });
+     *
+     * if (offer) {
+     *   // Use tracked click URL for attribution
+     *   window.open(offer.click_url);
+     * }
+     * ```
+     *
+     * @throws {Error} If agentId or appId not provided in SDKConfig
+     * @throws {Error} If intentKey format is invalid
+     * @throws {Error} If revenueSharePct out of range (0-50)
+     */
+    requestOffer(params: RequestOfferParams, options?: {
+        idempotencyKey?: string;
+    }): Promise<OfferResponse | null>;
+    /**
+     * Request an offer using semantic context matching.
+     *
+     * This is the fuzzy, discovery API for when you're NOT certain what
+     * the user wants. Pass conversation context and let semantic search
+     * figure out the best match.
+     *
+     * **Current Limitations:**
+     * - `campaign_id` not yet available from backend (returns `unit_id` as placeholder)
+     * - `click_url` equals `direct_url` (click redirector not implemented)
+     * - Revenue share tracked but payouts not active (preview mode)
+     * - Conversation history auto-limited to last 5 messages
+     *
+     * @example
+     * ```typescript
+     * const offer = await client.requestOfferFromContext({
+     *   placementId: 'chat_suggestion',
+     *   userMessage: "I'm so tired, long day at work...",
+     *   conversationHistory: ["How was your day?", "Exhausting"],
+     *   context: { geo: { city: 'NYC' } }
+     * });
+     *
+     * if (offer) {
+     *   console.log(`Maybe you'd like: ${offer.creative.title}`);
+     * }
+     * ```
+     *
+     * @throws {Error} If agentId was not provided in SDKConfig
+     * @throws {Error} If revenueSharePct out of range (0-50)
+     */
+    requestOfferFromContext(params: RequestOfferFromContextParams, options?: {
+        idempotencyKey?: string;
+    }): Promise<OfferResponse | null>;
 }
 
 /**
@@ -548,6 +812,127 @@ declare class TimeoutError extends AttentionMarketError {
     constructor(message?: string);
 }
 
+/**
+ * Natural ad formatting utilities
+ *
+ * Transforms ad copy to feel more conversational while preserving
+ * all tracking data and disclosure requirements.
+ */
+
+interface NaturalFormatOptions {
+    /**
+     * Tone/style for the formatted text
+     * - 'conversational': Friendly, natural language
+     * - 'helpful': Informative assistant tone
+     * - 'direct': Clear and concise
+     */
+    style?: 'conversational' | 'helpful' | 'direct';
+    /**
+     * Optional user context to make formatting more relevant
+     * Example: "User is looking for estate planning help"
+     */
+    userContext?: string;
+    /**
+     * Maximum length for formatted text (characters)
+     * Will truncate gracefully if needed
+     */
+    maxLength?: number;
+    /**
+     * Whether to include the disclosure inline
+     * Default: true (always show sponsored label)
+     */
+    includeDisclosure?: boolean;
+}
+interface FormattedAd {
+    /**
+     * Naturally formatted text suitable for conversation
+     */
+    text: string;
+    /**
+     * Call-to-action text
+     */
+    cta: string;
+    /**
+     * Action URL (preserved from original ad)
+     */
+    actionUrl: string;
+    /**
+     * Tracking data (preserved from original ad)
+     * IMPORTANT: Pass this to trackClick() when user clicks
+     */
+    tracking: {
+        eventId: string;
+        trackingToken: string;
+        decisionId: string;
+    };
+    /**
+     * Disclosure information (preserved from original ad)
+     */
+    disclosure: {
+        label: string;
+        sponsorName: string;
+    };
+}
+/**
+ * Format an ad unit into natural conversational text.
+ * Preserves all tracking data and disclosure requirements.
+ *
+ * @example
+ * ```typescript
+ * const ad = await client.decide({...});
+ * const formatted = formatNatural(ad, {
+ *   style: 'conversational',
+ *   userContext: "User needs estate planning help"
+ * });
+ *
+ * console.log(formatted.text);
+ * // "I found a service that might help: [Title]. [Body]"
+ *
+ * // When user clicks, tracking still works:
+ * await client.trackClick({
+ *   event_id: formatted.tracking.eventId,
+ *   tracking_token: formatted.tracking.trackingToken
+ * });
+ * ```
+ */
+declare function formatNatural(ad: AdUnit, options?: NaturalFormatOptions): FormattedAd;
+/**
+ * Extract just the essential info from an ad for inline mentions.
+ * Useful when you want to reference an ad without showing the full text.
+ *
+ * @example
+ * ```typescript
+ * const mention = formatInlineMention(ad);
+ * console.log(`You might want to check out ${mention.text}`);
+ * // "You might want to check out Estate Planning Services (Sponsored)"
+ * ```
+ */
+declare function formatInlineMention(ad: AdUnit): FormattedAd;
+/**
+ * Validate that an ad fits within UI constraints.
+ * Helps developers check if ad will display correctly before showing it.
+ *
+ * @example
+ * ```typescript
+ * const validation = validateAdFits(ad, {
+ *   maxTitleChars: 60,
+ *   maxBodyChars: 200
+ * });
+ *
+ * if (!validation.fits) {
+ *   console.log('Ad too long:', validation.violations);
+ * }
+ * ```
+ */
+declare function validateAdFits(ad: AdUnit, constraints: {
+    maxTitleChars?: number;
+    maxBodyChars?: number;
+    maxCtaChars?: number;
+}): {
+    fits: boolean;
+    violations: string[];
+};
+
 /**
  * Taxonomy helper utilities for AttentionMarket SDK
  * Helps with building, validating, and working with the 4-tier taxonomy system
@@ -705,4 +1090,4 @@ declare function getVertical(taxonomy: string): string | null;
  */
 declare function suggestTaxonomies(query: string): string[];
 
-export { type APIError, APIRequestError, 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 Intent, MockAttentionMarketClient, type MockClientConfig, NetworkError, type Opportunity, type ParsedTaxonomy, type Placement, type PlacementType, type PolicyResponse, type Privacy, type SDKConfig, type SanitizeURLOptions, type SponsoredSuggestion, type SponsoredTool, type TaxonomyIntent, TimeoutError, type ToolCall, type Tracking, buildTaxonomy, createClickEvent, createImpressionEvent, createOpportunity, detectIntent, escapeHTML, generateTimestamp, generateUUID, getBaseTaxonomy, getVertical, isValidTaxonomy, matchesTaxonomy, parseTaxonomy, sanitizeURL, suggestTaxonomies };
+export { type APIError, APIRequestError, 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 };