File Label Express API

Content-Type: application/json
Accept: application/json
Authorization: Bearer TEMPORARY_TOKEN

{
  "error": [],
  "output": { }
}

{
  "action": "labelData",
  "app": "Records System",
  "data": [
    {
      "last_name": "Morgan",
      "first_name": "Alex",
      "dob": "1985-04-12"
    },
    {
      "last_name": "Rivera",
      "first_name": "Jamie",
      "dob": "1977-11-03"
    }
  ]
}

curl --request POST 'https://filelabel.co/api/' \
  --header 'Content-Type: application/json' \
  --data '{
    "action": "auth",
    "apiKey": "YOUR_API_KEY"
  }'

{
  "error": [],
  "output": {
    "user": {
      "userId": "USER_ID",
      "logged_in": true,
      "token": "TEMPORARY_TOKEN"
    }
  }
}

curl --request POST 'https://filelabel.co/api/' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer TEMPORARY_TOKEN' \
  --data '{
    "action": "labelData",
    "app": "Records System",
    "data": [
      {
        "last_name": "Morgan",
        "first_name": "Alex",
        "dob": "1985-04-12"
      },
      {
        "last_name": "Rivera",
        "first_name": "Jamie",
        "dob": "1977-11-03"
      }
    ]
  }'

https://filelabel.co/preview?project=PROJECT_ID&token=TEMPORARY_TOKEN

<?php
function flxPost(array $parameters, ?string $token = null): array
{
    $handle = curl_init('https://filelabel.co/api/');
    $json = json_encode($parameters, JSON_THROW_ON_ERROR);
    $headers = [
        'Content-Type: application/json',
        'Accept: application/json',
    ];

    if ($token !== null) {
        $headers[] = 'Authorization: Bearer '.$token;
    }

    curl_setopt_array($handle, [
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => $json,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CONNECTTIMEOUT => 10,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_SSL_VERIFYPEER => true,
        CURLOPT_SSL_VERIFYHOST => 2,
        CURLOPT_HTTPHEADER => $headers,
    ]);

    $body = curl_exec($handle);
    if ($body === false) {
        throw new RuntimeException(curl_error($handle));
    }

    $status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
    curl_close($handle);

    if ($status < 200 || $status >= 300) {
        throw new RuntimeException('File Label Express returned HTTP '.$status.'.');
    }

    return json_decode($body, true, 512, JSON_THROW_ON_ERROR);
}

$auth = flxPost([
    'action' => 'auth',
    'apiKey' => getenv('FILELABEL_API_KEY'),
]);

if (!empty($auth['error'])) {
    throw new RuntimeException('File Label Express authentication failed.');
}

$token = $auth['output']['user']['token'];

$result = flxPost([
    'action' => 'labelData',
    'app'    => 'Records System',
    'data'   => [
        [
            'last_name'  => 'Morgan',
            'first_name' => 'Alex',
            'dob'        => '1985-04-12',
        ],
        [
            'last_name'  => 'Rivera',
            'first_name' => 'Jamie',
            'dob'        => '1977-11-03',
        ],
    ],
], $token);

$previewUrl = 'https://filelabel.co/preview?'.http_build_query([
    'project' => 'PROJECT_ID',
    'token'   => $token,
]);

// Redirect the user's browser or return this URL to the client application.
header('Location: '.$previewUrl);

<?php

declare(strict_types=1);

final class Filelabel_API
{
    private const API_URL = 'https://filelabel.co/api/';
    private const PREVIEW_URL = 'https://filelabel.co/preview';

    private string $apiKey;
    private ?string $token;
    private int $timeout;

    public bool $loggedIn = false;

    public function __construct(
        string $apiKey,
        ?string $token = null,
        int $timeout = 30
    ) {
        $apiKey = trim($apiKey);

        if ($apiKey === '') {
            throw new InvalidArgumentException('An API key is required.');
        }

        $this->apiKey = $apiKey;
        $this->token = $token ?: null;
        $this->timeout = max(1, $timeout);
    }

    /** Authenticate the API key and retain the returned temporary token. */
    public function auth(): array
    {
        $output = $this->requestJson([
            'action' => 'auth',
            'apiKey' => $this->apiKey,
        ], false);

        $token = $output['user']['token'] ?? null;

        if (!is_string($token) || $token === '') {
            throw new RuntimeException(
                'Authentication did not return a token.'
            );
        }

        $this->token = $token;
        $this->loggedIn = true;

        return $output['user'];
    }

    /** Check a previously saved token without exposing the API key. */
    public function checkSession(): bool
    {
        if ($this->token === null) {
            return false;
        }

        try {
            $session = $this->getSession();
            $this->loggedIn = !empty($session['logged_in']);
        } catch (RuntimeException $exception) {
            $this->loggedIn = false;
        }

        return $this->loggedIn;
    }

    public function getSession(): array
    {
        $output = $this->requestJson([
            'action' => 'getSession',
        ]);

        if (!isset($output['session']) || !is_array($output['session'])) {
            throw new RuntimeException('No session was returned.');
        }

        return $output['session'];
    }

    public function getProjects(): array
    {
        $output = $this->requestJson([
            'action' => 'getProjects',
        ]);

        return isset($output['projects']) && is_array($output['projects'])
            ? $output['projects']
            : [];
    }

    public function getProjectMeta(string $projectId): array
    {
        return $this->requestJson([
            'action' => 'getProjectMeta',
            'project' => $projectId,
        ]);
    }

    /** Submit one JSON object per label. */
    public function labelData(array $records, ?string $app = null): array
    {
        if ($records === []) {
            throw new InvalidArgumentException(
                'At least one label record is required.'
            );
        }

        foreach ($records as $record) {
            if (!is_array($record)) {
                throw new InvalidArgumentException(
                    'Every label record must be an array.'
                );
            }
        }

        $payload = [
            'action' => 'labelData',
            'data' => array_values($records),
        ];

        if ($app !== null && $app !== '') {
            $payload['app'] = $app;
        }

        return $this->requestJson($payload);
    }

    public function previewUrl(string $projectId, int $offset = 0): string
    {
        return self::PREVIEW_URL.'?'.http_build_query(
            [
                'project' => $projectId,
                'offset' => max(0, $offset),
                'token' => $this->requireToken(),
            ],
            '',
            '&',
            PHP_QUERY_RFC3986
        );
    }

    /** Download a PDF already generated by the preview flow. */
    public function downloadPDF(): string
    {
        [$status, $contentType, $body] = $this->sendJson([
            'action' => 'downloadPDF',
        ], 'application/pdf', true);

        if ($status < 200 || $status >= 300) {
            throw new RuntimeException(
                'File Label Express returned HTTP '.$status.'.'
            );
        }

        if (stripos($contentType, 'application/json') !== false) {
            $this->decodeResponse($body);
        }

        if (strncmp($body, '%PDF', 4) !== 0) {
            throw new RuntimeException(
                'File Label Express did not return a PDF.'
            );
        }

        return $body;
    }

    public function getToken(): ?string
    {
        return $this->token;
    }

    private function requestJson(
        array $payload,
        bool $authorized = true
    ): array
    {
        [$status, $contentType, $body] = $this->sendJson(
            $payload,
            'application/json',
            $authorized
        );

        if ($status < 200 || $status >= 300) {
            throw new RuntimeException(
                'File Label Express returned HTTP '.$status.'.'
            );
        }

        return $this->decodeResponse($body);
    }

    private function sendJson(
        array $payload,
        string $accept = 'application/json',
        bool $authorized = true
    ): array {
        try {
            $json = json_encode(
                $payload,
                JSON_UNESCAPED_SLASHES | JSON_THROW_ON_ERROR
            );
        } catch (JsonException $exception) {
            throw new InvalidArgumentException(
                'The request could not be encoded as JSON.',
                0,
                $exception
            );
        }

        $curl = curl_init(self::API_URL);

        if ($curl === false) {
            throw new RuntimeException('Unable to initialize cURL.');
        }

        $headers = [
            'Content-Type: application/json',
            'Accept: '.$accept,
        ];

        if ($authorized) {
            $headers[] = 'Authorization: Bearer '.$this->requireToken();
        }

        curl_setopt_array($curl, [
            CURLOPT_POST => true,
            CURLOPT_POSTFIELDS => $json,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_CONNECTTIMEOUT => 10,
            CURLOPT_TIMEOUT => $this->timeout,
            CURLOPT_SSL_VERIFYPEER => true,
            CURLOPT_SSL_VERIFYHOST => 2,
            CURLOPT_ENCODING => '',
            CURLOPT_USERAGENT => 'Filelabel_API/1.0',
            CURLOPT_HTTPHEADER => $headers,
        ]);

        $body = curl_exec($curl);
        $status = (int) curl_getinfo($curl, CURLINFO_HTTP_CODE);
        $contentType = (string) curl_getinfo($curl, CURLINFO_CONTENT_TYPE);

        if ($body === false) {
            $message = curl_error($curl);
            curl_close($curl);
            throw new RuntimeException('File Label Express: '.$message);
        }

        curl_close($curl);

        return [$status, $contentType, $body];
    }

    private function decodeResponse(string $body): array
    {
        try {
            $response = json_decode(
                $body,
                true,
                512,
                JSON_THROW_ON_ERROR
            );
        } catch (JsonException $exception) {
            throw new RuntimeException(
                'File Label Express returned invalid JSON.',
                0,
                $exception
            );
        }

        if (!is_array($response)) {
            throw new RuntimeException(
                'File Label Express returned an invalid response.'
            );
        }

        if ($this->hasError($response['error'] ?? null)) {
            throw new RuntimeException(
                'File Label Express: '.
                $this->formatError($response['error'])
            );
        }

        $output = $response['output'] ?? [];

        return is_array($output) ? $output : ['value' => $output];
    }

    private function requireToken(): string
    {
        if ($this->token === null || $this->token === '') {
            throw new LogicException(
                'Authenticate before calling this operation.'
            );
        }

        return $this->token;
    }

    private function hasError($error): bool
    {
        if ($error === null || $error === false || $error === '') {
            return false;
        }

        return !is_array($error) || $error !== [];
    }

    private function formatError($error): string
    {
        if (is_string($error)) {
            return $error;
        }

        $encoded = json_encode($error, JSON_UNESCAPED_SLASHES);

        return $encoded !== false ? $encoded : 'Unknown API error.';
    }
}

session_start();
require_once 'Filelabel_API.php';

$filelabel = new Filelabel_API(
    getenv('FILELABEL_API_KEY'),
    $_SESSION['filelabel_token'] ?? null
);

if (!$filelabel->checkSession()) {
    $filelabel->auth();
    $_SESSION['filelabel_token'] = $filelabel->getToken();
}

$projects = $filelabel->getProjects();
$projectIds = array_keys((array) $projects);

if (!$projectIds) {
    throw new RuntimeException('No label projects are assigned.');
}

$projectId = $projectIds[0];

$filelabel->labelData([
    [
        'last_name'  => 'Morgan',
        'first_name' => 'Alex',
        'dob'        => '1985-04-12',
    ],
    [
        'last_name'  => 'Rivera',
        'first_name' => 'Jamie',
        'dob'        => '1977-11-03',
    ],
], 'Records System');

header('Location: '.$filelabel->previewUrl($projectId));
exit;

{
  "error": {
    "apiKey": "The API key is incorrect."
  },
  "output": []
}