### Setup and Build SDK Environment

Source: https://github.com/beautyfree/yandex-direct-api-sdk/blob/main/examples/README.md

Initial setup commands required to install dependencies and build the SDK from the local repository root. This is a mandatory prerequisite for running any included code examples.

```bash
bun install
bun run build
```

--------------------------------

### Execute SDK Example

Source: https://github.com/beautyfree/yandex-direct-api-sdk/blob/main/examples/README.md

Steps to navigate to a specific example directory, install its local dependencies, and launch the application using a Yandex Direct OAuth token. Ensure the environment variable is set before starting the process.

```bash
cd examples/campaigns-basic
bun install
export YANDEX_DIRECT_TOKEN="your-oauth-token"
bun start
```

--------------------------------

### Run Agency Basic Example with Bun

Source: https://github.com/beautyfree/yandex-direct-api-sdk/blob/main/examples/agency-basic/README.md

This snippet shows the steps to run the agency-basic example using Bun. It involves building the project, navigating to the example directory, installing dependencies, setting Yandex Direct API credentials as environment variables, and executing the start script. Ensure you replace '...' with your actual token and 'advertiser-login' with the correct client login.

```bash
# from repo root: bun run build
cd examples/agency-basic
bun install
export YANDEX_DIRECT_TOKEN="..."
export YANDEX_DIRECT_CLIENT_LOGIN="advertiser-login"
export YANDEX_DIRECT_SANDBOX=true
bun start
```

--------------------------------

### Install SDK via NPM

Source: https://github.com/beautyfree/yandex-direct-api-sdk/blob/main/README.md

The command to add the Yandex Direct API SDK package to your Node.js project.

```bash
npm install yandex-direct-api-sdk
```

--------------------------------

### Initialize Yandex Direct Client

Source: https://context7.com/beautyfree/yandex-direct-api-sdk/llms.txt

Demonstrates how to instantiate the YandexDirectClient with authentication credentials, environment settings, and retry policies. This setup enables access to the full suite of advertising services.

```typescript
import { YandexDirectClient } from 'yandex-direct-api-sdk';

const client = new YandexDirectClient({
  token: process.env.YANDEX_DIRECT_TOKEN!,
  language: 'en',
  sandbox: true,
  clientLogin: 'agency-advertiser-login',
  useOperatorUnits: false,
  paymentToken: 'optional-payment-token',
  acceptGzip: true,
  extraHeaders: { 'Custom-Header': 'value' },
  apiVersion: 'v5',
  maxRetries: 3,
  retryDelayMs: 1000
});

const response = await client.campaigns.get({
  SelectionCriteria: { Ids: [123456789] },
  FieldNames: ['Id', 'Name', 'State', 'Status']
});

console.log(response.requestId);
console.log(response.units);
console.log(response.result.Campaigns[0].Name);
```

--------------------------------

### Manage Keyword Bids and Bid Modifiers in TypeScript

Source: https://context7.com/beautyfree/yandex-direct-api-sdk/llms.txt

Shows how to retrieve, set, and manage keyword bids and bid modifiers using the Yandex Direct API SDK. It includes examples for getting current bids, setting new bids, and adjusting modifiers for demographics and mobile devices.

```typescript
// Get current bids for keywords
const bidsResponse = await client.bids.get({
  SelectionCriteria: {
    KeywordIds: [888999, 777888],
    CampaignIds: [123456789]
  },
  FieldNames: ['KeywordId', 'Bid', 'ServingStatus']
});

bidsResponse.result.Bids.forEach(bid => {
  const bidValue = fromMicros(bid.Bid);
  console.log(`Keyword ${bid.KeywordId}: ${bidValue.toFixed(2)} RUB (${bid.ServingStatus})`);
});

// Set bids for keywords
await client.bids.set({
  Bids: [{
    KeywordId: 888999,
    Bid: toMicros(25.00)
  }, {
    KeywordId: 777888,
    Bid: toMicros(18.50)
  }]
});

// Manage bid modifiers by demographics, device, location
const modifiersResponse = await client.bidmodifiers.get({
  SelectionCriteria: {
    CampaignIds: [123456789],
    AdGroupIds: [555111]
  },
  FieldNames: ['Id', 'CampaignId', 'AdGroupId', 'Type']
});

// Add mobile bid adjustment
await client.bidmodifiers.add({
  BidModifiers: [{
    CampaignId: 123456789,
    MobileBidModifier: {
      BidModifier: 120 // 120% = +20% bid adjustment for mobile
    }
  }]
});

// Add demographic bid modifier
await client.bidmodifiers.add({
  BidModifiers: [{
    CampaignId: 123456789,
    DemographicsBidModifier: {
      BidModifierAdjustments: [{
        Gender: 'MALE',
        Age: '25_34',
        BidModifier: 150 // +50% for males aged 25-34
      }]
    }
  }]
});
```

--------------------------------

### Agency Client and Report Generation

Source: https://github.com/beautyfree/yandex-direct-api-sdk/blob/main/README.md

Example of configuring the client for agency workflows using a specific client login and fetching an analytical report.

```typescript
const agencyClient = new YandexDirectClient({
  token: process.env.YANDEX_DIRECT_TOKEN!,
  clientLogin: 'advertiser-login',
});

const clients = await agencyClient.agencyclients.get({
  SelectionCriteria: {},
  FieldNames: ['Login', 'CountryId'] as const,
});

const report = await agencyClient.reports.getReport(
  {
    SelectionCriteria: {
      Filter: [{ Field: 'CampaignId', Operator: 'IN', Values: ['10002'] }],
    },
    FieldNames: ['Date', 'CampaignId', 'Clicks', 'Cost'] as const,
    ReportName: 'Agency stats',
    ReportType: 'CAMPAIGN_PERFORMANCE_REPORT',
    DateRangeType: 'LAST_7_DAYS',
    Format: 'TSV',
    IncludeVAT: 'YES',
  },
  { processingMode: 'auto' }
);
```

--------------------------------

### Execute Basic Campaign Performance Report Request (Bash)

Source: https://github.com/beautyfree/yandex-direct-api-sdk/blob/main/examples/reports-basic/README.md

This snippet provides the bash commands to set up the environment and execute a basic campaign performance report request using the Yandex Direct API SDK. It requires setting environment variables for the API token, campaign ID, and sandbox mode before running the `bun start` command.

```bash
# from repo root: bun run build
cd examples/reports-basic
bun install
export YANDEX_DIRECT_TOKEN="..."
export YANDEX_DIRECT_CAMPAIGN_ID=10002
export YANDEX_DIRECT_SANDBOX=true
bun start
```

--------------------------------

### Initialize Client and Fetch Campaigns

Source: https://github.com/beautyfree/yandex-direct-api-sdk/blob/main/README.md

Demonstrates how to instantiate the YandexDirectClient with authentication credentials and perform a basic campaign retrieval query.

```typescript
import { YandexDirectClient } from 'yandex-direct-api-sdk';

const client = new YandexDirectClient({
  token: process.env.YANDEX_DIRECT_TOKEN!,
  language: 'en',
});

const response = await client.campaigns.get({
  SelectionCriteria: { Ids: [123456789] },
  FieldNames: ['Id', 'Name', 'State', 'Status'],
});

console.log(response.requestId);
console.log(response.units);
console.log(response.result.Campaigns);
```

--------------------------------

### Development Lifecycle Commands

Source: https://github.com/beautyfree/yandex-direct-api-sdk/blob/main/README.md

Standard commands for managing the development environment using the Bun runtime.

```bash
bun install
bun run typecheck
bun test
bun run build
```

--------------------------------

### Manage Agency Operations with Yandex Direct

Source: https://context7.com/beautyfree/yandex-direct-api-sdk/llms.txt

Demonstrates how to initialize an agency client and perform operations on behalf of specific advertisers. Includes listing clients under an agency and retrieving campaign reports.

```typescript
const agencyClient = new YandexDirectClient({
  token: process.env.YANDEX_DIRECT_TOKEN!,
  clientLogin: 'advertiser-login-123',
  language: 'en'
});

const clientsResponse = await agencyClient.agencyclients.get({
  SelectionCriteria: {},
  FieldNames: ['Login', 'CountryId', 'Currency', 'ClientId', 'ClientInfo']
});

const clientCampaigns = await agencyClient.campaigns.get({
  SelectionCriteria: {},
  FieldNames: ['Id', 'Name', 'State']
});

const clientReport = await agencyClient.reports.getReport({
  SelectionCriteria: {
    Filter: [{ Field: 'CampaignId', Operator: 'IN', Values: ['10002'] }]
  },
  FieldNames: ['Date', 'CampaignId', 'Clicks', 'Cost'],
  ReportName: 'Client Performance',
  ReportType: 'CAMPAIGN_PERFORMANCE_REPORT',
  DateRangeType: 'LAST_7_DAYS',
  Format: 'TSV',
  IncludeVAT: 'YES'
});
```

--------------------------------

### Implementing Pagination for API Requests

Source: https://github.com/beautyfree/yandex-direct-api-sdk/blob/main/README.md

Utilizes the paginate helper function to process large datasets from methods that support page-based navigation, allowing for memory-efficient iteration.

```typescript
import { paginate } from 'yandex-direct-api-sdk';

for await (const page of paginate(
  (params) => client.ads.get(params),
  {
    SelectionCriteria: { CampaignIds: [123456789] },
    FieldNames: ['Id', 'AdGroupId', 'CampaignId'],
  },
  { limit: 10_000 },
)) {
  console.log(page.result.Ads.length);
}
```

--------------------------------

### Manage Ad Groups

Source: https://context7.com/beautyfree/yandex-direct-api-sdk/llms.txt

Covers how to interact with ad groups, including fetching groups within a campaign, creating new groups with negative keywords, and modifying settings.

```typescript
const adGroupsResponse = await client.adGroups.get({
  SelectionCriteria: { CampaignIds: [123456789], Ids: [555111, 555222] },
  FieldNames: ['Id', 'Name', 'CampaignId', 'Status', 'Type'],
  Page: { Limit: 1000, Offset: 0 }
});

const newAdGroup = await client.adGroups.add({
  AdGroups: [{
    Name: 'Premium Keywords Group',
    CampaignId: 123456789,
    RegionIds: [225],
    NegativeKeywords: { Items: ['cheap', 'free', 'download'] }
  }]
});

const adGroupId = newAdGroup.result.AddResults?.[0]?.Id;

await client.adGroups.update({ AdGroups: [{ Id: adGroupId!, Name: 'Premium Keywords Group - Updated', RegionIds: [225, 187] }] });
await client.adGroups.delete({ SelectionCriteria: { Ids: [adGroupId!] } });
```

--------------------------------

### Manage Campaigns Lifecycle

Source: https://context7.com/beautyfree/yandex-direct-api-sdk/llms.txt

Illustrates standard CRUD operations for Yandex advertising campaigns, including retrieval, creation, updates, and state lifecycle management (suspend, resume, archive).

```typescript
const { result } = await client.campaigns.get({
  SelectionCriteria: { Ids: [123456789], States: ['ON', 'SUSPENDED'] },
  FieldNames: ['Id', 'Name', 'State', 'Status', 'StartDate'],
  TextCampaignFieldNames: ['BiddingStrategy']
});

const addResponse = await client.campaigns.add({
  Campaigns: [{
    Name: 'New Search Campaign',
    StartDate: '2026-04-01',
    TextCampaign: {
      BiddingStrategy: { Search: { BiddingStrategyType: 'HIGHEST_POSITION' }, Network: { BiddingStrategyType: 'SERVING_OFF' } },
      Settings: []
    }
  }]
});

const newCampaignId = addResponse.result.AddResults?.[0]?.Id;

await client.campaigns.update({ Campaigns: [{ Id: newCampaignId!, Name: 'Updated Campaign Name' }] });
await client.campaigns.suspend({ SelectionCriteria: { Ids: [newCampaignId!] } });
await client.campaigns.archive({ SelectionCriteria: { Ids: [newCampaignId!] } });
```

--------------------------------

### Requesting Statistics Reports in TypeScript

Source: https://github.com/beautyfree/yandex-direct-api-sdk/blob/main/README.md

Demonstrates how to fetch performance reports using client.reports.getReport and how to handle offline/queued report requests. The SDK automatically handles TSV parsing and polling for report generation status.

```typescript
const report = await client.reports.getReport({
  SelectionCriteria: {
    Filter: [
      { Field: 'CampaignId', Operator: 'IN', Values: ['10002', '10007'] },
    ],
  },
  FieldNames: ['Date', 'CampaignId', 'Clicks', 'Cost'] as const,
  ReportName: 'Actual Data',
  ReportType: 'CAMPAIGN_PERFORMANCE_REPORT',
  DateRangeType: 'AUTO',
  Format: 'TSV',
  IncludeVAT: 'YES',
});

console.log(report.rows[0].Clicks); // string
```

```typescript
const pendingOrReport = await client.reports.requestReport(
  {
    SelectionCriteria: {
      Filter: [{ Field: 'CampaignId', Operator: 'IN', Values: ['10002'] }],
    },
    FieldNames: ['Date', 'CampaignId', 'Clicks'] as const,
    ReportName: 'Queued report',
    ReportType: 'CAMPAIGN_PERFORMANCE_REPORT',
    DateRangeType: 'AUTO',
    Format: 'TSV',
    IncludeVAT: 'YES',
  },
  { processingMode: 'offline' },
);

if ('status' in pendingOrReport) {
  console.log(pendingOrReport.status, pendingOrReport.retryInSeconds);
}
```

--------------------------------

### Manage Yandex Direct Keywords (TypeScript)

Source: https://context7.com/beautyfree/yandex-direct-api-sdk/llms.txt

Manage search keywords within ad groups, including setting bids and matching parameters. Supports retrieval, addition, updates, and lifecycle management (suspend/resume, delete). Requires a Yandex Direct API client and ad group IDs.

```typescript
// Get keywords for ad groups
const keywordsResponse = await client.keywords.get({
  SelectionCriteria: {
    AdGroupIds: [555111, 555222],
    States: ['ON']
  },
  FieldNames: ['Id', 'Keyword', 'AdGroupId', 'Bid', 'State', 'Status']
});

keywordsResponse.result.Keywords.forEach(kw => {
  console.log(`${kw.Keyword}: bid ${kw.Bid} (${kw.State})`);
});

// Add keywords to ad group
const newKeywords = await client.keywords.add({
  Keywords: [{
    AdGroupId: 555111,
    Keyword: 'premium software solution',
    Bid: 15000000, // 15 rubles in micros
    UserParam1: 'category-a',
    UserParam2: 'segment-1'
  }, {
    AdGroupId: 555111,
    Keyword: 'business automation tools',
    Bid: 12000000 // 12 rubles in micros
  }]
});

const keywordId = newKeywords.result.AddResults?.[0]?.Id;

// Update keyword bid
await client.keywords.update({
  Keywords: [{
    Id: keywordId!,
    Bid: 20000000 // Increase to 20 rubles
  }]
});

// Suspend/resume keywords
await client.keywords.suspend({ SelectionCriteria: { Ids: [keywordId!] } });
await client.keywords.resume({ SelectionCriteria: { Ids: [keywordId!] } });

// Delete keywords
await client.keywords.delete({ SelectionCriteria: { Ids: [keywordId!] } });
```

--------------------------------

### Manage Yandex Direct Ads (TypeScript)

Source: https://context7.com/beautyfree/yandex-direct-api-sdk/llms.txt

Perform full lifecycle operations on text and dynamic ads, including creation, updating, moderation, and status changes. This requires a Yandex Direct API client instance and relevant IDs.

```typescript
const adsResponse = await client.ads.get({
  SelectionCriteria: {
    CampaignIds: [123456789],
    AdGroupIds: [555111],
    States: ['ON', 'SUSPENDED']
  },
  FieldNames: ['Id', 'AdGroupId', 'CampaignId', 'Status', 'State', 'Type'],
  TextAdFieldNames: ['Title', 'Text', 'DisplayUrlPath']
});

adsResponse.result.Ads.forEach(ad => {
  if (ad.TextAd) {
    console.log(`Ad ${ad.Id}: ${ad.TextAd.Title} - ${ad.State}`);
  }
});

// Create new text ad
const newAd = await client.ads.add({
  Ads: [{
    AdGroupId: 555111,
    TextAd: {
      Title: 'Premium Software Solution',
      Text: 'Best tools for your business. Free trial available.',
      DisplayUrlPath: 'products/premium'
    }
  }]
});

const adId = newAd.result.AddResults?.[0]?.Id;

// Update ad content
await client.ads.update({
  Ads: [{
    Id: adId!,
    TextAd: {
      Title: 'Premium Software - 20% Off',
      Text: 'Limited time offer on best tools. Start free trial today.'
    }
  }]
});

// Lifecycle operations
await client.ads.suspend({ SelectionCriteria: { Ids: [adId!] } });
await client.ads.resume({ SelectionCriteria: { Ids: [adId!] } });
await client.ads.moderate({ SelectionCriteria: { Ids: [adId!] } });
await client.ads.archive({ SelectionCriteria: { Ids: [adId!] } });
await client.ads.unarchive({ SelectionCriteria: { Ids: [adId!] } });
await client.ads.delete({ SelectionCriteria: { Ids: [adId!] } });
```

--------------------------------

### POST /json/v5/reports

Source: https://github.com/beautyfree/yandex-direct-api-sdk/blob/main/README.md

Generates performance reports for campaigns or ads, returning data in TSV or plain text format for statistical analysis.

```APIDOC
## POST /json/v5/reports

### Description
Requests and retrieves performance statistics reports for various campaign entities.

### Method
POST

### Endpoint
/json/v5/reports

### Parameters
#### Request Body
- **SelectionCriteria** (object) - Required - Filters for report data.
- **FieldNames** (array) - Required - Fields for the report columns.
- **ReportType** (string) - Required - The type of report (e.g., 'CAMPAIGN_PERFORMANCE_REPORT').
- **Format** (string) - Required - Response format (usually 'TSV').

### Request Example
{
  "method": "getReport",
  "params": {
    "SelectionCriteria": { "Filter": [{ "Field": "CampaignId", "Operator": "IN", "Values": ["10002"] }] },
    "FieldNames": ["Date", "CampaignId", "Clicks", "Cost"],
    "ReportType": "CAMPAIGN_PERFORMANCE_REPORT",
    "Format": "TSV"
  }
}

### Response
#### Success Response (200)
- **body** (string) - The raw TSV data of the requested report.

#### Response Example
"Date\tCampaignId\tClicks\tCost\n2023-10-01\t10002\t5\t100.50"
```

--------------------------------

### Converting Monetary Values

Source: https://github.com/beautyfree/yandex-direct-api-sdk/blob/main/README.md

Utilities to convert between standard currency values and the micros (1/1,000,000) format used by the Yandex Direct API.

```typescript
import { toMicros, fromMicros } from 'yandex-direct-api-sdk';

const apiValue = toMicros(12.34);  // 12340000
const human = fromMicros(apiValue); // 12.34
```

--------------------------------

### Handle API Errors and Retries in TypeScript

Source: https://context7.com/beautyfree/yandex-direct-api-sdk/llms.txt

Demonstrates how to catch and handle Yandex Direct API errors, including checking for retriable errors and implementing exponential backoff for automatic retries. It differentiates between API-specific errors and general exceptions.

```typescript
import { YandexDirectApiError } from 'yandex-direct-api-sdk';

try {
  await client.campaigns.update({
    Campaigns: [{
      Id: 999999999, // Non-existent campaign
      Name: 'Updated Name'
    }]
  });
} catch (error) {
  if (error instanceof YandexDirectApiError) {
    console.error(`API Error ${error.code}: ${error.message}`);
    console.error(`Detail: ${error.detail}`);
    console.error(`Request ID: ${error.requestId}`);

    if (error.units) {
      console.error(`Units spent: ${error.units.spent}, remaining: ${error.units.remaining}`);
    }

    if (error.isRetriable) {
      console.log('This error is retriable (rate limit, server error, etc.)');
      // Implement exponential backoff
      await new Promise(resolve => setTimeout(resolve, 2000));
      // Retry the request
    } else {
      console.error('This error is not retriable (invalid data, auth, etc.)');
      throw error;
    }
  } else {
    console.error('Non-API error:', error);
    throw error;
  }
}
```

```typescript
// Comprehensive error handling with retries
async function updateCampaignWithRetry(campaignId: number, name: string, maxRetries = 3) {
  let attempt = 0;

  while (attempt < maxRetries) {
    try {
      const response = await client.campaigns.update({
        Campaigns: [{ Id: campaignId, Name: name }]
      });

      console.log(`Campaign updated successfully: ${response.requestId}`);
      return response;
    } catch (error) {
      attempt++;

      if (error instanceof YandexDirectApiError) {
        if (error.isRetriable && attempt < maxRetries) {
          const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
          console.log(`Retriable error (${error.code}), retrying in ${delay}ms... (attempt ${attempt}/${maxRetries})`);
          await new Promise(resolve => setTimeout(resolve, delay));
        } else {
          throw error;
        }
      } else {
        throw error;
      }
    }
  }

  throw new Error('Max retries exceeded');
}

// Use with automatic retry
await updateCampaignWithRetry(123456789, 'New Campaign Name');
```

--------------------------------

### POST /json/v5/campaigns

Source: https://github.com/beautyfree/yandex-direct-api-sdk/blob/main/README.md

Retrieves campaign data based on specified selection criteria. Use this to fetch statuses, names, and identifiers for existing campaigns.

```APIDOC
## POST /json/v5/campaigns

### Description
Retrieves campaign information using specific criteria such as IDs or states.

### Method
POST

### Endpoint
/json/v5/campaigns

### Parameters
#### Request Body
- **SelectionCriteria** (object) - Required - Criteria for selecting campaigns (e.g., Ids).
- **FieldNames** (array) - Required - List of fields to retrieve (e.g., 'Id', 'Name', 'State').

### Request Example
{
  "method": "get",
  "params": {
    "SelectionCriteria": { "Ids": [123456789] },
    "FieldNames": ["Id", "Name", "State", "Status"]
  }
}

### Response
#### Success Response (200)
- **result** (object) - Contains the 'Campaigns' array with the requested field data.
- **requestId** (string) - Unique identifier for the request.
- **units** (object) - Metadata regarding API unit usage.

#### Response Example
{
  "result": {
    "Campaigns": [{ "Id": 123456789, "Name": "My Campaign", "State": "ON", "Status": "ACCEPTED" }]
  },
  "requestId": "123456789",
  "units": { "spent": 1, "remaining": 999, "dailyLimit": 1000 }
}
```

--------------------------------

### Paginate Large API Result Sets

Source: https://context7.com/beautyfree/yandex-direct-api-sdk/llms.txt

Utilizes the paginate async generator helper to iterate through large datasets from the Yandex Direct API. This pattern handles offset-based pagination automatically, ensuring efficient resource usage.

```typescript
import { paginate } from 'yandex-direct-api-sdk';

for await (const page of paginate(
  (params) => client.ads.get(params),
  {
    SelectionCriteria: { CampaignIds: [123456789, 987654321] },
    FieldNames: ['Id', 'AdGroupId', 'State', 'Status']
  },
  { limit: 10_000 }
)) {
  page.result.Ads.forEach(ad => {
    console.log(ad.Id);
  });
}
```

--------------------------------

### Handling Yandex Direct API Errors

Source: https://github.com/beautyfree/yandex-direct-api-sdk/blob/main/README.md

Shows how to catch and handle API-specific errors using the YandexDirectApiError class. This includes checking for retriable errors and accessing diagnostic information like request IDs.

```typescript
import { YandexDirectApiError } from 'yandex-direct-api-sdk';

try {
  await client.ads.update({
    Ads: [
      {
        Id: 111,
        TextAd: { Title: 'New title' },
      },
    ],
  });
} catch (error) {
  if (error instanceof YandexDirectApiError) {
    console.error(error.code, error.detail, error.requestId);
    if (error.isRetriable) {
      // retry logic
    }
  }
  throw error;
}
```

--------------------------------

### Convert Monetary Values to Micros

Source: https://context7.com/beautyfree/yandex-direct-api-sdk/llms.txt

Uses utility functions to convert currency between human-readable decimal values and the micros format required by the Yandex Direct API. Essential for bid management and cost calculation.

```typescript
import { toMicros, fromMicros } from 'yandex-direct-api-sdk';

const bidInRubles = 15.50;
const bidForApi = toMicros(bidInRubles); // 15500000

const keywordsResponse = await client.keywords.get({
  SelectionCriteria: { Ids: [777888] },
  FieldNames: ['Id', 'Keyword', 'Bid']
});

keywordsResponse.result.Keywords.forEach(kw => {
  const bidInRubles = fromMicros(kw.Bid);
  console.log(`${kw.Keyword}: ${bidInRubles.toFixed(2)} RUB`);
});
```

--------------------------------

### Request Yandex Direct Reports (TypeScript)

Source: https://context7.com/beautyfree/yandex-direct-api-sdk/llms.txt

Request performance reports in TSV format with automatic polling and typed row data. Supports custom filtering, field selection, date range specification, and sorting. Can also be used for manual, offline report requests.

```typescript
// Request performance report with automatic polling
const report = await client.reports.getReport({
  SelectionCriteria: {
    Filter: [
      { Field: 'CampaignId', Operator: 'IN', Values: ['123456789', '987654321'] },
      { Field: 'Date', Operator: 'GREATER_THAN_OR_EQUALS', Values: ['2026-03-01'] }
    ]
  },
  FieldNames: ['Date', 'CampaignId', 'CampaignName', 'Impressions', 'Clicks', 'Cost', 'Ctr'],
  ReportName: 'Campaign Performance Report',
  ReportType: 'CAMPAIGN_PERFORMANCE_REPORT',
  DateRangeType: 'LAST_30_DAYS',
  Format: 'TSV',
  IncludeVAT: 'YES',
  OrderBy: [{ Field: 'Cost', SortOrder: 'DESCENDING' }]
}, {
  returnMoneyInMicros: false, // Get currency values, not micros
  skipReportHeader: false,
  skipColumnHeader: false,
  skipReportSummary: false
});

// Typed report data
console.log(`Columns: ${report.columns.join(', ')}`);
report.rows.forEach(row => {
  console.log(`${row.Date}: ${row.CampaignName} - ${row.Clicks} clicks, ${row.Cost} cost, ${row.Ctr}% CTR`);
});

// Manual request with offline mode
const pendingOrReport = await client.reports.requestReport({
  SelectionCriteria: {
    Filter: [{ Field: 'CampaignId', Operator: 'IN', Values: ['123456789'] }]
  },
  FieldNames: ['Date', 'AdGroupId', 'Clicks', 'Impressions'],
  ReportName: 'Queued Report',
  ReportType: 'ADGROUP_PERFORMANCE_REPORT',
  DateRangeType: 'AUTO',
  Format: 'TSV',
  IncludeVAT: 'YES'
}, {
  processingMode: 'offline'
});

if ('status' in pendingOrReport) {
  console.log(`Report queued: ${pendingOrReport.status}, retry in ${pendingOrReport.retryInSeconds}s`);
  console.log(`Request ID: ${pendingOrReport.requestId}`);
} else {
  console.log(`Report ready: ${pendingOrReport.rows.length} rows`);
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.