Feature: Creating Shipping Carrier Contracts

CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.3.0] - 2026-07-12
+
+### Added
+- **Meilisearch product search**: pulled in `lunarphp/search` (Lunar's driver-agnostic search abstraction — `database`/`meilisearch`/`typesense` engines, selectable via Scout's own `SCOUT_DRIVER` config) and `lunarphp/meilisearch`, wiring Meilisearch in as the search engine for products.
+  - `Search\ProductIndexer` overrides Lunar's own indexer to strip HTML tags from string fields (e.g. `name_en`, `description_en`) before they reach the search index — Lunar's default indexer sends raw attribute HTML straight through, which pollutes relevance ranking and highlighting with markup.
+  - Meilisearch itself is treated as app-level infrastructure, not a `boboko-core` concern: the actual Meilisearch container, host port, and master key live in each consuming app's own `docker-compose.yml`/`.env` (e.g. `3dealer`), the same way Postgres and Valkey do — `boboko-core` only declares the PHP package dependency and the indexing code.
+
 ## [0.2.0] - 2026-07-10
 
 ### Added

composer.json

@@ -2,7 +2,7 @@
   "name": "boboko/core",
   "description": "Core module — authentication and shared panel behaviour",
   "type": "library",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "autoload": {
     "psr-4": {
       "Modules\\Core\\": "src/"
@@ -14,7 +14,9 @@
     "laravel/framework": "^12.0",
     "laravel/tinker": "^3.0",
     "symfony/yaml": "^7.0",
-    "lunarphp/table-rate-shipping": "^1.3"
+    "lunarphp/table-rate-shipping": "^1.3",
+    "lunarphp/search": "*",
+    "lunarphp/meilisearch": "*"
   },
   "require-dev": {
     "fakerphp/faker": "^1.23",

config/scout.php

@@ -0,0 +1,210 @@
+<?php
+
+return [
+
+    /*
+    |--------------------------------------------------------------------------
+    | Default Search Engine
+    |--------------------------------------------------------------------------
+    |
+    | This option controls the default search connection that gets used while
+    | using Laravel Scout. This connection is used when syncing all models
+    | to the search service. You should adjust this based on your needs.
+    |
+    | Supported: "algolia", "meilisearch", "typesense",
+    |            "database", "collection", "null"
+    |
+    */
+
+    'driver' => env('SCOUT_DRIVER', 'collection'),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Index Prefix
+    |--------------------------------------------------------------------------
+    |
+    | Here you may specify a prefix that will be applied to all search index
+    | names used by Scout. This prefix may be useful if you have multiple
+    | "tenants" or applications sharing the same search infrastructure.
+    |
+    */
+
+    'prefix' => env('SCOUT_PREFIX', ''),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Queue Data Syncing
+    |--------------------------------------------------------------------------
+    |
+    | This option allows you to control if the operations that sync your data
+    | with your search engines are queued. When this is set to "true" then
+    | all automatic data syncing will get queued for better performance.
+    |
+    */
+
+    'queue' => env('SCOUT_QUEUE', false),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Database Transactions
+    |--------------------------------------------------------------------------
+    |
+    | This configuration option determines if your data will only be synced
+    | with your search indexes after every open database transaction has
+    | been committed, thus preventing any discarded data from syncing.
+    |
+    */
+
+    'after_commit' => false,
+
+    /*
+    |--------------------------------------------------------------------------
+    | Chunk Sizes
+    |--------------------------------------------------------------------------
+    |
+    | These options allow you to control the maximum chunk size when you are
+    | mass importing data into the search engine. This allows you to fine
+    | tune each of these chunk sizes based on the power of the servers.
+    |
+    */
+
+    'chunk' => [
+        'searchable' => 500,
+        'unsearchable' => 500,
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Soft Deletes
+    |--------------------------------------------------------------------------
+    |
+    | This option allows to control whether to keep soft deleted records in
+    | the search indexes. Maintaining soft deleted records can be useful
+    | if your application still needs to search for the records later.
+    |
+    */
+
+    'soft_delete' => false,
+
+    /*
+    |--------------------------------------------------------------------------
+    | Identify User
+    |--------------------------------------------------------------------------
+    |
+    | This option allows you to control whether to notify the search engine
+    | of the user performing the search. This is sometimes useful if the
+    | engine supports any analytics based on this application's users.
+    |
+    | Supported engines: "algolia"
+    |
+    */
+
+    'identify' => env('SCOUT_IDENTIFY', false),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Algolia Configuration
+    |--------------------------------------------------------------------------
+    |
+    | Here you may configure your Algolia settings. Algolia is a cloud hosted
+    | search engine which works great with Scout out of the box. Just plug
+    | in your application ID and admin API key to get started searching.
+    |
+    */
+
+    'algolia' => [
+        'id' => env('ALGOLIA_APP_ID', ''),
+        'secret' => env('ALGOLIA_SECRET', ''),
+        'index-settings' => [
+            // 'users' => [
+            //     'searchableAttributes' => ['id', 'name', 'email'],
+            //     'attributesForFaceting'=> ['filterOnly(email)'],
+            // ],
+        ],
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Meilisearch Configuration
+    |--------------------------------------------------------------------------
+    |
+    | Here you may configure your Meilisearch settings. Meilisearch is an open
+    | source search engine with minimal configuration. Below, you can state
+    | the host and key information for your own Meilisearch installation.
+    |
+    | See: https://www.meilisearch.com/docs/learn/configuration/instance_options#all-instance-options
+    |
+    */
+
+    'meilisearch' => [
+        'host' => env('MEILISEARCH_HOST', 'http://localhost:7700'),
+        'key' => env('MEILISEARCH_KEY'),
+        'index-settings' => [
+            // 'users' => [
+            //     'filterableAttributes'=> ['id', 'name', 'email'],
+            // ],
+        ],
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Typesense Configuration
+    |--------------------------------------------------------------------------
+    |
+    | Here you may configure your Typesense settings. Typesense is an open
+    | source search engine using minimal configuration. Below, you will
+    | state the host, key, and schema configuration for the instance.
+    |
+    */
+
+    'typesense' => [
+        'client-settings' => [
+            'api_key' => env('TYPESENSE_API_KEY', 'xyz'),
+            'nodes' => [
+                [
+                    'host' => env('TYPESENSE_HOST', 'localhost'),
+                    'port' => env('TYPESENSE_PORT', '8108'),
+                    'path' => env('TYPESENSE_PATH', ''),
+                    'protocol' => env('TYPESENSE_PROTOCOL', 'http'),
+                ],
+            ],
+            'nearest_node' => [
+                'host' => env('TYPESENSE_HOST', 'localhost'),
+                'port' => env('TYPESENSE_PORT', '8108'),
+                'path' => env('TYPESENSE_PATH', ''),
+                'protocol' => env('TYPESENSE_PROTOCOL', 'http'),
+            ],
+            'connection_timeout_seconds' => env('TYPESENSE_CONNECTION_TIMEOUT_SECONDS', 2),
+            'healthcheck_interval_seconds' => env('TYPESENSE_HEALTHCHECK_INTERVAL_SECONDS', 30),
+            'num_retries' => env('TYPESENSE_NUM_RETRIES', 3),
+            'retry_interval_seconds' => env('TYPESENSE_RETRY_INTERVAL_SECONDS', 1),
+        ],
+        // 'max_total_results' => env('TYPESENSE_MAX_TOTAL_RESULTS', 1000),
+        'model-settings' => [
+            // User::class => [
+            //     'collection-schema' => [
+            //         'fields' => [
+            //             [
+            //                 'name' => 'id',
+            //                 'type' => 'string',
+            //             ],
+            //             [
+            //                 'name' => 'name',
+            //                 'type' => 'string',
+            //             ],
+            //             [
+            //                 'name' => 'created_at',
+            //                 'type' => 'int64',
+            //             ],
+            //         ],
+            //         'default_sorting_field' => 'created_at',
+            //     ],
+            //     'search-parameters' => [
+            //         'query_by' => 'name'
+            //     ],
+            // ],
+        ],
+        'import_action' => env('TYPESENSE_IMPORT_ACTION', 'upsert'),
+    ],
+
+];

database/migrations/2026_07_16_000001_create_shipments_table.php

@@ -0,0 +1,29 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('shipments', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('order_id')->constrained(config('lunar.database.table_prefix').'orders');
+            $table->string('carrier');
+            $table->string('tracking_reference')->unique();
+            $table->string('parent_reference')->nullable();
+            $table->timestamp('label_printed_at')->nullable();
+            $table->string('manifest_reference')->nullable();
+            $table->timestamp('cancelled_at')->nullable();
+            $table->json('meta')->nullable();
+            $table->timestamps();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('shipments');
+    }
+};

src/Providers/CoreServiceProvider.php

@@ -26,6 +26,7 @@ class CoreServiceProvider extends ServiceProvider
 
         $this->publishes([
             __DIR__ . '/../../config/core.php' => config_path('core.php'),
+            __DIR__ . '/../../config/scout.php' => config_path('scout.php'),
         ], 'core-config');
 
         $this->publishes([

src/Search/ProductIndexer.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace Modules\Core\Search;
+
+use Illuminate\Database\Eloquent\Model;
+use Lunar\Search\ProductIndexer as BaseProductIndexer;
+
+/**
+ * Lunar's own indexer puts raw attribute HTML (e.g. name_en, description_en) into
+ * the search index, which pollutes relevance ranking and highlighting with markup.
+ * Strip tags from string fields before they reach Meilisearch.
+ */
+class ProductIndexer extends BaseProductIndexer
+{
+    public function toSearchableArray(Model $model): array
+    {
+        $data = parent::toSearchableArray($model);
+
+        foreach ($data as $key => $value) {
+            if (is_string($value)) {
+                $data[$key] = trim(strip_tags($value));
+            }
+        }
+
+        return $data;
+    }
+}

src/Shipping/Contracts/CarrierFulfillmentInterface.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace Modules\Core\Shipping\Contracts;
+
+use Lunar\Models\Order;
+use Modules\Core\Shipping\Models\Shipment;
+
+interface CarrierFulfillmentInterface
+{
+    /**
+     * Create a shipment with the carrier for the given order.
+     */
+    public function createShipment(Order $order, array $overrides = []): Shipment;
+
+    /**
+     * Fetch the printable label for a shipment (raw file bytes).
+     */
+    public function printLabel(Shipment $shipment): string;
+
+    /**
+     * Cancel a shipment with the carrier.
+     */
+    public function cancelShipment(Shipment $shipment): void;
+}

src/Shipping/Contracts/SupportsLivePricing.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace Modules\Core\Shipping\Contracts;
+
+/**
+ * Marker for a Lunar\Shipping\Interfaces\ShippingRateInterface driver that
+ * calculates its price from a live carrier API rather than the manually
+ * configured ShippingRate price/price-breaks. Admin UI uses this to hide
+ * the manual pricing fields for such drivers — carriers without a pricing
+ * API simply don't implement it, and manual pricing remains required.
+ */
+interface SupportsLivePricing {}

src/Shipping/Contracts/SupportsManifestBatching.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace Modules\Core\Shipping\Contracts;
+
+use Illuminate\Support\Collection;
+use Modules\Core\Shipping\DataTransferObjects\ManifestResult;
+
+/**
+ * Optional capability for carriers that batch shipments into a manifest
+ * before courier pickup (e.g. ACS's end-of-day pickup list). Carriers
+ * without this concept simply don't implement it.
+ */
+interface SupportsManifestBatching
+{
+    /**
+     * Shipments created but not yet included in an issued manifest.
+     */
+    public function pendingForManifest(): Collection;
+
+    /**
+     * Finalize the given shipments into a manifest with the carrier.
+     */
+    public function issueManifest(Collection $shipments): ManifestResult;
+}

src/Shipping/Models/Shipment.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace Modules\Core\Shipping\Models;
+
+use Illuminate\Database\Eloquent\Casts\AsArrayObject;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Lunar\Models\Order;
+
+class Shipment extends Model
+{
+    protected $guarded = [];
+
+    protected $casts = [
+        'meta' => AsArrayObject::class,
+        'label_printed_at' => 'datetime',
+        'cancelled_at' => 'datetime',
+    ];
+
+    public function order(): BelongsTo
+    {
+        return $this->belongsTo(Order::class);
+    }
+}