@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

npm install @anmho/bluebubbles-sdk

Usage

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

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

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:

npm ci
npm run generate
npm test

If you want to refresh the spec first:

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:

npm run generate
npm run build
npm test

3. For any user-facing SDK change, add a changeset:

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:

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

---
"@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.