@braynexservices/nigeria-mcp-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Braynex Services Ltd (Samuel Orie)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,38 @@
+Nigeria MCP — NOTICE (Copyright, Authorship & Ownership)
+========================================================
+
+Copyright © 2026 Braynex Services Ltd. All rights reserved.
+
+Author & Founder:  Samuel Orie
+Company / Owner:    Braynex Services Ltd  (https://www.braynexservices.com)
+Contact:           braynexservices@gmail.com
+
+This repository and the MCP servers, tools, schemas, and supporting code within it
+(collectively, "the Software") are original works authored by Samuel Orie and owned by
+Braynex Services Ltd as company assets. They were independently conceived and built by the
+author; they are not copied from, and are not knowingly derived from, any third party's
+proprietary source code.
+
+Third-party data sources accessed at runtime (e.g. UN Comtrade, open.er-api.com) remain
+the property of their respective providers and are used under their own public terms; this
+notice covers only Braynex Services Ltd' own original code in this repository.
+
+LICENSING
+---------
+This software is released under the **MIT License** (see the LICENSE file at the repository
+root; each package also declares `"license": "MIT"`). Chosen deliberately for broad adoption.
+
+Braynex Services Ltd **retains the copyright** to all original code herein — MIT grants others a
+license to use/modify/redistribute it (with attribution and this notice preserved), but does
+NOT transfer ownership or trademark rights. The "Braynex Services Ltd" brand and product names
+are not licensed for others' use under MIT.
+
+TRADEMARKS
+----------
+"Braynex Services Ltd" and the product names used herein (including
+"Nigeria Trade Intel MCP") are unregistered trademarks / brands of Braynex Services Ltd.
+
+PROVENANCE
+----------
+Authorship and creation dates are evidenced by this repository's git history. This file
+records ownership; it is not a substitute for formal IP registration or legal advice.

package/README.md

@@ -0,0 +1,24 @@
+# `shared/` — `@braynexservices/nigeria-mcp-core`
+
+The shared MCP core consumed by every lane. **No lane logic lives here** — only the reusable spine.
+
+## Will contain (built in v1)
+```
+shared/src/
+├── server.ts        # buildServer(): new McpServer(), accepts tool registrations
+├── stdio.ts         # StdioServerTransport entrypoint (local, no auth)
+├── http.ts          # Express + stateless StreamableHTTPServerTransport + API-key auth + /health
+├── config.ts        # env parsing, provider selection, key list
+├── schemas.ts       # shared Zod base types + Normalized* contracts
+├── providers/types.ts  # CacProvider / BankProvider / FxProvider interfaces (the seam)
+└── lib/
+    ├── normalize.ts # raw → normalized helpers
+    ├── errors.ts    # actionable MCP error helpers
+    └── cache.ts     # in-memory TTL cache (Redis-swappable)
+```
+
+## Design rules
+- The **provider seam** (typed interfaces) is the moat — tools depend on interfaces, never concrete providers. See `brain/04-rules/engineering-rules.md`.
+- Normalized schema stability > provider breadth.
+
+> 🧠 Source of truth: `brain/05-plans/v1-plan.md` and `brain/08-tech-stack/core-stack.md`.

package/dist/config.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Environment configuration for the Nigeria MCP core.
+ * No hardcoded secrets — everything comes from process.env. See brain/04-rules/engineering-rules.md
+ */
+export interface Config {
+    cacProvider: string;
+    bankProvider: string;
+    fxProvider: string;
+    driversProvider: string;
+    electricityProvider: string;
+    credentialProvider: string;
+    tradeProvider: string;
+    apiKeys: string[];
+    port: number;
+    cacheTtlSeconds: number;
+    paystackSecretKey?: string;
+    vtpassApiKey?: string;
+    vtpassPublicKey?: string;
+    vtpassSecretKey?: string;
+    vtpassBaseUrl: string;
+}
+export declare function loadConfig(env?: NodeJS.ProcessEnv): Config;

package/dist/config.js

@@ -0,0 +1,32 @@
+/**
+ * Environment configuration for the Nigeria MCP core.
+ * No hardcoded secrets — everything comes from process.env. See brain/04-rules/engineering-rules.md
+ */
+function num(value, fallback) {
+    const n = Number(value);
+    return Number.isFinite(n) ? n : fallback;
+}
+export function loadConfig(env = process.env) {
+    return {
+        cacProvider: env.CAC_PROVIDER ?? "mock",
+        bankProvider: env.BANK_PROVIDER ?? "mock",
+        fxProvider: env.FX_PROVIDER ?? "mock",
+        driversProvider: env.DRIVERS_PROVIDER ?? "mock",
+        electricityProvider: env.ELECTRICITY_PROVIDER ?? "mock",
+        credentialProvider: env.CREDENTIAL_PROVIDER ?? "mock",
+        tradeProvider: env.TRADE_PROVIDER ?? "mock",
+        apiKeys: (env.API_KEYS ?? "")
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean),
+        port: num(env.PORT, 8787),
+        cacheTtlSeconds: num(env.CACHE_TTL_SECONDS, 300),
+        paystackSecretKey: env.PAYSTACK_SECRET_KEY,
+        vtpassApiKey: env.VTPASS_API_KEY,
+        vtpassPublicKey: env.VTPASS_PUBLIC_KEY,
+        vtpassSecretKey: env.VTPASS_SECRET_KEY,
+        // sandbox by default; set VTPASS_BASE_URL=https://vtpass.com/api + live keys for production
+        vtpassBaseUrl: env.VTPASS_BASE_URL ?? "https://sandbox.vtpass.com/api",
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAoBH,SAAS,GAAG,CAAC,KAAyB,EAAE,QAAgB;IACtD,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IACxB,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC7D,OAAO;QACL,WAAW,EAAE,GAAG,CAAC,YAAY,IAAI,MAAM;QACvC,YAAY,EAAE,GAAG,CAAC,aAAa,IAAI,MAAM;QACzC,UAAU,EAAE,GAAG,CAAC,WAAW,IAAI,MAAM;QACrC,eAAe,EAAE,GAAG,CAAC,gBAAgB,IAAI,MAAM;QAC/C,mBAAmB,EAAE,GAAG,CAAC,oBAAoB,IAAI,MAAM;QACvD,kBAAkB,EAAE,GAAG,CAAC,mBAAmB,IAAI,MAAM;QACrD,aAAa,EAAE,GAAG,CAAC,cAAc,IAAI,MAAM;QAC3C,OAAO,EAAE,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC;aAC1B,KAAK,CAAC,GAAG,CAAC;aACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;aACpB,MAAM,CAAC,OAAO,CAAC;QAClB,IAAI,EAAE,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC;QACzB,eAAe,EAAE,GAAG,CAAC,GAAG,CAAC,iBAAiB,EAAE,GAAG,CAAC;QAChD,iBAAiB,EAAE,GAAG,CAAC,mBAAmB;QAC1C,YAAY,EAAE,GAAG,CAAC,cAAc;QAChC,eAAe,EAAE,GAAG,CAAC,iBAAiB;QACtC,eAAe,EAAE,GAAG,CAAC,iBAAiB;QACtC,4FAA4F;QAC5F,aAAa,EAAE,GAAG,CAAC,eAAe,IAAI,gCAAgC;KACvE,CAAC;AACJ,CAAC"}

package/dist/http.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/http.js

@@ -0,0 +1,44 @@
+/**
+ * Streamable-HTTP entrypoint — stateless, deployable. API-key auth + /health.
+ * Stateless mode (sessionIdGenerator: undefined) is simpler to scale. A fresh server +
+ * transport is created per request. See brain/08-tech-stack/core-stack.md
+ */
+import express from "express";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { loadConfig } from "./config.js";
+import { buildServer, pingTool } from "./server.js";
+const config = loadConfig();
+const app = express();
+app.use(express.json());
+app.get("/health", (_req, res) => {
+    res.json({ status: "ok", service: "nigeria-mcp" });
+});
+function authorized(req) {
+    // No keys configured => open (local dev). Configure API_KEYS to enforce.
+    if (config.apiKeys.length === 0)
+        return true;
+    const fromHeader = req.header("x-api-key");
+    const bearer = req.header("authorization")?.replace(/^Bearer\s+/i, "");
+    const key = fromHeader ?? bearer;
+    return !!key && config.apiKeys.includes(key);
+}
+app.post("/mcp", async (req, res) => {
+    if (!authorized(req)) {
+        res
+            .status(401)
+            .json({ jsonrpc: "2.0", error: { code: -32001, message: "Unauthorized" }, id: null });
+        return;
+    }
+    const server = buildServer([pingTool]);
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+    res.on("close", () => {
+        void transport.close();
+        void server.close();
+    });
+    await server.connect(transport);
+    await transport.handleRequest(req, res, req.body);
+});
+app.listen(config.port, () => {
+    console.error(`[nigeria-mcp] HTTP listening on :${config.port} (auth: ${config.apiKeys.length ? "on" : "off"})`);
+});
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,OAAwC,MAAM,SAAS,CAAC;AAC/D,OAAO,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAC;AACnG,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEpD,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;AAC5B,MAAM,GAAG,GAAG,OAAO,EAAE,CAAC;AACtB,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;AAExB,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,IAAa,EAAE,GAAa,EAAE,EAAE;IAClD,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC,CAAC;AACrD,CAAC,CAAC,CAAC;AAEH,SAAS,UAAU,CAAC,GAAY;IAC9B,yEAAyE;IACzE,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7C,MAAM,UAAU,GAAG,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAC3C,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;IACvE,MAAM,GAAG,GAAG,UAAU,IAAI,MAAM,CAAC;IACjC,OAAO,CAAC,CAAC,GAAG,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;AAC/C,CAAC;AAED,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,GAAY,EAAE,GAAa,EAAE,EAAE;IACrD,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACrB,GAAG;aACA,MAAM,CAAC,GAAG,CAAC;aACX,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;QACxF,OAAO;IACT,CAAC;IAED,MAAM,MAAM,GAAG,WAAW,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;IACvC,MAAM,SAAS,GAAG,IAAI,6BAA6B,CAAC,EAAE,kBAAkB,EAAE,SAAS,EAAE,CAAC,CAAC;IACvF,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;QACnB,KAAK,SAAS,CAAC,KAAK,EAAE,CAAC;QACvB,KAAK,MAAM,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC,CAAC,CAAC;IAEH,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,MAAM,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;AACpD,CAAC,CAAC,CAAC;AAEH,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE;IAC3B,OAAO,CAAC,KAAK,CACX,oCAAoC,MAAM,CAAC,IAAI,WAAW,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG,CAClG,CAAC;AACJ,CAAC,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @braynexservices/nigeria-mcp-core — public surface consumed by every lane.
+ */
+export * from "./config.js";
+export * from "./schemas.js";
+export * from "./providers/types.js";
+export * from "./providers/registry.js";
+export * from "./lib/cache.js";
+export * from "./lib/errors.js";
+export * from "./lib/fetch.js";
+export * from "./lib/normalize.js";
+export * from "./server.js";
+export * from "./runtime.js";

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * @braynexservices/nigeria-mcp-core — public surface consumed by every lane.
+ */
+export * from "./config.js";
+export * from "./schemas.js";
+export * from "./providers/types.js";
+export * from "./providers/registry.js";
+export * from "./lib/cache.js";
+export * from "./lib/errors.js";
+export * from "./lib/fetch.js";
+export * from "./lib/normalize.js";
+export * from "./server.js";
+export * from "./runtime.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC"}

package/dist/lib/cache.d.ts

@@ -0,0 +1,19 @@
+/**
+ * In-memory TTL cache. Same get/set surface a Redis-backed cache will implement later,
+ * so lanes can stay cache-agnostic. See brain/08-tech-stack/core-stack.md
+ */
+export interface Cache {
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T, ttlSeconds?: number): void;
+    delete(key: string): void;
+    clear(): void;
+}
+export declare class MemoryCache implements Cache {
+    private readonly defaultTtlSeconds;
+    private readonly store;
+    constructor(defaultTtlSeconds: number);
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T, ttlSeconds?: number): void;
+    delete(key: string): void;
+    clear(): void;
+}

package/dist/lib/cache.js

@@ -0,0 +1,27 @@
+export class MemoryCache {
+    defaultTtlSeconds;
+    store = new Map();
+    constructor(defaultTtlSeconds) {
+        this.defaultTtlSeconds = defaultTtlSeconds;
+    }
+    get(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return undefined;
+        if (entry.expiresAt <= Date.now()) {
+            this.store.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    set(key, value, ttlSeconds = this.defaultTtlSeconds) {
+        this.store.set(key, { value, expiresAt: Date.now() + ttlSeconds * 1000 });
+    }
+    delete(key) {
+        this.store.delete(key);
+    }
+    clear() {
+        this.store.clear();
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/lib/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/lib/cache.ts"],"names":[],"mappings":"AAgBA,MAAM,OAAO,WAAW;IAGO;IAFZ,KAAK,GAAG,IAAI,GAAG,EAAiB,CAAC;IAElD,YAA6B,iBAAyB;QAAzB,sBAAiB,GAAjB,iBAAiB,CAAQ;IAAG,CAAC;IAE1D,GAAG,CAAI,GAAW;QAChB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAC7B,IAAI,KAAK,CAAC,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;YAClC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,KAAK,CAAC,KAAU,CAAC;IAC1B,CAAC;IAED,GAAG,CAAI,GAAW,EAAE,KAAQ,EAAE,aAAqB,IAAI,CAAC,iBAAiB;QACvE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,UAAU,GAAG,IAAI,EAAE,CAAC,CAAC;IAC5E,CAAC;IAED,MAAM,CAAC,GAAW;QAChB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;CACF"}

package/dist/lib/errors.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Actionable errors. Tool handlers throw ToolError with a hint; buildServer converts any
+ * throw into a clean, agent-readable tool result. See brain/04-rules/engineering-rules.md
+ */
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export declare class ToolError extends Error {
+    readonly hint?: string | undefined;
+    constructor(message: string, hint?: string | undefined);
+}
+/** Throw a not-found error with an optional next-step hint for the agent. */
+export declare function notFound(what: string, hint?: string): never;
+/** Convert any error into a CallToolResult with isError + a helpful message. */
+export declare function toToolResult(err: unknown): CallToolResult;

package/dist/lib/errors.js

@@ -0,0 +1,27 @@
+export class ToolError extends Error {
+    hint;
+    constructor(message, hint) {
+        super(message);
+        this.hint = hint;
+        this.name = "ToolError";
+    }
+}
+/** Throw a not-found error with an optional next-step hint for the agent. */
+export function notFound(what, hint) {
+    throw new ToolError(`${what} not found.`, hint);
+}
+/** Convert any error into a CallToolResult with isError + a helpful message. */
+export function toToolResult(err) {
+    const message = err instanceof ToolError
+        ? err.hint
+            ? `${err.message} ${err.hint}`
+            : err.message
+        : err instanceof Error
+            ? err.message
+            : String(err);
+    return {
+        content: [{ type: "text", text: `Error: ${message}` }],
+        isError: true,
+    };
+}
+//# sourceMappingURL=errors.js.map

package/dist/lib/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAMA,MAAM,OAAO,SAAU,SAAQ,KAAK;IAGhB;IAFlB,YACE,OAAe,EACC,IAAa;QAE7B,KAAK,CAAC,OAAO,CAAC,CAAC;QAFC,SAAI,GAAJ,IAAI,CAAS;QAG7B,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF;AAED,6EAA6E;AAC7E,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,IAAa;IAClD,MAAM,IAAI,SAAS,CAAC,GAAG,IAAI,aAAa,EAAE,IAAI,CAAC,CAAC;AAClD,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,MAAM,OAAO,GACX,GAAG,YAAY,SAAS;QACtB,CAAC,CAAC,GAAG,CAAC,IAAI;YACR,CAAC,CAAC,GAAG,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,IAAI,EAAE;YAC9B,CAAC,CAAC,GAAG,CAAC,OAAO;QACf,CAAC,CAAC,GAAG,YAAY,KAAK;YACpB,CAAC,CAAC,GAAG,CAAC,OAAO;YACb,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACpB,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,OAAO,EAAE,EAAE,CAAC;QACtD,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC"}

package/dist/lib/fetch.d.ts

@@ -0,0 +1,16 @@
+export interface FetchJsonOptions {
+    /** Human label for error messages, e.g. "Paystack". */
+    service: string;
+    /** Actionable tail appended to transient hints, e.g. "set BANK_PROVIDER=mock". */
+    fallbackHint: string;
+    /** Per-attempt timeout in ms. Default 15s. */
+    timeoutMs?: number;
+    /** Backoff (ms) before each attempt; first entry is usually 0. Default [0, 600, 1500]. */
+    backoffsMs?: number[];
+}
+export interface FetchJsonResult {
+    res: Response;
+    /** Parsed JSON body, or null if the response was not valid JSON. */
+    body: unknown;
+}
+export declare function fetchJson(url: string, init: RequestInit, opts: FetchJsonOptions): Promise<FetchJsonResult>;

package/dist/lib/fetch.js

@@ -0,0 +1,39 @@
+/**
+ * Shared fetch-with-retry used by every live adapter. Applies a per-attempt timeout and
+ * backoff-retry on TRANSIENT failures — network/timeout rejections, HTTP 429, and 5xx.
+ * (Hand-rolled retry loops in each adapter used to let a fetch() rejection escape unretried;
+ * centralizing it fixes that once.)
+ *
+ * Non-retryable responses are returned to the caller as { res, body } so each adapter keeps
+ * its own status/body policy — e.g. treat 401/403 as an auth error, or trust a provider's
+ * JSON envelope on a benign 4xx. Throws a ToolError only when all attempts are exhausted.
+ */
+import { ToolError } from "./errors.js";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export async function fetchJson(url, init, opts) {
+    const timeoutMs = opts.timeoutMs ?? 15_000;
+    const backoffs = opts.backoffsMs ?? [0, 600, 1500];
+    let lastError = null;
+    for (const backoff of backoffs) {
+        if (backoff)
+            await sleep(backoff);
+        let res;
+        try {
+            res = await fetch(url, { ...init, signal: AbortSignal.timeout(timeoutMs) });
+        }
+        catch {
+            // Timeout / DNS / connection reset — a transient we should retry, not leak raw.
+            lastError = new ToolError(`${opts.service} did not respond (network error or timeout).`, `Retried; try again shortly, or ${opts.fallbackHint}.`);
+            continue;
+        }
+        if (res.status === 429 || res.status >= 500) {
+            lastError = new ToolError(`${opts.service} is rate-limited or unavailable (HTTP ${res.status}).`, `Retried; try again shortly, or ${opts.fallbackHint}.`);
+            continue;
+        }
+        const body = await res.json().catch(() => null);
+        return { res, body };
+    }
+    throw (lastError ??
+        new ToolError(`${opts.service} request failed after retries.`, `Try again shortly, or ${opts.fallbackHint}.`));
+}
+//# sourceMappingURL=fetch.js.map

package/dist/lib/fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.js","sourceRoot":"","sources":["../../src/lib/fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAmBxC,MAAM,KAAK,GAAG,CAAC,EAAU,EAAiB,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;AAEnF,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,GAAW,EACX,IAAiB,EACjB,IAAsB;IAEtB,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,MAAM,CAAC;IAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IAEnD,IAAI,SAAS,GAAqB,IAAI,CAAC;IACvC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,OAAO;YAAE,MAAM,KAAK,CAAC,OAAO,CAAC,CAAC;QAClC,IAAI,GAAa,CAAC;QAClB,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QAC9E,CAAC;QAAC,MAAM,CAAC;YACP,gFAAgF;YAChF,SAAS,GAAG,IAAI,SAAS,CACvB,GAAG,IAAI,CAAC,OAAO,8CAA8C,EAC7D,kCAAkC,IAAI,CAAC,YAAY,GAAG,CACvD,CAAC;YACF,SAAS;QACX,CAAC;QACD,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,EAAE,CAAC;YAC5C,SAAS,GAAG,IAAI,SAAS,CACvB,GAAG,IAAI,CAAC,OAAO,yCAAyC,GAAG,CAAC,MAAM,IAAI,EACtE,kCAAkC,IAAI,CAAC,YAAY,GAAG,CACvD,CAAC;YACF,SAAS;QACX,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;QAChD,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;IACvB,CAAC;IACD,MAAM,CACJ,SAAS;QACT,IAAI,SAAS,CACX,GAAG,IAAI,CAAC,OAAO,gCAAgC,EAC/C,yBAAyB,IAAI,CAAC,YAAY,GAAG,CAC9C,CACF,CAAC;AACJ,CAAC"}

package/dist/lib/normalize.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Normalization helpers. Lane adapters map raw provider payloads into the schemas in
+ * schemas.ts and stamp provenance via these helpers.
+ */
+export declare function nowIso(): string;
+/** Stamp source + retrievedAt onto a normalized record. */
+export declare function stamp<T extends object>(record: T, source: string): T & {
+    source: string;
+    retrievedAt: string;
+};

package/dist/lib/normalize.js

@@ -0,0 +1,12 @@
+/**
+ * Normalization helpers. Lane adapters map raw provider payloads into the schemas in
+ * schemas.ts and stamp provenance via these helpers.
+ */
+export function nowIso() {
+    return new Date().toISOString();
+}
+/** Stamp source + retrievedAt onto a normalized record. */
+export function stamp(record, source) {
+    return { ...record, source, retrievedAt: nowIso() };
+}
+//# sourceMappingURL=normalize.js.map

package/dist/lib/normalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../../src/lib/normalize.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,UAAU,MAAM;IACpB,OAAO,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;AAClC,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,KAAK,CACnB,MAAS,EACT,MAAc;IAEd,OAAO,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,CAAC;AACtD,CAAC"}

package/dist/providers/registry.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Generic provider factory. Each lane builds a registry of { key -> factory } and calls
+ * selectProvider() with the env-selected key. Keeps provider selection uniform + typed.
+ */
+export type ProviderFactory<T> = () => T;
+export type ProviderRegistry<T> = Record<string, ProviderFactory<T>>;
+export declare function selectProvider<T>(kind: string, key: string, registry: ProviderRegistry<T>): T;

package/dist/providers/registry.js

@@ -0,0 +1,9 @@
+export function selectProvider(kind, key, registry) {
+    const factory = registry[key];
+    if (!factory) {
+        const available = Object.keys(registry).join(", ") || "(none)";
+        throw new Error(`Unknown ${kind} provider "${key}". Available: ${available}. Set the provider env var accordingly.`);
+    }
+    return factory();
+}
+//# sourceMappingURL=registry.js.map

package/dist/providers/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/providers/registry.ts"],"names":[],"mappings":"AAOA,MAAM,UAAU,cAAc,CAC5B,IAAY,EACZ,GAAW,EACX,QAA6B;IAE7B,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC;QAC/D,MAAM,IAAI,KAAK,CACb,WAAW,IAAI,cAAc,GAAG,iBAAiB,SAAS,yCAAyC,CACpG,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,EAAE,CAAC;AACnB,CAAC"}

package/dist/providers/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The provider seam — the moat. Tools depend on these interfaces, never on a concrete
+ * provider. Selecting/swapping a provider is one env var; adding one is one new file.
+ * See brain/02-strategy/positioning.md
+ */
+import type { NormalizedCompany, CompanyProfile, SearchHit, NormalizedBankAccount, FxRate, NormalizedDriversLicense, NormalizedVehicle, NormalizedMeter, NormalizedCredential, NormalizedTradeFlow, NormalizedHsCode } from "../schemas.js";
+export interface BankRef {
+    name: string;
+    code: string;
+}
+export interface CacProvider {
+    readonly name: string;
+    verify(rcOrName: string): Promise<NormalizedCompany>;
+    search(query: string): Promise<SearchHit[]>;
+    profile(rc: string): Promise<CompanyProfile>;
+}
+export interface BankProvider {
+    readonly name: string;
+    resolve(accountNumber: string, bankCode: string): Promise<NormalizedBankAccount>;
+    listBanks(): Promise<BankRef[]>;
+}
+export interface FxProvider {
+    readonly name: string;
+    rates(base?: string, quote?: string): Promise<FxRate[]>;
+}
+export interface DriversProvider {
+    readonly name: string;
+    verifyLicense(licenseNumber: string, dob?: string): Promise<NormalizedDriversLicense>;
+    verifyPlate(plateNumber: string): Promise<NormalizedVehicle>;
+}
+export interface Disco {
+    code: string;
+    name: string;
+}
+/** Electricity meter provider. READ-ONLY by design — no pay/recharge methods (NERC/CBN/AML). */
+export interface MeterProvider {
+    readonly name: string;
+    validate(meterNumber: string, disco: string, meterType: string): Promise<NormalizedMeter>;
+    listDiscos(): Promise<Disco[]>;
+}
+/** Credential (KYE) provider. Wrap licensed aggregators (NDPR) — never scrape WAEC/JAMB. */
+export interface CredentialProvider {
+    readonly name: string;
+    verify(type: string, candidateName: string, identifier: string): Promise<NormalizedCredential>;
+    verifyTeacher(trcnNumber: string): Promise<NormalizedCredential>;
+}
+/** Query for trade statistics. `commodity` is an HS code OR an aggregation level keyword. */
+export interface TradeStatsQuery {
+    flow: string;
+    partner?: string;
+    commodity?: string;
+    year?: number;
+    frequency?: string;
+    month?: number;
+}
+/** Trade-intelligence provider. Wrap OPEN global APIs (UN Comtrade, WITS) — not NICIS II. */
+export interface TradeProvider {
+    readonly name: string;
+    tradeStats(query: TradeStatsQuery): Promise<NormalizedTradeFlow[]>;
+    classifyHs(productDescription: string): Promise<NormalizedHsCode>;
+}

package/dist/providers/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/providers/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/providers/types.ts"],"names":[],"mappings":""}

package/dist/runtime.d.ts

@@ -0,0 +1,3 @@
+import { type ToolDef, type BuildServerOptions } from "./server.js";
+/** Build a server from the given tools and serve it over stdio (local use). */
+export declare function startStdio(tools: ToolDef[], opts?: BuildServerOptions): Promise<void>;

package/dist/runtime.js

@@ -0,0 +1,14 @@
+/**
+ * Transport runners. Lanes call startStdio() with their tools so they never import the
+ * MCP SDK transport directly — all SDK wiring stays in core.
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { buildServer } from "./server.js";
+/** Build a server from the given tools and serve it over stdio (local use). */
+export async function startStdio(tools, opts = {}) {
+    const server = buildServer(tools, opts);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`[${opts.name ?? "nigeria-mcp"}] stdio connected (${tools.length} tools)`);
+}
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,WAAW,EAAyC,MAAM,aAAa,CAAC;AAEjF,+EAA+E;AAC/E,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,KAAgB,EAAE,OAA2B,EAAE;IAC9E,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACxC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,IAAI,IAAI,aAAa,sBAAsB,KAAK,CAAC,MAAM,SAAS,CAAC,CAAC;AAC3F,CAAC"}

package/dist/schemas.d.ts

@@ -0,0 +1,380 @@
+/**
+ * Normalized, agent-facing data contracts. The SAME shape is returned regardless of
+ * which upstream provider served the request — this stability is the product.
+ * See brain/04-rules/engineering-rules.md and the lane dossiers in brain/07-lanes/.
+ */
+import { z } from "zod";
+/** Provenance fields stamped onto every normalized record. */
+export declare const Provenance: {
+    source: z.ZodString;
+    retrievedAt: z.ZodString;
+};
+export declare const NormalizedCompany: z.ZodObject<{
+    source: z.ZodString;
+    retrievedAt: z.ZodString;
+    rcNumber: z.ZodString;
+    name: z.ZodString;
+    status: z.ZodString;
+    address: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    registrationDate: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    status: string;
+    rcNumber: string;
+    source: string;
+    retrievedAt: string;
+    type?: string | null | undefined;
+    address?: string | null | undefined;
+    registrationDate?: string | null | undefined;
+}, {
+    name: string;
+    status: string;
+    rcNumber: string;
+    source: string;
+    retrievedAt: string;
+    type?: string | null | undefined;
+    address?: string | null | undefined;
+    registrationDate?: string | null | undefined;
+}>;
+export type NormalizedCompany = z.infer<typeof NormalizedCompany>;
+export declare const Director: z.ZodObject<{
+    name: z.ZodString;
+    role: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    role?: string | undefined;
+}, {
+    name: string;
+    role?: string | undefined;
+}>;
+export type Director = z.infer<typeof Director>;
+export declare const Shareholder: z.ZodObject<{
+    name: z.ZodString;
+    shares: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    shares?: number | undefined;
+}, {
+    name: string;
+    shares?: number | undefined;
+}>;
+export type Shareholder = z.infer<typeof Shareholder>;
+export declare const CompanyProfile: z.ZodObject<{
+    source: z.ZodString;
+    retrievedAt: z.ZodString;
+    rcNumber: z.ZodString;
+    name: z.ZodString;
+    status: z.ZodString;
+    address: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    registrationDate: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+} & {
+    classification: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    directors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        role: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        role?: string | undefined;
+    }, {
+        name: string;
+        role?: string | undefined;
+    }>, "many">>;
+    shareholders: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        shares: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        shares?: number | undefined;
+    }, {
+        name: string;
+        shares?: number | undefined;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    status: string;
+    rcNumber: string;
+    source: string;
+    retrievedAt: string;
+    email?: string | null | undefined;
+    type?: string | null | undefined;
+    address?: string | null | undefined;
+    registrationDate?: string | null | undefined;
+    classification?: string | null | undefined;
+    directors?: {
+        name: string;
+        role?: string | undefined;
+    }[] | undefined;
+    shareholders?: {
+        name: string;
+        shares?: number | undefined;
+    }[] | undefined;
+}, {
+    name: string;
+    status: string;
+    rcNumber: string;
+    source: string;
+    retrievedAt: string;
+    email?: string | null | undefined;
+    type?: string | null | undefined;
+    address?: string | null | undefined;
+    registrationDate?: string | null | undefined;
+    classification?: string | null | undefined;
+    directors?: {
+        name: string;
+        role?: string | undefined;
+    }[] | undefined;
+    shareholders?: {
+        name: string;
+        shares?: number | undefined;
+    }[] | undefined;
+}>;
+export type CompanyProfile = z.infer<typeof CompanyProfile>;
+export declare const SearchHit: z.ZodObject<{
+    rcNumber: z.ZodString;
+    name: z.ZodString;
+    status: z.ZodString;
+    registrationDate: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    status: string;
+    rcNumber: string;
+    registrationDate?: string | null | undefined;
+}, {
+    name: string;
+    status: string;
+    rcNumber: string;
+    registrationDate?: string | null | undefined;
+}>;
+export type SearchHit = z.infer<typeof SearchHit>;
+export declare const NormalizedBankAccount: z.ZodObject<{
+    source: z.ZodString;
+    retrievedAt: z.ZodString;
+    accountNumber: z.ZodString;
+    accountName: z.ZodString;
+    bankCode: z.ZodString;
+    bankName: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    source: string;
+    retrievedAt: string;
+    accountNumber: string;
+    accountName: string;
+    bankCode: string;
+    bankName?: string | undefined;
+}, {
+    source: string;
+    retrievedAt: string;
+    accountNumber: string;
+    accountName: string;
+    bankCode: string;
+    bankName?: string | undefined;
+}>;
+export type NormalizedBankAccount = z.infer<typeof NormalizedBankAccount>;
+export declare const FxRate: z.ZodObject<{
+    source: z.ZodString;
+    retrievedAt: z.ZodString;
+    base: z.ZodString;
+    quote: z.ZodString;
+    rate: z.ZodNumber;
+    market: z.ZodEnum<["official", "parallel"]>;
+}, "strip", z.ZodTypeAny, {
+    source: string;
+    retrievedAt: string;
+    base: string;
+    quote: string;
+    rate: number;
+    market: "official" | "parallel";
+}, {
+    source: string;
+    retrievedAt: string;
+    base: string;
+    quote: string;
+    rate: number;
+    market: "official" | "parallel";
+}>;
+export type FxRate = z.infer<typeof FxRate>;
+export declare const NormalizedDriversLicense: z.ZodObject<{
+    source: z.ZodString;
+    retrievedAt: z.ZodString;
+    licenseNumber: z.ZodString;
+    holderName: z.ZodString;
+    status: z.ZodString;
+    issueDate: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    expiryDate: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    class: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    status: string;
+    source: string;
+    retrievedAt: string;
+    licenseNumber: string;
+    holderName: string;
+    issueDate?: string | null | undefined;
+    expiryDate?: string | null | undefined;
+    class?: string | null | undefined;
+}, {
+    status: string;
+    source: string;
+    retrievedAt: string;
+    licenseNumber: string;
+    holderName: string;
+    issueDate?: string | null | undefined;
+    expiryDate?: string | null | undefined;
+    class?: string | null | undefined;
+}>;
+export type NormalizedDriversLicense = z.infer<typeof NormalizedDriversLicense>;
+export declare const NormalizedVehicle: z.ZodObject<{
+    source: z.ZodString;
+    retrievedAt: z.ZodString;
+    plateNumber: z.ZodString;
+    make: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    model: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    year: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    color: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    fuel: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    status: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    source: string;
+    retrievedAt: string;
+    plateNumber: string;
+    status?: string | null | undefined;
+    make?: string | null | undefined;
+    model?: string | null | undefined;
+    year?: number | null | undefined;
+    color?: string | null | undefined;
+    fuel?: string | null | undefined;
+}, {
+    source: string;
+    retrievedAt: string;
+    plateNumber: string;
+    status?: string | null | undefined;
+    make?: string | null | undefined;
+    model?: string | null | undefined;
+    year?: number | null | undefined;
+    color?: string | null | undefined;
+    fuel?: string | null | undefined;
+}>;
+export type NormalizedVehicle = z.infer<typeof NormalizedVehicle>;
+export declare const NormalizedMeter: z.ZodObject<{
+    source: z.ZodString;
+    retrievedAt: z.ZodString;
+    meterNumber: z.ZodString;
+    customerName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    address: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    disco: z.ZodString;
+    meterType: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    source: string;
+    retrievedAt: string;
+    meterNumber: string;
+    disco: string;
+    meterType: string;
+    address?: string | null | undefined;
+    customerName?: string | null | undefined;
+}, {
+    source: string;
+    retrievedAt: string;
+    meterNumber: string;
+    disco: string;
+    meterType: string;
+    address?: string | null | undefined;
+    customerName?: string | null | undefined;
+}>;
+export type NormalizedMeter = z.infer<typeof NormalizedMeter>;
+export declare const NormalizedCredential: z.ZodObject<{
+    source: z.ZodString;
+    retrievedAt: z.ZodString;
+    type: z.ZodString;
+    holderName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    institution: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    status: z.ZodString;
+    identifier: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: string;
+    status: string;
+    source: string;
+    retrievedAt: string;
+    identifier: string;
+    holderName?: string | null | undefined;
+    institution?: string | null | undefined;
+}, {
+    type: string;
+    status: string;
+    source: string;
+    retrievedAt: string;
+    identifier: string;
+    holderName?: string | null | undefined;
+    institution?: string | null | undefined;
+}>;
+export type NormalizedCredential = z.infer<typeof NormalizedCredential>;
+export declare const NormalizedTradeFlow: z.ZodObject<{
+    source: z.ZodString;
+    retrievedAt: z.ZodString;
+    reporter: z.ZodString;
+    partner: z.ZodString;
+    hsCode: z.ZodString;
+    commodity: z.ZodString;
+    flow: z.ZodEnum<["import", "export"]>;
+    period: z.ZodString;
+    year: z.ZodNumber;
+    valueUsd: z.ZodNumber;
+    cifValueUsd: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    fobValueUsd: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    netWeightKg: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    quantity: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    quantityUnit: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    source: string;
+    retrievedAt: string;
+    year: number;
+    reporter: string;
+    partner: string;
+    hsCode: string;
+    commodity: string;
+    flow: "import" | "export";
+    period: string;
+    valueUsd: number;
+    cifValueUsd?: number | null | undefined;
+    fobValueUsd?: number | null | undefined;
+    netWeightKg?: number | null | undefined;
+    quantity?: number | null | undefined;
+    quantityUnit?: string | null | undefined;
+}, {
+    source: string;
+    retrievedAt: string;
+    year: number;
+    reporter: string;
+    partner: string;
+    hsCode: string;
+    commodity: string;
+    flow: "import" | "export";
+    period: string;
+    valueUsd: number;
+    cifValueUsd?: number | null | undefined;
+    fobValueUsd?: number | null | undefined;
+    netWeightKg?: number | null | undefined;
+    quantity?: number | null | undefined;
+    quantityUnit?: string | null | undefined;
+}>;
+export type NormalizedTradeFlow = z.infer<typeof NormalizedTradeFlow>;
+export declare const NormalizedHsCode: z.ZodObject<{
+    source: z.ZodString;
+    retrievedAt: z.ZodString;
+    query: z.ZodString;
+    hsCode: z.ZodString;
+    heading: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    source: string;
+    retrievedAt: string;
+    hsCode: string;
+    query: string;
+    heading: string;
+}, {
+    source: string;
+    retrievedAt: string;
+    hsCode: string;
+    query: string;
+    heading: string;
+}>;
+export type NormalizedHsCode = z.infer<typeof NormalizedHsCode>;

package/dist/schemas.js

@@ -0,0 +1,122 @@
+/**
+ * Normalized, agent-facing data contracts. The SAME shape is returned regardless of
+ * which upstream provider served the request — this stability is the product.
+ * See brain/04-rules/engineering-rules.md and the lane dossiers in brain/07-lanes/.
+ */
+import { z } from "zod";
+/** Provenance fields stamped onto every normalized record. */
+export const Provenance = {
+    source: z.string().describe("Which provider/source served this record (e.g. 'mock', 'public', 'mono')"),
+    retrievedAt: z.string().describe("ISO-8601 timestamp when the record was fetched"),
+};
+// ---------- CAC / KYB ----------
+export const NormalizedCompany = z.object({
+    rcNumber: z.string().describe("CAC registration (RC) number"),
+    name: z.string().describe("Registered company name"),
+    status: z.string().describe("Registration status, e.g. ACTIVE / INACTIVE"),
+    address: z.string().nullable().optional().describe("Registered address"),
+    registrationDate: z.string().nullable().optional().describe("Date of incorporation (ISO date)"),
+    type: z.string().nullable().optional().describe("Entity type, e.g. LTD / BN / IT"),
+    ...Provenance,
+});
+export const Director = z.object({
+    name: z.string(),
+    role: z.string().optional(),
+});
+export const Shareholder = z.object({
+    name: z.string(),
+    shares: z.number().optional(),
+});
+export const CompanyProfile = NormalizedCompany.extend({
+    classification: z.string().nullable().optional(),
+    email: z.string().nullable().optional(),
+    directors: z.array(Director).optional(),
+    shareholders: z.array(Shareholder).optional(),
+});
+export const SearchHit = z.object({
+    rcNumber: z.string(),
+    name: z.string(),
+    status: z.string(),
+    registrationDate: z.string().nullable().optional(),
+});
+// ---------- Bank ----------
+export const NormalizedBankAccount = z.object({
+    accountNumber: z.string().describe("10-digit NUBAN"),
+    accountName: z.string().describe("Registered account holder name"),
+    bankCode: z.string(),
+    bankName: z.string().optional(),
+    ...Provenance,
+});
+// ---------- FX ----------
+export const FxRate = z.object({
+    base: z.string().describe("Base currency, e.g. NGN"),
+    quote: z.string().describe("Quote currency, e.g. USD"),
+    rate: z.number(),
+    market: z.enum(["official", "parallel"]).describe("Official (CBN) or parallel ('aboki') market"),
+    ...Provenance,
+});
+// ---------- Driver's licence + vehicle (FRSC) ----------
+// PII pass-through only — never persisted/cached (NDPA). Optional fields are provider-dependent.
+export const NormalizedDriversLicense = z.object({
+    licenseNumber: z.string().describe("Driver's licence number"),
+    holderName: z.string().describe("Licence holder's full name"),
+    status: z.string().describe("Validity status, e.g. VALID / EXPIRED"),
+    issueDate: z.string().nullable().optional().describe("Issue date (ISO)"),
+    expiryDate: z.string().nullable().optional().describe("Expiry date (ISO)"),
+    class: z.string().nullable().optional().describe("Licence class, e.g. A / B / C"),
+    ...Provenance,
+});
+export const NormalizedVehicle = z.object({
+    plateNumber: z.string().describe("Vehicle plate number (normalized, uppercase)"),
+    make: z.string().nullable().optional(),
+    model: z.string().nullable().optional(),
+    year: z.number().nullable().optional(),
+    color: z.string().nullable().optional(),
+    fuel: z.string().nullable().optional(),
+    status: z.string().nullable().optional().describe("Registration status, e.g. REGISTERED / EXPIRED"),
+    ...Provenance,
+});
+// ---------- Electricity / meter validation (READ-ONLY) ----------
+// Validation/info only — never payment execution (NERC/CBN/AML). Customer PII not persisted.
+export const NormalizedMeter = z.object({
+    meterNumber: z.string().describe("Electricity meter number"),
+    customerName: z.string().nullable().optional().describe("Registered customer name (PII — pass-through)"),
+    address: z.string().nullable().optional().describe("Service address (PII — pass-through)"),
+    disco: z.string().describe("Distribution company code, e.g. EKEDC / IKEDC / AEDC / PHED"),
+    meterType: z.string().describe("prepaid | postpaid"),
+    ...Provenance,
+});
+// ---------- Education / credential verification (KYE) ----------
+// Verify via licensed aggregators (they carry NDPR) — never scrape WAEC/JAMB. PII pass-through.
+export const NormalizedCredential = z.object({
+    type: z.string().describe("Credential type, e.g. WAEC / NECO / NYSC / DEGREE / TRCN"),
+    holderName: z.string().nullable().optional().describe("Credential holder name (PII — pass-through)"),
+    institution: z.string().nullable().optional().describe("Issuing institution / body"),
+    status: z.string().describe("Verification status, e.g. VERIFIED / REGISTERED / NOT_FOUND"),
+    identifier: z.string().describe("The certificate / exam / registration number verified"),
+    ...Provenance,
+});
+// ---------- Trade intelligence (public macro data, no PII) ----------
+export const NormalizedTradeFlow = z.object({
+    reporter: z.string().describe("Reporting country, e.g. Nigeria"),
+    partner: z.string().describe("Trade partner country"),
+    hsCode: z.string().describe("HS commodity code (or aggregate, e.g. TOTAL)"),
+    commodity: z.string().describe("Commodity description"),
+    flow: z.enum(["import", "export"]),
+    period: z.string().describe("Reporting period — year (2024) or year-month (202403)"),
+    year: z.number().describe("Reporting year"),
+    valueUsd: z.number().describe("Primary trade value in USD"),
+    cifValueUsd: z.number().nullable().optional().describe("CIF value in USD (imports), where reported"),
+    fobValueUsd: z.number().nullable().optional().describe("FOB value in USD (exports), where reported"),
+    netWeightKg: z.number().nullable().optional().describe("Net weight in kilograms, where reported"),
+    quantity: z.number().nullable().optional().describe("Quantity in the reported unit, where available"),
+    quantityUnit: z.string().nullable().optional().describe("Unit for quantity, e.g. 'N' (number of items), 'kg', 'l'"),
+    ...Provenance,
+});
+export const NormalizedHsCode = z.object({
+    query: z.string().describe("The product description that was classified"),
+    hsCode: z.string().describe("Best-match HS code"),
+    heading: z.string().describe("HS heading / description"),
+    ...Provenance,
+});
+//# sourceMappingURL=schemas.js.map

package/dist/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,8DAA8D;AAC9D,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0EAA0E,CAAC;IACvG,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,gDAAgD,CAAC;CACnF,CAAC;AAEF,kCAAkC;AAClC,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,8BAA8B,CAAC;IAC7D,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,yBAAyB,CAAC;IACpD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,6CAA6C,CAAC;IAC1E,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oBAAoB,CAAC;IACxE,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kCAAkC,CAAC;IAC/F,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iCAAiC,CAAC;IAClF,GAAG,UAAU;CACd,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC5B,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC9B,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,cAAc,GAAG,iBAAiB,CAAC,MAAM,CAAC;IACrD,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAChD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IACvC,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,QAAQ,EAAE;IACvC,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,QAAQ,EAAE;CAC9C,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC;IAChC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CACnD,CAAC,CAAC;AAGH,6BAA6B;AAC7B,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,gBAAgB,CAAC;IACpD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,gCAAgC,CAAC;IAClE,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,GAAG,UAAU;CACd,CAAC,CAAC;AAGH,2BAA2B;AAC3B,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,yBAAyB,CAAC;IACpD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0BAA0B,CAAC;IACtD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,6CAA6C,CAAC;IAChG,GAAG,UAAU;CACd,CAAC,CAAC;AAGH,0DAA0D;AAC1D,iGAAiG;AACjG,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,yBAAyB,CAAC;IAC7D,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,4BAA4B,CAAC;IAC7D,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,uCAAuC,CAAC;IACpE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kBAAkB,CAAC;IACxE,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mBAAmB,CAAC;IAC1E,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,+BAA+B,CAAC;IACjF,GAAG,UAAU;CACd,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,8CAA8C,CAAC;IAChF,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IACtC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IACvC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IACtC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IACvC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IACtC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gDAAgD,CAAC;IACnG,GAAG,UAAU;CACd,CAAC,CAAC;AAGH,mEAAmE;AACnE,6FAA6F;AAC7F,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0BAA0B,CAAC;IAC5D,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,+CAA+C,CAAC;IACxG,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,sCAAsC,CAAC;IAC1F,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,6DAA6D,CAAC;IACzF,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oBAAoB,CAAC;IACpD,GAAG,UAAU;CACd,CAAC,CAAC;AAGH,kEAAkE;AAClE,gGAAgG;AAChG,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0DAA0D,CAAC;IACrF,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,6CAA6C,CAAC;IACpG,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,4BAA4B,CAAC;IACpF,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,6DAA6D,CAAC;IAC1F,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,uDAAuD,CAAC;IACxF,GAAG,UAAU;CACd,CAAC,CAAC;AAGH,uEAAuE;AACvE,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iCAAiC,CAAC;IAChE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,uBAAuB,CAAC;IACrD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,8CAA8C,CAAC;IAC3E,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,uBAAuB,CAAC;IACvD,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAClC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,uDAAuD,CAAC;IACpF,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,gBAAgB,CAAC;IAC3C,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,4BAA4B,CAAC;IAC3D,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,4CAA4C,CAAC;IACpG,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,4CAA4C,CAAC;IACpG,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,yCAAyC,CAAC;IACjG,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gDAAgD,CAAC;IACrG,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,0DAA0D,CAAC;IACnH,GAAG,UAAU;CACd,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,6CAA6C,CAAC;IACzE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oBAAoB,CAAC;IACjD,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0BAA0B,CAAC;IACxD,GAAG,UAAU;CACd,CAAC,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Transport-agnostic MCP server builder. Lanes hand buildServer() an array of ToolDefs;
+ * stdio.ts and http.ts wrap the result in a transport. See brain/05-plans/v1-plan.md
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { type ZodRawShape } from "zod";
+export interface ToolAnnotations {
+    readOnlyHint?: boolean;
+    openWorldHint?: boolean;
+    idempotentHint?: boolean;
+    destructiveHint?: boolean;
+}
+export interface ToolDef {
+    name: string;
+    title?: string;
+    description: string;
+    inputSchema: ZodRawShape;
+    outputSchema?: ZodRawShape;
+    annotations?: ToolAnnotations;
+    handler: (args: Record<string, unknown>) => Promise<CallToolResult>;
+}
+export interface BuildServerOptions {
+    name?: string;
+    version?: string;
+}
+export declare function buildServer(tools: ToolDef[], opts?: BuildServerOptions): McpServer;
+/** Throwaway health tool used to smoke-test transports. Safe to keep; harmless. */
+export declare const pingTool: ToolDef;

package/dist/server.js

@@ -0,0 +1,50 @@
+/**
+ * Transport-agnostic MCP server builder. Lanes hand buildServer() an array of ToolDefs;
+ * stdio.ts and http.ts wrap the result in a transport. See brain/05-plans/v1-plan.md
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { toToolResult } from "./lib/errors.js";
+import { nowIso } from "./lib/normalize.js";
+export function buildServer(tools, opts = {}) {
+    const server = new McpServer({
+        name: opts.name ?? "nigeria-mcp",
+        version: opts.version ?? "0.0.0",
+    });
+    for (const tool of tools) {
+        server.registerTool(tool.name, {
+            title: tool.title ?? tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            outputSchema: tool.outputSchema,
+            // Lookup tools are read-only and talk to the outside world by default.
+            annotations: { readOnlyHint: true, openWorldHint: true, ...tool.annotations },
+            // Cast at the SDK boundary: the generic ties the callback to the inferred schema,
+            // but our ToolDef handler uses a uniform Record signature.
+        }, (async (args) => {
+            try {
+                return await tool.handler(args ?? {});
+            }
+            catch (err) {
+                return toToolResult(err);
+            }
+        }));
+    }
+    return server;
+}
+/** Throwaway health tool used to smoke-test transports. Safe to keep; harmless. */
+export const pingTool = {
+    name: "ping",
+    title: "Ping",
+    description: "Health check — returns pong and the server time.",
+    inputSchema: {},
+    outputSchema: { pong: z.boolean(), time: z.string() },
+    handler: async () => {
+        const time = nowIso();
+        return {
+            content: [{ type: "text", text: `pong @ ${time}` }],
+            structuredContent: { pong: true, time },
+        };
+    },
+};
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,CAAC,EAAoB,MAAM,KAAK,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAwB5C,MAAM,UAAU,WAAW,CAAC,KAAgB,EAAE,OAA2B,EAAE;IACzE,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,aAAa;QAChC,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,OAAO;KACjC,CAAC,CAAC;IAEH,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,CAAC,YAAY,CACjB,IAAI,CAAC,IAAI,EACT;YACE,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,IAAI;YAC9B,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,uEAAuE;YACvE,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC,WAAW,EAAE;YAC7E,kFAAkF;YAClF,2DAA2D;SAChB,EAC7C,CAAC,KAAK,EAAE,IAA6B,EAAE,EAAE;YACvC,IAAI,CAAC;gBACH,OAAO,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;YACxC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC;YAC3B,CAAC;QACH,CAAC,CAA6C,CAC/C,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,mFAAmF;AACnF,MAAM,CAAC,MAAM,QAAQ,GAAY;IAC/B,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,MAAM;IACb,WAAW,EAAE,kDAAkD;IAC/D,WAAW,EAAE,EAAE;IACf,YAAY,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE;IACrD,OAAO,EAAE,KAAK,IAAI,EAAE;QAClB,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC;QACtB,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,IAAI,EAAE,EAAE,CAAC;YACnD,iBAAiB,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE;SACxC,CAAC;IACJ,CAAC;CACF,CAAC"}

package/dist/stdio.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/stdio.js

@@ -0,0 +1,8 @@
+/**
+ * Core stdio entrypoint — ships only the ping tool. Lanes provide their own entrypoints
+ * that pass their tools to startStdio().
+ */
+import { startStdio } from "./runtime.js";
+import { pingTool } from "./server.js";
+await startStdio([pingTool]);
+//# sourceMappingURL=stdio.js.map

package/dist/stdio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.js","sourceRoot":"","sources":["../src/stdio.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,MAAM,UAAU,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@braynexservices/nigeria-mcp-core",
+  "version": "0.1.0",
+  "description": "Core runtime for the Nigeria MCP data-lane servers: MCP server builder, normalized Zod schemas, typed provider seam, and shared fetch/cache/error helpers.",
+  "private": false,
+  "publishConfig": { "access": "public" },
+  "files": ["dist", "LICENSE", "NOTICE"],
+  "homepage": "https://www.braynexservices.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/braynexservices/nigeria-mcp.git",
+    "directory": "shared"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepack": "tsc",
+    "start:stdio": "tsx src/stdio.ts",
+    "start:http": "tsx src/http.ts",
+    "smoke": "tsx scripts/smoke.ts",
+    "inspect": "mcp-inspector tsx src/stdio.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "express": "^4.22.2",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.25",
+    "@types/node": "^26.0.0",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3"
+  },
+  "license": "MIT",
+  "author": "Samuel Orie <braynexservices@gmail.com> (Braynex Services Ltd — https://www.braynexservices.com)"
+}