5474312
diff --git a/‎app/saas/src/main/java/stirling/software/saas/config/SaasJpaConfig.java‎
Lines changed: 9 additions & 3 deletions b/‎app/saas/src/main/java/stirling/software/saas/config/SaasJpaConfig.java‎
Lines changed: 9 additions & 3 deletions
diff --git a/‎app/saas/src/main/java/stirling/software/saas/model/TeamMembership.java‎
Lines changed: 7 additions & 0 deletions b/‎app/saas/src/main/java/stirling/software/saas/model/TeamMembership.java‎
Lines changed: 7 additions & 0 deletions
diff --git a/‎app/saas/src/main/java/stirling/software/saas/payg/docs/DefaultDocumentClassifier.java‎
Lines changed: 173 additions & 0 deletions b/‎app/saas/src/main/java/stirling/software/saas/payg/docs/DefaultDocumentClassifier.java‎
Lines changed: 173 additions & 0 deletions
diff --git a/‎app/saas/src/main/java/stirling/software/saas/payg/docs/DocumentClassifier.java‎
Lines changed: 25 additions & 0 deletions b/‎app/saas/src/main/java/stirling/software/saas/payg/docs/DocumentClassifier.java‎
Lines changed: 25 additions & 0 deletions
diff --git a/‎app/saas/src/main/java/stirling/software/saas/payg/docs/DocumentMetrics.java‎
Lines changed: 12 additions & 0 deletions b/‎app/saas/src/main/java/stirling/software/saas/payg/docs/DocumentMetrics.java‎
Lines changed: 12 additions & 0 deletions
diff --git a/‎app/saas/src/main/java/stirling/software/saas/payg/entitlement/WalletEntitlementSnapshot.java‎
Lines changed: 112 additions & 0 deletions b/‎app/saas/src/main/java/stirling/software/saas/payg/entitlement/WalletEntitlementSnapshot.java‎
Lines changed: 112 additions & 0 deletions
@@ -5,18 +5,24 @@
 import org.springframework.context.annotation.Profile;
 import org.springframework.data.jpa.repository.config.EnableJpaRepositories;
 
-/** Registers the {@code :saas} module's entities and repositories with Spring Data JPA. */
+/**
+ * Registers the {@code :saas} module's entities and repositories with Spring Data JPA. Any new
+ * package holding {@code @Repository} or {@code @Entity} classes must be added here, or the beans
+ * won't wire at startup.
+ */
 @Configuration
 @Profile("saas")
 @EnableJpaRepositories(
         basePackages = {
             "stirling.software.saas.repository",
             "stirling.software.saas.billing.repository",
-            "stirling.software.saas.ai.repository"
+            "stirling.software.saas.ai.repository",
+            "stirling.software.saas.payg.repository"
         })
 @EntityScan({
     "stirling.software.saas.model",
     "stirling.software.saas.billing.model",
-    "stirling.software.saas.ai.model"
+    "stirling.software.saas.ai.model",
+    "stirling.software.saas.payg"
 })
 public class SaasJpaConfig {}
@@ -73,6 +73,13 @@ public class TeamMembership implements Serializable {
     @Column(name = "updated_at", nullable = false)
     private LocalDateTime updatedAt;
 
+    /**
+     * Optional per-member spend cap inside the team's wallet, in doc units. NULL means the member
+     * is bounded only by the team-wide cap.
+     */
+    @Column(name = "cap_units")
+    private Long capUnits;
+
     public boolean isLeader() {
         return role == TeamRole.LEADER;
     }
 
@@ -0,0 +1,173 @@
+package stirling.software.saas.payg.docs;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.nio.file.Files;
+import java.util.List;
+import java.util.Objects;
+
+import org.springframework.context.annotation.Profile;
+import org.springframework.stereotype.Component;
+import org.springframework.web.multipart.MultipartFile;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+
+import stirling.software.common.util.TempFile;
+import stirling.software.common.util.TempFileManager;
+import stirling.software.jpdfium.PdfDocument;
+import stirling.software.saas.payg.policy.PricingPolicy;
+
+/**
+ * Reads pages via jpdfium for PDF inputs; treats every other content type as bytes-only.
+ *
+ * <p>For PDFs, units are the larger of {@code ceil(pages / docPagesPerUnit)} and {@code ceil(bytes
+ * / docBytesPerUnit)}. For non-PDFs, only the bytes axis contributes. A single file is clamped to
+ * {@code [1, policy.fileUnitCap]}; a multi-file group is clamped to {@code [1, policy.fileUnitCap *
+ * file_count]} applied to the sum of raw per-file units. Malformed/encrypted PDFs fall back to
+ * bytes-only.
+ *
+ * <p>{@code policy.minChargeUnits} is applied by the charge service, not here. The classifier only
+ * enforces an absolute floor of {@link #MIN_UNITS_PER_NONEMPTY_FILE} so callers can rely on
+ * "non-empty input → at least 1 unit".
+ */
+@Slf4j
+@Component
+@Profile("saas")
+@RequiredArgsConstructor
+public class DefaultDocumentClassifier implements DocumentClassifier {
+
+    private static final String PDF_CONTENT_TYPE = "application/pdf";
+    private static final String DEFAULT_CONTENT_TYPE = "application/octet-stream";
+
+    /** Floor for non-empty input. Distinct from {@code policy.minChargeUnits} (applied later). */
+    private static final int MIN_UNITS_PER_NONEMPTY_FILE = 1;
+
+    private final TempFileManager tempFileManager;
+
+    @Override
+    public DocumentMetrics classify(MultipartFile file, PricingPolicy policy) {
+        Objects.requireNonNull(file, "file");
+        Objects.requireNonNull(policy, "policy");
+
+        FileFacts facts = inspect(file);
+        long rawUnits = computeRawUnits(facts.pages, facts.bytes, policy);
+        // toIntExact: fail loud on overflow rather than silently wrapping a billing number.
+        int units =
+                Math.toIntExact(
+                        Math.max(
+                                MIN_UNITS_PER_NONEMPTY_FILE,
+                                Math.min(policy.getFileUnitCap(), rawUnits)));
+        return new DocumentMetrics(facts.pages, facts.bytes, facts.contentType, units);
+    }
+
+    @Override
+    public DocumentMetrics classify(List<MultipartFile> files, PricingPolicy policy) {
+        Objects.requireNonNull(files, "files");
+        Objects.requireNonNull(policy, "policy");
+        if (files.isEmpty()) {
+            throw new IllegalArgumentException("files must not be empty");
+        }
+
+        int totalPages = 0;
+        long totalBytes = 0;
+        long rawUnitsSum = 0;
+        String firstContentType = null;
+
+        for (MultipartFile file : files) {
+            FileFacts facts = inspect(file);
+            // Sum the *raw* (unclamped) per-file units so the group cap below can actually bind.
+            // Per-file clamping in this loop would make the group cap a no-op.
+            rawUnitsSum =
+                    saturatedAdd(rawUnitsSum, computeRawUnits(facts.pages, facts.bytes, policy));
+            totalPages = saturatedAdd(totalPages, facts.pages);
+            totalBytes = saturatedAdd(totalBytes, facts.bytes);
+            if (firstContentType == null) {
+                firstContentType = facts.contentType;
+            }
+        }
+
+        long groupCap = (long) policy.getFileUnitCap() * files.size();
+        // toIntExact: fail loud on overflow rather than silently wrapping.
+        int totalUnits =
+                Math.toIntExact(
+                        Math.max(
+                                (long) MIN_UNITS_PER_NONEMPTY_FILE,
+                                Math.min(groupCap, rawUnitsSum)));
+
+        return new DocumentMetrics(
+                totalPages,
+                totalBytes,
+                firstContentType != null ? firstContentType : DEFAULT_CONTENT_TYPE,
+                totalUnits);
+    }
+
+    private FileFacts inspect(MultipartFile file) {
+        long bytes = file.getSize();
+        String contentType =
+                file.getContentType() != null ? file.getContentType() : DEFAULT_CONTENT_TYPE;
+        int pages = isPdf(contentType, file.getOriginalFilename()) ? readPageCount(file) : 0;
+        return new FileFacts(pages, bytes, contentType);
+    }
+
+    private static long computeRawUnits(int pages, long bytes, PricingPolicy policy) {
+        long pageUnits = pages > 0 ? ceilDiv(pages, policy.getDocPagesPerUnit()) : 0L;
+        long byteUnits = ceilDiv(bytes, policy.getDocBytesPerUnit());
+        return Math.max(pageUnits, byteUnits);
+    }
+
+    private static long ceilDiv(long numerator, long divisor) {
+        if (numerator <= 0) {
+            return 0;
+        }
+        return (numerator + divisor - 1) / divisor;
+    }
+
+    private static boolean isPdf(String contentType, String filename) {
+        if (PDF_CONTENT_TYPE.equalsIgnoreCase(contentType)) {
+            return true;
+        }
+        return filename != null && filename.toLowerCase().endsWith(".pdf");
+    }
+
+    /**
+     * Materialises the upload to a managed temp file and asks jpdfium for the page count. Returns 0
+     * if the file can't be parsed — the byte-derived axis still produces a charge.
+     */
+    private int readPageCount(MultipartFile file) {
+        try (TempFile temp = tempFileManager.createManagedTempFile(".pdf")) {
+            try (InputStream in = file.getInputStream();
+                    OutputStream out = Files.newOutputStream(temp.getPath())) {
+                in.transferTo(out);
+            }
+            try (PdfDocument doc = PdfDocument.open(temp.getPath())) {
+                return doc.pageCount();
+            }
+        } catch (IOException | RuntimeException e) {
+            log.debug(
+                    "Could not read PDF page count for {} ({}); falling back to bytes-only units",
+                    file.getOriginalFilename(),
+                    e.getClass().getSimpleName());
+            return 0;
+        }
+    }
+
+    private static int saturatedAdd(int a, int b) {
+        long sum = (long) a + b;
+        if (sum > Integer.MAX_VALUE) {
+            return Integer.MAX_VALUE;
+        }
+        return (int) sum;
+    }
+
+    private static long saturatedAdd(long a, long b) {
+        try {
+            return Math.addExact(a, b);
+        } catch (ArithmeticException e) {
+            return Long.MAX_VALUE;
+        }
+    }
+
+    private record FileFacts(int pages, long bytes, String contentType) {}
+}
@@ -0,0 +1,25 @@
+package stirling.software.saas.payg.docs;
+
+import java.util.List;
+
+import org.springframework.web.multipart.MultipartFile;
+
+import stirling.software.saas.payg.policy.PricingPolicy;
+
+/**
+ * Computes the doc-unit cost of an uploaded file (or multi-file input) under a given policy.
+ *
+ * <p>Returns {@code docUnits} with an absolute floor of 1 for non-empty input. {@code
+ * policy.minChargeUnits} is applied at charge time, not here.
+ */
+public interface DocumentClassifier {
+
+    /** Classify a single uploaded file. Returns at least 1 unit, capped at {@code fileUnitCap}. */
+    DocumentMetrics classify(MultipartFile file, PricingPolicy policy);
+
+    /**
+     * Classify a multi-file input (e.g. a merge or overlay). Returns the sum of each file's raw
+     * units, capped at {@code fileUnitCap × files.size()} and floored at 1.
+     */
+    DocumentMetrics classify(List<MultipartFile> files, PricingPolicy policy);
+}
@@ -0,0 +1,12 @@
+package stirling.software.saas.payg.docs;
+
+/**
+ * Output of {@link DocumentClassifier#classify}. {@code pages} is {@code 0} for non-PDF inputs.
+ *
+ * @param pages page count (0 for non-PDFs and for files whose page count couldn't be read)
+ * @param bytes raw byte length of the file
+ * @param contentType MIME type as reported by the upload, or {@code "application/octet-stream"}
+ *     when unknown
+ * @param docUnits computed unit cost, clamped to the policy's {@code fileUnitCap}
+ */
+public record DocumentMetrics(int pages, long bytes, String contentType, int docUnits) {}
@@ -0,0 +1,112 @@
+package stirling.software.saas.payg.entitlement;
+
+import java.io.Serializable;
+import java.time.LocalDateTime;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Objects;
+
+import org.hibernate.annotations.CreationTimestamp;
+import org.hibernate.annotations.JdbcTypeCode;
+import org.hibernate.type.SqlTypes;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Embeddable;
+import jakarta.persistence.EmbeddedId;
+import jakarta.persistence.Entity;
+import jakarta.persistence.EnumType;
+import jakarta.persistence.Enumerated;
+import jakarta.persistence.Table;
+
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+import stirling.software.saas.payg.model.EntitlementState;
+import stirling.software.saas.payg.model.FeatureGate;
+import stirling.software.saas.payg.model.FeatureSet;
+
+/**
+ * Cached entitlement state for the team (one row with {@code user_id = 0}, the team-wide sentinel)
+ * plus optional per-member rows when a member sub-cap is configured. Read on the hot path by the
+ * entitlement guard.
+ *
+ * <p>Composite PK {@code (team_id, user_id)} uses 0 as the team-wide sentinel because Postgres
+ * treats {@code NULL} as not-equal-to-NULL in unique constraints — 0 keeps the PK well-defined.
+ *
+ * <p>No {@code @Version} — rows are produced by full-row recompute, no read-modify-write race.
+ */
+@Entity
+@Table(name = "wallet_entitlement_snapshot")
+@NoArgsConstructor
+@Getter
+@Setter
+public class WalletEntitlementSnapshot implements Serializable {
+
+    private static final long serialVersionUID = 1L;
+
+    public static final long TEAM_WIDE_USER_ID = 0L;
+
+    @EmbeddedId private WalletEntitlementSnapshotId id;
+
+    @Column(name = "period_start", nullable = false)
+    private LocalDateTime periodStart;
+
+    @Column(name = "period_end", nullable = false)
+    private LocalDateTime periodEnd;
+
+    @Column(name = "period_spend_units", nullable = false)
+    private Long periodSpendUnits = 0L;
+
+    @Column(name = "period_cap_units")
+    private Long periodCapUnits;
+
+    @Enumerated(EnumType.STRING)
+    @Column(name = "state", nullable = false, length = 16)
+    private EntitlementState state = EntitlementState.FULL;
+
+    @Enumerated(EnumType.STRING)
+    @Column(name = "feature_set", nullable = false, length = 32)
+    private FeatureSet featureSet = FeatureSet.FULL;
+
+    @JdbcTypeCode(SqlTypes.JSON)
+    @Column(name = "enabled_gates", columnDefinition = "jsonb", nullable = false)
+    private List<FeatureGate> enabledGates = new ArrayList<>();
+
+    @CreationTimestamp
+    @Column(name = "computed_at", nullable = false, updatable = false)
+    private LocalDateTime computedAt;
+
+    @Embeddable
+    @NoArgsConstructor
+    @Getter
+    @Setter
+    public static class WalletEntitlementSnapshotId implements Serializable {
+
+        private static final long serialVersionUID = 1L;
+
+        @Column(name = "team_id", nullable = false)
+        private Long teamId;
+
+        /** Use {@link #TEAM_WIDE_USER_ID} for the team-wide row. */
+        @Column(name = "user_id", nullable = false)
+        private Long userId;
+
+        public WalletEntitlementSnapshotId(Long teamId, Long userId) {
+            this.teamId = teamId;
+            this.userId = userId;
+        }
+
+        @Override
+        public boolean equals(Object o) {
+            if (this == o) return true;
+            if (!(o instanceof WalletEntitlementSnapshotId other)) return false;
+            return Objects.equals(teamId, other.teamId) && Objects.equals(userId, other.userId);
+        }
+
+        @Override
+        public int hashCode() {
+            return Objects.hash(teamId, userId);
+        }
+    }
+}