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 open to external contributions in the form of issues, proposals, and pull requests against the proto definitions. Generated code is not edited by hand — every change starts in a .proto file.

​
Workflow

  1. Fork github.com/anghami/sdk.
  2. Edit .proto files under sdk/. Never edit api/, web/, swift/Generated/, java/generated/, python/sdk/, or docs/api/.
  3. make generate to regenerate every language and the OpenAPI bundle.
  4. make check to run lint + breaking + generate. Must pass.
  5. Commit both proto and generated changes in the same commit.
  6. Open a PR. CI runs the same make ci pipeline.

​
Proto conventions

These are enforced by buf lint (STANDARD + COMMENTS). See CLAUDE.md in the repo for the full list, but the highlights:
  • Every message, field, enum, enum value, service, and RPC has a leading comment. The COMMENTS lint rule will fail your PR otherwise.
  • Enum zero values use _UNSPECIFIED suffix (CONTENT_TYPE_UNSPECIFIED = 0).
  • Service names end in Service (MusicCatalogService, not MusicCatalog).
  • IDs are typed messages, never raw int64 or string.
  • Pagination is always cursor-based via sdk.shared.v1.PaginationRequest / PaginationResponse.
  • No cross-service imports. A service may import from sdk.shared.v1 but never from another service’s package.
  • One file per request/response pair. service.proto only contains the service definition.
  • Validation rules use buf.validate field annotations.

​
Breaking changes

make breaking runs buf breaking --against main and fails the PR on any breaking change to a v1 package. If you genuinely need a breaking change:
  1. Introduce a v2 package alongside v1.
  2. Mark v1 operations as deprecated in proto comments.
  3. Plan a deprecation window before removing v1.
See Versioning.

​
Where to file what

  • Bug in generated code → file a proto-level issue describing the broken behavior; we’ll fix the proto and regenerate.
  • Incorrect documentation → PR against the matching .mdx under docs/. MDX edits don’t require regeneration.
  • New service or operation → start with an issue describing the use case before opening a proto PR — we want to discuss shape first.
  • Generator improvements → those go to sebuf, not this repo.

​
What’s out of scope

  • Direct edits to generated files. They will be reverted on the next make generate.
  • Adding live-channel or social-graph operations. See Overview for what’s in scope.