@caronashow/api 0.12.0 → 0.14.0

package/README.md

@@ -49,6 +49,7 @@ The package includes the following type definitions:
 - `ParticipationMode` - User's role in the system (offer, search, explore)
 - `DriverOfferSetup` - Driver's vehicle and route preferences
 - `PassengerSearchSetup` - Passenger's pickup and schedule preferences
+- `ShiftSelection` - One named organization shift or a custom arrival/departure schedule
 
 #### Services
 

package/dist/gen/caronashow/service/v1/home_pb.d.ts

@@ -1,5 +1,5 @@
 import type { GenEnum, GenFile, GenMessage, GenService } from "@bufbuild/protobuf/codegenv2";
-import type { FullAddress } from "../../types/v1/address_pb";
+import type { TimeWindow } from "./organization_pb";
 import type { TimeOfDay } from "../../types/v1/common_pb";
 import type { UserRank } from "../../types/v1/user_pb";
 import type { Timestamp } from "@bufbuild/protobuf/wkt";
@@ -16,13 +16,13 @@ export declare const file_caronashow_service_v1_home: GenFile;
  */
 export type ListRideSuggestionsRequest = Message<"caronashow.service.v1.ListRideSuggestionsRequest"> & {
     /**
-     * Visible map area used to select route geometries and ride offers.
+     * Visible map area used to select safe route geometries and ride offers.
      *
      * @generated from field: caronashow.service.v1.MapViewport viewport = 1;
      */
     viewport?: MapViewport | undefined;
     /**
-     * Commute leg for which routes, seat inventory, and estimates are requested.
+     * Commute leg for which route, seat, and schedule data is requested.
      *
      * @generated from field: caronashow.service.v1.CommuteDirection direction = 2;
      */
@@ -34,15 +34,21 @@ export type ListRideSuggestionsRequest = Message<"caronashow.service.v1.ListRide
  */
 export declare const ListRideSuggestionsRequestSchema: GenMessage<ListRideSuggestionsRequest>;
 /**
- * Contains complete synchronized map and drawer projections of one matching
- * result set. The service returns an error rather than either partial projection.
+ * Contains complete synchronized map and drawer projections of one published
+ * recommendation result set. The service returns an error rather than either
+ * partial projection. The Backend must validate the complete response key and
+ * retain any safe geometry needed for this response independently of Pooler's
+ * mutable operation rows.
  *
  * @generated from message caronashow.service.v1.ListRideSuggestionsResponse
  */
 export type ListRideSuggestionsResponse = Message<"caronashow.service.v1.ListRideSuggestionsResponse"> & {
     /**
-     * Opaque identifier for this immutable matching snapshot. It identifies the
-     * result but does not provide chronological ordering between responses.
+     * Non-enumerable opaque identifier for this immutable matching snapshot. It
+     * is scoped to the authenticated passenger and must not be a decimal database
+     * ID or a capability usable by another passenger. It does not provide
+     * chronological ordering between responses. Empty while availability is
+     * COMPUTING.
      *
      * @generated from field: string result_set_id = 1;
      */
@@ -62,11 +68,42 @@ export type ListRideSuggestionsResponse = Message<"caronashow.service.v1.ListRid
      */
     rankedSuggestions: RankedRideSuggestion[];
     /**
-     * Server time at which this matching snapshot was produced.
+     * Server time at which the published matching snapshot was produced. Empty
+     * while availability is COMPUTING.
      *
      * @generated from field: google.protobuf.Timestamp generated_at = 4;
      */
     generatedAt?: Timestamp | undefined;
+    /**
+     * Whether a published result is available for the requested passenger and
+     * direction. A successful response must set this field explicitly.
+     *
+     * @generated from field: caronashow.service.v1.RecommendationAvailability availability = 5;
+     */
+    availability: RecommendationAvailability;
+    /**
+     * True when a newer Backend batch is being coordinated while this response
+     * still serves the last valid published result. It is also true for a
+     * COMPUTING response with no published set; it is false for UNAVAILABLE.
+     *
+     * @generated from field: bool refresh_in_progress = 6;
+     */
+    refreshInProgress: boolean;
+    /**
+     * Number of candidates in the published result set before viewport filtering.
+     * Zero is meaningful only with EXHAUSTED; it is zero while COMPUTING. Clients
+     * derive the visible count from either projection array length.
+     *
+     * @generated from field: int32 result_candidate_count = 7;
+     */
+    resultCandidateCount: number;
+    /**
+     * IANA timezone used to interpret all organization schedule fields in this
+     * response. Empty while availability is COMPUTING or UNAVAILABLE.
+     *
+     * @generated from field: string organization_time_zone = 8;
+     */
+    organizationTimeZone: string;
 };
 /**
  * Describes the message caronashow.service.v1.ListRideSuggestionsResponse.
@@ -87,8 +124,8 @@ export type MapViewport = Message<"caronashow.service.v1.MapViewport"> & {
      */
     southwest?: LatLng | undefined;
     /**
-     * Northeast corner of the visible rectangle. The rectangle must not cross
-     * the antimeridian and must fit the server's supported maximum search area.
+     * Northeast corner of the visible rectangle. The rectangle must not cross the
+     * antimeridian or exceed the server's supported maximum search area.
      *
      * @generated from field: google.type.LatLng northeast = 2;
      */
@@ -113,8 +150,9 @@ export declare const MapViewportSchema: GenMessage<MapViewport>;
  */
 export type MapRideSuggestion = Message<"caronashow.service.v1.MapRideSuggestion"> & {
     /**
-     * Opaque passenger-scoped identifier shared with the ranked projection. It
-     * remains stable while the matched offer and commute direction are unchanged.
+     * Non-enumerable opaque passenger-scoped identifier shared with the ranked
+     * projection. It must not encode a database candidate ID and must be
+     * authorized against the authenticated passenger and result set.
      *
      * @generated from field: string suggestion_id = 1;
      */
@@ -126,18 +164,28 @@ export type MapRideSuggestion = Message<"caronashow.service.v1.MapRideSuggestion
      */
     rank: number;
     /**
-     * Driver-side route endpoint shown by the marker. This is the route start
-     * toward the organization and the route end when leaving the organization.
+     * Server-generated coarse center for the driver's endpoint. This field must
+     * never expose an exact home address.
      *
      * @generated from field: google.type.LatLng driver_endpoint_location = 3;
      */
     driverEndpointLocation?: LatLng | undefined;
     /**
-     * Route path and cache identity used by the map renderer.
+     * Safe route path and cache identity used by the map renderer. For the first
+     * outbound release, the path runs from the coarse driver area toward the
+     * organization area. It must not expose the passenger's exact origin or a
+     * raw Pooler stop sequence.
      *
      * @generated from field: caronashow.service.v1.RouteGeometry route_geometry = 4;
      */
     routeGeometry?: RouteGeometry | undefined;
+    /**
+     * Explicit uncertainty area for the endpoint. Clients should use this
+     * center and radius instead of treating the point as exact.
+     *
+     * @generated from field: caronashow.service.v1.ApproximateLocation driver_endpoint_area = 5;
+     */
+    driverEndpointArea?: ApproximateLocation | undefined;
 };
 /**
  * Describes the message caronashow.service.v1.MapRideSuggestion.
@@ -146,25 +194,30 @@ export type MapRideSuggestion = Message<"caronashow.service.v1.MapRideSuggestion
 export declare const MapRideSuggestionSchema: GenMessage<MapRideSuggestion>;
 /**
  * Map-ready geometry for one direction of a driver's organization commute.
+ * The Backend must materialize or retain this safe projection at publication;
+ * a later Pooler operation cleanup must not make a published card unreadable.
  *
  * @generated from message caronashow.service.v1.RouteGeometry
  */
 export type RouteGeometry = Message<"caronashow.service.v1.RouteGeometry"> & {
     /**
-     * Cache identifier for this exact encoded path, precision, direction, and
-     * simplification level. Any encoded-polyline change produces a new ID.
+     * Non-enumerable opaque cache identifier for this exact encoded path,
+     * precision, direction, and simplification level. It must not be a raw
+     * Pooler route ID; any encoded-polyline change produces a new ID.
      *
      * @generated from field: string route_geometry_id = 1;
      */
     routeGeometryId: string;
     /**
-     * Google Encoded Polyline Algorithm Format path at precision 5.
+     * Google Encoded Polyline Algorithm Format path at precision 5. The Backend
+     * must simplify/coarsen the path before encoding it for pre-connection use.
      *
      * @generated from field: string encoded_polyline = 2;
      */
     encodedPolyline: string;
     /**
-     * Bounds of the complete route, including portions outside the viewport.
+     * Safe bounds enclosing the displayed route. Bounds must follow the same
+     * privacy treatment as the route and must not recover an exact endpoint.
      *
      * @generated from field: caronashow.service.v1.RouteBounds bounds = 3;
      */
@@ -176,7 +229,7 @@ export type RouteGeometry = Message<"caronashow.service.v1.RouteGeometry"> & {
  */
 export declare const RouteGeometrySchema: GenMessage<RouteGeometry>;
 /**
- * Geographic bounds enclosing a complete route geometry.
+ * Geographic bounds enclosing a complete safe route geometry.
  *
  * @generated from message caronashow.service.v1.RouteBounds
  */
@@ -199,6 +252,68 @@ export type RouteBounds = Message<"caronashow.service.v1.RouteBounds"> & {
  * Use `create(RouteBoundsSchema)` to create a new message.
  */
 export declare const RouteBoundsSchema: GenMessage<RouteBounds>;
+/**
+ * Server-generated uncertainty area for a pre-connection location.
+ *
+ * @generated from message caronashow.service.v1.ApproximateLocation
+ */
+export type ApproximateLocation = Message<"caronashow.service.v1.ApproximateLocation"> & {
+    /**
+     * Coarse center of the neighborhood-level area. It is not an address pin and
+     * must equal driver_endpoint_location when both are set.
+     *
+     * @generated from field: google.type.LatLng center = 1;
+     */
+    center?: LatLng | undefined;
+    /**
+     * Positive radius in meters that communicates location uncertainty to the map
+     * UI. The Backend must not choose a radius that permits exact-address recovery.
+     *
+     * @generated from field: uint32 radius_meters = 2;
+     */
+    radiusMeters: number;
+};
+/**
+ * Describes the message caronashow.service.v1.ApproximateLocation.
+ * Use `create(ApproximateLocationSchema)` to create a new message.
+ */
+export declare const ApproximateLocationSchema: GenMessage<ApproximateLocation>;
+/**
+ * Neighborhood-level address summary safe to show before a ride connection.
+ *
+ * @generated from message caronashow.service.v1.ApproximateAddress
+ */
+export type ApproximateAddress = Message<"caronashow.service.v1.ApproximateAddress"> & {
+    /**
+     * Neighborhood or sublocality; street and number are never included.
+     *
+     * @generated from field: string neighborhood = 1;
+     */
+    neighborhood: string;
+    /**
+     * City or municipality.
+     *
+     * @generated from field: string city = 2;
+     */
+    city: string;
+    /**
+     * State or administrative area.
+     *
+     * @generated from field: string state = 3;
+     */
+    state: string;
+    /**
+     * ISO 3166-1 alpha-2 country code.
+     *
+     * @generated from field: string country = 4;
+     */
+    country: string;
+};
+/**
+ * Describes the message caronashow.service.v1.ApproximateAddress.
+ * Use `create(ApproximateAddressSchema)` to create a new message.
+ */
+export declare const ApproximateAddressSchema: GenMessage<ApproximateAddress>;
 /**
  * Rich ride card shown in the passenger's ranked suggestions drawer.
  *
@@ -206,8 +321,9 @@ export declare const RouteBoundsSchema: GenMessage<RouteBounds>;
  */
 export type RankedRideSuggestion = Message<"caronashow.service.v1.RankedRideSuggestion"> & {
     /**
-     * Opaque passenger-scoped identifier shared with the map projection. It
-     * remains stable while the matched offer and commute direction are unchanged.
+     * Non-enumerable opaque passenger-scoped identifier shared with the map
+     * projection. It must not encode a database candidate ID and must be
+     * authorized against the authenticated passenger and result set.
      *
      * @generated from field: string suggestion_id = 1;
      */
@@ -219,35 +335,29 @@ export type RankedRideSuggestion = Message<"caronashow.service.v1.RankedRideSugg
      */
     rank: number;
     /**
-     * Public driver profile data needed by the suggestion card.
+     * Public driver profile data displayed before a ride request.
      *
      * @generated from field: caronashow.service.v1.DriverSummary driver = 3;
      */
     driver?: DriverSummary | undefined;
     /**
-     * Vehicle details safe to display while browsing this ride offer.
-     *
-     * @generated from field: caronashow.service.v1.VehicleSummary vehicle = 4;
-     */
-    vehicle?: VehicleSummary | undefined;
-    /**
-     * Driver-side route endpoint opposite the organization. This is the route
-     * start toward the organization and the route end when leaving it.
+     * Neighborhood-level endpoint summary safe to show before a ride
+     * connection. Street, number, postal code, place ID, and exact coordinates
+     * are never included.
      *
-     * @generated from field: caronashow.types.v1.FullAddress driver_endpoint_address = 5;
+     * @generated from field: caronashow.service.v1.ApproximateAddress driver_endpoint_address = 5;
      */
-    driverEndpointAddress?: FullAddress | undefined;
+    driverEndpointAddress?: ApproximateAddress | undefined;
     /**
-     * Offer-specific seat inventory for this direction of travel.
+     * Offer-specific seat inventory for this directional ride suggestion.
      *
      * @generated from field: caronashow.service.v1.SeatAvailability seats = 6;
      */
     seats?: SeatAvailability | undefined;
     /**
-     * Driver's usual arrival time at the organization for
-     * COMMUTE_DIRECTION_TO_ORGANIZATION, or departure time from the organization
-     * for COMMUTE_DIRECTION_FROM_ORGANIZATION. Interpreted in the organization's
-     * local timezone.
+     * Optional exact organization time when a trusted Backend calculation exists
+     * for a custom schedule. Clients must prefer organization_arrival_window and
+     * hide the schedule when both are absent.
      *
      * @generated from field: caronashow.types.v1.TimeOfDay organization_time = 7;
      */
@@ -259,6 +369,41 @@ export type RankedRideSuggestion = Message<"caronashow.service.v1.RankedRideSugg
      * @generated from field: bool restricted_to_vulnerable_group = 8;
      */
     restrictedToVulnerableGroup: boolean;
+    /**
+     * Arrival window associated with the driver's named organization shift. It
+     * is interpreted using organization_time_zone and is the preferred schedule
+     * display for the first outbound release. It is absent for a custom schedule
+     * unless the Backend can derive a meaningful window; clients may use the
+     * exact-time field as a fallback.
+     *
+     * @generated from field: caronashow.service.v1.TimeWindow organization_arrival_window = 10;
+     */
+    organizationArrivalWindow?: TimeWindow | undefined;
+    /**
+     * Optional finite, nonnegative route distance from the published candidate,
+     * in kilometers. The Backend maps the Pooler result and does not ask the
+     * browser to calculate it.
+     *
+     * @generated from field: optional double route_distance_km = 11;
+     */
+    routeDistanceKm?: number | undefined;
+    /**
+     * Optional finite, nonnegative route duration from the published candidate,
+     * in seconds. The Backend maps the Pooler result and does not ask the browser
+     * to calculate it.
+     *
+     * @generated from field: optional double route_duration_seconds = 12;
+     */
+    routeDurationSeconds?: number | undefined;
+    /**
+     * Optional finite, nonnegative additional duration incurred by the driver
+     * for this passenger, relative to the driver's direct baseline route to the
+     * organization. The Backend derives it from the same published snapshot; the
+     * browser must not calculate it.
+     *
+     * @generated from field: optional double driver_detour_duration_seconds = 13;
+     */
+    driverDetourDurationSeconds?: number | undefined;
 };
 /**
  * Describes the message caronashow.service.v1.RankedRideSuggestion.
@@ -272,7 +417,8 @@ export declare const RankedRideSuggestionSchema: GenMessage<RankedRideSuggestion
  */
 export type DriverSummary = Message<"caronashow.service.v1.DriverSummary"> & {
     /**
-     * Stable driver identifier used to open the public driver profile.
+     * Non-enumerable opaque driver identifier used by a future public-profile
+     * route; it must not be a database identity or an unauthenticated capability.
      *
      * @generated from field: string driver_id = 1;
      */
@@ -284,7 +430,8 @@ export type DriverSummary = Message<"caronashow.service.v1.DriverSummary"> & {
      */
     firstName: string;
     /**
-     * URL of the driver's profile avatar.
+     * Absolute URL of a resolved avatar asset, when the asset contract permits
+     * it. Empty means the UI must use an initials fallback.
      *
      * @generated from field: string avatar_url = 3;
      */
@@ -296,53 +443,33 @@ export type DriverSummary = Message<"caronashow.service.v1.DriverSummary"> & {
      */
     rank: UserRank;
     /**
-     * Aggregate passenger rating from 0.0 to 5.0; zero when not yet rated.
+     * Aggregate passenger rating from 0.0 to 5.0; zero means no aggregate is
+     * available yet.
      *
      * @generated from field: double rating = 5;
      */
     rating: number;
     /**
-     * Nonnegative number of ratings included in rating; zero when not yet rated.
+     * Nonnegative number of ratings included in the aggregate rating, when
+     * available. Absence means the Backend has no value; clients must not display
+     * a fabricated zero.
      *
-     * @generated from field: int32 rating_count = 6;
+     * @generated from field: optional int32 rating_count = 6;
      */
-    ratingCount: number;
+    ratingCount?: number | undefined;
     /**
-     * Nonnegative number of completed rides used as an additional trust signal.
+     * Nonnegative number of completed rides, when available. Absence means the
+     * Backend has no value; clients must not display a fabricated zero.
      *
-     * @generated from field: int32 completed_rides = 7;
+     * @generated from field: optional int32 completed_rides = 7;
      */
-    completedRides: number;
+    completedRides?: number | undefined;
 };
 /**
  * Describes the message caronashow.service.v1.DriverSummary.
  * Use `create(DriverSummarySchema)` to create a new message.
  */
 export declare const DriverSummarySchema: GenMessage<DriverSummary>;
-/**
- * Vehicle details safe to display while browsing ride suggestions.
- *
- * @generated from message caronashow.service.v1.VehicleSummary
- */
-export type VehicleSummary = Message<"caronashow.service.v1.VehicleSummary"> & {
-    /**
-     * Vehicle make and model (e.g. "Honda Fit 2019").
-     *
-     * @generated from field: string model = 1;
-     */
-    model: string;
-    /**
-     * Vehicle exterior color (e.g. "Prata").
-     *
-     * @generated from field: string color = 2;
-     */
-    color: string;
-};
-/**
- * Describes the message caronashow.service.v1.VehicleSummary.
- * Use `create(VehicleSummarySchema)` to create a new message.
- */
-export declare const VehicleSummarySchema: GenMessage<VehicleSummary>;
 /**
  * Offer-specific seat inventory for one directional ride suggestion.
  *
@@ -350,17 +477,20 @@ export declare const VehicleSummarySchema: GenMessage<VehicleSummary>;
  */
 export type SeatAvailability = Message<"caronashow.service.v1.SeatAvailability"> & {
     /**
-     * Positive number of passenger seats offered for this commute leg.
+     * Positive number of passenger seats offered by the selected vehicle.
      *
      * @generated from field: int32 offered_seats = 1;
      */
     offeredSeats: number;
     /**
-     * Currently available seats, from zero through offered_seats.
+     * Current available seats when the request/capacity subsystem supplies it.
+     * Absence means seat availability is not part of the read contract; clients
+     * must show offered capacity without treating zero as remaining capacity. When
+     * present, the Backend must return 0 <= available_seats <= offered_seats.
      *
-     * @generated from field: int32 available_seats = 2;
+     * @generated from field: optional int32 available_seats = 2;
      */
-    availableSeats: number;
+    availableSeats?: number | undefined;
 };
 /**
  * Describes the message caronashow.service.v1.SeatAvailability.
@@ -380,13 +510,15 @@ export declare enum CommuteDirection {
      */
     UNSPECIFIED = 0,
     /**
-     * Driver and passenger travel toward the organization.
+     * Driver and passenger travel toward the organization. Supported by the
+     * first Backend recommendation release.
      *
      * @generated from enum value: COMMUTE_DIRECTION_TO_ORGANIZATION = 1;
      */
     TO_ORGANIZATION = 1,
     /**
-     * Driver and passenger leave the organization for their return trip.
+     * Driver and passenger leave the organization for their return trip. Kept
+     * for the shared Home model; not supported by the first Backend release.
      *
      * @generated from enum value: COMMUTE_DIRECTION_FROM_ORGANIZATION = 2;
      */
@@ -396,15 +528,69 @@ export declare enum CommuteDirection {
  * Describes the enum caronashow.service.v1.CommuteDirection.
  */
 export declare const CommuteDirectionSchema: GenEnum<CommuteDirection>;
+/**
+ * Availability of the authenticated passenger's published recommendation set.
+ * This describes the set before viewport filtering; projection array lengths
+ * describe the filtered projection returned in this response.
+ *
+ * @generated from enum caronashow.service.v1.RecommendationAvailability
+ */
+export declare enum RecommendationAvailability {
+    /**
+     * Default value; a successful response must never use it.
+     *
+     * @generated from enum value: RECOMMENDATION_AVAILABILITY_UNSPECIFIED = 0;
+     */
+    UNSPECIFIED = 0,
+    /**
+     * No published result exists yet because the Backend batch is queued,
+     * running, restoring, or otherwise has not produced a readable snapshot.
+     *
+     * @generated from enum value: RECOMMENDATION_AVAILABILITY_COMPUTING = 1;
+     */
+    COMPUTING = 1,
+    /**
+     * A published result exists and contains at least one safe suggestion. It
+     * may contain fewer than the configured maximum after successful exhaustion.
+     *
+     * @generated from enum value: RECOMMENDATION_AVAILABILITY_READY = 2;
+     */
+    READY = 2,
+    /**
+     * A published result exists and contains zero candidates after exhaustion.
+     *
+     * @generated from enum value: RECOMMENDATION_AVAILABILITY_EXHAUSTED = 3;
+     */
+    EXHAUSTED = 3,
+    /**
+     * No published result can be served because the first batch reached a
+     * terminal failure. Projections are empty; clients should offer retry.
+     *
+     * @generated from enum value: RECOMMENDATION_AVAILABILITY_UNAVAILABLE = 4;
+     */
+    UNAVAILABLE = 4
+}
+/**
+ * Describes the enum caronashow.service.v1.RecommendationAvailability.
+ */
+export declare const RecommendationAvailabilitySchema: GenEnum<RecommendationAvailability>;
 /**
  * @generated from service caronashow.service.v1.MatchingService
  */
 export declare const MatchingService: GenService<{
     /**
-     * Lists ride offers whose routes intersect the requested map viewport.
-     * The authenticated passenger and their saved search setup are inferred
-     * from the session token. Returns UNAUTHENTICATED without a valid session and
-     * INVALID_ARGUMENT for an invalid viewport or commute direction.
+     * Lists published ride offers whose safe route projection intersects the
+     * requested map viewport. The authenticated passenger, organization, and
+     * saved Search setup are inferred from the session token.
+     *
+     * The first Backend recommendation release supports only
+     * COMMUTE_DIRECTION_TO_ORGANIZATION. FROM_ORGANIZATION remains in the enum
+     * for forward compatibility and returns UNIMPLEMENTED until the Backend
+     * dataset and projection support the return direction.
+     *
+     * Returns UNAUTHENTICATED without a valid session, FAILED_PRECONDITION when
+     * the caller has no eligible Search setup, and INVALID_ARGUMENT for an
+     * invalid viewport or direction.
      *
      * @generated from rpc caronashow.service.v1.MatchingService.ListRideSuggestions
      */