@adcp/sdk 6.0.0 → 6.1.0

package/dist/lib/schemas-data/v2.5/core/brand-manifest.json

@@ -0,0 +1,409 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/core/brand-manifest.json",
+  "title": "Brand Manifest",
+  "description": "Standardized brand information manifest for creative generation and media buying. Enables low-friction creative workflows by providing brand context that can be easily cached and shared across requests.",
+  "type": "object",
+  "properties": {
+    "url": {
+      "type": "string",
+      "format": "uri",
+      "description": "Primary brand URL for context and asset discovery. Creative agents can infer brand information from this URL."
+    },
+    "name": {
+      "type": "string",
+      "description": "Brand or business name"
+    },
+    "logos": {
+      "type": "array",
+      "description": "Brand logo assets with semantic tags for different use cases",
+      "items": {
+        "type": "object",
+        "properties": {
+          "url": {
+            "type": "string",
+            "format": "uri",
+            "description": "URL to the logo asset"
+          },
+          "tags": {
+            "type": "array",
+            "description": "Semantic tags describing the logo variant (e.g., 'dark', 'light', 'square', 'horizontal', 'icon')",
+            "items": {
+              "type": "string"
+            }
+          },
+          "width": {
+            "type": "integer",
+            "description": "Logo width in pixels"
+          },
+          "height": {
+            "type": "integer",
+            "description": "Logo height in pixels"
+          }
+        },
+        "required": [
+          "url"
+        ]
+      }
+    },
+    "colors": {
+      "type": "object",
+      "description": "Brand color palette",
+      "properties": {
+        "primary": {
+          "type": "string",
+          "pattern": "^#[0-9A-Fa-f]{6}$",
+          "description": "Primary brand color (hex format)"
+        },
+        "secondary": {
+          "type": "string",
+          "pattern": "^#[0-9A-Fa-f]{6}$",
+          "description": "Secondary brand color (hex format)"
+        },
+        "accent": {
+          "type": "string",
+          "pattern": "^#[0-9A-Fa-f]{6}$",
+          "description": "Accent color (hex format)"
+        },
+        "background": {
+          "type": "string",
+          "pattern": "^#[0-9A-Fa-f]{6}$",
+          "description": "Background color (hex format)"
+        },
+        "text": {
+          "type": "string",
+          "pattern": "^#[0-9A-Fa-f]{6}$",
+          "description": "Text color (hex format)"
+        }
+      }
+    },
+    "fonts": {
+      "type": "object",
+      "description": "Brand typography guidelines",
+      "properties": {
+        "primary": {
+          "type": "string",
+          "description": "Primary font family name"
+        },
+        "secondary": {
+          "type": "string",
+          "description": "Secondary font family name"
+        },
+        "font_urls": {
+          "type": "array",
+          "description": "URLs to web font files if using custom fonts",
+          "items": {
+            "type": "string",
+            "format": "uri"
+          }
+        }
+      }
+    },
+    "tone": {
+      "type": "string",
+      "description": "Brand voice and messaging tone (e.g., 'professional', 'casual', 'humorous', 'trustworthy', 'innovative')"
+    },
+    "tagline": {
+      "type": "string",
+      "description": "Brand tagline or slogan"
+    },
+    "assets": {
+      "type": "array",
+      "description": "Brand asset library with explicit assets and tags. Assets are referenced inline with URLs pointing to CDN-hosted files.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "asset_id": {
+            "type": "string",
+            "description": "Unique identifier for this asset"
+          },
+          "asset_type": {
+            "$ref": "/schemas/enums/asset-content-type.json",
+            "description": "Type of asset. Note: Brand manifests typically contain basic media assets (image, video, audio, text). Code assets (html, javascript, css) and ad markup (vast, daast) are usually not part of brand asset libraries."
+          },
+          "url": {
+            "type": "string",
+            "format": "uri",
+            "description": "URL to CDN-hosted asset file"
+          },
+          "tags": {
+            "type": "array",
+            "description": "Tags for asset discovery (e.g., 'holiday', 'lifestyle', 'product_shot')",
+            "items": {
+              "type": "string"
+            }
+          },
+          "name": {
+            "type": "string",
+            "description": "Human-readable asset name"
+          },
+          "description": {
+            "type": "string",
+            "description": "Asset description or usage notes"
+          },
+          "width": {
+            "type": "integer",
+            "description": "Image/video width in pixels"
+          },
+          "height": {
+            "type": "integer",
+            "description": "Image/video height in pixels"
+          },
+          "duration_seconds": {
+            "type": "number",
+            "description": "Video/audio duration in seconds"
+          },
+          "file_size_bytes": {
+            "type": "integer",
+            "description": "File size in bytes"
+          },
+          "format": {
+            "type": "string",
+            "description": "File format (e.g., 'jpg', 'mp4', 'mp3')"
+          },
+          "metadata": {
+            "type": "object",
+            "description": "Additional asset-specific metadata",
+            "additionalProperties": true
+          }
+        },
+        "required": [
+          "asset_id",
+          "asset_type",
+          "url"
+        ],
+        "additionalProperties": true
+      }
+    },
+    "product_catalog": {
+      "type": "object",
+      "description": "Product catalog information for e-commerce advertisers. Enables SKU-level creative generation and product selection.",
+      "properties": {
+        "feed_url": {
+          "type": "string",
+          "format": "uri",
+          "description": "URL to product catalog feed"
+        },
+        "feed_format": {
+          "type": "string",
+          "enum": [
+            "google_merchant_center",
+            "facebook_catalog",
+            "custom"
+          ],
+          "default": "google_merchant_center",
+          "description": "Format of the product feed"
+        },
+        "categories": {
+          "type": "array",
+          "description": "Product categories available in the catalog (for filtering)",
+          "items": {
+            "type": "string"
+          }
+        },
+        "last_updated": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the product catalog was last updated"
+        },
+        "update_frequency": {
+          "type": "string",
+          "enum": [
+            "realtime",
+            "hourly",
+            "daily",
+            "weekly"
+          ],
+          "description": "How frequently the product catalog is updated"
+        }
+      },
+      "required": [
+        "feed_url"
+      ],
+      "additionalProperties": true
+    },
+    "disclaimers": {
+      "type": "array",
+      "description": "Legal disclaimers or required text that must appear in creatives",
+      "items": {
+        "type": "object",
+        "properties": {
+          "text": {
+            "type": "string",
+            "description": "Disclaimer text"
+          },
+          "context": {
+            "type": "string",
+            "description": "When this disclaimer applies (e.g., 'financial_products', 'health_claims', 'all')"
+          },
+          "required": {
+            "type": "boolean",
+            "description": "Whether this disclaimer must appear",
+            "default": true
+          }
+        },
+        "required": [
+          "text"
+        ]
+      }
+    },
+    "industry": {
+      "type": "string",
+      "description": "Industry or vertical (e.g., 'retail', 'automotive', 'finance', 'healthcare')"
+    },
+    "target_audience": {
+      "type": "string",
+      "description": "Primary target audience description"
+    },
+    "contact": {
+      "type": "object",
+      "description": "Brand contact information",
+      "properties": {
+        "email": {
+          "type": "string",
+          "format": "email",
+          "description": "Contact email"
+        },
+        "phone": {
+          "type": "string",
+          "description": "Contact phone number"
+        }
+      }
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Additional brand metadata",
+      "properties": {
+        "created_date": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When this brand manifest was created"
+        },
+        "updated_date": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When this brand manifest was last updated"
+        },
+        "version": {
+          "type": "string",
+          "description": "Brand card version number"
+        }
+      }
+    }
+  },
+  "required": [
+    "name"
+  ],
+  "additionalProperties": true,
+  "examples": [
+    {
+      "description": "Example with both URL and name",
+      "data": {
+        "url": "https://bobsfunburgers.com",
+        "name": "Bob's Fun Burgers"
+      }
+    },
+    {
+      "description": "Example: white-label brand without dedicated URL",
+      "data": {
+        "name": "Great Value",
+        "colors": {
+          "primary": "#0071CE",
+          "secondary": "#FFC220"
+        },
+        "tone": "affordable and trustworthy"
+      }
+    },
+    {
+      "description": "Full brand manifest with all fields",
+      "data": {
+        "url": "https://acmecorp.com",
+        "name": "ACME Corporation",
+        "logos": [
+          {
+            "url": "https://cdn.acmecorp.com/logo-square-dark.png",
+            "tags": [
+              "dark",
+              "square"
+            ],
+            "width": 512,
+            "height": 512
+          },
+          {
+            "url": "https://cdn.acmecorp.com/logo-horizontal-light.png",
+            "tags": [
+              "light",
+              "horizontal"
+            ],
+            "width": 1200,
+            "height": 400
+          }
+        ],
+        "colors": {
+          "primary": "#FF6B35",
+          "secondary": "#004E89",
+          "accent": "#F7931E",
+          "background": "#FFFFFF",
+          "text": "#1A1A1A"
+        },
+        "fonts": {
+          "primary": "Helvetica Neue",
+          "secondary": "Georgia"
+        },
+        "tone": "professional and trustworthy",
+        "tagline": "Innovation You Can Trust",
+        "assets": [
+          {
+            "asset_id": "hero_winter_2024",
+            "asset_type": "image",
+            "url": "https://cdn.acmecorp.com/hero-winter-2024.jpg",
+            "tags": [
+              "hero",
+              "winter",
+              "holiday",
+              "lifestyle"
+            ],
+            "name": "Winter Campaign Hero",
+            "width": 1920,
+            "height": 1080,
+            "format": "jpg"
+          },
+          {
+            "asset_id": "product_video_30s",
+            "asset_type": "video",
+            "url": "https://cdn.acmecorp.com/product-demo-30s.mp4",
+            "tags": [
+              "product",
+              "demo",
+              "30s"
+            ],
+            "name": "Product Demo 30 Second",
+            "width": 1920,
+            "height": 1080,
+            "duration_seconds": 30,
+            "format": "mp4"
+          }
+        ],
+        "product_catalog": {
+          "feed_url": "https://acmecorp.com/products.xml",
+          "feed_format": "google_merchant_center",
+          "categories": [
+            "electronics/computers",
+            "electronics/accessories"
+          ],
+          "last_updated": "2024-03-15T10:00:00Z",
+          "update_frequency": "hourly"
+        },
+        "disclaimers": [
+          {
+            "text": "Results may vary. Consult a professional before use.",
+            "context": "health_claims",
+            "required": true
+          }
+        ],
+        "industry": "technology",
+        "target_audience": "business decision-makers aged 35-55"
+      }
+    }
+  ]
+}

package/dist/lib/schemas-data/v2.5/core/context.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/core/context.json",
+  "title": "Context Object",
+  "description": "Opaque correlation data that is echoed unchanged in responses. Used for internal tracking, UI session IDs, trace IDs, and other caller-specific identifiers that don't affect protocol behavior. Context data is never parsed by AdCP agents - it's simply preserved and returned.",
+  "type": "object",
+  "additionalProperties": true
+}

package/dist/lib/schemas-data/v2.5/core/creative-asset.json

@@ -0,0 +1,125 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/core/creative-asset.json",
+  "title": "Creative Asset",
+  "description": "Creative asset for upload to library - supports static assets, generative formats, and third-party snippets",
+  "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. Can be: (1) concrete format_id referencing a format with fixed dimensions, (2) template format_id referencing a template format, or (3) parameterized format_id with dimensions/duration parameters for template formats."
+    },
+    "assets": {
+      "type": "object",
+      "description": "Assets required by the format, 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"
+            }
+          ]
+        }
+      },
+      "additionalProperties": true
+    },
+    "inputs": {
+      "type": "array",
+      "description": "Preview contexts for generative formats - defines what scenarios to generate previews for",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Human-readable name for this preview variant"
+          },
+          "macros": {
+            "type": "object",
+            "description": "Macro values to apply for this preview",
+            "additionalProperties": {
+              "type": "string"
+            }
+          },
+          "context_description": {
+            "type": "string",
+            "description": "Natural language description of the context for AI-generated content"
+          }
+        },
+        "required": [
+          "name"
+        ],
+        "additionalProperties": true
+      }
+    },
+    "tags": {
+      "type": "array",
+      "description": "User-defined tags for organization and searchability",
+      "items": {
+        "type": "string"
+      }
+    },
+    "approved": {
+      "type": "boolean",
+      "description": "For generative creatives: set to true to approve and finalize, false to request regeneration with updated assets/message. Omit for non-generative creatives."
+    },
+    "weight": {
+      "type": "number",
+      "description": "Optional delivery weight for creative rotation when uploading via create_media_buy or update_media_buy (0-100). If omitted, platform determines rotation. Only used during upload to media buy - not stored in creative library.",
+      "minimum": 0,
+      "maximum": 100
+    },
+    "placement_ids": {
+      "type": "array",
+      "description": "Optional array of placement IDs where this creative should run when uploading via create_media_buy or update_media_buy. References placement_id values from the product's placements array. If omitted, creative runs on all placements. Only used during upload to media buy - not stored in creative library.",
+      "items": {
+        "type": "string"
+      },
+      "minItems": 1
+    }
+  },
+  "required": [
+    "creative_id",
+    "name",
+    "format_id",
+    "assets"
+  ],
+  "additionalProperties": true
+}

package/dist/lib/schemas-data/v2.5/core/creative-assignment.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/core/creative-assignment.json",
+  "title": "Creative Assignment",
+  "description": "Assignment of a creative asset to a package with optional placement targeting. Used in create_media_buy and update_media_buy requests. Note: sync_creatives does not support placement_ids - use create/update_media_buy for placement-level targeting.",
+  "type": "object",
+  "properties": {
+    "creative_id": {
+      "type": "string",
+      "description": "Unique identifier for the creative"
+    },
+    "weight": {
+      "type": "number",
+      "description": "Delivery weight for this creative",
+      "minimum": 0,
+      "maximum": 100
+    },
+    "placement_ids": {
+      "type": "array",
+      "description": "Optional array of placement IDs where this creative should run. When omitted, the creative runs on all placements in the package. References placement_id values from the product's placements array.",
+      "items": {
+        "type": "string"
+      },
+      "minItems": 1
+    }
+  },
+  "required": [
+    "creative_id"
+  ],
+  "additionalProperties": true
+}

package/dist/lib/schemas-data/v2.5/core/creative-filters.json

@@ -0,0 +1,111 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/core/creative-filters.json",
+  "title": "Creative Filters",
+  "description": "Filter criteria for querying creative assets from the centralized library",
+  "type": "object",
+  "properties": {
+    "format": {
+      "type": "string",
+      "description": "Filter by creative format type (e.g., video, audio, display)"
+    },
+    "formats": {
+      "type": "array",
+      "description": "Filter by multiple creative format types",
+      "items": {
+        "type": "string"
+      }
+    },
+    "status": {
+      "$ref": "/schemas/enums/creative-status.json",
+      "description": "Filter by creative approval status"
+    },
+    "statuses": {
+      "type": "array",
+      "description": "Filter by multiple creative statuses",
+      "items": {
+        "$ref": "/schemas/enums/creative-status.json"
+      }
+    },
+    "tags": {
+      "type": "array",
+      "description": "Filter by creative tags (all tags must match)",
+      "items": {
+        "type": "string"
+      }
+    },
+    "tags_any": {
+      "type": "array",
+      "description": "Filter by creative tags (any tag must match)",
+      "items": {
+        "type": "string"
+      }
+    },
+    "name_contains": {
+      "type": "string",
+      "description": "Filter by creative names containing this text (case-insensitive)"
+    },
+    "creative_ids": {
+      "type": "array",
+      "description": "Filter by specific creative IDs",
+      "items": {
+        "type": "string"
+      },
+      "maxItems": 100
+    },
+    "created_after": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Filter creatives created after this date (ISO 8601)"
+    },
+    "created_before": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Filter creatives created before this date (ISO 8601)"
+    },
+    "updated_after": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Filter creatives last updated after this date (ISO 8601)"
+    },
+    "updated_before": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Filter creatives last updated before this date (ISO 8601)"
+    },
+    "assigned_to_package": {
+      "type": "string",
+      "description": "Filter creatives assigned to this specific package"
+    },
+    "assigned_to_packages": {
+      "type": "array",
+      "description": "Filter creatives assigned to any of these packages",
+      "items": {
+        "type": "string"
+      }
+    },
+    "media_buy_ids": {
+      "type": "array",
+      "description": "Filter creatives assigned to any of these media buys",
+      "items": {
+        "type": "string"
+      }
+    },
+    "buyer_refs": {
+      "type": "array",
+      "description": "Filter creatives assigned to media buys with any of these buyer references",
+      "items": {
+        "type": "string"
+      }
+    },
+    "unassigned": {
+      "type": "boolean",
+      "description": "Filter for unassigned creatives when true, assigned creatives when false"
+    },
+    "has_performance_data": {
+      "type": "boolean",
+      "description": "Filter creatives that have performance data when true"
+    }
+  },
+  "additionalProperties": true
+}