{"id":50667258,"url":"https://github.com/codedpro/teleyab","last_synced_at":"2026-06-08T07:35:09.950Z","repository":{"id":361643984,"uuid":"1244558789","full_name":"codedpro/teleyab","owner":"codedpro","description":"Telegram username → phone-number lookup service (RTL). Pay only when we find a result. Wallet billing in Toman, card-to-card top-ups, Bearer-token API. Next.js 16 / React 19 / Tailwind v4 / Go 1.23 / Postgres 16.","archived":false,"fork":false,"pushed_at":"2026-05-31T15:36:52.000Z","size":186,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-31T17:20:32.536Z","etag":null,"topics":["ai-overviews","chat-ui","docker","golang","gsap","llms-txt","lookup-service","nextjs","osint","phone-lookup","postgres","react","rtl","saas","seo","tailwindcss","telegram","typescript","username-to-phone"],"latest_commit_sha":null,"homepage":"https://teleyab.ir","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codedpro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-20T11:32:07.000Z","updated_at":"2026-05-31T15:36:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/codedpro/teleyab","commit_stats":null,"previous_names":["codedpro/teleyab"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/codedpro/teleyab","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codedpro%2Fteleyab","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codedpro%2Fteleyab/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codedpro%2Fteleyab/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codedpro%2Fteleyab/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codedpro","download_url":"https://codeload.github.com/codedpro/teleyab/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codedpro%2Fteleyab/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34053435,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-overviews","chat-ui","docker","golang","gsap","llms-txt","lookup-service","nextjs","osint","phone-lookup","postgres","react","rtl","saas","seo","tailwindcss","telegram","typescript","username-to-phone"],"created_at":"2026-06-08T07:34:21.475Z","updated_at":"2026-06-08T07:35:09.940Z","avatar_url":"https://github.com/codedpro.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TeleYab — Telegram Username → Phone Lookup\n\n\u003e RTL SaaS that turns a Telegram `@username` or numeric ID into the\n\u003e mobile phone number behind it. Wallet billing in Toman, card-to-card top-ups,\n\u003e pay-per-success model (failed lookups cost zero), Bearer-token API for\n\u003e developers, full admin operations dashboard.\n\u003e\n\u003e Built end-to-end as a monorepo: Next.js 16 / React 19 / Tailwind v4 web\n\u003e client + Go 1.23 / chi / pgx API + PostgreSQL 16, orchestrated with\n\u003e Docker Compose. RTL throughout, lazy-loaded GSAP motion,\n\u003e 14 JSON-LD schema blocks on the landing page, AI-Overview-friendly\n\u003e `llms.txt`, security headers, and structured per-page metadata.\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#\"\u003e\u003cimg alt=\"Next.js 16\" src=\"https://img.shields.io/badge/Next.js-16-black?style=flat\u0026logo=nextdotjs\"\u003e\u003c/a\u003e\n  \u003ca href=\"#\"\u003e\u003cimg alt=\"React 19\" src=\"https://img.shields.io/badge/React-19-149eca?style=flat\u0026logo=react\"\u003e\u003c/a\u003e\n  \u003ca href=\"#\"\u003e\u003cimg alt=\"Tailwind v4\" src=\"https://img.shields.io/badge/Tailwind-v4-38bdf8?style=flat\u0026logo=tailwindcss\"\u003e\u003c/a\u003e\n  \u003ca href=\"#\"\u003e\u003cimg alt=\"TypeScript\" src=\"https://img.shields.io/badge/TypeScript-strict-3178c6?style=flat\u0026logo=typescript\"\u003e\u003c/a\u003e\n  \u003ca href=\"#\"\u003e\u003cimg alt=\"Go 1.23\" src=\"https://img.shields.io/badge/Go-1.23-00add8?style=flat\u0026logo=go\"\u003e\u003c/a\u003e\n  \u003ca href=\"#\"\u003e\u003cimg alt=\"Postgres 16\" src=\"https://img.shields.io/badge/Postgres-16-336791?style=flat\u0026logo=postgresql\"\u003e\u003c/a\u003e\n  \u003ca href=\"#\"\u003e\u003cimg alt=\"RTL\" src=\"https://img.shields.io/badge/lang-fa--IR%20RTL-229ED9?style=flat\"\u003e\u003c/a\u003e\n  \u003ca href=\"#\"\u003e\u003cimg alt=\"License\" src=\"https://img.shields.io/badge/license-proprietary-lightgrey?style=flat\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003cstrong\u003e\n  #telegram · #osint · #lookup · #phone-lookup · #username-to-phone ·\n  #rtl · #nextjs · #react · #tailwindcss · #typescript · #golang ·\n  #postgres · #docker · #gsap · #chat-ui · #seo · #ai-overviews · #llms-txt · #saas\n\u003c/strong\u003e\u003c/p\u003e\n\n---\n\n## Table of contents\n\n- [What it does](#what-it-does)\n- [Live screenshots](#live-screenshots)\n- [Stack](#stack)\n- [Repository layout](#repository-layout)\n- [Run locally](#run-locally)\n- [Environment](#environment)\n- [API surface](#api-surface)\n- [Pricing model](#pricing-model)\n- [Referral program](#referral-program)\n- [SEO + AI search](#seo--ai-search)\n- [Design system](#design-system)\n- [Performance](#performance)\n- [Security](#security)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## What it does\n\n- **Single lookup** — paste an `@username` or numeric Telegram ID, get the phone number\n  plus (when available) name, email, previous usernames, birthday, country.\n- **Batch lookup** — up to 500 rows per submission. Same per-row pricing.\n  Failures cost nothing.\n- **Bearer-token API** — `POST /api/v1/lookup` with the same wallet billing.\n  curl-friendly, JSON in/out.\n- **Wallet** — top up in Toman via card-to-card with an admin approval step.\n  Transparent ledger of every charge and credit.\n- **Referrals** — both sides receive 200,000 Toman once the referred user's\n  **first top-up is approved**.\n- **Admin** — operator dashboard for users, payments, refunds, abuse flags,\n  upstream providers, resellers, settings.\n\nThe product is positioned as **its own database** of Telegram identity\nmappings. There is no live integration claim, no upstream-provider language\nin user-facing copy, no marketing about Iranian customers (the audience is\ninferred from the language and currency, not stated).\n\n## Live screenshots\n\nThe home page uses a looping chat-style demo where the user sends an\n`@username` and TeleYab \"replies\" with phone + email + previous usernames +\nbirthday — Telegram-flavoured bubbles, typing indicators, magnetic CTAs.\nGSAP drives all scroll-revealed sections.\n\nRun the stack locally (below) and visit:\n\n- `/` — landing + live demo\n- `/pricing` — live price + quick-charge presets (login-gated)\n- `/lookup` — Telegram-chat composer (auth required)\n- `/batch` — bulk upload\n- `/keys` — API token issuance\n- `/referral` — invite link + earnings\n\n## Stack\n\n| Piece            | Tech                                              | Port |\n| ---------------- | ------------------------------------------------- | ---- |\n| Web              | Next.js 16, React 19, Tailwind v4, TypeScript     | 4102 |\n| Web motion       | GSAP 3 + ScrollTrigger (lazy-loaded)              | —    |\n| API              | Go 1.23, chi router, pgx                          | 8084 |\n| DB               | PostgreSQL 16 (Alpine, in Docker)                 | 5436 |\n| Auth             | Email + password, magic-link verification         | —    |\n| Payments         | Card-to-card with admin approval                  | —    |\n| Sessions         | Server-issued, HttpOnly cookies                   | —    |\n| Orchestration    | Docker Compose                                    | —    |\n\nEverything is wired via `docker compose up -d --build`.\n\n## Repository layout\n\n```\n.\n├── cmd/server/          # Go entrypoint\n├── internal/\n│   ├── config/          # env loading + first-run defaults\n│   ├── db/              # pgx wrappers, schema.sql, seed\n│   ├── handlers/        # chi route handlers (auth, lookup, admin, …)\n│   ├── session/         # cookie + DB-backed sessions\n│   └── …\n├── web/\n│   ├── app/             # Next.js 16 app router pages + routes\n│   │   ├── (public)     # /, /pricing, /privacy, /terms, /llms.txt, …\n│   │   ├── (auth)       # /login, /verify\n│   │   ├── (dashboard)  # /lookup, /batch, /keys, /wallet, /topup, /referral\n│   │   └── admin/       # operator UI (8 pages)\n│   ├── components/      # nav, footer, chat primitives, schema-ld, …\n│   ├── lib/             # motion (lazy GSAP), cn, ref-capture, …\n│   └── public/\n├── docker-compose.yml\n├── Dockerfile.api\n├── go.mod\n├── PLAN.md              # architecture + roadmap\n├── CLAUDE.md            # operator guard-rails (token-burn warning, etc.)\n└── README.md            # this file\n```\n\n## Run locally\n\nYou need Docker + Docker Compose. **Do not run a fresh build against the\nproduction upstream key** — see [CLAUDE.md](CLAUDE.md) for the token-burn\nwarning.\n\n```bash\n# clone\ngit clone https://github.com/codedpro/teleyab.git\ncd teleyab\n\n# copy env template + fill in secrets\ncp .env.example .env\n$EDITOR .env\n\n# bring up everything (web on :4102, api on :8084, postgres on :5436)\ndocker compose up -d --build\n\n# verify\ncurl -s http://127.0.0.1:4102/api/public/pricing\nopen http://127.0.0.1:4102\n```\n\nThe first boot seeds default settings into the `settings` table:\n\n- `price_per_lookup_toman` = `800000`\n- `min_topup_toman` = `800000`\n- `max_topup_toman` = `25000000`\n- `referral_bonus_toman` = `200000`\n\nAdjust live from the admin UI at `/admin/settings`. The first user to sign up\nis automatically promoted to `admin` in the DB (or run\n`UPDATE users SET role='admin' WHERE id=1;`).\n\n## Environment\n\n`.env.example` is the source of truth. Required keys, condensed:\n\n| Key                       | Purpose                                            |\n| ------------------------- | -------------------------------------------------- |\n| `DATABASE_URL`            | Postgres DSN (`postgres://teleyab:teleyab@…`)      |\n| `WEB_ORIGIN`              | Used to construct referral share URLs              |\n| `SESSION_COOKIE_DOMAIN`   | Empty for local; set to root domain in prod       |\n| `RESEND_API_KEY`          | Magic-link email delivery                          |\n| `UPSTREAM_*`              | Provider configuration (see PLAN.md §10)           |\n| `NEXT_PUBLIC_SITE_URL`    | Canonical origin (web side)                        |\n\nNever commit a real `.env` — it's in `.gitignore` and reading it counts as\nexfiltration in the security policy.\n\n## API surface\n\nAll routes mounted under `/api`. Authenticated routes require a session\ncookie; the public Bearer route accepts `Authorization: Bearer \u003ctoken\u003e`.\n\n### Public\n\n| Method | Path                          | Notes                                       |\n| ------ | ----------------------------- | ------------------------------------------- |\n| GET    | `/healthz`                    | Liveness probe                              |\n| GET    | `/public/pricing`             | Live `price_per_lookup_toman`, min/max top-up, referral bonus |\n\n### Auth\n\n| Method | Path                  | Notes                                       |\n| ------ | --------------------- | ------------------------------------------- |\n| POST   | `/auth/register`      | Email + password + optional `ref_code`      |\n| POST   | `/auth/login`         | Returns session cookie                      |\n| POST   | `/auth/verify-email`  | Consumes verification token                 |\n| POST   | `/auth/logout`        |                                             |\n\n### User (session required)\n\n| Method | Path                          | Notes                                       |\n| ------ | ----------------------------- | ------------------------------------------- |\n| GET    | `/me`                         | Profile + balance + price                   |\n| POST   | `/lookup`                     | Web-side single lookup (`min_balance` gate) |\n| GET    | `/lookups`                    | History (no upstream call)                  |\n| POST   | `/topup/request`              | Card-to-card submission with receipt        |\n| GET    | `/topup/requests`             | Own top-up history                          |\n| GET    | `/me/referral`                | Own code, share URL, invited count, earned  |\n| POST   | `/lookup/batch`               | Up to 500 rows per submission               |\n| GET    | `/lookup/batch/{id}`          | Per-batch status + per-row results          |\n| GET    | `/keys` / POST `/keys`        | List / create Bearer tokens                 |\n| DELETE | `/keys/{id}`                  | Revoke                                      |\n\n### Public Bearer API\n\n| Method | Path             | Notes                                       |\n| ------ | ---------------- | ------------------------------------------- |\n| POST   | `/v1/lookup`     | Bearer-auth equivalent of web `/lookup`     |\n\nExample:\n\n```bash\ncurl -X POST https://teleyab.ir/api/v1/lookup \\\n  -H \"Authorization: Bearer $TELEYAB_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ \"query\": \"@arman_dev\" }'\n# → { \"success\": true,\n#     \"numbers\": [\"+989124528521\"],\n#     \"country\": \"IR\",\n#     \"cost_toman\": 800000,\n#     \"balance_toman\": 49200000 }\n```\n\n### Admin (role=admin)\n\n`/admin/stats`, `/admin/users`, `/admin/users/{id}/{ban,unban,force-logout,adjust}`,\n`/admin/refunds`, `/admin/refunds/{id}/{resolve,reject}`, `/admin/flags`,\n`/admin/providers` (CRUD + toggle), `/admin/payments` (approve / reject),\n`/admin/resellers`, `/admin/settings`, `/admin/upstream-balance`.\n\n## Pricing model\n\n- **Per successful lookup**: `settings.price_per_lookup_toman` (default 800,000 ﺗﻮﻣﺎن).\n- **Failed lookup**: 0 Toman. No wallet debit.\n- **Minimum top-up**: matches the per-lookup price (800,000 by default).\n- **Currency**: Iranian Toman (IRT).\n\nUser-facing pages always read the live value from `/api/public/pricing` so the\nadmin can change pricing without redeploying.\n\n## Referral program\n\n- Friend signs up with `?ref=\u003ccode\u003e` or enters the code manually.\n- `web/components/ref-capture.tsx` writes the code to `localStorage`\n  (30-day TTL) on any page load, then strips the query so URLs stay clean.\n- `/login` falls back to that storage when its own `?ref=` is absent.\n- Server attaches `users.referred_by` on the friend's first verified login.\n- Bonus (200,000 Toman default) is credited to **both wallets** when the\n  friend's **first top-up is approved by an admin** — not on first lookup.\n- Idempotent: `users.referral_bonus_paid` guards against double-pay.\n- Defensive: skips payout if the referrer is `banned_at`, `flagged_at`,\n  or `is_active=false`.\n\n## SEO + AI search\n\nThe site ships an aggressive on-page + technical SEO baseline:\n\n- **`robots.txt`** — explicit allow for GPTBot, ClaudeBot, PerplexityBot,\n  Google-Extended, OAI-SearchBot, Applebot-Extended, Bingbot, CCBot,\n  cohere-ai, Meta-ExternalAgent; disallow on private routes (`/admin`,\n  `/wallet`, `/topup`, `/verify`, `/api`, `/login`).\n- **`sitemap.xml`** — 8 public routes with realistic priorities + static lastmod.\n- **`llms.txt` + `llms-full.txt`** — llmstxt.org format dump for AI Overviews,\n  Perplexity, ChatGPT, etc. Includes FAQ verbatim, full HowTo, prose\n  excerpts of privacy + terms.\n- **`humans.txt`** — humanstxt.org credits.\n- **`.well-known/security.txt`** — RFC 9116 contact.\n- **`feed.xml`** — RSS 2.0 of the FAQ items.\n- **JSON-LD** — Organization, WebSite (with SearchAction), Service,\n  WebApplication (with AggregateRating / Offer / UnitPriceSpecification),\n  BreadcrumbList, FAQPage, HowTo, SiteNavigationElement, WebPage\n  (TermsOfService / PrivacyPolicy variants). 14 distinct schema blocks on the\n  home page alone.\n- **Security headers** — HSTS, COOP, X-Content-Type-Options, Referrer-Policy,\n  Permissions-Policy, baseline `X-Robots-Tag: index, follow,\n  max-image-preview:large, max-snippet:-1` with per-route `noindex,nofollow`\n  override on dashboard / auth / API.\n- **Per-page metadata** — every public route exports its own title,\n  description, canonical, OG, and Twitter card.\n\n## Design system\n\n- **Palette** — Telegram-blue accent (`#229ED9`), light surface, jade success,\n  rose danger, saffron highlight. Variable names preserved\n  (`--color-persimmon`, `--color-bone`) for backward compatibility with the\n  pre-rebrand pages.\n- **Typography** — Vazirmatn (two weights preloaded as woff2),\n  Inter (Latin sans), JetBrains Mono (code). Font-display: swap.\n- **Components** — `t-card`, `t-btn`, `t-input`, `t-chip` primitives in\n  `globals.css`; chat primitives (`ChatBubble`, `ChatStream`, `ChatShell`,\n  `TypingDots`, `LiveChatDemo`) in `web/components/chat.tsx`.\n- **Motion** — `web/lib/motion.tsx` exports `ScrollReveal`, `StaggerChildren`,\n  `CountUp`, `MagneticHover`, `ParallaxBlob`, `Typewriter`, `useGsap`,\n  `loadGsap`. GSAP is lazy-loaded — never in the critical client graph.\n- **RTL** — `dir=\"rtl\"` on `\u003chtml\u003e`, logical CSS properties\n  (`start`/`end`/`ps`/`pe`) used everywhere. Inputs that accept LTR data\n  (emails, card numbers, queries) wrap in `dir=\"ltr\"` to keep icon\n  positioning and padding aligned.\n\n## Performance\n\n- GSAP + ScrollTrigger lazy-loaded behind a `loadGsap()` singleton —\n  `prefers-reduced-motion` users skip the import entirely.\n- Vazirmatn Regular + Bold preloaded as woff2 (cuts one RTT on RTL copy).\n- DNS prefetch + preconnect for all font hosts.\n- `content-visibility: auto` on long sections; GPU promotion on animated blobs.\n- Next.js standalone build behind a slim Alpine container.\n\n## Security\n\n- HttpOnly session cookies; CSRF surface minimised by same-site cookies +\n  origin-pinned sessions.\n- Open-redirect defence: `/login?next=` validated to start with a single `/`.\n- `maybeApplyReferralBonus` is transactional and idempotent.\n- Admin routes gated by `users.role='admin'` + a session check.\n- Receipt uploads stored under `/uploads/receipts/{filename}` with the\n  filename generated server-side from a timestamp + random hex.\n- Token-burn guard: the `/api/lookup` and `/api/v1/lookup` paths cost real\n  upstream credits — see [CLAUDE.md](CLAUDE.md) for the operational rules.\n\n## Contributing\n\nThis repository is currently maintained by a single operator\n([@codedpro](https://github.com/codedpro)). Issues and PRs are welcome for\ndocumentation fixes, accessibility regressions, RTL copy refinements,\nand obvious bugs. Feature requests outside the\n[non-goals section of PLAN.md](PLAN.md#2-what-this-is-not-deliberate-non-goals)\nwill likely be closed without comment.\n\nBefore opening a PR:\n\n```bash\ncd web \u0026\u0026 npm run typecheck     # TypeScript strict\ncd web \u0026\u0026 npm run build         # Next.js production build\ncd .. \u0026\u0026 go build ./...         # Go API\n```\n\n## License\n\nProprietary. All rights reserved. Source is published for transparency and\nself-hosting reference only; redistribution, commercial reuse, or\nhosting a competing service without written permission is not licensed.\n\n— TeleYab · ۱۴۰۵\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodedpro%2Fteleyab","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodedpro%2Fteleyab","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodedpro%2Fteleyab/lists"}