وثائق TeamOnly

البدء السريع

تحتاج إلى Node.js 20 أو أحدث. لا خطة لديك بعد؟ عند أول تسجيل دخول، يمكنك بدء تجربة مجانية لمدة 14 يومًا دون بطاقة، أو الاشتراك. ويمكنك أيضًا الاشتراك من هنا. في مجلد جديد، أو في مشروع لديك بالفعل:

1. npx teamonly init يضيف تطبيقًا مبدئيًا والتعليمات التي تتبعها أداة الذكاء الاصطناعي لديك.
2. npx teamonly login مرة واحدة لكل جهاز. اكتب بريد العمل والرمز المكوّن من 6 أرقام الذي نرسله إليك. إن لم يكن لشركتك اشتراك بعد، يعرض التجربة المجانية لمدة 14 يومًا، وتبدأ فورًا، أو خطة مع صفحة دفع. اضغط Enter بدلًا من كتابة البريد لتسجيل الدخول من المتصفح.
3. npx teamonly deploy ينشر التطبيق على https://<app>.<company>.teamonly.app.

يبدو هكذا:

$npx teamonly init✔Added the TeamOnly skill, Cursor rules and SDK>ابنِ أداة لاعتماد المصروفات(الذكاء الاصطناعي يبني التطبيق)$npx teamonly login✔Signed in as dana@acme.com$npx teamonly deploy✔Live at https://expenses.acme.teamonly.appOnly @acme.com accounts can sign in

النشر الأول ينشئ التطبيق وقاعدة بياناته وتخزين ملفاته. وعمليات النشر اللاحقة تحدّث التطبيق نفسه على العنوان نفسه.

أوامر CLI

npx teamonly login

سجّل الدخول إلى TeamOnly من هذا الجهاز، مرة واحدة لكل جهاز. اكتب بريد العمل والرمز المكوّن من 6 أرقام الذي نرسله إليك، أو اضغط Enter لتسجيل الدخول من المتصفح. ‏--email و--code يفعلان الشيء نفسه دون أسئلة، لأدوات الذكاء الاصطناعي والسكربتات.

npx teamonly trial --company "Acme"

يبدأ التجربة المجانية لمدة 14 يومًا لشركتك، دون بطاقة. استخدمه بعد login حين لا تكون لشركتك خطة بعد. تجربة واحدة لكل نطاق بريد شركة.

npx teamonly subscribe --plan builder

للاشتراك، أو لإعادة تشغيل التطبيقات بعد التجربة. اختر builder أو team أو business. يفتح صفحة الدفع ويسجّل دخولك هنا بعد الدفع.

npx teamonly init

يجهّز هذا المجلد: تطبيقًا مبدئيًا، أو تعليمات TeamOnly لأداة الذكاء الاصطناعي (مهارة Claude Code، وقواعد Cursor، وAGENTS.md) مع SDK في مشروع قائم.

npx teamonly deploy

يبني التطبيق وينشره. ينشئ قاعدة البيانات وتخزين الملفات عند النشر الأول. ويعرض عنوان التطبيق.

npx teamonly access

يعرض من يمكنه فتح التطبيق. أضف only أو add أو remove مع عناوين البريد لاستخدام قائمة، أو everyone للشركة كلها.

npx teamonly roles

يمنح الأشخاص أدوارًا داخل التطبيق، مثل معتمِد أو مالية. ‏roles add approver dana@acme.com يمنح دورًا، وroles remove يسحبه، وroles وحده يعرض من لديه أي دور. عناوين الشركة فقط.

npx teamonly secrets set NAME

يخزّن سرًا لهذا التطبيق. يُطلب منك إدخال القيمة، فلا تظهر أبدًا في سجل أوامر الطرفية.

npx teamonly logs

تابع طلبات التطبيق الحي ومخرجات console.log والأخطاء لحظة حدوثها. اضغط Ctrl+C للإيقاف.

npx teamonly whoami

يعرض الحساب الذي سجّلت الدخول به، وخطتك، وتطبيقاتك.

npx teamonly delete

يحذف التطبيق الحي مع قاعدة بياناته وملفاته. ويطلب منك كتابة اسم التطبيق أولًا.

npx teamonly logout

تسجيل الخروج من TeamOnly على هذا الجهاز.

SDK

واجهة API لديك تطبيق Hono. تعطي البرمجية الوسيطة في SDK كل طلب سياقًا في c.var.ctx:

ctx.user

الشخص المسجّل الدخول: email وname، وisOwner للشخص الذي نشر التطبيق أول مرة، وroles، أي أدواره في هذا التطبيق. يتحقق منها TeamOnly قبل تشغيل كودك. لا تقرأ الهوية من الترويسات بنفسك أبدًا.

ctx.db

قاعدة بيانات SQL الخاصة بهذا التطبيق (SQLite، على Cloudflare D1). تُنشأ عند النشر الأول.

ctx.files

تخزين ملفات هذا التطبيق: put وget وlist وdelete.

ctx.secrets

قيم مضبوطة بـ npx teamonly secrets set. تُقرأ بـ ctx.secrets.get(name).

ctx.email

يرسل بريدًا إلى الزملاء: send({ to, subject, text, html?, replyTo? }). راجع البريد.

ctx.schedule

اسم المهمة حين يشغّل TeamOnly مهمة مجدولة، وإلا فهو undefined. راجع المهام المجدولة.

في المتصفح، تعيد useUser() من teamonly/react القيمة { email, name, roles }.

import { Hono } from 'hono'
import { teamonly, type TeamOnly } from 'teamonly/server'

const app = new Hono<TeamOnly>()
app.use('*', teamonly())

// Who is signed in. Verified before your code runs.
app.get('/api/me', (c) => {
  return c.json(c.var.ctx.user) // { email: 'dana@acme.com', name: 'Dana Okafor', isOwner: false, roles: ['approver'] }
})

// Save to this app's own database.
app.post('/api/expenses', async (c) => {
  const { db, user } = c.var.ctx
  const { amount, reason } = await c.req.json()
  await db
    .prepare('INSERT INTO expenses (amount, reason, submitted_by) VALUES (?, ?, ?)')
    .bind(amount, reason, user.email)
    .run()
  return c.json({ ok: true })
})

// Store an uploaded receipt in this app's file storage.
app.put('/api/receipts/:id', async (c) => {
  await c.var.ctx.files.put(`receipts/${c.req.param('id')}`, c.req.raw.body)
  return c.json({ ok: true })
})

// Read a secret set with: npx teamonly secrets set QUICKBOOKS_KEY
app.get('/api/sync', async (c) => {
  const key = c.var.ctx.secrets.get('QUICKBOOKS_KEY')
  // ...
})

export default app

البريد

يمكن للتطبيق أن يرسل بريدًا إلى الأشخاص في شركتك عبر ctx.email.send()، مثلًا لإبلاغ معتمِد بأن مصروفًا بانتظاره.

// Tell the approver an expense is waiting.
await c.var.ctx.email.send({
  to: 'priya@acme.com',   // one address or a list, up to 50
  subject: 'An expense is waiting for you',
  text: 'Dana sent a $42 expense. Review it: https://expenses.acme.teamonly.app',
})

• إلى العناوين على نطاقات البريد الخاصة بشركتك فقط، أي الأشخاص أنفسهم الذين يمكنهم تسجيل الدخول. أي عنوان آخر يُرفض ولا يُرسل شيء.
• يُرسل من notify@teamonly.app باسم التطبيق في شركتك، مثل «Expenses at Acme». تذهب الردود إلى مالك التطبيق، إلا إذا ضبطت replyTo (وهو أيضًا عنوان في الشركة).
• كل رسالة تحمل سطرًا يذكر التطبيق الذي أرسلها.
• الحدود لكل تطبيق: 100 مستلم في الساعة و500 في اليوم، وحتى 50 مستلمًا في الرسالة الواحدة.
• صفحة التطبيق في لوحة التحكم تعرض عدد الرسائل التي أرسلها في آخر 30 يومًا.
• محليًا، مع npm run dev، تُطبع الرسائل في الطرفية ولا تُرسل.
• البريد إلى أشخاص خارج شركتك غير مدعوم.

المهام المجدولة

للملخصات اليومية والتذكيرات وتقارير نهاية الشهر، اذكر المهام في teamonly.json. يستدعي TeamOnly كل مسار في تلك الأوقات.

{
  "name": "expenses",
  "timezone": "America/New_York",
  "schedules": [
    { "name": "daily-digest", "cron": "0 9 * * 1-5", "path": "/api/cron/daily-digest" }
  ]
}

import { scheduled } from 'teamonly/server'

// Runs at 9am New York time, Monday to Friday.
app.post('/api/cron/daily-digest', scheduled(async (c) => {
  const { db, email } = c.var.ctx
  // ...find what is waiting, then email each approver
  return c.json({ ok: true })
}))

• لـ cron خمسة حقول: الدقيقة، والساعة، ويوم الشهر، والشهر، ويوم الأسبوع. تعمل المهام عند كل 5 دقائق، لذا يجب أن تكون الدقائق من مضاعفات 5.
• timezone اختياري، والافتراضي UTC.
• ضع المسار داخل scheduled(...) من teamonly/server. من يفتح الرابط يحصل على 404.
• صفحة التطبيق في لوحة التحكم تعرض آخر تشغيل لكل مهمة وهل نجح.
• تتوقف المهام مؤقتًا عند انتهاء التجربة المجانية.

الأدوار

الأدوار مثل معتمِد أو مالية أو مسؤول تُحفظ في TeamOnly، لا في كودك. يمنحها مالك التطبيق أو المسؤول من صفحة التطبيق في لوحة التحكم، أو عبر npx teamonly roles. عناوين الشركة فقط.

$npx teamonly roles add approver dana@acme.com✔Gave dana@acme.com the role approverapprover: dana@acme.com

// Only approvers can approve.
app.post('/api/expenses/:id/approve', async (c) => {
  const { user } = c.var.ctx
  if (!user.roles.includes('approver')) return c.json({ error: 'Approvers only' }, 403)
  // ...
})

يقرؤها التطبيق في ctx.user.roles ويقرر ما يستطيعه كل دور. ولا يزال لا يوجد كود تسجيل دخول لتكتبه.

ملف المهارة

يضيف init ملف مهارة لـ Claude Code والمحتوى نفسه كملف قواعد لـ Cursor. تقرؤه أداة الذكاء الاصطناعي قبل كتابة الكود. ويعلّمها:

• شكل التطبيق الوحيد المدعوم (أدناه)، والبقاء داخله.
• استخدام ctx.user للهوية، وعدم كتابة شاشات خاصة بها لتسجيل الدخول أو التسجيل أو كلمات المرور.
• استخدام ctx.db وctx.files بدل إضافة خدمة قاعدة بيانات أو Express أو Supabase أو Firebase.
• إبقاء مفاتيح API في ctx.secrets، لا في الكود أبدًا.
• إرسال البريد عبر ctx.email، وتشغيل الأعمال المؤقتة كمهام مجدولة، والتحقق من ctx.user.roles على الخادم.
• كيفية تشغيل deploy وإصلاح ما يُبلغ عنه.

الهدف أن ينجح النشر الأول. إن ظل الذكاء الاصطناعي يلجأ إلى شيء لا نشغّله، أخبرنا، فهذا خلل في ملف المهارة.

خادم MCP

تشغّل حزمة teamonly أيضًا خادم MCP، لأدوات الذكاء الاصطناعي التي تفضّل الأدوات على أوامر الطرفية، مثل Claude Desktop أو وكيل Cursor دون طرفية. يعمل على جهازك، لأن النشر يقرأ ملفات مشروعك. أضفه إلى Claude Code بالأمر:

$claude mcp add teamonly -- npx -y teamonly mcp

• Cursor وClaude Desktop وWindsurf: أضف { "mcpServers": { "teamonly": { "command": "npx", "args": ["-y", "teamonly", "mcp"] } } } إلى إعدادات MCP الخاصة بها.
• VS Code: في .vscode/mcp.json المفتاح هو servers، مع "type": "stdio".
• أدواته الاثنتا عشرة: get_app_rules وinit وdeploy وstatus وlogs وaccess وroles وset_secret وsign_in وstart_trial وsubscribe وdelete_app.
• مدرج في سجل MCP الرسمي باسم dev.teamonly/teamonly.

يبقى ملف المهارة والقواعد الطريقة الأساسية التي يتعلم بها الذكاء الاصطناعي البنية، ويعمل CLI كما كان تمامًا. الإعداد لكل أداة، مع زر بنقرة واحدة لـ Cursor: خادم MCP من TeamOnly.

شكل التطبيق المدعوم

• الواجهة: React، مبنية بـ Vite، تُقدَّم كملفات ثابتة.
• واجهة API: تطبيق Hono بـ TypeScript أو JavaScript، تحت /api، على العنوان نفسه.
• بيئة التشغيل: Cloudflare Workers. واجهات الويب القياسية، ومعظم وحدات Node المدمجة عبر طبقة التوافق، لكن دون وحدات أصلية أو عمليات طويلة التشغيل.
• غير مدعوم: Python وRuby وPHP وحاويات Docker وWebSockets والتحديثات الفورية والعمليات الخلفية والبريد إلى أشخاص خارج شركتك والاتصال بخوادم على الشبكة الخاصة لشركتك والنطاقات المخصصة والتطبيقات العامة.

الحدود

الحدود اليوم:

• Builder: مُنشئ واحد، و3 تطبيقات. Team: مُنشئون وتطبيقات بلا حد.
• قاعدة بيانات كل تطبيق وتخزين ملفاته يتبعان حدود Cloudflare D1 وR2.
• تعمل الطلبات ضمن حدود Cloudflare Workers لوقت المعالج والذاكرة.

المزيد عن كيفية ترابط كل ذلك: كيف يعمل والأمان.