@factify/sdk-ts

Factify TypeScript SDK

The official TypeScript SDK for Factify's API. Built with ConnectRPC for type-safe, protocol-agnostic API calls.

🚀 Quick Start

npm install @factify/sdk-ts

import { FactifyClient } from '@factify/sdk-ts';

const client = new FactifyClient({
  baseUrl: 'https://rpc.factify.com',
  apiTokenAuth: {
    apiToken: process.env.FACTIFY_API_TOKEN, // ffy.{id}.{secret}
    validateFormat: true,
  },
});

// Create document
const pdfFile = new File(['PDF content'], 'document.pdf', { type: 'application/pdf' });
const result = await client.documents.createDocument(pdfFile, {
  name: 'My Document',
  description: 'Document description'
});

// Generate cover page
const coverPage = await client.coverPages.createDocumentCoverPage({
  documentId: result.documentId,
  title: 'My Document',
  description: 'Detailed document description'
});

📚 Documentation

• SDK Overview - Complete SDK documentation and feature overview
• Getting Started - Installation, setup, and first API call
• Document Creation - Complete guide to document creation
• API Reference - Complete SDK API documentation
• cURL Examples - REST API examples for testing
• Error Handling - Error types and handling patterns
• Configuration - Client options and environment setup

✨ Features

• 🔐 API Token Authentication - Secure machine-to-machine auth with ffy.{id}.{secret} tokens
• 📄 Document Management - Create and manage documents
• 🎨 Entry Page Generation - Create branded entry pages
• 🔒 Access Control - Attach/detach access policies for document permissions
• 📝 Form Submissions - Retrieve and manage form data with filtering
• ⚡ ConnectRPC Protocol - Type-safe calls over REST/JSON or gRPC-Web
• 🔄 Automatic Retries - Built-in exponential backoff for reliability
• 🌐 Universal Support - Works in Node.js and browsers
• 📦 TypeScript Native - Full type safety and IntelliSense

🏗️ Core Workflow

The Factify SDK provides a simplified PDF document workflow:

// 1. Initialize client
const client = new FactifyClient({
  baseUrl: 'https://rpc.factify.com',
  apiTokenAuth: { apiToken: 'ffy.your_token_id.your_token_secret' }
});

// 2. Create and upload PDF document
const pdfFile = new File(['PDF content'], 'report.pdf', { type: 'application/pdf' });
const result = await client.documents.createDocument(pdfFile, {
  name: 'Quarterly Report',
  description: 'Q4 2024 performance analysis'
});

// 3. Configure access (optional)
await client.access.attachAccessPolicy({
  organizationId: 'your-org-id',
  documentId: result.documentId,
  policyId: 'your-policy-id'
});

// 4. Generate cover page
const coverPage = await client.coverPages.createDocumentCoverPage({
  documentId: result.documentId,
  title: 'Quarterly Report',
  description: 'Comprehensive Q4 analysis with recommendations',
  downloadLinkExpirationSeconds: 7200
});

// 5. Retrieve form submissions (if applicable)
const submissions = await client.forms.getFormSubmissions({
  formId: 'your-form-id',
  filters: {
    createdAtAfter: { seconds: BigInt(Date.now() / 1000 - 86400) } // Last 24h
  }
});

🔧 Environment Setup

The SDK reads environment variables but does NOT automatically load .env files. You must manually configure dotenv in your application:

# .env file
FACTIFY_API_TOKEN=ffy.your_token_id.your_token_secret
FACTIFY_API_URL=https://rpc-stage.factify.com

// Load environment variables manually (recommended)
import dotenv from 'dotenv';
dotenv.config();

// Then initialize client
const client = new FactifyClient({
  baseUrl: process.env.FACTIFY_API_URL || 'https://rpc.factify.com',
  apiTokenAuth: {
    apiToken: process.env.FACTIFY_API_TOKEN!,
    validateFormat: true
  }
});

🎯 Service Overview

Service	Purpose	Key Methods
documents	PDF document management	createDocument(), getDocument(), listDocuments()
coverPages	Branded cover generation	createDocumentCoverPage()
access	Permission management	attachAccessPolicy(), detachAccessPolicy(), inspectAccess()
forms	Form data retrieval	getFormSubmissions()

🏃♂️ Development

# Setup
npm install

# Build
npm run build

# Test
npm test

# Development with watch
npm run dev

# Generate types from proto (developers only)
npm run generate

📖 Examples

Basic PDF Document Upload

// Create a PDF file (browser or Node.js)
const pdfFile = new File(['PDF content'], 'contract.pdf', { type: 'application/pdf' });

const result = await client.documents.createDocument(pdfFile, {
  name: 'Service Contract',
  description: 'Service agreement for Q1 2024'
});

console.log('Document created:', result.documentId);

Access Control

// Attach policy
await client.access.attachAccessPolicy({
  organizationId: 'org-123',
  documentId: 'doc-456', 
  policyId: 'policy-789'
});

// Check what policies are attached
const access = await client.access.inspectAccess({
  documentId: 'doc-456'
});
console.log(`${access.accessPolicies.length} policies attached`);

Form Data with Filtering

import { create, TimestampSchema } from '@bufbuild/protobuf';

const submissions = await client.forms.getFormSubmissions({
  formId: 'form-123',
  filters: {
    createdAtAfter: create(TimestampSchema, {
      seconds: BigInt(Math.floor(Date.now() / 1000) - 86400) // 24h ago
    })
  }
});