@webwaka/core 1.3.0

package/src/optimistic-lock.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect, vi } from 'vitest';
+import { updateWithVersionLock } from './optimistic-lock';
+
+function makeMockDb(changes: number) {
+  const mockRun = vi.fn().mockResolvedValue({ meta: { changes } });
+  const mockBind = vi.fn().mockReturnValue({ run: mockRun });
+  const mockPrepare = vi.fn().mockReturnValue({ bind: mockBind });
+  return { prepare: mockPrepare, mockRun, mockBind, mockPrepare };
+}
+
+describe('updateWithVersionLock', () => {
+  it('returns success: true when row is updated (changes = 1)', async () => {
+    const { prepare } = makeMockDb(1);
+    const result = await updateWithVersionLock(
+      { prepare } as any,
+      'orders',
+      { status: 'completed' },
+      { id: 'order-1', tenantId: 'tenant-1', expectedVersion: 3 }
+    );
+    expect(result.success).toBe(true);
+    expect(result.conflict).toBe(false);
+  });
+
+  it('returns conflict: true when no rows are updated (version mismatch)', async () => {
+    const { prepare } = makeMockDb(0);
+    const result = await updateWithVersionLock(
+      { prepare } as any,
+      'orders',
+      { status: 'completed' },
+      { id: 'order-1', tenantId: 'tenant-1', expectedVersion: 3 }
+    );
+    expect(result.success).toBe(false);
+    expect(result.conflict).toBe(true);
+  });
+
+  it('returns error when db throws', async () => {
+    const mockRun = vi.fn().mockRejectedValue(new Error('D1 error'));
+    const mockBind = vi.fn().mockReturnValue({ run: mockRun });
+    const mockPrepare = vi.fn().mockReturnValue({ bind: mockBind });
+    const mockDb = { prepare: mockPrepare } as any;
+
+    const result = await updateWithVersionLock(
+      mockDb,
+      'orders',
+      { status: 'completed' },
+      { id: 'order-1', tenantId: 'tenant-1', expectedVersion: 1 }
+    );
+    expect(result.success).toBe(false);
+    expect(result.conflict).toBe(false);
+    expect(result.error).toBe('D1 error');
+  });
+
+  it('builds SET clause from multiple update fields', async () => {
+    const { prepare, mockBind } = makeMockDb(1);
+    await updateWithVersionLock(
+      { prepare } as any,
+      'products',
+      { name: 'Widget', priceKobo: 5000, stock: 10 },
+      { id: 'prod-1', tenantId: 'tenant-2', expectedVersion: 5 }
+    );
+    const sql = (prepare as any).mock.calls[0][0] as string;
+    expect(sql).toContain('name = ?');
+    expect(sql).toContain('priceKobo = ?');
+    expect(sql).toContain('stock = ?');
+    expect(sql).toContain('version = version + 1');
+    // bind args: 3 update values + updatedAt + id + tenantId + expectedVersion
+    const bindArgs = mockBind.mock.calls[0];
+    expect(bindArgs).toContain('Widget');
+    expect(bindArgs).toContain(5000);
+    expect(bindArgs).toContain(10);
+    expect(bindArgs).toContain('prod-1');
+    expect(bindArgs).toContain('tenant-2');
+    expect(bindArgs).toContain(5);
+  });
+});

package/src/optimistic-lock.ts

@@ -0,0 +1,36 @@
+export interface OptimisticLockResult {
+  success: boolean;
+  conflict: boolean;
+  error?: string;
+}
+
+export async function updateWithVersionLock(
+  db: D1Database,
+  table: string,
+  updates: Record<string, any>,
+  where: { id: string; tenantId: string; expectedVersion: number }
+): Promise<OptimisticLockResult> {
+  try {
+    const now = new Date().toISOString();
+    const setClauses = Object.keys(updates)
+      .map((col) => `${col} = ?`)
+      .join(', ');
+    const setValues = Object.values(updates);
+
+    const sql = `
+      UPDATE ${table}
+      SET ${setClauses}, version = version + 1, updatedAt = ?
+      WHERE id = ? AND tenantId = ? AND version = ? AND deletedAt IS NULL
+    `;
+
+    const stmt = db.prepare(sql).bind(...setValues, now, where.id, where.tenantId, where.expectedVersion);
+    const result = await stmt.run();
+
+    if ((result.meta as any).changes === 0) {
+      return { success: false, conflict: true };
+    }
+    return { success: true, conflict: false };
+  } catch (err: any) {
+    return { success: false, conflict: false, error: err?.message };
+  }
+}

package/src/payment.test.ts

@@ -0,0 +1,152 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { PaystackProvider, createPaymentProvider } from './payment';
+
+const mockFetch = vi.fn();
+vi.stubGlobal('fetch', mockFetch);
+
+beforeEach(() => {
+  mockFetch.mockReset();
+});
+
+const provider = new PaystackProvider('sk_test_key');
+
+describe('PaystackProvider.verifyCharge', () => {
+  it('returns success when Paystack responds with status: true', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({
+        status: true,
+        data: { reference: 'ref-001', amount: 50000, status: 'success' },
+      }),
+    });
+    const result = await provider.verifyCharge('ref-001');
+    expect(result.success).toBe(true);
+    expect(result.reference).toBe('ref-001');
+    expect(result.amountKobo).toBe(50000);
+  });
+
+  it('returns failure when Paystack responds with status: false', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({ status: false, message: 'Invalid key' }),
+    });
+    const result = await provider.verifyCharge('ref-bad');
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('Invalid key');
+  });
+
+  it('returns failure when fetch throws', async () => {
+    mockFetch.mockRejectedValueOnce(new Error('Network error'));
+    const result = await provider.verifyCharge('ref-err');
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('Network error');
+  });
+
+  it('returns failure when response is not ok', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: false,
+      json: () => Promise.resolve({ message: 'Unauthorized' }),
+    });
+    const result = await provider.verifyCharge('ref-unauth');
+    expect(result.success).toBe(false);
+  });
+});
+
+describe('PaystackProvider.initiateRefund', () => {
+  it('returns success with refundId on successful refund', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({ status: true, data: { id: 'rfnd-123' } }),
+    });
+    const result = await provider.initiateRefund('ref-001', 50000);
+    expect(result.success).toBe(true);
+    expect(result.refundId).toBe('rfnd-123');
+  });
+
+  it('returns failure when Paystack returns status: false', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({ status: false, message: 'Refund failed' }),
+    });
+    const result = await provider.initiateRefund('ref-001');
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('Refund failed');
+  });
+
+  it('returns failure when fetch throws', async () => {
+    mockFetch.mockRejectedValueOnce(new Error('Timeout'));
+    const result = await provider.initiateRefund('ref-err');
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('Timeout');
+  });
+});
+
+describe('PaystackProvider.initiateSplit', () => {
+  it('returns success when split initiation succeeds', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({ status: true, data: {} }),
+    });
+    const result = await provider.initiateSplit(
+      100000,
+      [{ subaccountCode: 'ACCT_abc', amountKobo: 60000 }],
+      'split-ref-1'
+    );
+    expect(result.success).toBe(true);
+    expect(result.reference).toBe('split-ref-1');
+    expect(result.amountKobo).toBe(100000);
+  });
+
+  it('returns failure when Paystack returns status: false', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: false,
+      json: () => Promise.resolve({ status: false, message: 'Split failed' }),
+    });
+    const result = await provider.initiateSplit(100000, [], 'split-ref-2');
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('Split failed');
+  });
+
+  it('returns failure when fetch throws', async () => {
+    mockFetch.mockRejectedValueOnce(new Error('Network'));
+    const result = await provider.initiateSplit(100000, [], 'split-ref-3');
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('Network');
+  });
+});
+
+describe('PaystackProvider.initiateTransfer', () => {
+  it('returns success with transferCode', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({ status: true, data: { transfer_code: 'TRF_abc' } }),
+    });
+    const result = await provider.initiateTransfer('RCP_xyz', 25000, 'trf-ref-1');
+    expect(result.success).toBe(true);
+    expect(result.transferCode).toBe('TRF_abc');
+  });
+
+  it('returns failure when Paystack returns status: false', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: false,
+      json: () => Promise.resolve({ status: false, message: 'Transfer failed' }),
+    });
+    const result = await provider.initiateTransfer('RCP_xyz', 25000, 'trf-ref-2');
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('Transfer failed');
+  });
+
+  it('returns failure when fetch throws', async () => {
+    mockFetch.mockRejectedValueOnce(new Error('Timeout'));
+    const result = await provider.initiateTransfer('RCP_xyz', 25000, 'trf-ref-3');
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('Timeout');
+  });
+});
+
+describe('createPaymentProvider', () => {
+  it('returns a PaystackProvider instance', () => {
+    const p = createPaymentProvider('sk_live_key');
+    expect(p).toBeInstanceOf(PaystackProvider);
+  });
+});

package/src/payment.ts

@@ -0,0 +1,163 @@
+export interface ChargeResult {
+  success: boolean;
+  reference: string;
+  amountKobo: number;
+  error?: string;
+}
+
+export interface RefundResult {
+  success: boolean;
+  refundId: string;
+  error?: string;
+}
+
+export interface SplitRecipient {
+  subaccountCode: string;
+  amountKobo: number;
+}
+
+export interface IPaymentProvider {
+  verifyCharge(reference: string): Promise<ChargeResult>;
+  initiateRefund(reference: string, amountKobo?: number): Promise<RefundResult>;
+  initiateSplit(
+    totalKobo: number,
+    recipients: SplitRecipient[],
+    reference: string
+  ): Promise<ChargeResult>;
+  initiateTransfer(
+    recipientCode: string,
+    amountKobo: number,
+    reference: string
+  ): Promise<{ success: boolean; transferCode: string; error?: string }>;
+}
+
+export class PaystackProvider implements IPaymentProvider {
+  private secretKey: string;
+  private baseUrl = 'https://api.paystack.co';
+
+  constructor(secretKey: string) {
+    this.secretKey = secretKey;
+  }
+
+  private get headers(): Record<string, string> {
+    return {
+      Authorization: `Bearer ${this.secretKey}`,
+      'Content-Type': 'application/json',
+    };
+  }
+
+  async verifyCharge(reference: string): Promise<ChargeResult> {
+    try {
+      const res = await fetch(
+        `${this.baseUrl}/transaction/verify/${encodeURIComponent(reference)}`,
+        { method: 'GET', headers: this.headers }
+      );
+      const data = (await res.json()) as any;
+      if (!res.ok || !data.status) {
+        return {
+          success: false,
+          reference,
+          amountKobo: 0,
+          error: data.message ?? 'Verification failed',
+        };
+      }
+      return {
+        success: data.data?.status === 'success',
+        reference,
+        amountKobo: data.data?.amount ?? 0,
+        error: data.data?.status !== 'success' ? data.data?.gateway_response : undefined,
+      };
+    } catch (err: any) {
+      return { success: false, reference, amountKobo: 0, error: err?.message };
+    }
+  }
+
+  async initiateRefund(reference: string, amountKobo?: number): Promise<RefundResult> {
+    try {
+      const body: Record<string, unknown> = { transaction: reference };
+      if (amountKobo !== undefined) body.amount = amountKobo;
+
+      const res = await fetch(`${this.baseUrl}/refund`, {
+        method: 'POST',
+        headers: this.headers,
+        body: JSON.stringify(body),
+      });
+      const data = (await res.json()) as any;
+      if (!res.ok || !data.status) {
+        return { success: false, refundId: '', error: data.message ?? 'Refund failed' };
+      }
+      return { success: true, refundId: String(data.data?.id ?? '') };
+    } catch (err: any) {
+      return { success: false, refundId: '', error: err?.message };
+    }
+  }
+
+  async initiateSplit(
+    totalKobo: number,
+    recipients: SplitRecipient[],
+    reference: string
+  ): Promise<ChargeResult> {
+    const subaccounts = recipients.map((r) => ({
+      subaccount: r.subaccountCode,
+      amount: r.amountKobo,
+    }));
+
+    try {
+      const res = await fetch(`${this.baseUrl}/transaction/initialize`, {
+        method: 'POST',
+        headers: this.headers,
+        body: JSON.stringify({
+          amount: totalKobo,
+          reference,
+          split: { type: 'flat', subaccounts },
+        }),
+      });
+      const data = (await res.json()) as any;
+      if (!res.ok || !data.status) {
+        return {
+          success: false,
+          reference,
+          amountKobo: totalKobo,
+          error: data.message ?? 'Split initiation failed',
+        };
+      }
+      return { success: true, reference, amountKobo: totalKobo };
+    } catch (err: any) {
+      return { success: false, reference, amountKobo: totalKobo, error: err?.message };
+    }
+  }
+
+  async initiateTransfer(
+    recipientCode: string,
+    amountKobo: number,
+    reference: string
+  ): Promise<{ success: boolean; transferCode: string; error?: string }> {
+    try {
+      const res = await fetch(`${this.baseUrl}/transfer`, {
+        method: 'POST',
+        headers: this.headers,
+        body: JSON.stringify({
+          source: 'balance',
+          amount: amountKobo,
+          recipient: recipientCode,
+          reference,
+        }),
+      });
+      const data = (await res.json()) as any;
+      if (!res.ok || !data.status) {
+        return {
+          success: false,
+          transferCode: '',
+          error: data.message ?? 'Transfer failed',
+        };
+      }
+      return { success: true, transferCode: data.data?.transfer_code ?? '' };
+    } catch (err: any) {
+      return { success: false, transferCode: '', error: err?.message };
+    }
+  }
+}
+
+export function createPaymentProvider(secretKey: string): IPaymentProvider {
+  return new PaystackProvider(secretKey);
+}

package/src/pin.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from 'vitest';
+import { hashPin, verifyPin } from './pin';
+
+describe('hashPin', () => {
+  it('returns a hash and a salt', async () => {
+    const result = await hashPin('1234');
+    expect(result).toHaveProperty('hash');
+    expect(result).toHaveProperty('salt');
+    expect(typeof result.hash).toBe('string');
+    expect(typeof result.salt).toBe('string');
+    expect(result.hash.length).toBeGreaterThan(0);
+    expect(result.salt.length).toBeGreaterThan(0);
+  });
+
+  it('produces a deterministic hash when salt is provided', async () => {
+    const salt = 'fixed-salt-for-test';
+    const result1 = await hashPin('5678', salt);
+    const result2 = await hashPin('5678', salt);
+    expect(result1.hash).toBe(result2.hash);
+    expect(result1.salt).toBe(salt);
+  });
+
+  it('produces different hashes for different PINs with the same salt', async () => {
+    const salt = 'same-salt';
+    const r1 = await hashPin('1111', salt);
+    const r2 = await hashPin('2222', salt);
+    expect(r1.hash).not.toBe(r2.hash);
+  });
+
+  it('generates a random salt when none is provided', async () => {
+    const r1 = await hashPin('9999');
+    const r2 = await hashPin('9999');
+    // Different salts → different hashes
+    expect(r1.salt).not.toBe(r2.salt);
+    expect(r1.hash).not.toBe(r2.hash);
+  });
+});
+
+describe('verifyPin', () => {
+  it('returns true for a correct PIN', async () => {
+    const { hash, salt } = await hashPin('4321');
+    const valid = await verifyPin('4321', hash, salt);
+    expect(valid).toBe(true);
+  });
+
+  it('returns false for an incorrect PIN', async () => {
+    const { hash, salt } = await hashPin('4321');
+    const valid = await verifyPin('9999', hash, salt);
+    expect(valid).toBe(false);
+  });
+
+  it('returns false when salt is wrong', async () => {
+    const { hash } = await hashPin('1234', 'correct-salt');
+    const valid = await verifyPin('1234', hash, 'wrong-salt');
+    expect(valid).toBe(false);
+  });
+});

package/src/pin.ts

@@ -0,0 +1,38 @@
+export async function hashPin(
+  pin: string,
+  salt?: string
+): Promise<{ hash: string; salt: string }> {
+  const usedSalt = salt ?? crypto.randomUUID();
+  const enc = new TextEncoder();
+
+  const keyMaterial = await crypto.subtle.importKey(
+    'raw',
+    enc.encode(pin),
+    'PBKDF2',
+    false,
+    ['deriveBits']
+  );
+
+  const bits = await crypto.subtle.deriveBits(
+    {
+      name: 'PBKDF2',
+      salt: enc.encode(usedSalt),
+      iterations: 100_000,
+      hash: 'SHA-256',
+    },
+    keyMaterial,
+    256
+  );
+
+  const hash = btoa(String.fromCharCode(...new Uint8Array(bits)));
+  return { hash, salt: usedSalt };
+}
+
+export async function verifyPin(
+  pin: string,
+  storedHash: string,
+  salt: string
+): Promise<boolean> {
+  const { hash } = await hashPin(pin, salt);
+  return hash === storedHash;
+}

package/src/query-helpers.test.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect } from 'vitest';
+import { parsePagination, metaResponse, applyTenantScope } from './query-helpers';
+
+describe('parsePagination', () => {
+  it('returns default limit and offset when no params provided', () => {
+    const result = parsePagination({});
+    expect(result.limit).toBe(20);
+    expect(result.offset).toBe(0);
+  });
+
+  it('parses valid limit and offset', () => {
+    const result = parsePagination({ limit: '50', offset: '100' });
+    expect(result.limit).toBe(50);
+    expect(result.offset).toBe(100);
+  });
+
+  it('clamps limit to maxLimit', () => {
+    const result = parsePagination({ limit: '500' }, 100);
+    expect(result.limit).toBe(100);
+  });
+
+  it('clamps limit to minimum of 1 for non-zero invalid values', () => {
+    // parseInt('0') = 0, which is falsy, so || 20 kicks in → 20
+    // The minimum-1 clamp applies to values like parseInt('-5') = -5 → max(-5,1) = 1
+    const result = parsePagination({ limit: '-5' });
+    expect(result.limit).toBe(1);
+  });
+
+  it('clamps offset to minimum of 0', () => {
+    const result = parsePagination({ offset: '-5' });
+    expect(result.offset).toBe(0);
+  });
+
+  it('handles non-numeric values gracefully', () => {
+    const result = parsePagination({ limit: 'abc', offset: 'xyz' });
+    expect(result.limit).toBe(20);
+    expect(result.offset).toBe(0);
+  });
+});
+
+describe('metaResponse', () => {
+  it('returns data and correct meta fields', () => {
+    const data = [{ id: 1 }, { id: 2 }];
+    const result = metaResponse(data, 50, 20, 0);
+    expect(result.data).toEqual(data);
+    expect(result.meta.total).toBe(50);
+    expect(result.meta.limit).toBe(20);
+    expect(result.meta.offset).toBe(0);
+    expect(result.meta.has_more).toBe(true);
+  });
+
+  it('sets has_more to false when on last page', () => {
+    const result = metaResponse([], 20, 20, 0);
+    expect(result.meta.has_more).toBe(false);
+  });
+
+  it('sets has_more to false when offset + limit >= total', () => {
+    const result = metaResponse([], 25, 10, 20);
+    expect(result.meta.has_more).toBe(false);
+  });
+
+  it('sets has_more to true when more pages exist', () => {
+    const result = metaResponse([], 100, 10, 10);
+    expect(result.meta.has_more).toBe(true);
+  });
+});
+
+describe('applyTenantScope', () => {
+  it('appends WHERE clause when no WHERE exists', () => {
+    const { query, params } = applyTenantScope(
+      'SELECT * FROM orders',
+      [],
+      'tenant-1'
+    );
+    expect(query).toContain('WHERE operator_id = ?');
+    expect(params).toContain('tenant-1');
+  });
+
+  it('appends AND clause when WHERE already exists', () => {
+    const { query, params } = applyTenantScope(
+      'SELECT * FROM orders WHERE status = ?',
+      ['active'],
+      'tenant-2'
+    );
+    expect(query).toContain('AND operator_id = ?');
+    expect(params).toEqual(['active', 'tenant-2']);
+  });
+
+  it('uses custom column name when provided', () => {
+    const { query } = applyTenantScope(
+      'SELECT * FROM items',
+      [],
+      'tenant-3',
+      'tenant_id'
+    );
+    expect(query).toContain('WHERE tenant_id = ?');
+  });
+});

package/src/query-helpers.ts

@@ -0,0 +1,36 @@
+export function parsePagination(
+  q: Record<string, string>,
+  maxLimit = 100
+): { limit: number; offset: number } {
+  const limit = Math.min(Math.max(parseInt(q.limit ?? '20', 10) || 20, 1), maxLimit);
+  const offset = Math.max(parseInt(q.offset ?? '0', 10) || 0, 0);
+  return { limit, offset };
+}
+
+export function metaResponse<T>(
+  data: T[],
+  total: number,
+  limit: number,
+  offset: number
+) {
+  return {
+    data,
+    meta: {
+      total,
+      limit,
+      offset,
+      has_more: offset + limit < total,
+    },
+  };
+}
+
+export function applyTenantScope(
+  baseQuery: string,
+  params: unknown[],
+  tenantId: string,
+  column = 'operator_id'
+): { query: string; params: unknown[] } {
+  const hasWhere = /\bWHERE\b/i.test(baseQuery);
+  const clause = hasWhere ? ` AND ${column} = ?` : ` WHERE ${column} = ?`;
+  return { query: baseQuery + clause, params: [...params, tenantId] };
+}