feat: add e2e test that covers advance action

Author: borosr

e2e/billinginvoices_v3_test.go

@@ -1241,3 +1241,266 @@ func TestV3DeleteBillingInvoice(t *testing.T) {
 		assert.NotNil(t, problem)
 	})
 }
+
+// TestV3AdvanceBillingInvoice exercises POST /api/v3/openmeter/billing/invoices/{invoiceId}/advance
+// Flow:
+//   - Create a customer (v3)
+//   - Create a standard invoice with draft status (v1)
+//   - Apply the advance operation via v3 POST and assert 200
+//   - Attempt to advance the same invoice again and assert 400
+//   - Attempt to advance a gathering invoice via v3 POST and assert 400
+func TestV3AdvanceBillingInvoice(t *testing.T) {
+	c := newV3Client(t)
+	v1 := initClient(t)
+
+	var (
+		customerID         string
+		invoiceID          string // standard invoice ID
+		gatheringInvoiceID string // gathering invoice ID
+	)
+
+	t.Run("Should create a customer", func(t *testing.T) {
+		key := uniqueKey("advanceinv_customer")
+		currency := apiv3.CurrencyCode("USD")
+
+		status, customer, problem := c.CreateCustomer(apiv3.CreateCustomerRequest{
+			Key:      key,
+			Name:     gofakeit.ProductName(),
+			Currency: &currency,
+		})
+		require.Equal(t, http.StatusCreated, status, "problem: %+v", problem)
+		require.NotNil(t, customer)
+		customerID = customer.Id
+	})
+
+	t.Run("Should pin the customer to a short-draft-period billing profile", func(t *testing.T) {
+		require.NotEmpty(t, customerID, "depends on customer creation")
+
+		// A short, nonzero draft period parks the invoice in draft.waiting_auto_approval
+		// right after creation (auto-advance is otherwise instantaneous with the default
+		// P0D draft period, which would leave nothing in draft to advance). Once the
+		// period elapses, the first advance call unblocks trigger_next and drives the
+		// invoice forward; the second call then finds no further automatic transition.
+		//
+		// The default profile's payment settings auto-charge via CollectionMethodChargeAutomatically,
+		// which (with credits enabled in e2e) settles the invoice to "paid" synchronously
+		// the moment it's advanced past issued — leaving nothing observable to assert on.
+		// Overriding payment to send_invoice (same as the manual-approval profiles used
+		// elsewhere in this file) stops that auto-settlement, so advancing lands on a real,
+		// inspectable non-final status instead.
+		profile := createNewBillingProfileFromDefault(t, c, uniqueKey("advance_invoice"), func(profile *apiv3.CreateBillingProfileRequest) {
+			if profile.Workflow.Invoicing == nil {
+				profile.Workflow.Invoicing = &apiv3.BillingWorkflowInvoicingSettings{}
+			}
+			profile.Workflow.Invoicing.AutoAdvance = lo.ToPtr(true)
+			profile.Workflow.Invoicing.DraftPeriod = lo.ToPtr("PT5S")
+
+			sendInvoice := apiv3.BillingWorkflowPaymentSettings{}
+			require.NoError(t, sendInvoice.FromBillingWorkflowPaymentSendInvoiceSettings(apiv3.BillingWorkflowPaymentSendInvoiceSettings{
+				CollectionMethod: apiv3.BillingWorkflowPaymentSendInvoiceSettingsCollectionMethodSendInvoice,
+			}))
+			profile.Workflow.Payment = &sendInvoice
+		})
+
+		status, _, problem := c.UpdateCustomerBilling(customerID, apiv3.UpsertCustomerBillingDataRequest{
+			BillingProfile: &apiv3.BillingProfileReference{Id: profile.Id},
+		})
+		require.Equal(t, http.StatusOK, status, "problem: %+v", problem)
+	})
+
+	t.Run("Should create a single gathering invoice", func(t *testing.T) {
+		require.NotEmpty(t, customerID, "depends on customer creation")
+
+		now := time.Now().UTC()
+		price := api.RateCardUsageBasedPrice{}
+		require.NoError(t, price.FromFlatPriceWithPaymentTerm(api.FlatPriceWithPaymentTerm{
+			Amount:      api.Numeric("10.00"),
+			Type:        api.FlatPriceWithPaymentTermTypeFlat,
+			PaymentTerm: lo.ToPtr(api.PricePaymentTermInAdvance),
+		}))
+
+		invoiceAt := now.Add(time.Hour)
+		lineResp, err := v1.CreatePendingInvoiceLineWithResponse(t.Context(), customerID, api.InvoicePendingLineCreateInput{
+			Currency: "USD",
+			Lines: []api.InvoicePendingLineCreate{
+				{
+					Name:      uniqueKey("advance_inv_gathering_line"),
+					InvoiceAt: invoiceAt,
+					Period: api.Period{
+						From: now.Add(-24 * time.Hour),
+						To:   invoiceAt,
+					},
+					Price: &price,
+				},
+			},
+		})
+		require.NoError(t, err)
+		require.Equal(t, http.StatusCreated, lineResp.StatusCode(), "line: %s", string(lineResp.Body))
+		require.NotNil(t, lineResp.JSON201)
+
+		gatheringInvoiceID = (*lineResp.JSON201).Invoice.Id
+		require.NotEmpty(t, gatheringInvoiceID)
+	})
+
+	t.Run("Should create meter, feature, plan, and subscription", func(t *testing.T) {
+		require.NotEmpty(t, customerID, "depends on customer creation")
+
+		// An active subscription is what actually drives the billing-worker's sync
+		// loop for this customer; without one, a raw past-due pending line just sits
+		// in the gathering invoice forever (nothing else periodically collects it).
+		status, meter, problem := c.CreateMeter(apiv3.CreateMeterRequest{
+			Key:         uniqueKey("advanceinv_meter"),
+			Name:        gofakeit.ProductName(),
+			Aggregation: apiv3.MeterAggregationCount,
+			EventType:   uniqueKey("advanceinv_event"),
+		})
+		require.Equal(t, http.StatusCreated, status, "problem: %+v", problem)
+
+		status, f, problem := c.CreateFeature(apiv3.CreateFeatureRequest{
+			Key:   uniqueKey("advanceinv_feature"),
+			Name:  gofakeit.ProductName(),
+			Meter: &apiv3.FeatureMeterReference{Id: meter.Id},
+		})
+		require.Equal(t, http.StatusCreated, status, "problem: %+v", problem)
+
+		status, plan, problem := c.CreatePlan(apiv3.CreatePlanRequest{
+			Key:            uniqueKey("advanceinv_plan"),
+			Name:           gofakeit.ProductName(),
+			Currency:       "USD",
+			BillingCadence: apiv3.ISO8601Duration("P1M"),
+			Phases: []apiv3.BillingPlanPhase{{
+				Key:       uniqueKey("inv_phase_1"),
+				Name:      uniqueKey("Test Phase"),
+				RateCards: []apiv3.BillingRateCard{validUnitRateCard(*f)},
+			}},
+		})
+		require.Equal(t, http.StatusCreated, status, "problem: %+v", problem)
+		planID := plan.Id
+
+		status, plan, problem = c.PublishPlan(planID)
+		require.Equal(t, http.StatusOK, status, "problem: %+v", problem)
+		assert.Equal(t, apiv3.BillingPlanStatusActive, plan.Status)
+
+		status, _, problem = c.CreateSubscription(apiv3.BillingSubscriptionCreate{
+			Customer: struct {
+				Id  *apiv3.ULID                `json:"id,omitempty"`
+				Key *apiv3.ExternalResourceKey `json:"key,omitempty"`
+			}{Id: lo.ToPtr(customerID)},
+			Plan: struct {
+				Id      *apiv3.ULID        `json:"id,omitempty"`
+				Key     *apiv3.ResourceKey `json:"key,omitempty"`
+				Version *int               `json:"version,omitempty"`
+			}{Id: lo.ToPtr(planID)},
+		})
+		require.Equal(t, http.StatusCreated, status, "problem: %+v", problem)
+	})
+
+	t.Run("Should create a standard invoice in draft status", func(t *testing.T) {
+		require.NotEmpty(t, customerID, "depends on customer creation")
+
+		now := time.Now().UTC()
+		price := api.RateCardUsageBasedPrice{}
+		require.NoError(t, price.FromFlatPriceWithPaymentTerm(api.FlatPriceWithPaymentTerm{
+			Amount:      api.Numeric("10.00"),
+			Type:        api.FlatPriceWithPaymentTermTypeFlat,
+			PaymentTerm: lo.ToPtr(api.PricePaymentTermInAdvance),
+		}))
+
+		lineResp, err := v1.CreatePendingInvoiceLineWithResponse(t.Context(), customerID, api.InvoicePendingLineCreateInput{
+			Currency: "USD",
+			Lines: []api.InvoicePendingLineCreate{{
+				Name:      uniqueKey("advanceinv_line"),
+				InvoiceAt: now.Add(-10 * time.Hour),
+				Period: api.Period{
+					From: now.Add(-24 * time.Hour),
+					To:   now.Add(-2 * time.Hour),
+				},
+				Price: &price,
+			}},
+		})
+		require.NoError(t, err)
+		require.Equal(t, http.StatusCreated, lineResp.StatusCode())
+
+		ctx := t.Context()
+		customers := api.InvoiceListParamsCustomers{customerID}
+		assert.EventuallyWithT(t, func(co *assert.CollectT) {
+			listResp, err := v1.ListInvoicesWithResponse(ctx, &api.ListInvoicesParams{
+				Customers: &customers,
+				PageSize:  lo.ToPtr(api.PaginationPageSize(100)),
+			})
+			require.NoError(co, err)
+			require.Equal(co, http.StatusOK, listResp.StatusCode())
+
+			invoice, found := lo.Find(listResp.JSON200.Items, func(inv api.Invoice) bool {
+				return inv.Status == api.InvoiceStatusDraft
+			})
+			assert.True(co, found, "charges have not advanced a pending line into a standard invoice yet")
+			if found {
+				invoiceID = invoice.Id
+			}
+		}, time.Minute, time.Second)
+		require.NotEmpty(t, invoiceID)
+	})
+
+	t.Run("Should advance the standard invoice via v3 POST", func(t *testing.T) {
+		require.NotEmpty(t, invoiceID, "depends on invoice creation")
+
+		// The invoice rests in draft.waiting_auto_approval until the draft period
+		// (PT5S) elapses, so retry until the state machine's guard clears.
+		assert.EventuallyWithT(t, func(co *assert.CollectT) {
+			status, inv, problem := c.AdvanceBillingInvoice(invoiceID)
+			require.Equal(co, http.StatusOK, status, "problem: %+v", problem)
+			require.NotNil(co, inv)
+
+			stdInv, err := inv.AsBillingInvoiceStandard()
+			require.NoError(co, err)
+			assert.Equal(co, invoiceID, stdInv.Id)
+			// send_invoice payment settings prevent auto-settlement, so advancing
+			// should land on a real non-final status (e.g. issued/payment_processing),
+			// not race straight through to paid.
+			assert.NotEqual(co, apiv3.BillingInvoiceStandardStatusPaid, stdInv.Status)
+		}, 20*time.Second, time.Second)
+	})
+
+	t.Run("Should return 400 when advancing the same invoice again", func(t *testing.T) {
+		require.NotEmpty(t, invoiceID, "depends on invoice advance")
+
+		status, inv, problem := c.AdvanceBillingInvoice(invoiceID)
+		assert.Equal(t, http.StatusBadRequest, status, "problem: %+v", problem)
+		assert.Nil(t, inv)
+		assert.NotNil(t, problem)
+	})
+
+	t.Run("Should return 400 when advancing a gathering invoice via v3 POST", func(t *testing.T) {
+		require.NotEmpty(t, gatheringInvoiceID, "depends on gathering invoice creation")
+
+		status, inv, problem := c.AdvanceBillingInvoice(gatheringInvoiceID)
+		assert.Equal(t, http.StatusBadRequest, status, "problem: %+v", problem)
+		assert.Nil(t, inv)
+		assert.NotNil(t, problem)
+	})
+}
+
+// TestV3ApproveBillingInvoice exercises POST /api/v3/openmeter/billing/invoices/{invoiceId}/approve
+// Flow:
+//   - Create a customer (v3)
+//   - Create a standard invoice with draft status (v1)
+//   - Apply the approve operation via v3 POST and assert 200
+//   - Attempt to approve the same invoice again and assert 400
+//   - Attempt to approve a gathering invoice via v3 POST and assert 400
+//   - Create a standard invoice with manual_approval_needed status (v1)
+//   - Apply the approve operation via v3 POST and assert 200
+//   - Attempt to approve the same invoice again and assert 400
+//   - Attempt to approve a gathering invoice via v3 POST and assert 400
+func TestV3ApproveBillingInvoice(t *testing.T) {
+}
+
+// TestV3ApproveBillingInvoice exercises POST /api/v3/openmeter/billing/invoices/{invoiceId}/retry
+// Flow:
+//   - Create a customer (v3)
+//   - Create a standard invoice with draft status (v1)
+//   - Apply the retry operation via v3 POST and assert 200
+//   - Attempt to retry the same invoice again and assert 400
+//   - Attempt to retry a gathering invoice via v3 POST and assert 400
+func TestV3RetryBillingInvoice(t *testing.T) {
+}

e2e/v3helpers_test.go

@@ -437,6 +437,11 @@ func (c *v3Client) DeleteBillingInvoice(invoiceID string) (int, *v3Problem) {
 	return status, problem
 }
 
+func (c *v3Client) AdvanceBillingInvoice(invoiceID string) (int, *apiv3.BillingInvoice, *v3Problem) {
+	status, raw, problem := c.do(http.MethodPost, "/billing/invoices/"+invoiceID+"/advance", nil)
+	return decodeTyped[apiv3.BillingInvoice](c, status, raw, problem, http.StatusOK)
+}
+
 // --- Credits ---
 
 // CreateCreditGrant posts a credit grant for the given customer. customerID is

openmeter/billing/service/invoice.go

@@ -475,7 +475,9 @@ func (s *Service) withLockedInvoiceStateMachine(
 	}
 
 	if invoiceHeader.Type() != billing.InvoiceTypeStandard {
-		return billing.StandardInvoice{}, fmt.Errorf("invoice[%s] is not a standard invoice, state machine should not be used for manipulation", in.InvoiceID.ID)
+		return billing.StandardInvoice{}, billing.ValidationError{
+			Err: fmt.Errorf("invoice[%s] is not a standard invoice, state machine should not be used for manipulation", in.InvoiceID.ID),
+		}
 	}
 
 	standardInvoice, err := invoiceHeader.AsStandardInvoice()