1	<?php
2
3	declare(strict_types=1);
4
5	namespace App\Domain\Document\Service;
6
7	use App\Domain\Document\Data\PandaDocDocumentData;
8	use App\Domain\Document\Data\PandaDocDocumentRefData;
9	use App\Domain\Document\Data\PandaDocSigningSessionData;
10	use App\Domain\Document\Data\PandaDocTemplateDetailsData;
11	use RuntimeException;
12
13	/**
14	* Domain-shaped contract for talking to PandaDoc.
15	*
16	* The interface exists so application code (Actions, Services) depends only
17	* on our DTOs and never on PandaDoc's wire shape. All field-name translation
18	* lives in the implementation, which means a PandaDoc API rename touches
19	* exactly one file. It also lets tests substitute a fake client without
20	* hitting the live PandaDoc API.
21	*
22	* Implementations throw {@see RuntimeException} for any non-2xx response or
23	* transport failure; callers decide whether to surface or fall back.
24	*/
25	interface PandaDocClientInterface
26	{
27	/**
28	* Fetch full details for a single document.
29	*
30	* @param string $documentId
31	* @throws RuntimeException on API or transport failure
32	*/
33	public function getDocumentDetails(string $documentId): PandaDocDocumentData;
34
35	/**
36	* Create an embedded-signing session for a recipient and return the
37	* browser-facing signing URL.
38	*
39	* @param string $documentId
40	* @param string $recipientEmail
41	* @throws RuntimeException on API or transport failure
42	*/
43	public function createSigningSession(string $documentId, string $recipientEmail): PandaDocSigningSessionData;
44
45	/**
46	* Resend a document to its recipients.
47	*
48	* @param string $documentId
49	* @param ?string $message
50	* @throws RuntimeException on API or transport failure
51	*/
52	public function resendDocument(string $documentId, ?string $message = null): void;
53
54	/**
55	* Create a document from a PandaDoc template.
56	*
57	* The recipient role must match a role defined on the template
58	* (e.g. "Signer", "Client") — discoverable via {@see inspectTemplate()}.
59	*
60	* @param array<string, array{value: string}> $fields Field values keyed by field name
61	* @param array<string, string> $tokens Key-value pairs for template tokens
62	* @param string $templateId
63	* @param string $documentName
64	* @param string $recipientEmail
65	* @param string $firstName
66	* @param string $lastName
67	* @param string $recipientRole
68	*
69	* @throws RuntimeException on API or transport failure
70	*/
71	public function createDocumentFromTemplate(
72	string $templateId,
73	string $documentName,
74	string $recipientEmail,
75	string $firstName,
76	string $lastName,
77	array $fields = [],
78	array $tokens = [],
79	string $recipientRole = 'Signer',
80	): PandaDocDocumentRefData;
81
82	/**
83	* Get the current status of a document (full PandaDoc form, e.g. `document.draft`).
84	*
85	* @param string $documentId
86	* @throws RuntimeException on API or transport failure
87	*/
88	public function getDocumentStatus(string $documentId): string;
89
90	/**
91	* Send a draft document to its recipients for signing.
92	*
93	* @param string $documentId
94	* @param string $message
95	* @throws RuntimeException on API or transport failure
96	*/
97	public function sendDocument(string $documentId, string $message = 'Please review and sign this document.'): void;
98
99	/**
100	* Download a completed document and return the raw PDF bytes.
101	*
102	* @param string $documentId
103	* @throws RuntimeException on API or transport failure
104	*/
105	public function downloadDocument(string $documentId): string;
106
107	/**
108	* Inspect a template to discover its fields, tokens, and recipient roles.
109	*
110	* Used to verify a template is wired up correctly before sending real
111	* documents through it.
112	*
113	* @param string $templateId
114	* @throws RuntimeException on API or transport failure
115	*/
116	public function inspectTemplate(string $templateId): PandaDocTemplateDetailsData;
117
118	/**
119	* List templates in the workspace as `[id => name]` pairs.
120	*
121	* @throws RuntimeException on API or transport failure
122	* @return array<string, string>
123	*/
124	public function listTemplates(): array;
125	}