Feature/comments

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/Comment.php

@@ -0,0 +1,115 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DIJ\Langfuse\PHP;
+
+use DIJ\Langfuse\PHP\Contracts\TransporterInterface;
+use DIJ\Langfuse\PHP\Responses\CommentListResponse;
+use DIJ\Langfuse\PHP\Responses\CommentResponse;
+use JsonException;
+
+class Comment
+{
+    public function __construct(private readonly TransporterInterface $transporter)
+    {
+    }
+
+    /**
+     * @throws JsonException
+     */
+    public function get(string $commentId): CommentResponse
+    {
+        $response = $this->transporter->get(
+            uri: sprintf('/api/public/comments/%s', urlencode($commentId)),
+        );
+
+        /** @var array{
+         *     id: string,
+         *     content: string,
+         *     objectType: string,
+         *     objectId: string,
+         *     authorUserId: string|null,
+         *     createdAt: string,
+         *     updatedAt: string,
+         *     projectId: string
+         * } $data
+         */
+        $data = json_decode($response->getBody()->getContents(), true, flags: JSON_THROW_ON_ERROR);
+
+        return CommentResponse::fromArray($data);
+    }
+
+    /**
+     * @throws JsonException
+     */
+    public function list(
+        ?int $page = null,
+        ?int $limit = null,
+        ?string $objectType = null,
+        ?string $objectId = null,
+        ?string $authorUserId = null,
+    ): CommentListResponse {
+        $response = $this->transporter->get(
+            uri: '/api/public/comments',
+            options: ['query' => array_filter([
+                'page' => $page,
+                'limit' => $limit,
+                'objectType' => $objectType,
+                'objectId' => $objectId,
+                'authorUserId' => $authorUserId,
+            ])]
+        );
+
+        /** @var array{
+         *     data: array<int, array{
+         *         id: string,
+         *         content: string,
+         *         objectType: string,
+         *         objectId: string,
+         *         authorUserId: string|null,
+         *         createdAt: string,
+         *         updatedAt: string,
+         *         projectId: string
+         *     }>,
+         *     meta: array{page: int, limit: int, totalPages: int, totalItems: int}
+         * } $data
+         */
+        $data = json_decode($response->getBody()->getContents(), true, flags: JSON_THROW_ON_ERROR);
+
+        return CommentListResponse::fromArray($data);
+    }
+
+    /**
+     * @throws JsonException
+     */
+    public function create(
+        string $content,
+        string $objectType,
+        string $objectId,
+    ): CommentResponse {
+        $response = $this->transporter->postJson(
+            uri: '/api/public/comments',
+            data: [
+                'content' => $content,
+                'objectType' => $objectType,
+                'objectId' => $objectId,
+            ],
+        );
+
+        /** @var array{
+         *     id: string,
+         *     content: string,
+         *     objectType: string,
+         *     objectId: string,
+         *     authorUserId: string|null,
+         *     createdAt: string,
+         *     updatedAt: string,
+         *     projectId: string
+         * } $data
+         */
+        $data = json_decode($response->getBody()->getContents(), true, flags: JSON_THROW_ON_ERROR);
+
+        return CommentResponse::fromArray($data);
+    }
+}

src/Concerns/IsCompilable.php

@@ -38,7 +38,7 @@ private function compileString(string $prompt, array $data = []): string
         $values = array_values($data);
 
         return str_replace(
-            array_map(fn ($i): string => '{{' . $i . '}}', array_keys($data)),
+            array_map(fn (string $i): string => '{{' . $i . '}}', array_keys($data)),
             $values,
             $prompt
         );

src/Langfuse.php

@@ -37,4 +37,11 @@ public function score(): Score
             transporter: $this->transporter,
         );
     }
+
+    public function comment(): Comment
+    {
+        return new Comment(
+            transporter: $this->transporter,
+        );
+    }
 }

src/Prompt.php

@@ -21,7 +21,8 @@ class Prompt
     public function __construct(
         private readonly TransporterInterface $transporter,
         private readonly string $defaultLabel,
-    ) {}
+    ) {
+    }
 
     /**
      * Retrieve a text prompt by name. Uses default label if no version or label provided.
@@ -49,7 +50,7 @@ public function text(string $promptName, ?int $version = null, ?string $label =
     /**
      * Retrieve a chat prompt by name. Uses default label if no version or label provided.
      *
-     * @param  array<int, array{role: string, content: string}>|null  $fallback
+     * @param array<int, array{role: string, content: string}>|null $fallback
      *
      * @throws InvalidPromptTypeException
      */
@@ -96,10 +97,10 @@ public function list(?string $name = null, ?int $version = null, ?string $label
     /**
      * Create a new prompt.
      *
-     * @param  ($type is PromptType::TEXT ? string : array<int, array{role: string, content: string}>)  $prompt
-     * @param  array<int, string>|null  $labels
-     * @param  array<string, mixed>|null  $config
-     * @param  array<int, string>|null  $tags
+     * @param ($type is PromptType::TEXT ? string : array<int, array{role: string, content: string}>) $prompt
+     * @param array<int, string>|null $labels
+     * @param array<string, mixed>|null $config
+     * @param array<int, string>|null $tags
      * @return ($type is PromptType::TEXT ? TextPromptResponse : ChatPromptResponse)
      *
      * @throws JsonException
@@ -164,7 +165,7 @@ public function create(string $promptName, string|array $prompt, PromptType $typ
     /**
      * Update labels for a specific prompt version.
      *
-     * @param  array<int, string>  $labels
+     * @param array<int, string> $labels
      *
      * @throws JsonException
      */

src/Responses/CommentListResponse.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DIJ\Langfuse\PHP\Responses;
+
+use DIJ\Langfuse\PHP\ValueObjects\MetaData;
+
+readonly class CommentListResponse
+{
+    /**
+     * @param array<int, CommentResponse> $data
+     */
+    public function __construct(
+        public array $data,
+        public MetaData $meta,
+    ) {
+    }
+
+    /**
+     * @param array{
+     *     data: array<int, array{
+     *         id: string,
+     *         content: string,
+     *         objectType: string,
+     *         objectId: string,
+     *         authorUserId: string|null,
+     *         createdAt: string,
+     *         updatedAt: string,
+     *         projectId: string
+     *     }>,
+     *     meta: array{page: int, limit: int, totalPages: int, totalItems: int}
+     * } $data
+     */
+    public static function fromArray(array $data): self
+    {
+        return new self(
+            data: array_map(
+                CommentResponse::fromArray(...),
+                $data['data']
+            ),
+            meta: MetaData::fromArray($data['meta']),
+        );
+    }
+}

src/Responses/CommentResponse.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DIJ\Langfuse\PHP\Responses;
+
+readonly class CommentResponse
+{
+    public function __construct(
+        public string $id,
+        public string $content,
+        public string $objectType,
+        public string $objectId,
+        public ?string $authorUserId,
+        public string $createdAt,
+        public string $updatedAt,
+        public string $projectId,
+    ) {
+    }
+
+    /**
+     * @param array{
+     *     id: string,
+     *     content: string,
+     *     objectType: string,
+     *     objectId: string,
+     *     authorUserId: string|null,
+     *     createdAt: string,
+     *     updatedAt: string,
+     *     projectId: string
+     * } $data
+     */
+    public static function fromArray(array $data): self
+    {
+        return new self(
+            id: $data['id'],
+            content: $data['content'],
+            objectType: $data['objectType'],
+            objectId: $data['objectId'],
+            authorUserId: $data['authorUserId'],
+            createdAt: $data['createdAt'],
+            updatedAt: $data['updatedAt'],
+            projectId: $data['projectId'],
+        );
+    }
+}

src/Responses/FallbackPrompt.php

@@ -11,19 +11,6 @@
 {
     use IsCompilable;
 
-    /**
-     * @param ($type is "text" ? string : array<int, array{role: string, content: string}>) $prompt
-     */
-    public function __construct(
-        string|array $prompt,
-        string $type,
-    ) {
-        parent::__construct(
-            prompt: $prompt,
-            type: $type,
-        );
-    }
-
     /**
      * Create a text fallback prompt
      */

src/Responses/PromptListResponse.php

@@ -30,7 +30,7 @@ public function __construct(
     public static function fromArray(array $data): self
     {
         return new self(
-            data: array_map(fn (array $data): PromptListItem => PromptListItem::fromArray($data), $data['data']),
+            data: array_map(PromptListItem::fromArray(...), $data['data']),
             meta: MetaData::fromArray($data['meta']),
             pagination: PaginationData::fromArray($data['pagination']),
         );

src/Responses/ScoreListResponse.php

@@ -26,7 +26,7 @@ public function __construct(
     public static function fromArray(array $data): self
     {
         return new self(
-            data: array_map(fn (array $item): ScoreResponse => ScoreResponse::fromArray($item), $data['data']),
+            data: array_map(ScoreResponse::fromArray(...), $data['data']),
             meta: MetaData::fromArray($data['meta']),
         );
     }

src/Testing/Responses/GetCommentListResponse.php

@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DIJ\Langfuse\PHP\Testing\Responses;
+
+use GuzzleHttp\Psr7\Response;
+
+class GetCommentListResponse 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' => 'comment-abc123',
+                    'content' => 'First comment',
+                    'objectType' => 'trace',
+                    'objectId' => 'trace-123',
+                    'authorUserId' => 'user-456',
+                    'createdAt' => '2025-01-22T10:00:00.000Z',
+                    'updatedAt' => '2025-01-22T10:00:00.000Z',
+                    'projectId' => 'proj-abc123',
+                ],
+                [
+                    'id' => 'comment-def456',
+                    'content' => 'Second comment',
+                    'objectType' => 'observation',
+                    'objectId' => 'obs-789',
+                    'authorUserId' => null,
+                    'createdAt' => '2025-01-22T09:00:00.000Z',
+                    'updatedAt' => '2025-01-22T09:00:00.000Z',
+                    'projectId' => 'proj-abc123',
+                ],
+            ],
+            'meta' => [
+                'page' => 1,
+                'limit' => 10,
+                'totalPages' => 1,
+                'totalItems' => 2,
+            ],
+        ];
+    }
+}