You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -228,7 +236,10 @@ Every successful JSON response has the shape `{ data, meta? }`; every error has
228
236
229
237
### v11 → v12
230
238
231
-
v12 migrates the database from MongoDB to PostgreSQL. This is a hard cutover: all data must be migrated through the provided CLI before starting the new version. See [Upgrading to v12](./docs/migrations/v12.md).
239
+
> [!WARNING]
240
+
> v12 migrates the database from MongoDB to PostgreSQL. This is a hard cutover: all data must be migrated through the provided CLI before starting the new version.
241
+
242
+
See [Upgrading to v12](./docs/migrations/v12.md).
232
243
233
244
### v10 → v11
234
245
@@ -244,15 +255,10 @@ v10 includes a breaking auth system refactor. See [Upgrading to v10](./docs/migr
For the full stack, run the core server alongside (`pnpm dev` at the repo root), then bridge the production-served admin to the local dev server via `http://localhost:2333/proxy/qaqdmin/dev-proxy`.
34
+
35
+
### Environment
36
+
37
+
All variables are optional (empty = safe defaults); see `.env.example`.
38
+
39
+
| Variable | Purpose |
40
+
|----------|---------|
41
+
|`VITE_APP_BASE_API`| mx-core API endpoint |
42
+
|`VITE_APP_WEB_URL`| Blog frontend origin ("view on site" links) |
43
+
|`VITE_APP_GATEWAY`| Socket.IO gateway (derived from API origin if empty) |
44
+
|`VITE_APP_PUBLIC_URL`| Vite `base` for production builds |
The admin is built **into** the core release, not downloaded at runtime:
51
+
52
+
- The production Docker image builds `apps/admin` and bakes `dist/` into `out/admin/` with a stamped `version` file.
53
+
- The server serves it at `GET /proxy/qaqdmin` (see `apps/core/src/modules/pageproxy/`), semver-comparing the image-baked copy against a runtime-updated copy in `$DATA_DIR/admin` and serving the newer one.
54
+
- The former standalone `mx-space/mx-admin` repo is archived; see [`docs/admin-monorepo-migration.md`](../../docs/admin-monorepo-migration.md).
55
+
56
+
## Release
57
+
58
+
-**With a core release** — `apps/core/scripts/bump-admin-version.js` patch-bumps the admin version when it changed since the last server tag.
59
+
-**Independently** — `scripts/release-admin.sh [patch|minor|major]` tags `admin-v*`, triggering `admin-release.yml`, which builds, zips, and publishes the bundle to R2.
-`event` is one of `startup` or `heartbeat` (sent hourly).
14
+
-`instanceId` is a random UUID persisted in the instance's data directory — it is not derived from any user or site data.
15
+
- Field lengths are capped at 64 chars; anything else is rejected with `400`.
16
+
17
+
Users opt out with `--disable_telemetry` or `MX_DISABLE_TELEMETRY=true` (see `apps/core/src/utils/telemetry.util.ts`).
18
+
19
+
## Endpoints
20
+
21
+
| Route | Description |
22
+
|-------|-------------|
23
+
|`POST /collect`| Ingest one event (validated, inserted into D1) |
24
+
|`GET /stats`| JSON aggregates: total/active instances, version & Node distributions, daily series (last 30d) |
25
+
|`GET /` or `/dashboard`| Server-rendered Chart.js dashboard |
26
+
27
+
> [!NOTE]
28
+
> `/stats` and the dashboard are gated externally by Cloudflare Zero Trust, not by the Worker itself. `/collect` is open (CORS `*`) so any self-hosted instance can post.
29
+
30
+
A daily cron (`0 3 * * *`) deletes rows older than 90 days.
31
+
32
+
## Development
33
+
34
+
```bash
35
+
pnpm -C apps/telemetry run dev # wrangler dev
36
+
pnpm -C apps/telemetry run db:migrate # apply schema.sql to local D1
37
+
pnpm -C apps/telemetry run db:migrate:remote # apply schema.sql to remote D1
38
+
pnpm -C apps/telemetry run deploy # wrangler deploy
39
+
```
40
+
41
+
-`schema.sql` — the single `telemetry` table and its indexes.
42
+
-`mock-data.sql` — seed data so the local dashboard renders non-empty.
43
+
-`preview.html` — standalone static mock of the dashboard (hardcoded numbers) for design iteration; does not call the Worker.
Shared AI contracts for mx-space — the single source of truth for wire formats exchanged between the server ([`apps/core`](../../apps/core)) and its clients ([`apps/admin`](../../apps/admin)).
4
+
5
+
> [!NOTE]
6
+
> This package is private to the monorepo and consumed as TypeScript source via workspace exports.
7
+
8
+
## Contents
9
+
10
+
Currently the package contains one contract:
11
+
12
+
-**AI agent SSE events** (`src/ai-agent-sse.ts`) — a TypeBox union, `AiAgentSseEvent`, describing the server-sent event frames streamed by the AI agent: `text`, `thinking`, `toolcall`, `done`, and `error`. Exports `AiAgentSseEventSchema` (runtime validation) and the `AiAgentSseEvent` type.
13
+
14
+
## Usage
15
+
16
+
```ts
17
+
// apps/core — server emits JSON-framed SSE
18
+
importtype { AiAgentSseEvent } from'@mx-space/ai'
19
+
20
+
// apps/admin — client transport parses the same union
21
+
importtype { AiAgentSseEvent } from'@mx-space/ai'
22
+
```
23
+
24
+
Both sides import the same schema so neither defines the shape locally — a change here is a breaking change for server and client simultaneously, by design.
Copy file name to clipboardExpand all lines: packages/api-client/readme.md
+7-3Lines changed: 7 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# @mx-space/api-client
2
2
3
-
A framework-agnostic TypeScript/JavaScript SDK for the MX Space server (MServer v3). It wraps common API endpoints with typed request methods and response types for fast frontend and server-side integration.
3
+
A framework-agnostic TypeScript/JavaScript SDK for the MX Space Core server. It wraps common API endpoints with typed request methods and response types for fast frontend and server-side integration.
4
4
5
5
---
6
6
@@ -23,7 +23,7 @@ A framework-agnostic TypeScript/JavaScript SDK for the MX Space server (MServer
23
23
## Requirements
24
24
25
25
-**Node.js** ≥ 22 (see `engines` in `package.json`)
26
-
-**MX Space server**: v12+ (PostgreSQL + Snowflake IDs) for api-client **v4.x**. See the [Version Compatibility & Migration](#version-compatibility--migration) section for older lines.
26
+
-**MX Space server**: v12+ (PostgreSQL + Snowflake IDs) for api-client **v5.x**. See the [Version Compatibility & Migration](#version-compatibility--migration) section for older lines.
27
27
28
28
---
29
29
@@ -145,6 +145,9 @@ Inject one or more controllers so the client exposes them (e.g. `client.post`, `
Central Drizzle ORM schema and ID layer for mx-space. Single source of truth for table definitions, the branded `EntityId` type, and the Snowflake ID generator used across the monorepo.
4
+
5
+
> [!NOTE]
6
+
> This package is private to the monorepo and consumed as TypeScript source via workspace exports.
7
+
8
+
## Exports
9
+
10
+
| Subpath | Contents |
11
+
|---------|----------|
12
+
|`@mx-space/db-schema`| Everything: schema + ID layer + `CollectionRefTypes`|
13
+
|`@mx-space/db-schema/schema`| All Drizzle table definitions |
End-to-end test harness for the mx-space CLI ↔ server contract. Boots a **real** in-process NestJS core server backed by throwaway PostgreSQL and Redis containers, seeds an owner, then drives the **real**`mxs` CLI binary as a subprocess against it.
4
+
5
+
## How it works
6
+
7
+
Each test file follows the same lifecycle:
8
+
9
+
1.**Containers** — `createE2EBackend()` starts a `postgres:17-alpine` testcontainer (per-worker isolated database, migrated from `apps/core/src/database/migrations`) and a per-backend `redis:7-alpine` testcontainer.
10
+
2.**Env seeding** — `PG_*` / `REDIS_*` / `MIGRATIONS_DIR` / `JWT_SECRET` are written into `process.env`*before*`apps/core`'s `AppModule` is dynamically imported, so no frozen config defaults leak in.
11
+
3.**Server** — `@nestjs/testing` compiles `AppModule`; Fastify listens on an ephemeral loopback port in dev mode (no `/api/vN` prefix).
12
+
4.**Auth** — an owner is inserted directly into PostgreSQL (Better Auth credential rows), a bearer token is minted via `signInUsername`, and a CLI profile is written under a temporary `$XDG_CONFIG_HOME`.
13
+
5.**CLI** — tests spawn `packages/cli/src/bin/mxs.ts` via `tsx` with mode flags and assert on the parsed `{ ok, data }` envelope. `runAcrossModes()` walks all five output modes (`json`, `pretty-json`, `readable`, `llm`, `xml`).
14
+
15
+
## Running
16
+
17
+
```bash
18
+
# From the repo root
19
+
pnpm e2e
20
+
21
+
# Or from this package
22
+
pnpm -C packages/e2e run test
23
+
```
24
+
25
+
Requires Docker (testcontainers). No environment variables are strictly required — all are seeded with `??=` defaults. Set `PG_VERIFY_URL` to reuse an external PostgreSQL instead of starting a container.
26
+
27
+
> [!NOTE]
28
+
> Hook and test timeouts are 120s; CI runs with 2 retries and 2 workers.
0 commit comments