@vitaeflow/sdk-js
Version:
Official JavaScript/TypeScript SDK for VitaeFlow - Embed and extract structured resume data from PDFs
334 lines (259 loc) • 9.17 kB
Markdown
<p align="center">
<img src="https://vitaeflow.org/logo.svg" alt="VitaeFlow Logo" width="200" />
</p>
<p align="center">
<strong>Embed and extract structured resume data from PDFs</strong>
</p>
<p align="center">
<a href="https://www.npmjs.com/package/@vitaeflow/sdk"><img src="https://img.shields.io/npm/v/@vitaeflow/sdk.svg" alt="npm version"></a>
<a href="https://bundlephobia.com/package/@vitaeflow/sdk"><img src="https://img.shields.io/bundlephobia/minzip/@vitaeflow/sdk" alt="Bundle Size"></a>
<a href="https://github.com/VitaeFlow/vitaeflow-js/actions"><img src="https://github.com/VitaeFlow/vitaeflow-js/workflows/CI/badge.svg" alt="CI Status"></a>
<a href="https://codecov.io/gh/VitaeFlow/vitaeflow-js"><img src="https://codecov.io/gh/VitaeFlow/vitaeflow-js/branch/main/graph/badge.svg" alt="Coverage"></a>
<a href="https://github.com/VitaeFlow/vitaeflow-js/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@vitaeflow/sdk.svg" alt="License"></a>
</p>
---
- 🚀 **Lightning Fast** - Sub-100ms operations
- 🌐 **Universal** - Works in Node.js and browsers
- 📦 **Lightweight** - < 50KB minified + gzipped
- 🔒 **Type Safe** - Full TypeScript support
- 📉 **Smart Compression** - Automatic gzip compression
- 🔍 **Smart Detection** - Automatic VitaeFlow data detection
- 🏗️ **Builder Pattern** - Fluent API for creating CVs
- ✅ **Schema Validation** - Ensure data integrity
```bash
npm install @vitaeflow/sdk
yarn add @vitaeflow/sdk
pnpm add @vitaeflow/sdk
```
```typescript
import { VitaeFlow } from '@vitaeflow/sdk';
import { readFileSync } from 'fs';
// Initialize the SDK
const vitaeflow = new VitaeFlow({
compression: true,
logging: true
});
// Sample CV data
const cvData = {
version: "0.1.0",
meta: {
createdAt: new Date().toISOString(),
source: "my-app",
language: "en-US"
},
resume: {
basics: {
firstName: "John",
lastName: "Doe",
email: "john.doe@example.com",
phone: "+1234567890",
headline: "Senior Software Engineer",
summary: "Experienced developer with 5+ years in full-stack development"
},
experience: [{
position: "Senior Software Engineer",
company: "TechCorp",
startDate: "2020-01-01",
endDate: "2024-01-01",
current: false,
description: "Led development of microservices architecture"
}],
education: [{
institution: "University of Technology",
degree: "Computer Science",
area: "Software Engineering",
startDate: "2015-09-01",
endDate: "2019-06-01"
}],
skills: {
technical: ["JavaScript", "TypeScript", "Node.js", "React"],
languages: [{
name: "English",
level: "native"
}, {
name: "French",
level: "conversational"
}]
}
}
};
// Load your PDF
const pdfBuffer = readFileSync('resume.pdf');
// Embed CV data into PDF
const enhancedPdf = await vitaeflow.embed(pdfBuffer, cvData);
// Save the enhanced PDF
writeFileSync('resume-with-data.pdf', enhancedPdf);
// Later, extract the data
const extractResult = await vitaeflow.extract(enhancedPdf);
if (extractResult.success) {
console.log('Extracted CV data:', extractResult.data);
}
```
```html
<!DOCTYPE html>
<html>
<head>
<script type="module">
import { VitaeFlow } from 'https://unpkg.com/@vitaeflow/sdk/dist/browser/vitaeflow.esm.js';
const vitaeflow = new VitaeFlow();
// Handle file upload
document.getElementById('pdfFile').addEventListener('change', async (event) => {
const file = event.target.files[0];
const arrayBuffer = await file.arrayBuffer();
const pdfBytes = new Uint8Array(arrayBuffer);
// Check if PDF has VitaeFlow data
const hasData = await vitaeflow.hasVitaeFlow(pdfBytes);
console.log('Has VitaeFlow data:', hasData);
if (hasData) {
const result = await vitaeflow.extract(pdfBytes);
if (result.success) {
console.log('CV Data:', result.data);
}
}
});
</script>
</head>
<body>
<input type="file" id="pdfFile" accept=".pdf" />
</body>
</html>
```
```bash
npm install -g @vitaeflow/sdk
vitaeflow embed resume.pdf cv-data.json output.pdf
vitaeflow extract resume-with-data.pdf
vitaeflow validate cv-data.json
vitaeflow check resume.pdf
```
```typescript
new VitaeFlow(options?: VitaeFlowOptions)
```
**Options:**
- `compression`: Enable compression for large JSON (default: `true`)
- `compressionThreshold`: Minimum size in bytes to trigger compression (default: `1024`)
- `logging`: Enable debug logging (default: `false`)
- `logLevel`: Log level - `"debug" | "info" | "warn" | "error"` (default: `"info"`)
#### Methods
##### `embed(pdf, data, options?)`
Embeds CV data into a PDF file.
```typescript
async embed(
pdf: Buffer | Uint8Array,
data: CVData,
options?: EmbedOptions
): Promise<Uint8Array>
```
**Parameters:**
- `pdf`: PDF file as Buffer or Uint8Array
- `data`: Structured CV data to embed
- `options`: Optional embed configuration
- `forceCompress`: Force compression regardless of size
- `skipHash`: Skip integrity hash calculation
**Returns:** Enhanced PDF with embedded data
##### `extract(pdf, options?)`
Extracts CV data from a VitaeFlow-enhanced PDF.
```typescript
async extract(
pdf: Buffer | Uint8Array,
options?: ExtractOptions
): Promise<ExtractResult>
```
**Parameters:**
- `pdf`: PDF file as Buffer or Uint8Array
- `options`: Optional extract configuration
- `verifyIntegrity`: Verify data integrity with hash (default: `true`)
- `validate`: Validate against schema (default: `true`)
**Returns:** Extraction result with success status and data
##### `hasVitaeFlow(pdf)`
Checks if a PDF contains VitaeFlow data.
```typescript
async hasVitaeFlow(pdf: Buffer | Uint8Array): Promise<boolean>
```
##### `validate(data)`
Validates CV data against the VitaeFlow schema.
```typescript
async validate(data: CVData): Promise<ValidationResult>
```
## 🔧 Advanced Usage
### Error Handling
```typescript
import { VitaeFlow, ValidationError, EmbeddingError } from '@vitaeflow/sdk';
try {
const result = await vitaeflow.embed(pdfBuffer, cvData);
} catch (error) {
if (error instanceof ValidationError) {
console.error('Invalid CV data:', error.errors);
} else if (error instanceof EmbeddingError) {
console.error('Embedding failed:', error.message);
} else {
console.error('Unexpected error:', error);
}
}
```
```typescript
const environment = vitaeflow.getEnvironment(); // 'node' | 'browser' | 'unknown'
if (environment === 'browser') {
// Browser-specific code
} else if (environment === 'node') {
// Node.js-specific code
}
```
```typescript
const vitaeflow = new VitaeFlow({
logging: true,
logLevel: 'debug'
});
// Operations will log timing information
const start = Date.now();
const result = await vitaeflow.embed(pdfBuffer, cvData);
console.log(`Embed took ${Date.now() - start}ms`);
```
The VitaeFlow schema supports rich resume data including:
- **Personal Information**: Name, contact details, headline, summary
- **Work Experience**: Positions, companies, dates, descriptions
- **Education**: Degrees, institutions, dates
- **Skills**: Technical skills, soft skills, languages with proficiency levels
- **Metadata**: Creation timestamps, source system, language
See the [schema file](src/schemas/v0.1.0.json) for complete structure details.
- All PDF operations are performed in memory
- No data is transmitted to external services
- Hash verification ensures data integrity
- Schema validation prevents malformed data
- Sub-100ms operations for typical CV data
- Automatic compression for large datasets
- Optimized bundle sizes for browser usage
- Memory-efficient PDF processing
1. Fork the repository
2. Create your feature branch: `git checkout -b feature/amazing-feature`
3. Commit your changes: `git commit -m 'Add amazing feature'`
4. Push to the branch: `git push origin feature/amazing-feature`
5. Open a Pull Request
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
- 📚 [Documentation](https://vitaeflow.org/docs)
- 🐛 [Issues](https://github.com/VitaeFlow/vitaeflow-sdk-js/issues)
- 💬 [Discussions](https://github.com/VitaeFlow/vitaeflow-sdk-js/discussions)