Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
79 lines (56 loc) · 3.87 KB

CONTRIBUTING.md

File metadata and controls

79 lines (56 loc) · 3.87 KB
Raw

Contributing

Thanks for helping build Caspian's open core.

Ways to contribute

New here? Good places to start:

  • Good first issues - browse the good first issue label.
  • Examples - add or improve a runnable agent in examples/; small, self-contained, well-documented.
  • Docs fixes - typos, unclear steps, missing prerequisites. Small doc PRs are very welcome.
  • New language SDKs - port the client to Go, Ruby, Rust, etc. (see sdks/ for the Python and TypeScript references).
  • Channel adapters - add support for a new platform (see "Adding a new channel adapter" below).

Fork & pull request

You don't have push access to this repo, so contribute through a fork:

  1. Fork this repo (top-right on GitHub), then clone your fork: 
    git clone https://github.com/<your-username>/caspian-sdk.git
cd caspian-sdk
git remote add upstream https://github.com/TryCaspian/caspian-sdk.git
  2. Create a branch: git checkout -b my-change.
  3. Make your change and keep tests + lint green (see below).
  4. Push to your fork and open a pull request against TryCaspian/caspian-sdk:main.

Setup

This is a small monorepo: a Python side (uv) and a TypeScript SDK (bun).

Python (SDK, adapters, CLI):

uv sync
uv run pytest        # everything should be green before you start
uv run ruff check .

TypeScript SDK (packages/typescript):

cd packages/typescript
bun install
bun run ci           # tsc + eslint + dependency-cruiser + bun test

What lives where

  • server/src/comm_gateway/providers — channel adapters. Each adapter implements the small provider interface in providers/base.py: provision / send / reply / parse_webhook (+ optional typing, OAuth hooks), a capabilities set, and webhook signature verification.
  • sdks/python / python/ — the Python client (rewrite lives under python/ when present).
  • packages/typescript — the TypeScript client (bun). src/core must stay free of I/O.
  • apps/cli — the caspian CLI. It ships as a separate package caspian-cli (pip install caspian-cli, or run without installing via uvx caspian-cli), while caspian-sdk is the library. comm is a legacy alias only.

Adding a new channel adapter

  1. Implement the provider interface in a new module under server/src/comm_gateway/providers/.
  2. Register it in registry.py (or ship it as your own package via the caspian.providers entry-point group — no fork needed).
  3. Add an in-memory fake that consumes the platform's real inbound payload shape, so integrations can be tested offline.
  4. Add tests: payload normalization, webhook signature verification (accept + reject), and any routing rules.
  5. Use only the platform's official API. Adapters that automate private/unofficial protocols, evade platform enforcement, or enable bulk unsolicited messaging will not be accepted.

Ground rules

  • Python: uv run pytest and uv run ruff check . must pass.
  • TypeScript: in packages/typescript, bun run ci must pass.
  • No secrets in code, tests, or fixtures — use obviously-fake placeholder values.
  • Webhook verification is not optional: if the platform signs its webhooks, the adapter must verify the signature and reject mismatches.
  • Commit messages: concise imperative subject ("add reminder example", not "added"/"adds"), no emojis, and reference the issue number when there is one (e.g. fix email triage classifier (#42)).

Questions / community

Reporting security issues

See SECURITY.md — please don't open public issues for vulnerabilities.