jason/pos

Files

jason c426b19b7c Add token auto-refresh, single-transaction endpoint, shift summary, and CI

- client/api/client.ts: shared refreshPromise prevents concurrent refresh races;
  dispatches auth:logout event when refresh fails
- client/context/AuthContext.tsx: listen for auth:logout to clear user state
- server/routes/transactions.ts: POST / real-time single transaction through
  payment abstraction (201 completed, 202 pending); GET /reports/shift shift
  window totals with averageTransaction, shiftOpen/shiftClose timestamps
- .github/workflows/ci.yml: server typecheck+build, client typecheck+build,
  Docker smoke-test on push/PR to main

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-03-21 07:06:59 -05:00

4.6 KiB

Raw Blame History

INSTRUCTIONS.md — Local Development Guide

Prerequisites

Node.js 20+
npm 10+
Docker + Docker Compose (for containerized runs)

Local Development (No Docker)

1. Server

cd server
cp .env.example .env        # edit DATABASE_URL and JWT_SECRET
npm install
npx prisma migrate dev      # creates SQLite DB and runs migrations
npm run db:seed             # seeds demo vendor + admin user
npm run dev                 # starts API on :8080 with hot-reload

Default demo credentials: admin@demo.com / password123

2. Client

cd client
npm install
npm run dev                 # starts Vite dev server on :5173

The Vite dev server proxies /api to http://localhost:8080. Open http://localhost:5173 in your browser.

Docker (Single Container + SQLite)

docker build -t vendor-pos:latest .
docker run --rm -p 8080:8080 \
  -e NODE_ENV=production \
  -e PORT=8080 \
  -e DATABASE_URL=file:/data/pos.db \
  -e JWT_SECRET=change-me \
  -v pos_data:/data \
  vendor-pos:latest

Admin UI: http://localhost:8080 API: http://localhost:8080/api/v1

Docker Compose (App + PostgreSQL)

cp .env.example .env        # set JWT_SECRET
docker compose up --build

App: http://localhost:8080

API Overview

All endpoints live under /api/v1.

Method	Path	Auth	Description
GET	/health	None	Health check
POST	/auth/login	None	Obtain tokens
POST	/auth/refresh	None	Rotate refresh token
POST	/auth/logout	Bearer	Invalidate tokens
GET	/auth/me	Bearer	Current user info
GET	/vendors	Bearer	List vendor
PUT	/vendors/:id	owner	Update vendor settings
GET	/users	manager+	List users
POST	/users	manager+	Create user
PUT	/users/:id	manager+	Update user
DELETE	/users/:id	manager+	Delete user
GET	/users/roles/list	Bearer	List available roles
GET/POST/PUT/DELETE	/categories, /taxes, /products	manager+	Catalog CRUD
GET	/catalog/sync?since=	Bearer	Delta sync for Android
POST	/transactions/batch	Bearer	Batch upload (idempotent)
GET	/transactions	manager+	List transactions
GET	/transactions/:id	manager+	Get transaction detail
POST	/transactions/:id/refund	manager+	Refund a completed transaction
GET	/transactions/:id/receipt	Bearer	Structured receipt payload
GET	/transactions/reports/summary	manager+	Revenue/tax/top-product summary
GET	/transactions/reports/shift	manager+	Shift window totals + avg tx value

Environment Variables

Variable	Required	Default	Description
PORT	No	8080	HTTP port
NODE_ENV	No	development	`development` or `production`
DATABASE_URL	Yes	—	Prisma connection string
JWT_SECRET	Yes	—	Secret for signing JWT tokens
LOG_LEVEL	No	info	Logging verbosity
CORS_ORIGIN	No	*	Allowed CORS origin

For SQLite: DATABASE_URL=file:./dev.db For Postgres: DATABASE_URL=postgresql://user:pass@host:5432/db

Database Migrations

# Create a new migration (dev only)
cd server && npx prisma migrate dev --name <migration-name>

# Apply pending migrations (production)
cd server && npx prisma migrate deploy

# Open Prisma Studio (GUI)
cd server && npx prisma studio

4.6 KiB Raw Blame History