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

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:

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:

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.