bot-with-admin-starter/EXAMPLES.md

API Usage Examples

This document provides practical examples for using the API endpoints and common patterns.

Authentication

Login

// Backend endpoint: POST /auth/login
// Request body:
{
  "email": "admin@example.com",
  "password": "password123"
}

// Response:
{
  "statusCode": 200,
  "message": "Login successful",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Register (requires authentication)

// Backend endpoint: POST /auth/register
// Headers: Authorization: Bearer <token>
// Request body:
{
  "username": "newadmin",
  "email": "newadmin@example.com",
  "password": "securepassword",
  "role": "admin" // or "superadmin"
}

Verify Token

// Backend endpoint: GET /auth/verify-token
// Headers: Authorization: Bearer <token>
// Response: Admin object

Admins CRUD

Get All Admins (Paginated)

// Backend endpoint: GET /admins
// Query params:
//   page=1
//   size=25
//   sortBy=created_at
//   sortOrder=desc
//   filters[]=username:like:john
//   filters[]=role:eq:admin

// Example URL:
GET /admins?page=1&size=10&sortBy=created_at&sortOrder=desc&filters[]=role:eq:admin

// Response:
{
  "statusCode": 200,
  "message": "Success",
  "data": {
    "totalCount": 42,
    "items": [
      {
        "id": 1,
        "username": "admin",
        "email": "admin@example.com",
        "role": "admin",
        "is_active": true,
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

Get Single Admin

// Backend endpoint: GET /admins/one/:id
GET /admins/one/1

// Response:
{
  "statusCode": 200,
  "message": "Success",
  "data": {
    "id": 1,
    "username": "admin",
    "email": "admin@example.com",
    "role": "admin",
    "is_active": true,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}

Update Admin

// Backend endpoint: PATCH /admins/update/:id
// Headers: Authorization: Bearer <token>
// Request body:
{
  "username": "updated_username",
  "email": "newemail@example.com",
  "is_active": false
}

Delete Admin

// Backend endpoint: DELETE /admins/:id
// Headers: Authorization: Bearer <token>
DELETE /admins/1

Filtering Examples

Filter Rules

• eq: Equals - username:eq:john
• neq: Not equals - role:neq:superadmin
• gt: Greater than - id:gt:10
• gte: Greater than or equal - id:gte:10
• lt: Less than - id:lt:100
• lte: Less than or equal - id:lte:100
• like: Case-insensitive contains - username:like:john
• nlike: Not like - username:nlike:test
• in: In array - role:in:admin,superadmin
• nin: Not in array - role:nin:admin
• isnull: Is null - image:isnull:
• isnotnull: Is not null - image:isnotnull:
• between: Between values - id:between:10,20

Multiple Filters

GET /admins?filters[]=username:like:john&filters[]=role:eq:admin&filters[]=is_active:eq:true

Frontend Usage Examples

Using React Query Hooks

// In a component
import { useGetAdmins } from '@/hooks/api/admins';

function AdminsPage() {
  const { data, isLoading, error } = useGetAdmins({
    query: {
      page: 1,
      size: 25,
      sortBy: 'created_at',
      sortOrder: 'desc',
    },
    filters: [
      { field: 'role', rule: 'eq', value: 'admin' },
      { field: 'username', rule: 'like', value: 'john' },
    ],
  });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <p>Total: {data?.data.totalCount}</p>
      {data?.data.items.map(admin => (
        <div key={admin.id}>{admin.username}</div>
      ))}
    </div>
  );
}

Creating a Mutation Hook

// In hooks/api/admins.ts
import { createPostMutationHook } from '@/api/helpers';
import { CreateAdminSchema, AdminSchema } from '@/api/dtos/admin';

export const useCreateAdmin = createPostMutationHook({
  endpoint: '/auth/register',
  bodySchema: CreateAdminSchema,
  responseSchema: AdminSchema,
  rMutationParams: {
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['getAdmins'] });
    },
  },
});

// Usage in component
const createAdmin = useCreateAdmin();

const handleSubmit = async (formData) => {
  await createAdmin.mutateAsync({
    variables: formData,
  });
};

Telegram Bot Examples

Adding a New Command

// In bot.service.ts
public onModuleInit() {
  this.bot.command('start', this.onStart.bind(this));
  this.bot.command('help', this.onHelp.bind(this)); // New command
  this.bot.start();
}

private async onHelp(ctx: Context) {
  await ctx.reply('Available commands:\n/start - Start the bot\n/help - Show help');
}

Sending Messages from Backend

// In any service
constructor(private readonly botService: BotService) {}

async notifyUser(telegramId: string, message: string) {
  await this.botService.sendMessage(telegramId, message);
}

// With inline keyboard
import { InlineKeyboard } from 'grammy';

const keyboard = new InlineKeyboard()
  .text('Button 1', 'callback_data_1')
  .row()
  .text('Button 2', 'callback_data_2');

await this.botService.sendMessage(telegramId, 'Choose an option:', keyboard);

Handling Callbacks

public onModuleInit() {
  this.bot.callbackQuery('callback_data_1', this.onCallback1.bind(this));
}

private async onCallback1(ctx: Context) {
  await ctx.answerCallbackQuery();
  await ctx.reply('You clicked button 1!');
}

Database Migration Examples

Creating a Migration

cd back
pnpm migration:generate --name=add_user_table

Migration File Structure

import { MigrationInterface, QueryRunner } from 'typeorm';

export class AddUserTable1234567890 implements MigrationInterface {
  public async up(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.query(`
      CREATE TABLE "users" (
        "id" SERIAL NOT NULL,
        "username" VARCHAR(255) NOT NULL,
        "created_at" TIMESTAMP NOT NULL DEFAULT now(),
        "updated_at" TIMESTAMP NOT NULL DEFAULT now(),
        CONSTRAINT "PK_users" PRIMARY KEY ("id")
      )
    `);
  }

  public async down(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.query(`DROP TABLE "users"`);
  }
}

Environment Setup

.env.example Structure

# Docker
PROJECT_NAME=mybot

# Database
DB_PORT=5432
DB_NAME=mybot
DB_USERNAME=mybot
DB_PASSWORD=your_secure_password

# Backend
BACK_PORT=4000
JWT_SECRET=your_jwt_secret_here
TELEGRAM_BOT_TOKEN=your_bot_token_here

# Frontend
FRONT_PORT=3000
API_URL=http://127.0.0.1:4000

# Backup (optional)
BACKUP_DIR=/home/mybot/backups
BACKUP_TELEGRAM_BOT_TOKEN=your_backup_bot_token
BACKUP_TELEGRAM_CHAT_ID=your_chat_id

Generating JWT Secret

// In Node.js console
require('crypto').randomBytes(32).toString('hex')