refactor: simplify mpp-go public API and tooling

Author: brendanjryan

.gitignore

@@ -0,0 +1,3 @@
+bin/
+*.out
+cover.html

Makefile

@@ -1,7 +1,61 @@
-.PHONY: test integration
+.PHONY: all build_examples clean test test-coverage check fix integration docs help
 
+# Default target
+all: check
+
+# Builds all runnable examples
+build_examples:
+	@mkdir -p bin
+	go build -o bin/charge-basic ./examples/charge-basic
+	go build -o bin/charge-hash ./examples/charge-hash
+	go build -o bin/charge-fee-payer ./examples/charge-fee-payer
+
+# Cleans generated artifacts
+clean:
+	go clean
+	rm -rf bin/
+	rm -f cover.out cover.html coverage.out
+
+# Run unit tests only (integration tests use a build tag and are excluded)
 test:
 	go test ./...
 
+# Run unit tests with coverage
+test-coverage:
+	go test -coverprofile=coverage.out ./...
+	go tool cover -html=coverage.out -o cover.html
+
+# Run formatting, vet, module verification, and unit tests
+check:
+	go mod verify
+	test -z "$$(gofmt -l .)" || (echo "Code needs formatting. Run 'make fix'" && gofmt -l . && exit 1)
+	go vet ./...
+	go test ./...
+
+# Format code and tidy dependencies
+fix:
+	gofmt -s -w .
+	go mod tidy
+
+# Run integration tests against the local Tempo devnet by default
 integration:
 	@TEMPO_RPC_URL=$${TEMPO_RPC_URL:-http://localhost:8545} go test -tags=integration -run TestIntegration -timeout=5m ./tests
+
+# Start a local godoc server for this module
+docs:
+	which godoc > /dev/null || (echo "Installing godoc..." && go install golang.org/x/tools/cmd/godoc@latest)
+	echo "Documentation available at http://localhost:6060/pkg/github.com/tempoxyz/mpp-go/"
+	echo "Press Ctrl+C to stop the server"
+	@godoc -http=:6060
+
+# Show available targets
+help:
+	@echo "Available targets:"
+	@echo "  build_examples  Build the example binaries into ./bin"
+	@echo "  clean           Remove build artifacts and coverage files"
+	@echo "  test            Run unit tests"
+	@echo "  test-coverage   Run unit tests with coverage report"
+	@echo "  check           Run formatting checks, vet, and tests"
+	@echo "  fix             Format code and tidy modules"
+	@echo "  integration     Run integration tests against TEMPO_RPC_URL"
+	@echo "  docs            Start a local godoc server"

README.md

@@ -22,9 +22,18 @@ Go SDK for the [**Machine Payments Protocol**](https://mpp.dev)
 [![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue)](LICENSE)
 
 [MPP](https://mpp.dev) lets any client — agents, apps, or humans — pay for any service in the same HTTP request. It standardizes [HTTP 402](https://mpp.dev/protocol/http-402) with an open [IETF specification](https://paymentauth.org), so servers can charge and clients can pay without API keys, billing accounts, or checkout flows.
+## Documentation
 
 You can get started today by reading the [Go SDK docs](https://mpp.dev/sdk/go), exploring the [protocol overview](https://mpp.dev/protocol/), or jumping straight to the [quickstart](https://mpp.dev/quickstart/).
 
+Package docs:
+
+- [`pkg/client`](https://pkg.go.dev/github.com/tempoxyz/mpp-go/pkg/client)
+- [`pkg/server`](https://pkg.go.dev/github.com/tempoxyz/mpp-go/pkg/server)
+- [`pkg/tempo`](https://pkg.go.dev/github.com/tempoxyz/mpp-go/pkg/tempo)
+- [`pkg/tempo/client`](https://pkg.go.dev/github.com/tempoxyz/mpp-go/pkg/tempo/client)
+- [`pkg/tempo/server`](https://pkg.go.dev/github.com/tempoxyz/mpp-go/pkg/tempo/server)
+
 ## Install
 
 ```bash
@@ -42,13 +51,13 @@ import (
 	"encoding/json"
 	"net/http"
 
-	mppserver "github.com/tempoxyz/mpp-go/pkg/server"
+	"github.com/tempoxyz/mpp-go/pkg/server"
 	"github.com/tempoxyz/mpp-go/pkg/tempo"
 	charge "github.com/tempoxyz/mpp-go/pkg/tempo/server"
 )
 
 func main() {
-	intent, _ := charge.NewChargeIntent(charge.ChargeIntentConfig{
+	intent, _ := charge.NewIntent(charge.IntentConfig{
 		RPCURL: "https://rpc.moderato.tempo.xyz",
 	})
 
@@ -59,15 +68,15 @@ func main() {
 		Recipient: "0x70997970c51812dc3a010c7d01b50e0d17dc79c8",
 	})
 
-	payment := mppserver.New(method, "api.example.com", "replace-me")
+	payment := server.New(method, "api.example.com", "replace-me")
 
-	handler := mppserver.ChargeMiddleware(payment, mppserver.ChargeParams{
+	handler := server.ChargeMiddleware(payment, server.ChargeParams{
 		Amount:      "0.50",
 		Description: "Paid content",
 	})(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		_ = json.NewEncoder(w).Encode(map[string]any{
 			"data":  "paid content",
-			"payer": mppserver.CredentialFromContext(r.Context()).Source,
+			"payer": server.CredentialFromContext(r.Context()).Source,
 		})
 	}))
 
@@ -85,7 +94,7 @@ import (
 	"encoding/json"
 	"fmt"
 
-	mppclient "github.com/tempoxyz/mpp-go/pkg/client"
+	"github.com/tempoxyz/mpp-go/pkg/client"
 	"github.com/tempoxyz/mpp-go/pkg/mpp"
 	charge "github.com/tempoxyz/mpp-go/pkg/tempo/client"
 )
@@ -97,8 +106,8 @@ func main() {
 		RPCURL:     "https://rpc.moderato.tempo.xyz",
 	})
 
-	client := mppclient.New([]mppclient.Method{method})
-	response, err := client.Get(context.Background(), "https://api.example.com/paid")
+	paymentClient := client.New([]client.Method{method})
+	response, err := paymentClient.Get(context.Background(), "https://api.example.com/paid")
 	if err != nil {
 		panic(err)
 	}

examples/README.md

@@ -12,8 +12,8 @@ Start the local Tempo devnet before running them:
 docker compose up -d
 ```
 
-The examples use `mppclient` and `mppserver` for the generic HTTP 402 packages.
-Each file aliases the Tempo charge package to `charge`, since it only uses one
+The examples import the generic HTTP 402 packages as `client` and `server`.
+Each file aliases the Tempo package it uses to `charge`, since it only uses one
 side of the Tempo flow at a time.
 
 Run any example directly from the repo root:

examples/charge-basic/client.go

@@ -5,7 +5,7 @@ import (
 	"encoding/json"
 
 	"github.com/tempoxyz/mpp-go/examples/internal/devnet"
-	mppclient "github.com/tempoxyz/mpp-go/pkg/client"
+	"github.com/tempoxyz/mpp-go/pkg/client"
 	"github.com/tempoxyz/mpp-go/pkg/mpp"
 	charge "github.com/tempoxyz/mpp-go/pkg/tempo/client"
 )
@@ -25,9 +25,9 @@ func runClient(ctx context.Context, url, rpcURL string, chainID int64) (*clientR
 	if err != nil {
 		return nil, err
 	}
-	client := mppclient.New([]mppclient.Method{method})
+	paymentClient := client.New([]client.Method{method})
 
-	response, err := client.Get(ctx, url+"/paid")
+	response, err := paymentClient.Get(ctx, url+"/paid")
 	if err != nil {
 		return nil, err
 	}

examples/charge-basic/server.go

@@ -6,7 +6,7 @@ import (
 	"net/http/httptest"
 
 	"github.com/tempoxyz/mpp-go/examples/internal/devnet"
-	mppserver "github.com/tempoxyz/mpp-go/pkg/server"
+	"github.com/tempoxyz/mpp-go/pkg/server"
 	charge "github.com/tempoxyz/mpp-go/pkg/tempo/server"
 )
 
@@ -16,7 +16,7 @@ type exampleServer struct {
 }
 
 func startServer(rpcURL string, chainID int64) (*exampleServer, error) {
-	intent, err := charge.NewChargeIntent(charge.ChargeIntentConfig{RPCURL: rpcURL})
+	intent, err := charge.NewIntent(charge.IntentConfig{RPCURL: rpcURL})
 	if err != nil {
 		return nil, err
 	}
@@ -26,13 +26,13 @@ func startServer(rpcURL string, chainID int64) (*exampleServer, error) {
 		Currency:  devnet.Currency,
 		Recipient: devnet.Recipient,
 	})
-	payment := mppserver.New(method, devnet.Realm, "example-secret")
+	payment := server.New(method, devnet.Realm, "example-secret")
 
-	handler := mppserver.ChargeMiddleware(payment, mppserver.ChargeParams{
+	handler := server.ChargeMiddleware(payment, server.ChargeParams{
 		Amount:      "0.50",
 		Description: "Basic Tempo charge example",
 	})(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		credential := mppserver.CredentialFromContext(r.Context())
+		credential := server.CredentialFromContext(r.Context())
 		_ = json.NewEncoder(w).Encode(map[string]any{
 			"data":  "paid content",
 			"payer": credential.Source,

examples/charge-fee-payer/client.go

@@ -5,7 +5,7 @@ import (
 	"encoding/json"
 
 	"github.com/tempoxyz/mpp-go/examples/internal/devnet"
-	mppclient "github.com/tempoxyz/mpp-go/pkg/client"
+	"github.com/tempoxyz/mpp-go/pkg/client"
 	"github.com/tempoxyz/mpp-go/pkg/mpp"
 	charge "github.com/tempoxyz/mpp-go/pkg/tempo/client"
 )
@@ -24,9 +24,9 @@ func runClient(ctx context.Context, url, rpcURL string, chainID int64) (*clientR
 	if err != nil {
 		return nil, err
 	}
-	client := mppclient.New([]mppclient.Method{method})
+	paymentClient := client.New([]client.Method{method})
 
-	response, err := client.Get(ctx, url+"/paid")
+	response, err := paymentClient.Get(ctx, url+"/paid")
 	if err != nil {
 		return nil, err
 	}

examples/charge-fee-payer/server.go

@@ -6,7 +6,7 @@ import (
 	"net/http/httptest"
 
 	"github.com/tempoxyz/mpp-go/examples/internal/devnet"
-	mppserver "github.com/tempoxyz/mpp-go/pkg/server"
+	"github.com/tempoxyz/mpp-go/pkg/server"
 	charge "github.com/tempoxyz/mpp-go/pkg/tempo/server"
 )
 
@@ -16,7 +16,7 @@ type exampleServer struct {
 }
 
 func startServer(rpcURL string, chainID int64) (*exampleServer, error) {
-	intent, err := charge.NewChargeIntent(charge.ChargeIntentConfig{
+	intent, err := charge.NewIntent(charge.IntentConfig{
 		FeePayerPrivateKey: devnet.FeePayerPrivateKey,
 		RPCURL:             rpcURL,
 	})
@@ -30,15 +30,15 @@ func startServer(rpcURL string, chainID int64) (*exampleServer, error) {
 		FeePayer:  true,
 		Recipient: devnet.Recipient,
 	})
-	payment := mppserver.New(method, devnet.Realm, "example-secret")
+	payment := server.New(method, devnet.Realm, "example-secret")
 
-	handler := mppserver.ChargeMiddleware(payment, mppserver.ChargeParams{
+	handler := server.ChargeMiddleware(payment, server.ChargeParams{
 		Amount:      "0.50",
 		Description: "Fee-payer Tempo charge example",
 		FeePayer:    true,
 	})(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		_ = json.NewEncoder(w).Encode(map[string]any{
-			"tx": mppserver.ReceiptFromContext(r.Context()).Reference,
+			"tx": server.ReceiptFromContext(r.Context()).Reference,
 		})
 	}))
 

examples/charge-hash/client.go

@@ -5,7 +5,7 @@ import (
 	"encoding/json"
 
 	"github.com/tempoxyz/mpp-go/examples/internal/devnet"
-	mppclient "github.com/tempoxyz/mpp-go/pkg/client"
+	"github.com/tempoxyz/mpp-go/pkg/client"
 	"github.com/tempoxyz/mpp-go/pkg/mpp"
 	"github.com/tempoxyz/mpp-go/pkg/tempo"
 	charge "github.com/tempoxyz/mpp-go/pkg/tempo/client"
@@ -26,9 +26,9 @@ func runClient(ctx context.Context, url, rpcURL string, chainID int64) (*clientR
 	if err != nil {
 		return nil, err
 	}
-	client := mppclient.New([]mppclient.Method{method})
+	paymentClient := client.New([]client.Method{method})
 
-	response, err := client.Get(ctx, url+"/paid")
+	response, err := paymentClient.Get(ctx, url+"/paid")
 	if err != nil {
 		return nil, err
 	}

examples/charge-hash/server.go

@@ -6,7 +6,7 @@ import (
 	"net/http/httptest"
 
 	"github.com/tempoxyz/mpp-go/examples/internal/devnet"
-	mppserver "github.com/tempoxyz/mpp-go/pkg/server"
+	"github.com/tempoxyz/mpp-go/pkg/server"
 	"github.com/tempoxyz/mpp-go/pkg/tempo"
 	charge "github.com/tempoxyz/mpp-go/pkg/tempo/server"
 )
@@ -17,7 +17,7 @@ type exampleServer struct {
 }
 
 func startServer(rpcURL string, chainID int64) (*exampleServer, error) {
-	intent, err := charge.NewChargeIntent(charge.ChargeIntentConfig{RPCURL: rpcURL})
+	intent, err := charge.NewIntent(charge.IntentConfig{RPCURL: rpcURL})
 	if err != nil {
 		return nil, err
 	}
@@ -28,15 +28,15 @@ func startServer(rpcURL string, chainID int64) (*exampleServer, error) {
 		Recipient:      devnet.Recipient,
 		SupportedModes: []tempo.ChargeMode{tempo.ChargeModePush},
 	})
-	payment := mppserver.New(method, devnet.Realm, "example-secret")
+	payment := server.New(method, devnet.Realm, "example-secret")
 
-	handler := mppserver.ChargeMiddleware(payment, mppserver.ChargeParams{
+	handler := server.ChargeMiddleware(payment, server.ChargeParams{
 		Amount:         "0.50",
 		Description:    "Hash credential Tempo charge example",
 		SupportedModes: []tempo.ChargeMode{tempo.ChargeModePush},
 	})(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		_ = json.NewEncoder(w).Encode(map[string]any{
-			"tx": mppserver.ReceiptFromContext(r.Context()).Reference,
+			"tx": server.ReceiptFromContext(r.Context()).Reference,
 		})
 	}))