feat(interfaces): add comprehensive TypeScript interface modules, demo data, docs, and publish metadata
This commit is contained in:
502
ts_interfaces/pdf.ts
Normal file
502
ts_interfaces/pdf.ts
Normal file
@@ -0,0 +1,502 @@
|
||||
/**
|
||||
* @file pdf.ts
|
||||
* @description PDF generation configuration interfaces
|
||||
* Templates, branding, layout, headers/footers, and security
|
||||
*/
|
||||
|
||||
import * as plugins from './plugins.js';
|
||||
import type {
|
||||
TPageSize,
|
||||
TPageOrientation,
|
||||
THeaderFooterContentType,
|
||||
TPageNumberFormat,
|
||||
TPdfEncryptionAlgorithm,
|
||||
TPdfPrintingPermission,
|
||||
TPdfJobStatus,
|
||||
} from './types.js';
|
||||
|
||||
// ============================================================================
|
||||
// FONT CONFIGURATION
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* Font configuration
|
||||
*/
|
||||
export interface IFontConfig {
|
||||
family: string;
|
||||
fallback: string[];
|
||||
size: number;
|
||||
lineHeight: number;
|
||||
weight?: 'normal' | 'bold' | number;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// BRANDING
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* Logo configuration
|
||||
*/
|
||||
export interface ILogoConfig {
|
||||
url: string;
|
||||
position: 'left' | 'center' | 'right';
|
||||
maxWidth: number;
|
||||
maxHeight: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Watermark configuration
|
||||
*/
|
||||
export interface IWatermarkConfig {
|
||||
text?: string;
|
||||
imageUrl?: string;
|
||||
opacity: number;
|
||||
position: 'center' | 'diagonal';
|
||||
showOnlyOnDraft: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Branding configuration for PDF
|
||||
*/
|
||||
export interface IPdfBranding {
|
||||
logo?: ILogoConfig;
|
||||
primaryColor: string;
|
||||
secondaryColor: string;
|
||||
textColor: string;
|
||||
fonts: {
|
||||
heading: IFontConfig;
|
||||
body: IFontConfig;
|
||||
monospace?: IFontConfig;
|
||||
};
|
||||
watermark?: IWatermarkConfig;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// LAYOUT
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* Custom page size
|
||||
*/
|
||||
export interface ICustomPageSize {
|
||||
width: number;
|
||||
height: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Page margins
|
||||
*/
|
||||
export interface IPageMargins {
|
||||
top: number;
|
||||
right: number;
|
||||
bottom: number;
|
||||
left: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* PDF layout configuration
|
||||
*/
|
||||
export interface IPdfLayout {
|
||||
pageSize: TPageSize;
|
||||
customSize?: ICustomPageSize;
|
||||
orientation: TPageOrientation;
|
||||
margins: IPageMargins;
|
||||
columns: 1 | 2;
|
||||
columnGap?: number;
|
||||
paragraphSpacing: number;
|
||||
sectionSpacing: number;
|
||||
firstPageDifferent: boolean;
|
||||
firstPageMargins?: IPageMargins;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// HEADER/FOOTER
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* Header/Footer content definition
|
||||
*/
|
||||
export interface IPdfHeaderFooterContent {
|
||||
type: THeaderFooterContentType;
|
||||
text?: string;
|
||||
imageUrl?: string;
|
||||
pageNumberFormat?: TPageNumberFormat;
|
||||
pageNumberPrefix?: string;
|
||||
includeTotal?: boolean;
|
||||
dateFormat?: string;
|
||||
customTemplate?: string;
|
||||
fontSize?: number;
|
||||
fontWeight?: 'normal' | 'bold';
|
||||
color?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Header/Footer configuration
|
||||
*/
|
||||
export interface IPdfHeaderFooter {
|
||||
enabled: boolean;
|
||||
height: number;
|
||||
left?: IPdfHeaderFooterContent;
|
||||
center?: IPdfHeaderFooterContent;
|
||||
right?: IPdfHeaderFooterContent;
|
||||
borderBottom?: boolean;
|
||||
borderTop?: boolean;
|
||||
borderColor?: string;
|
||||
skipFirstPage: boolean;
|
||||
skipLastPage: boolean;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// PAGE NUMBERING
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* Page numbering configuration
|
||||
*/
|
||||
export interface IPdfPageNumbering {
|
||||
enabled: boolean;
|
||||
startFrom: number;
|
||||
format: TPageNumberFormat;
|
||||
position: 'header' | 'footer';
|
||||
alignment: 'left' | 'center' | 'right';
|
||||
prefix?: string;
|
||||
suffix?: string;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// CONTENT OPTIONS
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* Table of contents configuration
|
||||
*/
|
||||
export interface ITocConfig {
|
||||
enabled: boolean;
|
||||
depth: number;
|
||||
title: string;
|
||||
pageBreakAfter: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Cover page configuration
|
||||
*/
|
||||
export interface ICoverPageConfig {
|
||||
enabled: boolean;
|
||||
template: 'standard' | 'minimal' | 'custom';
|
||||
customTemplateId?: string;
|
||||
showLogo: boolean;
|
||||
showDate: boolean;
|
||||
showParties: boolean;
|
||||
showConfidentialityNotice: boolean;
|
||||
confidentialityText?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Signature page configuration
|
||||
*/
|
||||
export interface ISignaturePageConfig {
|
||||
enabled: boolean;
|
||||
signatureBlockStyle: 'inline' | 'separate_page' | 'both';
|
||||
includeWitnessLines: boolean;
|
||||
includeInitialsOnEachPage: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Attachment handling configuration
|
||||
*/
|
||||
export interface IAttachmentConfig {
|
||||
includeInline: boolean;
|
||||
includeSeparately: boolean;
|
||||
attachmentToc: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Content formatting configuration
|
||||
*/
|
||||
export interface IFormattingConfig {
|
||||
headingNumbering: boolean;
|
||||
paragraphNumbering: boolean;
|
||||
preserveMarkdownFormatting: boolean;
|
||||
convertLinksToFootnotes: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Content rendering options
|
||||
*/
|
||||
export interface IPdfContentOptions {
|
||||
tableOfContents: ITocConfig;
|
||||
coverPage?: ICoverPageConfig;
|
||||
signaturePages: ISignaturePageConfig;
|
||||
attachments: IAttachmentConfig;
|
||||
formatting: IFormattingConfig;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// SECURITY
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* Encryption configuration
|
||||
*/
|
||||
export interface IPdfEncryption {
|
||||
enabled: boolean;
|
||||
algorithm: TPdfEncryptionAlgorithm;
|
||||
}
|
||||
|
||||
/**
|
||||
* Password protection
|
||||
*/
|
||||
export interface IPdfPasswords {
|
||||
userPassword?: string;
|
||||
ownerPassword?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* PDF permissions
|
||||
*/
|
||||
export interface IPdfPermissions {
|
||||
printing: TPdfPrintingPermission;
|
||||
copying: boolean;
|
||||
modifying: boolean;
|
||||
annotating: boolean;
|
||||
formFilling: boolean;
|
||||
accessibility: boolean;
|
||||
assembly: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* PDF digital signature configuration
|
||||
*/
|
||||
export interface IPdfDigitalSignature {
|
||||
enabled: boolean;
|
||||
certificateId: string;
|
||||
signatureReason: string;
|
||||
signatureLocation?: string;
|
||||
timestampAuthority?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* PDF security options
|
||||
*/
|
||||
export interface IPdfSecurity {
|
||||
encryption: IPdfEncryption;
|
||||
passwords?: IPdfPasswords;
|
||||
permissions: IPdfPermissions;
|
||||
digitalSignature?: IPdfDigitalSignature;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// METADATA
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* PDF metadata
|
||||
*/
|
||||
export interface IPdfMetadata {
|
||||
title: string;
|
||||
subject?: string;
|
||||
author?: string;
|
||||
creator: string;
|
||||
producer: string;
|
||||
keywords: string[];
|
||||
creationDate: number;
|
||||
modificationDate?: number;
|
||||
customProperties?: Record<string, string>;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// COMPLETE CONFIGURATION
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* Complete PDF generation configuration
|
||||
*/
|
||||
export interface IPdfGenerationConfig {
|
||||
templateId?: string;
|
||||
useDefaultTemplate: boolean;
|
||||
branding: IPdfBranding;
|
||||
layout: IPdfLayout;
|
||||
header?: IPdfHeaderFooter;
|
||||
footer?: IPdfHeaderFooter;
|
||||
pageNumbering: IPdfPageNumbering;
|
||||
contentOptions: IPdfContentOptions;
|
||||
security?: IPdfSecurity;
|
||||
metadata: IPdfMetadata;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// PDF TEMPLATE
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* PDF template definition
|
||||
*/
|
||||
export interface IPdfTemplate {
|
||||
id: string;
|
||||
name: string;
|
||||
description?: string;
|
||||
version: string;
|
||||
config: IPdfGenerationConfig;
|
||||
allowedContractTypes?: string[];
|
||||
organizationId?: string;
|
||||
isSystem: boolean;
|
||||
createdAt: number;
|
||||
createdBy: string;
|
||||
lastModifiedAt?: number;
|
||||
lastModifiedBy?: string;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// PDF GENERATION JOB
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* PDF generation result
|
||||
*/
|
||||
export interface IPdfGenerationResult {
|
||||
pdf: plugins.tsclass.business.IPdf;
|
||||
pageCount: number;
|
||||
fileSize: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* PDF generation error
|
||||
*/
|
||||
export interface IPdfGenerationError {
|
||||
code: string;
|
||||
message: string;
|
||||
details?: unknown;
|
||||
}
|
||||
|
||||
/**
|
||||
* PDF generation job
|
||||
*/
|
||||
export interface IPdfGenerationJob {
|
||||
id: string;
|
||||
contractId: string;
|
||||
versionId: string;
|
||||
config: IPdfGenerationConfig;
|
||||
status: TPdfJobStatus;
|
||||
progress?: number;
|
||||
queuedAt: number;
|
||||
startedAt?: number;
|
||||
completedAt?: number;
|
||||
result?: IPdfGenerationResult;
|
||||
error?: IPdfGenerationError;
|
||||
retryCount: number;
|
||||
maxRetries: number;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// FACTORY FUNCTIONS
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* Create default branding
|
||||
*/
|
||||
export function createDefaultBranding(): IPdfBranding {
|
||||
return {
|
||||
primaryColor: '#1a1a1a',
|
||||
secondaryColor: '#666666',
|
||||
textColor: '#333333',
|
||||
fonts: {
|
||||
heading: {
|
||||
family: 'Helvetica',
|
||||
fallback: ['Arial', 'sans-serif'],
|
||||
size: 14,
|
||||
lineHeight: 1.4,
|
||||
weight: 'bold',
|
||||
},
|
||||
body: {
|
||||
family: 'Helvetica',
|
||||
fallback: ['Arial', 'sans-serif'],
|
||||
size: 11,
|
||||
lineHeight: 1.5,
|
||||
},
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Create default layout
|
||||
*/
|
||||
export function createDefaultLayout(): IPdfLayout {
|
||||
return {
|
||||
pageSize: 'A4',
|
||||
orientation: 'portrait',
|
||||
margins: {
|
||||
top: 25,
|
||||
right: 20,
|
||||
bottom: 25,
|
||||
left: 20,
|
||||
},
|
||||
columns: 1,
|
||||
paragraphSpacing: 10,
|
||||
sectionSpacing: 20,
|
||||
firstPageDifferent: false,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Create default content options
|
||||
*/
|
||||
export function createDefaultContentOptions(): IPdfContentOptions {
|
||||
return {
|
||||
tableOfContents: {
|
||||
enabled: true,
|
||||
depth: 2,
|
||||
title: 'Table of Contents',
|
||||
pageBreakAfter: true,
|
||||
},
|
||||
signaturePages: {
|
||||
enabled: true,
|
||||
signatureBlockStyle: 'inline',
|
||||
includeWitnessLines: false,
|
||||
includeInitialsOnEachPage: false,
|
||||
},
|
||||
attachments: {
|
||||
includeInline: false,
|
||||
includeSeparately: true,
|
||||
attachmentToc: true,
|
||||
},
|
||||
formatting: {
|
||||
headingNumbering: true,
|
||||
paragraphNumbering: false,
|
||||
preserveMarkdownFormatting: true,
|
||||
convertLinksToFootnotes: false,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Create default page numbering
|
||||
*/
|
||||
export function createDefaultPageNumbering(): IPdfPageNumbering {
|
||||
return {
|
||||
enabled: true,
|
||||
startFrom: 1,
|
||||
format: 'numeric',
|
||||
position: 'footer',
|
||||
alignment: 'center',
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Create default PDF generation config
|
||||
*/
|
||||
export function createDefaultPdfConfig(title: string): IPdfGenerationConfig {
|
||||
return {
|
||||
useDefaultTemplate: true,
|
||||
branding: createDefaultBranding(),
|
||||
layout: createDefaultLayout(),
|
||||
pageNumbering: createDefaultPageNumbering(),
|
||||
contentOptions: createDefaultContentOptions(),
|
||||
metadata: {
|
||||
title,
|
||||
creator: 'signature.digital',
|
||||
producer: 'signature.digital PDF Generator',
|
||||
keywords: [],
|
||||
creationDate: Date.now(),
|
||||
},
|
||||
};
|
||||
}
|
||||
Reference in New Issue
Block a user