‎LocalMe HTTP API

یک پروژه، پوشه‌ای از فایل‌های استاتیک به‌علاوهٔ یک بک‌اند مدیریت‌شده است: پایگاه‌دادهٔ سندی، فضای ذخیره‌سازی بلاب، کتابخانهٔ فایل‌های مشترک، حساب‌های بازدیدکننده و نقش‌ها، مسیریابی، اسرار رمز‌شده، یک پروکسی معکوس، وظایف زمان‌بندی‌شده، وب‌هوک‌ها و دامنه‌های اختصاصی. تو HTML، CSS و JavaScript مینویسی؛ بقیه‌اش مال پلتفرم است.

<!-- index.html — the whole integration is a fetch call -->
<script>
  const res = await fetch('/api/db/find', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    credentials: 'include',              // sends the visitor cookie
    body: JSON.stringify({ table: 'notes', filter: { done: false } })
  });
  const { data, total } = await res.json();
</script>

پروژه‌ها از https://localme.ir/[username]/[project-name]/ سرو میشوند. مسیرهای نسبی API درون یک صفحهٔ سروشده، خودبه‌خود همان بافت را به ارث میبرند. کلاینت‌های سمت سرور یا بیرونی میتوانند پروژه را صریح نشانی بدهند:

POST https://localme.ir/api/db/find
X-Project-Id: <projectId>
Content-Type: application/json

{ "table": "notes" }

ترتیب تشخیص این‌گونه است: هدر X-Project-Id، سپس فیلد projectId در بدنه، و در پایان پیشوند /username/project/ در مسیر درخواست.

سه نوع اعتبار به API میرسند و میتوانند در یک پروژه با هم ترکیب شوند:

ورود و ثبت‌نام برایت انجام میشود. بازدیدکننده‌ها را به /auth/login?returnUrl=/your/page بفرست و یک login.html در ریشهٔ پروژه بگذار تا صفحهٔ داخلی با طراحی خودت جایگزین شود.

await fetch('/auth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    action: 'login',              // or 'signup'
    username: 'jane',
    password: 'hunter2hunter2',
    captchaId: challenge.challengeId,   // from GET /auth/captcha
    captchaAnswer: solved,              // required for login
    returnUrl: location.pathname
  })
});
// → { success: true, visitor: true, redirectUrl: '/shop/private' }

هر وقت خواستی ببین چه کسی وارد است، /auth/me را صدا بزن؛ نقش، فهرست مجوزها و نوع فاعل (visitor، api_key، owner یا anonymous) را برمیگرداند.

یک ذخیره‌ساز سندی بدون اسکیما. جدول‌ها در نخستین درج به‌طور ضمنی ساخته میشوند و هر سند باید فیلد id غیرتهی داشته باشد که درون جدولش یکتاست. پرس‌وجوها دستور زبان فیلتر و مرتب‌سازی به سبک MongoDB را میپذیرند.

// Query
const res = await fetch('/api/db/find', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    table: 'orders',
    filter: { status: { $in: ['paid', 'shipped'] }, total: { $gt: 100 } },
    sort: { created: -1 },
    limit: 25,
    offset: 0
  })
});
// → { data: [...], total, limit, offset, truncated }

// Insert, update and delete
await fetch('/api/db/insert', {
  method: 'POST', headers: { 'Content-Type': 'application/json' }, credentials: 'include',
  body: JSON.stringify({ table: 'orders', document: { id: Date.now(), total: 140, status: 'paid' } })
});

await fetch('/api/db/update', {
  method: 'POST', headers: { 'Content-Type': 'application/json' }, credentials: 'include',
  body: JSON.stringify({ table: 'orders', filter: { id: 1 }, update: { status: 'shipped' }, many: false })
});

await fetch('/api/db/delete', {
  method: 'POST', headers: { 'Content-Type': 'application/json' }, credentials: 'include',
  body: JSON.stringify({ table: 'orders', filter: { status: 'cancelled' } })
});

به‌روزرسانی‌ها یا یک شیء ساده میپذیرند (که در هر سند ادغام میشود) یا فرم عملگری با $set، $inc و $unset. نتیجه‌ها فرادادهٔ _localme را با زمان ساخت و آخرین تغییر حمل میکنند.

id یک سند به‌صورت متنی مقایسه میشود، پس 1 عددی و "1" رشته‌ای روی هر دو بک‌اند پایگاه‌داده یک سند‌اند — درج شکل دوم ۴۰۹ برمیگرداند. نوع مقدار فیلتر رعایت میشود: id: 1 فقط شناسهٔ عددی را میخواند، هرگز رشته را.

فایل‌ها از ریشهٔ پروژه سرو میشوند، پس /static/app.js دقیقاً مثل هر میزبان استاتیک دیگری کار میکند. فایل‌های دودویی در فضای بلاب میمانند؛ فایل‌های متنی درون‌خطی ذخیره و در پیشخوان قابل ویرایش‌اند.

// Multipart upload
const form = new FormData();
form.append('file', input.files[0]);
form.append('path', '/static/logo.png');

await fetch('/api/storage/upload', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer sk_…' },   // or credentials: 'include'
  body: form
});

فهرست‌گیری یک پوشه میپذیرد: GET /api/storage/list?path=/static نام‌ها، اندازه‌ها، زمان‌های تغییر و نوع‌ها را برمیگرداند. نوشتن‌هایی که از سقف حساب فراتر بروند، پیش از ذخیرهٔ حتی یک بایت رد میشوند.

بارگذاری‌ها به‌طور پیش‌فرض هنگام ذخیره کمینه میشوند: کامنت‌ها و فاصله‌های بی‌مورد از CSS، JavaScript، JSON، HTML و SVG حذف میشوند. برای هر درخواست با ?minify=0 میتوان انصراف داد (یا با ?minify=1 اجبار کرد) و پیش‌فرض را در کل پلتفرم با storage.minify_on_save عوض کرد. هر چیزی که در Content-Length بیش از سقف ۱۰ مگابایت اعلام کند، پیش از بافر شدن بدنه با ۴۱۳ رد میشود.

کتابخانه یک CDN برای فایل‌هایی است که همهٔ پروژه‌هایت به اشتراک میگذارند — شیوه‌نامه‌ها، اسکریپت‌ها، فونت‌ها و تصویرها. یک بار بارگذاری کن و هر فایل یک نشانی عمومی پایدار زیر /{username}/library/ میگیرد؛ چیزی بین پروژه‌ها کپی نمیشود و HTML رد میشود چون این فایل‌ها از مبدأ پلتفرم سرو میشوند.

library نام پوشهٔ رزروشده است، پس ارجاع نسبی از درون یک پروژه به کتابخانهٔ تو میرسد و روی دامنهٔ اختصاصی هم کار میکند.

<link rel="stylesheet" href="/ada/library/theme.css">
<script src="/ada/library/analytics.js" defer></script>

<!-- or, from inside a project (custom-domain safe) -->
<link rel="stylesheet" href="library/theme.css">

اسرار با ‎AES-256-GCM رمزنگاری میشوند و فقط سمت سرور رمزگشایی میشوند. راه پشتیبانی‌شده برای استفاده از API شخص ثالث بدون افشای کلیدت، مسیر پروکسی است: مسیری با نشانی خودت بساز، آن را به سرویس‌دهنده وصل کن و در نقشهٔ هدر به اسرار ارجاع بده.

// Route:  /api/payments/create    (proxy enabled)
// Target: https://api.stripe.com/v1/payment_intents
// Method: POST
// Headers: { "Authorization": "Bearer {{STRIPE_KEY}}" }

const res = await fetch('/api/payments/create', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ amount: 1000, currency: 'usd' })
});

مقدار هدرها جایگزینی {{KEY_NAME}} را برای هر راز ذخیره‌شده پشتیبانی میکند. یک مسیر پروکسی همچنین نقش سوارشده را دارد: وقتی الگوی مسیر یک پیشوند باشد، باقی مسیر فراخوان به مسیر هدف اضافه میشود، پس /api/stripe/* میتواند جلوی https://api.stripe.com/v1 بنشیند، در حالی که تطبیق دقیق مسیر هدف را همان‌طور که نوشته شده نگه میدارد. اسرار را میتوان مستقیم هم با POST /api/secrets/get خواند؛ این نشانی مجوز secrets_admin میخواهد و فقط برای فراخوانی سرور به سرور است.

یک درخواست ورودی به این ترتیب تشخیص داده میشود:

1. تطبیق دقیق مسیر، فایل HTML هدفش را سرو میکند.
2. تطبیق مسیر با الگوی عام (مثلاً /blog/*) هدفش را سرو میکند.
3. فایل ذخیره‌شده در مسیر درخواستی مستقیم و با کش بلندمدت سرو میشود.
4. برای مسیرهای پوشه، <dir>/index.html سرو میشود.
5. /404.html با وضعیت ۴۰۴ برگردانده میشود، یا صفحهٔ خود پلتفرم.

مسیرها میتوانند بازدیدکنندهٔ واردشده، یک حداقل نقش، و/یا یک مجوز ریزدانه (مثلاً analytics_read) بخواهند که نقش بازدیدکننده باید داشته باشد. حتی وقتی requires_auth خاموش است، داشتن الزام مجوز، دروازهٔ احراز را فعال میکند. فقط فایل‌های HTML مسیرپذیرند — فایل‌های جانبی همیشه با مسیر خودشان در دسترس‌اند. وقتی واترمارک روشن باشد پلتفرم یک نشان کوچک انتساب به HTML سروشده اضافه میکند که میتوانی در تنظیمات هر پروژه خاموشش کنی.

درخواست‌های فایل و کتابخانه در برابر Referer و Origin بررسی میشوند: درخواست‌های مستقیم، صفحه‌های خودت (از جمله دامنه‌های اختصاصی تأییدشده) و خزندگان موتور جست‌وجو عبور میکنند و سایت‌های بیرونی ۴۰۳ میگیرند. اپراتورهایی که فایل‌ها را بین‌دامنه‌ای جاسازی میکنند میتوانند این بررسی را با serving.hotlink_protection در تنظیمات سیستم خاموش کنند. پاسخ‌های متنی در صورت درخواست کلاینت با Brotli/gzip فشرده میشوند، HTML همیشه no-store سرو میشود و فایل‌های جانبی یک روز کش و یک ETag قوی میگیرند، پس درخواست تکراری با If-None-Match به‌صورت ۳۰۴ برمیگردد. بایت‌های فایل در یک کش درون‌فرایندی با سقف مشخص نگه داشته میشوند و به‌محض نوشتن یا حذف یک فایل باطل میشوند.

رسیدگی به گواهی عمداً انتخابی است. وقتی ssl.auto_provision خاموش باشد (پیش‌فرض)، پلتفرم هرگز خودسرانه با هیچ ارائه‌دهندهٔ ACME تماس نمیگیرد: فقط آنچه اپراتور میدهد را ذخیره، گزارش و تمدید میکند. آن را روشن کنی، از HTTP-01 استفاده میکند — توکن برای واکشی مرجع CA در /.well-known/acme-challenge/<token> نوشته میشود — سپس گواهی را رمز‌شده ذخیره میکند و ssl.renewal_days_before_expiry روز پیش از انقضا تمدیدش میکند. ssl.acme_staging به‌طور پیش‌فرض روشن است تا یک استقرار تازه سهمیهٔ مراجع عمومی را نسوزاند.

GET  /api/domains/certificate?projectId=1&domain=app.example.com
  → { enabled, staging, domains, certificates, expiringSoon,
      domain, hasCertificate }

POST /api/domains/certificate?projectId=1&domain=app.example.com
  { "email": "ops@example.com", "sans": ["www.app.example.com"] }

POST /api/domains/renew?projectId=1
  → { skipped, due, renewed: [...], failed: [...] }

رفتار پلتفرم بیرون از مسیر درخواست از طریق تنظیمات سیستم پیکربندی میشود (/api/admin/config را ببین): logging.level، logging.sink و logging.file_path لاگ ساخت‌یافتهٔ NDJSON را کنترل میکنند (اطلاعات محرمانه پیش از نوشتن هر رکورد پاک میشوند)، serving.hotlink_protection میتواند بررسی ارجاع فایل را برای جاسازی بین‌دامنه‌ای تسهیل کند، و کلیدهای webhooks.retry_* تلاش مجدد outbox را کنترل میکنند.

مقصدهای وب‌هوک پیش از ثبت و دوباره پیش از هر تحویل اعتبارسنجی میشوند: فقط http و https، و نشانی‌های لوپ‌بک، خصوصی، لینک‌لوکال و فرادادهٔ ابری رد میشوند. یک پروژه نمیتواند با وب‌هوک، پلتفرم را به شبکهٔ خودش برساند. هر پاسخ همچنین X-Content-Type-Options: nosniff، یک سیاست قاب‌بندی و HSTS حمل میکند.

پیشخوان روی همان سطح REST ساخته شده است. این نشانی‌ها به‌جای دادهٔ یک پروژه، روی حساب و پروژه‌های تو کار میکنند؛ همه به نشست کنسول نیاز دارند و نشانی‌های مدیر به حساب مدیر.

دامنه‌های اختصاصی روی DNS تأیید میشوند: یک دامنه وصل کن تا توکن localme-verify=… بگیری، آن را به‌عنوان رکورد TXT در _localme-verify.<domain> منتشر کن و بعد نشانی تأیید را صدا بزن. پس از تأیید، کل میزبان همان پروژه را سرو میکند.

لوکال می پشتیبانی کامل و بومی از عامل‌های خودکار هوش مصنوعی (کلود، کرسر، آنتی‌گرویتی، ویندسرف و غیره) ارائه میدهد. عامل خود را به سرور MCP به نشانی https://localme.ir/api/mcp متصل کنید یا فایل اسکیل رسمی را در https://localme.ir/skills/localme/SKILL.md به آن بدهید. عامل‌ها میتوانند به صورت خودکار پروژه بسازند، فایل‌ها را بارگذاری کنند، دیتابیس را آماده کنند و مسیرها را تنظیم نمایند، در حالی که تایید صدور توکن همواره با تایید انسانی انجام میشود.

خطاها از کدهای وضعیت استاندارد و بدنهٔ JSON یکسان استفاده میکنند:

{ "error": "A document with id \"1\" already exists in orders", "code": "duplicate_document_id" }