@tileflow/search 0.1.0-alpha.2 → 0.1.0-alpha.4

package/README.md

@@ -1,8 +1,7 @@
 # @tileflow/search
 
-Forward and reverse geocoding, location suggestions, and selected-suggestion resolution. This is a
-headless client: it provides no search box, map control, address validation, category discovery, or
-batch interface.
+Headless forward/reverse geocoding, autocomplete, category discovery, Nearby POIs and explicit
+selected-place resolution. It uses `fetch` and has no renderer or global interaction state.
 
 > Related packages and guides: [documentation index](https://raw.githubusercontent.com/tileflow/tileflow-sdk/main/llms.txt).
 
@@ -12,134 +11,251 @@ batch interface.
 npm install @tileflow/search@alpha
 ```
 
-Use a runtime with `fetch`, such as Node.js 22 or newer. Live requests need an enabled Tileflow
-Geocoding service and a Team key or signed Team capability with `geocoding:read`. Installing the
-package does not enable that service. Keep privileged credentials on your server; a browser UI
-should call your own authorized endpoint.
+Use Node.js 22 or another runtime with `fetch`. Live requests require enabled Tileflow Search and a
+Team credential with `geocoding:read`. Keep privileged credentials on your application server.
+Browser and mobile interfaces call their own authorized server endpoint.
 
-## Find a place
+Managed operations require paid Starter or a separate, finite Search evaluation grant. A Starter
+trial or complimentary assignment alone does not authorize Search. Free Teams can read categories.
+Installing this package does not enable the service or grant access.
 
-Run this in a trusted server process with `TILEFLOW_API_KEY` set securely:
+## Find nearby places
+
+Run this example on your server with `TILEFLOW_API_KEY` set securely. It lists the current categories,
+then makes one explicit Nearby request using a discovered ID:
 
 <!-- docs:check -->
 
 ```ts
-import {GeocodingError, geocode} from '@tileflow/search';
+import {listCategories, searchNearby} from '@tileflow/search';
 
 const apiKey = process.env.TILEFLOW_API_KEY;
 if (!apiKey) throw new Error('Set TILEFLOW_API_KEY on the server.');
+const options = {apiKey};
+const catalog = await listCategories(options);
+const category = catalog.categories.find(({name}) => name.toLowerCase().includes('coffee'));
+if (!category) throw new Error('Choose a category from the current catalog.');
 
-try {
-  const response = await geocode(
-    {query: 'Praça do Comércio, Lisboa', language: 'en', retention: 'temporary'},
-    {apiKey, signal: AbortSignal.timeout(5000)},
-  );
-  console.log(response.results);
-  console.log(response.source, response.attribution);
-} catch (error) {
-  if (!(error instanceof GeocodingError)) throw error;
-  console.error(error.code, error.status, error.requestId);
-}
+const page = await searchNearby(
+  {
+    position: [-9.1393, 38.7223],
+    radiusMeters: 1000,
+    includeCategories: [category.id],
+    countries: ['PT'],
+    language: 'en',
+    limit: 20,
+  },
+  options,
+);
+
+console.log(page.results, page.attribution, page.usage.units);
 ```
 
-A successful response may have no results. Present all returned attribution entries alongside
-results, preserving any supplied URLs. A source revision of `null` means no reliable revision is
-available, not that provenance can be invented or omitted.
+Coordinates are WGS84 `[longitude, latitude]`. Results preserve native AWS proximity ordering.
+A POI's optional `name` is its establishment title; `label` and `address` describe its location.
+Categories and business-chain labels appear only when supplied. Missing metadata does not establish
+opening status, freshness or completeness. Co-located businesses are not merged.
+
+Display every attribution entry with results, preserving supplied URLs. Results and opaque references
+are temporary. Do not build a permanent place catalog, cache results, or persist provider references.
 
-## Reverse-geocode a position
+## Request another page or resolve a selection
 
-Positions use WGS84 `[longitude, latitude]`, not `[latitude, longitude]`:
+Save the original request in the current interaction. Another page repeats that request with the
+returned `nextCursor`; no page is fetched automatically. A successful empty page can have a cursor.
+Each explicit page costs 25 API units. There is no total-count or snapshot-consistency promise.
 
 <!-- docs:check -->
 
 ```ts
-import {geocodeReverse} from '@tileflow/search';
+import {type NearbyRequest, resolvePlace, searchNearby} from '@tileflow/search';
 
 const apiKey = process.env.TILEFLOW_API_KEY;
 if (!apiKey) throw new Error('Set TILEFLOW_API_KEY on the server.');
+const options = {apiKey};
+const original: NearbyRequest = {position: [-9.1393, 38.7223], radiusMeters: 1000};
 
-const response = await geocodeReverse(
-  {
-    position: [-9.1393, 38.7223],
-    kinds: ['address', 'place'],
-    language: 'en',
-    retention: 'temporary',
-  },
-  {apiKey},
-);
+export function requestPage(cursor?: string) {
+  return searchNearby({...original, ...(cursor ? {cursor} : {})}, options);
+}
 
-console.log(response.results, response.attribution);
+export function resolveSelectedPlace(token: string) {
+  return resolvePlace({token}, options);
+}
 ```
 
-Results are nearby candidates in provider order. They do not establish containment, administrative
-membership, parcel or entrance precision, routability, deliverability, or address validity.
-`kinds` is an OR filter with 1–4 values from `address`, `street`, `locality`, and `place`; ordering
-adds no priority. Reverse `limit` defaults to 1 and accepts 1–10.
+Invoke these handlers only after explicit user actions. Use a returned POI token for resolution;
+map feature IDs, click coordinates and raw AWS Place IDs are not selection tokens. A result without
+a token can be displayed but cannot be resolved. Selection and pagination references cannot be
+interchanged or moved between Teams. Changed query, language, filters or limit invalidates a cursor.
 
-## Resolve a user-selected suggestion
+`resolvePlace` and `resolveSuggestion` perform the same single resolution operation. Neither fetches
+other results or retries automatically. An expired reference requires an explicit fresh search.
 
-The server-side example returns suggestions first and exposes a separate selection handler:
+## Geocode text, reverse a position, or offer suggestions
 
 <!-- docs:check -->
 
 ```ts
-import {autocomplete, resolveSuggestion} from '@tileflow/search';
+import {autocomplete, geocode, geocodeReverse, resolveSuggestion} from '@tileflow/search';
 
 const apiKey = process.env.TILEFLOW_API_KEY;
 if (!apiKey) throw new Error('Set TILEFLOW_API_KEY on the server.');
 const options = {apiKey};
 
-const response = await autocomplete({query: 'Hospital La Paz', language: 'en'}, options);
-console.log(response.suggestions, response.attribution);
-
-export async function resolveUserSelection(token: string) {
-  const resolved = await resolveSuggestion({token, retention: 'temporary'}, options);
-  return {result: resolved.result, source: resolved.source, attribution: resolved.attribution};
-}
+export const findAddress = (query: string) => geocode({query, language: 'en'}, options);
+export const reversePosition = (position: [number, number]) =>
+  geocodeReverse({position, kinds: ['address', 'place']}, options);
+export const suggestPlaces = (query: string) => autocomplete({query, language: 'en'}, options);
+export const resolveSelection = (token: string) => resolveSuggestion({token}, options);
 ```
 
-Call `resolveUserSelection` only after explicit selection. Do not automatically resolve every
-suggestion. Tokens are opaque and ephemeral; an expired token needs fresh suggestions. Suggestions
-do not guarantee a match for every place and are not category or discovery queries.
+Text search and Nearby are distinct operations. A suggestion has a title, an optional one-line
+`addressLabel` that tells same-named places apart, and no position. Resolve only the selected
+suggestion. Reverse results are candidates in provider order, without containment, entrance
+precision, routability, deliverability or address-validation guarantees.
 
-Debounce input and cancel superseded requests, or ignore stale results. The client owns no shared
-interaction state. Autocomplete rejects `retention`, returns no usage record, and consumes zero
-units. Each completed resolution reports one unit; replaying it is another operation, not a retry
-of an idempotent request.
+To show positions, distances and categories while someone types, ask for each suggestion's place.
+A completed request then uses 25 units instead of 10, and choosing a suggestion needs no further
+resolution:
 
-## Request limits and retention
+<!-- docs:check -->
 
-Forward queries contain at most 200 characters. Forward and autocomplete `limit` default to 5 and
-accept 1–10. `bounds` and `proximity` are mutually exclusive. Bounds use
-`[west, south, east, north]` with west less than east and south less than north; do not pass a wrapped
-antimeridian box. Provider selection and raw provider options are not public controls.
+```ts
+import {autocomplete} from '@tileflow/search';
+
+const apiKey = process.env.TILEFLOW_API_KEY;
+if (!apiKey) throw new Error('Set TILEFLOW_API_KEY on the server.');
+const options = {apiKey};
 
-`retention` accepts `temporary` (default) or `persistent` for forward, reverse, and resolution.
-Temporary results are for immediate use, without a right granted by Tileflow to retain them
-permanently. Persistent mode requests compatible storage rights; it does not request or promise
-Tileflow storage. Only retain a resolved candidate with its source and attribution, not suggestion
-tokens or labels.
+export async function suggestNearbyPlaces(query: string, proximity: [number, number]) {
+  const {suggestions} = await autocomplete({query, proximity, include: ['place']}, options);
+  return suggestions.map(({label, addressLabel, place}) => ({
+    label,
+    addressLabel,
+    position: place?.position,
+    distanceMeters: place?.distanceMeters,
+  }));
+}
+```
 
-Persistent retention is unavailable in some territories. `GEOCODING_TERRITORY_UNSUPPORTED` (422)
-means the requested mode is unsupported, including AWS HERE-backed geocoding in Japan. It applies
-to forward, reverse, and resolution, not autocomplete. Follow the returned source terms rather
-than treating an SDK option as a blanket storage license.
+## Place details
 
-## Handle failures and usage
+Results carry an optional `distanceMeters` when the provider reports one: from `proximity`, from
+the centre of `bounds`, or from the reverse or Nearby position. Places can also carry `foodTypes`.
+Other details are requested with `include` and make the operation an extended one:
 
-Requests and normalized responses are strictly bounded. The client never retries automatically.
-Use `signal` to cancel work and `fetch` or `apiUrl` for tests. API URLs require HTTPS except for an
-explicit loopback HTTP origin during development.
+| Detail         | Returns                                                     | Available from                                           |
+| -------------- | ----------------------------------------------------------- | -------------------------------------------------------- |
+| `contacts`     | `phones`, `websites` and `emails`, each a `value` and label | Text search inside `bounds`, Nearby, explicit resolution |
+| `openingHours` | Display lines per schedule and `openNow` at request time    | Text search inside `bounds`, Nearby, explicit resolution |
+| `timeZone`     | IANA `name` and `utcOffsetSeconds`                          | Every place operation                                    |
+| `accessPoints` | Entrance or access positions, separate from `position`      | Every place operation                                    |
 
-Hosted errors throw `GeocodingError` with `status`, nullable `code`, and nullable `requestId`.
-Invalid local inputs and malformed remote documents can throw ordinary errors. A disabled service
-reports `GEOCODING_DISABLED`. Suggestion failures include `GEOCODING_INVALID_SUGGESTION` (400),
-`GEOCODING_SUGGESTION_EXPIRED` (410), `GEOCODING_UPSTREAM_THROTTLED` (429), and
-`GEOCODING_PICK_LIMIT_EXCEEDED` (429). Refresh an expired suggestion rather than replaying its token.
+Asking geocoding without `bounds`, or reverse geocoding, for contacts or opening hours fails with
+`GEOCODING_FILTER_UNSUPPORTED` before any request is sent. Each detail is optional in a response:
+a place whose hours the provider does not supply has no `openingHours`.
 
-`GEOCODING_USAGE_UNCONFIRMED` means completion may already have been charged; do not automatically
-repeat the request. Each completed forward or reverse request reports one unit, including an empty
-result; completed resolution also reports one. These are usage units, not monetary prices.
+<!-- docs:check -->
+
+```ts
+import {resolvePlace} from '@tileflow/search';
+
+const apiKey = process.env.TILEFLOW_API_KEY;
+if (!apiKey) throw new Error('Set TILEFLOW_API_KEY on the server.');
+const options = {apiKey};
+
+export async function placeCard(token: string) {
+  const {result} = await resolvePlace({token, include: ['contacts', 'openingHours']}, options);
+  const website = result.contacts?.websites?.find(({value}) => /^https?:\/\//iu.test(value));
+  return {
+    name: result.name ?? result.label,
+    openNow: result.openingHours?.some(({openNow}) => openNow) ?? false,
+    hours: result.openingHours?.flatMap(({display}) => display ?? []) ?? [],
+    phone: result.contacts?.phones?.[0]?.value,
+    website: website?.value,
+  };
+}
+```
 
-Use `@tileflow/search/contract` for schemas and `@tileflow/search/client` for transport. For a
-published release, its installed README and declarations take precedence over newer source on `main`.
+Contact values are provider text, not validated links: check the scheme before rendering one as
+a link, and expect several phones or websites for a place, not all equally relevant. `openNow`
+describes the moment of the request. Like every result, details are for temporary display.
+
+## Limits and temporary use
+
+Forward/autocomplete text accepts 1–200 characters. Their limit defaults to 5 and accepts 1–10;
+reverse defaults to 1 and accepts 1–10. Reverse kinds are an OR of `address`, `street`, `locality`
+and `place`. Forward/autocomplete `bounds` and `proximity` are mutually exclusive.
+
+Nearby requires `position`, defaults to 20 results and accepts 1–100. Optional `radiusMeters` accepts
+1–21,000,000. A bbox is `[west, south, east, north]`, with west < east and south < north; wrapping
+antimeridian boxes are unsupported. Position alone uses native provider scope and makes no hard
+extent promise. Combined radius+bbox is currently rejected with `GEOCODING_FILTER_UNSUPPORTED`.
+
+Use literal current category IDs, including spaces and punctuation. Include/exclude lists accept up
+to ten IDs each. Inclusion is OR; exclusion vetoes matches. No parent-category expansion is implied.
+Country filters accept up to 100 ISO alpha-2/alpha-3 codes and intersect spatial/category constraints.
+Unknown IDs or countries are rejected. Language requests use provider fallback, without a translation
+or localization completeness guarantee. Nearby does not accept text queries or an ordering selector.
+
+Nearby requests are bounded to 32 KiB and responses to 512 KiB. Cursors accept at most 8192 characters;
+selection tokens at most 2048. Oversized/invalid pages fail as a whole. The SDK parses strict schemas
+and never drops malformed results to manufacture a valid success.
+
+Forward, reverse and resolution accept only `retention: 'temporary'`, also the default. Persistent
+retention, Advanced features and caller-selected provider options are rejected before provider work.
+
+## Usage and errors
+
+| Completed operation                   | Shared API units | With `include` |
+| ------------------------------------- | ---------------: | -------------: |
+| Category discovery                    |                0 |              — |
+| Autocomplete                          |               10 |             25 |
+| Forward, reverse, explicit resolution |               25 |             75 |
+| Each Nearby page                      |               25 |             75 |
+
+`searchOperationUnits(operation, include)` returns the same weights. Valid empty responses consume
+the same units. Three autocomplete calls and one resolution consume 55 units. These are part of Starter's shared API allowance, with no separate Search credits or
+commercial search session. Hovering, displaying results and moving a map do not call Search.
+
+`GeocodingError` exposes `status`, nullable `code`, nullable `requestId` and nullable bounded
+`retryAfterSeconds`. The client never retries, including after throttling. Use `signal` for
+cancellation. Network failures can leave server completion uncertain.
+
+| Code                                                             | Action                                                              |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------- |
+| `GEOCODING_PLAN_UNAVAILABLE`                                     | Use paid Starter or request an eligible evaluation.                 |
+| `GEOCODING_EVALUATION_REQUIRED` / `GEOCODING_EVALUATION_EXPIRED` | Ask the Team's operator to review evaluation access.                |
+| `GEOCODING_EVALUATION_EXHAUSTED`                                 | Stop requests; review evaluation limits.                            |
+| `GEOCODING_PICK_LIMIT_EXCEEDED` / `GEOCODING_UPSTREAM_THROTTLED` | Respect `retryAfterSeconds`; retry only deliberately.               |
+| `GEOCODING_INVALID_CURSOR` / `GEOCODING_INVALID_SUGGESTION`      | Check the Team and original query; start a fresh search explicitly. |
+| `GEOCODING_CURSOR_EXPIRED` / `GEOCODING_SUGGESTION_EXPIRED`      | Request fresh results explicitly.                                   |
+| `GEOCODING_USAGE_UNCONFIRMED`                                    | Completion may already be charged. Inspect usage before repeating.  |
+| `GEOCODING_DISABLED`                                             | Search is disabled; installation does not activate it.              |
+
+Rejected or failed operations do not return a completed usage record. Never translate an unconfirmed
+completion into zero units. Confirmed server completion is not undone by a later disconnection.
+API URLs require HTTPS, except explicit loopback HTTP during development. `fetch` can be injected
+for local tests. Request and response schemas are exported from `@tileflow/search/contract`;
+transport is available from `@tileflow/search/client`.
+
+## Integrate an independent search interaction
+
+Each widget owns its timer, abort controller, request generation and selection state. Debounce input;
+suppress requests while IME composition is active; launch the final input on `compositionend`.
+Increment the generation and abort previous work on input, selection, dismissal or a view change.
+Apply a response only if its generation still matches, even if abort did not stop the transport.
+
+Use an accessible combobox/listbox for suggestions: arrow keys change the active option, Enter or a
+touch/click explicitly selects it, and Escape dismisses it. Give the input a label, maintain focus
+and active-option semantics, and announce loading, empty results and errors through a polite status
+region. Preserve attribution beside displayed results. Do not resolve on hover or focus changes.
+
+An explicit category action can call Nearby. Moving a map offers a “Search this area” button; only
+pressing it submits the new bounds. A late reply must not move the camera after a newer selection or
+view change. Keep independent generations for independent widgets. The SDK's tests demonstrate
+cancellation and stale-suggestion handling; it does not supply a UI component or client credentials.
+
+For a published package, its installed README and declarations describe that release; a link to
+GitHub `main` can describe newer source.

package/dist/{chunk-YMLUPVQH.js → chunk-QDEMNVJD.js}

@@ -5,13 +5,26 @@ import {
   geocodingForwardResponseSchema,
   geocodingLimits,
   geocodingReverseRequestSchema,
+  nearbyLimits,
+  nearbyRequestSchema,
+  nearbyResponseSchema,
   resolveSuggestionRequestSchema,
-  resolveSuggestionResponseSchema
-} from "./chunk-EDYCZVXI.js";
+  resolveSuggestionResponseSchema,
+  searchCategoriesResponseSchema,
+  searchContactDetails,
+  searchOperationUnits
+} from "./chunk-W66J2DAS.js";
 
 // src/client.ts
 import { z } from "zod";
 var GEOCODING_ERROR_CODES = [
+  "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",
@@ -20,7 +33,6 @@ var GEOCODING_ERROR_CODES = [
   "GEOCODING_QUOTA_EXCEEDED",
   "GEOCODING_REQUEST_TOO_LARGE",
   "GEOCODING_SUGGESTION_EXPIRED",
-  "GEOCODING_TERRITORY_UNSUPPORTED",
   "GEOCODING_UNAVAILABLE",
   "GEOCODING_UPSTREAM_INVALID",
   "GEOCODING_UPSTREAM_THROTTLED",
@@ -29,6 +41,13 @@ var GEOCODING_ERROR_CODES = [
   "GEOCODING_USAGE_UNCONFIRMED"
 ];
 var geocodingErrorStatuses = {
+  GEOCODING_FILTER_UNSUPPORTED: 422,
+  GEOCODING_PLAN_UNAVAILABLE: 403,
+  GEOCODING_EVALUATION_REQUIRED: 403,
+  GEOCODING_EVALUATION_EXPIRED: 403,
+  GEOCODING_EVALUATION_EXHAUSTED: 429,
+  GEOCODING_INVALID_CURSOR: 400,
+  GEOCODING_CURSOR_EXPIRED: 410,
   GEOCODING_ABORTED: 499,
   GEOCODING_DISABLED: 503,
   GEOCODING_INVALID_REQUEST: 400,
@@ -37,7 +56,6 @@ var geocodingErrorStatuses = {
   GEOCODING_QUOTA_EXCEEDED: 429,
   GEOCODING_REQUEST_TOO_LARGE: 413,
   GEOCODING_SUGGESTION_EXPIRED: 410,
-  GEOCODING_TERRITORY_UNSUPPORTED: 422,
   GEOCODING_UNAVAILABLE: 503,
   GEOCODING_UPSTREAM_INVALID: 502,
   GEOCODING_UPSTREAM_THROTTLED: 429,
@@ -60,12 +78,14 @@ var GeocodingError = class extends Error {
   code;
   requestId;
   status;
+  retryAfterSeconds;
   constructor(message, input) {
     super(message);
     this.name = "GeocodingError";
     this.code = input.code ?? null;
     this.requestId = input.requestId ?? null;
     this.status = input.status;
+    this.retryAfterSeconds = input.retryAfterSeconds ?? null;
   }
 };
 async function geocode(request, options) {
@@ -73,12 +93,14 @@ async function geocode(request, options) {
   if (!parsedRequest.success) {
     throw new Error("Invalid Tileflow geocoding request");
   }
+  if (!parsedRequest.data.bounds) rejectContactDetails(parsedRequest.data.include);
+  const units = searchOperationUnits("forward", parsedRequest.data.include);
   return requestGeocoding(
     "/v1/geocoding/forward",
     parsedRequest.data,
     options,
     geocodingForwardResponseSchema,
-    (response) => response.results.length <= (parsedRequest.data.limit ?? geocodingLimits.defaultLimit)
+    (response) => response.usage.units === units && response.results.length <= (parsedRequest.data.limit ?? geocodingLimits.defaultLimit)
   );
 }
 async function geocodeReverse(request, options) {
@@ -86,12 +108,14 @@ async function geocodeReverse(request, options) {
   if (!parsedRequest.success) {
     throw new Error("Invalid Tileflow geocoding request");
   }
+  rejectContactDetails(parsedRequest.data.include);
+  const units = searchOperationUnits("reverse", parsedRequest.data.include);
   return requestGeocoding(
     "/v1/geocoding/reverse",
     parsedRequest.data,
     options,
     geocodingForwardResponseSchema,
-    (response) => response.results.length <= parsedRequest.data.limit && containsOnlyKinds(response, parsedRequest.data.kinds)
+    (response) => response.usage.units === units && response.results.length <= parsedRequest.data.limit && containsOnlyKinds(response, parsedRequest.data.kinds)
   );
 }
 async function autocomplete(request, options) {
@@ -99,12 +123,13 @@ async function autocomplete(request, options) {
   if (!parsedRequest.success) {
     throw new Error("Invalid Tileflow geocoding request");
   }
+  const withPlaces = parsedRequest.data.include !== void 0;
   return requestGeocoding(
     "/v1/geocoding/autocomplete",
     parsedRequest.data,
     options,
     autocompleteResponseSchema,
-    (response) => response.suggestions.length <= parsedRequest.data.limit
+    (response) => response.usage.units === searchOperationUnits("autocomplete", parsedRequest.data.include) && response.suggestions.length <= parsedRequest.data.limit && response.suggestions.every((suggestion) => suggestion.place !== void 0 === withPlaces)
   );
 }
 async function resolveSuggestion(request, options) {
@@ -112,27 +137,64 @@ async function resolveSuggestion(request, options) {
   if (!parsedRequest.success) {
     throw new Error("Invalid Tileflow geocoding request");
   }
+  const units = searchOperationUnits("resolve", parsedRequest.data.include);
   return requestGeocoding(
-    "/v1/geocoding/resolve-suggestion",
+    "/v1/geocoding/resolve",
     parsedRequest.data,
     options,
-    resolveSuggestionResponseSchema
+    resolveSuggestionResponseSchema,
+    (response) => response.usage.units === units
   );
 }
-async function requestGeocoding(path, request, options, responseSchema, isExpectedResponse = () => true) {
+var resolvePlace = resolveSuggestion;
+async function searchNearby(request, options) {
+  const parsed = nearbyRequestSchema.safeParse(request);
+  if (!parsed.success) throw new Error("Invalid Tileflow Nearby request");
+  const query = parsed.data;
+  if (query.radiusMeters !== void 0 && query.bounds !== void 0 || query.includeCategories?.some((id) => query.excludeCategories?.includes(id))) {
+    throw new GeocodingError("Unsupported geocoding filters", {
+      code: "GEOCODING_FILTER_UNSUPPORTED",
+      status: 422
+    });
+  }
+  const units = searchOperationUnits("nearby", query.include);
+  return requestGeocoding(
+    "/v1/geocoding/nearby",
+    query,
+    options,
+    nearbyResponseSchema,
+    (response) => response.usage.units === units && response.results.length <= query.limit,
+    nearbyLimits.maximumResponseBytes
+  );
+}
+function listCategories(options) {
+  return requestGeocoding(
+    "/v1/geocoding/categories",
+    void 0,
+    options,
+    searchCategoriesResponseSchema,
+    () => true,
+    nearbyLimits.maximumResponseBytes
+  );
+}
+async function requestGeocoding(path, request, options, responseSchema, isExpectedResponse = () => true, maximumResponseBytes = geocodingLimits.maximumResponseBytes) {
+  const bodyText = request === void 0 ? void 0 : JSON.stringify(request);
+  const maximumRequestBytes = path === "/v1/geocoding/nearby" ? nearbyLimits.maximumRequestBytes : 8 * 1024;
+  if (bodyText && new TextEncoder().encode(bodyText).byteLength > maximumRequestBytes)
+    throw new Error("Tileflow Search request is too large");
   const apiKey = normalizeApiKey(options.apiKey);
   const apiUrl = normalizeApiUrl(options.apiUrl ?? "https://api.tileflow.dev");
   const fetcher = options.fetch ?? fetch;
   let response;
   try {
     response = await fetcher(`${apiUrl}${path}`, {
-      body: JSON.stringify(request),
+      ...bodyText === void 0 ? {} : { body: bodyText },
       headers: {
         Accept: "application/json",
         Authorization: `Bearer ${apiKey}`,
         "Content-Type": "application/json"
       },
-      method: "POST",
+      method: request === void 0 ? "GET" : "POST",
       redirect: "error",
       signal: options.signal
     });
@@ -149,7 +211,7 @@ async function requestGeocoding(path, request, options, responseSchema, isExpect
   }
   let body;
   try {
-    body = await readBoundedJson(response, geocodingLimits.maximumResponseBytes, options.signal);
+    body = await readBoundedJson(response, maximumResponseBytes, options.signal);
   } catch (error) {
     if (options.signal?.aborted) throw options.signal.reason ?? error;
     throw new GeocodingError("Tileflow geocoding returned an invalid response", {
@@ -164,6 +226,14 @@ async function requestGeocoding(path, request, options, responseSchema, isExpect
   }
   return parsedResponse.data;
 }
+function rejectContactDetails(include) {
+  if (include?.some((detail) => searchContactDetails.includes(detail))) {
+    throw new GeocodingError("Unsupported geocoding filters", {
+      code: "GEOCODING_FILTER_UNSUPPORTED",
+      status: 422
+    });
+  }
+}
 function containsOnlyKinds(response, allowedKinds) {
   if (!allowedKinds) return true;
   const kindFilter = new Set(allowedKinds);
@@ -189,18 +259,25 @@ function normalizeApiUrl(value) {
   return url.href.replace(/\/$/u, "");
 }
 async function readGeocodingError(response, signal) {
+  const value = response.headers.get("Retry-After");
+  const delay = value && /^\d{1,8}$/u.test(value) ? Number(value) : null;
+  const retryAfterSeconds = delay !== null && delay <= 31536e3 ? delay : null;
   let body;
   try {
     body = await readBoundedJson(response, geocodingLimits.maximumSafeErrorBytes, signal);
   } catch (error) {
     if (signal?.aborted) throw signal.reason ?? error;
-    return new GeocodingError("Tileflow geocoding request failed", { status: response.status });
+    return new GeocodingError("Tileflow geocoding request failed", {
+      retryAfterSeconds,
+      status: response.status
+    });
   }
   const geocoding = geocodingErrorResponseSchema.safeParse(body);
   if (geocoding.success && geocodingErrorStatuses[geocoding.data.code] === response.status) {
     return new GeocodingError(geocoding.data.error, {
       code: geocoding.data.code,
       requestId: geocoding.data.requestId,
+      retryAfterSeconds,
       status: response.status
     });
   }
@@ -208,10 +285,14 @@ async function readGeocodingError(response, signal) {
   if (credential.success && [401, 403, 429].includes(response.status)) {
     return new GeocodingError(credential.data.error, {
       requestId: credential.data.requestId,
+      retryAfterSeconds,
       status: response.status
     });
   }
-  return new GeocodingError("Tileflow geocoding request failed", { status: response.status });
+  return new GeocodingError("Tileflow geocoding request failed", {
+    retryAfterSeconds,
+    status: response.status
+  });
 }
 async function readBoundedJson(response, maximumBytes, signal) {
   const declaredLength = response.headers.get("Content-Length");
@@ -282,5 +363,8 @@ export {
   geocode,
   geocodeReverse,
   autocomplete,
-  resolveSuggestion
+  resolveSuggestion,
+  resolvePlace,
+  searchNearby,
+  listCategories
 };