nolo-cli 0.1.23 → 0.1.29

package/auth/server/revenueShareLedger.ts

@@ -0,0 +1,389 @@
+import { createHash } from "node:crypto";
+import { ulid } from "ulid";
+
+import { nolotusId } from "../../core/init";
+import { buildCreatorEarningStoreOps } from "./creatorEarningsLedger";
+import {
+  getBillingLedgerRuntime,
+  type BillingLedgerClusterId,
+  type BillingLedgerRole,
+} from "./ledger";
+import {
+  resolveRevenueSplitPolicy,
+  type RevenueSplitPolicyRef,
+} from "./revenueSplitPolicy";
+
+export type RevenueShareRuntime = {
+  clusterId: BillingLedgerClusterId;
+  nodeId: string;
+  role?: BillingLedgerRole;
+};
+
+export type RevenueShareStoreOperation = {
+  type: "put";
+  key: string;
+  value: unknown;
+};
+
+export type RevenueShareStore = {
+  get: (key: string) => Promise<unknown | null>;
+  batch: (ops: RevenueShareStoreOperation[]) => Promise<void>;
+};
+
+export type RevenueShareProductKind =
+  | "doc"
+  | "agent"
+  | "tool"
+  | "license"
+  | "agent_usage"
+  | "builtin_usage"
+  | "tool_usage"
+  | "llm_usage";
+
+export type RevenueShareLeg = {
+  role: "platform_cost" | "creator_share" | "platform_net";
+  accountId: string;
+  userId?: string;
+  amountCredits: number;
+};
+
+export type RevenueShareEventSource =
+  | {
+      kind: "token_usage";
+      tokenKey: string;
+      billingTxId?: string;
+      dialogId?: string;
+      cybotId?: string;
+    }
+  | {
+      kind: "product_purchase";
+      productId: string;
+      purchaseId: string;
+      billingTxId?: string;
+    };
+
+export type RevenueShareEvent = {
+  eventId: string;
+  idempotencyKey: string;
+  clusterId: BillingLedgerClusterId;
+  nodeId: string;
+  createdAt: number;
+  source: RevenueShareEventSource;
+  payerUserId?: string;
+  product: {
+    kind: RevenueShareProductKind;
+    id: string;
+    model?: string;
+    provider?: string;
+  };
+  splitPolicy?: RevenueSplitPolicyRef;
+  grossCredits: number;
+  platformCostCredits: number;
+  creatorShareCredits: number;
+  platformNetCredits: number;
+  shares: RevenueShareLeg[];
+  hash: string;
+};
+
+export type TokenRevenueShareRecord = {
+  type?: string;
+  userId?: string;
+  cybotId?: string;
+  dialogId?: string;
+  model?: string;
+  provider?: string;
+  cost?: number;
+  pay?: unknown;
+  revenueSplitPolicy?: unknown;
+  splitPolicy?: unknown;
+};
+
+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 isFinitePositive = (value: unknown): value is number =>
+  typeof value === "number" && Number.isFinite(value) && value > 0;
+
+const normalizePayMap = (value: unknown) => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return new Map<string, number>();
+  }
+  const pay = new Map<string, number>();
+  for (const [userId, amount] of Object.entries(value)) {
+    if (typeof amount === "number" && Number.isFinite(amount) && amount > 0) {
+      pay.set(userId, roundCredits(amount));
+    }
+  }
+  return pay;
+};
+
+const resolveProductKind = (record: TokenRevenueShareRecord): RevenueShareProductKind => {
+  const cybotId = record.cybotId || "";
+  if (cybotId === "external_tool") return "tool_usage";
+  if (cybotId.startsWith("builtin-")) return "builtin_usage";
+  if (cybotId.startsWith("agent-") || cybotId.startsWith("cybot-")) {
+    return "agent_usage";
+  }
+  return "llm_usage";
+};
+
+export const revenueShareEventKeyPrefix = (
+  clusterId: BillingLedgerClusterId
+) => `revenue-share-event-${clusterId}-`;
+
+export const revenueShareEventKey = (
+  clusterId: BillingLedgerClusterId,
+  eventId: string
+) => `${revenueShareEventKeyPrefix(clusterId)}${eventId}`;
+
+export const revenueShareIdempotencyKey = (
+  clusterId: BillingLedgerClusterId,
+  idempotencyKey: string
+) => `revenue-share-idem-${clusterId}-${safeKeyPart(idempotencyKey)}`;
+
+const computeRevenueShareEventHash = (
+  event: Omit<RevenueShareEvent, "hash">
+) =>
+  sha256(
+    stableJson({
+      version: 1,
+      event,
+    })
+  );
+
+export type RecordRevenueShareResult =
+  | { status: "recorded"; event: RevenueShareEvent }
+  | { status: "duplicate"; event: RevenueShareEvent }
+  | { status: "skipped"; reason: string };
+
+export type TokenRevenueShareProjectionResult =
+  | {
+      status: "projected";
+      event: RevenueShareEvent;
+      operations: RevenueShareStoreOperation[];
+    }
+  | { status: "skipped"; reason: string };
+
+export function buildRevenueShareProjectionOps({
+  runtime,
+  idempotencyKey,
+  eventId,
+  createdAt,
+  source,
+  payerUserId,
+  product,
+  splitPolicy,
+  grossCredits,
+  platformCostCredits,
+  creatorShareCredits,
+  platformNetCredits,
+  shares,
+}: {
+  runtime: RevenueShareRuntime;
+  idempotencyKey: string;
+  eventId?: string;
+  createdAt: number;
+  source: RevenueShareEventSource;
+  payerUserId?: string;
+  product: RevenueShareEvent["product"];
+  splitPolicy?: RevenueSplitPolicyRef;
+  grossCredits: number;
+  platformCostCredits: number;
+  creatorShareCredits: number;
+  platformNetCredits: number;
+  shares: RevenueShareLeg[];
+}): { event: RevenueShareEvent; operations: RevenueShareStoreOperation[] } {
+  const eventBase: Omit<RevenueShareEvent, "hash"> = {
+    eventId: eventId ?? ulid(createdAt),
+    idempotencyKey,
+    clusterId: runtime.clusterId,
+    nodeId: runtime.nodeId,
+    createdAt,
+    source,
+    ...(payerUserId ? { payerUserId } : {}),
+    product,
+    ...(splitPolicy ? { splitPolicy } : {}),
+    grossCredits: roundCredits(grossCredits),
+    platformCostCredits: roundCredits(platformCostCredits),
+    creatorShareCredits: roundCredits(creatorShareCredits),
+    platformNetCredits: roundCredits(platformNetCredits),
+    shares,
+  };
+  const event: RevenueShareEvent = {
+    ...eventBase,
+    hash: computeRevenueShareEventHash(eventBase),
+  };
+  const eventKey = revenueShareEventKey(runtime.clusterId, event.eventId);
+
+  return {
+    event,
+    operations: [
+      {
+        type: "put",
+        key: eventKey,
+        value: event,
+      },
+      {
+        type: "put",
+        key: revenueShareIdempotencyKey(runtime.clusterId, idempotencyKey),
+        value: {
+          eventKey,
+          event,
+          createdAt,
+        },
+      },
+      ...buildCreatorEarningStoreOps(event),
+    ],
+  };
+}
+
+export function buildTokenRevenueShareProjectionOps({
+  runtime,
+  tokenKey,
+  tokenRecord,
+  billingTxId,
+  nowMs,
+}: {
+  runtime: RevenueShareRuntime;
+  tokenKey: string;
+  tokenRecord: TokenRevenueShareRecord;
+  billingTxId?: string;
+  nowMs: number;
+}): TokenRevenueShareProjectionResult {
+  if (runtime.role && runtime.role !== "leader") {
+    return { status: "skipped", reason: "not_leader" };
+  }
+  if (!isFinitePositive(tokenRecord.cost)) {
+    return { status: "skipped", reason: "zero_cost" };
+  }
+
+  const grossCredits = roundCredits(tokenRecord.cost);
+  const pay = normalizePayMap(tokenRecord.pay);
+  const splitPolicy = resolveRevenueSplitPolicy(tokenRecord, nolotusId);
+  const productKind = resolveProductKind(tokenRecord);
+  const platformCostCredits = roundCredits(
+    pay.get(nolotusId) ?? (productKind === "tool_usage" ? grossCredits : 0)
+  );
+  const creatorShares = Array.from(pay.entries()).filter(
+    ([userId]) => userId !== nolotusId
+  );
+  const creatorShareCredits = roundCredits(
+    creatorShares.reduce((sum, [, amount]) => sum + amount, 0)
+  );
+  const platformNetCredits = roundCredits(
+    grossCredits - platformCostCredits - creatorShareCredits
+  );
+
+  const shares: RevenueShareLeg[] = [];
+  if (platformCostCredits > 0) {
+    shares.push({
+      role: "platform_cost",
+      accountId: `platform:${nolotusId}:provider-cost`,
+      userId: nolotusId,
+      amountCredits: platformCostCredits,
+    });
+  }
+  for (const [userId, amountCredits] of creatorShares) {
+    shares.push({
+      role: "creator_share",
+      accountId: `creator:${userId}:earnings:pending`,
+      userId,
+      amountCredits,
+    });
+  }
+  if (platformNetCredits !== 0) {
+    shares.push({
+      role: "platform_net",
+      accountId: `platform:${nolotusId}:net-revenue`,
+      userId: nolotusId,
+      amountCredits: platformNetCredits,
+    });
+  }
+
+  const projection = buildRevenueShareProjectionOps({
+    runtime,
+    idempotencyKey: `token:${tokenKey}`,
+    createdAt: nowMs,
+    source: {
+      kind: "token_usage",
+      tokenKey,
+      ...(billingTxId ? { billingTxId } : {}),
+      ...(tokenRecord.dialogId ? { dialogId: tokenRecord.dialogId } : {}),
+      ...(tokenRecord.cybotId ? { cybotId: tokenRecord.cybotId } : {}),
+    },
+    payerUserId: tokenRecord.userId,
+    product: {
+      kind: productKind,
+      id: tokenRecord.cybotId || "unknown",
+      ...(tokenRecord.model ? { model: tokenRecord.model } : {}),
+      ...(tokenRecord.provider ? { provider: tokenRecord.provider } : {}),
+    },
+    splitPolicy,
+    grossCredits,
+    platformCostCredits,
+    creatorShareCredits,
+    platformNetCredits,
+    shares,
+  });
+
+  return {
+    status: "projected",
+    event: projection.event,
+    operations: projection.operations,
+  };
+}
+
+export async function recordTokenRevenueShare({
+  store,
+  runtime = getBillingLedgerRuntime(),
+  tokenKey,
+  tokenRecord,
+  billingTxId,
+  nowMs = Date.now(),
+}: {
+  store: RevenueShareStore;
+  runtime?: RevenueShareRuntime;
+  tokenKey: string;
+  tokenRecord: TokenRevenueShareRecord;
+  billingTxId?: string;
+  nowMs?: number;
+}): Promise<RecordRevenueShareResult> {
+  const idempotencyKey = `token:${tokenKey}`;
+  const idemKey = revenueShareIdempotencyKey(runtime.clusterId, idempotencyKey);
+  const existing = (await store.get(idemKey).catch(() => null)) as
+    | { event?: RevenueShareEvent }
+    | null;
+  if (existing?.event) {
+    return { status: "duplicate", event: existing.event };
+  }
+
+  const projection = buildTokenRevenueShareProjectionOps({
+    runtime,
+    tokenKey,
+    tokenRecord,
+    billingTxId,
+    nowMs,
+  });
+  if (projection.status !== "projected") return projection;
+
+  await store.batch(projection.operations);
+
+  return { status: "recorded", event: projection.event };
+}

package/auth/server/revenueShareReport.ts

@@ -0,0 +1,258 @@
+import {
+  revenueShareEventKeyPrefix,
+  type RevenueShareEvent,
+  type RevenueShareProductKind,
+} from "./revenueShareLedger";
+import {
+  normalizeRevenueSplitPolicyRef,
+  type RevenueSplitPolicyRef,
+} from "./revenueSplitPolicy";
+
+export type RevenueShareReportStore = {
+  iterator: (options: {
+    gte?: string;
+    lte?: string;
+    reverse?: boolean;
+  }) => AsyncIterable<[string, unknown]>;
+};
+
+export type RevenueShareReport = {
+  clusterId: string;
+  generatedAt: string;
+  sinceMs: number;
+  untilMs: number;
+  summary: {
+    eventsScanned: number;
+    eventsInWindow: number;
+    grossCredits: number;
+    platformCostCredits: number;
+    creatorShareCredits: number;
+    platformNetCredits: number;
+    payerCount: number;
+    creatorCount: number;
+  };
+  byCreator: Array<{
+    userId: string;
+    count: number;
+    amountCredits: number;
+    grossCredits: number;
+  }>;
+  byProductKind: Array<{
+    productKind: RevenueShareProductKind;
+    count: number;
+    grossCredits: number;
+    creatorShareCredits: number;
+    platformNetCredits: number;
+  }>;
+  byProvider: Array<{
+    provider: string;
+    count: number;
+    grossCredits: number;
+    platformCostCredits: number;
+  }>;
+  byPolicy: Array<
+    RevenueSplitPolicyRef & {
+      count: number;
+      grossCredits: number;
+      creatorShareCredits: number;
+      platformNetCredits: number;
+    }
+  >;
+};
+
+const rangeEnd = (prefix: string) => `${prefix}\uffff`;
+
+const isObjectRecord = (value: unknown): value is Record<string, unknown> =>
+  !!value && typeof value === "object" && !Array.isArray(value);
+
+const isRevenueShareEvent = (value: unknown): value is RevenueShareEvent =>
+  isObjectRecord(value) &&
+  typeof value.eventId === "string" &&
+  typeof value.clusterId === "string" &&
+  typeof value.createdAt === "number" &&
+  typeof value.grossCredits === "number" &&
+  Array.isArray(value.shares);
+
+const roundCredits = (value: number) => Math.round(value * 1_000_000) / 1_000_000;
+
+type CreatorAccumulator = {
+  count: number;
+  amountCredits: number;
+  grossCredits: number;
+};
+
+type ProductAccumulator = {
+  count: number;
+  grossCredits: number;
+  creatorShareCredits: number;
+  platformNetCredits: number;
+};
+
+type ProviderAccumulator = {
+  count: number;
+  grossCredits: number;
+  platformCostCredits: number;
+};
+
+type PolicyAccumulator = RevenueSplitPolicyRef & {
+  count: number;
+  grossCredits: number;
+  creatorShareCredits: number;
+  platformNetCredits: number;
+};
+
+export async function buildRevenueShareReport({
+  store,
+  clusterId,
+  sinceMs,
+  untilMs,
+  nowMs = Date.now(),
+}: {
+  store: RevenueShareReportStore;
+  clusterId: string;
+  sinceMs: number;
+  untilMs: number;
+  nowMs?: number;
+}): Promise<RevenueShareReport> {
+  const byCreator = new Map<string, CreatorAccumulator>();
+  const byProductKind = new Map<RevenueShareProductKind, ProductAccumulator>();
+  const byProvider = new Map<string, ProviderAccumulator>();
+  const byPolicy = new Map<string, PolicyAccumulator>();
+  const payerIds = new Set<string>();
+  const creatorIds = new Set<string>();
+
+  let eventsScanned = 0;
+  let eventsInWindow = 0;
+  let grossCredits = 0;
+  let platformCostCredits = 0;
+  let creatorShareCredits = 0;
+  let platformNetCredits = 0;
+
+  const prefix = revenueShareEventKeyPrefix(clusterId);
+  for await (const [, value] of store.iterator({
+    gte: prefix,
+    lte: rangeEnd(prefix),
+  })) {
+    if (!isRevenueShareEvent(value)) continue;
+    eventsScanned += 1;
+    if (value.createdAt < sinceMs || value.createdAt > untilMs) continue;
+    eventsInWindow += 1;
+
+    grossCredits += value.grossCredits;
+    platformCostCredits += value.platformCostCredits;
+    creatorShareCredits += value.creatorShareCredits;
+    platformNetCredits += value.platformNetCredits;
+    if (value.payerUserId) payerIds.add(value.payerUserId);
+
+    const productKind = value.product.kind;
+    const productAcc =
+      byProductKind.get(productKind) ?? {
+        count: 0,
+        grossCredits: 0,
+        creatorShareCredits: 0,
+        platformNetCredits: 0,
+      };
+    productAcc.count += 1;
+    productAcc.grossCredits += value.grossCredits;
+    productAcc.creatorShareCredits += value.creatorShareCredits;
+    productAcc.platformNetCredits += value.platformNetCredits;
+    byProductKind.set(productKind, productAcc);
+
+    const provider = value.product.provider || "unknown";
+    const providerAcc =
+      byProvider.get(provider) ?? {
+        count: 0,
+        grossCredits: 0,
+        platformCostCredits: 0,
+      };
+    providerAcc.count += 1;
+    providerAcc.grossCredits += value.grossCredits;
+    providerAcc.platformCostCredits += value.platformCostCredits;
+    byProvider.set(provider, providerAcc);
+
+    const policy = normalizeRevenueSplitPolicyRef(value.splitPolicy);
+    const policyKey = `${policy.policyId}:${policy.policyVersion}:${policy.source}`;
+    const policyAcc =
+      byPolicy.get(policyKey) ?? {
+        ...policy,
+        count: 0,
+        grossCredits: 0,
+        creatorShareCredits: 0,
+        platformNetCredits: 0,
+      };
+    policyAcc.count += 1;
+    policyAcc.grossCredits += value.grossCredits;
+    policyAcc.creatorShareCredits += value.creatorShareCredits;
+    policyAcc.platformNetCredits += value.platformNetCredits;
+    byPolicy.set(policyKey, policyAcc);
+
+    for (const share of value.shares) {
+      if (share.role !== "creator_share" || !share.userId) continue;
+      creatorIds.add(share.userId);
+      const creatorAcc =
+        byCreator.get(share.userId) ?? {
+          count: 0,
+          amountCredits: 0,
+          grossCredits: 0,
+        };
+      creatorAcc.count += 1;
+      creatorAcc.amountCredits += share.amountCredits;
+      creatorAcc.grossCredits += value.grossCredits;
+      byCreator.set(share.userId, creatorAcc);
+    }
+  }
+
+  return {
+    clusterId,
+    generatedAt: new Date(nowMs).toISOString(),
+    sinceMs,
+    untilMs,
+    summary: {
+      eventsScanned,
+      eventsInWindow,
+      grossCredits: roundCredits(grossCredits),
+      platformCostCredits: roundCredits(platformCostCredits),
+      creatorShareCredits: roundCredits(creatorShareCredits),
+      platformNetCredits: roundCredits(platformNetCredits),
+      payerCount: payerIds.size,
+      creatorCount: creatorIds.size,
+    },
+    byCreator: Array.from(byCreator.entries())
+      .map(([userId, acc]) => ({
+        userId,
+        count: acc.count,
+        amountCredits: roundCredits(acc.amountCredits),
+        grossCredits: roundCredits(acc.grossCredits),
+      }))
+      .sort((a, b) => b.amountCredits - a.amountCredits || b.count - a.count),
+    byProductKind: Array.from(byProductKind.entries())
+      .map(([productKind, acc]) => ({
+        productKind,
+        count: acc.count,
+        grossCredits: roundCredits(acc.grossCredits),
+        creatorShareCredits: roundCredits(acc.creatorShareCredits),
+        platformNetCredits: roundCredits(acc.platformNetCredits),
+      }))
+      .sort((a, b) => b.grossCredits - a.grossCredits || b.count - a.count),
+    byProvider: Array.from(byProvider.entries())
+      .map(([provider, acc]) => ({
+        provider,
+        count: acc.count,
+        grossCredits: roundCredits(acc.grossCredits),
+        platformCostCredits: roundCredits(acc.platformCostCredits),
+      }))
+      .sort((a, b) => b.grossCredits - a.grossCredits || b.count - a.count),
+    byPolicy: Array.from(byPolicy.values())
+      .map((acc) => ({
+        policyId: acc.policyId,
+        policyVersion: acc.policyVersion,
+        source: acc.source,
+        label: acc.label,
+        count: acc.count,
+        grossCredits: roundCredits(acc.grossCredits),
+        creatorShareCredits: roundCredits(acc.creatorShareCredits),
+        platformNetCredits: roundCredits(acc.platformNetCredits),
+      }))
+      .sort((a, b) => b.grossCredits - a.grossCredits || b.count - a.count),
+  };
+}