contentstack · reeshika-h · Apr 7, 2026 · Apr 7, 2026 · Apr 7, 2026 · Apr 7, 2026
@@ -0,0 +1,5 @@
+# Cursor (optional)
+
+*Cursor* users: start at *[AGENTS.md](../../AGENTS.md)*. All conventions live in **skills/*/SKILL.md**.
+
+This folder only points contributors to *AGENTS.md* so editor-specific config does not duplicate the canonical docs.
@@ -0,0 +1,48 @@
+# Contentstack Marketplace Java SDK – Agent guide
+
+*Universal entry point* for contributors and AI agents. Detailed conventions live in **skills/*/SKILL.md**.
+
+## What this repo is
+
+| Field | Detail |
+| --- | --- |
+| *Name:* | [contentstack/contentstack-marketplace-java](https://github.com/contentstack/contentstack-marketplace-java) |
+| *Purpose:* | Java SDK for the Contentstack Marketplace API: apps, authorizations, installations, and related resources (Retrofit-based HTTP client). |
+| *Out of scope (if any):* | Not a general Contentstack Delivery or Management SDK; Marketplace API only. No Kotlin-first API surface (Kotlin stdlib is a transitive dependency). |
+
+## Tech stack (at a glance)
+
+| Area | Details |
+| --- | --- |
+| Language | Java 8 (compiler `source`/`target` in `pom.xml`; CI uses JDK 11). Lombok for generated code. |
+| Build | Maven — `pom.xml`; artifact `com.contentstack.sdk:marketplace`. |
+| Tests | JUnit 5 (and Vintage for legacy tests) — `src/test/java/**`. |
+| Lint / coverage | Compiler warnings (`-Xlint` in `maven-compiler-plugin`); JaCoCo (`target/site/jacoco/index.html` after tests). Optional JetBrains Qodana JVM — `qodana.yaml`. |
+| Other | HTTP: Retrofit 2, OkHttp, Gson. `README.md` for end-user install and usage. |
+
+## Commands (quick reference)
+
+| Command Type | Command |
+| --- | --- |
+| Build | `mvn -B package --file pom.xml` |
+| Test | `mvn test` |
+| Lint | No separate CLI lint target; use compiler warnings during `mvn compile` / `mvn package`, JaCoCo report after `mvn test`, or Qodana locally/CI per `qodana.yaml`. |
+
+CI: GitHub Actions — `.github/workflows/maven.yml` (`mvn -B package --file pom.xml` on push/PR to `main`).
+
+## Where the documentation lives: skills
+
+| Skill | Path | What it covers |
+| --- | --- | --- |
+| Dev workflow | [skills/dev-workflow/SKILL.md](skills/dev-workflow/SKILL.md) | Branches, CI, build/test, release notes |
+| Marketplace SDK API | [skills/contentstack-marketplace-sdk/SKILL.md](skills/contentstack-marketplace-sdk/SKILL.md) | Public API, `Marketplace` builder, domains (apps, auths, installations) |
+| Java layout & conventions | [skills/java/SKILL.md](skills/java/SKILL.md) | Package layout, Java/Lombok usage in this repo |
+| Testing | [skills/testing/SKILL.md](skills/testing/SKILL.md) | Test layout, `TestClient`, env / credentials |
+| Code review | [skills/code-review/SKILL.md](skills/code-review/SKILL.md) | PR checklist for this SDK |
+| Framework & HTTP | [skills/framework-and-http/SKILL.md](skills/framework-and-http/SKILL.md) | Retrofit `Client`, Gson, base URLs, extension points |
+
+An index with "when to use" hints is in [skills/README.md](skills/README.md).
+
+## Using Cursor (optional)
+
+If you use *Cursor*, [.cursor/rules/README.md](.cursor/rules/README.md) only points to *AGENTS.md*—same docs as everyone else.
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2012 - 2025 Contentstack
+Copyright (c) 2012 - 2026 Contentstack
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

@@ -20,10 +20,10 @@
         <maven-javadoc-plugin.version>3.4.1</maven-javadoc-plugin.version>
         <dotenv-source.version>5.2.2</dotenv-source.version>
         <rxjava-source.version>3.1.6</rxjava-source.version>
-        <retrofit-source.version>2.10.0</retrofit-source.version>
-        <converter-gson-version>2.10.0</converter-gson-version>
-        <okhttp.version>4.12.0</okhttp.version>
-        <okio.version>3.4.0</okio.version>
+        <retrofit-source.version>3.0.0</retrofit-source.version>
+        <converter-gson-version>3.0.0</converter-gson-version>
+        <okhttp.version>5.1.0</okhttp.version>
+        <okio.version>3.9.1</okio.version>
         <logging.version>4.10.0</logging.version>
         <jococo-plugin.version>0.8.7</jococo-plugin.version>
         <lombok-source.version>1.18.36</lombok-source.version>
@@ -125,6 +125,12 @@
             <artifactId>okhttp</artifactId>
             <version>${okhttp.version}</version>
         </dependency>
+        <!-- OkHttp 5+: the okhttp artifact is a stub on Maven; JVM classes ship in okhttp-jvm -->
+        <dependency>
+            <groupId>com.squareup.okhttp3</groupId>
+            <artifactId>okhttp-jvm</artifactId>
+            <version>${okhttp.version}</version>
+        </dependency>
         <dependency>
             <groupId>com.squareup.okio</groupId>
             <artifactId>okio</artifactId>
@@ -169,7 +175,7 @@
        <dependency>
             <groupId>org.jetbrains.kotlin</groupId>
             <artifactId>kotlin-stdlib</artifactId>
-            <version>2.1.0</version>
+            <version>2.2.0</version>
         </dependency>
     </dependencies>
 
@@ -225,6 +231,7 @@
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-javadoc-plugin</artifactId>
+                <version>${maven-javadoc-plugin.version}</version>
                 <configuration>
                     <source>8</source>
                 </configuration>

@@ -0,0 +1,16 @@
+# Skills – Contentstack Marketplace Java SDK
+
+Source of truth for detailed guidance. Read [AGENTS.md](../AGENTS.md) first, then open the skill that matches your task.
+
+## When to use which skill
+
+| Skill folder | Use when |
+| --- | --- |
+| [dev-workflow](dev-workflow/) | Branching, CI, local build/test commands, releases |
+| [contentstack-marketplace-sdk](contentstack-marketplace-sdk/) | `Marketplace` API surface, apps/auths/installations, versioning |
+| [java](java/) | Package structure, Java 8/Lombok patterns in this codebase |
+| [testing](testing/) | Writing or running tests, fixtures, `.env` / secrets |
+| [code-review](code-review/) | Reviewing or preparing PRs for this repository |
+| [framework-and-http](framework-and-http/) | Retrofit, OkHttp, Gson, `Client` and HTTP boundaries |
+
+Each folder contains `SKILL.md` with YAML frontmatter (`name`, `description`).
@@ -0,0 +1,42 @@
+---
+name: code-review
+description: Use when reviewing pull requests or preparing changes for review in this SDK repository.
+---
+
+# Code review – Contentstack Marketplace Java SDK
+
+## When to use
+
+- Reviewing a PR for correctness, API safety, and consistency
+- Self-review before requesting reviewers
+
+## Instructions
+
+### Blocker
+
+- Breaking changes to public **`Marketplace`** or domain types without version/changelog strategy and maintainer agreement.
+- Committed secrets, real org tokens, or `.env` files with live credentials.
+- New HTTP clients that bypass **`com.contentstack.sdk.Client`** without rationale (duplicated base URLs, converters).
+
+### Major
+
+- Missing or misleading Javadoc on new public methods/classes.
+- Tests absent for non-trivial new behavior (happy path at minimum).
+- Null/empty handling inconsistent with existing `Builder` and service patterns.
+- Compiler warnings introduced without justification.
+
+### Minor
+
+- Naming or package placement inconsistent with `com.contentstack.sdk.marketplace` structure.
+- Typos in user-facing Javadoc or `README.md` when behavior changes.
+
+### Quick checklist
+
+- [ ] `mvn -B package` succeeds locally.
+- [ ] Public API changes reflected in `README.md` or Javadoc where users look first.
+- [ ] Tests updated; integration tests respect env-based credentials ([../testing/SKILL.md](../testing/SKILL.md)).
+
+## References
+
+- [../contentstack-marketplace-sdk/SKILL.md](../contentstack-marketplace-sdk/SKILL.md)
+- [../testing/SKILL.md](../testing/SKILL.md)
@@ -0,0 +1,42 @@
+---
+name: contentstack-marketplace-sdk
+description: Use when changing or documenting the public Marketplace SDK API, entry points, or domain modules.
+---
+
+# Marketplace SDK API – Contentstack Marketplace Java SDK
+
+## When to use
+
+- Adding or changing `com.contentstack.sdk.marketplace.*` public types
+- Documenting how consumers construct `Marketplace` and access apps, auths, installations, requests
+- Deciding what belongs in this library vs. other Contentstack Java SDKs
+
+## Instructions
+
+### Entry point
+
+- **`com.contentstack.sdk.marketplace.Marketplace`** — constructed via **`Marketplace.Builder`**, which requires a non-null, non-empty organization UID (`Constants.ERROR_NO_ORGANIZATION_UID` on violation).
+- Optional builder knobs: `host`, `region` (`com.contentstack.sdk.Region`), `authtoken`, and login-related methods where implemented.
+- Host resolution: if `region` is set, the client prefixes the region to the host segment (see `Marketplace` constructor); empty host falls back to `Constants.DEFAULT_HOST`.
+
+### Domain surfaces (high level)
+
+- **`App`** / `AppService` — marketplace apps (including hosting, OAuth subpackages).
+- **`Auth`** — authorizations.
+- **`Installation`** — installations (including `location`, `webhook` subpackages).
+- **`AppRequest`** — app request flows via `RequestService`.
+
+### Integration boundaries
+
+- Shared HTTP/Retrofit wiring lives in **`com.contentstack.sdk.Client`**; do not duplicate base URL or converter setup on each feature without a design reason.
+- JSON: Gson via Retrofit; `org.json.simple` appears where legacy JSON types are needed — keep new code consistent with existing patterns in the same module.
+
+### Versioning
+
+- Library version is the Maven **`artifactId` `marketplace`** version in `pom.xml`; align changelog and consumer docs (`README.md`) when bumping.
+
+## References
+
+- [../framework-and-http/SKILL.md](../framework-and-http/SKILL.md) — Retrofit client and HTTP stack
+- [../java/SKILL.md](../java/SKILL.md) — packages and Lombok
+- End-user overview: repository root `README.md`
@@ -0,0 +1,39 @@
+---
+name: dev-workflow
+description: Use when branching, running CI locally, building, testing, or releasing this Maven project.
+---
+
+# Dev workflow – Contentstack Marketplace Java SDK
+
+## When to use
+
+- Setting up the repo locally or onboarding
+- Matching what CI runs before opening a PR
+- Cutting releases or understanding deploy steps in `pom.xml`
+
+## Instructions
+
+### Repository and default branch
+
+- Remote: `https://github.com/contentstack/contentstack-marketplace-java` (see `pom.xml` `<scm>`).
+- CI in `.github/workflows/maven.yml` runs on pushes and pull requests targeting `main`: checkout, JDK 11 (Temurin), `mvn -B package --file pom.xml`.
+
+### Local commands
+
+- Full package (compile, test, package): `mvn -B package --file pom.xml` — aligns with CI.
+- Tests only: `mvn test`.
+- Coverage HTML after tests: `target/site/jacoco/index.html` (JaCoCo is bound to the `test` phase).
+
+### Maven release / publishing
+
+- `pom.xml` documents release flow (e.g. `mvn clean deploy`, Central Publishing plugin, GPG signing in `verify`). Coordinate with maintainers before changing version or release profiles.
+
+### PR expectations
+
+- Ensure `mvn -B package` passes; note that Surefire may be configured with `testFailureIgnore` — still fix failing tests before merging when possible.
+
+## References
+
+- [../testing/SKILL.md](../testing/SKILL.md) — test env and credentials
+- [../java/SKILL.md](../java/SKILL.md) — compiler and layout
+- Official: [Maven](https://maven.apache.org/guides/), [GitHub Actions Java + Maven](https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-java-with-maven)
@@ -0,0 +1,36 @@
+---
+name: framework-and-http
+description: Use when changing Retrofit/OkHttp setup, Gson serialization, or HTTP behavior for the Marketplace client.
+---
+
+# Framework and HTTP – Contentstack Marketplace Java SDK
+
+## When to use
+
+- Editing **`com.contentstack.sdk.Client`** or how `Marketplace` obtains **`Retrofit`**
+- Adding interceptors, converters, or base URL behavior
+- Debugging API calls built with **Retrofit** + **Gson**
+
+## Instructions
+
+### Retrofit singleton
+
+- **`Client.getInstance(String host)`** lazily creates one **`Retrofit`** per JVM: the **first** `host` wins; later calls pass the parameter but do not recreate the client. Multiple `Marketplace` instances with different hosts in one process can mis-route requests unless this is addressed in `Client`.
+
+### Base URL and transport
+
+- **`createRetrofitInstance`** builds **`https://{host}/`** and attaches **`GsonConverterFactory.create()`** — new endpoints should use Retrofit interfaces consistent with existing `*Service` classes under `marketplace`.
+- **OkHttp** is a direct dependency (version in `pom.xml`) — configure timeouts, interceptors, or auth headers in one place when extending the stack.
+
+### JSON
+
+- Gson is the Retrofit converter; **`org.json.simple`** is used where historical code requires it — follow the dominant pattern in the package you touch.
+
+### Errors and responses
+
+- Services typically use **`retrofit2.Call`** / **`Response`** — preserve existing error-handling conventions when adding calls (see `Marketplace` and service classes for patterns).
+
+## References
+
+- [../contentstack-marketplace-sdk/SKILL.md](../contentstack-marketplace-sdk/SKILL.md) — domain entry points
+- [Retrofit](https://square.github.io/retrofit/), [OkHttp](https://square.github.io/okhttp/)
@@ -0,0 +1,36 @@
+---
+name: java
+description: Use when navigating Java package layout, compiler settings, or Lombok usage in this repository.
+---
+
+# Java layout and conventions – Contentstack Marketplace Java SDK
+
+## When to use
+
+- Adding new classes under `src/main/java`
+- Aligning with Java 8 language level and Maven compiler settings
+- Using Lombok consistently with existing types
+
+## Instructions
+
+### Layout
+
+- Root packages: **`com.contentstack.sdk`** (`Region`, `Client`, `BaseImplementation`) and **`com.contentstack.sdk.marketplace`** (Marketplace API and subpackages: `apps`, `auths`, `installations`, `login`, `request`).
+- Tests mirror main packages under `src/test/java/com/contentstack/sdk/...`.
+- `package-info.java` exists in several packages for Javadoc cohesion — add or update when expanding a package’s public story.
+
+### Compiler and language level
+
+- **`maven-compiler-plugin`** sets `source`/`target` **8** with Lombok on the annotation processor path; `-Xlint` style args are configured — fix new warnings when practical.
+- `pom.xml` also declares `maven.compiler.source/target` properties (9) while the plugin overrides to 8 — treat **the plugin’s Java 8** as authoritative for emitted bytecode unless maintainers unify properties.
+
+### Lombok and dependencies
+
+- **Lombok** is `provided` — use for DTOs/services only where the rest of the module already does; avoid mixing styles in one feature area.
+- **JetBrains annotations** (`@NotNull`, etc.) appear on public APIs — keep null contracts explicit for new parameters.
+
+## References
+
+- [../contentstack-marketplace-sdk/SKILL.md](../contentstack-marketplace-sdk/SKILL.md) — public API map
+- [../testing/SKILL.md](../testing/SKILL.md) — test code layout
+- [../dev-workflow/SKILL.md](../dev-workflow/SKILL.md) — `mvn` commands
@@ -0,0 +1,37 @@
+---
+name: testing
+description: Use when writing or running tests, configuring TestClient, or handling secrets and coverage.
+---
+
+# Testing – Contentstack Marketplace Java SDK
+
+## When to use
+
+- Adding unit or integration-style tests under `src/test/java`
+- Using **`TestClient`** helpers and environment variables
+- Interpreting Surefire / JaCoCo output
+
+## Instructions
+
+### Layout and naming
+
+- Tests live under **`src/test/java`**, mirroring `com.contentstack.sdk.marketplace.*` (e.g. `MarketplaceTest`, `AppUnitTests`, region-specific suites).
+- JUnit **Jupiter** is the primary stack; **Vintage** is on the classpath for older tests — prefer Jupiter for new classes.
+
+### TestClient and credentials
+
+- **`com.contentstack.sdk.TestClient`** loads **`io.github.cdimascio.dotenv.Dotenv`** and reads optional env vars: `organizationUid`, `authToken`, `userId`, with placeholder defaults when unset.
+- For real API runs, supply a `.env` file or environment variables locally; **never commit secrets** — keep tokens out of git and PR descriptions.
+- Helpers like `getMarketplace()`, `getMarketplaceEU()`, etc., centralize host `api.contentstack.io` and region variants.
+
+### Running tests and coverage
+
+- Run: **`mvn test`** (see [../dev-workflow/SKILL.md](../dev-workflow/SKILL.md)).
+- **`pom.xml`** configures Surefire with **`testFailureIgnore` true** — CI still runs `package`; treat red tests as something to fix before merge when possible.
+- JaCoCo report: **`target/site/jacoco/index.html`** after `mvn test`.
+
+## References
+
+- [../dev-workflow/SKILL.md](../dev-workflow/SKILL.md) — CI parity
+- [../contentstack-marketplace-sdk/SKILL.md](../contentstack-marketplace-sdk/SKILL.md) — API under test
+- [JUnit 5 User Guide](https://junit.org/junit5/docs/current/user-guide/)