---
title: "Contributing and support"
description: "Where to ask questions about SMS SDK, how to report bugs and security issues, how to set up the repository and run the tests, and how to propose a new provider."
---

SMS SDK is MIT licensed and maintained on [GitHub](https://github.com/opencoredev/sms-sdk). There is no paid support plan. Bug reports, provider corrections with evidence, docs fixes, and pull requests are welcome.

## Where to ask

| You have | Go to |
| --- | --- |
| A bug, or behavior that contradicts these docs | [GitHub issues](https://github.com/opencoredev/sms-sdk/issues) |
| A question about using SMS SDK | A GitHub issue with the `question` label |
| A provider fact that looks wrong | An issue with a link to the provider's official documentation |
| A docs mistake | An issue, or a pull request against `apps/docs` |
| A sender, delivery, account, or billing problem | Your SMS provider's support (see below) |

Before you ask, run the [doctor CLI](/reference/doctor-cli). A dry run catches many configuration problems without any network calls:

```bash
npx @opencoredev/sms-sdk doctor --adapter telnyx --to +14155550123
```

## Report a bug

Include:

- 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 redacted and safe to paste
- what you expected, with a link to the provider's documentation when the behavior concerns a provider

Never post credentials, full phone numbers, or message contents. A correction to provider behavior needs a source: the provider's official documentation, or a reproducible request and response with secrets and numbers removed.

## Report a security issue

:::warning
Do not open a public issue for a vulnerability, such as a way to bypass webhook signature verification.
:::

Use GitHub's [private vulnerability reporting](https://github.com/opencoredev/sms-sdk/security/advisories/new). Do not open a public issue. See [SECURITY.md](https://github.com/opencoredev/sms-sdk/blob/main/SECURITY.md) for what to include.

## Questions for your provider

SMS SDK cannot see or change your provider account. Ask your provider about sender provisioning, number porting, 10DLC, toll-free verification, short code approval, messages accepted but not delivered or filtered by carriers, account limits, trial restrictions, geographic permissions, and pricing. Give them the message's `providerId` from the send result or status webhook. Providers look messages up by their own ID.

## Set up the repository

```bash
git clone https://github.com/opencoredev/sms-sdk.git
cd sms-sdk
bun install
bun run typecheck   # SDK source, tests, and examples
bun run test        # unit, contract, webhook, CLI, examples, packaging
bun run build       # the SDK, then the docs site
```

Tests mock `fetch` and never contact a provider. `packages/sms-sdk/test/integration/live.test.ts` sends one real, billable message per configured provider, and only with `LIVE_SMS_TESTS=true`, a `LIVE_SMS_TO` listed in `LIVE_SMS_ALLOWLIST`, and provider credentials (see `packages/sms-sdk/.env.example`). Never enable it in CI for pull requests.

For the docs, run `bun run dev` for a local preview and `cd apps/docs && bun run check:snippets` to type-check every TypeScript snippet against the SDK source. Pages are MDX files in `apps/docs/docs`, and each folder's `meta.ts` sets the sidebar order. Mark a block that cannot type-check, such as code for another library, with `ignore="reason"` in its fence. Snippets may import the stub modules `./db`, `./sms`, and `./notify`.

## 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.

## How releases work

Every change to `@opencoredev/sms-sdk` ships with a changeset:

```bash
bun run changeset
```

Pick patch, minor, or major and write one line for the changelog. When the pull request merges to `main`, the release workflow opens or updates a "chore: version package" pull request that bumps the version and updates `CHANGELOG.md`. Merging that pull request publishes to npm from GitHub Actions with provenance, using npm trusted publishing, so no npm token exists anywhere. Changes to the docs site alone need no changeset.

## Propose a provider

Build it with [Build your own adapter](/advanced/writing-an-adapter), then open an issue with links to the provider's official API, error, and webhook documentation, and contract fixtures built from those docs. The repository's [CONTRIBUTING.md](https://github.com/opencoredev/sms-sdk/blob/main/packages/sms-sdk/CONTRIBUTING.md) has the full checklist: the adapter file and its `providerOptions` spec, error mapping, the subpath export, contract fixtures, the webhook parser and signed request builders, and entries in `PROVIDERS.md`, the README, and the doctor environment table.