> For the complete documentation index, see [llms.txt](https://docs.kangal.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kangal.dev/sdks/distribution.md).

# SDK distribution

Kangal builds the six official Admin API SDKs from the same immutable OpenAPI contract and version tag. The release workflow compiles or validates every language, creates package artifacts, signs release files with Sigstore, writes `SHA256SUMS.txt`, and publishes a GitHub Release.

## Release channels

| Language   | Package coordinate                | Primary channel                          | Registry automation                          |
| ---------- | --------------------------------- | ---------------------------------------- | -------------------------------------------- |
| TypeScript | `@kangal/sdk`                     | npm / signed GitHub Release              | npm Trusted Publishing                       |
| Python     | `kangal-api-sdk`                  | PyPI / signed GitHub Release             | PyPI Trusted Publisher                       |
| Go         | `github.com/latifv/kangal-sdk-go` | Go module mirror / signed GitHub Release | Source mirror and semantic tag required      |
| Java       | `dev.kangal:kangal-sdk`           | Maven Central / signed GitHub Release    | Central namespace and signing setup required |
| C#         | `Kangal.SDK`                      | NuGet / signed GitHub Release            | NuGet Trusted Publishing                     |
| PHP        | `kangal/sdk`                      | Packagist / signed GitHub Release        | Public Composer source mirror required       |

The package coordinate describes the official target. It does not prove that a particular version is already available in that external registry. Check the registry or the release page before adding a fixed version to a production build.

## Build a release locally

```bash
python scripts/build_official_sdks.py \
  --version 1.0.0 \
  --output dist/api-sdks
```

The command creates:

* `packages/` with registry-ready source for all six languages;
* `artifacts/` with deterministic SDK ZIPs;
* `release-manifest.json` with package coordinates, operation counts, and OpenAPI checksum.

The build refuses a non-semantic version or a non-empty output directory.

## Publish from GitHub Actions

Create and push an immutable tag:

```bash
git tag -a api-sdk-v1.0.0 -m "Kangal API SDKs v1.0.0"
git push origin api-sdk-v1.0.0
```

`.github/workflows/publish-api-sdks.yml` builds all languages and publishes the signed GitHub Release. External registry jobs stay disabled until their repository variable is set to `true`:

| Registry | Repository variable             | GitHub environment |
| -------- | ------------------------------- | ------------------ |
| npm      | `API_SDK_NPM_PUBLISH_ENABLED`   | `npm`              |
| PyPI     | `API_SDK_PYPI_PUBLISH_ENABLED`  | `pypi-api-sdk`     |
| NuGet    | `API_SDK_NUGET_PUBLISH_ENABLED` | `nuget`            |

Configure each trusted publisher for GitHub owner `latifv`, repository `kangal`, and workflow `publish-api-sdks.yml`. NuGet additionally requires the account username in repository secret `NUGET_USER`.

Registry setup references:

* [npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers/)
* [PyPI Trusted Publishers](https://docs.pypi.org/trusted-publishers/)
* [NuGet trusted publishing](https://learn.microsoft.com/en-us/nuget/nuget-org/trusted-publishing)

Go, Maven, and Composer publication needs a public source repository that owns the advertised module/package coordinate. The signed source artifact can be promoted to those mirrors without regenerating the SDK.

## Verify a downloaded release

```bash
sha256sum --check SHA256SUMS.txt
cosign verify-blob \
  --certificate-identity "https://github.com/latifv/kangal/.github/workflows/publish-api-sdks.yml@refs/tags/api-sdk-v1.0.0" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  --bundle kangal-api-sdk-1.0.0-python.zip.sigstore.json \
  kangal-api-sdk-1.0.0-python.zip
```

Also inspect `release-manifest.json`, the package-level `checksums.sha256`, and `sdk-manifest.json`. The version, target, OpenAPI checksum, and file inventory must match the release you selected.

## Versioning policy

* A tag is immutable and maps to one Admin OpenAPI snapshot.
* Breaking generated API or runtime changes require a major version.
* Additive operations and models use a minor version.
* Generator fixes that preserve the public method contract use a patch version.
* Plugin SDK versions are independent from Admin API SDK versions.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kangal.dev/sdks/distribution.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.