Plugin Development

פיתוח תוספים

מדריך כניסה למי שרוצה לכתוב תוסף לאוצריא. דף זה הוא מפת דרכים — התיעוד הקנוני והמלא יושב במאגר, בתיקיית docs/plugin-sdk/:

מסמך	מה יש בו
README.md	המדריך הראשי — מבנה תוסף, מניפסט, SDK, הרשאות, מצב פיתוח, אריזה והפצה
API_REFERENCE.md	ה־API המלא — כל הפעולות, הפרמטרים, ההרשאות והאירועים
COOKBOOK.md	מתכוני קוד מוכנים — גופנים מוזרקים, אייקונים, חלונית הגדרות בסגנון אוצריא
DESIGN_GUIDE.md	עיצוב שנראה כחלק מאוצריא — Material 3, צבעים מה־API בלבד
otzaria_plugin.d.ts	הגדרות TypeScript — השלמות אוטומטיות ב־IDE

מה זה תוסף

תוסף הוא אפליקציית web ‏(HTML/CSS/JS) הארוזה כקובץ ZIP עם סיומת .otzplugin. אוצריא פותחת את ה־HTML שלו ב־WebView מוגן ומזריקה אוטומטית אובייקט גלובלי Otzaria — אין ספריית JS לייבא, רק Otzaria.call(...) ו־Otzaria.on(...).

תוסף יכול, בין השאר: לחפש ולקרוא ספרים מהספרייה, לפתוח ספר בקורא (כולל לפי מראה מקום), להוסיף פריטים לתפריט ההקשר, לקרוא/לכתוב הערות אישיות, לפרסם אירועי לוח שנה, לגשת לרשת (עם allowlist), לשמור נתונים פרטיים, ולרוץ ברקע בעליית האפליקציה.

מבנה מינימלי

my-plugin/
├── manifest.json          ← חובה: id, name (עד 14 תווים), version, entrypoint, permissions[]
├── index.html             ← נקודת הכניסה
├── icon/icon.png          ← אייקון 64×64
└── js/, css/ ...

עקרונות שכדאי להכיר מהיום הראשון:

• הרשאות מוצהרות במניפסט ומאושרות על־ידי המשתמש בהתקנה. כל פעולת API ממופה למחרוזת הרשאה (library.content.read, ‏network.access...). בקשו רק מה שצריך.
• צבעים רק מה־API — המשתמש מחליף ערכות נושא ומצב כהה/בהיר; צבע קשיח ב־CSS ייראה שבור. פירוט ב־DESIGN_GUIDE.
• הגופנים העבריים של אוצריא מוזרקים אוטומטית ל־WebView — אין לארוז קובצי גופן.
• גישה לרשת דורשת networkEnabled + ‏allowlist דומיינים, וה־fetch עובר דרך צד ה־Flutter (עוקף CORS).
• כתיבה לדיסק מגודרת בהסכמת משתמש מפורשת (בחירת תיקייה/קובץ) — לא בהרשאת מניפסט בלבד.
• מגבלות חנות: name עד 14 תווים, description עד 150.

מחזור פיתוח

1. מצב פיתוח (Hot Reload) — טוענים את התוסף ישירות מתיקייה מקומית או משרת localhost (כולל HMR), דרך דיאלוג ניהול התוספים (otzaria://open/sdk). שינויים בקבצים נטענים מחדש אוטומטית.
2. אריזה — ‏otzaria pack-plugin מה־CLI של האפליקציה, או ה־GitHub Action (ראו בהמשך). קובץ .otzignore מחריג תיקיות פיתוח.
3. בדיקה מקומית — לחיצה כפולה על קובץ .otzplugin (משויך במערכת ההפעלה) או גרירה לדיאלוג ניהול התוספים.
4. פרסום לחנות — דרך otzaria.org, ידנית או אוטומטית מ־CI.

CI — אימות ופרסום אוטומטי

Otzaria/otzaria-plugin-validator הוא GitHub Action שמריץ על ריפו התוסף את כל מסלול ההפצה: אימות (אותן בדיקות של האריזה והחנות — מניפסט, מבנה, שימוש ב־API) ← בנייה (.otzplugin תקני) ← פרסום לחנות (כשמוגדרים Secrets; לעולם לא באירוע pull_request). רשימת ה־APIים וההרשאות נמשכת בזמן אמת מ־API_REFERENCE שבריפו הראשי, כך שהבדיקה תמיד מסונכרנת עם החוזה בפועל.

זרימה מומלצת: מעדכנים version ב־manifest.json ← ‏push ל־main ← ה־Action מאמת, אורז ומפרסם.

קישורי עומק לתוסף

• otzaria://open/plugin/<plugin-id> — פתיחת התוסף (גם אם אינו מוצמד ללשוניות).
• otzaria://plugin/install?url=<download-url> — קישור התקנה (לאתר/פורום).

פירוט: קישורי עומק.

איך זה עובד מבפנים

הצד של אוצריא — הגשר, אכיפת ההרשאות, ה־runtime, שרת הקבצים המקומי וגישת ה־DB — מתועד בדף מערכת התוספים.

דפים קשורים

• מערכת התוספים — הארכיטקטורה הפנימית
• תוספים — מדריך למשתמש — התקנה וניהול
• הריפואים של אוצריא — ה־validator ושאר הריפואים