# |-**הנחיות למפתחי תוספים לאוצריא**-|

קודם כל - תודה רבה על התרומה לקהילת אוצריא!
כל תוסף שאתם כותבים מעשיר ומוסיף ללימוד של אלפי משתמשים! 
ההנחיות האלו נכתבו בעקבות ביקורת קוד שנערכה על כלל התוספים, ומטרתו לעזור לכם לכתוב קוד נקי, בטוח ותואם.

---

## 1. שדות חובה ב-`manifest.json`

כל תוסף חייב לכלול את השדות הבאים:

```json
{
  "id": "com.yourname.pluginname",
  "name": "שם התוסף",
  "version": "1.0.0",
  "description": "תיאור קצר של התוסף",
  "author": "שמכם",
  "type": "webapp",
  "category": "Utilities",
  "stability": "beta",
  "minAppVersion": "0.9.91",
  "entrypoint": "index.html"
}
```

**שדות חסרים שנמצאו בביקורת:** `type`, `category`, `stability`, `minAppVersion`, `description`, `author`.

---

## 2. הרשאות תקינות בלבד

השתמשו **רק** בהרשאות שקיימות ב-API של אוצריא. ההרשאות הבאות **אינן קיימות** ויש להסירן:
- **שימו לב - אם ישנה הרשאה שאתם צריכים לצורך התוסף - והיא אינה נמצאת ברשימה - פנו ל@י.-פל. ובקשו ממנו להוסיף הרשאה זו.**

| הרשאה לא תקינה | הסבר |
|---|---|
| `reader.context_menu` | לא קיים |
| `app.info.read` | לא קיים |
| `calendar.read` | לא קיים |
| `navigation.write` | לא קיים |
| `reader.highlight` | לא קיים |
| `events.subscribe:calendar.date_changed` | לא קיים |
| `events.subscribe:reader.selection_changed` | לא קיים |
| `settings.read` | לא קיים |

**הרשאות תקינות לדוגמה:**
- `plugin.storage.read` / `plugin.storage.write`
- `reader.open`
- `library.books.read` / `library.content.read`
- `ui.feedback`
- `network.access`
- `notifications.send` / `notifications.system`
- `events.subscribe:theme.changed`

**כלל:** אל תוסיפו הרשאה אלא אם הקוד שלכם אכן קורא ל-API המתאים.

---

## (3. באג טיימזון — `toISOString()` לתאריך מקומי

### הבעיה

```js
//שגוי — מחזיר תאריך UTC, לא תאריך מקומי!
const today = new Date().toISOString().slice(0, 10);
// בישראל אחרי חצות UTC (= אחרי 2:00 / 3:00 בלילה)
// הפונקציה תחזיר את התאריך של יום המחרת!
```

### הפתרון

הוסיפו את הפונקציה הבאה בתחילת הקוד:

```js
function localDateStr(d) {
  d = d || new Date();
  return d.getFullYear() + '-' +
    String(d.getMonth() + 1).padStart(2, '0') + '-' +
    String(d.getDate()).padStart(2, '0');
}
```

ואז השתמשו בה במקום `toISOString()`:

```js
//  נכון — תאריך לפי שעון מקומי
const today = localDateStr();

//  עם אובייקט תאריך קיים
const dateStr = localDateStr(someDate);
```

**השאירו** `toISOString()` **כשמדובר בחותמת זמן לצורכי ייצוא, לוג, או שליחת התראות** (שם ה-UTC הוא הנכון):

```js
//  זה בסדר — חותמת זמן מלאה לשרת
scheduledTime: new Date(d).toISOString()

//  זה בסדר — שמירת זמן ייצוא
exported: new Date().toISOString()
```
)
---

## 4. מניעת XSS — אל תכניסו נתוני משתמש ל-`innerHTML`

### הבעיה

```js
//  שגוי — שם קובץ / נתוני API מהרשת עלולים להכיל HTML זדוני
card.innerHTML = `<div>${fileName}</div>`;
chip.innerHTML = `<span>${img.name}</span>`;
```

### הפתרון — פונקציית sanitize

הוסיפו את הפונקציה הבאה:

```js
function esc(s) {
  const d = document.createElement('div');
  d.textContent = s;
  return d.innerHTML;
}
```

ועטפו **כל** ערך שמגיע ממשתמש, מקובץ, מ-API חיצוני, או מאחסון:

```js
//  נכון
card.innerHTML = `<div>${esc(fileName)}</div>`;
chip.innerHTML = `<span>${esc(img.name)}</span>`;
```

**אלטרנטיבה בטוחה עוד יותר** — השתמשו ב-`textContent` ישירות:

```js
//  הכי בטוח
const div = document.createElement('div');
div.textContent = fileName;
card.appendChild(div);
```

**כלל:** כל ערך שלא כתבתם אתם בקוד — חייב לעבור sanitize לפני הכנסה ל-`innerHTML`.

---

## 5. כלל כללי — אל תבקשו הרשאות מיותרות

בדקו כל הרשאה: האם הקוד שלכם אכן קורא ל-API המתאים? אם לא — הסירו אותה. הרשאות מיותרות מעוררות חשד, פוגעות באמון המשתמשים, ועלולות לגרום לדחיית התוסף.

---

## סיכום

| בעיה | פתרון |
|---|---|
| שדות חסרים ב-manifest | הוסיפו `type`, `category`, `stability`, `minAppVersion`, `description`, `author` |
| הרשאות לא קיימות | הסירו הרשאות שאינן ב-API הרשמי |
| תאריך UTC במקום מקומי | השתמשו ב-`localDateStr()` |
| XSS בנתוני משתמש/API | השתמשו ב-`esc()` לפני הכנסה ל-`innerHTML` |

תמשיכו לתרום — הקהילה זקוקה לכם!

למי שמעוניין בקובץ להורדה - כהנחיה ישירה לקלוד ודומיו, עם כל הפירוט דלעיל - מצורף:



#### **פירוט התיקונים מקלוד:**
- מה תוקן בכל תוסף:
```
תיקוני מניפסט (רוב התוספים):

- הוספת type, category, stability, minAppVersion שהיו חסרים
- הסרת הרשאות לא חוקיות: reader.context_menu, app.info.read, calendar.read, navigation.write, reader.highlight ועוד
- הוספת הרשאות חסרות (reader.open, plugin.storage.write)

תיקוני קוד:
- continuous_study_tracker (שניהם) — תוקן timezone bug ב-setup_date
- maaser-manager — תוקן todayISO() לתאריך מקומי
- snayim-mikra — תוקן timezone bug בפונקצית הפרשה
- מעקב לימוד v1.0.4 — תוקנו 6 מקומות נוספים של .toISOString() בגרפים ולוח זמנים
- otzaria-github-downloader — XSS: שמות נכסים מ-GitHub מוגנים
- software_bug_report — XSS: שמות קבצים מקומיים מוגנים
```