Feature/traces

composer.json

@@ -54,7 +54,7 @@
         "test:lint": "@php vendor/bin/pint --config https://raw.githubusercontent.com/DIJ-digital/pint-config/main/pint.json",
         "test:unit": "pest",
         "test:types": "phpstan",
-        "test:refactor": "rector --dry-run",
+        "test:refactor": "rector",
         "test": [
             "@test:lint",
             "@test:type-coverage",

src/Contracts/TransporterInterface.php

@@ -9,34 +9,34 @@
 interface TransporterInterface
 {
     /**
-     * @param array<string, mixed> $options
+     * @param  array<string, mixed>  $options
      */
     public function request(string $method, string $uri, array $options = []): ResponseInterface;
 
     /**
-     * @param array<string, mixed> $options
+     * @param  array<string, mixed>  $options
      */
     public function get(string $uri, array $options = []): ResponseInterface;
 
     /**
-     * @param array<string, mixed> $options
+     * @param  array<string, mixed>  $options
      */
     public function post(string $uri, array $options = []): ResponseInterface;
 
     /**
-     * @param array<string, mixed> $data
-     * @param array<string, mixed> $options
+     * @param  array<string, mixed>  $data
+     * @param  array<string, mixed>  $options
      */
     public function postJson(string $uri, array $data = [], array $options = []): ResponseInterface;
 
     /**
-     * @param array<string, mixed> $options
+     * @param  array<string, mixed>  $options
      */
     public function delete(string $uri, array $options = []): ResponseInterface;
 
     /**
-     * @param array<string, mixed> $data
-     * @param array<string, mixed> $options
+     * @param  array<string, mixed>  $data
+     * @param  array<string, mixed>  $options
      */
     public function patchJson(string $uri, array $data = [], array $options = []): ResponseInterface;
 }

src/Langfuse.php

@@ -12,8 +12,7 @@ public function __construct(
         private readonly TransporterInterface $transporter,
         private readonly string $environment = 'default',
         private readonly string $label = 'latest',
-    ) {
-    }
+    ) {}
 
     public function prompt(): Prompt
     {
@@ -37,4 +36,11 @@ public function score(): Score
             transporter: $this->transporter,
         );
     }
+
+    public function trace(): Trace
+    {
+        return new Trace(
+            transporter: $this->transporter,
+        );
+    }
 }

src/Responses/TraceListResponse.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DIJ\Langfuse\PHP\Responses;
+
+use DIJ\Langfuse\PHP\ValueObjects\MetaData;
+
+readonly class TraceListResponse
+{
+    /**
+     * @param  array<int, TraceResponse>  $data
+     */
+    public function __construct(
+        public array $data,
+        public MetaData $meta,
+    ) {}
+
+    /**
+     * @param array{
+     *     data: array<int, array{
+     *         id: string,
+     *         timestamp: string,
+     *         name: string|null,
+     *         input: mixed,
+     *         output: mixed,
+     *         sessionId: string|null,
+     *         release: string|null,
+     *         version: string|null,
+     *         userId: string|null,
+     *         metadata: mixed,
+     *         tags: array<int, string>,
+     *         public: bool|null,
+     *         projectId: string,
+     *         createdAt: string,
+     *         updatedAt: string,
+     *         externalId?: string|null,
+     *         totalCost?: float|null,
+     *         latency?: float|null,
+     *         htmlPath?: string|null,
+     *         environment?: string|null
+     *     }>,
+     *     meta: array{page: int, limit: int, totalPages: int, totalItems: int}
+     * } $data
+     */
+    public static function fromArray(array $data): self
+    {
+        return new self(
+            data: array_map(fn (array $item): TraceResponse => TraceResponse::fromArray($item), $data['data']),
+            meta: MetaData::fromArray($data['meta']),
+        );
+    }
+}

src/Responses/TraceResponse.php

@@ -0,0 +1,92 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DIJ\Langfuse\PHP\Responses;
+
+readonly class TraceResponse
+{
+    /**
+     * @param  array<int, string>  $tags
+     * @param  array<int, mixed>  $observations
+     * @param  array<int, mixed>  $scores
+     */
+    public function __construct(
+        public string $id,
+        public string $timestamp,
+        public ?string $name,
+        public mixed $input,
+        public mixed $output,
+        public ?string $sessionId,
+        public ?string $release,
+        public ?string $version,
+        public ?string $userId,
+        public mixed $metadata,
+        public array $tags,
+        public ?bool $public,
+        public string $projectId,
+        public string $createdAt,
+        public string $updatedAt,
+        public ?string $externalId = null,
+        public ?float $totalCost = null,
+        public ?float $latency = null,
+        public array $observations = [],
+        public array $scores = [],
+        public ?string $htmlPath = null,
+        public ?string $environment = null,
+    ) {}
+
+    /**
+     * @param array{
+     *     id: string,
+     *     timestamp: string,
+     *     name: string|null,
+     *     input: mixed,
+     *     output: mixed,
+     *     sessionId: string|null,
+     *     release: string|null,
+     *     version: string|null,
+     *     userId: string|null,
+     *     metadata: mixed,
+     *     tags: array<int, string>,
+     *     public: bool|null,
+     *     projectId: string,
+     *     createdAt: string,
+     *     updatedAt: string,
+     *     externalId?: string|null,
+     *     totalCost?: float|null,
+     *     latency?: float|null,
+     *     observations?: array<int, mixed>,
+     *     scores?: array<int, mixed>,
+     *     htmlPath?: string|null,
+     *     environment?: string|null
+     * } $data
+     */
+    public static function fromArray(array $data): self
+    {
+        return new self(
+            id: $data['id'],
+            timestamp: $data['timestamp'],
+            name: $data['name'],
+            input: $data['input'],
+            output: $data['output'],
+            sessionId: $data['sessionId'],
+            release: $data['release'],
+            version: $data['version'],
+            userId: $data['userId'],
+            metadata: $data['metadata'],
+            tags: $data['tags'],
+            public: $data['public'],
+            projectId: $data['projectId'],
+            createdAt: $data['createdAt'],
+            updatedAt: $data['updatedAt'],
+            externalId: $data['externalId'] ?? null,
+            totalCost: $data['totalCost'] ?? null,
+            latency: $data['latency'] ?? null,
+            observations: $data['observations'] ?? [],
+            scores: $data['scores'] ?? [],
+            htmlPath: $data['htmlPath'] ?? null,
+            environment: $data['environment'] ?? null,
+        );
+    }
+}

src/Testing/Responses/GetTraceListResponse.php

@@ -0,0 +1,79 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DIJ\Langfuse\PHP\Testing\Responses;
+
+use GuzzleHttp\Psr7\Response;
+
+class GetTraceListResponse extends Response
+{
+    /**
+     * @param  array<array<string>|string>  $headers
+     */
+    public function __construct(int $status = 200, array $headers = [], string $version = '1.1', ?string $reason = null)
+    {
+        parent::__construct($status, $headers, (string) json_encode($this->payload()), $version, $reason);
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function payload(): array
+    {
+        return [
+            'data' => [
+                [
+                    'id' => 'trace-abc123',
+                    'timestamp' => '2025-01-22T10:30:00.000Z',
+                    'name' => 'test-trace-1',
+                    'input' => ['prompt' => 'Hello, world!'],
+                    'output' => ['response' => 'Hi there!'],
+                    'sessionId' => 'session-xyz789',
+                    'release' => '1.0.0',
+                    'version' => 'v1',
+                    'userId' => 'user-123',
+                    'metadata' => ['key' => 'value'],
+                    'tags' => ['production'],
+                    'public' => false,
+                    'projectId' => 'proj-abc123',
+                    'createdAt' => '2025-01-22T10:30:00.000Z',
+                    'updatedAt' => '2025-01-22T10:30:00.000Z',
+                    'externalId' => null,
+                    'totalCost' => 0.0025,
+                    'latency' => 1.5,
+                    'htmlPath' => '/traces/trace-abc123',
+                    'environment' => 'production',
+                ],
+                [
+                    'id' => 'trace-def456',
+                    'timestamp' => '2025-01-22T09:15:00.000Z',
+                    'name' => 'test-trace-2',
+                    'input' => ['prompt' => 'What is the weather?'],
+                    'output' => ['response' => 'It is sunny.'],
+                    'sessionId' => 'session-abc123',
+                    'release' => '1.0.0',
+                    'version' => 'v1',
+                    'userId' => 'user-456',
+                    'metadata' => null,
+                    'tags' => ['development'],
+                    'public' => true,
+                    'projectId' => 'proj-abc123',
+                    'createdAt' => '2025-01-22T09:15:00.000Z',
+                    'updatedAt' => '2025-01-22T09:15:00.000Z',
+                    'externalId' => 'ext-001',
+                    'totalCost' => 0.0012,
+                    'latency' => 0.8,
+                    'htmlPath' => '/traces/trace-def456',
+                    'environment' => 'development',
+                ],
+            ],
+            'meta' => [
+                'page' => 1,
+                'limit' => 10,
+                'totalPages' => 1,
+                'totalItems' => 2,
+            ],
+        ];
+    }
+}

src/Testing/Responses/GetTraceResponse.php

@@ -0,0 +1,63 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DIJ\Langfuse\PHP\Testing\Responses;
+
+use GuzzleHttp\Psr7\Response;
+
+class GetTraceResponse extends Response
+{
+    /**
+     * @param  array<array<string>|string>  $headers
+     * @param  array<string, mixed>  $data
+     */
+    public function __construct(int $status = 200, array $headers = [], string $version = '1.1', ?string $reason = null, array $data = [])
+    {
+        parent::__construct($status, $headers, (string) json_encode($this->payload($data)), $version, $reason);
+    }
+
+    /**
+     * @param  array<string, mixed>  $data
+     * @return array<string, mixed>
+     */
+    public function payload(array $data = []): array
+    {
+        return array_merge([
+            'id' => 'trace-abc123',
+            'timestamp' => '2025-01-22T10:30:00.000Z',
+            'name' => 'test-trace',
+            'input' => ['prompt' => 'Hello, world!'],
+            'output' => ['response' => 'Hi there!'],
+            'sessionId' => 'session-xyz789',
+            'release' => '1.0.0',
+            'version' => 'v1',
+            'userId' => 'user-123',
+            'metadata' => ['key' => 'value'],
+            'tags' => ['production', 'test'],
+            'public' => false,
+            'projectId' => 'proj-abc123',
+            'createdAt' => '2025-01-22T10:30:00.000Z',
+            'updatedAt' => '2025-01-22T10:30:00.000Z',
+            'externalId' => null,
+            'totalCost' => 0.0025,
+            'latency' => 1.5,
+            'observations' => [
+                [
+                    'id' => 'obs-001',
+                    'name' => 'generation-1',
+                    'type' => 'GENERATION',
+                ],
+            ],
+            'scores' => [
+                [
+                    'id' => 'score-001',
+                    'name' => 'quality',
+                    'value' => 0.95,
+                ],
+            ],
+            'htmlPath' => '/traces/trace-abc123',
+            'environment' => 'production',
+        ], $data);
+    }
+}