retech/sign-me

Celest Sign me SDK

v0.2.2 2024-04-23 02:34 UTC

Requires

• php: ^8.1
• symfony/http-client: ^7.0

MIT

README

Handle your SignMe-requests in a human-digestible way. The goal is to make it feel like working with local models.

SignMe is a signature service targeted at integrators, rather than a pure UI-solution like most competitors.

Status: Private BETA. Please do not use in production yet

Example

use Retech\Celest\SignMe\SignMeClient;

$sdk = (new SignMeClient())->authenticate();

// create a new document to sign
$newDocument = $sdk->uploadDocument('SDK upload','path/contracts/max-hunter-lease-agreement.pdf');

// add Signatory
$signatoryMax = $newDocument->addSignatory('my-reference-c9d9b8b8', 'Max Hunter', '[e-mail]');

// create field on page 4
$signatureField = $signatoryMax->addField('Please sign here', 4);

// move field in position using percentages
$signatureField->setX(53.3);
$signatureField->setY(40);

// you can set width/height as well
$signatureField->setHeight(7);

// send changes to API
$signatureField->update();

// and then some pseudo-code to get the picture
$email = new MyEmailClientWrapper();
$email->to('Max Hunter', '[e-mail]');
$email->body('Hi Max. Please sign this: ' . $signatoryMax->getSignatureLink());
$email->send();

Installation

composer require retech/sign-me

Usage

This package is a one-stop solution for all your remote signMe needs. It's functionality can be divided into three categories:

• api
• easy objects
• webhook reader

pure API

In order to use the public REST-API, method-wrappers simplify your calls. All of these methods return the result as assoc-array on success and throw the Exception Retech\Celest\SignMe\Exceptions\ConnectionException when things go wrong.

authenticate

argument	type	required
$clientId	string	no (reads from env)
$apiKey	string	no (reads from env)

The method establishes authentication using the environment variables SIGN_ME_CLIENT_ID and SIGN_ME_API_KEY. Alternatively, you can pass in your clientId & ApiKey directly.

$client = new SignMeClient();
$client->authenticate();

get

argument	type	required
$url	string	yes

Execute GET-calls against the base-uri https://sign.celest.services/api/

$myDocument = $client->get('documents/123-123-123-1231-123123123');

post

argument	type	required
$url	string	yes
$payload	array	no

Execute POST-calls against the base-uri https://sign.celest.services/api/

$myReference = 'user-123-345-523-93645'
$newSignatory = $client->post('signature/123-123-123-1231-123123123', [
    'signerHash' => $myReference,
    'signerEmail' => '[e-mail]'
]);

put

argument	type	required
$url	string	yes
$payload	array	yes

Execute PUT-calls against the base-uri https://sign.celest.services/api/

$webHookUrl = 'https://webhook.your-domain.com?mydocId=1023'
$updatedDoc = $client->put('documents/123-123-123-1231-123123123', [
    'webhookUrl' => $webHookUrl
]);

delete

argument	type	required
$url	string	yes

Execute DELETE-calls against the base-uri https://sign.celest.services/api/

$success = $client->delete('documents/123-123-123-1231-123123123');

Easy Objects (OO)

Other than managing your transactions and company-settings, the use-case of the signMe API is predictable enough to make your day-to-day life easier with our object oriented interaction possibilities.

getDocuments

argument	type	required
$page	int	no (defaults to 1)

$documents = $client->getDocuments();
$totalPages = $documents['pages']; // e.g. 3
$allDocumentCount = $documents['total'] // e.g. 127
$newestDocument = $documents[documents][0] // Document (see Entities)

getDocument

argument	type	required
$documentSlug	string	yes

$myDocument = $client->getDocument('d3373e45-f7bd-43dc-b48e-db5bca1a5493'); // Document (see Entities)

uploadDocument

argument	type	required
$name	string	yes
$filePath	string	yes

Currently accepts PDF & DOCX only

$myDocument = $client->uploadDocument('Mike\'s car sale', __DIR__ . '/file.php'); // Document (see Entities)

Entities

Document

• getDownloadUrl(): null|string
• getDownloadUrl(): null|string
• getFinalInstructions(): null|string
• setFinalInstructions(finalInstructions: null|string): void
• getWebhookUrl(): null|string
• setWebhookUrl(webhookUrl: null|string): void
• getSlug(): string
• getName(): string
• getRequesterHash(): string
• getFields(): array
• getSignatures(): array
• getSignature(signerHash: string): null|Signature
• addSignatory(signerHash: string, [signerName: null|string = null], [signerEmail: null|string = null]): Signature
• update(): Document

Signature

• fields: array = [...]
• documentSlug: string
• getSignerHash(): string
• getSignerName(): null|string
• getSignerEmail(): null|string
• getIp(): null|string
• getSignedAt(): DateTimeImmutable|null
• isSigned(): bool
• setSignerName(signerName: null|string): void
• setSignerEmail(signerEmail: null|string): void
• addField(label: string, [page: int = 1], [type: string = 'signature']): Field
• getSignatureLink(): string

Field

• setType(type: string): void
• setSignerHash(signerHash: string): void
• setPage(page: int): void
• setX(x: float): void
• setY(y: float): void
• setWidth(width: float): void
• setHeight(height: float): void
• setLabel(label: null|string): void
• getLabel(): null|string
• getHeight(): float
• getWidth(): float
• getY(): float
• getX(): float
• getPage(): int
• getSignerHash(): string
• getType(): string
• update(): Field
• delete(): void

Webhook Reader

Lastly, let's have a quick look at the webhook validation tool included in this package

$webHook = new Retech\Celest\SignMe\WebHookValidator($mySignatureSecret);
try{
    $webHook->validate();
} catch (WebhookValidationException $e){
    // malicious!! 
}

// readonly properties (available after validate() or parse())

$event = $webHook->event; // Retech\Celest\SignMe\Enums\Event e.g Event::UPDATE
$entity = $webHook->entity; // Retech\Celest\SignMe\Enums\Entity e.g. Entity::DOCUMENT
$slug = $webHook->slug;

// payload
$payload = $webHook->parse();

if($webHook->entity === Entity::DOCUMENT && $payload->isCompleted()){
    // all signatures are valid
} elseif ($webHook->entity === Entity::DOCUMENT) {
    // apparently some signatures are outstanding
    $signatures = $payload->getSignatures(); // e.g. [['ip' => null, 'time' => null, 'signerHash' => '123-123-123-k']]
    ...
    // or let's get the doc
    $sdk = (new SignMeClient())->authenticate();
    $document = $sdk->getDocument($webHook->slug);
    ...
    
}

Support

Before the official release, no public support is provided.

License

MIT