@hasna/microservices 0.0.15 → 0.0.17

package/README.md

@@ -1,189 +1,171 @@
 # @hasna/microservices
 
-Mini business apps for AI agents. Each microservice has its own SQLite database, CLI, and MCP server.
+> Production-grade microservice building blocks for SaaS apps.
+
+Each microservice is an **independent npm package** with its own PostgreSQL schema, HTTP API, MCP server, and CLI binary. Install only what you need. Plug into any app.
+
+[![npm](https://img.shields.io/npm/v/@hasna/microservices)](https://www.npmjs.com/package/@hasna/microservices)
+
+## The 8 Microservices
+
+| Package | Binary | Schema | What it does |
+|---------|--------|--------|--------------|
+| `@hasna/microservice-auth` | `microservice-auth` | `auth.*` | Users, sessions, JWT, magic links, OAuth, 2FA, API keys |
+| `@hasna/microservice-teams` | `microservice-teams` | `teams.*` | Workspaces, members, RBAC (owner/admin/member/viewer), invites |
+| `@hasna/microservice-billing` | `microservice-billing` | `billing.*` | Stripe subscriptions, plans, invoices, usage-based billing |
+| `@hasna/microservice-notify` | `microservice-notify` | `notify.*` | Email, SMS, in-app, outbound webhooks, templates |
+| `@hasna/microservice-files` | `microservice-files` | `files.*` | Uploads, S3 storage, presigned URLs, image transforms |
+| `@hasna/microservice-audit` | `microservice-audit` | `audit.*` | Immutable event log, compliance trail, retention policies |
+| `@hasna/microservice-flags` | `microservice-flags` | `flags.*` | Feature flags, gradual rollouts, A/B experiments |
+| `@hasna/microservice-jobs` | `microservice-jobs` | `jobs.*` | Background jobs, priority queues (SKIP LOCKED), cron, retries |
 
 ## Install
 
 ```bash
+# Install one or more
+bun install -g @hasna/microservice-auth @hasna/microservice-teams
+
+# Or use the hub CLI to manage all
 bun install -g @hasna/microservices
+microservices install auth teams billing
 ```
 
-## Setup MCP Server
-
-Register with all AI coding agents in one command:
+## Quick Start
 
 ```bash
-microservices mcp --register all
+# 1. Install a service
+bun install -g @hasna/microservice-auth
+
+# 2. Run migrations against your PostgreSQL
+microservice-auth migrate --db postgres://localhost/myapp
+
+# 3. Start the HTTP API (standalone mode)
+microservice-auth serve --port 3001
+
+# 4. Or start the MCP server (for AI agents)
+microservice-auth mcp
 ```
 
-Or register individually:
+## Two Modes: Embedded or Standalone
 
-```bash
-microservices mcp --register claude    # Claude Code
-microservices mcp --register codex     # Codex CLI
-microservices mcp --register gemini    # Gemini CLI
+### Embedded — import in your app
+
+```ts
+import { migrate, register, login } from '@hasna/microservice-auth'
+
+const sql = getDb('postgres://localhost/myapp')
+await migrate(sql)
+
+const { user, access_token, session } = await register(sql, {
+  email: 'user@example.com',
+  password: 'secure-password',
+})
 ```
 
-**Manual setup** if you prefer:
+### Standalone — run as HTTP service
 
-<details>
-<summary>Claude Code (~/.claude.json)</summary>
+```bash
+microservice-auth serve --port 3001
+# POST http://localhost:3001/auth/register
+# POST http://localhost:3001/auth/login
+# GET  http://localhost:3001/auth/session
+```
 
-```json
-{
-  "mcpServers": {
-    "microservices": {
-      "type": "stdio",
-      "command": "microservices-mcp",
-      "args": [],
-      "env": {}
-    }
-  }
-}
+## Complete SaaS Stack Example
+
+```ts
+import { register } from '@hasna/microservice-auth'
+import { createWorkspace, checkPermission } from '@hasna/microservice-teams'
+import { createCheckoutSession } from '@hasna/microservice-billing'
+import { sendNotification } from '@hasna/microservice-notify'
+import { logEvent } from '@hasna/microservice-audit'
+import { evaluateFlag } from '@hasna/microservice-flags'
+import { enqueue } from '@hasna/microservice-jobs'
+
+const { user, access_token } = await register(sql, { email, password })
+const workspace = await createWorkspace(sql, { name: 'My Company', ownerId: user.id })
+const checkout = await createCheckoutSession({ workspaceId: workspace.id, planId, successUrl, cancelUrl, stripeSecretKey })
+await sendNotification(sql, { userId: user.id, channel: 'email', type: 'welcome', body: 'Welcome!' })
+await logEvent(sql, { actorId: user.id, action: 'user.registered', resourceType: 'user', resourceId: user.id })
+const { value } = await evaluateFlag(sql, 'new-onboarding', { userId: user.id })
+await enqueue(sql, { type: 'onboarding.setup', payload: { userId: user.id } })
 ```
-</details>
 
-<details>
-<summary>Codex CLI (~/.codex/config.toml)</summary>
+## Environment Variables
+
+| Variable | Used by | Required |
+|----------|---------|----------|
+| `DATABASE_URL` | All services | Yes |
+| `JWT_SECRET` | auth | Yes |
+| `STRIPE_SECRET_KEY` | billing | Yes |
+| `STRIPE_WEBHOOK_SECRET` | billing | Yes |
+| `RESEND_API_KEY` | notify (email) | Optional |
+| `TWILIO_ACCOUNT_SID` | notify (SMS) | Optional |
+| `S3_BUCKET` | files | Optional (falls back to local) |
+| `GITHUB_CLIENT_ID` | auth (OAuth) | Optional |
+| `GOOGLE_CLIENT_ID` | auth (OAuth) | Optional |
 
-```toml
-[mcp_servers.microservices]
-command = "microservices-mcp"
+## Hub CLI
+
+```bash
+microservices list                    # List all available microservices
+microservices install auth teams      # Install specific services
+microservices install --all           # Install all 8
+microservices status                  # Check what's installed
+microservices info auth               # Detailed info + required env
+microservices migrate-all             # Run migrations on all installed
+microservices run auth status         # Run any CLI command on a service
+microservices search stripe           # Search by keyword
 ```
-</details>
 
-<details>
-<summary>Gemini CLI (~/.gemini/settings.json)</summary>
+## Hub MCP Server
+
+For AI agents — add to your Claude config:
 
 ```json
 {
   "mcpServers": {
     "microservices": {
-      "command": "microservices-mcp",
-      "args": []
+      "command": "microservices-mcp"
     }
   }
 }
 ```
-</details>
 
-## Quick Start
+Tools: `list_microservices`, `search_microservices`, `install_microservice`, `microservice_status`, `run_microservice_command`, `remove_microservice`, `get_microservice_info`
 
-```bash
-# Browse available microservices
-microservices
+## PostgreSQL Schema Isolation
 
-# Install microservices
-microservices install contacts invoices
+Each service owns its schema — all on one PostgreSQL instance:
 
-# Run commands
-microservices run contacts add --first-name "John" --last-name "Doe" --email "john@acme.com"
-microservices run contacts list --json
-microservices run invoices create --due 2026-04-01
-microservices run invoices add-item --invoice INV-00001 --description "Consulting" --price 5000
-
-# Check status
-microservices status
 ```
-
-## Available Microservices
-
-| Name | Category | Description |
-|------|----------|-------------|
-| `contacts` | CRM | Contacts, companies, and relationships |
-| `invoices` | Finance | Invoices with line items, clients, and payments |
-| `bookkeeping` | Finance | Double-entry bookkeeping |
-| `expenses` | Finance | Expense tracking and categorization |
-| `crm` | CRM | Sales pipeline with stages, deals, and activities |
-| `inventory` | Operations | Products, stock levels, and movements |
-| `notes` | Productivity | Structured notes with tags and search |
-| `calendar` | Productivity | Events, reminders, and scheduling |
-| `documents` | Productivity | Document metadata and versioning |
-| `timesheets` | HR | Time tracking per project and client |
+auth.*     teams.*     billing.*   notify.*
+files.*    audit.*     flags.*     jobs.*
+```
 
 ## Architecture
 
-```
-.microservices/
-├── microservice-contacts/
-│   ├── data.db              # SQLite database (WAL mode)
-│   └── src/                 # Service source code
-│       ├── db/              # Database layer (CRUD + migrations)
-│       ├── cli/             # CLI interface (Commander.js)
-│       └── mcp/             # MCP server (per-service)
-├── microservice-invoices/
-│   ├── data.db
-│   └── src/
-└── ...
-```
+- **Runtime**: Bun
+- **Database**: PostgreSQL (per-service schemas, migrations built-in)
+- **API**: Bun HTTP server (standalone mode)
+- **MCP**: `@modelcontextprotocol/sdk` (for AI agents)
+- **CLI**: Commander
+- **Auth crypto**: Web Crypto API (no external crypto deps)
+- **Stripe**: Direct `fetch()` calls (no Stripe SDK)
+- **S3**: Manual SigV4 signing via Web Crypto
 
-Each microservice:
-- Has its **own SQLite database** — no shared state
-- Exposes a **CLI** for direct use
-- Exposes an **MCP server** for AI agents
-- Manages its own **migrations**
-
-## CLI Commands
+## Development
 
 ```bash
-microservices                          # Interactive TUI
-microservices list                     # List all available
-microservices list --installed         # List installed only
-microservices search <query>           # Search by name/description
-microservices install <names...>       # Install microservices
-microservices remove <name>            # Remove (preserves data)
-microservices info <name>              # Show details
-microservices status                   # Show installed + DB sizes
-microservices categories               # List categories
-microservices run <name> [args...]     # Run a microservice command
-microservices ops <name>               # Show available operations
+bun install && bun test   # 127 tests, 0 failures
 ```
 
-## MCP Server
+With a real database:
 
 ```bash
-# Hub MCP (management)
-microservices-mcp
-
-# Per-service MCP (after install)
-bun run .microservices/microservice-contacts/src/mcp/index.ts
-bun run .microservices/microservice-invoices/src/mcp/index.ts
-```
-
-### Hub MCP Tools
-
-| Tool | Description |
-|------|-------------|
-| `search_microservices` | Search by name or keyword |
-| `list_microservices` | List with optional category filter |
-| `list_categories` | Categories with counts |
-| `microservice_info` | Metadata + install status + DB info |
-| `install_microservice` | Install to .microservices/ |
-| `remove_microservice` | Remove (data preserved by default) |
-| `list_installed` | Installed services with status |
-| `run_microservice` | Execute a command on a service |
-| `list_microservice_operations` | Discover available commands |
-
-## Library API
-
-```typescript
-import {
-  MICROSERVICES,
-  searchMicroservices,
-  installMicroservice,
-  runMicroserviceCommand,
-} from "@hasna/microservices";
-
-// Search
-const results = searchMicroservices("finance");
-
-// Install
-installMicroservice("contacts");
-
-// Run
-const output = await runMicroserviceCommand("contacts", ["list", "--json"]);
+DATABASE_URL=postgres://localhost/test_ms JWT_SECRET=test-secret bun test src/integration.test.ts
 ```
 
 ## License
 
-Apache-2.0
+Apache-2.0 — [Hasna](https://hasna.com)