Node SDK - pre.dev Architect API

A TypeScript/Node.js client library for the pre.dev Architect API. Generate comprehensive software specifications using AI-powered analysis.

Features

🚀 Fast Spec: Generate comprehensive specifications quickly - perfect for MVPs and prototypes
🔍 Deep Spec: Generate ultra-detailed specifications for complex systems with enterprise-grade depth
⚡ Async Spec: Non-blocking async methods for long-running requests
📊 Status Tracking: Check the status of async specification generation requests
✨ Full TypeScript Support: Complete type definitions for better IDE support
🛡️ Error Handling: Custom exceptions for different error scenarios
🌐 Modern ES Modules: Uses ES6+ import/export syntax

Installation

Install the pre.dev Node SDK using npm:

npm install predev-api

Quick Start

import { PredevAPI } from 'predev-api';

// Initialize the predev client with your API key
const predev = new PredevAPI({ apiKey: 'your_api_key_here' });

// Generate a fast specification
const result = await predev.fastSpec({
  input: 'Build a task management app with team collaboration',
  outputFormat: 'url'
});

console.log(result);

Authentication

The Pre.dev API uses API key authentication. Get your API key from the pre.dev dashboard under Settings → API Keys:

const predev = new PredevAPI({ apiKey: 'your_api_key' });

API Methods

Synchronous Methods

fastSpec()

Generate a fast specification (30-40 seconds, 10 credits).

const result = await predev.fastSpec({
  input: 'Build a SaaS project management tool with real-time collaboration',
  outputFormat: 'url'
});

Parameters:

options.input (required): string - Description of what you want to build
options.outputFormat (optional): "url" | "markdown" - Output format (default: "url")
options.currentContext (optional): string - Existing project context
options.docURLs (optional): string[] - Documentation URLs to reference

Returns: Promise<SpecResponse> object with complete specification data

deepSpec()

Generate a deep specification (2-3 minutes, 50 credits).

const result = await predev.deepSpec({
  input: 'Build a healthcare platform with HIPAA compliance',
  outputFormat: 'url'
});

Parameters: Same as fastSpec() Returns: Promise<SpecResponse> object with comprehensive specification data

Asynchronous Methods

fastSpecAsync()

Generate a fast specification asynchronously (returns immediately).

const result = await predev.fastSpecAsync({
  input: 'Build a comprehensive e-commerce platform',
  outputFormat: 'url'
});
// Returns: { specId: "spec_123", status: "pending" }

Parameters: Same as fastSpec() Returns: Promise<AsyncResponse> object with specId for polling

deepSpecAsync()

Generate a deep specification asynchronously (returns immediately).

const result = await predev.deepSpecAsync({
  input: 'Build a fintech platform with regulatory compliance',
  outputFormat: 'url'
});
// Returns: { specId: "spec_456", status: "pending" }

Parameters: Same as fastSpec() Returns: Promise<AsyncResponse> object with specId for polling

Status Checking

getSpecStatus()

Check the status of an async specification generation request.

const status = await predev.getSpecStatus('spec_123');
// Returns full SpecResponse with status: "pending" | "processing" | "completed" | "failed"

Parameters:

specId (required): string - The specification ID from async methods

Returns: Promise<SpecResponse> object with current status and data (when completed)

Listing and Searching Specs

listSpecs()

List all specs with optional filtering and pagination.

// Get first 20 specs
const result = await predev.listSpecs();

// Get completed specs only
const completed = await predev.listSpecs({ status: 'completed' });

// Paginate: get specs 20-40
const page2 = await predev.listSpecs({ skip: 20, limit: 20 });

// Filter by endpoint type
const fastSpecs = await predev.listSpecs({ endpoint: 'fast_spec' });

Parameters:

params.limit (optional): number - Results per page (1-100, default: 20)
params.skip (optional): number - Offset for pagination (default: 0)
params.endpoint (optional): "fast_spec" | "deep_spec" - Filter by endpoint type
params.status (optional): "pending" | "processing" | "completed" | "failed" - Filter by status

Returns: Promise<ListSpecsResponse> object with specs array and pagination metadata

findSpecs()

Search for specs using regex patterns.

// Search for "payment" specs
const paymentSpecs = await predev.findSpecs({ query: 'payment' });

// Search for specs starting with "Build"
const buildSpecs = await predev.findSpecs({ query: '^Build' });

// Search: only completed specs mentioning "auth"
const authSpecs = await predev.findSpecs({ 
  query: 'auth', 
  status: 'completed' 
});

// Complex regex: find SaaS or SASS projects
const saasSpecs = await predev.findSpecs({ query: 'saas|sass' });

Parameters:

params.query (required): string - Regex pattern (case-insensitive)
params.limit (optional): number - Results per page (1-100, default: 20)
params.skip (optional): number - Offset for pagination (default: 0)
params.endpoint (optional): "fast_spec" | "deep_spec" - Filter by endpoint type
params.status (optional): "pending" | "processing" | "completed" | "failed" - Filter by status

Returns: Promise<ListSpecsResponse> object with matching specs and pagination metadata Regex Pattern Examples:

Pattern	Matches
`payment`	”payment”, “Payment”, “make payment”
`^Build`	Specs starting with “Build”
`platform$`	Specs ending with “platform”
`(API\|REST)`	Either “API” or “REST”
`auth.*system`	”auth” then anything then “system”
`\\d{3,}`	3+ digits (budgets, quantities)
`saas\|sass`	SaaS or SASS

Response Types

AsyncResponse

{
  specId: string;      // Unique ID for polling (e.g., "spec_abc123")
  status: "pending" | "processing" | "completed" | "failed";
}

SpecResponse

{
  // Basic info
  _id?: string;                    // Internal ID
  created?: string;                // ISO timestamp
  endpoint: "fast_spec" | "deep_spec";
  input: string;                   // Original input text
  status: "pending" | "processing" | "completed" | "failed";
  success: boolean;
  uploadedFileShortUrl?: string;   // URL to input file
  uploadedFileName?: string;       // Name of input file

  // Output data (when completed)
  output?: any;                    // Raw content or URL
  outputFormat: "markdown" | "url";
  outputFileUrl?: string;          // Full URL to hosted spec
  executionTime?: number;          // Processing time in milliseconds

  // Integration URLs (when completed)
  predevUrl?: string;              // Link to pre.dev project
  lovableUrl?: string;             // Link to generate with Lovable
  cursorUrl?: string;              // Link to generate with Cursor
  v0Url?: string;                  // Link to generate with v0
  boltUrl?: string;                // Link to generate with Bolt

  // Error handling
  errorMessage?: string;           // Error details if failed
  progress?: string;               // Progress information
}

ListSpecsResponse

{
  specs: SpecResponse[];  // Array of spec objects
  total: number;          // Total count of matching specs
  hasMore: boolean;       // Whether more results are available
}

Examples

Generate Fast Spec

import { PredevAPI } from 'predev-api';

const predev = new PredevAPI({ apiKey: 'your_api_key' });

const result = await predev.fastSpec({
  input: 'Build a SaaS project management tool with team collaboration',
  outputFormat: 'url'
});

console.log(`Specification URL: ${result.outputFileUrl}`);

Generate Deep Spec with Context

import { PredevAPI } from 'predev-api';

const predev = new PredevAPI({ apiKey: 'your_api_key' });

const result = await predev.deepSpec({
  input: 'Add advanced analytics dashboard',
  currentContext: 'Existing e-commerce platform with user auth and product catalog',
  outputFormat: 'markdown'
});

console.log(result.output);

With Documentation URLs

import { PredevAPI } from 'predev-api';

const predev = new PredevAPI({ apiKey: 'your_api_key' });

const result = await predev.fastSpec({
  input: 'Build a customer support ticketing system',
  docURLs: ['https://docs.pre.dev', 'https://docs.stripe.com'],
  outputFormat: 'markdown'
});

Async Workflow with Polling

import { PredevAPI } from 'predev-api';

const predev = new PredevAPI({ apiKey: 'your_api_key' });

async function generateSpec() {
  // Start async generation
  const asyncResult = await predev.fastSpecAsync({
    input: 'Build a social media platform',
    outputFormat: 'url'
  });

  console.log(`Spec ID: ${asyncResult.specId}`);

  // Poll for completion
  let status;
  while (true) {
    status = await predev.getSpecStatus(asyncResult.specId);
    console.log(`Status: ${status.status}`);
    
    if (status.status === 'completed' || status.status === 'failed') {
      break;
    }
    
    await new Promise(resolve => setTimeout(resolve, 5000));
  }

  if (status.status === 'completed') {
    console.log(`Specification URL: ${status.outputFileUrl}`);
  }
}

generateSpec();

List and Filter Specs

import { PredevAPI } from 'predev-api';

const predev = new PredevAPI({ apiKey: 'your_api_key' });

// Get all completed specs
const completed = await predev.listSpecs({ 
  status: 'completed',
  limit: 50 
});

console.log(`Total completed specs: ${completed.total}`);
completed.specs.forEach(spec => {
  console.log(`- ${spec.input} (${spec.endpoint})`);
});

Search Specs with Regex

import { PredevAPI } from 'predev-api';

const predev = new PredevAPI({ apiKey: 'your_api_key' });

// Find all payment-related specs
const paymentSpecs = await predev.findSpecs({
  query: 'payment|checkout|billing',
  status: 'completed',
  limit: 20
});

console.log(`Found ${paymentSpecs.total} payment-related specs`);

Documentation

For more information about the Pre.dev Architect API, visit:

Support

For issues, questions, or contributions:

Official SDKs

​Features

​Installation

​Quick Start

​Authentication

​API Methods

​Synchronous Methods

​fastSpec()

​deepSpec()

​Asynchronous Methods

​fastSpecAsync()

​deepSpecAsync()

​Status Checking

​getSpecStatus()

​Listing and Searching Specs

​listSpecs()

​findSpecs()

​Response Types

​AsyncResponse

​SpecResponse

​ListSpecsResponse

​Examples

​Generate Fast Spec

​Generate Deep Spec with Context

​With Documentation URLs

​Async Workflow with Polling

​List and Filter Specs

​Search Specs with Regex

​Documentation

​Support

Features

Installation

Quick Start

Authentication

API Methods

Synchronous Methods

fastSpec()

deepSpec()

Asynchronous Methods

fastSpecAsync()

deepSpecAsync()

Status Checking

getSpecStatus()

Listing and Searching Specs

listSpecs()

findSpecs()

Response Types

AsyncResponse

SpecResponse

ListSpecsResponse

Examples

Generate Fast Spec

Generate Deep Spec with Context

With Documentation URLs

Async Workflow with Polling

List and Filter Specs

Search Specs with Regex

Documentation

Support