feat(examples): working npm-downloads custom connector for lobu-crm

[buremba]

What

Adds examples/lobu-crm/npm-downloads.connector.ts — a minimal but working custom connector — and wires it into the example via connectorFromFile + a npm-downloads-lobu-cli connection.

Why

#1107 removed the funnel-form connector because its endpoint was dead (404, zero events). That was the example's only connectorFromFile demonstration. This restores the showcase with a connector that actually works:

• Polls the public npm download-counts API (api.npmjs.org, no auth) for @lobu/cli.
• Emits one event per new weekly period; dedups via a typed rolling checkpoint of seen period-end dates.
• Weekly npm pulls are a genuine top-of-funnel adoption signal, so it belongs next to the GitHub-stars / X-mentions / HN connections.

Verification (ran against the live endpoint)

RUN 1 — events: 1
  @lobu/cli: 954 downloads (2026-05-20 → 2026-05-26)
  checkpoint: {"seen_periods":["2026-05-26"]}
RUN 2 (same week, with checkpoint) — events: 0   ✓ dedup

• bunx tsc --noEmit (workspace resolution): no errors in lobu.config.ts or npm-downloads.connector.ts.
• Pre-commit tsc + biome pass.

Note

This is example/repo content; it isn't auto-applied to the live lobu-crm org (which is now UI-managed and has drifted from this config).

Summary by CodeRabbit

• New Features

  • The CRM agent now supports npm package download metrics as an additional data source, automatically retrieving the latest metrics from the public npm registry on a weekly schedule

• Documentation

  • Updated README documentation to provide comprehensive information about the npm metrics integration feature, including detailed configuration steps and setup instructions

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR adds a new npm downloads connector to the lobu CRM example. The connector polls weekly npm download statistics from the public npm registry, maintains a rolling checkpoint to avoid duplicate events, and is wired into the example configuration with weekly feed scheduling. Documentation was updated to reflect the new data source.

Changes

NPM Downloads Connector Feature

Layer / File(s)	Summary
Connector Implementation examples/lobu-crm/npm-downloads.connector.ts	Defines NpmDownloadsConnector class with typed checkpoint (seen_periods) and config (package), implements sync() to fetch weekly npm download data, deduplicate by period end date, and emit events with package/count metadata, plus execute() stub.
Config Wiring and Registration examples/lobu-crm/lobu.config.ts	Imports connectorFromFile and NpmDownloadsConnector type, defines npm_downloadsConn connection with weekly feed, registers the connector implementation, and adds it to the connections array in the default config export.
Documentation and Example Updates examples/lobu-crm/README.md	Updates project description to include npm pulls, adds npm-downloads.connector.ts to the structure file tree, and documents the connector in the "Key files to read" table.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 A new connector hops into place,
Tallying npm pulls with weekly grace,
Config and docs in perfect sync,
The CRM gets a download link! 📊✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: adding a working npm-downloads custom connector to the lobu-crm example.
Description check	✅ Passed	The description provides a clear 'What' section explaining the connector addition, a 'Why' section with motivation, and verification results demonstrating the feature works as intended.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/lobu-crm-reconcile

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!