SDK Reference — @r-bsoftware/ecosystem-sdk

The single TypeScript SDK used by every ecosystem app. Factory functions for webhooks, OAuth2, dev impersonation, Firebase hooks, sealed commitments, and platform plumbing (cron, logging, Sentry, health, rate limiting) — plus typed event payloads shared by senders and receivers.

Package: @r-bsoftware/ecosystem-sdkCurrent version: 0.15.0 (changelog) Sibling package: @r-bsoftware/vitest-preset@0.1.0 (shared Vitest config helpers — new with v0.15.0) Source: ecosystem-sdk/packages/sdk/src/index.ts

Install

npm install @r-bsoftware/ecosystem-sdk

The package is published to GitHub Packages (npm.pkg.github.com), so your project needs a scoped .npmrc with a read:packages token. See Auth — package registry for the full setup.

# .npmrc
@r-bsoftware:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

Webhook + auth factories

createWebhookHandler

Verifies X-Webhook-Signature, dedupes by eventId, and routes events to your handler map. Replaces ~300 lines of per-app boilerplate with ~30.

import { createWebhookHandler } from '@r-bsoftware/ecosystem-sdk'

export const { POST, GET } = createWebhookHandler({
  app: 'plenura',
  secrets: { camino: env.CAMINO_WEBHOOK_SECRET, colectiva: env.COLECTIVA_WEBHOOK_SECRET },
  handlers: { 'subscription.activated': async (event, ctx) => {/* … */} },
})

secrets is keyed by source app — one verifier can accept signed events from multiple senders. See Webhooks — receiving.

createWebhookSender

Signs and POSTs an event to a target app, with retries and correlation-ID propagation. Reads the target base URL from APP_REGISTRY.

createDevAccessHandler

HMAC cookie signing + verification for developer impersonation. Pair with createDevAccessLogoutHandler to clear the cookie.

createFirebaseHooksChain

SvelteKit handle factory for Firebase-backed apps. Collapses identical 130-line hooks.server.ts files into ~10 lines.

createSealedCommitmentClient

Thin client for Colectiva's fifth-element attestation registry. Hashes the payload server-side and returns a salt (once) so the caller can reveal later.

v0.14.0 — platform plumbing

Five new factories, each on its own import subpath for tree-shaking.

Export	Subpath	Purpose
createCronHandler	/cron	Cron handler factory: CRON_SECRET bearer auth + QStash compatibility + error wrapping.
createLogger	/logger	Structured JSON logger — auto-wires Sentry on warn/error.
createSentryInit	/sentry	Sentry.init() config factory — DSN normalization + per-env sample-rate defaults.
createHealthHandler	/health	/api/health factory — parallel checks + critical/degraded/healthy classification.
createTierAwareRateLimiter	/tier-aware-rate-limit	Synchronous tier × type × tenantId rate limiter, in-memory by default, Upstash opt-in. Replaces the older createTenantRateLimiter (deprecated).

v0.15.0 — Firebase + CFDI sync

Export	Subpath	Purpose
createFirebaseAdminClient (+ helpers)	/firestore-admin	Factory for Firebase Admin init. firebase-admin is an optional peerDep. Replaces the ~50-LoC firebase-admin.ts duplicated across 9+ apps.
createCfdiSyncHandler	/firestore-cfdi-sync	Handlers for cfdi.stamped / cfdi.cancelled / payment.reconciled from Constanza → Firestore invoice doc updates. Wave-2 adopters: agente, cosmos-pet, madriguera.

Event payload types

Every event on the bus has a typed data shape in event-payloads.ts. Senders construct, receivers cast via EventDataOf<'sale.completed'> — the two ends stay in lockstep through EventPayloadMap.

Top event names (full list in the Events Registry):

Event	Payload type
subscription.activated	SubscriptionActivatedData
subscription.cancelled	SubscriptionCancelledData
subscription.payment_received	SubscriptionPaymentReceivedData
cfdi.stamped	CfdiStampedData
payment.received	PaymentReceivedData
sale.completed	SaleCompletedData
order.completed	OrderCompletedData
customer.created	CustomerCreatedData

Events without a typed payload fall back to Record<string, unknown>; coverage grows each minor release.

Other exports

The SDK also exports OAuth2 helpers (RBSAuth, generateState, validateState), the app registry (APP_REGISTRY, getAppBaseUrl), subscription entitlements (createSubscriptionClient), signing primitives (signPayload, verifySignature), identity registration (registerWithEcosystem, reconcileOrgs), public-endpoint rate limiting (rateLimit), and fiscal/Constanza shared types. Full export list: packages/sdk/src/index.ts.

Versioning

SemVer. Patch releases are backwards-compatible bug fixes; minor releases may add exports or typed event payloads; major bumps (0.x → 1.0) will signal stability and require a migration note.

Pin the version. Use ^0.15.x during active development and regenerate the lockfile after every SDK bump — stale lockfiles are the most common phantom install failure across apps.

See the changelog for the release history.