[skip-ci] add comments marking usage of metadata in avatax

apps/avatax/graphql/fragments/CalculateTaxesEvent.graphql

@@ -6,6 +6,7 @@ fragment CalculateTaxesEvent on Event {
       ...TaxBase
     }
     recipient {
+      # Entire metadata is fetched to provide app configuration. This can be moved to DB
       privateMetadata {
         key
         value

apps/avatax/graphql/fragments/TaxBase.graphql

@@ -63,15 +63,19 @@ fragment TaxBase on TaxableObject {
     __typename
     ... on Checkout {
       id
+      # TODO what was that
       avataxEntityCode: metafield(key: "avataxEntityCode")
+      # Legacy field - moved to user
       avataxCustomerCode: metafield(key: "avataxCustomerCode")
       user {
         ...User
       }
     }
     ... on Order {
       id
+      # TODO what was that
       avataxEntityCode: metafield(key: "avataxEntityCode")
+      # Legacy field - moved to user
       avataxCustomerCode: metafield(key: "avataxCustomerCode")
       user {
         ...User

apps/avatax/graphql/fragments/User.graphql

@@ -1,5 +1,6 @@
 fragment User on User {
   id
   email
+  # Metadata is fetched with user. This is on purpose - must be set on the frontend.
   avataxCustomerCode: metafield(key: "avataxCustomerCode")
 }

apps/avatax/graphql/queries/FetchAppDetails.graphql

@@ -1,6 +1,7 @@
 query FetchAppDetails {
   app {
     id
+    # Programmatic fetch of metadata -> to fetch config
     privateMetadata {
       key
       value

apps/avatax/graphql/queries/FetchAppMetafields.graphql

@@ -1,6 +1,7 @@
 query FetchAppMetafields($keys: [String!]) {
   app {
     id
+    # Programmatic fetch of metadata -> to fetch config
     privateMetafields(keys: $keys)
   }
 }

apps/avatax/graphql/subscriptions/OrderCancelled.graphql

@@ -1,5 +1,6 @@
 fragment OrderCancelledSubscription on Order {
   id
+  # Reference to Avatax transaction. Can be stored in the DB?
   avataxId: metafield(key: "avataxId")
   channel {
     id

apps/avatax/saleor-app.ts

@@ -20,6 +20,10 @@ switch (process.env.APL) {
       throw new Error("Rest APL is not configured - missing env variables. Check saleor-app.ts");
     }
 
+    /**
+     * APL:
+     * - Call REST service every time request to app is executed (webhook, frontend call)
+     */
     apl = new SaleorCloudAPL({
       resourceUrl: process.env.REST_APL_ENDPOINT,
       token: process.env.REST_APL_TOKEN,

apps/avatax/src/lib/app-config-extractor.ts

@@ -14,6 +14,9 @@ export interface IAppConfigExtractor {
 
 /**
  * Extracts app configuration from metadata. Performs initial validation, shared by all clients
+ *
+ * It takes metadata from event (or programmatic call) and maps it to the object.
+ * This can be replaced by similar entity, calling DB
  */
 export class AppConfigExtractor implements IAppConfigExtractor {
   static AppConfigExtractorError = BaseError.subclass("AppConfigExtractorError");

apps/avatax/src/modules/app/order-metadata-manager.ts

@@ -22,6 +22,8 @@ export class OrderMetadataManager {
    * @param orderId - Saleor order id
    * @param externalId - Provider order id
    * @deprecated - This will not be needed when we move to the new webhook flow because the transactions will be commited during OrderConfirmed
+   *
+   * Do we need to store this value? It seems like its stored to cancel order in order-cancelled. So we can store this in DB
    */
   async updateOrderMetadataWithExternalId(orderId: string, externalId: string) {
     const variables: UpdatePublicMetadataMutationVariables = {

apps/avatax/src/modules/avatax/configuration/avatax-connection-repository.ts

@@ -15,6 +15,7 @@ import {
 
 const getSchema = avataxConnectionSchema.strict();
 
+// Uses metadata to CRUD settings
 export class AvataxConnectionRepository {
   private crudSettingsManager: CrudSettingsManager;
   private logger = createLogger("AvataxConnectionRepository", {

apps/avatax/src/modules/avatax/configuration/avatax-patch-input-transformer.ts

@@ -35,6 +35,7 @@ export class AvataxPatchInputTransformer {
   }
 
   async patchCredentials(id: string, input: AvataxConfig["credentials"]) {
+    // Metadata call
     const connection = await this.connection.getById(id);
 
     const credentials: AvataxConfig["credentials"] = {

apps/avatax/src/modules/avatax/tax-code/avatax-tax-codes.router.ts

@@ -17,7 +17,10 @@ const getAllForIdSchema = z.object({
   uniqueKey: z.string(),
 });
 
-// TODO: Add test, but create dependency injection first, so services can be injected in ctx
+/*
+ * TODO: Add test, but create dependency injection first, so services can be injected in ctx
+ * Client router - only CRUD from frontend handled here
+ */
 export const avataxTaxCodesRouter = router({
   getAllForId: protectedClientProcedure.input(getAllForIdSchema).query(async ({ ctx, input }) => {
     const logger = createLogger("avataxTaxCodesRouter.getAllForId");

apps/avatax/src/modules/crud-settings/crud-settings.service.ts

@@ -7,6 +7,7 @@ import { createLogger } from "../../logger";
 const settingSchema = z.record(z.any()).and(z.object({ id: z.string() }));
 const settingsSchema = z.array(settingSchema);
 
+// Abstraction on CRUD operations - writing to Saleor metadata
 export class CrudSettingsManager {
   private logger = createLogger("CrudSettingsManager");
 

apps/avatax/src/pages/api/webhooks/order-confirmed.ts

@@ -78,6 +78,7 @@ export default wrapWithLoggerContext(
                 .json({ message: `Order ${payload.order?.id} has flat rates tax strategy.` });
             }
 
+            // metadata passed through subscription payload
             const appMetadata = payload.recipient?.privateMetadata ?? [];
 
             const configExtractor = new AppConfigExtractor();
@@ -155,6 +156,7 @@ export default wrapWithLoggerContext(
 
                 const orderMetadataManager = new OrderMetadataManager(client);
 
+                // We run metadata mutation here. Its public metadata - result from Avatax attached to Saleor entity
                 await orderMetadataManager.updateOrderMetadataWithExternalId(
                   confirmedOrderEvent.getOrderId(),
                   confirmedOrder.id,