Contributing and support

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. There is no paid support plan. Bug reports, provider corrections with evidence, docs fixes, and pull requests are welcome.

Where to ask

Before you ask, run the doctor CLI. A dry run catches many configuration problems without any network calls:

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

Use GitHub’s private vulnerability reporting. Do not open a public issue. See 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

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:

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