Documentation
/
AI Quick Reference
AI Quick Reference
v0.00
TypeScript
A compact summary of WAPPI conventions for AI coding agents (Cursor, Claude Code, Copilot and others). Each item links to its full page. For the complete docs as one markdown file, read https://www.wappi.dev/llms-full.txt. The index is at https://www.wappi.dev/llms.txt and every page is available as markdown by adding .md to its URL.
Endpoints are named Namespace_EndpointName_Major_Minor_Patch, for example User_UpdateDetails_2_3_4. The namespace works like a microservice (e.g. User), the endpoint name describes what it does, and the version has three numbers. The request Body type is named Namespace_EndpointName_Major_Minor_Patch__Body, e.g. User_GetUserData_1_0_0__Body. Namespaces
Each endpoint lives at API/<Namespace>/<EndpointName>/<x.y.z>/index.ts, with an index.spec.ts test from the template. Shared helpers live in API/CoreHelpers/ (e.g. types.ts, logging.ts). Always create endpoints and versions with the CLI, not by hand. Namespaces
1API/
2 Core/Login/1.0.0/index.ts // Core_Login_1_0_0
3 User/GetUserData/1.0.0/index.ts // User_GetUserData_1_0_0
4 CoreHelpers/types.ts
5 CoreHelpers/logging.tsEndpoints are registered in API/index.ts under exports.Endpoints, which also has LoginRequired and PublicApiEndpoint lists. A webhook goes in exports.Endpoints only, not in LoginRequired or PublicApiEndpoint, because the sender can't log in or send an API key. Webhooks
1// API/index.ts
2exports.Endpoints = {
3 ...
4 Webhook_StripeCheckout_1_0_0: true,
5 // NewEndpointGoesHere
6}Put webhooks in the Webhook namespace, so names start with Webhook_ (e.g. API/Webhook/StripeCheckout/1.0.0/index.ts is Webhook_StripeCheckout_1_0_0). The sender POSTs its own JSON to https://<your-api-url>/Webhook_StripeCheckout_1_0_0, with no query/data wrapper. The Body holds the parsed JSON plus the default body data, body.headers (request headers) and body.raw (the raw request body as a string). Always verify signatures against body.raw. The returned statusCode is the HTTP status the sender gets: return 200 when a retry can't help, 4xx/5xx only when a retry could succeed, and make handlers safe to run twice. Webhooks
A request names the endpoint in query and sends its Body in data. Optional results include or exclude fields on the server (WAPPI Query Language). Request, Query Language
1import { request } from 'wappi-fe'
2
3const response = await request(WAPPI_CONFIG, {
4 name: 'Get user info', // label shown in the network tab
5 query: 'NameSpace_FunctionName_1_0_0', // endpoint name
6 data: {}, // typed as NameSpace_FunctionName_1_0_0__Body
7 results: { name: 'user', include: [{ name: 'userName', key: 'name' }] }, // optional
8 authRequired: true, // optional, depends on the endpoint
9})Every endpoint function receives a Body parameter that includes correlationId, headers and env (localhost | dev | stage | prod). Authenticated endpoints also get auth, the data returned by your Core_Login endpoint. Body Data, Auth Keys
Every endpoint version is self-contained. Create a new version with npx wappi c and pick the endpoint; you can copy it and choose a major, minor or patch bump. Major = breaking, minor = recommended update, patch = fix. Keep old versions working until logs show they are unused. Versioning
Run with npx wappi <command>. CLI Commands
1wappi init (i) # initialise WAPPI, required for other commands
2wappi run (r) # run locally on the port in wappi.json
3wappi create (c) # new endpoint or new version from templates
4wappi delete (d) # delete an endpoint version and namespace
5wappi build (b) # build for running locally and testing
6wappi test (t) # run tests, optionally for one endpoint: wappi t Core_Login_1_0_0
7wappi lint (l) # eslint, based on .eslintrc.json
8wappi watch (w) # watch the API folder, works with wappi run
9wappi update (u) # update node modules to latest
10wappi help (h) # show the commands menuJest is set up out of the box. Every endpoint has an index.spec.ts; extend it when you add code. Run npx wappi t for everything or npx wappi t Test_Something_1_0_0 for one endpoint. Testing
wappi run writes <package name>-Internal-openAPI-spec.json (all endpoints) and <package name>-Public-openAPI-spec.json (endpoints in exports.PublicApiEndpoint) to the project root, using each endpoint's README.md, types.ts and optional docExample in _data/successData.ts. API Documentation
Every endpoint runs inside a try / catch and errors are logged automatically, so always throw errors. Customise log output in /API/CoreHelpers/logging.ts. Set SHOW_LOGS=false in production. Logging
Project settings are in wappi.json (apiKey, authRotation, domains, private, port, prisma, ...). Environment variables go in .env, kept in sync with .env.example (ENVIRONMENT, SHOW_LOGS, AUTH_KEY_CURRENT, AUTH_KEY_PREVIOUS, FRONTEND_PROJECT_PATHS). A health check is built in at /healthcheck. Configuration, Environment Variables, Health Checks
Copy one of these into your project so your coding agent uses the WAPPI docs.
1## WAPPI
2This project uses the WAPPI API framework (npm: wappi).
3Before writing or changing WAPPI code, read https://www.wappi.dev/llms-full.txt
4(index: https://www.wappi.dev/llms.txt, quick reference: https://www.wappi.dev/ai.md).
5- Endpoints: API/<Namespace>/<EndpointName>/<x.y.z>/index.ts, named Namespace_EndpointName_X_Y_Z
6- Create endpoints and versions with `npx wappi c`, never by hand
7- Run tests with `npx wappi t <EndpointName>`1---
2description: WAPPI API framework conventions
3globs: API/**/*.ts
4alwaysApply: false
5---
6This project uses WAPPI. Read https://www.wappi.dev/llms-full.txt for the full docs
7(quick reference: https://www.wappi.dev/ai.md).
8Follow the Namespace_EndpointName_X_Y_Z naming and API/<Namespace>/<EndpointName>/<x.y.z>/ layout.
9Use `npx wappi c` to create endpoints or versions and `npx wappi t` to test.1This project uses the WAPPI API framework. Use https://www.wappi.dev/llms-full.txt as the reference
2for endpoint naming, folder layout, CLI commands, versioning and testing.