jpdcl 1.0.0

package/src/smart-client.ts

@@ -0,0 +1,249 @@
+import { endpointCatalog, isEndpointName, type EndpointName } from "./catalog.js";
+import { SMART_API_URL, mutationsEnabled } from "./config.js";
+import { assertDateRange } from "./dates.js";
+import { AuthenticationError, JpdclError, MutationDisabledError } from "./errors.js";
+import { buildUrl } from "./http.js";
+import type { PortalResponse, RequestOptions } from "./types.js";
+
+export interface SmartTokenClaims {
+  sub?: string;
+  exp?: number;
+  tenantId?: string;
+  currentAccountTenantId?: string;
+  currentAccountKno?: string;
+  currentAccountMeterNo?: string;
+  currentAccountIsMeterPrepaid?: boolean | string;
+  currentAccountMeteringMode?: string;
+  currentAccountName?: string;
+  userAccounts?: string | unknown[];
+  [key: string]: unknown;
+}
+
+export class SmartMeterClient {
+  readonly claims: SmartTokenClaims;
+
+  constructor(
+    private token?: string,
+    readonly baseUrl = SMART_API_URL,
+    private readonly allowMutations = mutationsEnabled(),
+    readonly tenantId?: string,
+    private readonly adminToken = process.env.JPDCL_SMART_ADMIN_TOKEN,
+  ) {
+    this.claims = token ? decodeJwt(token) : {};
+  }
+
+  get bearerToken(): string | undefined { return this.token; }
+  get accountId(): string | undefined { return stringClaim(this.claims.currentAccountKno); }
+  get meterNumber(): string | undefined { return stringClaim(this.claims.currentAccountMeterNo); }
+  get effectiveTenantId(): string | undefined {
+    return this.tenantId ?? stringClaim(this.claims.currentAccountTenantId) ?? stringClaim(this.claims.tenantId);
+  }
+  get expiresAt(): string | undefined {
+    return typeof this.claims.exp === "number" ? new Date(this.claims.exp * 1000).toISOString() : undefined;
+  }
+
+  sessionInfo(): Record<string, unknown> {
+    return {
+      authenticated: Boolean(this.token),
+      expiresAt: this.expiresAt,
+      accountId: this.accountId,
+      meterNumber: this.meterNumber,
+      tenantId: this.effectiveTenantId,
+      userId: stringClaim(this.claims.sub),
+      isPrepaid: booleanClaim(this.claims.currentAccountIsMeterPrepaid),
+      meteringMode: stringClaim(this.claims.currentAccountMeteringMode),
+      accounts: parseAccounts(this.claims.userAccounts),
+    };
+  }
+
+  async request<T = unknown>(name: EndpointName | string, options: RequestOptions = {}): Promise<PortalResponse<T>> {
+    if (!isEndpointName(name)) throw new JpdclError(`Unknown endpoint: ${name}`, 400);
+    const endpoint = endpointCatalog[name];
+    if (endpoint.portal !== "smart") throw new JpdclError(`${name} belongs to the main JPDCL portal`, 400);
+    if (endpoint.mutation && !this.allowMutations) throw new MutationDisabledError();
+    if (endpoint.auth === "smart-bearer" && !this.token) throw new AuthenticationError("A smart-meter bearer token is required");
+    if (endpoint.auth === "smart-admin" && !this.adminToken) throw new AuthenticationError("JPDCL_SMART_ADMIN_TOKEN is required for this administrative endpoint");
+
+    const url = buildUrl(this.baseUrl, endpoint.path, options.params);
+    const headers: Record<string, string> = { Accept: endpoint.binary ? "*/*" : "application/json", ...options.headers };
+    if (endpoint.auth === "smart-bearer" && this.token) headers.Authorization = `Bearer ${this.token}`;
+    if (endpoint.auth === "smart-bearer" && this.effectiveTenantId) headers.TenantId = this.effectiveTenantId;
+    if (endpoint.auth === "smart-admin" && this.adminToken) headers.Authorization = `Bearer ${this.adminToken}`;
+
+    let body: string | undefined;
+    if (options.body !== undefined && endpoint.method !== "GET" && endpoint.method !== "DELETE") {
+      headers["Content-Type"] = "application/json";
+      body = JSON.stringify(options.body);
+    }
+    const response = await fetch(url, { method: endpoint.method, headers, body });
+    const contentType = response.headers.get("content-type") ?? "";
+    if (endpoint.binary || !contentType.toLowerCase().includes("json")) {
+      const bytes = Buffer.from(await response.arrayBuffer());
+      if (!response.ok) throw new JpdclError(`Smart-meter portal returned HTTP ${response.status}`, response.status, bytes.toString("utf8"));
+      return { status: true, data: { base64: bytes.toString("base64"), contentType } as T };
+    }
+
+    const raw = (await response.json()) as PortalResponse<T> & { success?: boolean; error?: unknown };
+    if (!response.ok || raw.success === false) {
+      throw new JpdclError(errorMessage(raw) ?? `Smart-meter portal returned HTTP ${response.status}`, response.status || 502, raw);
+    }
+    return normalizeEnvelope(raw);
+  }
+
+  async connections(): Promise<PortalResponse> {
+    const accounts = parseAccounts(this.claims.userAccounts);
+    const current = this.sessionInfo();
+    return { status: true, data: accounts.length ? accounts : [current] };
+  }
+
+  async dashboard(accountId = this.accountId, options: { includeDerived?: boolean } = {}): Promise<PortalResponse> {
+    if (!accountId) throw new JpdclError("Smart-meter account ID is required", 400);
+    const meterNumber = this.meterNumber;
+    if (!meterNumber) throw new JpdclError("Smart-meter number is required", 400);
+    const calls: Record<string, Promise<PortalResponse>> = {
+      usage: this.request("smart_today_monthly", { params: { meterNumber } }),
+      currentMonth: this.request("smart_current_month", { params: { accountId } }),
+      meterReadings: this.request("smart_meter_reading", { params: { meterNumber } }),
+      reading: this.request("smart_current_meter_reading", { params: { accountId } }),
+      lastBill: this.request("smart_postpaid_last_bill", { params: { accountId } }),
+      billHistory: this.request("smart_postpaid_bill_history", { params: { accountId } }),
+      paymentHistory: this.request("smart_postpaid_payment_history", { params: { accountId } }),
+      meterDetails: this.request("smart_meter_details", { params: { meterNumber } }),
+      preferences: this.request("smart_preferences", { params: { isPrepaid: booleanClaim(this.claims.currentAccountIsMeterPrepaid) ?? false } }),
+      alerts: this.request("smart_my_alerts", { params: { accountId, meterNumber } }),
+      onDemandRequests: this.request("smart_on_demand_logs", { params: { meterNumber } }),
+    };
+    const userId = stringClaim(this.claims.sub);
+    if (userId) {
+      calls.notifications = this.request("smart_notifications", { params: { userId } }).catch(() => ({ status: true, data: [] }));
+      calls.unreadNotifications = this.request("smart_notification_unread_count", { params: { userId } }).catch(() => ({ status: true, data: { unreadCount: 0 } }));
+    }
+    if (booleanClaim(this.claims.currentAccountIsMeterPrepaid)) {
+      delete calls.lastBill;
+      delete calls.billHistory;
+      delete calls.paymentHistory;
+      calls.prepaidBalance = this.request("smart_prepaid_balance", { params: { meterNumber } });
+      calls.rechargeBalance = this.request("smart_prepaid_recharge_balance", { params: { accountId } });
+      calls.rechargeHistory = this.request("smart_prepaid_recharge_history", { params: { meterNumber } });
+      calls.billHistory = this.request("smart_prepaid_bill_history", { params: { meterNumber } });
+    }
+    if (options.includeDerived) {
+      calls.derivedInsights = this.request("smart_insights", { params: { accountId } });
+      calls.derivedForecastToday = this.request("smart_forecast_today", { params: { meterNumber } });
+      calls.derivedForecastWeekly = this.request("smart_forecast_weekly", { params: { meterNumber } });
+      calls.derivedForecastMonthly = this.request("smart_forecast_monthly", { params: { meterNumber } });
+    }
+    const entries = await Promise.all(Object.entries(calls).map(async ([key, promise]) => {
+      try { return [key, (await promise).data] as const; }
+      catch (error) { return [key, { unavailable: true, message: error instanceof Error ? error.message : String(error) }] as const; }
+    }));
+    return {
+      status: true,
+      data: {
+        _meta: options.includeDerived
+          ? { dataPolicy: "observed-plus-derived", warning: "derivedInsights and derivedForecast* are predictions/advice, not meter evidence" }
+          : { dataPolicy: "observed-only", derivedAndAdvisoryExcluded: true },
+        session: this.sessionInfo(),
+        ...Object.fromEntries(entries),
+      },
+    };
+  }
+
+  consumption(accountId = this.accountId, type = "monthly", value = 12): Promise<PortalResponse> {
+    if (!accountId) throw new JpdclError("Smart-meter account ID is required", 400);
+    if (!this.meterNumber) throw new JpdclError("Smart-meter number is required", 400);
+    return this.request("smart_consumption_comparison", { params: { meterNumber: this.meterNumber, type, value } });
+  }
+
+  intervalConsumption(accountId: string | undefined, from: string, to: string, sortOrder = "date"): Promise<PortalResponse> {
+    if (!(accountId ?? this.accountId)) throw new JpdclError("Smart-meter account ID is required", 400);
+    if (!this.meterNumber) throw new JpdclError("Smart-meter number is required", 400);
+    assertDateRange(from, to, { requireBoth: true });
+    return this.request("smart_consumption_30min", { params: { meterNumber: this.meterNumber, fromDate: from, toDate: to, sortOrder } });
+  }
+
+  report(reportType: SmartReportType, accountId = this.accountId, options: SmartReportOptions = {}): Promise<PortalResponse> {
+    if (!accountId) throw new JpdclError("Smart-meter account ID is required", 400);
+    if (!this.meterNumber) throw new JpdclError("Smart-meter number is required", 400);
+    assertDateRange(options.from, options.to, { pairedWhenPresent: true });
+    const filter = options.filter ?? (options.from && options.to
+      ? encodeReportFilter(options.from, options.to, options.start ?? 1, options.end ?? defaultReportEnd(reportType))
+      : undefined);
+    return this.request("smart_report", { params: { meterNumber: this.meterNumber, reportType, filter, format: options.format } });
+  }
+}
+
+export type SmartReportType = "PowerOnOff" | "DayWiseTOD" | "MonthlyTOD" | "PeakSlotConsumption" |
+  "PeakSlotConsumptionMonthly" | "ConsumerVoltageDataProfile" | "SanctionLoadVSMaxDemand";
+
+export interface SmartReportOptions {
+  from?: string;
+  to?: string;
+  start?: number;
+  end?: number;
+  filter?: string;
+  format?: "xlsx" | "pdf";
+}
+
+export function encodeReportFilter(from: string, to: string, start = 1, end = 100): string {
+  return Buffer.from(JSON.stringify({
+    start,
+    end,
+    filters: { createdDateFrom: from, createdDateTo: to },
+  }), "utf8").toString("base64");
+}
+
+export function smartApiUrlFromAppUrl(appUrl?: string): string {
+  if (!appUrl) return SMART_API_URL;
+  return new URL("/api", appUrl).toString().replace(/\/$/, "");
+}
+
+export function decodeJwt(token: string): SmartTokenClaims {
+  try {
+    const payload = token.split(".")[1];
+    if (!payload) throw new Error("JWT payload is missing");
+    return JSON.parse(Buffer.from(payload, "base64url").toString("utf8")) as SmartTokenClaims;
+  } catch (error) {
+    throw new AuthenticationError("Invalid smart-meter SSO token", error);
+  }
+}
+
+function normalizeEnvelope<T>(raw: PortalResponse<T> & { success?: boolean }): PortalResponse<T> {
+  if (Object.prototype.hasOwnProperty.call(raw, "success")) {
+    return { status: raw.success, message: raw.message, data: raw.data, correlationId: raw.correlationId };
+  }
+  return raw;
+}
+
+function errorMessage(value: Record<string, unknown>): string | undefined {
+  const error = value.error;
+  if (typeof error === "string") return error;
+  if (error && typeof error === "object") {
+    const record = error as Record<string, unknown>;
+    return stringClaim(record.message) ?? stringClaim(record.title);
+  }
+  return stringClaim(value.message);
+}
+
+function stringClaim(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function booleanClaim(value: unknown): boolean | undefined {
+  if (typeof value === "boolean") return value;
+  if (typeof value === "string" && ["true", "false"].includes(value.toLowerCase())) return value.toLowerCase() === "true";
+  return undefined;
+}
+
+function parseAccounts(value: unknown): unknown[] {
+  if (Array.isArray(value)) return value;
+  if (typeof value === "string") {
+    try { const parsed = JSON.parse(value); return Array.isArray(parsed) ? parsed : []; }
+    catch { return []; }
+  }
+  return [];
+}
+
+function defaultReportEnd(reportType: SmartReportType): number {
+  return reportType === "ConsumerVoltageDataProfile" ? 100 : reportType === "SanctionLoadVSMaxDemand" ? 12 : 10;
+}

package/src/tariff.ts

@@ -0,0 +1,148 @@
+export const JPDCL_TARIFF_ORDER_2025_26 = {
+  id: "JPDCL-JERC-FY2025-26-SUBSIDIZED",
+  title: "JPDCL & KPDCL ARR and Tariff for FY 2025-26 - Subsidized Tariff",
+  fiscalYear: "2025-26",
+  sourceUrl: "https://jpdcl.jk.gov.in/downloads/tariff/JPDCL_Tariff_Order_2025_26.pdf",
+  domesticSchedule: {
+    pdfPages: [159, 160],
+    printedPages: [139, 140],
+    energySlabs: [
+      { upToKwh: 200, ratePerKwh: 2.30 },
+      { upToKwh: 400, ratePerKwh: 4.00 },
+      { upToKwh: null, ratePerKwh: 4.35 },
+    ],
+    fixedChargePerKwMonth: 8.00,
+    loadRoundingKw: 0.5,
+  },
+  generalTerms: {
+    pdfPages: [176, 177, 178, 179, 180],
+    printedPages: [156, 157, 158, 159, 160],
+    prepaidEnergyRebatePercent: 2,
+    latePaymentPercentPerMonth: 1.5,
+    solarWaterHeaterRebatePerMonth: 150,
+  },
+} as const;
+
+export interface DomesticTariffInput {
+  unitsKwh: number;
+  sanctionedLoadKw: number;
+  prepaid?: boolean;
+  solarWaterHeaterEligible?: boolean;
+  electricityDutyAmount?: number;
+  otherChargesAmount?: number;
+  unpaidPrincipalAmount?: number;
+  lateMonths?: number;
+}
+
+export interface TariffSlabCharge {
+  fromKwh: number;
+  toKwh: number | null;
+  unitsKwh: number;
+  ratePerKwh: number;
+  amount: number;
+}
+
+export function calculateDomesticMeteredCharges(input: DomesticTariffInput) {
+  requireNonNegative("unitsKwh", input.unitsKwh);
+  requireNonNegative("sanctionedLoadKw", input.sanctionedLoadKw);
+  const billedUnitsKwh = Math.round(input.unitsKwh);
+  const billedLoadKw = Math.ceil(input.sanctionedLoadKw / 0.5) * 0.5;
+  const slabCharges = calculateSlabs(billedUnitsKwh);
+  const energyCharge = roundMoney(slabCharges.reduce((sum, slab) => sum + slab.amount, 0));
+  const fixedCharge = roundMoney(billedLoadKw * JPDCL_TARIFF_ORDER_2025_26.domesticSchedule.fixedChargePerKwMonth);
+  const prepaidRebate = input.prepaid
+    ? roundMoney(energyCharge * JPDCL_TARIFF_ORDER_2025_26.generalTerms.prepaidEnergyRebatePercent / 100)
+    : 0;
+  const solarWaterHeaterRebate = input.solarWaterHeaterEligible
+    ? JPDCL_TARIFF_ORDER_2025_26.generalTerms.solarWaterHeaterRebatePerMonth
+    : 0;
+  const electricityDuty = optionalMoney("electricityDutyAmount", input.electricityDutyAmount);
+  const otherCharges = optionalMoney("otherChargesAmount", input.otherChargesAmount);
+  const lateMonths = input.lateMonths ?? 0;
+  requireNonNegative("lateMonths", lateMonths);
+  const unpaidPrincipal = optionalMoney("unpaidPrincipalAmount", input.unpaidPrincipalAmount);
+  const latePaymentSurcharge = roundMoney(
+    unpaidPrincipal * lateMonths * JPDCL_TARIFF_ORDER_2025_26.generalTerms.latePaymentPercentPerMonth / 100,
+  );
+  const tariffSubtotal = roundMoney(Math.max(0, energyCharge + fixedCharge - prepaidRebate - solarWaterHeaterRebate));
+  const totalEstimate = roundMoney(tariffSubtotal + electricityDuty + otherCharges + latePaymentSurcharge);
+
+  return {
+    _meta: {
+      dataClass: "deterministic-calculation",
+      purpose: "estimate-not-utility-bill",
+      tariffOrderId: JPDCL_TARIFF_ORDER_2025_26.id,
+      formulaVersion: "1.0",
+    },
+    input: {
+      measuredUnitsKwh: input.unitsKwh,
+      billedUnitsKwh,
+      sanctionedLoadKw: input.sanctionedLoadKw,
+      billedLoadKw,
+      prepaid: Boolean(input.prepaid),
+      solarWaterHeaterEligible: Boolean(input.solarWaterHeaterEligible),
+    },
+    rates: {
+      energySlabs: JPDCL_TARIFF_ORDER_2025_26.domesticSchedule.energySlabs,
+      fixedChargePerKwMonth: JPDCL_TARIFF_ORDER_2025_26.domesticSchedule.fixedChargePerKwMonth,
+      prepaidEnergyRebatePercent: JPDCL_TARIFF_ORDER_2025_26.generalTerms.prepaidEnergyRebatePercent,
+      latePaymentPercentPerMonth: JPDCL_TARIFF_ORDER_2025_26.generalTerms.latePaymentPercentPerMonth,
+      solarWaterHeaterRebatePerMonth: JPDCL_TARIFF_ORDER_2025_26.generalTerms.solarWaterHeaterRebatePerMonth,
+    },
+    slabCharges,
+    charges: {
+      energyCharge,
+      fixedCharge,
+      prepaidRebate: -prepaidRebate,
+      solarWaterHeaterRebate: -solarWaterHeaterRebate,
+      tariffSubtotal,
+      electricityDuty,
+      otherCharges,
+      latePaymentSurcharge,
+      totalEstimate,
+      currency: "INR",
+    },
+    exclusions: [
+      "arrears and bill adjustments unless supplied as otherChargesAmount",
+      "electricity duty or government levy unless supplied as electricityDutyAmount",
+      "FPPCA or later tariff revision not present in the cited order",
+      "excess-demand charges unless assessed by JPDCL",
+      "meter defects, penalties, and utility-specific rounding or adjustments",
+    ],
+    source: JPDCL_TARIFF_ORDER_2025_26,
+  };
+}
+
+function calculateSlabs(unitsKwh: number): TariffSlabCharge[] {
+  const definitions = [
+    { fromKwh: 1, toKwh: 200, width: 200, ratePerKwh: 2.30 },
+    { fromKwh: 201, toKwh: 400, width: 200, ratePerKwh: 4.00 },
+    { fromKwh: 401, toKwh: null, width: Number.POSITIVE_INFINITY, ratePerKwh: 4.35 },
+  ] as const;
+  let remaining = unitsKwh;
+  return definitions.map((definition) => {
+    const slabUnits = Math.max(0, Math.min(remaining, definition.width));
+    remaining -= slabUnits;
+    return {
+      fromKwh: definition.fromKwh,
+      toKwh: definition.toKwh,
+      unitsKwh: slabUnits,
+      ratePerKwh: definition.ratePerKwh,
+      amount: roundMoney(slabUnits * definition.ratePerKwh),
+    };
+  }).filter((slab) => slab.unitsKwh > 0);
+}
+
+function optionalMoney(name: string, value: number | undefined): number {
+  if (value === undefined) return 0;
+  requireNonNegative(name, value);
+  return roundMoney(value);
+}
+
+function requireNonNegative(name: string, value: number): void {
+  if (!Number.isFinite(value) || value < 0) throw new TypeError(`${name} must be a non-negative finite number`);
+}
+
+function roundMoney(value: number): number {
+  return Math.round((value + Number.EPSILON) * 100) / 100;
+}

package/src/toolkit.test.ts

@@ -0,0 +1,136 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { endpointCatalog, listEndpoints } from "./catalog.js";
+import { decryptPayload, encryptPayload, ENCRYPTED_FIELD } from "./crypto.js";
+import { resolveCredentials } from "./credentials.js";
+import { assertDateRange, isIsoDate } from "./dates.js";
+import { buildUrl } from "./http.js";
+import { ledgerPeriod, parseLedgerHtml } from "./ledger-client.js";
+import { decodeJwt, encodeReportFilter, smartApiUrlFromAppUrl } from "./smart-client.js";
+import { calculateDomesticMeteredCharges } from "./tariff.js";
+
+describe("JPDCL protocol helpers", () => {
+  it("round-trips the portal AES envelope", () => {
+    const source = { accountid: "0000000000", nested: { enabled: true } };
+    const encrypted = encryptPayload(source)[ENCRYPTED_FIELD];
+    assert.equal(typeof encrypted, "string");
+    assert.deepEqual(decryptPayload(encrypted!), source);
+  });
+
+  it("fills path parameters and preserves query parameters", () => {
+    assert.equal(buildUrl("https://example.test/api", "/meter/{id}", { id: "A/B", from: "2026-01-01" }),
+      "https://example.test/api/meter/A%2FB?from=2026-01-01");
+  });
+
+  it("derives the API root and decodes SSO claims", () => {
+    const payload = Buffer.from(JSON.stringify({ currentAccountKno: "123", exp: 2_000_000_000 }), "utf8").toString("base64url");
+    assert.equal(decodeJwt(`x.${payload}.y`).currentAccountKno, "123");
+    assert.equal(smartApiUrlFromAppUrl("https://cp.example.test/dashboard"), "https://cp.example.test/api");
+  });
+
+  it("encodes the report filter exactly as the smart portal", () => {
+    const decoded = JSON.parse(Buffer.from(encodeReportFilter("2026-07-01", "2026-07-24", 1, 10), "base64").toString("utf8"));
+    assert.deepEqual(decoded, { start: 1, end: 10, filters: { createdDateFrom: "2026-07-01", createdDateTo: "2026-07-24" } });
+  });
+
+  it("rejects impossible or descending date ranges before a portal call", () => {
+    assert.equal(isIsoDate("2026-02-28"), true);
+    assert.equal(isIsoDate("2026-02-31"), false);
+    assert.throws(() => assertDateRange("2026-07-25", "2026-07-24"), /from must be on or before to/);
+    assert.throws(() => assertDateRange("2026-07-24", undefined, { pairedWhenPresent: true }), /both from and to/i);
+  });
+
+  it("resolves unattended credentials from the environment without persisting them", async () => {
+    const previousLogin = process.env.JPDCL_LOGIN_ID;
+    const previousPassword = process.env.JPDCL_PASSWORD;
+    try {
+      process.env.JPDCL_LOGIN_ID = "test-login";
+      process.env.JPDCL_PASSWORD = "test-password";
+      assert.deepEqual(await resolveCredentials(), {
+        loginId: "test-login",
+        password: "test-password",
+        source: "environment",
+      });
+    } finally {
+      if (previousLogin === undefined) delete process.env.JPDCL_LOGIN_ID;
+      else process.env.JPDCL_LOGIN_ID = previousLogin;
+      if (previousPassword === undefined) delete process.env.JPDCL_PASSWORD;
+      else process.env.JPDCL_PASSWORD = previousPassword;
+    }
+  });
+});
+
+describe("endpoint catalog", () => {
+  it("contains broad main and smart coverage", () => {
+    assert.ok(listEndpoints("main").length >= 40);
+    assert.ok(listEndpoints("smart").length >= 70);
+    assert.equal(listEndpoints("ledger").length, 2);
+  });
+
+  it("marks consequential actions as mutations", () => {
+    assert.equal(endpointCatalog.main_initiate_payment.mutation, true);
+    assert.equal(endpointCatalog.smart_on_demand_request.mutation, true);
+    assert.equal(endpointCatalog.smart_update_preferences.mutation, true);
+    assert.equal(endpointCatalog.smart_update_preferences.method, "PUT");
+    assert.equal(endpointCatalog.smart_update_alerts.method, "POST");
+    assert.notEqual(endpointCatalog.smart_today_monthly.mutation, true);
+    assert.equal(endpointCatalog.smart_today_monthly.dataClass, "observed");
+    assert.equal(endpointCatalog.smart_forecast_monthly.dataClass, "derived");
+    assert.equal(endpointCatalog.smart_insights.dataClass, "derived");
+    assert.equal(endpointCatalog.smart_page_content.dataClass, "advisory");
+  });
+});
+
+describe("daily smart-meter ledger", () => {
+  it("normalizes public cumulative registers and computes net-meter period deltas", () => {
+    const html = `<div class="row"><div class="col">Consumer ID</div><div class="col">123</div></div>
+      <div class="row"><div class="col">Smart Meter</div><input value="M1"></div>
+      <div class="row"><div class="col">Net Meter</div><div class="col">Yes</div></div>||||
+      <table id="readtable1"><tbody>
+      <tr><td>2026-07-02</td><td>120</td><td>45</td><td>75</td><td>125</td><td>46</td><td>79</td></tr>
+      <tr><td>2026-07-01</td><td>110</td><td>42</td><td>68</td><td>114</td><td>43</td><td>71</td></tr>
+      <tr><td>2026-06-30</td><td>100</td><td>40</td><td>60</td><td>104</td><td>41</td><td>63</td></tr>
+      </tbody></table>`;
+    const data = parseLedgerHtml(html, "123");
+    assert.equal(data.consumer.netMeter, true);
+    assert.equal(data.readings.length, 3);
+    const period = ledgerPeriod(data, { from: "2026-07-01", to: "2026-07-02", limit: 10 });
+    assert.equal(period.period.usage?.importKwh, 20);
+    assert.equal(period.period.usage?.exportKwh, 5);
+    assert.equal(period.period.provisionalBillableKwh, 15);
+    assert.equal(period.readings[0]?.usageSincePreviousObservation?.netImportKwh, 7);
+  });
+});
+
+describe("FY 2025-26 domestic tariff", () => {
+  it("matches the user's actual recent bill components", () => {
+    const estimate = calculateDomesticMeteredCharges({ unitsKwh: 98, sanctionedLoadKw: 0.5 });
+    assert.equal(estimate.charges.energyCharge, 225.4);
+    assert.equal(estimate.charges.fixedCharge, 4);
+    assert.equal(estimate.charges.totalEstimate, 229.4);
+  });
+
+  it("applies progressive slabs and load rounding", () => {
+    assert.equal(calculateDomesticMeteredCharges({ unitsKwh: 220, sanctionedLoadKw: 0.5 }).charges.totalEstimate, 544);
+    assert.equal(calculateDomesticMeteredCharges({ unitsKwh: 240, sanctionedLoadKw: 0.5 }).charges.totalEstimate, 624);
+    const estimate = calculateDomesticMeteredCharges({ unitsKwh: 500, sanctionedLoadKw: 3 });
+    assert.equal(estimate.charges.energyCharge, 1695);
+    assert.equal(estimate.charges.fixedCharge, 24);
+    assert.equal(estimate.charges.totalEstimate, 1719);
+  });
+
+  it("applies only explicitly eligible rebates and additional charges", () => {
+    const estimate = calculateDomesticMeteredCharges({
+      unitsKwh: 100,
+      sanctionedLoadKw: 0.6,
+      prepaid: true,
+      electricityDutyAmount: 5,
+      unpaidPrincipalAmount: 1000,
+      lateMonths: 2,
+    });
+    assert.equal(estimate.charges.prepaidRebate, -4.6);
+    assert.equal(estimate.charges.fixedCharge, 8);
+    assert.equal(estimate.charges.latePaymentSurcharge, 30);
+    assert.equal(estimate.charges.totalEstimate, 268.4);
+  });
+});

package/src/types.ts

@@ -0,0 +1,51 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
+export type JsonObject = { [key: string]: JsonValue };
+
+export interface PortalResponse<T = unknown> {
+  status?: boolean | number | string;
+  message?: string;
+  data?: T;
+  [key: string]: unknown;
+}
+
+export interface MainSession {
+  version: 1;
+  createdAt: string;
+  updatedAt: string;
+  cookies: string;
+  loginId?: string;
+  primaryAccountId?: string;
+  consumerCode?: string;
+  user?: Record<string, unknown>;
+  smart?: {
+    token: string;
+    baseUrl: string;
+    appUrl?: string;
+    tenantId?: string;
+    accountId?: string;
+    meterNumber?: string;
+    userId?: string;
+    expiresAt?: string;
+  };
+}
+
+export interface EndpointDefinition {
+  portal: "main" | "smart" | "ledger";
+  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+  path: string;
+  encrypted?: boolean;
+  auth: "public" | "public-basic" | "main-session" | "smart-bearer" | "smart-admin" | "external-basic";
+  mutation?: boolean;
+  binary?: boolean;
+  dataClass?: "observed" | "derived" | "advisory" | "configuration" | "transactional";
+  description: string;
+  parameters?: string[];
+  bodyExample?: Record<string, unknown>;
+}
+
+export interface RequestOptions {
+  params?: Record<string, string | number | boolean | null | undefined>;
+  body?: unknown;
+  headers?: Record<string, string>;
+}

package/src/worker.ts

@@ -0,0 +1,3 @@
+import { handleMcpRequest } from "./http-handler.js";
+
+export default { fetch: handleMcpRequest };

package/tsconfig.build.json

@@ -0,0 +1,11 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "sourceMap": true,
+    "declaration": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/**/*.test.ts"]
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022", "DOM"],
+    "strict": true,
+    "declaration": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "noUncheckedIndexedAccess": true,
+    "outDir": "dist"
+  },
+  "include": ["src", "test"]
+}