Skip to content

feat: add Sendblue provider #26

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jmisilo merged 1 commit into from
Jul 16, 2026
Merged

feat: add Sendblue provider #26

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .changeset/quiet-phones-send.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
'@imessage-sdk/sendblue': minor
---

Add the initial Sendblue provider with direct text and single-attachment sends, message lookup and
status, typing indicators, opt-in mark-read, add-only tapbacks, authenticated webhooks, provider
error mapping, and provider-aware capability types.
10 changes: 10 additions & 0 deletions .env.example
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,3 +14,13 @@ PHOTON_TEST_RECIPIENT=
PHOTON_TEST_IMAGE_URL=
PHOTON_TEST_VIDEO_URL=
PHOTON_TEST_FILE_URL=

SENDBLUE_API_KEY=
SENDBLUE_API_SECRET=
SENDBLUE_FROM_NUMBER=
SENDBLUE_WEBHOOK_SECRET=
SENDBLUE_TEST_RECIPIENT=
SENDBLUE_TEST_IMAGE_URL=
SENDBLUE_TEST_VIDEO_URL=
SENDBLUE_TEST_FILE_URL=
SENDBLUE_TEST_MARK_READ=
1 change: 0 additions & 1 deletion AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,6 @@ depend on the public `imessage-sdk` interface rather than provider internals.
| `packages/providers/<provider>` | Independently published provider package |
| `packages/providers/README.md` | Cross-provider feature support matrix |
| `packages/chat-adapter` | Chat SDK integration (`@imessage-sdk/chat-adapter`) |
| `packages/eve-channel` | Private placeholder for `@imessage-sdk/eve-channel` |
| `packages/cli` | Private placeholder for `@imessage-sdk/cli` |
| `examples/basic-blooio` | Opt-in live example using only published Blooio and core APIs |
| `test/package-consumer` | Clean TypeScript consumer used by package smoke tests |
Expand Down
11 changes: 6 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,9 @@ const client = createIMessageClient({

P.S. remember to create your own [Blooio account](https://app.blooio.com/signup?ref=BLOO-2NS4AJM8) and configure the provider with your credentials.

Available normalized v0.1 operations, including signed webhook verification and normalized webhook
events, are stable.
The stable v0.1 providers are Blooio, Photon, and Sendblue. See the
[provider feature matrix](./packages/providers/README.md) for their verified surfaces and current
limitations.

See the [package README](./packages/imessage-sdk/README.md) for the public API,
provider configuration, capability boundary, and live integration tests.
Expand Down Expand Up @@ -58,9 +59,9 @@ packages/
├── imessage-sdk/ Provider-neutral core package
├── providers/
│ ├── blooio/ @imessage-sdk/blooio
│ └── photon/ @imessage-sdk/photon
│ ├── photon/ @imessage-sdk/photon
│ └── sendblue/ @imessage-sdk/sendblue
├── chat-adapter/ @imessage-sdk/chat-adapter
├── eve-channel/ Private placeholder for @imessage-sdk/eve-channel
└── cli/ Private placeholder for @imessage-sdk/cli
examples/
└── basic-blooio/ Opt-in live Blooio API and webhook example
Expand Down Expand Up @@ -120,7 +121,7 @@ Before publishing, the same release command used by automation also packs each
public package, runs Publint and Are the Types Wrong, installs all tarballs in
a clean strict-TypeScript consumer, and checks every public import.

Releases publish under npm's `latest` dist-tag. See
Stable releases publish under npm's `latest` dist-tag, while prereleases publish under `beta`. See
[RELEASING.md](./RELEASING.md) for the complete maintainer workflow.

### Release automation setup
Expand Down
57 changes: 37 additions & 20 deletions RELEASING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,14 +5,14 @@ requests, npm trusted publishing, and package-specific GitHub Releases.

## What is published

| Directory | npm package | Status |
| --------------------------- | ---------------------------- | ------------------- |
| `packages/imessage-sdk` | `imessage-sdk` | Public |
| `packages/providers/blooio` | `@imessage-sdk/blooio` | Public |
| `packages/providers/photon` | `@imessage-sdk/photon` | Public |
| `packages/chat-adapter` | `@imessage-sdk/chat-adapter` | Public |
| `packages/eve-channel` | `@imessage-sdk/eve-channel` | Private placeholder |
| `packages/cli` | `@imessage-sdk/cli` | Private placeholder |
| Directory | npm package | Status |
| ----------------------------- | ---------------------------- | ------------------- |
| `packages/imessage-sdk` | `imessage-sdk` | Public |
| `packages/providers/blooio` | `@imessage-sdk/blooio` | Public |
| `packages/providers/photon` | `@imessage-sdk/photon` | Public |
| `packages/providers/sendblue` | `@imessage-sdk/sendblue` | Public |
| `packages/chat-adapter` | `@imessage-sdk/chat-adapter` | Public |
| `packages/cli` | `@imessage-sdk/cli` | Private placeholder |

## One-time local setup

Expand Down Expand Up @@ -41,9 +41,9 @@ Normal releases run in GitHub Actions through OIDC and need neither a local
3. Bootstrap a new package name manually before configuring OIDC for it.
4. Configure trusted publishing separately for every public package.

The initial prereleases currently own `latest` as a consequence of package
bootstrap. The first stable release will replace it with `0.1.0`; no dist-tag
removal is required.
A package's first prerelease may also receive `latest` as a consequence of npm
bootstrap. Its first stable release replaces that tag; no dist-tag removal is
required.

## One-time GitHub setup

Expand Down Expand Up @@ -101,7 +101,8 @@ changelogs.
## Trusted publishing on npm

Configure trusted publishing separately in the settings for `imessage-sdk`,
`@imessage-sdk/blooio`, `@imessage-sdk/photon`, and `@imessage-sdk/chat-adapter`:
`@imessage-sdk/blooio`, `@imessage-sdk/photon`, `@imessage-sdk/sendblue`, and
`@imessage-sdk/chat-adapter`:

```text
Provider: GitHub Actions
Expand All @@ -128,11 +129,15 @@ npm cannot configure a trusted publisher for a package that does not exist.
For the first version of a future provider or adapter:

1. Merge its package and changeset through the normal reviewed PR flow.
2. Build and pack it from the exact `main` commit that will be tagged.
3. Inspect and publish the tarball locally under `beta`.
4. Configure that package's npm trusted publisher.
5. Backfill the matching Git tag and GitHub prerelease if automation did not
create them.
2. Review and merge the generated Version Packages pull request. The first
automated publish can fail with npm `E404` because trusted publishing cannot
be configured until the package exists.
3. Check out the resulting `main` commit, then build and pack the versioned
package from that exact commit.
4. Inspect and publish the tarball locally under the intended dist-tag.
5. Configure that package's npm trusted publisher.
6. Backfill the matching Git tag and GitHub Release if automation did not create
them. Mark the GitHub Release as a prerelease only for a prerelease version.

For example:

Expand All @@ -146,7 +151,17 @@ pnpm package:check

PACKAGE_DIR=$(mktemp -d)
pnpm --filter @imessage-sdk/<provider> pack --pack-destination "$PACKAGE_DIR"
npm publish "$PACKAGE_DIR/<tarball>.tgz" --tag beta --access public --provenance=false
npm publish "$PACKAGE_DIR/<tarball>.tgz" --access public --provenance=false
```

Add `--tag beta` when bootstrapping a prerelease. For the initial stable Sendblue release, use:

```bash
PACKAGE_DIR=$(mktemp -d)
pnpm --filter @imessage-sdk/sendblue pack --pack-destination "$PACKAGE_DIR"
npm publish "$PACKAGE_DIR/imessage-sdk-sendblue-0.1.0.tgz" \
--access public \
--provenance=false
```

Direct package publishing commands can incorrectly request provenance outside
Expand Down Expand Up @@ -261,10 +276,12 @@ imessage-sdk@0.1.0-beta.1
Confirm that npm versions and dist-tags match the generated package versions:

```bash
npm view imessage-sdk@beta version
npm view imessage-sdk version
npm dist-tag ls imessage-sdk
npm view @imessage-sdk/blooio@beta version
npm view @imessage-sdk/blooio version
npm dist-tag ls @imessage-sdk/blooio
npm view @imessage-sdk/sendblue version
npm dist-tag ls @imessage-sdk/sendblue
```

Then install the release in a clean external project using `@beta` during the
Expand Down
11 changes: 0 additions & 11 deletions packages/eve-channel/package.json
View file
Open in desktop

This file was deleted.

58 changes: 33 additions & 25 deletions packages/providers/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,29 +3,30 @@
Provider adapters are independently installable packages built on the public
`imessage-sdk` contract.

| Capability | Blooio | Photon Cloud |
| ----------------------------- | ---------------------- | --------------------------------- |
| Package | `@imessage-sdk/blooio` | `@imessage-sdk/photon` |
| Send text | ✅ | ✅ |
| Send public URL attachments | ✅ | ✅ |
| Send `Blob` attachments | — | ✅ |
| Send `Uint8Array` attachments | — | ✅ |
| Access inbound attachments | Public URL | Authenticated byte download |
| Reply to a message | ✅ | ✅ |
| Get a message | ✅ | ✅ |
| Edit a message | — | — |
| Delete or unsend a message | — | — |
| Open a direct conversation | ✅ | ✅ |
| Group conversations | — | Experimental, provider-level only |
| Get a conversation | ✅ | ✅ |
| Mark a conversation as read | ✅ | ✅ |
| Add and remove reactions | ✅ | ✅ |
| Start and stop typing | ✅ | ✅ |
| Read receipts | ✅ | ✅ |
| Signed webhooks | ✅ | ✅ |
| Normalized event stream | — | — |
| Provider-level event stream | — | Experimental |
| Sender or line discovery | Linked numbers | Connected line |
| Capability | Blooio | Photon Cloud | Sendblue |
| ----------------------------- | ---------------------- | --------------------------------- | ------------------------ |
| Package | `@imessage-sdk/blooio` | `@imessage-sdk/photon` | `@imessage-sdk/sendblue` |
| Send text | ✅ | ✅ | ✅ |
| Send public URL attachments | ✅ | ✅ | ✅ (one per message) |
| Send `Blob` attachments | — | ✅ | ✅ (one per message) |
| Send `Uint8Array` attachments | — | ✅ | ✅ (one per message) |
| Access inbound attachments | Public URL | Authenticated byte download | Expiring public URL |
| Reply to a message | ✅ | ✅ | — |
| Get a message | ✅ | ✅ | ✅ |
| Edit a message | — | — | — |
| Delete or unsend a message | — | — | — |
| Open a direct conversation | ✅ | ✅ | ✅ |
| Group conversations | — | Experimental, provider-level only | — |
| Get a conversation | ✅ | ✅ | — |
| Mark a conversation as read | ✅ | ✅ | Account-dependent |
| Add and remove reactions | ✅ | ✅ | — |
| Provider-level tapback add | — | — | ✅ |
| Start and stop typing | ✅ | ✅ | ✅ |
| Read receipts | ✅ | ✅ | — |
| Authenticated webhooks | Signed | Signed | Shared-secret header |
| Normalized event stream | — | — | — |
| Provider-level event stream | — | Experimental | — |
| Sender or line discovery | Linked numbers | Connected line | Configured sender |

`—` means the normalized v0.1 capability is unavailable. Unsupported
normalized operations throw `UnsupportedCapabilityError` rather than silently
Expand All @@ -35,8 +36,13 @@ Photon group conversations and streaming exist behind provider-specific APIs,
but their normalized capabilities remain disabled until their behavior and
integration tests are stable enough for the v0.1 contract.

All available normalized v0.1 operations, including webhook verification and event normalization,
are stable.
Sendblue accepts one outbound attachment per message in v0.1. Its normalized reaction capability
remains disabled because the documented API can add a tapback but cannot reliably remove one. The
add-only operation remains available through the concrete Sendblue provider. The Sendblue
mark-read endpoint depends on account support and must be explicitly enabled.

The published Blooio, Photon, and Sendblue v0.1 operations are stable. Their live integration suites
remain opt-in because they contact real provider accounts, send messages, and mutate provider state.

## Installation

Expand All @@ -45,6 +51,7 @@ Install the core together with exactly the providers an application uses:
```bash
pnpm add imessage-sdk @imessage-sdk/blooio
pnpm add imessage-sdk @imessage-sdk/photon
pnpm add imessage-sdk @imessage-sdk/sendblue
```

```ts
Expand All @@ -60,6 +67,7 @@ See each provider package for configuration and live integration-test details:

- [`@imessage-sdk/blooio`](./blooio)
- [`@imessage-sdk/photon`](./photon)
- [`@imessage-sdk/sendblue`](./sendblue)

For an executable end-to-end Blooio walkthrough, see
[`examples/basic-blooio`](../../examples/basic-blooio).
21 changes: 21 additions & 0 deletions packages/providers/sendblue/LICENSE
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
MIT License

Copyright (c) 2026 imessage-sdk contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Loading
Loading