feat(api): tax codes v3 spec (#3882)

Author: tothandras

api/spec/package.json

@@ -25,7 +25,7 @@
     }
   },
   "devDependencies": {
-    "@redocly/cli": "2.14.5",
+    "@redocly/cli": "2.19.1",
     "@types/node": "24.10.1",
     "@typespec/compiler": "1.6.0",
     "@typespec/http": "1.6.0",
@@ -35,7 +35,7 @@
     "@typespec/prettier-plugin-typespec": "1.6.0",
     "@typespec/rest": "0.76.0",
     "@typespec/versioning": "0.76.0",
-    "prettier": "3.8.0",
+    "prettier": "3.8.1",
     "yaml": "2.8.2"
   },
   "private": true,
@@ -53,7 +53,9 @@
       "@typespec/http-client-python": "patches/@typespec__http-client-python.patch"
     },
     "overrides": {
-      "tar@<=7.5.2": ">=7.5.3"
+      "minimatch@<10.2.1": ">=10.2.1",
+      "tar@<7.5.8": ">=7.5.8",
+      "ajv@>=7.0.0-alpha.0 <8.18.0": ">=8.18.0"
     }
   }
 }

api/spec/pnpm-lock.yaml

@@ -10,6 +10,7 @@ import "./entitlements/index.tsp";
 import "./subscriptions/index.tsp";
 import "./apps/index.tsp";
 import "./billing/index.tsp";
+import "./tax/index.tsp";
 
 using TypeSpec.Http;
 using TypeSpec.OpenAPI;
@@ -43,6 +44,7 @@ using TypeSpec.OpenAPI;
 )
 @tagMetadata(Shared.AppsTag, #{ description: Shared.AppsDescription })
 @tagMetadata(Shared.BillingTag, #{ description: Shared.BillingDescription })
+@tagMetadata(Shared.TaxTag, #{ description: Shared.TaxDescription })
 @useAuth(systemAccountAccessToken | personalAccessToken | konnectAccessToken)
 namespace MeteringAndBilling;
 
@@ -81,6 +83,10 @@ interface AppsEndpoints extends Apps.AppsOperations {}
 @tag(Shared.BillingTag)
 interface BillingProfilesEndpoints extends Billing.BillingProfilesOperations {}
 
+@route("/openmeter/tax-codes")
+@tag(Shared.TaxTag)
+interface TaxCodesEndpoints extends Tax.TaxCodesOperations {}
+
 /**
  * The system account access token is meant for automations and integrations that are not directly associated with a human identity.
  */

api/spec/src/v3/konnect.tsp

@@ -40,6 +40,7 @@ using TypeSpec.OpenAPI;
 )
 @tagMetadata(Shared.AppsTag, #{ description: Shared.AppsDescription })
 @tagMetadata(Shared.BillingTag, #{ description: Shared.BillingDescription })
+@tagMetadata(Shared.TaxTag, #{ description: Shared.TaxDescription })
 namespace OpenMeter;
 
 @route("/openmeter/events")
@@ -76,3 +77,7 @@ interface AppsEndpoints extends Apps.AppsOperations {}
 @route("/openmeter/profiles")
 @tag(Shared.BillingTag)
 interface BillingProfilesEndpoints extends Billing.BillingProfilesOperations {}
+
+@route("/openmeter/tax-codes")
+@tag(Shared.TaxTag)
+interface TaxCodesEndpoints extends Tax.TaxCodesOperations {}

api/spec/src/v3/openmeter.tsp

@@ -23,6 +23,9 @@ const AppsDescription = "Apps enable you to extend and customize billing and usa
 const BillingTag = "OpenMeter Billing";
 const BillingDescription = "Billing manages the billing profiles, and invoices for customers.";
 
+const TaxTag = "OpenMeter Tax";
+const TaxDescription = "Tax codes are used to calculate taxes for customers.";
+
 const UnstableExtension = "x-unstable";
 const InternalExtension = "x-internal";
 const PrivateExtension = "x-private";

api/spec/src/v3/shared/consts.tsp

@@ -0,0 +1,38 @@
+import "../shared/resource.tsp";
+import "../shared/index.tsp";
+import "../apps/app.tsp";
+
+namespace Tax;
+
+/**
+ * Mapping of app types to tax codes.
+ */
+@friendlyName("BillingTaxCodeAppMapping")
+model TaxCodeAppMapping {
+  /**
+   * The app type that the tax code is associated with.
+   */
+  @summary("App type")
+  app_type: Apps.AppType;
+
+  /**
+   * Tax code.
+   */
+  @summary("Tax code")
+  tax_code: string;
+}
+
+/**
+ * Tax codes by provider.
+ */
+@friendlyName("BillingTaxCode")
+model TaxCode {
+  ...Shared.ResourceWithKey;
+
+  /**
+   * Mapping of app types to tax codes.
+   */
+  @visibility(Lifecycle.Read, Lifecycle.Update, Lifecycle.Create)
+  @summary("App type to tax code mappings")
+  app_mappings: TaxCodeAppMapping[];
+}

api/spec/src/v3/tax/codes.tsp

@@ -0,0 +1,2 @@
+import "./codes.tsp";
+import "./operations.tsp";

api/spec/src/v3/tax/index.tsp

@@ -0,0 +1,69 @@
+import "@typespec/http";
+import "@typespec/rest";
+import "@typespec/openapi";
+import "@typespec/openapi3";
+import "../common/error.tsp";
+import "../common/pagination.tsp";
+import "../common/parameters.tsp";
+import "../shared/index.tsp";
+import "./codes.tsp";
+
+using TypeSpec.Http;
+using TypeSpec.OpenAPI;
+
+namespace Tax;
+
+interface TaxCodesOperations {
+  @post
+  @operationId("create-tax-code")
+  @summary("Create tax code")
+  @extension(Shared.PrivateExtension, true)
+  @extension(Shared.UnstableExtension, true)
+  create(
+    @body
+    tax_code: Shared.CreateRequest<TaxCode>,
+  ): Shared.CreateResponse<TaxCode> | Common.ErrorResponses;
+
+  @get
+  @operationId("get-tax-code")
+  @summary("Get tax code")
+  @extension(Shared.PrivateExtension, true)
+  @extension(Shared.UnstableExtension, true)
+  get(
+    @path taxCodeId: Shared.ULID,
+  ): Shared.GetResponse<TaxCode> | Common.NotFound | Common.ErrorResponses;
+
+  @get
+  @operationId("list-tax-codes")
+  @summary("List tax codes")
+  @extension(Shared.PrivateExtension, true)
+  @extension(Shared.UnstableExtension, true)
+  list(
+    ...Common.PagePaginationQuery,
+  ): Shared.PagePaginatedResponse<TaxCode> | Common.ErrorResponses;
+
+  @put
+  @operationId("upsert-tax-code")
+  @summary("Upsert tax code")
+  @extension(Shared.PrivateExtension, true)
+  @extension(Shared.UnstableExtension, true)
+  upsert(
+    @path taxCodeId: Shared.ULID,
+
+    @body
+    tax_code: Shared.UpsertRequest<TaxCode>,
+  ):
+    | Shared.UpsertResponse<TaxCode>
+    | Common.Gone
+    | Common.NotFound
+    | Common.ErrorResponses;
+
+  @delete
+  @operationId("delete-tax-code")
+  @summary("Delete tax code")
+  @extension(Shared.PrivateExtension, true)
+  @extension(Shared.UnstableExtension, true)
+  delete(
+    @path taxCodeId: Shared.ULID,
+  ): Shared.DeleteResponse | Common.NotFound | Common.ErrorResponses;
+}