jpdcl 1.0.0

package/src/runtime.ts

@@ -0,0 +1,329 @@
+import { JpdclError } from "./errors.js";
+import { resolveCredentials, type Credentials } from "./credentials.js";
+import { MAIN_API_URL, mutationsEnabled } from "./config.js";
+import { JpdclClient } from "./main-client.js";
+import { JpdclLedgerClient, ledgerPeriod, type LedgerPeriodOptions } from "./ledger-client.js";
+import { loadSession, saveSession } from "./session.js";
+import { decodeJwt, SmartMeterClient, smartApiUrlFromAppUrl } from "./smart-client.js";
+import { calculateDomesticMeteredCharges, type DomesticTariffInput } from "./tariff.js";
+import type { MainSession, PortalResponse } from "./types.js";
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+export class JpdclRuntime {
+  readonly main: JpdclClient;
+  readonly ledger = new JpdclLedgerClient();
+  smart?: SmartMeterClient;
+
+  private constructor(
+    session: MainSession | undefined,
+    private readonly options: {
+      credentials?: Credentials;
+      persistent: boolean;
+      allowMutations: boolean;
+    },
+  ) {
+    this.main = new JpdclClient(
+      session,
+      MAIN_API_URL,
+      options.allowMutations,
+      options.credentials,
+      options.persistent ? saveSession : async () => {},
+    );
+    if (session?.smart?.token) {
+      this.smart = new SmartMeterClient(session.smart.token, session.smart.baseUrl, options.allowMutations, session.smart.tenantId);
+    }
+  }
+
+  static async create(options: {
+    credentials?: Credentials;
+    session?: MainSession;
+    persistent?: boolean;
+    allowMutations?: boolean;
+  } = {}): Promise<JpdclRuntime> {
+    const persistent = options.persistent ?? true;
+    const session = options.session ?? (persistent ? await loadSession() : undefined);
+    return new JpdclRuntime(session, {
+      credentials: options.credentials,
+      persistent,
+      allowMutations: options.allowMutations ?? mutationsEnabled(),
+    });
+  }
+
+  async login(loginId: string, password: string): Promise<PortalResponse> {
+    const response = await this.main.login(loginId, password);
+    await this.persist();
+    return response;
+  }
+
+  async persist(): Promise<void> {
+    if (!this.options.persistent) return;
+    const session = this.main.currentSession;
+    if (!session) return;
+    if (this.smart?.bearerToken) {
+      session.smart = {
+        token: this.smart.bearerToken,
+        baseUrl: this.smart.baseUrl,
+        tenantId: this.smart.effectiveTenantId,
+        accountId: this.smart.accountId,
+        meterNumber: this.smart.meterNumber,
+        userId: typeof this.smart.claims.sub === "string" ? this.smart.claims.sub : undefined,
+        expiresAt: this.smart.expiresAt,
+      };
+    }
+    await saveSession(session);
+  }
+
+  async ensureLogin(): Promise<void> {
+    if (this.main.currentSession) return;
+    const credentials = this.options.credentials ?? await resolveCredentials();
+    if (!credentials) {
+      throw new JpdclError("Run `jpdcl auth login` or set JPDCL_LOGIN_ID and JPDCL_PASSWORD", 401);
+    }
+    await this.login(credentials.loginId, credentials.password);
+  }
+
+  async ensureSmart(accountId?: string, meterNumber?: string): Promise<SmartMeterClient> {
+    const smartMatches = this.smart?.bearerToken
+      && (!accountId || accountId === this.smart.accountId)
+      && (!meterNumber || meterNumber === this.smart.meterNumber)
+      && (!this.smart.expiresAt || new Date(this.smart.expiresAt).getTime() > Date.now() + 30_000);
+    if (smartMatches) return this.smart!;
+    await this.ensureLogin();
+    const customer = await this.main.customerInfo(accountId);
+    const customerData = record(customer.data) ?? {};
+    const resolvedAccount = accountId ?? this.main.currentSession?.primaryAccountId;
+    const resolvedMeter = meterNumber ?? String(
+      customerData.mtrSrNum ?? customerData.meterNumber ?? customerData.meterNo ?? "",
+    );
+    if (!resolvedAccount || !resolvedMeter) throw new JpdclError("Account ID and meter number are required", 400);
+    const sso = await this.main.smartSso(resolvedAccount, resolvedMeter);
+    const ssoData = record(sso.data) ?? {};
+    const jwt = ssoData.jwt;
+    if (typeof jwt !== "string") throw new JpdclError(sso.message ?? "JPDCL did not issue a smart-meter token", 502, sso);
+    const appUrl = typeof ssoData.app_url === "string" ? ssoData.app_url : undefined;
+    const claims = decodeJwt(jwt);
+    const tenantId = typeof claims.currentAccountTenantId === "string" ? claims.currentAccountTenantId : undefined;
+    this.smart = new SmartMeterClient(jwt, smartApiUrlFromAppUrl(appUrl), this.options.allowMutations, tenantId);
+    await this.persist();
+    return this.smart;
+  }
+
+  async aiSnapshot(accountId?: string): Promise<Record<string, unknown>> {
+    await this.ensureLogin();
+    const main = await this.main.digest(accountId);
+    const resolvedAccount = accountId ?? this.main.currentSession?.primaryAccountId;
+    const errors: Array<{ source: string; message: string }> = [];
+    const [smartResult, ledgerResult, tariffResult] = await Promise.all([
+      capture((async () => {
+      const client = await this.ensureSmart(resolvedAccount);
+        return (await client.dashboard(resolvedAccount, { includeDerived: false })).data;
+      })()),
+      capture(this.energyLedger(resolvedAccount, { limit: 7 })),
+      capture(this.tariffEstimate(resolvedAccount)),
+    ]);
+    if (!smartResult.ok) errors.push({ source: "smart-meter", message: smartResult.error });
+    if (!ledgerResult.ok) errors.push({ source: "daily-meter-ledger", message: ledgerResult.error });
+    if (!tariffResult.ok) errors.push({ source: "tariff-calculation", message: tariffResult.error });
+    const smart = smartResult.ok ? smartResult.value : null;
+    const ledger = ledgerResult.ok ? ledgerResult.value : null;
+    const tariff = tariffResult.ok ? tariffResult.value : null;
+    await this.persist();
+    return {
+      schemaVersion: "1.0",
+      generatedAt: new Date().toISOString(),
+      dataPolicy: {
+        mode: "observed-plus-deterministic-calculations",
+        excludes: ["forecasts", "recommendations", "energy-saving tips", "smartTips"],
+        calculated: [
+          "daily and period usage from cumulative register subtraction",
+          "provisional billable kWh from the net-import register for net-meter accounts",
+          "tariff estimate from observed kWh and official published rates",
+        ],
+      },
+      identity: {
+        accountId: resolvedAccount ?? null,
+        meterNumber: this.smart?.meterNumber ?? record(main.meter)?.number ?? null,
+        plan: this.smart ? (String(this.smart.claims.currentAccountIsMeterPrepaid).toLowerCase() === "true" ? "prepaid" : "postpaid") : null,
+      },
+      sources: {
+        mainPortal: { available: true, kind: "account-and-billing-records" },
+        smartMeter: { available: smart !== null, kind: "meter-and-consumer-api-records" },
+        dailyMeterLedger: { available: ledger !== null, kind: "daily-import-export-registers" },
+      },
+      data: { main, smart, ledger, tariff },
+      errors,
+    };
+  }
+
+  async tariffEstimate(accountId?: string, overrides: Partial<DomesticTariffInput> = {}): Promise<Record<string, unknown>> {
+    await this.ensureLogin();
+    const customerResponse = await this.main.customerInfo(accountId);
+    const customer = record(customerResponse.data) ?? {};
+    const resolvedAccount = accountId ?? this.main.currentSession?.primaryAccountId;
+    const category = String(customer.consumerType ?? customer.saTypeCd ?? customer.category ?? "").toUpperCase();
+    if (!category.includes("DOM") && category !== "1") {
+      throw new JpdclError(`Automatic tariff calculation currently supports domestic metered accounts; portal category is ${category || "unknown"}`, 422);
+    }
+    const sanctionedLoadKw = overrides.sanctionedLoadKw ?? Number(customer.sanctionedLoad);
+    if (!Number.isFinite(sanctionedLoadKw)) throw new JpdclError("The portal did not provide a valid sanctioned load", 422);
+
+    let unitsKwh = overrides.unitsKwh;
+    let usageSource: Record<string, unknown> = { kind: "manual" };
+    if (unitsKwh === undefined) {
+      const consumerId = String(customer.consumerID ?? "");
+      try {
+        const daily = await this.ledger.consumer(consumerId);
+        const period = ledgerPeriod(daily, { limit: 0 });
+        const periodRecord = record(period.period) ?? {};
+        unitsKwh = Number(periodRecord.provisionalBillableKwh);
+        usageSource = {
+          kind: "daily-register-ledger",
+          endpoint: "ledger_consumer_readings",
+          netMeter: daily.consumer.netMeter,
+          basis: periodRecord.provisionalBillableBasis,
+          from: periodRecord.from,
+          to: periodRecord.to,
+          latestObservation: periodRecord.latestObservation,
+          warning: periodRecord.warning,
+        };
+      } catch (ledgerError) {
+        const client = await this.ensureSmart(resolvedAccount);
+        if (!client.meterNumber) throw new JpdclError("The smart-meter number is unavailable", 422);
+        const usage = await client.request("smart_today_monthly", { params: { meterNumber: client.meterNumber } });
+        const usageData = record(usage.data) ?? {};
+        unitsKwh = Number(usageData.monthlyConsumption);
+        usageSource = {
+          kind: "smart-meter-current-month-fallback",
+          endpoint: "smart_today_monthly",
+          latestDate: usageData.latestDate ?? null,
+          unit: usageData.unit ?? "kWh",
+          ledgerError: ledgerError instanceof Error ? ledgerError.message : String(ledgerError),
+        };
+      }
+    }
+    if (!Number.isFinite(unitsKwh)) throw new JpdclError("The portal did not provide valid current-month consumption; pass unitsKwh explicitly", 422);
+    const prepaid = overrides.prepaid ?? String(customer.postOrPre ?? "").toUpperCase().includes("PREPAID");
+    const calculation = calculateDomesticMeteredCharges({
+      ...overrides,
+      unitsKwh,
+      sanctionedLoadKw,
+      prepaid,
+    });
+    return {
+      generatedAt: new Date().toISOString(),
+      account: {
+        accountId: resolvedAccount ?? null,
+        portalCategory: customer.consumerType ?? customer.saTypeCd ?? customer.category ?? null,
+        mappedTariff: "Domestic Supply - Metered Consumer",
+        plan: prepaid ? "prepaid" : "postpaid",
+        consumerId: customer.consumerID ?? null,
+      },
+      usageSource,
+      ...calculation,
+    };
+  }
+
+  async energyLedger(accountId?: string, options: LedgerPeriodOptions = {}): Promise<Record<string, unknown>> {
+    await this.ensureLogin();
+    const customer = record((await this.main.customerInfo(accountId)).data) ?? {};
+    const consumerId = String(customer.consumerID ?? "");
+    if (!consumerId) throw new JpdclError("The main portal did not provide a consumer ID", 422);
+    const data = await this.ledger.consumer(consumerId);
+    return ledgerPeriod(data, options);
+  }
+
+  async meterHealth(accountId?: string): Promise<Record<string, unknown>> {
+    await this.ensureLogin();
+    const customer = record((await this.main.customerInfo(accountId)).data) ?? {};
+    const resolvedAccount = accountId ?? this.main.currentSession?.primaryAccountId;
+    if (!resolvedAccount) throw new JpdclError("An account ID is required", 400);
+    const consumerId = String(customer.consumerID ?? "");
+    const client = await this.ensureSmart(resolvedAccount);
+    if (!client.meterNumber) throw new JpdclError("The smart-meter number is unavailable", 422);
+    const today = new Date().toISOString().slice(0, 10);
+    const from = new Date(Date.now() - 7 * 86_400_000).toISOString().slice(0, 10);
+    const [connection, onDemand, onDemandLogs, voltage, powerEvents, ledger, alarms] = await Promise.all([
+      capture(this.main.request("main_meter_status", { body: { account_id: resolvedAccount } })),
+      capture(client.request("smart_meter_reading", { params: { meterNumber: client.meterNumber } })),
+      capture(client.request("smart_on_demand_logs", { params: { meterNumber: client.meterNumber } })),
+      capture(client.report("ConsumerVoltageDataProfile", resolvedAccount, { from, to: today, start: 1, end: 100 })),
+      capture(client.report("PowerOnOff", resolvedAccount, { from, to: today, start: 1, end: 100 })),
+      capture(consumerId ? this.ledger.consumer(consumerId) : Promise.reject(new Error("Consumer ID unavailable"))),
+      capture(this.ledger.alarms(client.meterNumber)),
+    ]);
+    const connectionData = recordResponseData(connection);
+    const demandData = recordResponseData(onDemand);
+    const demandReadings = Array.isArray(demandData?.data) ? demandData.data : [];
+    const demandStatus = Number(demandData?.status);
+    const logsData = responseData(onDemandLogs);
+    const latestLog = Array.isArray(logsData) ? logsData[0] : null;
+    const voltageEnvelope = record(responseData(voltage));
+    const voltageRows = Array.isArray(voltageEnvelope?.data) ? voltageEnvelope.data : [];
+    const powerEnvelope = record(responseData(powerEvents));
+    const powerRows = Array.isArray(powerEnvelope?.data) ? powerEnvelope.data : [];
+    const ledgerData = ledger.ok ? ledger.value : undefined;
+    return {
+      _meta: {
+        dataClass: "observed-status-with-explicit-inferences",
+        generatedAt: new Date().toISOString(),
+        networkConnectivity: "not directly exposed by any consumer endpoint",
+      },
+      identity: { accountId: resolvedAccount, consumerId, meterNumber: client.meterNumber },
+      supply: {
+        state: connectionData?.meterConnectionStatus ?? null,
+        asOf: connectionData?.currentDate ?? null,
+        source: "main_meter_status",
+      },
+      communication: {
+        explicitOnlineStatus: null,
+        onDemandRequestAllowed: typeof demandData?.isRequestAllowed === "boolean" ? demandData.isRequestAllowed : null,
+        onDemandStatus: Number.isFinite(demandStatus) ? ({ 1: "pending", 2: "failed", 3: "completed" } as Record<number, string>)[demandStatus] ?? "unknown" : null,
+        latestRequest: latestLog,
+      },
+      instantaneousReadings: {
+        source: "smart_meter_reading/on-demand",
+        readings: demandReadings,
+        warning: "These are the latest on-demand values returned by the utility, not a continuous stream.",
+      },
+      voltageProfile: {
+        source: "ConsumerVoltageDataProfile",
+        latest: voltageRows[0] ?? null,
+        recordCount: voltageRows.length,
+      },
+      powerEvents: {
+        source: "PowerOnOff",
+        latest: powerRows[0] ?? null,
+        openEvent: powerRows.some((event) => event && typeof event === "object" && !(event as Record<string, unknown>).powerOffEnd),
+        recordCount: powerRows.length,
+      },
+      dailyLedger: ledgerData && typeof ledgerData === "object" && "readings" in ledgerData ? {
+        latest: (ledgerData as { readings: unknown[] }).readings[0] ?? null,
+        totalRecords: (ledgerData as { readings: unknown[] }).readings.length,
+      } : null,
+      alarms: alarms.ok ? alarms.value : { unavailable: true, error: alarms.error },
+      sourceErrors: [connection, onDemand, onDemandLogs, voltage, powerEvents, ledger, alarms]
+        .filter((result) => !result.ok)
+        .map((result) => result.error),
+    };
+  }
+}
+
+async function capture<T>(promise: Promise<T>): Promise<{ ok: true; value: T } | { ok: false; error: string }> {
+  try { return { ok: true, value: await promise }; }
+  catch (error) { return { ok: false, error: error instanceof Error ? error.message : String(error) }; }
+}
+
+function responseData(result: { ok: true; value: unknown } | { ok: false; error: string }): unknown {
+  if (!result.ok) return undefined;
+  const value = record(result.value);
+  return value && "data" in value ? value.data : result.value;
+}
+
+function recordResponseData(result: { ok: true; value: unknown } | { ok: false; error: string }): Record<string, unknown> | undefined {
+  return record(responseData(result));
+}

package/src/server.ts

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+import { serve } from "@hono/node-server";
+import { Hono } from "hono";
+import fs from "node:fs/promises";
+import { endpointCatalog, isEndpointName, listEndpoints } from "./catalog.js";
+import { credentialStatus } from "./credentials.js";
+import { JpdclError } from "./errors.js";
+import { JpdclRuntime } from "./runtime.js";
+import { JPDCL_TARIFF_ORDER_2025_26, type DomesticTariffInput } from "./tariff.js";
+
+const app = new Hono();
+const runtime = await JpdclRuntime.create();
+const openApiDocument = await fs.readFile(new URL("../openapi.yaml", import.meta.url), "utf8");
+
+app.use("/v1/*", async (c, next) => {
+  const configuredKey = process.env.JPDCL_API_KEY;
+  if (configuredKey && c.req.header("authorization") !== `Bearer ${configuredKey}`) {
+    return c.json({ error: "Unauthorized" }, 401);
+  }
+  await next();
+});
+
+app.onError((error, c) => {
+  const known = error instanceof JpdclError;
+  return c.json({
+    error: known ? error.name : "InternalError",
+    message: error.message,
+    details: known ? error.details : undefined,
+  }, (known && error.status && error.status >= 400 && error.status <= 599 ? error.status : 500) as 400);
+});
+
+app.get("/health", (c) => c.json({ status: "ok", service: "jpdcl-api", version: "1.0.0" }));
+app.get("/", (c) => c.json({ service: "jpdcl-api", health: "/health", openapi: "/openapi.yaml", catalog: "/v1/catalog" }));
+app.get("/openapi.yaml", (c) => c.text(openApiDocument, 200, { "Content-Type": "application/yaml; charset=utf-8" }));
+app.get("/v1/catalog", (c) => c.json(listEndpoints(c.req.query("portal") as "main" | "smart" | "ledger" | undefined)));
+app.get("/v1/tariff", (c) => c.json(JPDCL_TARIFF_ORDER_2025_26));
+
+app.post("/v1/auth/login", async (c) => {
+  const body = await c.req.json<{ loginId?: string; password?: string }>();
+  if (!body.loginId || !body.password) throw new JpdclError("loginId and password are required", 400);
+  const result = await runtime.login(body.loginId, body.password);
+  return c.json({ status: result.status, message: result.message ?? "Login successful" });
+});
+
+app.get("/v1/me", async (c) => {
+  await runtime.ensureLogin();
+  const session = runtime.main.currentSession;
+  const automatic = await credentialStatus();
+  return c.json({
+    loginId: session?.loginId,
+    primaryAccountId: session?.primaryAccountId,
+    smartAuthenticated: Boolean(session?.smart),
+    smartExpiresAt: session?.smart?.expiresAt,
+    automaticRelogin: automatic.automaticRelogin,
+    credentialSource: automatic.source,
+  });
+});
+app.get("/v1/snapshot", async (c) => c.json(await runtime.aiSnapshot(c.req.query("accountId"))));
+app.get("/v1/accounts/:accountId", async (c) => {
+  await runtime.ensureLogin();
+  return c.json(await runtime.main.customerInfo(c.req.param("accountId")));
+});
+app.get("/v1/accounts/:accountId/digest", async (c) => {
+  await runtime.ensureLogin();
+  return c.json(await runtime.main.digest(c.req.param("accountId")));
+});
+app.get("/v1/accounts/:accountId/bills", async (c) => {
+  await runtime.ensureLogin();
+  return c.json(await runtime.main.history("BILL", c.req.param("accountId"), c.req.query("from"), c.req.query("to")));
+});
+app.get("/v1/accounts/:accountId/payments", async (c) => {
+  await runtime.ensureLogin();
+  return c.json(await runtime.main.history("PAYM", c.req.param("accountId"), c.req.query("from"), c.req.query("to")));
+});
+app.get("/v1/accounts/:accountId/consumption", async (c) => {
+  await runtime.ensureLogin();
+  return c.json(await runtime.main.consumption(c.req.param("accountId"), c.req.query("from"), c.req.query("to")));
+});
+app.get("/v1/accounts/:accountId/tariff-estimate", async (c) => {
+  const query = c.req.query();
+  const overrides: Partial<DomesticTariffInput> = {};
+  assignQueryNumber(overrides, "unitsKwh", query.units);
+  assignQueryNumber(overrides, "sanctionedLoadKw", query.load);
+  assignQueryNumber(overrides, "electricityDutyAmount", query.electricityDuty);
+  assignQueryNumber(overrides, "otherChargesAmount", query.otherCharges);
+  assignQueryNumber(overrides, "unpaidPrincipalAmount", query.unpaidPrincipal);
+  assignQueryNumber(overrides, "lateMonths", query.lateMonths);
+  if (query.prepaid !== undefined) overrides.prepaid = query.prepaid === "true";
+  if (query.solarWaterHeaterEligible !== undefined) overrides.solarWaterHeaterEligible = query.solarWaterHeaterEligible === "true";
+  return c.json(await runtime.tariffEstimate(c.req.param("accountId"), overrides));
+});
+app.get("/v1/accounts/:accountId/energy-ledger", async (c) => {
+  const limit = c.req.query("limit") === undefined ? 35 : Number(c.req.query("limit"));
+  if (!Number.isInteger(limit) || limit < 0 || limit > 500) throw new JpdclError("limit must be an integer from 0 to 500", 400);
+  return c.json(await runtime.energyLedger(c.req.param("accountId"), {
+    from: c.req.query("from"),
+    to: c.req.query("to"),
+    limit,
+  }));
+});
+app.get("/v1/accounts/:accountId/meter-health", async (c) => {
+  return c.json(await runtime.meterHealth(c.req.param("accountId")));
+});
+app.get("/v1/accounts/:accountId/meter-changes", async (c) => {
+  await runtime.ensureLogin();
+  return c.json(await runtime.main.request("main_meter_changes", { body: { accountid: c.req.param("accountId") } }));
+});
+app.get("/v1/linked-accounts", async (c) => {
+  await runtime.ensureLogin();
+  return c.json(await runtime.main.linkedAccounts());
+});
+
+app.get("/v1/smart/session", async (c) => c.json(await (await runtime.ensureSmart()).connections()));
+app.get("/v1/smart/accounts/:accountId/dashboard", async (c) => {
+  const accountId = c.req.param("accountId");
+  return c.json(await (await runtime.ensureSmart(accountId)).dashboard(accountId, {
+    includeDerived: c.req.query("includeDerived") === "true",
+  }));
+});
+app.get("/v1/smart/accounts/:accountId/meter", async (c) => {
+  const accountId = c.req.param("accountId");
+  const client = await runtime.ensureSmart(accountId);
+  if (!client.meterNumber) throw new JpdclError("Smart-meter number is unavailable", 400);
+  const [details, reading] = await Promise.all([
+    client.request("smart_meter_details", { params: { meterNumber: client.meterNumber } }),
+    client.request("smart_current_meter_reading", { params: { accountId } }),
+  ]);
+  return c.json({ details: details.data, currentReading: reading.data });
+});
+app.get("/v1/smart/accounts/:accountId/alerts", async (c) => {
+  const accountId = c.req.param("accountId");
+  const client = await runtime.ensureSmart(accountId);
+  if (!client.meterNumber) throw new JpdclError("Smart-meter number is unavailable", 400);
+  return c.json(await client.request("smart_my_alerts", { params: { accountId, meterNumber: client.meterNumber } }));
+});
+app.get("/v1/smart/accounts/:accountId/preferences", async (c) => {
+  const client = await runtime.ensureSmart(c.req.param("accountId"));
+  const isPrepaid = String(client.claims.currentAccountIsMeterPrepaid).toLowerCase() === "true";
+  return c.json(await client.request("smart_preferences", { params: { isPrepaid } }));
+});
+app.get("/v1/smart/accounts/:accountId/notifications", async (c) => {
+  const client = await runtime.ensureSmart(c.req.param("accountId"));
+  const userId = typeof client.claims.sub === "string" ? client.claims.sub : undefined;
+  if (!userId) throw new JpdclError("Smart user ID is unavailable", 400);
+  const [items, unread] = await Promise.all([
+    client.request("smart_notifications", { params: { userId } }).catch(() => ({ status: true, data: [] })),
+    client.request("smart_notification_unread_count", { params: { userId } }).catch(() => ({ status: true, data: { unreadCount: 0 } })),
+  ]);
+  return c.json({ items: items.data, unread: unread.data });
+});
+app.get("/v1/smart/accounts/:accountId/support", async (c) => {
+  const client = await runtime.ensureSmart(c.req.param("accountId"));
+  const userId = typeof client.claims.sub === "string" ? client.claims.sub : undefined;
+  if (!userId) throw new JpdclError("Smart user ID is unavailable", 400);
+  const [faqs, contact, categories, complaints] = await Promise.all([
+    client.request("smart_faqs"), client.request("smart_contact_support").catch(() => ({ status: true, data: null })), client.request("smart_complaint_categories"),
+    client.request("smart_complaints", { params: { userId, pageNumber: Number(c.req.query("page") ?? 1), pageSize: Number(c.req.query("pageSize") ?? 20), statusCodes: c.req.query("statusCodes") } }),
+  ]);
+  return c.json({ faqs: faqs.data, contact: contact.data, categories: categories.data, complaints: complaints.data });
+});
+app.get("/v1/smart/accounts/:accountId/consumption", async (c) => {
+  const accountId = c.req.param("accountId");
+  return c.json(await (await runtime.ensureSmart(accountId)).consumption(accountId, c.req.query("type") ?? "monthly", Number(c.req.query("value") ?? 12)));
+});
+app.get("/v1/smart/accounts/:accountId/intervals", async (c) => {
+  const accountId = c.req.param("accountId");
+  const from = c.req.query("from");
+  const to = c.req.query("to");
+  if (!from || !to) throw new JpdclError("from and to (YYYY-MM-DD) are required", 400);
+  return c.json(await (await runtime.ensureSmart(accountId)).intervalConsumption(accountId, from, to, c.req.query("sort") ?? "date"));
+});
+app.get("/v1/smart/accounts/:accountId/reports/:reportType", async (c) => {
+  const accountId = c.req.param("accountId");
+  return c.json(await (await runtime.ensureSmart(accountId)).report(c.req.param("reportType") as never, accountId, {
+    from: c.req.query("from"),
+    to: c.req.query("to"),
+    start: c.req.query("start") ? Number(c.req.query("start")) : undefined,
+    end: c.req.query("end") ? Number(c.req.query("end")) : undefined,
+    filter: c.req.query("filter"),
+    format: c.req.query("format") as "xlsx" | "pdf" | undefined,
+  }));
+});
+
+app.all("/v1/raw/:endpoint", async (c) => {
+  const name = c.req.param("endpoint");
+  if (!isEndpointName(name)) throw new JpdclError(`Unknown endpoint: ${name}`, 404);
+  const requestUrl = new URL(c.req.url);
+  const input = c.req.method === "GET"
+    ? { params: Object.fromEntries(requestUrl.searchParams.entries()), confirm: requestUrl.searchParams.get("confirm") === "true" }
+    : await c.req.json<{ params?: Record<string, string>; body?: unknown; confirm?: boolean }>();
+  const definition = endpointCatalog[name];
+  if (definition.mutation && !input.confirm) {
+    throw new JpdclError("Mutating endpoints require confirm=true and JPDCL_ENABLE_MUTATIONS=true", 400);
+  }
+  if (input.params) delete input.params.confirm;
+  const result = definition.portal === "main"
+    ? await runtime.main.request(name, input)
+    : definition.portal === "smart"
+      ? await (await runtime.ensureSmart()).request(name, input)
+      : await runtime.ledger.request(name, input);
+  await runtime.persist();
+  return c.json(result);
+});
+
+const port = Number(process.env.JPDCL_API_PORT ?? 8787);
+const hostname = process.env.JPDCL_API_HOST ?? "127.0.0.1";
+serve({ fetch: app.fetch, port, hostname }, (info) => {
+  process.stderr.write(`JPDCL API listening on http://${hostname}:${info.port}\n`);
+});
+
+export { app };
+
+function assignQueryNumber<T extends object, K extends keyof T>(target: T, key: K, raw: string | undefined): void {
+  if (raw === undefined) return;
+  const value = Number(raw);
+  if (!Number.isFinite(value) || value < 0) throw new JpdclError(`${String(key)} must be a non-negative number`, 400);
+  target[key] = value as T[K];
+}

package/src/session.ts

@@ -0,0 +1,29 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { defaultSessionFile } from "./config.js";
+import type { MainSession } from "./types.js";
+
+export async function loadSession(file = defaultSessionFile): Promise<MainSession | undefined> {
+  try {
+    return JSON.parse(await fs.readFile(file, "utf8")) as MainSession;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+export async function saveSession(session: MainSession, file = defaultSessionFile): Promise<void> {
+  await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${process.pid}.tmp`;
+  await fs.writeFile(temporary, JSON.stringify(session, null, 2), { mode: 0o600 });
+  await fs.rename(temporary, file);
+  await fs.chmod(file, 0o600);
+}
+
+export async function clearSession(file = defaultSessionFile): Promise<void> {
+  try {
+    await fs.unlink(file);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+}