Skip to content
SMS SDK
Esc
↑↓navigate↵open⌘Jpreview
On this page

Contributing

Report issues, propose providers, and send pull requests to SMS SDK: setup, test commands, and the rules every change follows.

SMS SDK is MIT licensed and developed on GitHub. We take bug reports, provider corrections with evidence, docs fixes, and pull requests.

Report a problem

Open an issue with:

  • the SMS SDK version, and your runtime (Node.js or Bun) and its version
  • the provider and adapter options, without credentials
  • the error’s toJSON() output, which is already redacted
  • what you expected, with a link to the provider’s documentation when the behavior concerns a provider

A correction to provider behavior needs a source. Link the provider’s official documentation, or include a reproducible request and response with secrets and numbers removed.

Set up the repository

git clone https://github.com/opencoredev/sms-sdk.git
cd sms-sdk
bun install
cd packages/sms-sdk
bun run check-types   # source, tests, and examples
bun test              # unit, contract, webhook, CLI, examples, packaging
bun run build         # dist/ via tsc

Tests mock fetch and never contact a provider. test/integration/live.test.ts sends real messages only with LIVE_SMS_TESTS=true, a LIVE_SMS_TO listed in LIVE_SMS_ALLOWLIST, and provider credentials. Never enable it in CI for pull requests.

Rules for code changes

  • No runtime or peer dependencies. Use fetch, URL, URLSearchParams, AbortController, and Web Crypto.
  • An adapter file must not import another adapter, the webhook parsers, the testing helpers, or the CLI. The packaging test checks this on the built output.
  • No any. Parse provider responses as unknown and narrow them.
  • Never log or serialize credentials, message bodies, or full phone numbers.
  • Every provider fact needs an official source in PROVIDERS.md, with the date it was checked. If something cannot be confirmed, the adapter is partial and support.notes says why.

Add a provider

Follow Build a provider adapter, then the checklist in the repository’s CONTRIBUTING.md. It covers the adapter file and its providerOptions spec, error mapping, the subpath export, contract fixtures from the provider’s documented examples, the webhook parser and signed request builders, and entries in PROVIDERS.md, the README, and the doctor environment table.

Improve the docs

This site lives in apps/docs and is built with Blume. Pages are MDX files in apps/docs/docs, and each folder’s meta.ts sets the sidebar order.

cd apps/docs
bun run dev             # local preview
bun run check:snippets  # type-check every TypeScript snippet against the SDK source
bun run build

Every ts snippet must type-check against the SDK. Mark a block that cannot, such as code for another library, with ignore="reason" in its fence, as in ```ts ignore="Twilio SDK code". Snippets may import the stub modules ./db, ./sms, and ./notify from apps/docs/scripts/snippet-stubs.