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	* When $requireIdVerification is true, the recipient must pass PandaDoc
61	* ID Check (government-ID proofing) before they can sign. Callers express
62	* this as a boolean; the implementation owns PandaDoc's verification_settings
63	* wire shape.
64	*
65	* @param array<string, array{value: string}> $fields Field values keyed by field name
66	* @param array<string, string> $tokens Key-value pairs for template tokens
67	* @param string $templateId
68	* @param string $documentName
69	* @param string $recipientEmail
70	* @param string $firstName
71	* @param string $lastName
72	* @param string $recipientRole
73	* @param bool $requireIdVerification
74	*
75	* @throws RuntimeException on API or transport failure
76	*/
77	public function createDocumentFromTemplate(
78	string $templateId,
79	string $documentName,
80	string $recipientEmail,
81	string $firstName,
82	string $lastName,
83	array $fields = [],
84	array $tokens = [],
85	string $recipientRole = 'Signer',
86	bool $requireIdVerification = false,
87	): PandaDocDocumentRefData;
88
89	/**
90	* Get the current status of a document (full PandaDoc form, e.g. `document.draft`).
91	*
92	* @param string $documentId
93	* @throws RuntimeException on API or transport failure
94	*/
95	public function getDocumentStatus(string $documentId): string;
96
97	/**
98	* Send a draft document to its recipients for signing.
99	*
100	* @param string $documentId
101	* @param string $message
102	* @throws RuntimeException on API or transport failure
103	*/
104	public function sendDocument(string $documentId, string $message = 'Please review and sign this document.'): void;
105
106	/**
107	* Download a completed document and return the raw PDF bytes.
108	*
109	* @param string $documentId
110	* @throws RuntimeException on API or transport failure
111	*/
112	public function downloadDocument(string $documentId): string;
113
114	/**
115	* Inspect a template to discover its fields, tokens, and recipient roles.
116	*
117	* Used to verify a template is wired up correctly before sending real
118	* documents through it.
119	*
120	* @param string $templateId
121	* @throws RuntimeException on API or transport failure
122	*/
123	public function inspectTemplate(string $templateId): PandaDocTemplateDetailsData;
124
125	/**
126	* List templates in the workspace as `[id => name]` pairs.
127	*
128	* @throws RuntimeException on API or transport failure
129	* @return array<string, string>
130	*/
131	public function listTemplates(): array;
132	}