خانه
نمای کلی

مرجع

مرجع API

src/index.ts هفت ماژول را دوباره صادر می‌کند. این برابر ۱۵ نماد صادرشده است، به‌علاوه دو متد روی UnoPay. هر مدخل زیر از سورس منتقل شده، نه از README پکیج.

یک ماژول عمداً به‌عنوان عمومی مستند نشده

src/http.ts مقادیر request و HttpOptions را صادر می‌کند، اما src/index.ts هرگز آن‌ها را دوباره صادر نمی‌کند. پس داخلی‌اند و صفحه‌ای ندارند — که دلیل دیگری است برای اینکه زمان‌بندی ۱۰ ثانیه‌ای از کد شما قابل تنظیم نیست. پیش از جستجوی تنظیمی که وجود ندارد، این را بدانید.

PaymentRequest

ورودی متد UnoPay.createPayment. یک مبلغ، یک واحد پول، یک نشانی کال‌بک و یک کیسه باز برای متادیتای درگاه.

interface · src/types.ts

PaymentResult

نتیجه یک فراخوانی موفق createPayment. هر سه فیلد وضعیت پرداخت را پیش از وریفای توصیف می‌کنند.

interface · src/types.ts

CallbackRequest

کال‌بک ورودی درگاه، مستقل از فریم‌ورک به یک شکل واحد تخت شده است. تبدیل درخواست فریم‌ورک خودتان به این سه فیلد بر عهده شماست.

interface · src/types.ts

VerificationResult

نتیجه verifyCallback. پرداخت ردشده در اینجا یک مقدار بازگشتی عادی است، نه خطای پرتاب‌شده.

interface · src/types.ts

PaymentLogger

سطح لاگ ساختاریافته‌ای که UnoPay صدا می‌زند. Pino، Winston و console همگی از نظر ساختاری آن را برآورده می‌کنند، پس نیازی به آداپتور نیست.

interface · src/logger.ts

PaymentError

کلاس پایه تمام خطاهایی که SDK تولید می‌کند. برای گرفتن هر چیزی که UnoPay پرتاب می‌کند این را بگیرید.

class · src/errors.ts

PaymentValidationError

SDK ورودی را پیش از تماس با درگاه یا به‌جای آن رد کرده است.

class · src/errors.ts

GatewayNetworkError

درخواست هرگز پاسخ HTTP تولید نکرد: خطای DNS، قطع اتصال، یا خاتمه پس از ۱۰ ثانیه.

class · src/errors.ts

InvalidSignatureError

برای آداپتورهایی که امضای درگاه را اعتبارسنجی می‌کنند رزرو شده است. صادر شده و آماده است، اما در کد نسخه ۱٫۰٫۰ هرگز پرتاب نمی‌شود.

class · src/errors.ts

GatewayProviderError

درگاه پاسخ داد و پاسخ موفق نبود. این رایج‌ترین خطایی است که مدیریت می‌کنید.

class · src/errors.ts

toRials

مبلغ را به ریال نرمال می‌کند. کل لایه واحد پول همین است — پنج خط، بدون پیکربندی.

function · src/currency.ts

UnoPay

نقطه ورود. یک بار با درگاه‌هایی که پیکربندی کرده‌اید آن را می‌سازید؛ از آن پس کلید درگاه در هر فراخوانی در زمان کامپایل با همان نگاشت بررسی می‌شود.

class · src/client.ts

UnoPay.createPayment

از درگاه نام‌برده می‌خواهد پرداخت را آغاز کند و محل ارسال پرداخت‌کننده را برمی‌گرداند. قید K یک درگاه ناشناخته را به خطای کامپایل تبدیل می‌کند نه خطای زمان اجرا.

method · src/client.ts:12

UnoPay.verifyCallback

پرداخت را نزد درگاه تایید می‌کند و پاسخ را یکسان‌سازی می‌کند. پرداخت‌کننده‌ای که پرداخت را رها کرده به‌صورت نتیجه false برمی‌گردد، نه استثنا.

method · src/client.ts:33

GatewayAdapter

قرارداد دومتدی که هر درگاه پیاده می‌کند. چون به همین اندازه کوچک است، نوشتن آداپتور خودتان کار کوتاهی است — و UnoPay آن را هرجا آداپتور داخلی بپذیرد می‌پذیرد.

interface · src/adapters/base.ts

ZarinpalConfig

پیکربندی ZarinpalAdapter. سه فیلد، که تنها یکی از آن‌ها الزامی است.

interface · src/adapters/zarinpal.ts

ZarinpalAdapter

تنها درگاه کاملاً پیاده‌سازی‌شده که با REST API نسخه ۴ زرین‌پال صحبت می‌کند. هم‌زمان مرجعی برای شکل درست یک آداپتور است.

class · src/adapters/zarinpal.ts

toRials — تنها تابع واحد پول

functiontoRials

مبلغ را به ریال نرمال می‌کند. کل لایه واحد پول همین است — پنج خط، بدون پیکربندی.

export function toRials(amount: number, currency: string): number;

پارامترها

نام	تایپ	الزامی	توضیح
`amount`	`number`	بله	مبلغ بر حسب واحد داده‌شده.
`currency`	`string`	بله	واحد پول. پس از toUpperCase بدون حساسیت به بزرگی حروف مقایسه می‌شود.

خروجی

number — مبلغ در ۱۰ ضرب‌شده وقتی currency برابر IRT یا TOMAN باشد، در غیر این صورت مبلغ بدون تغییر.

نکته

هر چیزی که IRT یا TOMAN نباشد بی‌صدا IRR فرض می‌شود. برای کد ناشناخته خطایی پرتاب نمی‌شود، بنابراین غلط املایی مثل TOMN هم به‌صورت ریال عبور می‌کند.

نکته

ضریب ۱۰ است و گرد کردنی انجام نمی‌شود، بنابراین اگر ورودی عدد صحیح باشد مبلغ هم صحیح می‌ماند.

نمونه کد

toRials.tsts

toRials(50000, 'IRT');     // 500000
toRials(50000, 'toman');   // 500000
toRials(500000, 'IRR');    // 500000
toRials(50000, 'TOMN');    // 50000  <- typo, silently read as IRR

صادرشده اما عمومی نیست

این دو نماد در سورس صادر می‌شوند ولی به بسته عمومی نمی‌رسند. اگر آن‌ها را از مسیر عمیق ایمپورت کنید به نسخه بعدی وابسته می‌شوید.

نام	ماژول	چرا عمومی نیست
`request`	`src/http.ts`	پوشش‌دهنده مشترک fetch که هر آداپتور صدا می‌زند. هرگز از src/index.ts دوباره صادر نمی‌شود.
`HttpOptions`	`src/http.ts`	مقدار timeoutMs را نگه می‌دارد، ولی چون ماژول دوباره صادر نمی‌شود از کد برنامه در دسترس نیست. به همین دلیل زمان‌بندی ۱۰ ثانیه‌ای قابل تغییر نیست.

همه موارد استفاده از any

ادعای «صفر any» در README پکیج دقیقاً یک استثنا دارد. اینجا همه محل‌هایی که در سورس پیدا می‌شوند آمده‌اند — سه مورد در کامیت 4a04be5.

محل	کد
`src/types.ts:17`	`body: Record<string, any>;`
`src/adapters/zarinpal.ts:30`	`await request<any>(...)`
`src/adapters/zarinpal.ts:65`	`await request<any>(...)`