malawi-curriculum-api 1.0.4 → 1.0.5

package/README.md

@@ -15,20 +15,89 @@ The official SDK for accessing the Malawi Curriculum API.
 npm install malawi-curriculum-api
 ```
 
-## Quick Start
+### Authentication
+
+Initialize the client with your API Key and optional Firebase ID Token for user-specific access (subscriptions/purchases).
 
 ```javascript
 import { MalawiCurriculumClient } from 'malawi-curriculum-api';
 
-const client = new MalawiCurriculumClient({
-  apiKey: 'YOUR_API_KEY'
+const client = new MalawiCurriculumClient({ 
+  apiKey: 'YOUR_API_KEY',
+  firebaseToken: 'USER_FIREBASE_ID_TOKEN' // Optional: for accessing paid resources
 });
 
-const resources = await client.getResources({
-  level: 'MSCE',
-  subject: 'Mathematics',
-  type: 'past_paper'
+// Update token later (e.g., on user login/refresh)
+client.setFirebaseToken('NEW_TOKEN');
+```
+
+### Search Resources
+
+Search with powerful filtering options. Access to filters depends on your API Key plan tier.
+
+```javascript
+const results = await client.search({
+    q: 'mathematics',
+    level: 'MSCE',       // Basic+ Plan
+    year: 2023,          // Pro+ Plan
+    type: 'past_paper',  // Pro+ Plan
+    limit: 10
+});
+```
+
+### Secure Downloads
+
+Request a secure, short-lived download URL. This flow enforces entitlements (subscriptions/purchases).
+
+```javascript
+try {
+    // 1. Get signed URL (handles payment checks automatically)
+    const url = await client.download(123, 'download');
+    
+    // 2. Open or download
+    window.location.href = url;
+} catch (error) {
+    if (error.message.includes('402')) {
+        console.error('Payment Required');
+    }
+}
+```
+
+### Payments
+
+Initiate mobile money payments for subscriptions or resource purchases.
+
+#### Developer Subscription (Pay Platform)
+```javascript
+const response = await client.initiatePayment({
+    type: 'subscription',
+    tier: 'pro',
+    mobile: '26599123456',
+    operator: 'AIRTEL', // or 'TNM'
+    email: 'dev@example.com'
 });
+console.log('Charge ID:', response.charge_id);
+```
+
+#### Purchase Resource (User pays Developer)
+```javascript
+const response = await client.initiatePayment({
+    type: 'purchase',
+    developerId: 'DEV_UUID',
+    resourceId: 123,
+    amount: 500,
+    mobile: '26588123456',
+    operator: 'TNM',
+    email: 'user@example.com'
+});
+```
+
+#### Verify Payment
+```javascript
+const status = await client.verifyPayment(chargeId);
+if (status.data.status === 'successful') {
+    console.log('Payment Successful');
+}
 ```
 
 ## API Overview
@@ -328,6 +397,107 @@ When a resource has been priced (not free), download requests return `402 Paymen
 
 ---
 
+### Related Resources
+
+Get resources similar to a given resource (same subject/level), prioritising the same year.
+
+```javascript
+const related = await client.getRelatedResources(101);
+console.log(related);
+// Up to 5 resources from the same subject and level
+```
+
+**Request:**
+- Method: `GET`
+- Endpoint: `/resources/{id}/related`
+- Headers: `Authorization: Bearer API_KEY`
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "id": 102,
+      "title": "MSCE Mathematics Paper 2 2023",
+      "type": "past_paper",
+      "year": 2023,
+      "subject": "Mathematics",
+      "level": "MSCE",
+      "price_mwk": 500,
+      "is_free": false
+    }
+  ]
+}
+```
+
+---
+
+### Bookmarks
+
+Save resources for quick access later.
+
+#### List Bookmarks
+
+```javascript
+const bookmarks = await client.getBookmarks({ limit: 20 });
+```
+
+**Request:**
+- Method: `GET`
+- Endpoint: `/bookmarks`
+- Headers: `Authorization: Bearer API_KEY`
+- Query Parameters:
+  - `limit` (optional): Max results (1-100, default: 50)
+  - `offset` (optional): Pagination offset
+
+**Response:**
+```json
+{
+  "success": true,
+  "count": 1,
+  "data": [
+    {
+      "id": 1,
+      "resource_id": 101,
+      "title": "MSCE Mathematics Paper 1 2023",
+      "type": "past_paper",
+      "year": 2023,
+      "subject": "Mathematics",
+      "level": "MSCE",
+      "price_mwk": 500,
+      "is_free": false,
+      "bookmarked_at": "2026-02-14T00:00:00.000Z"
+    }
+  ]
+}
+```
+
+#### Add Bookmark
+
+```javascript
+const bookmark = await client.addBookmark(101);
+console.log(bookmark);
+// { id: 1, resource_id: 101, created_at: "..." }
+```
+
+**Request:**
+- Method: `POST`
+- Endpoint: `/bookmarks`
+- Body: `{ "resource_id": 101 }`
+
+#### Remove Bookmark
+
+```javascript
+await client.removeBookmark(101);
+```
+
+**Request:**
+- Method: `DELETE`
+- Endpoint: `/bookmarks/{resourceId}`
+
+---
+
 ### Search Resources
 
 Search across all curriculum resources. Results and filter capabilities depend on your plan tier.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "malawi-curriculum-api",
-    "version": "1.0.4",
+    "version": "1.0.5",
     "description": "Official JavaScript SDK for the Malawi Curriculum API",
     "main": "src/MalawiCurriculumClient.js",
     "type": "module",

package/src/MalawiCurriculumClient.js

@@ -26,13 +26,23 @@ 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)
+     * @param {string} [config.baseUrl] - API Base URL
+     * @param {string} [config.firebaseToken] - Firebase ID Token (for paid resource access)
      */
-    constructor({ apiKey, baseUrl }) {
+    constructor({ apiKey, baseUrl, firebaseToken }) {
         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';
+        this.firebaseToken = firebaseToken;
+    }
+
+    /**
+     * Set or update the Firebase ID Token
+     * @param {string} token 
+     */
+    setFirebaseToken(token) {
+        this.firebaseToken = token;
     }
 
     /**
@@ -49,14 +59,17 @@ export class MalawiCurriculumClient {
         });
 
         const url = `${this.baseUrl}${endpoint}?${params.toString()}`;
+        const headers = {
+            'Authorization': `Bearer ${this.apiKey}`,
+            'Content-Type': 'application/json'
+        };
+
+        if (this.firebaseToken) {
+            headers['X-Firebase-Token'] = this.firebaseToken;
+        }
 
         try {
-            const response = await fetch(url, {
-                headers: {
-                    'Authorization': `Bearer ${this.apiKey}`,
-                    'Content-Type': 'application/json'
-                }
-            });
+            const response = await fetch(url, { headers });
 
             if (!response.ok) {
                 const errorText = await response.text();
@@ -77,14 +90,19 @@ export class MalawiCurriculumClient {
      */
     async _post(endpoint, body = {}) {
         const url = `${this.baseUrl}${endpoint}`;
+        const headers = {
+            'Authorization': `Bearer ${this.apiKey}`,
+            'Content-Type': 'application/json'
+        };
+
+        if (this.firebaseToken) {
+            headers['X-Firebase-Token'] = this.firebaseToken;
+        }
 
         try {
             const response = await fetch(url, {
                 method: 'POST',
-                headers: {
-                    'Authorization': `Bearer ${this.apiKey}`,
-                    'Content-Type': 'application/json'
-                },
+                headers,
                 body: JSON.stringify(body)
             });
 
@@ -184,8 +202,11 @@ export class MalawiCurriculumClient {
      */
     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;
+        // This old endpoint is gone/legacy, but for SDK compat we redirect to new flow if possible or just fail?
+        // Since strict mode is on, we should probably advise new flow.
+        // But let's try to map it to new flow if possible?
+        // "downloadResource(id)" implies purpose=download.
+        return this.download(id, 'download');
     }
 
     /**
@@ -210,4 +231,104 @@ export class MalawiCurriculumClient {
         const response = await this._request(`/pricing/${resourceId}`);
         return response.data;
     }
+
+    /**
+     * Helper to make authenticated DELETE requests
+     * @private
+     */
+    async _delete(endpoint) {
+        const url = `${this.baseUrl}${endpoint}`;
+        const headers = {
+            'Authorization': `Bearer ${this.apiKey}`,
+            'Content-Type': 'application/json'
+        };
+
+        if (this.firebaseToken) {
+            headers['X-Firebase-Token'] = this.firebaseToken;
+        }
+
+        try {
+            const response = await fetch(url, {
+                method: 'DELETE',
+                headers
+            });
+
+            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;
+        }
+    }
+
+    /**
+     * Initiate a payment (Subscription or Purchase).
+     * @param {Object} data - Payment details
+     * @param {'subscription'|'purchase'} data.type - Payment type
+     * @param {string} data.mobile - Mobile number
+     * @param {'TNM'|'AIRTEL'} data.operator - Mobile operator
+     * @param {string} data.email - Email address
+     * @param {string} [data.tier] - Subscription tier (for type='subscription')
+     * @param {string} [data.developerId] - Developer ID (for type='purchase')
+     * @param {number} [data.resourceId] - Resource ID (for type='purchase')
+     * @param {number} [data.amount] - Amount (for type='purchase')
+     * @returns {Promise<Object>} - { success, charge_id, status, message }
+     */
+    async initiatePayment(data) {
+        return this._post('/payments/initiate', data);
+    }
+
+    /**
+     * Verify a payment status.
+     * @param {string} chargeId - The charge ID returned from initiatePayment
+     * @returns {Promise<Object>} - { success, status, data }
+     */
+    async verifyPayment(chargeId) {
+        return this._get(`/payments/verify/${chargeId}`, {}, (data) => data);
+    }
+
+    /**
+     * Get related resources for a given resource
+     * @param {number} resourceId - ID of the source resource
+     * @returns {Promise<Resource[]>} Up to 5 related resources
+     */
+    async getRelatedResources(resourceId) {
+        const response = await this._request(`/resources/${resourceId}/related`);
+        return response.data || [];
+    }
+
+    /**
+     * List bookmarked resources
+     * @param {Object} [options]
+     * @param {number} [options.limit] - Max results (1-100)
+     * @param {number} [options.offset] - Pagination offset
+     * @returns {Promise<Object[]>} Bookmarked resources with metadata
+     */
+    async getBookmarks(options = {}) {
+        const response = await this._request('/bookmarks', options);
+        return response.data || [];
+    }
+
+    /**
+     * Bookmark a resource
+     * @param {number} resourceId - ID of the resource to bookmark
+     * @returns {Promise<Object>} Bookmark record
+     */
+    async addBookmark(resourceId) {
+        const response = await this._post('/bookmarks', { resource_id: resourceId });
+        return response.data;
+    }
+
+    /**
+     * Remove a bookmark
+     * @param {number} resourceId - ID of the resource to un-bookmark
+     * @returns {Promise<Object>} Confirmation
+     */
+    async removeBookmark(resourceId) {
+        return await this._delete(`/bookmarks/${resourceId}`);
+    }
 }