Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.sdk.anghami.com/llms.txt

Use this file to discover all available pages before exploring further.

The SDK is proto-first: nothing in the public surface is hand-written. Every client, doc, and HTTP handler is generated from a single set of .proto files using buf v2 and sebuf.

​
Repository layout

​
Source of truth (edited by hand)

sdk/shared/v1/        # Pagination, errors, identifiers, content types, media, rate limit
sdk/auth/v1/          # OAuth — exchange, refresh, revoke
sdk/developer/v1/     # API key management
sdk/catalog/v1/       # MusicCatalogService — songs, albums, artists, lyrics
sdk/video/v1/         # VideoCatalogService — shows, seasons, episodes, movies
sdk/playlist/v1/      # PlaylistService
sdk/library/v1/       # LibraryService — liked, saved, followed, history
sdk/search/v1/        # DiscoveryService — search + browse
sdk/streaming/v1/     # StreamingService — stream acquisition (billable)
sdk/soundtrack/v1/    # SoundtrackService — cross-content linking
sdk/user/v1/          # UserService — current user profile
buf.yaml              # Lint + breaking rules (STANDARD + COMMENTS)
buf.gen.yaml          # Generation pipeline (Go, TS, Swift, Java, Python, OpenAPI)

​
Generated (never edited, but committed)

api/sdk/              # Go protobuf types + sebuf HTTP handlers
web/sdk/              # TypeScript interfaces (consumed via @anghami/sdk)
swift/Generated/      # Swift protobuf types (SPM target: AnghamiSDK)
java/generated/       # Java protobuf lite classes
python/sdk/           # Python protobuf modules + mypy stubs
docs/api/             # Bundled OpenAPI 3.1 (YAML + JSON)
Generated code is committed so consumers can depend on the repo directly without running the toolchain.

​
Build pipeline

make generate runs buf generate, which fans out to nine plugins:
#PluginOutput
1protoc-gen-goGo types
2protoc-gen-go-http (sebuf)Go HTTP handlers
3protoc-gen-openapiv3 (yaml, bundled)docs/api/anghami-sdk.openapi.yaml
4protoc-gen-openapiv3 (json, bundled)docs/api/anghami-sdk.openapi.json
5protoc-gen-swiftSwift types
6protoc-gen-ts_protoTypeScript interfaces
7protoc (java, lite)Java classes
8protoc (python)Python modules
9protoc-gen-mypyPython type stubs
Post-processing scripts inject HTTP path metadata into the TypeScript interfaces, strip @Generated annotations from Java, and emit __init__.py files for Python packages.

​
HTTP shape

Every RPC compiles into a stable path defined in the proto via sebuf.http. Reads are GET, mutations and batch operations are POST: 
service MusicCatalogService {
  option (sebuf.http.service_config) = { base_path: "/v1/music" };

  // GET /v1/music/songs/{id}
  rpc GetSong(GetSongRequest) returns (GetSongResponse) {
    option (sebuf.http.config) = { path: "/songs/{id}" method: HTTP_METHOD_GET };
  }

  // POST /v1/music/songs:batchGet
  rpc BatchGetSongs(BatchGetSongsRequest) returns (BatchGetSongsResponse) {
    option (sebuf.http.config) = { path: "/songs:batchGet" method: HTTP_METHOD_POST };
  }
}
The convention follows AIP-style: single-resource reads are GET with path parameters; multi-resource batch reads use POST with :batchGet suffix and a typed body. The full path/method mapping for every operation is in the API Reference.

​
Versioning

  • Proto packages are versioned — every package is sdk.{service}.v1. Breaking changes ship as v2 packages alongside v1 until consumers migrate.
  • make breaking runs against main — any breaking change to v1 fails CI.
  • Generated code follows proto versioning — TS/Go/Swift packages export typed namespaces matching the proto packages.
See Versioning for the deprecation policy.

​
Why proto-first

  • One source, many surfaces. OpenAPI, REST clients, and HTTP handlers stay in lock-step — they’re all derivatives of the same .proto.
  • Strict contracts. Validation rules (buf.validate) live in the proto and apply identically on every client and server.
  • Documentation by construction. Every field/message/RPC has a leading comment (enforced by buf lint COMMENTS), so the OpenAPI you import already has descriptions on every operation.