nolo-cli 0.1.31 → 0.1.32

package/auth/server/creatorEarningCreditConversion.ts

@@ -1,523 +0,0 @@
-import { createHash } from "node:crypto";
-
-import { createTransactionKey, DB_PREFIX } from "../../database/keys";
-import { getServerAuthorityStore } from "../../database/server/db";
-import { writeStoreOps } from "../../database/server/storeBatchCompat";
-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>;
-};
-
-const createCreatorEarningCreditConversionStore = (
-  authorityStore = getServerAuthorityStore()
-): CreatorEarningCreditConversionStore => ({
-  get: (key) => authorityStore.get(key),
-  batch: (ops) => writeStoreOps(authorityStore, ops),
-});
-
-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 = createCreatorEarningCreditConversionStore(getServerAuthorityStore()),
-  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

@@ -1,165 +0,0 @@
-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,
-          },
-        },
-      ];
-    }
-  );
-}