================================================================================
Auto Ngabari Extensions — Panduan Pembuatan Ekstensi Kustom
================================================================================

Folder ini (`wp-content/auto-ngabari/extensions/`) adalah tempat menyimpan file
ekstensi kustom Anda. File di sini aman dari auto-update plugin Auto Ngabari.

--------------------------------------------------------------------------------
1. FORMAT HEADER & METADATA
--------------------------------------------------------------------------------
Setiap file ekstensi berupa file PHP mandiri dan harus diawali dengan informasi
header agar terdeteksi oleh sistem di admin panel Auto Ngabari. Untuk membuat menu
pengaturan khusus untuk ekstensi Anda, tambahkan parameter `Extension Menu`:

<?php
/*
Extension Name: Nama Ekstensi Anda
Description: Penjelasan singkat fungsi ekstensi Anda.
Version: 1.0
Author: Nama Anda
Extension Menu: Nama Menu Ekstensi  <-- Untuk memunculkan subtab setting khusus
*/

// Mencegah akses langsung ke file
if (!defined('ABSPATH')) {
    exit;
}

--------------------------------------------------------------------------------
2. SISTEM SETTING & DOCKING PADA DASHBOARD
--------------------------------------------------------------------------------
Ketika ekstensi Anda aktif dan memiliki header `Extension Menu`, subtab dengan
nama tersebut akan otomatis muncul di menu Extensions Hub.

A. HOOK UNTUK RENDER FORM SETTING:
   an_extension_settings_render_{slug-file-tanpa-php}
   Gunakan action hook ini untuk mencetak elemen HTML input form pengaturan Anda.
   
   Contoh:
   add_action('an_extension_settings_render_my-custom-mod', 'my_custom_mod_settings');
   function my_custom_mod_settings() {
       $val = an_get_extension_setting('my-custom-mod.php', 'opsi_kunci', 'default_val');
       ?>
       <div>
           <label class="block text-sm font-medium text-slate-700">Contoh Setting:</label>
           <input type="text" name="opsi_kunci" value="<?php echo esc_attr($val); ?>" class="mt-1 block w-full rounded border-slate-300">
       </div>
       <?php
   }

B. HELPER FUNGSI UNTUK MEMBACA SETTING:
   - `an_get_extension_settings($ext_file)` : Mengambil array semua setting.
   - `an_get_extension_setting($ext_file, $key, $default)` : Mengambil satu nilai setting.

--------------------------------------------------------------------------------
3. HOOKS YANG TERSEDIA
--------------------------------------------------------------------------------

A. FILTER: an_before_insert_post
   Dipakai untuk memanipulasi data postingan (seperti judul, isi konten, status,
   tipe post, atau author) sebelum artikel hasil generator keyword disimpan.
   
   Contoh:
   add_filter('an_before_insert_post', function($post_data, $generated_json) {
       // Menambahkan teks/kategori kustom
       $post_data['post_title'] = '[BERITA] ' . $post_data['post_title'];
       return $post_data;
   }, 10, 2);

B. ACTION: an_after_post_published
   Dipakai untuk mengeksekusi proses tambahan (seperti webhook, pengiriman
   notifikasi, update meta kustom, dll) setelah artikel hasil generator keyword terbit.
   
   Contoh:
   add_action('an_after_post_published', function($post_id, $generated_json) {
       // Tandai postingan diproses oleh ekstensi
       update_post_meta($post_id, '_custom_processed_by_ext', current_time('mysql'));
   }, 10, 2);

C. FILTER: an_before_insert_post_feeder
   Sama seperti `an_before_insert_post`, tetapi khusus untuk artikel yang dibuat
   melalui generator Feeder (RSS/JSON Feed).

D. ACTION: an_after_post_published_feeder
   Sama seperti `an_after_post_published`, tetapi khusus untuk artikel yang dibuat
   melalui generator Feeder (RSS/JSON Feed).

E. FILTER: an_ai_prompt
   Dipakai untuk memotong dan memodifikasi prompt yang dikirim ke LLM sebelum
   dieksekusi oleh API AI. Berguna untuk menambahkan instruksi gaya penulisan secara global.
   
   Contoh:
   add_filter('an_ai_prompt', function($prompt, $keyword, $context) {
       if ($context === 'search') {
           $prompt .= "\nPastikan menggunakan tone santai.";
       }
       return $prompt;
   }, 10, 3);

F. FILTER: an_ai_call_args
   Dipakai untuk memodifikasi parameter API call ke LLM sebelum data dikirim.
   
   Struktur array `$args` yang bisa Anda overwrite:
   - `$args['max_tokens']` (int) : Batas maksimum token response (default: 3000).
   - `$args['temperature']` (float) : Tingkat kreativitas LLM 0.0 - 1.0 (default: 0.7).
   - `$args['model']` (string) : Memaksa LLM model tertentu untuk API provider terpilih.
   - `$args['json_mode']` (bool) : Memaksa API merespon dalam skema JSON terstruktur.
   
   Contoh:
   add_filter('an_ai_call_args', function($args, $keyword, $context) {
       $args['temperature'] = 0.9; 
       $args['max_tokens'] = 4000;
       return $args;
   }, 10, 3);

G. DETAIL OVERWRITE VARIABLE PADA `an_before_insert_post` & `an_before_insert_post_feeder`
   Filter ini membawa array `$post_data` yang akan dimasukkan ke `wp_insert_post()`.
   Anda bisa memanipulasi elemen array berikut sebelum data masuk ke database:
   
   - `$post_data['post_title']` (string) : Judul postingan (bisa ditambah prefiks/sufiks).
   - `$post_data['post_content']` (string) : Isi konten HTML artikel hasil AI.
   - `$post_data['post_status']` (string) : Status postingan ('publish', 'draft', 'pending').
   - `$post_data['post_type']` (string) : Tipe postingan ('post', 'page', atau custom post type 'berita').
   - `$post_data['post_author']` (int) : User ID penulis yang ditugaskan untuk artikel ini.
   - `$post_data['post_category']` (array) : Array ID kategori WordPress untuk artikel.
   - `$post_data['tags_input']` (array/string) : Tag yang akan ditambahkan ke postingan.

H. PANDUAN PENGIRIMAN INSTRUKSI KE AI UNTUK KONTEN TERSTRUKTUR (MISAL: RESEP)
   Gunakan filter `an_ai_prompt` untuk memodifikasi prompt bawaan jika mendeteksi kata kunci tertentu (misal: "resep" atau "masak"). Hal ini memastikan AI mengembalikan konten HTML terstruktur (seperti `<ul>` untuk bahan dan `<ol>` untuk langkah-langkah) yang nantinya dapat diproses oleh parser ekstensi.

   Contoh implementasi:
    add_filter('an_ai_prompt', function($prompt, $keyword, $context) {
        if (mb_stripos($keyword, 'resep') !== false || mb_stripos($keyword, 'cara membuat') !== false) {
            $prompt .= "\n\nPENTING: Karena ini adalah resep masakan, Anda wajib menstrukturkan konten artikel:\n" .
                       "- Bagian Bahan-Bahan WAJIB menggunakan format list HTML biasa (<ul> dan <li>).\n" .
                       "- Bagian Langkah Pembuatan WAJIB menggunakan format list urut HTML (<ol> dan <li>).\n" .
                       "Kembalikan response dalam JSON valid dengan key: 'title', 'content', 'category', 'tags'.";
        }
        return $prompt;
    }, 10, 3);

I. PANDUAN JALUR ENDPOINT REST API UNTUK KONTEN & LINKING SISTEM
   Ekstensi dapat mengakses jalur routing REST API bawaan Auto Ngabari untuk melakukan
   proses asinkronus (crawling, data scraping, graph mapping, atau linking approvals).
   Gunakan parameter URL `/wp-json/auto-ngabari/v1/internal-links/{session_key}/{action}`:

   1. CRAWL SITE POSTS DATA:
      Endpoint: `GET /wp-json/auto-ngabari/v1/internal-links/{session_key}/crawl`
      Mengembalikan payload list post terbit beserta judul, URL, tags, dan excerpt.

   2. GET LINKING RECOMMENDATIONS:
      Endpoint: `GET /wp-json/auto-ngabari/v1/internal-links/{session_key}/suggestions?post_id=X`
      Mengembalikan array rekomendasi link target berdasarkan database postingan sejenis.

   3. APPLY & INSERT LINK WITH APPROVAL:
      Endpoint: `POST /wp-json/auto-ngabari/v1/internal-links/{session_key}/insert`
      Menerima payload JSON: `{ "post_id": X, "anchor": "Kata Kunci", "target_url": "https://..." }`
      Menyisipkan link ke dalam artikel secara langsung di database.

--------------------------------------------------------------------------------
4. CARA PENGGUNAAN
--------------------------------------------------------------------------------
1. Tulis kode ekstensi Anda pada file PHP baru (misal: `my-custom-mod.php`).
2. Upload file tersebut ke folder ini (`wp-content/auto-ngabari/extensions/`).
3. Masuk ke halaman admin Extensions, pilih tab "Extensions Manager".
4. Klik "Aktifkan" pada nama ekstensi Anda.
5. Jika memiliki settings, klik subtab nama menu yang muncul di atas panel manager.
================================================================================
