@boelabs/billete-sdk 0.3.2 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +214 -35
- package/dist/client.d.ts +3 -3
- package/dist/client.js +1 -1
- package/dist/{errors-oT7VMFhd.d.ts → errors-gwEcSkzi.d.ts} +14 -11
- package/dist/{events-BJuSt_4W.d.ts → events-oZ08-Zz2.d.ts} +7 -7
- package/dist/{http-kkjWt1D4.js → http-B5DzcQK9.js} +1 -1
- package/dist/index.d.ts +3 -3
- package/dist/index.js +1 -1
- package/dist/webhooks.d.ts +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,28 +1,130 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
# Billete SDK
|
|
4
|
+
|
|
5
|
+
**SDK oficial de TypeScript para la API de [Billete](https://billete.run).**
|
|
6
|
+
|
|
7
|
+
Cobros con Pago Móvil, precios en bolívares o en divisas a tasa BCV y suscripciones, desde tu
|
|
8
|
+
servidor y tu frontend.
|
|
9
|
+
|
|
10
|
+
[](https://www.npmjs.com/package/@boelabs/billete-sdk)
|
|
11
|
+
[](./LICENSE)
|
|
12
|
+

|
|
13
|
+

|
|
14
|
+
|
|
15
|
+
</div>
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
- **Tipado de punta a punta:** cada recurso, entrada y evento tiene su tipo.
|
|
20
|
+
- **Sin dependencias:** solo `fetch` y Web Crypto; funciona en Node.js 20+, Bun, Deno y
|
|
21
|
+
runtimes edge (Cloudflare Workers, Vercel).
|
|
22
|
+
- **Seguro ante reintentos:** cada mutación lleva una clave de idempotencia, así un reintento
|
|
23
|
+
nunca cobra dos veces.
|
|
24
|
+
|
|
25
|
+
## Contenido
|
|
26
|
+
|
|
27
|
+
- [Instalación](#instalación)
|
|
28
|
+
- [Inicio rápido](#inicio-rápido)
|
|
29
|
+
- [Configuración](#configuración)
|
|
30
|
+
- [Recursos](#recursos)
|
|
31
|
+
- [Montos](#montos)
|
|
32
|
+
- [Paginación](#paginación)
|
|
33
|
+
- [Errores](#errores)
|
|
34
|
+
- [Idempotencia y reintentos](#idempotencia-y-reintentos)
|
|
35
|
+
- [Navegador](#navegador)
|
|
36
|
+
- [Webhooks](#webhooks)
|
|
37
|
+
- [Licencia](#licencia)
|
|
38
|
+
|
|
39
|
+
## Instalación
|
|
6
40
|
|
|
7
41
|
```bash
|
|
8
42
|
npm install @boelabs/billete-sdk
|
|
9
43
|
```
|
|
10
44
|
|
|
11
|
-
|
|
45
|
+
El paquete tiene tres puntos de entrada:
|
|
46
|
+
|
|
47
|
+
| Import | Dónde se usa | Para qué |
|
|
48
|
+
| --- | --- | --- |
|
|
49
|
+
| `@boelabs/billete-sdk` | Servidor | Toda la API, con tu clave secreta |
|
|
50
|
+
| `@boelabs/billete-sdk/client` | Navegador | Checkout y estado de un cliente, sin clave secreta |
|
|
51
|
+
| `@boelabs/billete-sdk/webhooks` | Servidor | Verificar la firma de los webhooks |
|
|
52
|
+
|
|
53
|
+
## Inicio rápido
|
|
54
|
+
|
|
55
|
+
Crea una clave secreta en el dashboard (**Desarrolladores → Claves API**) y guárdala en
|
|
56
|
+
`BILLETE_API_KEY`.
|
|
12
57
|
|
|
13
58
|
```ts
|
|
14
59
|
import { createBillete } from "@boelabs/billete-sdk";
|
|
15
60
|
|
|
61
|
+
const billete = createBillete({ environment: "test" });
|
|
62
|
+
|
|
63
|
+
const checkout = await billete.checkouts.create({
|
|
64
|
+
plan: "plan_…",
|
|
65
|
+
months: 1,
|
|
66
|
+
customer: { email: "ana@example.com", externalId: "user_123" },
|
|
67
|
+
});
|
|
68
|
+
|
|
69
|
+
// Redirige a tu cliente a checkout.url para que pague.
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Cuando el pago se confirma, Billete te avisa con el webhook `checkout.completed` (ver
|
|
73
|
+
[Webhooks](#webhooks)).
|
|
74
|
+
|
|
75
|
+
## Configuración
|
|
76
|
+
|
|
77
|
+
```ts
|
|
16
78
|
const billete = createBillete({
|
|
17
|
-
environment: "
|
|
18
|
-
|
|
19
|
-
|
|
79
|
+
environment: "production",
|
|
80
|
+
apiKey: process.env.BILLETE_API_KEY,
|
|
81
|
+
timeoutMs: 30_000,
|
|
82
|
+
maxRetries: 2,
|
|
20
83
|
});
|
|
21
84
|
```
|
|
22
85
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
86
|
+
| Opción | Por defecto | Descripción |
|
|
87
|
+
| --- | --- | --- |
|
|
88
|
+
| `environment` | — (obligatoria) | `"test"` o `"production"`. Debe coincidir con la clave. |
|
|
89
|
+
| `apiKey` | `BILLETE_API_KEY` | Clave secreta: `sk_test_…` o `sk_prod_…`. |
|
|
90
|
+
| `baseUrl` | `BILLETE_BASE_URL`, o `https://api.billete.run` | URL de la API. |
|
|
91
|
+
| `timeoutMs` | `30000` | Tiempo máximo por intento. |
|
|
92
|
+
| `maxRetries` | `2` | Reintentos ante errores de red, `429` y `5xx`. |
|
|
93
|
+
| `fetch` | `globalThis.fetch` | Implementación de `fetch` propia (proxies, tests). |
|
|
94
|
+
|
|
95
|
+
Si `environment` no coincide con el prefijo de la clave, `createBillete` lanza un error: una
|
|
96
|
+
clave de prueba nunca opera en producción ni al revés. Por la misma razón, el cliente de servidor
|
|
97
|
+
se niega a crearse en un navegador.
|
|
98
|
+
|
|
99
|
+
> [!WARNING]
|
|
100
|
+
> La clave secreta da acceso completo a tu negocio. Úsala solo en el servidor y nunca la
|
|
101
|
+
> incluyas en código que llegue al navegador.
|
|
102
|
+
|
|
103
|
+
## Recursos
|
|
104
|
+
|
|
105
|
+
Todos los métodos devuelven promesas con el recurso tipado. Los recursos con listado tienen
|
|
106
|
+
`create`, `retrieve`, `update`, `list` e `iterate`, además de sus acciones propias:
|
|
107
|
+
|
|
108
|
+
| Recurso | Acciones propias |
|
|
109
|
+
| --- | --- |
|
|
110
|
+
| `customers` | — |
|
|
111
|
+
| `customerSessions` | `create` |
|
|
112
|
+
| `products` | `retire`, `retireVariant` |
|
|
113
|
+
| `plans` | — |
|
|
114
|
+
| `features` | `check`, `isEnabled`, `listForCustomer`, `consume`, `release`, `set` |
|
|
115
|
+
| `coupons` | — |
|
|
116
|
+
| `checkouts` | `expire` |
|
|
117
|
+
| `paymentLinks` | `retire` |
|
|
118
|
+
| `subscriptions` | `cancel`, `resume` |
|
|
119
|
+
| `payments` | `refund`, `listRefunds` |
|
|
120
|
+
| `payouts` | — |
|
|
121
|
+
| `balance` | `retrieve` |
|
|
122
|
+
| `webhookEndpoints` | `delete` |
|
|
123
|
+
| `events` | `retrieve`, `list`, `iterate` |
|
|
124
|
+
| `exchangeRates` | `list` |
|
|
125
|
+
| `currencies` | `list` |
|
|
126
|
+
|
|
127
|
+
### Ejemplo: plan con cuotas
|
|
26
128
|
|
|
27
129
|
```ts
|
|
28
130
|
await billete.features.create({
|
|
@@ -43,48 +145,125 @@ const plan = await billete.plans.create({
|
|
|
43
145
|
features: { tokens: 100_000 },
|
|
44
146
|
});
|
|
45
147
|
|
|
46
|
-
|
|
47
|
-
plan: plan.id,
|
|
48
|
-
months: 1,
|
|
49
|
-
customer: { email: "ana@example.com", externalId: "user_123" },
|
|
50
|
-
});
|
|
51
|
-
// Redirige al cliente a checkout.url
|
|
52
|
-
|
|
148
|
+
// `customer` acepta el ID de Billete (cus_…) o tu propio externalId.
|
|
53
149
|
const { allowed } = await billete.features.consume("user_123", "tokens", 850);
|
|
54
150
|
```
|
|
55
151
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
152
|
+
`consume` es atómico: si el consumo supera el límite, no se descuenta nada y `allowed` es
|
|
153
|
+
`false`.
|
|
154
|
+
|
|
155
|
+
## Montos
|
|
156
|
+
|
|
157
|
+
Los montos son siempre **enteros en unidad menor** (céntimos), nunca decimales: `1_000` en `USD`
|
|
158
|
+
son 10,00 USD y `1_000` en `VES` son 10,00 Bs. Las tasas de cambio llegan como texto decimal para
|
|
159
|
+
no perder precisión.
|
|
160
|
+
|
|
161
|
+
## Paginación
|
|
162
|
+
|
|
163
|
+
`list` devuelve una página (`{ data, nextCursor }`); `iterate` recorre todas por ti:
|
|
164
|
+
|
|
165
|
+
```ts
|
|
166
|
+
const page = await billete.payments.list({ limit: 50 });
|
|
167
|
+
const next = await billete.payments.list({ limit: 50, cursor: page.nextCursor ?? undefined });
|
|
168
|
+
|
|
169
|
+
for await (const payment of billete.payments.iterate()) {
|
|
170
|
+
console.log(payment.id, payment.amount);
|
|
171
|
+
}
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
## Errores
|
|
175
|
+
|
|
176
|
+
Toda respuesta fallida lanza un `BilleteError`:
|
|
177
|
+
|
|
178
|
+
```ts
|
|
179
|
+
import { BilleteError } from "@boelabs/billete-sdk";
|
|
180
|
+
|
|
181
|
+
try {
|
|
182
|
+
await billete.payments.refund("pay_…");
|
|
183
|
+
} catch (error) {
|
|
184
|
+
if (error instanceof BilleteError && error.code === "payment_not_refundable") {
|
|
185
|
+
// …
|
|
186
|
+
}
|
|
187
|
+
throw error;
|
|
188
|
+
}
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
| Propiedad | Descripción |
|
|
192
|
+
| --- | --- |
|
|
193
|
+
| `type` | Categoría: `invalid_request`, `authentication`, `permission`, `not_found`, `conflict`, `validation`, `rate_limit`, `provider`, `internal` o `network`. |
|
|
194
|
+
| `code` | Código estable, apto para decidir en tu código. |
|
|
195
|
+
| `message` | Descripción legible del error. |
|
|
196
|
+
| `status` | Código HTTP (`0` si no hubo respuesta). |
|
|
197
|
+
| `param` | Campo que causó el error, cuando aplica. |
|
|
198
|
+
| `requestId` | Identificador de la petición; inclúyelo al pedir soporte. |
|
|
199
|
+
|
|
200
|
+
## Idempotencia y reintentos
|
|
201
|
+
|
|
202
|
+
Cada mutación envía una `Idempotency-Key` generada automáticamente, que se mantiene entre
|
|
203
|
+
reintentos. Si quieres que un reintento tuyo (por ejemplo, de un job) también sea seguro, pasa
|
|
204
|
+
una clave estable:
|
|
205
|
+
|
|
206
|
+
```ts
|
|
207
|
+
await billete.payments.refund("pay_…", {}, { idempotencyKey: `refund-${orderId}` });
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
Todos los métodos aceptan como último argumento `{ idempotencyKey?, signal? }`; `signal` permite
|
|
211
|
+
cancelar la petición con un `AbortController`.
|
|
59
212
|
|
|
60
213
|
## Navegador
|
|
61
214
|
|
|
62
|
-
|
|
63
|
-
|
|
215
|
+
El cliente de navegador nunca usa tu clave secreta. Tu servidor crea una **sesión de cliente**
|
|
216
|
+
de corta duración y se la entrega al frontend:
|
|
64
217
|
|
|
65
218
|
```ts
|
|
219
|
+
// Servidor
|
|
220
|
+
const session = await billete.customerSessions.create({ customer: "user_123" });
|
|
221
|
+
return { token: session.token };
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
```ts
|
|
225
|
+
// Navegador
|
|
66
226
|
import { createClient } from "@boelabs/billete-sdk/client";
|
|
67
227
|
|
|
68
|
-
const billete = createClient({ customerSession:
|
|
69
|
-
|
|
70
|
-
|
|
228
|
+
const billete = createClient({ customerSession: token });
|
|
229
|
+
|
|
230
|
+
const { data: subscriptions } = await billete.customer.subscriptions();
|
|
231
|
+
const tokens = await billete.customer.feature("tokens");
|
|
71
232
|
```
|
|
72
233
|
|
|
234
|
+
`customerSession` también acepta una función, útil cuando el token se renueva. Sin sesión, el
|
|
235
|
+
cliente puede leer y pagar checkouts y links de pago, y consultar tasas y monedas.
|
|
236
|
+
|
|
73
237
|
## Webhooks
|
|
74
238
|
|
|
75
|
-
|
|
239
|
+
Billete firma los webhooks con [Standard Webhooks](https://www.standardwebhooks.com). Verifica la
|
|
240
|
+
firma con el cuerpo **exactamente como llegó**, antes de parsearlo:
|
|
76
241
|
|
|
77
242
|
```ts
|
|
78
|
-
import { verifyWebhook } from "@boelabs/billete-sdk/webhooks";
|
|
243
|
+
import { verifyWebhook, WebhookVerificationError } from "@boelabs/billete-sdk/webhooks";
|
|
79
244
|
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
245
|
+
export async function POST(request: Request) {
|
|
246
|
+
try {
|
|
247
|
+
const event = await verifyWebhook({
|
|
248
|
+
payload: await request.text(),
|
|
249
|
+
headers: request.headers,
|
|
250
|
+
secret: process.env.BILLETE_WEBHOOK_SECRET!,
|
|
251
|
+
});
|
|
252
|
+
|
|
253
|
+
if (event.type === "checkout.completed") {
|
|
254
|
+
// event.data es un Checkout
|
|
255
|
+
}
|
|
256
|
+
return new Response(null, { status: 204 });
|
|
257
|
+
} catch (error) {
|
|
258
|
+
if (error instanceof WebhookVerificationError) return new Response(null, { status: 400 });
|
|
259
|
+
throw error;
|
|
260
|
+
}
|
|
261
|
+
}
|
|
86
262
|
```
|
|
87
263
|
|
|
264
|
+
`event` es una unión discriminada por `type`, así que `event.data` tiene el tipo correcto en cada
|
|
265
|
+
rama. Se rechazan las firmas con más de 5 minutos (`toleranceSeconds`).
|
|
266
|
+
|
|
88
267
|
## Licencia
|
|
89
268
|
|
|
90
|
-
MIT
|
|
269
|
+
[MIT](./LICENSE)
|
package/dist/client.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { $ as
|
|
2
|
-
import { A as ProductCheckoutCreate, B as
|
|
1
|
+
import { $ as SubscriptionRenewal, A as Payment, At as ENVIRONMENTS, B as Product, C as FEATURE_TYPES, Ct as MobilePrefix, D as FeatureUsageResult, Dt as isLandlinePhone, E as FeatureType, Et as Timestamp, F as PaymentStatus, G as Refund, H as ProductVariant, I as Payout, J as RiskLevel, K as ResetFrequency, L as Plan, M as PaymentFailure, Mt as TokenKind, N as PaymentLink, Nt as tokenEnvironment, O as PAYMENT_STATUSES, Ot as isMobilePhone, P as PaymentSettlement, Pt as tokenPrefix, Q as Subscription, R as PlanFeatureValues, S as ExchangeRate, St as Metadata, T as FeatureReset, Tt as TaxBehavior, U as RESET_FREQUENCIES, V as ProductCategory, W as RISK_LEVELS, X as SUBSCRIPTION_STATUSES, Y as SUBMIT_LABELS, Z as SubmitLabel, _ as Customer, _t as GracePeriodDays, a as Actor, at as ApiErrorBody, b as CustomerSession, bt as MAX_QUANTITY, c as BalanceAmount, ct as PAYMENT_FAILURE_CODES, d as CheckoutItem, dt as AddressInput, et as SubscriptionStatus, f as CheckoutPurpose, ft as BILLING_MONTHS, g as CustomField, gt as GRACE_PERIOD_DAYS, h as CurrencyAvailability, ht as Currency, i as WebhookEvent, it as API_ERROR_TYPES, j as PaymentAttempt, jt as Environment, k as PRODUCT_CATEGORIES, kt as nationalPhone, l as CHECKOUT_PURPOSES, lt as PaymentFailureCode, m as Coupon, mt as CURRENCIES, n as EventDataMap, nt as WebhookEndpoint, o as AfterCompletion, ot as ApiErrorEnvelope, p as CollectSettings, pt as BillingMonths, q as Retirement, r as EventType, rt as Weekday, s as Balance, st as ApiErrorType, t as EVENT_TYPES, tt as USAGE_FEATURE_TYPES, u as Checkout, ut as Address, v as CustomerDetails, vt as List, w as Feature, wt as TAX_BEHAVIORS, x as Event, xt as MOBILE_PREFIXES, y as CustomerFeature, yt as ListQuery, z as PlanPrice } from "./events-oZ08-Zz2.js";
|
|
2
|
+
import { A as ProductCheckoutCreate, B as WebhookEndpointCreate, C as PaymentLinkUpdate, D as PlanLinkCreate, E as PlanFeaturesInput, F as RetireInput, G as PaymentTestScenario, H as CheckoutPaymentMethod, I as SubscriptionCancel, K as PublicCheckout, L as SubscriptionCreate, M as ProductLinkCreate, N as ProductUpdate, O as PlanPriceInput, P as RefundCreate, R as SubscriptionUpdate, S as PaymentLinkCreate, T as PlanCreate, U as PaymentInstructions, V as WebhookEndpointUpdate, W as PaymentMethodField, _ as CustomerUpdate, a as CheckoutCreate, b as FeatureUpdate, c as ClientCheckoutUpdate, d as CouponCreate, f as CouponUpdate, g as CustomerSessionCreate, h as CustomerInput, i as AfterCompletionInput, j as ProductCreate, k as PlanUpdate, l as ClientLinkCheckout, m as CustomerCreate, n as RequestOptions, o as CheckoutItemInput, p as CustomFieldInput, q as PublicPaymentLink, r as TransportOptions, s as ClientCheckoutPay, t as BilleteError, u as CollectInput, v as EventSelector, w as PlanCheckoutCreate, x as KEY_PATTERN, y as FeatureCreate, z as VariantInput } from "./errors-gwEcSkzi.js";
|
|
3
3
|
//#region src/create-client.d.ts
|
|
4
4
|
interface ClientOptions extends TransportOptions {
|
|
5
5
|
/**
|
|
@@ -50,4 +50,4 @@ export declare function createClient(options?: ClientOptions): {
|
|
|
50
50
|
};
|
|
51
51
|
type BilleteClient = ReturnType<typeof createClient>;
|
|
52
52
|
//#endregion
|
|
53
|
-
export { type API_ERROR_TYPES, type Actor, type Address, type AddressInput, type AfterCompletion, type AfterCompletionInput, type ApiErrorBody, type ApiErrorEnvelope, type ApiErrorType, type BILLING_MONTHS, type Balance, type BalanceAmount, type BilleteClient, BilleteError, type BillingMonths, type CHECKOUT_PURPOSES, type CURRENCIES, type Checkout, type CheckoutCreate, type CheckoutItem, type CheckoutItemInput, type CheckoutPaymentMethod, type CheckoutPurpose, type ClientCheckoutPay, type ClientCheckoutUpdate, type ClientLinkCheckout, type ClientOptions, type CollectInput, type CollectSettings, type Coupon, type CouponCreate, type CouponUpdate, type Currency, type CurrencyAvailability, type CustomField, type CustomFieldInput, type Customer, type CustomerCreate, type CustomerDetails, type CustomerFeature, type CustomerInput, type CustomerSession, type CustomerSessionCreate, type CustomerUpdate, type ENVIRONMENTS, type EVENT_TYPES, type Environment, type Event, type EventDataMap, type EventSelector, type EventType, type ExchangeRate, type FEATURE_TYPES, type Feature, type FeatureCreate, type FeatureReset, type FeatureType, type FeatureUpdate, type FeatureUsageResult, type GRACE_PERIOD_DAYS, type GracePeriodDays, type KEY_PATTERN, type List, type ListQuery, type MOBILE_PREFIXES, type Metadata, type MobilePrefix, type PAYMENT_FAILURE_CODES, type PAYMENT_STATUSES, type PRODUCT_CATEGORIES, type Payment, type PaymentAttempt, type PaymentFailure, type PaymentFailureCode, type PaymentInstructions, type PaymentLink, type PaymentLinkCreate, type PaymentLinkUpdate, type PaymentMethodField, type PaymentSettlement, type PaymentStatus, type PaymentTestScenario, type Payout, type Plan, type PlanCheckoutCreate, type PlanCreate, type PlanFeatureValues, type PlanFeaturesInput, type PlanLinkCreate, type PlanPrice, type PlanPriceInput, type PlanUpdate, type Product, type ProductCategory, type ProductCheckoutCreate, type ProductCreate, type ProductLinkCreate, type ProductUpdate, type ProductVariant, type PublicCheckout, type PublicPaymentLink, type
|
|
53
|
+
export { type API_ERROR_TYPES, type Actor, type Address, type AddressInput, type AfterCompletion, type AfterCompletionInput, type ApiErrorBody, type ApiErrorEnvelope, type ApiErrorType, type BILLING_MONTHS, type Balance, type BalanceAmount, type BilleteClient, BilleteError, type BillingMonths, type CHECKOUT_PURPOSES, type CURRENCIES, type Checkout, type CheckoutCreate, type CheckoutItem, type CheckoutItemInput, type CheckoutPaymentMethod, type CheckoutPurpose, type ClientCheckoutPay, type ClientCheckoutUpdate, type ClientLinkCheckout, type ClientOptions, type CollectInput, type CollectSettings, type Coupon, type CouponCreate, type CouponUpdate, type Currency, type CurrencyAvailability, type CustomField, type CustomFieldInput, type Customer, type CustomerCreate, type CustomerDetails, type CustomerFeature, type CustomerInput, type CustomerSession, type CustomerSessionCreate, type CustomerUpdate, type ENVIRONMENTS, type EVENT_TYPES, type Environment, type Event, type EventDataMap, type EventSelector, type EventType, type ExchangeRate, type FEATURE_TYPES, type Feature, type FeatureCreate, type FeatureReset, type FeatureType, type FeatureUpdate, type FeatureUsageResult, type GRACE_PERIOD_DAYS, type GracePeriodDays, type KEY_PATTERN, type List, type ListQuery, type MAX_QUANTITY, type MOBILE_PREFIXES, type Metadata, type MobilePrefix, type PAYMENT_FAILURE_CODES, type PAYMENT_STATUSES, type PRODUCT_CATEGORIES, type Payment, type PaymentAttempt, type PaymentFailure, type PaymentFailureCode, type PaymentInstructions, type PaymentLink, type PaymentLinkCreate, type PaymentLinkUpdate, type PaymentMethodField, type PaymentSettlement, type PaymentStatus, type PaymentTestScenario, type Payout, type Plan, type PlanCheckoutCreate, type PlanCreate, type PlanFeatureValues, type PlanFeaturesInput, type PlanLinkCreate, type PlanPrice, type PlanPriceInput, type PlanUpdate, type Product, type ProductCategory, type ProductCheckoutCreate, type ProductCreate, type ProductLinkCreate, type ProductUpdate, type ProductVariant, type PublicCheckout, type PublicPaymentLink, type RESET_FREQUENCIES, type RISK_LEVELS, type Refund, type RefundCreate, type RequestOptions, type ResetFrequency, type RetireInput, type Retirement, type RiskLevel, type SUBMIT_LABELS, type SUBSCRIPTION_STATUSES, type SubmitLabel, type Subscription, type SubscriptionCancel, type SubscriptionCreate, type SubscriptionRenewal, type SubscriptionStatus, type SubscriptionUpdate, type TAX_BEHAVIORS, type TaxBehavior, type Timestamp, type TokenKind, type USAGE_FEATURE_TYPES, type VariantInput, type WebhookEndpoint, type WebhookEndpointCreate, type WebhookEndpointUpdate, type WebhookEvent, type Weekday, type isLandlinePhone, type isMobilePhone, type nationalPhone, type tokenEnvironment, type tokenPrefix };
|
package/dist/client.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { n as segment, r as BilleteError, t as createTransport } from "./http-
|
|
1
|
+
import { n as segment, r as BilleteError, t as createTransport } from "./http-B5DzcQK9.js";
|
|
2
2
|
//#region src/create-client.ts
|
|
3
3
|
/**
|
|
4
4
|
* Browser client. It never holds a secret key: checkouts are addressed by their unguessable ID
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { Et as Timestamp, F as PaymentStatus, M as PaymentFailure,
|
|
1
|
+
import { Et as Timestamp, F as PaymentStatus, M as PaymentFailure, St as Metadata, T as FeatureReset, Tt as TaxBehavior, V as ProductCategory, Z as SubmitLabel, _t as GracePeriodDays, at as ApiErrorBody, d as CheckoutItem, dt as AddressInput, f as CheckoutPurpose, g as CustomField, ht as Currency, jt as Environment, o as AfterCompletion, p as CollectSettings, pt as BillingMonths, r as EventType, st as ApiErrorType, v as CustomerDetails, z as PlanPrice } from "./events-oZ08-Zz2.js";
|
|
2
2
|
//#region ../contracts/src/client.d.ts
|
|
3
3
|
/** Browser-safe view of a checkout: everything needed to render and pay it, nothing internal. */
|
|
4
4
|
interface PublicCheckout {
|
|
@@ -23,8 +23,10 @@ interface PublicCheckout {
|
|
|
23
23
|
trialDays: number | null;
|
|
24
24
|
couponCode: string | null;
|
|
25
25
|
allowCoupons: boolean;
|
|
26
|
-
/**
|
|
27
|
-
|
|
26
|
+
/** The customer may change the quantity of the single item. */
|
|
27
|
+
adjustableQuantity: boolean;
|
|
28
|
+
/** Most units the customer can choose right now: the link's limit, capped by stock. */
|
|
29
|
+
maxQuantity: number;
|
|
28
30
|
/** Billing cycles the customer may switch between for a plan checkout. */
|
|
29
31
|
cycles: Array<{
|
|
30
32
|
months: BillingMonths;
|
|
@@ -125,7 +127,10 @@ interface PublicPaymentLink {
|
|
|
125
127
|
trialDays: number;
|
|
126
128
|
cycles: PlanPrice[];
|
|
127
129
|
} | null;
|
|
128
|
-
|
|
130
|
+
/** The customer chooses how many units to buy; otherwise every purchase is one unit. */
|
|
131
|
+
adjustableQuantity: boolean;
|
|
132
|
+
/** Most units per purchase when `adjustableQuantity`; `null` leaves stock as the only limit. */
|
|
133
|
+
maxQuantity: number | null;
|
|
129
134
|
collect: CollectSettings;
|
|
130
135
|
customFields: CustomField[];
|
|
131
136
|
allowCoupons: boolean;
|
|
@@ -315,11 +320,6 @@ type AfterCompletionInput = {
|
|
|
315
320
|
type: "redirect";
|
|
316
321
|
url: string;
|
|
317
322
|
};
|
|
318
|
-
interface QuantityInput {
|
|
319
|
-
adjustable?: boolean;
|
|
320
|
-
min?: number;
|
|
321
|
-
max?: number;
|
|
322
|
-
}
|
|
323
323
|
interface PaymentLinkFields {
|
|
324
324
|
collect?: CollectInput;
|
|
325
325
|
customFields?: CustomFieldInput[];
|
|
@@ -333,7 +333,10 @@ interface ProductLinkCreate extends PaymentLinkFields {
|
|
|
333
333
|
type: "product";
|
|
334
334
|
product: string;
|
|
335
335
|
variants?: string[];
|
|
336
|
-
|
|
336
|
+
/** Lets the customer choose how many units to buy. Defaults to one unit per purchase. */
|
|
337
|
+
adjustableQuantity?: boolean;
|
|
338
|
+
/** Most units per purchase; only with `adjustableQuantity`. Omit to limit by stock only. */
|
|
339
|
+
maxQuantity?: number;
|
|
337
340
|
}
|
|
338
341
|
interface PlanLinkCreate extends PaymentLinkFields {
|
|
339
342
|
type: "plan";
|
|
@@ -446,4 +449,4 @@ declare class BilleteError extends Error {
|
|
|
446
449
|
}, status: number);
|
|
447
450
|
}
|
|
448
451
|
//#endregion
|
|
449
|
-
export { ProductCheckoutCreate as A,
|
|
452
|
+
export { ProductCheckoutCreate as A, WebhookEndpointCreate as B, PaymentLinkUpdate as C, PlanLinkCreate as D, PlanFeaturesInput as E, RetireInput as F, PaymentTestScenario as G, CheckoutPaymentMethod as H, SubscriptionCancel as I, PublicCheckout as K, SubscriptionCreate as L, ProductLinkCreate as M, ProductUpdate as N, PlanPriceInput as O, RefundCreate as P, SubscriptionUpdate as R, PaymentLinkCreate as S, PlanCreate as T, PaymentInstructions as U, WebhookEndpointUpdate as V, PaymentMethodField as W, CustomerUpdate as _, CheckoutCreate as a, FeatureUpdate as b, ClientCheckoutUpdate as c, CouponCreate as d, CouponUpdate as f, CustomerSessionCreate as g, CustomerInput as h, AfterCompletionInput as i, ProductCreate as j, PlanUpdate as k, ClientLinkCheckout as l, CustomerCreate as m, RequestOptions as n, CheckoutItemInput as o, CustomFieldInput as p, PublicPaymentLink as q, TransportOptions as r, ClientCheckoutPay as s, BilleteError as t, CollectInput as u, EventSelector as v, PlanCheckoutCreate as w, KEY_PATTERN as x, FeatureCreate as y, VariantInput as z };
|
|
@@ -25,6 +25,8 @@ type Currency = (typeof CURRENCIES)[number];
|
|
|
25
25
|
/** Billing cycles, expressed in months, that a plan can offer. */
|
|
26
26
|
declare const BILLING_MONTHS: readonly [1, 3, 6, 9, 12];
|
|
27
27
|
type BillingMonths = (typeof BILLING_MONTHS)[number];
|
|
28
|
+
/** Most units of one product a single purchase can take. */
|
|
29
|
+
declare const MAX_QUANTITY = 999;
|
|
28
30
|
/** Grace periods, in days, a merchant can grant after a renewal is missed. */
|
|
29
31
|
declare const GRACE_PERIOD_DAYS: readonly [1, 3, 7];
|
|
30
32
|
type GracePeriodDays = (typeof GRACE_PERIOD_DAYS)[number];
|
|
@@ -335,18 +337,16 @@ type AfterCompletion = {
|
|
|
335
337
|
};
|
|
336
338
|
declare const SUBMIT_LABELS: readonly ["pay", "subscribe", "book", "donate"];
|
|
337
339
|
type SubmitLabel = (typeof SUBMIT_LABELS)[number];
|
|
338
|
-
interface QuantitySettings {
|
|
339
|
-
adjustable: boolean;
|
|
340
|
-
min: number;
|
|
341
|
-
max: number;
|
|
342
|
-
}
|
|
343
340
|
interface PaymentLink extends Resource<"payment_link">, Retirement {
|
|
344
341
|
url: string;
|
|
345
342
|
type: "product" | "plan";
|
|
346
343
|
productId: string | null;
|
|
347
344
|
/** Variants offered for a product link; `null` offers every active variant. */
|
|
348
345
|
variantIds: string[] | null;
|
|
349
|
-
|
|
346
|
+
/** The customer chooses how many units to buy; otherwise every purchase is one unit. */
|
|
347
|
+
adjustableQuantity: boolean;
|
|
348
|
+
/** Most units per purchase when `adjustableQuantity`; `null` leaves stock as the only limit. */
|
|
349
|
+
maxQuantity: number | null;
|
|
350
350
|
planId: string | null;
|
|
351
351
|
/** Billing cycles offered for a plan link; `null` offers every plan price. */
|
|
352
352
|
months: BillingMonths[] | null;
|
|
@@ -564,4 +564,4 @@ type WebhookEvent = { [TType in EventType]: {
|
|
|
564
564
|
data: EventDataMap[TType];
|
|
565
565
|
}; }[EventType];
|
|
566
566
|
//#endregion
|
|
567
|
-
export {
|
|
567
|
+
export { SubscriptionRenewal as $, Payment as A, ENVIRONMENTS as At, Product as B, FEATURE_TYPES as C, MobilePrefix as Ct, FeatureUsageResult as D, isLandlinePhone as Dt, FeatureType as E, Timestamp as Et, PaymentStatus as F, Refund as G, ProductVariant as H, Payout as I, RiskLevel as J, ResetFrequency as K, Plan as L, PaymentFailure as M, TokenKind as Mt, PaymentLink as N, tokenEnvironment as Nt, PAYMENT_STATUSES as O, isMobilePhone as Ot, PaymentSettlement as P, tokenPrefix as Pt, Subscription as Q, PlanFeatureValues as R, ExchangeRate as S, Metadata as St, FeatureReset as T, TaxBehavior as Tt, RESET_FREQUENCIES as U, ProductCategory as V, RISK_LEVELS as W, SUBSCRIPTION_STATUSES as X, SUBMIT_LABELS as Y, SubmitLabel as Z, Customer as _, GracePeriodDays as _t, Actor as a, ApiErrorBody as at, CustomerSession as b, MAX_QUANTITY as bt, BalanceAmount as c, PAYMENT_FAILURE_CODES as ct, CheckoutItem as d, AddressInput as dt, SubscriptionStatus as et, CheckoutPurpose as f, BILLING_MONTHS as ft, CustomField as g, GRACE_PERIOD_DAYS as gt, CurrencyAvailability as h, Currency as ht, WebhookEvent as i, API_ERROR_TYPES as it, PaymentAttempt as j, Environment as jt, PRODUCT_CATEGORIES as k, nationalPhone as kt, CHECKOUT_PURPOSES as l, PaymentFailureCode as lt, Coupon as m, CURRENCIES as mt, EventDataMap as n, WebhookEndpoint as nt, AfterCompletion as o, ApiErrorEnvelope as ot, CollectSettings as p, BillingMonths as pt, Retirement as q, EventType as r, Weekday as rt, Balance as s, ApiErrorType as st, EVENT_TYPES as t, USAGE_FEATURE_TYPES as tt, Checkout as u, Address as ut, CustomerDetails as v, List as vt, Feature as w, TAX_BEHAVIORS as wt, Event as x, MOBILE_PREFIXES as xt, CustomerFeature as y, ListQuery as yt, PlanPrice as z };
|
|
@@ -18,7 +18,7 @@ var BilleteError = class extends Error {
|
|
|
18
18
|
};
|
|
19
19
|
//#endregion
|
|
20
20
|
//#region src/http.ts
|
|
21
|
-
const SDK_VERSION = "0.
|
|
21
|
+
const SDK_VERSION = "0.4.0";
|
|
22
22
|
const DEFAULT_BASE_URL = "https://api.billete.run";
|
|
23
23
|
const RETRYABLE_STATUS = /* @__PURE__ */ new Set([
|
|
24
24
|
429,
|
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { $ as
|
|
2
|
-
import { A as ProductCheckoutCreate, B as
|
|
1
|
+
import { $ as SubscriptionRenewal, A as Payment, At as ENVIRONMENTS, B as Product, C as FEATURE_TYPES, Ct as MobilePrefix, D as FeatureUsageResult, Dt as isLandlinePhone, E as FeatureType, Et as Timestamp, F as PaymentStatus, G as Refund, H as ProductVariant, I as Payout, J as RiskLevel, K as ResetFrequency, L as Plan, M as PaymentFailure, Mt as TokenKind, N as PaymentLink, Nt as tokenEnvironment, O as PAYMENT_STATUSES, Ot as isMobilePhone, P as PaymentSettlement, Pt as tokenPrefix, Q as Subscription, R as PlanFeatureValues, S as ExchangeRate, St as Metadata, T as FeatureReset, Tt as TaxBehavior, U as RESET_FREQUENCIES, V as ProductCategory, W as RISK_LEVELS, X as SUBSCRIPTION_STATUSES, Y as SUBMIT_LABELS, Z as SubmitLabel, _ as Customer, _t as GracePeriodDays, a as Actor, at as ApiErrorBody, b as CustomerSession, bt as MAX_QUANTITY, c as BalanceAmount, ct as PAYMENT_FAILURE_CODES, d as CheckoutItem, dt as AddressInput, et as SubscriptionStatus, f as CheckoutPurpose, ft as BILLING_MONTHS, g as CustomField, gt as GRACE_PERIOD_DAYS, h as CurrencyAvailability, ht as Currency, i as WebhookEvent, it as API_ERROR_TYPES, j as PaymentAttempt, jt as Environment, k as PRODUCT_CATEGORIES, kt as nationalPhone, l as CHECKOUT_PURPOSES, lt as PaymentFailureCode, m as Coupon, mt as CURRENCIES, n as EventDataMap, nt as WebhookEndpoint, o as AfterCompletion, ot as ApiErrorEnvelope, p as CollectSettings, pt as BillingMonths, q as Retirement, r as EventType, rt as Weekday, s as Balance, st as ApiErrorType, t as EVENT_TYPES, tt as USAGE_FEATURE_TYPES, u as Checkout, ut as Address, v as CustomerDetails, vt as List, w as Feature, wt as TAX_BEHAVIORS, x as Event, xt as MOBILE_PREFIXES, y as CustomerFeature, yt as ListQuery, z as PlanPrice } from "./events-oZ08-Zz2.js";
|
|
2
|
+
import { A as ProductCheckoutCreate, B as WebhookEndpointCreate, C as PaymentLinkUpdate, D as PlanLinkCreate, E as PlanFeaturesInput, F as RetireInput, G as PaymentTestScenario, H as CheckoutPaymentMethod, I as SubscriptionCancel, K as PublicCheckout, L as SubscriptionCreate, M as ProductLinkCreate, N as ProductUpdate, O as PlanPriceInput, P as RefundCreate, R as SubscriptionUpdate, S as PaymentLinkCreate, T as PlanCreate, U as PaymentInstructions, V as WebhookEndpointUpdate, W as PaymentMethodField, _ as CustomerUpdate, a as CheckoutCreate, b as FeatureUpdate, c as ClientCheckoutUpdate, d as CouponCreate, f as CouponUpdate, g as CustomerSessionCreate, h as CustomerInput, i as AfterCompletionInput, j as ProductCreate, k as PlanUpdate, l as ClientLinkCheckout, m as CustomerCreate, n as RequestOptions, o as CheckoutItemInput, p as CustomFieldInput, q as PublicPaymentLink, r as TransportOptions, s as ClientCheckoutPay, t as BilleteError, u as CollectInput, v as EventSelector, w as PlanCheckoutCreate, x as KEY_PATTERN, y as FeatureCreate, z as VariantInput } from "./errors-gwEcSkzi.js";
|
|
3
3
|
import { WebhookVerificationError, verifyWebhook } from "./webhooks.js";
|
|
4
4
|
//#region src/server.d.ts
|
|
5
5
|
type Filters<T> = ListQuery & T;
|
|
@@ -194,4 +194,4 @@ export declare function createBillete(options: BilleteOptions): {
|
|
|
194
194
|
/** The server client: what `createBillete` returns. */
|
|
195
195
|
type Billete = ReturnType<typeof createBillete>;
|
|
196
196
|
//#endregion
|
|
197
|
-
export { type API_ERROR_TYPES, type Actor, type Address, type AddressInput, type AfterCompletion, type AfterCompletionInput, type ApiErrorBody, type ApiErrorEnvelope, type ApiErrorType, type BILLING_MONTHS, type Balance, type BalanceAmount, type Billete, BilleteError, type BilleteOptions, type BillingMonths, type CHECKOUT_PURPOSES, type CURRENCIES, type Checkout, type CheckoutCreate, type CheckoutItem, type CheckoutItemInput, type CheckoutPaymentMethod, type CheckoutPurpose, type ClientCheckoutPay, type ClientCheckoutUpdate, type ClientLinkCheckout, type CollectInput, type CollectSettings, type Coupon, type CouponCreate, type CouponUpdate, type Currency, type CurrencyAvailability, type CustomField, type CustomFieldInput, type Customer, type CustomerCreate, type CustomerDetails, type CustomerFeature, type CustomerInput, type CustomerSession, type CustomerSessionCreate, type CustomerUpdate, type ENVIRONMENTS, type EVENT_TYPES, type Environment, type Event, type EventDataMap, type EventSelector, type EventType, type ExchangeRate, type FEATURE_TYPES, type Feature, type FeatureCreate, type FeatureReset, type FeatureType, type FeatureUpdate, type FeatureUsageResult, type GRACE_PERIOD_DAYS, type GracePeriodDays, type KEY_PATTERN, type List, type ListQuery, type MOBILE_PREFIXES, type Metadata, type MobilePrefix, type PAYMENT_FAILURE_CODES, type PAYMENT_STATUSES, type PRODUCT_CATEGORIES, type Payment, type PaymentAttempt, type PaymentFailure, type PaymentFailureCode, type PaymentInstructions, type PaymentLink, type PaymentLinkCreate, type PaymentLinkUpdate, type PaymentMethodField, type PaymentSettlement, type PaymentStatus, type PaymentTestScenario, type Payout, type Plan, type PlanCheckoutCreate, type PlanCreate, type PlanFeatureValues, type PlanFeaturesInput, type PlanLinkCreate, type PlanPrice, type PlanPriceInput, type PlanUpdate, type Product, type ProductCategory, type ProductCheckoutCreate, type ProductCreate, type ProductLinkCreate, type ProductUpdate, type ProductVariant, type PublicCheckout, type PublicPaymentLink, type
|
|
197
|
+
export { type API_ERROR_TYPES, type Actor, type Address, type AddressInput, type AfterCompletion, type AfterCompletionInput, type ApiErrorBody, type ApiErrorEnvelope, type ApiErrorType, type BILLING_MONTHS, type Balance, type BalanceAmount, type Billete, BilleteError, type BilleteOptions, type BillingMonths, type CHECKOUT_PURPOSES, type CURRENCIES, type Checkout, type CheckoutCreate, type CheckoutItem, type CheckoutItemInput, type CheckoutPaymentMethod, type CheckoutPurpose, type ClientCheckoutPay, type ClientCheckoutUpdate, type ClientLinkCheckout, type CollectInput, type CollectSettings, type Coupon, type CouponCreate, type CouponUpdate, type Currency, type CurrencyAvailability, type CustomField, type CustomFieldInput, type Customer, type CustomerCreate, type CustomerDetails, type CustomerFeature, type CustomerInput, type CustomerSession, type CustomerSessionCreate, type CustomerUpdate, type ENVIRONMENTS, type EVENT_TYPES, type Environment, type Event, type EventDataMap, type EventSelector, type EventType, type ExchangeRate, type FEATURE_TYPES, type Feature, type FeatureCreate, type FeatureReset, type FeatureType, type FeatureUpdate, type FeatureUsageResult, type GRACE_PERIOD_DAYS, type GracePeriodDays, type KEY_PATTERN, type List, type ListQuery, type MAX_QUANTITY, type MOBILE_PREFIXES, type Metadata, type MobilePrefix, type PAYMENT_FAILURE_CODES, type PAYMENT_STATUSES, type PRODUCT_CATEGORIES, type Payment, type PaymentAttempt, type PaymentFailure, type PaymentFailureCode, type PaymentInstructions, type PaymentLink, type PaymentLinkCreate, type PaymentLinkUpdate, type PaymentMethodField, type PaymentSettlement, type PaymentStatus, type PaymentTestScenario, type Payout, type Plan, type PlanCheckoutCreate, type PlanCreate, type PlanFeatureValues, type PlanFeaturesInput, type PlanLinkCreate, type PlanPrice, type PlanPriceInput, type PlanUpdate, type Product, type ProductCategory, type ProductCheckoutCreate, type ProductCreate, type ProductLinkCreate, type ProductUpdate, type ProductVariant, type PublicCheckout, type PublicPaymentLink, type RESET_FREQUENCIES, type RISK_LEVELS, type Refund, type RefundCreate, type RequestOptions, type ResetFrequency, type RetireInput, type Retirement, type RiskLevel, type SUBMIT_LABELS, type SUBSCRIPTION_STATUSES, type SubmitLabel, type Subscription, type SubscriptionCancel, type SubscriptionCreate, type SubscriptionRenewal, type SubscriptionStatus, type SubscriptionUpdate, type TAX_BEHAVIORS, type TaxBehavior, type Timestamp, type TokenKind, type TransportOptions, type USAGE_FEATURE_TYPES, type VariantInput, type WebhookEndpoint, type WebhookEndpointCreate, type WebhookEndpointUpdate, type WebhookEvent, WebhookVerificationError, type Weekday, type isLandlinePhone, type isMobilePhone, type nationalPhone, type tokenEnvironment, type tokenPrefix, verifyWebhook };
|
package/dist/index.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { n as segment, r as BilleteError, t as createTransport } from "./http-
|
|
1
|
+
import { n as segment, r as BilleteError, t as createTransport } from "./http-B5DzcQK9.js";
|
|
2
2
|
import { WebhookVerificationError, verifyWebhook } from "./webhooks.js";
|
|
3
3
|
//#region ../contracts/src/environment.ts
|
|
4
4
|
/**
|
package/dist/webhooks.d.ts
CHANGED