TKAWEN developer platform

This repository holds the public developer surface of TKAWEN OS: a verified OpenAPI description of the tenant API (https://{academy}.tkawen.com/api/v1) and the npm packages built from it.

Status: published on npm — @tkawen/verify, @tkawen/os-sdk, @tkawen/os-mcp. MIT.

npm install @tkawen/os-sdk
npx -y @tkawen/os-mcp          # MCP server (set TKAWEN_ACADEMY)

Layout

path	what	status
openapi/	tkawen-os-v1.yaml — OpenAPI 3.1 description of the TKAWEN OS academy API v1 (46 operations), derived from the kernel source	stable v1
packages/verify	@tkawen/verify: a zero-dependency certificate verification client and the <tkawen-verify> web component (TKAWEN academies and Algeria Certify)	npm
packages/os-sdk	@tkawen/os-sdk: a typed, zero-dependency client for all 46 operations. Types are generated from the spec with openapi-typescript, and errors are typed	npm
packages/os-mcp	@tkawen/os-mcp: a read-only MCP stdio server (catalogue, instructors, certificate verification and, with a token, the learner's own dashboard, courses, transcript and whoami)	npm

The packages are independent npm projects, and each has its own package-lock.json. The root package.json does not declare npm workspaces. A workspace root would take over npm install inside packages/verify and bypass that package's own lockfile. The root scripts just run each package in turn:

npm run install:all   # verify, os-sdk, then os-mcp (os-mcp links ../os-sdk)
npm run build         # os-sdk must be built before os-mcp typechecks/tests
npm test
npm run pack:check    # npm pack --dry-run for every package

Important facts for API consumers

• The tenant is chosen by the host ({academy}.tkawen.com).
• Tokens. The spec defines POST /auth/token, which issues an expiring token with abilities (read, learn, purchase, requests), along with GET /auth/me and DELETE /auth/token. These are marked x-status: pending-deployment, together with ability enforcement (403 insufficient_ability), Idempotency-Key on checkout and payment, and the role-dependent metrics shape. Until the server release, tokens come only from the legacy POST /api/auth/login. Those tokens have full access and no expiry.
• Response and error envelopes are not uniform. The SDK keeps the server's shapes as they are and types each one from the spec.
• Two operations carry x-known-defect (createCheckoutOrder, getMyEnrollmentTimeline). Both are expected to answer 500 in specific cases. Fixes are pending deployment.

Release process

• Every maintainer of the @tkawen npm scope has 2FA enabled (auth and writes).
• Each package must pass npm run typecheck && npm test && npm run build && npm pack --dry-run before release.
• Publish @tkawen/os-sdk before @tkawen/os-mcp.
• Report security issues to security@tkawen.com (see each package's SECURITY.md).

License

MIT © TKAWEN