@nepse-toolkit/store

SQLite persistence layer for NEPSE toolkit data and operations.

Part of the nepse-toolkit monorepo.

Overview

Local-first SQLite database (better-sqlite3, WAL mode)
Auto-applied migrations
Storage for prices, floorsheet, fundamentals, watchlists, portfolio, and alerts
Persistent provider payload telemetry history and dashboard aggregation
Persistent telemetry anomaly sink and ack/silence control state
Telemetry retention pruning and dead-letter persistence for failed alert deliveries

Install

npm install @nepse-toolkit/store

Quick Start

import { NepseDatabase } from "@nepse-toolkit/store";

const db = new NepseDatabase();

db.upsertDailyPrices(ohlcvData);
const history = db.getDailyPrices("NABIL", {
  from: "2024-01-01",
  to: "2024-12-31",
});

db.addPosition("NABIL", 100, 850, "2024-06-15");
const positions = db.getPortfolio();

db.insertPayloadTelemetrySnapshots(liveSnapshots);
const dashboard = db.getPayloadTelemetryDashboard({ hours: 24, topEndpoints: 20 });
const pruneResult = db.prunePayloadTelemetryHistory({ retentionDays: 30 });

const sink = db.upsertPayloadTelemetryAlertSink({
  type: "webhook",
  target: "https://alerts.example.com/webhook",
  enabled: true,
});

const control = db.upsertPayloadTelemetryAlertControl({
  provider: "nepse",
  endpoint: "/api/nots/nepse-data/marketdepth/131",
  silencedUntil: new Date(Date.now() + 60_000).toISOString(),
  note: "known noisy endpoint",
});

const deadLetter = db.insertPayloadTelemetryAlertDeadLetter({
  provider: "nepse",
  endpoint: "/api/nots/nepse-data/marketdepth/131",
  sinkType: "webhook",
  sinkTarget: "https://alerts.example.com/webhook",
  payload: { event: { provider: "nepse" } },
  attempts: 3,
  maxAttempts: 3,
  lastError: "HTTP 500 upstream error",
});

const unresolvedDeadLetters = db.listPayloadTelemetryAlertDeadLetters({
  unresolvedOnly: true,
  limit: 50,
});

Runtime Note

@nepse-toolkit/store uses better-sqlite3 (native addon), so use Node.js runtime for this package.

Development

bun --filter @nepse-toolkit/store run build
bun --filter @nepse-toolkit/store run typecheck
node --import tsx --test packages/store/tests/database.test.ts

License

MIT