agentberlin 0.166.0__tar.gz → 0.167.0__tar.gz

{agentberlin-0.166.0 → agentberlin-0.167.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentberlin
-Version: 0.166.0
+Version: 0.167.0
 Summary: Python SDK for Agent Berlin - AI-powered SEO and AEO automation
 Project-URL: Homepage, https://agentberlin.ai
 Project-URL: Documentation, https://docs.agentberlin.ai/sdk/python
@@ -77,6 +77,7 @@ client = AgentBerlin()
 - **google_ads**: `search_terms()`, `keywords()`, `campaigns()`, `ad_groups()`, `landing_pages()`, `coverage()` - Google Ads performance reports (read-only, nightly-synced warehouse; cost values in micros)
 - **openai_ads**: `account()`, `campaigns()`, `ad_groups()`, `ads()`, `list_campaigns()`, `record_hint_set()`, `list_hint_sets()` - OpenAI (ChatGPT) Ads performance insights read live from the connected Advertiser API key (read-only; six metrics only; no keywords/search terms; insights money in account currency, not micros), plus recording/recall of generated ad-group context_hints for history
 - **microsoft_ads**: `search_terms()`, `keywords()`, `campaigns()`, `ad_groups()`, `landing_pages()`, `share_of_voice()`, `coverage()` - Microsoft Advertising performance reports (read-only, nightly-synced warehouse; money values are decimal, not micros; share-of-voice keeps ~6 months of history)
+- **linkedin_ads**: `account()`, `campaign_groups()`, `campaigns()`, `creatives()`, `list_campaigns()` - LinkedIn Ads (paid social) performance insights read live from the connected ad account via the /adAnalytics finder (read-only; no keywords/search terms; `cost_in_local_currency` in account currency, not micros)
 
 ## API Reference
 
@@ -3597,3 +3598,92 @@ cov = client.microsoft_ads.coverage(
 )
 print(f"Search terms cover {cov.coverage.coverage_ratio:.0%} of spend")
 ```
+
+### linkedin_ads
+
+LinkedIn Ads (paid social) performance for the project's connected ad account: account, campaign-group, campaign, and creative insights, plus a campaign listing. Read-only — the SDK never mutates campaigns or any other account state. Data is read LIVE via LinkedIn's /adAnalytics finder on every call (no warehouse, so no `data_as_of` staleness). This is paid SOCIAL, not paid search: there are NO keywords and NO search terms. Money (`cost_in_local_currency`) is a DECIMAL in the account currency in `meta.currency_code` — not micros, so no division is needed; all IDs are URNs kept as strings.
+
+
+#### client.linkedin_ads.account()
+
+Get account-level performance totals (one row per time bucket).
+
+Signature:
+```python
+result = client.linkedin_ads.account(
+    start_date="2026-06-01",  # Optional: YYYY-MM-DD (default 30 days ago)
+    end_date="2026-06-30",    # Optional: YYYY-MM-DD (default today)
+    granularity="daily",      # Optional: daily (default) | monthly | yearly | all
+)
+```
+
+Returns LinkedInAdsInsightsResponse with:
+- rows - List of LinkedInAdsInsightRow objects
+- row_count - Number of rows returned
+- meta - LinkedInAdsMeta (source, account_id, currency_code)
+
+Each LinkedInAdsInsightRow has:
+- pivot_value - URN of the pivoted entity (empty at account level)
+- start / end - Time-bucket bounds (YYYY-MM-DD)
+- impressions / clicks
+- cost_in_local_currency / cost_in_usd - decimal, not micros
+- conversions / one_click_leads / likes / comments / shares / follows
+
+#### client.linkedin_ads.campaign_groups()
+
+Per-campaign-group performance (one row per group per time bucket). Same
+args and shape as `account()`; each row's `pivot_value` is the campaign
+group URN.
+
+#### client.linkedin_ads.campaigns()
+
+Per-campaign performance (one row per campaign per time bucket). Same
+args and shape as `account()`; each row's `pivot_value` is the campaign
+URN. Pair with `list_campaigns()` for names, budgets, and type.
+
+Example:
+```python
+report = client.linkedin_ads.campaigns(
+    start_date="2026-06-01",
+    end_date="2026-06-30",
+)
+for row in report.rows:
+    print(f"{row.pivot_value}: {row.clicks} clicks, "
+          f"{row.cost_in_local_currency:.2f} {report.meta.currency_code}")
+```
+
+#### client.linkedin_ads.creatives()
+
+Per-creative performance (one row per creative per time bucket). Same
+args and shape as `account()`; each row's `pivot_value` is the creative
+URN.
+
+#### client.linkedin_ads.list_campaigns()
+
+List the connected account's campaigns with metadata for interpreting
+the insight rows.
+
+Signature:
+```python
+result = client.linkedin_ads.list_campaigns()
+```
+
+Returns LinkedInAdsCampaignsResponse with:
+- rows - List of LinkedInAdsCampaignRow objects
+- row_count - Number of campaigns returned
+- meta - LinkedInAdsMeta (source, account_id, currency_code)
+
+Each LinkedInAdsCampaignRow has:
+- id / name / status
+- type - SPONSORED_UPDATES | TEXT_AD | SPONSORED_INMAILS | DYNAMIC
+- cost_type - CPC | CPM | CPV
+- daily_budget / total_budget / unit_cost - decimal-string money objects
+  in the account currency (amount + currency_code)
+- campaign_group - the parent campaign group URN
+- audience_expansion_enabled / run_schedule / targeting_criteria
+
+Example:
+```python
+for c in client.linkedin_ads.list_campaigns().rows:
+    print(f"{c.name} [{c.status}] type={c.type}")
+```

{agentberlin-0.166.0 → agentberlin-0.167.0}/README.md

@@ -41,6 +41,7 @@ client = AgentBerlin()
 - **google_ads**: `search_terms()`, `keywords()`, `campaigns()`, `ad_groups()`, `landing_pages()`, `coverage()` - Google Ads performance reports (read-only, nightly-synced warehouse; cost values in micros)
 - **openai_ads**: `account()`, `campaigns()`, `ad_groups()`, `ads()`, `list_campaigns()`, `record_hint_set()`, `list_hint_sets()` - OpenAI (ChatGPT) Ads performance insights read live from the connected Advertiser API key (read-only; six metrics only; no keywords/search terms; insights money in account currency, not micros), plus recording/recall of generated ad-group context_hints for history
 - **microsoft_ads**: `search_terms()`, `keywords()`, `campaigns()`, `ad_groups()`, `landing_pages()`, `share_of_voice()`, `coverage()` - Microsoft Advertising performance reports (read-only, nightly-synced warehouse; money values are decimal, not micros; share-of-voice keeps ~6 months of history)
+- **linkedin_ads**: `account()`, `campaign_groups()`, `campaigns()`, `creatives()`, `list_campaigns()` - LinkedIn Ads (paid social) performance insights read live from the connected ad account via the /adAnalytics finder (read-only; no keywords/search terms; `cost_in_local_currency` in account currency, not micros)
 
 ## API Reference
 
@@ -3561,3 +3562,92 @@ cov = client.microsoft_ads.coverage(
 )
 print(f"Search terms cover {cov.coverage.coverage_ratio:.0%} of spend")
 ```
+
+### linkedin_ads
+
+LinkedIn Ads (paid social) performance for the project's connected ad account: account, campaign-group, campaign, and creative insights, plus a campaign listing. Read-only — the SDK never mutates campaigns or any other account state. Data is read LIVE via LinkedIn's /adAnalytics finder on every call (no warehouse, so no `data_as_of` staleness). This is paid SOCIAL, not paid search: there are NO keywords and NO search terms. Money (`cost_in_local_currency`) is a DECIMAL in the account currency in `meta.currency_code` — not micros, so no division is needed; all IDs are URNs kept as strings.
+
+
+#### client.linkedin_ads.account()
+
+Get account-level performance totals (one row per time bucket).
+
+Signature:
+```python
+result = client.linkedin_ads.account(
+    start_date="2026-06-01",  # Optional: YYYY-MM-DD (default 30 days ago)
+    end_date="2026-06-30",    # Optional: YYYY-MM-DD (default today)
+    granularity="daily",      # Optional: daily (default) | monthly | yearly | all
+)
+```
+
+Returns LinkedInAdsInsightsResponse with:
+- rows - List of LinkedInAdsInsightRow objects
+- row_count - Number of rows returned
+- meta - LinkedInAdsMeta (source, account_id, currency_code)
+
+Each LinkedInAdsInsightRow has:
+- pivot_value - URN of the pivoted entity (empty at account level)
+- start / end - Time-bucket bounds (YYYY-MM-DD)
+- impressions / clicks
+- cost_in_local_currency / cost_in_usd - decimal, not micros
+- conversions / one_click_leads / likes / comments / shares / follows
+
+#### client.linkedin_ads.campaign_groups()
+
+Per-campaign-group performance (one row per group per time bucket). Same
+args and shape as `account()`; each row's `pivot_value` is the campaign
+group URN.
+
+#### client.linkedin_ads.campaigns()
+
+Per-campaign performance (one row per campaign per time bucket). Same
+args and shape as `account()`; each row's `pivot_value` is the campaign
+URN. Pair with `list_campaigns()` for names, budgets, and type.
+
+Example:
+```python
+report = client.linkedin_ads.campaigns(
+    start_date="2026-06-01",
+    end_date="2026-06-30",
+)
+for row in report.rows:
+    print(f"{row.pivot_value}: {row.clicks} clicks, "
+          f"{row.cost_in_local_currency:.2f} {report.meta.currency_code}")
+```
+
+#### client.linkedin_ads.creatives()
+
+Per-creative performance (one row per creative per time bucket). Same
+args and shape as `account()`; each row's `pivot_value` is the creative
+URN.
+
+#### client.linkedin_ads.list_campaigns()
+
+List the connected account's campaigns with metadata for interpreting
+the insight rows.
+
+Signature:
+```python
+result = client.linkedin_ads.list_campaigns()
+```
+
+Returns LinkedInAdsCampaignsResponse with:
+- rows - List of LinkedInAdsCampaignRow objects
+- row_count - Number of campaigns returned
+- meta - LinkedInAdsMeta (source, account_id, currency_code)
+
+Each LinkedInAdsCampaignRow has:
+- id / name / status
+- type - SPONSORED_UPDATES | TEXT_AD | SPONSORED_INMAILS | DYNAMIC
+- cost_type - CPC | CPM | CPV
+- daily_budget / total_budget / unit_cost - decimal-string money objects
+  in the account currency (amount + currency_code)
+- campaign_group - the parent campaign group URN
+- audience_expansion_enabled / run_schedule / targeting_criteria
+
+Example:
+```python
+for c in client.linkedin_ads.list_campaigns().rows:
+    print(f"{c.name} [{c.status}] type={c.type}")
+```

{agentberlin-0.166.0 → agentberlin-0.167.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentberlin"
-version = "0.166.0"
+version = "0.167.0"
 description = "Python SDK for Agent Berlin - AI-powered SEO and AEO automation"
 readme = "README.md"
 license = {text = "MIT"}

{agentberlin-0.166.0 → agentberlin-0.167.0}/src/agentberlin/__init__.py

@@ -39,7 +39,7 @@ from .exceptions import (
 )
 from .utils import get_project_domain
 
-__version__ = "0.166.0"
+__version__ = "0.167.0"
 
 __all__ = [
     "AgentBerlin",

{agentberlin-0.166.0 → agentberlin-0.167.0}/src/agentberlin/_http.py

@@ -18,7 +18,7 @@ from .exceptions import (
     AgentBerlinServerError,
 )
 
-__version__ = "0.166.0"
+__version__ = "0.167.0"
 logger = logging.getLogger("agentberlin")
 
 

{agentberlin-0.166.0 → agentberlin-0.167.0}/src/agentberlin/client.py

@@ -42,6 +42,7 @@ from .resources.google_trends import GoogleTrendsResource
 from .resources.gsc import GSCResource
 from .resources.keywords import KeywordsResource
 from .resources.linkedin import LinkedInResource
+from .resources.linkedin_ads import LinkedInAdsResource
 from .resources.market import MarketResource
 from .resources.microsoft_ads import MicrosoftAdsResource
 from .resources.pages import PagesResource
@@ -139,6 +140,12 @@ class AgentBerlin:
             coverage metric, served from Berlin's nightly-synced warehouse.
             Money values are decimal in `meta.currency_code` (not micros);
             share-of-voice keeps only ~6 months of history.
+        linkedin_ads: LinkedIn Ads (paid social) performance resource
+            (read-only) — account/campaign-group/campaign/creative insights
+            plus a campaign listing, read live from the connected ad account
+            via the /adAnalytics finder. No keywords or search terms;
+            `cost_in_local_currency` is decimal in `meta.currency_code`, not
+            micros.
     """
 
     def __init__(
@@ -220,6 +227,7 @@ class AgentBerlin:
         self.google_ads = GoogleAdsResource(self._http)
         self.openai_ads = OpenAIAdsResource(self._http)
         self.microsoft_ads = MicrosoftAdsResource(self._http)
+        self.linkedin_ads = LinkedInAdsResource(self._http)
 
     def __repr__(self) -> str:
         return f"AgentBerlin(base_url='{self._config.base_url}')"

{agentberlin-0.166.0 → agentberlin-0.167.0}/src/agentberlin/models/__init__.py

@@ -144,6 +144,15 @@ from .openai_ads import (
     OpenAIAdsInsightsResponse,
     OpenAIAdsMeta,
 )
+from .linkedin_ads import (
+    LinkedInAdsCampaignRow,
+    LinkedInAdsCampaignsResponse,
+    LinkedInAdsInsightRow,
+    LinkedInAdsInsightsResponse,
+    LinkedInAdsMeta,
+    LinkedInAdsMoney,
+    LinkedInAdsRunSchedule,
+)
 from .google_maps import (
     GoogleMapsPlace,
     GoogleMapsReview,
@@ -409,6 +418,13 @@ __all__ = [
     "OpenAIAdsInsightRow",
     "OpenAIAdsInsightsResponse",
     "OpenAIAdsMeta",
+    "LinkedInAdsCampaignRow",
+    "LinkedInAdsCampaignsResponse",
+    "LinkedInAdsInsightRow",
+    "LinkedInAdsInsightsResponse",
+    "LinkedInAdsMeta",
+    "LinkedInAdsMoney",
+    "LinkedInAdsRunSchedule",
     # Google Maps
     "GoogleMapsPlace",
     "GoogleMapsReview",

agentberlin-0.167.0/src/agentberlin/models/linkedin_ads.py

@@ -0,0 +1,128 @@
+"""Pydantic models for LinkedIn Ads (Marketing API) responses.
+
+LinkedIn Ads reads are served LIVE from the project's connected ad account via
+the /adAnalytics finder (there is no warehouse — the finder is synchronous, and
+LinkedIn is outside the SEM warehouse plan). Insights money
+(``cost_in_local_currency``) is a decimal in the account currency
+(``meta.currency_code``), NOT micros. Campaign budgets are decimal-string money
+objects, also not micros.
+
+LinkedIn Ads is paid social: there are no keywords and no search terms. Pivots
+are account / campaign_group / campaign / creative, and ids are URNs kept as
+opaque strings.
+"""
+
+from typing import Any, List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class LinkedInAdsMeta(BaseModel):
+    """Metadata attached to every LinkedIn Ads response.
+
+    Attributes:
+        source: Where the data came from — always "linkedin_ads".
+        account_id: The connected sponsored ad-account id (numeric).
+        currency_code: Account currency. Insights ``cost_in_local_currency`` is
+            in this currency (not micros).
+    """
+
+    source: str
+    account_id: Optional[str] = None
+    currency_code: Optional[str] = None
+
+
+class LinkedInAdsMoney(BaseModel):
+    """A LinkedIn money amount — a decimal string in ``currency_code`` (not
+    micros)."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    amount: Optional[str] = None
+    currency_code: Optional[str] = Field(default=None, alias="currencyCode")
+
+
+class LinkedInAdsRunSchedule(BaseModel):
+    """An entity's flight window (epoch-millis). ``end`` of 0/None means
+    run-until-budget-spent."""
+
+    start: Optional[int] = None
+    end: Optional[int] = None
+
+
+class LinkedInAdsInsightRow(BaseModel):
+    """One /adAnalytics row at the requested pivot.
+
+    ``pivot_value`` is the URN of the pivoted entity (campaign / creative / ...),
+    empty at account pivot. ``start``/``end`` bound the time bucket (YYYY-MM-DD).
+    Money is in the account currency, not micros.
+    """
+
+    pivot_value: Optional[str] = None
+    start: Optional[str] = None
+    end: Optional[str] = None
+    impressions: int = 0
+    clicks: int = 0
+    cost_in_local_currency: float = 0.0
+    cost_in_usd: float = 0.0
+    conversions: float = 0.0
+    one_click_leads: float = 0.0
+    likes: int = 0
+    comments: int = 0
+    shares: int = 0
+    follows: int = 0
+
+
+class LinkedInAdsInsightsResponse(BaseModel):
+    """Response from the insights endpoint.
+
+    Attributes:
+        rows: One row per entity at the requested pivot (per time bucket).
+        row_count: Number of rows returned.
+        meta: Account metadata (see LinkedInAdsMeta). Data is live — there is no
+            ``data_as_of`` staleness stamp.
+    """
+
+    rows: List[LinkedInAdsInsightRow] = Field(default_factory=list)
+    row_count: int = 0
+    meta: LinkedInAdsMeta
+
+
+class LinkedInAdsCampaignRow(BaseModel):
+    """One campaign in the connected ad account.
+
+    ``type`` is the LinkedIn campaign type (SPONSORED_UPDATES, TEXT_AD, ...);
+    ``cost_type`` is CPC / CPM / CPV. Budgets are decimal-string money objects
+    in the account currency. ``targeting_criteria`` is the raw Rest.li targeting
+    object (kept opaque).
+    """
+
+    id: str
+    account: Optional[str] = None
+    campaign_group: Optional[str] = None
+    name: str
+    status: str
+    type: Optional[str] = None
+    cost_type: Optional[str] = None
+    format: Optional[str] = None
+    objective_type: Optional[str] = None
+    daily_budget: Optional[LinkedInAdsMoney] = None
+    total_budget: Optional[LinkedInAdsMoney] = None
+    unit_cost: Optional[LinkedInAdsMoney] = None
+    audience_expansion_enabled: bool = False
+    run_schedule: LinkedInAdsRunSchedule = Field(default_factory=LinkedInAdsRunSchedule)
+    targeting_criteria: Optional[Any] = None
+
+
+class LinkedInAdsCampaignsResponse(BaseModel):
+    """Response from the campaigns list endpoint.
+
+    Attributes:
+        rows: The account's campaigns.
+        row_count: Number of campaigns returned.
+        meta: Account metadata (see LinkedInAdsMeta).
+    """
+
+    rows: List[LinkedInAdsCampaignRow] = Field(default_factory=list)
+    row_count: int = 0
+    meta: LinkedInAdsMeta

{agentberlin-0.166.0 → agentberlin-0.167.0}/src/agentberlin/readme.yaml

@@ -51,6 +51,7 @@ introduction: |
   - **google_ads**: `search_terms()`, `keywords()`, `campaigns()`, `ad_groups()`, `landing_pages()`, `coverage()` - Google Ads performance reports (read-only, nightly-synced warehouse; cost values in micros)
   - **openai_ads**: `account()`, `campaigns()`, `ad_groups()`, `ads()`, `list_campaigns()`, `record_hint_set()`, `list_hint_sets()` - OpenAI (ChatGPT) Ads performance insights read live from the connected Advertiser API key (read-only; six metrics only; no keywords/search terms; insights money in account currency, not micros), plus recording/recall of generated ad-group context_hints for history
   - **microsoft_ads**: `search_terms()`, `keywords()`, `campaigns()`, `ad_groups()`, `landing_pages()`, `share_of_voice()`, `coverage()` - Microsoft Advertising performance reports (read-only, nightly-synced warehouse; money values are decimal, not micros; share-of-voice keeps ~6 months of history)
+  - **linkedin_ads**: `account()`, `campaign_groups()`, `campaigns()`, `creatives()`, `list_campaigns()` - LinkedIn Ads (paid social) performance insights read live from the connected ad account via the /adAnalytics finder (read-only; no keywords/search terms; `cost_in_local_currency` in account currency, not micros)
 
 resources:
   ga4:
@@ -3492,3 +3493,90 @@ resources:
         )
         print(f"Search terms cover {cov.coverage.coverage_ratio:.0%} of spend")
         ```
+
+  linkedin_ads:
+    description: >
+      LinkedIn Ads (paid social) performance for the project's connected ad
+      account: account, campaign-group, campaign, and creative insights, plus a
+      campaign listing. Read-only — the SDK never mutates campaigns or any other
+      account state. Data is read LIVE via LinkedIn's /adAnalytics finder on
+      every call (no warehouse, so no `data_as_of` staleness). This is paid
+      SOCIAL, not paid search: there are NO keywords and NO search terms. Money
+      (`cost_in_local_currency`) is a DECIMAL in the account currency in
+      `meta.currency_code` — not micros, so no division is needed; all IDs are
+      URNs kept as strings.
+    methods:
+      account: |
+        Get account-level performance totals (one row per time bucket).
+
+        Signature:
+        ```python
+        result = client.linkedin_ads.account(
+            start_date="2026-06-01",  # Optional: YYYY-MM-DD (default 30 days ago)
+            end_date="2026-06-30",    # Optional: YYYY-MM-DD (default today)
+            granularity="daily",      # Optional: daily (default) | monthly | yearly | all
+        )
+        ```
+
+        Returns LinkedInAdsInsightsResponse with:
+        - rows - List of LinkedInAdsInsightRow objects
+        - row_count - Number of rows returned
+        - meta - LinkedInAdsMeta (source, account_id, currency_code)
+
+        Each LinkedInAdsInsightRow has:
+        - pivot_value - URN of the pivoted entity (empty at account level)
+        - start / end - Time-bucket bounds (YYYY-MM-DD)
+        - impressions / clicks
+        - cost_in_local_currency / cost_in_usd - decimal, not micros
+        - conversions / one_click_leads / likes / comments / shares / follows
+      campaign_groups: |
+        Per-campaign-group performance (one row per group per time bucket). Same
+        args and shape as `account()`; each row's `pivot_value` is the campaign
+        group URN.
+      campaigns: |
+        Per-campaign performance (one row per campaign per time bucket). Same
+        args and shape as `account()`; each row's `pivot_value` is the campaign
+        URN. Pair with `list_campaigns()` for names, budgets, and type.
+
+        Example:
+        ```python
+        report = client.linkedin_ads.campaigns(
+            start_date="2026-06-01",
+            end_date="2026-06-30",
+        )
+        for row in report.rows:
+            print(f"{row.pivot_value}: {row.clicks} clicks, "
+                  f"{row.cost_in_local_currency:.2f} {report.meta.currency_code}")
+        ```
+      creatives: |
+        Per-creative performance (one row per creative per time bucket). Same
+        args and shape as `account()`; each row's `pivot_value` is the creative
+        URN.
+      list_campaigns: |
+        List the connected account's campaigns with metadata for interpreting
+        the insight rows.
+
+        Signature:
+        ```python
+        result = client.linkedin_ads.list_campaigns()
+        ```
+
+        Returns LinkedInAdsCampaignsResponse with:
+        - rows - List of LinkedInAdsCampaignRow objects
+        - row_count - Number of campaigns returned
+        - meta - LinkedInAdsMeta (source, account_id, currency_code)
+
+        Each LinkedInAdsCampaignRow has:
+        - id / name / status
+        - type - SPONSORED_UPDATES | TEXT_AD | SPONSORED_INMAILS | DYNAMIC
+        - cost_type - CPC | CPM | CPV
+        - daily_budget / total_budget / unit_cost - decimal-string money objects
+          in the account currency (amount + currency_code)
+        - campaign_group - the parent campaign group URN
+        - audience_expansion_enabled / run_schedule / targeting_criteria
+
+        Example:
+        ```python
+        for c in client.linkedin_ads.list_campaigns().rows:
+            print(f"{c.name} [{c.status}] type={c.type}")
+        ```

{agentberlin-0.166.0 → agentberlin-0.167.0}/src/agentberlin/resources/__init__.py

@@ -20,6 +20,7 @@ from .linkedin import LinkedInResource
 from .market import MarketResource
 from .openai_ads import OpenAIAdsResource
 from .microsoft_ads import MicrosoftAdsResource
+from .linkedin_ads import LinkedInAdsResource
 from .pages import PagesResource
 from .pagespeed import PageSpeedResource
 from .posthog import PostHogResource
@@ -46,6 +47,7 @@ __all__ = [
     "MarketResource",
     "OpenAIAdsResource",
     "MicrosoftAdsResource",
+    "LinkedInAdsResource",
     "PagesResource",
     "PageSpeedResource",
     "PostHogResource",

agentberlin-0.167.0/src/agentberlin/resources/linkedin_ads.py

@@ -0,0 +1,183 @@
+"""LinkedIn Ads (Marketing API) resource for Agent Berlin SDK."""
+
+from typing import Any, Dict, Optional
+
+from .._http import HTTPClient
+from ..models.linkedin_ads import (
+    LinkedInAdsCampaignsResponse,
+    LinkedInAdsInsightsResponse,
+)
+from ..utils import get_project_domain
+
+
+class LinkedInAdsResource:
+    """Resource for LinkedIn Ads (paid social) performance data (read-only).
+
+    Serves campaign performance for the project's connected LinkedIn ad account.
+    Data is read LIVE from the customer's own connected account via the
+    /adAnalytics finder on each call — there is no warehouse, because the finder
+    is synchronous. This resource is read-only: the SDK never mutates campaigns
+    or any account state.
+
+    LinkedIn Ads is paid social — there are NO keywords and NO search terms.
+    Targeting is job title / function / seniority / industry / geo facets, and
+    reporting money (``cost_in_local_currency``) is a decimal in the account
+    currency reported in ``meta.currency_code`` (NOT micros).
+
+    The insights methods mirror the platform's pivots: ``account()``,
+    ``campaign_groups()``, ``campaigns()``, and ``creatives()``. Use
+    ``list_campaigns()`` to fetch campaign metadata (names, statuses, budgets,
+    type) for interpreting the insight rows.
+
+    Example:
+        # Last 30 days of per-campaign performance
+        report = client.linkedin_ads.campaigns()
+        for row in report.rows:
+            print(f"{row.pivot_value}: {row.clicks} clicks, "
+                  f"{row.cost_in_local_currency:.2f} {report.meta.currency_code}")
+    """
+
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    def _insights(
+        self,
+        level: str,
+        start_date: Optional[str],
+        end_date: Optional[str],
+        granularity: Optional[str],
+    ) -> LinkedInAdsInsightsResponse:
+        payload: Dict[str, Any] = {
+            "project_domain": get_project_domain(),
+            "level": level,
+        }
+        if start_date is not None:
+            payload["start_date"] = start_date
+        if end_date is not None:
+            payload["end_date"] = end_date
+        if granularity is not None:
+            payload["granularity"] = granularity
+        data = self._http.post("/linkedin-ads/insights", json=payload)
+        return LinkedInAdsInsightsResponse.model_validate(data)
+
+    def account(
+        self,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+        *,
+        granularity: Optional[str] = None,
+    ) -> LinkedInAdsInsightsResponse:
+        """Get account-level performance totals (one row per time bucket).
+
+        Read live from the connected LinkedIn ad account.
+
+        Args:
+            start_date: Start date in YYYY-MM-DD format. Defaults to 30 days ago.
+            end_date: End date in YYYY-MM-DD format. Defaults to today.
+            granularity: Time bucket — daily (default), monthly, yearly, or all.
+
+        Returns:
+            LinkedInAdsInsightsResponse with rows (impressions, clicks,
+            cost_in_local_currency, conversions, engagement), row_count, and
+            meta. Money is in ``meta.currency_code``, not micros.
+
+        Raises:
+            AgentBerlinNotFoundError: If no LinkedIn Ads integration is connected
+                for the domain.
+            AgentBerlinAPIError: If the request is invalid or access was revoked
+                (reconnect the integration).
+        """
+        return self._insights("account", start_date, end_date, granularity)
+
+    def campaign_groups(
+        self,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+        *,
+        granularity: Optional[str] = None,
+    ) -> LinkedInAdsInsightsResponse:
+        """Get per-campaign-group performance (one row per group per bucket).
+
+        Read live. Each row's ``pivot_value`` is the campaign group URN.
+
+        Args:
+            start_date: Start date in YYYY-MM-DD format. Defaults to 30 days ago.
+            end_date: End date in YYYY-MM-DD format. Defaults to today.
+            granularity: Time bucket — daily (default), monthly, yearly, or all.
+
+        Returns:
+            LinkedInAdsInsightsResponse with per-campaign-group rows, row_count,
+            and meta.
+        """
+        return self._insights("campaign_group", start_date, end_date, granularity)
+
+    def campaigns(
+        self,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+        *,
+        granularity: Optional[str] = None,
+    ) -> LinkedInAdsInsightsResponse:
+        """Get per-campaign performance (one row per campaign per time bucket).
+
+        Read live. Each row's ``pivot_value`` is the campaign URN; use
+        ``list_campaigns()`` for budgets and type.
+
+        Args:
+            start_date: Start date in YYYY-MM-DD format. Defaults to 30 days ago.
+            end_date: End date in YYYY-MM-DD format. Defaults to today.
+            granularity: Time bucket — daily (default), monthly, yearly, or all.
+
+        Returns:
+            LinkedInAdsInsightsResponse with per-campaign rows, row_count, and
+            meta. Money is in ``meta.currency_code``, not micros.
+        """
+        return self._insights("campaign", start_date, end_date, granularity)
+
+    def creatives(
+        self,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+        *,
+        granularity: Optional[str] = None,
+    ) -> LinkedInAdsInsightsResponse:
+        """Get per-creative performance (one row per creative per time bucket).
+
+        Read live. Each row's ``pivot_value`` is the creative URN.
+
+        Args:
+            start_date: Start date in YYYY-MM-DD format. Defaults to 30 days ago.
+            end_date: End date in YYYY-MM-DD format. Defaults to today.
+            granularity: Time bucket — daily (default), monthly, yearly, or all.
+
+        Returns:
+            LinkedInAdsInsightsResponse with per-creative rows, row_count, and
+            meta.
+        """
+        return self._insights("creative", start_date, end_date, granularity)
+
+    def list_campaigns(self) -> LinkedInAdsCampaignsResponse:
+        """List the connected account's campaigns with their metadata.
+
+        Read live. Returns names, statuses, type, cost type, and budgets — the
+        context for interpreting the insights rows (which carry only pivot URNs
+        and metrics).
+
+        Returns:
+            LinkedInAdsCampaignsResponse with campaign rows (id, name, status,
+            type, cost_type, budgets, ...), row_count, and meta. Budgets are
+            decimal-string money objects in ``meta.currency_code``.
+
+        Raises:
+            AgentBerlinNotFoundError: If no LinkedIn Ads integration is connected
+                for the domain.
+            AgentBerlinAPIError: If access was revoked (reconnect the
+                integration).
+
+        Example:
+            for c in client.linkedin_ads.list_campaigns().rows:
+                print(f"{c.name} [{c.status}] type={c.type}")
+        """
+        payload = {"project_domain": get_project_domain()}
+        data = self._http.post("/linkedin-ads/campaigns", json=payload)
+        return LinkedInAdsCampaignsResponse.model_validate(data)

agentberlin-0.167.0/tests/test_linkedin_ads.py

@@ -0,0 +1,200 @@
+"""Tests for LinkedIn Ads (paid social) resource and models."""
+
+import os
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from agentberlin.models import (
+    LinkedInAdsCampaignRow,
+    LinkedInAdsCampaignsResponse,
+    LinkedInAdsInsightRow,
+    LinkedInAdsInsightsResponse,
+    LinkedInAdsMeta,
+    LinkedInAdsMoney,
+)
+from agentberlin.resources.linkedin_ads import LinkedInAdsResource
+
+META = {
+    "source": "linkedin_ads",
+    "account_id": "512345678",
+    "currency_code": "USD",
+}
+
+
+class TestLinkedInAdsModels:
+    """Tests for LinkedIn Ads Pydantic models."""
+
+    def test_meta(self):
+        meta = LinkedInAdsMeta.model_validate(META)
+        assert meta.source == "linkedin_ads"
+        assert meta.account_id == "512345678"
+        assert meta.currency_code == "USD"
+
+    def test_meta_minimal(self):
+        """Only source is required; the rest default to None."""
+        meta = LinkedInAdsMeta.model_validate({"source": "linkedin_ads"})
+        assert meta.source == "linkedin_ads"
+        assert meta.account_id is None
+        assert meta.currency_code is None
+
+    def test_insight_row_full(self):
+        row = LinkedInAdsInsightRow.model_validate(
+            {
+                "pivot_value": "urn:li:sponsoredCampaign:777",
+                "start": "2026-07-01",
+                "end": "2026-07-01",
+                "impressions": 1000,
+                "clicks": 25,
+                "cost_in_local_currency": 12.5,
+                "cost_in_usd": 12.5,
+                "conversions": 3,
+                "one_click_leads": 1,
+                "likes": 4,
+                "comments": 2,
+                "shares": 1,
+                "follows": 0,
+            }
+        )
+        assert row.pivot_value == "urn:li:sponsoredCampaign:777"
+        assert row.impressions == 1000
+        assert row.cost_in_local_currency == 12.5
+        assert row.conversions == 3
+
+    def test_insight_row_minimal(self):
+        """Metrics default to 0 and identity fields to None when omitted."""
+        row = LinkedInAdsInsightRow.model_validate({})
+        assert row.pivot_value is None
+        assert row.impressions == 0
+        assert row.cost_in_local_currency == 0.0
+
+    def test_insights_response_empty_rows(self):
+        resp = LinkedInAdsInsightsResponse.model_validate({"row_count": 0, "meta": META})
+        assert resp.rows == []
+        assert resp.row_count == 0
+        assert resp.meta.source == "linkedin_ads"
+
+    def test_campaign_row_with_money(self):
+        row = LinkedInAdsCampaignRow.model_validate(
+            {
+                "id": "500001",
+                "name": "Q3 Brand",
+                "status": "ACTIVE",
+                "type": "SPONSORED_UPDATES",
+                "cost_type": "CPC",
+                "daily_budget": {"amount": "50", "currencyCode": "USD"},
+                "campaign_group": "urn:li:sponsoredCampaignGroup:9001",
+                "audience_expansion_enabled": True,
+                "run_schedule": {"start": 1700000000000},
+            }
+        )
+        assert row.id == "500001"
+        assert row.type == "SPONSORED_UPDATES"
+        assert isinstance(row.daily_budget, LinkedInAdsMoney)
+        assert row.daily_budget.amount == "50"
+        # currencyCode (camelCase from the Go wire shape) maps onto currency_code.
+        assert row.daily_budget.currency_code == "USD"
+        assert row.audience_expansion_enabled is True
+        assert row.run_schedule.start == 1700000000000
+
+    def test_campaign_row_defaults(self):
+        row = LinkedInAdsCampaignRow.model_validate({"id": "2", "name": "X", "status": "DRAFT"})
+        assert row.daily_budget is None
+        assert row.audience_expansion_enabled is False
+        assert row.run_schedule.start is None
+
+
+class TestLinkedInAdsResource:
+    """Tests for LinkedInAdsResource methods."""
+
+    @pytest.fixture
+    def mock_http(self):
+        return MagicMock()
+
+    @pytest.fixture
+    def linkedin_ads_resource(self, mock_http):
+        return LinkedInAdsResource(mock_http)
+
+    @pytest.fixture(autouse=True)
+    def mock_project_domain(self):
+        with patch.dict(os.environ, {"PROJECT_DOMAIN": "example.com"}):
+            yield
+
+    def _insights_payload(self, mock_http):
+        mock_http.post.return_value = {
+            "rows": [
+                {
+                    "pivot_value": "urn:li:sponsoredCampaign:777",
+                    "impressions": 1000,
+                    "clicks": 25,
+                    "cost_in_local_currency": 12.5,
+                }
+            ],
+            "row_count": 1,
+            "meta": META,
+        }
+
+    def test_account_minimal_omits_optional_params(self, linkedin_ads_resource, mock_http):
+        """No dates/granularity => only project_domain + level sent."""
+        self._insights_payload(mock_http)
+
+        result = linkedin_ads_resource.account()
+
+        mock_http.post.assert_called_once_with(
+            "/linkedin-ads/insights",
+            json={"project_domain": "example.com", "level": "account"},
+        )
+        assert len(result.rows) == 1
+        assert result.rows[0].pivot_value == "urn:li:sponsoredCampaign:777"
+        assert result.meta.currency_code == "USD"
+
+    def test_campaigns_with_all_params(self, linkedin_ads_resource, mock_http):
+        self._insights_payload(mock_http)
+
+        linkedin_ads_resource.campaigns(
+            start_date="2026-07-01",
+            end_date="2026-07-31",
+            granularity="daily",
+        )
+
+        mock_http.post.assert_called_once_with(
+            "/linkedin-ads/insights",
+            json={
+                "project_domain": "example.com",
+                "level": "campaign",
+                "start_date": "2026-07-01",
+                "end_date": "2026-07-31",
+                "granularity": "daily",
+            },
+        )
+
+    def test_pivot_levels(self, linkedin_ads_resource, mock_http):
+        """Each insights method sends its own pivot level."""
+        for method, level in [
+            (linkedin_ads_resource.account, "account"),
+            (linkedin_ads_resource.campaign_groups, "campaign_group"),
+            (linkedin_ads_resource.campaigns, "campaign"),
+            (linkedin_ads_resource.creatives, "creative"),
+        ]:
+            self._insights_payload(mock_http)
+            mock_http.post.reset_mock()
+            method()
+            _, kwargs = mock_http.post.call_args
+            assert kwargs["json"]["level"] == level
+
+    def test_list_campaigns(self, linkedin_ads_resource, mock_http):
+        mock_http.post.return_value = {
+            "rows": [{"id": "1", "name": "C", "status": "ACTIVE", "type": "SPONSORED_UPDATES"}],
+            "row_count": 1,
+            "meta": META,
+        }
+
+        result = linkedin_ads_resource.list_campaigns()
+
+        mock_http.post.assert_called_once_with(
+            "/linkedin-ads/campaigns",
+            json={"project_domain": "example.com"},
+        )
+        assert isinstance(result, LinkedInAdsCampaignsResponse)
+        assert result.rows[0].name == "C"
+        assert result.rows[0].type == "SPONSORED_UPDATES"