nolo-cli 0.1.26 → 0.1.29

package/auth/server/productPurchase.ts

@@ -0,0 +1,382 @@
+import { DB_PREFIX, createTransactionKey } from "../../database/keys";
+import serverDb from "../../database/server/db";
+
+import { balanceLockManager } from "./locks";
+import {
+  prepareLedgerTransactionAppend,
+  userAvailableCreditsAccountId,
+  type BillingLedgerRuntime,
+} from "./ledger";
+import { resolveProductBillingSplit } from "./productBillingSplits";
+import { withRetry } from "./utils";
+import { buildRevenueShareProjectionOps } from "./revenueShareLedger";
+import {
+  entitlementKey,
+  getActiveEntitlement,
+  getProductRecord,
+  productPurchaseKey,
+  type EntitlementRecord,
+  type ProductPurchaseRecord,
+} from "./productEntitlements";
+
+type ProductPurchaseStore = {
+  get: (key: string) => Promise<unknown>;
+  batch: (
+    ops: Array<{ type: "put"; key: string; value: unknown }>
+  ) => Promise<void>;
+};
+
+export type PurchaseProductResult =
+  | {
+      success: true;
+      status: "purchased" | "already_entitled" | "owner_access";
+      productId: string;
+      buyerId: string;
+      purchaseId?: string;
+      entitlement?: EntitlementRecord;
+      balance?: number;
+      txId?: string;
+      amountCredits?: number;
+    }
+  | {
+      success: false;
+      status:
+        | "not_found"
+        | "disabled"
+        | "invalid_amount"
+        | "invalid_split_policy"
+        | "user_not_found"
+        | "invalid_user_balance"
+        | "insufficient_funds"
+        | "duplicate_without_entitlement"
+        | "ledger_rejected"
+        | "failed";
+      productId: string;
+      buyerId: string;
+      error: string;
+      balance?: number;
+      txId?: string;
+    };
+
+const getMaybe = async <T>(
+  store: ProductPurchaseStore,
+  key: string
+): Promise<T | null> => {
+  try {
+    return ((await store.get(key)) ?? null) as T | null;
+  } catch {
+    return null;
+  }
+};
+
+const isPositiveFinite = (value: unknown): value is number =>
+  typeof value === "number" && Number.isFinite(value) && value > 0;
+
+export async function purchaseProduct({
+  store = serverDb,
+  runtime,
+  buyerId,
+  productId,
+  txId = `product-purchase-${buyerId}-${productId}`,
+  nowMs = Date.now(),
+}: {
+  store?: ProductPurchaseStore;
+  runtime?: BillingLedgerRuntime;
+  buyerId: string;
+  productId: string;
+  txId?: string;
+  nowMs?: number;
+}): Promise<PurchaseProductResult> {
+  const lock = balanceLockManager.getLock(
+    `product-purchase:${buyerId}:${productId}`
+  );
+
+  return lock.runExclusive(async () => {
+    try {
+      const product = await getProductRecord({ store, productId });
+      if (!product) {
+        return {
+          success: false,
+          status: "not_found",
+          buyerId,
+          productId,
+          error: "Product not found",
+        };
+      }
+      if (product.status !== "active") {
+        return {
+          success: false,
+          status: "disabled",
+          buyerId,
+          productId,
+          error: "Product disabled",
+        };
+      }
+
+      const amountCredits = product.pricing?.amountCredits;
+      if (!isPositiveFinite(amountCredits)) {
+        return {
+          success: false,
+          status: "invalid_amount",
+          buyerId,
+          productId,
+          error: "Invalid product amount",
+        };
+      }
+      if (product.ownerUserId === buyerId) {
+        return {
+          success: true,
+          status: "owner_access",
+          buyerId,
+          productId,
+          amountCredits: 0,
+        };
+      }
+
+      const existingEntitlement = await getActiveEntitlement({
+        store,
+        userId: buyerId,
+        productId,
+        nowMs,
+      });
+      if (existingEntitlement) {
+        return {
+          success: true,
+          status: "already_entitled",
+          buyerId,
+          productId,
+          entitlement: existingEntitlement,
+          amountCredits,
+        };
+      }
+
+      const userKey = `${DB_PREFIX.USER}${buyerId}`;
+      const userData = await getMaybe<any>(store, userKey);
+      if (!userData) {
+        return {
+          success: false,
+          status: "user_not_found",
+          buyerId,
+          productId,
+          error: "User not found",
+        };
+      }
+      if (typeof userData.balance !== "number") {
+        return {
+          success: false,
+          status: "invalid_user_balance",
+          buyerId,
+          productId,
+          error: "User balance invalid",
+        };
+      }
+
+      const txIndexKey = createTransactionKey.index(txId);
+      const existingTx = await getMaybe(store, txIndexKey);
+      if (existingTx) {
+        return {
+          success: false,
+          status: "duplicate_without_entitlement",
+          buyerId,
+          productId,
+          error: "Duplicate product purchase transaction without entitlement",
+          txId,
+        };
+      }
+
+      const splitResult = resolveProductBillingSplit({ product });
+      if (splitResult.status !== "rated") {
+        return {
+          success: false,
+          status: "invalid_split_policy",
+          buyerId,
+          productId,
+          error: splitResult.error,
+          balance: userData.balance,
+          txId,
+        };
+      }
+      const split = splitResult.rating;
+
+      const ledgerAppend = await prepareLedgerTransactionAppend({
+        store,
+        runtime,
+        type: "purchase",
+        reason: `product_purchase:${productId}`,
+        idempotencyKey: `product_purchase:${buyerId}:${productId}`,
+        txId,
+        entries: [
+          {
+            accountId: userAvailableCreditsAccountId(buyerId),
+            ownerUserId: buyerId,
+            delta: -split.grossCredits,
+            startingBalance: userData.balance,
+            metadata: { role: "buyer_debit", productId },
+          },
+          ...split.shares.map((share) => ({
+            accountId: share.accountId,
+            ...(share.userId ? { ownerUserId: share.userId } : {}),
+            delta: share.amountCredits,
+            ...(share.role === "platform_net" &&
+            share.amountCredits < 0 &&
+            split.allowNegativePlatformNet
+              ? { allowNegative: true }
+              : {}),
+            metadata: { role: share.role, productId },
+          })),
+        ],
+        metadata: {
+          productId,
+          buyerId,
+          sellerUserId: product.ownerUserId,
+          kind: product.kind,
+          grossCredits: split.grossCredits,
+          platformCostCredits: split.platformCostCredits,
+          creatorShareCredits: split.creatorShareCredits,
+          platformNetCredits: split.platformNetCredits,
+          splitPolicy: split.splitPolicy,
+        },
+        now: nowMs,
+      });
+
+      if (
+        ledgerAppend.status === "insufficient_funds" ||
+        userData.balance < split.grossCredits
+      ) {
+        return {
+          success: false,
+          status: "insufficient_funds",
+          buyerId,
+          productId,
+          error: "Insufficient balance",
+          balance: userData.balance,
+          txId,
+        };
+      }
+      if (ledgerAppend.status !== "prepared") {
+        return {
+          success: false,
+          status: "ledger_rejected",
+          buyerId,
+          productId,
+          error: `Ledger append rejected: ${ledgerAppend.status}`,
+          txId,
+        };
+      }
+
+      const balanceAfter =
+        ledgerAppend.transaction.entries.find(
+          (entry) => entry.accountId === userAvailableCreditsAccountId(buyerId)
+        )?.balanceAfter ?? userData.balance - amountCredits;
+
+      const purchaseId = `product_purchase:${buyerId}:${productId}`;
+      const purchaseRecord: ProductPurchaseRecord = {
+        dbKey: productPurchaseKey(buyerId, productId),
+        purchaseId,
+        buyerId,
+        productId,
+        sellerUserId: product.ownerUserId,
+        amountCredits: split.grossCredits,
+        status: "succeeded",
+        ledgerTxId: txId,
+        idempotencyKey: purchaseId,
+        createdAt: nowMs,
+      };
+      const entitlement: EntitlementRecord = {
+        dbKey: entitlementKey(buyerId, productId),
+        userId: buyerId,
+        productId,
+        status: "active",
+        grants: ["read", "import", "use"],
+        sourcePurchaseId: purchaseId,
+        grantedAt: nowMs,
+      };
+      const projection = buildRevenueShareProjectionOps({
+        runtime: {
+          clusterId: ledgerAppend.transaction.clusterId,
+          nodeId: ledgerAppend.transaction.nodeId,
+          role: "leader",
+        },
+        idempotencyKey: `product_purchase:${buyerId}:${productId}`,
+        createdAt: nowMs,
+        source: {
+          kind: "product_purchase",
+          productId,
+          purchaseId,
+          billingTxId: txId,
+        },
+        payerUserId: buyerId,
+        product: {
+          kind: product.kind,
+          id: productId,
+        },
+        splitPolicy: split.splitPolicy,
+        grossCredits: split.grossCredits,
+        platformCostCredits: split.platformCostCredits,
+        creatorShareCredits: split.creatorShareCredits,
+        platformNetCredits: split.platformNetCredits,
+        shares: split.shares,
+      });
+
+      await withRetry(
+        async () => {
+          await store.batch([
+            ...ledgerAppend.operations,
+            ...projection.operations,
+            {
+              type: "put",
+              key: createTransactionKey.record(buyerId, txId),
+              value: {
+                txId,
+                userId: buyerId,
+                type: "purchase",
+                amount: split.grossCredits,
+                reason: `product_purchase:${productId}`,
+                timestamp: nowMs,
+                status: "completed",
+              },
+            },
+            {
+              type: "put",
+              key: txIndexKey,
+              value: { userId: buyerId, timestamp: nowMs },
+            },
+            {
+              type: "put",
+              key: userKey,
+              value: {
+                ...userData,
+                balance: balanceAfter,
+                lastDeductAt: nowMs,
+              },
+            },
+            { type: "put", key: purchaseRecord.dbKey, value: purchaseRecord },
+            { type: "put", key: entitlement.dbKey, value: entitlement },
+          ]);
+        },
+        { maxAttempts: 3, delayMs: 1000, backoff: true }
+      );
+
+      return {
+        success: true,
+        status: "purchased",
+        buyerId,
+        productId,
+        purchaseId,
+        entitlement,
+        balance: balanceAfter,
+        txId,
+        amountCredits: split.grossCredits,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        status: "failed",
+        buyerId,
+        productId,
+        error: error instanceof Error ? error.message : String(error),
+        txId,
+      };
+    }
+  });
+}

package/auth/server/recharge.ts

@@ -0,0 +1,284 @@
+// auth/server/recharge.ts
+import { ulid } from "ulid";
+import serverDb from "../../database/server/db";
+import { createTransactionKey } from "../../database/keys";
+import { balanceLockManager } from "./locks";
+import { withRetry } from "./utils";
+import pino from "pino";
+import { DB_PREFIX } from "../../database/keys";
+import { notifyRechargeResultEmail } from "./emailScenarioNotifications";
+import { CORE_FLOW_STAGES } from "./emailAutomationTypes";
+import {
+  prepareLedgerTransactionAppend,
+  userAvailableCreditsAccountId,
+} from "./ledger";
+
+const logger = pino({ name: "recharge" });
+
+interface RechargeResult {
+  success: boolean;
+  balance?: number;
+  error?: string;
+  txId?: string;
+}
+
+interface TransactionRecord {
+  txId: string;
+  toUserId: string;
+  type: "recharge";
+  amount: number;
+  reason: string;
+  timestamp: number;
+  status: "completed" | "failed";
+}
+
+interface UserData {
+  username: string;
+  publicKey: string;
+  locale: string;
+  createdAt: number;
+  email: string;
+  balance: number;
+  balanceUpdatedAt: number;
+  [key: string]: any;
+}
+
+const shouldMarkFirstCoreAction = (reason: string) => {
+  const value = String(reason || "").toLowerCase();
+  if (!value) return false;
+  if (value.includes("bonus")) return false;
+  if (value.includes("invite")) return false;
+  if (value.includes("reward")) return false;
+  return true;
+};
+
+export async function rechargeUserBalance(
+  toUserId: string,
+  amount: number,
+  reason: string = "admin_recharge",
+  txId: string = ulid()
+): Promise<RechargeResult> {
+  const lock = balanceLockManager.getLock(toUserId);
+
+  return await lock.runExclusive(async () => {
+    try {
+      const numericAmount = Number(amount);
+
+      if (!numericAmount || isNaN(numericAmount) || numericAmount <= 0) {
+        logger.warn({ toUserId, amount }, "Invalid recharge amount");
+        return { success: false, error: "Invalid amount" };
+      }
+
+      const txIndexKey = createTransactionKey.index(txId);
+      let existingTx = null;
+
+      try {
+        existingTx = await serverDb.get(txIndexKey);
+      } catch (err) {
+        if (!(err instanceof Error && "notFound" in err)) {
+          throw err;
+        }
+      }
+
+      if (existingTx) {
+        logger.warn({ txId, toUserId }, "Duplicate transaction detected");
+        return {
+          success: false,
+          error: "Duplicate transaction",
+          txId,
+        };
+      }
+
+      const userKey = `${DB_PREFIX.USER}${toUserId}`;
+      let userData: UserData | null = null;
+
+      try {
+        userData = await serverDb.get(userKey);
+        logger.debug({ toUserId, userData, userKey }, "Retrieved user data");
+      } catch (err) {
+        if (err instanceof Error && "notFound" in err) {
+          logger.error({ toUserId, userKey }, "User not found");
+          return { success: false, error: "User not found" };
+        }
+        throw err;
+      }
+
+      if (typeof userData?.balance !== "number") {
+        logger.error(
+          { toUserId, userData, userKey },
+          "Invalid user data - balance must be a number"
+        );
+        void notifyRechargeResultEmail({
+          userId: toUserId,
+          amount: numericAmount,
+          reason,
+          success: false,
+          error: "User data invalid",
+        });
+        return { success: false, error: "User data invalid" };
+      }
+
+      const currentBalance = userData.balance;
+      const now = Date.now();
+      const ledgerAppend = await prepareLedgerTransactionAppend({
+        store: serverDb,
+        type: "recharge",
+        reason,
+        idempotencyKey: txId,
+        txId,
+        entries: [
+          {
+            accountId: userAvailableCreditsAccountId(toUserId),
+            ownerUserId: toUserId,
+            delta: numericAmount,
+            startingBalance: currentBalance,
+            metadata: { reason },
+          },
+        ],
+        metadata: { legacyTxId: txId },
+        now,
+      });
+      if (ledgerAppend.status === "duplicate") {
+        logger.warn({ txId, toUserId }, "Duplicate ledger transaction detected");
+        return {
+          success: false,
+          error: "Duplicate transaction",
+          txId,
+        };
+      }
+      if (ledgerAppend.status !== "prepared") {
+        logger.warn(
+          { txId, toUserId, status: ledgerAppend.status },
+          "Ledger append rejected"
+        );
+        return { success: false, error: "Ledger append rejected", txId };
+      }
+      const newBalance =
+        ledgerAppend.transaction.entries.find(
+          (entry) => entry.accountId === userAvailableCreditsAccountId(toUserId)
+        )?.balanceAfter ?? currentBalance + numericAmount;
+      const userPatch: UserData = {
+        ...userData,
+        balance: newBalance,
+        balanceUpdatedAt: now,
+      };
+      if (shouldMarkFirstCoreAction(reason) && !Number(userData.firstCoreActionAt || 0)) {
+        userPatch.firstCoreActionAt = now;
+        userPatch.firstCoreActionReason = reason;
+        userPatch.coreFlowStage = CORE_FLOW_STAGES.firstCoreActionCompleted;
+        userPatch.coreFlowStageUpdatedAt = now;
+      }
+
+      const txRecord: TransactionRecord = {
+        txId,
+        toUserId,
+        type: "recharge",
+        amount: numericAmount,
+        reason,
+        timestamp: now,
+        status: "completed",
+      };
+
+      await withRetry(
+        async () => {
+          await serverDb.batch([
+            ...ledgerAppend.operations,
+            {
+              type: "put",
+              key: createTransactionKey.record(toUserId, txId),
+              value: txRecord,
+            },
+            {
+              type: "put",
+              key: txIndexKey,
+              value: {
+                toUserId,
+                timestamp: now,
+              },
+            },
+            {
+              type: "put",
+              key: userKey,
+              value: userPatch,
+            },
+          ]);
+        },
+        {
+          maxAttempts: 3,
+          delayMs: 1000,
+          backoff: true,
+        }
+      );
+
+      logger.info(
+        { toUserId, amount: numericAmount, newBalance, txId },
+        "Recharge completed successfully"
+      );
+      void notifyRechargeResultEmail({
+        userId: toUserId,
+        amount: numericAmount,
+        reason,
+        success: true,
+      });
+
+      return {
+        success: true,
+        balance: newBalance,
+        txId,
+      };
+    } catch (err) {
+      logger.error(
+        { err, toUserId, amount, txId },
+        "Error during recharge process"
+      );
+
+      try {
+        await withRetry(
+          async () => {
+            const txKey = createTransactionKey.record(toUserId, txId);
+            let txRecord: TransactionRecord | null = null;
+
+            try {
+              txRecord = await serverDb.get(txKey);
+            } catch (err) {
+              if (!(err instanceof Error && "notFound" in err)) {
+                throw err;
+              }
+            }
+
+            if (txRecord) {
+              await serverDb.put(txKey, {
+                ...txRecord,
+                status: "failed",
+              });
+            }
+          },
+          {
+            maxAttempts: 2,
+            delayMs: 500,
+            backoff: true,
+          }
+        );
+      } catch (updateError) {
+        logger.error(
+          { updateError, toUserId, txId },
+          "Failed to update transaction status"
+        );
+      }
+
+      void notifyRechargeResultEmail({
+        userId: toUserId,
+        amount: Number(amount),
+        reason,
+        success: false,
+        error: "Internal error during recharge",
+      });
+
+      return {
+        success: false,
+        error: "Internal error during recharge",
+        txId,
+      };
+    }
+  });
+}