@ranamaps/maps-js 0.0.0-stage → 0.4.0-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE.md ADDED
@@ -0,0 +1,13 @@
1
+ # Rana Maps SDK licence (draft)
2
+
3
+ Copyright © 2026 EL-Joy Technologies. All rights reserved.
4
+
5
+ The Rana Maps SDKs (`@ranamaps/maps-js`, `com.ranamaps:maps-android`, `RanaMapsSDK`) are proprietary. You may use them,
6
+ free of charge, inside your own web pages and apps, only with a valid Rana key and under the Rana Maps API and SDK
7
+ terms (https://ranamaps.com/api-terms). You may ship them inside your app. You may not sell them on their own, remove
8
+ the attribution "© Rana Maps © OpenStreetMap", or use them to copy Rana's map data in bulk. Using them after your key is
9
+ revoked is not allowed.
10
+
11
+ They include open-source parts under their own licences; NOTICES.md lists them and their notices, which must be kept.
12
+
13
+ This licence is a draft until a Nigerian lawyer has reviewed it (lawyer checklist item H5).
package/NOTICES.md ADDED
@@ -0,0 +1,230 @@
1
+ # Third-party notices
2
+
3
+ The Rana Maps SDKs include open-source software. Their licences require these notices to travel with the SDKs. They
4
+ are the only place the parts are named; the SDKs' own API never exposes them (decision 0017).
5
+
6
+ ## MapLibre GL JS (in @ranamaps/maps-js)
7
+
8
+ Copyright (c) 2023, MapLibre contributors
9
+
10
+ All rights reserved.
11
+
12
+ Redistribution and use in source and binary forms, with or without modification,
13
+ are permitted provided that the following conditions are met:
14
+
15
+ * Redistributions of source code must retain the above copyright notice,
16
+ this list of conditions and the following disclaimer.
17
+ * Redistributions in binary form must reproduce the above copyright notice,
18
+ this list of conditions and the following disclaimer in the documentation
19
+ and/or other materials provided with the distribution.
20
+ * Neither the name of MapLibre GL JS nor the names of its contributors
21
+ may be used to endorse or promote products derived from this software
22
+ without specific prior written permission.
23
+
24
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
25
+ "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
26
+ LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
27
+ A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
28
+ CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
29
+ EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
30
+ PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
31
+ PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
32
+ LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
33
+ NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
34
+ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
35
+
36
+
37
+ -------------------------------------------------------------------------------
38
+
39
+ Contains code from mapbox-gl-js v1.13 and earlier
40
+
41
+ Version v1.13 of mapbox-gl-js and earlier are licensed under a BSD-3-Clause license
42
+
43
+ Copyright (c) 2020, Mapbox
44
+ Redistribution and use in source and binary forms, with or without modification,
45
+ are permitted provided that the following conditions are met:
46
+
47
+ * Redistributions of source code must retain the above copyright notice,
48
+ this list of conditions and the following disclaimer.
49
+ * Redistributions in binary form must reproduce the above copyright notice,
50
+ this list of conditions and the following disclaimer in the documentation
51
+ and/or other materials provided with the distribution.
52
+ * Neither the name of Mapbox GL JS nor the names of its contributors
53
+ may be used to endorse or promote products derived from this software
54
+ without specific prior written permission.
55
+
56
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
57
+ "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
58
+ LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
59
+ A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
60
+ CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
61
+ EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
62
+ PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
63
+ PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
64
+ LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
65
+ NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
66
+ EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
67
+
68
+
69
+ -------------------------------------------------------------------------------
70
+
71
+ Contains code from glfx.js
72
+
73
+ Copyright (C) 2011 by Evan Wallace
74
+
75
+ Permission is hereby granted, free of charge, to any person obtaining a copy
76
+ of this software and associated documentation files (the "Software"), to deal
77
+ in the Software without restriction, including without limitation the rights
78
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
79
+ copies of the Software, and to permit persons to whom the Software is
80
+ furnished to do so, subject to the following conditions:
81
+
82
+ The above copyright notice and this permission notice shall be included in
83
+ all copies or substantial portions of the Software.
84
+
85
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
86
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
87
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
88
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
89
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
90
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
91
+ THE SOFTWARE.
92
+
93
+ --------------------------------------------------------------------------------
94
+
95
+ Contains a portion of d3-color https://github.com/d3/d3-color
96
+
97
+ Copyright 2010-2016 Mike Bostock
98
+ All rights reserved.
99
+
100
+ Redistribution and use in source and binary forms, with or without modification,
101
+ are permitted provided that the following conditions are met:
102
+
103
+ * Redistributions of source code must retain the above copyright notice, this
104
+ list of conditions and the following disclaimer.
105
+
106
+ * Redistributions in binary form must reproduce the above copyright notice,
107
+ this list of conditions and the following disclaimer in the documentation
108
+ and/or other materials provided with the distribution.
109
+
110
+ * Neither the name of the author nor the names of contributors may be used to
111
+ endorse or promote products derived from this software without specific prior
112
+ written permission.
113
+
114
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
115
+ ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
116
+ WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
117
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
118
+ ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
119
+ (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
120
+ LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
121
+ ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
122
+ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
123
+ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
124
+
125
+ ## MapLibre Native (in com.ranamaps:maps-android and RanaMapsSDK)
126
+
127
+ BSD 2-Clause licence, held by the MapLibre contributors (and Mapbox for older parts). The full text, with its exact
128
+ copyright lines, ships inside the engine's own package (its LICENSE.md) and must be kept with any copy of it. Copy that
129
+ text here when the first release is built.
130
+
131
+ ## Plus Jakarta Sans (in com.ranamaps:maps-android and RanaMapsSDK)
132
+
133
+ The Rana Kit typeface, drawn into marker labels, badges, avatars and clusters. Bundled unmodified as
134
+ `PlusJakartaSans-Variable.ttf`, with its licence beside it as `PlusJakartaSans-OFL.txt`.
135
+
136
+ ```
137
+ Copyright 2020 The Plus Jakarta Sans Project Authors (https://github.com/tokotype/PlusJakartaSans)
138
+
139
+ This Font Software is licensed under the SIL Open Font License, Version 1.1.
140
+ This license is copied below, and is also available with a FAQ at:
141
+ http://scripts.sil.org/OFL
142
+
143
+
144
+ -----------------------------------------------------------
145
+ SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
146
+ -----------------------------------------------------------
147
+
148
+ PREAMBLE
149
+ The goals of the Open Font License (OFL) are to stimulate worldwide
150
+ development of collaborative font projects, to support the font creation
151
+ efforts of academic and linguistic communities, and to provide a free and
152
+ open framework in which fonts may be shared and improved in partnership
153
+ with others.
154
+
155
+ The OFL allows the licensed fonts to be used, studied, modified and
156
+ redistributed freely as long as they are not sold by themselves. The
157
+ fonts, including any derivative works, can be bundled, embedded,
158
+ redistributed and/or sold with any software provided that any reserved
159
+ names are not used by derivative works. The fonts and derivatives,
160
+ however, cannot be released under any other type of license. The
161
+ requirement for fonts to remain under this license does not apply
162
+ to any document created using the fonts or their derivatives.
163
+
164
+ DEFINITIONS
165
+ "Font Software" refers to the set of files released by the Copyright
166
+ Holder(s) under this license and clearly marked as such. This may
167
+ include source files, build scripts and documentation.
168
+
169
+ "Reserved Font Name" refers to any names specified as such after the
170
+ copyright statement(s).
171
+
172
+ "Original Version" refers to the collection of Font Software components as
173
+ distributed by the Copyright Holder(s).
174
+
175
+ "Modified Version" refers to any derivative made by adding to, deleting,
176
+ or substituting -- in part or in whole -- any of the components of the
177
+ Original Version, by changing formats or by porting the Font Software to a
178
+ new environment.
179
+
180
+ "Author" refers to any designer, engineer, programmer, technical
181
+ writer or other person who contributed to the Font Software.
182
+
183
+ PERMISSION & CONDITIONS
184
+ Permission is hereby granted, free of charge, to any person obtaining
185
+ a copy of the Font Software, to use, study, copy, merge, embed, modify,
186
+ redistribute, and sell modified and unmodified copies of the Font
187
+ Software, subject to the following conditions:
188
+
189
+ 1) Neither the Font Software nor any of its individual components,
190
+ in Original or Modified Versions, may be sold by itself.
191
+
192
+ 2) Original or Modified Versions of the Font Software may be bundled,
193
+ redistributed and/or sold with any software, provided that each copy
194
+ contains the above copyright notice and this license. These can be
195
+ included either as stand-alone text files, human-readable headers or
196
+ in the appropriate machine-readable metadata fields within text or
197
+ binary files as long as those fields can be easily viewed by the user.
198
+
199
+ 3) No Modified Version of the Font Software may use the Reserved Font
200
+ Name(s) unless explicit written permission is granted by the corresponding
201
+ Copyright Holder. This restriction only applies to the primary font name as
202
+ presented to the users.
203
+
204
+ 4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
205
+ Software shall not be used to promote, endorse or advertise any
206
+ Modified Version, except to acknowledge the contribution(s) of the
207
+ Copyright Holder(s) and the Author(s) or with their explicit written
208
+ permission.
209
+
210
+ 5) The Font Software, modified or unmodified, in part or in whole,
211
+ must be distributed entirely under this license, and must not be
212
+ distributed under any other license. The requirement for fonts to
213
+ remain under this license does not apply to any document created
214
+ using the Font Software.
215
+
216
+ TERMINATION
217
+ This license becomes null and void if any of the above conditions are
218
+ not met.
219
+
220
+ DISCLAIMER
221
+ THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
222
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
223
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
224
+ OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
225
+ COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
226
+ INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
227
+ DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
228
+ FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
229
+ OTHER DEALINGS IN THE FONT SOFTWARE.
230
+ ```
package/README.md CHANGED
@@ -1,3 +1,120 @@
1
- # Temporary Holding Version
1
+ # @ranamaps/maps-js (beta)
2
2
 
3
- 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.
3
+ Rana Maps for the web: the map (`Rana.Map`) and the web services (`RanaClient`). Source version `0.4.0-beta.0`; the hosted preview below is `0.2.0-beta.1`. Proprietary,
4
+ free to use with a Rana key (LICENSE.md; third-party notices in NOTICES.md). npm publication is deferred. The prepared beta tarball is already hosted by Rana; the release is not finalized.
5
+
6
+ One package; there is nothing else to install. Needs a browser with ES2020.
7
+
8
+ ## Install
9
+
10
+ ```sh
11
+ npm i https://assets.ranamaps.com/sdk/js/0.2.0-beta.1/ranamaps-maps-js-0.2.0-beta.1.tgz
12
+ ```
13
+
14
+ ```js
15
+ import { Rana } from "@ranamaps/maps-js";
16
+ import "@ranamaps/maps-js/style.css";
17
+
18
+ const map = new Rana.Map({ key: "pk_live_…", container: "map", style: "day", center: { lat: 6.5244, lng: 3.3792 }, zoom: 12 });
19
+ map.on("load", () => map.addMarker({ lat: 6.5095, lng: 3.3711 }, Rana.MarkerContent.badge("₦2,500")));
20
+
21
+ const client = new Rana.RanaClient("pk_live_…");
22
+ const { routes } = await client.directions({ origin: { lat: 6.5095, lng: 3.3711 }, destination: { lat: 6.6018, lng: 3.3515 }, mode: "okada" });
23
+ if (routes[0]) map.showRoute(routes[0].geometry);
24
+ // "© Rana Maps © OpenStreetMap" stays on the map and with every answer you show.
25
+ ```
26
+
27
+ Without a bundler, copy the installed package’s `dist` directory to `/vendor/rana/` on your own site:
28
+
29
+ ```html
30
+ <link rel="stylesheet" href="/vendor/rana/style.css">
31
+ <script type="module">
32
+ import { Rana } from "/vendor/rana/index.js";
33
+ new Rana.Map({ key: "pk_live_…", container: "map" });
34
+ </script>
35
+ ```
36
+
37
+ ## What it does
38
+
39
+ - `Rana.Map`: Rana's day or night style or a Studio style code; camera (`setCenter`, `setZoom`, `flyTo`, `fitPoints`),
40
+ kit markers, clustered points, animated vehicles, progress lines, polygons, circles, user location, custom controls,
41
+ `showRoute`, `setStyle`, and events (`load`, `click`, `moveend`, `error`). Your key goes on Rana's map requests only;
42
+ secret keys are refused; the Rana credit is always shown.
43
+ - `RanaClient` calls `/v1` on maps-api.ranamaps.com with the `X-Rana-Key` header: `directions`, `matrix`,
44
+ `snapToRoads`, `reverseGeocode`, `geocode` (alpha), `places.autocomplete`, `places.details`, `places.nearby`
45
+ (alpha) and `describeKey`. Search results carry `source`, `osm`, `sources` and `alsoKnownAs`; use `resultSource` and
46
+ `isOsmPlaceDetails`. Result `kind` can be `address` (OSM address points, ids `osm-addr-…`); `resultKind()` maps
47
+ any unknown kind to `place`. Answers may carry `attributions` and `attributions_url`; show the response's
48
+ `attribution` string as given. Every failure is a `RanaError` with the API's `code`, `status`, `requestId` and
49
+ `retryAfter`. It does not retry by itself.
50
+ - Health telemetry: map started, style loaded, tile errors, SDK version. No location, viewport or user id. Off with
51
+ `telemetry: false`, or `Rana.telemetry.enabled = false` for the page.
52
+
53
+ ## Develop
54
+
55
+ ```sh
56
+ cd sdk/js && npm ci && npm run typecheck && npm test && npm run build
57
+ python3 -m http.server 8080 # then open http://localhost:8080/sample/index.html?key=pk_live_…
58
+ ```
59
+
60
+ The build embeds the worker script for rebundling and also emits `dist/rana-maps-worker.js` for strict-CSP self-hosting. It fails if a type declaration
61
+ names the engine (decision 0017). The client's contract tests against the real API run in Rana's API repository; the tests here need only this folder.
62
+
63
+ ## Journey interaction sample
64
+
65
+ See [sample interactions](../SAMPLES.md) for destination selection, replayed trips, draggable sheets,
66
+ viewport padding and optional live actions. See [configuration](../CUSTOMIZATION.md) for runtime settings.
67
+
68
+ ## Diagnostics and accounting
69
+
70
+ SDK health diagnostics are enabled by default. The telemetry opt-out affects only best-effort map-start,
71
+ style-load and tile-failure events sent to `/v1/telemetry`. It does not turn off server-side usage metering,
72
+ key restrictions, quotas or rate limits. Client diagnostic counts are not billable usage totals.
73
+ See [telemetry and privacy](../../docs/developers/telemetry-and-privacy.md) for fields, retention and switches.
74
+
75
+ The journey sample uses one location puck rather than an additional animated vehicle at the same replay fix.
76
+ Distinct vehicles/fleets can still use the independent vehicle APIs.
77
+
78
+ ## Smooth traveller movement
79
+
80
+ Opt into smooth location movement and vehicle-course or walking-compass heading through `LocationOptions`.
81
+ Existing defaults remain direct/generic. Timestamped fixes accept optional speed and course accuracy; compass
82
+ updates are independent. See [the motion contract](../LOCATION-MOTION.md) for policies, examples, lifecycle and limits.
83
+
84
+ ## Route-aware traveller movement
85
+
86
+ `setLocationRoute` optionally matches timestamped traveller fixes to an ordered path and animates along its bends.
87
+ Vehicle heading follows the route tangent; walking retains the phone compass. Match status and callbacks expose
88
+ confidence fallback. Clear the route at trip end or replace it after rerouting. The SDK makes no matching-service
89
+ requests and does not infer unknown roads. See the motion contract linked above for options, examples and limits.
90
+
91
+ ## Optional automatic rerouting
92
+
93
+ After setting the location route, explicitly enable `setAutomaticRerouting` with `ReroutingOptions` and a
94
+ `DirectionsReroutingProvider` using your client. The default is off. Sustained accurate off-route fixes can consume
95
+ normal directions usage. Cooldown, backoff, cancellation and stale-reply checks bound the work. The SDK
96
+ installs accepted movement geometry; `onRerouted` supplies the replacement for the host-owned line and trip UI.
97
+ Manual route changes disable the session. The linked motion contract includes complete examples and limits.
98
+
99
+
100
+ ### Measured journey contributions
101
+
102
+ Explicitly attach `JourneyTraceRecorder` after permission to contribute measured fixes. Collection is off by
103
+ default and independent of health diagnostics and rerouting. Raw measured positions feed staged trace/missing-road
104
+ review, never interpolated positions or planned route geometry. The samples label their replay traces as simulated
105
+ and the API validates them without adding learning evidence. See [the complete trace contract](../JOURNEY-TRACES.md) for APIs,
106
+ buffering/retry/revocation, deployment requirements and privacy. Rerouting has no separate attempt allowance;
107
+ normal account directions usage and server limits apply.
108
+
109
+ ## Worker hosting and bundlers
110
+
111
+ The next source build embeds its worker script, so bundling the SDK does not require copying a sibling worker file. Allow `worker-src blob:` in your site's CSP. For a CSP using only `worker-src 'self'`, copy `dist/rana-maps-worker.js` from this same SDK build to your site and configure its absolute URL before creating the first map:
112
+
113
+ ```js
114
+ import { Rana, setWorkerUrl } from "@ranamaps/maps-js";
115
+ setWorkerUrl(new URL("/vendor/rana/rana-maps-worker.js", location.href).href);
116
+ const map = new Rana.Map({ key: "pk_live_...", container: "map" });
117
+ // © Rana Maps © OpenStreetMap
118
+ ```
119
+
120
+ The URL is process-wide and cannot change after the first map. Use matching SDK/worker versions. These source fixes are unpublished; the existing hosted `0.2.0-beta.1` preview is unchanged.
package/dist/VERSION ADDED
@@ -0,0 +1 @@
1
+ 0.4.0-beta.0
@@ -0,0 +1,69 @@
1
+ import type { JourneyTraceBatch, JourneyTraceReceipt } from "./journey-trace.js";
2
+ import { RanaError } from "./errors.js";
3
+ import type { AutocompleteResponse, DirectionsRequest, DirectionsResponse, GeocodeResponse, KeyInfo, LatLng, MatrixRequest, MatrixResponse, NearbyRequest, NearbyResponse, OsmPlaceDetails, OsmPlaceId, PlaceDetails, SnapRequest, SnapResponse, Address } from "./types.js";
4
+ export declare const DEFAULT_API = "https://maps-api.ranamaps.com";
5
+ export interface ClientOptions {
6
+ /** Defaults to https://maps-api.ranamaps.com. */
7
+ baseUrl?: string;
8
+ /** For tests and server runtimes without a global fetch. */
9
+ fetch?: typeof fetch;
10
+ /** Milliseconds before each attempt gives up with RanaError("timeout"). Default 15,000. */
11
+ timeoutMs?: number;
12
+ /**
13
+ * Retries for reads and route calculations after a dropped connection, a timeout, 429, 502, 503 or 504: up to
14
+ * `attempts` more times (default 2), waiting a random time up to `baseDelayMs` × 2ⁿ (default 300), never more than
15
+ * `maxDelayMs` (default 5,000). A server's Retry-After is honoured when it fits; a longer one is returned as the
16
+ * error. Journey-trace uploads are never retried here. `false` turns retries off.
17
+ */
18
+ retry?: RetryOptions | false;
19
+ }
20
+ export interface RetryOptions {
21
+ attempts?: number;
22
+ baseDelayMs?: number;
23
+ maxDelayMs?: number;
24
+ }
25
+ /** Errors worth another try: the request never reached a working server, or it was asked to come back. */
26
+ export declare function isRetryable(error: RanaError): boolean;
27
+ /**
28
+ * How long to wait before retry `attempt` (0-based): a server's Retry-After when it fits under `maxDelayMs`, else
29
+ * full jitter up to `baseDelayMs` × 2^attempt. Null means do not retry (the server asked for longer than the cap).
30
+ */
31
+ export declare function retryDelayMs(attempt: number, error: RanaError, options: Required<RetryOptions>, random?: () => number): number | null;
32
+ export declare class RanaClient {
33
+ readonly key: string;
34
+ private readonly base;
35
+ private readonly fetcher;
36
+ private readonly timeoutMs;
37
+ private readonly retry;
38
+ /** Replaced in tests. */
39
+ protected sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
40
+ readonly places: {
41
+ autocomplete(q: string, options?: {
42
+ near?: LatLng;
43
+ limit?: number;
44
+ }): Promise<AutocompleteResponse>;
45
+ /** An `osm-poi-…`, `osm-stop-…`, `osm-street-…` or `osm-addr-…` id answers OsmPlaceDetails; check with `isOsmPlaceDetails`. */
46
+ details(placeId: OsmPlaceId): Promise<OsmPlaceDetails>;
47
+ details(placeId: string): Promise<PlaceDetails>;
48
+ nearby(request: NearbyRequest): Promise<NearbyResponse>;
49
+ };
50
+ constructor(key: string, options?: ClientOptions);
51
+ /** The key's organisation, plan and limits. Free. */
52
+ describeKey(): Promise<KeyInfo>;
53
+ directions(request: DirectionsRequest, signal?: AbortSignal): Promise<DirectionsResponse>;
54
+ uploadJourneyTrace(batch: JourneyTraceBatch, signal?: AbortSignal): Promise<JourneyTraceReceipt>;
55
+ /** Up to 100 cells (origins × destinations). Usage counts one unit per cell. */
56
+ matrix(request: MatrixRequest): Promise<MatrixResponse>;
57
+ snapToRoads(request: SnapRequest): Promise<SnapResponse>;
58
+ reverseGeocode(point: LatLng): Promise<Address>;
59
+ /** Alpha: finds few results outside Lagos. */
60
+ geocode(q: string, options?: {
61
+ near?: LatLng;
62
+ limit?: number;
63
+ }): Promise<GeocodeResponse>;
64
+ private get;
65
+ /** Every POST here but journey traces is a pure calculation, so repeating it is safe. */
66
+ private post;
67
+ private request;
68
+ private attempt;
69
+ }
@@ -0,0 +1,21 @@
1
+ /** The one error type of the SDK. `code` is the API's stable error code (see developers.ranamaps.com/errors.html). */
2
+ export declare class RanaError extends Error {
3
+ /** For example "rate_limited", "scope_not_allowed", or "network_error" when no answer arrived. */
4
+ readonly code: string;
5
+ /** HTTP status, or 0 when no answer arrived. */
6
+ readonly status: number;
7
+ /** Rana-Request-Id of the answer, to quote to support. */
8
+ readonly requestId: string | null;
9
+ /** Seconds to wait, from Retry-After, on 429 and 503. */
10
+ readonly retryAfter: number | null;
11
+ readonly name = "RanaError";
12
+ constructor(
13
+ /** For example "rate_limited", "scope_not_allowed", or "network_error" when no answer arrived. */
14
+ code: string, message: string,
15
+ /** HTTP status, or 0 when no answer arrived. */
16
+ status: number,
17
+ /** Rana-Request-Id of the answer, to quote to support. */
18
+ requestId?: string | null,
19
+ /** Seconds to wait, from Retry-After, on 429 and 503. */
20
+ retryAfter?: number | null);
21
+ }
@@ -0,0 +1,79 @@
1
+ import { setWorkerUrl } from "./worker.js";
2
+ import { BrowserLocationProvider } from "./location.js";
3
+ import { RanaClient, DEFAULT_API, type ClientOptions } from "./client.js";
4
+ export { isRetryable, retryDelayMs, type RetryOptions } from "./client.js";
5
+ import { RanaError } from "./errors.js";
6
+ import { ATTRIBUTION, RanaMap, STYLE_URLS, styleUrl, type MapOptions, type MapControls, type ControlCorner, type ControlSetting, type Marker, MarkerContent, type MarkerStyle, type PinGlyph, type MarkerState, type MarkerSize, type PointsOptions, type PointsOverlay, type VehicleOptions, type Vehicle, type LinePreset, type PolylineOptions, type RouteOptions, type RouteLine, type PolygonOptions, type CircleOptions, type Shape, type UserLocationOptions, type MapClick, type MapStyle } from "./map.js";
7
+ import { decodePolyline } from "./polyline.js";
8
+ import { telemetry } from "./telemetry.js";
9
+ import { VehicleAppearance, TravellerAppearance } from "./vehicle.js";
10
+ import { VERSION } from "./version.js";
11
+ export * from "./types.js";
12
+ export { resultSource, isOsmPlaceDetails, resultKind, isAddressId } from "./search.js";
13
+ export { DirectionsReroutingProvider } from "./rerouting.js";
14
+ export type { ReroutingOptions, ReroutingProvider, ReroutingRequest, ReroutingResult, ReroutingStatus, ReroutingState } from "./rerouting.js";
15
+ export type { LocationRouteOptions, LocationRouteStatus, LocationRouteState } from "./location-route.js";
16
+ export type { MapPadding, CameraOptions, CameraState, CameraBounds, CameraConstraints, GestureOptions, LocationTracking, LocationOptions, LocationMotion, LocationActivity, AttributionOptions, DragPhase, MapEvents, MapSettings, StyleExpression, FeatureFilter, DataLayerOptions, GeoJsonSource, StyleLayer, RenderedFeature } from "./settings.js";
17
+ export { BrowserLocationProvider } from "./location.js";
18
+ export type { LocationProvider, LocationFix, HeadingProvider, HeadingFix } from "./location.js";
19
+ export type { MarkerAnchor, MapEvent } from "./map.js";
20
+ export { KIT } from "./kit.js";
21
+ export { VehicleAppearance, TravellerAppearance } from "./vehicle.js";
22
+ export type { VehicleKind, VehicleState } from "./vehicle.js";
23
+ export type { RanaKit } from "./kit.js";
24
+ export { setWorkerUrl, RanaClient, RanaError, RanaMap, MarkerContent, ATTRIBUTION, STYLE_URLS, DEFAULT_API, VERSION, styleUrl, telemetry, decodePolyline };
25
+ export type { ClientOptions, MapOptions, MapControls, ControlCorner, ControlSetting, Marker, MarkerStyle, PinGlyph, MarkerState, MarkerSize, PointsOptions, PointsOverlay, VehicleOptions, Vehicle, LinePreset, PolylineOptions, RouteOptions, RouteLine, PolygonOptions, CircleOptions, Shape, UserLocationOptions, MapClick, MapStyle };
26
+ /** The namespace the docs use: new Rana.Map({...}) and new Rana.RanaClient(key). */
27
+ export declare const Rana: {
28
+ Map: typeof RanaMap;
29
+ MarkerContent: {
30
+ pin: (glyph?: PinGlyph, size?: MarkerSize) => MarkerContent;
31
+ labelledPin: (label: string, size?: MarkerSize) => MarkerContent;
32
+ badge: (text: string, icon?: PinGlyph) => MarkerContent;
33
+ dropPin: (glyph?: PinGlyph) => MarkerContent;
34
+ avatar: (name: string, live?: boolean) => MarkerContent;
35
+ dot: () => MarkerContent;
36
+ photo: (image: HTMLImageElement) => MarkerContent;
37
+ routeStart: () => MarkerContent;
38
+ routeStop: (label?: string) => MarkerContent;
39
+ routeDestination: () => MarkerContent;
40
+ image: (image: HTMLImageElement, width?: number, anchor?: import("./map.js").MarkerAnchor) => MarkerContent;
41
+ view: (element: HTMLElement, anchor?: import("./map.js").MarkerAnchor) => MarkerContent;
42
+ };
43
+ VehicleAppearance: {
44
+ kit: (vehicle: import("./vehicle.js").VehicleKind, options?: {
45
+ color?: string;
46
+ base?: "none" | "disc";
47
+ }) => VehicleAppearance;
48
+ image: (image: HTMLImageElement, options?: {
49
+ size?: number;
50
+ rotates?: boolean;
51
+ }) => VehicleAppearance;
52
+ animated: (frames: HTMLImageElement[], options?: {
53
+ frameMs?: number;
54
+ size?: number;
55
+ rotates?: boolean;
56
+ }) => VehicleAppearance;
57
+ view: (element: HTMLElement, options?: {
58
+ rotates?: boolean;
59
+ }) => VehicleAppearance;
60
+ };
61
+ TravellerAppearance: {
62
+ puck: () => TravellerAppearance;
63
+ dot: () => TravellerAppearance;
64
+ vehicle: (vehicle: VehicleAppearance) => TravellerAppearance;
65
+ };
66
+ setWorkerUrl: typeof setWorkerUrl;
67
+ BrowserLocationProvider: typeof BrowserLocationProvider;
68
+ RanaClient: typeof RanaClient;
69
+ RanaError: typeof RanaError;
70
+ telemetry: {
71
+ enabled: boolean;
72
+ };
73
+ version: string;
74
+ ATTRIBUTION: string;
75
+ decodePolyline: typeof decodePolyline;
76
+ };
77
+ export default Rana;
78
+ export { JourneyTraceRecorder } from "./journey-trace.js";
79
+ export type { JourneyTraceOptions, JourneyTracePoint, JourneyTraceBatch, JourneyTraceReceipt, JourneyTraceStatus } from "./journey-trace.js";