@pagouai/api-sdk 0.1.1-next.7

package/README.md

@@ -0,0 +1,231 @@
+# Pagou.ai TypeScript SDK (`/v2`)
+
+Cross-runtime SDK template for Node.js 18+, Bun, and Deno.
+
+- Resource-first API (`client.transactions.*`)
+- `fetch`-based (no axios)
+- Typed errors
+- Retries + timeout + idempotency
+- Native `/v2` page/limit pagination
+
+## Install
+
+```bash
+bun add @pagouai/api-sdk
+# or npm i / pnpm add
+```
+
+## Quick Start
+
+```ts
+import { Client } from "@pagouai/api-sdk";
+
+const client = new Client({
+	apiKey: "YOUR_API_KEY",
+	timeoutMs: 30_000,
+	maxRetries: 2,
+	telemetry: true,
+});
+```
+
+## Configuration
+
+```ts
+new Client({
+	apiKey: "YOUR_API_KEY",
+	environment: "production", // default: "production"
+	// environment: "sandbox",
+	// baseUrl: "https://api.sandbox.pagou.ai", // explicit override if needed
+	timeoutMs: 30_000,
+	maxRetries: 2,
+	telemetry: true,
+	userAgent: "PagouTS-SDK/0.1.0 (Transactions; +https://pagou.ai)",
+	fetch: customFetch,
+	auth: { scheme: "bearer" }, // default
+	// apiVersion: "2026-02-01",
+});
+```
+
+Auth schemes:
+
+- `bearer` (default) -> `Authorization: Bearer <apiKey>`
+- `basic` -> `Authorization: Basic <base64(apiKey:x)>`
+- `api_key_header` -> `apikey: <apiKey>` (or custom `headerName`)
+
+Default base URLs:
+
+- production: `https://api.pagou.ai`
+- sandbox/test: `https://api.sandbox.pagou.ai`
+
+## API Coverage (`/v2`)
+
+- `POST /v2/transactions`
+- `GET /v2/transactions`
+- `GET /v2/transactions/{id}`
+- `PUT /v2/transactions/{id}` (test/sandbox-only behavior)
+- `PUT /v2/transactions/{id}/refund`
+
+## Usage Examples
+
+### 1) Create a transaction
+
+For `method: "pix"`, `buyer.document` is required and `buyer.document.type` must be uppercase:
+- `CPF`
+- `CNPJ`
+
+```ts
+const created = await client.transactions.create({
+	amount: 1500,
+	method: "pix",
+	currency: "BRL",
+	buyer: {
+		name: "Jane Doe",
+		email: "jane@example.com",
+		document: {
+			type: "CPF",
+			number: "12345678901",
+		},
+	},
+	products: [{ name: "Pro Plan", price: 1500, quantity: 1 }],
+});
+
+console.log(created.data.id, created.meta.requestId);
+```
+
+### 2) Retrieve a transaction
+
+```ts
+const tx = await client.transactions.retrieve("tr_123");
+console.log(tx.data.status);
+```
+
+### 3) List transactions with page/limit + filters
+
+```ts
+const page = await client.transactions.list({
+	page: 1,
+	limit: 20,
+	status: ["pending", "paid"],
+	paymentMethods: ["pix"],
+});
+
+console.log(page.data.metadata.total);
+for (const item of page.data.data) {
+	console.log(item.id, item.status);
+}
+```
+
+### 4) Update a transaction (test/sandbox only)
+
+```ts
+const updated = await client.transactions.update(
+	"tr_123",
+	{ status: "paid" },
+	{ idempotencyKey: "idem_update_tr_123_1" },
+);
+
+console.log(updated.data.status);
+```
+
+### 5) Auto-paging iterator
+
+```ts
+for await (const item of client.transactions.listAutoPagingIterator({ limit: 100 })) {
+	console.log(item.id);
+}
+```
+
+### 6) Refund a transaction
+
+```ts
+const refunded = await client.transactions.refund(
+	"tr_123",
+	{ amount: 500, reason: "requested_by_customer" },
+	{ idempotencyKey: "idem_refund_tr_123_1" },
+);
+
+console.log(refunded.data);
+```
+
+## Request Options
+
+All resource methods accept `opts?`:
+
+```ts
+{
+	idempotencyKey?: string;
+	requestId?: string;
+	timeoutMs?: number;
+	signal?: AbortSignal;
+}
+```
+
+## Retries and Timeout
+
+Retries happen for:
+
+- Network errors
+- `429`, `500`, `502`, `503`, `504`
+
+Rules:
+
+- Always retry for `GET`/`HEAD`
+- Retry `POST`/`PUT` only when `idempotencyKey` is set
+- Respect `Retry-After` header when available
+
+Timeout uses `AbortController`.
+
+## Error Handling
+
+```ts
+import {
+	AuthenticationError,
+	InvalidRequestError,
+	NotFoundError,
+	RateLimitError,
+	ServerError,
+	NetworkError,
+} from "@pagouai/api-sdk";
+
+try {
+	await client.transactions.retrieve("tr_404");
+} catch (error) {
+	if (error instanceof NotFoundError) {
+		console.error("Missing transaction", error.requestId);
+	} else if (error instanceof RateLimitError) {
+		console.error("Back off", error.status, error.code);
+	} else if (error instanceof NetworkError) {
+		console.error("Network issue", error.message);
+	} else if (error instanceof InvalidRequestError || error instanceof AuthenticationError || error instanceof ServerError) {
+		console.error(error.message);
+	} else {
+		throw error;
+	}
+}
+```
+
+## Response Shapes
+
+Data endpoints:
+
+```ts
+{
+	success: boolean;
+	requestId: string;
+	data: T;
+}
+```
+
+List endpoints:
+
+```ts
+{
+	success: boolean;
+	requestId: string;
+	metadata: { page: number; limit: number; total: number };
+	data: T[];
+}
+```
+
+Notes:
+- This SDK uses `/v2` endpoint paths.

package/dist/client.d.ts

@@ -0,0 +1,50 @@
+import { TransactionsResource } from "./resources/transactions";
+import type { ApiResponse, ClientOptions, PaginatedEnvelope, RequestOptions } from "./types";
+type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD";
+interface RawResponse {
+    status: number;
+    headers: Headers;
+    body: unknown;
+    requestId?: string;
+}
+interface RequestInput {
+    method: HttpMethod;
+    path: string;
+    query?: Record<string, unknown>;
+    body?: unknown;
+    options?: RequestOptions;
+}
+/**
+ * Main SDK client for Pagou.ai API.
+ */
+export declare class Client {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly telemetry;
+    private readonly userAgent;
+    private readonly fetchImpl;
+    private readonly auth;
+    private readonly apiVersion?;
+    private readonly retryBaseDelayMs;
+    private readonly maxRetryDelayMs;
+    readonly transactions: TransactionsResource;
+    constructor(options: ClientOptions);
+    /**
+     * Sends a request and unwraps a data envelope.
+     */
+    requestData<T>(input: RequestInput): Promise<ApiResponse<T>>;
+    /**
+     * Sends a request and unwraps a paginated envelope.
+     */
+    requestPaginated<T>(input: RequestInput): Promise<ApiResponse<PaginatedEnvelope<T>>>;
+    requestRaw(input: RequestInput): Promise<RawResponse>;
+    private prepareRequest;
+    private applyAuthHeader;
+    private applyVersionHeader;
+    private applyTelemetryHeaders;
+    private toApiError;
+}
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,KAAK,EACX,WAAW,EAGX,aAAa,EAGb,iBAAiB,EACjB,cAAc,EAEd,MAAM,SAAS,CAAC;AAajB,KAAK,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAUvE,UAAU,WAAW;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,YAAY;IACrB,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,cAAc,CAAC;CACzB;AAED;;GAEG;AACH,qBAAa,MAAM;IAClB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAU;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IAEzC,SAAgB,YAAY,EAAE,oBAAoB,CAAC;gBAEvC,OAAO,EAAE,aAAa;IAoBlC;;OAEG;IACU,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAiBzE;;OAEG;IACU,gBAAgB,CAAC,CAAC,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;IAiBpF,UAAU,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAsElE,OAAO,CAAC,cAAc;IA+FtB,OAAO,CAAC,eAAe;IAgBvB,OAAO,CAAC,kBAAkB;IAQ1B,OAAO,CAAC,qBAAqB;IAa7B,OAAO,CAAC,UAAU;CA+BlB"}