@tileflow/search 0.1.0-alpha.2 → 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 +141 -93
  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,8 +1,7 @@
1
1
  # @tileflow/search
2
2
 
3
- Forward and reverse geocoding, location suggestions, and selected-suggestion resolution. This is a
4
- headless client: it provides no search box, map control, address validation, category discovery, or
5
- batch interface.
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.
6
5
 
7
6
  > Related packages and guides: [documentation index](https://raw.githubusercontent.com/tileflow/tileflow-sdk/main/llms.txt).
8
7
 
@@ -12,134 +11,183 @@ batch interface.
12
11
  npm install @tileflow/search@alpha
13
12
  ```
14
13
 
15
- Use a runtime with `fetch`, such as Node.js 22 or newer. Live requests need an enabled Tileflow
16
- Geocoding service and a Team key or signed Team capability with `geocoding:read`. Installing the
17
- package does not enable that service. Keep privileged credentials on your server; a browser UI
18
- should call your own authorized endpoint.
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.
19
17
 
20
- ## Find a place
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
21
 
22
- Run this in a trusted server process with `TILEFLOW_API_KEY` set securely:
22
+ ## Find nearby places
23
23
 
24
- <!-- docs:check -->
25
-
26
- ```ts
27
- import {GeocodingError, geocode} from '@tileflow/search';
28
-
29
- const apiKey = process.env.TILEFLOW_API_KEY;
30
- if (!apiKey) throw new Error('Set TILEFLOW_API_KEY on the server.');
31
-
32
- try {
33
- const response = await geocode(
34
- {query: 'Praça do Comércio, Lisboa', language: 'en', retention: 'temporary'},
35
- {apiKey, signal: AbortSignal.timeout(5000)},
36
- );
37
- console.log(response.results);
38
- console.log(response.source, response.attribution);
39
- } catch (error) {
40
- if (!(error instanceof GeocodingError)) throw error;
41
- console.error(error.code, error.status, error.requestId);
42
- }
43
- ```
44
-
45
- A successful response may have no results. Present all returned attribution entries alongside
46
- results, preserving any supplied URLs. A source revision of `null` means no reliable revision is
47
- available, not that provenance can be invented or omitted.
48
-
49
- ## Reverse-geocode a position
50
-
51
- Positions use WGS84 `[longitude, latitude]`, not `[latitude, longitude]`:
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:
52
26
 
53
27
  <!-- docs:check -->
54
28
 
55
29
  ```ts
56
- import {geocodeReverse} from '@tileflow/search';
30
+ import {listCategories, searchNearby} from '@tileflow/search';
57
31
 
58
32
  const apiKey = process.env.TILEFLOW_API_KEY;
59
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.');
60
38
 
61
- const response = await geocodeReverse(
39
+ const page = await searchNearby(
62
40
  {
63
41
  position: [-9.1393, 38.7223],
64
- kinds: ['address', 'place'],
42
+ radiusMeters: 1000,
43
+ includeCategories: [category.id],
44
+ countries: ['PT'],
65
45
  language: 'en',
66
- retention: 'temporary',
46
+ limit: 20,
67
47
  },
68
- {apiKey},
48
+ options,
69
49
  );
70
50
 
71
- console.log(response.results, response.attribution);
51
+ console.log(page.results, page.attribution, page.usage.units);
72
52
  ```
73
53
 
74
- Results are nearby candidates in provider order. They do not establish containment, administrative
75
- membership, parcel or entrance precision, routability, deliverability, or address validity.
76
- `kinds` is an OR filter with 1–4 values from `address`, `street`, `locality`, and `place`; ordering
77
- adds no priority. Reverse `limit` defaults to 1 and accepts 1–10.
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.
78
61
 
79
- ## Resolve a user-selected suggestion
62
+ ## Request another page or resolve a selection
80
63
 
81
- The server-side example returns suggestions first and exposes a separate selection handler:
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.
82
67
 
83
68
  <!-- docs:check -->
84
69
 
85
70
  ```ts
86
- import {autocomplete, resolveSuggestion} from '@tileflow/search';
71
+ import {type NearbyRequest, resolvePlace, searchNearby} from '@tileflow/search';
87
72
 
88
73
  const apiKey = process.env.TILEFLOW_API_KEY;
89
74
  if (!apiKey) throw new Error('Set TILEFLOW_API_KEY on the server.');
90
75
  const options = {apiKey};
76
+ const original: NearbyRequest = {position: [-9.1393, 38.7223], radiusMeters: 1000};
91
77
 
92
- const response = await autocomplete({query: 'Hospital La Paz', language: 'en'}, options);
93
- console.log(response.suggestions, response.attribution);
78
+ export function requestPage(cursor?: string) {
79
+ return searchNearby({...original, ...(cursor ? {cursor} : {})}, options);
80
+ }
94
81
 
95
- export async function resolveUserSelection(token: string) {
96
- const resolved = await resolveSuggestion({token, retention: 'temporary'}, options);
97
- return {result: resolved.result, source: resolved.source, attribution: resolved.attribution};
82
+ export function resolveSelectedPlace(token: string) {
83
+ return resolvePlace({token}, options);
98
84
  }
99
85
  ```
100
86
 
101
- Call `resolveUserSelection` only after explicit selection. Do not automatically resolve every
102
- suggestion. Tokens are opaque and ephemeral; an expired token needs fresh suggestions. Suggestions
103
- do not guarantee a match for every place and are not category or discovery queries.
104
-
105
- Debounce input and cancel superseded requests, or ignore stale results. The client owns no shared
106
- interaction state. Autocomplete rejects `retention`, returns no usage record, and consumes zero
107
- units. Each completed resolution reports one unit; replaying it is another operation, not a retry
108
- of an idempotent request.
109
-
110
- ## Request limits and retention
111
-
112
- Forward queries contain at most 200 characters. Forward and autocomplete `limit` default to 5 and
113
- accept 1–10. `bounds` and `proximity` are mutually exclusive. Bounds use
114
- `[west, south, east, north]` with west less than east and south less than north; do not pass a wrapped
115
- antimeridian box. Provider selection and raw provider options are not public controls.
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.
116
91
 
117
- `retention` accepts `temporary` (default) or `persistent` for forward, reverse, and resolution.
118
- Temporary results are for immediate use, without a right granted by Tileflow to retain them
119
- permanently. Persistent mode requests compatible storage rights; it does not request or promise
120
- Tileflow storage. Only retain a resolved candidate with its source and attribution, not suggestion
121
- tokens or labels.
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.
122
94
 
123
- Persistent retention is unavailable in some territories. `GEOCODING_TERRITORY_UNSUPPORTED` (422)
124
- means the requested mode is unsupported, including AWS HERE-backed geocoding in Japan. It applies
125
- to forward, reverse, and resolution, not autocomplete. Follow the returned source terms rather
126
- than treating an SDK option as a blanket storage license.
95
+ ## Geocode text, reverse a position, or offer suggestions
127
96
 
128
- ## Handle failures and usage
97
+ <!-- docs:check -->
129
98
 
130
- Requests and normalized responses are strictly bounded. The client never retries automatically.
131
- Use `signal` to cancel work and `fetch` or `apiUrl` for tests. API URLs require HTTPS except for an
132
- explicit loopback HTTP origin during development.
99
+ ```ts
100
+ import {autocomplete, geocode, geocodeReverse, resolveSuggestion} from '@tileflow/search';
133
101
 
134
- Hosted errors throw `GeocodingError` with `status`, nullable `code`, and nullable `requestId`.
135
- Invalid local inputs and malformed remote documents can throw ordinary errors. A disabled service
136
- reports `GEOCODING_DISABLED`. Suggestion failures include `GEOCODING_INVALID_SUGGESTION` (400),
137
- `GEOCODING_SUGGESTION_EXPIRED` (410), `GEOCODING_UPSTREAM_THROTTLED` (429), and
138
- `GEOCODING_PICK_LIMIT_EXCEEDED` (429). Refresh an expired suggestion rather than replaying its token.
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};
139
105
 
140
- `GEOCODING_USAGE_UNCONFIRMED` means completion may already have been charged; do not automatically
141
- repeat the request. Each completed forward or reverse request reports one unit, including an empty
142
- result; completed resolution also reports one. These are usage units, not monetary prices.
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
+ ```
143
112
 
144
- Use `@tileflow/search/contract` for schemas and `@tileflow/search/client` for transport. For a
145
- published release, its installed README and declarations take precedence over newer source on `main`.
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.2",
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",