Skip to content

Commit 4b8e1e8

Browse files
turipturip
committed
feat: charges list api
1 parent fe83424 commit 4b8e1e8

17 files changed

Lines changed: 8566 additions & 6696 deletions

File tree

‎api/client/javascript/src/zod/index.ts‎

Lines changed: 6175 additions & 6187 deletions
Large diffs are not rendered by default.

‎api/spec/packages/aip/src/customers/charges/charges.tsp‎

Lines changed: 290 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,290 @@
1+
import "../../shared/index.tsp";
2+
import "../../productcatalog/index.tsp";
3+
import "../../subscriptions/index.tsp";
4+
import "../customer.tsp";
5+
6+
namespace Customers;
7+
8+
/**
9+
* Type of a charge.
10+
*/
11+
@friendlyName("BillingChargeType")
12+
@summary("Charge type")
13+
enum ChargeType {
14+
/**
15+
* A fixed-amount charge.
16+
*/
17+
FlatFee: "flat_fee",
18+
19+
/**
20+
* A usage-priced charge.
21+
*/
22+
UsageBased: "usage_based",
23+
}
24+
25+
/**
26+
* Lifecycle status of a charge.
27+
*/
28+
@friendlyName("BillingChargeStatus")
29+
@summary("Charge status")
30+
enum ChargeStatus {
31+
/**
32+
* The charge has been created but is not active yet.
33+
*/
34+
Created: "created",
35+
36+
/**
37+
* The charge is active.
38+
*/
39+
Active: "active",
40+
41+
/**
42+
* The charge is settled for the service period, but late events may still arrive.
43+
*/
44+
Settled: "settled",
45+
46+
/**
47+
* The charge is fully finalized and no further changes are expected.
48+
*/
49+
Final: "final",
50+
51+
/**
52+
* The charge has been deleted.
53+
*/
54+
Deleted: "deleted",
55+
}
56+
57+
/**
58+
* Shared fields present on all customer charge responses.
59+
*/
60+
#suppress "@openmeter/api-spec-aip/repeated-prefix-grouping" "charge temporal fields should remain flat"
61+
@friendlyName("BillingChargeBase")
62+
@summary("Charge")
63+
model ChargeBase<T extends ChargeType> {
64+
...Shared.Resource;
65+
66+
/**
67+
* The type of the charge.
68+
*/
69+
@visibility(Lifecycle.Read)
70+
@summary("Type")
71+
type: T;
72+
73+
/**
74+
* The customer owning the charge.
75+
*/
76+
@visibility(Lifecycle.Read)
77+
@summary("Customer")
78+
customer: CustomerReference;
79+
80+
/**
81+
* The charge is managed by the following entity.
82+
*/
83+
@visibility(Lifecycle.Read)
84+
@summary("Managed by")
85+
managed_by: Shared.ResourceManagedBy;
86+
87+
/**
88+
* The subscription that originated the charge, when the charge was created from a subscription item.
89+
*/
90+
@visibility(Lifecycle.Read)
91+
@summary("Subscription")
92+
subscription?: Subscriptions.SubscriptionReference;
93+
94+
/**
95+
* The currency of the charge.
96+
*/
97+
@visibility(Lifecycle.Read)
98+
@summary("Currency")
99+
currency: Shared.CurrencyCode;
100+
101+
/**
102+
* The lifecycle status of the charge.
103+
*/
104+
@visibility(Lifecycle.Read)
105+
@summary("Status")
106+
status: ChargeStatus;
107+
108+
/**
109+
* The timestamp when the charge is intended to be invoiced.
110+
*/
111+
@visibility(Lifecycle.Read)
112+
@summary("Invoice at")
113+
invoice_at: Shared.DateTime;
114+
115+
/**
116+
* The effective service period covered by the charge.
117+
*/
118+
@visibility(Lifecycle.Read)
119+
@summary("Service period")
120+
service_period: Shared.ClosedPeriod;
121+
122+
/**
123+
* The full, unprorated service period of the charge.
124+
*/
125+
@visibility(Lifecycle.Read)
126+
@summary("Full service period")
127+
full_service_period: Shared.ClosedPeriod;
128+
129+
/**
130+
* The billing period the charge belongs to.
131+
*/
132+
@visibility(Lifecycle.Read)
133+
@summary("Billing period")
134+
billing_period: Shared.ClosedPeriod;
135+
136+
/**
137+
* The earliest time when the charge should be advanced again by background processing.
138+
*/
139+
@visibility(Lifecycle.Read)
140+
@summary("Advance after")
141+
advance_after?: Shared.DateTime;
142+
143+
/**
144+
* The price of the charge.
145+
*/
146+
@visibility(Lifecycle.Read)
147+
@summary("Price")
148+
price: Shared.CurrencyAmount;
149+
150+
/**
151+
* Unique reference ID of the charge.
152+
*/
153+
@visibility(Lifecycle.Read)
154+
@summary("Unique reference ID")
155+
unique_reference_id?: string;
156+
157+
/**
158+
* Settlement mode of the charge.
159+
*/
160+
@visibility(Lifecycle.Read)
161+
@summary("Settlement mode")
162+
settlement_mode: ProductCatalog.SettlementMode;
163+
}
164+
165+
/**
166+
* A flat fee charge for a customer.
167+
*/
168+
@friendlyName("BillingFlatFeeCharge")
169+
@summary("Flat fee charge")
170+
model FlatFeeCharge {
171+
...ChargeBase<ChargeType.FlatFee>;
172+
173+
/**
174+
* Payment term of the flat fee charge.
175+
*/
176+
@visibility(Lifecycle.Read, Lifecycle.Create)
177+
@summary("Payment term")
178+
payment_term: ProductCatalog.PricePaymentTerm;
179+
180+
/**
181+
* The discounts applied to the charge.
182+
*/
183+
@visibility(Lifecycle.Read, Lifecycle.Create)
184+
@summary("Discounts")
185+
discounts?: OmitProperties<ProductCatalog.Discounts, "usage">;
186+
187+
/**
188+
* The feature associated with the charge, when applicable.
189+
*/
190+
@visibility(Lifecycle.Read, Lifecycle.Create)
191+
@summary("Feature key")
192+
feature_key?: string;
193+
194+
/**
195+
* The proration configuration of the charge.
196+
*/
197+
@visibility(Lifecycle.Read, Lifecycle.Create)
198+
@summary("Proration configuration")
199+
proration_configuration: ProductCatalog.ProrationConfiguration;
200+
201+
// Calculated fields
202+
/**
203+
* The amount after proration of the charge.
204+
*/
205+
@visibility(Lifecycle.Read)
206+
@summary("Amount after proration")
207+
amount_after_proration: Shared.CurrencyAmount;
208+
}
209+
210+
/**
211+
* A usage-based charge for a customer.
212+
*/
213+
@friendlyName("BillingChargeTotals")
214+
model ChargeTotals {
215+
/**
216+
* The amount of the charge already booked to the internal accounting system.
217+
*/
218+
@visibility(Lifecycle.Read)
219+
@summary("Booked")
220+
booked: Shared.Totals;
221+
222+
/**
223+
* The realtime amount of the charge.
224+
*
225+
* Requires the `realtime_usage` expand.
226+
*/
227+
@visibility(Lifecycle.Read)
228+
@summary("Realtime totals")
229+
realtime?: Shared.Totals;
230+
}
231+
232+
/**
233+
* A usage-based charge for a customer.
234+
*/
235+
@friendlyName("BillingUsageBasedCharge")
236+
@summary("Usage-based charge")
237+
model UsageBasedCharge {
238+
...ChargeBase<ChargeType.UsageBased>;
239+
240+
/**
241+
* Discounts applied to the usage-based charge.
242+
*/
243+
@visibility(Lifecycle.Read, Lifecycle.Create)
244+
@summary("Discounts")
245+
discounts?: ProductCatalog.Discounts;
246+
247+
/**
248+
* The feature associated with the charge.
249+
*/
250+
@visibility(Lifecycle.Read, Lifecycle.Create)
251+
@summary("Feature key")
252+
feature_key: string;
253+
254+
// Status fields
255+
256+
/** Aggregated booked and realtime totals for the charge. */
257+
@visibility(Lifecycle.Read)
258+
@summary("Totals for the charge")
259+
totals: ChargeTotals;
260+
}
261+
262+
/**
263+
* Customer charge.
264+
*/
265+
@friendlyName("BillingCharge")
266+
@summary("Customer charge")
267+
@discriminated(#{ envelope: "none", discriminatorPropertyName: "type" })
268+
union Charge {
269+
/**
270+
* A flat fee charge.
271+
*/
272+
flat_fee: FlatFeeCharge,
273+
274+
/**
275+
* A usage-based charge.
276+
*/
277+
usage_based: UsageBasedCharge,
278+
}
279+
280+
/**
281+
* Expands for customer charges.
282+
*/
283+
@friendlyName("BillingChargesExpand")
284+
@summary("Customer charge expands")
285+
enum ChargesExpand {
286+
/**
287+
* The charge's realizations.
288+
*/
289+
RealtimeUsage: "realtime_usage",
290+
}

‎api/spec/packages/aip/src/customers/charges/index.tsp‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
import "./charges.tsp";
2+
import "./operations.tsp";

‎api/spec/packages/aip/src/customers/charges/operations.tsp‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
import "@typespec/http";
2+
import "@typespec/openapi";
3+
import "@typespec/openapi3";
4+
import "../../common/error.tsp";
5+
import "../../common/pagination.tsp";
6+
import "../../shared/index.tsp";
7+
import "../../common/parameters.tsp";
8+
import "./charges.tsp";
9+
10+
using TypeSpec.Http;
11+
using TypeSpec.OpenAPI;
12+
13+
namespace Customers;
14+
15+
interface CustomerChargesOperations {
16+
/**
17+
* List customer charges.
18+
*
19+
* Returns the customer's charges that are represented as either flat fee or usage-based charges.
20+
*/
21+
@get
22+
@operationId("list-customer-charges")
23+
@summary("List customer charges")
24+
list(
25+
...Common.PagePaginationQuery,
26+
@path customerId: Shared.ULID,
27+
28+
/**
29+
* Sort charges returned in the response.
30+
*
31+
* Supported sort attributes are:
32+
* - `id`
33+
* - `created_at`
34+
* - `service_period.from`
35+
* - `billing_period.from`
36+
*/
37+
@query(#{ name: "sort" })
38+
sort?: Common.SortQuery,
39+
40+
/**
41+
* Filter charges by status.
42+
*
43+
* Supported statuses are:
44+
* - `created`
45+
* - `active`
46+
* - `settled`
47+
* - `final`
48+
* - `deleted`
49+
*
50+
* If omitted, all statuses are returned except for `deleted`.
51+
*/
52+
@query(#{ name: "status", explode: true })
53+
status?: ChargeStatus[],
54+
55+
/**
56+
* Expands
57+
*/
58+
@query(#{ name: "expand", explode: true })
59+
expand?: ChargesExpand[],
60+
): Shared.PagePaginatedResponse<Charge> | Common.NotFound | Common.ErrorResponses;
61+
}

‎api/spec/packages/aip/src/customers/index.tsp‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
import "./customer.tsp";
22
import "./operations.tsp";
33
import "./credits/index.tsp";
4+
import "./charges/index.tsp";

‎api/spec/packages/aip/src/konnect.tsp‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,11 @@ interface CustomerCreditGrantEndpoints {
9898
interface CustomerCreditTransactionEndpoints
9999
extends Customers.CustomerCreditTransactionOperations {}
100100

101+
@route("/openmeter/customers/{customerId}/charges")
102+
@tag(Shared.BillingTag)
103+
interface CustomerChargesEndpoints
104+
extends Customers.CustomerChargesOperations {}
105+
101106
@route("/openmeter/subscriptions")
102107
@tag(Shared.SubscriptionsTag)
103108
interface SubscriptionsEndpoints

‎api/spec/packages/aip/src/openmeter.tsp‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,11 @@ interface CustomerCreditGrantEndpoints {
107107
interface CustomerCreditTransactionEndpoints
108108
extends Customers.CustomerCreditTransactionOperations {}
109109

110+
@route("/openmeter/customers/{customerId}/charges")
111+
@tag(Shared.BillingTag)
112+
interface CustomerChargesEndpoints
113+
extends Customers.CustomerChargesOperations {}
114+
110115
@route("/openmeter/subscriptions")
111116
@tag(Shared.SubscriptionsTag)
112117
interface SubscriptionsEndpoints

0 commit comments

Comments
 (0)