DOCSP-51008: Add billing examples

.env.example

@@ -1,2 +1,2 @@
 MONGODB_ATLAS_SERVICE_ACCOUNT_ID=your_mdb_service_account_id
-MONGODB_ATLAS_SERVICE_ACCOUNT_SECRET=your_mdb_service_account_secret
+MONGODB_ATLAS_SERVICE_ACCOUNT_SECRET=your_mdb_service_account_secret

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 Notable changes to the project.
 
+## v1.1 (2025-06-17)
+### Added
+- Example scripts for fetching cross-organization billing information.
+
 ## v1.0 (2025-05-29)
 ### Added
-- Initial project structure with example scripts for fetching logs and metrics.
+- Initial project structure with example scripts for fetching logs and metrics.

README.md

@@ -1,42 +1,48 @@
 # Atlas Go SDK Examples for the MongoDB Atlas Architecture Center
 
-This repository contains runnable examples for the 
-[Atlas Go SDK](https://www.mongodb.com/docs/atlas/sdk/) 
-that align with best practices from the MongoDB 
-[Atlas Architecture
-Center](https://www.mongodb.com/docs/atlas/architecture/current/).
+This repository contains runnable examples for the
+[Atlas Go SDK](https://www.mongodb.com/docs/atlas/sdk/)
+that align with best practices from the MongoDB
+[Atlas Architecture Center](https://www.mongodb.com/docs/atlas/architecture/current/).
 
-Use these examples as starting points for your own Atlas integration. 
+Use these examples as starting points for your own Atlas integration.
 
 ## Features
 
-Currently, the repository includes examples for:
+Currently, the repository includes examples that demonstrate the following:
 
 - Authenticate with service accounts
-- Retrieve cluster and database metrics
+- Return cluster and database metrics
 - Download logs for a specific host
-- Programmatically manage Atlas resources 
+- Pull and parse line-item-level billing data
+- Return all linked organizations from a specific billing organization
+- Get historical invoices for an organization 
+- Programmatically manage Atlas resources
 
-As the Architecture Center documentation evolves, this repository will be updated with new examples and improvements to existing code.
+As the Architecture Center documentation evolves, this repository will be updated with new examples 
+and improvements to existing code. 
 
 ## Project Structure
 
 ```text
 .
-├── cmd                  # Runnable examples by category
-│   ├── get_logs/main.go
-│   ├── get_metrics_disk/main.go
-│   └── get_metrics_process/main.go
+├── examples             # Runnable examples by category
+│   ├── billing/
+│   └── monitoring/
 ├── configs              # Atlas configuration template
 │   └── config.json
 ├── internal             # Shared utilities and helpers
 │   ├── auth/
+│   ├── billing/
 │   ├── config/
+│   ├── data/
+│   ├── errors/
+│   ├── fileutils/
 │   ├── logs/
-│   ├── metrics/
-│   └── utils.go
+│   └── metrics/
 ├── go.mod
 ├── go.sum
+├── CHANGELOG.md         # List of major changes to the project 
 ├── .gitignore           # Ignores .env file and log output
 └── .env.example         # Example environment variables
 ```
@@ -46,24 +52,20 @@ As the Architecture Center documentation evolves, this repository will be update
 - Go 1.16 or later
 - A MongoDB Atlas project and cluster
 - Service account credentials with appropriate permissions. See
-    [Service Account Overview](https://www.mongodb.com/docs/atlas/api/service-accounts-overview/).
+  [Service Account Overview](https://www.mongodb.com/docs/atlas/api/service-accounts-overview/).
 
-## Setup
+## Setting Environment Variables
 
-1. Clone the repository:
-   ```bash
-   git clone https://github.com/mongodb/atlas-architecture-go-sdk.git
-   cd atlas-architecture-go-sdk
-   ```
-
-2. Create a `.env` file in the root directory with your MongoDB Atlas service account credentials:
-   ```env
+1. Create a `.env` file in the root directory with your MongoDB Atlas service account credentials:
+   ```dotenv
    MONGODB_ATLAS_SERVICE_ACCOUNT_ID=your_service_account_id
    MONGODB_ATLAS_SERVICE_ACCOUNT_SECRET=your_service_account_secret
    ```
-   > **NOTE:** For production, use a secrets manager (e.g. HashiCorp Vault, AWS Secrets Manager) instead of environment variables. See [Secrets management](https://www.mongodb.com/docs/atlas/architecture/current/auth/#secrets-management).
+   > **NOTE:** For production, use a secrets manager (e.g. HashiCorp Vault, AWS Secrets Manager) 
+   > instead of environment variables. 
+   > See [Secrets management](https://www.mongodb.com/docs/atlas/architecture/current/auth/#secrets-management).
 
-3. Configure Atlas details in `configs/config.json`:
+2. Configure Atlas details in `configs/config.json`:
    ```json
    {
      "MONGODB_ATLAS_BASE_URL": "<optional-base-url>",
@@ -75,46 +77,60 @@ As the Architecture Center documentation evolves, this repository will be update
    ```
    > **NOTE:** The base URL defaults to `https://cloud.mongodb.com` if not specified.
 
-4. Install dependencies:
-   ```bash
-   go mod tidy
-   ```
-
 ## Running Examples
 
-### Fetch Logs
+Examples in this project are intended to be run as individual scripts. 
+You can also adjust them to suit your needs:
+
+- Modify time ranges
+- Add filtering parameters
+- Change output formats
+
+### Billing
+#### Get Historical Invoices 
 ```bash
-go run cmd/get_logs/main.go
+go run examples/billing/historical/main.go
 ```
+#### Get Line-Item-Level Billing Data
+```bash
+go run examples/billing/line_items/main.go
+```
+#### Get All Linked Organizations
+```bash
+go run examples/billing/linked_orgs/main.go
+```
+
+### Logs
 Logs output to `./logs` as `.gz` and `.txt`.
 
-### Fetch Metrics
+#### Fetch All Host Logs
 ```bash
-go run cmd/get_metrics_disk/main.go
-# or
-go run cmd/get_metrics_process/main.go
+go run examples/monitoring/logs/main.go
 ```
-Metrics print to the console.
 
-## Customization
+### Metrics
+Metrics print to the console.
 
-Adjust the examples to suit your needs:
+#### Get Disk Measurements
+```bash
+go run examples/monitoring/metrics_disk/main.go
+```
 
-- Modify time ranges
-- Add filtering parameters
-- Change output formats
-- Integrate data into your own tooling
+#### Get Cluster Metrics
+```bash
+go run examples/monitoring/metrics_process/main.go
+```
 
 ## Changelog
 
-For list of changes to this project, see [CHANGELOG](CHANGELOG.md).
+For list of major changes to this project, see [CHANGELOG](CHANGELOG.md).
 
 ## Reporting Issues
 
-Use the "Rate this page" widget on the 
-[Atlas Architecture Center](https://www.mongodb.com/docs/atlas/architecture/current/) 
+Use the "Rate this page" widget on the
+[Atlas Architecture Center](https://www.mongodb.com/docs/atlas/architecture/current/)
 docs to leave feedback or file issues.
 
 ## License
 
-This project is licensed under Apache 2.0. See [LICENSE](LICENSE).
+This project is licensed under Apache 2.0. See [LICENSE](LICENSE.md).

examples/billing/historical/main.go

@@ -0,0 +1,99 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"time"
+
+	"atlas-sdk-go/internal/auth"
+	"atlas-sdk-go/internal/billing"
+	"atlas-sdk-go/internal/config"
+	"atlas-sdk-go/internal/data/export"
+	"atlas-sdk-go/internal/errors"
+	"atlas-sdk-go/internal/fileutils"
+
+	"github.com/joho/godotenv"
+	"go.mongodb.org/atlas-sdk/v20250219001/admin"
+)
+
+func main() {
+	if err := godotenv.Load(); err != nil {
+		log.Printf("Warning: .env file not loaded: %v", err)
+	}
+
+	secrets, cfg, err := config.LoadAll("configs/config.json")
+	if err != nil {
+		errors.ExitWithError("Failed to load configuration", err)
+	}
+
+	client, err := auth.NewClient(cfg, secrets)
+	if err != nil {
+		errors.ExitWithError("Failed to initialize authentication client", err)
+	}
+
+	ctx := context.Background()
+	p := &admin.ListInvoicesApiParams{
+		OrgId: cfg.OrgID,
+	}
+
+	fmt.Printf("Fetching historical invoices for organization: %s\n", p.OrgId)
+
+	// Fetch invoices from the previous six months with the provided options
+	invoices, err := billing.ListInvoicesForOrg(ctx, client.InvoicesApi, p,
+		billing.WithViewLinkedInvoices(true),
+		billing.WithIncludeCount(true),
+		billing.WithDateRange(time.Now().AddDate(0, -6, 0), time.Now()))
+	if err != nil {
+		errors.ExitWithError("Failed to retrieve invoices", err)
+	}
+
+	if invoices.GetTotalCount() > 0 {
+		fmt.Printf("Total count of invoices: %d\n", invoices.GetTotalCount())
+	} else {
+		fmt.Println("No invoices found for the specified date range")
+		return
+	}
+
+	// Export invoice data to be used in other systems or for reporting
+	outDir := "invoices"
+	prefix := fmt.Sprintf("historical_%s", p.OrgId)
+
+	exportInvoicesToJSON(invoices, outDir, prefix)
+	exportInvoicesToCSV(invoices, outDir, prefix)
+}
+
+func exportInvoicesToJSON(invoices *admin.PaginatedApiInvoiceMetadata, outDir, prefix string) {
+	jsonPath, err := fileutils.GenerateOutputPath(outDir, prefix, "json")
+	if err != nil {
+		errors.ExitWithError("Failed to generate JSON output path", err)
+	}
+	if err := export.ToJSON(invoices.GetResults(), jsonPath); err != nil {
+		errors.ExitWithError("Failed to write JSON file", err)
+	}
+	fmt.Printf("Exported invoice data to %s\n", jsonPath)
+}
+
+func exportInvoicesToCSV(invoices *admin.PaginatedApiInvoiceMetadata, outDir, prefix string) {
+	csvPath, err := fileutils.GenerateOutputPath(outDir, prefix, "csv")
+	if err != nil {
+		errors.ExitWithError("Failed to generate CSV output path", err)
+	}
+
+	// Set the headers and mapped rows for the CSV export
+	headers := []string{"InvoiceID", "Status", "Created", "AmountBilled"}
+	err = export.ToCSVWithMapper(invoices.GetResults(), csvPath, headers, func(invoice admin.BillingInvoiceMetadata) []string {
+		return []string{
+			invoice.GetId(),
+			invoice.GetStatusName(),
+			invoice.GetCreated().Format(time.RFC3339),
+			fmt.Sprintf("%.2f", float64(invoice.GetAmountBilledCents())/100.0),
+		}
+	})
+	if err != nil {
+		errors.ExitWithError("Failed to write CSV file", err)
+	}
+
+	fmt.Printf("Exported invoice data to %s\n", csvPath)
+}
+