mapricot 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mapricot
+
+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/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# Mapricot for JavaScript and TypeScript
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The official JavaScript client for the [Mapricot API](https://mapricot.com/): address and place search, reverse geocoding, nearby places, routing, and IP geolocation, with 250,000 free requests every month.
+
+```sh
+npm install mapricot
+```
+
+It uses the built-in `fetch`, so it has no dependencies and runs in Node.js 20 and later, Deno (as `npm:mapricot`), Bun, Cloudflare Workers, and browsers. Types are included.
+
+## Quick start
+
+Create a server key in the [dashboard](https://app.mapricot.com/) and set it as `MAPRICOT_KEY`:
+
+```sh
+export MAPRICOT_KEY="mapricot_sk_…"
+```
+
+```js
+import { Mapricot } from "mapricot";
+
+const client = new Mapricot();
+
+const { results } = await client.search("128 SW 3rd Ave, Portland", { limit: 1 });
+console.log(results[0].label, results[0].lat, results[0].lon);
+```
+
+Pass the key yourself with `new Mapricot({ apiKey: "mapricot_sk_…" })`. In a web page, use a browser key, which works only from the origins you allow, and keep server keys on your server.
+
+## Methods
+
+Each method returns the API's JSON, typed, with the same field names as the [API reference](https://mapricot.com/api-reference/).
+
+| Method | Endpoint |
+| --- | --- |
+| `client.search(q, { focus, country, limit, lang })` | [`GET /v1/search`](https://mapricot.com/docs/geocoding/#find-an-address) |
+| `client.autocomplete(q, { focus, country, limit, lang })` | [`GET /v1/autocomplete`](https://mapricot.com/docs/places/#suggest-as-people-type) |
+| `client.reverse(lat, lon, { limit, lang })` | [`GET /v1/reverse`](https://mapricot.com/docs/geocoding/#find-the-address-at-a-point) |
+| `client.nearby(lat, lon, { category, radius, limit, lang })` | [`GET /v1/nearby`](https://mapricot.com/docs/places/#list-places-around-a-point) |
+| `client.place(id, { lang })` | [`GET /v1/places/{id}`](https://mapricot.com/docs/places/#look-up-a-saved-place) |
+| `client.route(waypoints, { mode })` | [`POST /v1/route`](https://mapricot.com/docs/routing/#get-a-route) |
+| `client.ip(address)` | [`GET /v1/ip/{ip}`](https://mapricot.com/docs/ip-geolocation/#look-up-an-address) |
+| `client.account()` | `GET /v1/account`, which checks a key and is never billed |
+
+`focus` and each waypoint are `{ lat, lon }`. `country` and `category` take an array or a comma-separated string.
+
+```js
+const nearby = await client.nearby(45.52, -122.68, { category: ["food:coffee_shop"], radius: 1000 });
+const { routes } = await client.route([{ lat: 45.5189, lon: -122.6793 }, { lat: 45.5214, lon: -122.6828 }], { mode: "walk" });
+console.log(routes[0].durationSeconds);
+```
+
+A route's `polyline` is encoded with six decimal places. Decode it with precision 6, as [decoding a route polyline](https://mapricot.com/docs/polyline/) shows.
+
+If your app shows results, show the credits in each response's `attribution`.
+
+## Errors and retries
+
+An error response throws `MapricotError`, with the HTTP `status`, the API's error `code`, a `message`, and the `requestId`:
+
+```js
+import { MapricotError } from "mapricot";
+
+try {
+  await client.search("");
+} catch (error) {
+  if (!(error instanceof MapricotError)) throw error;
+  console.log(error.status, error.code, error.message); // 400 invalid_request The service rejected the request.
+}
+```
+
+The client retries `503` responses and `429 concurrency_exceeded`, up to twice, waiting longer each time. Errors aren't billed. Set `maxRetries` and `timeout` (milliseconds) in the constructor's options to change this. The [API reference](https://mapricot.com/api-reference/#errors) lists every status.
+
+## Links
+
+- [Mapricot](https://mapricot.com/)
+- [Node.js docs](https://mapricot.com/docs/node/)
+- [API reference](https://mapricot.com/api-reference/)
+- [Pricing](https://mapricot.com/pricing/)

package/dist/index.d.ts

@@ -0,0 +1,130 @@
+export interface Attribution {
+    source: string;
+    text: string;
+    url: string;
+}
+export interface Address {
+    houseNumber?: string;
+    street?: string;
+    postalCode?: string;
+    locality?: string;
+    region?: string;
+    regionCode?: string;
+    country?: string;
+    countryCode?: string;
+}
+export interface Place {
+    id: string;
+    type: string;
+    name: string;
+    label: string;
+    lat: number;
+    lon: number;
+    address?: Address;
+    categories?: string[];
+    distanceMeters?: number;
+    source: string;
+}
+export interface Places {
+    results: Place[];
+    attribution: Attribution[];
+}
+export interface PlaceResult {
+    result: Place;
+    attribution: Attribution[];
+}
+export interface Leg {
+    distanceMeters: number;
+    durationSeconds: number;
+}
+export interface Route {
+    distanceMeters: number;
+    durationSeconds: number;
+    /** Encoded polyline with six decimal places of precision. */
+    polyline: string;
+    legs: Leg[];
+}
+export interface Routes {
+    routes: Route[];
+    attribution?: Attribution[];
+}
+export interface IpLocation {
+    ip: string;
+    found: boolean;
+    continentCode?: string;
+    countryCode?: string;
+    countryName?: string;
+    regionCode?: string;
+    regionName?: string;
+    city?: string;
+    location?: Point;
+    source: string;
+    attributionUrl: string;
+    licenseUrl: string;
+    datasetRelease: string;
+}
+export interface Account {
+    id: string;
+    name: string;
+    status: string;
+    created_at: string;
+}
+export interface Point {
+    lat: number;
+    lon: number;
+}
+export interface SearchOptions {
+    focus?: Point;
+    country?: string | string[];
+    limit?: number;
+    lang?: string;
+}
+export interface ReverseOptions {
+    limit?: number;
+    lang?: string;
+}
+export interface NearbyOptions {
+    category?: string | string[];
+    radius?: number;
+    limit?: number;
+    lang?: string;
+}
+export interface ClientOptions {
+    /** Defaults to the MAPRICOT_KEY environment variable. */
+    apiKey?: string;
+    baseUrl?: string;
+    /** Milliseconds per attempt. */
+    timeout?: number;
+    /** Retries for 503 and for 429 with too many requests in progress. */
+    maxRetries?: number;
+}
+export declare class MapricotError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly requestId: string | null;
+    constructor(status: number, code: string, message: string, requestId: string | null);
+}
+export declare class Mapricot {
+    #private;
+    constructor(options?: ClientOptions);
+    /** Find addresses and places matching free text. */
+    search(q: string, options?: SearchOptions): Promise<Places>;
+    /** Suggest addresses and places as someone types. */
+    autocomplete(q: string, options?: SearchOptions): Promise<Places>;
+    /** Find the address nearest a coordinate, or the area around it. */
+    reverse(lat: number, lon: number, options?: ReverseOptions): Promise<Places>;
+    /** List places around a coordinate, optionally by category. */
+    nearby(lat: number, lon: number, options?: NearbyOptions): Promise<Places>;
+    /** Look up one place by its Mapricot ID. */
+    place(id: string, options?: {
+        lang?: string;
+    }): Promise<PlaceResult>;
+    /** Find a route through 2 to 20 waypoints. */
+    route(waypoints: Point[], options?: {
+        mode?: "drive" | "walk" | "bicycle";
+    }): Promise<Routes>;
+    /** Approximate location of a public IP address. */
+    ip(address: string): Promise<IpLocation>;
+    /** The key's account. Not billed, so it checks a key for free. */
+    account(): Promise<Account>;
+}

package/dist/index.js

@@ -0,0 +1,106 @@
+export class MapricotError extends Error {
+    status;
+    code;
+    requestId;
+    constructor(status, code, message, requestId) {
+        super(message);
+        this.name = "MapricotError";
+        this.status = status;
+        this.code = code;
+        this.requestId = requestId;
+    }
+}
+export class Mapricot {
+    #apiKey;
+    #baseUrl;
+    #timeout;
+    #maxRetries;
+    constructor(options = {}) {
+        const apiKey = options.apiKey ?? globalThis.process?.env?.MAPRICOT_KEY;
+        if (!apiKey)
+            throw new Error("Pass apiKey or set MAPRICOT_KEY.");
+        this.#apiKey = apiKey;
+        this.#baseUrl = options.baseUrl ?? "https://api.mapricot.com";
+        this.#timeout = options.timeout ?? 30_000;
+        this.#maxRetries = options.maxRetries ?? 2;
+    }
+    /** Find addresses and places matching free text. */
+    search(q, options = {}) {
+        return this.#request("GET", "/v1/search", { q, ...options });
+    }
+    /** Suggest addresses and places as someone types. */
+    autocomplete(q, options = {}) {
+        return this.#request("GET", "/v1/autocomplete", { q, ...options });
+    }
+    /** Find the address nearest a coordinate, or the area around it. */
+    reverse(lat, lon, options = {}) {
+        return this.#request("GET", "/v1/reverse", { lat, lon, ...options });
+    }
+    /** List places around a coordinate, optionally by category. */
+    nearby(lat, lon, options = {}) {
+        return this.#request("GET", "/v1/nearby", { lat, lon, ...options });
+    }
+    /** Look up one place by its Mapricot ID. */
+    place(id, options = {}) {
+        return this.#request("GET", `/v1/places/${encodeURIComponent(id)}`, options);
+    }
+    /** Find a route through 2 to 20 waypoints. */
+    route(waypoints, options = {}) {
+        return this.#request("POST", "/v1/route", {}, { waypoints, ...options });
+    }
+    /** Approximate location of a public IP address. */
+    ip(address) {
+        return this.#request("GET", `/v1/ip/${encodeURIComponent(address)}`, {});
+    }
+    /** The key's account. Not billed, so it checks a key for free. */
+    account() {
+        return this.#request("GET", "/v1/account", {});
+    }
+    async #request(method, path, params, body) {
+        const url = new URL(path, this.#baseUrl);
+        for (const [name, value] of Object.entries(params)) {
+            if (value === undefined)
+                continue;
+            url.searchParams.set(name, format(value));
+        }
+        const headers = { Authorization: `Bearer ${this.#apiKey}` };
+        if (body)
+            headers["Content-Type"] = "application/json";
+        for (let attempt = 0;; attempt++) {
+            const response = await fetch(url, {
+                method,
+                headers,
+                body: body && JSON.stringify(body),
+                signal: AbortSignal.timeout(this.#timeout),
+            });
+            if (response.ok)
+                return (await response.json());
+            const error = await errorFrom(response);
+            if (attempt < this.#maxRetries && retryable(error)) {
+                await new Promise((resolve) => setTimeout(resolve, 500 * 2 ** attempt));
+                continue;
+            }
+            throw error;
+        }
+    }
+}
+function format(value) {
+    if (Array.isArray(value))
+        return value.join(",");
+    if (typeof value === "object")
+        return `${value.lat},${value.lon}`;
+    return String(value);
+}
+async function errorFrom(response) {
+    const requestId = response.headers.get("X-Request-Id");
+    try {
+        const { error } = await response.json();
+        return new MapricotError(response.status, error.code, error.message, requestId);
+    }
+    catch {
+        return new MapricotError(response.status, "unknown", `HTTP ${response.status}`, requestId);
+    }
+}
+function retryable(error) {
+    return error.status === 503 || error.code === "concurrency_exceeded";
+}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "mapricot",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Official client for the Mapricot API: geocoding, places, routing, and IP geolocation.",
+  "keywords": [
+    "geocoding",
+    "places",
+    "routing",
+    "ip-geolocation",
+    "maps"
+  ],
+  "homepage": "https://mapricot.com/docs/node/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mapricothq/mapricot.git",
+    "directory": "sdks/js"
+  },
+  "bugs": "https://github.com/mapricothq/mapricot/issues",
+  "license": "MIT",
+  "type": "module",
+  "exports": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "tsc && node --test",
+    "prepublishOnly": "tsc"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2"
+  }
+}