@wildo-ai/saas-backend-lib 1.1.1 → 1.1.3

package/dist/esm/billing/services/back-office/usage-metering.backend.service.d.ts

@@ -6,13 +6,13 @@
  *
  * Flow:
  * 1. Operation hook calls recordUsage() after successful operation
- * 2. Usage records are stored in DB (reportedToProvider: false)
+ * 2. Usage records are stored in DB (flushState: pending)
  * 3. Periodic flush (cron) aggregates and reports to provider
  * 4. Provider bills at the end of the billing period
  *
  * @see billing-and-features-system.md §9 (Usage & Consumption Tracking)
  */
-import { UsageSourceType } from '@wildo-ai/saas-models';
+import { type MeteredUsageRecordingDefinition, UsageSourceType } from '@wildo-ai/saas-models';
 import type { StandardBilling_Interface } from '@wildo-ai/external-connectors-models';
 import { AbstractBillingBackendService } from '../../../billing/services/back-office/abstract-billing.backend.service';
 import { type BillingResolvedVariants } from '../../../billing/services/custom-impl/billing-custom-impl-utils.backend';
@@ -21,6 +21,7 @@ import type { ServicesRegistryHandlerBackendService } from '../../../base-classe
 import type { ExecutionContextCreatorBackendService } from '../../../runtime/services/execution-context-creator.backend.service';
 import type { ResourcesRegistryBackendService } from '../../../resources/services/resources-registry.backend.service';
 import type { ErrorBuilderBackendService } from '../../../errors/services/error-builder.backend.service';
+import type { ExecutionContext } from '../../../runtime/models/execution-context.backend.schemas';
 import type { RepositoriesRegistryHandlerBackendService } from '../../../base-classes/services/repositories/repositories-registry-handler.backend.service';
 export interface RecordUsageOptions {
     /** What generated this usage */
@@ -36,10 +37,58 @@ export interface UsageFlushResult {
     totalRecords: number;
     reported: number;
     failed: number;
+    /**
+     * Rows this run moved to `flushState: unreportable` — a PERMANENT determination, distinct from
+     * `failed`, which means "try again next run" (#512).
+     *
+     * The two must never be merged. A failure that is counted as unreportable silently abandons
+     * billable usage; an unreportable row counted as failed is re-selected forever and grows a
+     * backlog nothing can drain, which is the defect this counter was added with.
+     */
+    unreportable: number;
     errors: string[];
+    /**
+     * The RECONCILIATION line: quantity recorded locally versus quantity reported to the provider,
+     * per run (#415).
+     *
+     * Getting metering wrong moves money in BOTH directions, and neither direction announces itself —
+     * an under-report is revenue that never appears, an over-report is a customer charged twice. A
+     * counter of ROWS cannot see either, because rows carry quantities: ten rows reported can be any
+     * amount at all. So the run states what it took in and what it sent out, and the two are meant to
+     * be equal. When they are not, `errors` says why.
+     */
+    quantityRecorded: number;
+    quantityReported: number;
+    /**
+     * Quantity this run determined will NEVER be billed. Counted separately from
+     * {@link quantityReported} because it is the opposite outcome: the provider was not told, and
+     * never will be. It closes the reconciliation identity —
+     * `quantityRecorded === quantityReported + quantityUnreportable + (what stays pending)`.
+     */
+    quantityUnreportable: number;
 }
 export declare class UsageMeteringBackendService extends AbstractBillingBackendService {
     private readonly repositoriesRegistry;
+    /**
+     * How many rows one LIST page fetches while draining the pending set.
+     *
+     * A page size, never a cap: the drain pages until exhausted. It exists because a single query for an
+     * unbounded set is the shape that produced the `limit: 10000` this replaced.
+     */
+    private static readonly FLUSH_PAGE_SIZE;
+    /**
+     * The runaway guard, in PAGES. Reaching it aborts the scope and reports nothing — see
+     * `listAllUnreportedRecords` for why a partial flush is worse than none.
+     *
+     * 2,000 pages is a million pending rows. That is not a busy hour, it is a flush that has not run for
+     * a long time, and the right response is a person rather than a bigger number.
+     */
+    private static readonly MAX_FLUSH_PAGES;
+    /** First retry delay; each subsequent one multiplies by the product's `backoffMultiplier`. */
+    private static readonly RETRY_BASE_DELAY_MS;
+    /** Per-run caches, held only for the duration of one `flushToProvider`. `null` means "looked up, absent". */
+    private flushProductCache?;
+    private flushPeriodCache?;
     constructor(logger: LoggerService, servicesRegistry: ServicesRegistryHandlerBackendService, executionContextCreator: ExecutionContextCreatorBackendService, resourcesRegistry: ResourcesRegistryBackendService, errorBuilder: ErrorBuilderBackendService, repositoriesRegistry: RepositoriesRegistryHandlerBackendService);
     initialize(provider: StandardBilling_Interface): Promise<void>;
     /**
@@ -47,8 +96,46 @@ export declare class UsageMeteringBackendService extends AbstractBillingBackendS
      * Stores locally — NOT reported to provider immediately.
      *
      * @param variants — resolved billing polymorphic variants for the target scope
+     * @returns whether a usage row was actually written.
+     *
+     * The return type was `void` until 2026-09-08 (#415), which was harmless only while nothing called
+     * this: the method DECLINES silently when the account holds no active metered subscription, so a
+     * caller could not distinguish "recorded" from "declined". The first real caller then reported the
+     * quantity it had ASKED for whichever happened — an operational counter claiming usage that was
+     * never written, the same shape as the discarded `modifiedCount` this file already fixed once in
+     * the flush. Caught by a pin rather than by a reading, which is the argument for writing the
+     * refusal cases as carefully as the success ones.
+     */
+    recordUsage(variants: BillingResolvedVariants, billingAccountId: string, productKey: string, quantity: number, options?: RecordUsageOptions): Promise<boolean>;
+    /**
+     * Record usage declared by an OPERATION, resolving the scope, the billing account and the quantity
+     * from the operation's own execution context and result (#415).
+     *
+     * This is the caller `recordUsage` never had. Until it existed, a product could be declared METERED,
+     * priced and synced to the provider while nothing in the framework ever wrote a usage row — the
+     * only way to meter was to reach into this service by hand from a custom implementation, which is a
+     * workaround rather than an authoring surface.
+     *
+     * **Never throws.** It runs after a write has already committed, so a failure here must not turn a
+     * successful operation into an error the caller sees. Every refusal is a warning naming the product
+     * and the reason, because an unrecorded unit is revenue that will not be billed and the log line is
+     * the only thing that will ever say so.
+     *
+     * @returns the quantity recorded, or 0 when nothing was recorded — so a caller can log the outcome
+     *   rather than assume it.
+     */
+    recordDeclaredOperationUsage(declaration: MeteredUsageRecordingDefinition, executionContext: ExecutionContext<any>, operationResult: unknown): Promise<number>;
+    /**
+     * The declared quantity: fixed, or read from the written row.
+     *
+     * A `quantityFromResultField` that does not resolve to a finite non-negative number records NOTHING
+     * and warns, rather than falling back to 1. Silently billing the wrong amount is worse than billing
+     * nothing and saying so — a fallback here would be a wrong number nobody could distinguish from a
+     * right one.
      */
-    recordUsage(variants: BillingResolvedVariants, billingAccountId: string, productKey: string, quantity: number, options?: RecordUsageOptions): Promise<void>;
+    private resolveDeclaredQuantity;
+    /** The scope's billing account, addressed by the scope entity rather than by an id the caller supplies. */
+    private resolveBillingAccountIdForScope;
     /**
      * Get usage summary for a billing account.
      *
@@ -67,6 +154,82 @@ export declare class UsageMeteringBackendService extends AbstractBillingBackendS
      */
     flushToProvider(): Promise<UsageFlushResult>;
     private flushScopeToProvider;
+    /**
+     * Page through EVERY unreported row in this scope.
+     *
+     * The whole set is read before anything is reported, because aggregation is defined over the whole
+     * pending set and a page is not a meaningful unit of it.
+     *
+     * This replaced a single `{ limit: 10000 }` (#415). That cap did not fail when it was reached — it
+     * returned the first ten thousand rows and the run looked healthy, so the eleven-thousandth unit of
+     * usage was simply never billed and nothing anywhere said so. A cap that is reached is money not
+     * billed; the only honest cap is one that REFUSES.
+     */
+    private listAllUnreportedRecords;
+    /**
+     * Keep only the rows whose PRODUCT is due to be flushed, per its authored `flushIntervalMinutes`
+     * (#415).
+     *
+     * The field means "usage for this product should reach the provider within N minutes of being
+     * recorded", so a product is due when its OLDEST pending row has waited that long. Derived from the
+     * rows already in hand — no last-flush timestamp is stored anywhere, because storing one would be a
+     * second source of truth for something the rows already say, and one that can go stale.
+     *
+     * The batch runs on a cadence at least as fast as the shortest interval any product can author; this
+     * is what turns one shared schedule into per-product intervals. A product authoring 1440 accumulates
+     * for a day and produces one provider event instead of 288, which is what its author asked for.
+     *
+     * Note the ASYMMETRY, and it is deliberate: waiting is per product, but once ONE product is due its
+     * rows go now rather than at the next tick. Reporting sooner than authored is never wrong; later is.
+     */
+    private selectDueRecords;
+    /**
+     * Turn pending rows into the groups that will each become one provider meter event, honouring the
+     * product's authored `metering` policy (#415).
+     *
+     * Until this existed the policy block was declared, defaulted, documented and read by NOTHING: every
+     * row was merged by (account, product) whatever the product said, so `preFlushAggregation: false`
+     * was unrepresentable and `aggregationWindow` chose between two behaviours that were the same one.
+     * Its own JSDoc said so and asked that the gap stay visible, which is why this comment says what
+     * replaced it.
+     *
+     * The policy is per PRODUCT, so two products flushing in the same run are grouped by their own
+     * rules — that is why the policy is resolved inside the loop rather than once for the run.
+     */
+    private buildFlushGroups;
+    private reportGroup;
+    /**
+     * Report one meter event, honouring the product's authored `retryPolicy` (#415).
+     *
+     * `maxRetries` and `backoffMultiplier` were authored, defaulted and read by nothing — a provider
+     * blip failed the whole group and left it for the next scheduled run, which on a 60-minute schedule
+     * is an hour of unbilled usage for a fault that would have cleared in a second.
+     *
+     * The retry is SAFE only because of the idempotency identifier the caller supplies: a retry after a
+     * response that was lost in transit re-sends the same identifier, and the provider discards it. Retry
+     * without that is how a timeout becomes a double charge, which is why the two landed together.
+     */
+    private reportWithRetry;
+    /**
+     * A stable, bounded idempotency key for one meter event.
+     *
+     * Derived from the ROWS the event carries — sorted, so ordering cannot change it — and hashed, so a
+     * group of ten thousand rows produces the same short key as a group of one. Two different groups
+     * cannot collide; the same group retried, or re-reported after a partial marking, produces the same
+     * key and the provider discards the repeat.
+     */
+    private buildUsageEventIdentifier;
+    /** The product's authored metering policy, or `undefined` when it authored none. */
+    private resolveMeteringPolicy;
+    /**
+     * The start of the billing period containing `timestamp`, for `PER_BILLING_PERIOD` grouping.
+     *
+     * Derived from the subscription's own `currentPeriodStart` / `currentPeriodEnd` — real data, not a
+     * calendar rule invented here — stepping backwards by the period's own length for usage older than
+     * the current period. Returns `undefined` when no subscription can be resolved, which merges the
+     * rows exactly as `PER_FLUSH` would: an unknown boundary must not silently invent one.
+     */
+    private resolvePeriodStartFor;
     /**
      * Validate that the billing account has an active subscription containing
      * a metered product matching the given product key. Returns true as soon
@@ -75,6 +238,39 @@ export declare class UsageMeteringBackendService extends AbstractBillingBackendS
      * not by subscription item.
      */
     private hasActiveMeteredSubscription;
-    private resolveProviderCustomerId;
+    /**
+     * Resolve the provider customer for a billing account, distinguishing the two ways it can fail.
+     *
+     * This used to return `string | null`, and that single `null` fused a PERMANENT condition with a
+     * TRANSIENT one (#512):
+     *
+     * - the account row is GONE — legitimately reachable, because usage rows are RETAINED when their
+     *   subject is erased, so a deleted account leaves rows behind. Nothing will ever restore the
+     *   mapping, and a flush that keeps retrying is building a backlog it cannot drain;
+     * - the account EXISTS but carries no `providerCustomerId` yet — provisioning may still complete,
+     *   and abandoning those rows would throw away billable usage.
+     *
+     * They lead to opposite actions, so the caller must be able to tell them apart. Two plain fields
+     * rather than a discriminated union deliberately: `engine/tsconfig.common.json` sets
+     * `strict: false`, under which narrowing a union on a boolean-literal discriminant does not work,
+     * and a caller that cannot narrow reads the wrong field with no diagnostic.
+     *
+     * A read that THROWS is treated as transient — `degradeOrRethrow` has already decided the error is
+     * survivable, and a storage failure says nothing about whether the row exists.
+     */
+    private resolveProviderCustomer;
+    /**
+     * Move a group's rows to the terminal `unreportable` state so the flush stops re-selecting them.
+     *
+     * NO money moved and none ever will, which is why this is its own state rather than a convenient
+     * `reported: true`. The reason and the instant are written beside it, because the row is a
+     * RETAINED financial record and the next reader of it — an auditor, an operator reconciling a
+     * period — needs to know why a measured quantity was never billed.
+     *
+     * A marking that does not fully land is reported and NOT retried here: the rows that stayed
+     * pending are simply selected again next run, which is harmless (unlike the reported case, where
+     * a partial marking risks double-billing). The counters follow what the write actually did.
+     */
+    private markGroupUnreportable;
 }
 //# sourceMappingURL=usage-metering.backend.service.d.ts.map

package/dist/esm/billing/services/back-office/usage-metering.backend.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usage-metering.backend.service.d.ts","sourceRoot":"","sources":["../../../../../../src/billing/services/back-office/usage-metering.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAIL,eAAe,EAKhB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,sCAAsC,CAAC;AACtF,OAAO,EAAE,6BAA6B,EAAE,MAAM,kFAAkF,CAAC;AACjI,OAAO,EAAE,KAAK,uBAAuB,EAA6B,MAAM,mFAAmF,CAAC;AAE5J,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAC;AAClG,OAAO,KAAK,EAAE,qCAAqC,EAAE,MAAM,6FAA6F,CAAC;AACzJ,OAAO,KAAK,EAAE,qCAAqC,EAAE,MAAM,+EAA+E,CAAC;AAC3I,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,0EAA0E,CAAC;AAChI,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,kEAAkE,CAAC;AACnH,OAAO,KAAK,EAAE,yCAAyC,EAAE,MAAM,qGAAqG,CAAC;AAMrK,MAAM,WAAW,kBAAkB;IACjC,gCAAgC;IAChC,MAAM,CAAC,EAAE;QACP,IAAI,EAAE,eAAe,CAAC;QACtB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAMD,qBACa,2BAA4B,SAAQ,6BAA6B;IAQX,OAAO,CAAC,QAAQ,CAAC,oBAAoB;gBALjE,MAAM,EAAE,aAAa,EACG,gBAAgB,EAAE,qCAAqC,EAChD,uBAAuB,EAAE,qCAAqC,EAC5E,iBAAiB,EAAE,+BAA+B,EACtD,YAAY,EAAE,0BAA0B,EACR,oBAAoB,EAAE,yCAAyC;IASpI,UAAU,CAAC,QAAQ,EAAE,yBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC;IAU3E;;;;;OAKG;IACU,WAAW,CACtB,QAAQ,EAAE,uBAAuB,EACjC,gBAAgB,EAAE,MAAM,EACxB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,IAAI,CAAC;IAyBhB;;;;OAIG;IACU,QAAQ,CACnB,QAAQ,EAAE,uBAAuB,EACjC,gBAAgB,EAAE,MAAM,EACxB,UAAU,CAAC,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,IAAI,CAAC;QAAC,GAAG,EAAE,IAAI,CAAA;KAAE,GAClC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAwBlC;;;;;;OAMG;IACU,eAAe,IAAI,OAAO,CAAC,gBAAgB,CAAC;YAgC3C,oBAAoB;IAoGlC;;;;;;OAMG;YACW,4BAA4B;YAoC5B,yBAAyB;CAYxC"}
+{"version":3,"file":"usage-metering.backend.service.d.ts","sourceRoot":"","sources":["../../../../../../src/billing/services/back-office/usage-metering.backend.service.ts"],"names":[],"mappings":"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"}