hood-alerts 0.1.0 → 0.2.0

package/.env.example

@@ -0,0 +1,90 @@
+# hood-alerts configuration. Copy to .env and fill in what you use.
+# Everything is optional: with zero env vars the engine runs with the console
+# transport only (alerts printed as structured logs), which is the self-host
+# smoke-test mode.
+
+# ---- chain ----
+# Custom RPC (e.g. Alchemy: https://robinhood-mainnet.g.alchemy.com/v2/KEY).
+# Defaults to the public RPC from viem's official `robinhood` chain definition.
+HOOD_ALERTS_RPC_URL=
+
+# ---- storage ----
+# SQLite database path (subscriptions, entitlements, dedup, delivery log).
+HOOD_ALERTS_DB=./data/hood-alerts.db
+
+# ---- HTTP server ----
+# Cloud Run injects PORT. /healthz + the premium x402 endpoints live here.
+PORT=8080
+# Public base URL of this instance (used in payment challenges + bot replies).
+HOOD_ALERTS_PUBLIC_URL=
+
+# ---- Telegram bot ----
+# Create with @BotFather -> /newbot. Leave empty to disable the transport.
+HOOD_ALERTS_TELEGRAM_TOKEN=
+
+# ---- Discord bot ----
+# Create at https://discord.com/developers/applications (Bot token + App ID).
+# Leave empty to disable the transport.
+HOOD_ALERTS_DISCORD_TOKEN=
+HOOD_ALERTS_DISCORD_APP_ID=
+
+# ---- X (Twitter) auto-posting: pick ONE mode ----
+# Leave empty to disable. X has no inbound bot (no watch/unwatch DMs), so what
+# it posts is fixed at startup via HOOD_ALERTS_X_TOPICS below.
+HOOD_ALERTS_X_MODE=                    # official | xactions
+
+# official mode: the real X API v2, POST /2/tweets, OAuth1 user context.
+# Requires a developer.x.com app with a posting-capable tier (check current
+# pricing at https://developer.x.com/en/portal/products/buy before relying on
+# this; it has changed before and may change again). Create an app, generate
+# a consumer key/secret, then generate an access token/secret with
+# read+write permissions.
+HOOD_ALERTS_X_API_KEY=
+HOOD_ALERTS_X_API_SECRET=
+HOOD_ALERTS_X_ACCESS_TOKEN=
+HOOD_ALERTS_X_ACCESS_SECRET=
+
+# xactions mode: free, self-hosted browser-automation posting via your own X
+# session cookie instead of the official API. See
+# https://github.com/nirholas/XActions to run your own instance. Not the
+# official API: carries ToS risk. Posting is async (queued, not confirmed
+# synchronously).
+HOOD_ALERTS_XACTIONS_URL=
+HOOD_ALERTS_XACTIONS_TOKEN=
+
+# Topics the X broadcast auto-posts (comma-separated; parsed the same way a
+# `watch` command target is). Premium-tier topics (premiums, rugs) only post
+# if the x/public subscriber has been granted premium (see grant-premium).
+HOOD_ALERTS_X_TOPICS=launches,graduations,whales
+
+# ---- premium (x402 USDG on Robinhood Chain via hood402) ----
+# Rail selector. `hood402` (USDG on chain 4663) is implemented end-to-end.
+# `x402-usdc` is a documented alternative (see README) and is rejected at
+# startup until wired to your own facilitator.
+HOOD_ALERTS_PREMIUM_RAIL=hood402
+# Address that receives premium payments. Premium purchase endpoints stay
+# disabled (503 + guidance) until this is set.
+HOOD402_PAY_TO=
+# Settlement mode A: a hood402 facilitator base URL (recommended; no gas key
+# on this box).
+HOOD402_FACILITATOR_URL=
+# Settlement mode B: self-settle with a gas key. READ THE WARNING in the
+# README before putting a key here.
+HOOD402_SETTLER_KEY=
+# Price + duration of one premium purchase.
+HOOD_ALERTS_PREMIUM_PRICE_USDG=5
+HOOD_ALERTS_PREMIUM_DAYS=30
+
+# ---- detector tuning (defaults shown) ----
+# Floor below which whale trades are not even emitted engine-side (USD).
+HOOD_ALERTS_WHALE_FLOOR_USD=1000
+# Default per-subscription whale threshold when none is given (USD).
+HOOD_ALERTS_WHALE_DEFAULT_USD=5000
+# Price-move window (seconds) and default threshold (percent).
+HOOD_ALERTS_PRICE_WINDOW_S=900
+HOOD_ALERTS_PRICE_DEFAULT_PCT=2
+# Stock premium/discount poll interval (seconds) and default threshold (%).
+HOOD_ALERTS_PREMIUM_POLL_S=60
+HOOD_ALERTS_PREMIUM_DEFAULT_PCT=2
+# Liquidity-pull default threshold (percent of pool quote reserves).
+HOOD_ALERTS_RUG_DEFAULT_PCT=30

package/Dockerfile

@@ -0,0 +1,65 @@
+# syntax=docker/dockerfile:1
+#
+# hood-alerts: one long-running process runs the detection engine, the HTTP
+# server (/healthz + premium x402), and both bots (env-gated). Min-instances 1
+# on Cloud Run; this is a service, not a job.
+#
+# The build context MUST be the parent `robinhood/` directory so the local
+# file: siblings (robinhood-chain-sdk, hoodkit, hood402) resolve:
+#
+#   docker build -f hood-alerts/Dockerfile -t hood-alerts .   # run from robinhood/
+#
+# Once those packages are published to npm, switch the file: specs in
+# package.json to the published versions and the app builds from its own dir.
+
+# ---- build: full install (better-sqlite3 needs a toolchain) + tsc ----
+FROM node:22-slim AS build
+RUN apt-get update && apt-get install -y --no-install-recommends python3 make g++ \
+  && rm -rf /var/lib/apt/lists/*
+WORKDIR /build
+# Prebuilt sibling packages (manifest + dist) for the file: links.
+COPY robinhood-chain-sdk/package.json ./robinhood-chain-sdk/package.json
+COPY robinhood-chain-sdk/dist ./robinhood-chain-sdk/dist
+COPY hoodkit/package.json ./hoodkit/package.json
+COPY hoodkit/dist ./hoodkit/dist
+COPY hood402/package.json ./hood402/package.json
+COPY hood402/dist ./hood402/dist
+WORKDIR /build/hood-alerts
+COPY hood-alerts/package.json ./package.json
+# --install-links copies the file: siblings into node_modules as real packages
+# (not symlinks), so their `viem` dependency hoists and resolves at runtime.
+RUN npm install --install-links --no-audit --no-fund
+COPY hood-alerts/tsconfig.json ./tsconfig.json
+COPY hood-alerts/src ./src
+COPY hood-alerts/scripts ./scripts
+RUN npm run build
+
+# ---- prod-deps: runtime node_modules only (no tsc/tsx/vitest) ----
+FROM node:22-slim AS prod-deps
+RUN apt-get update && apt-get install -y --no-install-recommends python3 make g++ \
+  && rm -rf /var/lib/apt/lists/*
+WORKDIR /build
+COPY robinhood-chain-sdk/package.json ./robinhood-chain-sdk/package.json
+COPY robinhood-chain-sdk/dist ./robinhood-chain-sdk/dist
+COPY hoodkit/package.json ./hoodkit/package.json
+COPY hoodkit/dist ./hoodkit/dist
+COPY hood402/package.json ./hood402/package.json
+COPY hood402/dist ./hood402/dist
+WORKDIR /build/hood-alerts
+COPY hood-alerts/package.json ./package.json
+RUN npm install --omit=dev --install-links --no-audit --no-fund
+
+# ---- runtime ----
+FROM node:22-slim AS runtime
+ENV NODE_ENV=production
+ENV PORT=8080
+ENV HOOD_ALERTS_DB=/data/hood-alerts.db
+WORKDIR /app
+COPY --from=prod-deps /build/hood-alerts/node_modules ./node_modules
+COPY --from=build /build/hood-alerts/dist ./dist
+COPY --from=build /build/hood-alerts/package.json ./package.json
+# SQLite lives on a mounted volume so subscriptions survive restarts.
+RUN mkdir -p /data
+VOLUME ["/data"]
+EXPOSE 8080
+CMD ["node", "dist/src/index.js"]

package/LICENSE

@@ -1,20 +1,21 @@
-Copyright 2026 nirholas
+MIT License
 
-All rights reserved.
+Copyright (c) 2026 nirholas
 
-This software is proprietary and may not be used, copied, modified, distributed,
-translated, or made available to any third party without the express written
-permission of the copyright owner.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-No rights are granted by implication, estoppel, or otherwise. Use of this
-software is subject to the terms of a separate license agreement with the
-copyright owner.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
-
-IN NO EVENT SHALL THE COPYRIGHT OWNER BE LIABLE FOR ANY CLAIM, DAMAGES, OR
-OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE,
-ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
-DEALINGS IN THE SOFTWARE.
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.