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

package/README.md

@@ -11,14 +11,43 @@ selected-place resolution. It uses `fetch` and has no renderer or global interac
 npm install @tileflow/search@alpha
 ```
 
-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.
+Use Node.js 22, a browser or another runtime with `fetch`. Live requests require enabled Tileflow
+Search and a Team credential with `geocoding:read`: a publishable credential in websites and apps,
+or a server credential on your server.
 
-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.
+Free Teams, Starter trials and complimentary access run Search within their period's API units, up
+to 100,000 Search units, while Search without payment is open; a finite evaluation grant can extend
+them. Paid Starter runs Search within its shared API allowance and excess.
 Installing this package does not enable the service or grant access.
 
+## Call Search from a browser or app
+
+A publishable credential (`tf_public_…`) is meant to be visible in client code. It grants Search
+only, works only from the websites and native apps listed for it, and always carries per-minute and
+per-day quotas. A Team Admin creates one under **Credentials** in the Tileflow dashboard.
+
+```ts
+import {autocomplete} from '@tileflow/search';
+
+const options = {apiKey: 'tf_public_…'};
+const page = await autocomplete({query: 'Hospital La Paz', proximity: [-3.7, 40.42]}, options);
+```
+
+Browsers send the page's origin, which must match one of the credential's websites exactly: scheme,
+host and port. Native apps send no origin, so name the app instead. The SDK then sends its bundle ID
+or package name and, on Android, the SHA-256 fingerprint of its signing certificate:
+
+```ts
+const options = {
+  apiKey: 'tf_public_…',
+  app: {id: 'com.example.store', certificateSha256: '14:6D:E9:…'},
+};
+```
+
+Anyone can read a publishable credential and imitate an origin or app outside a browser, so these
+restrictions limit casual reuse rather than prove identity. Its quotas and the Team's spending limit
+bound what a copied credential can consume. Keep server credentials (`tf_live_…`) on your server.
+
 ## Find nearby places
 
 Run this example on your server with `TILEFLOW_API_KEY` set securely. It lists the current categories,
@@ -63,7 +92,7 @@ are temporary. Do not build a permanent place catalog, cache results, or persist
 
 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.
+Each explicit page costs 10 API units. There is no total-count or snapshot-consistency promise.
 
 <!-- docs:check -->
 
@@ -110,15 +139,84 @@ export const suggestPlaces = (query: string) => autocomplete({query, language: '
 export const resolveSelection = (token: string) => resolveSuggestion({token}, options);
 ```
 
-Text search and Nearby are distinct operations. Suggestions have no position. Resolve only the
-selected suggestion. Reverse results are candidates in provider order, without containment,
-entrance precision, routability, deliverability or address-validation guarantees.
+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.
+
+To show positions, distances and categories while someone types, ask for each suggestion's place.
+A completed request then uses 10 units instead of 4, and choosing a suggestion needs no further
+resolution:
+
+<!-- docs:check -->
+
+```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};
+
+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,
+  }));
+}
+```
+
+## Place details
+
+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:
+
+| 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                                    |
+
+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`.
+
+<!-- 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,
+  };
+}
+```
+
+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.
+and `place`. Forward/autocomplete `proximity` biases ranking and `bounds` restricts results; they
+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
@@ -140,31 +238,37 @@ retention, Advanced features and caller-selected provider options are rejected b
 
 ## Usage and errors
 
-| Completed operation                   | Shared API units |
-| ------------------------------------- | ---------------: |
-| Category discovery                    |                0 |
-| Autocomplete                          |               10 |
-| Forward, reverse, explicit resolution |               25 |
-| Each Nearby page                      |               25 |
+| Completed operation                   | Shared API units | With `include` |
+| ------------------------------------- | ---------------: | -------------: |
+| Category discovery                    |                0 |              — |
+| Autocomplete                          |                4 |             10 |
+| Forward, reverse, explicit resolution |               10 |             30 |
+| Each Nearby page                      |               10 |             30 |
 
-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
+`searchOperationUnits(operation, include)` returns the same weights. Valid empty responses consume
+the same units. Three autocomplete calls and one resolution consume 22 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.              |
+| 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_UNPAID_LIMIT_REACHED`                                 | Search without payment reached its period limit; upgrade to Starter.  |
+| `GEOCODING_UNPAID_BUDGET_EXHAUSTED`                              | Search without payment is paused; retry after `retryAfterSeconds`.    |
+| `GEOCODING_SUSPENDED`                                            | Search is suspended for the Team; contact support.                    |
+| `GEOCODING_SPENDING_LIMIT_REACHED`                               | The Team reached its spending limit; raise it or wait for the period. |
+| `GEOCODING_CREDENTIAL_QUOTA_EXCEEDED`                            | The credential reached its quota; respect `retryAfterSeconds`.        |
+| `GEOCODING_ORIGIN_NOT_ALLOWED`                                   | Add this website or app to the publishable credential.                |
+| `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.
@@ -184,10 +288,16 @@ touch/click explicitly selects it, and Escape dismisses it. Give the input a lab
 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.
 
+Text search over a map should favor the view without being confined to it. Send the map's centre as
+`proximity` while it shows a city or closer, and omit it at country or world scale; nearer matches
+then rank first, and a better match elsewhere, such as the city of Madrid typed over Lisbon, still
+appears. `bounds` excludes everything outside the box, so do not derive it from the view for typed
+search.
+
 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.
+cancellation and stale-suggestion handling; it does not supply a UI component.
 
 For a published package, its installed README and declarations describe that release; a link to
 GitHub `main` can describe newer source.

package/dist/{chunk-FEWG4I4E.js → chunk-7PHOZFMS.js}

@@ -10,8 +10,10 @@ import {
   nearbyResponseSchema,
   resolveSuggestionRequestSchema,
   resolveSuggestionResponseSchema,
-  searchCategoriesResponseSchema
-} from "./chunk-R7KE2IN7.js";
+  searchCategoriesResponseSchema,
+  searchContactDetails,
+  searchOperationUnits
+} from "./chunk-W7IIJLOI.js";
 
 // src/client.ts
 import { z } from "zod";
@@ -27,11 +29,17 @@ var GEOCODING_ERROR_CODES = [
   "GEOCODING_DISABLED",
   "GEOCODING_INVALID_REQUEST",
   "GEOCODING_INVALID_SUGGESTION",
+  "GEOCODING_ORIGIN_NOT_ALLOWED",
   "GEOCODING_PICK_LIMIT_EXCEEDED",
   "GEOCODING_QUOTA_EXCEEDED",
   "GEOCODING_REQUEST_TOO_LARGE",
+  "GEOCODING_SPENDING_LIMIT_REACHED",
+  "GEOCODING_CREDENTIAL_QUOTA_EXCEEDED",
   "GEOCODING_SUGGESTION_EXPIRED",
+  "GEOCODING_SUSPENDED",
   "GEOCODING_UNAVAILABLE",
+  "GEOCODING_UNPAID_BUDGET_EXHAUSTED",
+  "GEOCODING_UNPAID_LIMIT_REACHED",
   "GEOCODING_UPSTREAM_INVALID",
   "GEOCODING_UPSTREAM_THROTTLED",
   "GEOCODING_UPSTREAM_TIMEOUT",
@@ -50,11 +58,17 @@ var geocodingErrorStatuses = {
   GEOCODING_DISABLED: 503,
   GEOCODING_INVALID_REQUEST: 400,
   GEOCODING_INVALID_SUGGESTION: 400,
+  GEOCODING_ORIGIN_NOT_ALLOWED: 403,
   GEOCODING_PICK_LIMIT_EXCEEDED: 429,
   GEOCODING_QUOTA_EXCEEDED: 429,
   GEOCODING_REQUEST_TOO_LARGE: 413,
+  GEOCODING_SPENDING_LIMIT_REACHED: 429,
+  GEOCODING_CREDENTIAL_QUOTA_EXCEEDED: 429,
   GEOCODING_SUGGESTION_EXPIRED: 410,
+  GEOCODING_SUSPENDED: 403,
   GEOCODING_UNAVAILABLE: 503,
+  GEOCODING_UNPAID_BUDGET_EXHAUSTED: 429,
+  GEOCODING_UNPAID_LIMIT_REACHED: 429,
   GEOCODING_UPSTREAM_INVALID: 502,
   GEOCODING_UPSTREAM_THROTTLED: 429,
   GEOCODING_UPSTREAM_TIMEOUT: 504,
@@ -91,12 +105,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) {
@@ -104,12 +120,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) {
@@ -117,12 +135,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) {
@@ -130,11 +149,13 @@ 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",
     parsedRequest.data,
     options,
-    resolveSuggestionResponseSchema
+    resolveSuggestionResponseSchema,
+    (response) => response.usage.units === units
   );
 }
 var resolvePlace = resolveSuggestion;
@@ -148,12 +169,13 @@ async function searchNearby(request, options) {
       status: 422
     });
   }
+  const units = searchOperationUnits("nearby", query.include);
   return requestGeocoding(
     "/v1/geocoding/nearby",
     query,
     options,
     nearbyResponseSchema,
-    (response) => response.results.length <= query.limit,
+    (response) => response.usage.units === units && response.results.length <= query.limit,
     nearbyLimits.maximumResponseBytes
   );
 }
@@ -173,6 +195,7 @@ async function requestGeocoding(path, request, options, responseSchema, isExpect
   if (bodyText && new TextEncoder().encode(bodyText).byteLength > maximumRequestBytes)
     throw new Error("Tileflow Search request is too large");
   const apiKey = normalizeApiKey(options.apiKey);
+  const app = normalizeApp(options.app);
   const apiUrl = normalizeApiUrl(options.apiUrl ?? "https://api.tileflow.dev");
   const fetcher = options.fetch ?? fetch;
   let response;
@@ -182,7 +205,9 @@ async function requestGeocoding(path, request, options, responseSchema, isExpect
       headers: {
         Accept: "application/json",
         Authorization: `Bearer ${apiKey}`,
-        "Content-Type": "application/json"
+        "Content-Type": "application/json",
+        ...app ? { "X-Tileflow-App": app.id } : {},
+        ...app?.certificateSha256 ? { "X-Tileflow-App-Certificate": app.certificateSha256 } : {}
       },
       method: request === void 0 ? "GET" : "POST",
       redirect: "error",
@@ -216,11 +241,27 @@ 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);
   return response.results.every(({ kind }) => kindFilter.has(kind));
 }
+function normalizeApp(value) {
+  if (value === void 0) return null;
+  const certificate = value?.certificateSha256?.replaceAll(":", "").toLowerCase();
+  if (typeof value?.id !== "string" || value.id.length > 255 || !/^[A-Za-z][A-Za-z0-9_-]*(\.[A-Za-z0-9_-]+)+$/u.test(value.id) || certificate !== void 0 && !/^[0-9a-f]{64}$/u.test(certificate)) {
+    throw new Error("Invalid Tileflow app identity");
+  }
+  return { id: value.id, certificateSha256: certificate };
+}
 function normalizeApiKey(value) {
   if (typeof value !== "string" || value.length < 1 || value.length > 4096 || value !== value.trim() || /\p{Cc}/u.test(value)) {
     throw new Error("Invalid Tileflow API key");

package/dist/{chunk-R7KE2IN7.js → chunk-W7IIJLOI.js}

@@ -16,7 +16,10 @@ var geocodingLimits = Object.freeze({
   maximumResponseBytes: 64 * 1024,
   maximumSafeErrorBytes: 8 * 1024,
   maximumSourceCharacters: 128,
-  maximumSuggestionTokenCharacters: 2048
+  maximumSuggestionTokenCharacters: 2048,
+  maximumDetailEntries: 100,
+  maximumOpeningHoursEntries: 20,
+  maximumOpeningHoursLines: 50
 });
 var boundedText = (maximum) => z.string().trim().min(1).max(maximum).refine((value) => !controlCharacterPattern.test(value), {
   message: "Control characters are not allowed"
@@ -28,8 +31,14 @@ var geocodingRetentionModes = ["temporary"];
 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, {
   message: "South must be less than north"
 });
+var searchPlaceDetails = ["contacts", "openingHours", "timeZone", "accessPoints"];
+var searchPlaceDetailSchema = z.enum(searchPlaceDetails);
+var searchPlaceDetailsSchema = z.array(searchPlaceDetailSchema).min(1).max(searchPlaceDetails.length).refine((values) => new Set(values).size === values.length, {
+  message: "Place details must be unique"
+});
 var geocodingForwardRequestSchema = z.object({
   bounds: geocodingBoundsSchema.optional(),
+  include: searchPlaceDetailsSchema.optional(),
   language: z.string().max(geocodingLimits.maximumLanguageCharacters).regex(languagePattern).optional(),
   limit: z.number().int().min(1).max(geocodingLimits.maximumLimit).optional(),
   proximity: geocodingPositionSchema.optional(),
@@ -39,8 +48,10 @@ var geocodingForwardRequestSchema = z.object({
   message: "Bounds and proximity are mutually exclusive",
   path: ["proximity"]
 });
+var autocompleteIncludeSchema = z.tuple([z.literal("place")]);
 var autocompleteRequestSchema = z.object({
   bounds: geocodingBoundsSchema.optional(),
+  include: autocompleteIncludeSchema.optional(),
   language: z.string().max(geocodingLimits.maximumLanguageCharacters).regex(languagePattern).optional(),
   limit: z.number().int().min(1).max(geocodingLimits.maximumLimit).default(geocodingLimits.defaultLimit),
   proximity: geocodingPositionSchema.optional(),
@@ -51,6 +62,7 @@ var autocompleteRequestSchema = z.object({
 });
 var reverseGeocodingKindSchema = z.enum(["address", "street", "locality", "place"]);
 var geocodingReverseRequestSchema = z.object({
+  include: searchPlaceDetailsSchema.optional(),
   kinds: z.array(reverseGeocodingKindSchema).min(1).max(4).optional(),
   language: z.string().max(geocodingLimits.maximumLanguageCharacters).regex(languagePattern).optional(),
   limit: z.number().int().min(1).max(geocodingLimits.maximumLimit).default(geocodingLimits.defaultReverseLimit),
@@ -93,10 +105,40 @@ var searchCategorySchema = z.object({
 var searchPlaceMetadata = {
   name: searchLiteralText(200).optional(),
   categories: z.array(searchCategorySchema).min(1).max(100).optional(),
+  foodTypes: z.array(searchCategorySchema).min(1).max(100).optional(),
   businessChains: z.array(z.object({ id: searchLiteralText(100), name: searchLiteralText(100) }).strict()).min(1).max(100).optional()
 };
+var contactListSchema = z.array(
+  z.object({
+    value: searchLiteralText(2048),
+    label: searchLiteralText(256).optional()
+  }).strict()
+).min(1).max(geocodingLimits.maximumDetailEntries);
+var searchContactsSchema = z.object({
+  phones: contactListSchema.optional(),
+  websites: contactListSchema.optional(),
+  emails: contactListSchema.optional()
+}).strict();
+var searchOpeningHoursSchema = z.array(
+  z.object({
+    display: z.array(searchLiteralText(256)).min(1).max(geocodingLimits.maximumOpeningHoursLines).optional(),
+    openNow: z.boolean().optional()
+  }).strict()
+).min(1).max(geocodingLimits.maximumOpeningHoursEntries);
+var searchTimeZoneSchema = z.object({
+  name: searchLiteralText(64),
+  utcOffsetSeconds: z.number().int().min(-86400).max(86400).optional()
+}).strict();
+var searchPlaceDetailFields = {
+  distanceMeters: z.number().finite().nonnegative().optional(),
+  contacts: searchContactsSchema.optional(),
+  openingHours: searchOpeningHoursSchema.optional(),
+  timeZone: searchTimeZoneSchema.optional(),
+  accessPoints: z.array(z.object({ position: geocodingPositionSchema }).strict()).min(1).max(geocodingLimits.maximumDetailEntries).optional()
+};
 var geocodingResultSchema = z.object({
   ...searchPlaceMetadata,
+  ...searchPlaceDetailFields,
   address: geocodingAddressSchema,
   bounds: geocodingBoundsSchema.optional(),
   kind: z.enum(geocodingResultKinds),
@@ -116,18 +158,21 @@ var geocodingAttributionSchema = z.object({
     message: "Expected an HTTPS URL without credentials"
   }).optional()
 }).strict();
+var placeOperationUnitsSchema = z.union([z.literal(10), z.literal(30)]);
 var geocodingForwardResponseSchema = z.object({
   attribution: z.array(geocodingAttributionSchema).min(1).max(geocodingLimits.maximumAttributionEntries),
   queryId: z.string().regex(queryIdPattern),
   results: z.array(geocodingResultSchema).max(geocodingLimits.maximumLimit),
   schemaVersion: z.literal(1),
   source: geocodingSourceSchema,
-  usage: z.object({ units: z.literal(25) }).strict()
+  usage: z.object({ units: placeOperationUnitsSchema }).strict()
 }).strict();
 var geocodingReverseResponseSchema = geocodingForwardResponseSchema;
 var geocodingSuggestionSchema = z.object({
   kind: z.enum(geocodingResultKinds),
   label: boundedText(512),
+  addressLabel: boundedText(512).optional(),
+  place: geocodingResultSchema.optional(),
   token: z.string().min(1).max(geocodingLimits.maximumSuggestionTokenCharacters).regex(/^[\x21-\x7e]+$/u)
 }).strict();
 var autocompleteResponseSchema = z.object({
@@ -135,9 +180,10 @@ var autocompleteResponseSchema = z.object({
   schemaVersion: z.literal(1),
   source: geocodingSourceSchema,
   suggestions: z.array(geocodingSuggestionSchema).max(geocodingLimits.maximumLimit),
-  usage: z.object({ units: z.literal(10) }).strict()
+  usage: z.object({ units: z.union([z.literal(4), z.literal(10)]) }).strict()
 }).strict();
 var resolveSuggestionRequestSchema = z.object({
+  include: searchPlaceDetailsSchema.optional(),
   retention: z.enum(geocodingRetentionModes).default("temporary"),
   token: z.string().min(1).max(geocodingLimits.maximumSuggestionTokenCharacters).regex(/^[\x21-\x7e]+$/u)
 }).strict();
@@ -146,7 +192,7 @@ var resolveSuggestionResponseSchema = z.object({
   result: geocodingResultSchema,
   schemaVersion: z.literal(1),
   source: geocodingSourceSchema,
-  usage: z.object({ units: z.literal(25) }).strict()
+  usage: z.object({ units: placeOperationUnitsSchema }).strict()
 }).strict();
 function isCredentialFreeHttpsUrl(value) {
   try {
@@ -177,12 +223,12 @@ var nearbyRequestSchema = z.object({
   excludeCategories: categoryFilter.optional(),
   countries: z.array(z.string().regex(/^(?:[A-Z]{2}|[A-Z]{3})$/u)).min(1).max(nearbyLimits.maximumCountries).optional(),
   language: geocodingForwardRequestSchema.shape.language,
+  include: searchPlaceDetailsSchema.optional(),
   limit: z.number().int().min(1).max(nearbyLimits.maximumLimit).default(nearbyLimits.defaultLimit),
   cursor: nearbyCursorSchema.optional()
 }).strict();
 var nearbyPlaceSchema = geocodingResultSchema.omit({ sourceRef: true }).extend({
   kind: z.literal("place"),
-  distanceMeters: z.number().finite().nonnegative().optional(),
   token: geocodingSuggestionSchema.shape.token.optional()
 }).strict();
 var nearbyResponseSchema = z.object({
@@ -192,7 +238,7 @@ var nearbyResponseSchema = z.object({
   nextCursor: nearbyCursorSchema.optional(),
   source: geocodingSourceSchema,
   attribution: geocodingForwardResponseSchema.shape.attribution,
-  usage: z.object({ units: z.literal(25) }).strict()
+  usage: z.object({ units: placeOperationUnitsSchema }).strict()
 }).strict().refine(
   (value) => new TextEncoder().encode(JSON.stringify(value)).byteLength <= nearbyLimits.maximumResponseBytes,
   { message: "Nearby response exceeds the encoded byte limit" }
@@ -207,13 +253,23 @@ var searchCategoriesResponseSchema = z.object({
 }).strict();
 var resolvePlaceRequestSchema = resolveSuggestionRequestSchema;
 var resolvePlaceResponseSchema = resolveSuggestionResponseSchema;
+var searchContactDetails = ["contacts", "openingHours"];
+function searchOperationUnits(operation, include) {
+  if (operation === "categories") return 0;
+  if (operation === "autocomplete") return include?.length ? 10 : 4;
+  return include?.length ? 30 : 10;
+}
 
 export {
   geocodingLimits,
   geocodingPositionSchema,
   geocodingRetentionModes,
   geocodingBoundsSchema,
+  searchPlaceDetails,
+  searchPlaceDetailSchema,
+  searchPlaceDetailsSchema,
   geocodingForwardRequestSchema,
+  autocompleteIncludeSchema,
   autocompleteRequestSchema,
   reverseGeocodingKindSchema,
   geocodingReverseRequestSchema,
@@ -223,6 +279,10 @@ export {
   searchCategoryIdSchema,
   searchCategorySchema,
   searchPlaceMetadata,
+  searchContactsSchema,
+  searchOpeningHoursSchema,
+  searchTimeZoneSchema,
+  searchPlaceDetailFields,
   geocodingResultSchema,
   geocodingSourceSchema,
   geocodingAttributionSchema,
@@ -239,5 +299,7 @@ export {
   nearbyResponseSchema,
   searchCategoriesResponseSchema,
   resolvePlaceRequestSchema,
-  resolvePlaceResponseSchema
+  resolvePlaceResponseSchema,
+  searchContactDetails,
+  searchOperationUnits
 };

package/dist/client.d.ts

@@ -1,11 +1,19 @@
 import { AutocompleteRequest, AutocompleteResponse, GeocodingForwardRequest, GeocodingForwardResponse, GeocodingReverseRequest, GeocodingReverseResponse, SearchCategoriesResponse, ResolveSuggestionRequest, ResolveSuggestionResponse, NearbyRequest, NearbyResponse } from './contract.js';
 import 'zod';
 
-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"];
+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_ORIGIN_NOT_ALLOWED", "GEOCODING_PICK_LIMIT_EXCEEDED", "GEOCODING_QUOTA_EXCEEDED", "GEOCODING_REQUEST_TOO_LARGE", "GEOCODING_SPENDING_LIMIT_REACHED", "GEOCODING_CREDENTIAL_QUOTA_EXCEEDED", "GEOCODING_SUGGESTION_EXPIRED", "GEOCODING_SUSPENDED", "GEOCODING_UNAVAILABLE", "GEOCODING_UNPAID_BUDGET_EXHAUSTED", "GEOCODING_UNPAID_LIMIT_REACHED", "GEOCODING_UPSTREAM_INVALID", "GEOCODING_UPSTREAM_THROTTLED", "GEOCODING_UPSTREAM_TIMEOUT", "GEOCODING_UPSTREAM_UNAVAILABLE", "GEOCODING_USAGE_UNCONFIRMED"];
 type GeocodingErrorCode = (typeof GEOCODING_ERROR_CODES)[number];
 type GeocodeOptions = Readonly<{
     apiKey: string;
     apiUrl?: string;
+    /**
+     * The native app a publishable credential admits: its iOS bundle ID, or its Android package name
+     * with the SHA-256 fingerprint of its signing certificate. Browsers send their origin instead.
+     */
+    app?: Readonly<{
+        id: string;
+        certificateSha256?: string;
+    }>;
     fetch?: typeof fetch;
     signal?: AbortSignal;
 }>;

package/dist/client.js

@@ -8,8 +8,8 @@ import {
   resolvePlace,
   resolveSuggestion,
   searchNearby
-} from "./chunk-FEWG4I4E.js";
-import "./chunk-R7KE2IN7.js";
+} from "./chunk-7PHOZFMS.js";
+import "./chunk-W7IIJLOI.js";
 export {
   GEOCODING_ERROR_CODES,
   GeocodingError,