@pague-dev/sdk-node 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,437 @@
+//#region src/charges/interfaces/charge.interface.d.ts
+type ChargeStatus = 'active' | 'expired' | 'disabled' | 'paid';
+type PaymentMethod = 'pix' | 'credit_card' | 'boleto';
+type NotificationType = 'email';
+interface Charge {
+  id: string;
+  projectId: string;
+  customerId?: string;
+  name: string;
+  description?: string;
+  amount: number;
+  currency: string;
+  status: ChargeStatus;
+  slug: string;
+  url: string;
+  paymentMethods: PaymentMethod[];
+  maxInstallments?: number;
+  notifications: NotificationType[];
+  allowCoupons: boolean;
+  expiresAt?: string;
+  paymentsCount: number;
+  totalCollected: number;
+  createdAt: string;
+  updatedAt?: string;
+}
+//#endregion
+//#region src/interfaces.d.ts
+type Response<T> = {
+  data: T;
+  error: null;
+} | {
+  data: null;
+  error: ErrorResponse;
+};
+interface ErrorResponse {
+  statusCode: number | null;
+  error: string;
+  message: string;
+  details?: Record<string, unknown>;
+  timestamp?: string;
+  traceId?: string;
+}
+interface PaginatedResponse<T> {
+  items: T[];
+  total: number;
+  page: number;
+  limit: number;
+  totalPages: number;
+}
+interface PaginationOptions {
+  page?: number;
+  limit?: number;
+}
+interface GetOptions {
+  query?: Record<string, unknown>;
+}
+interface PostOptions {
+  query?: Record<string, unknown>;
+}
+//#endregion
+//#region src/charges/interfaces/create-charge.interface.d.ts
+interface CreateChargeOptions {
+  projectId: string;
+  name: string;
+  description?: string;
+  amount: number;
+  paymentMethods: PaymentMethod[];
+  expiresAt?: string;
+  customerId?: string;
+}
+type CreateChargeResponse = Response<Charge>;
+//#endregion
+//#region src/charges/interfaces/get-charge.interface.d.ts
+type GetChargeResponse = Response<Charge>;
+//#endregion
+//#region src/charges/interfaces/list-charges.interface.d.ts
+interface ListChargesOptions extends PaginationOptions {
+  search?: string;
+  status?: ChargeStatus;
+  projectId?: string;
+}
+type ListChargesResponse = Response<PaginatedResponse<Charge>>;
+//#endregion
+//#region src/customers/interfaces/customer.interface.d.ts
+type DocumentType = 'cpf' | 'cnpj';
+interface Customer {
+  id: string;
+  name: string;
+  email?: string;
+  phone?: string;
+  documentType: DocumentType;
+  document: string;
+  createdAt: string;
+}
+//#endregion
+//#region src/customers/interfaces/create-customer.interface.d.ts
+interface CreateCustomerOptions {
+  name: string;
+  document: string;
+  email?: string;
+  phone?: string;
+}
+type CreateCustomerResponse = Response<Customer>;
+//#endregion
+//#region src/customers/interfaces/list-customers.interface.d.ts
+interface ListCustomersOptions extends PaginationOptions {
+  search?: string;
+}
+type ListCustomersResponse = Response<PaginatedResponse<Customer>>;
+//#endregion
+//#region src/common/base-resource.d.ts
+/**
+ * Base class for API resources that follow CRUD patterns.
+ * Provides common create, list, and get operations.
+ */
+declare abstract class BaseResource<TEntity, TCreateOptions = never, TListOptions extends object = object> {
+  protected readonly pdev: Pdev;
+  protected abstract readonly endpoint: string;
+  constructor(pdev: Pdev);
+  /**
+   * Create a new entity
+   */
+  create(options: TCreateOptions): Promise<Response<TEntity>>;
+  /**
+   * List entities with pagination
+   */
+  list(options?: TListOptions): Promise<Response<PaginatedResponse<TEntity>>>;
+  /**
+   * Get a single entity by ID
+   */
+  get(id: string): Promise<Response<TEntity>>;
+}
+/**
+ * Base class for resources that only support create operations
+ */
+declare abstract class CreateOnlyResource<TEntity, TCreateOptions> {
+  protected readonly pdev: Pdev;
+  protected abstract readonly endpoint: string;
+  constructor(pdev: Pdev);
+  create(options: TCreateOptions): Promise<Response<TEntity>>;
+}
+/**
+ * Base class for resources that only support get operations
+ */
+declare abstract class GetOnlyResource<TEntity> {
+  protected readonly pdev: Pdev;
+  protected abstract readonly endpoint: string;
+  constructor(pdev: Pdev);
+  get(id: string): Promise<Response<TEntity>>;
+}
+//#endregion
+//#region src/charges/charges.d.ts
+declare class Charges extends BaseResource<Charge, CreateChargeOptions, ListChargesOptions> {
+  protected readonly endpoint = "/charges";
+}
+//#endregion
+//#region src/customers/customers.d.ts
+declare class Customers extends BaseResource<Customer, CreateCustomerOptions, ListCustomersOptions> {
+  protected readonly endpoint = "/customers";
+}
+//#endregion
+//#region src/pix/interfaces/pix.interface.d.ts
+type PixStatus = 'pending' | 'completed' | 'failed' | 'cancelled';
+interface PixCharge {
+  id: string;
+  status: PixStatus;
+  amount: number;
+  currency: string;
+  pixCopyPaste: string;
+  expiresAt: string;
+  externalReference?: string;
+  customerId?: string;
+  createdAt: string;
+}
+//#endregion
+//#region src/pix/interfaces/create-pix.interface.d.ts
+interface CreatePixCustomer {
+  name: string;
+  document: string;
+  email?: string;
+  phone?: string;
+}
+interface CreatePixOptions {
+  amount: number;
+  description?: string;
+  customerId?: string;
+  customer?: CreatePixCustomer;
+  projectId?: string;
+  expiresIn?: number;
+  externalReference?: string;
+  metadata?: Record<string, unknown>;
+}
+type CreatePixResponse = Response<PixCharge>;
+//#endregion
+//#region src/pix/pix.d.ts
+declare class Pix extends CreateOnlyResource<PixCharge, CreatePixOptions> {
+  protected readonly endpoint = "/pix";
+}
+//#endregion
+//#region src/projects/interfaces/project.interface.d.ts
+interface Project {
+  id: string;
+  name: string;
+  description?: string;
+  color: string;
+  logoUrl?: string;
+  createdAt: string;
+}
+//#endregion
+//#region src/projects/interfaces/create-project.interface.d.ts
+interface CreateProjectOptions {
+  name: string;
+  description?: string;
+  color: string;
+  logoUrl?: string;
+}
+type CreateProjectResponse = Response<Project>;
+//#endregion
+//#region src/projects/interfaces/list-projects.interface.d.ts
+type SortBy = 'createdAt' | 'updatedAt' | 'name';
+type SortOrder = 'asc' | 'desc';
+interface ListProjectsOptions extends PaginationOptions {
+  sortBy?: SortBy;
+  sortOrder?: SortOrder;
+}
+type ListProjectsResponse = Response<PaginatedResponse<Project>>;
+//#endregion
+//#region src/projects/projects.d.ts
+declare class Projects extends BaseResource<Project, CreateProjectOptions, ListProjectsOptions> {
+  protected readonly endpoint = "/projects";
+}
+//#endregion
+//#region src/transactions/interfaces/transaction.interface.d.ts
+type TransactionStatus = 'pending' | 'completed' | 'failed' | 'cancelled';
+type TransactionType = 'payment' | 'fee' | 'refund' | 'chargeback' | 'withdrawal';
+type TransactionPaymentMethod = 'pix' | 'credit_card' | 'boleto';
+interface Transaction {
+  id: string;
+  status: TransactionStatus;
+  type: TransactionType;
+  paymentMethod: TransactionPaymentMethod;
+  amount: number;
+  currency: string;
+  description?: string;
+  externalReference?: string;
+  customerId?: string;
+  projectId?: string;
+  metadata?: Record<string, unknown>;
+  pixCopyPaste?: string;
+  expiresAt?: string;
+  paidAt?: string;
+  createdAt: string;
+  updatedAt?: string;
+}
+//#endregion
+//#region src/transactions/interfaces/get-transaction.interface.d.ts
+type GetTransactionResponse = Response<Transaction>;
+//#endregion
+//#region src/transactions/transactions.d.ts
+declare class Transactions extends GetOnlyResource<Transaction> {
+  protected readonly endpoint = "/transactions";
+}
+//#endregion
+//#region src/pdev.d.ts
+declare class Pdev {
+  readonly key: string;
+  private readonly baseUrl;
+  private readonly headers;
+  readonly pix: Pix;
+  readonly customers: Customers;
+  readonly projects: Projects;
+  readonly charges: Charges;
+  readonly transactions: Transactions;
+  constructor(key?: string);
+  post<T>(path: string, body?: unknown, options?: PostOptions): Promise<Response<T>>;
+  get<T>(path: string, options?: GetOptions): Promise<Response<T>>;
+  private buildUrl;
+  private fetchRequest;
+}
+//#endregion
+//#region src/webhooks/interfaces.d.ts
+/**
+ * Available webhook event types
+ */
+type WebhookEventType = 'payment_completed' | 'payment_failed' | 'refund_completed';
+/**
+ * Base webhook payload structure
+ */
+interface WebhookPayload<T extends WebhookEventType, D> {
+  /** Type of event that triggered the webhook */
+  event: T;
+  /** Unique event identifier (typically the transaction ID) */
+  eventId: string;
+  /** ISO 8601 formatted timestamp of when the event occurred */
+  timestamp: string;
+  /** Event-specific data */
+  data: D;
+}
+/**
+ * Data payload for payment_completed event
+ */
+interface PaymentCompletedData {
+  /** Transaction identifier */
+  transactionId: string;
+  /** Payment amount */
+  amount: number;
+  /** Platform fees charged */
+  feeAmount: number;
+  /** Amount received after fees (amount - feeAmount) */
+  netAmount: number;
+  /** Currency code (e.g., "BRL") */
+  currency: string;
+  /** Payment method used (e.g., "pix") */
+  paymentMethod: string;
+  /** Payment status */
+  status: 'completed';
+  /** ISO 8601 timestamp of when payment was completed */
+  completedAt: string;
+}
+/**
+ * Data payload for payment_failed event
+ */
+interface PaymentFailedData {
+  /** Transaction identifier */
+  transactionId: string;
+  /** Payment amount */
+  amount: number;
+  /** Currency code (e.g., "BRL") */
+  currency: string;
+  /** Payment method used (e.g., "pix") */
+  paymentMethod: string;
+  /** Payment status */
+  status: 'failed';
+  /** ISO 8601 timestamp of when payment failed */
+  failedAt: string;
+  /** Reason for failure (e.g., "expired", "insufficient_funds") */
+  failureReason: string;
+}
+/**
+ * Data payload for refund_completed event
+ */
+interface RefundCompletedData {
+  /** Refund transaction identifier */
+  refundTransactionId: string;
+  /** Original payment transaction ID that was refunded */
+  originalTransactionId: string;
+  /** Refunded amount */
+  amount: number;
+  /** Fees (typically 0 for refunds) */
+  feeAmount: number;
+  /** Currency code (e.g., "BRL") */
+  currency: string;
+  /** Refund status */
+  status: 'completed';
+  /** ISO 8601 timestamp of when refund was completed */
+  refundedAt: string;
+}
+/**
+ * Payment completed webhook event
+ */
+type PaymentCompletedEvent = WebhookPayload<'payment_completed', PaymentCompletedData>;
+/**
+ * Payment failed webhook event
+ */
+type PaymentFailedEvent = WebhookPayload<'payment_failed', PaymentFailedData>;
+/**
+ * Refund completed webhook event
+ */
+type RefundCompletedEvent = WebhookPayload<'refund_completed', RefundCompletedData>;
+/**
+ * Union type of all possible webhook events
+ */
+type WebhookEvent = PaymentCompletedEvent | PaymentFailedEvent | RefundCompletedEvent;
+/**
+ * Webhook headers sent with each request
+ */
+interface WebhookHeaders {
+  /** HMAC-SHA256 signature of the payload */
+  'x-webhook-signature': string;
+  /** Unix timestamp in milliseconds when webhook was sent */
+  'x-webhook-timestamp': string;
+  /** Content type (always application/json) */
+  'content-type': string;
+}
+//#endregion
+//#region src/webhooks/verify.d.ts
+/**
+ * Parses a webhook payload and returns a type-safe WebhookEvent.
+ * Returns null if the payload is invalid.
+ *
+ * @param payload - The raw request body as a string
+ * @returns Parsed WebhookEvent or null if invalid
+ *
+ * @example
+ * ```typescript
+ * import { parseWebhook } from 'pague-dev';
+ *
+ * app.post('/webhook', (req, res) => {
+ *   // 1. Verify signature first (implement using your framework)
+ *   // const isValid = verifySignature(req.body, req.headers['x-webhook-signature'], secret);
+ *
+ *   // 2. Parse the webhook payload
+ *   const event = parseWebhook(req.body);
+ *
+ *   if (!event) {
+ *     return res.status(400).send('Invalid webhook payload');
+ *   }
+ *
+ *   // 3. Handle the event with full type safety
+ *   switch (event.event) {
+ *     case 'payment_completed':
+ *       // event.data is PaymentCompletedData
+ *       console.log('Payment completed:', event.data.transactionId);
+ *       console.log('Amount:', event.data.amount);
+ *       console.log('Net amount:', event.data.netAmount);
+ *       break;
+ *
+ *     case 'payment_failed':
+ *       // event.data is PaymentFailedData
+ *       console.log('Payment failed:', event.data.transactionId);
+ *       console.log('Reason:', event.data.failureReason);
+ *       break;
+ *
+ *     case 'refund_completed':
+ *       // event.data is RefundCompletedData
+ *       console.log('Refund completed:', event.data.refundTransactionId);
+ *       console.log('Original transaction:', event.data.originalTransactionId);
+ *       break;
+ *   }
+ *
+ *   res.status(200).send('OK');
+ * });
+ * ```
+ */
+declare function parseWebhook(payload: string): WebhookEvent | null;
+//#endregion
+export { Charge, ChargeStatus, CreateChargeOptions, CreateChargeResponse, CreateCustomerOptions, CreateCustomerResponse, CreatePixCustomer, CreatePixOptions, CreatePixResponse, CreateProjectOptions, CreateProjectResponse, Customer, DocumentType, type ErrorResponse, GetChargeResponse, GetTransactionResponse, ListChargesOptions, ListChargesResponse, ListCustomersOptions, ListCustomersResponse, ListProjectsOptions, ListProjectsResponse, NotificationType, type PaginatedResponse, type PaginationOptions, PaymentCompletedData, PaymentCompletedEvent, PaymentFailedData, PaymentFailedEvent, PaymentMethod, Pdev, PixCharge, PixStatus, Project, RefundCompletedData, RefundCompletedEvent, type Response, SortBy, SortOrder, Transaction, TransactionPaymentMethod, TransactionStatus, TransactionType, WebhookEvent, WebhookEventType, WebhookHeaders, WebhookPayload, parseWebhook };

package/dist/index.mjs

@@ -0,0 +1,263 @@
+//#region src/common/utils/build-pagination-query.ts
+function buildPaginationQuery(options) {
+	const searchParams = new URLSearchParams();
+	for (const [key, value] of Object.entries(options)) if (value !== void 0 && value !== null) searchParams.set(key, String(value));
+	return searchParams.toString();
+}
+
+//#endregion
+//#region src/common/base-resource.ts
+/**
+* Base class for API resources that follow CRUD patterns.
+* Provides common create, list, and get operations.
+*/
+var BaseResource = class {
+	constructor(pdev) {
+		this.pdev = pdev;
+	}
+	/**
+	* Create a new entity
+	*/
+	async create(options) {
+		return this.pdev.post(this.endpoint, options);
+	}
+	/**
+	* List entities with pagination
+	*/
+	async list(options = {}) {
+		const queryString = buildPaginationQuery(options);
+		const path = queryString ? `${this.endpoint}?${queryString}` : this.endpoint;
+		return this.pdev.get(path);
+	}
+	/**
+	* Get a single entity by ID
+	*/
+	async get(id) {
+		return this.pdev.get(`${this.endpoint}/${id}`);
+	}
+};
+/**
+* Base class for resources that only support create operations
+*/
+var CreateOnlyResource = class {
+	constructor(pdev) {
+		this.pdev = pdev;
+	}
+	async create(options) {
+		return this.pdev.post(this.endpoint, options);
+	}
+};
+/**
+* Base class for resources that only support get operations
+*/
+var GetOnlyResource = class {
+	constructor(pdev) {
+		this.pdev = pdev;
+	}
+	async get(id) {
+		return this.pdev.get(`${this.endpoint}/${id}`);
+	}
+};
+
+//#endregion
+//#region src/charges/charges.ts
+var Charges = class extends BaseResource {
+	endpoint = "/charges";
+};
+
+//#endregion
+//#region src/config.ts
+const config = { baseUrl: "https://api.pague.dev/v1" };
+
+//#endregion
+//#region src/customers/customers.ts
+var Customers = class extends BaseResource {
+	endpoint = "/customers";
+};
+
+//#endregion
+//#region src/pix/pix.ts
+var Pix = class extends CreateOnlyResource {
+	endpoint = "/pix";
+};
+
+//#endregion
+//#region src/projects/projects.ts
+var Projects = class extends BaseResource {
+	endpoint = "/projects";
+};
+
+//#endregion
+//#region src/transactions/transactions.ts
+var Transactions = class extends GetOnlyResource {
+	endpoint = "/transactions";
+};
+
+//#endregion
+//#region src/pdev.ts
+var Pdev = class {
+	key;
+	baseUrl;
+	headers;
+	pix;
+	customers;
+	projects;
+	charges;
+	transactions;
+	constructor(key) {
+		if (!key) {
+			if (typeof process !== "undefined" && process.env) this.key = process.env.PDEV_API_KEY || "";
+			else this.key = "";
+			if (!this.key) throw new Error("Missing API key. Pass it to the constructor `new Pdev(\"pd_live_xxx\")` or set the PDEV_API_KEY environment variable.");
+		} else this.key = key;
+		this.baseUrl = config.baseUrl;
+		this.headers = new Headers({
+			"X-API-Key": this.key,
+			"Content-Type": "application/json"
+		});
+		this.pix = new Pix(this);
+		this.customers = new Customers(this);
+		this.projects = new Projects(this);
+		this.charges = new Charges(this);
+		this.transactions = new Transactions(this);
+	}
+	async post(path, body, options = {}) {
+		const url = this.buildUrl(path, options.query);
+		return this.fetchRequest(url, {
+			method: "POST",
+			headers: this.headers,
+			body: body ? JSON.stringify(body) : void 0
+		});
+	}
+	async get(path, options = {}) {
+		const url = this.buildUrl(path, options.query);
+		return this.fetchRequest(url, {
+			method: "GET",
+			headers: this.headers
+		});
+	}
+	buildUrl(path, query) {
+		let url = `${this.baseUrl}${path}`;
+		if (query) {
+			const searchParams = new URLSearchParams();
+			for (const [key, value] of Object.entries(query)) if (value !== void 0 && value !== null) searchParams.set(key, String(value));
+			const queryString = searchParams.toString();
+			if (queryString) url += `?${queryString}`;
+		}
+		return url;
+	}
+	async fetchRequest(url, options) {
+		try {
+			const response = await fetch(url, options);
+			if (!response.ok) try {
+				const rawError = await response.text();
+				return {
+					data: null,
+					error: JSON.parse(rawError)
+				};
+			} catch {
+				return {
+					data: null,
+					error: {
+						statusCode: response.status,
+						error: "UnknownError",
+						message: "An unexpected error occurred"
+					}
+				};
+			}
+			return {
+				data: await response.json(),
+				error: null
+			};
+		} catch {
+			return {
+				data: null,
+				error: {
+					statusCode: null,
+					error: "NetworkError",
+					message: "Unable to fetch data. The request could not be resolved."
+				}
+			};
+		}
+	}
+};
+
+//#endregion
+//#region src/webhooks/verify.ts
+/**
+* Type guard to check if an event is a valid WebhookEvent
+*/
+function isValidWebhookEvent(event) {
+	if (typeof event !== "object" || event === null) return false;
+	const obj = event;
+	if (typeof obj.event !== "string") return false;
+	if (typeof obj.eventId !== "string") return false;
+	if (typeof obj.timestamp !== "string") return false;
+	if (typeof obj.data !== "object" || obj.data === null) return false;
+	return [
+		"payment_completed",
+		"payment_failed",
+		"refund_completed"
+	].includes(obj.event);
+}
+/**
+* Parses a webhook payload and returns a type-safe WebhookEvent.
+* Returns null if the payload is invalid.
+*
+* @param payload - The raw request body as a string
+* @returns Parsed WebhookEvent or null if invalid
+*
+* @example
+* ```typescript
+* import { parseWebhook } from 'pague-dev';
+*
+* app.post('/webhook', (req, res) => {
+*   // 1. Verify signature first (implement using your framework)
+*   // const isValid = verifySignature(req.body, req.headers['x-webhook-signature'], secret);
+*
+*   // 2. Parse the webhook payload
+*   const event = parseWebhook(req.body);
+*
+*   if (!event) {
+*     return res.status(400).send('Invalid webhook payload');
+*   }
+*
+*   // 3. Handle the event with full type safety
+*   switch (event.event) {
+*     case 'payment_completed':
+*       // event.data is PaymentCompletedData
+*       console.log('Payment completed:', event.data.transactionId);
+*       console.log('Amount:', event.data.amount);
+*       console.log('Net amount:', event.data.netAmount);
+*       break;
+*
+*     case 'payment_failed':
+*       // event.data is PaymentFailedData
+*       console.log('Payment failed:', event.data.transactionId);
+*       console.log('Reason:', event.data.failureReason);
+*       break;
+*
+*     case 'refund_completed':
+*       // event.data is RefundCompletedData
+*       console.log('Refund completed:', event.data.refundTransactionId);
+*       console.log('Original transaction:', event.data.originalTransactionId);
+*       break;
+*   }
+*
+*   res.status(200).send('OK');
+* });
+* ```
+*/
+function parseWebhook(payload) {
+	let parsed;
+	try {
+		parsed = JSON.parse(payload);
+	} catch {
+		return null;
+	}
+	if (!isValidWebhookEvent(parsed)) return null;
+	return parsed;
+}
+
+//#endregion
+export { Pdev, parseWebhook };