SDK Overview

This page does one job: it pulls the calling model of @downcity/city into one reference overview.

If you want the integration story first, start with @downcity/city. If you need concrete method details, continue to User City and Admin City.

Two roles

Four common call types

// City side
const client = new City({
  role: "user",
  federation_url,
  city_id,
  user_token,
});

// AI Service
await client.ai.text({ prompt: "hello", model: "deepseek-v4-flash" });
await client.ai.stream({ prompt: "hello" });

// Custom Service
await client.service("translate").action("zh2en").invoke({ text: "hello" });
await client.service("accounts").action("login").invoke({ email: "a@b.com", password: "..." });

// GET action
const items = await client.service("cities").get("list");

// Payment methods
const methods = await client.payment.methods();
const checkout = await client.payment.method("stripe").invoke({
  topup_id: "topup_demo",
});

// Admin side
const admin = new City({
  role: "admin",
  federation_url,
  admin_secret_key,
});
await admin.service("cities").action("create").invoke({ name: "My App" });

Relationship between service, service, and AI service

• AI service: called through client.ai.*
• custom service: called through client.service(name)...
• service: still called through client.service(name)..., but the service comes from a service

Examples:

• rewrite, translate: custom services you registered yourself
• accounts, usage, payment: services exposed by official packages; payment providers such as Stripe and Creem are selected inside payment

From the caller's point of view, they all live in the same City route space.

Where registration and login fit in the SDK model

The two most common paths are:

1. your backend finishes login first, then uses Admin City to request user_token
2. the frontend uses a guest User City to call accounts.login/register, and the accounts service returns user_token

Both paths end in the same user context:

federation_url + city_id + user_token
  -> new City({ role: "user", ... })
  -> client.ai.* or client.service(...)

Which page to read next

1. To understand package composition, read Packages
2. To understand city integration, read @downcity/city
3. For detailed product-side calls, read User City
4. For trusted-side management, read Admin City
5. For minimal auth, read Federation Services Docs / Accounts