Marketplace Transaction Validator

A Next.js application that validates Atlassian Marketplace transactions to ensure:

• Pricing is correct based on user count and platform
• Manual discounts have proper explanations
• Partner cuts are calculated correctly (for specific products)

Features

• Automated Price Validation: Fetches current pricing from marketplace listings and compares against transaction amounts
• Discount Verification: Ensures all manual discounts have explanations
• Partner Cut Validation: Verifies partner commission calculations (20% for Table Grid Next Generation)
• Multiple Report Formats: Generate reports in HTML, JSON, or plain text
• API-First Design: Use via web UI or direct API calls
• Vercel-Ready: Optimized for deployment on Vercel

Prerequisites

• Node.js 18.x or higher
• Atlassian Marketplace API credentials
• Your Developer/Space ID from Atlassian

Getting Your Atlassian API Credentials

The Marketplace API uses Basic Authentication with your email and API token.

1. Get your API Token:

   • Go to https://id.atlassian.com/manage-profile/security/api-tokens
   • Click "Create API token"
   • Give it a name (e.g., "Marketplace Validator")
   • Copy and save the token (you won't see it again!)

2. Get your Developer ID:

   • Go to https://developer.atlassian.com/
   • Navigate to your developer profile or app listings
   • Your Developer/Space ID is in the URL or profile settings
   • It looks like: 39811bd6-659c-4089-a14f-a016fbfec7d9

3. Use your Atlassian account email:

   • This is the email you use to log in to Atlassian

Installation

1. Clone the repository:

git clone <repository-url>
cd mpwatcher

2. Install dependencies:

npm install

3. Create environment file:

cp .env.example .env

4. Configure environment variables in .env:

ATLASSIAN_EMAIL=your_email@example.com
ATLASSIAN_API_TOKEN=your_api_token_here
ATLASSIAN_DEVELOPER_ID=39811bd6-659c-4089-a14f-a016fbfec7d9
PARTNER_CUT_PERCENTAGE=20

Local Development

Run the development server:

npm run dev

Open http://localhost:3000 in your browser.

Deployment to Vercel

Option 1: Vercel CLI

1. Install Vercel CLI:

npm install -g vercel

2. Deploy:

vercel

3. Set environment variables:

vercel env add ATLASSIAN_EMAIL
vercel env add ATLASSIAN_API_TOKEN
vercel env add ATLASSIAN_DEVELOPER_ID
vercel env add PARTNER_CUT_PERCENTAGE

4. Redeploy with environment variables:

vercel --prod

Option 2: Vercel Dashboard

1. Push your code to GitHub
2. Go to vercel.com
3. Click "New Project"
4. Import your GitHub repository
5. Add environment variables:
   • ATLASSIAN_API_TOKEN
   • ATLASSIAN_DEVELOPER_ID
   • PARTNER_CUT_PERCENTAGE
6. Click "Deploy"

API Usage

Validate Transactions

GET /api/validate?startDate=2024-01-01&endDate=2024-12-31&format=json

Parameters:

• startDate (optional): Start date in YYYY-MM-DD format
• endDate (optional): End date in YYYY-MM-DD format
• appKey (optional): Specific app key to validate
• format (optional): Report format - json, html, or text (default: json)

Example Response (JSON format):

{
  "success": true,
  "report": {
    "generatedAt": "2024-10-25T10:30:00.000Z",
    "totalTransactions": 150,
    "validTransactions": 142,
    "invalidTransactions": 8,
    "summary": {
      "priceIssues": 3,
      "discountIssues": 4,
      "partnerCutIssues": 1
    },
    "results": [...]
  }
}

Health Check

GET /api/health

Returns API status and configuration check.

How It Works

1. Price Validation

The validator:

• Fetches current pricing from marketplace listings
• Extracts the pricing tier and platform from each transaction
• Compares the charged amount against expected pricing
• Accounts for discounts and rounding differences

2. Discount Validation

For each transaction with discounts:

• Identifies manual/custom discounts
• Checks if an explanation/reason is provided
• Validates explanation quality (minimum length)

3. Partner Cut Validation

For Table Grid Next Generation transactions:

• Verifies partner commission is calculated correctly
• Checks if the partner cut matches the configured percentage (default 20%)
• Flags any discrepancies

Validation Rules

Price Checks

• ✓ Price matches the marketplace listing for the given tier and platform
• ✓ Discounts are properly applied
• ⚠️ Allows ±$0.02 tolerance for rounding differences

Discount Checks

• ✓ All manual discounts have explanations
• ✓ Explanations are at least 10 characters
• ⚠️ Warning if explanation is too brief

Partner Cut Checks

• ✓ Partner commission is exactly 20% (configurable) of vendor amount
• ✓ Only applies to Table Grid Next Generation
• ⚠️ Allows ±$0.02 tolerance for rounding differences

Project Structure

mpwatcher/
├── lib/
│   ├── atlassian-api.ts      # Atlassian API client
│   ├── pricing-fetcher.ts    # Marketplace pricing scraper
│   ├── validator.ts           # Transaction validation logic
│   └── report-generator.ts   # Report generation
├── pages/
│   ├── api/
│   │   ├── validate.ts       # Main validation endpoint
│   │   └── health.ts         # Health check endpoint
│   ├── _app.tsx
│   └── index.tsx             # Web UI
├── types/
│   └── index.ts              # TypeScript types
├── package.json
├── tsconfig.json
└── next.config.js

Environment Variables

Variable	Description	Required	Default
ATLASSIAN_EMAIL	Your Atlassian account email	Yes	-
ATLASSIAN_API_TOKEN	Your Atlassian API token	Yes	-
ATLASSIAN_DEVELOPER_ID	Your developer/space ID	Yes	-
PARTNER_CUT_PERCENTAGE	Partner commission %	No	20
APP_KEYS	Comma-separated app keys to validate	No	All apps

Troubleshooting

"Missing required environment variables"

• Ensure ATLASSIAN_EMAIL, ATLASSIAN_API_TOKEN, and ATLASSIAN_DEVELOPER_ID are set in your .env file or Vercel environment variables
• The email should be your Atlassian account email (used for Basic Auth)
• Get your API token from: https://id.atlassian.com/manage-profile/security/api-tokens

"401 Unauthorized" or "credentials not valid"

• Double-check your email and API token are correct
• Make sure the API token hasn't expired
• Verify the email matches your Atlassian account
• The API uses Basic Authentication (email + token), not OAuth

"Could not fetch pricing information"

• The marketplace listing page structure may have changed
• Check if the app key is correct
• Verify the app is publicly listed on the marketplace

"No transactions found"

• Check your API token has the correct permissions
• Verify your developer ID is correct
• Ensure there are transactions in the specified date range

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

MIT

Support

For issues or questions, please open an issue on GitHub.