diff --git a/.cursor/rules/README.md b/.cursor/rules/README.md new file mode 100644 index 0000000..d8f3545 --- /dev/null +++ b/.cursor/rules/README.md @@ -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. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..5cf714e --- /dev/null +++ b/AGENTS.md @@ -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. diff --git a/LICENSE b/LICENSE index d78b6bc..c2a603d 100644 --- a/LICENSE +++ b/LICENSE @@ -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 diff --git a/pom.xml b/pom.xml index f0cd851..5d56daa 100644 --- a/pom.xml +++ b/pom.xml @@ -20,10 +20,10 @@ 3.4.1 5.2.2 3.1.6 - 2.10.0 - 2.10.0 - 4.12.0 - 3.4.0 + 3.0.0 + 3.0.0 + 5.1.0 + 3.9.1 4.10.0 0.8.7 1.18.36 @@ -125,6 +125,12 @@ okhttp ${okhttp.version} + + + com.squareup.okhttp3 + okhttp-jvm + ${okhttp.version} + com.squareup.okio okio @@ -169,7 +175,7 @@ org.jetbrains.kotlin kotlin-stdlib - 2.1.0 + 2.2.0 @@ -225,6 +231,7 @@ org.apache.maven.plugins maven-javadoc-plugin + ${maven-javadoc-plugin.version} 8 diff --git a/skills/README.md b/skills/README.md new file mode 100644 index 0000000..5cc89ff --- /dev/null +++ b/skills/README.md @@ -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`). diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md new file mode 100644 index 0000000..aac551b --- /dev/null +++ b/skills/code-review/SKILL.md @@ -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) diff --git a/skills/contentstack-marketplace-sdk/SKILL.md b/skills/contentstack-marketplace-sdk/SKILL.md new file mode 100644 index 0000000..ae8c717 --- /dev/null +++ b/skills/contentstack-marketplace-sdk/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` diff --git a/skills/dev-workflow/SKILL.md b/skills/dev-workflow/SKILL.md new file mode 100644 index 0000000..861c7c7 --- /dev/null +++ b/skills/dev-workflow/SKILL.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` ``). +- 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) diff --git a/skills/framework-and-http/SKILL.md b/skills/framework-and-http/SKILL.md new file mode 100644 index 0000000..1e4906e --- /dev/null +++ b/skills/framework-and-http/SKILL.md @@ -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/) diff --git a/skills/java/SKILL.md b/skills/java/SKILL.md new file mode 100644 index 0000000..1c80c3a --- /dev/null +++ b/skills/java/SKILL.md @@ -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 diff --git a/skills/testing/SKILL.md b/skills/testing/SKILL.md new file mode 100644 index 0000000..aa79275 --- /dev/null +++ b/skills/testing/SKILL.md @@ -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/)