# Extension and action examples

<!-- Maintained by scripts/generate-package-readmes.php -->

Use the action functions with records and Data objects supplied by your application.
They pass each argument to the package operation and return its result.

These adapters show container registration. Use the owning package registry when
a contract requires contributor discovery.

Contract adapters wrap an existing implementation. Call their registration function
from your service provider with that implementation; tagged contracts keep their declared tag.
Resolve the backend by its concrete class before registration so the replacement contract
does not resolve itself. Static contract metadata uses one backend class per adapter.

## Contract `Capell\LiveChat\Contracts\LiveChatKnowledgeProvider`

<!-- example: contract Capell\LiveChat\Contracts\LiveChatKnowledgeProvider -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\LiveChat;

final class LiveChatKnowledgeProviderAdapter implements \Capell\LiveChat\Contracts\LiveChatKnowledgeProvider
{
    public function __construct(private readonly \Capell\LiveChat\Contracts\LiveChatKnowledgeProvider $backend) {}

    #[\Override]
    public function documents(\Capell\LiveChat\Models\LiveChatConversation $conversation, \Capell\LiveChat\Models\LiveChatMessage $message): array
    {
        return $this->backend->documents($conversation, $message);
    }
}

function registerLiveChatKnowledgeProviderAdapter(\Capell\LiveChat\Contracts\LiveChatKnowledgeProvider $backend): void
{
    app()->bind(LiveChatKnowledgeProviderAdapter::class, static fn (): LiveChatKnowledgeProviderAdapter => new LiveChatKnowledgeProviderAdapter($backend));
    app()->bind(\Capell\LiveChat\Contracts\LiveChatKnowledgeProvider::class, LiveChatKnowledgeProviderAdapter::class);
    app()->tag([LiveChatKnowledgeProviderAdapter::class], \Capell\LiveChat\Contracts\LiveChatKnowledgeProvider::TAG);
}
```

## Contract `Capell\LiveChat\Contracts\LiveChatResponder`

<!-- example: contract Capell\LiveChat\Contracts\LiveChatResponder -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\LiveChat;

final class LiveChatResponderAdapter implements \Capell\LiveChat\Contracts\LiveChatResponder
{
    public function __construct(private readonly \Capell\LiveChat\Contracts\LiveChatResponder $backend) {}

    #[\Override]
    public function respond(\Capell\LiveChat\Models\LiveChatConversation $conversation, \Capell\LiveChat\Models\LiveChatMessage $message): \Capell\LiveChat\Data\LiveChatResponseData
    {
        return $this->backend->respond($conversation, $message);
    }
}

function registerLiveChatResponderAdapter(\Capell\LiveChat\Contracts\LiveChatResponder $backend): void
{
    app()->bind(LiveChatResponderAdapter::class, static fn (): LiveChatResponderAdapter => new LiveChatResponderAdapter($backend));
    app()->bind(\Capell\LiveChat\Contracts\LiveChatResponder::class, LiveChatResponderAdapter::class);
}
```

## Contract `Capell\LiveChat\Contracts\LiveChatWidgetRenderer`

<!-- example: contract Capell\LiveChat\Contracts\LiveChatWidgetRenderer -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\LiveChat;

final class LiveChatWidgetRendererAdapter implements \Capell\LiveChat\Contracts\LiveChatWidgetRenderer
{
    public function __construct(private readonly \Capell\LiveChat\Contracts\LiveChatWidgetRenderer $backend) {}

    #[\Override]
    public function render(): \Symfony\Component\HttpFoundation\Response
    {
        return $this->backend->render();
    }
}

function registerLiveChatWidgetRendererAdapter(\Capell\LiveChat\Contracts\LiveChatWidgetRenderer $backend): void
{
    app()->bind(LiveChatWidgetRendererAdapter::class, static fn (): LiveChatWidgetRendererAdapter => new LiveChatWidgetRendererAdapter($backend));
    app()->bind(\Capell\LiveChat\Contracts\LiveChatWidgetRenderer::class, LiveChatWidgetRendererAdapter::class);
}
```

## Action `buildLiveChatAnalytics`

<!-- example: action buildLiveChatAnalytics -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\LiveChat;

function runBuildLiveChatAnalytics(int $siteId, ?int $installationId = null): array
{
    return \Capell\LiveChat\Actions\BuildLiveChatAnalyticsAction::run($siteId, $installationId);
}
```

## Action `buildLiveChatOperatorState`

<!-- example: action buildLiveChatOperatorState -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\LiveChat;

function runBuildLiveChatOperatorState(\Capell\LiveChat\Models\LiveChatConversation $conversation): array
{
    return \Capell\LiveChat\Actions\BuildLiveChatOperatorStateAction::run($conversation);
}
```

## Action `buildLiveChatSuggestedReply`

<!-- example: action buildLiveChatSuggestedReply -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\LiveChat;

function runBuildLiveChatSuggestedReply(\Capell\LiveChat\Models\LiveChatConversation $conversation, ?array $state = null): string
{
    return \Capell\LiveChat\Actions\BuildLiveChatSuggestedReplyAction::run($conversation, $state);
}
```

## Action `buildLiveChatTranscript`

<!-- example: action buildLiveChatTranscript -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\LiveChat;

function runBuildLiveChatTranscript(\Capell\LiveChat\Models\LiveChatConversation $conversation): array
{
    return \Capell\LiveChat\Actions\BuildLiveChatTranscriptAction::run($conversation);
}
```

## Action `buildLiveChatWidgetConfig`

<!-- example: action buildLiveChatWidgetConfig -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\LiveChat;

function runBuildLiveChatWidgetConfig(?\Capell\LiveChat\Models\LiveChatInstallation $installation = null): \Capell\LiveChat\Data\LiveChatWidgetConfigData
{
    return \Capell\LiveChat\Actions\BuildLiveChatWidgetConfigAction::run($installation);
}
```

## Action `closeLiveChatConversation`

<!-- example: action closeLiveChatConversation -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\LiveChat;

function runCloseLiveChatConversation(\Capell\LiveChat\Models\LiveChatConversation $conversation): \Capell\LiveChat\Models\LiveChatConversation
{
    return \Capell\LiveChat\Actions\CloseLiveChatConversationAction::run($conversation);
}
```

## Action `detectLiveChatIntent`

<!-- example: action detectLiveChatIntent -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\LiveChat;

function runDetectLiveChatIntent(string $message): \Capell\LiveChat\Enums\LiveChatIntent
{
    return \Capell\LiveChat\Actions\DetectLiveChatIntentAction::run($message);
}
```

## Action `determineLiveChatEscalation`

<!-- example: action determineLiveChatEscalation -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\LiveChat;

function runDetermineLiveChatEscalation(\Capell\LiveChat\Models\LiveChatConversation $conversation, \Capell\LiveChat\Models\LiveChatMessage $message, \Capell\LiveChat\Data\LiveChatResponseData $response, bool $available): \Capell\LiveChat\Data\LiveChatEscalationDecisionData
{
    return \Capell\LiveChat\Actions\DetermineLiveChatEscalationAction::run($conversation, $message, $response, $available);
}
```

## Action `generateLiveChatSummary`

<!-- example: action generateLiveChatSummary -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\LiveChat;

function runGenerateLiveChatSummary(\Capell\LiveChat\Models\LiveChatConversation $conversation): array
{
    return \Capell\LiveChat\Actions\GenerateLiveChatSummaryAction::run($conversation);
}
```

## Action `guardLiveChatInstallationOrigin`

<!-- example: action guardLiveChatInstallationOrigin -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\LiveChat;

function runGuardLiveChatInstallationOrigin(\Capell\LiveChat\Models\LiveChatInstallation $installation, \Illuminate\Http\Request $request): string
{
    return \Capell\LiveChat\Actions\GuardLiveChatInstallationOriginAction::run($installation, $request);
}
```

## Action `guardLiveChatSameSiteRequest`

<!-- example: action guardLiveChatSameSiteRequest -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\LiveChat;

function runGuardLiveChatSameSiteRequest(\Capell\LiveChat\Models\LiveChatInstallation $installation, \Illuminate\Http\Request $request): void
{
    \Capell\LiveChat\Actions\GuardLiveChatSameSiteRequestAction::run($installation, $request);
}
```

## Action `indexLiveChatKnowledgeDocument`

<!-- example: action indexLiveChatKnowledgeDocument -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\LiveChat;

function runIndexLiveChatKnowledgeDocument(\Capell\LiveChat\Data\LiveChatKnowledgeDocumentData $data): \Capell\LiveChat\Models\LiveChatKnowledgeDocument
{
    return \Capell\LiveChat\Actions\IndexLiveChatKnowledgeDocumentAction::run($data);
}
```

## Action `indexLiveChatKnowledgeSource`

<!-- example: action indexLiveChatKnowledgeSource -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\LiveChat;

function runIndexLiveChatKnowledgeSource(\Capell\LiveChat\Models\LiveChatKnowledgeSource $source, ?int $installationId = null): ?\Capell\LiveChat\Models\LiveChatKnowledgeDocument
{
    return \Capell\LiveChat\Actions\IndexLiveChatKnowledgeSourceAction::run($source, $installationId);
}
```

## Action `recordLiveChatAIRun`

<!-- example: action recordLiveChatAIRun -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\LiveChat;

function runRecordLiveChatAIRun(\Capell\LiveChat\Data\LiveChatAIRunData $data): \Capell\LiveChat\Models\LiveChatAIRun
{
    return \Capell\LiveChat\Actions\RecordLiveChatAIRunAction::run($data);
}
```

## Action `recordLiveChatKnowledgeGap`

<!-- example: action recordLiveChatKnowledgeGap -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\LiveChat;

function runRecordLiveChatKnowledgeGap(string $question, ?int $installationId = null, ?int $conversationId = null, ?int $messageId = null, ?string $sourceArea = null, array $metadata = []): \Capell\LiveChat\Models\LiveChatKnowledgeGap
{
    return \Capell\LiveChat\Actions\RecordLiveChatKnowledgeGapAction::run($question, $installationId, $conversationId, $messageId, $sourceArea, $metadata);
}
```

## Action `replyToLiveChatMessage`

<!-- example: action replyToLiveChatMessage -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\LiveChat;

function runReplyToLiveChatMessage(\Capell\LiveChat\Models\LiveChatConversation $conversation, \Capell\LiveChat\Models\LiveChatMessage $message): \Capell\LiveChat\Models\LiveChatMessage
{
    return \Capell\LiveChat\Actions\ReplyToLiveChatMessageAction::run($conversation, $message);
}
```

## Action `requestLiveChatHandoff`

<!-- example: action requestLiveChatHandoff -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\LiveChat;

function runRequestLiveChatHandoff(\Capell\LiveChat\Models\LiveChatConversation $conversation, ?string $note = null): \Capell\LiveChat\Models\LiveChatConversation
{
    return \Capell\LiveChat\Actions\RequestLiveChatHandoffAction::run($conversation, $note);
}
```

## Action `resolveLiveChatAvailability`

<!-- example: action resolveLiveChatAvailability -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\LiveChat;

function runResolveLiveChatAvailability(int $siteId, ?\Carbon\CarbonImmutable $at = null, ?string $timezone = null): \Capell\LiveChat\Data\LiveChatAvailabilityData
{
    return \Capell\LiveChat\Actions\ResolveLiveChatAvailabilityAction::run($siteId, $at, $timezone);
}
```

## Action `resolveLiveChatConversationForInstallation`

<!-- example: action resolveLiveChatConversationForInstallation -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\LiveChat;

function runResolveLiveChatConversationForInstallation(\Capell\LiveChat\Models\LiveChatInstallation $installation, string $uuid, ?string $visitorToken): \Capell\LiveChat\Models\LiveChatConversation
{
    return \Capell\LiveChat\Actions\ResolveLiveChatConversationForInstallationAction::run($installation, $uuid, $visitorToken);
}
```

## Action `resolveLiveChatInstallation`

<!-- example: action resolveLiveChatInstallation -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\LiveChat;

function runResolveLiveChatInstallation(?string $publicKey = null, ?int $siteId = null): ?\Capell\LiveChat\Models\LiveChatInstallation
{
    return \Capell\LiveChat\Actions\ResolveLiveChatInstallationAction::run($publicKey, $siteId);
}
```

## Action `searchLiveChatKnowledgeDocuments`

<!-- example: action searchLiveChatKnowledgeDocuments -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\LiveChat;

function runSearchLiveChatKnowledgeDocuments(\Capell\LiveChat\Models\LiveChatConversation $conversation, \Capell\LiveChat\Models\LiveChatMessage $message, int $limit = 3): array
{
    return \Capell\LiveChat\Actions\SearchLiveChatKnowledgeDocumentsAction::run($conversation, $message, $limit);
}
```

## Action `startLiveChatConversation`

<!-- example: action startLiveChatConversation -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\LiveChat;

function runStartLiveChatConversation(\Capell\LiveChat\Data\IncomingLiveChatMessageData $data, int $siteId, ?\Capell\LiveChat\Models\LiveChatInstallation $installation = null): array
{
    return \Capell\LiveChat\Actions\StartLiveChatConversationAction::run($data, $siteId, $installation);
}
```

## Action `storeLiveChatAttachments`

<!-- example: action storeLiveChatAttachments -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\LiveChat;

function runStoreLiveChatAttachments(array $files, string $conversationUuid): array
{
    return \Capell\LiveChat\Actions\StoreLiveChatAttachmentsAction::run($files, $conversationUuid);
}
```

## Action `storeLiveChatMessage`

<!-- example: action storeLiveChatMessage -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\LiveChat;

function runStoreLiveChatMessage(\Capell\LiveChat\Models\LiveChatConversation $conversation, \Capell\LiveChat\Data\IncomingLiveChatMessageData $data): array
{
    return \Capell\LiveChat\Actions\StoreLiveChatMessageAction::run($conversation, $data);
}
```

## Action `suggestLiveChatHumanReply`

<!-- example: action suggestLiveChatHumanReply -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\LiveChat;

function runSuggestLiveChatHumanReply(\Capell\LiveChat\Models\LiveChatConversation $conversation): array
{
    return \Capell\LiveChat\Actions\SuggestLiveChatHumanReplyAction::run($conversation);
}
```

## Action `syncLiveChatConversationContact`

<!-- example: action syncLiveChatConversationContact -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\LiveChat;

function runSyncLiveChatConversationContact(\Capell\LiveChat\Models\LiveChatConversation $conversation, ?string $leadTitle = null): ?\Capell\Contacts\Data\ContactSourceSyncResultData
{
    return \Capell\LiveChat\Actions\SyncLiveChatConversationContactAction::run($conversation, $leadTitle);
}
```