@zephyr424/wb-sdk 0.1.1 → 0.3.0

package/docs/en/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/en/guide/index.md

@@ -0,0 +1,28 @@
+# Getting Started
+
+## Installation
+
+\\\ash
+npm install @zephyr424/wb-sdk
+\\\
+
+## Quick Start
+
+\\\javascript
+const { WordBank } = require('@zephyr424/wb-sdk');
+
+const wb = new WordBank();
+
+// Add words
+wb.word.add({ id: '1', word: 'apple', definition: 'a fruit' });
+wb.word.add({ id: '2', word: 'benevolent', definition: 'kind' });
+
+// Get today's review queue
+const due = wb.review.getDue();
+console.log(\📚 \ words due today\);
+\\\
+
+## Next Steps
+
+- [API Documentation](/en/api/word) — Explore all methods
+- [Blog](/en/blog/) — Read about design decisions

package/docs/en/index.md

@@ -0,0 +1,25 @@
+---
+layout: home
+
+hero:
+  name: "wb-sdk"
+  text: "A spaced repetition engine"
+  tagline: Build smarter vocabulary apps with one command
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /en/guide/
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/Zephyr424/wb-sdk
+
+features:
+  - title: 🧠 SM-2 Algorithm
+    details: Industry-standard spaced repetition, proven to optimize memory retention
+  - title: 📚 Zero Dependencies
+    details: Lightweight and fast — no bloat, just the engine
+  - title: 🔁 Intuitive API
+    details: Clean, chainable methods — wb.word & wb.review
+  - title: 📦 npm Ready
+    details: npm install @zephyr424/wb-sdk and start building
+---

package/docs/guide/index.md

@@ -0,0 +1,100 @@
+# Getting Started
+
+## Introduction
+
+**wb-sdk** is a lightweight, zero‑dependency JavaScript library that implements the **SM‑2 spaced repetition algorithm** — the same engine behind Anki and many other flashcard apps. It provides a clean, intuitive API (`wb.word` and `wb.review`) so you can easily add intelligent vocabulary review to your own applications without reinventing the wheel.
+
+## Installation
+
+Install the package via npm:
+
+```bash
+npm install @zephyr424/wb-sdk
+```
+
+Or using yarn:
+
+```bash
+yarn add @zephyr424/wb-sdk
+```
+
+## Quick Start
+
+Here’s a minimal example to get you up and running in seconds:
+
+```javascript
+// 1. Import the library
+const { WordBank } = require('@zephyr424/wb-sdk');
+
+// 2. Create a word bank instance
+const wb = new WordBank();
+
+// 3. Add some words
+wb.word.add({ id: '1', word: 'apple', definition: 'a fruit' });
+wb.word.add({ id: '2', word: 'benevolent', definition: 'kind and generous' });
+wb.word.add({ id: '3', word: 'ephemeral', definition: 'lasting for a short time' });
+
+// 4. Get today's review queue (all words are due initially)
+const due = wb.review.getDue();
+console.log(`📚 ${due.length} words due for review today:`);
+due.forEach(w => console.log(`  - ${w.word}: ${w.definition}`));
+
+// 5. Simulate a review (quality from 0 = forgot to 5 = perfect)
+wb.review.submit('1', 4); // "apple" with quality 4/5
+
+// 6. Check progress
+console.log(wb.review.progress());
+// { total: 3, mastered: 0, remaining: 3, daysToMaster: 1 }
+```
+
+## Core Concepts
+
+### The SM‑2 Algorithm
+
+SM‑2 is a **spaced repetition** algorithm that optimizes the interval between reviews based on your performance. Each time you review a word and rate your recall (0–5), the engine:
+
+- Adjusts the word’s **ease factor** (difficulty) dynamically
+- Calculates the **next review interval** (in days)
+- Tracks **repetition count** to determine when a word is “mastered”
+
+This ensures you spend time on the words you’re most likely to forget — maximizing learning efficiency.
+
+### Data Structure
+
+Each word is stored as a `Word` object with the following fields:
+
+| Field | Type | Description |
+| :--- | :--- | :--- |
+| `id` | `string` | Unique identifier (required) |
+| `word` | `string` | The word itself (required) |
+| `definition` | `string` | Meaning or translation (required) |
+| `repetitions` | `number` | Number of successful reviews (default `0`) |
+| `interval` | `number` | Current interval in days (default `0`) |
+| `easeFactor` | `number` | Difficulty factor between `1.3` and `2.5` (default `2.5`) |
+| `lastReviewed` | `Date \| null` | Timestamp of the last review (default `null`) |
+
+### Workflow
+
+1. **Add** words to the bank using `wb.word.add()`.
+2. Each day, call `wb.review.getDue()` to get the words that need review.
+3. For each reviewed word, call `wb.review.submit(id, quality)` with your self‑rated quality score.
+4. The engine updates the word’s state automatically — the next review date is calculated for you.
+5. Track overall progress with `wb.review.progress()`.
+
+## API Overview
+
+The library exposes two main sub‑modules:
+
+- **`wb.word`** – manage your word list (`list`, `get`, `add`, `remove`, `search`, `top`)
+- **`wb.review`** – handle review scheduling (`getDue`, `submit`, `forecast`, `progress`)
+
+For detailed method signatures and examples, visit the [API Reference](/api/word).
+
+## Next Steps
+
+- 📖 Read the full [API Documentation](/api/word) to explore every method.
+- 🧪 Run the built‑in example: `node example.js` (in the project root).
+- 💡 Check the [GitHub repository](https://github.com/Zephyr424/wb-sdk) for source code and contributing guidelines.
+- 🌟 If you find this library useful, please give it a star ⭐ on GitHub!
+
+---

package/docs/index.md

@@ -0,0 +1,39 @@
+---
+layout: home
+
+hero:
+  name: "wb-sdk"
+  text: "A spaced repetition engine"
+  tagline: Build smarter vocabulary apps with one command
+  actions:
+  - theme: brand
+    text: Get Started
+    link: /guide/
+  - theme: alt
+    text: View on GitHub
+    link: https://github.com/Zephyr424/wb-sdk
+
+features:
+  - title: 🧠 SM-2 Algorithm
+    details: Industry-standard spaced repetition, proven to optimize memory retention
+  - title: 📚 Zero Dependencies
+    details: Lightweight and fast — no bloat, just the engine
+  - title: 🔁 Intuitive API
+    details: Clean, chainable methods — wb.word & wb.review
+  - title: 📦 npm Ready
+    details: npm install @zephyr424/wb-sdk and start building
+---
+
+## 📊 Download Stats
+
+![npm downloads](https://img.shields.io/npm/dt/@zephyr424/wb-sdk.svg)
+![npm version](https://img.shields.io/npm/v/@zephyr424/wb-sdk.svg)
+![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
+
+---
+
+## 🚀 Try it online
+
+Click the button above to open an interactive demo on CodeSandbox. No installation required!
+
+---