@payzcore/node 1.0.1

package/README.md

@@ -0,0 +1,188 @@
+# @payzcore/node
+
+Official Node.js SDK for the [PayzCore](https://payzcore.com) blockchain monitoring API.
+
+Monitor incoming stablecoin transfers (USDT, USDC) across multiple chains (TRC20, BEP20, ERC20, Polygon, Arbitrum) with typed methods and automatic webhook verification.
+
+## Installation
+
+```bash
+npm install @payzcore/node
+```
+
+Requires Node.js 18+. Zero runtime dependencies.
+
+## Supported Chains & Tokens
+
+| Chain | Network | Tokens |
+|-------|---------|--------|
+| `TRC20` | Tron | USDT, USDC |
+| `BEP20` | BNB Smart Chain | USDT, USDC |
+| `ERC20` | Ethereum | USDT, USDC |
+| `POLYGON` | Polygon | USDT, USDC |
+| `ARBITRUM` | Arbitrum One | USDT, USDC |
+
+Token defaults to `'USDT'` if not specified, so existing code works without changes.
+
+## Quick Start
+
+```typescript
+import PayzCore from '@payzcore/node'
+
+const payz = new PayzCore('pk_live_xxx')
+
+// Create a payment monitoring request
+const { payment } = await payz.payments.create({
+  amount: 50,
+  chain: 'TRC20',
+  externalRef: 'user-123',
+})
+
+console.log(payment.address) // Blockchain address to monitor
+console.log(payment.amount)  // Amount with random cents (e.g. "50.07")
+console.log(payment.token)   // Token name (e.g. "USDT")
+console.log(payment.qrCode)  // QR code data URL
+```
+
+## Configuration
+
+```typescript
+const payz = new PayzCore('pk_live_xxx', {
+  baseUrl: 'https://api.payzcore.com', // default
+  timeout: 30000,                       // default 30s
+  maxRetries: 2,                        // default 2 (retries on 5xx/network errors)
+})
+```
+
+## Payments
+
+### Create
+
+```typescript
+const { payment } = await payz.payments.create({
+  amount: 50,
+  chain: 'TRC20',              // 'TRC20' | 'BEP20' | 'ERC20' | 'POLYGON' | 'ARBITRUM'
+  token: 'USDT',              // 'USDT' | 'USDC' (optional, defaults to 'USDT')
+  externalRef: 'user-123',     // your reference
+  externalOrderId: 'order-456', // optional
+  expiresIn: 3600,             // optional, seconds (300–86400)
+  metadata: { type: 'topup' }, // optional
+})
+
+// payment.id, payment.address, payment.amount, payment.token, payment.expiresAt, payment.qrCode
+```
+
+#### USDC on Polygon Example
+
+```typescript
+const { payment } = await payz.payments.create({
+  amount: 100,
+  chain: 'POLYGON',
+  token: 'USDC',
+  externalRef: 'user-456',
+})
+```
+
+### List
+
+```typescript
+const { payments } = await payz.payments.list({
+  status: 'paid', // optional filter
+  limit: 20,      // optional, max 100
+  offset: 0,      // optional
+})
+```
+
+### Get (Real-Time)
+
+```typescript
+const { payment } = await payz.payments.get('payment-uuid')
+
+// Triggers real-time blockchain check for pending payments
+// payment.transactions[].txHash, payment.transactions[].amount, etc.
+```
+
+## Projects (Admin)
+
+Requires a master key (`mk_xxx`):
+
+```typescript
+const admin = new PayzCore('mk_xxx', { masterKey: true })
+
+const { project } = await admin.projects.create({
+  name: 'My Store',
+  slug: 'my-store',
+  webhookUrl: 'https://mysite.com/webhooks',
+})
+
+const { projects } = await admin.projects.list()
+```
+
+## Webhook Verification
+
+```typescript
+import { verifyWebhookSignature, constructEvent } from '@payzcore/node'
+
+// In your webhook handler (Express, Next.js, etc.)
+export async function POST(req: Request) {
+  const body = await req.text()
+  const signature = req.headers.get('x-payzcore-signature')!
+
+  // Option 1: Just verify
+  const isValid = verifyWebhookSignature(body, signature, 'whsec_xxx')
+
+  // Option 2: Verify + parse (throws WebhookSignatureError if invalid)
+  const event = constructEvent(body, signature, 'whsec_xxx')
+
+  if (event.event === 'payment.completed') {
+    console.log(event.paymentId, event.paidAmount)
+  }
+
+  return new Response('ok')
+}
+```
+
+### Webhook Events
+
+| Event | Description |
+|-------|-------------|
+| `payment.completed` | Payment fully received |
+| `payment.overpaid` | Received more than expected |
+| `payment.partial` | Partial payment received |
+| `payment.expired` | Payment window expired |
+
+## Error Handling
+
+All errors extend `PayzCoreError` with `status`, `code`, and optional `details`:
+
+```typescript
+import { PayzCoreError, RateLimitError, ValidationError } from '@payzcore/node'
+
+try {
+  await payz.payments.create({ ... })
+} catch (err) {
+  if (err instanceof RateLimitError) {
+    console.log(err.retryAfter) // Unix timestamp
+    console.log(err.isDaily)    // true if daily plan limit
+  } else if (err instanceof ValidationError) {
+    console.log(err.details)    // field-level errors
+  } else if (err instanceof PayzCoreError) {
+    console.log(err.status, err.message)
+  }
+}
+```
+
+### Error Classes
+
+| Class | Status | When |
+|-------|--------|------|
+| `AuthenticationError` | 401 | Invalid/missing API key |
+| `ForbiddenError` | 403 | Project deactivated |
+| `NotFoundError` | 404 | Payment/resource not found |
+| `ValidationError` | 400 | Invalid request body |
+| `RateLimitError` | 429 | Rate limit or daily plan limit exceeded |
+| `WebhookSignatureError` | — | Invalid webhook signature |
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,231 @@
+type Chain = 'TRC20' | 'BEP20' | 'ERC20' | 'POLYGON' | 'ARBITRUM';
+type Token = 'USDT' | 'USDC';
+type PaymentStatus = 'pending' | 'confirming' | 'partial' | 'paid' | 'overpaid' | 'expired' | 'cancelled';
+type WebhookEventType = 'payment.completed' | 'payment.overpaid' | 'payment.partial' | 'payment.expired';
+interface PayzCoreOptions {
+    /** API base URL. Default: https://api.payzcore.com */
+    baseUrl?: string;
+    /** Request timeout in ms. Default: 30000 */
+    timeout?: number;
+    /** Max retries on 5xx/network errors. Default: 2 */
+    maxRetries?: number;
+    /** Use master key auth (x-master-key header). Default: false */
+    masterKey?: boolean;
+}
+interface CreatePaymentParams {
+    amount: number;
+    chain: Chain;
+    /** Token to monitor. Default: 'USDT' */
+    token?: Token;
+    externalRef: string;
+    externalOrderId?: string;
+    /** Expiry in seconds (300–86400). Default: 3600 */
+    expiresIn?: number;
+    metadata?: Record<string, unknown>;
+}
+interface Payment {
+    id: string;
+    address: string;
+    amount: string;
+    chain: Chain;
+    token: string;
+    status: PaymentStatus;
+    expiresAt: string;
+    externalOrderId?: string;
+    qrCode?: string;
+}
+interface CreatePaymentResponse {
+    success: true;
+    existing: boolean;
+    payment: Payment;
+}
+interface PaymentListItem {
+    id: string;
+    externalRef: string;
+    externalOrderId?: string;
+    chain: Chain;
+    token: string;
+    address: string;
+    expectedAmount: string;
+    paidAmount: string;
+    status: PaymentStatus;
+    txHash: string | null;
+    expiresAt: string;
+    paidAt: string | null;
+    createdAt: string;
+}
+interface ListPaymentsParams {
+    status?: PaymentStatus;
+    limit?: number;
+    offset?: number;
+}
+interface ListPaymentsResponse {
+    success: true;
+    payments: PaymentListItem[];
+}
+interface Transaction {
+    txHash: string;
+    amount: string;
+    from: string;
+    confirmed: boolean;
+}
+interface PaymentDetail {
+    id: string;
+    status: PaymentStatus;
+    expectedAmount: string;
+    paidAmount: string;
+    address: string;
+    chain: Chain;
+    token: string;
+    txHash: string | null;
+    expiresAt: string;
+    transactions: Transaction[];
+}
+interface GetPaymentResponse {
+    success: true;
+    payment: PaymentDetail;
+}
+interface CreateProjectParams {
+    name: string;
+    slug: string;
+    webhookUrl?: string;
+    metadata?: Record<string, unknown>;
+}
+interface Project {
+    id: string;
+    name: string;
+    slug: string;
+    apiKey: string;
+    webhookSecret: string;
+    webhookUrl: string | null;
+    createdAt: string;
+}
+interface CreateProjectResponse {
+    success: true;
+    project: Project;
+}
+interface ProjectListItem {
+    id: string;
+    name: string;
+    slug: string;
+    apiKey: string;
+    webhookUrl: string | null;
+    isActive: boolean;
+    createdAt: string;
+}
+interface ListProjectsResponse {
+    success: true;
+    projects: ProjectListItem[];
+}
+interface WebhookPayload {
+    event: WebhookEventType;
+    paymentId: string;
+    externalRef: string;
+    externalOrderId?: string;
+    chain: Chain;
+    token: string;
+    address: string;
+    expectedAmount: string;
+    paidAmount: string;
+    txHash: string | null;
+    status: PaymentStatus;
+    paidAt: string | null;
+    metadata: Record<string, unknown>;
+    timestamp: string;
+}
+interface ApiErrorBody {
+    error: string;
+    details?: Array<{
+        code: string;
+        path?: string[];
+        message: string;
+    }>;
+    limit?: number;
+    plan?: string;
+}
+
+declare class HttpClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly maxRetries;
+    private readonly useMasterKey;
+    constructor(apiKey: string, options?: PayzCoreOptions);
+    request<T>(method: string, path: string, body?: unknown): Promise<T>;
+    get<T>(path: string): Promise<T>;
+    post<T>(path: string, body: unknown): Promise<T>;
+}
+
+declare class Payments {
+    private readonly client;
+    constructor(client: HttpClient);
+    create(params: CreatePaymentParams): Promise<CreatePaymentResponse>;
+    list(params?: ListPaymentsParams): Promise<ListPaymentsResponse>;
+    get(id: string): Promise<GetPaymentResponse>;
+}
+
+declare class Projects {
+    private readonly client;
+    constructor(client: HttpClient);
+    create(params: CreateProjectParams): Promise<CreateProjectResponse>;
+    list(): Promise<ListProjectsResponse>;
+}
+
+/**
+ * Verify a webhook signature from PayzCore.
+ *
+ * @param body - Raw request body string
+ * @param signature - Value of X-PayzCore-Signature header
+ * @param secret - Webhook secret from project creation (whsec_xxx)
+ * @returns true if signature is valid
+ */
+declare function verifyWebhookSignature(body: string, signature: string, secret: string): boolean;
+/**
+ * Verify signature and parse the webhook payload.
+ * Throws WebhookSignatureError if signature is invalid.
+ *
+ * @param body - Raw request body string
+ * @param signature - Value of X-PayzCore-Signature header
+ * @param secret - Webhook secret from project creation (whsec_xxx)
+ * @returns Parsed and typed webhook payload
+ */
+declare function constructEvent(body: string, signature: string, secret: string): WebhookPayload;
+
+declare class PayzCoreError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details?: Array<{
+        code: string;
+        path?: string[];
+        message: string;
+    }>;
+    constructor(message: string, status: number, code: string, details?: ApiErrorBody['details']);
+}
+declare class AuthenticationError extends PayzCoreError {
+    constructor(message?: string);
+}
+declare class ForbiddenError extends PayzCoreError {
+    constructor(message?: string);
+}
+declare class NotFoundError extends PayzCoreError {
+    constructor(message?: string);
+}
+declare class ValidationError extends PayzCoreError {
+    constructor(message: string, details?: ApiErrorBody['details']);
+}
+declare class RateLimitError extends PayzCoreError {
+    readonly retryAfter: number | null;
+    readonly isDaily: boolean;
+    constructor(message: string, retryAfter?: number | null, isDaily?: boolean);
+}
+declare class WebhookSignatureError extends Error {
+    constructor(message?: string);
+}
+
+declare class PayzCore {
+    readonly payments: Payments;
+    readonly projects: Projects;
+    constructor(apiKey: string, options?: PayzCoreOptions);
+}
+
+export { AuthenticationError, type Chain, type CreatePaymentParams, type CreatePaymentResponse, type CreateProjectParams, type CreateProjectResponse, ForbiddenError, type GetPaymentResponse, type ListPaymentsParams, type ListPaymentsResponse, type ListProjectsResponse, NotFoundError, type Payment, type PaymentDetail, type PaymentListItem, type PaymentStatus, PayzCore, PayzCoreError, type PayzCoreOptions, type Project, type ProjectListItem, RateLimitError, type Token, type Transaction, ValidationError, type WebhookEventType, type WebhookPayload, WebhookSignatureError, constructEvent, PayzCore as default, verifyWebhookSignature };

package/dist/index.d.ts

@@ -0,0 +1,231 @@
+type Chain = 'TRC20' | 'BEP20' | 'ERC20' | 'POLYGON' | 'ARBITRUM';
+type Token = 'USDT' | 'USDC';
+type PaymentStatus = 'pending' | 'confirming' | 'partial' | 'paid' | 'overpaid' | 'expired' | 'cancelled';
+type WebhookEventType = 'payment.completed' | 'payment.overpaid' | 'payment.partial' | 'payment.expired';
+interface PayzCoreOptions {
+    /** API base URL. Default: https://api.payzcore.com */
+    baseUrl?: string;
+    /** Request timeout in ms. Default: 30000 */
+    timeout?: number;
+    /** Max retries on 5xx/network errors. Default: 2 */
+    maxRetries?: number;
+    /** Use master key auth (x-master-key header). Default: false */
+    masterKey?: boolean;
+}
+interface CreatePaymentParams {
+    amount: number;
+    chain: Chain;
+    /** Token to monitor. Default: 'USDT' */
+    token?: Token;
+    externalRef: string;
+    externalOrderId?: string;
+    /** Expiry in seconds (300–86400). Default: 3600 */
+    expiresIn?: number;
+    metadata?: Record<string, unknown>;
+}
+interface Payment {
+    id: string;
+    address: string;
+    amount: string;
+    chain: Chain;
+    token: string;
+    status: PaymentStatus;
+    expiresAt: string;
+    externalOrderId?: string;
+    qrCode?: string;
+}
+interface CreatePaymentResponse {
+    success: true;
+    existing: boolean;
+    payment: Payment;
+}
+interface PaymentListItem {
+    id: string;
+    externalRef: string;
+    externalOrderId?: string;
+    chain: Chain;
+    token: string;
+    address: string;
+    expectedAmount: string;
+    paidAmount: string;
+    status: PaymentStatus;
+    txHash: string | null;
+    expiresAt: string;
+    paidAt: string | null;
+    createdAt: string;
+}
+interface ListPaymentsParams {
+    status?: PaymentStatus;
+    limit?: number;
+    offset?: number;
+}
+interface ListPaymentsResponse {
+    success: true;
+    payments: PaymentListItem[];
+}
+interface Transaction {
+    txHash: string;
+    amount: string;
+    from: string;
+    confirmed: boolean;
+}
+interface PaymentDetail {
+    id: string;
+    status: PaymentStatus;
+    expectedAmount: string;
+    paidAmount: string;
+    address: string;
+    chain: Chain;
+    token: string;
+    txHash: string | null;
+    expiresAt: string;
+    transactions: Transaction[];
+}
+interface GetPaymentResponse {
+    success: true;
+    payment: PaymentDetail;
+}
+interface CreateProjectParams {
+    name: string;
+    slug: string;
+    webhookUrl?: string;
+    metadata?: Record<string, unknown>;
+}
+interface Project {
+    id: string;
+    name: string;
+    slug: string;
+    apiKey: string;
+    webhookSecret: string;
+    webhookUrl: string | null;
+    createdAt: string;
+}
+interface CreateProjectResponse {
+    success: true;
+    project: Project;
+}
+interface ProjectListItem {
+    id: string;
+    name: string;
+    slug: string;
+    apiKey: string;
+    webhookUrl: string | null;
+    isActive: boolean;
+    createdAt: string;
+}
+interface ListProjectsResponse {
+    success: true;
+    projects: ProjectListItem[];
+}
+interface WebhookPayload {
+    event: WebhookEventType;
+    paymentId: string;
+    externalRef: string;
+    externalOrderId?: string;
+    chain: Chain;
+    token: string;
+    address: string;
+    expectedAmount: string;
+    paidAmount: string;
+    txHash: string | null;
+    status: PaymentStatus;
+    paidAt: string | null;
+    metadata: Record<string, unknown>;
+    timestamp: string;
+}
+interface ApiErrorBody {
+    error: string;
+    details?: Array<{
+        code: string;
+        path?: string[];
+        message: string;
+    }>;
+    limit?: number;
+    plan?: string;
+}
+
+declare class HttpClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly maxRetries;
+    private readonly useMasterKey;
+    constructor(apiKey: string, options?: PayzCoreOptions);
+    request<T>(method: string, path: string, body?: unknown): Promise<T>;
+    get<T>(path: string): Promise<T>;
+    post<T>(path: string, body: unknown): Promise<T>;
+}
+
+declare class Payments {
+    private readonly client;
+    constructor(client: HttpClient);
+    create(params: CreatePaymentParams): Promise<CreatePaymentResponse>;
+    list(params?: ListPaymentsParams): Promise<ListPaymentsResponse>;
+    get(id: string): Promise<GetPaymentResponse>;
+}
+
+declare class Projects {
+    private readonly client;
+    constructor(client: HttpClient);
+    create(params: CreateProjectParams): Promise<CreateProjectResponse>;
+    list(): Promise<ListProjectsResponse>;
+}
+
+/**
+ * Verify a webhook signature from PayzCore.
+ *
+ * @param body - Raw request body string
+ * @param signature - Value of X-PayzCore-Signature header
+ * @param secret - Webhook secret from project creation (whsec_xxx)
+ * @returns true if signature is valid
+ */
+declare function verifyWebhookSignature(body: string, signature: string, secret: string): boolean;
+/**
+ * Verify signature and parse the webhook payload.
+ * Throws WebhookSignatureError if signature is invalid.
+ *
+ * @param body - Raw request body string
+ * @param signature - Value of X-PayzCore-Signature header
+ * @param secret - Webhook secret from project creation (whsec_xxx)
+ * @returns Parsed and typed webhook payload
+ */
+declare function constructEvent(body: string, signature: string, secret: string): WebhookPayload;
+
+declare class PayzCoreError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details?: Array<{
+        code: string;
+        path?: string[];
+        message: string;
+    }>;
+    constructor(message: string, status: number, code: string, details?: ApiErrorBody['details']);
+}
+declare class AuthenticationError extends PayzCoreError {
+    constructor(message?: string);
+}
+declare class ForbiddenError extends PayzCoreError {
+    constructor(message?: string);
+}
+declare class NotFoundError extends PayzCoreError {
+    constructor(message?: string);
+}
+declare class ValidationError extends PayzCoreError {
+    constructor(message: string, details?: ApiErrorBody['details']);
+}
+declare class RateLimitError extends PayzCoreError {
+    readonly retryAfter: number | null;
+    readonly isDaily: boolean;
+    constructor(message: string, retryAfter?: number | null, isDaily?: boolean);
+}
+declare class WebhookSignatureError extends Error {
+    constructor(message?: string);
+}
+
+declare class PayzCore {
+    readonly payments: Payments;
+    readonly projects: Projects;
+    constructor(apiKey: string, options?: PayzCoreOptions);
+}
+
+export { AuthenticationError, type Chain, type CreatePaymentParams, type CreatePaymentResponse, type CreateProjectParams, type CreateProjectResponse, ForbiddenError, type GetPaymentResponse, type ListPaymentsParams, type ListPaymentsResponse, type ListProjectsResponse, NotFoundError, type Payment, type PaymentDetail, type PaymentListItem, type PaymentStatus, PayzCore, PayzCoreError, type PayzCoreOptions, type Project, type ProjectListItem, RateLimitError, type Token, type Transaction, ValidationError, type WebhookEventType, type WebhookPayload, WebhookSignatureError, constructEvent, PayzCore as default, verifyWebhookSignature };