Skip to content

AGENTS.md

Latest commit

 

History

History
46 lines (35 loc) · 3.66 KB

AGENTS.md

File metadata and controls

46 lines (35 loc) · 3.66 KB
Raw

Didit Java / Kotlin SDK (sdk-java)

The official Didit server-side library for Java / Kotlin: me.didit:didit-java on Maven Central. Status: released (1.0.0 on 2026-10-29). Merging the release-please pull request publishes the next version.

Read first

  • docs/DESIGN.md is the shared contract of all seven Didit server SDKs (sdk-python, sdk-node, sdk-go, sdk-java, sdk-php, sdk-ruby, sdk-dotnet). It is binding: when this code and the design disagree, the code is wrong.
  • openapi/ holds the API contract this SDK is generated from (see DESIGN.md section 3).

Toolchain

Gradle with the Kotlin DSL and the wrapper committed, JUnit 5, errorprone, Spotless, Java 11 bytecode.

Rules

  • Generated code is never edited by hand. Change the generator in codegen/ or openapi/overlay.json, then regenerate; CI fails when the committed generated code is stale.
  • openapi/verification.json, openapi/account.json and openapi/webhook-vectors.json are upstream copies; never edit them by hand. Only the spec sync workflow updates them.
  • Keep the SDKs in sync (HARD RULE). Any public API change in service-didit-verification or service-didit-auth must reach the OpenAPI documents in mintlify-docs, and from there every server SDK through the spec sync pull request. A change to hand-written core behaviour that DESIGN.md describes (client options, errors, retries, pagination, webhooks, Authentication) is made in all seven SDK repositories, one pull request each, and DESIGN.md is updated in all seven in the same words.
  • Feature parity across languages: a capability shipped in one server SDK ships in the other six.
  • Releases publish straight from this repository (Alex, 2026-10-29): merging the release-please pull request is the release approval, and the release workflow then creates the vX.Y.Z tag and publishes to the registry. Never push a release tag, create a release or publish by hand outside that flow, and never store a registry token where trusted publishing works.
  • Unit tests never touch the network. Live smoke tests run only when DIDIT_SANDBOX_API_KEY is set.
  • Never commit secrets, API keys or real customer data. Fixtures are synthetic.
  • CHANGELOG.md is generated by release-please from conventional commits; never edit it by hand.
  • Public API changes need tests, README updates and a conventional commit type that matches their semver impact.

Commands

Task Command
Install Nothing to install beyond JDK 21 and Python 3.10+; ./gradlew downloads Gradle and the dependencies
Generate python3 codegen/generate.py (check: python3 codegen/generate.py --check)
Generator tests python3 -m unittest discover -s codegen/tests -t codegen
Test ./gradlew test (another JDK: -PtestJavaVersion=11; live sandbox: DIDIT_SANDBOX_API_KEY=... ./gradlew liveTest)
Lint ./gradlew spotlessCheck (fix: ./gradlew spotlessApply)
Type-check ./gradlew compileJava compileTestJava (javac -Werror, errorprone, NullAway with JSpecify)
Build ./gradlew build (everything above plus Javadoc, coverage gate and the examples)
Examples ./gradlew :examples:build, ./gradlew :examples:quickstartDemo
Spec sync python3 codegen/spec_sync.py --summary /tmp/summary.md

Layout

  • codegen/: the generator (Python, standard library only) and spec_sync.py; it reads only openapi/.
  • Generated: src/main/java/me/didit/resources, src/main/java/me/didit/types, src/test/java/me/didit/resources.
  • Hand-written core: src/main/java/me/didit/Didit.java and the packages core, errors, webhooks, authentication.
  • examples/: runnable examples, framework webhook receivers and the Kotlin API tests.