@fleetbase/fleetops-engine 0.6.58 → 0.6.59

package/server/tests/Feature/Http/Internal/OrderControllerImportFromFilesTest.php

@@ -0,0 +1,179 @@
+<?php
+
+if (!function_exists('Fleetbase\Support\session')) {
+    eval('namespace Fleetbase\Support; function session($key = null, $default = null) { if ($key === null) { return new class { public function has($k) { return \session($k) !== null; } public function get($k, $d = null) { return \session($k, $d); } }; } return \session($key, $default); }');
+}
+
+if (!function_exists('Fleetbase\Support\env')) {
+    eval('namespace Fleetbase\Support; function env($key = null, $default = null) { return $default; }');
+}
+
+if (!function_exists('Fleetbase\Support\auth')) {
+    eval('namespace Fleetbase\Support; function auth() { return new class { public function user() { return null; } public function id() { return null; } }; }');
+}
+
+use Fleetbase\FleetOps\Http\Controllers\Internal\v1\OrderController;
+use Illuminate\Database\ConnectionResolver;
+use Illuminate\Database\Eloquent\Model as EloquentModel;
+use Illuminate\Database\SQLiteConnection;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Http;
+
+/**
+ * Covers the internal OrderController importFromFiles endpoint against
+ * SQLite with faked ip lookup, excel reader and geocoder: spreadsheet rows
+ * imported into places with delimited entity items, empty-row skips,
+ * invalid file type rejection, and unreadable spreadsheet errors.
+ */
+function fleetopsOrderImportFilesBoot(): SQLiteConnection
+{
+    $pdo = new PDO('sqlite::memory:');
+    $pdo->sqliteCreateFunction('ST_PointFromText', fn ($wkt, $srid = 0, $axisOrder = null) => $wkt);
+    $pdo->sqliteCreateFunction('ST_GeomFromText', fn ($wkt, $srid = 0, $axisOrder = null) => $wkt);
+    $connection = new SQLiteConnection($pdo);
+    $resolver   = new ConnectionResolver(['default' => $connection, 'mysql' => $connection]);
+    $resolver->setDefaultConnection('mysql');
+    EloquentModel::setConnectionResolver($resolver);
+    EloquentModel::setEventDispatcher(new Illuminate\Events\Dispatcher());
+    app()->instance('db', new class($connection) {
+        public function __construct(public SQLiteConnection $c)
+        {
+        }
+
+        public function connection($name = null): SQLiteConnection
+        {
+            return $this->c;
+        }
+
+        public function __call($method, $arguments)
+        {
+            return $this->c->{$method}(...$arguments);
+        }
+    });
+    Illuminate\Support\Facades\DB::clearResolvedInstance('db');
+
+    app()->instance('request', Request::create('/int/v1/orders/import-from-files', 'POST'));
+
+    app()->instance('geocoder', new class {
+        public function geocode($query)
+        {
+            return $this;
+        }
+
+        public function reverse($latitude, $longitude)
+        {
+            return $this;
+        }
+
+        public function get()
+        {
+            return collect();
+        }
+
+        public function __call($method, $arguments)
+        {
+            return $this;
+        }
+    });
+
+    Http::clearResolvedInstances();
+    app()->forgetInstance(Illuminate\Http\Client\Factory::class);
+    Http::fake(['api.ipdata.co/*' => Http::response(['country_name' => 'Singapore'], 200)]);
+
+    $schema = $connection->getSchemaBuilder();
+    $tables = [
+        'files'  => ['uuid', 'public_id', 'company_uuid', 'name', 'original_filename', 'extension', 'content_type', 'path', 'bucket', 'disk', 'type', 'size', 'meta', '_key'],
+        'places' => ['uuid', 'public_id', 'company_uuid', 'owner_uuid', 'name', 'street1', 'street2', 'city', 'province', 'postal_code', 'country', 'neighborhood', 'building', 'phone', 'location', 'meta', 'type', '_key', '_import_id'],
+    ];
+    foreach ($tables as $table => $columns) {
+        $schema->create($table, function ($blueprint) use ($columns) {
+            $blueprint->increments('id');
+            foreach ($columns as $column) {
+                $blueprint->string($column)->nullable();
+            }
+            $blueprint->timestamps();
+            $blueprint->timestamp('deleted_at')->nullable();
+        });
+    }
+
+    session(['company' => 'company-1', 'api_key' => 'console']);
+
+    return $connection;
+}
+
+function fleetopsOrderImportFilesExcelFake(array $rows, bool $throws = false): void
+{
+    app()->instance('excel', new class($rows, $throws) {
+        public function __construct(public array $rows, public bool $throws)
+        {
+        }
+
+        public function toArray($import, $path, $disk = null)
+        {
+            if ($this->throws) {
+                throw new RuntimeException('corrupt spreadsheet');
+            }
+
+            return $this->rows;
+        }
+
+        public function __call($method, $arguments)
+        {
+            return null;
+        }
+    });
+}
+
+function fleetopsOrderImportFilesRequest(array $input): Request
+{
+    $request = Request::create('/int/v1/orders/import-from-files', 'POST', $input);
+    $store   = app('session.store');
+    $store->put('company', 'company-1');
+    $request->setLaravelSession($store);
+
+    return $request;
+}
+
+test('spreadsheet rows import places and delimited entities', function () {
+    $connection = fleetopsOrderImportFilesBoot();
+    $connection->table('files')->insert(['uuid' => '11111111-1111-4111-8111-111111111111', 'public_id' => 'file_ordimport1', 'company_uuid' => 'company-1', 'path' => 'uploads/orders.xlsx', 'disk' => 'local']);
+    fleetopsOrderImportFilesExcelFake([[
+        ['name' => 'Import Stop', 'street1' => 'Import Rd 1', 'city' => 'Singapore', 'items' => 'Box A|Box B'],
+        // populated, but with nothing that resolves to an address — the row is
+        // skipped rather than producing a place or its items
+        ['items' => 'Orphan Box'],
+        [],
+    ]]);
+
+    $response = (new OrderController())->importFromFiles(fleetopsOrderImportFilesRequest([
+        'files' => ['11111111-1111-4111-8111-111111111111'],
+    ]));
+
+    $data = $response->getData(true);
+    expect($data['places'])->toHaveCount(1)
+        ->and($data['entities'])->toHaveCount(2)
+        ->and($data['entities'][0]['name'])->toBe('Box A')
+        ->and(collect($data['entities'])->pluck('name')->all())->not->toContain('Orphan Box');
+});
+
+test('invalid file types and unreadable spreadsheets return errors', function () {
+    $connection = fleetopsOrderImportFilesBoot();
+    $connection->table('files')->insert([
+        ['uuid' => '11111111-1111-4111-8111-111111111111', 'public_id' => 'file_ordimport2', 'company_uuid' => 'company-1', 'path' => 'uploads/orders.pdf', 'disk' => 'local'],
+        ['uuid' => '22222222-2222-4222-8222-222222222222', 'public_id' => 'file_ordimport3', 'company_uuid' => 'company-1', 'path' => 'uploads/orders.csv', 'disk' => 'local'],
+    ]);
+
+    $controller = new OrderController();
+
+    fleetopsOrderImportFilesExcelFake([]);
+    $invalidType = $controller->importFromFiles(fleetopsOrderImportFilesRequest([
+        'files' => ['11111111-1111-4111-8111-111111111111'],
+    ]));
+    expect($invalidType->getStatusCode())->toBeGreaterThanOrEqual(400);
+
+    fleetopsOrderImportFilesExcelFake([], true);
+    $unreadable = $controller->importFromFiles(fleetopsOrderImportFilesRequest([
+        'files' => ['22222222-2222-4222-8222-222222222222'],
+    ]));
+    expect($unreadable->getStatusCode())->toBeGreaterThanOrEqual(400);
+});

package/server/tests/Feature/Http/Internal/OrderControllerUpstreamNotFoundTest.php

@@ -0,0 +1,80 @@
+<?php
+
+use Fleetbase\FleetOps\Http\Controllers\Internal\v1\OrderController;
+use Illuminate\Http\Request;
+
+/**
+ * Covers the not-found branch of Internal\v1\OrderController::nextActivity().
+ *
+ * ---------------------------------------------------------------------------
+ * THIS FILE IS EXPECTED TO FAIL until fleetbase/core-api 1.6.55 is released and
+ * pulled into server_vendor. Do not "fix" it by weakening the assertion.
+ * ---------------------------------------------------------------------------
+ *
+ * The controller wraps `Order::findByIdOrFail($id)` in a
+ * `catch (ModelNotFoundException)` that returns 'No order found.'. Today that
+ * catch never fires: core-api's Model::findByIdOrFail() calls a
+ * getModelNotFoundException() method that does not exist on Eloquent's builder,
+ * so a missing order raises BadMethodCallException, escapes the catch, and
+ * surfaces as a 500 instead of the intended error response.
+ *
+ * core-api#231 (branch dev-v1.6.55) replaces that with
+ * `throw (new ModelNotFoundException())->setModel(static::class, [$identifier]);`
+ * which makes this branch live. The assertion below states the post-fix
+ * contract deliberately — asserting today's BadMethodCallException would
+ * codify the defect instead of the intent.
+ *
+ * If CI must be green before that release lands, neutralise this file with a
+ * single `->skip('pending fleetbase/core-api 1.6.55')` on the test below rather
+ * than changing what it asserts.
+ */
+function fleetopsUpstreamNotFoundBoot(): Illuminate\Database\SQLiteConnection
+{
+    $connection = new Illuminate\Database\SQLiteConnection(new PDO('sqlite::memory:'));
+    $resolver   = new Illuminate\Database\ConnectionResolver(['default' => $connection, 'mysql' => $connection]);
+    $resolver->setDefaultConnection('mysql');
+    Illuminate\Database\Eloquent\Model::setConnectionResolver($resolver);
+    app()->instance('db', new class($connection) {
+        public function __construct(public $c)
+        {
+        }
+
+        public function connection($name = null)
+        {
+            return $this->c;
+        }
+
+        public function __call($method, $arguments)
+        {
+            return $this->c->{$method}(...$arguments);
+        }
+    });
+    Illuminate\Support\Facades\DB::clearResolvedInstance('db');
+
+    $connection->getSchemaBuilder()->create('orders', function ($blueprint) {
+        $blueprint->increments('id');
+        foreach (['uuid', 'public_id', 'company_uuid', 'payload_uuid', 'order_config_uuid', 'status', 'type', '_key'] as $column) {
+            $blueprint->string($column)->nullable();
+        }
+        $blueprint->timestamps();
+        $blueprint->timestamp('deleted_at')->nullable();
+    });
+
+    session(['company' => 'company-upstream-1']);
+
+    return $connection;
+}
+
+test('next activity reports a missing order instead of failing the request', function () {
+    fleetopsUpstreamNotFoundBoot();
+
+    // No order with this id exists, so findByIdOrFail must raise a
+    // ModelNotFoundException that the controller catches and turns into an
+    // error response — rather than an exception escaping as a 500
+    $response = (new OrderController())->nextActivity(
+        'order_does_not_exist',
+        Request::create('/int/v1/orders/order_does_not_exist/next-activity', 'GET')
+    );
+
+    expect($response->getData(true))->toBe(['error' => 'No order found.']);
+});

package/server/tests/Feature/Http/Internal/PaymentControllerPaymentsTest.php

@@ -0,0 +1,154 @@
+<?php
+
+use Fleetbase\FleetOps\Http\Controllers\Internal\v1\PaymentController;
+use Illuminate\Database\ConnectionResolver;
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Model as EloquentModel;
+use Illuminate\Database\SQLiteConnection;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+
+/**
+ * Covers the internal PaymentController received-payments listing and the real
+ * bodies of its protected helper methods. The payments query executes against
+ * an in-memory SQLite fixture including the serviceQuote/order whereHas
+ * scoping, eager loads, sorting, pagination, and per-currency totals.
+ */
+class FleetOpsInternalPaymentProbe extends PaymentController
+{
+    public function callProtected(string $method, array $arguments = []): mixed
+    {
+        $reflection = new ReflectionMethod(PaymentController::class, $method);
+        $reflection->setAccessible(true);
+
+        return $reflection->invoke($this, ...$arguments);
+    }
+}
+
+function fleetopsInternalPaymentBoot(): SQLiteConnection
+{
+    $connection = new SQLiteConnection(new PDO('sqlite::memory:'));
+    $resolver   = new ConnectionResolver(['default' => $connection, 'mysql' => $connection]);
+    $resolver->setDefaultConnection('mysql');
+    EloquentModel::setConnectionResolver($resolver);
+    app()->instance('db', new class($connection) {
+        public function __construct(public SQLiteConnection $c)
+        {
+        }
+
+        public function connection($name = null): SQLiteConnection
+        {
+            return $this->c;
+        }
+
+        public function __call($method, $arguments)
+        {
+            return $this->c->{$method}(...$arguments);
+        }
+    });
+    Illuminate\Support\Facades\DB::clearResolvedInstance('db');
+
+    // The fast-paginate package is not installed in the test harness; a plain
+    // limited collection satisfies the resource collection contract.
+    if (!Builder::hasGlobalMacro('fastPaginate')) {
+        Builder::macro('fastPaginate', function ($limit = 15) {
+            return $this->limit($limit)->get();
+        });
+    }
+
+    $schema = $connection->getSchemaBuilder();
+    $tables = [
+        'purchase_rates' => ['uuid', 'public_id', 'company_uuid', 'customer_uuid', 'customer_type', 'service_quote_uuid', 'transaction_uuid', 'status', 'meta'],
+        'service_quotes' => ['uuid', 'public_id', 'company_uuid', 'request_id', 'service_rate_uuid', 'amount', 'currency', 'meta', 'expired_at'],
+        'orders'         => ['uuid', 'public_id', 'company_uuid', 'purchase_rate_uuid', 'status'],
+        'transactions'   => ['uuid', 'public_id', 'company_uuid'],
+    ];
+    foreach ($tables as $table => $columns) {
+        $schema->create($table, function ($blueprint) use ($columns) {
+            $blueprint->increments('id');
+            foreach ($columns as $column) {
+                $blueprint->string($column)->nullable();
+            }
+            $blueprint->timestamps();
+            $blueprint->timestamp('deleted_at')->nullable();
+        });
+    }
+
+    session(['company' => 'company-1']);
+
+    return $connection;
+}
+
+function fleetopsInternalPaymentSeed(SQLiteConnection $connection, string $suffix, string $currency, int $amount): void
+{
+    $connection->table('service_quotes')->insert([
+        'uuid'         => 'sq-' . $suffix,
+        'public_id'    => 'service_quote_' . $suffix,
+        'amount'       => $amount,
+        'currency'     => $currency,
+        'company_uuid' => 'company-1',
+    ]);
+    $connection->table('purchase_rates')->insert([
+        'uuid'               => 'pr-' . $suffix,
+        'public_id'          => 'purchase_rate_' . $suffix,
+        'company_uuid'       => 'company-1',
+        'service_quote_uuid' => 'sq-' . $suffix,
+        'status'             => 'created',
+        'created_at'         => '2026-01-01 00:00:00',
+    ]);
+    $connection->table('orders')->insert([
+        'uuid'               => 'order-' . $suffix,
+        'public_id'          => 'order_' . $suffix,
+        'company_uuid'       => 'company-1',
+        'purchase_rate_uuid' => 'pr-' . $suffix,
+    ]);
+}
+
+test('received payments endpoint lists company payments with per-currency totals', function () {
+    $connection = fleetopsInternalPaymentBoot();
+    fleetopsInternalPaymentSeed($connection, 'a', 'USD', 100);
+    fleetopsInternalPaymentSeed($connection, 'b', 'USD', 50);
+    fleetopsInternalPaymentSeed($connection, 'c', 'SGD', 75);
+
+    $result = (new PaymentController())->getCompanyReceivedPayments(Request::create('/x', 'GET'));
+
+    expect($result)->toBeInstanceOf(Fleetbase\Http\Resources\FleetbaseResourceCollection::class)
+        ->and($result->collection->count())->toBe(3)
+        ->and($result->additional['amount_totals'])->toBe(['USD' => 150, 'SGD' => 75]);
+});
+
+test('received payments endpoint excludes purchase rates without a live order', function () {
+    $connection = fleetopsInternalPaymentBoot();
+    fleetopsInternalPaymentSeed($connection, 'kept', 'USD', 100);
+
+    // Purchase rate whose order is soft-deleted must be filtered out
+    $connection->table('service_quotes')->insert(['uuid' => 'sq-x', 'public_id' => 'service_quote_x', 'amount' => 999, 'currency' => 'USD', 'company_uuid' => 'company-1']);
+    $connection->table('purchase_rates')->insert(['uuid' => 'pr-x', 'public_id' => 'purchase_rate_x', 'company_uuid' => 'company-1', 'service_quote_uuid' => 'sq-x', 'status' => 'created']);
+    $connection->table('orders')->insert(['uuid' => 'order-x', 'public_id' => 'order_x', 'company_uuid' => 'company-1', 'purchase_rate_uuid' => 'pr-x', 'deleted_at' => '2026-01-01 00:00:00']);
+
+    $result = (new PaymentController())->getCompanyReceivedPayments(Request::create('/x', 'GET', ['limit' => 10]));
+
+    expect($result->collection->count())->toBe(1)
+        ->and($result->additional['amount_totals'])->toBe(['USD' => 100]);
+});
+
+test('json and error response helpers build the expected responses', function () {
+    $probe = new FleetOpsInternalPaymentProbe();
+
+    $json = $probe->callProtected('jsonResponse', [['ok' => true]]);
+    expect($json)->toBeInstanceOf(JsonResponse::class)
+        ->and($json->getData(true))->toBe(['ok' => true]);
+
+    $error = $probe->callProtected('errorResponse', ['payment failed']);
+    expect($error->getData(true))->toBe(['error' => 'payment failed']);
+});
+
+test('company and stripe client helpers delegate to their integration seams', function () {
+    $probe = new FleetOpsInternalPaymentProbe();
+
+    // Auth::getCompany requires a full session/auth boot and the Stripe SDK is
+    // not installed in the harness; both helpers still execute their real
+    // delegation bodies, which is the covered contract here.
+    expect(fn () => $probe->callProtected('getCompany'))->toThrow(Error::class)
+        ->and(fn () => $probe->callProtected('stripeClient'))->toThrow(Error::class);
+});

package/server/tests/Feature/Http/Internal/PlaceControllerTest.php

@@ -0,0 +1,252 @@
+<?php
+
+use Fleetbase\FleetOps\Exports\PlaceExport;
+use Fleetbase\FleetOps\Http\Controllers\Internal\v1\PlaceController;
+use Fleetbase\FleetOps\Models\Place;
+use Fleetbase\Http\Requests\ExportRequest;
+use Fleetbase\Http\Requests\ImportRequest;
+use Illuminate\Database\ConnectionResolver;
+use Illuminate\Database\Eloquent\Builder as EloquentBuilder;
+use Illuminate\Database\Eloquent\Model as EloquentModel;
+use Illuminate\Database\SQLiteConnection;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Collection;
+
+/**
+ * Covers the internal PlaceController geocode/export/import endpoints and the
+ * real bodies of its protected helper methods. The existing contracts test
+ * overrides every helper on its probe, so the genuine implementations
+ * (Place::query(), PlaceSearch::search/geocode, Place::getAvatarOptions and
+ * the custom-field sync delegation) were never executed.
+ */
+if (!class_exists('Fleetbase\Http\Requests\ExportRequest', false)) {
+    eval('namespace Fleetbase\Http\Requests; class ExportRequest extends \Illuminate\Http\Request {}');
+}
+
+if (!class_exists('Fleetbase\Http\Requests\ImportRequest', false)) {
+    eval('namespace Fleetbase\Http\Requests; class ImportRequest extends \Illuminate\Http\Request {}');
+}
+
+if (!Request::hasMacro('searchQuery')) {
+    Request::macro('searchQuery', fn () => $this->input('query', $this->input('search', $this->input('searchQuery'))));
+}
+
+if (!Request::hasMacro('resolveFilesFromIds')) {
+    Request::macro('resolveFilesFromIds', fn () => FleetOpsInternalPlaceEndpointsState::$files);
+}
+
+class FleetOpsInternalPlaceEndpointsState
+{
+    public static array $files = [];
+}
+
+class FleetOpsInternalPlaceEndpointsExcelFake
+{
+    public array $downloads    = [];
+    public array $imports      = [];
+    public bool $importFails   = false;
+
+    public function download($export, string $fileName): string
+    {
+        $this->downloads[] = [$export, $fileName];
+
+        return 'downloaded:' . $fileName;
+    }
+
+    public function import($import, $path, $disk = null): bool
+    {
+        if ($this->importFails) {
+            throw new RuntimeException('corrupt file');
+        }
+
+        $this->imports[] = [$import, $path, $disk];
+        $import->imported++;
+
+        return true;
+    }
+}
+
+class FleetOpsInternalPlaceEndpointsPlaceFake extends Place
+{
+    protected $guarded         = [];
+    public $exists             = true;
+    public array $syncedValues = [];
+
+    public function syncCustomFieldValues(array $payload, array $options = []): array
+    {
+        $this->syncedValues[] = $payload;
+
+        return $payload;
+    }
+}
+
+class FleetOpsInternalPlaceEndpointsProbe extends PlaceController
+{
+    public function callProtected(string $method, array $arguments = []): mixed
+    {
+        $reflection = new ReflectionMethod(PlaceController::class, $method);
+        $reflection->setAccessible(true);
+
+        return $reflection->invoke($this, ...$arguments);
+    }
+}
+
+function fleetopsInternalPlaceEndpointsBoot(): SQLiteConnection
+{
+    $connection = new SQLiteConnection(new PDO('sqlite::memory:'));
+    $resolver   = new ConnectionResolver(['default' => $connection, 'mysql' => $connection]);
+    $resolver->setDefaultConnection('mysql');
+    EloquentModel::setConnectionResolver($resolver);
+    app()->instance('db', new class($connection) {
+        public function __construct(public SQLiteConnection $c)
+        {
+        }
+
+        public function connection($name = null): SQLiteConnection
+        {
+            return $this->c;
+        }
+
+        public function __call($method, $arguments)
+        {
+            return $this->c->{$method}(...$arguments);
+        }
+    });
+
+    $schema = $connection->getSchemaBuilder();
+    $schema->create('places', function ($table) {
+        $table->increments('id');
+        $table->string('uuid')->nullable();
+        $table->string('public_id')->nullable();
+        $table->string('company_uuid')->nullable();
+        $table->string('name')->nullable();
+        $table->string('street1')->nullable();
+        $table->string('street2')->nullable();
+        $table->string('city')->nullable();
+        $table->string('province')->nullable();
+        $table->string('postal_code')->nullable();
+        $table->string('location')->nullable();
+        $table->timestamp('created_at')->nullable();
+        $table->timestamp('deleted_at')->nullable();
+    });
+    $schema->create('files', function ($table) {
+        $table->increments('id');
+        $table->string('uuid')->nullable();
+        $table->string('type')->nullable();
+        $table->string('original_filename')->nullable();
+        $table->timestamp('deleted_at')->nullable();
+    });
+
+    return $connection;
+}
+
+function fleetopsInternalPlaceEndpointsExcel(): FleetOpsInternalPlaceEndpointsExcelFake
+{
+    $fake = new FleetOpsInternalPlaceEndpointsExcelFake();
+    app()->instance('excel', $fake);
+    Maatwebsite\Excel\Facades\Excel::clearResolvedInstance('excel');
+
+    return $fake;
+}
+
+test('geocode endpoint returns empty results without a query or coordinates', function () {
+    $request  = ExportRequest::create('/int/v1/places/geocode', 'GET');
+    $response = (new PlaceController())->geocode($request);
+
+    expect($response)->toBeInstanceOf(JsonResponse::class)
+        ->and($response->headers->get('Cache-Control'))->toContain('no-cache')
+        ->and($response->getData(true))->toBe([]);
+});
+
+test('export endpoint streams a place export download with a dated filename', function () {
+    $excel = fleetopsInternalPlaceEndpointsExcel();
+
+    $request  = ExportRequest::create('/int/v1/places/export', 'POST', ['format' => 'csv', 'selections' => ['place-1']]);
+    $response = (new PlaceController())->export($request);
+
+    expect($response)->toStartWith('downloaded:places-')
+        ->and($response)->toEndWith('.csv')
+        ->and($excel->downloads)->toHaveCount(1)
+        ->and($excel->downloads[0][0])->toBeInstanceOf(PlaceExport::class);
+});
+
+test('import endpoint imports each resolved file and reports the count', function () {
+    $excel                                      = fleetopsInternalPlaceEndpointsExcel();
+    FleetOpsInternalPlaceEndpointsState::$files = [
+        (object) ['path' => 'uploads/places-a.xlsx'],
+        (object) ['path' => 'uploads/places-b.xlsx'],
+    ];
+
+    $request  = ImportRequest::create('/int/v1/places/import', 'POST', ['disk' => 'local']);
+    $response = (new PlaceController())->import($request);
+
+    expect($response)->toBeInstanceOf(JsonResponse::class)
+        ->and($response->getData(true))->toBe(['status' => 'ok', 'message' => 'Import completed', 'imported' => 2])
+        ->and($excel->imports)->toHaveCount(2);
+});
+
+test('import endpoint returns an error response for unreadable files', function () {
+    $excel                                      = fleetopsInternalPlaceEndpointsExcel();
+    $excel->importFails                         = true;
+    FleetOpsInternalPlaceEndpointsState::$files = [(object) ['path' => 'uploads/corrupt.xlsx']];
+
+    $request  = ImportRequest::create('/int/v1/places/import', 'POST', []);
+    $response = (new PlaceController())->import($request);
+
+    expect($response->getData(true))->toBe(['error' => 'Invalid file, unable to proccess.']);
+});
+
+test('place query helper builds an eloquent builder for places', function () {
+    fleetopsInternalPlaceEndpointsBoot();
+
+    $query = (new FleetOpsInternalPlaceEndpointsProbe())->callProtected('newPlaceQuery');
+
+    expect($query)->toBeInstanceOf(EloquentBuilder::class)
+        ->and($query->getModel())->toBeInstanceOf(Place::class);
+});
+
+test('search places helper runs the place search pipeline against the database', function () {
+    $connection = fleetopsInternalPlaceEndpointsBoot();
+    $connection->table('places')->insert(['uuid' => 'place-1', 'name' => 'Central Depot', 'company_uuid' => 'company-1']);
+
+    $results = (new FleetOpsInternalPlaceEndpointsProbe())->callProtected('searchPlaces', [
+        Place::query(),
+        'Depot',
+        ['limit' => 5, 'no_query_order' => 'name_desc'],
+    ]);
+
+    expect($results)->toBeInstanceOf(Collection::class)
+        ->and($results->count())->toBe(1)
+        ->and($results->first()->name)->toBe('Central Depot');
+});
+
+test('geocode places helper returns an empty collection without inputs', function () {
+    $results = (new FleetOpsInternalPlaceEndpointsProbe())->callProtected('geocodePlaces', [null, null, null]);
+
+    expect($results)->toBeInstanceOf(Collection::class)
+        ->and($results->isEmpty())->toBeTrue();
+});
+
+test('avatar options helper merges custom avatars with fleetbase defaults', function () {
+    $connection = fleetopsInternalPlaceEndpointsBoot();
+    $connection->table('files')->insert([
+        'uuid'              => 'file-1',
+        'type'              => 'place-avatar',
+        'original_filename' => 'depot.png',
+    ]);
+
+    $options = (new FleetOpsInternalPlaceEndpointsProbe())->callProtected('avatarOptions');
+
+    expect($options)->toBeArray()
+        ->and($options)->toHaveKey('Custom: depot')
+        ->and($options)->toHaveKey('basic-building');
+});
+
+test('sync custom field values helper delegates to the place model', function () {
+    $place = new FleetOpsInternalPlaceEndpointsPlaceFake();
+
+    (new FleetOpsInternalPlaceEndpointsProbe())->callProtected('syncCustomFieldValues', [$place, ['priority' => 'high']]);
+
+    expect($place->syncedValues)->toBe([['priority' => 'high']]);
+});