https://github.com/anmho/bluebubbles-sdk
Resource-grouped TypeScript SDK for the BlueBubbles Server API
https://github.com/anmho/bluebubbles-sdk
bluebubbles mintlify openapi sdk typescript
Last synced: 26 days ago
JSON representation
Resource-grouped TypeScript SDK for the BlueBubbles Server API
- Host: GitHub
- URL: https://github.com/anmho/bluebubbles-sdk
- Owner: anmho
- Created: 2026-04-12T11:24:50.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-28T08:53:07.000Z (2 months ago)
- Last Synced: 2026-05-19T23:51:50.008Z (about 1 month ago)
- Topics: bluebubbles, mintlify, openapi, sdk, typescript
- Language: TypeScript
- Homepage: https://bluebubbles.anmho.com/
- Size: 455 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# @anmho/bluebubbles-sdk
Resource-grouped TypeScript SDK for BlueBubbles.
- Primitives and types are generated by Hey API.
- Public client is a thin static wrapper over generated primitives.
- OpenAPI spec is derived from the official BlueBubbles Postman collection.
- Documentation: https://bluebubbles.anmho.com/
## Install
```bash
npm install @anmho/bluebubbles-sdk
```
## Usage
```ts
import { BlueBubblesClient } from '@anmho/bluebubbles-sdk';
const client = new BlueBubblesClient({
baseUrl: 'http://localhost:1234',
password: 'your-server-password',
});
const chat = await client.chats.get({ path: { chatGuid: 'iMessage;+;12345' } });
const chats = await client.chats.query(); // optional input
await client.messages.sendText({
body: {
chatGuid: 'iMessage;+;12345',
message: 'hello from sdk',
},
});
const attachment = await client.attachments.download({ path: { guid: 'ATTACHMENT_GUID' } });
```
## Resources
`client.attachments`, `client.backups`, `client.chats`, `client.contacts`, `client.fcm`, `client.handles`, `client.icloud`, `client.macos`, `client.messages`, `client.server`, `client.web`, `client.webhooks`
## Event constants
```ts
import { WEBHOOK_EVENT_TYPES } from '@anmho/bluebubbles-sdk';
await client.webhooks.create({
url: 'https://example.com/webhooks/bluebubbles',
events: [WEBHOOK_EVENT_TYPES.NEW_MESSAGE, WEBHOOK_EVENT_TYPES.UPDATED_MESSAGE],
});
const event = client.webhooks.constructEvent(rawBody);
if (event.type === WEBHOOK_EVENT_TYPES.NEW_MESSAGE) {
console.log(event.data);
}
```
## Generation
```bash
npm run spec:download
npm run generate
```
`spec:download` (optional spec refresh):
1. Downloads the official Postman collection.
2. Normalizes unresolved placeholders required by the converter.
3. Converts Postman -> OpenAPI (`spec/openapi.yaml`).
`generate` (normal SDK build path):
1. Generates Hey API primitives and types to `src/generated`.
`spec/openapi.yaml` is the source of truth for generation.
`prepare_postman.ts` is only used during `spec:download` to make Postman conversion reproducible.
## Repro Steps
From a clean checkout:
```bash
npm ci
npm run generate
npm test
```
If you want to refresh the spec first:
```bash
npm run spec:download
npm run generate
npm test
```
## Contributing
1. Create a feature branch and make your changes.
2. Run local checks before opening a PR:
```bash
npm run generate
npm run build
npm test
```
3. For any user-facing SDK change, add a changeset:
```bash
npm run changeset
```
Choose `patch`, `minor`, or `major` for `@anmho/bluebubbles-sdk` and include a short summary.
4. Commit both your code changes and the generated `.changeset/*.md` file.
Release flow:
- Merging PRs into `main` updates or creates a release PR.
- Merging the release PR publishes to npm and creates a GitHub Release.
- Merging a normal feature PR into `main` does not publish by itself. Publish only happens when the generated `chore(release): version package` PR is merged.
Release troubleshooting:
- Merging a normal PR does not publish immediately. Publish happens only after the release PR is merged.
- If no `.changeset/*.md` file is included in merged PRs, no release PR is created.
- The npm Trusted Publisher mapping for `anmho/bluebubbles-sdk` and `release.yml` must remain configured on npm.
- The publish build must be green (`npm run build`) in CI.
### Example release-ready PR
Use this sequence when your PR includes user-facing SDK changes:
```bash
# 1) Make your code/docs change
git checkout -b feat/my-change
# 2) Add release metadata
npm run changeset
# 3) Validate locally
npm run generate
npm run build
npm test
# 4) Commit and open PR
git add .
git commit -m "feat: describe your change"
git push
```
The changeset file should look like:
```md
---
"@anmho/bluebubbles-sdk": patch
---
Brief release note for users.
```
After merge to `main`, automation opens or updates a release PR. Merging that release PR publishes to npm and creates a GitHub Release.
The publish workflow lives in `.github/workflows/release.yml` and uses npm trusted publishing via GitHub OIDC, not `NPM_TOKEN`.
## Scripts
- `spec:download`
- `generate`
- `build`
- `check`
- `test`
- `docs:sync-openapi`
- `docs:dev`
- `docs:validate`
## Notes
- Do not hand-edit generated files in `src/generated`.
- The wrapper keeps BlueBubbles semantics and groups methods by resource.