### Install and Setup laravel-metrics-fathom

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/resources/boost/skills/metrics-fathom-development/SKILL.md

Install the package via Composer and run the necessary migrations for settings.

```bash
composer require jeffersongoncalves/laravel-metrics-fathom
php artisan vendor:publish --tag=metrics-fathom-settings-migrations
php artisan migrate
```

--------------------------------

### Install package via Composer

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/README.md

Install the package using the composer command.

```bash
composer require jeffersongoncalves/laravel-metrics-fathom
```

--------------------------------

### get() usage example

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/FathomClient.md

Creates a FathomClient with a token and base URL, then fetches the account and sites with a limit parameter.

```php
use JeffersonGoncalves\MetricsFathom\FathomClient;

$client = new FathomClient(token: 'fathom_abc123', baseUrl: 'https://api.usefathom.com/v1');

$account = $client->get('account');
$sites   = $client->get('sites', ['limit' => 20]);
```

--------------------------------

### currentVisitors() usage example

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Fathom.md

Example calls to currentVisitors(). The first call uses default settings and prints the total. The second enables detailed mode to include content and referrers.

```php
$visitors = Fathom::currentVisitors();
echo $visitors->total; // 42

$detailed = Fathom::currentVisitors(detailed: true);
```

--------------------------------

### query() usage example

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Fathom.md

Example call to Fathom::query() to get a query for pageview aggregations.

```php
$query = Fathom::query(); // pageview aggregations
```

--------------------------------

### queryEvents() usage example

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Fathom.md

Example showing how to build an event aggregation query for conversions of a specific event and run it with Fathom::aggregate(). Requires importing the Aggregate enum.

```php
use JeffersonGoncalves\MetricsFathom\Enums\Aggregate;

$query = Fathom::queryEvents()
    ->aggregate(Aggregate::Conversions)
    ->forEvent('signup');
$result = Fathom::aggregate($query);
```

--------------------------------

### milestones() usage example

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Fathom.md

Example call to Fathom::milestones() without arguments, using default settings for site ID and pagination.

```php
$milestones = Fathom::milestones();
```

--------------------------------

### createEvent() usage example

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Fathom.md

Creates an event named 'signup'.

```php
$event = Fathom::createEvent('signup');
```

--------------------------------

### get() error handling example

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/FathomClient.md

Catches RateLimitException when calling get() on aggregations. Fathom caps aggregations at 10 requests/minute, so the example sleeps 6 seconds before retrying.

```php
use JeffersonGoncalves\MetricsFathom\Exceptions\RateLimitException;

try {
    $client->get('aggregations', ['entity' => 'pageview']);
} catch (RateLimitException $e) {
    // Fathom caps aggregations at 10 requests/minute — back off and retry
    sleep(6);
}
```

--------------------------------

### milestone() usage example

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Fathom.md

Example call to Fathom::milestone('MSID') to fetch a specific milestone.

```php
$milestone = Fathom::milestone('MSID');
```

--------------------------------

### createMilestone() usage example

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Fathom.md

Example call to Fathom::createMilestone() with a name and an ISO date string for the milestone date.

```php
$milestone = Fathom::createMilestone('v2.0 Launch', '2026-03-01');
```

--------------------------------

### aggregate() usage example with query builder

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Fathom.md

Example showing how to build an AggregationQuery with aggregate functions and date grouping, then pass it to Fathom::aggregate(). Requires importing Aggregate and DateGrouping enums.

```php
use JeffersonGoncalves\MetricsFathom\Enums\Aggregate;
use JeffersonGoncalves\MetricsFathom\Enums\DateGrouping;

$query = Fathom::query()
    ->aggregate(Aggregate::Visits, Aggregate::Pageviews)
    ->groupByDate(DateGrouping::Day);

$result = Fathom::aggregate($query);
```

--------------------------------

### deleteSite() usage example

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Fathom.md

Deletes a site by its ID.

```php
Fathom::deleteSite('SITEID');
```

--------------------------------

### post() usage example

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/FathomClient.md

Creates a site and an event using the post() method.

```php
$site = $client->post('sites', ['name' => 'My Site', 'sharing' => 'public']);
$event = $client->post('sites/SITE1/events', ['name' => 'signup']);
```

--------------------------------

### events() usage example

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Fathom.md

Fetches up to 5 events and prints each event name.

```php
$events = Fathom::events(limit: 5);
foreach ($events['data'] as $event) {
    echo $event->name;
}
```

--------------------------------

### wipeSite() usage example

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Fathom.md

Erases all data for a site.

```php
Fathom::wipeSite('SITEID');
```

--------------------------------

### Container resolution examples

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Fathom.md

Shows three interchangeable ways to resolve the Fathom service from the container: via the 'fathom' binding, the class alias, or the static facade.

```php
use JeffersonGoncalves\MetricsFathom\Fathom;

$fathom = app('fathom');        // container binding
$fathom = app(Fathom::class);   // class alias
Fathom::site('SITEID');         // facade (static)
```

--------------------------------

### Event::fromArray usage example

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Data-DTOs.md

Shows how to create an Event instance from an array using the static factory Event::fromArray. The example passes 'object' key for the name and accesses the siteId property.

```php
use JeffersonGoncalves\MetricsFathom\Data\Event;

$event = Event::fromArray(['id' => 'EV1', 'object' => 'signup', 'site_id' => 'SITE1']);
echo $event->siteId; // 'SITE1'
```

--------------------------------

### get()

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/FathomClient.md

Sends a GET request to the specified endpoint with optional query parameters and returns the decoded JSON response as an associative array.

```APIDOC
## GET {baseUrl}/{endpoint}

### Description
Sends a GET request to the specified endpoint with optional query parameters and returns the decoded JSON response as an associative array.

### Method
GET

### Endpoint
{baseUrl}/{endpoint}

### Parameters
#### Path Parameters
- **endpoint** (string) - Required - API path appended to baseUrl, e.g. `sites` or `sites/{id}/events`

#### Query Parameters
- **params** (array<string, mixed>) - Optional - Query-string parameters

### Request Example
```
GET https://api.usefathom.com/v1/sites?limit=20
```

### Response
#### Success Response (200)
- **body** (array<string, mixed>) - Decoded JSON body as an associative array; `[]` when the body is empty.

#### Response Example
```json
{
  "id": "SITE1",
  "name": "My Site"
}
```

### Errors
- **AuthenticationException** - Empty token or HTTP 401
- **RateLimitException** - HTTP 429
- **FathomException** - Any other non-2xx status
```

--------------------------------

### Milestone::fromArray usage example

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Data-DTOs.md

Shows how to create a Milestone instance from an array using the static factory Milestone::fromArray. The example includes a milestone_date and accesses the milestoneDate property.

```php
use JeffersonGoncalves\MetricsFathom\Data\Milestone;

$milestone = Milestone::fromArray([
    'id' => 'MS1', 'object' => 'v2.0 Launch', 'site_id' => 'SITE1', 'milestone_date' => '2026-03-01',
]);
echo $milestone->milestoneDate; // '2026-03-01'
```

--------------------------------

### Usage examples for enums

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Enums.md

Shows how to access enum values and use them with Fathom::createSite and the query builder. Demonstrates that FilterOperator::IsLike includes spaces in its value.

```php
use JeffersonGoncalves\MetricsFathom\Enums\Aggregate;
use JeffersonGoncalves\MetricsFathom\Enums\DateGrouping;
use JeffersonGoncalves\MetricsFathom\Enums\Entity;
use JeffersonGoncalves\MetricsFathom\Enums\FieldGrouping;
use JeffersonGoncalves\MetricsFathom\Enums\FilterOperator;
use JeffersonGoncalves\MetricsFathom\Enums\Sharing;

Aggregate::Visits->value;                  // 'visits'
FilterOperator::IsLike->value;             // 'is like' (spaces included)
Sharing::Public->value;                    // 'public'

// Enums cross-checked by Fathom::createSite and the query builder
Fathom::createSite('Blog', Sharing::Private);

$q = Fathom::query()
    ->aggregate(Aggregate::Uniques)
    ->groupByDate(DateGrouping::Day)
    ->groupByField(FieldGrouping::CountryCode)
    ->where(FieldGrouping::CountryCode, FilterOperator::Is, 'US');
```

--------------------------------

### delete() usage example

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/FathomClient.md

Deletes a site and wipes site data using the delete() method.

```php
$client->delete('sites/SITE1');            // delete site
$client->delete('sites/SITE1/data');       // wipe site data
```

--------------------------------

### event() usage example

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Fathom.md

Fetches a single event by its ID.

```php
$event = Fathom::event('EVENTID');
```

--------------------------------

### updateSite() usage example

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Fathom.md

Updates a site with a new name and sharing level. Only provided fields are sent.

```php
$site = Fathom::updateSite('SITEID', name: 'New Name', sharing: Sharing::Private);
```

--------------------------------

### get() method signature

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/FathomClient.md

Issues a GET request to the Fathom API. Returns decoded JSON body as an associative array, or [] when the body is empty. Throws AuthenticationException (empty token or HTTP 401), RateLimitException (HTTP 429), or FathomException (any other non-2xx status).

```php
/**
 * @param  array<string, mixed>  $params
 * @return array<string, mixed>
 */
public function get(string $endpoint, array $params = []): array
```

--------------------------------

### updateMilestone() usage example

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Fathom.md

Example call to Fathom::updateMilestone() using a named argument to update only the milestone name.

```php
$milestone = Fathom::updateMilestone('MSID', name: 'v2.1 Launch');
```

--------------------------------

### Using the Fathom facade to get account info

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Fathom.md

Shows how to use the Fathom facade to call the account() method. The facade resolves the 'fathom' container binding and provides static analysis support via PHPDoc annotations.

```php
use JeffersonGoncalves\MetricsFathom\Facades\Fathom;

$account = Fathom::account();
```

--------------------------------

### wipeEvent() usage example

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Fathom.md

Erases all data for an event.

```php
Fathom::wipeEvent('EVENTID');
```

--------------------------------

### Retrieve current visitors

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/README.md

Get current visitor counts, optionally including detailed page and referrer data.

```php
// Simple count
$visitors = Fathom::currentVisitors();
echo $visitors->total; // 42

// Detailed (top pages & referrers)
$visitors = Fathom::currentVisitors(detailed: true);
```

--------------------------------

### updateEvent() usage example

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Fathom.md

Renames an event to 'new-name'.

```php
$event = Fathom::updateEvent('EVENTID', 'new-name');
```

--------------------------------

### from()

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/AggregationQuery.md

Sets the start of the date range for the query.

```APIDOC
## from()

### Description
Sets the start of the date range for the query.

### Method
`public function from(DateTimeInterface|string $date): self`

### Parameters
- **date** (`DateTimeInterface|string`) - Required - Start of range; `DateTimeInterface` instances are formatted `Y-m-d H:i:s`.

### Serialization
`date_from`.

### Notes
String values pass through verbatim; they are not validated or reformatted.

### Example
```php
$q = Fathom::query()->from('2026-02-01 00:00:00');

use Carbon\Carbon;
$q = Fathom::query()->from(Carbon::now()->subDays(30)); // formatted to 'Y-m-d H:i:s'
```
```

--------------------------------

### from() method

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/AggregationQuery.md

Sets the start of the date range. DateTimeInterface instances are formatted as 'Y-m-d H:i:s'. String values pass through verbatim without validation or reformatting.

```php
public function from(DateTimeInterface|string $date): self
```

```php
$q = Fathom::query()->from('2026-02-01 00:00:00');

use Carbon\Carbon;
$q = Fathom::query()->from(Carbon::now()->subDays(30)); // formatted to 'Y-m-d H:i:s'
```

--------------------------------

### Site::fromArray and toArray usage example

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Data-DTOs.md

Shows how to hydrate a Site from an API payload using `Site::fromArray()` and serialize it back with `toArray()`. The `name` field accepts `object` or `name`; missing `sharing` defaults to `'none'`. Output comment shows the resulting array.

```php
use JeffersonGoncalves\MetricsFathom\Data\Site;

$site = Site::fromArray([
    'id' => 'SITE1', 'object' => 'My Site', 'sharing' => 'public',
]);
echo $site->name;    // 'My Site'

$array = $site->toArray();
// ['id' => 'SITE1', 'name' => 'My Site', 'sharing' => 'public', 'share_password' => null]
```

--------------------------------

### post() method signature

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/FathomClient.md

Issues a POST request with a JSON body. Returns decoded JSON body as an associative array (the created/updated resource). Throws the same exception contract as get().

```php
/**
 * @param  array<string, mixed>  $data
 * @return array<string, mixed>
 */
public function post(string $endpoint, array $data = []): array
```

--------------------------------

### limit() usage example

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/AggregationQuery.md

Limits the aggregation query to return at most 10 result rows for visits.

```php
$q = Fathom::query()->aggregate(Aggregate::Visits)->limit(10);
```

--------------------------------

### GET /sites

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/endpoints.md

Retrieves a list of sites. Supports pagination via cursor parameters. Returns a list of Site DTOs and a has_more flag.

```APIDOC
## GET /sites

### Description
Retrieves a list of sites. Supports pagination via cursor parameters. Returns a list of Site DTOs and a has_more flag.

### Method
GET

### Endpoint
/sites

### Parameters
#### Query Parameters
- **limit** (int) - Required - Default `10`
- **starting_after** (string) - Optional - Cursor; sent only when non-null
- **ending_before** (string) - Optional - Cursor; sent only when non-null

### Response
#### Success Response (200)
- **data** (Site[]) - List of Site DTOs
- **has_more** (bool) - Indicates if more results are available; defaults to `false` when missing

#### Response Example
{
  "data": [],
  "has_more": false
}
```

--------------------------------

### Run migrations

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/README.md

Run the artisan command to create the necessary settings table.

```bash
php artisan migrate
```

--------------------------------

### toQueryParams() usage example

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/AggregationQuery.md

Builds an aggregation query for visits grouped by day and converts it to query parameters. The resulting array includes entity, entity_id, timezone, aggregates, and date_grouping keys.

```php
$params = Fathom::query()
    ->aggregate(Aggregate::Visits)
    ->groupByDate(DateGrouping::Day)
    ->toQueryParams();

// ['entity' => 'pageview', 'entity_id' => 'A123', 'timezone' => 'UTC',
//  'aggregates' => 'visits', 'date_grouping' => 'day']
```

--------------------------------

### account() method signature with return type

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Fathom.md

Defines the account() method that returns the raw JSON payload of GET /v1/account as an associative array. The payload is not wrapped in a DTO.

```php
/**
 * @return array<string, mixed>
 */
public function account(): array
```

--------------------------------

### Run tests with composer

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/README.md

Executes the project test suite using Composer.

```bash
composer test
```

--------------------------------

### Format code with composer

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/README.md

Applies code style formatting using Composer.

```bash
composer format
```

--------------------------------

### deleteMilestone() usage example

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Fathom.md

Example call to Fathom::deleteMilestone('MSID') to delete a milestone.

```php
Fathom::deleteMilestone('MSID');
```

--------------------------------

### Import Fathom Facade

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/README.md

Import the Fathom facade to access the API methods.

```php
use JeffersonGoncalves\MetricsFathom\Facades\Fathom;
```

--------------------------------

### Run static analysis with composer

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/README.md

Performs static analysis on the codebase using Composer.

```bash
composer analyse
```

--------------------------------

### createSite()

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Fathom.md

Creates a new site with the given name and sharing settings. Returns the created Site DTO.

```APIDOC
## POST /v1/sites

### Description
Creates a new site.

### Method
POST

### Endpoint
/v1/sites

### Parameters
#### Request Body
- **name** (string) - Required - Site name
- **sharing** (string) - Optional - Sharing setting: 'none', 'private', or 'public' (default: 'none')
- **share_password** (string) - Optional - Password for private sharing

### Request Example
{
  "name": "My Site",
  "sharing": "public",
  "share_password": "letmein"
}

### Response
#### Success Response (200)
- **id** (string) - Site ID
- **name** (string) - Site name
- **sharing** (string) - Sharing setting

#### Response Example
{
  "id": "new_site_id",
  "name": "My Site",
  "sharing": "public"
}
```

--------------------------------

### deleteEvent() usage example

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Fathom.md

Deletes an event by its ID.

```php
Fathom::deleteEvent('EVENTID');
```

--------------------------------

### createSite() method signature with sharing enum

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Fathom.md

Defines the createSite() method that creates a new site. Accepts a name, a Sharing enum (defaults to Sharing::None), and an optional share password.

```php
public function createSite(string $name, Sharing $sharing = Sharing::None, ?string $sharePassword = null): Site
```

--------------------------------

### Configure environment variables

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/README.md

Set the Fathom configuration values in your environment file.

```env
FATHOM_API_TOKEN=your-api-token
FATHOM_SITE_ID=your-site-id
FATHOM_BASE_URL=https://api.usefathom.com/v1
FATHOM_TIMEZONE=UTC
```

--------------------------------

### sites() method signature with pagination parameters

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Fathom.md

Defines the sites() method that returns a paginated envelope with a list of Site DTOs and a has_more flag. Supports limit, startingAfter, and endingBefore parameters for pagination.

```php
/**
 * @return array{data: list<Site>, has_more: bool}
 */
public function sites(int $limit = 10, ?string $startingAfter = null, ?string $endingBefore = null): array
```

--------------------------------

### Running Development Commands

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/resources/boost/skills/metrics-fathom-development/SKILL.md

Commands to execute tests, static analysis, and code style checks.

```bash
vendor/bin/pest
vendor/bin/phpstan analyse
vendor/bin/pint
```

--------------------------------

### sites()

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Fathom.md

Lists sites with pagination support. Returns a paginated envelope containing an array of Site DTOs and a has_more flag.

```APIDOC
## GET /v1/sites

### Description
Retrieves a list of sites with optional pagination.

### Method
GET

### Endpoint
/v1/sites

### Parameters
#### Query Parameters
- **limit** (int) - Optional - Maximum number of sites to return (default: 10)
- **starting_after** (string) - Optional - Cursor for forward pagination
- **ending_before** (string) - Optional - Cursor for backward pagination

### Request Example
GET /v1/sites?limit=20&starting_after=abc123

### Response
#### Success Response (200)
- **data** (array of Site) - List of sites
- **has_more** (boolean) - Whether more results are available

#### Response Example
{
  "data": [
    {
      "id": "site_id",
      "name": "Site Name"
    }
  ],
  "has_more": false
}
```

--------------------------------

### Mocking Fathom Facade, HTTP, and AggregationQuery

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/resources/boost/skills/metrics-fathom-development/SKILL.md

Demonstrates how to mock the Fathom facade and HTTP responses, and how to verify AggregationQuery parameters in tests.

```php
// Mock facade
Fathom::shouldReceive('site')->with('SITE_ID')
    ->andReturn(Site::fromArray(['id' => 'SITE_ID', 'name' => 'Test', 'sharing' => 'none']));

// Mock HTTP
Http::fake([
    'api.usefathom.com/v1/sites' => Http::response([
        'data' => [['id' => 'SITE_1', 'object' => 'Test', 'sharing' => 'none']],
        'has_more' => false,
    ]),
]);

// Test query builder
$query = AggregationQuery::pageviews()->aggregate(Aggregate::Pageviews)->groupByDate(DateGrouping::Day);
$params = $query->toQueryParams();
expect($params['entity'])->toBe('pageview');
expect($params['aggregates'])->toBe('pageviews');
```

--------------------------------

### GET /sites/{siteId}/milestones/{milestoneId}

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/endpoints.md

Retrieves a single milestone by its ID.

```APIDOC
## GET /sites/{siteId}/milestones/{milestoneId}

### Description
Retrieves a single milestone by its ID.

### Method
GET

### Endpoint
/sites/{siteId}/milestones/{milestoneId}

### Parameters
#### Path Parameters
- **siteId** (string) - Optional - The site ID; falls back to `FathomSettings::site_id` when null.
- **milestoneId** (string) - Required - The milestone ID.

### Response
#### Success Response (200)
- **Milestone** (Milestone) - The milestone DTO.

#### Response Example
{
  "id": "milestone-id",
  "name": "milestone-name"
}
```

--------------------------------

### GET /sites/{siteId}/milestones

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/endpoints.md

Retrieves a list of milestones for a given site.

```APIDOC
## GET /sites/{siteId}/milestones

### Description
Retrieves a list of milestones for a given site.

### Method
GET

### Endpoint
/sites/{siteId}/milestones

### Parameters
#### Path Parameters
- **siteId** (string) - Optional - The site ID; falls back to `FathomSettings::site_id` when null.

#### Query Parameters
- **limit** (int) - Optional - Default 10.
- **starting_after** (string) - Optional - Sent only when non-null.
- **ending_before** (string) - Optional - Sent only when non-null.

### Response
#### Success Response (200)
- **data** (Milestone[]) - List of milestones.
- **has_more** (bool) - Indicates if more results are available.

#### Response Example
{
  "data": [],
  "has_more": false
}
```

--------------------------------

### GET /sites/{siteId}/events/{eventId}

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/endpoints.md

Retrieves a single event by its ID.

```APIDOC
## GET /sites/{siteId}/events/{eventId}

### Description
Retrieves a single event by its ID.

### Method
GET

### Endpoint
/sites/{siteId}/events/{eventId}

### Parameters
#### Path Parameters
- **siteId** (string) - Optional - The site ID; falls back to `FathomSettings::site_id` when null.
- **eventId** (string) - Required - The event ID.

### Response
#### Success Response (200)
- **Event** (Event) - The event DTO.

#### Response Example
{
  "id": "event-id",
  "name": "event-name"
}
```

--------------------------------

### Publish and run settings migrations

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/configuration.md

Publishes the settings migration with the `metrics-fathom-settings-migrations` tag and then runs the migrations. The migration seeds the `metrics-fathom` settings group from environment variables.

```bash
php artisan vendor:publish --tag=metrics-fathom-settings-migrations
php artisan migrate
```

--------------------------------

### Resolving Fathom instances from the container

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/FathomServiceProvider.md

Shows how to resolve the singleton Fathom instance via 'fathom' or the Fathom::class alias, and the FathomClient singleton. All return the same instances due to container bindings.

```php
use JeffersonGoncalves\MetricsFathom\Fathom;
use JeffersonGoncalves\MetricsFathom\FathomClient;

$fathom  = app('fathom');                  // singleton Fathom instance
$fathom2 = app(Fathom::class);             // same instance (alias)
$client  = app(FathomClient::class);       // singleton HTTP client
```

--------------------------------

### between(DateTimeInterface|string $from, DateTimeInterface|string $to): self

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/AggregationQuery.md

Sets both the start and end of the date range for the aggregation query. It is implemented by calling `from()` and `to()`.

```APIDOC
## between(DateTimeInterface|string $from, DateTimeInterface|string $to): self

### Description
Sets both the start and end of the date range for the aggregation query. It is implemented by calling `from()` and `to()`.

### Method
`between`

### Signature
```php
public function between(DateTimeInterface|string $from, DateTimeInterface|string $to): self
```

### Parameters
- **from** (`DateTimeInterface|string`) - Required - Forwarded to `from()`
- **to** (`DateTimeInterface|string`) - Required - Forwarded to `to()`

### Serialization
Sets both `date_from` and `date_to`.

### Example
```php
use Carbon\Carbon;

$q = Fathom::query()
    ->aggregate(Aggregate::Visits)
    ->between(Carbon::now()->subDays(30), Carbon::now());
```
```

--------------------------------

### delete() method signature

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/FathomClient.md

Issues a DELETE request. Returns decoded JSON body as an associative array. Throws the same exception contract as get().

```php
/**
 * @return array<string, mixed>
 */
public function delete(string $endpoint): array
```

--------------------------------

### GET /sites/{siteId}/events

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/endpoints.md

Retrieves a list of events for a given site. The site ID can be omitted to use the default from settings.

```APIDOC
## GET /sites/{siteId}/events

### Description
Retrieves a list of events for a given site.

### Method
GET

### Endpoint
/sites/{siteId}/events

### Parameters
#### Path Parameters
- **siteId** (string) - Optional - The site ID; falls back to `FathomSettings::site_id` when null.

#### Query Parameters
- **limit** (int) - Optional - Default 10.
- **starting_after** (string) - Optional - Sent only when non-null.
- **ending_before** (string) - Optional - Sent only when non-null.

### Response
#### Success Response (200)
- **data** (Event[]) - List of events.
- **has_more** (bool) - Indicates if more results are available.

#### Response Example
{
  "data": [],
  "has_more": false
}
```

--------------------------------

### Manage sites

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/README.md

Perform CRUD operations on sites using the Fathom facade.

```php
// List sites
$result = Fathom::sites(limit: 20);
foreach ($result['data'] as $site) {
    echo $site->id . ' - ' . $site->name;
}

// Get a site
$site = Fathom::site('SITEID');

// Create a site
use JeffersonGoncalves\MetricsFathom\Enums\Sharing;
$site = Fathom::createSite('My Site', Sharing::Public);

// Update a site
$site = Fathom::updateSite('SITEID', name: 'New Name');

// Delete a site
Fathom::deleteSite('SITEID');
```

--------------------------------

### between() method signature

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/AggregationQuery.md

Sets both the start and end of the date range for an aggregation query. Forwards the from parameter to from() and the to parameter to to(). Serialization sets both 'date_from' and 'date_to'.

```php
public function between(DateTimeInterface|string $from, DateTimeInterface|string $to): self
```

--------------------------------

### Handling AuthenticationException from account()

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Fathom.md

Shows error handling for Fathom::account() when the token is missing or invalid. An empty token throws before any HTTP call.

```php
use JeffersonGoncalves\MetricsFathom\Exceptions\AuthenticationException;

try {
    Fathom::account();
} catch (AuthenticationException $e) {
    // token missing or invalid (empty token throws before any HTTP call)
}
```

--------------------------------

### Fathom Site Management

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/README.md

Methods for listing, creating, updating, and deleting sites.

```APIDOC
## Fathom Site Management

### Description
Provides methods to interact with Fathom sites including listing, retrieving, creating, updating, and deleting site records.
```

--------------------------------

### Creating a site with public sharing and password

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Fathom.md

Calls Fathom::createSite() with a site name, Sharing::Public, and a share password. The password is only sent when non-null.

```php
use JeffersonGoncalves\MetricsFathom\Enums\Sharing;

$site = Fathom::createSite('My Site', Sharing::Public, 'letmein');
```

--------------------------------

### Use DateTime objects in queries

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/README.md

Use Carbon instances to define date ranges in your queries.

```php
use Carbon\Carbon;

$query = Fathom::query()
    ->aggregate(Aggregate::Visits)
    ->between(Carbon::now()->subDays(30), Carbon::now());

$result = Fathom::aggregate($query);
```

--------------------------------

### to() usage example

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/AggregationQuery.md

Sets the end of the date range to a specific date and time string. The date string format matches the from() method's formatting rule.

```php
$q = Fathom::query()->to('2026-02-28 23:59:59');
```

--------------------------------

### milestone() signature

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Fathom.md

Signature for the milestone() method that retrieves a single milestone by ID. Returns a Milestone DTO. HTTP call: GET /v1/sites/{siteId}/milestones/{milestoneId}.

```php
public function milestone(string $milestoneId, ?string $siteId = null): Milestone
```

--------------------------------

### Retrieve account information

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/README.md

Fetch account details using the Fathom facade.

```php
$account = Fathom::account();
```

--------------------------------

### site()

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Fathom.md

Retrieves a single site by its ID. If no site ID is provided, falls back to the default site ID from settings.

```APIDOC
## GET /v1/sites/{siteId}

### Description
Retrieves details of a specific site.

### Method
GET

### Endpoint
/v1/sites/{siteId}

### Parameters
#### Path Parameters
- **siteId** (string) - Optional - Site ID; falls back to default site ID if omitted

### Request Example
GET /v1/sites/SITEID

### Response
#### Success Response (200)
- **id** (string) - Site ID
- **name** (string) - Site name
- **sharing** (string) - Sharing setting (none, private, public)

#### Response Example
{
  "id": "SITEID",
  "name": "My Site",
  "sharing": "private"
}
```

--------------------------------

### Usage: resolve, read, update, and save FathomSettings

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/FathomSettings.md

Shows how to resolve the settings via the container, read the four properties, update them, and persist changes with save(). The api_token, site_id, base_url, and timezone are all mutable at runtime.

```php
use JeffersonGoncalves\MetricsFathom\Settings\FathomSettings;

$settings = app(FathomSettings::class);       // resolve via container

// Read
$token    = $settings->api_token;
$siteId   = $settings->site_id;
$baseUrl  = $settings->base_url;
$timezone = $settings->timezone;

// Update + persist
$settings->api_token = 'new-token';
$settings->site_id = 'NEWSITE';
$settings->timezone = 'America/Sao_Paulo';
$settings->save();
```

--------------------------------

### GET /current_visitors

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/endpoints.md

Retrieves the current number of visitors on your site. Optionally includes detailed page and referrer data when the 'detailed' parameter is set to true.

```APIDOC
## GET /current_visitors

### Description
Retrieves the current number of visitors on your site. Optionally includes detailed page and referrer data when the 'detailed' parameter is set to true.

### Method
GET

### Endpoint
/current_visitors

### Parameters
#### Query Parameters
- **site_id** (string) - Required - Always sent; defaults to `FathomSettings::site_id`
- **detailed** (bool) - Required - Always sent; `true`/`false`

### Response
#### Success Response (200)
- **total** (int) - Total number of current visitors
- **content** (list) - List of raw page rows; populated only when `detailed: true`
- **referrers** (list) - List of raw referrer rows; populated only when `detailed: true`

#### Response Example
```json
{
  "total": 123,
  "content": [],
  "referrers": []
}
```

### Authentication
Requires a bearer API token. No unauthenticated access is available.
```

--------------------------------

### query()

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Fathom.md

Creates a new AggregationQuery for pageview aggregations. Equivalent to calling AggregationQuery::pageviews().

```APIDOC
## query()

### Description
Creates a new AggregationQuery for pageview aggregations.

### Method
N/A (SDK method)

### Endpoint
N/A

### Parameters
None

### Returns
- **AggregationQuery** - A fresh query configured for pageview aggregations
```

--------------------------------

### GET /sites/{siteId}

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/endpoints.md

Retrieves a single site by its ID. If the siteId is not provided, it defaults to the configured site ID. Returns a single Site DTO.

```APIDOC
## GET /sites/{siteId}

### Description
Retrieves a single site by its ID. If the siteId is not provided, it defaults to the configured site ID. Returns a single Site DTO.

### Method
GET

### Endpoint
/sites/{siteId}

### Parameters
#### Path Parameters
- **siteId** (string) - Optional - Site ID; defaults to `FathomSettings::site_id` when null

### Response
#### Success Response (200)
- **Site** (Site) - A single Site DTO
```

--------------------------------

### Using Fathom::currentVisitors() with detailed: true

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Data-DTOs.md

Shows how to fetch current visitors with detailed breakdowns using the Fathom facade. The total property returns an integer, and content contains raw API rows with keys like pathname.

```php
use JeffersonGoncalves\MetricsFathom\Facades\Fathom;

$visitors = Fathom::currentVisitors(detailed: true);
echo $visitors->total;                 // int
foreach ($visitors->content as $page) {
    echo $page['pathname'];            // raw API row
}
```

--------------------------------

### Build custom reports with aggregations

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/README.md

Use the fluent query builder to generate custom analytics reports.

```php
use JeffersonGoncalves\MetricsFathom\Enums\Aggregate;
use JeffersonGoncalves\MetricsFathom\Enums\DateGrouping;
use JeffersonGoncalves\MetricsFathom\Enums\FieldGrouping;
use JeffersonGoncalves\MetricsFathom\Enums\FilterOperator;

// Pageviews per day for the last month
$query = Fathom::query()
    ->aggregate(Aggregate::Visits, Aggregate::Pageviews, Aggregate::BounceRate)
    ->groupByDate(DateGrouping::Day)
    ->from('2026-02-01 00:00:00')
    ->to('2026-02-28 23:59:59');

$result = Fathom::aggregate($query);

// Top pages by visits
$query = Fathom::query()
    ->aggregate(Aggregate::Visits)
    ->groupByField(FieldGrouping::Pathname)
    ->sortBy('visits', 'desc')
    ->limit(10);

$result = Fathom::aggregate($query);

// Visitors by country
$query = Fathom::query()
    ->aggregate(Aggregate::Uniques)
    ->groupByField(FieldGrouping::CountryCode)
    ->sortBy('uniques', 'desc');

$result = Fathom::aggregate($query);

// Filter by UTM source
$query = Fathom::query()
    ->aggregate(Aggregate::Visits, Aggregate::Uniques)
    ->where(FieldGrouping::UtmSource, FilterOperator::Is, 'twitter')
    ->from('2026-01-01 00:00:00');

$result = Fathom::aggregate($query);

// Event conversions
$query = Fathom::queryEvents()
    ->aggregate(Aggregate::Conversions, Aggregate::UniqueConversions)
    ->forSite('SITEID')
    ->forEvent('signup')
    ->groupByDate(DateGrouping::Month);

$result = Fathom::aggregate($query);
```

--------------------------------

### GET /account

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/endpoints.md

Retrieves the authenticated Fathom account details. This is an outbound call made by the FathomClient against the Fathom Analytics v1 REST API, returning the raw account payload.

```APIDOC
## [GET] /account

### Description
Retrieves the authenticated Fathom account details. This is an outbound call made by the FathomClient against the Fathom Analytics v1 REST API, returning the raw account payload.

### Method
GET

### Endpoint
/account

### Parameters
No parameters.

### Response
#### Success Response (200)
- **id** (string) - Account identifier
- **name** (string) - Account name
- **email** (string) - Account email

#### Response Example
{
  "id": "account-id",
  "name": "Account Name",
  "email": "account@example.com"
}

### Error Handling
- **401** - Invalid token (AuthenticationException::invalidToken)
- **429** - Rate limit exceeded (RateLimitException::exceeded)
- **Other 4xx/5xx** - Generic error (FathomException)
```

--------------------------------

### between() usage example with Carbon

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/AggregationQuery.md

Sets a date range from 30 days ago to the current time using Carbon instances. Requires the Carbon library. The query aggregates visits within that range.

```php
use Carbon\Carbon;

$q = Fathom::query()
    ->aggregate(Aggregate::Visits)
    ->between(Carbon::now()->subDays(30), Carbon::now());
```

--------------------------------

### POST /sites

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/endpoints.md

Creates a new site. Requires a name and optionally specifies sharing settings. Returns the created Site DTO.

```APIDOC
## POST /sites

### Description
Creates a new site. Requires a name and optionally specifies sharing settings. Returns the created Site DTO.

### Method
POST

### Endpoint
/sites

### Parameters
#### Request Body
- **name** (string) - Required - Site name
- **sharing** (string) - Optional - Sharing level: 'none', 'private', or 'public'; default 'none'
- **share_password** (string) - Optional - Password for sharing; sent only when non-null

### Request Example
{
  "name": "My Site",
  "sharing": "private",
  "share_password": "secret"
}

### Response
#### Success Response (200)
- **Site** (Site) - The created Site DTO
```

--------------------------------

### milestones() signature with docblock

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Fathom.md

Signature for the milestones() method that retrieves a paginated list of milestones. Returns an array with 'data' (list of Milestone DTOs) and 'has_more' boolean. HTTP call: GET /v1/sites/{siteId}/milestones.

```php
/**
 * @return array{data: list<Milestone>, has_more: bool}
 */
public function milestones(?string $siteId = null, int $limit = 10, ?string $startingAfter = null, ?string $endingBefore = null): array
```

--------------------------------

### site() method signature with optional siteId

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Fathom.md

Defines the site() method that returns a Site DTO. The siteId parameter is optional and falls back to FathomSettings::site_id when omitted.

```php
public function site(?string $siteId = null): Site
```

--------------------------------

### FathomClient class declaration

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/FathomClient.md

Constructor with immutable token and baseUrl parameters. An empty-string token is rejected at request time by ensureToken(), which throws AuthenticationException::missingToken().

```php
class FathomClient
{
    public function __construct(
        private readonly string $token,
        private readonly string $baseUrl,
    ) {}
}
```

--------------------------------

### GET /aggregations

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/endpoints.md

Retrieves raw aggregation data from Fathom Analytics. This endpoint is called via the Fathom::aggregate() method with an AggregationQuery object, and returns raw aggregation rows without a DTO wrapper.

```APIDOC
## [GET] /aggregations

### Description
Retrieves raw aggregation data from Fathom Analytics. This endpoint is called via the Fathom::aggregate() method with an AggregationQuery object, and returns raw aggregation rows without a DTO wrapper.

### Method
GET

### Endpoint
/aggregations

### Parameters
#### Query Parameters
- **entity** (string) - Required - `pageview` or `event` (always)
- **entity_id** (string) - Required - Query `entityId` or settings `site_id` (always)
- **timezone** (string) - Required - Query timezone or settings `timezone` (always)
- **aggregates** (string) - Optional - Comma-joined aggregate values, e.g. `visits,pageviews` (when set)
- **site_id** (string) - Optional - Event-entity site override (when set)
- **entity_name** (string) - Optional - Event name filter (when set)
- **date_grouping** (string) - Optional - `hour`|`day`|`month`|`year` (when set)
- **field_grouping** (string) - Optional - e.g. `pathname`, `country_code` (when set)
- **sort_by** (string) - Optional - `"{field}:{direction}"`, e.g. `visits:desc` (when set)
- **date_from / date_to** (string) - Optional - `Y-m-d H:i:s` or raw string (when set)
- **limit** (int) - Optional - Row cap (when set)
- **filters** (string) - Optional - JSON array of `{property, operator, value}` objects (when set)

### Response
#### Success Response (200)
- **array<int|string, mixed>** - The raw aggregation rows (each row keyed by aggregate/grouping values, e.g. `['visits' => '1234', 'pageviews' => '5678']`). Not wrapped in a DTO.

#### Response Example
{
  "visits": "1234",
  "pageviews": "5678"
}

### Error Handling
- **429 RateLimitException** - Fathom caps aggregation requests at 10/min; expect this under heavy use.
```

--------------------------------

### where() usage example with multiple filters

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/AggregationQuery.md

Adds two filter conditions to an aggregation query: one on the UTM source field and one on the browser field. The filters are accumulated and serialized as a JSON array in the 'filters' query parameter.

```php
$q = Fathom::query()
    ->aggregate(Aggregate::Visits, Aggregate::Uniques)
    ->where(FieldGrouping::UtmSource, FilterOperator::Is, 'twitter')
    ->where('browser', FilterOperator::IsNotLike, 'Chrome%');
```

--------------------------------

### events()

Source: https://github.com/jeffersongoncalves/laravel-metrics-fathom/blob/main/_autodocs/api-reference/Fathom.md

Retrieves a list of events for a site, with pagination support. Returns an array with event data and a has_more flag.

```APIDOC
## GET /v1/sites/{siteId}/events

### Description
Retrieves a list of events for a site, with pagination support. Returns an array with event data and a has_more flag.

### Method
GET

### Endpoint
/v1/sites/{siteId}/events

### Parameters
#### Path Parameters
- **siteId** (string) - Required - Site ID; falls back to FathomSettings::site_id

#### Query Parameters
- **limit** (int) - Optional - Maximum number of events to return (default: 10)
- **starting_after** (string) - Optional - Cursor for forward pagination
- **ending_before** (string) - Optional - Cursor for backward pagination

### Response
#### Success Response (200)
- **data** (list<Event>) - List of events
- **has_more** (bool) - Whether more events are available

#### Response Example
{
  "data": [
    {
      "id": "EVENTID",
      "name": "signup"
    }
  ],
  "has_more": false
}
```