SnakeQuery Node.js SDK

The official Node.js SDK for SnakeQuery - Transform natural language into structured data queries with AI.

🚀 Quick Start

npm install snake-query

const SnakeQuery = require('snake-query');
const { SchemaBuilder } = SnakeQuery;

const client = new SnakeQuery('your-api-key-here');

const result = await client.query({
  query: 'Find products under $100',
  fetchUrl: 'https://api.store.com/products',
  responseSchema: SchemaBuilder.create()
    .array(
      SchemaBuilder.create()
        .object()
        .addStringProperty('name')
        .addNumberProperty('price', { minimum: 0 })
        .required(['name', 'price'])
        .build()
    )
    .build()
});

console.log(result.response); // Structured data

✨ Features

• 🧠 Natural Language Processing: Write queries in plain language
• 🏗️ Schema-Driven: Type-safe, validated responses
• 🌐 Multiple Data Sources: Query arrays, objects, or REST APIs
• ⚡ High Performance: Optimized for production use
• 🔒 Secure: Built-in authentication and error handling
• 📝 TypeScript Support: Full type definitions included

📖 Documentation

• 📚 Full Documentation
• 🚀 Getting Started
• 🏗️ Schema Building Guide
• 💻 Examples

🎯 Core Concepts

Natural Language Queries

Transform complex data operations into simple language:

// Instead of complex JavaScript:
const result = data
  .filter(item => item.price < 500 && item.category === 'electronics')
  .map(item => ({ name: item.title, price: item.price, rating: item.rating }))
  .sort((a, b) => b.rating - a.rating)
  .slice(0, 5);

// Use natural language:
const result = await client.query({
  query: 'Find top 5 electronics under $500, show name, price and rating, sort by rating',
  data: products
});

Structured Responses

Control output format with schemas:

const schema = SchemaBuilder.create()
  .array(
    SchemaBuilder.create()
      .object()
      .addStringProperty('productName')
      .addNumberProperty('price', { minimum: 0 })
      .addNumberProperty('rating', { minimum: 0, maximum: 5 })
      .required(['productName', 'price'])
      .build()
  )
  .build();

const result = await client.query({
  query: 'Show top rated products',
  data: products,
  responseSchema: schema
});

// Guaranteed structure:
// [{ productName: "iPhone", price: 999, rating: 4.8 }]

💻 Usage Examples

Query Direct Data

const products = [
  { name: 'iPhone', price: 999, category: 'electronics' },
  { name: 'Shoes', price: 129, category: 'fashion' }
];

const result = await client.query({
  query: 'Find products by category and calculate average price per category',
  data: products
});

Query External APIs

const result = await client.query({
  query: 'Show me the 5 most expensive products with their details',
  fetchUrl: 'https://api.escuelajs.co/api/v1/products',
  responseSchema: expensiveProductsSchema
});

Complex Analytics

const result = await client.query({
  query: 'Analyze monthly sales trends, identify peak months and calculate growth rates',
  fetchUrl: 'https://api.company.com/sales',
  responseSchema: analyticsSchema
});

🔧 API Reference

SnakeQuery Constructor

const client = new SnakeQuery(apiKey);

query(options)

Main method for all query operations:

interface QueryOptions {
  query: string;                    // Natural language query
  data?: any;                      // Direct data to query
  fetchUrl?: string;               // URL to fetch data from  
  responseSchema?: Schema;         // Response structure schema
  debug?: boolean;                 // Enable debug mode
}

SchemaBuilder

Build type-safe response schemas:

const schema = SchemaBuilder.create()
  .array(itemSchema)              // Array of items
  .object()                       // Object structure
  .addStringProperty('name')      // Add string field
  .addNumberProperty('price')     // Add number field
  .required(['name'])             // Mark fields as required
  .build();                       // Generate schema

⚠️ Error Handling

try {
  const result = await client.query(options);
} catch (error) {
  switch (error.status) {
    case 401:
      console.error('Invalid API key');
      break;
    case 402:
      console.error('Insufficient credits');
      break;
    case 504:
      console.error('Query timeout - try simplifying');
      break;
    default:
      console.error('Error:', error.message);
  }
}

🌟 Advanced Features

Environment Variables

export SNAKE_QUERY_API_KEY="your-api-key-here"

const client = new SnakeQuery(process.env.SNAKE_QUERY_API_KEY);

Debug Mode

const result = await client.query({
  query: 'Analyze data',
  data: dataset,
  debug: true  // Enables detailed logging
});

Custom Timeouts

The SDK includes a 10-minute timeout for complex queries with automatic retry logic.

📊 Response Format

All successful queries return:

{
  usageCount: {
    inputTokens: 150,
    outputTokens: 75,
    totalTokens: 225
  },
  response: [
    // Your structured data here
  ]
}

🚀 Examples

Check out the examples directory for complete working examples:

• data-query-demo.js - Query direct data arrays
• url-query-demo.js - Query external APIs

Run an example:

export SNAKE_QUERY_API_KEY="your-key"
node examples/data-query-demo.js

📝 Requirements

• Node.js 14+
• Valid SnakeQuery API key
• Internet connection (for external API queries)

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• SnakeQuery Dashboard - Get your API key
• Documentation - Full documentation
• Examples - Working code examples
• Issues - Report bugs
• Discussions - Community

💬 Support

• 📖 Documentation
• 💻 Examples
• 🐛 GitHub Issues
• 💬 Community Discussions

---

Made with ❤️ by the SnakeQuery team