# Nexus — llms-full.txt

## Product description
Nexus is a multi-tenant operations operating system (Ops OS) for SMEs in the MENA region.
It combines CRM, omnichannel messaging, order management, fulfillment, inventory,
shipping, VoIP/PBX, AI analytics, and automation in one platform.

## Technology stack
- Frontend: React + TypeScript + Vite
- Backend: Supabase (PostgreSQL, Edge Functions, Storage)
- Auth: Supabase Auth for humans, agent API keys + short-lived JWTs for AI agents
- Integrations: WhatsApp, Meta, Shopify, couriers, PBX, n8n

## Docs root
https://nexus-docs.aiforstartups.io

## Canonical AI-agent workflow

### 0. Agent self-registers on the free plan
URL: https://lgwvoomgrwpsgpxwyaec.supabase.co/functions/v1/agent-register
Summary: Public POST endpoint for new agent-owned organizations. Creates an agent auth user, a free-plan organization, one initial agent API key, and returns that raw key once only. Rate limited by owner email and IP.

### 1. Human admin creates an API key
URL: https://lgwvoomgrwpsgpxwyaec.supabase.co/functions/v1/agent-api-key-create
Summary: Requires a human bearer JWT for an org owner/admin. Returns the raw `nxs_ak_...` key once only. Stores only a bcrypt hash.

### 2. Agent exchanges API key for JWT
URL: https://lgwvoomgrwpsgpxwyaec.supabase.co/functions/v1/agent-auth
Summary: Public POST endpoint. Accepts `{ "api_key": "nxs_ak_..." }`. Returns a short-lived agent JWT valid for 1 hour. Rate limited to 10 attempts/minute/IP.

### 3. Agent calls Nexus MCP
URL: https://lgwvoomgrwpsgpxwyaec.supabase.co/functions/v1/mcp-server
Summary: Hosted MCP endpoint using Streamable HTTP in JSON-response mode. Requires `Authorization: Bearer <agent-jwt>`.

### 4. Agent or human checks usage
URL: https://lgwvoomgrwpsgpxwyaec.supabase.co/functions/v1/agent-usage
Summary: Returns the current plan, usage counters, remaining capacity, warning messages, and upgrade guidance for the current organization.

## Agent auth model

- API key format: `nxs_ak_` + 48 random alphanumeric chars
- Raw keys are never stored
- Raw keys are never retrievable again after creation
- Agent JWT contains:
  - `organization_id`
  - `org_role = agent`
  - `agent_scopes`
- Scope model:
  - `read`
  - `write`
  - `admin`
- Plan ceilings also cap MCP scopes and API usage, even if an older key requested broader access.

## Pricing

- Free ($0): read-only MCP, 50 contacts, 25 orders, no messaging, 500 API calls/day, 30-day retention
- Starter ($99/mo): read+write MCP, 500 contacts, 200 orders/month, 1,000 outbound messages, 5,000 API calls/day
- Growth ($199/mo): full MCP, 5,000 contacts, unlimited orders, 5,000 outbound messages, 25,000 API calls/day, VoIP, automation
- Scale ($599/mo): highest limits plus the AI suite, custom integrations, onboarding, SLA, and priority support
- Additional agents: $10/agent/month on Starter, $5/agent/month on Growth and Scale

## MCP tools

- `nexus_list_contacts`
- `nexus_get_contact`
- `nexus_create_contact`
- `nexus_update_contact`
- `nexus_list_orders`
- `nexus_get_order`
- `nexus_create_order`
- `nexus_update_order_status`
- `nexus_list_inventory`
- `nexus_check_stock`
- `nexus_list_conversations`
- `nexus_send_message`
- `nexus_search`

## MCP resources

- `nexus://organization/info`
- `nexus://schema/contacts`
- `nexus://schema/orders`
- `nexus://schema/inventory`

## Important AI-agent pages

### Nexus Documentation
URL: https://nexus-docs.aiforstartups.io/
Summary: Main landing page and navigation hub.

### API Reference
URL: https://nexus-docs.aiforstartups.io/api
Summary: API overview including bearer-token model, base URLs, and security model.

### Authentication
URL: https://nexus-docs.aiforstartups.io/api/auth
Summary: Human user auth, agent API-key exchange, token claims, and MCP auth requirements.

### AI Agents, API Keys, and MCP
URL: https://nexus-docs.aiforstartups.io/api/ai-agents-mcp
Summary: Canonical page for agent provisioning, JWT exchange, MCP endpoint usage, tools, resources, and deployed agent endpoints.

### Rate Limiting & Pagination
URL: https://nexus-docs.aiforstartups.io/api/rate-limiting
Summary: General API limits plus the 10 attempts/minute/IP rate limit on `agent-auth`.

### Edge Functions Reference
URL: https://nexus-docs.aiforstartups.io/reference/functions
Summary: Includes `agent-api-key-create`, `agent-auth`, `mcp-server`, and messaging functions used by agent workflows.

### Contacts & Companies
URL: https://nexus-docs.aiforstartups.io/concepts/contacts-companies
Summary: Contact/customer concept and related CRM entities.

### Conversations & Messages
URL: https://nexus-docs.aiforstartups.io/concepts/conversations-messages
Summary: Chat and message model across WhatsApp, Facebook, and Instagram.

### Orders & Fulfillment
URL: https://nexus-docs.aiforstartups.io/concepts/orders-fulfillment
Summary: Order model, lifecycle, and fulfillment workflow.

### Inventory & Warehousing
URL: https://nexus-docs.aiforstartups.io/concepts/inventory-warehousing
Summary: Items, stock balances, warehouses, and stock movement concepts.

## Direct API guidance for agents

Agents may use direct API access with the agent JWT when MCP is not suitable.

- PostgREST base: `https://lgwvoomgrwpsgpxwyaec.supabase.co/rest/v1/`
- Edge Functions base: `https://lgwvoomgrwpsgpxwyaec.supabase.co/functions/v1/`
- PostgREST requires:
  - `Authorization: Bearer <agent-jwt>`
  - `apikey: <anon-key>`

## Agent-relevant deployed endpoints

- `POST /functions/v1/agent-api-key-create`
- `POST /functions/v1/agent-auth`
- `POST /functions/v1/mcp-server`
- `POST /functions/v1/whatsapp-send-message`
- `POST /functions/v1/facebook-send-message`
- `POST /functions/v1/instagram-send-message`

## Core objects

- Contact (Customer): Core CRM record in `customers`
- Conversation (Chat): Threaded exchange in `chats`
- Message: Single event in `messages`
- Order: Sales transaction in `orders`
- Order Item: Normalized line item in `order_items`
- Inventory Item: Product record in `items`
- Stock Balance: Warehouse quantity in `stock_balances`

## Machine-readable resources

- Compatibility alias: https://nexus-docs.aiforstartups.io/llm.txt
- Short index: https://nexus-docs.aiforstartups.io/llms.txt
- This file: https://nexus-docs.aiforstartups.io/llms-full.txt
- OpenAPI 3.1 spec: https://nexus-docs.aiforstartups.io/openapi.yaml