nolo-cli 0.1.23 → 0.1.29

package/auth/server/creatorEarningCreditConversion.ts

@@ -0,0 +1,515 @@
+import { createHash } from "node:crypto";
+
+import { createTransactionKey, DB_PREFIX } from "../../database/keys";
+import serverDb from "../../database/server/db";
+import { ulid } from "ulid";
+import { balanceLockManager } from "./locks";
+import { withRetry } from "./utils";
+import {
+  creatorEarningEntryKey,
+  type CreatorEarningEntry,
+  type CreatorEarningStatus,
+} from "./creatorEarningsLedger";
+import {
+  creatorEarningStatusProjectionKey,
+  prepareCreatorEarningStatusTransition,
+  type CreatorEarningStatusProjection,
+} from "./creatorSettlementLedger";
+import {
+  creatorPendingEarningsAccountId,
+  getBillingLedgerRuntime,
+  prepareLedgerTransactionAppend,
+  userAvailableCreditsAccountId,
+  type BillingLedgerRuntime,
+  type LedgerStoreOperation,
+} from "./ledger";
+
+type StoreOperation = { type: "put"; key: string; value: unknown };
+
+export type CreatorEarningCreditConversionStore = {
+  get: (key: string) => Promise<unknown | null>;
+  batch: (ops: StoreOperation[]) => Promise<void>;
+};
+
+type ConversionRecord = {
+  kind: "creator_earning_credit_conversion";
+  clusterId: string;
+  creatorUserId: string;
+  entryId: string;
+  amountCredits: number;
+  balanceAfter: number;
+  ledgerTxId: string;
+  settlementEventId: string;
+  createdAt: number;
+};
+
+export type CreatorEarningCreditConversionResult =
+  | {
+      success: true;
+      status: "converted" | "duplicate";
+      creatorUserId: string;
+      entryId: string;
+      amountCredits: number;
+      balance: number;
+      txId: string;
+      settlementEventId: string;
+    }
+  | {
+      success: false;
+      status:
+        | "not_leader"
+        | "not_balance_authority"
+        | "earning_not_found"
+        | "creator_mismatch"
+        | "cluster_mismatch"
+        | "invalid_amount"
+        | "not_available"
+        | "user_not_found"
+        | "invalid_user_balance"
+        | "duplicate_transaction"
+        | "insufficient_earnings_balance"
+        | "ledger_rejected"
+        | "settlement_rejected"
+        | "failed";
+      error: string;
+      creatorUserId: string;
+      entryId: string;
+      currentStatus?: CreatorEarningStatus;
+      balance?: number;
+      txId?: string;
+    };
+
+const sha256 = (value: string) =>
+  createHash("sha256").update(value).digest("hex");
+
+const safeKeyPart = (value: string) => sha256(value).slice(0, 32);
+
+export const creatorEarningCreditConversionKey = (
+  clusterId: string,
+  entryId: string
+) => `creator-earning-credit-conversion-${clusterId}-${safeKeyPart(entryId)}`;
+
+const roundCredits = (value: number) => Math.round(value * 1_000_000) / 1_000_000;
+
+const getMaybe = async <T>(
+  store: Pick<CreatorEarningCreditConversionStore, "get">,
+  key: string
+): Promise<T | null> => {
+  return (await store.get(key).catch((error) => {
+    if (error instanceof Error && "notFound" in error) return null;
+    throw error;
+  })) as T | null;
+};
+
+const isObjectRecord = (value: unknown): value is Record<string, unknown> =>
+  !!value && typeof value === "object" && !Array.isArray(value);
+
+const isCreatorEarningStatus = (
+  value: unknown
+): value is CreatorEarningStatus =>
+  value === "pending" ||
+  value === "available" ||
+  value === "held" ||
+  value === "paid";
+
+const isCreatorEarningEntry = (value: unknown): value is CreatorEarningEntry =>
+  isObjectRecord(value) &&
+  typeof value.entryId === "string" &&
+  typeof value.clusterId === "string" &&
+  typeof value.creatorUserId === "string" &&
+  typeof value.amountCredits === "number" &&
+  isCreatorEarningStatus(value.status) &&
+  isObjectRecord(value.product) &&
+  typeof value.product.kind === "string";
+
+const isStatusProjection = (
+  value: unknown
+): value is CreatorEarningStatusProjection =>
+  isObjectRecord(value) &&
+  typeof value.entryId === "string" &&
+  typeof value.clusterId === "string" &&
+  isCreatorEarningStatus(value.currentStatus);
+
+const isConversionRecord = (value: unknown): value is ConversionRecord =>
+  isObjectRecord(value) &&
+  value.kind === "creator_earning_credit_conversion" &&
+  typeof value.clusterId === "string" &&
+  typeof value.creatorUserId === "string" &&
+  typeof value.entryId === "string" &&
+  typeof value.amountCredits === "number" &&
+  typeof value.balanceAfter === "number" &&
+  typeof value.ledgerTxId === "string" &&
+  typeof value.settlementEventId === "string";
+
+const conversionIdempotencyKey = (clusterId: string, entryId: string) =>
+  `creator_earning_credit_conversion:${clusterId}:${entryId}`;
+
+const defaultTxId = (clusterId: string, entryId: string) =>
+  `creator-earning-credit-${clusterId}-${safeKeyPart(entryId)}`;
+
+export async function convertCreatorEarningToCredits({
+  store = serverDb,
+  runtime = getBillingLedgerRuntime(),
+  creatorUserId,
+  entryId,
+  reviewedByUserId,
+  reason,
+  txId,
+  settlementEventId,
+  nowMs = Date.now(),
+}: {
+  store?: CreatorEarningCreditConversionStore;
+  runtime?: BillingLedgerRuntime;
+  creatorUserId: string;
+  entryId: string;
+  reviewedByUserId?: string;
+  reason?: string;
+  txId?: string;
+  settlementEventId?: string;
+  nowMs?: number;
+}): Promise<CreatorEarningCreditConversionResult> {
+  const effectiveTxId = txId ?? defaultTxId(runtime.clusterId, entryId);
+  const conversionKey = creatorEarningCreditConversionKey(
+    runtime.clusterId,
+    entryId
+  );
+
+  if (runtime.role !== "leader") {
+    return {
+      success: false,
+      status: "not_leader",
+      creatorUserId,
+      entryId,
+      txId: effectiveTxId,
+      error: `Creator earning credit conversion requires leader role, got ${runtime.role}`,
+    };
+  }
+  if (!runtime.isAuthoritativeBalance) {
+    return {
+      success: false,
+      status: "not_balance_authority",
+      creatorUserId,
+      entryId,
+      txId: effectiveTxId,
+      error: `Creator earning credit conversion requires balance authority cluster ${runtime.balanceAuthorityClusterId}`,
+    };
+  }
+
+  const lock = balanceLockManager.getLock(creatorUserId);
+  return await lock.runExclusive(async () => {
+    try {
+      const existingConversion = await getMaybe<unknown>(store, conversionKey);
+      if (isConversionRecord(existingConversion)) {
+        if (existingConversion.creatorUserId !== creatorUserId) {
+          return {
+            success: false,
+            status: "creator_mismatch",
+            creatorUserId,
+            entryId,
+            txId: existingConversion.ledgerTxId,
+            error: `Conversion belongs to creator ${existingConversion.creatorUserId}`,
+          };
+        }
+        return {
+          success: true,
+          status: "duplicate",
+          creatorUserId,
+          entryId,
+          amountCredits: existingConversion.amountCredits,
+          balance: existingConversion.balanceAfter,
+          txId: existingConversion.ledgerTxId,
+          settlementEventId: existingConversion.settlementEventId,
+        };
+      }
+
+      const entry = await getMaybe<unknown>(
+        store,
+        creatorEarningEntryKey(runtime.clusterId, entryId)
+      );
+      if (!isCreatorEarningEntry(entry)) {
+        return {
+          success: false,
+          status: "earning_not_found",
+          creatorUserId,
+          entryId,
+          txId: effectiveTxId,
+          error: "Creator earning entry not found",
+        };
+      }
+      if (entry.creatorUserId !== creatorUserId) {
+        return {
+          success: false,
+          status: "creator_mismatch",
+          creatorUserId,
+          entryId,
+          txId: effectiveTxId,
+          error: `Earning belongs to creator ${entry.creatorUserId}`,
+        };
+      }
+      if (entry.clusterId !== runtime.clusterId) {
+        return {
+          success: false,
+          status: "cluster_mismatch",
+          creatorUserId,
+          entryId,
+          txId: effectiveTxId,
+          error: `Earning belongs to cluster ${entry.clusterId}`,
+        };
+      }
+
+      const amountCredits = roundCredits(entry.amountCredits);
+      if (!Number.isFinite(amountCredits) || amountCredits <= 0) {
+        return {
+          success: false,
+          status: "invalid_amount",
+          creatorUserId,
+          entryId,
+          txId: effectiveTxId,
+          error: `Invalid creator earning amount: ${entry.amountCredits}`,
+        };
+      }
+
+      const projection = await getMaybe<unknown>(
+        store,
+        creatorEarningStatusProjectionKey(runtime.clusterId, entry.entryId)
+      );
+      const currentStatus =
+        isStatusProjection(projection) && projection.entryId === entry.entryId
+          ? projection.currentStatus
+          : entry.status;
+      if (currentStatus !== "available") {
+        return {
+          success: false,
+          status: "not_available",
+          creatorUserId,
+          entryId,
+          currentStatus,
+          txId: effectiveTxId,
+          error: `Creator earning must be available before conversion, got ${currentStatus}`,
+        };
+      }
+
+      const userKey = `${DB_PREFIX.USER}${creatorUserId}`;
+      const userData = await getMaybe<Record<string, unknown>>(store, userKey);
+      if (!userData) {
+        return {
+          success: false,
+          status: "user_not_found",
+          creatorUserId,
+          entryId,
+          txId: effectiveTxId,
+          error: "Creator user not found",
+        };
+      }
+      if (typeof userData.balance !== "number") {
+        return {
+          success: false,
+          status: "invalid_user_balance",
+          creatorUserId,
+          entryId,
+          txId: effectiveTxId,
+          error: "Creator user balance invalid",
+        };
+      }
+
+      const txIndexKey = createTransactionKey.index(effectiveTxId);
+      const existingTx = await getMaybe<unknown>(store, txIndexKey);
+      if (existingTx) {
+        return {
+          success: false,
+          status: "duplicate_transaction",
+          creatorUserId,
+          entryId,
+          txId: effectiveTxId,
+          error: "Duplicate transaction id without conversion record",
+        };
+      }
+
+      const idempotencyKey = conversionIdempotencyKey(
+        runtime.clusterId,
+        entry.entryId
+      );
+      const effectiveSettlementEventId =
+        settlementEventId ?? `creator-credit-settlement-${ulid(nowMs)}`;
+      const conversionReason =
+        reason ?? `creator_earning_credit_conversion:${entry.entryId}`;
+      const earningsAccountId = creatorPendingEarningsAccountId(creatorUserId);
+      const userCreditsAccountId = userAvailableCreditsAccountId(creatorUserId);
+
+      const ledgerAppend = await prepareLedgerTransactionAppend({
+        store,
+        runtime,
+        txId: effectiveTxId,
+        type: "adjustment",
+        reason: conversionReason,
+        idempotencyKey,
+        entries: [
+          {
+            accountId: earningsAccountId,
+            ownerUserId: creatorUserId,
+            delta: -amountCredits,
+            metadata: {
+              role: "creator_earning_liability_debit",
+              entryId: entry.entryId,
+            },
+          },
+          {
+            accountId: userCreditsAccountId,
+            ownerUserId: creatorUserId,
+            delta: amountCredits,
+            startingBalance: userData.balance,
+            metadata: {
+              role: "creator_spendable_credit",
+              entryId: entry.entryId,
+            },
+          },
+        ],
+        metadata: {
+          kind: "creator_earning_credit_conversion",
+          creatorUserId,
+          entryId: entry.entryId,
+          creatorEarningHash: entry.hash,
+          amountCredits,
+          settlementMethod: "spendable_credit",
+        },
+        now: nowMs,
+      });
+
+      if (ledgerAppend.status === "insufficient_funds") {
+        return {
+          success: false,
+          status: "insufficient_earnings_balance",
+          creatorUserId,
+          entryId,
+          txId: effectiveTxId,
+          balance: ledgerAppend.balance,
+          error: `Creator earnings account has ${ledgerAppend.balance}, needs ${amountCredits}`,
+        };
+      }
+      if (ledgerAppend.status !== "prepared") {
+        return {
+          success: false,
+          status: "ledger_rejected",
+          creatorUserId,
+          entryId,
+          txId: effectiveTxId,
+          error: `Ledger append rejected: ${ledgerAppend.status}`,
+        };
+      }
+
+      const settlement = await prepareCreatorEarningStatusTransition({
+        store,
+        runtime,
+        entry,
+        toStatus: "paid",
+        idempotencyKey,
+        reason: conversionReason,
+        reviewedByUserId,
+        settlementMethod: "spendable_credit",
+        settlementMetadata: {
+          ledgerTxId: effectiveTxId,
+          amountCredits,
+        },
+        eventId: effectiveSettlementEventId,
+        nowMs,
+      });
+      if (settlement.status !== "prepared") {
+        return {
+          success: false,
+          status: "settlement_rejected",
+          creatorUserId,
+          entryId,
+          currentStatus:
+            settlement.status === "invalid_transition"
+              ? settlement.fromStatus
+              : currentStatus,
+          txId: effectiveTxId,
+          error: `Creator settlement transition rejected: ${settlement.status}`,
+        };
+      }
+
+      const balanceAfter =
+        ledgerAppend.transaction.entries.find(
+          (entryItem) => entryItem.accountId === userCreditsAccountId
+        )?.balanceAfter ?? roundCredits(userData.balance + amountCredits);
+      const conversionRecord: ConversionRecord = {
+        kind: "creator_earning_credit_conversion",
+        clusterId: runtime.clusterId,
+        creatorUserId,
+        entryId: entry.entryId,
+        amountCredits,
+        balanceAfter,
+        ledgerTxId: effectiveTxId,
+        settlementEventId: settlement.event.eventId,
+        createdAt: nowMs,
+      };
+
+      await withRetry(
+        async () => {
+          await store.batch([
+            ...(ledgerAppend.operations as LedgerStoreOperation[]),
+            ...settlement.operations,
+            {
+              type: "put",
+              key: createTransactionKey.record(creatorUserId, effectiveTxId),
+              value: {
+                txId: effectiveTxId,
+                userId: creatorUserId,
+                type: "adjustment",
+                amount: amountCredits,
+                reason: conversionReason,
+                timestamp: nowMs,
+                status: "completed",
+                metadata: {
+                  kind: "creator_earning_credit_conversion",
+                  entryId: entry.entryId,
+                  settlementEventId: settlement.event.eventId,
+                },
+              },
+            },
+            {
+              type: "put",
+              key: txIndexKey,
+              value: { userId: creatorUserId, timestamp: nowMs },
+            },
+            {
+              type: "put",
+              key: userKey,
+              value: {
+                ...userData,
+                balance: balanceAfter,
+                balanceUpdatedAt: nowMs,
+              },
+            },
+            {
+              type: "put",
+              key: conversionKey,
+              value: conversionRecord,
+            },
+          ]);
+        },
+        { maxAttempts: 3, delayMs: 1000, backoff: true }
+      );
+
+      return {
+        success: true,
+        status: "converted",
+        creatorUserId,
+        entryId: entry.entryId,
+        amountCredits,
+        balance: balanceAfter,
+        txId: effectiveTxId,
+        settlementEventId: settlement.event.eventId,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        status: "failed",
+        creatorUserId,
+        entryId,
+        txId: effectiveTxId,
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  });
+}

package/auth/server/creatorEarningsLedger.ts

@@ -0,0 +1,165 @@
+import { createHash } from "node:crypto";
+
+import type { BillingLedgerClusterId } from "./ledger";
+import type {
+  RevenueShareEvent,
+  RevenueShareProductKind,
+  RevenueShareStoreOperation,
+} from "./revenueShareLedger";
+import type { RevenueSplitPolicyRef } from "./revenueSplitPolicy";
+
+export type CreatorEarningStatus = "pending" | "available" | "held" | "paid";
+
+export type CreatorEarningEntry = {
+  entryId: string;
+  idempotencyKey: string;
+  clusterId: BillingLedgerClusterId;
+  nodeId: string;
+  createdAt: number;
+  creatorUserId: string;
+  accountId: string;
+  status: CreatorEarningStatus;
+  amountCredits: number;
+  source: {
+    kind: "revenue_share";
+    revenueShareEventId: string;
+    revenueShareEventHash: string;
+    revenueShareIdempotencyKey: string;
+    billingTxId?: string;
+    tokenKey?: string;
+  };
+  payerUserId?: string;
+  product: {
+    kind: RevenueShareProductKind;
+    id: string;
+    model?: string;
+    provider?: string;
+  };
+  splitPolicy?: RevenueSplitPolicyRef;
+  hash: string;
+};
+
+const stableJson = (value: unknown): string => {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableJson(item)).join(",")}]`;
+  }
+  return `{${Object.entries(value as Record<string, unknown>)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`)
+    .join(",")}}`;
+};
+
+const sha256 = (value: string) =>
+  createHash("sha256").update(value).digest("hex");
+
+const safeKeyPart = (value: string) => sha256(value).slice(0, 32);
+
+const roundCredits = (value: number) => Math.round(value * 1_000_000) / 1_000_000;
+
+const computeCreatorEarningEntryHash = (
+  entry: Omit<CreatorEarningEntry, "hash">
+) =>
+  sha256(
+    stableJson({
+      version: 1,
+      entry,
+    })
+  );
+
+export const creatorEarningEntryKeyPrefix = (
+  clusterId: BillingLedgerClusterId
+) => `creator-earning-entry-${clusterId}-`;
+
+export const creatorEarningEntryKey = (
+  clusterId: BillingLedgerClusterId,
+  entryId: string
+) => `${creatorEarningEntryKeyPrefix(clusterId)}${entryId}`;
+
+export const creatorEarningIdempotencyKey = (
+  clusterId: BillingLedgerClusterId,
+  idempotencyKey: string
+) => `creator-earning-idem-${clusterId}-${safeKeyPart(idempotencyKey)}`;
+
+export function buildCreatorEarningEntriesForRevenueShareEvent(
+  event: RevenueShareEvent
+): CreatorEarningEntry[] {
+  const entries: CreatorEarningEntry[] = [];
+  event.shares.forEach((share, index) => {
+    if (
+      share.role !== "creator_share" ||
+      !share.userId ||
+      !Number.isFinite(share.amountCredits) ||
+      share.amountCredits <= 0
+    ) {
+      return;
+    }
+
+    const idempotencyKey = `revenue-share:${event.eventId}:creator:${share.userId}:${index}`;
+    const entryBase: Omit<CreatorEarningEntry, "hash"> = {
+      entryId: `${event.eventId}-${index}`,
+      idempotencyKey,
+      clusterId: event.clusterId,
+      nodeId: event.nodeId,
+      createdAt: event.createdAt,
+      creatorUserId: share.userId,
+      accountId: share.accountId,
+      status: "pending",
+      amountCredits: roundCredits(share.amountCredits),
+      source: {
+        kind: "revenue_share",
+        revenueShareEventId: event.eventId,
+        revenueShareEventHash: event.hash,
+        revenueShareIdempotencyKey: event.idempotencyKey,
+        ...(event.source.billingTxId
+          ? { billingTxId: event.source.billingTxId }
+          : {}),
+        ...(event.source.kind === "token_usage" && event.source.tokenKey
+          ? { tokenKey: event.source.tokenKey }
+          : {}),
+      },
+      ...(event.payerUserId ? { payerUserId: event.payerUserId } : {}),
+      product: {
+        kind: event.product.kind,
+        id: event.product.id,
+        ...(event.product.model ? { model: event.product.model } : {}),
+        ...(event.product.provider ? { provider: event.product.provider } : {}),
+      },
+      ...(event.splitPolicy ? { splitPolicy: event.splitPolicy } : {}),
+    };
+
+    entries.push({
+      ...entryBase,
+      hash: computeCreatorEarningEntryHash(entryBase),
+    });
+  });
+  return entries;
+}
+
+export function buildCreatorEarningStoreOps(
+  event: RevenueShareEvent
+): RevenueShareStoreOperation[] {
+  return buildCreatorEarningEntriesForRevenueShareEvent(event).flatMap(
+    (entry) => {
+      const entryKey = creatorEarningEntryKey(entry.clusterId, entry.entryId);
+      return [
+        {
+          type: "put" as const,
+          key: entryKey,
+          value: entry,
+        },
+        {
+          type: "put" as const,
+          key: creatorEarningIdempotencyKey(entry.clusterId, entry.idempotencyKey),
+          value: {
+            entryKey,
+            entry,
+            createdAt: entry.createdAt,
+          },
+        },
+      ];
+    }
+  );
+}