@use-the-fork/spindle 0.0.2 → 0.2.0

package/build/Assets/Blueprints/skills/{asd-ste100 → ref-asd-ste100}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: asd-ste100
+name: ref-asd-ste100
 description:  "Rewrites ambiguous English into ASD-STE100 style — one meaning per word, active voice, simple tense, short sentences. Use when agent output is hard to parse; triggers: simplify this, STE100 rewrite."
 user-invocable: false
 metadata:

package/build/Assets/Blueprints/skills/ref-php-laravel-saloon-api-integrations/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: ref-php-laravel-saloon-api-integrations
+description: "Use when building or testing Laravel API integrations with Saloon: connectors, requests, responses, failures, mocks, pools, or DTOs."
+metadata:
+  spindle:
+    version: 1.0.0
+---
+
+# Working with Saloon
+
+This skill covers the latest Saloon release and its Laravel plugin.
+
+## Integration boundaries
+
+A connector owns the base URL, shared authentication, default headers, and client configuration.
+A request owns its method, endpoint, and request-specific query, headers, and body.
+The connector sends the request.
+
+## Topic lookup
+
+Before writing code, read each reference whose condition matches the task.
+For combined tasks, read all matching references.
+
+| When working on                                                                     | Read                                                         |
+| ----------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| Base URL, shared authentication, default headers, timeouts, or client configuration | [Connectors](references/connectors.md)                       |
+| HTTP method, endpoint, inputs, query parameters, headers, or JSON body              | [Requests](references/requests.md)                           |
+| `send()` or `sendAsync()`, including promise handling                               | [Sending requests](references/sending-requests.md)           |
+| Status, headers, body parsing, response helpers, or custom response classes         | [Responses](references/responses.md)                         |
+| HTTP or connection failures, throwing, or custom failure detection and exceptions   | [Handling failures](references/handling-failures.md)         |
+| Tests, request assertions, mocks, or recorded fixtures                              | [Testing](references/testing.md)                             |
+| Concurrent batches, rate limits, keyed results, or pool handlers                    | [Concurrency and pools](references/concurrency-and-pools.md) |
+| Typed response mapping or DTO-driven request bodies                                 | [Data transfer objects](references/data-transfer-objects.md) |
+
+## Sources
+
+Use the [official documentation](https://docs.saloon.dev/) for API details beyond these references.
+Use the [latest release](https://github.com/saloonphp/saloon/releases/latest) for current changes.

package/build/Assets/Blueprints/skills/ref-php-laravel-saloon-api-integrations/references/concurrency-and-pools.md

@@ -0,0 +1,73 @@
+# Concurrency & Pools
+
+A pool sends independent requests concurrently through one connector.
+Use pools for batches such as fetching records by ID.
+Concurrency requires `GuzzleSender` (the default) or `HttpSender`.
+
+## Basic pool
+
+```php
+use Saloon\Exceptions\Request\FatalRequestException;
+use Saloon\Exceptions\Request\RequestException;
+use Saloon\Http\Response;
+
+$products = [];
+$failures = [];
+
+$pool = $connector->pool(
+    requests: function () use ($ids): Generator {
+        foreach ($ids as $id) {
+            yield $id => new GetProductRequest($id);
+        }
+    },
+    concurrency: 10,
+    responseHandler: function (Response $response, int|string $key) use (&$products) {
+        $products[$key] = $response->dtoOrFail();
+    },
+    exceptionHandler: function (FatalRequestException|RequestException $exception, int|string $key) use (&$failures) {
+        $failures[$key] = $exception instanceof RequestException
+            ? $exception->getResponse()->status()
+            : $exception->getMessage();
+    },
+);
+
+$pool->send()->wait();
+```
+
+`send()` returns a promise; call `wait()` before reading the results.
+
+## Requests
+
+Provide any of the following as the first argument or with `setRequests()`:
+
+- An array of `Request` or `PendingRequest` objects.
+- A generator, to keep memory low for large batches.
+- A closure or invokable class returning an array or generator, to run setup just before sending.
+
+Keys from arrays or generators reach both handlers, so key by ID to match results. Responses complete in any order; never rely on input order.
+
+## Concurrency
+
+The default is 5 requests in flight.
+Use the `concurrency` argument or `$pool->setConcurrency(10)` to change it. Both also accept a callable.
+Choose a value that respects the API's rate limits. A pool does not throttle requests over time.
+
+## Handlers
+
+- `responseHandler` / `withResponseHandler()`: receives each **successful** `Response`.
+- `exceptionHandler` / `withExceptionHandler()`: receives `RequestException` for 4xx/5xx responses and `FatalRequestException` for connection failures. HTTP failures always arrive here, even without `throw()` or `AlwaysThrowOnErrors`.
+
+Each pool holds one handler of each kind.
+For failure classification and custom exceptions, read [Handling failures](handling-failures.md).
+
+## Testing pools
+
+Use `MockClient` with pools. Mocked HTTP failures reach the exception handler.
+For offline setup and request assertions, read [Testing](testing.md).
+
+```php
+$connector->withMockClient(new MockClient([
+    MockResponse::make(['id' => 1, 'name' => 'Widget', 'price_cents' => 999], 200),
+    MockResponse::make(['message' => 'Not found'], 404),
+]));
+```

package/build/Assets/Blueprints/skills/ref-php-laravel-saloon-api-integrations/references/connectors.md

@@ -0,0 +1,99 @@
+# Connectors
+
+A connector represents one external API. Create one connector per integration under `app/Http/Integrations/<Api>/`.
+
+## Minimal connector
+
+Extend `Saloon\Http\Connector` and implement `resolveBaseUrl()`.
+
+```php
+use Saloon\Http\Connector;
+
+class InventoryConnector extends Connector
+{
+    public function resolveBaseUrl(): string
+    {
+        return 'https://inventory.example.com/api/v1';
+    }
+}
+```
+
+With the Laravel plugin installed, `php artisan saloon:connector` scaffolds one.
+
+## Constructor arguments and authentication
+
+Pass instance-specific values through the constructor. Put shared bearer authentication in `defaultAuth()`.
+
+```php
+use Saloon\Contracts\Authenticator;
+use Saloon\Http\Auth\TokenAuthenticator;
+use Saloon\Http\Connector;
+
+class InventoryConnector extends Connector
+{
+    public function __construct(
+        protected readonly string $baseUrl,
+        protected readonly string $token,
+    ) {}
+
+    public function resolveBaseUrl(): string
+    {
+        return $this->baseUrl;
+    }
+
+    protected function defaultAuth(): ?Authenticator
+    {
+        return new TokenAuthenticator($this->token);
+    }
+}
+
+$connector = new InventoryConnector(config('services.inventory.url'), config('services.inventory.token'));
+```
+
+`TokenAuthenticator` sends `Authorization: Bearer <token>`.
+Load credentials from configuration or secrets. Never hard-code production credentials.
+
+## Default headers
+
+Override `defaultHeaders()` for headers every request needs. Request headers are merged on top.
+
+```php
+protected function defaultHeaders(): array
+{
+    return [
+        'Accept' => 'application/json',
+        'Content-Type' => 'application/json',
+    ];
+}
+```
+
+Change headers on an instance with `$connector->headers()->add('X-Tenant', 'acme');`.
+
+## Timeouts
+
+Defaults are a 10-second connection timeout and a 30-second request timeout.
+Use `HasTimeout` on a connector for shared timeouts, or on a request for endpoint-specific timeouts.
+
+```php
+use Saloon\Traits\Plugins\HasTimeout;
+
+class InventoryConnector extends Connector
+{
+    use HasTimeout;
+
+    protected int $connectTimeout = 60;
+
+    protected int $requestTimeout = 120;
+}
+```
+
+## HTTP client config
+
+The default sender is Guzzle. Pass Guzzle request options through `defaultConfig()` or `$connector->config()->add(...)`.
+
+```php
+public function defaultConfig(): array
+{
+    return ['verify' => true];
+}
+```

package/build/Assets/Blueprints/skills/ref-php-laravel-saloon-api-integrations/references/data-transfer-objects.md

@@ -0,0 +1,104 @@
+# Data Transfer Objects
+
+A data transfer object (DTO) gives typed fields to API data.
+Define response mapping on the request, or on the connector when all requests share that mapping.
+Retrieve the DTO from the response.
+
+## Define the DTO and mapping
+
+```php
+final class Product
+{
+    public function __construct(
+        public readonly int $id,
+        public readonly string $name,
+        public readonly int $priceCents,
+    ) {}
+}
+```
+
+```php
+use Saloon\Http\Request;
+use Saloon\Http\Response;
+
+class GetProductRequest extends Request
+{
+    // method, constructor, and endpoint ...
+
+    public function createDtoFromResponse(Response $response): Product
+    {
+        $data = $response->json();
+
+        return new Product(
+            id: $data['id'],
+            name: $data['name'],
+            priceCents: $data['price_cents'],
+        );
+    }
+}
+```
+
+## Retrieve the DTO
+
+```php
+$response = $connector->send(new GetProductRequest(42));
+
+$product = $response->dtoOrFail(); // throws LogicException if the response failed
+$product = $response->dto();       // always maps, even for failed responses
+```
+
+Use `dtoOrFail()` for success-only DTOs. It prevents mapping an error body into `Product`.
+Use `dto()` only when the mapping handles error payloads.
+"Failed" follows `hasRequestFailed()`; see [Handling failures](handling-failures.md).
+
+`dto()` returns `mixed`. For static analysis, annotate it with `/** @var Product $product */`, or call the typed method directly: `$request->createDtoFromResponse($response)`.
+
+## DTOs in requests
+
+Accept a DTO in a request constructor to build the request body.
+
+```php
+use Saloon\Contracts\Body\HasBody;
+use Saloon\Enums\Method;
+use Saloon\Traits\Body\HasJsonBody;
+
+class UpdateProductRequest extends Request implements HasBody
+{
+    use HasJsonBody;
+
+    protected Method $method = Method::PUT;
+
+    public function __construct(protected readonly Product $product) {}
+
+    public function resolveEndpoint(): string
+    {
+        return '/products/' . $this->product->id;
+    }
+
+    protected function defaultBody(): array
+    {
+        return [
+            'name' => $this->product->name,
+            'price_cents' => $this->product->priceCents,
+        ];
+    }
+}
+```
+
+## Keep the source response
+
+Implement `WithResponse` and use `HasResponse` to attach the original response to the DTO.
+
+```php
+use Saloon\Contracts\DataObjects\WithResponse;
+use Saloon\Traits\Responses\HasResponse;
+
+final class Product implements WithResponse
+{
+    use HasResponse;
+
+    // constructor ...
+}
+
+$product->getResponse()->status();
+```

package/build/Assets/Blueprints/skills/ref-php-laravel-saloon-api-integrations/references/handling-failures.md

@@ -0,0 +1,95 @@
+# Handling Failures
+
+Saloon separates two kinds of failure:
+
+- **HTTP failure**: the API returned 4xx/5xx. Synchronous `send()` returns a `Response` with `failed()` set to `true`, unless throwing is enabled.
+- **Connection failure**: the API returned no response, such as a DNS error or connection timeout. Saloon throws `FatalRequestException`.
+
+```php
+$response = $connector->send(new CreateProductRequest('Widget', 999));
+
+if ($response->failed()) {
+    $errors = $response->json('errors'); // e.g. a 422 validation payload
+}
+```
+
+## Throwing on HTTP failures
+
+Call `throw()` to throw on a failed response. It returns the response on success.
+
+```php
+$product = $connector->send(new GetProductRequest(42))->throw()->json();
+```
+
+For every request on a connector, add `AlwaysThrowOnErrors`.
+
+```php
+use Saloon\Traits\Plugins\AlwaysThrowOnErrors;
+
+class InventoryConnector extends Connector
+{
+    use AlwaysThrowOnErrors;
+}
+```
+
+## Exception hierarchy
+
+Catch the most specific type the application needs. `RequestException` exposes the response through `getResponse()`.
+
+```
+SaloonException
+├── FatalRequestException            connection errors, no response
+└── RequestException                 HTTP 4xx/5xx
+    ├── ClientException              4xx
+    │   ├── UnauthorizedException (401), PaymentRequiredException (402)
+    │   ├── ForbiddenException (403), NotFoundException (404)
+    │   ├── MethodNotAllowedException (405), RequestTimeOutException (408)
+    │   └── UnprocessableEntityException (422), TooManyRequestsException (429)
+    └── ServerException              5xx
+        └── InternalServerErrorException (500), ServiceUnavailableException (503), GatewayTimeoutException (504)
+```
+
+```php
+use Saloon\Exceptions\Request\Statuses\UnprocessableEntityException;
+
+try {
+    $connector->send(new CreateProductRequest('', 0))->throw();
+} catch (UnprocessableEntityException $e) {
+    $errors = $e->getResponse()->json('errors');
+}
+```
+
+## Async and pools
+
+Promises from `sendAsync()` and pools reject on HTTP and connection failures.
+Handle both in `otherwise` or the pool's exception handler. Calling `throw()` is unnecessary.
+For callback examples, read [Sending requests](sending-requests.md) or [Concurrency and pools](concurrency-and-pools.md).
+
+## Custom failure detection
+
+Some APIs return 200 with an error in the body. Override `hasRequestFailed()` on the connector or request; returning `null` falls back to the status-code check.
+
+```php
+use Saloon\Http\Response;
+
+public function hasRequestFailed(Response $response): ?bool
+{
+    return $response->json('status') === 'error';
+}
+```
+
+This changes `failed()`, `throw()`, `dtoOrFail()`, and `AlwaysThrowOnErrors`.
+
+## Custom exception
+
+Override `getRequestException()` on the connector or request to throw an application exception. A request's override wins over the connector's.
+
+```php
+use Saloon\Http\Response;
+use Throwable;
+
+public function getRequestException(Response $response, ?Throwable $senderException): ?Throwable
+{
+    return new InventoryApiException($response->json('message', 'Inventory API error'), $response->status(), $senderException);
+}
+```

package/build/Assets/Blueprints/skills/ref-php-laravel-saloon-api-integrations/references/requests.md

@@ -0,0 +1,111 @@
+# Requests
+
+Create a request class for each endpoint operation.
+Saloon appends the endpoint to the connector's base URL.
+Keep request classes beside their connector.
+
+## Minimal request
+
+Extend `Saloon\Http\Request`, set `$method`, and implement `resolveEndpoint()`.
+
+```php
+use Saloon\Enums\Method;
+use Saloon\Http\Request;
+
+class ListProductsRequest extends Request
+{
+    protected Method $method = Method::GET;
+
+    public function resolveEndpoint(): string
+    {
+        return '/products';
+    }
+}
+```
+
+With the Laravel plugin installed, `php artisan saloon:request` scaffolds one.
+
+## Constructor arguments
+
+Pass identifiers and inputs through the constructor.
+
+```php
+class GetProductRequest extends Request
+{
+    protected Method $method = Method::GET;
+
+    public function __construct(protected readonly int $id) {}
+
+    public function resolveEndpoint(): string
+    {
+        return '/products/' . $this->id;
+    }
+}
+```
+
+## Query parameters
+
+Override `defaultQuery()`, or add to an instance with `$request->query()->add('page', 2)`.
+
+```php
+protected function defaultQuery(): array
+{
+    return [
+        'sort' => 'name',
+        'filter[active]' => 'true',
+    ];
+}
+```
+
+Saloon builds query strings with `http_build_query`.
+
+## Headers
+
+Override `defaultHeaders()`; these merge with the connector's headers. Instance changes use `$request->headers()->add(...)`.
+
+```php
+protected function defaultHeaders(): array
+{
+    return ['Accept' => 'application/json'];
+}
+```
+
+## JSON body
+
+Implement `HasBody`, use `HasJsonBody`, and override `defaultBody()`.
+
+```php
+use Saloon\Contracts\Body\HasBody;
+use Saloon\Enums\Method;
+use Saloon\Http\Request;
+use Saloon\Traits\Body\HasJsonBody;
+
+class CreateProductRequest extends Request implements HasBody
+{
+    use HasJsonBody;
+
+    protected Method $method = Method::POST;
+
+    public function __construct(
+        protected readonly string $name,
+        protected readonly int $priceCents,
+    ) {}
+
+    public function resolveEndpoint(): string
+    {
+        return '/products';
+    }
+
+    protected function defaultBody(): array
+    {
+        return [
+            'name' => $this->name,
+            'price_cents' => $this->priceCents,
+        ];
+    }
+}
+```
+
+## Timeouts
+
+For endpoint-specific timeouts, use the trait and properties shown in [Timeouts](connectors.md#timeouts) on the request.

package/build/Assets/Blueprints/skills/ref-php-laravel-saloon-api-integrations/references/responses.md

@@ -0,0 +1,56 @@
+# Responses
+
+Synchronous `send()` returns a `Saloon\Http\Response`.
+For HTTP and connection failure behavior, read [Handling failures](handling-failures.md).
+
+## Reading a response
+
+```php
+$response = $connector->send(new GetProductRequest(42));
+
+$response->status();             // 200
+$response->header('Content-Type');
+$response->body();               // raw string
+$response->json();               // decoded array
+$response->json('data.name');    // nested key (dot notation)
+$response->json('missing', 'x'); // default when absent
+$response->object();             // stdClass
+$response->collect('data');      // Laravel Collection (requires illuminate/collections)
+```
+
+## Useful methods
+
+| Method                                                                             | Purpose                                                                    |
+| ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `status()`, `headers()`, `header($name)`                                           | Status code and headers                                                    |
+| `body()`, `json()` / `array()`, `object()`, `collect()`                            | Body as string, array, object, or Collection                               |
+| `stream()`, `saveBodyToFile($path)`                                                | Large or binary bodies                                                     |
+| `xmlReader()`, `dom()`                                                             | XML (needs `saloonphp/xml-wrangler`) or HTML (needs `symfony/dom-crawler`) |
+| `ok()`, `successful()`, `redirect()`, `failed()`, `clientError()`, `serverError()` | Status checks; `failed()` is customizable                                  |
+| `throw()`                                                                          | Throw if the response is considered failed                                 |
+| `dto()`, `dtoOrFail()`                                                             | Convert to a DTO; see [Data Transfer Objects](data-transfer-objects.md)    |
+| `getPendingRequest()`, `getPsrRequest()`, `getPsrResponse()`                       | The built request and the raw PSR-7 messages                               |
+
+## Custom response class
+
+Extend `Response` to add API-specific helpers.
+Register the class on the connector for all requests, or on a request for that request only.
+
+```php
+use Saloon\Http\Response;
+
+class InventoryResponse extends Response
+{
+    public function nextPage(): ?int
+    {
+        return $this->json('meta.next_page');
+    }
+}
+
+class InventoryConnector extends Connector
+{
+    protected ?string $response = InventoryResponse::class;
+}
+```
+
+Override `resolveResponseClass(): string` instead of the property when the class must be chosen dynamically.

package/build/Assets/Blueprints/skills/ref-php-laravel-saloon-api-integrations/references/sending-requests.md

@@ -0,0 +1,42 @@
+# Sending Requests
+
+Pass a request to its connector to send it.
+
+## Synchronous
+
+```php
+$connector = new InventoryConnector($baseUrl, $token);
+
+$response = $connector->send(new ListProductsRequest);
+
+$products = $response->json('data');
+```
+
+`send()` returns a `Saloon\Http\Response`. A 4xx/5xx status does **not** throw by default; see [Handling Failures](handling-failures.md).
+
+## Asynchronous
+
+`sendAsync()` returns a Guzzle `PromiseInterface`.
+Successful responses reach `then`. HTTP and connection failures reject the promise and reach `otherwise`.
+
+```php
+use Saloon\Exceptions\Request\FatalRequestException;
+use Saloon\Exceptions\Request\RequestException;
+use Saloon\Http\Response;
+
+$promise = $connector->sendAsync(new ListProductsRequest);
+
+$promise
+    ->then(function (Response $response) {
+        // handle success
+    })
+    ->otherwise(function (FatalRequestException|RequestException $exception) {
+        // RequestException: the API returned 4xx/5xx; use $exception->getResponse()
+        // FatalRequestException: no response, e.g. connection failure
+    });
+
+$promise->wait(); // resolve the promise
+```
+
+For concurrent batches, read [Concurrency and pools](concurrency-and-pools.md).
+For failure classification and custom exceptions, read [Handling failures](handling-failures.md).