Document Storefront verified reviews, promotion availability, order chat and add-on limits

[roncodes]

Summary

Documents the Storefront API changes from fleetbase/storefront#115, #116, #117 and #118, which the redesigned app uses:

• Reviews (#115):
  • New Check Review Eligibility request (GET reviews/eligibility), returning can_review, reason, message, order and review.
  • Create a review: documents the verified-purchase rule, the optional order and files, and the 403 { error, reason } refusal.
  • Delete a Review: now sends the customer token, since customers can only delete their own reviews.
  • Query Reviews: documents the store param (required with network keys) and the sort values.
  • Review object: gains subject_type, verified and is_mine. The reviewer is shown as first name and last initial, with no email or phone.
• Promotions (#116):
  • Query Promotions: documents include=scheduled.
  • Retrieve a Promotion: now also returns scheduled and ended promotions.
  • Promotion object: gains code (a shareable code), availability, next_starts_at and owner. applies_to lists public IDs.
• Order Chat (#117): new folder with Get Order Chat, List Order Chat Messages (before/limit), Send Order Chat Message and Mark Order Chat as Read. It covers the Order Chat object, the chat.{id} socket channel and events, and the 401/403/404/409 driver_not_assigned/423 chat_closed refusals.
• Products (#118): add-on categories document is_required and max_selectable.

Related Issue

Closes #

Type of Change

• Bug fix
• Feature
• Refactor
• Documentation
• Test
• Chore

Implementation Notes

Requests whose result depends on data the run may not have follow the collection's existing expected_status pattern:

• Create a review: expects the 403 refusal unless the environment sets review_eligible.
• Order Chat requests:
  • with chat_order_id set (an order with an assigned driver), they expect success;
  • otherwise they address order_id and expect 409 driver_not_assigned;
  • with no order at all, they expect 404.

Validation

• Tests
• Lint
• Build
• Manual validation

Command output / summary:

npm run postman:lint
Validated 5 Postman Native Git collections and 3 environments.
Linting Fleetbase Storefront API...
No issues found.
Scanned: 81 | Errors: 0 | Warnings: 0

Not run: postman:run:storefront. It needs a running stack with the backend PRs deployed.

Documentation Impact

• No documentation changes needed
• Documentation updated in fleetbase/fleetbase.io
• Documentation needed but not included: the API reference on fleetbase.io needs regenerating once this and the backend PRs merge.

Update: complete against storefront v0.4.25 (fleetbase/storefront#119)

I compared every storefront/v1 route, controller and response resource on release/v0.4.25 with this collection.

New requests

• GET orders/{id}/activity-flow: the order's progress steps.
• GET orders/{id}/stores: each store's part of a multi-store Network order.
• POST customers/socket-token: a customer token for the realtime connection.

Corrected or completed

• Checkout
  • gateway is a gateway code or cash.
  • customer, cart and service_quote are now marked required where the API requires them.
  • pickup and cash are booleans, and tips accept percentages.
  • Adds the promoCode alias and ebarimt_registration_no.
  • Documents socket_token and the checkout.{id} realtime channel.
  • Status is answered from the database, with verify.
  • The QPay callback answers SUCCESS in plain text, and PAYMENT_NOT_PAID replaces PAYMENT_NOTFOUND.
  • Updating a Stripe payment intent keeps the same checkout.
  • The setup intent takes only customer.
  • Capture uses the cart as it was at checkout, and documents booking and master orders.
• Carts: documents the open, checked out and cleared statuses. Emptying a cart returns the device's open cart. Lines can come from a catalog or a food truck.
• Service quotes: the cart_items_unavailable 422, new params (facilitator, scheduled_at, service_type, all, is_route_optimized) and the full quote object.
• Customers: the SMS login falls back to email, the review-account bypass, and corrected create and update fields.
• Order chat: limit defaults to 50, chat ids use the chat_ prefix, the 403 and 422 responses, and the socket token.
• Food trucks: the store and network fields, catalog pricing, network scoping, and retrieve limited to the storefront's own trucks.
• Reviews: reviews_disabled and the network store param.
• Other: fields and descriptions corrected for products, stores, promotions, notifications and categories.

npm run postman:lint passes with 0 errors.