nolo-cli 0.1.23 → 0.1.29

package/auth/server/inviteReward.ts

@@ -0,0 +1,295 @@
+import serverDb from "../../database/server/db.js";
+import { DB_PREFIX } from "../../database/keys";
+import { rechargeUserBalance } from "../server/recharge";
+import { balanceLockManager } from "./locks";
+import { canSendEmailToUser } from "./emailPolicy";
+import { sendManagedEmail } from "./inviteRewardEmail";
+import {
+  buildInviteRewardReason,
+  buildInviteRewardTxId,
+} from "../invite";
+
+function isDbNotFoundError(err: any) {
+  return err?.code === "LEVEL_NOT_FOUND" || err?.notFound === true;
+}
+
+function isDuplicateTransactionError(error?: string) {
+  return error === "Duplicate transaction";
+}
+
+type InviteLogger = {
+  warn: (obj: any, msg: string) => void;
+};
+
+/**
+ * 邀请奖励邮件状态：
+ * - queued: 已进入邮件发送队列，避免重复入队
+ * - sent: 已成功发送
+ */
+type InviteRewardEmailState = {
+  status: "queued" | "sent";
+  updatedAt: number;
+};
+
+const INVITE_EMAIL_STATE_PREFIX = "email:invite-reward:state:";
+
+const getInviteRewardEmailStateKey = (inviterId: string, inviteeUserId: string) =>
+  `${INVITE_EMAIL_STATE_PREFIX}${inviterId}:${inviteeUserId}`;
+
+const getAppName = () => process.env.EMAIL_APP_NAME?.trim() || "Nolo";
+const getAppUrl = () => process.env.EMAIL_APP_URL?.trim() || "";
+const escapeHtml = (value: string) =>
+  value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+
+function normalizePublicUrl(url: string) {
+  if (!url) return "";
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return "";
+    return parsed.toString();
+  } catch {
+    return "";
+  }
+}
+
+function joinPublicUrl(baseUrl: string, path: string) {
+  if (!baseUrl) return "";
+  try {
+    return new URL(path, baseUrl).toString();
+  } catch {
+    return "";
+  }
+}
+
+function buildInviteRewardEmail(inviterName?: string, inviteeName?: string) {
+  const appName = getAppName();
+  const appUrl = normalizePublicUrl(getAppUrl());
+  const inviter = inviterName?.trim() || "朋友";
+  const invitee = inviteeName?.trim() || "你的好友";
+  const safeInviter = escapeHtml(inviter);
+  const safeInvitee = escapeHtml(invitee);
+  const safeAppName = escapeHtml(appName);
+  const accountUrl = joinPublicUrl(appUrl, "/account");
+  const safeAccountUrl = escapeHtml(accountUrl);
+  const subject = `${inviter}，邀请奖励已到账`;
+  const textBody = accountUrl
+    ? `你好 ${inviter}，\n\n你邀请的 ${invitee} 已完成注册，邀请奖励已发放到你的账户。\n\n查看账户：${accountUrl}\n\n感谢你对 ${appName} 的支持。`
+    : `你好 ${inviter}，\n\n你邀请的 ${invitee} 已完成注册，邀请奖励已发放到你的账户。\n\n感谢你对 ${appName} 的支持。`;
+  const htmlBody = appUrl
+    ? `<p>你好 ${safeInviter}，</p><p>你邀请的 <strong>${safeInvitee}</strong> 已完成注册，邀请奖励已发放到你的账户。</p><p><a href="${safeAccountUrl}">查看账户</a></p><p>感谢你对 ${safeAppName} 的支持。</p>`
+    : `<p>你好 ${safeInviter}，</p><p>你邀请的 <strong>${safeInvitee}</strong> 已完成注册，邀请奖励已发放到你的账户。</p><p>感谢你对 ${safeAppName} 的支持。</p>`;
+
+  return { subject, textBody, htmlBody };
+}
+
+function normalizeInviteRewardEmailState(value: any): InviteRewardEmailState | null {
+  if (
+    value &&
+    typeof value === "object" &&
+    (value.status === "queued" || value.status === "sent")
+  ) {
+    return {
+      status: value.status,
+      updatedAt: Number(value.updatedAt) || Date.now(),
+    };
+  }
+  return null;
+}
+
+async function getInviteRewardEmailState(
+  inviterId: string,
+  inviteeUserId: string
+): Promise<InviteRewardEmailState | null> {
+  try {
+    return normalizeInviteRewardEmailState(
+      await serverDb.get(getInviteRewardEmailStateKey(inviterId, inviteeUserId))
+    );
+  } catch (err: any) {
+    if (!isDbNotFoundError(err)) throw err;
+  }
+  return null;
+}
+
+async function markInviteRewardEmailState(
+  inviterId: string,
+  inviteeUserId: string,
+  status: InviteRewardEmailState["status"]
+) {
+  await serverDb.put(getInviteRewardEmailStateKey(inviterId, inviteeUserId), {
+    status,
+    updatedAt: Date.now(),
+  });
+}
+
+async function trySendInviteRewardEmail(
+  inviterId: string,
+  inviteeUserId: string,
+  logger: InviteLogger
+) {
+  const lock = balanceLockManager.getLock(`invite-email:${inviterId}:${inviteeUserId}`);
+  await lock.runExclusive(async () => {
+    // 只要已有状态（queued/sent），就不再重复触发邮件流程。
+    const existingState = await getInviteRewardEmailState(inviterId, inviteeUserId);
+    if (existingState) {
+      return;
+    }
+
+    let inviter: any = null;
+    try {
+      inviter = await serverDb.get(DB_PREFIX.USER + inviterId);
+    } catch (err: any) {
+      if (!isDbNotFoundError(err)) {
+        logger.warn({ inviterId, inviteeUserId, err }, "Failed to read inviter.");
+      }
+      return;
+    }
+
+    const policy = canSendEmailToUser(inviter, "invite-reward");
+    if (!policy.allowed) {
+      return;
+    }
+
+    let inviteeName = inviteeUserId;
+    try {
+      const invitee = await serverDb.get(DB_PREFIX.USER + inviteeUserId);
+      if (typeof invitee?.username === "string" && invitee.username.trim()) {
+        inviteeName = invitee.username;
+      }
+    } catch (err: any) {
+      if (!isDbNotFoundError(err)) {
+        logger.warn(
+          { inviterId, inviteeUserId, err },
+          "Failed to read invitee for email."
+        );
+      }
+    }
+
+    const email = buildInviteRewardEmail(inviter.username, inviteeName);
+    try {
+      const result = await sendManagedEmail({
+        userId: inviterId,
+        to: inviter.email,
+        subject: email.subject,
+        textBody: email.textBody,
+        htmlBody: email.htmlBody,
+        tag: "invite-reward",
+      });
+      if (result.suppressed) {
+        return;
+      }
+      if (!result.success && !result.queued) {
+        throw new Error(result.error || "Failed to send invite reward email");
+      }
+      await markInviteRewardEmailState(
+        inviterId,
+        inviteeUserId,
+        result.success ? "sent" : "queued"
+      );
+    } catch (err: any) {
+      logger.warn(
+        { inviterId, inviteeUserId, err: err?.message || String(err) },
+        "Failed to send invite reward email."
+      );
+    }
+  });
+}
+
+export async function resolveValidInviterId(
+  inviterId: string | undefined,
+  newUserId: string,
+  logger: InviteLogger
+) {
+  if (!inviterId) return undefined;
+
+  if (inviterId === newUserId) {
+    logger.warn({ inviterId, newUserId }, "Self-invite blocked.");
+    return undefined;
+  }
+
+  try {
+    const inviter = await serverDb.get(DB_PREFIX.USER + inviterId);
+    if (!inviter) {
+      logger.warn({ inviterId, newUserId }, "Inviter not found.");
+      return undefined;
+    }
+    if (inviter.isDisabled) {
+      logger.warn({ inviterId, newUserId }, "Disabled inviter blocked.");
+      return undefined;
+    }
+    return inviterId;
+  } catch (err: any) {
+    if (isDbNotFoundError(err)) {
+      logger.warn({ inviterId, newUserId }, "Inviter not found.");
+      return undefined;
+    }
+    throw err;
+  }
+}
+
+export async function creditInviterReward(
+  inviterId: string | undefined,
+  inviteeUserId: string,
+  logger: InviteLogger
+) {
+  if (!inviterId) return;
+
+  let inviteeCreatedAt = 0;
+  try {
+    const invitee = await serverDb.get(DB_PREFIX.USER + inviteeUserId);
+    inviteeCreatedAt =
+      typeof invitee?.createdAt === "number" ? invitee.createdAt : 0;
+  } catch (err: any) {
+    if (!isDbNotFoundError(err)) {
+      throw err;
+    }
+  }
+
+  if (!inviteeCreatedAt) {
+    logger.warn(
+      { inviterId, userId: inviteeUserId },
+      "Invitee createdAt missing, skip inviter reward."
+    );
+    return;
+  }
+
+  const inviterReward = 1;
+  const inviterRewardReason = buildInviteRewardReason(inviteeUserId);
+  const inviterRewardTxId = buildInviteRewardTxId(
+    inviteeUserId,
+    inviteeCreatedAt
+  );
+  const inviterRechargeResult = await rechargeUserBalance(
+    inviterId,
+    inviterReward,
+    inviterRewardReason,
+    inviterRewardTxId
+  );
+  const isDuplicate = isDuplicateTransactionError(inviterRechargeResult.error);
+  if (
+    !inviterRechargeResult.success &&
+    !isDuplicate
+  ) {
+    logger.warn(
+      {
+        inviterId,
+        userId: inviteeUserId,
+        error: inviterRechargeResult.error,
+      },
+      "Failed to credit inviter for new user signup."
+    );
+    return;
+  }
+
+  await trySendInviteRewardEmail(inviterId, inviteeUserId, logger);
+  if (isDuplicate) {
+    logger.warn(
+      { inviterId, userId: inviteeUserId },
+      "Invite reward transaction duplicated; ensured invite email state."
+    );
+  }
+}

package/auth/server/inviteRewardEmail.ts

@@ -0,0 +1 @@
+export { sendManagedEmail } from "./emailDelivery";

package/auth/server/ledger.ts

@@ -0,0 +1,422 @@
+import { createHash } from "node:crypto";
+import { ulid } from "ulid";
+
+export const CREDIT_MICROS_PER_CREDIT = 1_000_000n;
+
+export type BillingLedgerClusterId = "main" | "alpha" | "local" | string;
+export type BillingLedgerRole = "leader" | "replica" | "disabled";
+
+export type BillingLedgerRuntime = {
+  clusterId: BillingLedgerClusterId;
+  nodeId: string;
+  role: BillingLedgerRole;
+  balanceAuthorityClusterId: BillingLedgerClusterId;
+  isAuthoritativeBalance: boolean;
+};
+
+type BillingLedgerEnv = {
+  [key: string]: string | undefined;
+  APP_BASE_URL?: string;
+  BILLING_LEDGER_CLUSTER_ID?: string;
+  BILLING_LEDGER_NODE_ID?: string;
+  BILLING_LEDGER_ROLE?: string;
+  BILLING_LEDGER_ACTIVE_NODE_ID?: string;
+  BILLING_LEDGER_BALANCE_AUTHORITY_CLUSTER_ID?: string;
+};
+
+export type LedgerTransactionType =
+  | "recharge"
+  | "usage_charge"
+  | "purchase"
+  | "adjustment";
+
+export type LedgerEntryInput = {
+  accountId: string;
+  ownerUserId?: string;
+  delta: number;
+  startingBalance?: number;
+  allowNegative?: boolean;
+  metadata?: Record<string, unknown>;
+};
+
+export type LedgerEntry = {
+  entryId: string;
+  accountId: string;
+  ownerUserId?: string;
+  delta: number;
+  deltaMicros: string;
+  balanceBefore: number;
+  balanceBeforeMicros: string;
+  balanceAfter: number;
+  balanceAfterMicros: string;
+  accountVersion: number;
+  prevAccountHash: string;
+  hash: string;
+  metadata?: Record<string, unknown>;
+};
+
+export type LedgerTransaction = {
+  txId: string;
+  idempotencyKey: string;
+  type: LedgerTransactionType;
+  reason: string;
+  clusterId: BillingLedgerClusterId;
+  nodeId: string;
+  createdAt: number;
+  entries: LedgerEntry[];
+  metadata?: Record<string, unknown>;
+};
+
+export type LedgerAccountState = {
+  accountId: string;
+  ownerUserId?: string;
+  balance: number;
+  balanceMicros: string;
+  accountVersion: number;
+  accountHash: string;
+  updatedAt: number;
+};
+
+export type LedgerStoreOperation = {
+  type: "put";
+  key: string;
+  value: unknown;
+};
+
+export type LedgerStore = {
+  get: (key: string) => Promise<unknown | null>;
+  batch: (ops: LedgerStoreOperation[]) => Promise<void>;
+};
+
+export type PreparedLedgerAppend =
+  | {
+      status: "prepared";
+      transaction: LedgerTransaction;
+      operations: LedgerStoreOperation[];
+    }
+  | {
+      status: "duplicate";
+      transaction: LedgerTransaction;
+    }
+  | {
+      status: "not_leader";
+      error: string;
+    }
+  | {
+      status: "insufficient_funds";
+      accountId: string;
+      balance: number;
+      attemptedDelta: number;
+    };
+
+export type AppendLedgerResult =
+  | { status: "appended"; transaction: LedgerTransaction }
+  | Exclude<PreparedLedgerAppend, { status: "prepared" }>;
+
+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 normalizeRole = (value: string | undefined): BillingLedgerRole => {
+  if (value === "replica" || value === "disabled") return value;
+  return "leader";
+};
+
+const inferClusterId = (env: BillingLedgerEnv): BillingLedgerClusterId => {
+  if (env.BILLING_LEDGER_CLUSTER_ID?.trim()) {
+    return env.BILLING_LEDGER_CLUSTER_ID.trim();
+  }
+  const appBaseUrl = env.APP_BASE_URL?.trim();
+  if (appBaseUrl) {
+    try {
+      const host = new URL(appBaseUrl).hostname;
+      if (host === "nolo.chat") return "main";
+      if (host === "us.nolo.chat") return "alpha";
+    } catch {
+      // fall through to local
+    }
+  }
+  return "local";
+};
+
+export const getBillingLedgerRuntime = (
+  env: BillingLedgerEnv = process.env
+): BillingLedgerRuntime => {
+  const clusterId = inferClusterId(env);
+  const nodeId = env.BILLING_LEDGER_NODE_ID?.trim() || clusterId;
+  const explicitActiveNodeId = env.BILLING_LEDGER_ACTIVE_NODE_ID?.trim();
+  const explicitRole = env.BILLING_LEDGER_ROLE?.trim();
+  const balanceAuthorityClusterId =
+    env.BILLING_LEDGER_BALANCE_AUTHORITY_CLUSTER_ID?.trim() || "main";
+  const role =
+    explicitRole === "disabled" || explicitRole === "replica"
+      ? explicitRole
+      : explicitActiveNodeId
+        ? explicitActiveNodeId === nodeId
+          ? "leader"
+          : "replica"
+        : normalizeRole(explicitRole);
+  return {
+    clusterId,
+    nodeId,
+    role,
+    balanceAuthorityClusterId,
+    isAuthoritativeBalance: clusterId === balanceAuthorityClusterId,
+  };
+};
+
+export const toCreditMicros = (amount: number) => {
+  if (!Number.isFinite(amount)) {
+    throw new Error(`Invalid credit amount: ${amount}`);
+  }
+  return BigInt(Math.round(amount * Number(CREDIT_MICROS_PER_CREDIT)));
+};
+
+export const fromCreditMicros = (amountMicros: bigint) =>
+  Number(amountMicros) / Number(CREDIT_MICROS_PER_CREDIT);
+
+const safeKeyPart = (value: string) => sha256(value).slice(0, 32);
+
+export const ledgerTransactionKeyPrefix = (
+  clusterId: BillingLedgerClusterId
+) => `ledger-tx-${clusterId}-`;
+
+export const ledgerTransactionKey = (
+  clusterId: BillingLedgerClusterId,
+  txId: string
+) => `${ledgerTransactionKeyPrefix(clusterId)}${txId}`;
+
+export const ledgerIdempotencyKey = (
+  clusterId: BillingLedgerClusterId,
+  idempotencyKey: string
+) => `ledger-idem-${clusterId}-${safeKeyPart(idempotencyKey)}`;
+
+export const ledgerAccountKeyPrefix = (clusterId: BillingLedgerClusterId) =>
+  `ledger-account-${clusterId}-`;
+
+export const ledgerAccountKey = (
+  clusterId: BillingLedgerClusterId,
+  accountId: string
+) => `${ledgerAccountKeyPrefix(clusterId)}${safeKeyPart(accountId)}`;
+
+export const ledgerAccountEntryKeyPrefix = (
+  clusterId: BillingLedgerClusterId,
+  accountId: string
+) => `ledger-entry-${clusterId}-${safeKeyPart(accountId)}-`;
+
+export const ledgerAccountEntryKey = (
+  clusterId: BillingLedgerClusterId,
+  accountId: string,
+  accountVersion: number
+) =>
+  `${ledgerAccountEntryKeyPrefix(clusterId, accountId)}${String(
+    accountVersion
+  ).padStart(16, "0")}`;
+
+export const userAvailableCreditsAccountId = (userId: string) =>
+  `user:${userId}:credits:available`;
+
+export const platformProviderCostAccountId = (platformUserId: string) =>
+  `platform:${platformUserId}:provider-cost`;
+
+export const platformNetRevenueAccountId = (platformUserId: string) =>
+  `platform:${platformUserId}:net-revenue`;
+
+export const creatorPendingEarningsAccountId = (creatorUserId: string) =>
+  `creator:${creatorUserId}:earnings:pending`;
+
+const normalizeAccountState = (
+  value: unknown,
+  input: LedgerEntryInput,
+  now: number
+): LedgerAccountState => {
+  if (value && typeof value === "object") {
+    const state = value as LedgerAccountState;
+    if (typeof state.balanceMicros === "string") return state;
+  }
+  const startingMicros = toCreditMicros(input.startingBalance ?? 0);
+  return {
+    accountId: input.accountId,
+    ownerUserId: input.ownerUserId,
+    balance: fromCreditMicros(startingMicros),
+    balanceMicros: startingMicros.toString(),
+    accountVersion: 0,
+    accountHash: "",
+    updatedAt: now,
+  };
+};
+
+export const computeLedgerEntryHash = (
+  transactionBase: Omit<LedgerTransaction, "entries">,
+  entry: Omit<LedgerEntry, "hash">
+) =>
+  sha256(
+    stableJson({
+      version: 1,
+      txId: transactionBase.txId,
+      idempotencyKey: transactionBase.idempotencyKey,
+      type: transactionBase.type,
+      clusterId: transactionBase.clusterId,
+      nodeId: transactionBase.nodeId,
+      createdAt: transactionBase.createdAt,
+      entry,
+    })
+  );
+
+export const prepareLedgerTransactionAppend = async ({
+  store,
+  runtime = getBillingLedgerRuntime(),
+  txId = ulid(),
+  type,
+  reason,
+  idempotencyKey,
+  entries,
+  metadata,
+  now = Date.now(),
+}: {
+  store: Pick<LedgerStore, "get">;
+  runtime?: BillingLedgerRuntime;
+  txId?: string;
+  type: LedgerTransactionType;
+  reason: string;
+  idempotencyKey: string;
+  entries: LedgerEntryInput[];
+  metadata?: Record<string, unknown>;
+  now?: number;
+}): Promise<PreparedLedgerAppend> => {
+  if (runtime.role !== "leader") {
+    return {
+      status: "not_leader",
+      error: `Billing ledger writes require leader role, got ${runtime.role}`,
+    };
+  }
+
+  const idemKey = ledgerIdempotencyKey(runtime.clusterId, idempotencyKey);
+  const existing = (await store.get(idemKey).catch(() => null)) as
+    | { txKey?: string; transaction?: LedgerTransaction }
+    | null;
+  if (existing?.transaction) {
+    return { status: "duplicate", transaction: existing.transaction };
+  }
+
+  const transactionBase = {
+    txId,
+    idempotencyKey,
+    type,
+    reason,
+    clusterId: runtime.clusterId,
+    nodeId: runtime.nodeId,
+    createdAt: now,
+    ...(metadata ? { metadata } : {}),
+  };
+
+  const operations: LedgerStoreOperation[] = [];
+  const ledgerEntries: LedgerEntry[] = [];
+  const nextAccountStates = new Map<string, LedgerAccountState>();
+
+  for (const input of entries) {
+    const accountKey = ledgerAccountKey(runtime.clusterId, input.accountId);
+    const state =
+      nextAccountStates.get(input.accountId) ||
+      normalizeAccountState(
+        await store.get(accountKey).catch(() => null),
+        input,
+        now
+      );
+    const deltaMicros = toCreditMicros(input.delta);
+    const balanceBeforeMicros = BigInt(state.balanceMicros);
+    const balanceAfterMicros = balanceBeforeMicros + deltaMicros;
+    if (balanceAfterMicros < 0n && input.allowNegative !== true) {
+      return {
+        status: "insufficient_funds",
+        accountId: input.accountId,
+        balance: fromCreditMicros(balanceBeforeMicros),
+        attemptedDelta: input.delta,
+      };
+    }
+
+    const entryWithoutHash: Omit<LedgerEntry, "hash"> = {
+      entryId: `${txId}:${ledgerEntries.length}`,
+      accountId: input.accountId,
+      ...(input.ownerUserId ? { ownerUserId: input.ownerUserId } : {}),
+      delta: fromCreditMicros(deltaMicros),
+      deltaMicros: deltaMicros.toString(),
+      balanceBefore: fromCreditMicros(balanceBeforeMicros),
+      balanceBeforeMicros: balanceBeforeMicros.toString(),
+      balanceAfter: fromCreditMicros(balanceAfterMicros),
+      balanceAfterMicros: balanceAfterMicros.toString(),
+      accountVersion: state.accountVersion + 1,
+      prevAccountHash: state.accountHash,
+      ...(input.metadata ? { metadata: input.metadata } : {}),
+    };
+    const hash = computeLedgerEntryHash(transactionBase, entryWithoutHash);
+    const entry: LedgerEntry = { ...entryWithoutHash, hash };
+    ledgerEntries.push(entry);
+
+    const nextState: LedgerAccountState = {
+      accountId: input.accountId,
+      ...(input.ownerUserId ? { ownerUserId: input.ownerUserId } : {}),
+      balance: entry.balanceAfter,
+      balanceMicros: entry.balanceAfterMicros,
+      accountVersion: entry.accountVersion,
+      accountHash: hash,
+      updatedAt: now,
+    };
+    nextAccountStates.set(input.accountId, nextState);
+    operations.push({
+      type: "put",
+      key: accountKey,
+      value: nextState,
+    });
+    operations.push({
+      type: "put",
+      key: ledgerAccountEntryKey(
+        runtime.clusterId,
+        input.accountId,
+        entry.accountVersion
+      ),
+      value: entry,
+    });
+  }
+
+  const transaction: LedgerTransaction = {
+    ...transactionBase,
+    entries: ledgerEntries,
+  };
+  const txKey = ledgerTransactionKey(runtime.clusterId, txId);
+  operations.push({ type: "put", key: txKey, value: transaction });
+  operations.push({
+    type: "put",
+    key: idemKey,
+    value: { txKey, transaction, createdAt: now },
+  });
+
+  return {
+    status: "prepared",
+    transaction,
+    operations,
+  };
+};
+
+export const appendLedgerTransaction = async (
+  options: Parameters<typeof prepareLedgerTransactionAppend>[0] & {
+    store: LedgerStore;
+  }
+): Promise<AppendLedgerResult> => {
+  const prepared = await prepareLedgerTransactionAppend(options);
+  if (prepared.status !== "prepared") return prepared;
+  await options.store.batch(prepared.operations);
+  return { status: "appended", transaction: prepared.transaction };
+};