@chargealong/client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ChargeAlong
+
+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/dist/index.cjs

@@ -0,0 +1,382 @@
+'use strict';
+
+// src/errors.ts
+var ChargeAlongError = class extends Error {
+  status;
+  title;
+  detail;
+  constructor(status, title = "", detail = "") {
+    super([title || `HTTP ${status}`, detail].filter(Boolean).join(": "));
+    this.name = "ChargeAlongError";
+    this.status = status;
+    this.title = title;
+    this.detail = detail;
+  }
+};
+var NotFound = class extends ChargeAlongError {
+  constructor(status, title = "", detail = "") {
+    super(status, title, detail);
+    this.name = "NotFound";
+  }
+};
+var Gone = class extends ChargeAlongError {
+  constructor(status, title = "", detail = "") {
+    super(status, title, detail);
+    this.name = "Gone";
+  }
+};
+var BadRequest = class extends ChargeAlongError {
+  constructor(status, title = "", detail = "") {
+    super(status, title, detail);
+    this.name = "BadRequest";
+  }
+};
+var RateLimited = class extends ChargeAlongError {
+  /** Seconds the service asked for, when it said. */
+  retryAfter;
+  constructor(status, title = "", detail = "", retryAfter) {
+    super(status, title, detail);
+    this.name = "RateLimited";
+    this.retryAfter = retryAfter;
+  }
+};
+function errorFor(status, title = "", detail = "", retryAfter) {
+  if (status === 404) return new NotFound(status, title, detail);
+  if (status === 410) return new Gone(status, title, detail);
+  if (status === 429) return new RateLimited(status, title, detail, retryAfter);
+  if (status >= 400 && status < 500) return new BadRequest(status, title, detail);
+  return new ChargeAlongError(status, title, detail);
+}
+
+// src/types.ts
+var CONNECTORS = ["ccs2", "chademo", "type-2", "nacs", "ccs1", "type-1", "gbt"];
+
+// src/client.ts
+var VERSION = "0.1.0";
+var DEFAULT_BASE_URL = "https://api.chargealong.io";
+var MIN_QUERY = 3;
+var MAX_QUERY = 100;
+var ChargeAlong = class {
+  baseUrl;
+  fetchImpl;
+  constructor(options = {}) {
+    this.baseUrl = checkBaseUrl(options.baseUrl ?? DEFAULT_BASE_URL);
+    const impl = options.fetch ?? globalThis.fetch;
+    if (typeof impl !== "function") {
+      throw new Error("chargealong: no fetch in this runtime. Pass one: new ChargeAlong({ fetch })");
+    }
+    this.fetchImpl = options.fetch ? impl : impl.bind(globalThis);
+  }
+  /** Every country with charging sites, and how many each has. */
+  async countries(options = {}) {
+    const body = await this.get("/v1/countries", {}, options);
+    return Array.isArray(body.data) ? body.data : [];
+  }
+  /** What the whole directory holds: countries with their busiest places. */
+  async overview(options = {}) {
+    return (await this.get("/v1/overview", {}, options)).data;
+  }
+  /** One country: its regions and their counts. */
+  async country(country, options = {}) {
+    return (await this.get(`/v1/countries/${slug(country, "country")}`, {}, options)).data;
+  }
+  /** One region: the places in it that have charging sites. */
+  async region(country, region, options = {}) {
+    const path = `/v1/countries/${slug(country, "country")}/regions/${slug(region, "region")}`;
+    return (await this.get(path, {}, options)).data;
+  }
+  /** Every charging network in a country, with its site and region counts. */
+  async networks(country, options = {}) {
+    return (await this.get(`/v1/countries/${slug(country, "country")}/networks`, {}, options)).data;
+  }
+  /** One network in a country: where it reaches, and a sample of its sites. */
+  async network(country, network, options = {}) {
+    const path = `/v1/countries/${slug(country, "country")}/networks/${slug(network, "network")}`;
+    return (await this.get(path, {}, options)).data;
+  }
+  /** One suburb or town: every charging site in it, with facet counts. */
+  async locality(country, region, locality, options = {}) {
+    const path = `/v1/localities/${slug(country, "country")}/${slug(region, "region")}/${slug(locality, "locality")}`;
+    return (await this.get(path, {}, options)).data;
+  }
+  /**
+   * One charging site: connectors, power, price, access, network, sources,
+   * and what is close by.
+   *
+   * The id is permanent. Rejects with {@link NotFound} for an id that never
+   * existed, and with {@link Gone} for a site that was removed, so code holding
+   * stored ids can drop the retired ones.
+   */
+  async site(publicId, options = {}) {
+    return (await this.get(`/v1/sites/${slug(publicId, "site id")}`, {}, options)).data;
+  }
+  /**
+   * Places, postcodes and sites matching a name, for a search box.
+   *
+   * Fewer than three letters or digits answers empty without a request, which
+   * is what the service would answer anyway. Debounce and pass a `signal`.
+   */
+  async search(term, options = {}) {
+    const q = String(term ?? "").trim();
+    if (q.length > MAX_QUERY) {
+      throw new Error(`chargealong: a search is at most ${MAX_QUERY} characters`);
+    }
+    const significant = q.match(/[\p{L}\p{N}]/gu)?.length ?? 0;
+    if (significant < MIN_QUERY) return { localities: [], postcodes: [], sites: [] };
+    let prefer;
+    if (options.prefer !== void 0) {
+      prefer = options.prefer.trim().toUpperCase();
+      if (!/^[A-Z]{2}$/.test(prefer)) {
+        throw new Error(`chargealong: prefer ${options.prefer} is not a two letter country code`);
+      }
+    }
+    const body = await this.get("/v1/search", { q, prefer }, options);
+    const data = body.data ?? {};
+    return { localities: data.localities ?? [], postcodes: data.postcodes ?? [], sites: data.sites ?? [] };
+  }
+  /** The charging sites nearest a coordinate, nearest first. */
+  async nearby(options) {
+    const { lat, lng } = point(options);
+    const connector = options.connector === void 0 ? void 0 : connectors(Array.isArray(options.connector) ? options.connector : [options.connector], "connector");
+    const body = await this.get(
+      "/v1/nearby",
+      {
+        lat,
+        lng,
+        min_kw: bounded(options.minKw, "minKw", 0, 400),
+        radius_km: bounded(options.radiusKm, "radiusKm", 1, 150),
+        limit: whole(options.limit, "limit", 1, 50),
+        connector,
+        network: options.network?.trim() || void 0
+      },
+      options
+    );
+    const data = body.data ?? {};
+    return { near: data.near ?? null, sites: data.sites ?? [] };
+  }
+  /**
+   * A road trip from A to B through charging stops: the route, where to stop,
+   * how long to charge at each, and the battery on arrival.
+   *
+   * Rejects with a {@link BadRequest} of status 422 when there is no road route
+   * between the two points (across water, say), and with a 503 when trip
+   * planning is briefly unavailable.
+   */
+  async planTrip(options) {
+    const from = point(options.from ?? {});
+    const to = point(options.to ?? {});
+    if (from.lat === to.lat && from.lng === to.lng) {
+      throw new Error("chargealong: a trip must end somewhere other than where it starts");
+    }
+    const rangeKm = bounded(options.rangeKm, "rangeKm", 50, 1500);
+    if (rangeKm === void 0) throw new Error("chargealong: rangeKm is required");
+    const body = await this.get(
+      "/v1/trips/plan",
+      {
+        from: `${from.lat},${from.lng}`,
+        to: `${to.lat},${to.lng}`,
+        range_km: rangeKm,
+        reserve: bounded(options.reserve, "reserve", 5, 50),
+        start: bounded(options.start, "start", 5, 100),
+        charge_to: bounded(options.chargeTo, "chargeTo", 50, 100),
+        battery_kwh: bounded(options.batteryKwh, "batteryKwh", 10, 250),
+        max_dc_kw: bounded(options.maxDcKw, "maxDcKw", 20, 400),
+        max_ac_kw: bounded(options.maxAcKw, "maxAcKw", 3, 22),
+        min_kw: bounded(options.minKw, "minKw", 0, 350),
+        // One parameter, comma separated: the planner reads it that way.
+        connectors: options.connectors === void 0 ? void 0 : connectors(options.connectors, "connectors").join(",")
+      },
+      options
+    );
+    return body.data;
+  }
+  /** Electric cars: battery, range and how they charge. */
+  async vehicles(options = {}) {
+    const body = await this.get(
+      "/v1/vehicles",
+      {
+        q: options.q?.trim() || void 0,
+        limit: whole(options.limit, "limit", 1, 100),
+        all: options.all ? "true" : void 0
+      },
+      options
+    );
+    return { vehicles: Array.isArray(body.data) ? body.data : [], source: sourceOf(body) };
+  }
+  /** One electric car, with how long it takes to charge on chargers of each size. */
+  async vehicle(slugName, options = {}) {
+    const body = await this.get(`/v1/vehicles/${slug(slugName, "vehicle")}`, {}, options);
+    return { vehicle: body.data, source: sourceOf(body) };
+  }
+  /**
+   * Where a page on chargealong.io went, if it moved. Null for a page that
+   * never did, which is most of them.
+   */
+  async redirect(path, options = {}) {
+    const p = String(path ?? "").trim();
+    if (!p.startsWith("/") || p.startsWith("//") || p.includes("://") || p.includes("\\")) {
+      throw new Error(`chargealong: ${JSON.stringify(path)} is not a path on chargealong.io`);
+    }
+    try {
+      return (await this.get("/v1/redirect", { path: p }, options)).data ?? null;
+    } catch (err) {
+      if (err instanceof NotFound) return null;
+      throw err;
+    }
+  }
+  async get(path, params, options) {
+    const query = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+      if (value === void 0 || value === "") continue;
+      if (Array.isArray(value)) {
+        for (const v of value) query.append(key, v);
+      } else {
+        query.set(key, String(value));
+      }
+    }
+    const url = this.baseUrl + path + (query.size ? `?${query}` : "");
+    const response = await this.fetchImpl(url, {
+      method: "GET",
+      headers: { Accept: "application/json" },
+      signal: options.signal,
+      // Nothing here is authenticated, and a cookie on a cacheable GET is how a
+      // shared cache comes to hold something that belongs to one visitor.
+      credentials: "omit",
+      // The API does not redirect; one on the way is a proxy, not an answer.
+      redirect: "error"
+    });
+    let parsed;
+    try {
+      parsed = await response.json();
+    } catch {
+      parsed = void 0;
+    }
+    const body = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+    if (!response.ok) {
+      const retryAfter = Number(response.headers.get("Retry-After"));
+      throw errorFor(
+        response.status,
+        typeof body.title === "string" ? body.title : "",
+        typeof body.detail === "string" ? body.detail : "",
+        Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : void 0
+      );
+    }
+    return body;
+  }
+};
+function createClient(options = {}) {
+  return new ChargeAlong(options);
+}
+function sourceOf(body) {
+  const s = body.source ?? {};
+  return { name: s.name ?? "", url: s.url ?? "", licence: s.licence ?? "" };
+}
+function slug(value, what) {
+  const text = String(value ?? "").trim();
+  if (!text || text === "." || text === "..") throw new Error(`chargealong: no ${what}`);
+  return encodeURIComponent(text);
+}
+function point(p) {
+  const lat = p.lat;
+  const lng = p.lng;
+  if (!(lat >= -90 && lat <= 90) || !(lng >= -180 && lng <= 180)) {
+    throw new Error(`chargealong: (${lat}, ${lng}) is not a point on the globe; lat -90..90, lng -180..180`);
+  }
+  return { lat, lng };
+}
+function bounded(value, name, lo, hi) {
+  if (value === void 0) return void 0;
+  if (!(typeof value === "number" && value >= lo && value <= hi)) {
+    throw new Error(`chargealong: ${name} must be a number from ${lo} to ${hi}, not ${value}`);
+  }
+  return value;
+}
+function whole(value, name, lo, hi) {
+  const v = bounded(value, name, lo, hi);
+  if (v !== void 0 && !Number.isInteger(v)) {
+    throw new Error(`chargealong: ${name} must be a whole number, not ${value}`);
+  }
+  return v;
+}
+function connectors(list, name) {
+  if (list.length === 0) throw new Error(`chargealong: ${name} is empty; leave it out for any`);
+  for (const c of list) {
+    if (!CONNECTORS.includes(c)) {
+      throw new Error(`chargealong: ${c} is not a connector the service knows: ${CONNECTORS.join(", ")}`);
+    }
+  }
+  return [...list];
+}
+function checkBaseUrl(raw) {
+  let parsed;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw new Error(`chargealong: base URL ${raw} is not absolute`);
+  }
+  if (parsed.username || parsed.password) {
+    throw new Error(`chargealong: base URL ${raw} carries credentials, and the host it would reach is not the one it reads as`);
+  }
+  if (/[?#]/.test(raw)) {
+    throw new Error(`chargealong: base URL ${raw} has a query or a fragment, which would swallow the path`);
+  }
+  const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(parsed.hostname);
+  if (parsed.protocol === "https:" || parsed.protocol === "http:" && loopback) {
+    return raw.replace(/\/+$/, "");
+  }
+  if (parsed.protocol === "http:") {
+    throw new Error(`chargealong: base URL ${raw} is plaintext http to a public host, which would send where people are in the clear`);
+  }
+  throw new Error(`chargealong: base URL ${raw} has scheme ${parsed.protocol}, want https`);
+}
+
+// src/paths.ts
+var SITE_URL = "https://chargealong.io";
+var LANG = "en";
+function pageUrl(row) {
+  const path = typeof row === "string" ? row : row.path ?? "";
+  if (!path.startsWith("/") || path.startsWith("//") || path.includes("\\") || path.includes("://")) return "";
+  return SITE_URL + path;
+}
+function countryPath(country) {
+  return country ? `/${LANG}/${country}/` : "";
+}
+function regionPath(country, region) {
+  return country && region ? `/${LANG}/${country}/${region}/` : "";
+}
+function localityPath(country, region, locality) {
+  return country && region && locality ? `/${LANG}/${country}/${region}/${locality}/` : "";
+}
+function networksPath(country) {
+  return country ? `/${LANG}/${country}/networks/` : "";
+}
+function networkPath(country, network) {
+  return country && network ? `/${LANG}/${country}/networks/${network}/` : "";
+}
+function vehiclePath(slug2) {
+  return slug2 ? `/${LANG}/vehicles/${slug2}/` : "";
+}
+function metres(distanceKm) {
+  return Math.round(distanceKm * 1e3);
+}
+
+exports.BadRequest = BadRequest;
+exports.CONNECTORS = CONNECTORS;
+exports.ChargeAlong = ChargeAlong;
+exports.ChargeAlongError = ChargeAlongError;
+exports.DEFAULT_BASE_URL = DEFAULT_BASE_URL;
+exports.Gone = Gone;
+exports.MIN_QUERY = MIN_QUERY;
+exports.NotFound = NotFound;
+exports.RateLimited = RateLimited;
+exports.SITE_URL = SITE_URL;
+exports.VERSION = VERSION;
+exports.countryPath = countryPath;
+exports.createClient = createClient;
+exports.localityPath = localityPath;
+exports.metres = metres;
+exports.networkPath = networkPath;
+exports.networksPath = networksPath;
+exports.pageUrl = pageUrl;
+exports.regionPath = regionPath;
+exports.vehiclePath = vehiclePath;