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.

عن توثيق YAS.SH

يوثّق هذا القسم واجهات منصة YAS.SH البرمجية: اختصار الروابط وإدارتها، وواجهة الأدوات، والمراقبة، ونموذج المصادقة الذي يحكمها جميعًا. وهو مرجع لا شرح تعليمي، منظّم لتجد المسار ومعاملاته وشكل استجابته ورموز أخطائه دون قراءة ما لا تحتاجه.

يُولَّد مرجع واجهة الأدوات من العقود نفسها التي تغذّي صفحات الأدوات، ما يعني أن المثال على صفحة الأداة والعقد في المرجع لا يمكن أن يفترقا — فهما البيانات ذاتها معروضة مرتين، ويفشل اختبار العقود عند أي اختلاف.

ما الموثّق هنا

واجهة الأدوات
المسار POST /api/v1/tools/:slug لكل أداة تدعم التنفيذ البرمجي، مع المعاملات وأنواعها وقيمها الافتراضية ومثال طلب وشكل الاستجابة.
واجهة الروابط
إنشاء الروابط القصيرة وتحديثها وإنهاؤها والاستعلام عنها، مع المعرّفات المخصصة وقواعد الانتهاء وتحليلات النقرات.
المصادقة
كيفية إصدار مفاتيح الواجهة وتحديد نطاقها وتمريرها، وما يحدث عند إبطال مفتاح أو بلوغ حد المعدل.
الأخطاء والحدود
صيغة الخطأ، ورموز الحالة لكل مسار، وحدود حجم المدخلات والمعدل.

أسئلة شائعة

هل أحتاج إلى مفتاح لاستخدام واجهة الأدوات؟

يمكن استخدام مسارات الأدوات دون مصادقة ضمن حدود مخصصة للاستخدام التفاعلي والأتمتة الخفيفة. أما الاستخدام الأكثف وواجهتا الروابط والمراقبة فتتطلب مفتاحًا من حسابك.

لماذا لا تملك بعض الأدوات واجهة برمجية؟

لأن تنفيذها على الخادم يتيح لمتصل مجهول إرسال طلبات صادرة عشوائية من بنيتنا التحتية، وهو خطر تزوير طلبات من جهة الخادم، أو لأنها تعتمد على واجهة متصفح بلا مقابل على الخادم. وهذه الأدوات مؤشَّرة والسبب مذكور.

ما الحد الأقصى لحجم الطلب؟

تقبل مسارات الأدوات حتى 64 كيلوبايت من المدخلات لكل طلب. والحمولات الأكبر يجب تقسيمها أو معالجتها عبر نسخة المتصفح حيث توجد.

كيف تُعاد الأخطاء؟

كصيغة JSON تحوي رمزًا قابلًا للقراءة آليًا ورسالة مفهومة، مع رمز حالة HTTP المناسب. ورموز الأخطاء مذكورة مع كل مسار.