nolo-cli 0.1.26 → 0.1.29

package/auth/server/creatorSettlementReport.ts

@@ -0,0 +1,442 @@
+import {
+  creatorEarningEntryKeyPrefix,
+  type CreatorEarningEntry,
+  type CreatorEarningStatus,
+} from "./creatorEarningsLedger";
+import {
+  creatorEarningStatusProjectionKeyPrefix,
+  creatorSettlementEventKeyPrefix,
+  type CreatorEarningStatusProjection,
+  type CreatorSettlementEvent,
+} from "./creatorSettlementLedger";
+import type { RevenueShareProductKind } from "./revenueShareLedger";
+import {
+  normalizeRevenueSplitPolicyRef,
+  type RevenueSplitPolicyRef,
+} from "./revenueSplitPolicy";
+
+export type CreatorSettlementReportStore = {
+  iterator: (options: {
+    gte?: string;
+    lte?: string;
+    reverse?: boolean;
+  }) => AsyncIterable<[string, unknown]>;
+};
+
+type CreditBuckets = {
+  pendingCredits: number;
+  availableCredits: number;
+  heldCredits: number;
+  paidCredits: number;
+  convertedToCreditCredits: number;
+};
+
+type SettlementCounts = {
+  count: number;
+  adjustmentCount: number;
+};
+
+export type CreatorSettlementReport = {
+  clusterId: string;
+  generatedAt: string;
+  sinceMs: number;
+  untilMs: number;
+  summary: CreditBuckets & {
+    entriesScanned: number;
+    entriesInWindow: number;
+    settlementEventsScanned: number;
+    settlementEventsInWindow: number;
+    transitionCount: number;
+    adjustmentCount: number;
+    creatorCount: number;
+  };
+  byCreator: Array<
+    CreditBuckets &
+      SettlementCounts & {
+        userId: string;
+        totalCredits: number;
+      }
+  >;
+  byProductKind: Array<
+    CreditBuckets &
+      SettlementCounts & {
+        productKind: RevenueShareProductKind;
+        totalCredits: number;
+      }
+  >;
+  byProvider: Array<
+    CreditBuckets &
+      SettlementCounts & {
+        provider: string;
+        totalCredits: number;
+      }
+  >;
+  byPolicy: Array<
+    RevenueSplitPolicyRef &
+      CreditBuckets &
+      SettlementCounts & {
+        totalCredits: number;
+      }
+  >;
+};
+
+const rangeEnd = (prefix: string) => `${prefix}\uffff`;
+
+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.createdAt === "number" &&
+  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" &&
+  typeof value.creatorUserId === "string" &&
+  isCreatorEarningStatus(value.currentStatus);
+
+const isSettlementEvent = (value: unknown): value is CreatorSettlementEvent =>
+  isObjectRecord(value) &&
+  typeof value.eventId === "string" &&
+  typeof value.clusterId === "string" &&
+  typeof value.createdAt === "number" &&
+  typeof value.creatorUserId === "string" &&
+  (value.type === "status_transition" || value.type === "adjustment") &&
+  typeof value.amountCredits === "number" &&
+  isObjectRecord(value.product) &&
+  typeof value.product.kind === "string";
+
+const roundCredits = (value: number) => Math.round(value * 1_000_000) / 1_000_000;
+
+const emptyBuckets = (): CreditBuckets => ({
+  pendingCredits: 0,
+  availableCredits: 0,
+  heldCredits: 0,
+  paidCredits: 0,
+  convertedToCreditCredits: 0,
+});
+
+const addStatusAmount = (
+  buckets: CreditBuckets,
+  status: CreatorEarningStatus,
+  amountCredits: number,
+  settlementMethod?: string
+) => {
+  if (status === "pending") buckets.pendingCredits += amountCredits;
+  if (status === "available") buckets.availableCredits += amountCredits;
+  if (status === "held") buckets.heldCredits += amountCredits;
+  if (status === "paid") {
+    buckets.paidCredits += amountCredits;
+    if (settlementMethod === "spendable_credit") {
+      buckets.convertedToCreditCredits += amountCredits;
+    }
+  }
+};
+
+const bucketTotal = (buckets: CreditBuckets) =>
+  buckets.pendingCredits +
+  buckets.availableCredits +
+  buckets.heldCredits +
+  buckets.paidCredits;
+
+const roundedBuckets = (buckets: CreditBuckets) => ({
+  pendingCredits: roundCredits(buckets.pendingCredits),
+  availableCredits: roundCredits(buckets.availableCredits),
+  heldCredits: roundCredits(buckets.heldCredits),
+  paidCredits: roundCredits(buckets.paidCredits),
+  convertedToCreditCredits: roundCredits(buckets.convertedToCreditCredits),
+});
+
+type Accumulator = CreditBuckets & SettlementCounts;
+
+const emptyAccumulator = (): Accumulator => ({
+  count: 0,
+  adjustmentCount: 0,
+  ...emptyBuckets(),
+});
+
+const addToAccumulator = ({
+  acc,
+  status,
+  amountCredits,
+  settlementMethod,
+  isAdjustment = false,
+}: {
+  acc: Accumulator;
+  status: CreatorEarningStatus;
+  amountCredits: number;
+  settlementMethod?: string;
+  isAdjustment?: boolean;
+}) => {
+  acc.count += 1;
+  if (isAdjustment) acc.adjustmentCount += 1;
+  addStatusAmount(acc, status, amountCredits, settlementMethod);
+};
+
+const policyKey = (policy: RevenueSplitPolicyRef) =>
+  `${policy.policyId}:${policy.policyVersion}:${policy.source}`;
+
+async function readStatusProjections({
+  store,
+  clusterId,
+}: {
+  store: CreatorSettlementReportStore;
+  clusterId: string;
+}) {
+  const projections = new Map<string, CreatorEarningStatusProjection>();
+  const prefix = creatorEarningStatusProjectionKeyPrefix(clusterId);
+  for await (const [, value] of store.iterator({
+    gte: prefix,
+    lte: rangeEnd(prefix),
+  })) {
+    if (isStatusProjection(value)) projections.set(value.entryId, value);
+  }
+  return projections;
+}
+
+export async function buildCreatorSettlementReport({
+  store,
+  clusterId,
+  sinceMs,
+  untilMs,
+  nowMs = Date.now(),
+}: {
+  store: CreatorSettlementReportStore;
+  clusterId: string;
+  sinceMs: number;
+  untilMs: number;
+  nowMs?: number;
+}): Promise<CreatorSettlementReport> {
+  const statusProjections = await readStatusProjections({ store, clusterId });
+  const latestTransitions = new Map<
+    string,
+    CreatorSettlementEvent & { type: "status_transition" }
+  >();
+  const adjustmentsInWindow: Array<
+    CreatorSettlementEvent & { type: "adjustment" }
+  > = [];
+  const summaryBuckets = emptyBuckets();
+  const byCreator = new Map<string, Accumulator>();
+  const byProductKind = new Map<RevenueShareProductKind, Accumulator>();
+  const byProvider = new Map<string, Accumulator>();
+  const byPolicy = new Map<string, RevenueSplitPolicyRef & Accumulator>();
+  const creatorIds = new Set<string>();
+
+  let entriesScanned = 0;
+  let entriesInWindow = 0;
+  let settlementEventsScanned = 0;
+  let settlementEventsInWindow = 0;
+  let transitionCount = 0;
+  let adjustmentCount = 0;
+
+  const settlementPrefix = creatorSettlementEventKeyPrefix(clusterId);
+  for await (const [, value] of store.iterator({
+    gte: settlementPrefix,
+    lte: rangeEnd(settlementPrefix),
+  })) {
+    if (!isSettlementEvent(value)) continue;
+    settlementEventsScanned += 1;
+    if (value.type === "status_transition" && value.createdAt <= untilMs) {
+      const previous = latestTransitions.get(value.entryId);
+      if (!previous || previous.createdAt < value.createdAt) {
+        latestTransitions.set(value.entryId, value);
+      }
+    }
+    if (value.createdAt < sinceMs || value.createdAt > untilMs) continue;
+    settlementEventsInWindow += 1;
+    if (value.type === "status_transition") {
+      transitionCount += 1;
+      continue;
+    }
+    adjustmentCount += 1;
+    adjustmentsInWindow.push(value);
+  }
+
+  const addRecord = ({
+    creatorUserId,
+    product,
+    splitPolicy,
+    status,
+    amountCredits,
+    settlementMethod,
+    isAdjustment = false,
+  }: {
+    creatorUserId: string;
+    product: CreatorEarningEntry["product"];
+    splitPolicy?: RevenueSplitPolicyRef;
+    status: CreatorEarningStatus;
+    amountCredits: number;
+    settlementMethod?: string;
+    isAdjustment?: boolean;
+  }) => {
+    creatorIds.add(creatorUserId);
+    addStatusAmount(summaryBuckets, status, amountCredits, settlementMethod);
+
+    const creatorAcc = byCreator.get(creatorUserId) ?? emptyAccumulator();
+    addToAccumulator({
+      acc: creatorAcc,
+      status,
+      amountCredits,
+      settlementMethod,
+      isAdjustment,
+    });
+    byCreator.set(creatorUserId, creatorAcc);
+
+    const productKind = product.kind;
+    const productAcc = byProductKind.get(productKind) ?? emptyAccumulator();
+    addToAccumulator({
+      acc: productAcc,
+      status,
+      amountCredits,
+      settlementMethod,
+      isAdjustment,
+    });
+    byProductKind.set(productKind, productAcc);
+
+    const provider = product.provider || "unknown";
+    const providerAcc = byProvider.get(provider) ?? emptyAccumulator();
+    addToAccumulator({
+      acc: providerAcc,
+      status,
+      amountCredits,
+      settlementMethod,
+      isAdjustment,
+    });
+    byProvider.set(provider, providerAcc);
+
+    const policy = normalizeRevenueSplitPolicyRef(splitPolicy);
+    const key = policyKey(policy);
+    const policyAcc =
+      byPolicy.get(key) ?? {
+        ...policy,
+        ...emptyAccumulator(),
+      };
+    addToAccumulator({
+      acc: policyAcc,
+      status,
+      amountCredits,
+      settlementMethod,
+      isAdjustment,
+    });
+    byPolicy.set(key, policyAcc);
+  };
+
+  const entryPrefix = creatorEarningEntryKeyPrefix(clusterId);
+  for await (const [, value] of store.iterator({
+    gte: entryPrefix,
+    lte: rangeEnd(entryPrefix),
+  })) {
+    if (!isCreatorEarningEntry(value)) continue;
+    entriesScanned += 1;
+    if (value.createdAt < sinceMs || value.createdAt > untilMs) continue;
+    entriesInWindow += 1;
+    const projection = statusProjections.get(value.entryId);
+    const status =
+      latestTransitions.get(value.entryId)?.toStatus ??
+      (projection && projection.updatedAt <= untilMs
+        ? projection.currentStatus
+        : value.status);
+    const settlementMethod =
+      latestTransitions.get(value.entryId)?.settlementMethod;
+    addRecord({
+      creatorUserId: value.creatorUserId,
+      product: value.product,
+      splitPolicy: value.splitPolicy,
+      status,
+      amountCredits: value.amountCredits,
+      settlementMethod,
+    });
+  }
+
+  for (const value of adjustmentsInWindow) {
+    addRecord({
+      creatorUserId: value.creatorUserId,
+      product: value.product,
+      splitPolicy: value.splitPolicy,
+      status: value.status,
+      amountCredits: value.amountCredits,
+      isAdjustment: true,
+    });
+  }
+
+  const mapAccumulator = <
+    T extends string,
+    K extends "userId" | "productKind" | "provider",
+  >(
+    entries: Array<[T, Accumulator]>,
+    keyName: K
+  ): Array<
+    Record<K, T> &
+      CreditBuckets &
+      SettlementCounts & {
+        totalCredits: number;
+      }
+  > =>
+    entries
+      .map(
+        ([key, acc]) =>
+          ({
+            [keyName]: key,
+            count: acc.count,
+            adjustmentCount: acc.adjustmentCount,
+            ...roundedBuckets(acc),
+            totalCredits: roundCredits(bucketTotal(acc)),
+          }) as Record<K, T> &
+            CreditBuckets &
+            SettlementCounts & { totalCredits: number }
+      )
+      .sort((a, b) => b.totalCredits - a.totalCredits || b.count - a.count);
+
+  return {
+    clusterId,
+    generatedAt: new Date(nowMs).toISOString(),
+    sinceMs,
+    untilMs,
+    summary: {
+      entriesScanned,
+      entriesInWindow,
+      settlementEventsScanned,
+      settlementEventsInWindow,
+      transitionCount,
+      adjustmentCount,
+      ...roundedBuckets(summaryBuckets),
+      creatorCount: creatorIds.size,
+    },
+    byCreator: mapAccumulator(Array.from(byCreator.entries()), "userId"),
+    byProductKind: mapAccumulator(
+      Array.from(byProductKind.entries()),
+      "productKind"
+    ),
+    byProvider: mapAccumulator(Array.from(byProvider.entries()), "provider"),
+    byPolicy: Array.from(byPolicy.values())
+      .map((acc) => ({
+        policyId: acc.policyId,
+        policyVersion: acc.policyVersion,
+        source: acc.source,
+        label: acc.label,
+        count: acc.count,
+        adjustmentCount: acc.adjustmentCount,
+        ...roundedBuckets(acc),
+        totalCredits: roundCredits(bucketTotal(acc)),
+      }))
+      .sort((a, b) => b.totalCredits - a.totalCredits || b.count - a.count),
+  };
+}

package/auth/server/creatorSplitConfig.ts

@@ -0,0 +1,191 @@
+import { nolotusId } from "../../core/init";
+
+import type { ProductSplitPolicy } from "./productEntitlements";
+import type { RevenueSplitPolicyRef } from "./revenueSplitPolicy";
+
+export type CreatorSplitConfigInput = {
+  policyId: string;
+  policyVersion?: number;
+  label?: string;
+  creatorUserId: string;
+  creatorShareRatio: number;
+  platformCostCredits?: number;
+  allowNegativePlatformNet?: boolean;
+};
+
+export type NormalizedCreatorSplitConfig = {
+  policyId: string;
+  policyVersion: number;
+  label: string;
+  creatorUserId: string;
+  creatorShareRatio: number;
+  platformCostCredits: number;
+  allowNegativePlatformNet: boolean;
+};
+
+export type CreatorSplitConfigResult =
+  | { status: "valid"; config: NormalizedCreatorSplitConfig }
+  | { status: "invalid"; error: string };
+
+export type BuildCreatorProductSplitPolicyResult =
+  | { status: "built"; policy: ProductSplitPolicy }
+  | { status: "invalid"; error: string };
+
+export type BuildCreatorTokenPayMapResult =
+  | {
+      status: "built";
+      grossCredits: number;
+      platformCostCredits: number;
+      creatorShareCredits: number;
+      platformNetCredits: number;
+      pay: Record<string, number>;
+      splitPolicy: RevenueSplitPolicyRef;
+    }
+  | { status: "invalid"; error: string };
+
+const roundCredits = (value: number) =>
+  Math.round(value * 1_000_000) / 1_000_000;
+
+const isNonEmptyString = (value: unknown): value is string =>
+  typeof value === "string" && value.trim().length > 0;
+
+const isRatio = (value: unknown): value is number =>
+  typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1;
+
+const isNonNegativeFinite = (value: unknown): value is number =>
+  typeof value === "number" && Number.isFinite(value) && value >= 0;
+
+const normalizePolicyVersion = (value: unknown) => {
+  if (typeof value !== "number" || !Number.isFinite(value)) return 1;
+  return Math.max(1, Math.trunc(value));
+};
+
+const explicitPolicyRef = (
+  config: NormalizedCreatorSplitConfig
+): RevenueSplitPolicyRef => ({
+  policyId: config.policyId,
+  policyVersion: config.policyVersion,
+  source: "explicit",
+  label: config.label,
+});
+
+export function normalizeCreatorSplitConfig(
+  input: CreatorSplitConfigInput
+): CreatorSplitConfigResult {
+  const policyId = input.policyId?.trim();
+  if (!isNonEmptyString(policyId)) {
+    return { status: "invalid", error: "Creator split policyId is required" };
+  }
+
+  const creatorUserId = input.creatorUserId?.trim();
+  if (!isNonEmptyString(creatorUserId)) {
+    return {
+      status: "invalid",
+      error: "Creator split creatorUserId is required",
+    };
+  }
+
+  if (!isRatio(input.creatorShareRatio)) {
+    return {
+      status: "invalid",
+      error: "Creator split ratio must be between 0 and 1",
+    };
+  }
+
+  const platformCostCredits = roundCredits(input.platformCostCredits ?? 0);
+  if (!isNonNegativeFinite(platformCostCredits)) {
+    return {
+      status: "invalid",
+      error: "Creator split platformCostCredits must be non-negative",
+    };
+  }
+
+  return {
+    status: "valid",
+    config: {
+      policyId,
+      policyVersion: normalizePolicyVersion(input.policyVersion),
+      creatorUserId,
+      creatorShareRatio: roundCredits(input.creatorShareRatio),
+      label: input.label?.trim() || policyId,
+      platformCostCredits,
+      allowNegativePlatformNet: input.allowNegativePlatformNet === true,
+    },
+  };
+}
+
+export function buildCreatorProductSplitPolicy(
+  input: CreatorSplitConfigInput
+): BuildCreatorProductSplitPolicyResult {
+  const normalized = normalizeCreatorSplitConfig(input);
+  if (normalized.status !== "valid") return normalized;
+
+  const { config } = normalized;
+  return {
+    status: "built",
+    policy: {
+      policyId: config.policyId,
+      policyVersion: config.policyVersion,
+      label: config.label,
+      creatorShareRatio: config.creatorShareRatio,
+      platformCostCredits: config.platformCostCredits,
+      allowNegativePlatformNet: config.allowNegativePlatformNet,
+    },
+  };
+}
+
+export function buildCreatorTokenPayMap({
+  config,
+  grossCredits,
+  platformCostCredits,
+  platformUserId = nolotusId,
+}: {
+  config: CreatorSplitConfigInput;
+  grossCredits: number;
+  platformCostCredits?: number;
+  platformUserId?: string;
+}): BuildCreatorTokenPayMapResult {
+  const normalized = normalizeCreatorSplitConfig(config);
+  if (normalized.status !== "valid") return normalized;
+
+  const gross = roundCredits(grossCredits);
+  if (!Number.isFinite(gross) || gross <= 0) {
+    return { status: "invalid", error: "Gross credits must be positive" };
+  }
+
+  const effectivePlatformCost = roundCredits(
+    platformCostCredits ?? normalized.config.platformCostCredits
+  );
+  if (!isNonNegativeFinite(effectivePlatformCost)) {
+    return { status: "invalid", error: "Platform cost must be non-negative" };
+  }
+
+  const creatorShareCredits = roundCredits(
+    gross * normalized.config.creatorShareRatio
+  );
+  const platformNetCredits = roundCredits(
+    gross - effectivePlatformCost - creatorShareCredits
+  );
+  if (platformNetCredits < 0 && !normalized.config.allowNegativePlatformNet) {
+    return {
+      status: "invalid",
+      error: "Creator split would make platform net negative",
+    };
+  }
+
+  const pay: Record<string, number> = {};
+  if (effectivePlatformCost > 0) pay[platformUserId] = effectivePlatformCost;
+  if (creatorShareCredits > 0) {
+    pay[normalized.config.creatorUserId] = creatorShareCredits;
+  }
+
+  return {
+    status: "built",
+    grossCredits: gross,
+    platformCostCredits: effectivePlatformCost,
+    creatorShareCredits,
+    platformNetCredits,
+    pay,
+    splitPolicy: explicitPolicyRef(normalized.config),
+  };
+}