City

City is a set of SDK capabilities + an HTTP routing engine. Extend with Service and AIService.

City is the core instance. It encapsulates HTTP routing, auth, env vars, and database infrastructure.

Minimal Usage

import { City } from "@downcity/city";

const base = new City({ db });

Service Registration

import { AIService, Provider } from "@downcity/city";

const deepseek = new Provider("deepseek", {
  baseURL: "https://api.deepseek.com",
  envKey: "DEEPSEEK_API_KEY",
  text: myTextHandler,
  stream: myStreamHandler,
});

const ai = new AIService();
ai.use(deepseek.model({ id: "deepseek-v4-flash", name: "DeepSeek V4 Flash" }));
base.use(ai);

See Provider & Model Registration.

Official Service Registration

import { accountsService } from "@downcity/services";
base.use(accountsService());

Routing

import { serve } from "@hono/node-server";
serve({ fetch: base.router().fetch, port: 43127, hostname: "127.0.0.1" });

instruction aggregation

City can return a plain-text instruction document for the current instance:

const text = await base.instruction();

The text aggregates:

how to use the City itself
which services are currently mounted
env requirements declared by each module
extra usage notes contributed by services

To read the same document remotely from a trusted admin side, call:

GET /v1/base/instruction

This route is admin-only and returns text/plain.

Auth

City automatically validates user_token and admin_secret_key. Access current user via ctx.user.

Database

ctx.db["table_name"] provides CityTableApi. Supports SQLite and PostgreSQL.