node-chargepoint 0.3.5 → 0.4.0

package/README.md

@@ -289,172 +289,18 @@ for (const s of filtered) {
 
 ## CLI
 
-After installation, a `chargepoint` command is available.
-
-### Authentication
-
-Credentials are read from environment variables:
-
-```bash
-export CP_USERNAME="user@example.com"
-export CP_TOKEN="<coulomb_sess cookie value>"
-# or use --password / CP_PASSWORD for password-based login
-```
-
-### Commands
-
-```bash
-# Show account info
-chargepoint -u user@example.com -t $CP_TOKEN account
-
-# List registered vehicles
-chargepoint -u user@example.com -t $CP_TOKEN vehicles
-
-# Show current charging session status
-chargepoint -u user@example.com -t $CP_TOKEN status
-
-# List home charger IDs
-chargepoint -u user@example.com -t $CP_TOKEN chargers
-
-# Start a charging session on a device
-chargepoint -u user@example.com -t $CP_TOKEN start <deviceId>
-
-# Show details for a charging station
-chargepoint -u user@example.com -t $CP_TOKEN station <deviceId>
-```
-
-Global options:
-
-```
--u, --username <username>   ChargePoint username (or set CP_USERNAME)
--t, --token <token>         Coulomb session token (or set CP_TOKEN)
--p, --password <password>   Password login fallback (or set CP_PASSWORD)
--V, --version               Print version
--h, --help                  Display help
-```
+See [docs/cli.md](docs/cli.md) for usage, commands, and global options.
 
 ---
 
 ## Error Handling
 
-```typescript
-import {
-  ChargePoint,
-  LoginError,
-  InvalidSession,
-  DatadomeCaptcha,
-  CommunicationError,
-  APIError,
-} from 'node-chargepoint';
-
-try {
-  await client.loginWithPassword('bad-password');
-} catch (err) {
-  if (err instanceof LoginError) {
-    console.error('Wrong credentials');
-  } else if (err instanceof InvalidSession) {
-    console.error('Session expired — re-authenticate');
-  } else if (err instanceof DatadomeCaptcha) {
-    console.error('Bot protection triggered:', err.captchaUrl);
-  } else if (err instanceof CommunicationError) {
-    console.error(`API error ${err.statusCode}:`, err.message);
-  }
-}
-```
-
-**Error hierarchy:**
-
-```
-APIError
-├── CommunicationError     (non-2xx response)
-│   ├── LoginError         (authentication failed)
-│   └── InvalidSession     (session expired — HTTP 401)
-└── DatadomeCaptcha        (Datadome bot protection — HTTP 403)
-```
+See [docs/error-handling.md](docs/error-handling.md) for the error class hierarchy and handling examples.
 
 ---
 
 ## Development
 
-### Setup
-
-```bash
-git clone https://github.com/musicbender/node-chargepoint.git
-cd node-chargepoint
-pnpm install
-```
-
-### Type checking
-
-```bash
-pnpm typecheck
-```
-
-### Tests
-
-```bash
-pnpm test
-```
-
-Tests use [Vitest](https://vitest.dev/) and [MSW](https://mswjs.io/) to intercept `fetch` calls. No real network traffic is made during tests.
-
-### E2E Tests
-
-An optional E2E suite runs against the live ChargePoint API using a real home charger. It requires valid credentials and is not run as part of `pnpm test`.
-
-**Setup:**
-
-Create a `.env.e2e` file in the project root (it is gitignored):
-
-```
-CP_USERNAME=your-chargepoint-email@example.com
-CP_PASSWORD=your-chargepoint-password
-
-# After first run, paste the printed token here to avoid re-logging in:
-# CP_TOKEN=
-```
-
-> **Tip:** `coulomb_sess` tokens contain special characters (`#`, `?`). Always wrap the value in
-> double quotes when exporting to your shell:
-> ```bash
-> export CP_TOKEN="abc...#D???"
-> ```
-
-**Run (read-only — safe with charger in any state):**
-
-```bash
-pnpm test:e2e
-```
-
-On first run the session token is printed. Paste it into `CP_TOKEN` in `.env.e2e` to skip
-password re-authentication on subsequent runs.
-
-**Run with mutation tests** (schedule, amperage limit, LED brightness — each test restores
-original values):
-
-```bash
-E2E_MUTATIONS=true pnpm test:e2e
-```
-
-The following operations are intentionally excluded from the automated suite due to their
-disruptive nature: `restartHomeCharger()`, `startChargingSession()`, `stopChargingSession()`.
-Use the CLI to invoke these manually.
-
-### Build
-
-```bash
-pnpm build
-```
-
-Produces `dist/index.js` (ESM), `dist/index.cjs` (CommonJS), and `dist/index.d.ts` (type declarations) via [tsup](https://tsup.egoist.dev/).
-
-### Checks
-
-| Command | Purpose |
-|---|---|
-| `pnpm typecheck` | TypeScript strict type checking |
-| `pnpm test` | Run all tests |
-| `pnpm build` | Build CJS + ESM + `.d.ts` |
-| `pnpm prepublishOnly` | Build + typecheck (runs automatically before `pnpm publish`) |
+See [docs/development.md](docs/development.md) for setup, tests, E2E tests, and build instructions.
 
 ---

package/dist/cli.cjs

@@ -29,7 +29,7 @@ var import_commander = require("commander");
 // package.json
 var package_default = {
   name: "node-chargepoint",
-  version: "0.3.5",
+  version: "0.4.0",
   description: "A Node.js/TypeScript wrapper for the ChargePoint EV charging network API. Based on python-chargepoint by Marc Billow.",
   keywords: [
     "chargepoint",
@@ -80,7 +80,7 @@ var package_default = {
     prepublishOnly: "pnpm build && pnpm typecheck"
   },
   engines: {
-    node: ">=24"
+    node: ">=22"
   },
   packageManager: "pnpm@11.0.9+sha512.34ce82e6780233cf9cad8685029a8f81d2e06196c5a9bad98879f7424940c6817c4e4524fb7d38b8553ceed48b9758b8ebaf1abd3600c232c4c8cf7366086f38",
   dependencies: {
@@ -100,6 +100,7 @@ var package_default = {
 // src/constants.ts
 var DISCOVERY_API = "https://discovery.chargepoint.com/discovery/v3/globalconfig";
 var VERSION = package_default.version;
+var NODE_CHARGEPOINT_VERSION = package_default.version;
 var USER_AGENT = `node-chargepoint/${VERSION}`;
 
 // src/exceptions.ts
@@ -404,12 +405,12 @@ var ChargingSession = class _ChargingSession {
       this.sessionId
     );
   }
-  static async start(deviceId, client) {
+  static async start(deviceId, client, options) {
     await sendCommand(client, "start", deviceId);
-    const deadline = Date.now() + 15e3;
+    const deadline = Date.now() + (options?.pollTimeoutMs ?? 15e3);
     let status = await client.getUserChargingStatus();
     while (!status && Date.now() < deadline) {
-      await sleep(2e3);
+      await sleep(options?.pollIntervalMs ?? 2e3);
       status = await client.getUserChargingStatus();
     }
     if (!status) {
@@ -434,6 +435,8 @@ var ChargePoint = class _ChargePoint {
   _coulombToken = null;
   _region;
   _userId = null;
+  _timeout;
+  _debug;
   /** The current session token. Save this after login to avoid re-authenticating. */
   get coulombToken() {
     return this._coulombToken;
@@ -450,10 +453,16 @@ var ChargePoint = class _ChargePoint {
     if (options.coulombToken) {
       client._setToken(options.coulombToken, region);
     }
+    client._timeout = options.timeout;
+    client._debug = options.debug;
     return client;
   }
   _setToken(token, region) {
-    this._coulombToken = decodeURIComponent(token);
+    try {
+      this._coulombToken = decodeURIComponent(token);
+    } catch {
+      throw new APIError("Malformed coulomb_sess token: invalid percent-encoding");
+    }
     this._region = region;
   }
   /** @internal Used by session.ts and tests. */
@@ -469,12 +478,19 @@ var ChargePoint = class _ChargePoint {
       headers.set("cp-session-token", this._coulombToken);
       headers.set("cp-region", this._region);
     }
-    const response = await fetch(url, { ...init, method, headers });
+    this._debug?.(`${method} ${url}`);
+    const signal = this._timeout !== void 0 ? AbortSignal.timeout(this._timeout) : void 0;
+    const response = await fetch(url, { ...init, method, headers, signal });
+    this._debug?.(`${response.status} ${url}`);
     const setCookies = typeof response.headers.getSetCookie === "function" ? response.headers.getSetCookie() : [response.headers.get("set-cookie") ?? ""].filter(Boolean);
     for (const cookie of setCookies) {
       const match = /^coulomb_sess=([^;]+)/.exec(cookie);
       if (match) {
-        this._coulombToken = decodeURIComponent(match[1] ?? "");
+        try {
+          this._coulombToken = decodeURIComponent(match[1] ?? "");
+        } catch {
+          throw new CommunicationError(response.status, "Malformed coulomb_sess cookie: invalid percent-encoding");
+        }
         break;
       }
     }
@@ -773,8 +789,8 @@ var ChargePoint = class _ChargePoint {
     await session.refresh();
     return session;
   }
-  async startChargingSession(deviceId) {
-    return ChargingSession.start(deviceId, this);
+  async startChargingSession(deviceId, options) {
+    return ChargingSession.start(deviceId, this, options);
   }
   // ---------------------------------------------------------------------------
   // Stations

package/dist/index.cjs

@@ -8,11 +8,12 @@ var https__default = /*#__PURE__*/_interopDefault(https);
 
 // package.json
 var package_default = {
-  version: "0.3.5"};
+  version: "0.4.0"};
 
 // src/constants.ts
 var DISCOVERY_API = "https://discovery.chargepoint.com/discovery/v3/globalconfig";
 var VERSION = package_default.version;
+var NODE_CHARGEPOINT_VERSION = package_default.version;
 var USER_AGENT = `node-chargepoint/${VERSION}`;
 
 // src/exceptions.ts
@@ -314,12 +315,12 @@ var ChargingSession = class _ChargingSession {
       this.sessionId
     );
   }
-  static async start(deviceId, client) {
+  static async start(deviceId, client, options) {
     await sendCommand(client, "start", deviceId);
-    const deadline = Date.now() + 15e3;
+    const deadline = Date.now() + (options?.pollTimeoutMs ?? 15e3);
     let status = await client.getUserChargingStatus();
     while (!status && Date.now() < deadline) {
-      await sleep(2e3);
+      await sleep(options?.pollIntervalMs ?? 2e3);
       status = await client.getUserChargingStatus();
     }
     if (!status) {
@@ -344,6 +345,8 @@ var ChargePoint = class _ChargePoint {
   _coulombToken = null;
   _region;
   _userId = null;
+  _timeout;
+  _debug;
   /** The current session token. Save this after login to avoid re-authenticating. */
   get coulombToken() {
     return this._coulombToken;
@@ -360,10 +363,16 @@ var ChargePoint = class _ChargePoint {
     if (options.coulombToken) {
       client._setToken(options.coulombToken, region);
     }
+    client._timeout = options.timeout;
+    client._debug = options.debug;
     return client;
   }
   _setToken(token, region) {
-    this._coulombToken = decodeURIComponent(token);
+    try {
+      this._coulombToken = decodeURIComponent(token);
+    } catch {
+      throw new APIError("Malformed coulomb_sess token: invalid percent-encoding");
+    }
     this._region = region;
   }
   /** @internal Used by session.ts and tests. */
@@ -379,12 +388,19 @@ var ChargePoint = class _ChargePoint {
       headers.set("cp-session-token", this._coulombToken);
       headers.set("cp-region", this._region);
     }
-    const response = await fetch(url, { ...init, method, headers });
+    this._debug?.(`${method} ${url}`);
+    const signal = this._timeout !== void 0 ? AbortSignal.timeout(this._timeout) : void 0;
+    const response = await fetch(url, { ...init, method, headers, signal });
+    this._debug?.(`${response.status} ${url}`);
     const setCookies = typeof response.headers.getSetCookie === "function" ? response.headers.getSetCookie() : [response.headers.get("set-cookie") ?? ""].filter(Boolean);
     for (const cookie of setCookies) {
       const match = /^coulomb_sess=([^;]+)/.exec(cookie);
       if (match) {
-        this._coulombToken = decodeURIComponent(match[1] ?? "");
+        try {
+          this._coulombToken = decodeURIComponent(match[1] ?? "");
+        } catch {
+          throw new CommunicationError(response.status, "Malformed coulomb_sess cookie: invalid percent-encoding");
+        }
         break;
       }
     }
@@ -683,8 +699,8 @@ var ChargePoint = class _ChargePoint {
     await session.refresh();
     return session;
   }
-  async startChargingSession(deviceId) {
-    return ChargingSession.start(deviceId, this);
+  async startChargingSession(deviceId, options) {
+    return ChargingSession.start(deviceId, this, options);
   }
   // ---------------------------------------------------------------------------
   // Stations
@@ -726,5 +742,6 @@ exports.CommunicationError = CommunicationError;
 exports.DatadomeCaptcha = DatadomeCaptcha;
 exports.InvalidSession = InvalidSession;
 exports.LoginError = LoginError;
+exports.NODE_CHARGEPOINT_VERSION = NODE_CHARGEPOINT_VERSION;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map