mpx-api 1.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,71 @@
+# Contributing to mpx-api
+
+Thanks for your interest in contributing to mpx-api! We welcome contributions from the community.
+
+## Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/mesaplex/mpx-api.git
+cd mpx-api
+
+# Install dependencies
+npm install
+
+# Link for local development
+npm link
+
+# Run tests
+npm test
+```
+
+## Testing
+
+All pull requests must include tests. We use Node.js built-in test runner.
+
+Run tests:
+```bash
+npm test
+```
+
+Add tests in the `test/` directory with the `.test.js` extension.
+
+## Code Style
+
+- Use ES modules (import/export)
+- 2-space indentation
+- Semicolons required
+- Descriptive variable names
+- Comment complex logic
+
+## Pull Request Process
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Add tests for new functionality
+5. Ensure all tests pass (`npm test`)
+6. Commit your changes (`git commit -m 'Add amazing feature'`)
+7. Push to your fork (`git push origin feature/amazing-feature`)
+8. Open a Pull Request
+
+## Feature Requests
+
+Open an issue with the "enhancement" label. Please include:
+- Use case / problem you're trying to solve
+- Proposed solution
+- Alternative solutions considered
+
+## Bug Reports
+
+Open an issue with the "bug" label. Please include:
+- Steps to reproduce
+- Expected behavior
+- Actual behavior
+- mpx-api version (`mpx-api --version`)
+- Node.js version (`node --version`)
+- Operating system
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mesaplex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,345 @@
+# mpx-api 🚀
+
+**Developer-first API testing, mocking, and documentation CLI.**
+
+No GUI. No proprietary formats. Just powerful, git-friendly API testing from your terminal.
+
+[![npm version](https://img.shields.io/npm/v/mpx-api.svg)](https://www.npmjs.com/package/mpx-api)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+## Why mpx-api?
+
+- **Git-friendly**: Collections are YAML files, not proprietary blobs
+- **CI/CD ready**: Exit codes, JSON output, no GUI dependency
+- **Developer experience**: Beautiful terminal output, syntax highlighting
+- **Request chaining**: Use response from one request in another (`{{request.response.body.id}}`)
+- **Built-in mock server**: Test against OpenAPI specs without deploying
+- **Assertions in collections**: No separate test code needed
+- **Fast**: Pure Node.js, minimal dependencies, < 200ms startup
+
+## Installation
+
+```bash
+npm install -g mpx-api
+```
+
+Or use with `npx`:
+
+```bash
+npx mpx-api get https://api.github.com/users/octocat
+```
+
+## Quick Start
+
+### Make HTTP Requests
+
+```bash
+# Simple GET request
+mpx-api get https://jsonplaceholder.typicode.com/users
+
+# POST with JSON
+mpx-api post https://api.example.com/users --json '{"name":"Alice","email":"alice@example.com"}'
+
+# Custom headers
+mpx-api get https://api.example.com/protected \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Accept: application/json"
+
+# Verbose output (show headers)
+mpx-api get https://httpbin.org/get -v
+
+# Quiet mode (only response body)
+mpx-api get https://api.example.com/data -q
+```
+
+### Create a Collection
+
+```bash
+# Initialize collection in your project
+mpx-api collection init
+
+# Add requests
+mpx-api collection add get-users GET /users
+mpx-api collection add create-user POST /users --json '{"name":"Bob"}'
+
+# Run the collection
+mpx-api collection run
+```
+
+### Collection File Format
+
+Collections are simple YAML files (`.mpx-api/collection.yaml`):
+
+```yaml
+name: My API Tests
+baseUrl: https://api.example.com
+
+requests:
+  - name: get-users
+    method: GET
+    url: /users
+    headers:
+      Authorization: Bearer {{env.API_TOKEN}}
+    assert:
+      status: 200
+      body.length: { gt: 0 }
+      responseTime: { lt: 500 }
+
+  - name: get-specific-user
+    method: GET
+    url: /users/{{get-users.response.body[0].id}}
+    assert:
+      status: 200
+      body.email: { exists: true }
+
+  - name: create-post
+    method: POST
+    url: /posts
+    json:
+      title: New Post
+      userId: {{get-users.response.body[0].id}}
+    assert:
+      status: 201
+      body.title: New Post
+```
+
+**Key features:**
+
+- **Request chaining**: `{{get-users.response.body[0].id}}` uses the response from a previous request
+- **Environment variables**: `{{env.API_TOKEN}}` pulls from environment files
+- **Assertions**: Test status codes, response times, body fields, headers
+- **Operators**: `gt`, `lt`, `gte`, `lte`, `eq`, `ne`, `contains`, `exists`
+
+### Environments
+
+```bash
+# Initialize environments (creates dev, staging, production)
+mpx-api env init
+
+# Set variables
+mpx-api env set staging API_URL=https://staging.example.com
+mpx-api env set staging API_TOKEN=abc123
+
+# List environments
+mpx-api env list
+
+# List variables in environment
+mpx-api env list staging
+
+# Run collection with environment
+mpx-api collection run --env staging
+```
+
+Environment files (`.mpx-api/environments/staging.yaml`):
+
+```yaml
+name: staging
+variables:
+  API_URL: https://staging.example.com
+  API_TOKEN: secret-token-here
+```
+
+### Testing & Assertions
+
+```bash
+# Run tests from collection
+mpx-api test ./collection.yaml
+
+# With environment
+mpx-api test ./collection.yaml --env production
+
+# JSON output for CI/CD
+mpx-api test ./collection.yaml --json
+```
+
+Assertions support:
+
+- **Status codes**: `status: 200`
+- **Response time**: `responseTime: { lt: 500 }`
+- **Headers**: `headers.content-type: application/json`
+- **Body fields**: `body.users[0].name: Alice`
+- **Operators**:
+  - `{ gt: 10 }` - greater than
+  - `{ lt: 100 }` - less than
+  - `{ gte: 5 }` - greater than or equal
+  - `{ lte: 50 }` - less than or equal
+  - `{ eq: "value" }` - equals
+  - `{ ne: "value" }` - not equals
+  - `{ contains: "text" }` - contains substring
+  - `{ exists: true }` - field exists
+
+### Request History
+
+```bash
+# View recent requests
+mpx-api history
+
+# Limit to last 50
+mpx-api history -n 50
+```
+
+### Cookie Management
+
+Cookies are automatically saved and sent with subsequent requests. Cookie jar is stored at `~/.mpx-api/cookies.json`.
+
+## Pro Features 💎
+
+Upgrade to **mpx-api Pro** ($12/mo) for advanced features:
+
+### Mock Server
+
+Start a mock API server from an OpenAPI spec:
+
+```bash
+mpx-api mock ./openapi.yaml --port 4000
+```
+
+Supports:
+- OpenAPI 3.0 specs (YAML or JSON)
+- Automatic response generation from schemas
+- Configurable response delay: `--delay 200`
+- CORS support: `--cors`
+
+### Load Testing
+
+```bash
+mpx-api load https://api.example.com/health --rps 100 --duration 30s
+```
+
+Features:
+- Requests per second (RPS) control
+- Response time percentiles (P50, P95, P99)
+- Status code distribution
+- Error tracking
+
+### Documentation Generation
+
+Generate beautiful API docs from your collections:
+
+```bash
+mpx-api docs ./collection.yaml --output API.md
+```
+
+Creates Markdown documentation with:
+- Table of contents
+- Request/response examples
+- Expected responses from assertions
+- Auto-generated from your test collections
+
+### Request Chaining
+
+Already included in free tier! Use response data from previous requests:
+
+```yaml
+requests:
+  - name: login
+    method: POST
+    url: /auth/login
+    json:
+      username: test
+      password: secret
+
+  - name: get-profile
+    method: GET
+    url: /users/me
+    headers:
+      Authorization: Bearer {{login.response.body.token}}
+```
+
+## Examples
+
+See the `examples/` directory for real-world collections:
+
+- `jsonplaceholder.yaml` - CRUD operations with JSONPlaceholder API
+- `github-api.yaml` - GitHub API with request chaining
+- `openapi-petstore.yaml` - OpenAPI spec for mock server testing
+
+Run examples:
+
+```bash
+mpx-api test examples/jsonplaceholder.yaml
+mpx-api collection run examples/github-api.yaml
+```
+
+## CI/CD Integration
+
+Use exit codes for CI/CD pipelines:
+
+```bash
+# In your CI script
+mpx-api test ./api-tests.yaml --env production
+
+# Exit code 0 = all tests passed
+# Exit code 1 = tests failed
+```
+
+GitHub Actions example:
+
+```yaml
+- name: Run API Tests
+  run: npx mpx-api test ./tests/api-collection.yaml --env staging
+```
+
+## Error Handling
+
+mpx-api gracefully handles:
+
+- **DNS failures**: Clear error messages
+- **Timeouts**: Configurable with `--timeout <ms>`
+- **SSL errors**: Skip verification with `--no-verify`
+- **Invalid JSON**: Parse errors with helpful messages
+- **Large responses**: Automatic truncation in terminal (full body still accessible)
+
+## Configuration
+
+Global config: `~/.mpx-api/config.json`  
+Project config: `.mpx-api/config.json`  
+Cookie jar: `~/.mpx-api/cookies.json`  
+History: `~/.mpx-api/history.jsonl`
+
+## Comparison
+
+| Feature | mpx-api | Postman | HTTPie Pro | curl |
+|---------|---------|---------|------------|------|
+| **Price** | Free / $12 Pro | $49/user | $9/mo | Free |
+| **Collections** | ✅ YAML files | ✅ Proprietary | ❌ | ❌ |
+| **Request chaining** | ✅ | ✅ | ❌ | ❌ |
+| **Assertions** | ✅ Built-in | ✅ Scripts | ❌ | ❌ |
+| **Mock server** | ✅ Pro | ✅ Pro | ❌ | ❌ |
+| **Load testing** | ✅ Pro | ✅ Pro | ❌ | ❌ |
+| **Git-friendly** | ✅ | ⚠️ Export needed | N/A | N/A |
+| **No GUI needed** | ✅ | ❌ | ✅ | ✅ |
+| **Syntax highlighting** | ✅ | ✅ | ✅ | ❌ |
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/mesaplex/mpx-api.git
+cd mpx-api
+npm install
+
+# Run tests
+npm test
+
+# Link for local development
+npm link
+```
+
+## Contributing
+
+Contributions welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.
+
+## License
+
+MIT © Mesaplex
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/mesaplex/mpx-api/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/mesaplex/mpx-api/discussions)
+- **Email**: support@mpx-api.dev
+
+---
+
+**Built with ❤️ by developers, for developers.**

package/bin/mpx-api.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+import { program } from 'commander';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { readFileSync } from 'fs';
+
+// Command imports
+import { registerRequestCommands } from '../src/commands/request.js';
+import { registerCollectionCommands } from '../src/commands/collection.js';
+import { registerEnvCommands } from '../src/commands/env.js';
+import { registerMockCommands } from '../src/commands/mock.js';
+import { registerTestCommand } from '../src/commands/test.js';
+import { registerHistoryCommand } from '../src/commands/history.js';
+import { registerLoadCommand } from '../src/commands/load.js';
+import { registerDocsCommand } from '../src/commands/docs.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const pkg = JSON.parse(
+  readFileSync(join(__dirname, '../package.json'), 'utf8')
+);
+
+program
+  .name('mpx-api')
+  .description('Developer-first API testing, mocking, and documentation CLI')
+  .version(pkg.version);
+
+// Register HTTP method commands (get, post, put, patch, delete, head, options)
+registerRequestCommands(program);
+
+// Register collection commands
+registerCollectionCommands(program);
+
+// Register environment commands
+registerEnvCommands(program);
+
+// Register mock server commands
+registerMockCommands(program);
+
+// Register test command
+registerTestCommand(program);
+
+// Register history command
+registerHistoryCommand(program);
+
+// Register Pro commands (gracefully handle unlicensed)
+registerLoadCommand(program);
+registerDocsCommand(program);
+
+program.parse();

package/examples/github-api.yaml

@@ -0,0 +1,35 @@
+name: GitHub API Collection
+description: Example collection for GitHub API with request chaining
+baseUrl: https://api.github.com
+
+requests:
+  - name: get-user
+    method: GET
+    url: /users/octocat
+    headers:
+      Accept: application/vnd.github+json
+      User-Agent: mpx-api
+    assert:
+      status: 200
+      body.login: octocat
+      body.type: User
+
+  - name: get-repos
+    method: GET
+    url: /users/{{get-user.response.body.login}}/repos
+    headers:
+      Accept: application/vnd.github+json
+      User-Agent: mpx-api
+    assert:
+      status: 200
+      body.length: { gt: 0 }
+
+  - name: get-first-repo
+    method: GET
+    url: "{{get-repos.response.body[0].url}}"
+    headers:
+      Accept: application/vnd.github+json
+      User-Agent: mpx-api
+    assert:
+      status: 200
+      body.owner.login: octocat

package/examples/jsonplaceholder.yaml

@@ -0,0 +1,52 @@
+name: JSONPlaceholder API Tests
+description: Example collection testing JSONPlaceholder API
+baseUrl: https://jsonplaceholder.typicode.com
+
+requests:
+  - name: Get all users
+    method: GET
+    url: /users
+    assert:
+      status: 200
+      body.length: { gt: 0 }
+      headers.content-type: application/json
+      responseTime: { lt: 2000 }
+
+  - name: Get specific user
+    method: GET
+    url: /users/1
+    assert:
+      status: 200
+      body.id: 1
+      body.name: { exists: true }
+      body.email: { exists: true }
+
+  - name: Create new post
+    method: POST
+    url: /posts
+    json:
+      title: Test Post
+      body: This is a test post created by mpx-api
+      userId: 1
+    assert:
+      status: 201
+      body.title: Test Post
+      body.userId: 1
+
+  - name: Update post
+    method: PUT
+    url: /posts/1
+    json:
+      id: 1
+      title: Updated Title
+      body: Updated content
+      userId: 1
+    assert:
+      status: 200
+      body.title: Updated Title
+
+  - name: Delete post
+    method: DELETE
+    url: /posts/1
+    assert:
+      status: 200

package/examples/openapi-petstore.yaml

@@ -0,0 +1,88 @@
+openapi: 3.0.0
+info:
+  title: Pet Store API
+  version: 1.0.0
+  description: A simple pet store API for testing mpx-api mock server
+
+paths:
+  /pets:
+    get:
+      summary: List all pets
+      responses:
+        '200':
+          description: A list of pets
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    id:
+                      type: integer
+                      example: 1
+                    name:
+                      type: string
+                      example: "Fluffy"
+                    species:
+                      type: string
+                      example: "cat"
+    
+    post:
+      summary: Create a pet
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                name:
+                  type: string
+                species:
+                  type: string
+      responses:
+        '201':
+          description: Pet created
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id:
+                    type: integer
+                    example: 2
+                  name:
+                    type: string
+                    example: "Buddy"
+                  species:
+                    type: string
+                    example: "dog"
+
+  /pets/{id}:
+    get:
+      summary: Get a pet by ID
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: A single pet
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id:
+                    type: integer
+                    example: 1
+                  name:
+                    type: string
+                    example: "Fluffy"
+                  species:
+                    type: string
+                    example: "cat"
+        '404':
+          description: Pet not found