Server health status (for the monitoring card in the admin panel)

cmd/main.go. Public, no auth — deliberately lightweight (2s DB ping timeout) so it's safe to poll every few seconds. Returns HTTP 200 when status=ok, HTTP 503 when status=degraded (mirrors the existing /readyz convention). Redis isn't wired into the app yet (see docs/redis-caching-plan.md) — checks.redis always reports not_configured rather than opening a new connection just for this endpoint.

Responses

Owner login with identifier and password

Authenticate owner via identifier (email OR klay_id) + password. Account must have been created by Skalar admin during onboarding. Success = access token in body, refresh token in httpOnly cookie. Response data contains only access_token (no nested user object).

Request body

{
  "identifier": "string",
  "password": "string"
}

Responses

Owner login with Google OAuth (NOT IMPLEMENTED)

Handler currently returns 501 Not Implemented (auth/handler.go GoogleLogin). Google OAuth login is not yet wired. The 200/403 entries below are the intended contract but not yet built: called by NextAuth after Google OAuth succeeds, server verifies the email is registered as an owner, then issues its own Klay JWT.

Request body

{
  "email": "owner@klay.id",
  "name": "string"
}

Responses

Refresh access token

Reads refresh token from httpOnly cookie, issues a new access token.

Responses

Logout

Clears the refresh token httpOnly cookie.

Responses

Profile of the currently authenticated owner

Returns the owner's profile along with associated business data.

Responses

Update owner profile

Owner can update name or phone. Email cannot be changed (Skalar admin only).

Request body

{
  "full_name": "string",
  "phone": "string"
}

Responses

Business details for the authenticated owner

Responses

Update business info (restricted)

Owner can only update display fields. Plan, features, max_operators, status, and xendit_status are Skalar admin-only fields.

Request body

{
  "business_name": "string",
  "phone": "string",
  "address": "string",
  "city": "string",
  "country": "string",
  "qris_string": "string",
  "category": "string"
}

Responses

List business operators

Lists operators with quota info. qr_token is not returned in the list — only on create and regenerate.

Responses

Add a new operator

Owner-only. Cap is validated against business.max_operators (default 3, admin updates if add-on purchased, -1 = unlimited). Body contains only name; server generates operator_code (KL-XXXXX), PIN, and qr_token. operator_code and credentials (qr_token/pin) are returned only in this create/regenerate response (one-time).

Request body

{
  "name": "string"
}

Responses

Get a single operator

Parameters

Responses

Update operator (partial)

Owner updates name or is_active. Password and QR reset are handled by separate endpoints.

Parameters

Request body

{
  "name": "string",
  "is_active": true
}

Responses

Delete operator (soft delete)

Soft delete — deleted_at is set, row remains. operator_code is NOT released (stored in row, unique index slot consumed). Operator can no longer log in. Active operator slot count decreases (COUNT is_active drops). Historical data remains valid.

Parameters

Responses

Regenerate operator qr_token

Issues a new qr_token. The old QR is invalid for new logins, but any currently active JWT sessions remain valid until the access token expires.

Parameters

Responses

Get operator_code and qr_token

Owner-only. Returns the current operator_code and qr_token to re-render the QR in the dashboard without regenerating.

Parameters

Responses

Rotate operator credentials

Owner-only. Re-issues the operator's qr_token and PIN. New credentials are returned only once (one-time) in this response.

Parameters

Responses

Force logout operator

Owner-only. Revokes the operator's active session (revoke refresh token). Returns 204 No Content on success.

Parameters

Responses

Operator login with credentials

Public endpoint. identifier (business email or klay_id) resolves the business; operator is looked up via operator_code + PIN.

Request body

{
  "identifier": "string",
  "operator_code": "string",
  "pin": "string"
}

Responses

Operator login with QR scan

Public endpoint. qr_token is static, regenerated via owner.

Request body

{
  "qr_token": "string"
}

Responses

Profile of the currently authenticated operator (PWA)

Responses

List business products

Owner & operator (RequireOperator) can GET. Handler only uses business_id from JWT; no query filter/sort/search is processed by the server.

Responses

Add product (owner only)

RequireOwner. business_id is taken from JWT, not the body.

Request body

Responses

Get product details

Owner & operator (RequireOperator).

Parameters

Responses

Update product (owner only, partial)

RequireOwner. Partial update — fields not sent remain unchanged.

Parameters

Request body

Responses

Delete product (owner only)

RequireOwner.

Parameters

Responses

List orders for the authenticated operator

order.ListMyOrders (RequireOperator). Only orders belonging to the operator from JWT. If called as owner (operator_id empty) returns an empty array. Response is a Transaction array directly in `data`, NOT a paginated object.

Responses

Create a new order (status DRAFT)

order.CreateOrder (RequireOperator). Initial status is DRAFT. Backend calculates total_amount from items and snapshots product_name + unit_price into order_items. operator_id is taken from JWT (nullable if owner).

Request body

{
  "items": [
    {
      "product_id": "string",
      "quantity": 0
    }
  ],
  "note": "string"
}

Responses

Replace items in a DRAFT order

order.UpdateItems (RequireOperator). Only valid when status is DRAFT.

Parameters

Request body

{
  "items": [
    {
      "product_id": "string",
      "quantity": 0
    }
  ],
  "note": "string"
}

Responses

Begin checkout (DRAFT -> PENDING)

order.BeginCheckout (RequireOperator). Stamps checkout_started_at and moves status to PENDING. No request body. Must be called before confirm — confirming without begin yields ErrCheckoutNotStarted (400).

Parameters

Responses

Confirm checkout (PENDING -> CONFIRMED)

order.ConfirmCheckout (RequireOperator). Body requires `payment_method`. Server rejects if begin-checkout was not called (ErrCheckoutNotStarted) or gesture was too fast <800ms since checkout_started_at (ErrGestureTooFast). Stamps confirmed_at + confirmed_by (string), then triggers consumption_log from product.recipe. Response includes qris_string when payment is QRIS_STATIC.

Parameters

Request body

{
  "payment_method": null
}

Responses

Void order (operator)

order.VoidOrder (RequireOperator). No request body. Returns response.NoContent = HTTP 200 with body {"success":true} (NOT 204).

Parameters

Responses

Void order (owner)

order.VoidOrderByOwner (RequireOwner). Write mutation in the order domain but mounted at /transactions/{id}/void. Body requires `void_reason`. Owner identity is taken from user_id JWT. Returns response.NoContent = HTTP 200 with {"success":true} (NOT 204).

Parameters

Request body

{
  "void_reason": "string"
}

Responses

Business transaction list (read-only log)

transaction.List (RequireOwner). Read-only history. status query accepts only DRAFT/CONFIRMED/VOIDED — PENDING is rejected 400 by list-filter validation.

Parameters

Responses

Transaction details

transaction.GetByID (RequireOperator). Returns OrderWithItems (Transaction + items[]).

Parameters

Responses

Transaction list for the authenticated operator

transaction.OperatorList (RequireOperatorOnly). Operator-scoped — only transactions from the operator in JWT. Filters: start_date, end_date, page, limit (no status/payment_method/operator_id filter on this endpoint).

Parameters

Responses

Business performance summary

Dashboard aggregate. Counts CONFIRMED status only.

Parameters

Responses

Daily transaction trend

Parameters

Responses

Top-selling products

Parameters

Responses

Peak hour distribution

Parameters

Responses

Analytics overview for custom date range

Used on the Analytics page, supports custom timeframes and period comparison.

Parameters

Responses

Daily sales report

Aggregates CONFIRMED transactions per day for a given date.

Parameters

Responses

Monthly sales report

Parameters

Responses

Raw material consumption report

Aggregates consumption_log per ingredient for a period. Foundation for owner restock decisions and downstream AI insights.

Parameters

Responses

Export report to PDF or CSV

Generates a file download. Server returns a temporary URL or streams directly. Report type and period are passed via body.

Request body

{
  "type": "daily_sales",
  "format": "pdf",
  "period": {}
}

Responses

List insight cards

Rule-based MVP. Schema is ready for model_version + confidence if later switching to an AI engine.

Responses

Admin Skalar login via Google OAuth

core/adminauth. Frontend gets a Google ID token (credential) from Google Sign-In and posts it here. Server verifies the token against Google (signature + audience == GOOGLE_CLIENT_ID), extracts the verified email, and checks it against ADMIN_WHITELIST_EMAILS (env var, comma-separated — no DB table, parsed once into an in-memory set). No match -> 403, no token issued. Match -> admin JWT issued (access_token in body, refresh token via httpOnly "admin_refresh_token" cookie — separate cookie name from owner/operator's "refresh_token" so sessions can't collide if both panels share a browser/cookie domain). Logs admin.login to audit_logs.

Request body

{
  "credential": "string"
}

Responses

Refresh admin access token

Responses

Admin logout

core/adminauth. Public — no Bearer required (same pattern as owner /auth/logout): reads the admin_refresh_token cookie, best-effort deletes it server-side, always clears the cookie. Idempotent — calling it with no cookie still returns 200.

Responses

Identity of the admin from the active session

core/adminauth. Used by the FE to check the session. Pure JWT-claims read, no DB call — email and name both come from the Google-verified token at login time and are embedded in the JWT itself (there's no admin identity row to look up). Reflects whatever Google returned at login, not live data — if an admin's Google profile name changes, /me won't show it until they log in again.

Responses

List all owners (cross-merchant)

Admin view. handler.ListOwners — accepts only page and limit. Status/plan/q filters are not processed by the server (admin/handler.go).

Parameters

Responses

Onboard a new merchant

Creates Business + User owner in one operation. Body matches admin/model.go CreateBusinessRequest. business_id is server-generated.

Request body

Responses

Owner details

Parameters

Responses

Update business info owner (admin-controlled fields)

Matches admin/model.go UpdateBusinessRequest. Fields not sent remain unchanged. merchant_status enum: PENDING | REGISTERED | ACTIVE | SUSPENDED.

Parameters

Request body

Responses

Toggle aktif/suspend owner

handler.SetOwnerStatus — boolean toggle. enabled=true activates, enabled=false suspends. Returns HTTP 200 { success: true } via response.NoContent().

Parameters

Request body

{
  "enabled": true
}

Responses

Set owner login credentials (email and/or password)

handler.SetOwnerCredential. email is optional (must be valid format if provided). password is required, min 6 characters. Returns HTTP 200 { success:true } via response.NoContent().

Parameters

Request body

{
  "email": "owner@klay.id",
  "password": "string"
}

Responses

List products for the business

handler.ListOwnerProducts. Response wraps products inside an object { products: [...] } (not a direct array).

Parameters

Responses

Add a product for the business

handler.CreateProduct. Body matches admin/model.go AdminCreateProductRequest. business_id is taken from the path param, not the body.

Parameters

Request body

Responses

Product details (including recipe)

handler.GetProduct. Returns AdminProductDetail which includes the recipe array.

Parameters

Responses

Update produk (partial)

handler.UpdateProduct. Body matches admin/model.go AdminUpdateProductRequest. All fields are optional (pointer) — fields not sent remain unchanged.

Parameters

Request body

Responses

Delete product

handler.DeleteProduct. Soft delete if product already exists in historical transactions. Returns HTTP 200 { success:true } via response.NoContent() (NOT 204).

Parameters

Responses

Replace recipe produk

handler.UpdateProductRecipe. Replaces the entire recipe array (not a merge). Returns HTTP 200 { success:true } via response.NoContent() (NOT 204).

Parameters

Request body

{
  "recipe": [
    null
  ]
}

Responses

Remove operator on merchant request

handler.DeleteOperator. Admin can only REMOVE operator on request. No request body — handler does not read body (admin/handler.go). Returns HTTP 200 { success:true } via response.NoContent() (NOT 204).

Parameters

Responses

List transaksi cross-merchant

handler.ListTransactions. Filter yang diproses: status (string), business_id (uuid), start_date (YYYY-MM-DD, filter created_at >= start), end_date (YYYY-MM-DD, filter created_at < end+1day), page (default 1), limit (default 20, max 100).

Parameters

Responses

Void transaksi (admin)

handler.VoidTransaction. Tidak ada request body — handler tidak membaca body. Returns HTTP 200 { success:true } via response.NoContent() (BUKAN 204). 409 dikembalikan jika transaksi bukan status PENDING/CONFIRMED (tidak bisa di-void).

Parameters

Responses

Run a single read-only SELECT query (SQL console)

core/adminquery. Guarded, not a general SQL endpoint: rejects anything that isn't a single SELECT/WITH statement (write CTEs, SELECT ... INTO, FOR UPDATE/SHARE, dangerous function calls like pg_terminate_backend, and multi-statement input via ';' are all rejected before reaching the database). Executes inside a Postgres READ ONLY transaction as a second, DB-enforced layer beyond the text guard, with SET LOCAL statement_timeout=5s and the query outer-wrapped in "SELECT * FROM (...) LIMIT 1000" so returned rows are bounded regardless of what the inner query requested. Every submitted query is audit-logged (action: admin.query, query text + outcome in metadata) — including ones the guard blocked, since a blocked destructive attempt is itself worth having on record. Errors (guard rejection or a real Postgres error — syntax, unknown column, timeout) are returned verbatim in `error`: this is a debugging tool for a trusted, whitelisted admin, not a public surface, so hiding SQL errors would make it useless.

Request body

{
  "query": "string"
}

Responses

Report one PWA install/version heartbeat

core/telemetry. Called by klay-app (owner + operator apps; entry has no authenticated session so it never calls this) once per session boot plus occasionally while active. Upserts app_installs keyed on (business_id, app, device_id) — business_id comes from the authenticated JWT claim, NOT from the request body, so a client can't report installs against a merchant it doesn't belong to. device_id is a client-generated pseudonymous fingerprint (crypto.randomUUID(), persisted in localStorage) — never a real device or personal identifier. No transaction/order data travels this path. Best-effort on the client: failures are swallowed there, never surfaced to the user.

Request body

Responses

Aggregated PWA distribution stats for the admin panel

core/telemetry. Powers klay-admin's Distribution page. JWT RequireAdmin only — same pattern as /admin/query, no X-Admin-Key required. Returns total installs, breakdown by app, breakdown by app version, breakdown by merchant, and a list of devices that haven't reported in `stale_after_days` days (churn/uninstall signal, capped at 100 rows).

Parameters

Responses