@webwaka/core 1.3.0

package/dist/core/auth/index.js

@@ -0,0 +1,369 @@
+/**
+ * @webwaka/core — Auth Module
+ * Blueprint Reference: Part 9.2 (Universal Architecture Standards — Auth & Authorization)
+ *
+ * Canonical authentication primitives for all WebWaka OS v4 Cloudflare Workers.
+ *
+ * Invariants enforced:
+ *  - Build Once Use Infinitely: single implementation, all suites import from here.
+ *  - tenantId ALWAYS sourced from validated JWT payload, NEVER from request headers.
+ *  - CORS NEVER uses wildcard `origin: '*'` in production.
+ *  - All auth/mutation endpoints MUST apply rateLimit middleware.
+ *
+ * Exports:
+ *  - signJWT()           — Issue a signed HS256 JWT (used by super-admin-v2 login)
+ *  - verifyJWT()         — Verify & decode an HS256 JWT (used by all suites)
+ *  - jwtAuthMiddleware() — Hono middleware: verify token, inject user into context
+ *  - requireRole()       — Hono middleware factory: enforce RBAC after jwtAuthMiddleware
+ *  - secureCORS()        — Hono CORS middleware with environment-aware origin allowlist
+ *  - rateLimit()         — Hono middleware: KV-backed sliding-window rate limiter
+ *  - AuthUser            — Canonical user session type
+ *  - JWTPayload          — Canonical JWT payload type
+ */
+import { cors } from 'hono/cors';
+import { logger } from '../logger/index.js';
+// ─── JWT Utilities ────────────────────────────────────────────────────────────
+/**
+ * Encodes a string as a URL-safe Base64 string (no padding).
+ * Uses TextEncoder so any Unicode content (accented chars, CJK, Arabic, etc.)
+ * is first converted to UTF-8 bytes before btoa — avoiding InvalidCharacterError.
+ */
+function toBase64Url(str) {
+    const bytes = new TextEncoder().encode(str);
+    let binary = '';
+    for (const byte of bytes) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary).replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
+}
+/**
+ * Decodes a URL-safe Base64 string back to its original UTF-8 string.
+ * Inverse of toBase64Url — required for verifying payloads that contain Unicode.
+ */
+function fromBase64Url(b64url) {
+    const padded = b64url.replace(/-/g, '+').replace(/_/g, '/');
+    const binary = atob(padded);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return new TextDecoder().decode(bytes);
+}
+/**
+ * Sign a new HS256 JWT using the Web Crypto API (Cloudflare Workers compatible).
+ * Returns a compact `header.payload.signature` string.
+ */
+export async function signJWT(payload, secret, expiresInSeconds = 86400) {
+    const now = Math.floor(Date.now() / 1000);
+    const fullPayload = {
+        ...payload,
+        iat: now,
+        exp: now + expiresInSeconds,
+    };
+    const header = { alg: 'HS256', typ: 'JWT' };
+    // Header is always ASCII — btoa is fine; payload uses Unicode-safe toBase64Url
+    const headerB64 = btoa(JSON.stringify(header))
+        .replace(/=/g, '')
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_');
+    const payloadB64 = toBase64Url(JSON.stringify(fullPayload));
+    const encoder = new TextEncoder();
+    const keyData = encoder.encode(secret);
+    const key = await crypto.subtle.importKey('raw', keyData, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const data = encoder.encode(`${headerB64}.${payloadB64}`);
+    const signatureBuffer = await crypto.subtle.sign('HMAC', key, data);
+    const signatureB64 = btoa(String.fromCharCode(...new Uint8Array(signatureBuffer)))
+        .replace(/=/g, '')
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_');
+    return `${headerB64}.${payloadB64}.${signatureB64}`;
+}
+/**
+ * Verify an HS256 JWT and return its decoded payload.
+ * Returns null if the token is invalid, expired, or tampered with.
+ * Uses the Web Crypto API — safe for Cloudflare Workers edge runtime.
+ */
+export async function verifyJWT(token, secret) {
+    try {
+        const parts = token.split('.');
+        if (parts.length !== 3)
+            return null;
+        const [headerB64, payloadB64, signatureB64] = parts;
+        const encoder = new TextEncoder();
+        const keyData = encoder.encode(secret);
+        const key = await crypto.subtle.importKey('raw', keyData, { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
+        const data = encoder.encode(`${headerB64}.${payloadB64}`);
+        const signature = Uint8Array.from(atob(signatureB64.replace(/-/g, '+').replace(/_/g, '/')), (c) => c.charCodeAt(0));
+        const valid = await crypto.subtle.verify('HMAC', key, signature, data);
+        if (!valid)
+            return null;
+        const payload = JSON.parse(fromBase64Url(payloadB64));
+        // Reject expired tokens
+        if (payload.exp < Math.floor(Date.now() / 1000))
+            return null;
+        return payload;
+    }
+    catch {
+        return null;
+    }
+}
+// ─── API Key Authentication ───────────────────────────────────────────────────
+/**
+ * Verifies an API key by hashing it with SHA-256 and looking it up in the
+ * api_keys table. Returns a WakaUser on success or null if the key is invalid.
+ * Compatible with Cloudflare Workers (Web Crypto API only).
+ */
+export async function verifyApiKey(rawKey, db) {
+    const encoder = new TextEncoder();
+    const data = encoder.encode(rawKey);
+    const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+    const hashArray = Array.from(new Uint8Array(hashBuffer));
+    const keyHash = hashArray.map((b) => b.toString(16).padStart(2, '0')).join('');
+    const row = await db
+        .prepare(`SELECT ak.*, o.name as operator_name FROM api_keys ak
+       JOIN operators o ON o.id = ak.operator_id
+       WHERE ak.key_hash = ? AND ak.revoked_at IS NULL AND ak.deleted_at IS NULL`)
+        .bind(keyHash)
+        .first();
+    if (!row)
+        return null;
+    // Non-blocking: update last_used_at
+    db.prepare(`UPDATE api_keys SET last_used_at = ? WHERE id = ?`)
+        .bind(Date.now(), row.id)
+        .run()
+        .catch(() => { });
+    return {
+        id: row.id,
+        tenant_id: row.operator_id,
+        role: row.scope === 'read_write' ? 'TENANT_ADMIN' : 'STAFF',
+        name: `api_key:${row.id}`,
+        phone: '',
+        operator_id: row.operator_id,
+    };
+}
+/**
+ * Hono middleware that verifies the Bearer JWT, rejects invalid/expired tokens,
+ * and injects the canonical `AuthUser` into the Hono context as `c.get('user')`.
+ *
+ * Also sets `c.get('tenantId')` from the JWT payload — NEVER from headers.
+ *
+ * Usage:
+ *   app.use('/api/*', jwtAuthMiddleware({ publicRoutes: [{ path: '/health' }] }));
+ */
+export function jwtAuthMiddleware(options = {}) {
+    const { publicRoutes = [] } = options;
+    return async (c, next) => {
+        const method = c.req.method;
+        const path = c.req.path;
+        // Allow public routes through without auth
+        const isPublic = publicRoutes.some((r) => path.startsWith(r.path) && (!r.method || r.method === '*' || r.method === method));
+        if (isPublic)
+            return next();
+        const authHeader = c.req.header('Authorization') ?? '';
+        // ── API Key auth (B2B / third-party systems) ──────────────────────────────
+        if (authHeader.startsWith('ApiKey ')) {
+            const rawKey = authHeader.slice(7).trim();
+            const db = c.env.DB;
+            if (!db) {
+                return c.json({ success: false, error: 'Unauthorized: DB binding not configured' }, 401);
+            }
+            const wakaUser = await verifyApiKey(rawKey, db);
+            if (!wakaUser) {
+                return c.json({ error: 'Invalid API key' }, 401);
+            }
+            c.set('user', wakaUser);
+            c.set('tenantId', wakaUser.operator_id);
+            return next();
+        }
+        // ── JWT Bearer auth ───────────────────────────────────────────────────────
+        if (!authHeader.startsWith('Bearer ')) {
+            return c.json({ success: false, error: 'Unauthorized: missing or malformed Authorization header' }, 401);
+        }
+        const token = authHeader.slice(7).trim();
+        if (!token) {
+            return c.json({ success: false, error: 'Unauthorized: empty token' }, 401);
+        }
+        const payload = await verifyJWT(token, c.env.JWT_SECRET);
+        if (!payload) {
+            return c.json({ success: false, error: 'Unauthorized: invalid or expired token' }, 401);
+        }
+        const user = {
+            userId: payload.sub,
+            email: payload.email,
+            role: payload.role,
+            tenantId: payload.tenantId,
+            permissions: payload.permissions ?? [],
+        };
+        // Inject into Hono context — downstream handlers use c.get('user') and c.get('tenantId')
+        c.set('user', user);
+        c.set('tenantId', payload.tenantId);
+        return next();
+    };
+}
+// ─── Hono Middleware: RBAC ────────────────────────────────────────────────────
+/**
+ * Hono middleware factory that enforces role-based access control.
+ * MUST be used AFTER jwtAuthMiddleware on the same route.
+ *
+ * Usage:
+ *   app.post('/api/admin/tenants', requireRole(['SUPER_ADMIN', 'TENANT_ADMIN']), handler);
+ */
+export function requireRole(allowedRoles) {
+    return async (c, next) => {
+        const user = c.get('user');
+        if (!user) {
+            return c.json({ success: false, error: 'Unauthorized: no authenticated user' }, 401);
+        }
+        if (!allowedRoles.includes(user.role)) {
+            return c.json({
+                success: false,
+                error: `Forbidden: requires one of [${allowedRoles.join(', ')}]`,
+            }, 403);
+        }
+        return next();
+    };
+}
+/**
+ * Hono middleware factory that enforces permission-based access control.
+ * SUPER_ADMIN role bypasses all permission checks.
+ * MUST be used AFTER jwtAuthMiddleware.
+ *
+ * Usage:
+ *   app.delete('/api/tenants/:id', requirePermissions(['delete:tenants']), handler);
+ */
+export function requirePermissions(requiredPermissions) {
+    return async (c, next) => {
+        const user = c.get('user');
+        if (!user) {
+            return c.json({ success: false, error: 'Unauthorized: no authenticated user' }, 401);
+        }
+        if (user.role === 'SUPER_ADMIN')
+            return next();
+        const hasAll = requiredPermissions.every((p) => user.permissions.includes(p));
+        if (!hasAll) {
+            return c.json({
+                success: false,
+                error: `Forbidden: missing required permissions [${requiredPermissions.join(', ')}]`,
+            }, 403);
+        }
+        return next();
+    };
+}
+/**
+ * Environment-aware CORS middleware.
+ * - Production: restricts to an explicit allowlist of WebWaka domains.
+ * - Non-production (staging/dev/local): allows all origins for developer convenience.
+ *
+ * NEVER uses `origin: '*'` in production.
+ *
+ * Usage:
+ *   app.use('*', secureCORS());
+ *   app.use('*', secureCORS({ allowedOrigins: ['https://app.mywebwaka.com'] }));
+ */
+export function secureCORS(options = {}) {
+    const defaultProductionOrigins = [
+        'https://webwaka.com',
+        'https://app.webwaka.com',
+        'https://admin.webwaka.com',
+        'https://webwaka-super-admin.pages.dev',
+    ];
+    const allowedOrigins = options.allowedOrigins ?? defaultProductionOrigins;
+    return cors({
+        origin: (origin, c) => {
+            const env = c.env.ENVIRONMENT ?? 'production';
+            const isProd = env === 'production';
+            if (!isProd) {
+                // Allow all origins in non-production environments
+                return origin;
+            }
+            // In production: only allow explicitly listed origins
+            if (allowedOrigins.includes(origin))
+                return origin;
+            // Block all other origins in production
+            return null;
+        },
+        allowMethods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
+        allowHeaders: ['Content-Type', 'Authorization', 'X-Request-ID'],
+        exposeHeaders: ['X-Request-ID'],
+        maxAge: 86400,
+        credentials: true,
+    });
+}
+/**
+ * KV-backed sliding-window rate limiter for Cloudflare Workers.
+ * Requires a `RATE_LIMIT_KV` KV namespace binding.
+ *
+ * Usage (auth endpoints — strict):
+ *   app.post('/auth/login', rateLimit({ limit: 10, windowSeconds: 60, keyPrefix: 'login' }), handler);
+ *
+ * Usage (general API):
+ *   app.use('/api/*', rateLimit({ limit: 300, windowSeconds: 60 }));
+ */
+export function rateLimit(options = {}) {
+    const { limit = 60, windowSeconds = 60, keyPrefix = 'rl', keyExtractor, } = options;
+    return async (c, next) => {
+        const kv = c.env.RATE_LIMIT_KV;
+        if (!kv) {
+            // If KV is not configured, fail open (do not block) but log a warning
+            logger.warn('[rateLimit] RATE_LIMIT_KV binding not configured — rate limiting disabled');
+            return next();
+        }
+        const clientKey = keyExtractor
+            ? keyExtractor(c)
+            : (c.req.header('CF-Connecting-IP') ?? c.req.header('X-Forwarded-For') ?? 'unknown');
+        const windowStart = Math.floor(Date.now() / 1000 / windowSeconds);
+        const kvKey = `${keyPrefix}:${clientKey}:${windowStart}`;
+        let count = 0;
+        try {
+            const existing = await kv.get(kvKey);
+            count = existing ? parseInt(existing, 10) : 0;
+        }
+        catch {
+            // Fail open on KV errors
+            return next();
+        }
+        if (count >= limit) {
+            return c.json({
+                success: false,
+                error: `Rate limit exceeded. Maximum ${limit} requests per ${windowSeconds}s.`,
+            }, 429);
+        }
+        // Increment counter; set TTL to expire at end of window
+        try {
+            await kv.put(kvKey, String(count + 1), { expirationTtl: windowSeconds * 2 });
+        }
+        catch {
+            // Fail open on KV write errors
+        }
+        // Attach rate limit headers
+        c.header('X-RateLimit-Limit', String(limit));
+        c.header('X-RateLimit-Remaining', String(Math.max(0, limit - count - 1)));
+        c.header('X-RateLimit-Reset', String((windowStart + 1) * windowSeconds));
+        return next();
+    };
+}
+// ─── Tenant Utilities ─────────────────────────────────────────────────────────
+/**
+ * Safely extract tenantId from the Hono context.
+ * Throws if tenantId is not present (i.e., jwtAuthMiddleware was not applied).
+ * Use this in route handlers to enforce that tenant context is always present.
+ */
+export function getTenantId(c) {
+    const tenantId = c.get('tenantId');
+    if (!tenantId) {
+        throw new Error('getTenantId() called without jwtAuthMiddleware — tenantId not in context');
+    }
+    return tenantId;
+}
+/**
+ * Safely extract the authenticated user from the Hono context.
+ * Throws if user is not present.
+ */
+export function getAuthUser(c) {
+    const user = c.get('user');
+    if (!user) {
+        throw new Error('getAuthUser() called without jwtAuthMiddleware — user not in context');
+    }
+    return user;
+}
+//# sourceMappingURL=index.js.map

package/dist/core/auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/auth/index.ts"],"names":[],"mappings":"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"}

package/dist/core/billing/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * CORE-8: Platform Billing & Usage Ledger
+ * Blueprint Reference: Part 10.1 (Central Management & Economics)
+ * Blueprint Reference: Part 9.1 #6 (Africa First - Integer Kobo Values)
+ *
+ * Implements internal ledger for tracking tenant API/AI usage and credits.
+ */
+export declare enum LedgerEntryType {
+    CREDIT = "CREDIT",
+    DEBIT = "DEBIT"
+}
+export declare enum UsageCategory {
+    AI_TOKENS = "AI_TOKENS",
+    SMS_SENT = "SMS_SENT",
+    EMAIL_SENT = "EMAIL_SENT",
+    SUBSCRIPTION_FEE = "SUBSCRIPTION_FEE",
+    SUBSCRIPTION_CREDIT = "SUBSCRIPTION_CREDIT"
+}
+export interface LedgerEntry {
+    id: string;
+    tenantId: string;
+    type: LedgerEntryType;
+    category: UsageCategory;
+    amountKobo: number;
+    description: string;
+    metadata?: Record<string, any>;
+    createdAt: Date;
+    deletedAt?: Date;
+}
+export declare class BillingLedger {
+    private db;
+    constructor(db: any);
+    /**
+     * Records a usage debit for a tenant.
+     */
+    recordUsage(tenantId: string, category: UsageCategory, amountKobo: number, description: string, metadata?: Record<string, any>): Promise<LedgerEntry>;
+    /**
+     * Records a credit for a tenant (wallet top-up, refund, promotional credit,
+     * or subscription payment).
+     */
+    recordCredit(tenantId: string, category: UsageCategory, amountKobo: number, description: string, metadata?: Record<string, any>): Promise<LedgerEntry>;
+    /**
+     * Calculates the current balance for a tenant.
+     *
+     * @stub This implementation always returns 0. Real balance calculation
+     * requires D1 database wiring (separate task). Any caller that gates
+     * actions on this value will silently allow unlimited usage until
+     * D1 integration is complete.
+     */
+    getTenantBalance(tenantId: string): Promise<number>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/core/billing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/billing/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,oBAAY,eAAe;IACzB,MAAM,WAAW;IACjB,KAAK,UAAU;CAChB;AAED,oBAAY,aAAa;IACvB,SAAS,cAAc;IACvB,QAAQ,aAAa;IACrB,UAAU,eAAe;IACzB,gBAAgB,qBAAqB;IACrC,mBAAmB,wBAAwB;CAC5C;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,eAAe,CAAC;IACtB,QAAQ,EAAE,aAAa,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC/B,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,CAAC,EAAE,IAAI,CAAC;CAClB;AASD,qBAAa,aAAa;IACxB,OAAO,CAAC,EAAE,CAAM;gBAEJ,EAAE,EAAE,GAAG;IAInB;;OAEG;IACG,WAAW,CACf,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,aAAa,EACvB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC7B,OAAO,CAAC,WAAW,CAAC;IAoBvB;;;OAGG;IACG,YAAY,CAChB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,aAAa,EACvB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC7B,OAAO,CAAC,WAAW,CAAC;IAoBvB;;;;;;;OAOG;IACG,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAe1D"}

package/dist/core/billing/index.js

@@ -0,0 +1,91 @@
+/**
+ * CORE-8: Platform Billing & Usage Ledger
+ * Blueprint Reference: Part 10.1 (Central Management & Economics)
+ * Blueprint Reference: Part 9.1 #6 (Africa First - Integer Kobo Values)
+ *
+ * Implements internal ledger for tracking tenant API/AI usage and credits.
+ */
+import { logger } from '../logger';
+export var LedgerEntryType;
+(function (LedgerEntryType) {
+    LedgerEntryType["CREDIT"] = "CREDIT";
+    LedgerEntryType["DEBIT"] = "DEBIT";
+})(LedgerEntryType || (LedgerEntryType = {}));
+export var UsageCategory;
+(function (UsageCategory) {
+    UsageCategory["AI_TOKENS"] = "AI_TOKENS";
+    UsageCategory["SMS_SENT"] = "SMS_SENT";
+    UsageCategory["EMAIL_SENT"] = "EMAIL_SENT";
+    UsageCategory["SUBSCRIPTION_FEE"] = "SUBSCRIPTION_FEE";
+    UsageCategory["SUBSCRIPTION_CREDIT"] = "SUBSCRIPTION_CREDIT";
+})(UsageCategory || (UsageCategory = {}));
+/** Shared kobo validation used by both debit and credit paths. */
+function validateKobo(amountKobo) {
+    if (!Number.isInteger(amountKobo) || amountKobo < 0) {
+        throw new Error('Amount must be a positive integer in kobo');
+    }
+}
+export class BillingLedger {
+    db; // Type would be D1Database from @cloudflare/workers-types
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Records a usage debit for a tenant.
+     */
+    async recordUsage(tenantId, category, amountKobo, description, metadata) {
+        validateKobo(amountKobo);
+        const entry = {
+            id: crypto.randomUUID(),
+            tenantId,
+            type: LedgerEntryType.DEBIT,
+            category,
+            amountKobo,
+            description,
+            ...(metadata !== undefined ? { metadata } : {}),
+            createdAt: new Date(),
+        };
+        // In a real implementation, this would insert into D1:
+        // await this.db.prepare('INSERT INTO ledger_entries ...').bind(...).run();
+        return entry;
+    }
+    /**
+     * Records a credit for a tenant (wallet top-up, refund, promotional credit,
+     * or subscription payment).
+     */
+    async recordCredit(tenantId, category, amountKobo, description, metadata) {
+        validateKobo(amountKobo);
+        const entry = {
+            id: crypto.randomUUID(),
+            tenantId,
+            type: LedgerEntryType.CREDIT,
+            category,
+            amountKobo,
+            description,
+            ...(metadata !== undefined ? { metadata } : {}),
+            createdAt: new Date(),
+        };
+        // In a real implementation, this would insert into D1:
+        // await this.db.prepare('INSERT INTO ledger_entries ...').bind(...).run();
+        return entry;
+    }
+    /**
+     * Calculates the current balance for a tenant.
+     *
+     * @stub This implementation always returns 0. Real balance calculation
+     * requires D1 database wiring (separate task). Any caller that gates
+     * actions on this value will silently allow unlimited usage until
+     * D1 integration is complete.
+     */
+    async getTenantBalance(tenantId) {
+        logger.warn('getTenantBalance is a stub and always returns 0. D1 integration is required for real balance calculation.', { tenantId });
+        // Real implementation:
+        // const result = await this.db.prepare(
+        //   'SELECT SUM(CASE WHEN type = "CREDIT" THEN amountKobo ELSE -amountKobo END) as balance ' +
+        //   'FROM ledger_entries WHERE tenantId = ? AND deletedAt IS NULL'
+        // ).bind(tenantId).first();
+        // return result.balance ?? 0;
+        return 0;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/core/billing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/billing/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAEnC,MAAM,CAAN,IAAY,eAGX;AAHD,WAAY,eAAe;IACzB,oCAAiB,CAAA;IACjB,kCAAe,CAAA;AACjB,CAAC,EAHW,eAAe,KAAf,eAAe,QAG1B;AAED,MAAM,CAAN,IAAY,aAMX;AAND,WAAY,aAAa;IACvB,wCAAuB,CAAA;IACvB,sCAAqB,CAAA;IACrB,0CAAyB,CAAA;IACzB,sDAAqC,CAAA;IACrC,4DAA2C,CAAA;AAC7C,CAAC,EANW,aAAa,KAAb,aAAa,QAMxB;AAcD,kEAAkE;AAClE,SAAS,YAAY,CAAC,UAAkB;IACtC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/D,CAAC;AACH,CAAC;AAED,MAAM,OAAO,aAAa;IAChB,EAAE,CAAM,CAAC,0DAA0D;IAE3E,YAAY,EAAO;QACjB,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;IACf,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,WAAW,CACf,QAAgB,EAChB,QAAuB,EACvB,UAAkB,EAClB,WAAmB,EACnB,QAA8B;QAE9B,YAAY,CAAC,UAAU,CAAC,CAAC;QAEzB,MAAM,KAAK,GAAgB;YACzB,EAAE,EAAE,MAAM,CAAC,UAAU,EAAE;YACvB,QAAQ;YACR,IAAI,EAAE,eAAe,CAAC,KAAK;YAC3B,QAAQ;YACR,UAAU;YACV,WAAW;YACX,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/C,SAAS,EAAE,IAAI,IAAI,EAAE;SACtB,CAAC;QAEF,uDAAuD;QACvD,2EAA2E;QAE3E,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,YAAY,CAChB,QAAgB,EAChB,QAAuB,EACvB,UAAkB,EAClB,WAAmB,EACnB,QAA8B;QAE9B,YAAY,CAAC,UAAU,CAAC,CAAC;QAEzB,MAAM,KAAK,GAAgB;YACzB,EAAE,EAAE,MAAM,CAAC,UAAU,EAAE;YACvB,QAAQ;YACR,IAAI,EAAE,eAAe,CAAC,MAAM;YAC5B,QAAQ;YACR,UAAU;YACV,WAAW;YACX,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/C,SAAS,EAAE,IAAI,IAAI,EAAE;SACtB,CAAC;QAEF,uDAAuD;QACvD,2EAA2E;QAE3E,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,gBAAgB,CAAC,QAAgB;QACrC,MAAM,CAAC,IAAI,CACT,2GAA2G,EAC3G,EAAE,QAAQ,EAAE,CACb,CAAC;QAEF,uBAAuB;QACvB,wCAAwC;QACxC,+FAA+F;QAC/F,mEAAmE;QACnE,4BAA4B;QAC5B,8BAA8B;QAE9B,OAAO,CAAC,CAAC;IACX,CAAC;CACF"}

package/dist/core/booking/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * CORE-10: Universal Booking & Scheduling Engine
+ * Blueprint Reference: Part 10.3 (Transport), Part 10.7 (Health)
+ *
+ * Unified system for managing time slots, availability, and reservations.
+ *
+ * Tenant Isolation: every mutating and querying method requires a tenantId.
+ * All data is scoped per tenant — cross-tenant leakage is impossible by construction.
+ */
+export interface TimeSlot {
+    startTime: Date;
+    endTime: Date;
+}
+export interface Booking {
+    id: string;
+    tenantId: string;
+    resourceId: string;
+    userId: string;
+    slot: TimeSlot;
+    status: 'pending' | 'confirmed' | 'cancelled';
+}
+export declare class BookingEngine {
+    private bookings;
+    /**
+     * Checks if a resource is available for a given time slot within a tenant.
+     */
+    isAvailable(tenantId: string, resourceId: string, requestedSlot: TimeSlot): boolean;
+    /**
+     * Creates a new booking if the resource is available within the tenant.
+     */
+    createBooking(tenantId: string, resourceId: string, userId: string, slot: TimeSlot): Booking;
+    /**
+     * Cancels an existing booking, scoped to the tenant.
+     * Returns false if the booking does not exist within the tenant.
+     */
+    cancelBooking(tenantId: string, bookingId: string): boolean;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/core/booking/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/booking/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,EAAE,IAAI,CAAC;CACf;AAED,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,WAAW,CAAC;CAC/C;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAiB;IAEjC;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,QAAQ,GAAG,OAAO;IAmBnF;;OAEG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO;IAqB5F;;;OAGG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;CAa5D"}

package/dist/core/booking/index.js

@@ -0,0 +1,60 @@
+/**
+ * CORE-10: Universal Booking & Scheduling Engine
+ * Blueprint Reference: Part 10.3 (Transport), Part 10.7 (Health)
+ *
+ * Unified system for managing time slots, availability, and reservations.
+ *
+ * Tenant Isolation: every mutating and querying method requires a tenantId.
+ * All data is scoped per tenant — cross-tenant leakage is impossible by construction.
+ */
+export class BookingEngine {
+    bookings = [];
+    /**
+     * Checks if a resource is available for a given time slot within a tenant.
+     */
+    isAvailable(tenantId, resourceId, requestedSlot) {
+        const resourceBookings = this.bookings.filter(b => b.tenantId === tenantId &&
+            b.resourceId === resourceId &&
+            b.status !== 'cancelled');
+        for (const booking of resourceBookings) {
+            if (requestedSlot.startTime < booking.slot.endTime &&
+                requestedSlot.endTime > booking.slot.startTime) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Creates a new booking if the resource is available within the tenant.
+     */
+    createBooking(tenantId, resourceId, userId, slot) {
+        if (!this.isAvailable(tenantId, resourceId, slot)) {
+            throw new Error('Resource is not available for the requested time slot');
+        }
+        const newBooking = {
+            id: `bk_${crypto.randomUUID()}`,
+            tenantId,
+            resourceId,
+            userId,
+            slot,
+            status: 'confirmed',
+        };
+        this.bookings.push(newBooking);
+        // eventBus.publish(WebWakaEventType.BOOKING_CONFIRMED, createEvent(WebWakaEventType.BOOKING_CONFIRMED, tenantId, newBooking));
+        return newBooking;
+    }
+    /**
+     * Cancels an existing booking, scoped to the tenant.
+     * Returns false if the booking does not exist within the tenant.
+     */
+    cancelBooking(tenantId, bookingId) {
+        const booking = this.bookings.find(b => b.id === bookingId && b.tenantId === tenantId);
+        if (booking) {
+            booking.status = 'cancelled';
+            // eventBus.publish(WebWakaEventType.BOOKING_CANCELLED, createEvent(WebWakaEventType.BOOKING_CANCELLED, tenantId, booking));
+            return true;
+        }
+        return false;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/core/booking/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/booking/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAgBH,MAAM,OAAO,aAAa;IAChB,QAAQ,GAAc,EAAE,CAAC;IAEjC;;OAEG;IACH,WAAW,CAAC,QAAgB,EAAE,UAAkB,EAAE,aAAuB;QACvE,MAAM,gBAAgB,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAChD,CAAC,CAAC,QAAQ,KAAK,QAAQ;YACvB,CAAC,CAAC,UAAU,KAAK,UAAU;YAC3B,CAAC,CAAC,MAAM,KAAK,WAAW,CACzB,CAAC;QAEF,KAAK,MAAM,OAAO,IAAI,gBAAgB,EAAE,CAAC;YACvC,IACE,aAAa,CAAC,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO;gBAC9C,aAAa,CAAC,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,SAAS,EAC9C,CAAC;gBACD,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,aAAa,CAAC,QAAgB,EAAE,UAAkB,EAAE,MAAc,EAAE,IAAc;QAChF,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,CAAC;YAClD,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;QAC3E,CAAC;QAED,MAAM,UAAU,GAAY;YAC1B,EAAE,EAAE,MAAM,MAAM,CAAC,UAAU,EAAE,EAAE;YAC/B,QAAQ;YACR,UAAU;YACV,MAAM;YACN,IAAI;YACJ,MAAM,EAAE,WAAW;SACpB,CAAC;QAEF,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAE/B,+HAA+H;QAE/H,OAAO,UAAU,CAAC;IACpB,CAAC;IAED;;;OAGG;IACH,aAAa,CAAC,QAAgB,EAAE,SAAiB;QAC/C,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAChC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,SAAS,IAAI,CAAC,CAAC,QAAQ,KAAK,QAAQ,CACnD,CAAC;QACF,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,CAAC,MAAM,GAAG,WAAW,CAAC;YAE7B,4HAA4H;YAE5H,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;CACF"}