Morph API Client

Config-driven, multi-context HTTP client with built-in OAuth2 token lifecycle management.

Quick start

Prerequisites: Docker, Node.js 20+, python3, curl

First time setup

make install        # install all npm dependencies
make build          # build all SDK packages
cp poc/ts-vue/.env.example poc/ts-vue/.env   # create env with client secrets
make up             # start Keycloak + setup + mock API + Vue dev server

Day-to-day

make up             # start full stack (Keycloak -> setup -> mock API -> Vue)
make down           # stop everything

Opens http://127.0.0.1:5173/ (Vue PoC). Run make help to see all targets.

Makefile targets

Target	Description
make install	Install npm deps for all packages, Vue PoC, and mock API
make build	Build all SDK packages (core -> oauth2 -> browser-storage)
make up	Start full stack: Keycloak -> setup -> mock API -> Vue
make down	Stop all services
make dev	Start Vue dev server only (http://127.0.0.1:5173)
make mock-api	Start mock API server only (http://localhost:3000)
make keycloak-up	Start Keycloak container (port 8080)
make keycloak-down	Stop Keycloak container
make keycloak-setup	Run realm setup (clients, redirects, lifetimes, tests)
make keycloak-test	Run OAuth2 flow smoke tests
make keycloak-logs	Tail Keycloak logs
make keycloak-short-tokens	Apply short token lifetimes (15s/30s/20s)
make keycloak-restore-tokens	Restore long-lived token lifetimes
make clean	Remove node_modules and dist

Services

Service	URL
Vue PoC	http://127.0.0.1:5173
Mock API	http://localhost:3000
Keycloak Admin	http://localhost:8080/admin (admin/admin)

Documentation

See docs/README.md for the full documentation index.

Document	Description
Overview	System architecture, auth flow diagrams, Keycloak client mapping
PoC Guide	Step-by-step walkthrough of the Vue PoC app
Troubleshooting	Common errors and fixes
Getting Started	SDK installation and basic usage
Writing Plugins	How to create custom plugins (auth, storage, or utility)
Configuration	Full config field reference
API Reference	Complete public API
Architecture	Internal design and module structure
Dart parity	Dart/Flutter SDK roadmap (scaffold under packages/dart/morph_core)

Layout

Path	Package	Role
packages/ts/core/	@morph/core	Types, config, HTTP pipeline, MorphClient, AuthHandle
packages/ts/oauth2/	@morph/oauth2	TokenLifecycle, TokenVault, OAuth helpers
packages/ts/browser-storage/	@morph/browser-storage	sessionStorage / localStorage adapters
packages/ts/logger/	@morph/logger	Structured logging and HTTP trace plugin
packages/dart/morph_core/	morph_core	Dart — config validation + indexes (parity with TS validate.ts); runtime/OAuth TBD — docs/dart-parity.md
poc/ts-vue/		Vue 3 demo app
poc/keycloak/		Docker Keycloak realm + setup/test scripts
poc/mock-api/		Mock REST API (Express, validates JWT)
docs/		Design & API docs