Initial release of the Datalumo PHP client.

Covers Me, Pages, Widgets, Conversations, Identity, and streaming against the current API.

Author: jeffreyvr

.github/workflows/tests.yml

@@ -0,0 +1,32 @@
+name: Tests
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        php: ['8.2', '8.3', '8.4']
+
+    name: PHP ${{ matrix.php }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          coverage: none
+          tools: composer:v2
+
+      - name: Install dependencies
+        run: composer install --prefer-dist --no-interaction --no-progress
+
+      - name: Run tests
+        run: vendor/bin/pest

.gitignore

@@ -0,0 +1,8 @@
+/vendor/
+/composer.lock
+/.phpunit.cache/
+/.phpunit.result.cache
+/.idea/
+/.vscode/
+*.swp
+.DS_Store

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Datalumo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,59 @@
+# datalumo/php
+
+PHP client for the [Datalumo](https://datalumo.app) API.
+
+## Install
+
+```bash
+composer require datalumo/php
+```
+
+Requires PHP 8.2+.
+
+## Quick start
+
+```php
+use Datalumo\Client;
+
+$client = new Client(
+    token: getenv('DATALUMO_TOKEN'),
+    organisation: getenv('DATALUMO_ORG'), // organisation public id, not the slug
+);
+
+// Confirm the token and list sources
+$me = $client->me()->get();
+
+// Push a page (indexing is asynchronous)
+$client->pages('docs')->upsert([
+    'external_id' => 'post-42',
+    'name' => 'Hello',
+    'content' => '# Hello',
+    'content_mime' => 'text/markdown',
+    'source_url' => 'https://example.com/hello',
+]);
+
+// Search via a widget
+$result = $client->widgets($widgetId)->search([
+    'query' => 'how does pricing work',
+    'limit' => 5,
+]);
+
+foreach ($result->data as $hit) {
+    echo $hit->name;
+}
+```
+
+Self-hosted:
+
+```php
+$client = new Client(
+    token: $token,
+    organisation: $orgId,
+    baseUrl: 'https://your-instance.example',
+);
+```
+
+## Next steps
+
+- [API docs](https://datalumo.app/docs)
+- Laravel package: [`datalumo/laravel`](https://github.com/datalumo/laravel)

composer.json

@@ -0,0 +1,50 @@
+{
+    "name": "datalumo/php",
+    "description": "Official PHP client for the Datalumo API",
+    "type": "library",
+    "license": "MIT",
+    "keywords": [
+        "datalumo",
+        "search",
+        "ai",
+        "sdk"
+    ],
+    "authors": [
+        {
+            "name": "Datalumo",
+            "homepage": "https://datalumo.app"
+        }
+    ],
+    "require": {
+        "php": "^8.2",
+        "guzzlehttp/guzzle": "^7.8",
+        "psr/log": "^3.0"
+    },
+    "require-dev": {
+        "laravel/pint": "^1.18",
+        "mockery/mockery": "^1.6",
+        "pestphp/pest": "^3.0"
+    },
+    "autoload": {
+        "psr-4": {
+            "Datalumo\\": "src/"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "Datalumo\\Tests\\": "tests/"
+        }
+    },
+    "scripts": {
+        "test": "pest",
+        "format": "pint"
+    },
+    "config": {
+        "sort-packages": true,
+        "allow-plugins": {
+            "pestphp/pest-plugin": true
+        }
+    },
+    "minimum-stability": "stable",
+    "prefer-stable": true
+}

phpunit.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
+         bootstrap="vendor/autoload.php"
+         colors="true"
+         cacheDirectory=".phpunit.cache"
+>
+    <testsuites>
+        <testsuite name="Datalumo PHP SDK">
+            <directory>tests</directory>
+        </testsuite>
+    </testsuites>
+    <source>
+        <include>
+            <directory>src</directory>
+        </include>
+    </source>
+</phpunit>

src/Client.php

@@ -0,0 +1,57 @@
+<?php
+
+namespace Datalumo;
+
+use Datalumo\Resources\MeResource;
+use Datalumo\Resources\PagesResource;
+use Datalumo\Resources\WidgetsResource;
+
+class Client
+{
+    private HttpClient $http;
+
+    public function __construct(
+        private readonly string $token,
+        private readonly string $organisation,
+        private readonly string $baseUrl = 'https://datalumo.app',
+        ?HttpClientOptions $options = null,
+    ) {
+        $this->http = new HttpClient(
+            baseUrl: $this->baseUrl,
+            organisation: $this->organisation,
+            token: $this->token,
+            options: $options,
+        );
+    }
+
+    public function http(): HttpClient
+    {
+        return $this->http;
+    }
+
+    public function organisation(): string
+    {
+        return $this->organisation;
+    }
+
+    public function baseUrl(): string
+    {
+        return $this->baseUrl;
+    }
+
+    public function me(): MeResource
+    {
+        return new MeResource($this->http);
+    }
+
+    public function pages(string $source): PagesResource
+    {
+        return new PagesResource($this->http, $source);
+    }
+
+    /** @param  string  $widget  Widget public id only, not the org/widget embed key */
+    public function widgets(string $widget): WidgetsResource
+    {
+        return new WidgetsResource($this->http, $widget);
+    }
+}

src/Data/ChatReply.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace Datalumo\Data;
+
+final readonly class ChatReply
+{
+    /**
+     * @param  list<SearchHit>  $sources
+     */
+    public function __construct(
+        public string $text,
+        public ?string $conversationId,
+        public ?string $answerId,
+        public array $sources,
+        public string $sessionId,
+    ) {}
+
+    /**
+     * @param  array<string, mixed>  $payload
+     */
+    public static function fromArray(array $payload): self
+    {
+        $data = $payload['data'] ?? $payload;
+        $sources = array_map(
+            fn (array $hit) => SearchHit::fromArray($hit),
+            $data['sources'] ?? [],
+        );
+
+        return new self(
+            text: (string) ($data['text'] ?? ''),
+            conversationId: isset($data['conversation_id']) ? (string) $data['conversation_id'] : null,
+            answerId: isset($data['answer_id']) ? (string) $data['answer_id'] : null,
+            sources: $sources,
+            sessionId: (string) ($payload['session_id'] ?? $data['session_id'] ?? ''),
+        );
+    }
+}

src/Data/Conversation.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace Datalumo\Data;
+
+final readonly class Conversation
+{
+    public function __construct(
+        public string $conversationId,
+        public ?string $title,
+        public bool $kept,
+        public ?string $lastMessageAt,
+    ) {}
+
+    /**
+     * @param  array<string, mixed>  $data
+     */
+    public static function fromArray(array $data): self
+    {
+        return new self(
+            conversationId: (string) ($data['conversation_id'] ?? ''),
+            title: isset($data['title']) ? (string) $data['title'] : null,
+            kept: (bool) ($data['kept'] ?? false),
+            lastMessageAt: isset($data['last_message_at']) ? (string) $data['last_message_at'] : null,
+        );
+    }
+}

src/Data/ConversationDetail.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace Datalumo\Data;
+
+final readonly class ConversationDetail
+{
+    /**
+     * @param  list<ConversationMessage>  $messages
+     */
+    public function __construct(
+        public string $conversationId,
+        public bool $kept,
+        public array $messages,
+    ) {}
+
+    /**
+     * @param  array<string, mixed>  $payload
+     */
+    public static function fromArray(array $payload): self
+    {
+        $data = $payload['data'] ?? $payload;
+        $messages = array_map(
+            fn (array $message) => ConversationMessage::fromArray($message),
+            $data['messages'] ?? [],
+        );
+
+        return new self(
+            conversationId: (string) ($data['conversation_id'] ?? ''),
+            kept: (bool) ($data['kept'] ?? false),
+            messages: $messages,
+        );
+    }
+}