@zephyr424/wb-sdk 0.1.1 → 0.2.0

package/docs/.vitepress/config.mjs

@@ -0,0 +1,112 @@
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+  title: "wb-sdk",
+  description: "A spaced repetition engine for vocabulary building",
+
+  // 网站图标
+  head: [
+    ['link', { rel: 'icon', href: '/logo.png' }],
+    // Google Analytics（替换为你的 GA ID）
+    ['script', { async: '', src: 'https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX' }],
+    ['script', {}, `
+      window.dataLayer = window.dataLayer || [];
+      function gtag(){dataLayer.push(arguments);}
+      gtag('js', new Date());
+      gtag('config', 'G-XXXXXXXXXX');
+    `]
+  ],
+
+  // 深浅主题（默认已支持）
+  appearance: true,
+
+  themeConfig: {
+    // 搜索
+    search: {
+      provider: 'local'
+    },
+
+    // 导航栏
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'Guide', link: '/guide/' },
+      { text: 'API', link: '/api/word' },
+      { text: 'Blog', link: '/blog/' },
+      { text: 'GitHub', link: 'https://github.com/Zephyr424/wb-sdk' },
+      { text: 'npm', link: 'https://www.npmjs.com/package/@zephyr424/wb-sdk' }
+    ],
+
+    // 侧边栏
+    sidebar: {
+      '/guide/': [
+        {
+          text: 'Guide',
+          items: [
+            { text: 'Getting Started', link: '/guide/' },
+            { text: 'Core Concepts', link: '/guide/core-concepts' }
+          ]
+        }
+      ],
+      '/api/': [
+        {
+          text: 'API Reference',
+          items: [
+            { text: 'Word Management', link: '/api/word' },
+            { text: 'Review Scheduling', link: '/api/review' },
+            { text: 'Types', link: '/api/types' }
+          ]
+        }
+      ],
+      '/blog/': [
+        {
+          text: 'Blog',
+          items: [
+            { text: 'Why SM-2 Algorithm', link: '/blog/why-sm2' },
+            { text: 'Designing wb.word API', link: '/blog/designing-api' },
+            { text: 'How I Published to npm', link: '/blog/publishing-to-npm' }
+          ]
+        }
+      ]
+    },
+
+    // 社交链接
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/Zephyr424/wb-sdk' }
+    ],
+
+    // 页脚
+    footer: {
+      message: 'Released under the MIT License',
+      copyright: 'Copyright © 2026 Zephyr424'
+    },
+
+    // 上次更新时间
+    lastUpdated: {
+      text: 'Last updated'
+    },
+
+    // 贡献者展示（需要 GitHub API 支持，先配置）
+    contributors: {
+      avatarSize: 32
+    },
+
+    // 编辑链接（指向 GitHub）
+    editLink: {
+      pattern: 'https://github.com/Zephyr424/wb-sdk/edit/main/docs/:path',
+      text: 'Edit this page on GitHub'
+    }
+  },
+
+  // 多语言支持 (i18n)
+  locales: {
+    root: {
+      label: '简体中文',
+      lang: 'zh-CN'
+    },
+    en: {
+      label: 'English',
+      lang: 'en',
+      link: '/en/'
+    }
+  }
+})

package/docs/api/review.md

@@ -0,0 +1,155 @@
+# Review Scheduling API
+
+The `wb.review` module handles all spaced repetition logic — determining which words are due, recording review performance, and forecasting future workload.
+
+---
+
+## `wb.review.getDue([today])`
+
+Returns all words that are due for review on a given date.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `today` | `Date` | ❌ No | The date to check (defaults to `new Date()`). |
+
+**Returns:** `Word[]` — an array of `Word` objects that are due.
+
+**Example:**
+
+```javascript
+// Get words due today
+const dueToday = wb.review.getDue();
+console.log(`📚 ${dueToday.length} words due today`);
+
+// Get words due on a specific date
+const christmasDue = wb.review.getDue(new Date('2026-12-25'));
+```
+
+---
+
+## `wb.review.submit(id, quality)`
+
+Records a review attempt for a specific word and updates its SM‑2 state (interval, repetitions, ease factor, and last reviewed date).
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `id` | `string` | ✅ Yes | The ID of the word being reviewed. |
+| `quality` | `number` | ✅ Yes | Self‑rated recall quality from `0` (completely forgot) to `5` (perfect recall). |
+
+**Returns:** `Word` — the updated `Word` object.
+
+**Quality Scale:**
+
+| Score | Meaning |
+| :--- | :--- |
+| `5` | Perfect recall |
+| `4` | Good recall, slight hesitation |
+| `3` | Recalled with difficulty |
+| `2` | Forgot, but recognized |
+| `1` | Almost forgot |
+| `0` | Completely forgot |
+
+**Example:**
+
+```javascript
+// Review the word with ID 'apple' and rate it as 4/5
+const updated = wb.review.submit('apple', 4);
+console.log(`Next review in ${updated.interval} days`);
+```
+
+---
+
+## `wb.review.forecast([days])`
+
+Predicts how many words will become due for each day over the next N days, based on current word states.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `days` | `number` | ❌ No | Number of days to forecast (default: `7`). |
+
+**Returns:** `Object` — a dictionary where keys are date strings (`YYYY-MM-DD`) and values are the number of words due on that day.
+
+**Example:**
+
+```javascript
+const forecast = wb.review.forecast(7);
+console.log(forecast);
+// {
+//   '2026-09-01': 5,
+//   '2026-09-02': 8,
+//   '2026-09-03': 3,
+//   '2026-09-04': 0,
+//   '2026-09-05': 2,
+//   '2026-09-06': 4,
+//   '2026-09-07': 1
+// }
+```
+
+---
+
+## `wb.review.progress()`
+
+Returns an overview of your overall learning status — total words, mastered, remaining, and estimated days to mastery.
+
+**Returns:** `Object` with the following fields:
+
+| Field | Type | Description |
+| :--- | :--- | :--- |
+| `total` | `number` | Total number of words in the bank. |
+| `mastered` | `number` | Number of words with an interval ≥ 30 days. |
+| `remaining` | `number` | Words not yet mastered (`total - mastered`). |
+| `daysToMaster` | `number` | Estimated days until all words are mastered (based on an assumed rate of 5 new words mastered per day). |
+
+**Example:**
+
+```javascript
+const stats = wb.review.progress();
+console.log(stats);
+// { total: 5000, mastered: 1200, remaining: 3800, daysToMaster: 760 }
+```
+
+---
+
+## Understanding the SM‑2 Algorithm
+
+The `submit` method implements the **SM‑2** algorithm, which works as follows:
+
+- If `quality < 3` (failed recall):
+  - The word's `repetitions` counter is reset to `0`.
+  - The `interval` is set to `1` day (review again tomorrow).
+  - The `easeFactor` remains unchanged.
+
+- If `quality >= 3` (successful recall):
+  - The `interval` is updated based on the current `repetitions` count:
+    - `repetitions == 0` → interval = `1` day
+    - `repetitions == 1` → interval = `6` days
+    - `repetitions >= 2` → interval = `round(interval * easeFactor)`
+  - The `repetitions` count is incremented.
+  - The `easeFactor` is adjusted using the formula:
+    ```
+    ease += 0.1 - (5 - quality) * (0.08 + (5 - quality) * 0.02)
+    ```
+    The result is clamped between `1.3` and `2.5`.
+
+This dynamic adjustment ensures that words you find difficult appear more frequently, while easy words are spaced out over longer intervals.
+
+---
+
+## Summary of `wb.review` Methods
+
+| Method | Description |
+| :--- | :--- |
+| `getDue([today])` | Get words due for review today (or on a custom date). |
+| `submit(id, quality)` | Record a review and update the word's SM‑2 state. |
+| `forecast([days])` | Predict how many words will be due each day for the next N days. |
+| `progress()` | Get overall learning statistics (total, mastered, remaining, days to mastery). |
+
+For word management methods (`list`, `get`, `add`, `remove`, `search`, `top`), see the [Word Management API](/api/word).
+
+---

package/docs/api/word.md

@@ -0,0 +1,189 @@
+# Word Management API
+
+The `wb.word` module provides methods for managing your word bank — adding, retrieving, searching, and deleting words.
+
+---
+
+## `wb.word.list()`
+
+Returns all words currently stored in the bank.
+
+**Returns:** `Word[]` — an array of `Word` objects.
+
+**Example:**
+
+```javascript
+const allWords = wb.word.list();
+console.log(allWords);
+// [
+//   Word { id: '1', word: 'apple', definition: 'a fruit', ... },
+//   Word { id: '2', word: 'book', definition: 'a set of pages', ... }
+// ]
+```
+
+---
+
+## `wb.word.get(id)`
+
+Retrieves a single word by its unique identifier.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `id` | `string` | ✅ Yes | The unique ID of the word |
+
+**Returns:** `Word | null` — the word object if found, otherwise `null`.
+
+**Example:**
+
+```javascript
+const word = wb.word.get('apple');
+if (word) {
+  console.log(word.definition); // "a fruit"
+} else {
+  console.log('Word not found');
+}
+```
+
+---
+
+## `wb.word.add(data)`
+
+Adds a new word to the bank. If a word with the same ID already exists, it will be overwritten.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `data.id` | `string` | ✅ Yes | Unique identifier |
+| `data.word` | `string` | ✅ Yes | The word itself |
+| `data.definition` | `string` | ✅ Yes | Meaning or translation |
+| `data.repetitions` | `number` | ❌ No | Default: `0` |
+| `data.interval` | `number` | ❌ No | Default: `0` (days) |
+| `data.easeFactor` | `number` | ❌ No | Default: `2.5` (range 1.3–2.5) |
+| `data.lastReviewed` | `string \| Date \| null` | ❌ No | Default: `null` (ISO string or Date object) |
+
+**Returns:** `Word` — the newly created (or updated) word object.
+
+**Example:**
+
+```javascript
+// Add a simple word
+wb.word.add({
+  id: 'grok',
+  word: 'grok',
+  definition: 'to understand intuitively'
+});
+
+// Add a word with explicit SM‑2 state (e.g., when importing data)
+wb.word.add({
+  id: 'serendipity',
+  word: 'serendipity',
+  definition: 'the occurrence of events by chance in a happy way',
+  repetitions: 3,
+  interval: 15,
+  easeFactor: 2.3,
+  lastReviewed: '2026-08-15T10:00:00.000Z'
+});
+```
+
+---
+
+## `wb.word.remove(id)`
+
+Permanently deletes a word from the bank by its ID.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `id` | `string` | ✅ Yes | The unique ID of the word to remove |
+
+**Returns:** `void`
+
+**Example:**
+
+```javascript
+wb.word.remove('grok');
+// Now 'grok' is no longer in the bank
+```
+
+---
+
+## `wb.word.search(keyword)`
+
+Searches for words whose **word** or **definition** contains the given keyword (case‑insensitive).
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `keyword` | `string` | ✅ Yes | The search term (case‑insensitive) |
+
+**Returns:** `Word[]` — an array of matching words (empty if none found).
+
+**Example:**
+
+```javascript
+const results = wb.word.search('bene');
+// Returns words like "benevolent", "beneficial", "benefit"
+results.forEach(w => console.log(`${w.word}: ${w.definition}`));
+```
+
+---
+
+## `wb.word.top(n)`
+
+Returns the top `n` words with the **highest repetition count** — i.e., the words you have reviewed most often.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `n` | `number` | ✅ Yes | Number of top words to return |
+
+**Returns:** `Word[]` — an array of the top `n` words (sorted descending by repetitions).
+
+**Example:**
+
+```javascript
+const mostPracticed = wb.word.top(10);
+console.log('Your top 10 most practiced words:');
+mostPracticed.forEach(w => console.log(`${w.word} (${w.repetitions} reviews)`));
+```
+
+---
+
+## Data Type: `Word`
+
+The `Word` object contains the following fields:
+
+| Field | Type | Description |
+| :--- | :--- | :--- |
+| `id` | `string` | Unique identifier |
+| `word` | `string` | The word itself |
+| `definition` | `string` | Meaning or translation |
+| `repetitions` | `number` | Number of successful reviews |
+| `interval` | `number` | Current interval in days |
+| `easeFactor` | `number` | Difficulty factor (1.3 – 2.5) |
+| `lastReviewed` | `Date \| null` | Timestamp of the last review (Date object or null) |
+| `isDue(today?: Date)` | `function` | Returns `true` if the word is due for review on the given date (default: today) |
+| `toJSON()` | `function` | Returns a plain object suitable for serialization (e.g., to store in JSON) |
+
+---
+
+## Summary of `wb.word` Methods
+
+| Method | Description |
+| :--- | :--- |
+| `list()` | Get all words |
+| `get(id)` | Get a word by ID |
+| `add(data)` | Add or update a word |
+| `remove(id)` | Delete a word |
+| `search(keyword)` | Search words by word or definition |
+| `top(n)` | Get the most frequently reviewed words |
+
+For the review‑scheduling methods, see the [Review Scheduling API](/api/review).
+
+---

package/docs/blog/designing-api.md

@@ -0,0 +1,30 @@
+# Designing wb.word API
+
+The **API design** is the most important part of any library. A well-designed API makes developers want to use your library — and a bad one makes them run away.
+
+## Design principles
+
+1. **Intuitive**: Developers should guess how to use it without reading the docs.
+2. **Chainable**: Group related methods under clear namespaces.
+3. **Minimal**: Don't expose internal complexity.
+
+## Why wb.word and wb.review?
+
+I wanted developers to write code that reads like English:
+
+```javascript
+wb.word.add({ id: '1', word: 'apple', definition: 'a fruit' });
+const due = wb.review.getDue();
+```
+
+This is **self-documenting code** — you don't need comments to understand what it does.
+
+## What I learned
+
+- **Simplicity wins**: Remove unnecessary options and configurations.
+- **Document everything**: Even the most intuitive API needs examples.
+- **Listen to users**: The first user feedback I got helped me improve the design.
+
+---
+
+*Written on September 1, 2026*

package/docs/blog/index.md

@@ -0,0 +1,19 @@
+# Blog
+
+Welcome to the wb-sdk blog! Here I share my thoughts, learnings, and updates about the project.
+
+## Latest Posts
+
+- [Why SM-2 Algorithm](./why-sm2) — Understanding the science behind spaced repetition
+- [Designing wb.word API](./designing-api) — How I designed the word management interface
+- [How I Published to npm](./publishing-to-npm) — The journey from local code to global package
+
+---
+
+## All Posts
+
+| Date | Title | Description |
+| :--- | :--- | :--- |
+| 2026-09-01 | [Why SM-2 Algorithm](./why-sm2) | Why I chose SM-2 over other algorithms |
+| 2026-09-01 | [Designing wb.word API](./designing-api) | The design principles behind the API |
+| 2026-08-31 | [How I Published to npm](./publishing-to-npm) | A step-by-step guide to npm publishing |

package/docs/blog/publishing-to-npm.md

@@ -0,0 +1,36 @@
+# How I Published to npm
+
+Publishing my first npm package was harder than writing the code itself.
+
+## The challenges
+
+1. **2FA setup**: npm requires two-factor authentication, and I had to generate tokens properly.
+2. **Scoped package name**: wb-sdk was too similar to ws-sdk, so I had to use @zephyr424/wb-sdk.
+3. **GitHub integration**: Configuring the repository link and GitHub Pages deployment.
+
+## Step-by-step guide
+
+\\\ash
+# 1. Login to npm
+npm login
+
+# 2. Build and test locally
+npm run test
+
+# 3. Bump version
+npm version patch
+
+# 4. Publish to npm
+npm publish --access public
+\\\
+
+## Lessons learned
+
+- **Read the error messages**: npm tells you exactly what's wrong.
+- **Test before publishing**: Always test with 
+pm link first.
+- **Use a .npmignore file**: Control which files get published.
+
+---
+
+*Written on August 31, 2026*

package/docs/blog/why-sm2.md

@@ -0,0 +1,26 @@
+# Why SM-2 Algorithm
+
+The **SM-2** algorithm, developed by Piotr Woźniak in the 1980s, is the foundation of **spaced repetition** — a technique that optimizes memory retention by scheduling reviews at increasing intervals.
+
+## Why I chose SM-2
+
+1. **Proven track record**: SM-2 is the algorithm behind Anki, the most popular flashcard app.
+2. **Simple implementation**: The algorithm is elegant and easy to code.
+3. **Highly effective**: Research shows spaced repetition can boost retention by over 200%.
+
+## How it works
+
+When you rate your recall quality from 0 to 5:
+
+- **Quality < 3**: You forgot the word → reset interval to 1 day.
+- **Quality ≥ 3**: You remembered it → increase the interval and adjust the ease factor.
+
+This dynamic adjustment ensures you spend time on words you're about to forget.
+
+## Future plans
+
+I'm planning to add **FSRS** support in a future version — a more advanced algorithm that uses machine learning to optimize intervals.
+
+---
+
+*Written on September 1, 2026*

package/docs/contributors.md

@@ -0,0 +1,16 @@
+# Contributors
+
+Thank you to everyone who has contributed to \wb-sdk\!
+
+## Core Contributors
+
+- [@Zephyr424](https://github.com/Zephyr424) — Creator and maintainer
+
+## How to Contribute
+
+Want to join this list? Check out the [GitHub repository](https://github.com/Zephyr424/wb-sdk) and submit a pull request!
+
+- 🐛 Found a bug? Open an issue.
+- 💡 Have an idea? Start a discussion.
+- 📝 Want to improve docs? Send a PR.
+- 🧪 Want to add a feature? Fork and contribute!