@the_ro_show/agent-ads-sdk 0.4.2 → 0.4.3

package/dist/index.d.mts

@@ -548,6 +548,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 +826,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 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, formatInlineMention, formatNatural, generateTimestamp, generateUUID, getBaseTaxonomy, getVertical, isValidTaxonomy, matchesTaxonomy, parseTaxonomy, sanitizeURL, suggestTaxonomies, validateAdFits };

package/dist/index.d.ts

@@ -548,6 +548,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 +826,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 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, formatInlineMention, formatNatural, generateTimestamp, generateUUID, getBaseTaxonomy, getVertical, isValidTaxonomy, matchesTaxonomy, parseTaxonomy, sanitizeURL, suggestTaxonomies, validateAdFits };

package/dist/index.js

@@ -32,6 +32,8 @@ __export(index_exports, {
   createOpportunity: () => createOpportunity,
   detectIntent: () => detectIntent,
   escapeHTML: () => escapeHTML,
+  formatInlineMention: () => formatInlineMention,
+  formatNatural: () => formatNatural,
   generateTimestamp: () => generateTimestamp,
   generateUUID: () => generateUUID,
   getBaseTaxonomy: () => getBaseTaxonomy,
@@ -40,7 +42,8 @@ __export(index_exports, {
   matchesTaxonomy: () => matchesTaxonomy,
   parseTaxonomy: () => parseTaxonomy,
   sanitizeURL: () => sanitizeURL,
-  suggestTaxonomies: () => suggestTaxonomies
+  suggestTaxonomies: () => suggestTaxonomies,
+  validateAdFits: () => validateAdFits
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -807,6 +810,128 @@ var MockAttentionMarketClient = class {
   }
 };
 
+// src/formatting.ts
+function formatNatural(ad, options = {}) {
+  if (ad.unit_type !== "sponsored_suggestion") {
+    throw new Error("formatNatural() currently only supports sponsored_suggestion ad units");
+  }
+  const suggestion = ad.suggestion;
+  const style = options.style || "conversational";
+  const includeDisclosure = options.includeDisclosure !== false;
+  let text = "";
+  switch (style) {
+    case "conversational":
+      text = buildConversationalText(suggestion, options.userContext);
+      break;
+    case "helpful":
+      text = buildHelpfulText(suggestion, options.userContext);
+      break;
+    case "direct":
+      text = buildDirectText(suggestion);
+      break;
+  }
+  if (includeDisclosure) {
+    text = `${text}
+
+_${ad.disclosure.label}_ by ${ad.disclosure.sponsor_name}`;
+  }
+  if (options.maxLength && text.length > options.maxLength) {
+    text = truncateGracefully(text, options.maxLength);
+  }
+  return {
+    text,
+    cta: suggestion.cta,
+    actionUrl: suggestion.action_url,
+    tracking: {
+      eventId: ad.unit_id,
+      // Use unit_id as event_id
+      trackingToken: ad.tracking.token,
+      decisionId: ad.unit_id
+      // Use unit_id as decision_id fallback
+    },
+    disclosure: {
+      label: ad.disclosure.label,
+      sponsorName: ad.disclosure.sponsor_name
+    }
+  };
+}
+function buildConversationalText(ad, userContext) {
+  const intro = userContext ? `Based on what you mentioned, I found something that might help: ` : `I found something that might be useful: `;
+  return `${intro}**${ad.title}**. ${ad.body}`;
+}
+function buildHelpfulText(ad, userContext) {
+  const intro = userContext ? `For your situation, here's a relevant service: ` : `Here's a service you might find helpful: `;
+  return `${intro}**${ad.title}** \u2014 ${ad.body}`;
+}
+function buildDirectText(ad) {
+  return `**${ad.title}**
+${ad.body}`;
+}
+function truncateGracefully(text, maxLength) {
+  if (text.length <= maxLength) {
+    return text;
+  }
+  const truncated = text.substring(0, maxLength);
+  const lastPeriod = truncated.lastIndexOf(".");
+  const lastQuestion = truncated.lastIndexOf("?");
+  const lastExclamation = truncated.lastIndexOf("!");
+  const sentenceEnd = Math.max(lastPeriod, lastQuestion, lastExclamation);
+  if (sentenceEnd > maxLength * 0.7) {
+    return text.substring(0, sentenceEnd + 1);
+  }
+  const lastSpace = truncated.lastIndexOf(" ");
+  if (lastSpace > 0) {
+    return truncated.substring(0, lastSpace) + "...";
+  }
+  return truncated.substring(0, maxLength - 3) + "...";
+}
+function formatInlineMention(ad) {
+  if (ad.unit_type !== "sponsored_suggestion") {
+    throw new Error("formatInlineMention() currently only supports sponsored_suggestion ad units");
+  }
+  const suggestion = ad.suggestion;
+  return {
+    text: `${suggestion.title} (${ad.disclosure.label})`,
+    cta: suggestion.cta,
+    actionUrl: suggestion.action_url,
+    tracking: {
+      eventId: ad.unit_id,
+      trackingToken: ad.tracking.token,
+      decisionId: ad.unit_id
+    },
+    disclosure: {
+      label: ad.disclosure.label,
+      sponsorName: ad.disclosure.sponsor_name
+    }
+  };
+}
+function validateAdFits(ad, constraints) {
+  if (ad.unit_type !== "sponsored_suggestion") {
+    return { fits: true, violations: [] };
+  }
+  const suggestion = ad.suggestion;
+  const violations = [];
+  if (constraints.maxTitleChars && suggestion.title.length > constraints.maxTitleChars) {
+    violations.push(
+      `Title too long: ${suggestion.title.length} chars (max ${constraints.maxTitleChars})`
+    );
+  }
+  if (constraints.maxBodyChars && suggestion.body.length > constraints.maxBodyChars) {
+    violations.push(
+      `Body too long: ${suggestion.body.length} chars (max ${constraints.maxBodyChars})`
+    );
+  }
+  if (constraints.maxCtaChars && suggestion.cta.length > constraints.maxCtaChars) {
+    violations.push(
+      `CTA too long: ${suggestion.cta.length} chars (max ${constraints.maxCtaChars})`
+    );
+  }
+  return {
+    fits: violations.length === 0,
+    violations
+  };
+}
+
 // src/taxonomy-utils.ts
 function buildTaxonomy(vertical, category, subcategory, intent) {
   const parts = [vertical, category, subcategory];
@@ -949,6 +1074,8 @@ function suggestTaxonomies(query) {
   createOpportunity,
   detectIntent,
   escapeHTML,
+  formatInlineMention,
+  formatNatural,
   generateTimestamp,
   generateUUID,
   getBaseTaxonomy,
@@ -957,6 +1084,7 @@ function suggestTaxonomies(query) {
   matchesTaxonomy,
   parseTaxonomy,
   sanitizeURL,
-  suggestTaxonomies
+  suggestTaxonomies,
+  validateAdFits
 });
 //# sourceMappingURL=index.js.map