Function grantOrganizationCredits

packages/billing/src/org-billing.ts:329–396

(
  params: OptionalFields<
    {
      organizationId: string
      userId: string
      amount: number
      operationId: string
      description: string
      expiresAt: Date | null
      logger: Logger
    },
    'description' | 'expiresAt'
  >,
)

 * Uses advisory lock to serialize with other credit operations for the organization.
 */
export async function grantOrganizationCredits(
  params: OptionalFields<
    {
      organizationId: string
      userId: string
      amount: number
      operationId: string
      description: string
      expiresAt: Date | null
      logger: Logger
    },
    'description' | 'expiresAt'
  >,
): Promise<void> {
  const withDefaults = {
    description: 'Organization credit purchase',
    expiresAt: null,
    ...params,
  }
  const {
    organizationId,
    userId,
    amount,
    operationId,
    description,
    expiresAt,
    logger,
  } = withDefaults

  await withAdvisoryLockTransaction({
    callback: async (tx) => {
      const now = new Date()

      // Use onConflictDoNothing for idempotency - duplicate operation_ids are silently ignored
      const result = await tx
        .insert(schema.creditLedger)
        .values({
          operation_id: operationId,
          user_id: userId,
          org_id: organizationId,
          principal: amount,
          balance: amount,
          type: 'organization',
          description,
          priority: GRANT_PRIORITIES.organization,
          expires_at: expiresAt,
          created_at: now,
        })
        .onConflictDoNothing({ target: schema.creditLedger.operation_id })
        .returning({ id: schema.creditLedger.operation_id })

      if (result.length > 0) {
        logger.info(
          { organizationId, userId, operationId, amount, expiresAt },
          'Created new organization credit grant',
        )
      } else {
        logger.debug(