پرش به مطلب اصلی

SDK جاوااسکریپت / تایپ‌اسکریپت

🖼
تصویر: استفاده از SDK JavaScriptplaceholder — تصویر را اینجا جایگزین کنید

SDK رسمی ابرکلیک برای جاوااسکریپت و تایپ‌اسکریپت. تمام عملیات پلتفرم از جمله مدیریت اپلیکیشن‌ها، دیتابیس‌ها و دیپلوی را از کد خود انجام دهید.

نصب​

npm install @abrclick/sdk

یا با pnpm / yarn:

pnpm add @abrclick/sdk
yarn add @abrclick/sdk

راه‌اندازی اولیه​

برای استفاده از SDK به یک API Key نیاز دارید. از داشبورد به تنظیمات → API Keys بروید و یک کلید جدید بسازید.

import { AbrclickClient } from '@abrclick/sdk';

const client = new AbrclickClient({
  apiKey: 'abr_live_xxxxxxxxxxxxxxxxxxxx',
});
متغیر محیطی

API Key خود را هرگز مستقیم در کد قرار ندهید. از متغیر محیطی استفاده کنید:

const client = new AbrclickClient({
  apiKey: process.env.ABRCLICK_API_KEY!,
});

اپلیکیشن‌ها​

لیست اپلیکیشن‌ها​

import { AbrclickClient } from '@abrclick/sdk';

const client = new AbrclickClient({ apiKey: process.env.ABRCLICK_API_KEY! });

async function listApps() {
  const apps = await client.apps.list({ projectId: 'proj_abc123' });

  for (const app of apps) {
    console.log(`${app.name} — ${app.status} — ${app.url}`);
  }
}

listApps();

نوع بازگشتی:

interface App {
  id: string;
  name: string;
  slug: string;
  runtime: 'node' | 'python' | 'go' | 'php' | 'static' | 'docker';
  status: 'running' | 'stopped' | 'building' | 'error' | 'creating';
  url: string;
  projectId: string;
  createdAt: string;
  updatedAt: string;
}

ساخت اپلیکیشن جدید​

const app = await client.apps.create({
  projectId: 'proj_abc123',
  name: 'my-api',
  runtime: 'node',
  port: 3000,
});

console.log(`اپ ساخته شد: ${app.url}`);

پارامترها:

interface CreateAppInput {
  projectId: string;
  name: string;
  runtime: 'node' | 'python' | 'go' | 'php' | 'static' | 'docker';
  port?: number;       // پیش‌فرض: 3000
  rootDir?: string;    // پیش‌فرض: '/'
}

اطلاعات یک اپلیکیشن​

const app = await client.getApp('app_xyz789');

console.log(app.status);   // 'running'
console.log(app.url);      // 'https://my-api.apps.abrclick.cloud'

شروع، توقف و ری‌استارت​

await client.startApp('app_xyz789');
await client.stopApp('app_xyz789');
await client.restartApp('app_xyz789');

حذف اپلیکیشن​

await client.deleteApp('app_xyz789');

دیپلوی​

دیپلوی از سورس کد​

import { AbrclickClient } from '@abrclick/sdk';
import path from 'path';

const client = new AbrclickClient({ apiKey: process.env.ABRCLICK_API_KEY! });

async function deploy() {
  // گام 1: دریافت URL آپلود
  const { uploadUrl, sourceKey } = await client.getSourceUploadUrl('app_xyz789');
  
  // گام 2: آپلود tarball به S3 (با axios یا fetch)
  // ... (آپلود کد منبع به uploadUrl)
  
  // گام 3: شروع دیپلوی
  const deployment = await client.deployApp('app_xyz789', {
    source_type: 'upload',
    source_key: sourceKey,
  });

  console.log(`دیپلوی شروع شد: ${deployment.id}`);

  // پیگیری لاگ‌های live
  for await (const line of client.streamBuildLogs('app_xyz789', deployment.id)) {
    process.stdout.write(line);
  }

  console.log(`دیپلوی کامل شد`);
}

deploy();

دیپلوی با ایمیج از پیش ساخته‌شده​

const deployment = await client.deployApp('app_xyz789', {
  source_type: 'image',
  image_tag: 'harbor.abrclick.ir/my-tenant/my-app:v1.2.3',
});

نوع Deployment:

interface Deployment {
  id: string;
  appId: string;
  status: 'pending' | 'building' | 'deploying' | 'success' | 'failed';
  imageTag: string;
  createdAt: string;
  finishedAt?: string;
}

دیتابیس‌ها​

لیست دیتابیس‌ها​

const { data: databases } = await client.getDatabases('proj_abc123', 1, 20);

for (const db of databases) {
  console.log(`${db.name} (${db.type} ${db.version}) — ${db.status}`);
}

نوع Database:

interface Database {
  id: string;
  name: string;
  type: 'postgresql' | 'redis' | 'mongodb';
  version: string;
  status: 'provisioning' | 'running' | 'error' | 'deleting';
  storageGb: number;
  projectId: string;
  createdAt: string;
}

ساخت دیتابیس جدید​

// PostgreSQL
const pg = await client.createDatabase('proj_abc123', {
  name: 'main-db',
  type: 'postgres',
  version: '16',
  storage_gb: 10,
});

// Redis
const redis = await client.createDatabase('proj_abc123', {
  name: 'cache',
  type: 'redis',
  version: '7',
  storage_gb: 2,
});

// MongoDB
const mongo = await client.createDatabase('proj_abc123', {
  name: 'documents',
  type: 'mongo',
  version: '7',
  storage_gb: 20,
});

console.log(`دیتابیس در حال ساخت: ${pg.id}`);

پارامترها:

interface CreateDatabaseInput {
  name: string;
  type: 'postgres' | 'redis' | 'mongo' | 'mysql' | 'mariadb' | 'valkey' | 'memcached' | 'rabbitmq' | 'kafka';
  version: string;
  storage_gb: number;
  cpu_limit?: string;
  memory_limit?: string;
  replica_set?: boolean;
}

اطلاعات یک دیتابیس​

const db = await client.getDatabase('db_abc456');

console.log(db.status);    // 'running'
console.log(db.storage_gb); // 10

دریافت اطلاعات اتصال​

const credentials = await client.getDatabaseCredentials('db_abc456');

console.log(credentials.host);
console.log(credentials.port);
console.log(credentials.username);
console.log(credentials.password);
console.log(credentials.connection_string);
// postgresql://user:pass@host:5432/dbname

نوع DatabaseCredentials:

interface DatabaseCredentials {
  host: string;
  port: number;
  username: string;
  password: string;
  database: string;
  connectionString: string;
}
امنیت

اطلاعات اتصال را هرگز در کد یا لاگ ذخیره نکنید. آن‌ها را مستقیم به عنوان متغیر محیطی به اپلیکیشن تزریق کنید.

حذف دیتابیس​

await client.deleteDatabase('db_abc456');

پروژه‌ها​

// لیست پروژه‌ها
const projects = await client.getProjects();

// ساخت پروژه جدید
const project = await client.createProject({ name: 'my-startup' });

// حذف پروژه
await client.deleteProject('proj_abc123');

نوع Project:

interface Project {
  id: string;
  name: string;
  slug: string;
  createdAt: string;
}

مدیریت خطا​

تمام متدها در صورت بروز خطا یک نمونه از AbrclickError پرتاب می‌کنند:

import { AbrclickClient, AbrclickError } from '@abrclick/sdk';

const client = new AbrclickClient({ apiKey: process.env.ABRCLICK_API_KEY! });

async function safeCreateApp() {
  try {
    const app = await client.apps.create({
      projectId: 'proj_abc123',
      name: 'my-api',
      runtime: 'node',
    });
    console.log('اپ ساخته شد:', app.id);
  } catch (err) {
    if (err instanceof AbrclickError) {
      console.error('کد خطا:', err.code);
      // مثال: 'APP_LIMIT_REACHED'

      console.error('پیام فارسی:', err.messageFa);
      // مثال: 'به محدودیت تعداد اپلیکیشن رسیده‌اید.'

      console.error('وضعیت HTTP:', err.status);
      // مثال: 400
    } else {
      throw err;
    }
  }
}

ساختار AbrclickError:

class AbrclickError extends Error {
  code: string;         // کد ماشینی مانند APP_LIMIT_REACHED
  messageFa: string;    // پیام فارسی برای نمایش به کاربر
  status: number;       // HTTP status code
}
کدهای خطای متداول
کدتوضیح
APP_LIMIT_REACHEDتعداد اپ‌ها به سقف پلن رسیده
DB_LIMIT_REACHEDتعداد دیتابیس‌ها به سقف پلن رسیده
UNAUTHORIZEDAPI Key نامعتبر یا منقضی
NOT_FOUNDاپ یا دیتابیس یافت نشد
BUILD_FAILEDخطا در مرحله بیلد
SOURCE_TOO_LARGEحجم سورس از ۱۰۰ مگابایت بیشتر است

مثال کامل: اتوماسیون دیپلوی​

import { AbrclickClient, AbrclickError } from '@abrclick/sdk';
import path from 'path';

const client = new AbrclickClient({
  apiKey: process.env.ABRCLICK_API_KEY!,
});

async function deployProject() {
  const projectId = process.env.ABRCLICK_PROJECT_ID!;

  // ساخت اپ در صورت نبود
  let app;
  const { data: apps } = await client.getApps(projectId);
  const existing = apps.find((a) => a.name === 'backend-api');

  if (existing) {
    app = existing;
    console.log('اپ موجود پیدا شد:', app.id);
  } else {
    app = await client.createApp(projectId, {
      name: 'backend-api',
      runtime: 'node',
      port: 4000,
    });
    console.log('اپ جدید ساخته شد:', app.id);
  }

  // دیپلوی سورس کد (در واقعیت باید سورس را آپلود کنید)
  console.log('شروع دیپلوی...');
  const { uploadUrl, sourceKey } = await client.getSourceUploadUrl(app.id);
  
  // ... آپلود tarball به uploadUrl ...
  
  const deployment = await client.deployApp(app.id, {
    source_type: 'upload',
    source_key: sourceKey,
  });

  // نمایش لاگ‌های real-time
  for await (const line of client.streamBuildLogs(app.id, deployment.id)) {
    process.stdout.write(line);
  }

  console.log(`\nدیپلوی موفق: ${app.url}`);
}

deployProject().catch((err: unknown) => {
  if (err instanceof AbrclickError) {
    console.error(err.messageFa);
  } else {
    console.error(err);
  }
  process.exit(1);
});

پشتیبانی از تایپ‌اسکریپت​

پکیج @abrclick/sdk به صورت کامل با تایپ‌اسکریپت نوشته شده است و نیازی به نصب @types/* جداگانه ندارد. تمام تایپ‌ها از خود پکیج قابل import هستند:

import type {
  App,
  Database,
  Deployment,
  Project,
  DatabaseCredentials,
  CreateAppInput,
  CreateDatabaseInput,
} from '@abrclick/sdk';

امکانات پیشرفته​

نواحی (Regions)​

// لیست نواحی موجود
const regions = await client.listRegions();
for (const r of regions) {
  console.log(`${r.slug} — ${r.display_name} — ${r.api_url}`);
}

// تغییر ناحیه فعال
const tehran = regions.find(r => r.slug === 'ir-thr-1');
client.useRegion(tehran!);

قالب‌های آماده (Templates)​

// لیست قالب‌های آماده
const templates = await client.getTemplates();

// استقرار یک قالب (مثلاً WordPress)
const deployment = await client.deployTemplate('wordpress', {
  project_id: 'proj_abc123',
  app_name: 'my-blog',
  app_cpu: '500m',
  app_memory: '512Mi',
  db_cpu: '500m',
  db_memory: '512Mi',
});

// پیگیری وضعیت استقرار
const status = await client.getTemplateDeployment(deployment.id);
console.log(status.status); // 'provisioning_db' | 'deploying_app' | 'running'

دامنه‌ها و DNS​

// لیست دامنه‌های یک اپ
const domains = await client.getDomains('app_xyz789');

// افزودن دامنه سفارشی
await client.addDomain('app_xyz789', 'example.com');

// تأیید دامنه
await client.verifyDomain('app_xyz789', 'domain_123');

// مدیریت DNS zones
const zones = await client.getDnsZones();
const zone = await client.createDnsZone('example.com');

// افزودن رکورد DNS
await client.upsertDnsRecord(zone.id, {
  name: 'www',
  type: 'A',
  ttl: 3600,
  records: ['192.0.2.1'],
});

مانیتورینگ و هشدارها​

// متریک‌های اپ
const appMetrics = await client.getAppMetrics('app_xyz789', '24h');
console.log(appMetrics.metrics.cpu);
console.log(appMetrics.metrics.memory);

// متریک‌های دیتابیس
const dbMetrics = await client.getDatabaseMetrics('db_abc456', '7d');
console.log(dbMetrics.metrics.active_connections);

// ایجاد قانون هشدار
await client.createAlertRule({
  resourceId: 'app_xyz789',
  resourceType: 'app',
  metric: 'cpu',
  operator: 'gt',
  threshold: 80,
  durationMinutes: 2,
  notifyVia: 'email',
});

// لیست قوانین هشدار
const rules = await client.getAlertRules();

// فعال/غیرفعال کردن یک قانون
await client.toggleAlertRule('rule_123', false);

// حذف قانون
await client.deleteAlertRule('rule_123');

اعلان‌ها (Notifications)​

// دریافت اعلان‌ها
const notifications = await client.getNotifications();

// فقط خوانده‌نشده‌ها
const unread = await client.getNotifications(true);

// تعداد خوانده‌نشده
const count = await client.getUnreadCount();

// علامت‌گذاری به عنوان خوانده‌شده
await client.markNotificationRead('notif_123');

// علامت‌گذاری همه به عنوان خوانده‌شده
await client.markAllNotificationsRead();

وظایف (Tasks)​

// لیست وظایف پروژه
const tasks = await client.getTasks('proj_abc123');

// ایجاد وظیفه جدید
await client.createTask('proj_abc123', {
  title: 'Fix login bug',
  description: 'User reported 500 error',
  appId: 'app_xyz789',
  status: 'todo',
  priority: 'high',
  labels: ['bug', 'backend'],
});

// به‌روزرسانی وظیفه
await client.updateTask('task_123', {
  status: 'done',
  assigneeId: 'user_456',
});

صورتحساب و کیف پول​

// اطلاعات کیف پول
const wallet = await client.getWallet();
console.log(wallet.balance); // موجودی به تومان

// تراکنش‌های کیف پول
const txs = await client.getWalletTransactions(50, 0);

// لیست صورتحساب‌ها
const invoices = await client.getInvoices(1, 20);

// لیست پلن‌ها
const plans = await client.getPlans();

// ارتقا پلن
await client.upgradePlan('rain');

// لیست افزونه‌ها
const addons = await client.getAddons();

// خرید افزونه
await client.purchaseAddon('storage', 2);

بک‌آپ دیتابیس​

// لیست بک‌آپ‌ها
const backups = await client.getBackups('db_abc456');

// ایجاد بک‌آپ دستی
await client.createBackup('db_abc456');

// بازگردانی از بک‌آپ
await client.restoreBackup('db_abc456', 'backup_123');

// کلون کردن از بک‌آپ (دیتابیس جدید)
await client.cloneBackup('db_abc456', 'backup_123', {
  name: 'staging-db',
  cpu_limit: '500m',
  memory_limit: '1Gi',
  storage_gb: 10,
});

// تنظیم زمان‌بندی خودکار بک‌آپ
await client.setBackupSchedule('db_abc456', '0 3 * * *'); // روزانه ساعت 3 صبح

GitHub Integration​

// دریافت لینک نصب GitHub App
const { url } = await client.getGithubInstallUrl();
console.log('Install app:', url);

// لیست ریپازیتوری‌های متصل
const repos = await client.listGithubRepos();

// قطع اتصال GitHub
await client.githubDisconnect();
Node.js حداقل نسخه

SDK با Node.js نسخه ۱۸ و بالاتر سازگار است. برای استفاده از for await...of روی stream لاگ‌ها، Node.js 18+ توصیه می‌شود.