cp .env.example .env
# Set SESSION_SECRET and a unique SEED_ADMIN_PASSWORD (never use examples)
# SEED_ADMIN_PASSWORD="$(openssl rand -base64 24)" 
pnpm install --frozen-lockfile
bash scripts/copy-blog-images.sh
pnpm db:push
SEED_ADMIN_EMAIL=admin@localhost SEED_ADMIN_PASSWORD="$SEED_ADMIN_PASSWORD" pnpm db:seed
pnpm dev
# http://localhost:3000 → sign in with the email/password YOU set above

Works identically on macOS and Oracle Linux 9. See #production.

Installation

Requirements: Node ≥22.13 <25 (required by pnpm 11.20.0), pnpm 11.20.0 (corepack), Sharp (libvips), Prisma (openssl), MariaDB 11 prod or SQLite dev.

node -v # v20.20.2
pnpm -v # 9.12.3
openssl version # OpenSSL 3.x

Oracle Linux 9: dnf install openssl vips + nodesource.

Configuration

All config via env + next.config.mjs + CSS vars.

Theme: app/globals.css :root --brand/--bg + components/theme-provider.tsx 7 palettes.

Images: next.config images.remotePatterns locked to yas.sh / unsplash / cdn. AVIF/WebP.

Environment Variables

DATABASE_URL"file:./dev.db" dev, "mysql://user:pass@host:3306/yas" prod

SESSION_SECRET"32+ random chars — openssl rand -hex 32"

BASE_URL"http://localhost:3000" dev, "https://yas.sh" prod

SEED_ADMIN_EMAIL/PASSWORDset your own (dev only) — never commit; blocked in production

REDIS_URL"redis://localhost:6379" optional Valkey for rate-limit/cache

NODE_ENVdevelopment | production

Never commit real secrets. .env.example is placeholder.

Deployment

Three options — local build, Docker, Coolify.

pnpm build && pnpm start
# or
docker compose up -d
# or Coolify on Oracle Linux 9 — see docs/10_DEPLOYMENT.md

Standalone when BUILD_STANDALONE=true — copies minimal deps for Docker.

API Guide

Base /api/v1 • OpenAPI 3.1 at /api/v1/openapi • Errors application/problem+json.

GET /api/v1/links?search=&limit=20&cursor=

POST /api/v1/links {originalUrl}

Full reference →

Authentication

Cookie: yas_session httpOnly Secure SameSite Lax — for dashboard.

Bearer: Authorization: Bearer yas_live_… — for servers, auto hashed (SHA-256), lastUsedAt tracked.

curl -H "Authorization: Bearer yas_live_abc123" https://yas.sh/api/v1/links

Scopes: links:read,links:write,analytics:read. Rotate via /api/v1/api-keys show-once, 10 max.

Search

Global ⌘K opens Fuse.js index of pages/tools/blogs. Endpoint /api/search/index serves blog slugs.

Link Intelligence

Shorten (random base62 7 chars + alias) → 302 redirect (lookup cacheable, optional Valkey) → ClickEvent (geo/device/referrer, bot filtered) → analytics rollup.

Every share hits same redirect — single source of truth. Password (bcrypt), expiry (datetime/clicks), QR sync via short code.

Blog System

See Blog Guide. Co-located blog/content/<slug>/index.mdx + hero.webp, auto SSG, sanitized marked, JSON-LD, i18n EN/AR RTL, sticky TOC, progress bar.

Project Structure

app/            Next.js (marketing, dashboard, blog/[slug], docs, api/v1, [code], status, case-studies)
components/ui/  Card/Badge/Button/Input + blog-progress/theme-provider/search
lib/            api-helpers, api-sdk (UI→REST), auth, prisma, utils, validators, tools-def
blog/content/   MDX + hero/cover/thumb per post (EN + AR)
prisma/         schema.prisma + seed.ts
public/blog-img/ served images (copied via script)
scripts/        smoke.sh, security-smoke.sh, copy-blog-images.sh (POSIX)
docs/           markdown + BLOG_GUIDE.md

Development Workflow

Add feature = add folder (app/tools/[slug] + lib/tools-def) — no core edits.
UI never imports Prisma — only lib/api-sdk.ts → REST /v1.
Theme via CSS vars — change 2 vars to rebrand.
Blog via file system — no registry.
Test: pnpm build + bash scripts/smoke.sh + BASE= prod bash scripts/security-smoke.sh.

Production Deployment (Oracle Linux 9)

sudo dnf install -y openssl vips
# Node 22 LTS via nodesource, pnpm 11.20.0 via corepack (Node 22.13+ required)
cp .env.example .env # edit
pnpm install --frozen-lockfile
pnpm db:push && pnpm db:seed
bash scripts/copy-blog-images.sh
pnpm build
pnpm start # behind Nginx with CSP (next.config headers)

Nginx: proxy + HSTS, 4GB RAM recommended for build, 1GB runtime.

Troubleshooting

Build OOM: Use BUILD_STANDALONE=true pnpm build or 4GB instance.

Prisma engine: openssl version must be 3.x; prisma generate on postinstall.

Blog 404: Check slug /^[a-z0-9-]+$/, file index.mdx, run copy script.

/contact not sending: Check Web3Forms key, honeypot, network tab.

Theme flash: ThemeProvider sets vars post-hydration — default palette SSR matches to avoid FOUC.

Deployment

Self-host yas.sh: Docker, Coolify, or standalone Next behind Nginx with TLS. Operational runbook is available to operators — see the deploy/ and docs/ folders in the repo.

Security →Contact →

User Guide

Getting started, the full feature tour, tutorials, FAQ, and troubleshooting for end users.

Read the user guide →

FAQ

Free limit?

50 links, 1k clicks/mo, 1 API key. Pro 5k/100k, Business 50k/1M.

Backups?

Documented in the operations runbook (see docs/15). Backups are an operator responsibility; retention and encryption depend on deployment configuration.

Support SLA?

Target response via Contact; formal SLAs are agreed per contract for paid/Enterprise plans.

i18n?

EN + AR RTL supported, dir auto, locale frontmatter.

O dokumentácii YAS.SH

Táto sekcia dokumentuje API platformy YAS.SH: skracovanie a správu odkazov, API nástrojov, monitoring a autentifikačný model, ktorý ich všetky zastrešuje. Ide o referenciu, nie o tutoriál, usporiadanú tak, aby ste našli endpoint, jeho parametre, tvar odpovede a chybové kódy bez čítania toho, čo nepotrebujete.

Referencia API nástrojov sa generuje z tých istých strojovo čitateľných kontraktov, ktoré poháňajú stránky nástrojov. Príklad na stránke nástroja a kontrakt v referencii sa preto nemôžu rozísť — sú to tie isté dáta vykreslené dvakrát a kontraktný test build zhodí pri akomkoľvek rozdiele.

Čo je tu zdokumentované

API nástrojov
POST /api/v1/tools/:slug pre každý nástroj s programovým spustením, s parametrami, typmi, predvolenými hodnotami, príkladom požiadavky a presným tvarom odpovede.
API odkazov
Vytváranie, úprava, expirácia a dopytovanie krátkych odkazov vrátane vlastných slugov, pravidiel expirácie a analytiky klikov.
Autentifikácia
Ako sa vydávajú a obmedzujú API kľúče, ako sa odovzdávajú a čo sa stane pri zneplatnení kľúča alebo dosiahnutí limitu.
Chyby a limity
Obálka chyby, stavové kódy jednotlivých endpointov a limity veľkosti vstupu aj frekvencie.

Často kladené otázky

Potrebujem API kľúč na používanie API nástrojov?

Endpointy nástrojov sa dajú používať bez autentifikácie v rámci limitov určených na interaktívne a ľahké automatizované použitie. Väčší objem a API odkazov či monitoringu vyžadujú kľúč z vášho účtu.

Prečo niektoré nástroje nemajú API?

Pretože ich serverové spustenie by anonymnému volajúcemu umožnilo posielať ľubovoľné odchádzajúce požiadavky z našej infraštruktúry, čo je riziko SSRF, alebo pretože závisia od API prehliadača bez serverového ekvivalentu. Tieto nástroje sú označené a dôvod je uvedený.

Aká je maximálna veľkosť požiadavky?

Endpointy nástrojov prijímajú do 64 kB vstupu na požiadavku. Väčšie objemy treba rozdeliť alebo spracovať prehliadačovou verziou nástroja tam, kde existuje.

Ako sa vracajú chyby?

Ako JSON obálka so strojovo čitateľným kódom a zrozumiteľnou správou spolu s príslušným HTTP stavom. Chybové kódy sú uvedené pri každom endpointe.