### Environment variables setup (.env)

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

Example `.env` file setting the required `G2_API_TOKEN` and optionally overriding `G2_BASE_URL`.

```env
# .env
G2_API_TOKEN=your-api-token
# G2_BASE_URL=https://data.g2.com/api/v1   # optional override
```

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

### get

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Products.md

Fetches a single product by its ID. Sends a GET request to /products/{id}.

```APIDOC
## [GET] /products/{id}

### Description
Fetches a single product by its ID. Sends a GET request to /products/{id}.

### Method
GET

### Endpoint
/products/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Product ID.

### Request Example
GET /products/123

### Response
#### Success Response (200)
- **data** (object) - Product resource object.

#### Response Example
{
  "data": {}
}

### Error Handling
Throws G2Exception with statusCode 404 when the ID does not exist.
```

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

### Install Laravel G2 via Composer

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

Install the package with Composer. Run this in your terminal.

```bash
composer require jeffersongoncalves/laravel-g2
```

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

### Get report with error handling

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Reports.md

Shows how to catch G2Exception when calling get(). The example logs a warning and falls back to an empty array on failure.

```php
use JeffersonGoncalves\G2\Facades\G2;
use JeffersonGoncalves\G2\Exceptions\G2Exception;

try {
    $report = G2::reports()->get('789');
} catch (G2Exception $e) {
    Log::warning('Could not load G2 report', ['status' => $e->statusCode]);
    $report = [];
}
```

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

### Basic GET request with G2::get()

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/G2Client.md

Performs a low-level GET request against the configured base URL. The $uri must start with '/' and $query is passed verbatim to PendingRequest::get(). Returns the decoded JSON:API response, or an empty array if the body is not a JSON array. Throws G2Exception on non-2xx status.

```php
use JeffersonGoncalves\G2\Facades\G2;

$response = G2::get('/products', ['filter[name]' => 'laravel', 'page[number]' => 1]);
// => ['data' => [...], 'meta' => [...], ...]
```

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

### Basic usage of Tracking::visitors()

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Tracking.md

Shows how to call visitors() via the G2 facade with a date range and with only a start date, demonstrating that null filters are omitted from the query string.

```php
use JeffersonGoncalves\G2\Facades\G2;

// Basic call: visitors between 2026-01-01 and 2026-01-31
$visitors = G2::tracking()->visitors('2026-01-01', '2026-01-31', 1, 25);

// Omit one bound — the null filter is dropped from the query string:
$since = G2::tracking()->visitors(startDate: '2026-01-01');
```

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

### Get product error handling

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Products.md

Handles G2Exception when fetching a product, aborting with the status code and message when the product does not exist (404).

```php
use JeffersonGoncalves\G2\Facades\G2;
use JeffersonGoncalves\G2\Exceptions\G2Exception;

try {
    $product = G2::products()->get('123');
} catch (G2Exception $e) {
    // $e->statusCode === 404, $e->getMessage() reads errors[0].detail
    abort($e->statusCode, $e->getMessage());
}
```

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

### get() basic usage with G2 facade

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Reviews.md

Fetches a single review by its ID using the get() method.

```php
use JeffersonGoncalves\G2\Facades\G2;

$review = G2::reviews()->get('456');
```

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

### list

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Products.md

Fetches a paginated list of products, optionally filtered by name. Sends a GET request to /products with optional query parameters for filtering and pagination.

```APIDOC
## [GET] /products

### Description
Fetches a paginated list of products, optionally filtered by name. Sends a GET request to /products with optional query parameters for filtering and pagination.

### Method
GET

### Endpoint
/products

### Parameters
#### Query Parameters
- **filter[name]** (string) - Optional - Filter products by name.
- **page[number]** (integer) - Optional - Page number (default: 1).
- **page[size]** (integer) - Optional - Page size (default: 25).

### Request Example
GET /products?filter[name]=laravel&page[number]=1&page[size]=25

### Response
#### Success Response (200)
- **data** (array) - List of product resources.
- **meta** (object) - Pagination metadata.
- **links** (object) - Pagination links.

#### Response Example
{
  "data": [],
  "meta": {},
  "links": {}
}

### Error Handling
Throws G2Exception on non-2xx responses.
```

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

### Products endpoint usage

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

List products with optional name filter and get a specific product by ID.

```php
G2::products()->list(name: 'laravel', page: 1, perPage: 25);
G2::products()->get('123');
```

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

### Get single product

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Products.md

Fetches a single product by its ID using the G2 facade. The ID is interpolated into the path /products/{$id}.

```php
use JeffersonGoncalves\G2\Facades\G2;

$product = G2::products()->get('123');
```

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

### get(string $uri, array $query = [])

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/G2Client.md

Performs a GET request to the specified URI with optional query parameters. Throws a G2Exception on non-2xx responses.

```APIDOC
## get(string $uri, array $query = [])

### Description
Performs a GET request to the specified URI with optional query parameters. Throws a G2Exception on non-2xx responses.

### Method
get

### Parameters
- **$uri** (string) - Required - The URI to request.
- **$query** (array<string, mixed>) - Optional - Query parameters to include in the request.

### Return Type
array<string, mixed>

### Exceptions
- **G2Exception** - Thrown on non-2xx response.
```

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

### Tracking endpoint usage

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

Get visitors for a date range.

```php
G2::tracking()->visitors(startDate: '2026-01-01', endDate: '2026-01-31', page: 1, perPage: 25);
```

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

### get(string $uri, array $query = []): array

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/G2Client.md

Performs a low-level GET request against the configured base URL. It applies authentication and JSON API headers, and returns the decoded JSON response or throws an exception on failure.

```APIDOC
## get(string $uri, array $query = []): array

### Description
Performs a low-level GET request against the configured base URL. It applies authentication and JSON API headers, and returns the decoded JSON response or throws an exception on failure.

### Method
`get`

### Parameters
#### Path Parameters
- `$uri` (string) - Required - Path appended to the configured `base_url` (must start with `/`, e.g. `/products`).

#### Query Parameters
- `$query` (array<string, mixed>) - Optional - Query-string parameters passed verbatim to `Illuminate\Http\Client\PendingRequest::get()` (e.g. `['filter[name]' => 'laravel']`).

### Return
`array<string, mixed>` — the raw decoded JSON:API response. If the response body is not a JSON array, an empty array `[]` is returned.

### Throws
`G2Exception` when the HTTP response status is non-2xx.

### Example
```php
use JeffersonGoncalves\G2\Facades\G2;

$response = G2::get('/products', ['filter[name]' => 'laravel', 'page[number]' => 1]);
// => ['data' => [...], 'meta' => [...], ...]
```

### Error Handling
```php
use JeffersonGoncalves\G2\Facades\G2;
use JeffersonGoncalves\G2\Exceptions\G2Exception;

try {
    $data = G2::get('/products/does-not-exist');
} catch (G2Exception $e) {
    echo $e->getMessage();   // errors[0].detail, else errors[0].title, else raw body
    echo $e->statusCode;     // e.g. 404
    echo $e->getCode();      // same HTTP status (passed to RuntimeException)
}
```
```

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

### Instantiate G2Client via app() or new

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/G2Client.md

G2Client is a plain class with an implicit public constructor, so it can be instantiated directly or resolved from the container. The app() call returns the singleton bound by G2ServiceProvider, while new G2Client() uses configuration-driven setup.

```php
use JeffersonGoncalves\G2\G2Client;

$client = app(G2Client::class);      // singleton bound by G2ServiceProvider
$client = new G2Client();            // direct instantiation, config-driven
```

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

### get(string $id): array

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Categories.md

Fetches a single category by its ID. Sends a GET request to /categories/{id}.

```APIDOC
## [GET] /categories/{id}

### Description
Fetches a single category by its ID. Sends a GET request to /categories/{id}.

### Method
GET

### Endpoint
/categories/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Category ID.

### Request Example
GET /categories/321

### Response
#### Success Response (200)
- **data** (object) - Category resource object.

#### Response Example
{
  "data": {}
}

### Error Handling
Throws G2Exception with statusCode 404 when the ID does not exist.
```

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

### Reviews endpoint usage

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

List reviews with optional filters and get a specific review by ID.

```php
G2::reviews()->list(productId: '123', state: 'published', page: 1, perPage: 25);
G2::reviews()->get('456');
```

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

### G2 facade usage without import using global alias

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Facades/G2.md

Demonstrates calling the G2 facade without an import statement when the global alias is available (default), using the products() accessor and get() method.

```php
$product = G2::products()->get('123');
```

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

### get

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Reviews.md

Fetches a single review by its ID from the G2 API. This method sends a GET request to /survey-responses/{id}.

```APIDOC
## [GET] /survey-responses/{id}

### Description
Fetches a single review by its ID from the G2 API. This method sends a GET request to /survey-responses/{id}.

### Method
GET

### Endpoint
/survey-responses/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The review ID.

### Request Example
GET /survey-responses/456

### Response
#### Success Response (200)
- **data** (object) - The review resource object.

#### Response Example
{
  "data": {
    "id": "456",
    "type": "review",
    "attributes": {}
  }
}

### Error Handling
- **G2Exception** - Thrown on non-2xx responses, e.g., 404 Not Found when the ID does not exist.
```

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

### get(string $id): array

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Reports.md

Fetches a single report by its ID. Sends a GET request to /reports/{id}.

```APIDOC
## [GET] /reports/{id}

### Description
Fetches a single report by its ID.

### Method
GET

### Endpoint
/reports/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Report ID.

### Request Example
```
GET /reports/789
```

### Response
#### Success Response (200)
- **data** (object) - Report resource object.

#### Response Example
```json
{
  "data": {}
}
```

```

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

### Request shape for product endpoints

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Products.md

Shows the HTTP GET requests generated by the Products resource, including query parameters and headers set by G2Client::http().

```http
GET {base_url}/products{?filter[name]&page[size]&page[number]}
GET {base_url}/products/{id}
Authorization: Token token={token}
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
```

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

### Reviews class signature

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Reviews.md

Class definition for the Reviews resource, holding a G2Client and providing list() and get() methods that map to GET requests against /survey-responses.

```php
class Reviews
{
    public function __construct(private readonly G2Client $client) {}

    /**
     * @return array<string, mixed>
     */
    public function list(?string $productId = null, ?string $state = null, int $page = 1, int $perPage = 25): array
    {
        return $this->client->get('/survey-responses', array_filter([
            'filter[product_id]' => $productId,
            'filter[state]' => $state,
            'page[size]' => $perPage,
            'page[number]' => $page,
        ]));
    }

    /**
     * @return array<string, mixed>
     */
    public function get(string $id): array
    {
        return $this->client->get("/survey-responses/{$id}");
    }
}
```

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

### Tracking class signature and visitors() method

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Tracking.md

Defines the Tracking resource class with a constructor that promotes the G2Client and a visitors() method that sends a GET request to /tracking-events with optional date filters and pagination parameters.

```php
class Tracking
{
    public function __construct(private readonly G2Client $client) {}

    /**
     * @return array<string, mixed>
     */
    public function visitors(?string $startDate = null, ?string $endDate = null, int $page = 1, int $perPage = 25): array
    {
        return $this->client->get('/tracking-events', array_filter([
            'filter[start_date]' => $startDate,
            'filter[end_date]' => $endDate,
            'page[size]' => $perPage,
            'page[number]' => $page,
        ]));
    }
}
```

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

### get() error handling with G2Exception

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Reviews.md

Handles G2Exception when fetching a review, checking for a 404 status code and aborting with a 'Review not found' message.

```php
use JeffersonGoncalves\G2\Facades\G2;
use JeffersonGoncalves\G2\Exceptions\G2Exception;

try {
    $review = G2::reviews()->get('missing');
} catch (G2Exception $e) {
    // $e->getMessage() === 'errors[0].detail' or 'errors[0].title' from the API
    if ($e->statusCode === 404) {
        abort(404, 'Review not found');
    }
}
```

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

### Example reproduction with Http::fake

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Exceptions/G2Exception.md

Test-suite style reproduction using Laravel's Http::fake to simulate a 404 response with a JSON:API error. Verifies that getMessage() returns 'Product not found.' and statusCode is 404.

```php
use Illuminate\Support\Facades\Http;
use JeffersonGoncalves\G2\Facades\G2;
use JeffersonGoncalves\G2\Exceptions\G2Exception;

Http::fake([
    'data.g2.com/api/v1/products/1' => Http::response(
        ['errors' => [['status' => '404', 'title' => 'Not Found', 'detail' => 'Product not found.']]],
        404
    ),
]);

try {
    G2::products()->get('1');
} catch (G2Exception $e) {
    // $e->getMessage() === 'Product not found.'
    // $e->statusCode   === 404
}
```

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

### Reports endpoint usage

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

List reports and get a specific report by ID.

```php
G2::reports()->list(page: 1, perPage: 25);
G2::reports()->get('789');
```

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

### Request shape for competitor comparisons

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Competitors.md

Shows the HTTP request structure: GET to /competitor-comparisons with query parameters and required headers.

```http
GET {base_url}/competitor-comparisons{?filter[product_id]&page[size]&page[number]}
Authorization: Token token={token}
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
```

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

### Set G2 API token in .env

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

Add your G2 API token to the .env file. Request access at https://data.g2.com/api/v1 to get a token.

```env
G2_API_TOKEN=your-api-token
```

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

### List with error handling

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Reports.md

Shows how to catch G2Exception when calling list(). The example checks if the status code is >= 500 to detect server-side issues like downtime or rate limiting.

```php
use JeffersonGoncalves\G2\Facades\G2;
use JeffersonGoncalves\G2\Exceptions\G2Exception;

// Error handling — surface the failure status to the caller
try {
    $reports = G2::reports()->list();
} catch (G2Exception $e) {
    if ($e->statusCode >= 500) {
        // G2 API is down or rate-limiting; retry later.
    }
}
```

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

### Get category with error handling

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Categories.md

Shows error handling for the get method. $e->getMessage() is the API error detail or title; then falls back to the raw body.

```php
use JeffersonGoncalves\G2\Facades\G2;
use JeffersonGoncalves\G2\Exceptions\G2Exception;

try {
    $category = G2::categories()->get('321');
} catch (G2Exception $e) {
    // $e->getMessage() is the API error detail or title; then falls back to the raw body.
    report($e);
}
```

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

### Request shape for review endpoints

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Reviews.md

Shows the HTTP GET request format and headers used for list and get operations, including query parameters and authentication headers.

```http
GET {base_url}/survey-responses{?filter[product_id]&filter[state]&page[size]&page[number]}
GET {base_url}/survey-responses/{id}
Authorization: Token token={token}
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
```

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

### Basic list call with pagination

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Reports.md

Fetches a paginated list of reports using the G2 facade. The example calls list with page 2 and 10 reports per page.

```php
use JeffersonGoncalves\G2\Facades\G2;

// Basic call: page 2 with 10 reports per page
$reports = G2::reports()->list(page: 2, perPage: 10);
```

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

### Products class signature

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Products.md

The Products resource class maps method calls to GET requests against /products. It holds a reference to the owning G2Client and is returned by G2Client::products() and G2::products().

```php
class Products
{
    public function __construct(private readonly G2Client $client) {}

    /**
     * @return array<string, mixed>
     */
    public function list(?string $name = null, int $page = 1, int $perPage = 25): array
    {
        return $this->client->get('/products', array_filter([
            'filter[name]' => $name,
            'page[size]' => $perPage,
            'page[number]' => $page,
        ]));
    }

    /**
     * @return array<string, mixed>
     */
    public function get(string $id): array
    {
        return $this->client->get("/products/{$id}");
    }
}
```

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

### Categories endpoint usage

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

List categories with optional name filter and get a specific category by ID.

```php
G2::categories()->list(name: 'crm', page: 1, perPage: 25);
G2::categories()->get('321');
```

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

### Request shape for tracking-events endpoint

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Tracking.md

Illustrates the HTTP GET request structure sent to /tracking-events, including query parameters and required headers.

```http
GET {base_url}/tracking-events{?filter[start_date]&filter[end_date]&page[size]&page[number]}
Authorization: Token token={token}
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
```

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

### list

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Reviews.md

Fetches a paginated list of survey responses (reviews) from the G2 API. This method sends a GET request to /survey-responses with optional filters and pagination parameters.

```APIDOC
## [GET] /survey-responses

### Description
Fetches a paginated list of survey responses (reviews) from the G2 API. This method sends a GET request to /survey-responses with optional filters and pagination parameters.

### Method
GET

### Endpoint
/survey-responses

### Parameters
#### Query Parameters
- **filter[product_id]** (string) - Optional - Filter by product ID.
- **filter[state]** (string) - Optional - Filter by state, e.g., 'published'.
- **page[number]** (integer) - Optional - Page number (default: 1).
- **page[size]** (integer) - Optional - Page size (default: 25).

### Request Example
GET /survey-responses?filter[product_id]=123&filter[state]=published&page[number]=2&page[size]=50

### Response
#### Success Response (200)
- **data** (array) - List of review resources.
- **meta** (object) - Pagination metadata.
- **links** (object) - Pagination links.

#### Response Example
{
  "data": [
    {
      "id": "123",
      "type": "review",
      "attributes": {}
    }
  ],
  "meta": {
    "total": 100,
    "count": 50
  },
  "links": {
    "first": "...",
    "last": "..."
  }
}

### Error Handling
- **G2Exception** - Thrown on non-2xx responses, e.g., 401 Unauthorized.
```

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

### Get single report by ID

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Reports.md

Fetches a single report by its ID using the G2 facade. The ID is interpolated into the path /reports/{$id}.

```php
use JeffersonGoncalves\G2\Facades\G2;

$report = G2::reports()->get('789');
```

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

### Catching G2Exception via RuntimeException

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Exceptions/G2Exception.md

Because G2Exception extends RuntimeException, broader handlers can catch it. This example shows catching it as RuntimeException.

```php
use RuntimeException;

try {
    G2::reports()->get('789');
} catch (RuntimeException $e) {
    // Also catches G2Exception.
}
```

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

### Get category by ID

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Categories.md

Fetches a single category by its ID, interpolated into the path /categories/{$id}. Throws G2Exception with statusCode 404 when the ID does not exist.

```php
use JeffersonGoncalves\G2\Facades\G2;

$category = G2::categories()->get('321');
```

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

### Request shape for category endpoints

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Categories.md

Every call produces a GET request with the headers and base URL set by G2Client::http(). Shows the request paths and required headers.

```http
GET {base_url}/categories{?filter[name]&page[size]&page[number]}
GET {base_url}/categories/{id}
Authorization: Token token={token}
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
```

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

### list(?string $name = null, int $page = 1, int $perPage = 25): array

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Categories.md

Fetches a paginated list of categories, optionally filtered by name. Sends a GET request to /categories with query parameters for filtering and pagination.

```APIDOC
## [GET] /categories

### Description
Fetches a paginated list of categories, optionally filtered by name. Sends a GET request to /categories with query parameters for filtering and pagination.

### Method
GET

### Endpoint
/categories

### Parameters
#### Query Parameters
- **filter[name]** (string) - Optional - Filter categories by name (e.g. 'crm'). Omitted when null.
- **page[number]** (int) - Optional - Page number (default: 1).
- **page[size]** (int) - Optional - Page size (default: 25).

### Request Example
GET /categories?filter[name]=crm&page[number]=1&page[size]=25

### Response
#### Success Response (200)
- **data** (array) - List of category resources.
- **meta** (object) - Pagination metadata.
- **links** (object) - Pagination links.

#### Response Example
{
  "data": [],
  "meta": {},
  "links": {}
}

### Error Handling
Throws G2Exception on non-2xx responses.
```

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

### Reports class signature

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Reports.md

The Reports resource class maps method calls to GET requests against /reports. It holds a reference to the owning G2Client and has no filter parameters, only pagination.

```php
class Reports
{
    public function __construct(private readonly G2Client $client) {}

    /**
     * @return array<string, mixed>
     */
    public function list(int $page = 1, int $perPage = 25): array
    {
        return $this->client->get('/reports', [
            'page[size]' => $perPage,
            'page[number]' => $page,
        ]);
    }

    /**
     * @return array<string, mixed>
     */
    public function get(string $id): array
    {
        return $this->client->get("/reports/{$id}");
    }
}
```

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

### list(int $page = 1, int $perPage = 25): array

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Reports.md

Fetches a paginated list of reports. Sends a GET request to /reports with page[size] and page[number] query parameters.

```APIDOC
## [GET] /reports

### Description
Fetches a paginated list of reports.

### Method
GET

### Endpoint
/reports

### Parameters
#### Query Parameters
- **page[size]** (int) - Optional - Page size, default 25.
- **page[number]** (int) - Optional - Page number, default 1.

### Request Example
```
GET /reports?page[size]=25&page[number]=1
```

### Response
#### Success Response (200)
- **data** (array) - List of report resources.
- **meta** (object) - Pagination metadata.
- **links** (object) - Pagination links.

#### Response Example
```json
{
  "data": [],
  "meta": {},
  "links": {}
}
```

```

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

### Run code formatting

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

Apply code style fixes.

```bash
composer format
```

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

### Categories class signature

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Categories.md

The Categories resource class maps method calls to GET requests against /categories. It holds a reference to the owning G2Client and is returned by G2Client::categories() and G2::categories().

```php
class Categories
{
    public function __construct(private readonly G2Client $client) {}

    /**
     * @return array<string, mixed>
     */
    public function list(?string $name = null, int $page = 1, int $perPage = 25): array
    {
        return $this->client->get('/categories', array_filter([
            'filter[name]' => $name,
            'page[size]' => $perPage,
            'page[number]' => $page,
        ]));
    }

    /**
     * @return array<string, mixed>
     */
    public function get(string $id): array
    {
        return $this->client->get("/categories/{$id}");
    }
}
```

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

### Run tests

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

Execute the test suite.

```bash
composer test
```

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

### G2::products()

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Facades/G2.md

Returns a Products resource instance for interacting with products. Proxies to G2Client::products().

```APIDOC
## G2::products()

### Description
Returns a Products resource instance for interacting with products. Proxies to G2Client::products().

### Method
Static method on the G2 facade.

### Endpoint
`/products`

### Returns
- **Products** - A resource instance for products.

### Example
```php
$product = G2::products()->get('123');
```
```

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

### Run static analysis

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

Run PHPStan static analysis.

```bash
composer analyse
```

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

### Basic chained usage of G2 facade with import

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Facades/G2.md

Shows how to use the G2 facade with an explicit import statement, calling the reviews() accessor and chaining the list() method with named arguments.

```php
use JeffersonGoncalves\G2\Facades\G2;

$reviews = G2::reviews()->list(productId: '123', state: 'published', page: 1, perPage: 25);
```

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

### Basic product list call

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Products.md

Fetches the first 25 products matching 'laravel' using the G2 facade. The name filter is sent as filter[name], page size as page[size], and page number as page[number].

```php
use JeffersonGoncalves\G2\Facades\G2;

// Basic call: first 25 products matching "laravel"
$products = G2::products()->list(name: 'laravel', page: 1, perPage: 25);
```

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

### products(): Products

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/G2Client.md

Returns a fresh Products resource instance bound to this client. This provides access to the /products endpoint.

```APIDOC
## products(): Products

### Description
Returns a fresh `Products` resource instance bound to this client. This provides access to the `/products` endpoint.

### Method
`products()`

### Parameters
None.

### Return
`Products` — resource accessor for the `/products` endpoint.

### Example
```php
use JeffersonGoncalves\G2\Facades\G2;

$products = G2::products();
```
```

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

### Access Products resource via G2::products()

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/G2Client.md

Returns a fresh Products resource instance bound to the client for the /products endpoint. Use the facade to access the resource.

```php
use JeffersonGoncalves\G2\Facades\G2;

$products = G2::products();
```

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

### Competitors endpoint usage

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

List competitors for a given product ID.

```php
G2::competitors()->list(productId: '123', page: 1, perPage: 25);
```

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

### Basic usage of G2::competitors()->list()

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Competitors.md

Shows a basic call to list competitor comparisons for a product. The productId is required; omitting it raises a TypeError.

```php
use JeffersonGoncalves\G2\Facades\G2;

// Basic call: competitor comparisons for product 123
$comparisons = G2::competitors()->list(productId: '123', page: 1, perPage: 25);

// $productId is required — calling list() without it raises a PHP TypeError:
// G2::competitors()->list(); // TypeError: Argument #1 ($productId) must be of type string
```

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

### Error handling for G2::competitors()->list()

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Competitors.md

Demonstrates catching G2Exception when the productId is invalid. A 404 status code indicates an unknown or excluded product.

```php
use JeffersonGoncalves\G2\Facades\G2;
use JeffersonGoncalves\G2\Exceptions\G2Exception;

// Error handling — productId must reference a valid product
try {
    $comparisons = G2::competitors()->list('unknown-product');
} catch (G2Exception $e) {
    if ($e->statusCode === 404) {
        // Unknown or excluded product.
    }
}
```

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

### list() basic usage with G2 facade

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Reviews.md

Fetches published reviews for a specific product, page 2 with 50 per page, and iterates over the returned data.

```php
use JeffersonGoncalves\G2\Facades\G2;

// Basic call: published reviews for a specific product, page 2 of 50
$reviews = G2::reviews()->list(productId: '123', state: 'published', page: 2, perPage: 50);

foreach ($reviews['data'] as $review) {
    echo $review['id'];
}
```

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

### Product list error handling

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Products.md

Handles G2Exception when listing products, specifically checking for a 401 status code to throw a RuntimeException for an invalid token.

```php
use JeffersonGoncalves\G2\Facades\G2;
use JeffersonGoncalves\G2\Exceptions\G2Exception;

// Error handling — unauthorized token
try {
    $products = G2::products()->list();
} catch (G2Exception $e) {
    if ($e->statusCode === 401) {
        throw new RuntimeException('G2 token is invalid');
    }
}
```

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

### G2ServiceProvider class implementation

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/G2ServiceProvider.md

Extends Spatie\LaravelPackageTools\PackageServiceProvider. configurePackage() sets the package name to 'g2' and publishes config/g2.php. packageRegistered() binds G2Client as a singleton and aliases it to 'g2'.

```php
class G2ServiceProvider extends PackageServiceProvider
{
    public function configurePackage(Package $package): void
    {
        $package
            ->name('g2')
            ->hasConfigFile();
    }

    public function packageRegistered(): void
    {
        $this->app->singleton(G2Client::class);
        $this->app->alias(G2Client::class, 'g2');
    }
}
```

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

### list(string $productId, int $page = 1, int $perPage = 25): array

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Competitors.md

Fetches a paginated list of competitor comparisons. This method is the only operation exposed by the Competitors resource and requires a productId parameter.

```APIDOC
## [GET] /competitor-comparisons

### Description
Fetches a paginated list of competitor comparisons for a given product.

### Method
GET

### Endpoint
/competitor-comparisons

### Parameters
#### Query Parameters
- **filter[product_id]** (string) - Required - Product to compare against.
- **page[number]** (int) - Optional - Page number (default: 1).
- **page[size]** (int) - Optional - Page size (default: 25).

### Request Example
GET /competitor-comparisons?filter[product_id]=123&page[number]=1&page[size]=25

### Response
#### Success Response (200)
- **data** (array) - List of competitor comparison resources.
- **meta** (object) - Pagination metadata.
- **links** (object) - Related links.

#### Response Example
{
  "data": [],
  "meta": {},
  "links": {}
}

### Error Handling
- **404** - Unknown or excluded product.
- **G2Exception** - Thrown on non-2xx responses.
```

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

### Resolve G2Client singleton via class or alias

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/G2ServiceProvider.md

Shows that app(G2Client::class) and app('g2') return the same singleton instance, as the alias resolves to the same binding.

```php
// Any of these resolve to the same singleton instance:
use JeffersonGoncalves\G2\G2Client;

$viaClass = app(G2Client::class);
$viaAlias = app('g2');

$same = $viaClass === $viaAlias; // true (singleton + alias)
```

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

### products()

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/G2Client.md

Returns a Products resource accessor for interacting with product-related endpoints of the G2 API.

```APIDOC
## products()

### Description
Returns a Products resource accessor for interacting with product-related endpoints of the G2 API.

### Method
products()

### Return Type
Products
```

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

### Import G2 facade and exception

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

Import the G2 facade and G2Exception class for use in your code.

```php
use JeffersonGoncalves\G2\Facades\G2;
use JeffersonGoncalves\G2\Exceptions\G2Exception;
```

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

### G2::reviews()

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Facades/G2.md

Returns a Reviews resource instance for interacting with survey responses. Proxies to G2Client::reviews().

```APIDOC
## G2::reviews()

### Description
Returns a Reviews resource instance for interacting with survey responses. Proxies to G2Client::reviews().

### Method
Static method on the G2 facade.

### Endpoint
`/survey-responses`

### Returns
- **Reviews** - A resource instance for survey responses.

### Example
```php
$reviews = G2::reviews()->list(productId: '123', state: 'published', page: 1, perPage: 25);
```
```

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

### Access Competitors resource via G2::competitors()

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/G2Client.md

Returns a fresh Competitors resource instance bound to the client for the /competitor-comparisons endpoint. Use the facade to access the resource.

```php
use JeffersonGoncalves\G2\Facades\G2;

$competitors = G2::competitors();
```

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

### G2 config options

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

Default configuration file for the package. The token is read from the G2_API_TOKEN environment variable, and the base URL defaults to https://data.g2.com/api/v1.

```php
// config/g2.php
return [
    'token' => env('G2_API_TOKEN'),
    'base_url' => env('G2_BASE_URL', 'https://data.g2.com/api/v1'),
];
```

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

### visitors(?string $startDate = null, ?string $endDate = null, int $page = 1, int $perPage = 25): array

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Tracking.md

Fetches a paginated list of tracking events (visitors), optionally filtered by a date range. Returns the raw decoded JSON:API response. Throws G2Exception on non-2xx responses.

```APIDOC
## [GET] /tracking-events

### Description
Fetches a paginated list of tracking events (visitors), optionally filtered by a date range.

### Method
GET

### Endpoint
/tracking-events

### Parameters
#### Query Parameters
- **filter[start_date]** (string) - Optional - Filter sent as `filter[start_date]`. The G2 API expects a date string such as `'2026-01-01'`; the package itself does not parse or validate the format. Omitted from the query when null.
- **filter[end_date]** (string) - Optional - Filter sent as `filter[end_date]`, e.g. `'2026-01-31'`. Omitted from the query when null.
- **page[number]** (integer) - Optional - Page number sent as `page[number]`. Default: 1.
- **page[size]** (integer) - Optional - Page size sent as `page[size]`. Default: 25.

### Request Example
```
GET {base_url}/tracking-events?filter[start_date]=2026-01-01&filter[end_date]=2026-01-31&page[size]=25&page[number]=1
Authorization: Token token={token}
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
```

### Response
#### Success Response (200)
- **data** (array) - The list of tracking events.
- **meta** (object) - Pagination metadata.
- **links** (object) - Pagination links.

#### Response Example
```json
{
  "data": [],
  "meta": {},
  "links": {}
}
```

#### Error Response
- **G2Exception** - Thrown on non-2xx responses (e.g., 401, 403, 500).
```

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

### G2::tracking()

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Facades/G2.md

Returns a Tracking resource instance for interacting with tracking events. Proxies to G2Client::tracking().

```APIDOC
## G2::tracking()

### Description
Returns a Tracking resource instance for interacting with tracking events. Proxies to G2Client::tracking().

### Method
Static method on the G2 facade.

### Endpoint
`/tracking-events`

### Returns
- **Tracking** - A resource instance for tracking events.
```

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

### Error handling for Tracking::visitors()

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Tracking.md

Wraps the visitors() call in a try-catch block to handle G2Exception, checking the statusCode for 403 to indicate missing tracking-event permissions.

```php
use JeffersonGoncalves\G2\Facades\G2;
use JeffersonGoncalves\G2\Exceptions\G2Exception;

// Error handling — non-2xx response (e.g. 401, 403, 500)
try {
    $visitors = G2::tracking()->visitors('2026-01-01', '2026-01-31');
} catch (G2Exception $e) {
    if ($e->statusCode === 403) {
        // Your token may not have tracking-event permissions.
    }
}
```

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

### G2::competitors()

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Facades/G2.md

Returns a Competitors resource instance for interacting with competitor comparisons. Proxies to G2Client::competitors().

```APIDOC
## G2::competitors()

### Description
Returns a Competitors resource instance for interacting with competitor comparisons. Proxies to G2Client::competitors().

### Method
Static method on the G2 facade.

### Endpoint
`/competitor-comparisons`

### Returns
- **Competitors** - A resource instance for competitor comparisons.
```

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

### reviews(): Reviews

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/G2Client.md

Returns a fresh Reviews resource instance bound to this client. This provides access to the /survey-responses endpoint.

```APIDOC
## reviews(): Reviews

### Description
Returns a fresh `Reviews` resource instance bound to this client. This provides access to the `/survey-responses` endpoint.

### Method
`reviews()`

### Parameters
None.

### Return
`Reviews` — resource accessor for the `/survey-responses` endpoint.

### Example
```php
use JeffersonGoncalves\G2\Facades\G2;

$reviews = G2::reviews(); // Returns a Reviews instance
```
```

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

### Competitors class signature

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Resources/Competitors.md

Defines the Competitors resource class with a constructor and a list() method. The list() method requires a productId and sends pagination parameters.

```php
class Competitors
{
    public function __construct(private readonly G2Client $client) {}

    /**
     * @return array<string, mixed>
     */
    public function list(string $productId, int $page = 1, int $perPage = 25): array
    {
        return $this->client->get('/competitor-comparisons', [
            'filter[product_id]' => $productId,
            'page[size]' => $perPage,
            'page[number]' => $page,
        ]);
    }
}
```

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

### Access Reviews resource via G2::reviews()

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/G2Client.md

Returns a fresh Reviews resource instance bound to the client for the /survey-responses endpoint. Use the facade to access the resource.

```php
use JeffersonGoncalves\G2\Facades\G2;

$reviews = G2::reviews(); // Returns a Reviews instance
```

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

### Access Tracking resource via G2::tracking()

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/G2Client.md

Returns a fresh Tracking resource instance bound to the client for the /tracking-events endpoint. Use the facade to access the resource.

```php
use JeffersonGoncalves\G2\Facades\G2;

$tracking = G2::tracking();
```

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

### reviews()

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/G2Client.md

Returns a Reviews resource accessor for interacting with review-related endpoints of the G2 API.

```APIDOC
## reviews()

### Description
Returns a Reviews resource accessor for interacting with review-related endpoints of the G2 API.

### Method
reviews()

### Return Type
Reviews
```

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

### G2::reports()

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Facades/G2.md

Returns a Reports resource instance for interacting with reports. Proxies to G2Client::reports().

```APIDOC
## G2::reports()

### Description
Returns a Reports resource instance for interacting with reports. Proxies to G2Client::reports().

### Method
Static method on the G2 facade.

### Endpoint
`/reports`

### Returns
- **Reports** - A resource instance for reports.

### Example
```php
$report = G2::reports()->get('missing-report-id');
```
```

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

### tracking(): Tracking

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/G2Client.md

Returns a fresh Tracking resource instance bound to this client. This provides access to the /tracking-events endpoint.

```APIDOC
## tracking(): Tracking

### Description
Returns a fresh `Tracking` resource instance bound to this client. This provides access to the `/tracking-events` endpoint.

### Method
`tracking()`

### Parameters
None.

### Return
`Tracking` — resource accessor for the `/tracking-events` endpoint.

### Example
```php
use JeffersonGoncalves\G2\Facades\G2;

$tracking = G2::tracking();
```
```

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

### G2::categories()

Source: https://github.com/jeffersongoncalves/laravel-g2/blob/main/_autodocs/api-reference/Facades/G2.md

Returns a Categories resource instance for interacting with categories. Proxies to G2Client::categories().

```APIDOC
## G2::categories()

### Description
Returns a Categories resource instance for interacting with categories. Proxies to G2Client::categories().

### Method
Static method on the G2 facade.

### Endpoint
`/categories`

### Returns
- **Categories** - A resource instance for categories.
```