example added

Author: MarketDataDev03

.gitignore

@@ -25,6 +25,11 @@ Thumbs.db
 .env
 .env.local
 
+# Python (examples/mock-server)
+.venv/
+__pycache__/
+*.pyc
+
 # Logs / coverage
 *.log
 hs_err_pid*

CLAUDE.md

@@ -63,7 +63,7 @@ The Java SDK must also satisfy the canonical, cross-language [SDK Requirements](
 **Already wired in:**
 - §1.1 client object — `MarketDataClient` with two public constructors: a no-arg one for production (everything from the cascade) and a 4-arg `(apiKey, baseUrl, apiVersion, validateOnStartup)` for tests and short-lived runtimes. All fields `final` (immutable). Default base URL `https://api.marketdata.app`, default API version `v1`, single shared `HttpClient`, `User-Agent: marketdata-sdk-java/{version}` (version auto-detected from JAR manifest), `close()` for resource release, `getRateLimits()` accessor.
 - §4 configuration cascade — `Configuration.resolve(...)` does explicit → `MARKETDATA_*` env var → `.env` in CWD → default. Env var names live in `EnvVars` (package-private, in the SDK root package). `baseUrl` and `apiVersion` are normalized (trailing/leading slashes stripped) and validated (scheme http/https, host present, no query/fragment/user-info on `baseUrl`; `[A-Za-z0-9._-]+` on `apiVersion`) at resolution time, so misconfigured cascade inputs fail at construction with a clear message instead of producing malformed URLs later.
-- §5 demo mode + `validateOnStartup` parameter on the 4-arg constructor (defaults to `true` via the no-arg constructor); token redaction via `Tokens.redact` (matches the spec example `***…***YKT0`). `runStartupValidation` fires a single `GET /v1/user/` via `utilities.user(RetryPolicy.noRetry())`, skipping in demo mode; the no-retry policy keeps construction snappy on a slow/down API.
+- §5 demo mode + `validateOnStartup` parameter on the 4-arg constructor (defaults to `true` via the no-arg constructor); token redaction via `Tokens.redact` (matches the spec example `***…***YKT0`). `runStartupValidation` fires a single `GET /user/` (unversioned, like `/status/` and `/headers/`) via `utilities.validateAuth()` with `RetryPolicy.noRetry()`, skipping in demo mode; the no-retry policy keeps construction snappy on a slow/down API.
 - §6 sealed `MarketDataException` hierarchy with the 7 canonical subtypes and full support context (`requestId`, `requestUrl`, `statusCode`, `timestamp`, `exceptionType`) + `getSupportInfo()`.
 - §7 logging — `MarketDataLogging.configure(...)` installs `CanonicalLogFormatter` (the spec's `{timestamp} - {logger_name} - {level} - {message}` shape) on `com.marketdata.sdk` and applies the level from `MARKETDATA_LOGGING_LEVEL`. Detects consumer-pre-configured loggers (handler attached or level set) and backs off entirely so embedding the SDK doesn't clobber existing logging setups.
 - §8 rate-limit tracking — `RateLimitHeaders.parse` reads the four `x-api-ratelimit-*` headers per response (all-or-nothing: a partial header set returns null rather than emitting a snapshot with phantom zeros); `HttpTransport.latestRateLimits` keeps the latest snapshot, exposed via `client.getRateLimits()`. §10.3 preflight (`HttpTransport.checkRateLimitPreflight`) fails fast on `remaining=0`, but only while `now < reset` — once the reset window elapses the request goes through so the next response refreshes the snapshot.

Makefile

@@ -0,0 +1,92 @@
+# Convenience wrapper around ./gradlew and the consumer-test / mock-server.
+# Run `make` (no args) or `make help` for the target list.
+
+CONSUMER_DIR := examples/consumer-test
+MOCK_DIR     := examples/mock-server
+
+.DEFAULT_GOAL := help
+
+# ---------------------------------------------------------------------------
+# Help
+# ---------------------------------------------------------------------------
+
+.PHONY: help
+help: ## Show this help
+	@awk 'BEGIN {FS = ":.*##"; printf "Usage:\n  make \033[36m<target>\033[0m\n\nTargets:\n"} \
+	  /^# ===/ { in_section = 1; next } \
+	  /^[a-zA-Z_-]+:.*?##/ { printf "  \033[36m%-22s\033[0m %s\n", $$1, $$2 } \
+	  /^## ---/ { printf "\n\033[33m%s\033[0m\n", substr($$0, 5) }' $(MAKEFILE_LIST)
+	@echo ""
+	@echo "Typical workflow:"
+	@echo "  make publish              # publish SDK to mavenLocal"
+	@echo "  make mock-server          # in another terminal"
+	@echo "  make demo-config          # in a third terminal"
+
+# ---------------------------------------------------------------------------
+## --- SDK build ---
+# ---------------------------------------------------------------------------
+
+.PHONY: build
+build: ## Full build: unit tests + Spotless + JaCoCo (JDK 17)
+	./gradlew build
+
+.PHONY: test
+test: ## Unit tests only
+	./gradlew test
+
+.PHONY: spotless
+spotless: ## Apply code formatting
+	./gradlew spotlessApply
+
+.PHONY: clean
+clean: ## Clean all Gradle outputs (SDK + consumer-test)
+	./gradlew clean
+	cd $(CONSUMER_DIR) && ./gradlew clean
+
+.PHONY: publish
+publish: ## Publish SDK to ~/.m2 (prereq for any demo)
+	./gradlew publishToMavenLocal
+
+# ---------------------------------------------------------------------------
+## --- Mock server ---
+# ---------------------------------------------------------------------------
+
+.PHONY: mock-server
+mock-server: ## Start the FastAPI mock server (blocks, Ctrl+C to stop)
+	cd $(MOCK_DIR) && ./run.sh
+
+# ---------------------------------------------------------------------------
+## --- Consumer demos (need `make publish` first) ---
+# ---------------------------------------------------------------------------
+
+.PHONY: demo-quickstart
+demo-quickstart: ## Idiomatic per-resource usage tour (live API; grows as resources land)
+	cd $(CONSUMER_DIR) && ./gradlew runQuickstart
+
+.PHONY: demo-live
+demo-live: ## Live API smoke (needs MARKETDATA_TOKEN in examples/consumer-test/.env)
+	cd $(CONSUMER_DIR) && ./gradlew runLive
+
+.PHONY: demo-config
+demo-config: ## Demo mode, cascade, validation (needs mock-server)
+	cd $(CONSUMER_DIR) && ./gradlew runDemoConfig
+
+.PHONY: demo-exceptions
+demo-exceptions: ## Every MarketDataException subtype (needs mock-server)
+	cd $(CONSUMER_DIR) && ./gradlew runExceptions
+
+.PHONY: demo-retry
+demo-retry: ## Retry, Retry-After, preflight (needs mock-server)
+	cd $(CONSUMER_DIR) && ./gradlew runRetry
+
+.PHONY: demo-response
+demo-response: ## Response<T> surface features (needs mock-server)
+	cd $(CONSUMER_DIR) && ./gradlew runResponse
+
+.PHONY: demo-concurrency
+demo-concurrency: ## 50-permit semaphore (needs mock-server)
+	cd $(CONSUMER_DIR) && ./gradlew runConcurrency
+
+.PHONY: demos-all
+demos-all: ## Run every mock-server-based demo back-to-back (needs mock-server)
+	cd $(CONSUMER_DIR) && ./gradlew runDemoConfig runExceptions runRetry runResponse runConcurrency