@the_ro_show/agent-ads-sdk 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,300 @@
+/**
+ * TypeScript types mirroring the AttentionMarket OpenAPI specification.
+ * These types are the source of truth for the SDK API surface.
+ */
+interface AgentSignupRequest {
+    owner_email: string;
+    agent_name: string;
+    sdk?: 'typescript' | 'python' | 'other';
+    environment?: 'test' | 'live';
+    declared_placements?: PlacementType[];
+    declared_capabilities?: string[];
+}
+interface AgentSignupResponse {
+    agent_id: string;
+    api_key: string;
+    test_api_key: string;
+    created_at: string;
+}
+interface DecideRequest {
+    request_id: string;
+    agent_id: string;
+    placement: Placement;
+    opportunity: Opportunity;
+}
+interface DecideResponse {
+    request_id: string;
+    decision_id: string;
+    status: 'filled' | 'no_fill';
+    ttl_ms: number;
+    units: AdUnit[];
+}
+type PlacementType = 'sponsored_suggestion' | 'sponsored_block' | 'sponsored_tool';
+interface Placement {
+    type: PlacementType;
+    surface: string;
+}
+interface Opportunity {
+    intent: Intent;
+    context: Context;
+    constraints: Constraints;
+    privacy: Privacy;
+}
+interface Intent {
+    taxonomy: string;
+    query?: string;
+}
+interface Context {
+    country: string;
+    language: string;
+    platform: 'web' | 'ios' | 'android' | 'desktop' | 'voice' | 'other';
+    region?: string;
+    city?: string;
+}
+interface Constraints {
+    max_units: number;
+    allowed_unit_types: PlacementType[];
+    blocked_categories?: string[];
+    max_title_chars?: number;
+    max_body_chars?: number;
+}
+interface Privacy {
+    data_policy: 'coarse_only' | 'none' | 'extended';
+}
+/**
+ * AdUnit is a discriminated union enforcing the OpenAPI oneOf constraint.
+ * Either suggestion OR tool is required based on unit_type.
+ */
+type AdUnit = {
+    unit_id: string;
+    unit_type: 'sponsored_suggestion';
+    disclosure: Disclosure;
+    tracking: Tracking;
+    suggestion: SponsoredSuggestion;
+} | {
+    unit_id: string;
+    unit_type: 'sponsored_tool';
+    disclosure: Disclosure;
+    tracking: Tracking;
+    tool: SponsoredTool;
+};
+interface Disclosure {
+    label: string;
+    explanation: string;
+    sponsor_name: string;
+}
+interface Tracking {
+    token: string;
+    impression_url?: string;
+    click_url?: string;
+}
+interface SponsoredSuggestion {
+    title: string;
+    body: string;
+    cta: string;
+    action_url: string;
+}
+interface SponsoredTool {
+    tool_name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+    call: ToolCall;
+}
+interface ToolCall {
+    method: 'GET' | 'POST';
+    url: string;
+    headers?: Record<string, string>;
+}
+type EventType = 'impression' | 'click' | 'action' | 'conversion' | 'dismiss' | 'hide_advertiser' | 'report';
+interface EventIngestRequest {
+    event_id: string;
+    occurred_at: string;
+    agent_id: string;
+    request_id: string;
+    decision_id: string;
+    unit_id: string;
+    event_type: EventType;
+    tracking_token: string;
+    metadata?: Record<string, unknown>;
+}
+interface EventIngestResponse {
+    accepted: boolean;
+}
+interface PolicyResponse {
+    version: string;
+    disclosure: {
+        required: boolean;
+        label: string;
+        require_sponsor_name: boolean;
+    };
+    defaults: {
+        max_units_per_response: number;
+        blocked_categories: string[];
+    };
+    unit_rules: Record<string, unknown>;
+}
+interface APIError {
+    error: string;
+    message: string;
+    request_id: string;
+    details?: Record<string, unknown>;
+}
+interface SDKConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+}
+
+/**
+ * Utility functions for the AttentionMarket SDK.
+ * Includes UUID generation, opportunity helpers, and event builders.
+ */
+
+/**
+ * Generate a UUID v4 for use as event_id, request_id, etc.
+ */
+declare function generateUUID(): string;
+/**
+ * Generate an ISO 8601 timestamp for the current moment.
+ */
+declare function generateTimestamp(): string;
+interface CreateOpportunityParams {
+    taxonomy: string;
+    country: string;
+    language: string;
+    platform: 'web' | 'ios' | 'android' | 'desktop' | 'voice' | 'other';
+    query?: string;
+    region?: string;
+    city?: string;
+    constraints?: {
+        max_units?: number;
+        allowed_unit_types?: ('sponsored_suggestion' | 'sponsored_block' | 'sponsored_tool')[];
+        blocked_categories?: string[];
+        max_title_chars?: number;
+        max_body_chars?: number;
+    };
+    privacy?: {
+        data_policy?: 'coarse_only' | 'none' | 'extended';
+    };
+}
+/**
+ * Create a valid Opportunity object with safe defaults.
+ *
+ * Defaults:
+ * - constraints.max_units = 1
+ * - constraints.allowed_unit_types = ['sponsored_suggestion']
+ * - privacy.data_policy = 'coarse_only'
+ */
+declare function createOpportunity(params: CreateOpportunityParams): Opportunity;
+interface CreateImpressionEventParams {
+    agent_id: string;
+    request_id: string;
+    decision_id: string;
+    unit_id: string;
+    tracking_token: string;
+    occurred_at?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Helper to create an impression event payload.
+ *
+ * @param params - Event parameters (snake_case to match API)
+ * @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;
+    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;
+
+/**
+ * Main SDK client for AttentionMarket Agent Ads API.
+ * Provides public methods: decide(), decideRaw(), track(), getPolicy(), signupAgent()
+ */
+
+declare class AttentionMarketClient {
+    private http;
+    constructor(config: SDKConfig);
+    /**
+     * Request a sponsored unit decision for an agent opportunity.
+     * Returns the full DecideResponse including status, ttl_ms, and all units.
+     */
+    decideRaw(request: DecideRequest, options?: {
+        idempotencyKey?: string;
+    }): Promise<DecideResponse>;
+    /**
+     * Convenience wrapper around decideRaw().
+     * Returns null if status is no_fill, otherwise returns the first ad unit.
+     */
+    decide(request: DecideRequest, options?: {
+        idempotencyKey?: string;
+    }): Promise<AdUnit | null>;
+    /**
+     * Report an event (impression, click, action, conversion, feedback).
+     */
+    track(event: EventIngestRequest): Promise<EventIngestResponse>;
+    /**
+     * Convenience method to track an impression event.
+     * Creates an impression event using createImpressionEvent() and calls track().
+     */
+    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>;
+    /**
+     * Fetch default policy constraints and formatting requirements.
+     */
+    getPolicy(): Promise<PolicyResponse>;
+    /**
+     * Create or register an agent (optional helper).
+     * Note: This endpoint is unauthenticated in v1.
+     */
+    static signupAgent(request: AgentSignupRequest, options?: {
+        baseUrl?: string;
+    }): Promise<AgentSignupResponse>;
+}
+
+/**
+ * Error classes for AttentionMarket SDK.
+ * Surfaces HTTP status, API error codes, messages, and request_id.
+ */
+
+declare class AttentionMarketError extends Error {
+    constructor(message: string);
+}
+declare class APIRequestError extends AttentionMarketError {
+    readonly statusCode: number;
+    readonly errorCode: string;
+    readonly requestId?: string;
+    readonly details?: Record<string, unknown>;
+    constructor(statusCode: number, apiError: APIError);
+}
+declare class NetworkError extends AttentionMarketError {
+    readonly cause?: Error;
+    constructor(message: string, cause?: Error);
+}
+declare class TimeoutError extends AttentionMarketError {
+    constructor(message?: string);
+}
+
+export { type APIError, APIRequestError, type AdUnit, type AgentSignupRequest, type AgentSignupResponse, AttentionMarketClient, AttentionMarketError, type Constraints, type Context, type CreateClickEventParams, type CreateImpressionEventParams, type CreateOpportunityParams, type DecideRequest, type DecideResponse, type Disclosure, type EventIngestRequest, type EventIngestResponse, type EventType, type Intent, NetworkError, type Opportunity, type Placement, type PlacementType, type PolicyResponse, type Privacy, type SDKConfig, type SponsoredSuggestion, type SponsoredTool, TimeoutError, type ToolCall, type Tracking, createClickEvent, createImpressionEvent, createOpportunity, generateTimestamp, generateUUID };

package/dist/index.d.ts

@@ -0,0 +1,300 @@
+/**
+ * TypeScript types mirroring the AttentionMarket OpenAPI specification.
+ * These types are the source of truth for the SDK API surface.
+ */
+interface AgentSignupRequest {
+    owner_email: string;
+    agent_name: string;
+    sdk?: 'typescript' | 'python' | 'other';
+    environment?: 'test' | 'live';
+    declared_placements?: PlacementType[];
+    declared_capabilities?: string[];
+}
+interface AgentSignupResponse {
+    agent_id: string;
+    api_key: string;
+    test_api_key: string;
+    created_at: string;
+}
+interface DecideRequest {
+    request_id: string;
+    agent_id: string;
+    placement: Placement;
+    opportunity: Opportunity;
+}
+interface DecideResponse {
+    request_id: string;
+    decision_id: string;
+    status: 'filled' | 'no_fill';
+    ttl_ms: number;
+    units: AdUnit[];
+}
+type PlacementType = 'sponsored_suggestion' | 'sponsored_block' | 'sponsored_tool';
+interface Placement {
+    type: PlacementType;
+    surface: string;
+}
+interface Opportunity {
+    intent: Intent;
+    context: Context;
+    constraints: Constraints;
+    privacy: Privacy;
+}
+interface Intent {
+    taxonomy: string;
+    query?: string;
+}
+interface Context {
+    country: string;
+    language: string;
+    platform: 'web' | 'ios' | 'android' | 'desktop' | 'voice' | 'other';
+    region?: string;
+    city?: string;
+}
+interface Constraints {
+    max_units: number;
+    allowed_unit_types: PlacementType[];
+    blocked_categories?: string[];
+    max_title_chars?: number;
+    max_body_chars?: number;
+}
+interface Privacy {
+    data_policy: 'coarse_only' | 'none' | 'extended';
+}
+/**
+ * AdUnit is a discriminated union enforcing the OpenAPI oneOf constraint.
+ * Either suggestion OR tool is required based on unit_type.
+ */
+type AdUnit = {
+    unit_id: string;
+    unit_type: 'sponsored_suggestion';
+    disclosure: Disclosure;
+    tracking: Tracking;
+    suggestion: SponsoredSuggestion;
+} | {
+    unit_id: string;
+    unit_type: 'sponsored_tool';
+    disclosure: Disclosure;
+    tracking: Tracking;
+    tool: SponsoredTool;
+};
+interface Disclosure {
+    label: string;
+    explanation: string;
+    sponsor_name: string;
+}
+interface Tracking {
+    token: string;
+    impression_url?: string;
+    click_url?: string;
+}
+interface SponsoredSuggestion {
+    title: string;
+    body: string;
+    cta: string;
+    action_url: string;
+}
+interface SponsoredTool {
+    tool_name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+    call: ToolCall;
+}
+interface ToolCall {
+    method: 'GET' | 'POST';
+    url: string;
+    headers?: Record<string, string>;
+}
+type EventType = 'impression' | 'click' | 'action' | 'conversion' | 'dismiss' | 'hide_advertiser' | 'report';
+interface EventIngestRequest {
+    event_id: string;
+    occurred_at: string;
+    agent_id: string;
+    request_id: string;
+    decision_id: string;
+    unit_id: string;
+    event_type: EventType;
+    tracking_token: string;
+    metadata?: Record<string, unknown>;
+}
+interface EventIngestResponse {
+    accepted: boolean;
+}
+interface PolicyResponse {
+    version: string;
+    disclosure: {
+        required: boolean;
+        label: string;
+        require_sponsor_name: boolean;
+    };
+    defaults: {
+        max_units_per_response: number;
+        blocked_categories: string[];
+    };
+    unit_rules: Record<string, unknown>;
+}
+interface APIError {
+    error: string;
+    message: string;
+    request_id: string;
+    details?: Record<string, unknown>;
+}
+interface SDKConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+}
+
+/**
+ * Utility functions for the AttentionMarket SDK.
+ * Includes UUID generation, opportunity helpers, and event builders.
+ */
+
+/**
+ * Generate a UUID v4 for use as event_id, request_id, etc.
+ */
+declare function generateUUID(): string;
+/**
+ * Generate an ISO 8601 timestamp for the current moment.
+ */
+declare function generateTimestamp(): string;
+interface CreateOpportunityParams {
+    taxonomy: string;
+    country: string;
+    language: string;
+    platform: 'web' | 'ios' | 'android' | 'desktop' | 'voice' | 'other';
+    query?: string;
+    region?: string;
+    city?: string;
+    constraints?: {
+        max_units?: number;
+        allowed_unit_types?: ('sponsored_suggestion' | 'sponsored_block' | 'sponsored_tool')[];
+        blocked_categories?: string[];
+        max_title_chars?: number;
+        max_body_chars?: number;
+    };
+    privacy?: {
+        data_policy?: 'coarse_only' | 'none' | 'extended';
+    };
+}
+/**
+ * Create a valid Opportunity object with safe defaults.
+ *
+ * Defaults:
+ * - constraints.max_units = 1
+ * - constraints.allowed_unit_types = ['sponsored_suggestion']
+ * - privacy.data_policy = 'coarse_only'
+ */
+declare function createOpportunity(params: CreateOpportunityParams): Opportunity;
+interface CreateImpressionEventParams {
+    agent_id: string;
+    request_id: string;
+    decision_id: string;
+    unit_id: string;
+    tracking_token: string;
+    occurred_at?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Helper to create an impression event payload.
+ *
+ * @param params - Event parameters (snake_case to match API)
+ * @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;
+    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;
+
+/**
+ * Main SDK client for AttentionMarket Agent Ads API.
+ * Provides public methods: decide(), decideRaw(), track(), getPolicy(), signupAgent()
+ */
+
+declare class AttentionMarketClient {
+    private http;
+    constructor(config: SDKConfig);
+    /**
+     * Request a sponsored unit decision for an agent opportunity.
+     * Returns the full DecideResponse including status, ttl_ms, and all units.
+     */
+    decideRaw(request: DecideRequest, options?: {
+        idempotencyKey?: string;
+    }): Promise<DecideResponse>;
+    /**
+     * Convenience wrapper around decideRaw().
+     * Returns null if status is no_fill, otherwise returns the first ad unit.
+     */
+    decide(request: DecideRequest, options?: {
+        idempotencyKey?: string;
+    }): Promise<AdUnit | null>;
+    /**
+     * Report an event (impression, click, action, conversion, feedback).
+     */
+    track(event: EventIngestRequest): Promise<EventIngestResponse>;
+    /**
+     * Convenience method to track an impression event.
+     * Creates an impression event using createImpressionEvent() and calls track().
+     */
+    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>;
+    /**
+     * Fetch default policy constraints and formatting requirements.
+     */
+    getPolicy(): Promise<PolicyResponse>;
+    /**
+     * Create or register an agent (optional helper).
+     * Note: This endpoint is unauthenticated in v1.
+     */
+    static signupAgent(request: AgentSignupRequest, options?: {
+        baseUrl?: string;
+    }): Promise<AgentSignupResponse>;
+}
+
+/**
+ * Error classes for AttentionMarket SDK.
+ * Surfaces HTTP status, API error codes, messages, and request_id.
+ */
+
+declare class AttentionMarketError extends Error {
+    constructor(message: string);
+}
+declare class APIRequestError extends AttentionMarketError {
+    readonly statusCode: number;
+    readonly errorCode: string;
+    readonly requestId?: string;
+    readonly details?: Record<string, unknown>;
+    constructor(statusCode: number, apiError: APIError);
+}
+declare class NetworkError extends AttentionMarketError {
+    readonly cause?: Error;
+    constructor(message: string, cause?: Error);
+}
+declare class TimeoutError extends AttentionMarketError {
+    constructor(message?: string);
+}
+
+export { type APIError, APIRequestError, type AdUnit, type AgentSignupRequest, type AgentSignupResponse, AttentionMarketClient, AttentionMarketError, type Constraints, type Context, type CreateClickEventParams, type CreateImpressionEventParams, type CreateOpportunityParams, type DecideRequest, type DecideResponse, type Disclosure, type EventIngestRequest, type EventIngestResponse, type EventType, type Intent, NetworkError, type Opportunity, type Placement, type PlacementType, type PolicyResponse, type Privacy, type SDKConfig, type SponsoredSuggestion, type SponsoredTool, TimeoutError, type ToolCall, type Tracking, createClickEvent, createImpressionEvent, createOpportunity, generateTimestamp, generateUUID };