{"_id":"@ap3x/solana-webhooks","_rev":"3-9930fde90e0ac266e944a81e7bb2511a","name":"@ap3x/solana-webhooks","dist-tags":{"latest":"0.0.0"},"versions":{"0.0.0":{"name":"@ap3x/solana-webhooks","version":"0.0.0","_id":"@ap3x/solana-webhooks@0.0.0","maintainers":[{"name":"botstack","email":"GuerrillaMedia702@gmail.com"}],"dist":{"shasum":"b42c0b09c557bed23cfed093433b59387c41c806","tarball":"https://registry.npmjs.org/@ap3x/solana-webhooks/-/solana-webhooks-0.0.0.tgz","fileCount":8,"integrity":"sha512-chpJFHGfByU32RbAu/UghDnUAAABW4Q55LqKTeevs6LWUcTI5wEg50qRtvtoEasA6YVy0A+vY42S7Ut9e34Scw==","signatures":[{"sig":"MEYCIQCzMkj9krB4jEk9MP4/kdBTwX80ZWTvaMzgMN5GUPMzBQIhAPW98OZ0PUnsVB2WcsisRrWLf2/ziF65aCqdL5H2vKjI","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":342752},"main":"./dist/index.cjs","type":"module","_from":"file:ap3x-solana-webhooks-0.0.0.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"private":false,"scripts":{"lint":"eslint src","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit","test:watch":"vitest","test:coverage":"vitest run --coverage"},"_npmUser":{"name":"botstack","email":"GuerrillaMedia702@gmail.com"},"_resolved":"C:\\Users\\Guerr\\AppData\\Local\\Temp\\685cd0929b4290c7410736f59307ee13\\ap3x-solana-webhooks-0.0.0.tgz","_integrity":"sha512-chpJFHGfByU32RbAu/UghDnUAAABW4Q55LqKTeevs6LWUcTI5wEg50qRtvtoEasA6YVy0A+vY42S7Ut9e34Scw==","deprecated":"Discontinued. NOT part of the AP3X agent framework.","_npmVersion":"11.5.1","description":"Webhook ingestion as a peer transport to Geyser for the AP3X Solana substrate. Receiver, outbox-first persistence, HMAC verify, backpressure, gap catchup. Helius is the first driver.","directories":{},"_nodeVersion":"20.18.2","dependencies":{"@ap3x/solana-core":"0.1.0","@ap3x/solana-events":"0.1.0","@ap3x/solana-signals":"0.0.0","@ap3x/solana-connectivity":"0.1.0"},"_hasShrinkwrap":false,"devDependencies":{"pg":"^8.11.0","tsup":"^8.3.0","vitest":"^2.1.0","typescript":"^5.6.0","better-sqlite3":">=9.0.0"},"peerDependencies":{"pg":">=8.11.0","better-sqlite3":">=9.0.0"},"peerDependenciesMeta":{"pg":{"optional":true},"better-sqlite3":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/solana-webhooks_0.0.0_1777660161119_0.014062353749604295","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-05-01T18:29:21.058Z","modified":"2026-08-01T03:36:48.929Z","0.0.0":"2026-05-01T18:29:21.276Z"},"description":"Webhook ingestion as a peer transport to Geyser for the AP3X Solana substrate. Receiver, outbox-first persistence, HMAC verify, backpressure, gap catchup. Helius is the first driver.","maintainers":[{"name":"botstack","email":"GuerrillaMedia702@gmail.com"}],"readme":"# @ap3x/solana-webhooks\n\nWebhook ingestion as a peer transport to Geyser for the AP3X Solana substrate.\n\n## Overview\n\n`@ap3x/solana-webhooks` is a transport-shaped package for ingesting Solana on-chain events delivered as webhooks. It pairs with `@ap3x/solana-signals` — every webhook event becomes a `Signal` on the same multi-source bus that Geyser, historical RPC replay, and any future transport feeds into. Consumers subscribe by signal type, not by transport.\n\nThe package is driver-shaped: Helius is the first driver and the canonical reference; the receiver/outbox/backpressure/admin/catchup machinery is generic and accepts a `WebhookDriver` contract for future drivers (a self-hosted Geyser→webhook bridge, a second commercial provider, a replay-from-archive driver).\n\n## Why webhooks, not just Geyser\n\nGeyser is the right tap when latency matters and cost is justified. Webhooks are the right tap for everyone else — products that need swap/transfer-class events but can't justify a Geyser bill. The two are peers, not fallbacks: many consumers will run webhook-only; some will run both for redundancy and gap recovery.\n\n## What you get\n\n- **HTTP receiver.** Typed Node `http` handler. Configurable payload-size cap (default 1 MiB). HMAC verification with constant-time compare. Backpressure (saturation-aware acceptance — refuses new work above N concurrent ingests with `503` so the upstream backs off).\n- **Outbox-first persistence.** The handler persists raw payload + returns `200` *before* decoding. A background drainer reads `processed_at IS NULL` rows, decodes via `@ap3x/solana-events`, emits to the signal bus, marks processed. Idempotency on `(source, helius_event_id)` — re-deliveries no-op. Backends: SQLite (dev), Postgres (production).\n- **Event normalization.** Helius enhanced-transaction payloads → typed event records that match what `@ap3x/solana-events`' decoder framework emits from Geyser. Where Helius's parsing is sufficient, trust it; where it isn't (custom programs, unknown variants), fall back to raw transaction parsing through `@ap3x/solana-events`. Unknown variants surface as `UnknownEventDecode` records, never silently dropped.\n- **Webhook config sync.** Typed wrapper over Helius's webhook management API: `subscribeAddresses`, `removeAddresses`, `reconcile` (idempotent diff/apply).\n- **Gap catchup.** When the outbox detects a delivery gap (no events for window > threshold, or sequence-id discontinuity) or the operator triggers manually, fetch missing signatures via `@ap3x/solana-connectivity`'s historical RPC backfill, replay through decoders, mark backfilled rows with `source: 'catchup'`.\n- **Healthz + metrics.** `lastEventAt()`, `isHealthy()`, structured counters/latencies surfaced through a pluggable `MetricsEmitter` interface.\n\n## Driver contract\n\nA `WebhookDriver` implementation is everything specific to one webhook provider. Helius is shipped; future drivers plug in by implementing:\n\n```ts\nexport interface WebhookDriver {\n  readonly source: string;\n  verifyRequest(req: IncomingRequest): VerifyResult;\n  parseRawPayload(body: Uint8Array): RawWebhookEvent[];\n  normalizeEvent(raw: RawWebhookEvent): TypedSolanaEvent[];\n  admin?: WebhookAdminClient;\n  catchup?: WebhookCatchupClient;\n}\n```\n\n## Status\n\nThis package is alpha (`0.0.x` series). The public types are stable as of `0.1.0`; outbox schema is migration-managed at `init()` so existing data is preserved across minor versions.\n\n## Dependency posture\n\nSame as the rest of `@ap3x/solana-*`: hand-rolled where practical, with documented exceptions. The HTTP server is built on Node's built-in `http`; HMAC verify uses Node `crypto`; JSON parsing is native. The outbox declares `better-sqlite3` and `pg` as **optional peer dependencies** — consumers who use the SQLite outbox install `better-sqlite3`; consumers who use the Postgres outbox install `pg`. Both are widely-audited, version-pinned, and only loaded via dynamic `import()` from their respective backends.\n","readmeFilename":"README.md"}