Public API

queries

import queries from "./kutt/server/queries/index";
// queries.domain  - domain-related DB operations
// queries.host    - host-related DB operations
// queries.link    - link CRUD and lookup
// queries.user    - user CRUD and lookup
// queries.visit   - visit recording and stats

The queries object is the primary data-access layer. Use queries.link to create or retrieve shortened links, queries.user for account management, and queries.visit for analytics. Each sub-namespace wraps Knex query builders for the corresponding table.

models (via server/models/index.js)

const models = require("./kutt/server/models/index");
// Spreads: domain.model, host.model, ip.model, link.model, user.model, visit.model

Models define the Knex table schemas and seed/factory helpers used internally by queries and migrations. Reference them when writing custom queries or extending the schema.

queues (via server/queues/index.js)

const { visit } = require("./kutt/server/queues/index");
// visit: Bull queue for async visit recording

The visit queue is a Bull job queue. Enqueue a job whenever a link is visited to record analytics asynchronously without blocking the redirect response. Backed by Redis when REDIS_ENABLED=true, otherwise falls back to in-process processing.

mail (via server/mail/index.js)

const mail = require("./kutt/server/mail/index");
// Re-exports ./mail.js: functions for sending verification, reset, and change-email messages

Use mail to trigger transactional emails (account verification, password reset, email change). Requires SMTP configuration via environment variables (MAIL_HOST, MAIL_PORT, MAIL_USER, MAIL_PASSWORD).

Working examples

Scenario - Mount Kutt routes in an existing Express app

Drop Kutt's route tree under a sub-path in your existing Express application, sharing the same process.

import express from "express";
import cookieParser from "cookie-parser";
import helmet from "helmet";

const app = express();

// Kutt expects these middleware upstream
app.use(helmet());
app.use(cookieParser());
app.use(express.json());

// Mount Kutt routes
const kuttRoutes = require("./kutt/server/routes/index");
app.use("/k", kuttRoutes);

app.listen(3000, () => {
  console.log("Server running on port 3000");
});

Scenario - Record a visit asynchronously via the visit queue

When you handle a custom redirect outside Kutt's own handlers, enqueue a visit job so analytics are still recorded.

import express from "express";
const { visit: visitQueue } = require("./kutt/server/queues/index");
const queries = require("./kutt/server/queries/index");

const router = express.Router();

router.get("/r/:slug", async (req, res) => {
  const link = await queries.link.find({ address: req.params.slug });
  if (!link) return res.status(404).send("Not found");

  // Enqueue visit for async processing - do not await
  visitQueue.add({
    linkId: link.id,
    referrer: req.headers.referer || "",
    ip: req.ip,
    headers: req.headers,
  });

  return res.redirect(301, link.target);
});

export default router;

Scenario - Send a password-reset email

Trigger a reset email from your own auth controller using Kutt's mail module directly.

const mail = require("./kutt/server/mail/index");
const queries = require("./kutt/server/queries/index");

async function requestPasswordReset(email: string): Promise<void> {
  const user = await queries.user.find({ email });
  if (!user) return; // silently ignore unknown addresses

  const resetToken = generateSecureToken(); // your own token utility
  await queries.user.update({ id: user.id, reset_password_token: resetToken });

  await mail.sendResetEmail({
    to: email,
    resetLink: `https://yourdomain.com/reset?token=${resetToken}`,
  });
}

File walkthrough

• server/server.js - Entry point; creates and starts the Express server.
• server/env.js - Validates and exports typed environment variables via envalid.
• server/knex.js - Initializes and exports the Knex database connection singleton.
• server/redis.js - Initializes and exports the ioredis client; no-op when Redis is disabled.
• server/passport.js - Configures Passport.js strategies (JWT, OIDC).
• server/cron.js - Registers cron jobs (e.g., expiring links cleanup).
• server/consts.js - Shared application-wide constants.
• server/handlers/ - Express request handlers for auth, domains, links, users, renders, and validation.
• server/routes/ - Route definitions wiring HTTP verbs to handlers; index.js is the root export.
• server/models/ - Knex table schema definitions for all entities.
• server/queries/ - Database query functions grouped by entity; exported as a single namespace object.
• server/queues/ - Bull queue definitions; visit queue for async analytics.
• server/migrations/ - Ordered Knex migration files for schema versioning.
• server/mail/ - Nodemailer-based email utilities and HTML templates.
• server/views/ - Handlebars templates for server-rendered pages.
• static/ - Public static assets (images, CSS, JS) served directly by Express.
• knexfile.js - Knex CLI configuration; reads env vars for DB client and connection.
• docs/api/ - Scripts to generate the public API documentation site.

Common pitfalls and fixes

• JWT_SECRET not set in production: The app will fail to sign tokens. Always set JWT_SECRET via env or .env file before starting in production.
• better-sqlite3 native build fails: Ensure python3, make, and g++ are installed; on CI, add apt-get install -y python3 make g++ before npm install.
• Redis connection refused when REDIS_ENABLED=true: Either start a Redis instance or set REDIS_ENABLED=false; the app does not gracefully fall back automatically.
• Migrations not run before first start: Always run npx knex migrate:latest --knexfile knexfile.js before starting; missing tables cause immediate 500 errors.
• geoip-lite database not downloaded: Run node node_modules/geoip-lite/scripts/updatedb.js after install if geographic visit data is needed; the module ships without the data files.
• Port conflicts when embedding: Kutt's server.js calls app.listen internally; when mounting only routes into your own app, require server/routes/index directly and do not call server.js.

Vibe-coding prompt template

I have purchased the "Kutt URL Shortener (Backend)" AVCP block. The source is
in ./kutt/ (copied from source/). I also have USAGE.md open for reference.

Upstream package: user@example.com

My project is a Node.js/TypeScript Express application. Please help me
integrate Kutt step by step:

1. Read USAGE.md and the file layout in ./kutt/server/ to understand the
   exported modules (routes, queries, queues, mail, models).
2. Mount ./kutt/server/routes/index.js under /links in my existing app.js.
3. Wire the required middleware (helmet, cookieParser, express.json) before
   the mounted routes.
4. Show me how to use queries.link and queries.user from
   ./kutt/server/queries/index.js in a custom controller.
5. Show me how to enqueue a visit using the Bull queue exported from
   ./kutt/server/queues/index.js.
6. Generate the .env entries I need, referencing ./kutt/server/env.js for
   the full list of accepted variables.
7. Run the migrations using knexfile.js and confirm the schema is ready.

Do not invent any API surface; only use exports documented in USAGE.md and
visible in the source files.

License and credit

Kutt is released under the MIT License. See source/LICENSE for the full text.

Upstream repository and package: kutt on npm / thedevs-network/kutt on GitHub.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.