125 lines
3.3 KiB
Markdown
125 lines
3.3 KiB
Markdown
# Template Studio
|
|
|
|
Mobile-first email template and report builder for Arrowstack applications.
|
|
|
|
## Current MVP
|
|
|
|
- PWA designed from 320px upward
|
|
- tap-to-add and tap-to-edit block workflow
|
|
- local IndexedDB draft persistence plus debounced server autosave
|
|
- report and email template profiles
|
|
- sample JSON data and variable bindings
|
|
- MJML email rendering
|
|
- HTML and A4 PDF report rendering
|
|
- immutable publish versions
|
|
- stable template keys for consuming apps
|
|
- server-side Keycloak OIDC authorization-code + PKCE flow
|
|
- authenticated published-template API
|
|
- revocable hashed API keys
|
|
- PostgreSQL persistence
|
|
|
|
## Consumer API
|
|
|
|
Drafts are editor-only. Consuming apps can only retrieve or render published versions.
|
|
|
|
List published templates:
|
|
|
|
```http
|
|
GET /api/v1/templates
|
|
X-API-Key: ts_live_...
|
|
```
|
|
|
|
Pull one published template:
|
|
|
|
```http
|
|
GET /api/v1/templates/{template-key}
|
|
X-API-Key: ts_live_...
|
|
```
|
|
|
|
Render it with runtime data:
|
|
|
|
```http
|
|
POST /api/v1/templates/{template-key}/render
|
|
X-API-Key: ts_live_...
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"format": "pdf",
|
|
"data": {
|
|
"customer": {
|
|
"name": "Example Customer"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Email templates accept `format: "email"` and return rendered HTML. Reports accept `html` or `pdf`.
|
|
|
|
### Authentication
|
|
|
|
Anonymous access is rejected.
|
|
|
|
Two machine authentication modes are supported:
|
|
|
|
1. `X-API-Key` using a key generated from the Template Studio **Use** screen. Keys are displayed once and stored only as SHA-256 hashes.
|
|
2. `Authorization: Bearer <token>` using the Keycloak machine client `template-studio-api`.
|
|
|
|
For another Arrowstack/Coolify application, prefer OAuth. The Arrowstack MCP secret broker can inject the existing `template-studio-api` client credentials directly into the consuming application without returning the client secret.
|
|
|
|
## Local development
|
|
|
|
Copy `.env.example` to `.env`, provide a PostgreSQL database, and leave `AUTH_REQUIRED=false` for local-only development.
|
|
|
|
```bash
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
The production deployment uses Arrowstack MCP to inject `DATABASE_URL`, `KEYCLOAK_ISSUER`, `KEYCLOAK_CLIENT_ID`, and `KEYCLOAK_CLIENT_SECRET`. Never commit real credentials.
|
|
|
|
## Production
|
|
|
|
Canonical public repository:
|
|
|
|
```text
|
|
https://git.arrowstack.dev/Admin/template-studio
|
|
```
|
|
|
|
Production URL:
|
|
|
|
```text
|
|
https://templates.arrowstack.dev
|
|
```
|
|
|
|
|
|
## MCP authoring endpoint
|
|
|
|
Template Studio exposes a Keycloak-protected Streamable HTTP MCP endpoint at:
|
|
|
|
```text
|
|
https://templates.arrowstack.dev/mcp
|
|
```
|
|
|
|
This endpoint is separate from the published-template consumer API and from the browser editor session. It accepts only:
|
|
|
|
```http
|
|
Authorization: Bearer <Keycloak access token>
|
|
```
|
|
|
|
The token must be issued by the configured Keycloak realm and its `azp` client ID must appear in `TEMPLATE_MCP_ALLOWED_CLIENTS`. API keys and browser cookies are intentionally not accepted for MCP authoring.
|
|
|
|
The endpoint exposes these tools:
|
|
|
|
- `templates_list`
|
|
- `template_get`
|
|
- `template_create`
|
|
- `template_update_draft`
|
|
- `template_publish`
|
|
- `folders_list`
|
|
- `folder_create`
|
|
- `template_move`
|
|
|
|
`template_update_draft` accepts `expected_updated_at`; callers should pass the value returned by `template_get` to detect concurrent edits instead of silently overwriting them.
|
|
|
|
The MCP surface does not expose API-key management, authentication administration, template deletion, or arbitrary database access.
|