# 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.