@webwaka/core 1.3.0

package/src/rate-limit.test.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { checkRateLimit, type RateLimitOptions } from './rate-limit.js';
+
+function createMockKV(): KVNamespace {
+  const store = new Map<string, { value: string; expiresAt?: number }>();
+
+  return {
+    async get(key: string): Promise<string | null> {
+      const entry = store.get(key);
+      if (!entry) return null;
+      if (entry.expiresAt && Date.now() > entry.expiresAt) {
+        store.delete(key);
+        return null;
+      }
+      return entry.value;
+    },
+    async put(key: string, value: string, options?: { expirationTtl?: number }): Promise<void> {
+      const expiresAt = options?.expirationTtl
+        ? Date.now() + options.expirationTtl * 1000
+        : undefined;
+      store.set(key, { value, expiresAt });
+    },
+    async delete(key: string): Promise<void> {
+      store.delete(key);
+    },
+    async list(): Promise<any> {
+      return { keys: [] };
+    },
+    async getWithMetadata(): Promise<any> {
+      return { value: null, metadata: null };
+    },
+  } as unknown as KVNamespace;
+}
+
+describe('checkRateLimit()', () => {
+  let kv: KVNamespace;
+
+  beforeEach(() => {
+    kv = createMockKV();
+  });
+
+  it('allows requests under the limit', async () => {
+    const opts: RateLimitOptions = { kv, key: 'user:1', maxRequests: 5, windowSeconds: 60 };
+
+    const result = await checkRateLimit(opts);
+    expect(result.allowed).toBe(true);
+    expect(result.remaining).toBe(4);
+  });
+
+  it('blocks requests once the limit is reached', async () => {
+    const opts: RateLimitOptions = { kv, key: 'user:2', maxRequests: 3, windowSeconds: 60 };
+
+    await checkRateLimit(opts);
+    await checkRateLimit(opts);
+    await checkRateLimit(opts);
+
+    const blocked = await checkRateLimit(opts);
+    expect(blocked.allowed).toBe(false);
+    expect(blocked.remaining).toBe(0);
+  });
+
+  it('counts remaining correctly as requests accumulate', async () => {
+    const opts: RateLimitOptions = { kv, key: 'user:3', maxRequests: 5, windowSeconds: 60 };
+
+    const r1 = await checkRateLimit(opts);
+    expect(r1.remaining).toBe(4);
+
+    const r2 = await checkRateLimit(opts);
+    expect(r2.remaining).toBe(3);
+
+    const r3 = await checkRateLimit(opts);
+    expect(r3.remaining).toBe(2);
+  });
+
+  it('allows exactly maxRequests requests before blocking', async () => {
+    const opts: RateLimitOptions = { kv, key: 'user:4', maxRequests: 2, windowSeconds: 60 };
+
+    const r1 = await checkRateLimit(opts);
+    expect(r1.allowed).toBe(true);
+
+    const r2 = await checkRateLimit(opts);
+    expect(r2.allowed).toBe(true);
+
+    const r3 = await checkRateLimit(opts);
+    expect(r3.allowed).toBe(false);
+  });
+
+  it('provides resetAt as epoch milliseconds in the future', async () => {
+    const opts: RateLimitOptions = { kv, key: 'user:5', maxRequests: 5, windowSeconds: 60 };
+
+    const before = Date.now();
+    const result = await checkRateLimit(opts);
+
+    expect(result.resetAt).toBeGreaterThan(before);
+    expect(result.resetAt).toBeGreaterThan(Date.now() - 1000);
+    expect(result.resetAt % 1000).toBe(0);
+  });
+});

package/src/rate-limit.ts

@@ -0,0 +1,33 @@
+export interface RateLimitOptions {
+  kv: KVNamespace;
+  key: string;
+  maxRequests: number;
+  windowSeconds: number;
+}
+
+export interface RateLimitResult {
+  allowed: boolean;
+  remaining: number;
+  resetAt: number;
+}
+
+export async function checkRateLimit(opts: RateLimitOptions): Promise<RateLimitResult> {
+  const { kv, key, maxRequests, windowSeconds } = opts;
+
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  const windowStart = Math.floor(nowSeconds / windowSeconds) * windowSeconds;
+  const resetAt = (windowStart + windowSeconds) * 1000;
+  const kvKey = `rl:${key}:${windowStart}`;
+
+  const raw = await kv.get(kvKey);
+  let count = raw ? parseInt(raw, 10) : 0;
+
+  if (count >= maxRequests) {
+    return { allowed: false, remaining: 0, resetAt };
+  }
+
+  count += 1;
+  await kv.put(kvKey, String(count), { expirationTtl: windowSeconds * 2 });
+
+  return { allowed: true, remaining: maxRequests - count, resetAt };
+}

package/src/sms.test.ts

@@ -0,0 +1,112 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { TermiiProvider, createSmsProvider, sendTermiiSms } from './sms';
+
+const mockFetch = vi.fn();
+vi.stubGlobal('fetch', mockFetch);
+
+beforeEach(() => {
+  mockFetch.mockReset();
+});
+
+function makeTermiiResponse(ok: boolean, body: Record<string, unknown>) {
+  return Promise.resolve({
+    ok,
+    json: () => Promise.resolve(body),
+  });
+}
+
+describe('TermiiProvider', () => {
+  const provider = new TermiiProvider('test-api-key', 'WebWaka');
+
+  it('sendOtp succeeds via whatsapp on first attempt', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({ message_id: 'msg-1' }),
+    });
+    const result = await provider.sendOtp('2348012345678', 'Your OTP is 123456');
+    expect(result.success).toBe(true);
+    expect(result.messageId).toBe('msg-1');
+    expect(result.channel).toBe('whatsapp');
+  });
+
+  it('sendOtp falls back to sms when whatsapp fails', async () => {
+    // First call (whatsapp) fails
+    mockFetch.mockResolvedValueOnce({
+      ok: false,
+      json: () => Promise.resolve({ message: 'whatsapp unavailable' }),
+    });
+    // Second call (sms fallback) succeeds
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({ message_id: 'msg-sms-1' }),
+    });
+    const result = await provider.sendOtp('2348012345678', 'Your OTP is 654321');
+    expect(result.success).toBe(true);
+    expect(result.channel).toBe('sms');
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+  });
+
+  it('sendOtp does not retry when channel is sms and it fails', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: false,
+      json: () => Promise.resolve({ message: 'sms failed' }),
+    });
+    const result = await provider.sendOtp('2348012345678', 'OTP', 'sms');
+    expect(result.success).toBe(false);
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+  });
+
+  it('sendMessage calls sendOtp with whatsapp channel', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({ message_id: 'msg-2' }),
+    });
+    const result = await provider.sendMessage('2348012345678', 'Hello');
+    expect(result.success).toBe(true);
+    const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+    expect(body.channel).toBe('whatsapp');
+  });
+
+  it('returns error when fetch throws', async () => {
+    mockFetch.mockRejectedValueOnce(new Error('Network error'));
+    // whatsapp fails with network error → falls back to sms
+    mockFetch.mockRejectedValueOnce(new Error('Network error'));
+    const result = await provider.sendOtp('2348012345678', 'OTP');
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('Network error');
+  });
+
+  it('uses whatsapp_business channel as whatsapp in Termii API', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({ message_id: 'msg-wb' }),
+    });
+    await provider.sendOtp('2348012345678', 'OTP', 'whatsapp_business');
+    const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+    expect(body.channel).toBe('whatsapp');
+  });
+});
+
+describe('createSmsProvider', () => {
+  it('returns a TermiiProvider instance', () => {
+    const p = createSmsProvider('key-123');
+    expect(p).toBeInstanceOf(TermiiProvider);
+  });
+
+  it('accepts custom senderId', () => {
+    const p = createSmsProvider('key-123', 'MyApp') as TermiiProvider;
+    expect(p).toBeInstanceOf(TermiiProvider);
+  });
+});
+
+describe('sendTermiiSms', () => {
+  it('sends a message and returns result', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({ message_id: 'msg-3' }),
+    });
+    const result = await sendTermiiSms('2348012345678', 'Test message', 'api-key');
+    expect(result.success).toBe(true);
+    expect(result.messageId).toBe('msg-3');
+  });
+});

package/src/sms.ts

@@ -0,0 +1,85 @@
+export type OtpChannel = 'sms' | 'whatsapp' | 'whatsapp_business';
+
+export interface OtpResult {
+  success: boolean;
+  messageId?: string;
+  channel: OtpChannel;
+  error?: string;
+}
+
+export interface ISmsProvider {
+  sendOtp(to: string, message: string, channel?: OtpChannel): Promise<OtpResult>;
+  sendMessage(to: string, message: string): Promise<OtpResult>;
+}
+
+export class TermiiProvider implements ISmsProvider {
+  private apiKey: string;
+  private senderId: string;
+  private apiUrl = 'https://api.ng.termii.com/api/sms/send';
+
+  constructor(apiKey: string, senderId = 'WebWaka') {
+    this.apiKey = apiKey;
+    this.senderId = senderId;
+  }
+
+  async sendOtp(to: string, message: string, channel: OtpChannel = 'whatsapp'): Promise<OtpResult> {
+    const result = await this.deliver(to, message, channel);
+    if (!result.success && channel !== 'sms') {
+      return this.deliver(to, message, 'sms');
+    }
+    return result;
+  }
+
+  async sendMessage(to: string, message: string): Promise<OtpResult> {
+    return this.sendOtp(to, message, 'whatsapp');
+  }
+
+  private async deliver(to: string, message: string, channel: OtpChannel): Promise<OtpResult> {
+    const termiiChannel =
+      channel === 'whatsapp' || channel === 'whatsapp_business' ? 'whatsapp' : 'generic';
+
+    try {
+      const res = await fetch(this.apiUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          to,
+          from: this.senderId,
+          sms: message,
+          type: 'plain',
+          channel: termiiChannel,
+          api_key: this.apiKey,
+        }),
+      });
+      const data = (await res.json()) as any;
+      if (!res.ok) {
+        return {
+          success: false,
+          channel,
+          error: data?.message ?? 'Termii request failed',
+        };
+      }
+      return {
+        success: true,
+        messageId: data?.message_id ?? data?.pinId,
+        channel,
+      };
+    } catch (err: any) {
+      return { success: false, channel, error: err?.message };
+    }
+  }
+}
+
+export function createSmsProvider(apiKey: string, senderId?: string): ISmsProvider {
+  return new TermiiProvider(apiKey, senderId);
+}
+
+export async function sendTermiiSms(
+  to: string,
+  message: string,
+  apiKey: string,
+  senderId?: string
+): Promise<OtpResult> {
+  const provider = createSmsProvider(apiKey, senderId);
+  return provider.sendMessage(to, message);
+}

package/src/tax.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect } from 'vitest';
+import { TaxEngine, createTaxEngine } from './tax.js';
+
+describe('TaxEngine.compute()', () => {
+  it('applies VAT to all items when none are exempt', () => {
+    const engine = createTaxEngine({
+      vatRate: 0.075,
+      vatRegistered: true,
+      exemptCategories: [],
+    });
+
+    const result = engine.compute([
+      { category: 'food', amountKobo: 10_000 },
+      { category: 'electronics', amountKobo: 50_000 },
+    ]);
+
+    expect(result.subtotalKobo).toBe(60_000);
+    expect(result.vatKobo).toBe(Math.round(10_000 * 0.075) + Math.round(50_000 * 0.075));
+    expect(result.totalKobo).toBe(result.subtotalKobo + result.vatKobo);
+    expect(result.vatBreakdown).toHaveLength(2);
+  });
+
+  it('skips VAT for exempt categories', () => {
+    const engine = createTaxEngine({
+      vatRate: 0.075,
+      vatRegistered: true,
+      exemptCategories: ['food', 'medicine'],
+    });
+
+    const result = engine.compute([
+      { category: 'food', amountKobo: 10_000 },
+      { category: 'electronics', amountKobo: 20_000 },
+      { category: 'medicine', amountKobo: 5_000 },
+    ]);
+
+    const foodBreakdown = result.vatBreakdown.find((b) => b.category === 'food');
+    const medicineBreakdown = result.vatBreakdown.find((b) => b.category === 'medicine');
+    const electronicsBreakdown = result.vatBreakdown.find((b) => b.category === 'electronics');
+
+    expect(foodBreakdown?.vatKobo).toBe(0);
+    expect(medicineBreakdown?.vatKobo).toBe(0);
+    expect(electronicsBreakdown?.vatKobo).toBe(Math.round(20_000 * 0.075));
+    expect(result.subtotalKobo).toBe(35_000);
+  });
+
+  it('skips all VAT when vatRegistered is false', () => {
+    const engine = createTaxEngine({
+      vatRate: 0.075,
+      vatRegistered: false,
+      exemptCategories: [],
+    });
+
+    const result = engine.compute([
+      { category: 'electronics', amountKobo: 100_000 },
+    ]);
+
+    expect(result.vatKobo).toBe(0);
+    expect(result.totalKobo).toBe(100_000);
+  });
+
+  it('rounds kobo values correctly', () => {
+    const engine = new TaxEngine({
+      vatRate: 0.075,
+      vatRegistered: true,
+      exemptCategories: [],
+    });
+
+    const result = engine.compute([{ category: 'misc', amountKobo: 1 }]);
+    expect(result.vatKobo).toBe(Math.round(1 * 0.075));
+  });
+
+  it('returns zero totals for empty items', () => {
+    const engine = createTaxEngine({
+      vatRate: 0.075,
+      vatRegistered: true,
+      exemptCategories: [],
+    });
+
+    const result = engine.compute([]);
+    expect(result.subtotalKobo).toBe(0);
+    expect(result.vatKobo).toBe(0);
+    expect(result.totalKobo).toBe(0);
+    expect(result.vatBreakdown).toHaveLength(0);
+  });
+});

package/src/tax.ts

@@ -0,0 +1,57 @@
+export interface TaxConfig {
+  vatRate: number;
+  vatRegistered: boolean;
+  exemptCategories: string[];
+}
+
+export interface TaxLineItem {
+  category: string;
+  amountKobo: number;
+}
+
+export interface TaxResult {
+  subtotalKobo: number;
+  vatKobo: number;
+  totalKobo: number;
+  vatBreakdown: { category: string; vatKobo: number }[];
+}
+
+export class TaxEngine {
+  private config: TaxConfig;
+
+  constructor(config: TaxConfig) {
+    this.config = config;
+  }
+
+  compute(items: TaxLineItem[]): TaxResult {
+    let subtotalKobo = 0;
+    let vatKobo = 0;
+    const vatBreakdown: { category: string; vatKobo: number }[] = [];
+
+    for (const item of items) {
+      subtotalKobo += item.amountKobo;
+
+      const isExempt =
+        !this.config.vatRegistered ||
+        this.config.exemptCategories.includes(item.category);
+
+      const itemVat = isExempt
+        ? 0
+        : Math.round(item.amountKobo * this.config.vatRate);
+
+      vatKobo += itemVat;
+      vatBreakdown.push({ category: item.category, vatKobo: itemVat });
+    }
+
+    return {
+      subtotalKobo,
+      vatKobo,
+      totalKobo: subtotalKobo + vatKobo,
+      vatBreakdown,
+    };
+  }
+}
+
+export function createTaxEngine(config: TaxConfig): TaxEngine {
+  return new TaxEngine(config);
+}