@chargealong/client 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,516 @@
+/**
+ * The API's responses, field for field as they arrive: snake case, as the
+ * service writes them, so the reference and your editor agree.
+ */
+/** The connector standards the service knows, by slug. */
+declare const CONNECTORS: readonly ["ccs2", "chademo", "type-2", "nacs", "ccs1", "type-1", "gbt"];
+type Connector = (typeof CONNECTORS)[number];
+/** ac up to 22 kW, fast up to 99, ultra-fast from 100. */
+type Speed = "ac" | "fast" | "ultra-fast";
+/** Only active sites are worth sending a driver to. */
+type SiteStatus = "active" | "unavailable" | "planned" | "removed";
+type CostKind = "free" | "paid" | "unknown";
+/** Every answer arrives in one envelope. */
+interface Envelope<T> {
+    data: T;
+    /** When the service built this answer. */
+    generated_at?: string;
+}
+interface CountrySummary {
+    iso2: string;
+    slug: string;
+    name: string;
+    site_count: number;
+}
+/** A busy suburb or town, by how many sites it has. */
+interface PlaceCount {
+    slug: string;
+    name: string;
+    postcode?: string;
+    site_count: number;
+    /** The region's slug. */
+    region: string;
+}
+interface Overview {
+    sites: number;
+    ultra_fast: number;
+    countries: (CountrySummary & {
+        busiest: PlaceCount[];
+    })[];
+}
+interface RegionSummary {
+    slug: string;
+    code: string;
+    name: string;
+    site_count: number;
+}
+interface CountryDetail {
+    country: CountrySummary;
+    regions: RegionSummary[];
+    busiest: PlaceCount[];
+}
+interface LocalitySummary {
+    slug: string;
+    name: string;
+    postcode?: string;
+    site_count: number;
+}
+interface RegionDetail {
+    country: CountrySummary;
+    region: RegionSummary;
+    localities: LocalitySummary[];
+}
+interface NetworkSummary {
+    /** The network's slug. */
+    key: string;
+    /** Empty for unbranded sites. */
+    name: string;
+    site_count: number;
+    region_count: number;
+}
+interface NetworksDetail {
+    country: CountrySummary;
+    networks: NetworkSummary[];
+}
+/** One charging site, as every list carries it. */
+interface Site {
+    /** Permanent: minted once, never derived from a source record. Store this. */
+    public_id: string;
+    name: string;
+    network: string;
+    network_name: string;
+    address: string;
+    status: SiteStatus;
+    speed: Speed;
+    /** The fastest connector, in kW. */
+    max_kw: number;
+    plugs: number;
+    standards: Connector[];
+    cost_kind: CostKind;
+    lat: number;
+    lng: number;
+    /** The site's page on chargealong.io. */
+    path: string;
+    /** Present where the answer is about a point. */
+    distance_km?: number;
+}
+interface NetworkDetail {
+    country: CountrySummary;
+    network: NetworkSummary;
+    regions: RegionSummary[];
+    busiest: PlaceCount[];
+    /** A sample of the network's sites, not every one. */
+    sites: Site[];
+}
+interface LocalityInfo extends LocalitySummary {
+    time_zone: string;
+}
+interface Facet {
+    /** What the count is of: a speed, a connector, a network. */
+    kind: string;
+    key: string;
+    count: number;
+}
+interface Neighbour {
+    region: string;
+    slug: string;
+    name: string;
+    site_count: number;
+    distance_km: number;
+}
+interface LocalityDetail {
+    country: CountrySummary;
+    region: RegionSummary;
+    locality: LocalityInfo;
+    sites: Site[];
+    facets: Facet[];
+    neighbours: Neighbour[];
+}
+interface Connection {
+    standard: Connector;
+    label: string;
+    current: "ac" | "dc";
+    power_kw: number;
+    quantity: number;
+}
+interface Source {
+    /** ocm for Open Charge Map, and one key per government register. */
+    key: string;
+    external_id: string;
+    provider: string;
+    licence: string;
+    last_seen_at: string;
+}
+interface SiteInfo extends Site {
+    operator?: string;
+    usage?: string;
+    cost?: {
+        kind: CostKind;
+        has_conditions: boolean;
+        text: string;
+    };
+    /** When a person last confirmed the site worked, per its source. */
+    last_verified_at?: string;
+    updated_at?: string;
+}
+interface Review {
+    [field: string]: unknown;
+}
+interface SiteDetail {
+    country: CountrySummary;
+    region: RegionSummary;
+    locality: LocalityInfo;
+    site: SiteInfo;
+    connectors: Connection[];
+    sources: Source[];
+    /** Other sites close by. */
+    alternatives: Site[];
+    /** The nearest faster site, when there is one. */
+    faster?: Site | null;
+    reviews: {
+        summary: {
+            count: number;
+            average: number | null;
+            last_worked_at: string | null;
+            last_checked_at: string | null;
+        };
+        recent: Review[];
+    };
+    photos: unknown[];
+}
+interface PlaceMatch {
+    country_iso2: string;
+    country_name: string;
+    region_code?: string;
+    region_name: string;
+    slug: string;
+    name: string;
+    postcode?: string;
+    site_count: number;
+    path: string;
+    /** A name that matches in full: a search box can go straight to it. */
+    exact: boolean;
+    lat: number;
+    lng: number;
+}
+/** A postcode's centre, for chargers near it. */
+interface PostcodeMatch {
+    country_iso2: string;
+    country_name: string;
+    code: string;
+    lat: number;
+    lng: number;
+}
+interface SearchResult {
+    localities: PlaceMatch[];
+    postcodes: PostcodeMatch[];
+    sites: Site[];
+}
+/** The closest named place to a point, for a heading. */
+interface NearPlace {
+    country_iso2: string;
+    name: string;
+    region_code: string;
+    region_name: string;
+    path: string;
+    distance_km: number;
+}
+interface NearbyResult {
+    /** Null in the middle of nowhere. */
+    near: NearPlace | null;
+    /** Nearest first. */
+    sites: Site[];
+}
+interface TripStop {
+    site: Pick<Site, "public_id" | "name" | "network" | "network_name" | "address" | "status" | "lat" | "lng" | "path"> & {
+        operator?: string;
+    };
+    along_km: number;
+    detour_km: number;
+    power_kw: number;
+    dc: boolean;
+    arrive_pct: number;
+    depart_pct: number;
+    energy_kwh: number;
+    charge_min: number;
+}
+interface TripPlan {
+    route: {
+        distance_km: number;
+        duration_min: number;
+        /** The road, as [lng, lat] pairs: GeoJSON order, ready for a map. */
+        line: [number, number][];
+    };
+    /** Whether the car makes it with the chargers there are. */
+    feasible: boolean;
+    /** Battery on arrival, in percent. */
+    arrival_pct: number;
+    drive_min: number;
+    charge_min: number;
+    total_min: number;
+    stops: TripStop[];
+}
+interface Vehicle {
+    slug: string;
+    brand: string;
+    model: string;
+    variant?: string;
+    year: number;
+    source_id: string;
+    battery_kwh: number;
+    consumption_kwh_100km: number;
+    range_km: number;
+    ac_kw: number;
+    ac_ports: Connector[];
+    dc_kw: number;
+    dc_ports: Connector[];
+    /** DC charging power by state of charge. */
+    curve: {
+        pct: number;
+        power_kw: number;
+    }[];
+    voltage_v: number;
+}
+interface VehicleDetail extends Vehicle {
+    /** Minutes from 10 to 80 percent on chargers of each size. */
+    charging: {
+        charger_kw: number;
+        minutes_10_80: number;
+    }[];
+}
+/** Where vehicle figures come from, and their licence: credit it when you show them. */
+interface DataSource {
+    name: string;
+    url: string;
+    licence: string;
+}
+interface Redirect {
+    from: string;
+    to: string;
+    status: 301 | 302 | 308;
+}
+
+declare const VERSION = "0.1.0";
+declare const DEFAULT_BASE_URL = "https://api.chargealong.io";
+/** The service reads a search once it holds this many letters or digits. */
+declare const MIN_QUERY = 3;
+interface ClientOptions {
+    /** Point somewhere else: a proxy of your own, or a test server. */
+    baseUrl?: string;
+    /** Your own fetch, for a custom transport or for testing. */
+    fetch?: typeof globalThis.fetch;
+}
+interface RequestOptions {
+    /** Cancel a request whose answer is no longer wanted. */
+    signal?: AbortSignal;
+}
+interface Point {
+    lat: number;
+    lng: number;
+}
+interface SearchOptions extends RequestOptions {
+    /** A two letter country code whose places rank first. */
+    prefer?: string;
+}
+interface NearbyOptions extends RequestOptions, Point {
+    /** Only sites with a connector of at least this many kW, 0 to 400. */
+    minKw?: number;
+    /** How far to look, 1 to 150 km. The service's default is 50. */
+    radiusKm?: number;
+    /** How many sites, 1 to 50. The service's default is 30. */
+    limit?: number;
+    /** Only sites with one of these connectors. */
+    connector?: Connector | Connector[];
+    /** Only sites on this network, by slug: evie-networks. */
+    network?: string;
+}
+interface TripOptions extends RequestOptions {
+    from: Point;
+    /** Somewhere other than from. */
+    to: Point;
+    /** How far the car goes on a full battery, 50 to 1500 km: the real figure, not the rated one. */
+    rangeKm: number;
+    /** Never arrive anywhere below this percentage, 5 to 50. Default 20. */
+    reserve?: number;
+    /** Battery percentage at the start, above the reserve. Default 100. */
+    start?: number;
+    /** Never charge above this percentage, 50 to 100 and at least reserve + 10. Default 80. */
+    chargeTo?: number;
+    /** Usable battery, 10 to 250 kWh. Only charging times need it. */
+    batteryKwh?: number;
+    /** The most DC power the car accepts, 20 to 400 kW. Default 150. */
+    maxDcKw?: number;
+    /** The most AC power the car accepts, 3 to 22 kW. Default 11. */
+    maxAcKw?: number;
+    /** Ignore chargers slower than this, 0 to 350 kW. Default 50. */
+    minKw?: number;
+    /** The connectors the car takes. Default CCS2 and Type 2. */
+    connectors?: Connector[];
+}
+interface VehiclesOptions extends RequestOptions {
+    /** Any part of the brand, model or variant. */
+    q?: string;
+    /** 1 to 100. The service's default is 20. */
+    limit?: number;
+    /** Every car rather than the first page. Ignored when q is given. */
+    all?: boolean;
+}
+/**
+ * A client for the ChargeAlong API: public EV charging sites, trip planning
+ * through charging stops, and how fast electric cars charge.
+ *
+ * ```ts
+ * const ca = new ChargeAlong();
+ * const { sites } = await ca.nearby({ lat: -37.8136, lng: 144.9631, minKw: 50 });
+ * ```
+ *
+ * Free, keyless and cached at the edge. Runs anywhere there is `fetch`: a
+ * browser, a worker, a server. Nothing is kept on the instance between calls,
+ * so one can be shared.
+ *
+ * Attribution travels with the data: see chargealong.io/en/guides/where-the-data-comes-from/.
+ */
+declare class ChargeAlong {
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options?: ClientOptions);
+    /** Every country with charging sites, and how many each has. */
+    countries(options?: RequestOptions): Promise<CountrySummary[]>;
+    /** What the whole directory holds: countries with their busiest places. */
+    overview(options?: RequestOptions): Promise<Overview>;
+    /** One country: its regions and their counts. */
+    country(country: string, options?: RequestOptions): Promise<CountryDetail>;
+    /** One region: the places in it that have charging sites. */
+    region(country: string, region: string, options?: RequestOptions): Promise<RegionDetail>;
+    /** Every charging network in a country, with its site and region counts. */
+    networks(country: string, options?: RequestOptions): Promise<NetworksDetail>;
+    /** One network in a country: where it reaches, and a sample of its sites. */
+    network(country: string, network: string, options?: RequestOptions): Promise<NetworkDetail>;
+    /** One suburb or town: every charging site in it, with facet counts. */
+    locality(country: string, region: string, locality: string, options?: RequestOptions): Promise<LocalityDetail>;
+    /**
+     * 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.
+     */
+    site(publicId: string, options?: RequestOptions): Promise<SiteDetail>;
+    /**
+     * 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`.
+     */
+    search(term: string, options?: SearchOptions): Promise<SearchResult>;
+    /** The charging sites nearest a coordinate, nearest first. */
+    nearby(options: NearbyOptions): Promise<NearbyResult>;
+    /**
+     * 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.
+     */
+    planTrip(options: TripOptions): Promise<TripPlan>;
+    /** Electric cars: battery, range and how they charge. */
+    vehicles(options?: VehiclesOptions): Promise<{
+        vehicles: Vehicle[];
+        source: DataSource;
+    }>;
+    /** One electric car, with how long it takes to charge on chargers of each size. */
+    vehicle(slugName: string, options?: RequestOptions): Promise<{
+        vehicle: VehicleDetail;
+        source: DataSource;
+    }>;
+    /**
+     * Where a page on chargealong.io went, if it moved. Null for a page that
+     * never did, which is most of them.
+     */
+    redirect(path: string, options?: RequestOptions): Promise<Redirect | null>;
+    private get;
+}
+/** Shorthand for `new ChargeAlong(options)`, for code that prefers a factory. */
+declare function createClient(options?: ClientOptions): ChargeAlong;
+
+/** What the API said when it refused. */
+/**
+ * The service answers RFC 7807 problem documents: a title and a detail written
+ * for a person to read and act on, such as which parameter is out of range.
+ * Collapsing that into "HTTP 400" throws away the only part of the answer that
+ * says what to do about it.
+ */
+declare class ChargeAlongError extends Error {
+    readonly status: number;
+    readonly title: string;
+    readonly detail: string;
+    constructor(status: number, title?: string, detail?: string);
+}
+/** Nothing is filed under that id or slug, and never was. */
+declare class NotFound extends ChargeAlongError {
+    constructor(status: number, title?: string, detail?: string);
+}
+/**
+ * The site existed and was removed: decommissioned, or merged into another.
+ *
+ * Its own class rather than a NotFound, because code holding stored site ids
+ * wants to tell "retired, drop it" from "never existed, something is wrong".
+ */
+declare class Gone extends ChargeAlongError {
+    constructor(status: number, title?: string, detail?: string);
+}
+/**
+ * The request could not be served as written. The detail names the parameter.
+ *
+ * Also a 422 from planTrip: there is no road route between the two points.
+ */
+declare class BadRequest extends ChargeAlongError {
+    constructor(status: number, title?: string, detail?: string);
+}
+/**
+ * Too many requests from here.
+ *
+ * The API is free and keyless and asks callers to be gentle: answers kept
+ * rather than fetched again, typing debounced.
+ */
+declare class RateLimited extends ChargeAlongError {
+    /** Seconds the service asked for, when it said. */
+    readonly retryAfter?: number;
+    constructor(status: number, title?: string, detail?: string, retryAfter?: number);
+}
+
+/**
+ * Where a row lives on chargealong.io.
+ *
+ * Sites, places and trip stops carry their page's `path`, so linking to the
+ * site needs no second request. The builders below cover the rows that carry
+ * only slugs, building the path the site itself serves.
+ */
+declare const SITE_URL = "https://chargealong.io";
+/**
+ * A row's page as an absolute URL, or "" for a row without one.
+ *
+ * Only a path on this site becomes a link: a row claiming `//elsewhere` or a
+ * scheme gives nothing rather than a link off the site.
+ */
+declare function pageUrl(row: {
+    path?: string | null;
+} | string): string;
+/** `/en/australia/` */
+declare function countryPath(country: string): string;
+/** `/en/australia/victoria/` */
+declare function regionPath(country: string, region: string): string;
+/** `/en/australia/victoria/coburg/` */
+declare function localityPath(country: string, region: string, locality: string): string;
+/** `/en/australia/networks/` */
+declare function networksPath(country: string): string;
+/** `/en/australia/networks/chargefox/` */
+declare function networkPath(country: string, network: string): string;
+/** `/en/vehicles/tesla-model-3/` */
+declare function vehiclePath(slug: string): string;
+/** Metres, rounded. What a page prints: "560 m", not "0.56 km". */
+declare function metres(distanceKm: number): number;
+
+export { BadRequest, CONNECTORS, ChargeAlong, ChargeAlongError, type ClientOptions, type Connection, type Connector, type CostKind, type CountryDetail, type CountrySummary, DEFAULT_BASE_URL, type DataSource, type Envelope, type Facet, Gone, type LocalityDetail, type LocalityInfo, type LocalitySummary, MIN_QUERY, type NearPlace, type NearbyOptions, type NearbyResult, type Neighbour, type NetworkDetail, type NetworkSummary, type NetworksDetail, NotFound, type Overview, type PlaceCount, type PlaceMatch, type Point, type PostcodeMatch, RateLimited, type Redirect, type RegionDetail, type RegionSummary, type RequestOptions, SITE_URL, type SearchOptions, type SearchResult, type Site, type SiteDetail, type SiteInfo, type SiteStatus, type Source, type Speed, type TripOptions, type TripPlan, type TripStop, VERSION, type Vehicle, type VehicleDetail, type VehiclesOptions, countryPath, createClient, localityPath, metres, networkPath, networksPath, pageUrl, regionPath, vehiclePath };