{
  "openapi": "3.0.3",
  "info": {
    "title": "MetaTerminal Facade API",
    "version": "26.5.10-unstable",
    "description": "Typed public facade over the current MetaTerminal runtime. The facade keeps a stable contract while the legacy impress API remains an internal implementation detail."
  },
  "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Token" } }, "schemas": {} },
  "paths": {
    "/v1/healthz": {
      "get": {
        "operationId": "systemHealth",
        "summary": "Facade health check",
        "tags": ["System"],
        "description": "Simple health endpoint for the TypeScript facade service.",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data"],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": ["status", "service", "version"],
                      "properties": {
                        "status": { "description": "Health indicator", "type": "string", "enum": ["ok"] },
                        "service": { "description": "Service name", "type": "string", "enum": ["facade"] },
                        "version": { "description": "Public API version", "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/auth/sign-in": {
      "post": {
        "operationId": "authSignIn",
        "summary": "Authenticate user via the legacy backend and issue facade bearer token",
        "tags": ["Auth"],
        "description": "Validates user credentials against the legacy auth API, then returns a facade bearer token backed by the shared terminal_tokens session store.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "description": "Credentials used to create a facade bearer token",
                "type": "object",
                "required": ["login", "password"],
                "properties": {
                  "login": {
                    "minLength": 1,
                    "description": "User login used by the legacy auth backend",
                    "type": "string",
                    "example": "demo@example.com"
                  },
                  "password": {
                    "minLength": 1,
                    "description": "Plain-text password for the user account",
                    "type": "string",
                    "example": "secret"
                  }
                }
              }
            }
          },
          "description": "Credentials used to create a facade bearer token"
        },
        "responses": {
          "200": {
            "description": "Successful authentication response",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Successful authentication response",
                  "type": "object",
                  "required": ["data"],
                  "properties": {
                    "data": {
                      "description": "Created facade session",
                      "type": "object",
                      "required": ["accessToken", "tokenType", "user"],
                      "properties": {
                        "accessToken": { "description": "Facade bearer token backed by the shared session table", "type": "string" },
                        "tokenType": { "description": "Authorization scheme for the access token", "type": "string", "enum": ["Bearer"] },
                        "user": {
                          "description": "Normalized facade user",
                          "type": "object",
                          "required": ["id", "login", "type"],
                          "properties": {
                            "id": {
                              "description": "Internal user identifier from the shared session store",
                              "anyOf": [{ "type": "integer" }, { "type": "string" }]
                            },
                            "login": { "description": "Login of the authenticated user", "type": "string" },
                            "type": {
                              "description": "User type from the legacy auth model",
                              "anyOf": [{ "type": "string" }, { "type": "null" }]
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["error"],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": ["code", "message"],
                      "properties": {
                        "code": { "description": "Stable machine-readable error code", "type": "string" },
                        "message": { "description": "Human-readable error message", "type": "string" },
                        "details": {
                          "description": "Optional structured details from the facade or upstream systems",
                          "anyOf": [
                            { "additionalProperties": true, "type": "object", "properties": {} },
                            { "type": "array", "items": {} },
                            { "type": "string" },
                            { "type": "null" }
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["error"],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": ["code", "message"],
                      "properties": {
                        "code": { "description": "Stable machine-readable error code", "type": "string" },
                        "message": { "description": "Human-readable error message", "type": "string" },
                        "details": {
                          "description": "Optional structured details from the facade or upstream systems",
                          "anyOf": [
                            { "additionalProperties": true, "type": "object", "properties": {} },
                            { "type": "array", "items": {} },
                            { "type": "string" },
                            { "type": "null" }
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["error"],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": ["code", "message"],
                      "properties": {
                        "code": { "description": "Stable machine-readable error code", "type": "string" },
                        "message": { "description": "Human-readable error message", "type": "string" },
                        "details": {
                          "description": "Optional structured details from the facade or upstream systems",
                          "anyOf": [
                            { "additionalProperties": true, "type": "object", "properties": {} },
                            { "type": "array", "items": {} },
                            { "type": "string" },
                            { "type": "null" }
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/auth/sign-out": {
      "post": {
        "operationId": "authSignOut",
        "summary": "Delete the current facade token from the shared session store",
        "tags": ["Auth"],
        "description": "Deletes the current token from the shared session store and clears the facade cookie if it was present in the request.",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data"],
                  "properties": { "data": { "type": "object", "required": ["ok"], "properties": { "ok": { "type": "boolean" } } } }
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["error"],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": ["code", "message"],
                      "properties": {
                        "code": { "description": "Stable machine-readable error code", "type": "string" },
                        "message": { "description": "Human-readable error message", "type": "string" },
                        "details": {
                          "description": "Optional structured details from the facade or upstream systems",
                          "anyOf": [
                            { "additionalProperties": true, "type": "object", "properties": {} },
                            { "type": "array", "items": {} },
                            { "type": "string" },
                            { "type": "null" }
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/me": {
      "get": {
        "operationId": "authRefresh",
        "summary": "Resolve current user from the shared session store",
        "tags": ["Auth"],
        "description": "Reads the current bearer token or token cookie, resolves the shared session from Postgres, and returns a normalized user object.",
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": {
            "description": "Current authenticated user",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Current authenticated user",
                  "type": "object",
                  "required": ["data"],
                  "properties": {
                    "data": {
                      "type": "object",
                      "allOf": [
                        {
                          "type": "object",
                          "required": ["user"],
                          "properties": {
                            "user": {
                              "description": "Normalized facade user",
                              "type": "object",
                              "required": ["id", "login", "type"],
                              "properties": {
                                "id": {
                                  "description": "Internal user identifier from the shared session store",
                                  "anyOf": [{ "type": "integer" }, { "type": "string" }]
                                },
                                "login": { "description": "Login of the authenticated user", "type": "string" },
                                "type": {
                                  "description": "User type from the legacy auth model",
                                  "anyOf": [{ "type": "string" }, { "type": "null" }]
                                }
                              }
                            }
                          }
                        },
                        {
                          "description": "Optional refreshed facade token returned when the current token is close to expiration",
                          "type": "object",
                          "properties": {
                            "auth": {
                              "description": "Facade bearer token payload",
                              "type": "object",
                              "required": ["accessToken", "tokenType"],
                              "properties": {
                                "accessToken": {
                                  "description": "Facade bearer token backed by the shared session table",
                                  "type": "string"
                                },
                                "tokenType": {
                                  "description": "Authorization scheme for the access token",
                                  "type": "string",
                                  "enum": ["Bearer"]
                                }
                              }
                            }
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["error"],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": ["code", "message"],
                      "properties": {
                        "code": { "description": "Stable machine-readable error code", "type": "string" },
                        "message": { "description": "Human-readable error message", "type": "string" },
                        "details": {
                          "description": "Optional structured details from the facade or upstream systems",
                          "anyOf": [
                            { "additionalProperties": true, "type": "object", "properties": {} },
                            { "type": "array", "items": {} },
                            { "type": "string" },
                            { "type": "null" }
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/debug/browser": {
      "post": {
        "operationId": "debugBrowser",
        "summary": "Accept browser diagnostic telemetry over HTTP",
        "tags": ["Debug"],
        "description": "Receives authenticated browser telemetry for websocket troubleshooting and writes it to the structured facade logs.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "description": "Browser diagnostic payload sent over HTTP when websocket delivery is not reliable enough for debugging",
                "type": "object",
                "required": ["kind", "clientTime", "page", "browser", "screen"],
                "properties": {
                  "kind": {
                    "description": "Telemetry mode: periodic state snapshot or a discrete debug event",
                    "anyOf": [
                      { "type": "string", "enum": ["snapshot"] },
                      { "type": "string", "enum": ["event"] }
                    ]
                  },
                  "eventType": {
                    "description": "Application-defined debug event name, for example ws-error or ws-close",
                    "maxLength": 64,
                    "type": "string",
                    "example": "ws-error"
                  },
                  "clientTime": {
                    "description": "Client-side event timestamp in ISO 8601 format",
                    "format": "date-time",
                    "type": "string"
                  },
                  "page": {
                    "type": "object",
                    "properties": {
                      "origin": {
                        "description": "Page origin without user-specific secrets",
                        "maxLength": 256,
                        "type": "string",
                        "example": "https://app.example.com"
                      },
                      "path": {
                        "description": "Current pathname or route without query string",
                        "maxLength": 512,
                        "type": "string",
                        "example": "/terminal/orders"
                      },
                      "visibilityState": {
                        "description": "Browser document visibility state",
                        "maxLength": 32,
                        "type": "string",
                        "example": "visible"
                      },
                      "focused": { "description": "Whether the tab is focused", "type": "boolean" }
                    }
                  },
                  "browser": {
                    "type": "object",
                    "required": ["userAgent"],
                    "properties": {
                      "userAgent": { "description": "Full browser user agent string", "maxLength": 1024, "type": "string" },
                      "language": { "description": "Primary browser language", "maxLength": 32, "type": "string", "example": "ru-RU" },
                      "languages": {
                        "maxItems": 16,
                        "type": "array",
                        "items": { "description": "Browser language preference", "maxLength": 32, "type": "string" }
                      },
                      "platform": { "description": "Navigator platform string", "maxLength": 64, "type": "string", "example": "Win32" },
                      "timezone": {
                        "description": "IANA timezone reported by the browser",
                        "maxLength": 64,
                        "type": "string",
                        "example": "Europe/Berlin"
                      }
                    }
                  },
                  "screen": {
                    "type": "object",
                    "properties": {
                      "width": { "minimum": 0, "description": "Physical screen width in CSS pixels", "type": "number" },
                      "height": { "minimum": 0, "description": "Physical screen height in CSS pixels", "type": "number" },
                      "availWidth": { "minimum": 0, "description": "Available screen width in CSS pixels", "type": "number" },
                      "availHeight": { "minimum": 0, "description": "Available screen height in CSS pixels", "type": "number" },
                      "devicePixelRatio": { "minimum": 0, "description": "Window device pixel ratio", "type": "number" },
                      "viewportWidth": { "minimum": 0, "description": "Viewport width in CSS pixels", "type": "number" },
                      "viewportHeight": { "minimum": 0, "description": "Viewport height in CSS pixels", "type": "number" }
                    }
                  },
                  "connection": {
                    "type": "object",
                    "properties": {
                      "online": { "description": "Navigator online state", "type": "boolean" },
                      "effectiveType": {
                        "description": "NetworkInformation.effectiveType value",
                        "maxLength": 32,
                        "type": "string",
                        "example": "4g"
                      },
                      "downlink": { "minimum": 0, "description": "Estimated network downlink in Mbps", "type": "number" },
                      "rtt": { "minimum": 0, "description": "Estimated network RTT in milliseconds", "type": "number" },
                      "saveData": { "description": "Whether the browser requests reduced data usage", "type": "boolean" }
                    }
                  },
                  "websocket": {
                    "type": "object",
                    "properties": {
                      "url": {
                        "description": "Current websocket URL without query string",
                        "maxLength": 512,
                        "type": "string",
                        "example": "wss://app.example.com/ws"
                      },
                      "state": { "description": "Current websocket client state", "maxLength": 32, "type": "string", "example": "open" },
                      "retryCount": { "minimum": 0, "description": "Reconnect retry counter", "type": "integer" },
                      "lastError": { "description": "Last websocket error summary", "maxLength": 2048, "type": "string" },
                      "lastCloseCode": { "minimum": 0, "description": "Last websocket close code", "type": "integer" },
                      "lastCloseReason": { "description": "Last websocket close reason", "maxLength": 512, "type": "string" }
                    }
                  },
                  "context": {
                    "type": "object",
                    "properties": {
                      "appVersion": {
                        "description": "Frontend application version string",
                        "maxLength": 64,
                        "type": "string",
                        "example": "26.5.13-unstable"
                      },
                      "buildTag": {
                        "description": "Build or deploy tag of the frontend bundle",
                        "maxLength": 64,
                        "type": "string",
                        "example": "26.5.13-unstable"
                      },
                      "sessionId": {
                        "description": "Client-side session identifier for correlating browser events",
                        "maxLength": 128,
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "description": "Browser diagnostic payload sent over HTTP when websocket delivery is not reliable enough for debugging"
        },
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data"],
                  "properties": {
                    "data": {
                      "type": "object",
                      "allOf": [
                        {
                          "type": "object",
                          "required": ["ok"],
                          "properties": {
                            "ok": { "description": "Debug payload was accepted and logged", "type": "boolean", "enum": [true] }
                          }
                        },
                        {
                          "description": "Optional refreshed facade token returned when the current token is close to expiration",
                          "type": "object",
                          "properties": {
                            "auth": {
                              "description": "Facade bearer token payload",
                              "type": "object",
                              "required": ["accessToken", "tokenType"],
                              "properties": {
                                "accessToken": {
                                  "description": "Facade bearer token backed by the shared session table",
                                  "type": "string"
                                },
                                "tokenType": {
                                  "description": "Authorization scheme for the access token",
                                  "type": "string",
                                  "enum": ["Bearer"]
                                }
                              }
                            }
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["error"],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": ["code", "message"],
                      "properties": {
                        "code": { "description": "Stable machine-readable error code", "type": "string" },
                        "message": { "description": "Human-readable error message", "type": "string" },
                        "details": {
                          "description": "Optional structured details from the facade or upstream systems",
                          "anyOf": [
                            { "additionalProperties": true, "type": "object", "properties": {} },
                            { "type": "array", "items": {} },
                            { "type": "string" },
                            { "type": "null" }
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["error"],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": ["code", "message"],
                      "properties": {
                        "code": { "description": "Stable machine-readable error code", "type": "string" },
                        "message": { "description": "Human-readable error message", "type": "string" },
                        "details": {
                          "description": "Optional structured details from the facade or upstream systems",
                          "anyOf": [
                            { "additionalProperties": true, "type": "object", "properties": {} },
                            { "type": "array", "items": {} },
                            { "type": "string" },
                            { "type": "null" }
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/openapi.json": { "get": { "responses": { "200": { "description": "Default Response" } } } }
  },
  "servers": [{ "url": "/" }],
  "tags": [{ "name": "System" }, { "name": "Auth" }, { "name": "Debug" }]
}