malawi-curriculum-api 1.0.3

package/README.md

@@ -0,0 +1,424 @@
+# Malawi Curriculum API - JavaScript SDK
+
+A simple, typed client for accessing the Malawi Curriculum API.
+
+## Installation
+
+```bash
+npm install malawi-curriculum-api
+```
+
+## Quick Start
+
+```javascript
+import { MalawiCurriculumClient } from 'malawi-curriculum-api';
+
+const client = new MalawiCurriculumClient({
+  apiKey: 'YOUR_API_KEY'
+});
+
+const resources = await client.getResources({
+  level: 'MSCE',
+  subject: 'Mathematics',
+  type: 'past_paper'
+});
+```
+
+## API Overview
+
+The Malawi Curriculum API provides access to educational resources across various academic levels in Malawi. All endpoints require authentication via an API key.
+
+### Base URL
+
+```
+https://malawi-curricular-api-production.up.railway.app/api/v1
+```
+
+### Authentication
+
+Include your API key in the `Authorization` header:
+
+```
+Authorization: Bearer YOUR_API_KEY
+```
+
+## API Reference
+
+### Get Levels
+
+Retrieves all academic levels available in the Malawi curriculum.
+
+```javascript
+const levels = await client.getLevels();
+```
+
+**Request:**
+- Method: `GET`
+- Endpoint: `/levels`
+- Headers: `Authorization: Bearer API_KEY`
+
+**Response:**
+```json
+{
+  "success": true,
+  "count": 3,
+  "data": [
+    { "id": 1, "name": "JCE" },
+    { "id": 2, "name": "MSCE" },
+    { "id": 3, "name": "Primary" }
+  ]
+}
+```
+
+---
+
+### Get Subjects
+
+Retrieves subjects, optionally filtered by academic level.
+
+```javascript
+const subjects = await client.getSubjects('MSCE');
+```
+
+**Request:**
+- Method: `GET`
+- Endpoint: `/subjects`
+- Headers: `Authorization: Bearer API_KEY`
+- Query Parameters:
+  - `level` (optional): Filter by level name (e.g., "MSCE", "JCE")
+
+**Response:**
+```json
+{
+  "success": true,
+  "count": 12,
+  "data": [
+    { "id": 1, "name": "Mathematics", "level": "MSCE" },
+    { "id": 2, "name": "Physics", "level": "MSCE" },
+    { "id": 3, "name": "Chemistry", "level": "MSCE" }
+  ]
+}
+```
+
+---
+
+### Get Resources
+
+Retrieves curriculum resources with filtering options.
+
+```javascript
+const resources = await client.getResources({
+  level: 'MSCE',
+  subject: 'Mathematics',
+  type: 'past_paper',
+  year: 2023,
+  limit: 10
+});
+```
+
+**Request:**
+- Method: `GET`
+- Endpoint: `/resources`
+- Headers: `Authorization: Bearer API_KEY`
+- Query Parameters:
+  - `level` (required): Academic level (e.g., "MSCE", "JCE")
+  - `subject` (required): Subject name (e.g., "Mathematics")
+  - `type` (optional): Resource type
+    - `past_paper`
+    - `marking_scheme`
+    - `textbook`
+    - `teacher_notes`
+    - `student_notes`
+    - `scheme_of_work`
+  - `year` (optional): Year of the resource (integer)
+  - `limit` (optional): Number of results (1-100, default: 50)
+  - `offset` (optional): Pagination offset (default: 0)
+
+**Response:**
+```json
+{
+  "success": true,
+  "count": 5,
+  "total_count": 47,
+  "data": [
+    {
+      "id": 101,
+      "title": "MSCE Mathematics Paper 1 2023",
+      "type": "past_paper",
+      "year": 2023,
+      "description": "Main examination paper",
+      "subject": "Mathematics",
+      "level": "MSCE"
+    }
+  ]
+}
+```
+
+---
+
+### Download Resource (Secure Token Flow)
+
+Downloads use a two-step token flow for security. Requires a paid subscription (Basic, Pro, or Enterprise).
+
+#### Request a Download Token
+
+```javascript
+const tokenData = await client.requestDownload(101);
+console.log('Token:', tokenData.token);
+console.log('Expires in:', tokenData.expires_in_seconds, 'seconds');
+```
+
+**Request:**
+- Method: `POST`
+- Endpoint: `/downloads/request`
+- Headers: `Authorization: Bearer API_KEY`
+- Body: `{ "resourceId": 101 }`
+
+**Response:**
+```json
+{
+  "success": true,
+  "token": "a1b2c3d4e5f6...",
+  "expires_in_seconds": 900,
+  "download_url": "/api/v1/downloads/a1b2c3d4e5f6..."
+}
+```
+
+#### Redeem the Token
+
+```javascript
+const download = await client.redeemDownload(tokenData.token);
+console.log('File URL:', download.download_url);
+// URL is valid for 5 minutes, max 2 attempts per token
+```
+
+**Request:**
+- Method: `GET`
+- Endpoint: `/downloads/{token}`
+- No API key required (token is the authentication)
+
+**Response:**
+```json
+{
+  "success": true,
+  "download_url": "https://storage.googleapis.com/...",
+  "expires_in_seconds": 300,
+  "attempts_remaining": 1
+}
+```
+
+**Error Responses:**
+```json
+// Free Tier
+{ "error": "Free tier cannot download files.", "code": "PLAN_INSUFFICIENT" }
+
+// Limit Exceeded
+{ "error": "Daily download limit exceeded (100/day).", "code": "DOWNLOAD_LIMIT_EXCEEDED" }
+
+// Token Expired
+{ "error": "Download token has expired.", "code": "TOKEN_EXPIRED" }
+
+// Max Attempts
+{ "error": "Maximum download attempts reached (2).", "code": "TOKEN_MAX_ATTEMPTS" }
+```
+
+> **Security:** Tokens expire after 15 minutes, allow max 2 download attempts, and are stored as SHA-256 hashes in the database. The signed download URL is only valid for 5 minutes.
+
+---
+
+### Resource Pricing
+
+Set custom prices on resources or mark them as free. Each developer's pricing is independent, identified by their API key.
+
+#### Set a Price
+
+```javascript
+// Mark a resource as paid (500 MWK)
+const pricing = await client.setPrice({
+  resourceId: 101,
+  price: 500,
+  isFree: false
+});
+console.log(pricing);
+// { resource_id: 101, price_mwk: 500, is_free: false }
+
+// Mark a resource as free
+await client.setPrice({ resourceId: 101, isFree: true });
+```
+
+**Request:**
+- Method: `POST`
+- Endpoint: `/pricing/set`
+- Headers: `Authorization: Bearer API_KEY`
+- Body:
+  - `resourceId` (required): Resource ID
+  - `price` (optional): Price in MWK (ignored if `isFree` is true)
+  - `isFree` (optional): Set to `true` for free access
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "resource_id": 101,
+    "price_mwk": 500,
+    "is_free": false
+  }
+}
+```
+
+#### Get a Price
+
+```javascript
+const pricing = await client.getPrice(101);
+console.log(pricing.is_free);  // true or false
+console.log(pricing.price_mwk); // price in MWK
+```
+
+**Request:**
+- Method: `GET`
+- Endpoint: `/pricing/{resourceId}`
+- Headers: `Authorization: Bearer API_KEY`
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "resource_id": 101,
+    "price_mwk": 0,
+    "is_free": true
+  }
+}
+```
+
+If no price has been set, the resource defaults to free.
+
+**Download Enforcement:**
+
+When a resource has been priced (not free), download requests return `402 Payment Required`:
+
+```json
+{
+  "error": "This resource requires purchase before downloading.",
+  "code": "PAYMENT_REQUIRED",
+  "price_mwk": 500
+}
+```
+
+---
+
+### Search Resources
+
+Search across all curriculum resources. Results and filter capabilities depend on your plan tier.
+
+```javascript
+const results = await client.search({
+  q: 'biology past paper',
+  level: 'MSCE',        // Basic+ plans
+  type: 'past_paper',   // Pro+ plans
+  year: 2024            // Pro+ plans
+});
+```
+
+**Request:**
+- Method: `GET`
+- Endpoint: `/search`
+- Headers: `Authorization: Bearer API_KEY`
+- Query Parameters:
+  - `q` (required): Search query (min 2 characters)
+  - `level` (optional): Filter by level -- Basic+ plans only
+  - `subject` (optional): Filter by subject -- Basic+ plans only
+  - `type` (optional): Filter by resource type -- Pro+ plans only
+  - `year` (optional): Filter by year -- Pro+ plans only
+  - `limit` (optional): Max results (capped by plan tier)
+  - `offset` (optional): Pagination offset
+  - `sort` (optional): Sort order -- Enterprise only (`relevance`, `newest`, `oldest`, `title`)
+
+**Response:**
+```json
+{
+  "success": true,
+  "count": 5,
+  "total_count": 23,
+  "tier": "basic",
+  "tier_info": "Title & description search with basic filters.",
+  "data": [
+    {
+      "id": 101,
+      "title": "MSCE Biology Paper 1 2024",
+      "type": "past_paper",
+      "year": 2024,
+      "subject": "Biology",
+      "level": "MSCE",
+      "relevance": 0.8721
+    }
+  ]
+}
+```
+
+**Search Tier Limits:**
+
+| Feature | Free | Basic | Pro | Enterprise |
+|---|---|---|---|---|
+| Search fields | Title only | Title + Description | Title + Description | Title + Description |
+| Max results | 10 | 50 | 100 | 500 |
+| Filters | None | Level, Subject | All | All + Sorting |
+```
+
+## Error Handling
+
+All methods may throw errors for various reasons:
+
+```javascript
+try {
+  const resources = await client.getResources({ level: 'MSCE', subject: 'Math' });
+} catch (error) {
+  if (error.response?.status === 401) {
+    console.error('Invalid API key');
+  } else if (error.response?.status === 402) {
+    console.error('Payment required for this resource');
+  } else if (error.response?.status === 429) {
+    console.error('Rate limit exceeded');
+  } else {
+    console.error('Error:', error.message);
+  }
+}
+```
+
+### Common HTTP Status Codes
+
+- `200` - Success
+- `401` - Unauthorized (invalid or missing API key)
+- `402` - Payment Required (resource has a price set)
+- `403` - Forbidden (subscription expired or insufficient permissions)
+- `404` - Resource not found
+- `429` - Rate limit exceeded
+
+## Rate Limits & Plans
+
+Different subscription tiers provide varying levels of access. Visit the [developer portal](https://malawi-curricular-api-production.up.railway.app) for current pricing.
+
+### Free Plan
+- 100 requests/day
+- Metadata access only
+- No file downloads
+
+### Basic Plan
+- 1,000 requests/day
+- 5 downloads/day
+- Full API access
+
+### Pro Plan
+- 10,000 requests/day
+- 100 downloads/day
+- Priority support
+
+### Enterprise Plan
+- 100,000 requests/day
+- 1,000 downloads/day
+- 24/7 support
+
+## License
+
+ISC

package/package.json

@@ -0,0 +1,22 @@
+{
+    "name": "malawi-curriculum-api",
+    "version": "1.0.3",
+    "description": "Official JavaScript SDK for the Malawi Curriculum API",
+    "main": "src/MalawiCurriculumClient.js",
+    "type": "module",
+    "scripts": {
+        "test": "node test-sdk.js"
+    },
+    "keywords": [
+        "malawi",
+        "curriculum",
+        "education",
+        "api",
+        "sdk"
+    ],
+    "author": "CodingCodeMW",
+    "license": "ISC",
+    "dependencies": {
+        "node-fetch": "^3.3.0"
+    }
+}

package/src/MalawiCurriculumClient.js

@@ -0,0 +1,209 @@
+
+/**
+ * @typedef {Object} ResourceFilter
+ * @property {string} [level] - Education level (e.g., 'MSCE', 'JCE', 'PRIMARY')
+ * @property {string} [subject] - Subject name (e.g., 'Mathematics')
+ * @property {string} [type] - Resource type (e.g., 'past_paper', 'textbook')
+ * @property {number} [year] - Year of the resource
+ * @property {number} [limit] - Max number of results (1-100)
+ * @property {number} [offset] - Pagination offset
+ */
+
+/**
+ * @typedef {Object} Resource
+ * @property {number} id
+ * @property {string} title
+ * @property {string} type
+ * @property {string} subject
+ * @property {string} level
+ * @property {number|null} year
+ * @property {string|null} description
+ */
+
+export class MalawiCurriculumClient {
+    /**
+     * @param {Object} config
+     * @param {string} config.apiKey - Your API Key
+     * @param {string} [config.baseUrl] - API Base URL (default: https://malawi-curricular-api-production.up.railway.app/api/v1)
+     */
+    constructor({ apiKey, baseUrl }) {
+        if (!apiKey) throw new Error('API Key is required');
+
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl || 'https://malawi-curricular-api-production.up.railway.app/api/v1';
+    }
+
+    /**
+     * Helper to make authenticated requests
+     * @private
+     */
+    async _request(endpoint, query = {}) {
+        // Filter out undefined query params
+        const params = new URLSearchParams();
+        Object.entries(query).forEach(([key, value]) => {
+            if (value !== undefined && value !== null) {
+                params.append(key, String(value));
+            }
+        });
+
+        const url = `${this.baseUrl}${endpoint}?${params.toString()}`;
+
+        try {
+            const response = await fetch(url, {
+                headers: {
+                    'Authorization': `Bearer ${this.apiKey}`,
+                    'Content-Type': 'application/json'
+                }
+            });
+
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new Error(`API Error ${response.status}: ${errorText}`);
+            }
+
+            const json = await response.json();
+            return json;
+        } catch (error) {
+            if (error.cause) console.error('Network Error Cause:', error.cause);
+            throw error;
+        }
+    }
+
+    /**
+     * Helper to make authenticated POST requests
+     * @private
+     */
+    async _post(endpoint, body = {}) {
+        const url = `${this.baseUrl}${endpoint}`;
+
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${this.apiKey}`,
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify(body)
+            });
+
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new Error(`API Error ${response.status}: ${errorText}`);
+            }
+
+            return await response.json();
+        } catch (error) {
+            if (error.cause) console.error('Network Error Cause:', error.cause);
+            throw error;
+        }
+    }
+
+    /**
+     * Get filtered resources
+     * @param {ResourceFilter} filter 
+     * @returns {Promise<Resource[]>}
+     */
+    async getResources(filter = {}) {
+        const response = await this._request('/resources', filter);
+        return response.data || [];
+    }
+
+    /**
+     * Get all subjects, optionally filtered by level
+     * @param {string} [level] 
+     * @returns {Promise<Object[]>}
+     */
+    async getSubjects(level) {
+        const response = await this._request('/subjects', { level });
+        return response.data || [];
+    }
+
+    /**
+     * Get all education levels
+     * @returns {Promise<Object[]>}
+     */
+    async getLevels() {
+        const response = await this._request('/levels');
+        return response.data || [];
+    }
+
+    /**
+     * Search resources with plan-tiered filtering
+     * @param {Object} options
+     * @param {string} options.q - Search query (required, min 2 chars)
+     * @param {string} [options.level] - Filter by level (Basic+ plans)
+     * @param {string} [options.subject] - Filter by subject (Basic+ plans)
+     * @param {string} [options.type] - Filter by type (Pro+ plans)
+     * @param {number} [options.year] - Filter by year (Pro+ plans)
+     * @param {number} [options.limit] - Max results (capped by plan)
+     * @param {number} [options.offset] - Pagination offset
+     * @param {string} [options.sort] - Sort order (Enterprise only: 'relevance', 'newest', 'oldest', 'title')
+     * @returns {Promise<Object>} Search results with tier info
+     */
+    async search(options = {}) {
+        return await this._request('/search', options);
+    }
+
+    /**
+     * Request a secure download token (paid plans only)
+     * @param {number} resourceId - ID of the resource to download
+     * @returns {Promise<{token: string, expires_in_seconds: number, download_url: string}>}
+     */
+    async requestDownload(resourceId) {
+        return await this._post('/downloads/request', { resourceId });
+    }
+
+    /**
+     * Redeem a download token to get the file URL
+     * @param {string} token - Token from requestDownload()
+     * @returns {Promise<{download_url: string, expires_in_seconds: number, attempts_remaining: number}>}
+     */
+    async redeemDownload(token) {
+        return await this._request(`/downloads/${token}`);
+    }
+
+    /**
+     * Convenience: Request token and redeem in one call
+     * @param {number} resourceId
+     * @returns {Promise<string>} Signed download URL
+     */
+    async download(resourceId) {
+        const { token } = await this.requestDownload(resourceId);
+        const { download_url } = await this.redeemDownload(token);
+        return download_url;
+    }
+
+    /**
+     * @deprecated Use requestDownload() + redeemDownload() or download() instead
+     * @param {number} id 
+     * @returns {Promise<string>} Signed download URL
+     */
+    async downloadResource(id) {
+        console.warn('[DEPRECATED] downloadResource() is deprecated. Use download() for the secure token flow.');
+        const response = await this._request(`/resources/${id}/download`);
+        return response.download_url;
+    }
+
+    /**
+     * Set or update pricing for a resource
+     * @param {Object} options
+     * @param {number} options.resourceId - ID of the resource to price
+     * @param {number} [options.price] - Price in MWK (ignored if isFree is true)
+     * @param {boolean} [options.isFree] - Set to true to make the resource free
+     * @returns {Promise<{resource_id: number, price_mwk: number, is_free: boolean}>}
+     */
+    async setPrice({ resourceId, price, isFree }) {
+        const response = await this._post('/pricing/set', { resourceId, price, isFree });
+        return response.data;
+    }
+
+    /**
+     * Get the price set for a specific resource
+     * @param {number} resourceId - ID of the resource
+     * @returns {Promise<{resource_id: number, price_mwk: number, is_free: boolean}>}
+     */
+    async getPrice(resourceId) {
+        const response = await this._request(`/pricing/${resourceId}`);
+        return response.data;
+    }
+}

package/test-sdk.js

@@ -0,0 +1,42 @@
+
+import { MalawiCurriculumClient } from './src/MalawiCurriculumClient.js';
+
+// Use the known test key or replace with yours
+const API_KEY = 'YOUR_API_KEY'; // Replace with your actual key
+const BASE_URL = 'https://malawi-curricular-api-production.up.railway.app/api/v1';
+
+async function testSDK() {
+    console.log('Testing Malawi Curriculum SDK...');
+
+    const client = new MalawiCurriculumClient({
+        apiKey: API_KEY,
+        baseUrl: BASE_URL
+    });
+
+    try {
+        console.log('\nFetching Subjects...');
+        const subjects = await client.getSubjects();
+        console.log(`Success! Found ${subjects.length} subjects.`);
+        if (subjects.length > 0) console.log('   Sample:', subjects[0]);
+
+        console.log('\nFetching Levels...');
+        const levels = await client.getLevels();
+        console.log(`Success! Found ${levels.length} levels.`);
+        if (levels.length > 0) console.log('   Sample:', levels[0]);
+
+        console.log('\nFetching Resources (MSCE Mathematics)...');
+        const resources = await client.getResources({
+            level: 'MSCE',
+            subject: 'Mathematics',
+            limit: 5
+        });
+        console.log(`Success! Found ${resources.length} resources.`);
+        if (resources.length > 0) console.log('   Sample:', resources[0]);
+
+    } catch (error) {
+        console.error('SDK Test Failed:', error.message);
+        if (error.cause) console.error('   Cause:', error.cause);
+    }
+}
+
+testSDK();