feat: show this month's birthdays and send a greeting SMS

Each owner sees their customers born this Jalali month and can text a custom greeting.

Co-authored-by: Cursor <cursoragent@cursor.com>

apps/api/package.json

@@ -12,7 +12,7 @@
     "prisma:seed": "tsx prisma/seed.ts",
     "lint": "echo \"api lint placeholder\"",
     "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p test/tsconfig.json",
-    "test": "tsx --test test/tahesab-methods.test.ts test/dates.test.ts test/message-automation.test.ts test/record-scope.test.ts test/gamification-engine.test.ts test/automation-branches.test.ts test/pipeline-merge.test.ts"
+    "test": "tsx --test test/tahesab-methods.test.ts test/dates.test.ts test/birthdays.test.ts test/message-automation.test.ts test/record-scope.test.ts test/gamification-engine.test.ts test/automation-branches.test.ts test/pipeline-merge.test.ts"
   },
   "dependencies": {
     "@mento/shared": "*",

apps/api/src/contacts/birthday-month.ts

@@ -0,0 +1,70 @@
+import { jalaliMonthName, toJalali } from '../common/jalali';
+
+export const BIRTHDAY_SMS_DEFAULT = '{نام} عزیز، تولدتان مبارک.';
+
+export type BirthdayRow = {
+  id: string;
+  firstName: string;
+  lastName: string;
+  mobile: string | null;
+  birthDate: Date;
+};
+
+export type BirthdayPick = {
+  id: string;
+  firstName: string;
+  lastName: string;
+  mobile: string | null;
+  day: number;
+};
+
+export function fillBirthdaySmsText(template: string, firstName: string, lastName: string) {
+  const name = `${firstName} ${lastName}`.trim().replace(/\s+/g, ' ');
+  return template.replaceAll('{نام}', name).replaceAll('{name}', name).trim();
+}
+
+function tehranJalali(d: Date) {
+  const [gy, gm, gd] = new Intl.DateTimeFormat('en-CA', {
+    timeZone: 'Asia/Tehran',
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+  })
+    .format(d)
+    .split('-')
+    .map(Number);
+  return toJalali(gy, gm, gd);
+}
+
+function birthJalali(d: Date) {
+  return toJalali(d.getUTCFullYear(), d.getUTCMonth() + 1, d.getUTCDate());
+}
+
+/** متولدین ماه جاری تهران. پیش‌نمایش فقط روزهای امروز و بعد است. */
+export function selectMonthBirthdays(people: BirthdayRow[], now = new Date(), previewLimit = 6) {
+  const today = tehranJalali(now);
+  const matched = people.flatMap((person) => {
+    const birth = birthJalali(person.birthDate);
+    if (birth.jm !== today.jm) return [];
+    return [
+      {
+        id: person.id,
+        firstName: person.firstName,
+        lastName: person.lastName,
+        mobile: person.mobile,
+        day: birth.jd,
+      },
+    ];
+  });
+  const byDay = (a: BirthdayPick, b: BirthdayPick) => a.day - b.day || a.firstName.localeCompare(b.firstName, 'fa');
+  const upcoming = matched.filter((row) => row.day >= today.jd).sort(byDay);
+  const passed = matched.filter((row) => row.day < today.jd).sort(byDay);
+  return {
+    month: today.jm,
+    monthName: jalaliMonthName(today.jm),
+    today: today.jd,
+    total: matched.length,
+    preview: upcoming.slice(0, previewLimit),
+    items: [...upcoming, ...passed],
+  };
+}

apps/api/src/contacts/contacts.module.ts

@@ -8,6 +8,7 @@ import { CompaniesService } from './companies.service';
 import { PeopleController } from './people.controller';
 import { PeopleService } from './people.service';
 import { ContactsExcelService } from './contacts-excel.service';
+import { SmsService } from '../common/sms.service';
 
 @Module({
   imports: [
@@ -17,7 +18,7 @@ import { ContactsExcelService } from './contacts-excel.service';
     PublicApiModule,
   ],
   controllers: [PeopleController, CompaniesController],
-  providers: [PeopleService, CompaniesService, ContactsExcelService],
+  providers: [PeopleService, CompaniesService, ContactsExcelService, SmsService],
   exports: [PeopleService, CompaniesService],
 })
 export class ContactsModule {}

apps/api/src/contacts/dto.ts

@@ -17,6 +17,13 @@ import {
 } from 'class-validator';
 import { PERSON_IMPORT_SOURCES, PERSON_MOODS } from '@mento/shared';
 
+export class BirthdaySmsDto {
+  @IsString()
+  @MinLength(1)
+  @MaxLength(500)
+  text!: string;
+}
+
 export class BulkDeletePeopleDto {
   @IsArray()
   @ArrayMinSize(1)

apps/api/src/contacts/people.controller.ts

@@ -22,7 +22,7 @@ import { CurrentUser } from '../auth/current-user.decorator';
 import type { Actor } from '../common/record-scope';
 import { OrgModuleGuard } from '../billing/org-module.guard';
 import { RequireOrgModule } from '../billing/org-module.decorator';
-import { BulkDeletePeopleDto, CreatePersonDto, ListQueryDto, UpdatePersonDto } from './dto';
+import { BirthdaySmsDto, BulkDeletePeopleDto, CreatePersonDto, ListQueryDto, UpdatePersonDto } from './dto';
 import { PeopleService } from './people.service';
 import { ContactsExcelService } from './contacts-excel.service';
 import { brand } from '@mento/shared';
@@ -105,6 +105,20 @@ export class PeopleController {
     });
   }
 
+  @Get('birthdays')
+  birthdays(@CurrentUser() user: Actor) {
+    return this.peopleService.birthdaysThisMonth(user);
+  }
+
+  @Post(':id/birthday-sms')
+  birthdaySms(
+    @CurrentUser() user: Actor,
+    @Param('id') id: string,
+    @Body() dto: BirthdaySmsDto,
+  ) {
+    return this.peopleService.sendBirthdaySms(user, id, dto.text);
+  }
+
   @Get(':id')
   get(@CurrentUser() user: Actor, @Param('id') id: string) {
     return this.peopleService.get(user, id);

apps/api/src/contacts/people.service.ts

@@ -1,8 +1,11 @@
 import {
+  BadRequestException,
   ConflictException,
+  ForbiddenException,
   Injectable,
   Logger,
   NotFoundException,
+  ServiceUnavailableException,
   type OnModuleInit,
 } from '@nestjs/common';
 import type {
@@ -35,6 +38,8 @@ import { MessageAutomationsService } from '../message-automations/message-automa
 import { WebhooksService } from '../public-api/webhooks.service';
 import { GamificationService } from '../gamification/gamification.service';
 import { parseBirthDate } from '../common/excel';
+import { SmsService } from '../common/sms.service';
+import { fillBirthdaySmsText, selectMonthBirthdays } from './birthday-month';
 import { normalizeTags } from '../common/tags';
 import { buildSearchWhere, ci } from '../common/search';
 import {
@@ -97,6 +102,7 @@ export class PeopleService implements OnModuleInit {
     private readonly messageAutomations: MessageAutomationsService,
     private readonly webhooks: WebhooksService,
     private readonly game: GamificationService,
+    private readonly sms: SmsService,
   ) {}
 
   async list(
@@ -447,6 +453,107 @@ export class PeopleService implements OnModuleInit {
     throw new ConflictException('شخص تکراری است');
   }
 
+  async birthdaysThisMonth(actor: Actor) {
+    const rows = await this.prisma.person.findMany({
+      where: {
+        organizationId: actor.organizationId,
+        ownerId: actor.userId,
+        birthDate: { not: null },
+      },
+      select: {
+        id: true,
+        firstName: true,
+        lastName: true,
+        mobile: true,
+        phone: true,
+        birthDate: true,
+      },
+    });
+    const selected = selectMonthBirthdays(
+      rows.flatMap((row) =>
+        row.birthDate
+          ? [
+              {
+                id: row.id,
+                firstName: row.firstName,
+                lastName: row.lastName,
+                mobile: row.mobile || row.phone,
+                birthDate: row.birthDate,
+              },
+            ]
+          : [],
+      ),
+    );
+    const toItem = (row: (typeof selected.items)[number]) => ({
+      id: row.id,
+      firstName: row.firstName,
+      lastName: row.lastName,
+      fullName: `${row.firstName} ${row.lastName}`.trim(),
+      mobile: row.mobile,
+      day: row.day,
+    });
+    return {
+      month: selected.month,
+      monthName: selected.monthName,
+      today: selected.today,
+      total: selected.total,
+      preview: selected.preview.map(toItem),
+      items: selected.items.map(toItem),
+    };
+  }
+
+  async sendBirthdaySms(actor: Actor, personId: string, text: string) {
+    const body = text.trim();
+    if (!body || body.length > 500) {
+      throw new BadRequestException('متن پیامک را تا ۵۰۰ نویسه بنویسید.');
+    }
+    const person = await this.prisma.person.findFirst({
+      where: { id: personId, organizationId: actor.organizationId },
+      select: {
+        id: true,
+        firstName: true,
+        lastName: true,
+        mobile: true,
+        phone: true,
+        ownerId: true,
+        birthDate: true,
+      },
+    });
+    if (!person) throw new NotFoundException('مشتری پیدا نشد');
+    if (person.ownerId !== actor.userId) {
+      throw new ForbiddenException('فقط مسئول این مشتری می‌تواند پیامک تبریک بفرستد.');
+    }
+    if (!person.birthDate) {
+      throw new BadRequestException('برای این مشتری تاریخ تولد ثبت نشده است.');
+    }
+    const inMonth = selectMonthBirthdays(
+      [
+        {
+          id: person.id,
+          firstName: person.firstName,
+          lastName: person.lastName,
+          mobile: person.mobile || person.phone,
+          birthDate: person.birthDate,
+        },
+      ],
+    );
+    if (!inMonth.total) {
+      throw new BadRequestException('تولد این مشتری در ماه جاری نیست.');
+    }
+    const mobile = person.mobile || person.phone;
+    if (!mobile) throw new BadRequestException('برای این مشتری شماره موبایل ثبت نشده است.');
+    const message = fillBirthdaySmsText(body, person.firstName, person.lastName);
+    const result = await this.sms.sendSmsDetailed(mobile, message);
+    if (!result.ok) {
+      throw new ServiceUnavailableException(
+        result.reason === 'SMS not configured'
+          ? 'ارسال پیامک روی سرور فعال نیست.'
+          : 'پیامک ارسال نشد. کمی بعد دوباره تلاش کنید.',
+      );
+    }
+    return { ok: true };
+  }
+
   private toDto(row: PersonRow): PersonDto {
     const previousFullName = `${row.previousFirstName ?? ''} ${row.previousLastName ?? ''}`.trim();
     const importSource = row.importSource || 'manual';

apps/api/test/birthdays.test.ts

@@ -0,0 +1,52 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { toGregorian } from '../src/common/jalali';
+import {
+  BIRTHDAY_SMS_DEFAULT,
+  fillBirthdaySmsText,
+  selectMonthBirthdays,
+} from '../src/contacts/birthday-month';
+
+function birth(jy: number, jm: number, jd: number) {
+  const g = toGregorian(jy, jm, jd);
+  return new Date(Date.UTC(g.gy, g.gm - 1, g.gd, 12, 0, 0));
+}
+
+const now = new Date('2026-10-08T08:00:00Z');
+
+describe('تولدهای ماه شمسی', () => {
+  it('فقط متولدین همین ماه را می‌آورد و روزهای مانده را جلوتر می‌گذارد', () => {
+    const result = selectMonthBirthdays(
+      [
+        { id: 'soon', firstName: 'آیدا', lastName: 'کریمی', mobile: '09120000000', birthDate: birth(1370, 7, 20) },
+        { id: 'past', firstName: 'رضا', lastName: 'بهرامی', mobile: null, birthDate: birth(1360, 7, 2) },
+        { id: 'other', firstName: 'پریسا', lastName: 'قاسمی', mobile: '09121111111', birthDate: birth(1369, 6, 30) },
+        { id: 'today', firstName: 'سارا', lastName: 'محمدی', mobile: '09123333333', birthDate: birth(1375, 7, 16) },
+      ],
+      now,
+      2,
+    );
+
+    assert.equal(result.month, 7);
+    assert.equal(result.monthName, 'مهر');
+    assert.equal(result.today, 16);
+    assert.equal(result.total, 3);
+    assert.deepEqual(
+      result.preview.map((row) => row.id),
+      ['today', 'soon'],
+    );
+    assert.deepEqual(
+      result.items.map((row) => row.id),
+      ['today', 'soon', 'past'],
+    );
+    assert.equal(result.items.find((row) => row.id === 'past')?.mobile, null);
+  });
+
+  it('نام را در متن پیامک می‌گذارد', () => {
+    assert.equal(
+      fillBirthdaySmsText(BIRTHDAY_SMS_DEFAULT, 'آیدا', 'کریمی'),
+      'آیدا کریمی عزیز، تولدتان مبارک.',
+    );
+    assert.equal(fillBirthdaySmsText('  سلام {نام}  ', 'آیدا', ''), 'سلام آیدا');
+  });
+});

apps/web/src/components/dashboard/HomeBirthdayStrip.vue

@@ -0,0 +1,300 @@
+<script setup lang="ts">
+import { computed, onMounted, ref } from 'vue';
+import { RouterLink } from 'vue-router';
+import axios from 'axios';
+import { api } from '@/lib/api';
+import { toFaDigits } from '@/lib/jalali';
+import UiIcon from '@/components/UiIcon.vue';
+import { UiButton, UiModal, UiTextarea } from '@/components/ui';
+
+type BirthdayItem = {
+  id: string;
+  firstName: string;
+  lastName: string;
+  fullName: string;
+  mobile: string | null;
+  day: number;
+};
+
+type BirthdayMonth = {
+  monthName: string;
+  today: number;
+  total: number;
+  preview: BirthdayItem[];
+  items: BirthdayItem[];
+};
+
+const data = ref<BirthdayMonth | null>(null);
+const listOpen = ref(false);
+const smsTarget = ref<BirthdayItem | null>(null);
+const smsText = ref('');
+const smsBusy = ref(false);
+const smsError = ref('');
+const smsDone = ref('');
+
+const groups = computed(() => {
+  const map = new Map<number, BirthdayItem[]>();
+  for (const item of data.value?.items ?? []) {
+    const list = map.get(item.day) ?? [];
+    list.push(item);
+    map.set(item.day, list);
+  }
+  return [...map.entries()].sort((a, b) => a[0] - b[0]);
+});
+
+function apiMessage(e: unknown, fallback: string) {
+  if (!axios.isAxiosError(e)) return fallback;
+  const msg = (e.response?.data as { message?: string | string[] })?.message;
+  if (Array.isArray(msg)) return msg.join('، ') || fallback;
+  if (typeof msg === 'string' && msg.trim()) return msg;
+  return fallback;
+}
+
+function openSms(person: BirthdayItem) {
+  smsTarget.value = person;
+  smsText.value = `${person.fullName} عزیز، تولدتان مبارک.`;
+  smsError.value = '';
+  smsDone.value = '';
+}
+
+async function sendSms() {
+  const person = smsTarget.value;
+  if (!person || smsBusy.value) return;
+  smsBusy.value = true;
+  smsError.value = '';
+  try {
+    await api.post(`/people/${person.id}/birthday-sms`, { text: smsText.value });
+    smsDone.value = `پیامک برای ${person.fullName} ارسال شد.`;
+  } catch (e) {
+    smsError.value = apiMessage(e, 'ارسال پیامک ناموفق بود.');
+  } finally {
+    smsBusy.value = false;
+  }
+}
+
+onMounted(async () => {
+  try {
+    const { data: body } = await api.get<BirthdayMonth>('/people/birthdays');
+    data.value = body.total > 0 ? body : null;
+  } catch {
+    data.value = null;
+  }
+});
+</script>
+
+<template>
+  <section v-if="data" class="birthdays">
+    <div class="head">
+      <span class="ico"><UiIcon name="gift" :size="18" /></span>
+      <div>
+        <strong>تولدهای {{ data.monthName }}</strong>
+        <p>{{ toFaDigits(data.total) }} مشتری این ماه تولد دارند</p>
+      </div>
+    </div>
+
+    <div class="chips">
+      <RouterLink
+        v-for="person in data.preview"
+        :key="person.id"
+        class="chip"
+        :to="{ name: 'person-detail', params: { id: person.id } }"
+      >
+        <b>{{ toFaDigits(person.day) }} {{ data.monthName }}</b>
+        <span>{{ person.fullName }}</span>
+      </RouterLink>
+      <button v-if="data.total > data.preview.length" type="button" class="more" @click="listOpen = true">
+        همه
+      </button>
+      <button v-else type="button" class="more" @click="listOpen = true">فهرست و پیامک</button>
+    </div>
+
+    <UiModal :open="listOpen" :title="`تولدهای ${data.monthName}`" @close="listOpen = false">
+      <div class="days">
+        <section v-for="[day, people] in groups" :key="day" class="day">
+          <h3>
+            {{ toFaDigits(day) }} {{ data.monthName }}
+            <em v-if="day < data.today">گذشته</em>
+            <em v-else-if="day === data.today">امروز</em>
+          </h3>
+          <ul>
+            <li v-for="person in people" :key="person.id">
+              <RouterLink :to="{ name: 'person-detail', params: { id: person.id } }" @click="listOpen = false">
+                {{ person.fullName }}
+              </RouterLink>
+              <UiButton
+                size="sm"
+                variant="outline"
+                :disabled="!person.mobile"
+                @click="openSms(person)"
+              >
+                {{ person.mobile ? 'پیامک تبریک' : 'بدون شماره' }}
+              </UiButton>
+            </li>
+          </ul>
+        </section>
+      </div>
+    </UiModal>
+
+    <UiModal
+      :open="!!smsTarget"
+      nest
+      title="پیامک تبریک تولد"
+      @close="smsTarget = null"
+    >
+      <p v-if="smsTarget" class="lead">برای {{ smsTarget.fullName }}</p>
+      <UiTextarea v-model="smsText" :rows="4" />
+      <p class="hint">می‌توانید متن را عوض کنید. عبارت {نام} با نام مشتری جایگزین می‌شود.</p>
+      <p v-if="smsError" class="err">{{ smsError }}</p>
+      <p v-if="smsDone" class="ok">{{ smsDone }}</p>
+      <template #footer>
+        <UiButton variant="ghost" :disabled="smsBusy" @click="smsTarget = null">بستن</UiButton>
+        <UiButton variant="primary" :loading="smsBusy" :disabled="smsBusy || !smsText.trim() || !!smsDone" @click="sendSms">
+          ارسال پیامک
+        </UiButton>
+      </template>
+    </UiModal>
+  </section>
+</template>
+
+<style scoped>
+.birthdays {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+  background: #fff;
+  border: 1px solid #eef2f7;
+  border-radius: var(--radius);
+  box-shadow: 0 8px 24px rgba(15, 23, 42, 0.04);
+  padding: 0.85rem 1rem;
+}
+
+.head {
+  display: flex;
+  align-items: center;
+  gap: 0.7rem;
+  flex-shrink: 0;
+}
+
+.ico {
+  width: 40px;
+  height: 40px;
+  border-radius: 12px;
+  display: grid;
+  place-items: center;
+  background: #fff7ed;
+  color: #ea580c;
+}
+
+.head strong {
+  display: block;
+  color: #0f172a;
+}
+
+.head p {
+  margin: 0.15rem 0 0;
+  color: #94a3b8;
+  font-size: 0.82rem;
+}
+
+.chips {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.45rem;
+  min-width: 0;
+}
+
+.chip,
+.more {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.4rem;
+  border-radius: 999px;
+  border: 1px solid #fed7aa;
+  background: #fff7ed;
+  color: #9a3412;
+  padding: 0.35rem 0.7rem;
+  text-decoration: none;
+  font: inherit;
+  cursor: pointer;
+}
+
+.chip b {
+  font-weight: 700;
+}
+
+.more {
+  background: #0f172a;
+  border-color: #0f172a;
+  color: #fff;
+}
+
+.days {
+  display: grid;
+  gap: 0.9rem;
+  max-height: 60vh;
+  overflow: auto;
+}
+
+.day h3 {
+  margin: 0 0 0.4rem;
+  font-size: 0.92rem;
+  color: #0f172a;
+}
+
+.day em {
+  margin-inline-start: 0.4rem;
+  font-style: normal;
+  font-size: 0.75rem;
+  color: #94a3b8;
+}
+
+.day ul {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: grid;
+  gap: 0.35rem;
+}
+
+.day li {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.6rem;
+}
+
+.day a {
+  color: #0f172a;
+  text-decoration: none;
+}
+
+.lead {
+  margin: 0 0 0.6rem;
+}
+
+.hint,
+.err,
+.ok {
+  margin: 0.55rem 0 0;
+  font-size: 0.82rem;
+}
+
+.hint {
+  color: #94a3b8;
+}
+
+.err {
+  color: #dc2626;
+}
+
+.ok {
+  color: #16a34a;
+}
+
+@media (max-width: 720px) {
+  .birthdays {
+    align-items: flex-start;
+    flex-direction: column;
+  }
+}
+</style>

apps/web/src/views/HomeView.vue

@@ -6,6 +6,7 @@ import { formatMoney } from '@/lib/money';
 import { formatJalaliDateTime, rewriteGregorianDates, toFaDigits } from '@/lib/jalali';
 import HomeHero from '@/components/dashboard/HomeHero.vue';
 import HomeKpiRow from '@/components/dashboard/HomeKpiRow.vue';
+import HomeBirthdayStrip from '@/components/dashboard/HomeBirthdayStrip.vue';
 import HomeSalesTrend from '@/components/dashboard/HomeSalesTrend.vue';
 import HomeSourcesChart from '@/components/dashboard/HomeSourcesChart.vue';
 import HomeAiAssistant from '@/components/dashboard/HomeAiAssistant.vue';
@@ -190,6 +191,7 @@ onUnmounted(() => {
         :format-value="formatKpiValue"
         :format-change="formatChange"
       />
+      <HomeBirthdayStrip />
 
       <div class="mid-grid">
         <HomeSalesTrend