codehooks-js

The official JavaScript/TypeScript library for Codehooks.io - the platform for webhooks, automations, and integrations.

Why Codehooks?

Deploy production-ready webhook endpoints in under a minute. No need to assemble API Gateway, Lambda, DynamoDB, and SQS yourself.

• Webhook-First Design - Built-in rawBody access for HMAC signature verification
• Reliable Processing - Automatic retries via queues and workers
• All-in-One Infrastructure - Database, key-value store, queues, and workers included
• Flat-Rate Pricing - Unlimited compute, no surprise bills from webhook volume

Quick Start

Install the Codehooks CLI:

npm install -g codehooks

Create a new project and install the library:

codehooks create myproject
cd myproject
npm install codehooks-js

Webhook Handler Example

Handle incoming webhooks with signature verification and reliable background processing:

import { app, datastore } from 'codehooks-js';
import crypto from 'crypto';

// Webhook endpoint with HMAC signature verification
app.post('/webhooks/incoming', async (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const secret = process.env.WEBHOOK_SECRET;

  // Use rawBody for signature verification (preserves exact bytes)
  const expectedSig = crypto
    .createHmac('sha256', secret)
    .update(req.rawBody)
    .digest('hex');

  if (signature !== expectedSig) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Store the webhook event
  const conn = await datastore.open();
  const event = await conn.insertOne('webhook_events', {
    payload: req.body,
    received: new Date()
  });

  // Queue for reliable background processing
  await conn.enqueue('processWebhook', { eventId: event._id });

  res.json({ received: true });
});

// Background worker with automatic retries
app.worker('processWebhook', async (req, res) => {
  const { eventId } = req.body.payload;
  const conn = await datastore.open();

  const event = await conn.getOne('webhook_events', eventId);
  console.log('Processing webhook:', event.payload);

  // Your processing logic here

  res.end();
});

export default app.init();

TypeScript Support

Full TypeScript support with strong types:

import { app, datastore, httpRequest, httpResponse } from 'codehooks-js';

app.post('/webhooks/github', async (req: httpRequest, res: httpResponse) => {
  const event = req.headers['x-github-event'];
  const payload = req.body;

  const conn = await datastore.open();
  await conn.insertOne('github_events', {
    event,
    payload,
    timestamp: new Date()
  });

  res.json({ status: 'ok' });
});

export default app.init();

REST API Example

Build traditional REST APIs with the same simplicity:

import { app, datastore } from 'codehooks-js';

app.get('/api/users/:id', async (req, res) => {
  const conn = await datastore.open();
  const user = await conn.getOne('users', req.params.id);
  res.json(user);
});

app.post('/api/users', async (req, res) => {
  const conn = await datastore.open();
  const user = await conn.insertOne('users', req.body);
  res.status(201).json(user);
});

// Auto-generate CRUD endpoints for any collection
app.crudlify();

export default app.init();

Compile

When running the coho compile command, it will automatically create a tsconfig.json file in the project directory. The tsconfig file can be further adapted to your needs, the initial configuration is shown in the example below:

{
  "files": ["./index.ts"],
  "compilerOptions": {
    "allowJs": true,
    "lib": ["ES6", "dom"]
  }
}

Any syntax or type error will be displayed accordingly from the compile command, for example:

$ coho compile

🤔 [tsl] ERROR in /Users/jane/projects/tsdemo/index.ts(9,9)
      TS2345: Argument of type '(req: httpRequest, res: httpResponse) => void' is not assignable to parameter of type 'string'.

Correcting the errors should ultimately show a successfull compile output, ready for deployment of your backend app.

$ coho compile

OK 🙌

Your backend application is now available at your project's endpoint URL. For example:

https://myproject-ff00.codehooks.io/dev/*

Deploy

From the project directory run:

$ codehooks deploy

Documentation

For complete documentation, visit https://codehooks.io/docs.

API

Codehooks Class API Reference

The Codehooks class provides a comprehensive backend application framework with the following APIs:

HTTP Routing APIs

• post(path, ...hook) - Register POST route handlers
• get(path, ...hook) - Register GET route handlers
• put(path, ...hook) - Register PUT route handlers
• patch(path, ...hook) - Register PATCH route handlers
• delete(path, ...hook) - Register DELETE route handlers
• all(path, ...hook) - Register handlers for all HTTP methods

Middleware & Authentication APIs

• use(...hook) - Register global middleware (supports string paths, RegExp, or function)
• useRoute(route, ...hook) - Register route-specific middleware
• auth(path, ...hook) - Register authentication middleware for specific paths

Background Processing APIs

• queue(topic, ...hook) - Register queue handlers for background processing
• worker(name, ...hook) - Register worker functions (also adds to queues for legacy support)
• job(cronExpression, ...hook) - Register scheduled cron jobs

Static File Serving APIs

• static(options, hook) - Serve static files from source code directory
• storage(options, hook) - Serve files from blob storage directory

Template & Configuration APIs

• set(key, val) - Set application configuration settings
• render(view, data, cb) - Render templates with data
• crudlify(schema, options) - Auto-generate CRUD REST API endpoints

Real-time Communication APIs

• realtime(path, ...hook) - Set up server-sent events (SSE) channels for real-time communication

Workflow Management APIs

• createWorkflow(name, description, steps, options) - Create and register a new workflow instance

Application Lifecycle APIs

• init(hook) - Initialize the application and return manifest
• start(hook) - Alias for init() method

The Codehooks class serves as a comprehensive backend application framework that combines HTTP routing, background processing, real-time communication, and workflow management capabilities in a single, cohesive API.

Datastore API Reference

The Datastore provides a unified interface for both NoSQL document storage and Key-Value operations. It supports MongoDB-like query syntax and provides streaming capabilities for large datasets.

Connection & Collection Management

• open() - Connect to the Datastore and return the API interface
• collection(name) - Get a NoSQL collection by name for document operations

NoSQL Document Operations

Read Operations

• getOne(collection, query) - Get a single document by ID or query
• findOne(collection, query) - Alias for getOne
• getMany(collection, query?, options?) - Get a stream of documents matching query
• find(collection, query?, options?) - Alias for getMany

Write Operations

• insertOne(collection, document) - Insert a new document into a collection
• updateOne(collection, query, document, updateOperators?, options?) - Update one document (patches existing data)
• updateMany(collection, query, document, updateOperators?) - Update multiple documents
• replaceOne(collection, query, document, options?) - Replace one document completely
• replaceMany(collection, query, document, options?) - Replace multiple documents

Delete Operations

• removeOne(collection, query) - Remove one document by ID or query
• removeMany(collection, query) - Remove multiple documents matching query

Schema Management

• createSchema(collection, schema) - Validate collection data against JSON-Schema
• setSchema(collection, schema) - Alias for createSchema
• removeSchema(collection) - Remove JSON-schema validation for collection
• getSchema(collection) - Get JSON-schema for collection

Utility Operations

• count(collection) - Count documents in a collection

Key-Value Operations

Basic Key-Value Operations

• set(key, value, options?) - Set a key-value pair
• get(key, options?) - Get a value by key
• getAll(keyPattern, options?) - Get all key-value pairs matching pattern
• del(key, options?) - Delete a key-value pair
• delAll(keyPattern, options?) - Delete all key-value pairs matching pattern

Numeric Operations

• incr(key, value, options?) - Increment a numeric value
• decr(key, value, options?) - Decrement a numeric value

Queue Operations

• enqueue(topic, document, options?) - Add a job to a queue for background processing
• enqueueFromQuery(collection, query, topic, options?) - Queue each item from a database query

DataStream Interface

When using getMany() or find(), you get a DataStream object with these methods:

• on(event, callback) - Listen for data events (e.g., 'data', 'end')
• json(response) - Pipe data directly to HTTP response as JSON
• toArray() - Convert stream to array of objects
• forEach(callback) - Iterate over each object in the stream

Usage Examples

import { datastore } from 'codehooks-js';

// Connect to datastore
const conn = await datastore.open();

// NoSQL operations
const doc = await conn.insertOne('users', {
  name: 'John',
  email: '[email protected]',
});
const user = await conn.getOne('users', { _id: doc._id });
const users = await conn.getMany('users', { active: true }).toArray();
await conn.updateOne('users', { _id: doc._id }, { lastLogin: new Date() });

// Key-Value operations
await conn.set('user:123:session', { token: 'abc123', expires: new Date() });
const session = await conn.get('user:123:session');
await conn.incr('visits', 1);

// Queue operations
await conn.enqueue('emailWorker', {
  to: '[email protected]',
  template: 'welcome',
});

Query Syntax

The Datastore supports MongoDB-like query syntax:

// Simple equality
{
  status: 'active';
}

// Comparison operators
{
  age: {
    $gt: 18;
  }
}
{
  price: {
    $lte: 100;
  }
}

// Logical operators
{
  $and: [{ status: 'active' }, { age: { $gte: 18 } }];
}
{
  $or: [{ category: 'A' }, { category: 'B' }];
}

// Array operations
{
  tags: {
    $in: ['javascript', 'nodejs'];
  }
}
{
  tags: {
    $all: ['javascript', 'nodejs'];
  }
}

// Regular expressions
{
  name: {
    $regex: /john/i;
  }
}

Options

Many operations accept an options object for additional configuration:

// Upsert option for updates
await conn.updateOne(
  'users',
  { email: '[email protected]' },
  { lastLogin: new Date() },
  {},
  { upsert: true }
);

// Key-Value options
await conn.set('key', 'value', { ttl: 3600000 }); // 1 hour TTL

Key Features:

1. Express-style routing with support for all HTTP methods
2. Middleware system with global and route-specific middleware
3. Background processing with queues, workers, and scheduled jobs
4. Static file serving from both source and blob storage
5. Real-time communication via Server-Sent Events
6. Workflow engine for complex step-based applications
7. Auto-generated CRUD APIs with schema validation
8. Datastore with MongoDB-like query syntax, key-value operations, and queue management
9. Security & Authentication with JWKS support and custom auth middleware for secure API endpoints