Contracts API¶

namespace NextPDF\Core\Contracts;

/**
 * 文件渲染器的統一介面。
 * Artisan、Gotenberg、Cloudflare 均實作此介面。
 */
interface RendererInterface
{
    /**
     * @return non-empty-string PDF 二進位資料
     * @throws RenderingException
     */
    public function render(RenderRequest $request): string;

    /** 渲染器識別碼（如 'artisan-chrome'、'gotenberg'）*/
    public function identifier(): string;
}

/** 文字預處理器（敏感文字過濾、轉換等）*/
interface TextPreprocessorInterface
{
    /** @param array<string, mixed> $context */
    public function process(string $text, array $context): ?string;
    public function priority(): int;
}

/** 字型提供者（允許替換字型載入策略）*/
interface FontProviderInterface
{
    /** @return non-empty-string 字型二進位資料 */
    public function load(string $alias): string;
    public function supports(string $alias): bool;
}

/** Spectrum 加速引擎的 PHP 側介面 */
interface AcceleratorInterface
{
    public function isAvailable(): bool;
    public function shapingEngine(): ShapingEngineInterface;
    public function imageCompressor(): ImageCompressorInterface;
}

/** JWT 簽章（Spectrum Client 使用）*/
interface JwtMinterInterface
{
    /** @return non-empty-string JWT 字串 */
    public function mint(array $claims): string;
}

/** 簽章提供者（支援本地憑證或 HSM 替換）*/
interface SignatureProviderInterface
{
    /**
     * @param non-empty-string $hash     SHA-256 / SHA-384 雜湊值（hex）
     * @param 'sha256'|'sha384'|'sha512' $algorithm
     * @return non-empty-string DER 編碼的簽章值
     */
    public function sign(string $hash, string $algorithm): string;

    /** 取得 DER 編碼的憑證 */
    public function certificate(): string;

    /** 取得憑證鏈（DER 編碼，從葉憑證到根憑證）*/
    public function certificateChain(): list<string>;
}

/** 時間戳記提供者（TSA 連接）*/
interface TimestampProviderInterface
{
    /**
     * @param non-empty-string $hash     要蓋章的資料雜湊值
     * @return non-empty-string TSTInfo DER 編碼
     */
    public function timestamp(string $hash): string;
}

/** 撤銷資料提供者（OCSP / CRL）*/
interface RevocationProviderInterface
{
    public function getOcspResponse(string $certificateDer): string;
    public function getCrl(string $distributionPointUrl): string;
}

/** PDF 輸出接收器（檔案、串流、記憶體等）*/
interface OutputSinkInterface
{
    /** @param non-empty-string $data */
    public function write(string $data): void;
    public function close(): void;
}

/** 向量資料庫接收器（RAG 索引用，Enterprise）*/
interface VectorStoreSinkInterface
{
    public function upsert(string $id, array $vector, array $metadata): void;
    public function query(array $vector, int $topK, array $filters): list<VectorResult>;
}

/** 指標記錄（Prometheus、Datadog 等）*/
interface MetricsCollectorInterface
{
    public function recordRenderTime(float $seconds, array $labels): void;
    public function recordMemoryPeak(int $bytes): void;
    public function incrementCounter(string $name, array $labels = []): void;
}

namespace NextPDF\Core\Contracts;

/** 文件合規等級 */
enum ComplianceProfile: string
{
    case PDF_2_0    = 'pdf-2.0';
    case PDF_A_1B   = 'pdf-a-1b';
    case PDF_A_2B   = 'pdf-a-2b';
    case PDF_A_3B   = 'pdf-a-3b';
    case PDF_A_4    = 'pdf-a-4';
    case PDF_UA_1   = 'pdf-ua-1';
    case PDF_UA_2   = 'pdf-ua-2';
}

/** 簽章等級 */
enum SignatureLevel: string
{
    case PADES_B_B   = 'pades-b-b';
    case PADES_B_T   = 'pades-b-t';
    case PADES_B_LT  = 'pades-b-lt';
    case PADES_B_LTA = 'pades-b-lta';
}

/** 渲染引擎 */
enum RenderEngine: string
{
    case CORE_PHP   = 'core-php';
    case SPECTRUM   = 'spectrum';
    case PRISMA_PRO = 'prisma-pro';
    case PRISMA_ENT = 'prisma-enterprise';
}

/** 圖像格式 */
enum ImageFormat: string
{
    case JPEG  = 'jpeg';
    case PNG   = 'png';
    case WEBP  = 'webp';
    case GIF   = 'gif';
    case BMP   = 'bmp';
    case JBIG2 = 'jbig2';
    case JP2   = 'jpeg2000';
}

/** 渲染請求的標準化格式 */
final readonly class RenderRequest
{
    public function __construct(
        public readonly string  $sourceType,    // 'html' | 'url' | 'file'
        public readonly string  $source,
        public readonly array   $options,
    ) {}
}

/** 向量搜尋結果 */
final readonly class VectorResult
{
    public readonly string $id;
    public readonly float  $score;      // 相似度分數（0.0–1.0）
    public readonly array  $metadata;
    public readonly string $text;       // 原始文字片段
}