Skip to content

Commit bfbea34

Browse files
almeidazsalmeidazs
committed
feat(@abacatepay/zod): add examples in v2 schemas
1 parent 33c1960 commit bfbea34

9 files changed

Lines changed: 276 additions & 70 deletions

File tree

‎packages/zod/src/v2/resources/checkout.ts‎

Lines changed: 47 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ import { StringEnum } from '../../utils';
77
export const PaymentStatus = StringEnum(
88
['PENDING', 'EXPIRED', 'CANCELLED', 'PAID', 'REFUNDED'],
99
'Billing status. Can be `PENDING`, `EXPIRED`, `CANCELLED`, `PAID`, `REFUNDED`.',
10-
);
10+
).meta({ example: 'PENDING' });
1111

1212
/**
1313
* https://docs.abacatepay.com/pages/payment/reference#atributos
@@ -17,7 +17,10 @@ export type PaymentStatus = z.infer<typeof PaymentStatus>;
1717
/**
1818
* https://docs.abacatepay.com/pages/payment/create#body-methods
1919
*/
20-
export const PaymentMethod = StringEnum(['PIX', 'CARD'], 'Payment method.');
20+
export const PaymentMethod = StringEnum(
21+
['PIX', 'CARD'],
22+
'Payment method.',
23+
).meta({ example: 'PIX' });
2124

2225
/**
2326
* https://docs.abacatepay.com/pages/payment/create#body-methods
@@ -28,56 +31,91 @@ export type PaymentMethod = z.infer<typeof PaymentMethod>;
2831
* https://docs.abacatepay.com/pages/checkouts/reference#estrutura
2932
*/
3033
export const APICheckout = z.object({
31-
id: z.string().describe('Unique billing identifier.'),
32-
amount: z.int().min(100).describe('Total amount to be paid in cents.'),
34+
id: z
35+
.string()
36+
.describe('Unique billing identifier.')
37+
.meta({ example: 'bill_123' }),
38+
amount: z
39+
.int()
40+
.min(100)
41+
.describe('Total amount to be paid in cents.')
42+
.meta({ example: 4000 }),
3343
paidAmount: z
3444
.union([z.null(), z.int().min(100)])
3545
.describe(
3646
'Amount already paid in cents.`null` if it has not yet been paid.',
37-
),
47+
)
48+
.meta({ example: null }),
3849
externalId: z
3950
.union([z.null(), z.string()])
51+
.meta({ example: null })
4052
.describe('Bill ID in your system.'),
41-
url: z.url().describe('URL where the user can complete the payment.'),
53+
url: z
54+
.url()
55+
.describe('URL where the user can complete the payment.')
56+
.meta({ example: 'https://myshop.com/premium' }),
4257
items: z
4358
.array(
4459
z.object({
4560
id: z.string().describe('Product ID.'),
4661
quantity: z.int().min(1).describe('Item quantity.'),
4762
}),
4863
)
64+
.meta({
65+
example: [
66+
{
67+
id: 'prod_123',
68+
quantity: 1,
69+
},
70+
],
71+
})
4972
.min(1)
5073
.describe('List of items in billing.'),
5174
status: PaymentStatus,
5275
devMode: z
5376
.boolean()
77+
.meta({ example: true })
5478
.describe(
5579
'Indicates whether the charge was created in a development (true) or production (false) environment.',
5680
),
5781
metadata: z
5882
.record(z.string(), z.any())
83+
.meta({ example: {} })
5984
.describe('Additial metadata for the charge.'),
6085
returnUrl: z
6186
.url()
87+
.meta({ example: 'https://myshop.com/premium' })
6288
.describe(
6389
'URL that the customer will be redirected to when clicking the "back" button.',
6490
),
6591
completionUrl: z
6692
.url()
93+
.meta({ example: 'https://myshop.com/thanks' })
6794
.describe(
6895
'URL that the customer will be redirected to when making payment.',
6996
),
70-
receiptUrl: z.union([z.null(), z.url()]).describe('Payment receipt URL.'),
97+
receiptUrl: z
98+
.union([z.null(), z.url()])
99+
.meta({ example: null })
100+
.describe('Payment receipt URL.'),
71101
coupons: z
72102
.array(z.string())
73103
.max(50)
74104
.default([])
105+
.meta({ example: ['SUMMER'] })
75106
.describe('Coupons allowed in billing.'),
76107
customerId: z
77108
.union([z.null(), z.string()])
109+
.meta({ example: null })
78110
.describe('Customer ID associated with the charge.'),
79-
createdAt: z.coerce.date().describe('Charge creation date and time.'),
80-
updatedAt: z.coerce.date().describe('Charge last updated date and time.'),
111+
createdAt: z.coerce
112+
.date()
113+
.describe('Charge creation date and time.')
114+
.meta({ example: new Date() }),
115+
updatedAt: z.coerce
116+
.date()
117+
.describe('Charge last updated date and time.')
118+
.meta({ example: new Date() }),
81119
});
82120

83121
/**

‎packages/zod/src/v2/resources/coupon.ts‎

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ import { StringEnum } from '../../utils';
77
export const CouponDiscountKind = StringEnum(
88
['FIXED', 'PERCENTAGE'],
99
'Type of discount applied by the coupon.',
10-
);
10+
).meta({ example: 'FIXED' });
1111

1212
/**
1313
* https://docs.abacatepay.com/pages/coupon/reference#atributos
@@ -20,7 +20,7 @@ export type CouponDiscountKind = z.infer<typeof CouponDiscountKind>;
2020
export const CouponStatus = StringEnum(
2121
['ACTIVE', 'INACTIVE', 'EXPIRED'],
2222
'Coupon status.',
23-
);
23+
).meta({ example: 'ACTIVE' });
2424

2525
/**
2626
* https://docs.abacatepay.com/pages/coupon/reference#atributos
@@ -33,24 +33,28 @@ export type CouponStatus = z.infer<typeof CouponStatus>;
3333
export const APICoupon = z.object({
3434
id: z
3535
.string()
36+
.meta({ example: 'SUMMER' })
3637
.describe(
3738
'Unique coupon code that your customers will use to apply the discount.',
3839
),
3940
discountKind: CouponDiscountKind,
4041
status: CouponStatus,
4142
maxRedeems: z
4243
.int()
44+
.meta({ example: 25 })
4345
.describe(
4446
'Limit on the number of times the coupon can be used. Use `-1` for unlimited coupons or a specific number to limit usage.',
4547
),
4648
redeemsCount: z
4749
.int()
4850
.min(0)
51+
.meta({ example: 0 })
4952
.describe(
5053
'Counter of how many times the coupon has been used by customers.',
5154
),
5255
devMode: z
5356
.boolean()
57+
.meta({ example: false })
5458
.describe(
5559
'Indicates whether the coupon was created in a development (true) or production (false) environment.',
5660
),
@@ -60,10 +64,17 @@ export const APICoupon = z.object({
6064
'Internal description of the coupon for your organization and control.',
6165
)
6266
.optional(),
63-
createdAt: z.coerce.date().describe('Coupon creation date and time.'),
64-
updatedAt: z.coerce.date().describe('Coupon last updated date and time.'),
67+
createdAt: z.coerce
68+
.date()
69+
.describe('Coupon creation date and time.')
70+
.meta({ example: new Date() }),
71+
updatedAt: z.coerce
72+
.date()
73+
.describe('Coupon last updated date and time.')
74+
.meta({ example: new Date() }),
6575
metadata: z
6676
.record(z.string(), z.any())
77+
.meta({ example: {} })
6778
.describe(
6879
'Object to store additional information about the coupon, such as campaign, category, or other data relevant to your organization.',
6980
),

‎packages/zod/src/v2/resources/customer.ts‎

Lines changed: 24 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,21 +4,38 @@ import { z } from 'zod';
44
* https://docs.abacatepay.com/pages/client/reference#estrutura
55
*/
66
export const APICustomer = z.object({
7-
id: z.string().describe('Unique customer identifier.'),
7+
id: z
8+
.string()
9+
.describe('Unique customer identifier.')
10+
.meta({ example: 'cust_123' }),
811
devMode: z
912
.boolean()
13+
.meta({ example: true })
1014
.describe(
1115
'Indicates whether the client was created in a testing environment.',
1216
),
13-
country: z.string().describe('Customer country.'),
14-
name: z.string().describe("Customer's full name."),
15-
email: z.email().describe("Customer's email"),
16-
taxId: z.string().describe("Customer's CPF or CNPJ."),
17-
cellphone: z.string().describe("Customer's cell phone."),
18-
zipCode: z.string().describe('Customer zip code.'),
17+
country: z.string().describe('Customer country.').meta({ example: 'Brazil' }),
18+
name: z
19+
.string()
20+
.describe("Customer's full name.")
21+
.meta({ example: 'Daniel Lima' }),
22+
email: z
23+
.email()
24+
.describe("Customer's email")
25+
.meta({ example: 'daniel_lima@abacatepay.com' }),
26+
taxId: z
27+
.string()
28+
.describe("Customer's CPF or CNPJ.")
29+
.meta({ example: '012.345.678-90' }),
30+
cellphone: z
31+
.string()
32+
.describe("Customer's cell phone.")
33+
.meta({ example: '(00) 00000-0000' }),
34+
zipCode: z.string().describe('Customer zip code.').meta({ example: '...' }),
1935
metadata: z
2036
.record(z.string(), z.any())
2137
.describe('Additional customer metadata.')
38+
.meta({ example: { externalId: 'my_customer_123' } })
2239
.optional(),
2340
});
2441

‎packages/zod/src/v2/resources/payout.ts‎

Lines changed: 24 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ import { StringEnum } from '../../utils';
77
export const PayoutStatus = StringEnum(
88
['PENDING', 'EXPIRED', 'CANCELLED', 'COMPLETE', 'REFUNDED'],
99
'Transaction status.',
10-
);
10+
).meta({ example: 'PENDING' });
1111

1212
/**
1313
* https://docs.abacatepay.com/pages/payouts/reference#atributos
@@ -18,19 +18,35 @@ export type PayoutStatus = z.infer<typeof PayoutStatus>;
1818
* https://docs.abacatepay.com/pages/payouts/reference
1919
*/
2020
export const APIPayout = z.object({
21-
id: z.string().describe('Unique transaction identifier.'),
21+
id: z
22+
.string()
23+
.describe('Unique transaction identifier.')
24+
.meta({ example: 'payout_123' }),
2225
status: PayoutStatus,
2326
devMode: z
2427
.boolean()
28+
.meta({ example: false })
2529
.describe(
2630
'Indicates whether the transaction was created in a testing environment.',
2731
),
28-
receiptUrl: z.union([z.null(), z.url()]).describe('Transaction proof URL.'),
29-
amount: z.int().describe('Payout value in cents.'),
30-
platformFee: z.int().describe('Platform fee in cents.'),
31-
externalId: z.string().describe('External transaction identifier.'),
32-
createdAt: z.coerce.date().describe('Transaction creation date.'),
33-
updatedAt: z.coerce.date().describe('Transaction update date.'),
32+
receiptUrl: z
33+
.union([z.null(), z.url()])
34+
.describe('Transaction proof URL.')
35+
.meta({ example: null }),
36+
amount: z.int().describe('Payout value in cents.').meta({ example: 3000 }),
37+
platformFee: z.int().describe('Platform fee in cents.').meta({ example: 80 }),
38+
externalId: z
39+
.string()
40+
.describe('External transaction identifier.')
41+
.meta({ example: 'tsx_123' }),
42+
createdAt: z.coerce
43+
.date()
44+
.describe('Transaction creation date.')
45+
.meta({ example: new Date() }),
46+
updatedAt: z.coerce
47+
.date()
48+
.describe('Transaction update date.')
49+
.meta({ example: new Date() }),
3450
});
3551

3652
/**

‎packages/zod/src/v2/resources/pix.ts‎

Lines changed: 28 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -5,24 +5,45 @@ import { PaymentStatus } from './checkout';
55
* https://docs.abacatepay.com/pages/transparents/reference
66
*/
77
export const APIQRCodePIX = z.object({
8-
id: z.string().describe('Unique QRCode PIX identifier.'),
9-
amount: z.int().describe('Charge amount in cents (e.g. 4000 = R$40.00).'),
8+
id: z
9+
.string()
10+
.describe('Unique QRCode PIX identifier.')
11+
.meta({ example: 'pix_char_123' }),
12+
amount: z
13+
.int()
14+
.describe('Charge amount in cents (e.g. 4000 = R$40.00).')
15+
.meta({ example: 4000 }),
1016
status: PaymentStatus,
1117
devMode: z
1218
.boolean()
19+
.meta({ example: false })
1320
.describe(
1421
'Indicates whether the charge is in a testing (true) or production (false) environment.',
1522
),
16-
brCode: z.string().describe('PIX code (copy-and-paste) for payment.'),
17-
brCodeBase64: z
23+
brCode: z
1824
.string()
25+
.describe('PIX code (copy-and-paste) for payment.')
26+
.meta({ example: '00020101021226950014br.gov.bcb.pix' }),
27+
brCodeBase64: z
28+
.base64()
29+
.meta({ example: 'data:image/png;base64,iVBORw0KGgoAAA' })
1930
.describe('PIX code in Base64 format (Useful for displaying in images).'),
2031
platformFee: z
2132
.int()
33+
.meta({ example: 80 })
2234
.describe('Platform fee in cents. Example: 80 means R$0.80.'),
23-
createdAt: z.coerce.date().describe('QRCode PIX creation date and time.'),
24-
updatedAt: z.coerce.date().describe('QRCode PIX last updated date and time.'),
25-
expiresAt: z.coerce.date().describe('QRCode expiration date and time.'),
35+
createdAt: z.coerce
36+
.date()
37+
.describe('QRCode PIX creation date and time.')
38+
.meta({ example: new Date() }),
39+
updatedAt: z.coerce
40+
.date()
41+
.describe('QRCode PIX last updated date and time.')
42+
.meta({ example: new Date() }),
43+
expiresAt: z.coerce
44+
.date()
45+
.describe('QRCode expiration date and time.')
46+
.meta({ example: new Date() }),
2647
});
2748

2849
/**

‎packages/zod/src/v2/resources/product.ts‎

Lines changed: 25 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ import { StringEnum } from '../../utils';
77
export const ProductStatus = StringEnum(
88
['ACTIVE', 'INACTIVE'],
99
'Product status.',
10-
);
10+
).meta({ example: 'ACTIVE' });
1111

1212
/**
1313
* https://docs.abacatepay.com/pages/products/reference#atributos
@@ -18,20 +18,36 @@ export type ProductStatus = z.infer<typeof ProductStatus>;
1818
* https://docs.abacatepay.com/pages/products/reference#estrutura
1919
*/
2020
export const APIProduct = z.object({
21-
id: z.string().describe('The ID of your product.'),
22-
externalId: z.string().describe('Unique product identifier in your system.'),
23-
name: z.string().describe('Product name.'),
24-
price: z.int().describe('Product price in cents.'),
25-
currency: z.string().describe('Product currency.'),
21+
id: z
22+
.string()
23+
.describe('The ID of your product.')
24+
.meta({ example: 'prod_123' }),
25+
externalId: z
26+
.string()
27+
.describe('Unique product identifier in your system.')
28+
.meta({ example: 'product_xyz' }),
29+
name: z.string().describe('Product name.').meta({ example: 'Premium' }),
30+
price: z.int().describe('Product price in cents.').meta({ example: 4000 }),
31+
currency: z.string().describe('Product currency.').meta({ example: 'BRL' }),
2632
status: ProductStatus,
2733
devMode: z
2834
.boolean()
35+
.meta({ example: false })
2936
.describe(
3037
'Indicates whether the product was created in a testing environment.',
3138
),
32-
createdAt: z.coerce.date().describe('Product creation date.'),
33-
updatedAt: z.coerce.date().describe('Product update date.'),
34-
description: z.union([z.null(), z.string()]).describe('Product description.'),
39+
createdAt: z.coerce
40+
.date()
41+
.describe('Product creation date.')
42+
.meta({ example: new Date() }),
43+
updatedAt: z.coerce
44+
.date()
45+
.describe('Product update date.')
46+
.meta({ example: new Date() }),
47+
description: z
48+
.union([z.null(), z.string()])
49+
.meta({ example: null })
50+
.describe('Product description.'),
3551
});
3652

3753
/**

0 commit comments

Comments
 (0)