feat(reviews): verified-purchase reviews, eligibility endpoint and own-review delete

server/migrations/2026_10_07_000000_add_order_uuid_to_reviews_table.php

@@ -0,0 +1,41 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration {
+    /**
+     * Link a review to the completed order it was written for.
+     *
+     * Reviews from customers are only accepted for a completed order that contains the
+     * store or product, and an order can be reviewed once per subject.
+     */
+    public function up(): void
+    {
+        $connection = config('storefront.connection.db');
+
+        if (Schema::connection($connection)->hasColumn('reviews', 'order_uuid')) {
+            return;
+        }
+
+        Schema::connection($connection)->table('reviews', function (Blueprint $table) {
+            $table->char('order_uuid', 36)->nullable()->after('customer_uuid');
+            $table->index(['customer_uuid', 'subject_uuid', 'order_uuid'], 'reviews_customer_subject_order_index');
+        });
+    }
+
+    public function down(): void
+    {
+        $connection = config('storefront.connection.db');
+
+        if (!Schema::connection($connection)->hasColumn('reviews', 'order_uuid')) {
+            return;
+        }
+
+        Schema::connection($connection)->table('reviews', function (Blueprint $table) {
+            $table->dropIndex('reviews_customer_subject_order_index');
+            $table->dropColumn('order_uuid');
+        });
+    }
+};

server/src/Http/Controllers/v1/ReviewController.php

@@ -11,6 +11,7 @@
 use Fleetbase\Storefront\Models\Product;
 use Fleetbase\Storefront\Models\Review;
 use Fleetbase\Storefront\Models\Store;
+use Fleetbase\Storefront\Support\ReviewEligibility;
 use Fleetbase\Storefront\Support\Storefront;
 use Illuminate\Database\Eloquent\ModelNotFoundException;
 use Illuminate\Http\Request;
@@ -216,6 +217,29 @@ public function find($id)
         return new StorefrontReview($review);
     }
 
+    /**
+     * Whether the signed-in customer can review a store or product, and why not.
+     *
+     * The app calls this before showing "Write a review", so a customer who has not completed
+     * an order, or has already reviewed every completed one, sees an explanation instead.
+     */
+    public function eligibility(Request $request)
+    {
+        $subjectId = $request->input('subject');
+        if (!is_string($subjectId) || $subjectId === '') {
+            return response()->error('A subject is required.');
+        }
+
+        $subject = Utils::resolveSubject($subjectId);
+        if (!$subject || !$this->subjectBelongsToContext($subject)) {
+            return response()->error('Invalid subject for review');
+        }
+
+        $eligibility = ReviewEligibility::check(Storefront::getCustomerFromToken(), $subject, $request->input('order'));
+
+        return response()->json($eligibility->toArray());
+    }
+
     /**
      * Create a review.
      *
@@ -238,9 +262,15 @@ public function create(CreateReviewRequest $request)
             return response()->error('Invalid subject for review');
         }
 
+        $eligibility = ReviewEligibility::check($customer, $subject, $request->input('order'));
+        if (!$eligibility->allowed) {
+            return response()->json(['error' => $eligibility->message(), 'reason' => $eligibility->reason], 403);
+        }
+
         $review = Review::create([
             'created_by_uuid' => $customer->user_uuid,
             'customer_uuid'   => $customer->uuid,
+            'order_uuid'      => $eligibility->order->uuid,
             'subject_uuid'    => $subject->uuid,
             'subject_type'    => Utils::getMutationType($subject),
             'rating'          => $request->input('rating'),

server/src/Http/Requests/CreateReviewRequest.php

@@ -31,11 +31,14 @@ public function rules()
         // — as a 500, before the controller's own "Invalid subject for review" guard
         // could run. That guard was unreachable for the commonest way to get it wrong.
         return [
-            'subject'  => 'required|string',
-            'rating'   => 'required|numeric',
-            'content'  => 'required',
-            'files'    => 'sometimes|array',
-            'rejected' => 'sometimes|boolean',
+            'subject'      => 'required|string',
+            'order'        => 'sometimes|nullable|string',
+            'rating'       => 'required|integer|between:1,5',
+            'content'      => 'required|string|max:2000',
+            'files'        => 'sometimes|array|max:4',
+            'files.*.data' => 'required_with:files|string',
+            'files.*.type' => 'required_with:files|string|starts_with:image/,video/',
+            'rejected'     => 'sometimes|boolean',
         ];
     }
 }

server/src/Http/Resources/Review.php

@@ -3,6 +3,8 @@
 namespace Fleetbase\Storefront\Http\Resources;
 
 use Fleetbase\Http\Resources\FleetbaseResource;
+use Fleetbase\Storefront\Models\Product;
+use Fleetbase\Storefront\Support\Storefront;
 use Fleetbase\Support\Http;
 
 class Review extends FleetbaseResource
@@ -17,17 +19,21 @@ class Review extends FleetbaseResource
     public function toArray($request)
     {
         return [
-            'id'         => $this->when(Http::isInternalRequest(), $this->id, $this->public_id),
-            'uuid'       => $this->when(Http::isInternalRequest(), $this->uuid),
-            'public_id'  => $this->when(Http::isInternalRequest(), $this->public_id),
-            'subject_id' => $this->subject->id,
-            'rating'     => $this->rating,
-            'content'    => $this->content,
-            'customer'   => new ReviewCustomer($this->customer),
-            'slug'       => $this->slug,
-            'photos'     => $this->mapPhotos($this->photos),
-            'created_at' => $this->created_at,
-            'updated_at' => $this->updated_at,
+            'id'           => $this->when(Http::isInternalRequest(), $this->id, $this->public_id),
+            'uuid'         => $this->when(Http::isInternalRequest(), $this->uuid),
+            'public_id'    => $this->when(Http::isInternalRequest(), $this->public_id),
+            'subject_id'   => $this->when(Http::isInternalRequest(), $this->subject?->id, $this->subject?->public_id),
+            'subject_type' => $this->subject instanceof Product ? 'product' : 'store',
+            'order_uuid'   => $this->when(Http::isInternalRequest(), $this->order_uuid),
+            'verified'     => !empty($this->order_uuid),
+            'is_mine'      => $this->customer_uuid !== null && $this->customer_uuid === static::viewerCustomerUuid(),
+            'rating'       => $this->rating,
+            'content'      => $this->content,
+            'customer'     => new ReviewCustomer($this->customer),
+            'slug'         => $this->slug,
+            'photos'       => $this->mapPhotos($this->photos),
+            'created_at'   => $this->created_at,
+            'updated_at'   => $this->updated_at,
         ];
     }
 
@@ -43,4 +49,20 @@ public function mapPhotos($photos = [])
             ];
         });
     }
+
+    /**
+     * The uuid of the customer making the request, looked up once per request so that a
+     * page of reviews does not resolve the customer token for every review.
+     */
+    public static function viewerCustomerUuid(): ?string
+    {
+        $request = request();
+        $key     = 'storefront.review_viewer_uuid';
+
+        if (!$request->attributes->has($key)) {
+            $request->attributes->set($key, Http::isInternalRequest() ? null : Storefront::getCustomerFromToken()?->uuid);
+        }
+
+        return $request->attributes->get($key);
+    }
 }

server/src/Http/Resources/ReviewCustomer.php

@@ -17,13 +17,17 @@ class ReviewCustomer extends FleetbaseResource
      */
     public function toArray($request)
     {
+        $internal = Http::isInternalRequest();
+
+        // Reviews are public: customers see each other's first name and last initial only,
+        // never their contact details.
         return [
             'id'            => $this->when(Http::isInternalRequest(), $this->id, Str::replaceFirst('contact', 'customer', $this->public_id)),
             'uuid'          => $this->when(Http::isInternalRequest(), $this->uuid),
             'public_id'     => $this->when(Http::isInternalRequest(), $this->public_id),
-            'name'          => $this->name,
-            'email'         => $this->email,
-            'phone'         => $this->phone,
+            'name'          => $internal ? $this->name : static::publicName($this->name),
+            'email'         => $this->when($internal, $this->email),
+            'phone'         => $this->when($internal, $this->phone),
             'photo_url'     => $this->photo_url,
             'reviews_count' => $this->resource->reviews()->count(),
             'uploads_count' => $this->resource->reviewUploads()->count(),
@@ -32,4 +36,21 @@ public function toArray($request)
             'updated_at'    => $this->updated_at,
         ];
     }
+
+    /**
+     * "Ada B." from "Ada Buyer"; a single name is shown as is.
+     */
+    public static function publicName(?string $name): ?string
+    {
+        $parts = preg_split('/\s+/u', trim((string) $name), -1, PREG_SPLIT_NO_EMPTY);
+        if (!$parts) {
+            return null;
+        }
+
+        if (count($parts) === 1) {
+            return $parts[0];
+        }
+
+        return $parts[0] . ' ' . mb_strtoupper(mb_substr(end($parts), 0, 1)) . '.';
+    }
 }

server/src/Models/Review.php

@@ -2,6 +2,7 @@
 
 namespace Fleetbase\Storefront\Models;
 
+use Fleetbase\FleetOps\Models\Order;
 use Fleetbase\Models\File;
 use Fleetbase\Models\User;
 use Fleetbase\Traits\HasApiModelBehavior;
@@ -45,6 +46,7 @@ class Review extends StorefrontModel
     protected $fillable = [
         'created_by_uuid',
         'customer_uuid',
+        'order_uuid',
         'subject_uuid',
         'subject_type',
         'rating',
@@ -57,7 +59,9 @@ class Review extends StorefrontModel
      *
      * @var array
      */
-    protected $casts = [];
+    protected $casts = [
+        'rating' => 'integer',
+    ];
 
     /**
      * Dynamic attributes that are appended to object.
@@ -89,6 +93,14 @@ public function customer()
         return $this->setConnection(config('fleetbase.connection.db'))->belongsTo(Customer::class);
     }
 
+    /**
+     * The completed order this review was written for.
+     */
+    public function order()
+    {
+        return $this->belongsTo(Order::class, 'order_uuid', 'uuid');
+    }
+
     /**
      * @return \Illuminate\Database\Eloquent\Relations\HasMany
      */