npm package: @rbaileysr/atlassian-marketplace-managed-api
Description: Managed API wrapper for Atlassian Marketplace API Reporting endpoints
Author: rbaileysr
Latest version: 1.0.0

# Atlassian Marketplace Managed API

A type-safe Managed API wrapper for Atlassian Marketplace API Reporting endpoints, designed for use in ScriptRunner Connect.

## Overview

This package provides a comprehensive, type-safe interface to the Atlassian Marketplace API Reporting section, including:

- **Reporting Links**: Get links to permitted vendor reporting resources
- **Feedback**: Get feedback and aggregated feedback metrics
- **Evaluations**: Get aggregated evaluation metrics (by hosting, country, partner, region)
- **Licenses**: Get licenses, export licenses, and initiate async license exports
- **Sales**: Get sales metrics (churn, conversion, renewal), transactions, and benchmarks
- **Customer Insights**: Get customer insights by regions, editions, active users, and tiers
- **Search Keywords**: Get search keyword data and zero search results keywords
- **Benchmark**: Get benchmark evaluations and sales metrics
- **App Requests**: Get app requests and approvals

## Installation

```bash
npm install @rbaileysr/atlassian-marketplace-managed-api
```

## Usage

### Setup

1. Configure an API Connection in ScriptRunner Connect web UI:
   - **Path**: `scripts/api/atlassian-marketplace`
   - **Base URL**: `https://marketplace.atlassian.com/rest/3`
   - **Authentication**: Configure using Generic Connector or appropriate authentication method

2. Import and use the Managed API:

```typescript
import { createMarketplaceApi } from '@rbaileysr/atlassian-marketplace-managed-api';
import MarketplaceApiConnection from './api/atlassian-marketplace';

const Marketplace = createMarketplaceApi(MarketplaceApiConnection);

// Get reporting links
const links = await Marketplace.Reporting.getReportingLinks({
  developerId: 'your-developer-id'
});

// Get licenses
const licenses = await Marketplace.Licenses.getLicenses({
  developerId: 'your-developer-id',
  limit: 10
});

// Get aggregated evaluations by hosting
const evaluations = await Marketplace.Evaluations.getAggregatedEvaluations({
  developerId: 'your-developer-id',
  metric: 'hosting'
});

// Initiate async export of licenses
const exportResponse = await Marketplace.Licenses.initiateAsyncExportLicenses({
  developerId: 'your-developer-id',
  startDate: '2024-01-01',
  endDate: '2024-12-31'
});

// Check export status
const status = await Marketplace.Licenses.getAsyncExportStatus({
  developerId: 'your-developer-id',
  exportId: exportResponse.exportId
});
```

## API Groups

### Reporting

- `getReportingLinks(options)` - Get links to permitted vendor reporting resources

### Feedback

- `getFeedback(options)` - Get a list of feedback for the specified vendor's apps
- `getAggregatedFeedback(options)` - Get aggregated feedback (metric: 'reason' or 'type')

### Evaluations

- `getAggregatedEvaluations(options)` - Get aggregated evaluations (metric: 'hosting', 'country', 'partner', or 'region')

### Licenses

- `getLicenses(options)` - Get a list of licenses for the specified vendor's apps
- `exportLicenses(options)` - Export all licenses (CSV or JSON)
- `initiateAsyncExportLicenses(options)` - Initiate async export of licenses
- `getAsyncExportStatus(options)` - Get status of async license export
- `getAsyncExportResult(options)` - Get result of async license export

### Sales

- `getSalesMetricsChurn(options)` - Get churn metrics
- `getSalesMetricsConversion(options)` - Get conversion metrics
- `getSalesMetricsRenewal(options)` - Get renewal metrics
- `getSalesMetricDetails(options)` - Get details about individual Cloud license events
- `exportSalesMetricDetails(options)` - Export sales metric details (CSV or JSON)
- `getSalesTransactions(options)` - Get sales transactions
- `exportSalesTransactions(options)` - Export sales transactions (CSV or JSON)
- `initiateAsyncExportSalesTransactions(options)` - Initiate async export of sales transactions
- `getAsyncExportSalesTransactionsStatus(options)` - Get status of async sales transactions export
- `getAsyncExportSalesTransactionsResult(options)` - Get result of async sales transactions export
- `getSalesTransactionsByMetric(options)` - Get sales transactions aggregated by metric
- `exportFreeStarterTier(options)` - Export free starter tier data (CSV or JSON)
- `getSalesMetricsChurnBenchmark(options)` - Get churn benchmark metrics

### Customer Insights

- `getCustomerInsightsRegions(options)` - Get customer insights by region
- `getCustomerInsightsEditions(options)` - Get customer insights by edition
- `getCustomerInsightsActiveUsers(options)` - Get customer insights for active users
- `getCustomerInsightsTiers(options)` - Get customer insights by tier

### Search Keywords

- `getSearchKeywordsBySource(options)` - Get top 500 searched keywords by source
- `exportSearchKeywordsBySource(options)` - Export search keywords by source (CSV or JSON)
- `getZeroSearchResultsKeywordsBySource(options)` - Get keywords with zero search results by source
- `exportZeroSearchResultsKeywordsBySource(options)` - Export zero search results keywords by source (CSV or JSON)
- `getSearchKeywords(options)` - Get search keywords for vendor's apps
- `exportSearchKeywords(options)` - Export search keywords (CSV or JSON)
- `getProductSearchKeywords(options)` - Get search keywords for a specific product
- `exportProductSearchKeywords(options)` - Export product search keywords (CSV or JSON)

### Benchmark

- `getBenchmarkEvaluations(options)` - Get benchmark evaluation metrics
- `getBenchmarkSales(options)` - Get benchmark sales metrics

### App Requests

- `getAppRequestsAndApprovals(options)` - Get app requests and approvals

## Type Definitions

All types are exported from the package for use in your scripts:

```typescript
import type {
  GetLicensesOptions,
  LicensesResponse,
  GetFeedbackOptions,
  Feedback,
  // ... other types
} from '@rbaileysr/atlassian-marketplace-managed-api';
```

## Features

- **Type Safety**: Full TypeScript support with IntelliSense
- **Error Handling**: Comprehensive error handling with meaningful error messages
- **Query Building**: Automatic query string building from options
- **Response Parsing**: Automatic response parsing with proper error handling
- **Export Support**: Support for CSV and JSON export formats
- **Async Exports**: Support for async export operations with status checking

## Requirements

- ScriptRunner Connect workspace
- API Connection configured in ScriptRunner Connect web UI
- Node.js >= 18.0.0 (for local development)

## License

MIT

## Support

For issues and questions, please refer to the [ScriptRunner Connect Documentation](https://docs.adaptavist.com/src/latest/).