hamravesh-mcp 0.1.0

package/WRITE-ENDPOINTS.md

@@ -0,0 +1,264 @@
+# Hamravesh — بدنه‌ی درخواست write ها
+
+> استخراج‌شده از کد پنل کنسول هم‌روش (۱۴۰۵/۰۳/۲۳ — 2026-06-13).
+> ستون «Body» شکل بدنه‌ی JSON است که فرانت می‌فرستد. متغیرهای تک‌حرفی (مثل `t`,`i`,`e`) یعنی
+> یک آبجکت/مقدار که از ورودی کاربر می‌آید. `{paas}`=`darkube`.
+
+> 🔐 احراز هویت: `Authorization: Api-Key <key>` + `X-Organization: <org>` (یا `Bearer <jwt>`).
+
+---
+
+## ⭐ ساخت اپ داکر-ایمیج — بدنه‌ی تأییدشده با تست زنده (2026-06-13)
+
+این بدنه با ضبط از پنل + اجرای واقعی (CREATE→201، RESTART→200، DELETE→204) تأیید شده است:
+
+```
+POST /api/v1/darkube/apps/
+{
+  "image_repo": "traefik/whoami",
+  "image_tag": "latest",
+  "builder": "dockerfile",
+  "creation_method": "docker_image",
+  "name": "<نام یکتا، بعداً غیرقابل‌تغییر>",
+  "svc": {"type":"ClusterIP","ports":{"main":{"protocol":"TCP","servicePort":80,"containerPort":80}}},
+  "command": "",
+  "args": "",
+  "readiness_probe_path": "",
+  "custom_config": {},
+  "plan": "<uuid پلن منابع>",
+  "replicas": 1,
+  "backup_config": null,
+  "namespace": <id عددی namespace>,
+  "deploy_context": null,
+  "ssl_challenge_type": "dns01",
+  "organization": <id عددی سازمان>
+}
+→ 201 { "id": "<uuid اپ>", ... }
+```
+
+- مقادیر **wgcup**: `organization=24772`، `namespace=165693`، پلن کوچک `plan=73904144-6592-40ce-a96f-3789f611b5e4` (۵۰۰MB/0.25core).
+- یک pre-step هم هست: `POST /api/v1/darkube/apps/schedule_info/` (پنل قبل از create صدا می‌زند؛ برای create لازم نیست).
+- **چرخه‌ی عمر تأییدشده:** `POST .../apps/{id}/restart/` با `{}` → 200 ؛ `DELETE .../apps/{id}/` (بدون بدنه) → 204.
+- این دقیقاً همان کاری است که ابزار `hamravesh_create_app` در MCP انجام می‌دهد.
+
+## Auth & API Keys
+
+| Method | Path | Body |
+|---|---|---|
+| POST | `/api/v1/2fa/disable/` | `e` |
+| POST | `/api/v1/2fa/enable/` | `e` |
+| POST | `/api/v1/account/cluster/cluster_ingress_host_name/` | `e` |
+| POST | `/api/v1/apikeys/` | `e` |
+| DELETE | `/api/v1/apikeys/{id}/` | `e` |
+| POST | `/api/v1/oauth/auth/` | `t` |
+| POST | `/api/v1/token/` | `a` |
+| POST | `/api/v1/token/refresh/` | `{refresh:a}` |
+| POST | `/api/v1/users/change_password/` | `e` |
+| POST | `/api/v1/users/forget_password/` | `e` |
+| POST | `/api/v1/users/logout` | `{token:a,organization_id:t}` |
+| PUT | `/api/v1/users/profile` | `e` |
+| POST | `/api/v1/users/reset_password/` | `e` |
+| PUT | `/api/v2/users/profile` | `e` |
+| POST | `/api/v2/users/register_user/` | `e` |
+| POST | `/api/v2/users/resend_verification_email/` | `e` |
+| POST | `/api/v2/users/send_verification_sms/` | `e` |
+| POST | `/api/v2/users/update_email/` | `e` |
+| POST | `/api/v2/users/verify_email/` | `e` |
+| POST | `/api/v2/users/verify_mobile/` | `e` |
+| POST | `/api/v2/users/verify_mobile_national_id/` | `e` |
+
+## PaaS / Darkube apps
+
+| Method | Path | Body |
+|---|---|---|
+| POST | `/api/v1/darkube/apps/{id}/backup/download_information/` | `{backup_id:t}` |
+| POST | `/api/v1/darkube/apps/{id}/backup/trigger_backup/` | `{backup_id:t}` |
+| POST | `/api/v1/darkube/apps/{id}/backup/trigger_restore/` | `{snapshot_id:t}` |
+| POST | `/api/v1/darkube/apps/{id}/compatible_plan/` | `{backupConfig:t}` |
+| PUT | `/api/v1/darkube/database/user/{id}` | `{username:t,password:r}` |
+| POST | `/api/v1/darkube/postgres_standby/check` | `{src_host:s,src_username:r,src_password:a,src_port:t,dst_tag:o}` |
+| PUT | `/api/v1/darkube/promote-to-master/{id}` | `—` |
+| POST | `/api/v1/darkube/pvcs/defrag/` | `e` |
+| POST | `/api/v1/{paas}/apps/` | `a` |
+| POST | `/api/v1/{paas}/apps/check_dns_records/` | `{hosts:a}` |
+| POST | `/api/v1/{paas}/apps/check_subdomain/` | `{subdomain:a}` |
+| POST | `/api/v1/{paas}/apps/docker_compose/` | `e` |
+| POST | `/api/v1/{paas}/apps/schedule_info/` | `e` |
+| DELETE | `/api/v1/{paas}/apps/{id}/` | `{git_repo_url:i}` |
+| PATCH | `/api/v1/{paas}/apps/{id}/` | `{fields:["is_enabled"],is_enabled:i}` |
+| PUT | `/api/v1/{paas}/apps/{id}/` | `i` |
+| POST | `/api/v1/{paas}/apps/{id}/app_files/` | `a` |
+| POST | `/api/v1/{paas}/apps/{id}/check_repo/` | `{git_repo_url:i}` |
+| POST | `/api/v1/{paas}/apps/{id}/migrate/` | `i` |
+| DELETE | `/api/v1/{paas}/apps/{id}/plugins/` | `—` |
+| POST | `/api/v1/{paas}/apps/{id}/plugins/` | `{plugin_type:i}` |
+| POST | `/api/v1/{paas}/apps/{id}/read_vault_secret/` | `{path:t}` |
+| POST | `/api/v1/{paas}/apps/{id}/read_vault_secret_env/` | `{name:t}` |
+| POST | `/api/v1/{paas}/apps/{id}/reinstall/` | `{}` |
+| POST | `/api/v1/{paas}/apps/{id}/restart/` | `{}` |
+| POST | `/api/v1/{paas}/apps/{id}/ssl_certificate_records/` | `{external_hosts:i}` |
+| POST | `/api/v1/{paas}/apps/{id}/suggestions/` | `{}` |
+| POST | `/api/v1/{paas}/apps/{id}/upgrade_version/` | `t` |
+| POST | `/api/v1/{paas}/build/{id}/stop/` | `{}` |
+| POST | `/api/v1/{paas}/deploy_contexts/` | `e` |
+| DELETE | `/api/v1/{paas}/deploy_contexts/{id}/` | `a` |
+| PUT | `/api/v1/{paas}/deploy_contexts/{id}/` | `i` |
+| POST | `/api/v1/{paas}/github/branches/` | `{full_name:a}` |
+| POST | `/api/v1/{paas}/gitlab/branches/` | `{id:a}` |
+| POST | `/api/v1/{paas}/license/confluence/` | `a` |
+| POST | `/api/v1/{paas}/license/jira/` | `a` |
+| POST | `/api/v1/{paas}/license/jirasm/` | `a` |
+| POST | `/api/v1/{paas}/license/plugin/` | `a` |
+| POST | `/api/v1/{paas}/logs/loki/` | `{app_id:a,start:i,end:r,stream_name:s}` |
+| POST | `/api/v1/{paas}/namespaces/` | `{name:a,cluster_id:i}` |
+| PUT | `/api/v1/{paas}/permissions/app/{id}/` | `i` |
+| PUT | `/api/v1/{paas}/permissions/user/{id}/` | `i` |
+| POST | `/api/v1/{paas}/plans/calculator/` | `a` |
+| POST | `/api/v1/{paas}/stateless_apps/sync_apps_data/` | `{}` |
+| DELETE | `/api/v1/{paas}/template/` | `s` |
+
+## Databases (DBaaS)
+
+| Method | Path | Body |
+|---|---|---|
+| POST | `/dbaas/api/v1/app/backups/{app_id}/download_info/` | `—` |
+| POST | `/dbaas/api/v1/app/backups/{app_id}/trigger_backup/` | `—` |
+| POST | `/dbaas/api/v1/app/database/` | `{...a,cpu:(0,r.yr)(a.cpu),ram:(0,r.ft)(a.ram),disk:(0,r.ft)(a.disk)}` |
+| POST | `/dbaas/api/v1/app/database/compatibility_check/` | `{src_host:e,src_username:l,src_password:o,src_port:i,dst_tag:r,engine:t}` |
+| PUT | `/dbaas/api/v1/app/database/config/{app_id}/` | `{config:a.config}` |
+| POST | `/dbaas/api/v1/app/database/readonly-cluster/` | `{...a,cpu:(0,r.yr)(a.cpu),ram:(0,r.ft)(a.ram),disk:(0,r.ft)(a.disk)}` |
+| DELETE | `/dbaas/api/v1/app/database/{app_id}/` | `—` |
+| PUT | `/dbaas/api/v1/app/database/{app_id}/` | `{plan:a.plan,disk:(0,r.ft)(a.disk),cpu:(0,r.yr)(a.cpu),ram:(0,r.ft)(a.ram),nodes:a.nodes}` |
+| POST | `/dbaas/api/v1/app/database/{app_id}/external_access/` | `—` |
+| POST | `/dbaas/api/v1/app/database/{app_id}/internal_access/` | `—` |
+| POST | `/dbaas/api/v1/app/database/{app_id}/shutdown/` | `—` |
+| POST | `/dbaas/api/v1/app/database/{app_id}/start/` | `—` |
+| POST | `/dbaas/api/v1/app/database/{id}/promote/` | `—` |
+| POST | `/dbaas/api/v1/app/db/database/{app_id}/` | `{db_name:a.database}` |
+| DELETE | `/dbaas/api/v1/app/db/database/{app_id}/{id}/` | `{db_name:a.database}` |
+| PUT | `/dbaas/api/v1/app/permissions/database/{app_id}/` | `a.permissions` |
+| DELETE | `/dbaas/api/v1/app/pghero/{app_id}` | `—` |
+| POST | `/dbaas/api/v1/app/pghero/{app_id}` | `—` |
+| POST | `/dbaas/api/v1/app/pools/database/{app_id}/` | `{pool_name:a.poolName,pool_mode:a.poolMode,db_name:a.database,user_name:a.username,pool_size:a.poolSize}` |
+| DELETE | `/dbaas/api/v1/app/pools/database/{app_id}/{id}/` | `{pool_name:a.poolName,pool_mode:a.poolMode,db_name:a.database,user_name:a.username,pool_size:a.poolSize}` |
+| PUT | `/dbaas/api/v1/app/pools/database/{app_id}/{id}/` | `{pool_mode:a.poolMode,db_name:a.database,user_name:a.username,pool_size:a.poolSize}` |
+| POST | `/dbaas/api/v1/app/query-analysis/{app_id}/activate/` | `i` |
+| POST | `/dbaas/api/v1/app/query-analysis/{id}/metrics/` | `i` |
+| POST | `/dbaas/api/v1/app/query-analysis/{id}/report/` | `i` |
+| POST | `/dbaas/api/v1/app/user/database/{app_id}/` | `{username:a.username}` |
+| DELETE | `/dbaas/api/v1/app/user/database/{app_id}/{id}/` | `—` |
+| PUT | `/dbaas/api/v1/app/user/database/{app_id}/{id}/change_password/` | `{username:a.username}` |
+
+## Container Registry
+
+| Method | Path | Body |
+|---|---|---|
+| POST | `/api/v1/registry-gc-strategies/` | `—` |
+| DELETE | `/api/v1/registry-gc-strategies/{id}/` | `—` |
+| PUT | `/api/v1/registry-gc-strategies/{id}/` | `i` |
+| POST | `/api/v1/registry/` | `a` |
+| DELETE | `/api/v1/registry/{id}/` | `{secret_fields:["vault_password"]}` |
+| POST | `/api/v1/registry/{id}/change_password/` | `i` |
+| POST | `/api/v1/registry/{id}/delete_digests/` | `{repository_name:i,digests_sha:r}` |
+| POST | `/api/v1/registry/{id}/delete_repository/` | `{repository_name:i}` |
+| POST | `/api/v1/registry/{id}/delete_tags/` | `{repository_name:i,tags:r,digest_sha:s}` |
+| POST | `/api/v1/registry/{id}/list_repository_digests/` | `{repository_name:i}` |
+| POST | `/api/v1/registry/{id}/read_vault_secret/` | `{secret_fields:["vault_password"]}` |
+
+## Monitoring & Logging
+
+| Method | Path | Body |
+|---|---|---|
+| POST | `/api/v1/datasources/` | `{name:s,plan:a,datasource_type:r,zone_id:i}` |
+| DELETE | `/api/v1/datasources/zones/` | `—` |
+| DELETE | `/api/v1/datasources/{id}` | `{username:s,role:a}` |
+| POST | `/api/v1/datasources/{id}/users/` | `{username:s,role:a}` |
+| DELETE | `/api/v1/datasources/{id}/users/{id}/` | `—` |
+| POST | `/api/v1/dazzle/metric-datasources/` | `{}` |
+| DELETE | `/api/v1/dazzle/metric-datasources/{id}/` | `{secret_fields:["vault_password"]}` |
+| POST | `/api/v1/dazzle/metric-datasources/{id}/read_vault_secret/` | `{secret_fields:["vault_password"]}` |
+| POST | `/api/v1/hamartia/datasources/` | `{}` |
+| DELETE | `/api/v1/hamartia/datasources/{id}/` | `i` |
+| POST | `/api/v1/hamartia/datasources/{id}/pipelines/` | `i` |
+| DELETE | `/api/v1/hamartia/datasources/{id}/pipelines/?pipeline_id={id}` | `{secret_fields:["vault_password"]}` |
+| POST | `/api/v1/hamartia/datasources/{id}/read_vault_secret/` | `{secret_fields:["vault_password"]}` |
+| POST | `/api/v1/logstorage/loki/` | `{name:s,controller_loki_service:a,users:l}` |
+| DELETE | `/api/v1/logstorage/loki/{id}/` | `—` |
+| PUT | `/api/v1/logstorage/loki/{id}/` | `{users:l}` |
+| DELETE | `/api/v1/logstorage/loki/{id}/users/{id}/` | `{data_store_name:a,` |
+| POST | `/api/v1/loki/usages/` | `{data_store_name:a,data_store_id:t}` |
+
+## Marketplace / SaaS
+
+| Method | Path | Body |
+|---|---|---|
+| POST | `/api/v1/app/license/{id}/` | `o` |
+| POST | `/api/v1/app/saas/` | `e` |
+| POST | `/api/v1/app/saas/set_ssl_challenge_dns01/` | `{app_id:e.serviceId,domain:e.domain}` |
+| DELETE | `/api/v1/app/saas/{id}/` | `e` |
+| PUT | `/api/v1/app/saas/{id}/` | `o` |
+| POST | `/api/v1/app/saas/{id}/backup/download_info/` | `{backup_id:o}` |
+| POST | `/api/v1/app/saas/{id}/backup/trigger_backup/` | `{backup_id:o}` |
+| POST | `/api/v1/app/saas/{id}/backup/trigger_restore/` | `{snapshot_id:o}` |
+| POST | `/api/v1/app/saas/{id}/check_upgrade_compatibility/` | `o` |
+| POST | `/api/v1/app/saas/{id}/disable_filebrowser/` | `—` |
+| POST | `/api/v1/app/saas/{id}/enable_filebrowser/` | `o` |
+| POST | `/api/v1/app/saas/{id}/restart/` | `o` |
+| POST | `/api/v1/app/saas/{id}/set_ssl_challenge_type/` | `{ssl_challenge_type:e.ssl_challenge_type}` |
+| POST | `/api/v1/app/saas/{id}/shown_field/` | `o` |
+| POST | `/api/v1/app/saas/{id}/ssl_certificate_records/` | `{external_hosts:e.external_hosts}` |
+| PUT | `/api/v1/app/saas/{id}/version_upgrade/` | `o` |
+
+## Organizations & Members
+
+| Method | Path | Body |
+|---|---|---|
+| POST | `/api/v1/organizations/join_by_token` | `{token:a,organization_id:t}` |
+| POST | `/api/v1/organizations/{id}/accept-transfer` | `null` |
+| POST | `/api/v1/organizations/{id}/cancel-transfer` | `null` |
+| PUT | `/api/v1/organizations/{id}/edit` | `i` |
+| DELETE | `/api/v1/organizations/{id}/enforce-2fa/` | `e` |
+| POST | `/api/v1/organizations/{id}/enforce-2fa/` | `—` |
+| POST | `/api/v1/organizations/{id}/initiate-transfer` | `{target_user_email:i}` |
+| POST | `/api/v1/organizations/{id}/leave` | `null` |
+| PUT | `/api/v1/organizations/{id}/members` | `i` |
+| POST | `/api/v1/organizations/{id}/reject-transfer` | `null` |
+
+## Billing
+
+| Method | Path | Body |
+|---|---|---|
+| POST | `/api/v1/billing/billbillak/history/` | `{app_name:t,cluster:i,namespace:a,resource:r,owner_kind:n,start_time:l,end_time:s}` |
+| POST | `/api/v1/billing/invoices/export_report/` | `{start_date:t,end_date:i}` |
+| POST | `/api/v1/billing/invoices/invoice_settings/` | `e` |
+
+## Sentry
+
+| Method | Path | Body |
+|---|---|---|
+| POST | `/api/v1/sentry/sentrys/` | `e` |
+| DELETE | `/api/v1/sentry/sentrys/{id}/` | `t` |
+| PATCH | `/api/v1/sentry/sentrys/{id}/` | `t` |
+
+## Notifications & Alerts
+
+| Method | Path | Body |
+|---|---|---|
+| POST | `/api/v1/viper/alert_routes/` | `a` |
+| DELETE | `/api/v1/viper/alert_routes/{id}/` | `—` |
+| POST | `/notifications/alerts/api/organization-id-alert-routers/` | `e` |
+
+## Backup
+
+| Method | Path | Body |
+|---|---|---|
+| POST | `/api/v1/backups/storage_destinations/{id}/read_vault_secret/` | `{secret_fields:["vault_password"]}` |
+
+## Other
+
+| Method | Path | Body |
+|---|---|---|
+| PUT | `/api/v1/{id}/permissions/user/{id}/` | `o` |
+| POST | `/backup/` | `{...s,worker_type:"rclone",sync_mode:"backup"}` |
+| DELETE | `/backup/{id}/` | `{user_email:e.user_email,st` |
+| DELETE | `/backup/{id}/progress` | `{user_email:e.user_email,storages_access:e.storages_access}` |

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "hamravesh-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for the Hamravesh / Darkube console API — manage apps, deploys, databases, registries and billing from any MCP client (Claude, etc.).",
+  "type": "module",
+  "bin": {
+    "hamravesh-mcp": "src/index.js"
+  },
+  "main": "src/index.js",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    ".env.example",
+    "ENDPOINTS.md",
+    "WRITE-ENDPOINTS.md",
+    "LIVE-STATUS.md",
+    "ENDPOINTS-RAW.txt"
+  ],
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "node test/ci.js",
+    "smoke": "node test/smoke.js",
+    "smoke:write": "node test/write-smoke.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "modelcontextprotocol",
+    "hamravesh",
+    "darkube",
+    "kubernetes",
+    "paas",
+    "devops",
+    "claude",
+    "ai"
+  ],
+  "license": "MIT",
+  "author": "Mohammad Bakhtari <skyborn91@gmail.com>",
+  "homepage": "https://github.com/bakhtarimohammad/hamravesh-mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bakhtarimohammad/hamravesh-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/bakhtarimohammad/hamravesh-mcp/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.18.0"
+  }
+}

package/src/client.js

@@ -0,0 +1,181 @@
+// @ts-check
+/**
+ * client.js — کلاینت HTTP برای API داخلی کنسول هم‌روش (api.hamravesh.com).
+ *
+ * دو روش احراز هویت:
+ *   1) API Key  (توصیه‌شده):  هدر  Authorization: Api-Key <key>
+ *   2) ایمیل/رمز:             لاگین JWT + تمدید خودکار توکن
+ *
+ * این کلاینت از fetch داخلی Node (>=18) استفاده می‌کند؛ هیچ وابستگی شبکه‌ای ندارد.
+ */
+
+const DEFAULT_BASE = "https://api.hamravesh.com";
+
+/** @param {string} token */
+function jwtExp(token) {
+  try {
+    const payload = token.split(".")[1];
+    const json = Buffer.from(payload.replace(/-/g, "+").replace(/_/g, "/"), "base64").toString("utf8");
+    return (JSON.parse(json).exp || 0) * 1000; // ms
+  } catch {
+    return 0;
+  }
+}
+
+export class HamraveshError extends Error {
+  /** @param {number} status @param {any} body */
+  constructor(status, body) {
+    const msg = typeof body === "string" ? body : JSON.stringify(body);
+    super(`HTTP ${status}: ${msg}`);
+    this.name = "HamraveshError";
+    this.status = status;
+    this.body = body;
+  }
+}
+
+export class HamraveshClient {
+  /**
+   * @param {object} cfg
+   * @param {string} [cfg.apiKey]
+   * @param {string} [cfg.email]
+   * @param {string} [cfg.password]
+   * @param {string} [cfg.otp]
+   * @param {string} [cfg.org]      سازمان پیش‌فرض (X-Organization)
+   * @param {string} [cfg.base]     base URL
+   */
+  constructor(cfg = {}) {
+    this.apiKey = cfg.apiKey || "";
+    this.email = cfg.email || "";
+    this.password = cfg.password || "";
+    this.otp = cfg.otp || "";
+    this.org = cfg.org || "";
+    this.base = (cfg.base || DEFAULT_BASE).replace(/\/$/, "");
+    /** @type {{access?:string, refresh?:string}} */
+    this.tokens = {};
+    if (!this.apiKey && (!this.email || !this.password)) {
+      throw new Error(
+        "احراز هویت تنظیم نشده: یا HAMRAVESH_API_KEY بده، یا HAMRAVESH_EMAIL + HAMRAVESH_PASSWORD."
+      );
+    }
+  }
+
+  get authMode() {
+    return this.apiKey ? "api-key" : "password";
+  }
+
+  async _login() {
+    const r = await fetch(this.base + "/api/v1/token/", {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json" },
+      body: JSON.stringify({
+        email: this.email,
+        password: this.password,
+        captcha: "",
+        client_time: Date.now(),
+        ...(this.otp ? { otp: this.otp } : {}),
+      }),
+    });
+    // متن را اول بگیر تا اگر JSON نبود، خطای واقعی گم نشود
+    const text = await r.text();
+    let body;
+    try {
+      body = text ? JSON.parse(text) : {};
+    } catch {
+      body = text;
+    }
+    if (!r.ok) throw new HamraveshError(r.status, body);
+    this.tokens = { access: body.access, refresh: body.refresh };
+  }
+
+  async _refresh() {
+    const rt = this.tokens.refresh;
+    if (!rt || jwtExp(rt) < Date.now() + 30_000) return this._login();
+    const r = await fetch(this.base + "/api/v1/token/refresh/", {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json" },
+      body: JSON.stringify({ refresh: rt }),
+    });
+    if (!r.ok) return this._login();
+    const body = await r.json().catch(() => ({}));
+    this.tokens.access = body.access;
+    if (body.refresh) this.tokens.refresh = body.refresh;
+  }
+
+  async _authHeader() {
+    if (this.apiKey) return "Api-Key " + this.apiKey;
+    const exp = this.tokens.access ? jwtExp(this.tokens.access) : 0;
+    if (!this.tokens.access || exp <= 0 || exp < Date.now() + 60_000) {
+      await this._refresh();
+    }
+    return "Bearer " + this.tokens.access;
+  }
+
+  /**
+   * یک درخواست خام به API هم‌روش.
+   * @param {string} method
+   * @param {string} path  مثل /api/v1/darkube/apps/  یا URL کامل
+   * @param {object} [opts]
+   * @param {string} [opts.org]
+   * @param {Record<string,any>} [opts.params]
+   * @param {any} [opts.body]
+   * @returns {Promise<{status:number, body:any}>}
+   */
+  async request(method, path, opts = {}) {
+    const org = opts.org || this.org;
+    // قفلِ میزبان: فقط با base host خودِ هم‌روش حرف بزن (جلوگیری از SSRF)
+    let url;
+    if (path.startsWith("http")) {
+      const u = new URL(path);
+      const baseHost = new URL(this.base).host;
+      if (u.host !== baseHost) {
+        throw new Error(`میزبان غیرمجاز: ${u.host} — فقط ${baseHost} مجاز است.`);
+      }
+      url = path;
+    } else {
+      if (!path.startsWith("/")) throw new Error("مسیر باید با / شروع شود.");
+      url = this.base + path;
+    }
+    if (opts.params && typeof opts.params === "object" && !Array.isArray(opts.params) && Object.keys(opts.params).length) {
+      const qs = new URLSearchParams();
+      for (const [k, v] of Object.entries(opts.params)) {
+        if (v === undefined || v === null) continue;
+        if (Array.isArray(v)) v.forEach((x) => qs.append(k, String(x)));
+        else qs.append(k, String(v));
+      }
+      url += (url.includes("?") ? "&" : "?") + qs.toString();
+    }
+    const doFetch = async () => {
+      const headers = {
+        accept: "application/json, text/plain, */*",
+        "accept-language": "fa",
+        authorization: await this._authHeader(),
+      };
+      if (org) headers["x-organization"] = org;
+      /** @type {RequestInit} */
+      const init = { method: method.toUpperCase(), headers };
+      if (opts.body !== undefined && method.toUpperCase() !== "GET") {
+        headers["content-type"] = "application/json";
+        init.body = JSON.stringify(opts.body);
+      }
+      return fetch(url, init);
+    };
+    let r = await doFetch();
+    if (r.status === 401 && this.authMode === "password") {
+      await this._login();
+      r = await doFetch();
+    }
+    let body;
+    const text = await r.text();
+    try {
+      body = text ? JSON.parse(text) : "";
+    } catch {
+      body = text;
+    }
+    if (!r.ok) throw new HamraveshError(r.status, body);
+    return { status: r.status, body };
+  }
+
+  get(path, opts) {
+    return this.request("GET", path, opts);
+  }
+}