New Integration: AWS Marketplace

Description

Add AWS Marketplace integration to sync product listings, subscriptions, agreements, metering data, and catalog operations into CORE.

Reference Implementations

Existing Integrations (use as templates)

• integrations/github/ - Similar platform with multiple API surfaces
• integrations/linear/ - Project management integration
• integrations/slack/ - For reference

Required Files Structure

integrations/aws-marketplace/
├── src/
│   ├── index.ts          # Main entry, AWS auth spec
│   ├── schedule.ts       # Sync logic
│   ├── utils.ts          # AWS Marketplace API utilities
│   ├── account-create.ts # AWS credentials setup
│   └── create-activity.ts # Activity formatting
├── package.json
├── tsup.config.ts
└── README.md

AWS Marketplace API Integration

Authentication Setup

• Use AWS IAM credentials (Access Key ID + Secret Access Key)
• Supports AWS Signature Version 4 signing
• Can also use IAM roles and temporary credentials via STS
• Region-specific endpoints

Key APIs and Endpoints

• Catalog API (marketplace-catalog)
  • ListEntities - List products, offers, and other entities
  • DescribeEntity - Get details of a specific entity
  • StartChangeSet - Initiate changes to entities
  • DescribeChangeSet - Get status of pending changes
• Metering Service API (metering.marketplace)
  • BatchMeterUsage - Submit usage records for custom dimensions
  • MeterUsage - Submit a single usage record
  • ResolveCustomer - Resolve customer identifier from registration token
• Entitlement Service API
  • GetEntitlements - Get entitlements for a product
• Agreement API
  • SearchAgreements - Search for agreements
  • DescribeAgreement - Get agreement details
  • GetAgreementTerms - Get agreement terms
• Discovery API (for buyers)
  • Product search and filtering
  • Category browsing

Events to Track

1. Product Management - New product listings, updates, version changes
2. Subscriptions - New subscriptions, cancellations, renewals
3. Agreements - Agreement creation, modification, acceptance
4. Metering & Usage - Usage data submissions, billing events
5. Catalog Changes - Entity modifications, change set completions

Implementation Tasks

• Set up basic integration structure following integrations/github/src/index.ts pattern
• Implement AWS IAM credential authentication flow in account-create.ts
• Create API utilities in utils.ts using AWS SDK for JavaScript
• Implement sync logic in schedule.ts for catalog, subscriptions, and agreements
• Convert marketplace events to CORE activity format
• Add error handling and rate limiting
• Create integration documentation
• Add to integrations/README.md

Technical Notes

• Recommend using the AWS SDK for JavaScript v3 (@aws-sdk/client-marketplace-catalog, @aws-sdk/client-marketplace-metering, etc.)
• Multiple API surfaces exist (Catalog, Metering, Entitlements, Agreements) - each is a separate AWS service
• Change sets in the Catalog API are asynchronous - need to poll for completion
• API reference available as PDF at docs.aws.amazon.com
• Sample code available in the aws-samples/aws-marketplace-api-samples GitHub repository

Resources

• AWS Marketplace API Reference
• Catalog API Documentation
• AWS Marketplace Documentation
• API Samples on GitHub
• Boto3 MarketplaceCatalog Docs

Labels

enhancement, integration, new-feature