@adcp/sdk 6.0.0 → 6.1.0

package/dist/lib/schemas-data/v2.5/media-buy/list-creatives-request.json

@@ -0,0 +1,137 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/media-buy/list-creatives-request.json",
+  "title": "List Creatives Request",
+  "description": "Request parameters for querying creative assets from the centralized library with filtering, sorting, and pagination",
+  "type": "object",
+  "properties": {
+    "filters": {
+      "$ref": "/schemas/core/creative-filters.json"
+    },
+    "sort": {
+      "type": "object",
+      "description": "Sorting parameters",
+      "properties": {
+        "field": {
+          "$ref": "/schemas/enums/creative-sort-field.json",
+          "default": "created_date",
+          "description": "Field to sort by"
+        },
+        "direction": {
+          "$ref": "/schemas/enums/sort-direction.json",
+          "default": "desc",
+          "description": "Sort direction"
+        }
+      },
+      "additionalProperties": true
+    },
+    "pagination": {
+      "type": "object",
+      "description": "Pagination parameters",
+      "properties": {
+        "limit": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 100,
+          "default": 50,
+          "description": "Maximum number of creatives to return"
+        },
+        "offset": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 0,
+          "description": "Number of creatives to skip"
+        }
+      },
+      "additionalProperties": true
+    },
+    "include_assignments": {
+      "type": "boolean",
+      "default": true,
+      "description": "Include package assignment information in response"
+    },
+    "include_performance": {
+      "type": "boolean",
+      "default": false,
+      "description": "Include aggregated performance metrics in response"
+    },
+    "include_sub_assets": {
+      "type": "boolean",
+      "default": false,
+      "description": "Include sub-assets (for carousel/native formats) in response"
+    },
+    "fields": {
+      "type": "array",
+      "description": "Specific fields to include in response (omit for all fields)",
+      "items": {
+        "type": "string",
+        "enum": [
+          "creative_id",
+          "name",
+          "format",
+          "status",
+          "created_date",
+          "updated_date",
+          "tags",
+          "assignments",
+          "performance",
+          "sub_assets"
+        ]
+      }
+    },
+    "context": {
+      "$ref": "/schemas/core/context.json"
+    },
+    "ext": {
+      "$ref": "/schemas/core/ext.json"
+    }
+  },
+  "additionalProperties": true,
+  "examples": [
+    {
+      "description": "List all approved video creatives",
+      "data": {
+        "filters": {
+          "format": "video",
+          "status": "approved"
+        }
+      }
+    },
+    {
+      "description": "Search for Nike creatives with performance data",
+      "data": {
+        "filters": {
+          "name_contains": "nike",
+          "has_performance_data": true
+        },
+        "include_performance": true
+      }
+    },
+    {
+      "description": "Get unassigned creatives for assignment",
+      "data": {
+        "filters": {
+          "unassigned": true
+        },
+        "sort": {
+          "field": "created_date",
+          "direction": "desc"
+        },
+        "pagination": {
+          "limit": 20
+        }
+      }
+    },
+    {
+      "description": "Lightweight list with minimal fields",
+      "data": {
+        "fields": [
+          "creative_id",
+          "name",
+          "status"
+        ],
+        "include_assignments": false
+      }
+    }
+  ]
+}

package/dist/lib/schemas-data/v2.5/media-buy/list-creatives-response.json

@@ -0,0 +1,437 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/media-buy/list-creatives-response.json",
+  "title": "List Creatives Response",
+  "description": "Response from creative library query with filtered results, metadata, and optional enriched data",
+  "type": "object",
+  "properties": {
+    "query_summary": {
+      "type": "object",
+      "description": "Summary of the query that was executed",
+      "properties": {
+        "total_matching": {
+          "type": "integer",
+          "description": "Total number of creatives matching filters (across all pages)",
+          "minimum": 0
+        },
+        "returned": {
+          "type": "integer",
+          "description": "Number of creatives returned in this response",
+          "minimum": 0
+        },
+        "filters_applied": {
+          "type": "array",
+          "description": "List of filters that were applied to the query",
+          "items": {
+            "type": "string"
+          }
+        },
+        "sort_applied": {
+          "type": "object",
+          "description": "Sort order that was applied",
+          "properties": {
+            "field": {
+              "type": "string"
+            },
+            "direction": {
+              "$ref": "/schemas/enums/sort-direction.json"
+            }
+          }
+        }
+      },
+      "required": [
+        "total_matching",
+        "returned"
+      ],
+      "additionalProperties": true
+    },
+    "pagination": {
+      "type": "object",
+      "description": "Pagination information for navigating results",
+      "properties": {
+        "limit": {
+          "type": "integer",
+          "description": "Maximum number of results requested",
+          "minimum": 1
+        },
+        "offset": {
+          "type": "integer",
+          "description": "Number of results skipped",
+          "minimum": 0
+        },
+        "has_more": {
+          "type": "boolean",
+          "description": "Whether more results are available"
+        },
+        "total_pages": {
+          "type": "integer",
+          "description": "Total number of pages available",
+          "minimum": 0
+        },
+        "current_page": {
+          "type": "integer",
+          "description": "Current page number (1-based)",
+          "minimum": 1
+        }
+      },
+      "required": [
+        "limit",
+        "offset",
+        "has_more"
+      ],
+      "additionalProperties": true
+    },
+    "creatives": {
+      "type": "array",
+      "description": "Array of creative assets matching the query",
+      "items": {
+        "type": "object",
+        "properties": {
+          "creative_id": {
+            "type": "string",
+            "description": "Unique identifier for the creative"
+          },
+          "name": {
+            "type": "string",
+            "description": "Human-readable creative name"
+          },
+          "format_id": {
+            "$ref": "/schemas/core/format-id.json",
+            "description": "Format identifier specifying which format this creative conforms to"
+          },
+          "status": {
+            "$ref": "/schemas/enums/creative-status.json",
+            "description": "Current approval status of the creative"
+          },
+          "created_date": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When the creative was uploaded to the library"
+          },
+          "updated_date": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When the creative was last modified"
+          },
+          "assets": {
+            "type": "object",
+            "description": "Assets for this creative, keyed by asset_role",
+            "patternProperties": {
+              "^[a-zA-Z0-9_-]+$": {
+                "oneOf": [
+                  {
+                    "$ref": "/schemas/core/assets/image-asset.json"
+                  },
+                  {
+                    "$ref": "/schemas/core/assets/video-asset.json"
+                  },
+                  {
+                    "$ref": "/schemas/core/assets/audio-asset.json"
+                  },
+                  {
+                    "$ref": "/schemas/core/assets/text-asset.json"
+                  },
+                  {
+                    "$ref": "/schemas/core/assets/html-asset.json"
+                  },
+                  {
+                    "$ref": "/schemas/core/assets/css-asset.json"
+                  },
+                  {
+                    "$ref": "/schemas/core/assets/javascript-asset.json"
+                  },
+                  {
+                    "$ref": "/schemas/core/assets/vast-asset.json"
+                  },
+                  {
+                    "$ref": "/schemas/core/assets/daast-asset.json"
+                  },
+                  {
+                    "$ref": "/schemas/core/promoted-offerings.json"
+                  },
+                  {
+                    "$ref": "/schemas/core/assets/url-asset.json"
+                  }
+                ]
+              }
+            }
+          },
+          "tags": {
+            "type": "array",
+            "description": "User-defined tags for organization and searchability",
+            "items": {
+              "type": "string"
+            }
+          },
+          "assignments": {
+            "type": "object",
+            "description": "Current package assignments (included when include_assignments=true)",
+            "properties": {
+              "assignment_count": {
+                "type": "integer",
+                "description": "Total number of active package assignments",
+                "minimum": 0
+              },
+              "assigned_packages": {
+                "type": "array",
+                "description": "List of packages this creative is assigned to",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "package_id": {
+                      "type": "string",
+                      "description": "Package identifier"
+                    },
+                    "package_name": {
+                      "type": "string",
+                      "description": "Human-readable package name"
+                    },
+                    "assigned_date": {
+                      "type": "string",
+                      "format": "date-time",
+                      "description": "When this assignment was created"
+                    },
+                    "status": {
+                      "type": "string",
+                      "enum": [
+                        "active",
+                        "paused",
+                        "ended"
+                      ],
+                      "description": "Status of this specific assignment"
+                    }
+                  },
+                  "required": [
+                    "package_id",
+                    "assigned_date",
+                    "status"
+                  ],
+                  "additionalProperties": true
+                }
+              }
+            },
+            "required": [
+              "assignment_count"
+            ],
+            "additionalProperties": true
+          },
+          "performance": {
+            "type": "object",
+            "description": "Aggregated performance metrics (included when include_performance=true)",
+            "properties": {
+              "impressions": {
+                "type": "integer",
+                "description": "Total impressions across all assignments",
+                "minimum": 0
+              },
+              "clicks": {
+                "type": "integer",
+                "description": "Total clicks across all assignments",
+                "minimum": 0
+              },
+              "ctr": {
+                "type": "number",
+                "description": "Click-through rate (clicks/impressions)",
+                "minimum": 0,
+                "maximum": 1
+              },
+              "conversion_rate": {
+                "type": "number",
+                "description": "Conversion rate across all assignments",
+                "minimum": 0,
+                "maximum": 1
+              },
+              "performance_score": {
+                "type": "number",
+                "description": "Aggregated performance score (0-100)",
+                "minimum": 0,
+                "maximum": 100
+              },
+              "last_updated": {
+                "type": "string",
+                "format": "date-time",
+                "description": "When performance data was last updated"
+              }
+            },
+            "required": [
+              "last_updated"
+            ],
+            "additionalProperties": true
+          },
+          "sub_assets": {
+            "type": "array",
+            "description": "Sub-assets for multi-asset formats (included when include_sub_assets=true)",
+            "items": {
+              "$ref": "/schemas/core/sub-asset.json"
+            }
+          }
+        },
+        "required": [
+          "creative_id",
+          "name",
+          "format_id",
+          "status",
+          "created_date",
+          "updated_date"
+        ],
+        "additionalProperties": true
+      }
+    },
+    "format_summary": {
+      "type": "object",
+      "description": "Breakdown of creatives by format type",
+      "patternProperties": {
+        "^[a-zA-Z0-9_-]+$": {
+          "type": "integer",
+          "description": "Number of creatives with this format",
+          "minimum": 0
+        }
+      },
+      "additionalProperties": true
+    },
+    "status_summary": {
+      "type": "object",
+      "description": "Breakdown of creatives by status",
+      "properties": {
+        "approved": {
+          "type": "integer",
+          "description": "Number of approved creatives",
+          "minimum": 0
+        },
+        "pending_review": {
+          "type": "integer",
+          "description": "Number of creatives pending review",
+          "minimum": 0
+        },
+        "rejected": {
+          "type": "integer",
+          "description": "Number of rejected creatives",
+          "minimum": 0
+        },
+        "archived": {
+          "type": "integer",
+          "description": "Number of archived creatives",
+          "minimum": 0
+        }
+      },
+      "additionalProperties": true
+    },
+    "context": {
+      "$ref": "/schemas/core/context.json"
+    },
+    "ext": {
+      "$ref": "/schemas/core/ext.json"
+    }
+  },
+  "required": [
+    "query_summary",
+    "pagination",
+    "creatives"
+  ],
+  "additionalProperties": true,
+  "examples": [
+    {
+      "description": "Successful library query with results",
+      "data": {
+        "query_summary": {
+          "total_matching": 3,
+          "returned": 3,
+          "filters_applied": [
+            "format=video",
+            "status=approved"
+          ],
+          "sort_applied": {
+            "field": "created_date",
+            "direction": "desc"
+          }
+        },
+        "pagination": {
+          "limit": 50,
+          "offset": 0,
+          "has_more": false,
+          "total_pages": 1,
+          "current_page": 1
+        },
+        "creatives": [
+          {
+            "creative_id": "hero_video_30s",
+            "name": "Brand Hero Video 30s",
+            "format_id": {
+              "agent_url": "https://creative.adcontextprotocol.org",
+              "id": "video_30s_vast"
+            },
+            "status": "approved",
+            "created_date": "2024-01-15T10:30:00Z",
+            "updated_date": "2024-01-15T14:20:00Z",
+            "assets": {
+              "vast": {
+                "url": "https://vast.example.com/video/123",
+                "vast_version": "4.1"
+              }
+            },
+            "tags": [
+              "q1_2024",
+              "video",
+              "brand_awareness"
+            ]
+          }
+        ],
+        "format_summary": {
+          "video_30s_vast": 2,
+          "display_300x250": 1
+        },
+        "status_summary": {
+          "approved": 3,
+          "pending_review": 0,
+          "rejected": 0,
+          "archived": 0
+        }
+      }
+    },
+    {
+      "description": "Query with assignments and performance data",
+      "data": {
+        "query_summary": {
+          "total_matching": 1,
+          "returned": 1
+        },
+        "pagination": {
+          "limit": 50,
+          "offset": 0,
+          "has_more": false
+        },
+        "creatives": [
+          {
+            "creative_id": "hero_video_30s",
+            "name": "Brand Hero Video 30s",
+            "format_id": {
+              "agent_url": "https://creative.adcontextprotocol.org",
+              "id": "video_30s_vast"
+            },
+            "status": "approved",
+            "created_date": "2024-01-15T10:30:00Z",
+            "updated_date": "2024-01-15T14:20:00Z",
+            "assignments": {
+              "assignment_count": 2,
+              "assigned_packages": [
+                {
+                  "package_id": "pkg_ctv_001",
+                  "package_name": "CTV Prime Time",
+                  "assigned_date": "2024-01-16T09:00:00Z",
+                  "status": "active"
+                }
+              ]
+            },
+            "performance": {
+              "impressions": 150000,
+              "clicks": 1200,
+              "ctr": 0.008,
+              "performance_score": 85.2,
+              "last_updated": "2024-01-20T12:00:00Z"
+            }
+          }
+        ]
+      }
+    }
+  ]
+}

package/dist/lib/schemas-data/v2.5/media-buy/package-request.json

@@ -0,0 +1,80 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/media-buy/package-request.json",
+  "title": "Package Request",
+  "description": "Package configuration for media buy creation",
+  "type": "object",
+  "properties": {
+    "buyer_ref": {
+      "type": "string",
+      "description": "Buyer's reference identifier for this package"
+    },
+    "product_id": {
+      "type": "string",
+      "description": "Product ID for this package"
+    },
+    "format_ids": {
+      "type": "array",
+      "description": "Array of format IDs that will be used for this package - must be supported by the product. If omitted, defaults to all formats supported by the product.",
+      "items": {
+        "$ref": "/schemas/core/format-id.json"
+      },
+      "minItems": 1
+    },
+    "budget": {
+      "type": "number",
+      "description": "Budget allocation for this package in the media buy's currency",
+      "minimum": 0
+    },
+    "pacing": {
+      "$ref": "/schemas/enums/pacing.json"
+    },
+    "pricing_option_id": {
+      "type": "string",
+      "description": "ID of the selected pricing option from the product's pricing_options array"
+    },
+    "bid_price": {
+      "type": "number",
+      "description": "Bid price for auction-based CPM pricing (required if using cpm-auction-option)",
+      "minimum": 0
+    },
+    "impressions": {
+      "type": "number",
+      "description": "Impression goal for this package",
+      "minimum": 0
+    },
+    "paused": {
+      "type": "boolean",
+      "description": "Whether this package should be created in a paused state. Paused packages do not deliver impressions. Defaults to false.",
+      "default": false
+    },
+    "targeting_overlay": {
+      "$ref": "/schemas/core/targeting.json"
+    },
+    "creative_ids": {
+      "type": "array",
+      "description": "Creative IDs to assign to this package at creation time (references existing library creatives)",
+      "items": {
+        "type": "string"
+      }
+    },
+    "creatives": {
+      "type": "array",
+      "description": "Full creative objects to upload and assign to this package at creation time (alternative to creative_ids - creatives will be added to library). Supports both static and generative creatives.",
+      "items": {
+        "$ref": "/schemas/core/creative-asset.json"
+      },
+      "maxItems": 100
+    },
+    "ext": {
+      "$ref": "/schemas/core/ext.json"
+    }
+  },
+  "required": [
+    "buyer_ref",
+    "product_id",
+    "budget",
+    "pricing_option_id"
+  ],
+  "additionalProperties": true
+}