# Plugin API (สรุปอ้างอิง)

> สรุป API สาธารณะทั้งหมดที่ปลั๊กอินใช้ได้ — เวอร์ชันที่เพิ่มเข้ามา, minCore และ feature detection, site.*, db.*, http/mail/jobs/plugins, ฮุกหน้าเว็บ, หน้าหลังบ้าน และ admin UI kit

ที่มา: https://anasaki.live/docs/developers/plugin-api

ระบบหลักไม่เคยเขียนโค้ดพิเศษให้ปลั๊กอินตัวใด — ปลั๊กอินทางการ (seo, forms …) ใช้เฉพาะ API ในหน้านี้ สิ่งที่ปลั๊กอินทางการทำได้ ปลั๊กอินของคุณก็ทำได้ เอกสารฉบับเต็มอยู่ใน repository: `docs/plugin-api.md` (API), `docs/site-code.md` (รายละเอียด JS API) และ type ที่ถูกต้องที่สุดคือ `anasaki.d.ts` (`GET /api/v1/code/types`)

## เวอร์ชันของ API

| เวอร์ชัน CMS | เพิ่มอะไร |
| --- | --- |
| **2.0.0** | แพลตฟอร์มปลั๊กอินรุ่นแรก (แพ็กเกจ, service, WASM และ JavaScript) — ทุกอย่างในหน้านี้ที่ไม่ได้ระบุเวอร์ชัน |
| **2.0.3** | `AK.line`, `AK.open`, `AK.height`, `data-ak-line`, `data-ak-open`; หน้าจัดการและวิดเจ็ตปรับความสูงตามเนื้อหา |
| **2.0.4** | `AK.pickMedia` (เลือกรูปจากคลังสื่อ); พาธที่ปลั๊กอินประกาศถูกสงวน (`GET /api/v1/settings/reserved-paths`); ปลั๊กอินแนะนำในหน้าตั้งค่าเริ่มต้นมาจาก Store |
| **2.0.5** | ปลั๊กอิน JavaScript ประกาศประเภทเนื้อหา (`site.postType`) ของตัวเองได้ — scope `post-types`, id `_` (≤ 20 ตัว), `public: false` ปิดการ route ของระบบ, ช่องใน spec เก็บชื่อตรง ๆ (ดู [สร้างปลั๊กอิน JavaScript](/docs/developers/js-plugins)) |
| **2.0.6** | สิทธิ์ของปลั๊กอิน: `capabilities` ใน manifest (ผู้ดูแลติ๊กต่อตำแหน่งที่ ผู้ใช้งาน → สิทธิ์การใช้งาน), `'cap:'` ในรายการ `access`, `site.can(user, cap)` / `user.can(cap)` และ `caps: { edit, publish }` ของประเภทเนื้อหา — ดู [สิทธิ์ของปลั๊กอิน](/docs/developers/plugin-capabilities) |
| **2.1.0** | `site.taxonomy` และ `db.terms.*` (scope `taxonomies` / `terms-write`), `media.*` / `files.*` / `request.files()` (scope `media` / `media-write` / `files`), ค่าตั้งค่าแบบ `secret`, ฟิลด์ใหม่ (relation, user, term, file, gallery, repeater, richtext, color), event มี `actor` และ `previous`, บทความตั้งเวลาเผยแพร่ (`scheduled`) |
| **2.1.1** | `site.cron(expr, fn, { name })`; `toLocaleString('th-TH')` / `toLocaleDateString` ทำงานได้ (ปี พ.ศ.); REST `terms` รับ slug |
| **2.2.0** | `site.asset('public/…')` ใน Site Code และไฟล์ `public/` ที่ `/site-assets/`; `atob` / `btoa`; ฝั่งหน้าเว็บ `anasaki.ref()` / `anasaki.refs()` (ชื่อสำหรับโค้ด) และ `anasaki.lib()` / `anasaki.style()` — ดู [API ของหน้าออกแบบ](/docs/developers/designer-api) |
| **2.2.2** | `db.users.list / get` (scope `users`) — โปรไฟล์สาธารณะของผู้ใช้ ไม่มีอีเมล; ประเภทเนื้อหาที่ผู้ดูแลสร้างใน ตั้งค่า → ประเภทเนื้อหา อ่านด้วย `db.posts` ได้เหมือนประเภทจากโค้ด (`post-types` ของ `GET /api/v1/post-types` มี `admin: true`); `ctx.preview` ใน `render` ของ `site.block` (`true` = แสดงในหน้าออกแบบ, `false` = หน้าเว็บจริง) ใช้ซ่อนข้อความแนะนำ เช่น &#34;เลือกฟอร์ม&#34; จากผู้เข้าชม; `code.routes` มีจุดได้ เช่น `/feed.xml` (ห้าม `..` และห้ามขึ้นต้นด้วยจุด); ไฟล์ที่ส่งออกจาก Site Code มี `category: &#34;utilities&#34;` |
| **2.3.0** | `ctx.isAdminUser` (middleware) / `isAdminUser` (afterResponse) รวมผู้ดูแลที่เปิดดูเว็บในเบราว์เซอร์เดียวกับหลังบ้าน (`ctx.user` ยังเป็น `null`); URL ของหน้าแรกจาก `db.posts` เป็น `/`; REST `GET /posts?status=any` และฉบับร่างของหน้าที่เผยแพร่แล้ว (`asDraft`); รายการแหล่งข้อมูลของหน้าออกแบบไม่แสดงตารางของปลั๊กอิน (`p_*`); รายการบทความของประเภทเนื้อหาที่สร้างเองกรองด้วยหมวดของตัวเองได้ (slug, id หรือชื่อ) |
| **2.4.0** | บันทึกกิจกรรมของผู้ดูแล (`GET /api/v1/audit`, สิทธิ์ `manage_users`) — action ของหน้าจัดการปลั๊กอินที่ผู้ใช้กดถูกบันทึกด้วย; แพ็กเกจจาก Store มีลายเซ็น Ed25519 (`X-Anasaki-Signature`, `GET /api/v1/signing-key` ของ Store) และ CMS ตรวจก่อนติดตั้ง; รูปในหน้าออกแบบมี `props.lightbox`; ปลั๊กอิน Docs 1.2.0 มีบทความหลายภาษา (`/docs//…`) |

เลขเวอร์ชันของเว็บดูได้จาก `GET /api/public/site` (`version`) และหน้า ตั้งค่าเว็บไซต์ → ทั่วไป

### minCore และ feature detection

```jsonc
{ &#34;id&#34;: &#34;my-plugin&#34;, &#34;version&#34;: &#34;1.0.0&#34;, &#34;minCore&#34;: &#34;2.0.4&#34; }
```

ตั้ง `minCore` เป็นเวอร์ชันของ API ที่ **ขาดไม่ได้** (ระบบที่เก่ากว่าปฏิเสธการติดตั้ง) ส่วนความสามารถเสริมให้ตรวจก่อนใช้ เพื่อให้เว็บรุ่นเก่ายังติดตั้งได้:

```ts
if (typeof site.dashboardWidget === 'function') site.dashboardWidget('visits', { /* … */ });
if (plugins.has('thai')) site.formatter('price', (v) => plugins.call('thai', 'bahtText', v));
```

```js
// ในหน้าจัดการ (เบราว์เซอร์)
if (window.AK && AK.pickMedia) pickButton.hidden = false; else urlInput.hidden = false;
```

## site.*

| API | scope |
| --- | --- |
| `site.route(spec, opts?, handler)` — `&#34;GET /x/{id}&#34;`, `access`, `rawBody`, `maxBody` | `routes` |
| `site.page(path, {access, load})` — ข้อมูลของหน้าที่ออกแบบ | `routes` |
| `site.collection(name, spec)` · `site.action(name, spec)` · `site.formatter(name, fn)` | — |
| `site.on(event, fn)` · `site.emit(name, data)` · `site.export(name, fn)` | — |
| `site.filter(name, fn, {priority})` · `site.applyFilter(name, value, ctx)` | `filters-core` สำหรับจุดของระบบ |
| `site.visitor(fn)` · `site.visitorGroups(groups)` | `visitor` |
| `site.fields(type, fields)` · `site.meta(postId)` · `site.setMeta(postId, values)` | `content-fields` |
| `site.postType(id, spec)` — ปลั๊กอิน: ตั้งแต่ 2.0.5, id `_`, `public: false` = ปลั๊กอินเสิร์ฟหน้าเอง | `post-types` |
| `site.job(name, opts?, fn)` · `site.cron(expr, target, { name }?)` | `jobs` |
| `site.can(user, capability)` — ตั้งแต่ 2.0.6 ([สิทธิ์ของปลั๊กอิน](/docs/developers/plugin-capabilities)) | — |
| `site.adminPage(id, spec)` · `site.dashboardWidget(id, spec)` · `site.adminNotice(fn, {access})` | `admin-pages` |
| `site.block(type, spec)` — บล็อกที่เรนเดอร์ฝั่งเซิร์ฟเวอร์ (`render(ctx, props)`: `ctx.site`, `ctx.post`, `ctx.item`, `ctx.path`, `ctx.query`, `ctx.user`, `ctx.preview` ตั้งแต่ 2.2.2) | — |
| `site.middleware(fn, {priority})` · `site.afterResponse(fn)` | `middleware` |
| `site.head(fn)` · `site.bodyEnd(fn)` | — (`head-scripts` = ไม่กรอง HTML) |
| `site.settings(key?)` · `site.saveSettings(values)` · `site.info()` · `site.asset(path)` | — |

ผลลัพธ์ของ route/page/action: ค่า (JSON), `{status, headers?, body?}`, bytes (`Uint8Array` ≤ 20 MB), `{page: {title, html}}` (แสดงในหัว/ท้ายของเว็บ) — context: `request {method, path, params, query, headers, cookies, body, json(), ip, host}`, `response.setCookie(...)`, `user`, `visitor`

## db.*

| API | scope |
| --- | --- |
| `db.table(name)` / `db.from(name)` — query builder, aggregate (`selectCount`, `selectSum` …) | `db` |
| `db.transaction(fn)` · `db.raw(sql, params)` (ห้าม SELECT/FROM/JOIN) · `db.docs(name)` | `db` |
| migration `migrations/NNN_name.ts` ด้วย `migration({up, down})` | `db` |
| `db.posts.list / get` · view `core_*` | `content` |
| `db.users.list({ role?, search?, page?, perPage? })` · `db.users.get(id)` — ชื่อ รูป ประวัติ เว็บไซต์ ตำแหน่ง จำนวนบทความ (ไม่มีอีเมล ไม่รวมผู้ใช้ที่ถูกระงับ, 2.2.2) | `users` |
| `db.posts.create / update / delete` · `db.asSystem(fn)` | `content-write` |

ปลั๊กอินไม่ได้ `db.query` และ `schema.raw` — ตารางของปลั๊กอินคือ `p__*` เท่านั้น

## http, mail, jobs, plugins และอื่น ๆ

| API | scope |
| --- | --- |
| `http.fetch(url, {method, headers, body, timeout})` | `http` (+ `code.hosts`) |
| `http.webhook(url, event, data, {secret?})` | `webhooks` |
| `mail.send({to, subject, html?, text?, replyTo?})` | `mail` |
| `jobs.enqueue(name, data, {delay, key})` | `jobs` |
| `plugins.call(id, fn, ...args)` · `plugins.has(id)` · `plugins.version(id)` · error `PluginUnavailable` | — |
| `import { x } from ''` — library/exports ของปลั๊กอินใน `requires` | — |
| `cache.*` · `crypto.*` · `log.*` / `console.*` | — |

## Event และ filter ของระบบ

- **event**: `post.published`, `post.saved`, `post.deleted`, `user.created`, `media.uploaded` — event อื่นเป็นของปลั๊กอินที่ส่ง (`.…` หรือชื่อใน `code.eventAliases` เช่น `form.submitted`)
- **filter** (scope `filters-core`): `post.content`, `post.beforeSave`, `page.head`, `page.meta`, `collection.items`, `action.input`, `action.result`, `mail.beforeSend`, `sitemap.urls`, `robots.txt` — เมื่อมีหน่วยใดกรอง `sitemap.urls` หรือ `robots.txt` ระบบจะเสิร์ฟ `/sitemap.xml` และ `/robots.txt` ให้

## ฮุกของหน้าเว็บสาธารณะ

| ฮุก | ทำงานเมื่อ | เวลา |
| --- | --- | --- |
| `site.middleware` | ก่อนจัดเส้นทางทุกคำขอ — คืนค่าว่าง = ไปต่อ, คืนผลลัพธ์ = ตอบเลย, คืน `{headers}` = เพิ่ม header แล้วไปต่อ | 20 ms |
| `site.afterResponse` | หลังตอบแล้ว (ในคิว ไม่ทำให้ช้า) — ข้อมูลคำขอ สถานะ IP ฯลฯ | 2 วินาที (ก่อน 2.2.0: 500 ms) |
| `site.head` / `site.bodyEnd` | HTML ใน `` / ก่อน `` (กรอง HTML ถ้าไม่มี `head-scripts`) | 50 ms |
| filter `page.meta` | `{title, fullTitle, description, image, canonical, robots, noindex, og}` | 50 ms |

`ctx.isAdminUser` ของ middleware และ `isAdminUser` ของ afterResponse เป็น `true` เมื่อผู้ใช้ CMS ที่ล็อกอินอยู่เป็นคนเปิดหน้า ตั้งแต่ 2.3.0 นับรวมผู้ดูแลที่เปิดดูเว็บ (GET) ในเบราว์เซอร์เดียวกับหลังบ้านด้วย แต่ `ctx.user` ยังเป็น `null` ในกรณีนั้น ใช้ตัดสินใจเรื่องการแสดงผลได้ (เช่น ข้ามหน้าปิดปรับปรุง ไม่นับสถิติ) แต่ห้ามใช้ให้สิทธิ์ทำรายการ

## หน้าหลังบ้าน วิดเจ็ต และแถบแจ้งเตือน

- **หน้าจัดการ** (`site.adminPage`) อยู่ที่ `/admin/x/code/:` รันใน iframe แบบ sandbox — ใช้ `anasaki.call(':', input)` เรียก action ในนามผู้ใช้, `anasaki.download(query)` สำหรับไฟล์ดาวน์โหลด และวาด `` เอง
- **วิดเจ็ตแดชบอร์ด** (`site.dashboardWidget`, ≤ 10 ต่อปลั๊กอิน) แสดงบนหน้าหลักของหลังบ้าน
- **แถบแจ้งเตือน** (`site.adminNotice`, ≤ 5 ต่อปลั๊กอิน) ระดับ `info | warning | danger | success` พร้อมลิงก์
- ผู้ดูแลระบบ override ตำแหน่งที่เปิดหน้าได้ที่ **โค้ดของเว็บไซต์ → สิทธิ์การเข้าถึง**

## Admin UI kit (`window.AK`)

ทุกหน้าจัดการและวิดเจ็ตโหลด `/ext-ui/kit.css` + `/ext-ui/kit.js` ให้เอง — คลาส `ak-*` (การ์ด ปุ่ม ป้าย ตาราง ฟอร์ม แท็บ toast dialog กราฟ) รองรับธีมสว่าง/มืด

| ฟังก์ชัน | เวอร์ชัน |
| --- | --- |
| `AK.toast(msg, kind?)` · `AK.confirm(text, {ok, cancel, danger})` · `AK.tabs(el)` · `AK.table(el, opts)` · `AK.sortable(table)` · `AK.pager(el, opts)` · `AK.validate(form)` · `AK.bar(el, data)` · `AK.sparkline(el, data)` · `AK.lang()` · `AK.t(key)` | 2.0.0 |
| `AK.line(el, {labels, series})` · `AK.open(path)` · `AK.height()` | 2.0.3 |
| `AK.pickMedia({accept: 'image' \| 'file'})` → `{url, id, alt, width, height}` หรือ `null` | 2.0.4 |

## พาธสาธารณะที่สงวนไว้

ปลั๊กอินประกาศพาธของตัวเองใน `code.routes` (JavaScript) หรือ `service.public` (service/WASM) และใช้พาธของระบบไม่ได้: `api`, `uploads`, `download`, `plugin-assets`, `ext-ui`, `setup`, `_a`, `_c`, `site-assets` (ตั้งแต่ 2.2.0), `sitemap.xml`, `robots.txt`, `favicon.ico`, `favicon.svg`, `assets`, `static` รวมถึงที่อยู่หน้าจัดการและคำนำหน้าบทความ/หมวดหมู่ ตั้งแต่ 2.0.4 พาธที่ปลั๊กอินที่ติดตั้งประกาศไว้ก็ถูกสงวน — ผู้ดูแลตั้งที่อยู่หน้าจัดการหรือคำนำหน้าให้ชนกับพาธเหล่านั้นไม่ได้

---

ขาด API ที่ต้องใช้? ทุก API ในหน้านี้ถูกเพิ่มเพราะมีปลั๊กอินต้องการ — อธิบาย use case และ API ทั่วไปที่เล็กที่สุดที่แก้ปัญหาได้ แทนการพึ่งการทำงานภายในของระบบ ดูตัวอย่างการใช้งานจริงที่ [ตัวอย่างปลั๊กอิน](/docs/developers/plugin-example)
