@undernouzen/ay-payments-sdk 1.0.2 → 1.0.3

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 1.0.3
+
+- Reorganized public SDK types by module.
+- Added typed `ApiResult<T>` responses.
+- Added `isApiError`, `isContextError` and `isExternalProviderError` helpers.
+- Sanitized connected account types so public SDK responses do not expose `accessToken` or `refreshToken`.
+- Added module-specific package exports.
+
+## 1.0.2
+
+- Updated package scope to `@undernouzen/ay-payments-sdk`.
+- Added AY Payments docs homepage.
+
+## 1.0.0
+
+- Initial SDK client for AY Payments API v1.

package/README.md

@@ -1,20 +1,20 @@
 # AY Payments SDK
 
-Documentacao completa: https://aypayments.undernouzen.com.br/docs/
+TypeScript/JavaScript SDK for the AY Payments API.
 
-SDK TypeScript/JavaScript para consumir a API do AY Payments.
+Full docs: https://aypayments.undernouzen.com.br/docs/
 
-O pacote não lê `.env`. A autenticação é passada na inicialização. Se você criar o client sem `apiKey`, ele continua funcionando como instância HTTP, mas as rotas protegidas vão depender de sessão/cookie ou retornar erro de autenticação da API.
-
-## Instalação
+## Install
 
 ```bash
 npm install @undernouzen/ay-payments-sdk
 ```
 
-Se o escopo `@ay-payments` não estiver disponível no npm, publique como `@undernouzen/ay-payments-sdk` ou outro escopo seu e mantenha os imports equivalentes.
+```bash
+pnpm add @undernouzen/ay-payments-sdk
+```
 
-## Criar o client
+## Create a client
 
 ```ts
 import { createAYPaymentsClient } from "@undernouzen/ay-payments-sdk";
@@ -25,13 +25,13 @@ const ay = createAYPaymentsClient({
 });
 ```
 
-Por padrão, o client usa:
+The default API base is:
 
-```text
+```txt
 https://aypayments.undernouzen.com.br/api/v1
 ```
 
-Você também pode passar a URL exata da API:
+You can also pass the exact API URL:
 
 ```ts
 const ay = createAYPaymentsClient({
@@ -40,28 +40,24 @@ const ay = createAYPaymentsClient({
 });
 ```
 
-## Autenticação
+## Authentication
 
-Authorization Bearer é o padrão:
+Default:
 
-```ts
-const ay = createAYPaymentsClient({
-  baseUrl: "https://aypayments.undernouzen.com.br",
-  apiKey: "ayp_secret",
-});
+```http
+Authorization: Bearer ayp_secret
 ```
 
-Usando `x-api-key`:
+Use `x-api-key` instead:
 
 ```ts
 const ay = createAYPaymentsClient({
-  baseUrl: "https://aypayments.undernouzen.com.br",
   apiKey: "ayp_secret",
   authHeader: "x-api-key",
 });
 ```
 
-Usando Authorization sem `Bearer`:
+Send the raw key in `Authorization`:
 
 ```ts
 const ay = createAYPaymentsClient({
@@ -70,56 +66,68 @@ const ay = createAYPaymentsClient({
 });
 ```
 
-Sem autenticação:
+The client can be created without an API key. Protected routes will then depend on session cookies or return an API auth error.
+
+## Error handling
+
+Mapped SDK methods return `ApiResult<T>`, which is either the expected response or an `ErrorResponse`.
 
 ```ts
-const ay = createAYPaymentsClient();
-```
+import { createAYPaymentsClient, isApiError } from "@undernouzen/ay-payments-sdk";
 
-## Versionamento
+const ay = createAYPaymentsClient({ apiKey: "ayp_secret" });
 
-A versão padrão é `v1`.
+const result = await ay.projects.accounts.list("project-id-or-external-id");
+
+if (isApiError(result)) {
+  console.log(result.error);
+  return;
+}
+
+console.log(result.accounts);
+```
+
+Error shapes:
 
 ```ts
-const ay = createAYPaymentsClient({
-  baseUrl: "https://aypayments.undernouzen.com.br",
-  apiVersion: "v1",
-});
+type ErrorResponse = CommunError | ContextError | ExternalProviderError;
+```
+
+## Versioning
 
+`v1` is the default.
+
+```ts
 await ay.v1.projects.list();
 ```
 
-Os atalhos abaixo apontam para `v1`:
+Convenience aliases point to `v1`:
 
 ```ts
 await ay.projects.list();
-await ay.products.list();
+await ay.products.listByProject("project-id");
 await ay.checkouts.create(payload);
 ```
 
-## Raw Axios
+## Raw requests
 
-Para rotas novas que ainda não foram mapeadas:
+Use `raw` or the exposed Axios instance for endpoints not mapped yet.
 
 ```ts
-const response = await ay.raw<{ ok: boolean }>({
+const result = await ay.raw<{ ok: boolean }>({
   method: "GET",
-  url: "/minha-rota",
+  url: "/projects",
 });
 ```
 
-Você também pode usar a instância diretamente:
-
 ```ts
 const response = await ay.api.get("/projects");
 ```
 
 ## Projects
 
-Criar ou atualizar por `externalId`:
-
 ```ts
-const { project, created } = await ay.projects.create({
+const result = await ay.projects.create({
   externalId: "832320430277918720",
   name: "Vagalumes",
   webhookUrl: "https://guildbuilders.example.com/webhooks/aypayments",
@@ -127,32 +135,15 @@ const { project, created } = await ay.projects.create({
     guildId: "832320430277918720",
   },
 });
-```
-
-Listar:
-
-```ts
-const { projects, pagination } = await ay.projects.list({
-  page: 1,
-  limit: 50,
-});
-```
-
-Buscar com query parcial, incluindo metadata:
 
-```ts
-const result = await ay.projects.query({
-  metadata: {
-    guildId: "832320430277918720",
-  },
-});
+if (!isApiError(result)) {
+  console.log(result.project.id, result.created);
+}
 ```
 
-O identificador do projeto aceita `id` interno ou `externalId` nas rotas que usam `projectIdOrExternalId`.
+## Connected accounts
 
-## Contas conectadas
-
-Gerar URL OAuth:
+Generate an OAuth URL:
 
 ```ts
 const oauth = await ay.projects.accounts.oauth({
@@ -162,43 +153,34 @@ const oauth = await ay.projects.accounts.oauth({
   redirectUrl: "https://guildbuilders.example.com/connect/result",
 });
 
-console.log(oauth.authorizationUrl);
+if (!isApiError(oauth)) {
+  console.log(oauth.authorizationUrl);
+}
 ```
 
-Listar contas:
+List connected accounts:
 
 ```ts
-const { accounts } = await ay.projects.accounts.list("832320430277918720");
-```
-
-Editar nome/status:
+const accounts = await ay.projects.accounts.list("832320430277918720");
 
-```ts
-await ay.projects.accounts.update("832320430277918720", "connection-id", {
-  name: "Conta Pix principal",
-  status: "active",
-});
+if (!isApiError(accounts)) {
+  console.log(accounts.accounts);
+}
 ```
 
-Remover:
-
-```ts
-await ay.projects.accounts.delete("832320430277918720", "connection-id");
-```
+Public connected account responses never expose `accessToken` or `refreshToken`.
 
 ## Products
 
-Produtos usam `value`. Comissão não é calculada no produto; ela é calculada no checkout.
-
-Criar produto:
+Products use `value`. Product routes do not calculate platform commission; commission is calculated by checkout routes.
 
 ```ts
-const { product } = await ay.products.create("832320430277918720", {
+const product = await ay.products.create("832320430277918720", {
   connectedAccountId: "330692399",
   name: "Cargo VIP",
+  value: 19.9,
   icon: "https://cdn.example.com/vip.png",
   description: "Acesso VIP no Discord",
-  value: 19.9,
   fees: [
     {
       name: "Taxa operacional",
@@ -208,63 +190,30 @@ const { product } = await ay.products.create("832320430277918720", {
       active: true,
     },
   ],
-  metadata: {
-    discordRoleId: "123",
-  },
-});
-```
-
-Listar por projeto:
-
-```ts
-const { products } = await ay.products.listByProject("832320430277918720");
-```
-
-Buscar produtos:
-
-```ts
-const result = await ay.products.query({
-  metadata: {
-    discordRoleId: "123",
-  },
 });
 ```
 
 ## Checkouts
 
-### Calcular sem criar cobrança
-
-Use `calculate` para exibir o resumo antes de gerar Pix, boleto ou Checkout Pro/Stripe Checkout.
+Calculate totals without creating an order/payment:
 
 ```ts
 const calculation = await ay.checkouts.calculate({
-  items: [
-    {
-      productId: "product-id",
-      quantity: 1,
-    },
-  ],
+  items: [{ productId: "product-id", quantity: 1 }],
   customer: {
     email: "cliente@example.com",
     name: "Cliente Teste",
   },
   currency: "BRL",
 });
-
-console.log(calculation.summary.amount);
 ```
 
-### Criar checkout com produto cadastrado
+Create a real checkout:
 
 ```ts
 const checkout = await ay.checkouts.create({
   paymentMethod: "pix",
-  items: [
-    {
-      productId: "product-id",
-      quantity: 1,
-    },
-  ],
+  items: [{ productId: "product-id", quantity: 1 }],
   customer: {
     email: "cliente@example.com",
     name: "Cliente Teste",
@@ -273,26 +222,14 @@ const checkout = await ay.checkouts.create({
   },
   externalReference: "guild-832320430277918720-user-123",
   webhookUrl: "https://guildbuilders.example.com/webhooks/orders",
-  redirectUrls: {
-    successUrl: "https://guildbuilders.example.com/payments/success",
-    pendingUrl: "https://guildbuilders.example.com/payments/pending",
-    failureUrl: "https://guildbuilders.example.com/payments/failure",
-    cancelUrl: "https://guildbuilders.example.com/payments/cancel",
-  },
   metadata: {
     guildId: "832320430277918720",
     discordUserId: "123456789",
   },
 });
-
-console.log(checkout.order.id);
-console.log(checkout.payment?.qrCode);
-console.log(checkout.checkout?.url);
 ```
 
-### Criar checkout avulso
-
-Para itens sem produto cadastrado, informe `projectId` e `accountId`. Todos os itens do mesmo checkout devem resolver para o mesmo projeto e a mesma conta conectada.
+Custom checkout without a registered product:
 
 ```ts
 const checkout = await ay.checkouts.create({
@@ -304,108 +241,30 @@ const checkout = await ay.checkouts.create({
       name: "Cargo VIP",
       amount: 19.9,
       quantity: 1,
-      description: "Acesso VIP no Discord",
     },
   ],
   customer: {
     email: "cliente@example.com",
     name: "Cliente Teste",
   },
-  externalReference: "guild-832320430277918720-custom-001",
-});
-```
-
-## Orders
-
-Listar orders:
-
-```ts
-const { orders } = await ay.orders.list({ page: 1, limit: 100 });
-```
-
-Buscar por metadata:
-
-```ts
-const result = await ay.orders.query({
-  metadata: {
-    guildId: "832320430277918720",
-  },
 });
 ```
 
-Listar por projeto:
+## Typed imports
 
-```ts
-const result = await ay.orders.listByProject("832320430277918720");
-```
-
-## Customers
-
-A API atual usa `/clients`, mas a SDK expõe `customers` e o alias `clients`.
+Everything is also available from `types`:
 
 ```ts
-const { client } = await ay.customers.create({
-  email: "cliente@example.com",
-  password: "123456",
-  fullName: "Cliente Teste",
-  document: "00000000000",
-});
-
-const { clients } = await ay.customers.list();
+import type {
+  AyPaymentsCreateProjectPayload,
+  AyPaymentsCreateCheckoutResponse,
+  ErrorResponse,
+} from "@undernouzen/ay-payments-sdk/types";
 ```
 
-## Merchants, Admins, API Keys
-
-Essas rotas dependem do escopo da sessão/API key.
+Module-specific imports are supported:
 
 ```ts
-await ay.merchants.create({
-  email: "merchant@example.com",
-  password: "123456",
-  name: "Minha Loja",
-  fullName: "Responsavel",
-});
-
-const key = await ay.apiKeys.create({
-  name: "Guild Builders",
-  permissions: {
-    projects: { list: true, create: true, edit: true, delete: false },
-    products: { list: true, create: true, edit: true, delete: true },
-    orders: { list: true, create: true },
-  },
-});
-```
-
-Revogar, habilitar/desabilitar ou deletar:
-
-```ts
-await ay.apiKeys.revoke("api-key-id");
-await ay.apiKeys.setStatus("api-key-id", "active");
-await ay.apiKeys.delete("api-key-id");
-```
-
-## Tratamento de erro
-
-Métodos da SDK retornam `data` em caso de sucesso e lançam `AyPaymentsApiError` em caso de erro.
-
-```ts
-import { AyPaymentsApiError } from "@ay-payments/sdk";
-
-try {
-  await ay.projects.list();
-} catch (error) {
-  if (error instanceof AyPaymentsApiError) {
-    console.log(error.status);
-    console.log(error.payload.error);
-  }
-}
+import type { AyPaymentsCheckoutPayload } from "@undernouzen/ay-payments-sdk/modules/checkouts.types";
+import { isApiError } from "@undernouzen/ay-payments-sdk/errors";
 ```
-
-## Notas de contrato
-
-- Produto usa `value`.
-- Produto não calcula comissão.
-- Comissão é calculada em `POST /checkouts/calculate` e `POST /checkouts`.
-- `projectIdOrExternalId` aceita o `id` interno do AY Payments ou o `externalId` do projeto.
-- `connectedAccountId` é o id da conta conectada no provedor, como `acct_...` na Stripe ou o user id do Mercado Pago.
-- `connectionId` é o id interno da conexão dentro do projeto.