mirror of
https://github.com/mastra-ai/mastra.git
synced 2026-11-17 08:44:46 +00:00
## Description
Adds `@mastra/ring-signals` (`signals/ring`), a `SignalProvider` for
Ring doorbells and cameras, plus its integration guide and reference
page.
- `RingSignals` verifies Ring webhooks (`X-Signature`, HMAC-SHA256 over
the raw body) and sends each enabled event to agent threads as a
notification signal. Devices route to threads added with
`subscribeThread(target, deviceId)`, otherwise to the `target` option
(object or resolver), otherwise to `{ resourceId: <agent id>, threadId:
<deviceId> }`.
- `getRoutes()` returns the Ring routes (`POST /ring/token`, `GET
/ring/link`, `POST /ring/webhook`, `GET /ring/home`, `GET
/ring/media/:kind/:deviceId/:timestamp`), which Mastra adds to the
server automatically.
- Account linking stores each linked account in the channels storage
domain, with tokens encrypted (AES-256-GCM) when `encryptionKey` /
`MASTRA_ENCRYPTION_KEY` is set. Unlinking the app in Ring removes the
stored tokens.
- `ring_snapshot` and `ring_clip` tools fetch media with the linked
account, return signed, expiring media links, and attach files on
channel threads.
- Ported from the working prototype in PaulieScanlon/iot-home-security;
package layout follows `signals/github`. Adds a changeset (minor), a
CODEOWNERS entry, and the lockfile importer.
Tests (`signals/ring/src/ring-signals.test.ts`) run the provider inside
a real `Mastra` + `Agent` + `InMemoryStore`, call the routes through
Hono, and stub only `fetch` for the Ring API and the agent's
`sendNotificationSignal`.
## Related issue(s)
DEVED-559
## Type of change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [x] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [ ] Test update
## Checklist
- [x] I have linked the related issue(s) in the description above
- [x] I have made corresponding changes to the documentation (if
applicable)
- [x] I have added tests that prove my fix is effective or that my
feature works
- [ ] I have addressed all Coderabbit comments on this PR
Link to Devin session:
https://app.devin.ai/sessions/2cbcddf6003e48f1b776d172de84527c
Open in Devin Desktop:
https://app.devin.ai/desktop/session/2cbcddf6003e48f1b776d172de84527c?variant=devin
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->
## ELI5
This PR adds a Ring integration for Mastra agents. Ring doorbell and
camera events can reach agent threads, and agents can request snapshots
or video clips for those events.
## What changed
- Added the `@mastra/ring-signals` package with a `RingSignals`
provider, Ring API client, configuration types, and public exports.
- Added webhook signature verification and event routing. Events go to
device subscribers first, then to the configured target, or to a default
agent thread.
- Added account-linking, token, webhook, home, and signed media routes.
Mastra registers the provider’s routes automatically.
- Stored linked Ring accounts in the channels storage domain. Tokens are
encrypted when `encryptionKey` or `MASTRA_ENCRYPTION_KEY` is configured.
Ring unlink events remove stored account tokens.
- Added `ring_snapshot` and `ring_clip` tools. They fetch media from
Ring and can attach files to channel threads. Signed media links are
available when `baseUrl` is configured.
- Added integration and API reference documentation, sidebar entries, a
changeset, and a CODEOWNERS rule.
## Tests
The PR adds tests for provider routes, webhook handling, account
linking, token storage, media links, and tool configuration. Test
execution results were not provided.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
225 lines
12 KiB
225 lines
12 KiB