@tileflow/search 0.1.0-alpha.1 → 0.1.0-alpha.3

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.
Files changed (10) hide show
  1. package/README.md +170 -84
  2. package/dist/{chunk-YMLUPVQH.js → chunk-FEWG4I4E.js} +78 -12
  3. package/dist/{chunk-EDYCZVXI.js → chunk-R7KE2IN7.js} +84 -6
  4. package/dist/client.d.ts +8 -3
  5. package/dist/client.js +10 -4
  6. package/dist/contract.d.ts +266 -8
  7. package/dist/contract.js +27 -3
  8. package/dist/index.d.ts +2 -2
  9. package/dist/index.js +35 -5
  10. package/package.json +1 -1
package/README.md CHANGED
@@ -1,107 +1,193 @@
1
- # `@tileflow/search`
1
+ # @tileflow/search
2
2
 
3
- Headless geocoding and location selection for Tileflow.
3
+ Headless forward/reverse geocoding, autocomplete, category discovery, Nearby POIs and explicit
4
+ selected-place resolution. It uses `fetch` and has no renderer or global interaction state.
4
5
 
5
- ```ts
6
- import {geocode} from '@tileflow/search';
6
+ > Related packages and guides: [documentation index](https://raw.githubusercontent.com/tileflow/tileflow-sdk/main/llms.txt).
7
7
 
8
- const response = await geocode(
9
- {query: 'Rua Tileflow 42, Lisboa', language: 'en', retention: 'temporary'},
10
- {apiKey: process.env.TILEFLOW_API_KEY!},
11
- );
8
+ ## Install
12
9
 
13
- console.log(response.results);
10
+ ```sh
11
+ npm install @tileflow/search@alpha
14
12
  ```
15
13
 
16
- Reverse geocoding returns nearby addresses or geographic places:
14
+ Use Node.js 22 or another runtime with `fetch`. Live requests require enabled Tileflow Search and a
15
+ Team credential with `geocoding:read`. Keep privileged credentials on your application server.
16
+ Browser and mobile interfaces call their own authorized server endpoint.
17
+
18
+ Managed operations require paid Starter or a separate, finite Search evaluation grant. A Starter
19
+ trial or complimentary assignment alone does not authorize Search. Free Teams can read categories.
20
+ Installing this package does not enable the service or grant access.
21
+
22
+ ## Find nearby places
23
+
24
+ Run this example on your server with `TILEFLOW_API_KEY` set securely. It lists the current categories,
25
+ then makes one explicit Nearby request using a discovered ID:
26
+
27
+ <!-- docs:check -->
17
28
 
18
29
  ```ts
19
- import {geocodeReverse} from '@tileflow/search';
30
+ import {listCategories, searchNearby} from '@tileflow/search';
20
31
 
21
- const response = await geocodeReverse(
32
+ const apiKey = process.env.TILEFLOW_API_KEY;
33
+ if (!apiKey) throw new Error('Set TILEFLOW_API_KEY on the server.');
34
+ const options = {apiKey};
35
+ const catalog = await listCategories(options);
36
+ const category = catalog.categories.find(({name}) => name.toLowerCase().includes('coffee'));
37
+ if (!category) throw new Error('Choose a category from the current catalog.');
38
+
39
+ const page = await searchNearby(
22
40
  {
23
41
  position: [-9.1393, 38.7223],
24
- kinds: ['address', 'place'],
42
+ radiusMeters: 1000,
43
+ includeCategories: [category.id],
44
+ countries: ['PT'],
25
45
  language: 'en',
26
- retention: 'temporary',
46
+ limit: 20,
27
47
  },
28
- {apiKey: process.env.TILEFLOW_API_KEY!},
48
+ options,
29
49
  );
50
+
51
+ console.log(page.results, page.attribution, page.usage.units);
30
52
  ```
31
53
 
32
- Location selection starts with suggestions and resolves one selected token:
54
+ Coordinates are WGS84 `[longitude, latitude]`. Results preserve native AWS proximity ordering.
55
+ A POI's optional `name` is its establishment title; `label` and `address` describe its location.
56
+ Categories and business-chain labels appear only when supplied. Missing metadata does not establish
57
+ opening status, freshness or completeness. Co-located businesses are not merged.
58
+
59
+ Display every attribution entry with results, preserving supplied URLs. Results and opaque references
60
+ are temporary. Do not build a permanent place catalog, cache results, or persist provider references.
61
+
62
+ ## Request another page or resolve a selection
63
+
64
+ Save the original request in the current interaction. Another page repeats that request with the
65
+ returned `nextCursor`; no page is fetched automatically. A successful empty page can have a cursor.
66
+ Each explicit page costs 25 API units. There is no total-count or snapshot-consistency promise.
67
+
68
+ <!-- docs:check -->
33
69
 
34
70
  ```ts
35
- import {autocomplete, resolveSuggestion} from '@tileflow/search';
71
+ import {type NearbyRequest, resolvePlace, searchNearby} from '@tileflow/search';
36
72
 
37
- const suggestions = await autocomplete(
38
- {query: 'Hospital La Paz', language: 'en'},
39
- {apiKey: process.env.TILEFLOW_API_KEY!},
40
- );
73
+ const apiKey = process.env.TILEFLOW_API_KEY;
74
+ if (!apiKey) throw new Error('Set TILEFLOW_API_KEY on the server.');
75
+ const options = {apiKey};
76
+ const original: NearbyRequest = {position: [-9.1393, 38.7223], radiusMeters: 1000};
77
+
78
+ export function requestPage(cursor?: string) {
79
+ return searchNearby({...original, ...(cursor ? {cursor} : {})}, options);
80
+ }
41
81
 
42
- async function resolveUserSelection(token: string) {
43
- const response = await resolveSuggestion(
44
- {token, retention: 'temporary'},
45
- {apiKey: process.env.TILEFLOW_API_KEY!},
46
- );
47
- console.log(response.result);
82
+ export function resolveSelectedPlace(token: string) {
83
+ return resolvePlace({token}, options);
48
84
  }
49
85
  ```
50
86
 
51
- Call `resolveUserSelection` only after an explicit user selection. The package provides no UI.
52
-
53
- `geocode` and `geocodeReverse` each send one authenticated request to Tileflow and never retry
54
- automatically. They validate strict requests and bounded normalized responses. Forward queries
55
- contain at most 200 characters; `bounds` and `proximity` are mutually exclusive. Reverse positions
56
- are `[longitude, latitude]` WGS84 coordinates. Reverse `limit` defaults to 1 and accepts 1–10.
57
- Optional `kinds` are an OR filter containing 1–4 of `address`, `street`, `locality`, or `place`;
58
- order adds no priority and repeated values have no additional effect. Provider selection and raw
59
- provider options are not public.
60
-
61
- `autocomplete` accepts the same text, language, `bounds`, and `proximity` rules as forward
62
- geocoding. Its `limit` defaults to 5 and accepts 1–10. Suggestions are ephemeral opaque tokens;
63
- they can expire, and an expired token requires fresh suggestions. Suggestions do not promise a
64
- match for every named location and do not provide category or discovery queries. `autocomplete`
65
- rejects `retention` and returns no usage record. Each completed `resolveSuggestion` returns one
66
- existing result and `usage.units: 1`; replaying a resolution is another request and unit.
67
-
68
- Applications may debounce autocomplete calls and cancel superseded calls or ignore stale results.
69
- The client has no shared interaction state and never retries automatically. Do not expose
70
- privileged credentials in browser code.
71
-
72
- Reverse results are nearby candidates reasonably corresponding to the position, in provider order.
73
- They do not guarantee containment, administrative membership, parcel or entrance precision,
74
- routability, postal precision, or a validated or deliverable address. A successful empty result
75
- still reports `usage.units: 1`.
76
-
77
- Supply `fetch` and `apiUrl` for tests or a custom runtime, and pass an `AbortSignal` to control
78
- cancellation. API URLs require HTTPS except for an explicit loopback HTTP origin used during local
79
- development.
80
-
81
- `retention` expresses whether the client intends to store results. It accepts `temporary` (the
82
- default) or `persistent`. `temporary` permits immediate use without a right granted by Tileflow to
83
- retain results permanently. `persistent` requests compatible storage rights for the client; it
84
- neither requests nor promises Tileflow storage. Persistent retention is unavailable
85
- for some territories. The API reports `GEOCODING_TERRITORY_UNSUPPORTED` with HTTP 422 when the
86
- requested mode is unsupported, including AWS HERE-backed geocoding in Japan. This applies equally
87
- to forward, reverse, and suggestion resolution. It does not apply to autocomplete. Retain only a
88
- resolved candidate with its source and attribution; do not retain a suggestion token or label.
89
-
90
- Geocoding requires an enabled Tileflow API environment and a Team key or signed Team capability
91
- with `geocoding:read`; a disabled service returns `GEOCODING_DISABLED`. Each completed forward,
92
- reverse, or suggestion resolution reports `usage.units: 1`. Forward and reverse also count empty
93
- results. Autocomplete consumes zero units. These are usage units, not monetary prices.
94
-
95
- Suggestion resolution can report `GEOCODING_INVALID_SUGGESTION` (400),
96
- `GEOCODING_SUGGESTION_EXPIRED` (410), `GEOCODING_UPSTREAM_THROTTLED` (429), or
97
- `GEOCODING_PICK_LIMIT_EXCEEDED` (429). The client never retries automatically.
98
-
99
- Responses include source metadata and one or more attribution entries. Applications must pass every
100
- entry through to end users or documentation and preserve any supplied URL as required by its source
101
- terms. A source revision may be `null` when no reliable revision is available.
102
-
103
- The package does not provide autocomplete UI, structured address input, category discovery,
104
- batches, or address validation.
105
-
106
- Use `@tileflow/search/contract` for the request and result schemas, or
107
- `@tileflow/search/client` for transport without importing the root facade.
87
+ Invoke these handlers only after explicit user actions. Use a returned POI token for resolution;
88
+ map feature IDs, click coordinates and raw AWS Place IDs are not selection tokens. A result without
89
+ a token can be displayed but cannot be resolved. Selection and pagination references cannot be
90
+ interchanged or moved between Teams. Changed query, language, filters or limit invalidates a cursor.
91
+
92
+ `resolvePlace` and `resolveSuggestion` perform the same single resolution operation. Neither fetches
93
+ other results or retries automatically. An expired reference requires an explicit fresh search.
94
+
95
+ ## Geocode text, reverse a position, or offer suggestions
96
+
97
+ <!-- docs:check -->
98
+
99
+ ```ts
100
+ import {autocomplete, geocode, geocodeReverse, resolveSuggestion} from '@tileflow/search';
101
+
102
+ const apiKey = process.env.TILEFLOW_API_KEY;
103
+ if (!apiKey) throw new Error('Set TILEFLOW_API_KEY on the server.');
104
+ const options = {apiKey};
105
+
106
+ export const findAddress = (query: string) => geocode({query, language: 'en'}, options);
107
+ export const reversePosition = (position: [number, number]) =>
108
+ geocodeReverse({position, kinds: ['address', 'place']}, options);
109
+ export const suggestPlaces = (query: string) => autocomplete({query, language: 'en'}, options);
110
+ export const resolveSelection = (token: string) => resolveSuggestion({token}, options);
111
+ ```
112
+
113
+ Text search and Nearby are distinct operations. Suggestions have no position. Resolve only the
114
+ selected suggestion. Reverse results are candidates in provider order, without containment,
115
+ entrance precision, routability, deliverability or address-validation guarantees.
116
+
117
+ ## Limits and temporary use
118
+
119
+ Forward/autocomplete text accepts 1–200 characters. Their limit defaults to 5 and accepts 1–10;
120
+ reverse defaults to 1 and accepts 1–10. Reverse kinds are an OR of `address`, `street`, `locality`
121
+ and `place`. Forward/autocomplete `bounds` and `proximity` are mutually exclusive.
122
+
123
+ Nearby requires `position`, defaults to 20 results and accepts 1–100. Optional `radiusMeters` accepts
124
+ 1–21,000,000. A bbox is `[west, south, east, north]`, with west < east and south < north; wrapping
125
+ antimeridian boxes are unsupported. Position alone uses native provider scope and makes no hard
126
+ extent promise. Combined radius+bbox is currently rejected with `GEOCODING_FILTER_UNSUPPORTED`.
127
+
128
+ Use literal current category IDs, including spaces and punctuation. Include/exclude lists accept up
129
+ to ten IDs each. Inclusion is OR; exclusion vetoes matches. No parent-category expansion is implied.
130
+ Country filters accept up to 100 ISO alpha-2/alpha-3 codes and intersect spatial/category constraints.
131
+ Unknown IDs or countries are rejected. Language requests use provider fallback, without a translation
132
+ or localization completeness guarantee. Nearby does not accept text queries or an ordering selector.
133
+
134
+ Nearby requests are bounded to 32 KiB and responses to 512 KiB. Cursors accept at most 8192 characters;
135
+ selection tokens at most 2048. Oversized/invalid pages fail as a whole. The SDK parses strict schemas
136
+ and never drops malformed results to manufacture a valid success.
137
+
138
+ Forward, reverse and resolution accept only `retention: 'temporary'`, also the default. Persistent
139
+ retention, Advanced features and caller-selected provider options are rejected before provider work.
140
+
141
+ ## Usage and errors
142
+
143
+ | Completed operation | Shared API units |
144
+ | ------------------------------------- | ---------------: |
145
+ | Category discovery | 0 |
146
+ | Autocomplete | 10 |
147
+ | Forward, reverse, explicit resolution | 25 |
148
+ | Each Nearby page | 25 |
149
+
150
+ Valid empty responses consume the same units. Three autocomplete calls and one resolution consume
151
+ 55 units. These are part of Starter's shared API allowance, with no separate Search credits or
152
+ commercial search session. Hovering, displaying results and moving a map do not call Search.
153
+
154
+ `GeocodingError` exposes `status`, nullable `code`, nullable `requestId` and nullable bounded
155
+ `retryAfterSeconds`. The client never retries, including after throttling. Use `signal` for
156
+ cancellation. Network failures can leave server completion uncertain.
157
+
158
+ | Code | Action |
159
+ | ---------------------------------------------------------------- | ------------------------------------------------------------------- |
160
+ | `GEOCODING_PLAN_UNAVAILABLE` | Use paid Starter or request an eligible evaluation. |
161
+ | `GEOCODING_EVALUATION_REQUIRED` / `GEOCODING_EVALUATION_EXPIRED` | Ask the Team's operator to review evaluation access. |
162
+ | `GEOCODING_EVALUATION_EXHAUSTED` | Stop requests; review evaluation limits. |
163
+ | `GEOCODING_PICK_LIMIT_EXCEEDED` / `GEOCODING_UPSTREAM_THROTTLED` | Respect `retryAfterSeconds`; retry only deliberately. |
164
+ | `GEOCODING_INVALID_CURSOR` / `GEOCODING_INVALID_SUGGESTION` | Check the Team and original query; start a fresh search explicitly. |
165
+ | `GEOCODING_CURSOR_EXPIRED` / `GEOCODING_SUGGESTION_EXPIRED` | Request fresh results explicitly. |
166
+ | `GEOCODING_USAGE_UNCONFIRMED` | Completion may already be charged. Inspect usage before repeating. |
167
+ | `GEOCODING_DISABLED` | Search is disabled; installation does not activate it. |
168
+
169
+ Rejected or failed operations do not return a completed usage record. Never translate an unconfirmed
170
+ completion into zero units. Confirmed server completion is not undone by a later disconnection.
171
+ API URLs require HTTPS, except explicit loopback HTTP during development. `fetch` can be injected
172
+ for local tests. Request and response schemas are exported from `@tileflow/search/contract`;
173
+ transport is available from `@tileflow/search/client`.
174
+
175
+ ## Integrate an independent search interaction
176
+
177
+ Each widget owns its timer, abort controller, request generation and selection state. Debounce input;
178
+ suppress requests while IME composition is active; launch the final input on `compositionend`.
179
+ Increment the generation and abort previous work on input, selection, dismissal or a view change.
180
+ Apply a response only if its generation still matches, even if abort did not stop the transport.
181
+
182
+ Use an accessible combobox/listbox for suggestions: arrow keys change the active option, Enter or a
183
+ touch/click explicitly selects it, and Escape dismisses it. Give the input a label, maintain focus
184
+ and active-option semantics, and announce loading, empty results and errors through a polite status
185
+ region. Preserve attribution beside displayed results. Do not resolve on hover or focus changes.
186
+
187
+ An explicit category action can call Nearby. Moving a map offers a “Search this area” button; only
188
+ pressing it submits the new bounds. A late reply must not move the camera after a newer selection or
189
+ view change. Keep independent generations for independent widgets. The SDK's tests demonstrate
190
+ cancellation and stale-suggestion handling; it does not supply a UI component or client credentials.
191
+
192
+ For a published package, its installed README and declarations describe that release; a link to
193
+ GitHub `main` can describe newer source.
package/dist/{chunk-YMLUPVQH.js → chunk-FEWG4I4E.js} RENAMED
@@ -5,13 +5,24 @@ import {
5
5
  geocodingForwardResponseSchema,
6
6
  geocodingLimits,
7
7
  geocodingReverseRequestSchema,
8
+ nearbyLimits,
9
+ nearbyRequestSchema,
10
+ nearbyResponseSchema,
8
11
  resolveSuggestionRequestSchema,
9
- resolveSuggestionResponseSchema
10
- } from "./chunk-EDYCZVXI.js";
12
+ resolveSuggestionResponseSchema,
13
+ searchCategoriesResponseSchema
14
+ } from "./chunk-R7KE2IN7.js";
11
15
 
12
16
  // src/client.ts
13
17
  import { z } from "zod";
14
18
  var GEOCODING_ERROR_CODES = [
19
+ "GEOCODING_FILTER_UNSUPPORTED",
20
+ "GEOCODING_PLAN_UNAVAILABLE",
21
+ "GEOCODING_EVALUATION_REQUIRED",
22
+ "GEOCODING_EVALUATION_EXPIRED",
23
+ "GEOCODING_EVALUATION_EXHAUSTED",
24
+ "GEOCODING_INVALID_CURSOR",
25
+ "GEOCODING_CURSOR_EXPIRED",
15
26
  "GEOCODING_ABORTED",
16
27
  "GEOCODING_DISABLED",
17
28
  "GEOCODING_INVALID_REQUEST",
@@ -20,7 +31,6 @@ var GEOCODING_ERROR_CODES = [
20
31
  "GEOCODING_QUOTA_EXCEEDED",
21
32
  "GEOCODING_REQUEST_TOO_LARGE",
22
33
  "GEOCODING_SUGGESTION_EXPIRED",
23
- "GEOCODING_TERRITORY_UNSUPPORTED",
24
34
  "GEOCODING_UNAVAILABLE",
25
35
  "GEOCODING_UPSTREAM_INVALID",
26
36
  "GEOCODING_UPSTREAM_THROTTLED",
@@ -29,6 +39,13 @@ var GEOCODING_ERROR_CODES = [
29
39
  "GEOCODING_USAGE_UNCONFIRMED"
30
40
  ];
31
41
  var geocodingErrorStatuses = {
42
+ GEOCODING_FILTER_UNSUPPORTED: 422,
43
+ GEOCODING_PLAN_UNAVAILABLE: 403,
44
+ GEOCODING_EVALUATION_REQUIRED: 403,
45
+ GEOCODING_EVALUATION_EXPIRED: 403,
46
+ GEOCODING_EVALUATION_EXHAUSTED: 429,
47
+ GEOCODING_INVALID_CURSOR: 400,
48
+ GEOCODING_CURSOR_EXPIRED: 410,
32
49
  GEOCODING_ABORTED: 499,
33
50
  GEOCODING_DISABLED: 503,
34
51
  GEOCODING_INVALID_REQUEST: 400,
@@ -37,7 +54,6 @@ var geocodingErrorStatuses = {
37
54
  GEOCODING_QUOTA_EXCEEDED: 429,
38
55
  GEOCODING_REQUEST_TOO_LARGE: 413,
39
56
  GEOCODING_SUGGESTION_EXPIRED: 410,
40
- GEOCODING_TERRITORY_UNSUPPORTED: 422,
41
57
  GEOCODING_UNAVAILABLE: 503,
42
58
  GEOCODING_UPSTREAM_INVALID: 502,
43
59
  GEOCODING_UPSTREAM_THROTTLED: 429,
@@ -60,12 +76,14 @@ var GeocodingError = class extends Error {
60
76
  code;
61
77
  requestId;
62
78
  status;
79
+ retryAfterSeconds;
63
80
  constructor(message, input) {
64
81
  super(message);
65
82
  this.name = "GeocodingError";
66
83
  this.code = input.code ?? null;
67
84
  this.requestId = input.requestId ?? null;
68
85
  this.status = input.status;
86
+ this.retryAfterSeconds = input.retryAfterSeconds ?? null;
69
87
  }
70
88
  };
71
89
  async function geocode(request, options) {
@@ -113,26 +131,60 @@ async function resolveSuggestion(request, options) {
113
131
  throw new Error("Invalid Tileflow geocoding request");
114
132
  }
115
133
  return requestGeocoding(
116
- "/v1/geocoding/resolve-suggestion",
134
+ "/v1/geocoding/resolve",
117
135
  parsedRequest.data,
118
136
  options,
119
137
  resolveSuggestionResponseSchema
120
138
  );
121
139
  }
122
- async function requestGeocoding(path, request, options, responseSchema, isExpectedResponse = () => true) {
140
+ var resolvePlace = resolveSuggestion;
141
+ async function searchNearby(request, options) {
142
+ const parsed = nearbyRequestSchema.safeParse(request);
143
+ if (!parsed.success) throw new Error("Invalid Tileflow Nearby request");
144
+ const query = parsed.data;
145
+ if (query.radiusMeters !== void 0 && query.bounds !== void 0 || query.includeCategories?.some((id) => query.excludeCategories?.includes(id))) {
146
+ throw new GeocodingError("Unsupported geocoding filters", {
147
+ code: "GEOCODING_FILTER_UNSUPPORTED",
148
+ status: 422
149
+ });
150
+ }
151
+ return requestGeocoding(
152
+ "/v1/geocoding/nearby",
153
+ query,
154
+ options,
155
+ nearbyResponseSchema,
156
+ (response) => response.results.length <= query.limit,
157
+ nearbyLimits.maximumResponseBytes
158
+ );
159
+ }
160
+ function listCategories(options) {
161
+ return requestGeocoding(
162
+ "/v1/geocoding/categories",
163
+ void 0,
164
+ options,
165
+ searchCategoriesResponseSchema,
166
+ () => true,
167
+ nearbyLimits.maximumResponseBytes
168
+ );
169
+ }
170
+ async function requestGeocoding(path, request, options, responseSchema, isExpectedResponse = () => true, maximumResponseBytes = geocodingLimits.maximumResponseBytes) {
171
+ const bodyText = request === void 0 ? void 0 : JSON.stringify(request);
172
+ const maximumRequestBytes = path === "/v1/geocoding/nearby" ? nearbyLimits.maximumRequestBytes : 8 * 1024;
173
+ if (bodyText && new TextEncoder().encode(bodyText).byteLength > maximumRequestBytes)
174
+ throw new Error("Tileflow Search request is too large");
123
175
  const apiKey = normalizeApiKey(options.apiKey);
124
176
  const apiUrl = normalizeApiUrl(options.apiUrl ?? "https://api.tileflow.dev");
125
177
  const fetcher = options.fetch ?? fetch;
126
178
  let response;
127
179
  try {
128
180
  response = await fetcher(`${apiUrl}${path}`, {
129
- body: JSON.stringify(request),
181
+ ...bodyText === void 0 ? {} : { body: bodyText },
130
182
  headers: {
131
183
  Accept: "application/json",
132
184
  Authorization: `Bearer ${apiKey}`,
133
185
  "Content-Type": "application/json"
134
186
  },
135
- method: "POST",
187
+ method: request === void 0 ? "GET" : "POST",
136
188
  redirect: "error",
137
189
  signal: options.signal
138
190
  });
@@ -149,7 +201,7 @@ async function requestGeocoding(path, request, options, responseSchema, isExpect
149
201
  }
150
202
  let body;
151
203
  try {
152
- body = await readBoundedJson(response, geocodingLimits.maximumResponseBytes, options.signal);
204
+ body = await readBoundedJson(response, maximumResponseBytes, options.signal);
153
205
  } catch (error) {
154
206
  if (options.signal?.aborted) throw options.signal.reason ?? error;
155
207
  throw new GeocodingError("Tileflow geocoding returned an invalid response", {
@@ -189,18 +241,25 @@ function normalizeApiUrl(value) {
189
241
  return url.href.replace(/\/$/u, "");
190
242
  }
191
243
  async function readGeocodingError(response, signal) {
244
+ const value = response.headers.get("Retry-After");
245
+ const delay = value && /^\d{1,8}$/u.test(value) ? Number(value) : null;
246
+ const retryAfterSeconds = delay !== null && delay <= 31536e3 ? delay : null;
192
247
  let body;
193
248
  try {
194
249
  body = await readBoundedJson(response, geocodingLimits.maximumSafeErrorBytes, signal);
195
250
  } catch (error) {
196
251
  if (signal?.aborted) throw signal.reason ?? error;
197
- return new GeocodingError("Tileflow geocoding request failed", { status: response.status });
252
+ return new GeocodingError("Tileflow geocoding request failed", {
253
+ retryAfterSeconds,
254
+ status: response.status
255
+ });
198
256
  }
199
257
  const geocoding = geocodingErrorResponseSchema.safeParse(body);
200
258
  if (geocoding.success && geocodingErrorStatuses[geocoding.data.code] === response.status) {
201
259
  return new GeocodingError(geocoding.data.error, {
202
260
  code: geocoding.data.code,
203
261
  requestId: geocoding.data.requestId,
262
+ retryAfterSeconds,
204
263
  status: response.status
205
264
  });
206
265
  }
@@ -208,10 +267,14 @@ async function readGeocodingError(response, signal) {
208
267
  if (credential.success && [401, 403, 429].includes(response.status)) {
209
268
  return new GeocodingError(credential.data.error, {
210
269
  requestId: credential.data.requestId,
270
+ retryAfterSeconds,
211
271
  status: response.status
212
272
  });
213
273
  }
214
- return new GeocodingError("Tileflow geocoding request failed", { status: response.status });
274
+ return new GeocodingError("Tileflow geocoding request failed", {
275
+ retryAfterSeconds,
276
+ status: response.status
277
+ });
215
278
  }
216
279
  async function readBoundedJson(response, maximumBytes, signal) {
217
280
  const declaredLength = response.headers.get("Content-Length");
@@ -282,5 +345,8 @@ export {
282
345
  geocode,
283
346
  geocodeReverse,
284
347
  autocomplete,
285
- resolveSuggestion
348
+ resolveSuggestion,
349
+ resolvePlace,
350
+ searchNearby,
351
+ listCategories
286
352
  };
package/dist/{chunk-EDYCZVXI.js → chunk-R7KE2IN7.js} RENAMED
@@ -24,8 +24,8 @@ var boundedText = (maximum) => z.string().trim().min(1).max(maximum).refine((val
24
24
  var longitude = z.number().finite().min(-180).max(180);
25
25
  var latitude = z.number().finite().min(-90).max(90);
26
26
  var geocodingPositionSchema = z.tuple([longitude, latitude]);
27
- var geocodingRetentionModes = ["temporary", "persistent"];
28
- var geocodingBoundsSchema = z.tuple([longitude, latitude, longitude, latitude]).refine(([west, south, east]) => west < east, { message: "West must be less than east" }).refine(([, south, , north]) => south < north, {
27
+ var geocodingRetentionModes = ["temporary"];
28
+ var geocodingBoundsSchema = z.tuple([longitude, latitude, longitude, latitude]).refine(([west, , east]) => west < east, { message: "West must be less than east" }).refine(([, south, , north]) => south < north, {
29
29
  message: "South must be less than north"
30
30
  });
31
31
  var geocodingForwardRequestSchema = z.object({
@@ -82,7 +82,21 @@ var geocodingAddressSchema = z.object({
82
82
  region: addressPart.optional(),
83
83
  street: addressPart.optional()
84
84
  }).strict();
85
+ var searchLiteralText = (maximum) => z.string().min(1).max(maximum).refine((value) => !/[\p{Cc}\p{Cs}]/u.test(value));
86
+ var searchCategoryIdSchema = searchLiteralText(100);
87
+ var searchCategorySchema = z.object({
88
+ id: searchCategoryIdSchema,
89
+ name: searchLiteralText(100),
90
+ localizedName: searchLiteralText(100).optional(),
91
+ primary: z.boolean().optional()
92
+ }).strict();
93
+ var searchPlaceMetadata = {
94
+ name: searchLiteralText(200).optional(),
95
+ categories: z.array(searchCategorySchema).min(1).max(100).optional(),
96
+ businessChains: z.array(z.object({ id: searchLiteralText(100), name: searchLiteralText(100) }).strict()).min(1).max(100).optional()
97
+ };
85
98
  var geocodingResultSchema = z.object({
99
+ ...searchPlaceMetadata,
86
100
  address: geocodingAddressSchema,
87
101
  bounds: geocodingBoundsSchema.optional(),
88
102
  kind: z.enum(geocodingResultKinds),
@@ -108,7 +122,7 @@ var geocodingForwardResponseSchema = z.object({
108
122
  results: z.array(geocodingResultSchema).max(geocodingLimits.maximumLimit),
109
123
  schemaVersion: z.literal(1),
110
124
  source: geocodingSourceSchema,
111
- usage: z.object({ units: z.literal(1) }).strict()
125
+ usage: z.object({ units: z.literal(25) }).strict()
112
126
  }).strict();
113
127
  var geocodingReverseResponseSchema = geocodingForwardResponseSchema;
114
128
  var geocodingSuggestionSchema = z.object({
@@ -120,7 +134,8 @@ var autocompleteResponseSchema = z.object({
120
134
  attribution: z.array(geocodingAttributionSchema).min(1).max(geocodingLimits.maximumAttributionEntries),
121
135
  schemaVersion: z.literal(1),
122
136
  source: geocodingSourceSchema,
123
- suggestions: z.array(geocodingSuggestionSchema).max(geocodingLimits.maximumLimit)
137
+ suggestions: z.array(geocodingSuggestionSchema).max(geocodingLimits.maximumLimit),
138
+ usage: z.object({ units: z.literal(10) }).strict()
124
139
  }).strict();
125
140
  var resolveSuggestionRequestSchema = z.object({
126
141
  retention: z.enum(geocodingRetentionModes).default("temporary"),
@@ -131,7 +146,7 @@ var resolveSuggestionResponseSchema = z.object({
131
146
  result: geocodingResultSchema,
132
147
  schemaVersion: z.literal(1),
133
148
  source: geocodingSourceSchema,
134
- usage: z.object({ units: z.literal(1) }).strict()
149
+ usage: z.object({ units: z.literal(25) }).strict()
135
150
  }).strict();
136
151
  function isCredentialFreeHttpsUrl(value) {
137
152
  try {
@@ -141,6 +156,57 @@ function isCredentialFreeHttpsUrl(value) {
141
156
  return false;
142
157
  }
143
158
  }
159
+ var nearbyLimits = Object.freeze({
160
+ defaultLimit: 20,
161
+ maximumLimit: 100,
162
+ maximumRadiusMeters: 21e6,
163
+ maximumCategoryCharacters: 100,
164
+ maximumFilterCategories: 10,
165
+ maximumCountries: 100,
166
+ maximumCursorCharacters: 8192,
167
+ maximumRequestBytes: 32 * 1024,
168
+ maximumResponseBytes: 512 * 1024
169
+ });
170
+ var nearbyCursorSchema = z.string().min(1).max(nearbyLimits.maximumCursorCharacters).regex(/^[\x21-\x7e]+$/u);
171
+ var categoryFilter = z.array(searchCategoryIdSchema).min(1).max(nearbyLimits.maximumFilterCategories);
172
+ var nearbyRequestSchema = z.object({
173
+ position: geocodingPositionSchema,
174
+ radiusMeters: z.number().int().min(1).max(nearbyLimits.maximumRadiusMeters).optional(),
175
+ bounds: geocodingBoundsSchema.optional(),
176
+ includeCategories: categoryFilter.optional(),
177
+ excludeCategories: categoryFilter.optional(),
178
+ countries: z.array(z.string().regex(/^(?:[A-Z]{2}|[A-Z]{3})$/u)).min(1).max(nearbyLimits.maximumCountries).optional(),
179
+ language: geocodingForwardRequestSchema.shape.language,
180
+ limit: z.number().int().min(1).max(nearbyLimits.maximumLimit).default(nearbyLimits.defaultLimit),
181
+ cursor: nearbyCursorSchema.optional()
182
+ }).strict();
183
+ var nearbyPlaceSchema = geocodingResultSchema.omit({ sourceRef: true }).extend({
184
+ kind: z.literal("place"),
185
+ distanceMeters: z.number().finite().nonnegative().optional(),
186
+ token: geocodingSuggestionSchema.shape.token.optional()
187
+ }).strict();
188
+ var nearbyResponseSchema = z.object({
189
+ schemaVersion: z.literal(1),
190
+ provider: z.literal("aws"),
191
+ results: z.array(nearbyPlaceSchema).max(nearbyLimits.maximumLimit),
192
+ nextCursor: nearbyCursorSchema.optional(),
193
+ source: geocodingSourceSchema,
194
+ attribution: geocodingForwardResponseSchema.shape.attribution,
195
+ usage: z.object({ units: z.literal(25) }).strict()
196
+ }).strict().refine(
197
+ (value) => new TextEncoder().encode(JSON.stringify(value)).byteLength <= nearbyLimits.maximumResponseBytes,
198
+ { message: "Nearby response exceeds the encoded byte limit" }
199
+ );
200
+ var searchCategoriesResponseSchema = z.object({
201
+ schemaVersion: z.literal(1),
202
+ provider: z.literal("aws"),
203
+ categories: z.array(searchCategorySchema).min(1).max(2e3),
204
+ source: geocodingSourceSchema,
205
+ attribution: geocodingForwardResponseSchema.shape.attribution,
206
+ usage: z.object({ units: z.literal(0) }).strict()
207
+ }).strict();
208
+ var resolvePlaceRequestSchema = resolveSuggestionRequestSchema;
209
+ var resolvePlaceResponseSchema = resolveSuggestionResponseSchema;
144
210
 
145
211
  export {
146
212
  geocodingLimits,
@@ -153,6 +219,10 @@ export {
153
219
  geocodingReverseRequestSchema,
154
220
  geocodingResultKinds,
155
221
  geocodingAddressSchema,
222
+ searchLiteralText,
223
+ searchCategoryIdSchema,
224
+ searchCategorySchema,
225
+ searchPlaceMetadata,
156
226
  geocodingResultSchema,
157
227
  geocodingSourceSchema,
158
228
  geocodingAttributionSchema,
@@ -161,5 +231,13 @@ export {
161
231
  geocodingSuggestionSchema,
162
232
  autocompleteResponseSchema,
163
233
  resolveSuggestionRequestSchema,
164
- resolveSuggestionResponseSchema
234
+ resolveSuggestionResponseSchema,
235
+ nearbyLimits,
236
+ nearbyCursorSchema,
237
+ nearbyRequestSchema,
238
+ nearbyPlaceSchema,
239
+ nearbyResponseSchema,
240
+ searchCategoriesResponseSchema,
241
+ resolvePlaceRequestSchema,
242
+ resolvePlaceResponseSchema
165
243
  };
package/dist/client.d.ts CHANGED
@@ -1,7 +1,7 @@
1
- import { AutocompleteRequest, AutocompleteResponse, GeocodingForwardRequest, GeocodingForwardResponse, GeocodingReverseRequest, GeocodingReverseResponse, ResolveSuggestionRequest, ResolveSuggestionResponse } from './contract.js';
1
+ import { AutocompleteRequest, AutocompleteResponse, GeocodingForwardRequest, GeocodingForwardResponse, GeocodingReverseRequest, GeocodingReverseResponse, SearchCategoriesResponse, ResolveSuggestionRequest, ResolveSuggestionResponse, NearbyRequest, NearbyResponse } from './contract.js';
2
2
  import 'zod';
3
3
 
4
- declare const GEOCODING_ERROR_CODES: readonly ["GEOCODING_ABORTED", "GEOCODING_DISABLED", "GEOCODING_INVALID_REQUEST", "GEOCODING_INVALID_SUGGESTION", "GEOCODING_PICK_LIMIT_EXCEEDED", "GEOCODING_QUOTA_EXCEEDED", "GEOCODING_REQUEST_TOO_LARGE", "GEOCODING_SUGGESTION_EXPIRED", "GEOCODING_TERRITORY_UNSUPPORTED", "GEOCODING_UNAVAILABLE", "GEOCODING_UPSTREAM_INVALID", "GEOCODING_UPSTREAM_THROTTLED", "GEOCODING_UPSTREAM_TIMEOUT", "GEOCODING_UPSTREAM_UNAVAILABLE", "GEOCODING_USAGE_UNCONFIRMED"];
4
+ declare const GEOCODING_ERROR_CODES: readonly ["GEOCODING_FILTER_UNSUPPORTED", "GEOCODING_PLAN_UNAVAILABLE", "GEOCODING_EVALUATION_REQUIRED", "GEOCODING_EVALUATION_EXPIRED", "GEOCODING_EVALUATION_EXHAUSTED", "GEOCODING_INVALID_CURSOR", "GEOCODING_CURSOR_EXPIRED", "GEOCODING_ABORTED", "GEOCODING_DISABLED", "GEOCODING_INVALID_REQUEST", "GEOCODING_INVALID_SUGGESTION", "GEOCODING_PICK_LIMIT_EXCEEDED", "GEOCODING_QUOTA_EXCEEDED", "GEOCODING_REQUEST_TOO_LARGE", "GEOCODING_SUGGESTION_EXPIRED", "GEOCODING_UNAVAILABLE", "GEOCODING_UPSTREAM_INVALID", "GEOCODING_UPSTREAM_THROTTLED", "GEOCODING_UPSTREAM_TIMEOUT", "GEOCODING_UPSTREAM_UNAVAILABLE", "GEOCODING_USAGE_UNCONFIRMED"];
5
5
  type GeocodingErrorCode = (typeof GEOCODING_ERROR_CODES)[number];
6
6
  type GeocodeOptions = Readonly<{
7
7
  apiKey: string;
@@ -13,15 +13,20 @@ declare class GeocodingError extends Error {
13
13
  readonly code: GeocodingErrorCode | null;
14
14
  readonly requestId: string | null;
15
15
  readonly status: number;
16
+ readonly retryAfterSeconds: number | null;
16
17
  constructor(message: string, input: {
17
18
  code?: GeocodingErrorCode;
18
19
  requestId?: string;
19
20
  status: number;
21
+ retryAfterSeconds?: number | null;
20
22
  });
21
23
  }
22
24
  declare function geocode(request: GeocodingForwardRequest, options: GeocodeOptions): Promise<GeocodingForwardResponse>;
23
25
  declare function geocodeReverse(request: GeocodingReverseRequest, options: GeocodeOptions): Promise<GeocodingReverseResponse>;
24
26
  declare function autocomplete(request: AutocompleteRequest, options: GeocodeOptions): Promise<AutocompleteResponse>;
25
27
  declare function resolveSuggestion(request: ResolveSuggestionRequest, options: GeocodeOptions): Promise<ResolveSuggestionResponse>;
28
+ declare const resolvePlace: typeof resolveSuggestion;
29
+ declare function searchNearby(request: NearbyRequest, options: GeocodeOptions): Promise<NearbyResponse>;
30
+ declare function listCategories(options: GeocodeOptions): Promise<SearchCategoriesResponse>;
26
31
 
27
- export { GEOCODING_ERROR_CODES, type GeocodeOptions, GeocodingError, type GeocodingErrorCode, autocomplete, geocode, geocodeReverse, resolveSuggestion };
32
+ export { GEOCODING_ERROR_CODES, type GeocodeOptions, GeocodingError, type GeocodingErrorCode, autocomplete, geocode, geocodeReverse, listCategories, resolvePlace, resolveSuggestion, searchNearby };
package/dist/client.js CHANGED
@@ -4,14 +4,20 @@ import {
4
4
  autocomplete,
5
5
  geocode,
6
6
  geocodeReverse,
7
- resolveSuggestion
8
- } from "./chunk-YMLUPVQH.js";
9
- import "./chunk-EDYCZVXI.js";
7
+ listCategories,
8
+ resolvePlace,
9
+ resolveSuggestion,
10
+ searchNearby
11
+ } from "./chunk-FEWG4I4E.js";
12
+ import "./chunk-R7KE2IN7.js";
10
13
  export {
11
14
  GEOCODING_ERROR_CODES,
12
15
  GeocodingError,
13
16
  autocomplete,
14
17
  geocode,
15
18
  geocodeReverse,
16
- resolveSuggestion
19
+ listCategories,
20
+ resolvePlace,
21
+ resolveSuggestion,
22
+ searchNearby
17
23
  };
package/dist/contract.d.ts CHANGED
@@ -15,7 +15,7 @@ declare const geocodingLimits: Readonly<{
15
15
  maximumSuggestionTokenCharacters: 2048;
16
16
  }>;
17
17
  declare const geocodingPositionSchema: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
18
- declare const geocodingRetentionModes: readonly ["temporary", "persistent"];
18
+ declare const geocodingRetentionModes: readonly ["temporary"];
19
19
  declare const geocodingBoundsSchema: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
20
20
  declare const geocodingForwardRequestSchema: z.ZodObject<{
21
21
  bounds: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
@@ -24,7 +24,6 @@ declare const geocodingForwardRequestSchema: z.ZodObject<{
24
24
  proximity: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
25
25
  query: z.ZodString;
26
26
  retention: z.ZodDefault<z.ZodEnum<{
27
- persistent: "persistent";
28
27
  temporary: "temporary";
29
28
  }>>;
30
29
  }, z.core.$strict>;
@@ -52,7 +51,6 @@ declare const geocodingReverseRequestSchema: z.ZodObject<{
52
51
  limit: z.ZodDefault<z.ZodNumber>;
53
52
  position: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
54
53
  retention: z.ZodDefault<z.ZodEnum<{
55
- persistent: "persistent";
56
54
  temporary: "temporary";
57
55
  }>>;
58
56
  }, z.core.$strict>;
@@ -70,6 +68,27 @@ declare const geocodingAddressSchema: z.ZodObject<{
70
68
  region: z.ZodOptional<z.ZodString>;
71
69
  street: z.ZodOptional<z.ZodString>;
72
70
  }, z.core.$strict>;
71
+ declare const searchLiteralText: (maximum: number) => z.ZodString;
72
+ declare const searchCategoryIdSchema: z.ZodString;
73
+ declare const searchCategorySchema: z.ZodObject<{
74
+ id: z.ZodString;
75
+ name: z.ZodString;
76
+ localizedName: z.ZodOptional<z.ZodString>;
77
+ primary: z.ZodOptional<z.ZodBoolean>;
78
+ }, z.core.$strict>;
79
+ declare const searchPlaceMetadata: {
80
+ name: z.ZodOptional<z.ZodString>;
81
+ categories: z.ZodOptional<z.ZodArray<z.ZodObject<{
82
+ id: z.ZodString;
83
+ name: z.ZodString;
84
+ localizedName: z.ZodOptional<z.ZodString>;
85
+ primary: z.ZodOptional<z.ZodBoolean>;
86
+ }, z.core.$strict>>>;
87
+ businessChains: z.ZodOptional<z.ZodArray<z.ZodObject<{
88
+ id: z.ZodString;
89
+ name: z.ZodString;
90
+ }, z.core.$strict>>>;
91
+ };
73
92
  declare const geocodingResultSchema: z.ZodObject<{
74
93
  address: z.ZodObject<{
75
94
  city: z.ZodOptional<z.ZodString>;
@@ -99,6 +118,17 @@ declare const geocodingResultSchema: z.ZodObject<{
99
118
  label: z.ZodString;
100
119
  position: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
101
120
  sourceRef: z.ZodOptional<z.ZodString>;
121
+ name: z.ZodOptional<z.ZodString>;
122
+ categories: z.ZodOptional<z.ZodArray<z.ZodObject<{
123
+ id: z.ZodString;
124
+ name: z.ZodString;
125
+ localizedName: z.ZodOptional<z.ZodString>;
126
+ primary: z.ZodOptional<z.ZodBoolean>;
127
+ }, z.core.$strict>>>;
128
+ businessChains: z.ZodOptional<z.ZodArray<z.ZodObject<{
129
+ id: z.ZodString;
130
+ name: z.ZodString;
131
+ }, z.core.$strict>>>;
102
132
  }, z.core.$strict>;
103
133
  declare const geocodingSourceSchema: z.ZodObject<{
104
134
  id: z.ZodString;
@@ -143,6 +173,17 @@ declare const geocodingForwardResponseSchema: z.ZodObject<{
143
173
  label: z.ZodString;
144
174
  position: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
145
175
  sourceRef: z.ZodOptional<z.ZodString>;
176
+ name: z.ZodOptional<z.ZodString>;
177
+ categories: z.ZodOptional<z.ZodArray<z.ZodObject<{
178
+ id: z.ZodString;
179
+ name: z.ZodString;
180
+ localizedName: z.ZodOptional<z.ZodString>;
181
+ primary: z.ZodOptional<z.ZodBoolean>;
182
+ }, z.core.$strict>>>;
183
+ businessChains: z.ZodOptional<z.ZodArray<z.ZodObject<{
184
+ id: z.ZodString;
185
+ name: z.ZodString;
186
+ }, z.core.$strict>>>;
146
187
  }, z.core.$strict>>;
147
188
  schemaVersion: z.ZodLiteral<1>;
148
189
  source: z.ZodObject<{
@@ -150,7 +191,7 @@ declare const geocodingForwardResponseSchema: z.ZodObject<{
150
191
  revision: z.ZodNullable<z.ZodString>;
151
192
  }, z.core.$strict>;
152
193
  usage: z.ZodObject<{
153
- units: z.ZodLiteral<1>;
194
+ units: z.ZodLiteral<25>;
154
195
  }, z.core.$strict>;
155
196
  }, z.core.$strict>;
156
197
  declare const geocodingReverseResponseSchema: z.ZodObject<{
@@ -188,6 +229,17 @@ declare const geocodingReverseResponseSchema: z.ZodObject<{
188
229
  label: z.ZodString;
189
230
  position: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
190
231
  sourceRef: z.ZodOptional<z.ZodString>;
232
+ name: z.ZodOptional<z.ZodString>;
233
+ categories: z.ZodOptional<z.ZodArray<z.ZodObject<{
234
+ id: z.ZodString;
235
+ name: z.ZodString;
236
+ localizedName: z.ZodOptional<z.ZodString>;
237
+ primary: z.ZodOptional<z.ZodBoolean>;
238
+ }, z.core.$strict>>>;
239
+ businessChains: z.ZodOptional<z.ZodArray<z.ZodObject<{
240
+ id: z.ZodString;
241
+ name: z.ZodString;
242
+ }, z.core.$strict>>>;
191
243
  }, z.core.$strict>>;
192
244
  schemaVersion: z.ZodLiteral<1>;
193
245
  source: z.ZodObject<{
@@ -195,7 +247,7 @@ declare const geocodingReverseResponseSchema: z.ZodObject<{
195
247
  revision: z.ZodNullable<z.ZodString>;
196
248
  }, z.core.$strict>;
197
249
  usage: z.ZodObject<{
198
- units: z.ZodLiteral<1>;
250
+ units: z.ZodLiteral<25>;
199
251
  }, z.core.$strict>;
200
252
  }, z.core.$strict>;
201
253
  declare const geocodingSuggestionSchema: z.ZodObject<{
@@ -238,10 +290,12 @@ declare const autocompleteResponseSchema: z.ZodObject<{
238
290
  label: z.ZodString;
239
291
  token: z.ZodString;
240
292
  }, z.core.$strict>>;
293
+ usage: z.ZodObject<{
294
+ units: z.ZodLiteral<10>;
295
+ }, z.core.$strict>;
241
296
  }, z.core.$strict>;
242
297
  declare const resolveSuggestionRequestSchema: z.ZodObject<{
243
298
  retention: z.ZodDefault<z.ZodEnum<{
244
- persistent: "persistent";
245
299
  temporary: "temporary";
246
300
  }>>;
247
301
  token: z.ZodString;
@@ -280,6 +334,17 @@ declare const resolveSuggestionResponseSchema: z.ZodObject<{
280
334
  label: z.ZodString;
281
335
  position: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
282
336
  sourceRef: z.ZodOptional<z.ZodString>;
337
+ name: z.ZodOptional<z.ZodString>;
338
+ categories: z.ZodOptional<z.ZodArray<z.ZodObject<{
339
+ id: z.ZodString;
340
+ name: z.ZodString;
341
+ localizedName: z.ZodOptional<z.ZodString>;
342
+ primary: z.ZodOptional<z.ZodBoolean>;
343
+ }, z.core.$strict>>>;
344
+ businessChains: z.ZodOptional<z.ZodArray<z.ZodObject<{
345
+ id: z.ZodString;
346
+ name: z.ZodString;
347
+ }, z.core.$strict>>>;
283
348
  }, z.core.$strict>;
284
349
  schemaVersion: z.ZodLiteral<1>;
285
350
  source: z.ZodObject<{
@@ -287,7 +352,7 @@ declare const resolveSuggestionResponseSchema: z.ZodObject<{
287
352
  revision: z.ZodNullable<z.ZodString>;
288
353
  }, z.core.$strict>;
289
354
  usage: z.ZodObject<{
290
- units: z.ZodLiteral<1>;
355
+ units: z.ZodLiteral<25>;
291
356
  }, z.core.$strict>;
292
357
  }, z.core.$strict>;
293
358
  type GeocodingForwardRequest = z.input<typeof geocodingForwardRequestSchema>;
@@ -305,5 +370,198 @@ type AutocompleteResponse = z.infer<typeof autocompleteResponseSchema>;
305
370
  type ResolveSuggestionRequest = z.input<typeof resolveSuggestionRequestSchema>;
306
371
  type NormalizedResolveSuggestionRequest = z.output<typeof resolveSuggestionRequestSchema>;
307
372
  type ResolveSuggestionResponse = z.infer<typeof resolveSuggestionResponseSchema>;
373
+ declare const nearbyLimits: Readonly<{
374
+ defaultLimit: 20;
375
+ maximumLimit: 100;
376
+ maximumRadiusMeters: 21000000;
377
+ maximumCategoryCharacters: 100;
378
+ maximumFilterCategories: 10;
379
+ maximumCountries: 100;
380
+ maximumCursorCharacters: 8192;
381
+ maximumRequestBytes: number;
382
+ maximumResponseBytes: number;
383
+ }>;
384
+ declare const nearbyCursorSchema: z.ZodString;
385
+ declare const nearbyRequestSchema: z.ZodObject<{
386
+ position: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
387
+ radiusMeters: z.ZodOptional<z.ZodNumber>;
388
+ bounds: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
389
+ includeCategories: z.ZodOptional<z.ZodArray<z.ZodString>>;
390
+ excludeCategories: z.ZodOptional<z.ZodArray<z.ZodString>>;
391
+ countries: z.ZodOptional<z.ZodArray<z.ZodString>>;
392
+ language: z.ZodOptional<z.ZodString>;
393
+ limit: z.ZodDefault<z.ZodNumber>;
394
+ cursor: z.ZodOptional<z.ZodString>;
395
+ }, z.core.$strict>;
396
+ declare const nearbyPlaceSchema: z.ZodObject<{
397
+ bounds: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
398
+ address: z.ZodObject<{
399
+ city: z.ZodOptional<z.ZodString>;
400
+ country: z.ZodOptional<z.ZodString>;
401
+ countryCode: z.ZodOptional<z.ZodString>;
402
+ county: z.ZodOptional<z.ZodString>;
403
+ district: z.ZodOptional<z.ZodString>;
404
+ houseNumber: z.ZodOptional<z.ZodString>;
405
+ locality: z.ZodOptional<z.ZodString>;
406
+ name: z.ZodOptional<z.ZodString>;
407
+ postalCode: z.ZodOptional<z.ZodString>;
408
+ region: z.ZodOptional<z.ZodString>;
409
+ street: z.ZodOptional<z.ZodString>;
410
+ }, z.core.$strict>;
411
+ position: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
412
+ name: z.ZodOptional<z.ZodString>;
413
+ label: z.ZodString;
414
+ categories: z.ZodOptional<z.ZodArray<z.ZodObject<{
415
+ id: z.ZodString;
416
+ name: z.ZodString;
417
+ localizedName: z.ZodOptional<z.ZodString>;
418
+ primary: z.ZodOptional<z.ZodBoolean>;
419
+ }, z.core.$strict>>>;
420
+ businessChains: z.ZodOptional<z.ZodArray<z.ZodObject<{
421
+ id: z.ZodString;
422
+ name: z.ZodString;
423
+ }, z.core.$strict>>>;
424
+ kind: z.ZodLiteral<"place">;
425
+ distanceMeters: z.ZodOptional<z.ZodNumber>;
426
+ token: z.ZodOptional<z.ZodString>;
427
+ }, z.core.$strict>;
428
+ declare const nearbyResponseSchema: z.ZodObject<{
429
+ schemaVersion: z.ZodLiteral<1>;
430
+ provider: z.ZodLiteral<"aws">;
431
+ results: z.ZodArray<z.ZodObject<{
432
+ bounds: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
433
+ address: z.ZodObject<{
434
+ city: z.ZodOptional<z.ZodString>;
435
+ country: z.ZodOptional<z.ZodString>;
436
+ countryCode: z.ZodOptional<z.ZodString>;
437
+ county: z.ZodOptional<z.ZodString>;
438
+ district: z.ZodOptional<z.ZodString>;
439
+ houseNumber: z.ZodOptional<z.ZodString>;
440
+ locality: z.ZodOptional<z.ZodString>;
441
+ name: z.ZodOptional<z.ZodString>;
442
+ postalCode: z.ZodOptional<z.ZodString>;
443
+ region: z.ZodOptional<z.ZodString>;
444
+ street: z.ZodOptional<z.ZodString>;
445
+ }, z.core.$strict>;
446
+ position: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
447
+ name: z.ZodOptional<z.ZodString>;
448
+ label: z.ZodString;
449
+ categories: z.ZodOptional<z.ZodArray<z.ZodObject<{
450
+ id: z.ZodString;
451
+ name: z.ZodString;
452
+ localizedName: z.ZodOptional<z.ZodString>;
453
+ primary: z.ZodOptional<z.ZodBoolean>;
454
+ }, z.core.$strict>>>;
455
+ businessChains: z.ZodOptional<z.ZodArray<z.ZodObject<{
456
+ id: z.ZodString;
457
+ name: z.ZodString;
458
+ }, z.core.$strict>>>;
459
+ kind: z.ZodLiteral<"place">;
460
+ distanceMeters: z.ZodOptional<z.ZodNumber>;
461
+ token: z.ZodOptional<z.ZodString>;
462
+ }, z.core.$strict>>;
463
+ nextCursor: z.ZodOptional<z.ZodString>;
464
+ source: z.ZodObject<{
465
+ id: z.ZodString;
466
+ revision: z.ZodNullable<z.ZodString>;
467
+ }, z.core.$strict>;
468
+ attribution: z.ZodArray<z.ZodObject<{
469
+ text: z.ZodString;
470
+ url: z.ZodOptional<z.ZodString>;
471
+ }, z.core.$strict>>;
472
+ usage: z.ZodObject<{
473
+ units: z.ZodLiteral<25>;
474
+ }, z.core.$strict>;
475
+ }, z.core.$strict>;
476
+ declare const searchCategoriesResponseSchema: z.ZodObject<{
477
+ schemaVersion: z.ZodLiteral<1>;
478
+ provider: z.ZodLiteral<"aws">;
479
+ categories: z.ZodArray<z.ZodObject<{
480
+ id: z.ZodString;
481
+ name: z.ZodString;
482
+ localizedName: z.ZodOptional<z.ZodString>;
483
+ primary: z.ZodOptional<z.ZodBoolean>;
484
+ }, z.core.$strict>>;
485
+ source: z.ZodObject<{
486
+ id: z.ZodString;
487
+ revision: z.ZodNullable<z.ZodString>;
488
+ }, z.core.$strict>;
489
+ attribution: z.ZodArray<z.ZodObject<{
490
+ text: z.ZodString;
491
+ url: z.ZodOptional<z.ZodString>;
492
+ }, z.core.$strict>>;
493
+ usage: z.ZodObject<{
494
+ units: z.ZodLiteral<0>;
495
+ }, z.core.$strict>;
496
+ }, z.core.$strict>;
497
+ declare const resolvePlaceRequestSchema: z.ZodObject<{
498
+ retention: z.ZodDefault<z.ZodEnum<{
499
+ temporary: "temporary";
500
+ }>>;
501
+ token: z.ZodString;
502
+ }, z.core.$strict>;
503
+ declare const resolvePlaceResponseSchema: z.ZodObject<{
504
+ attribution: z.ZodArray<z.ZodObject<{
505
+ text: z.ZodString;
506
+ url: z.ZodOptional<z.ZodString>;
507
+ }, z.core.$strict>>;
508
+ result: z.ZodObject<{
509
+ address: z.ZodObject<{
510
+ city: z.ZodOptional<z.ZodString>;
511
+ country: z.ZodOptional<z.ZodString>;
512
+ countryCode: z.ZodOptional<z.ZodString>;
513
+ county: z.ZodOptional<z.ZodString>;
514
+ district: z.ZodOptional<z.ZodString>;
515
+ houseNumber: z.ZodOptional<z.ZodString>;
516
+ locality: z.ZodOptional<z.ZodString>;
517
+ name: z.ZodOptional<z.ZodString>;
518
+ postalCode: z.ZodOptional<z.ZodString>;
519
+ region: z.ZodOptional<z.ZodString>;
520
+ street: z.ZodOptional<z.ZodString>;
521
+ }, z.core.$strict>;
522
+ bounds: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
523
+ kind: z.ZodEnum<{
524
+ address: "address";
525
+ country: "country";
526
+ county: "county";
527
+ district: "district";
528
+ locality: "locality";
529
+ place: "place";
530
+ region: "region";
531
+ street: "street";
532
+ unknown: "unknown";
533
+ }>;
534
+ label: z.ZodString;
535
+ position: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
536
+ sourceRef: z.ZodOptional<z.ZodString>;
537
+ name: z.ZodOptional<z.ZodString>;
538
+ categories: z.ZodOptional<z.ZodArray<z.ZodObject<{
539
+ id: z.ZodString;
540
+ name: z.ZodString;
541
+ localizedName: z.ZodOptional<z.ZodString>;
542
+ primary: z.ZodOptional<z.ZodBoolean>;
543
+ }, z.core.$strict>>>;
544
+ businessChains: z.ZodOptional<z.ZodArray<z.ZodObject<{
545
+ id: z.ZodString;
546
+ name: z.ZodString;
547
+ }, z.core.$strict>>>;
548
+ }, z.core.$strict>;
549
+ schemaVersion: z.ZodLiteral<1>;
550
+ source: z.ZodObject<{
551
+ id: z.ZodString;
552
+ revision: z.ZodNullable<z.ZodString>;
553
+ }, z.core.$strict>;
554
+ usage: z.ZodObject<{
555
+ units: z.ZodLiteral<25>;
556
+ }, z.core.$strict>;
557
+ }, z.core.$strict>;
558
+ type NearbyRequest = z.input<typeof nearbyRequestSchema>;
559
+ type NormalizedNearbyRequest = z.output<typeof nearbyRequestSchema>;
560
+ type NearbyPlace = z.infer<typeof nearbyPlaceSchema>;
561
+ type NearbyResponse = z.infer<typeof nearbyResponseSchema>;
562
+ type SearchCategory = z.infer<typeof searchCategorySchema>;
563
+ type SearchCategoriesResponse = z.infer<typeof searchCategoriesResponseSchema>;
564
+ type ResolvePlaceRequest = ResolveSuggestionRequest;
565
+ type ResolvePlaceResponse = ResolveSuggestionResponse;
308
566
 
309
- export { type AutocompleteRequest, type AutocompleteResponse, type GeocodingForwardRequest, type GeocodingForwardResponse, type GeocodingResult, type GeocodingReverseRequest, type GeocodingReverseResponse, type GeocodingSuggestion, type NormalizedAutocompleteRequest, type NormalizedGeocodingForwardRequest, type NormalizedGeocodingReverseRequest, type NormalizedResolveSuggestionRequest, type ResolveSuggestionRequest, type ResolveSuggestionResponse, type ReverseGeocodingKind, autocompleteRequestSchema, autocompleteResponseSchema, geocodingAddressSchema, geocodingAttributionSchema, geocodingBoundsSchema, geocodingForwardRequestSchema, geocodingForwardResponseSchema, geocodingLimits, geocodingPositionSchema, geocodingResultKinds, geocodingResultSchema, geocodingRetentionModes, geocodingReverseRequestSchema, geocodingReverseResponseSchema, geocodingSourceSchema, geocodingSuggestionSchema, resolveSuggestionRequestSchema, resolveSuggestionResponseSchema, reverseGeocodingKindSchema };
567
+ export { type AutocompleteRequest, type AutocompleteResponse, type GeocodingForwardRequest, type GeocodingForwardResponse, type GeocodingResult, type GeocodingReverseRequest, type GeocodingReverseResponse, type GeocodingSuggestion, type NearbyPlace, type NearbyRequest, type NearbyResponse, type NormalizedAutocompleteRequest, type NormalizedGeocodingForwardRequest, type NormalizedGeocodingReverseRequest, type NormalizedNearbyRequest, type NormalizedResolveSuggestionRequest, type ResolvePlaceRequest, type ResolvePlaceResponse, type ResolveSuggestionRequest, type ResolveSuggestionResponse, type ReverseGeocodingKind, type SearchCategoriesResponse, type SearchCategory, autocompleteRequestSchema, autocompleteResponseSchema, geocodingAddressSchema, geocodingAttributionSchema, geocodingBoundsSchema, geocodingForwardRequestSchema, geocodingForwardResponseSchema, geocodingLimits, geocodingPositionSchema, geocodingResultKinds, geocodingResultSchema, geocodingRetentionModes, geocodingReverseRequestSchema, geocodingReverseResponseSchema, geocodingSourceSchema, geocodingSuggestionSchema, nearbyCursorSchema, nearbyLimits, nearbyPlaceSchema, nearbyRequestSchema, nearbyResponseSchema, resolvePlaceRequestSchema, resolvePlaceResponseSchema, resolveSuggestionRequestSchema, resolveSuggestionResponseSchema, reverseGeocodingKindSchema, searchCategoriesResponseSchema, searchCategoryIdSchema, searchCategorySchema, searchLiteralText, searchPlaceMetadata };
package/dist/contract.js CHANGED
@@ -15,10 +15,22 @@ import {
15
15
  geocodingReverseResponseSchema,
16
16
  geocodingSourceSchema,
17
17
  geocodingSuggestionSchema,
18
+ nearbyCursorSchema,
19
+ nearbyLimits,
20
+ nearbyPlaceSchema,
21
+ nearbyRequestSchema,
22
+ nearbyResponseSchema,
23
+ resolvePlaceRequestSchema,
24
+ resolvePlaceResponseSchema,
18
25
  resolveSuggestionRequestSchema,
19
26
  resolveSuggestionResponseSchema,
20
- reverseGeocodingKindSchema
21
- } from "./chunk-EDYCZVXI.js";
27
+ reverseGeocodingKindSchema,
28
+ searchCategoriesResponseSchema,
29
+ searchCategoryIdSchema,
30
+ searchCategorySchema,
31
+ searchLiteralText,
32
+ searchPlaceMetadata
33
+ } from "./chunk-R7KE2IN7.js";
22
34
  export {
23
35
  autocompleteRequestSchema,
24
36
  autocompleteResponseSchema,
@@ -36,7 +48,19 @@ export {
36
48
  geocodingReverseResponseSchema,
37
49
  geocodingSourceSchema,
38
50
  geocodingSuggestionSchema,
51
+ nearbyCursorSchema,
52
+ nearbyLimits,
53
+ nearbyPlaceSchema,
54
+ nearbyRequestSchema,
55
+ nearbyResponseSchema,
56
+ resolvePlaceRequestSchema,
57
+ resolvePlaceResponseSchema,
39
58
  resolveSuggestionRequestSchema,
40
59
  resolveSuggestionResponseSchema,
41
- reverseGeocodingKindSchema
60
+ reverseGeocodingKindSchema,
61
+ searchCategoriesResponseSchema,
62
+ searchCategoryIdSchema,
63
+ searchCategorySchema,
64
+ searchLiteralText,
65
+ searchPlaceMetadata
42
66
  };
package/dist/index.d.ts CHANGED
@@ -1,3 +1,3 @@
1
- export { GEOCODING_ERROR_CODES, GeocodeOptions, GeocodingError, GeocodingErrorCode, autocomplete, geocode, geocodeReverse, resolveSuggestion } from './client.js';
2
- export { AutocompleteRequest, AutocompleteResponse, GeocodingForwardRequest, GeocodingForwardResponse, GeocodingResult, GeocodingReverseRequest, GeocodingReverseResponse, GeocodingSuggestion, NormalizedAutocompleteRequest, NormalizedGeocodingForwardRequest, NormalizedGeocodingReverseRequest, NormalizedResolveSuggestionRequest, ResolveSuggestionRequest, ResolveSuggestionResponse, ReverseGeocodingKind, autocompleteRequestSchema, autocompleteResponseSchema, geocodingAddressSchema, geocodingAttributionSchema, geocodingBoundsSchema, geocodingForwardRequestSchema, geocodingForwardResponseSchema, geocodingLimits, geocodingPositionSchema, geocodingResultKinds, geocodingResultSchema, geocodingRetentionModes, geocodingReverseRequestSchema, geocodingReverseResponseSchema, geocodingSourceSchema, geocodingSuggestionSchema, resolveSuggestionRequestSchema, resolveSuggestionResponseSchema, reverseGeocodingKindSchema } from './contract.js';
1
+ export { GEOCODING_ERROR_CODES, GeocodeOptions, GeocodingError, GeocodingErrorCode, autocomplete, geocode, geocodeReverse, listCategories, resolvePlace, resolveSuggestion, searchNearby } from './client.js';
2
+ export { AutocompleteRequest, AutocompleteResponse, GeocodingForwardRequest, GeocodingForwardResponse, GeocodingResult, GeocodingReverseRequest, GeocodingReverseResponse, GeocodingSuggestion, NearbyPlace, NearbyRequest, NearbyResponse, NormalizedAutocompleteRequest, NormalizedGeocodingForwardRequest, NormalizedGeocodingReverseRequest, NormalizedNearbyRequest, NormalizedResolveSuggestionRequest, ResolvePlaceRequest, ResolvePlaceResponse, ResolveSuggestionRequest, ResolveSuggestionResponse, ReverseGeocodingKind, SearchCategoriesResponse, SearchCategory, autocompleteRequestSchema, autocompleteResponseSchema, geocodingAddressSchema, geocodingAttributionSchema, geocodingBoundsSchema, geocodingForwardRequestSchema, geocodingForwardResponseSchema, geocodingLimits, geocodingPositionSchema, geocodingResultKinds, geocodingResultSchema, geocodingRetentionModes, geocodingReverseRequestSchema, geocodingReverseResponseSchema, geocodingSourceSchema, geocodingSuggestionSchema, nearbyCursorSchema, nearbyLimits, nearbyPlaceSchema, nearbyRequestSchema, nearbyResponseSchema, resolvePlaceRequestSchema, resolvePlaceResponseSchema, resolveSuggestionRequestSchema, resolveSuggestionResponseSchema, reverseGeocodingKindSchema, searchCategoriesResponseSchema, searchCategoryIdSchema, searchCategorySchema, searchLiteralText, searchPlaceMetadata } from './contract.js';
3
3
  import 'zod';
package/dist/index.js CHANGED
@@ -4,8 +4,11 @@ import {
4
4
  autocomplete,
5
5
  geocode,
6
6
  geocodeReverse,
7
- resolveSuggestion
8
- } from "./chunk-YMLUPVQH.js";
7
+ listCategories,
8
+ resolvePlace,
9
+ resolveSuggestion,
10
+ searchNearby
11
+ } from "./chunk-FEWG4I4E.js";
9
12
  import {
10
13
  autocompleteRequestSchema,
11
14
  autocompleteResponseSchema,
@@ -23,10 +26,22 @@ import {
23
26
  geocodingReverseResponseSchema,
24
27
  geocodingSourceSchema,
25
28
  geocodingSuggestionSchema,
29
+ nearbyCursorSchema,
30
+ nearbyLimits,
31
+ nearbyPlaceSchema,
32
+ nearbyRequestSchema,
33
+ nearbyResponseSchema,
34
+ resolvePlaceRequestSchema,
35
+ resolvePlaceResponseSchema,
26
36
  resolveSuggestionRequestSchema,
27
37
  resolveSuggestionResponseSchema,
28
- reverseGeocodingKindSchema
29
- } from "./chunk-EDYCZVXI.js";
38
+ reverseGeocodingKindSchema,
39
+ searchCategoriesResponseSchema,
40
+ searchCategoryIdSchema,
41
+ searchCategorySchema,
42
+ searchLiteralText,
43
+ searchPlaceMetadata
44
+ } from "./chunk-R7KE2IN7.js";
30
45
  export {
31
46
  GEOCODING_ERROR_CODES,
32
47
  GeocodingError,
@@ -49,8 +64,23 @@ export {
49
64
  geocodingReverseResponseSchema,
50
65
  geocodingSourceSchema,
51
66
  geocodingSuggestionSchema,
67
+ listCategories,
68
+ nearbyCursorSchema,
69
+ nearbyLimits,
70
+ nearbyPlaceSchema,
71
+ nearbyRequestSchema,
72
+ nearbyResponseSchema,
73
+ resolvePlace,
74
+ resolvePlaceRequestSchema,
75
+ resolvePlaceResponseSchema,
52
76
  resolveSuggestion,
53
77
  resolveSuggestionRequestSchema,
54
78
  resolveSuggestionResponseSchema,
55
- reverseGeocodingKindSchema
79
+ reverseGeocodingKindSchema,
80
+ searchCategoriesResponseSchema,
81
+ searchCategoryIdSchema,
82
+ searchCategorySchema,
83
+ searchLiteralText,
84
+ searchNearby,
85
+ searchPlaceMetadata
56
86
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tileflow/search",
3
- "version": "0.1.0-alpha.1",
3
+ "version": "0.1.0-alpha.3",
4
4
  "license": "Apache-2.0",
5
5
  "description": "Headless geocoding and location selection client and wire contracts for Tileflow.",
6
6
  "type": "module",