@xylentis/xylentis-portal

One command. Any AI tool. Correct Xylentis API integration code.

npx @xylentis/xylentis-portal

The installer asks which AI you use (Claude Code / Cursor / Windsurf / Cline / GitHub Copilot / Gemini Code Assist / Aider / Codex / ...), then drops a curated docs bundle (OpenAPI spec, PAT setup, endpoint reference, sandbox guide, ready-to-paste TS/Python/PHP/Go/curl examples, error catalog) into the right place in your project. From then on, your AI writes correct Xylentis Affiliate API integration code on the first try.

Ask your AI things like:

• "Tích hợp Xylentis VPS vào reseller portal của tôi, bắt đầu từ đâu?"
• "Create a VPS order via the Xylentis API in TypeScript"
• "What ability does the Xylentis PAT need to read affiliate stats?"
• "I'm getting customer_email.exists from POST /affiliate/orders — what does that mean?"

Install

Option 1 — npx (recommended, works for any AI)

npx @xylentis/xylentis-portal              # interactive: pick your AI tool
npx @xylentis/xylentis-portal --yes        # non-interactive: auto-detect target
npx @xylentis/xylentis-portal --target=cursor   # explicit target (CI-friendly)
npx @xylentis/xylentis-portal --help       # all flags

Interactive prompt looks like this:

@xylentis/xylentis-portal installer

  cwd:      /Users/you/projects/your-reseller
  detected: cursor

Install Xylentis API docs for which AI tool?

  1. Claude Code                              → .claude/skills/xylentis-api/
  2. Cursor                                   → .cursor/rules/xylentis-api/      ← detected
  3. Windsurf                                 → docs/xylentis-api/ + .windsurfrules
  4. Cline                                    → docs/xylentis-api/ + .clinerules
  5. GitHub Copilot                           → docs/xylentis-api/ + .github/copilot-instructions.md
  6. Gemini Code Assist                       → docs/xylentis-api/ + AGENTS.md
  7. Other AI (Aider / Codex / Continue / generic AGENTS.md) → docs/xylentis-api/ + AGENTS.md
  0. Cancel

Select [2]:

Re-running is idempotent: existing rule sections aren't duplicated.

Option 2 — Claude Code marketplace (Claude Code only)

If you want machine-wide install + auto-updates without copying files into each project:

/plugin marketplace add Xylentis/xylentis-portal
/plugin install xylentis-api@xylentis-portal

Option 3 — git fallback (no npm, no Claude marketplace)

If you don't want any dependency on npm:

# tiged is the maintained fork of degit; works for any public GitHub subdir
npx tiged Xylentis/xylentis-portal/plugins/xylentis-api/skills/xylentis-api docs/xylentis-api

Then add a one-liner to your AI tool's rules file pointing at docs/xylentis-api/SKILL.md.

What gets installed where

| Target | Files land in | Why | |---|---|---| | claude | .claude/skills/xylentis-api/ | Claude Code reads project-local skills | | cursor | .cursor/rules/xylentis-api/ | Cursor reads all rule subdirs | | windsurf | docs/xylentis-api/ + appends to .windsurfrules | Windsurf rule references the docs | | cline | docs/xylentis-api/ + appends to .clinerules | Cline rule references the docs | | copilot | docs/xylentis-api/ + appends to .github/copilot-instructions.md | Copilot picks up custom instructions | | gemini | docs/xylentis-api/ + appends to AGENTS.md | Gemini Code Assist + AGENTS.md universal pattern | | agents | docs/xylentis-api/ + appends to AGENTS.md | Any AGENTS.md-aware agent (Aider, Codex, Continue…) |

Auto-detection scans for .claude/, .cursor/, .windsurfrules, .clinerules, .github/copilot-instructions.md, .gemini/, .idx/. Falls back to agents if nothing matches.

Override the docs directory: --dir=docs/api/xyl (applies to windsurf/cline/copilot/gemini/agents).

What's inside the bundle

| File | Loaded when | |---|---| | SKILL.md | Always (entry point, ~100 lines) | | auth-pat-setup.md | "How do I get an API token?" | | environments.md | "Sandbox vs production?" / "How do I test without real billing?" | | endpoints.md | "What endpoints exist?" / "Which ability for X?" | | seller-integration-spec.md | "Integrate into seller portal" / "which APIs to call first" | | https://portal.xylentis.com/api-docs.json (live) | "Exact schema for endpoint X" — OpenAPI 3.0.3, full Xylentis surface. Filter paths to /affiliate/* for the partner-facing subset (8 endpoints). Vietnamese variant: api-docs.vi.json. | | examples/ | "Show me code in TS / Python / PHP / Go / curl" | | errors.md | "What does HTTP 400/403/422/503 mean?" |

Quickstart for partners — sandbox first

Always test on sandbox first — mocked Proxmox, nightly data reset, no real billing. Full env comparison: environments.md.

1. Sign in at https://sandbox-portal.xylentis.com (or use seeded [email protected] / default password Demo@2026).
2. Open Settings → Security → Integration API keys → Create token (direct link: /settings#integration-api-keys). Pick least-privilege abilities; for a full-flow test check all 7: products:read, regions:read, pricing:read, orders:create, orders:read, customers:read, affiliate:read.
3. Copy the token (shown once).
4. In your project:

   npx @xylentis/xylentis-portal               # answer the prompt for your AI tool
   export XYLENTIS_API_URL=https://sandbox-portal.xylentis.com/api/v1
   export XYLENTIS_PAT=<sandbox-token>

5. Ask your AI: "using the xylentis-api skill, write a TypeScript function that calls POST /affiliate/orders".
6. When sandbox tests pass, regenerate the PAT at https://portal.xylentis.com (production), swap env vars (unset XYLENTIS_API_URL to default to production), and ship.

No-AI alternative — generate a typed SDK

Don't want AI in the loop? Generate a client directly from the live OpenAPI spec at https://portal.xylentis.com/api-docs.json:

npx openapi-typescript https://portal.xylentis.com/api-docs.json -o xylentis.d.ts
# or any other language
npx @openapitools/openapi-generator-cli generate \
    -i https://portal.xylentis.com/api-docs.json -g python -o ./xylentis-sdk

The published spec covers the full Xylentis surface. The 8 partner endpoints — GET /products, GET /regions, POST /pricing, POST /orders, GET /orders, GET /orders/{vps_code}, GET /customers, GET /stats — all live under /affiliate/*. If your generator supports path filtering, restrict to that prefix so the generated SDK doesn't expose the internal /user/* and /admin/* (session-token-only) routes that also appear in the spec.

For Xylentis maintainers

Regenerate the published OpenAPI JSON

Source of truth: web/src/features/api-docs/openapi/affiliateIntegrationSpec.ts — same module the live Swagger UI loads. After editing it:

cd web && npm run export:openapi

That writes services/api/public/api-docs.json and services/api/public/api-docs.vi.json (full spec, production base URL). nginx serves them as static files at https://portal.xylentis.com/api-docs{,.vi}.json. Commit both files so they ship with the next deploy. This skill no longer bundles its own copy of the JSON — it points consumers at the live URL instead, which guarantees AI agents and generated SDKs always see the latest spec.

Release a new version

1. Bump version in package.json and .claude-plugin/plugin.json — keep them in sync.
2. Commit + tag:

   git tag v1.0.0 && git push --tags

3. Publish to npm:

   cd plugins/xylentis-api
   npm publish --access=public

   Use npm pack --dry-run first to inspect the tarball. The @xylentis org owner credentials (or a granular token with Scope: @xylentis + Bypass 2FA) are required.
4. The Claude Code marketplace entry updates automatically on the next /plugin marketplace update once the new commit reaches the repo's default branch (main).

License

MIT — see LICENSE (root of repo).