def auth_paid_promo(thing, user, pay_id, bid):
    """
    promotes a promotion from 'unpaid' to 'unseen'.  
    
    In the case that bid already exists on the current promotion, the
    previous transaction is voided and repalced with the new bid.
    """
    if thing.promote_status == STATUS.finished:
        return
    elif (thing.promote_status > STATUS.unpaid and
          thing.promote_trans_id):
        # void the existing transaction
        authorize.void_transaction(user, thing.promote_trans_id)

    # create a new transaction and update the bid
    trans_id = authorize.auth_transaction(bid, user, pay_id, thing)
    thing.promote_bid = bid
    
    if trans_id is not None:
        # we won't reset to unseen if already approved and the payment went ok
        promotion_log(thing, "updated payment and/or bid: SUCCESS")
        if trans_id < 0:
            promotion_log(thing, "FREEBIE")
        thing.promote_status = max(thing.promote_status, STATUS.unseen)
        thing.promote_trans_id = trans_id
    else:
        # something bad happend.  
        promotion_log(thing, "updated payment and/or bid: FAILED")    
        thing.promore_status = STATUS.unpaid
        thing.promote_trans_id = 0
    PromoteDates.update_bid(thing)
    # commit last to guarantee consistency
    thing._commit()
    emailer.promo_bid(thing)
    return bool(trans_id)

def auth_campaign(link, campaign, user, pay_id=None, freebie=False):
    """
    Authorizes (but doesn't charge) a budget with authorize.net.
    Args:
    - link: promoted link
    - campaign: campaign to be authorized
    - user: Account obj of the user doing the auth (usually the currently
        logged in user)
    - pay_id: customer payment profile id to use for this transaction. (One
        user can have more than one payment profile if, for instance, they have
        more than one credit card on file.) Set pay_id to -1 for freebies.

    Returns: (True, "") if successful or (False, error_msg) if not. 
    """
    void_campaign(link, campaign, reason='changed_payment')

    if freebie:
        trans_id, reason = authorize.auth_freebie_transaction(
            campaign.total_budget_dollars, user, link, campaign._id)
    else:
        trans_id, reason = authorize.auth_transaction(
            campaign.total_budget_dollars, user, pay_id, link, campaign._id)

    if trans_id and not reason:
        text = ('updated payment and/or budget for campaign %s: '
                'SUCCESS (trans_id: %d, amt: %0.2f)' %
                (campaign._id, trans_id, campaign.total_budget_dollars))
        PromotionLog.add(link, text)
        if trans_id < 0:
            PromotionLog.add(link, 'FREEBIE (campaign: %s)' % campaign._id)

        if trans_id:
            if is_finished(link):
                # When a finished promo gets a new paid campaign it doesn't
                # need to go through approval again and is marked accepted
                new_status = PROMOTE_STATUS.accepted
            else:
                new_status = max(PROMOTE_STATUS.unseen, link.promote_status)
        else:
            new_status = max(PROMOTE_STATUS.unpaid, link.promote_status)
        update_promote_status(link, new_status)

        if user and (user._id == link.author_id) and trans_id > 0:
            emailer.promo_total_budget(link,
                campaign.total_budget_dollars,
                campaign.start_date)

    else:
        text = ("updated payment and/or budget for campaign %s: FAILED ('%s')"
                % (campaign._id, reason))
        PromotionLog.add(link, text)
        trans_id = 0

    campaign.trans_id = trans_id
    campaign._commit()

    return bool(trans_id), reason

def auth_campaign(link, index, user, pay_id):
    """
    for setting up a campaign as a real bid with authorize.net
    """
    with g.make_lock(campaign_lock(link)):
        campaigns = getattr(link, "campaigns", {}).copy()
        if index in campaigns:
            # void any existing campaign
            void_campaign(link, index, user)

            sd, ed, bid, sr, trans_id = campaigns[index]
            # create a new transaction and update the bid
            test = 1 if g.debug else None
            trans_id, reason = authorize.auth_transaction(bid, user,
                                                          pay_id, link,
                                                          index,
                                                          test = test)
            if not reason and trans_id is not None and int(trans_id) != 0:
                promotion_log(link, "updated payment and/or bid for campaign %s: "
                              "SUCCESS (trans_id: %d, amt: %0.2f)"
                              % (index, trans_id, bid))
                if trans_id < 0:
                    promotion_log(link, "FREEBIE (campaign: %s)" % index)

                set_status(link,
                           max(STATUS.unseen if trans_id else STATUS.unpaid,
                               link.promote_status))
                # notify of campaign creation
                # update the query queue
                if user._id == link.author_id and trans_id > 0:
                    emailer.promo_bid(link, bid, sd)
            
            else:
                # something bad happend.
                promotion_log(link, "updated payment and/or bid for campaign %s: FAILED ('%s')" 
                              % (index, reason))
                trans_id = 0

            campaigns[index] = sd, ed, bid, sr, trans_id
            link.campaigns = {}
            link.campaigns = campaigns
            link._commit()

            # dual-write update to campaign Thing
            campaign = PromoCampaign._byID(index)
            if campaign:
                if trans_id > 0:
                    campaign.mark_paid(trans_id)
                elif trans_id < 0:
                    campaign.mark_freebie(trans_id)
                else:
                    campaign.mark_payment_error(reason)
                campaign._commit()

            return bool(trans_id), reason
        return False, ""

def auth_campaign(link, campaign_id, user, pay_id):
    """
    Authorizes (but doesn't charge) a bid with authorize.net.
    Args:
    - link: promoted link
    - campaign_id: long id of the campaign on link to be authorized
    - user: Account obj of the user doing the auth (usually the currently
        logged in user)
    - pay_id: customer payment profile id to use for this transaction. (One
        user can have more than one payment profile if, for instance, they have
        more than one credit card on file.) Set pay_id to -1 for freebies.

    Returns: (True, "") if successful or (False, error_msg) if not. 
    """
    try:
        campaign = PromoCampaign._byID(campaign_id, data=True)
    except NotFound:
        g.log.error("Ignoring attempt to auth non-existent campaign: %d" % 
                    campaign_id)
        return False, "Campaign not found."

    void_campaign(link, campaign_id)
    test = 1 if g.debug else None
    trans_id, reason = authorize.auth_transaction(campaign.bid, user, pay_id,
                                                  link, campaign_id, test=test)

    if trans_id and not reason:
        text = ('updated payment and/or bid for campaign %s: '
                'SUCCESS (trans_id: %d, amt: %0.2f)' % (campaign_id, trans_id,
                                                        campaign.bid))
        PromotionLog.add(link, text)
        if trans_id < 0:
            PromotionLog.add(link, 'FREEBIE (campaign: %s)' % campaign_id)

        set_status(link,
                   max(STATUS.unseen if trans_id else STATUS.unpaid,
                       link.promote_status))
        # notify of campaign creation
        # update the query queue
        if user and (user._id == link.author_id) and trans_id > 0:
            emailer.promo_bid(link, campaign.bid, campaign.start_date)
    
    else:
        # something bad happend.
        text = ("updated payment and/or bid for campaign %s: FAILED ('%s')"
                % (campaign_id, reason))
        PromotionLog.add(link, text)
        trans_id = 0

    campaign.trans_id = trans_id
    campaign._commit()

    return bool(trans_id), reason

def convert_promoted():
    """
    should only need to be run once to update old style promoted links
    to the new style.
    """
    from r2.lib.utils import fetch_things2
    from r2.lib import authorize

    q = Link._query(Link.c.promoted == (True, False),
                    sort = desc("_date"))
    sr_id = PromoteSR._id
    bid = 100
    with g.make_lock(promoted_lock_key):
        promoted = {}
        set_promoted({})
        for l in fetch_things2(q):
            print "updating:", l
            try:
                if not l._loaded: l._load()
                # move the promotion into the promo subdigg
                l.sr_id = sr_id
                # set it to accepted (since some of the update functions
                # check that it is not already promoted)
                l.promote_status = STATUS.accepted
                author = Account._byID(l.author_id)
                l.promote_trans_id = authorize.auth_transaction(bid, author, -1, l)
                l.promote_bid = bid
                l.maximum_clicks = None
                l.maximum_views = None
                # set the dates
                start = getattr(l, "promoted_on", l._date)
                until = getattr(l, "promote_until", None) or \
                    (l._date + timedelta(1))
                l.promote_until = None
                update_promo_dates(l, start, until)
                # mark it as promoted if it was promoted when we got there
                if l.promoted and l.promote_until > datetime.now(g.tz):
                    l.promote_status = STATUS.pending
                else:
                    l.promote_status = STATUS.finished
    
                if not hasattr(l, "disable_comments"):
                    l.disable_comments = False
                # add it to the auction list
                if l.promote_status == STATUS.pending and l._fullname not in promoted:
                    promoted[l._fullname] = auction_weight(l)
                l._commit()
            except AttributeError:
                print "BAD THING:", l
        print promoted
        set_promoted(promoted)

def auth_campaign(link, campaign, user, pay_id):
    """
    Authorizes (but doesn't charge) a bid with authorize.net.
    Args:
    - link: promoted link
    - campaign: campaign to be authorized
    - user: Account obj of the user doing the auth (usually the currently
        logged in user)
    - pay_id: customer payment profile id to use for this transaction. (One
        user can have more than one payment profile if, for instance, they have
        more than one credit card on file.) Set pay_id to -1 for freebies.

    Returns: (True, "") if successful or (False, error_msg) if not. 
    """
    void_campaign(link, campaign)
    test = 1 if g.debug else None
    trans_id, reason = authorize.auth_transaction(campaign.bid, user, pay_id, link, campaign._id, test=test)

    if trans_id and not reason:
        text = "updated payment and/or bid for campaign %s: " "SUCCESS (trans_id: %d, amt: %0.2f)" % (
            campaign._id,
            trans_id,
            campaign.bid,
        )
        PromotionLog.add(link, text)
        if trans_id < 0:
            PromotionLog.add(link, "FREEBIE (campaign: %s)" % campaign._id)

        if trans_id:
            new_status = max(PROMOTE_STATUS.unseen, link.promote_status)
        else:
            new_status = max(PROMOTE_STATUS.unpaid, link.promote_status)
        set_promote_status(link, new_status)
        # notify of campaign creation
        # update the query queue
        if user and (user._id == link.author_id) and trans_id > 0:
            emailer.promo_bid(link, campaign.bid, campaign.start_date)

    else:
        # something bad happend.
        text = "updated payment and/or bid for campaign %s: FAILED ('%s')" % (campaign._id, reason)
        PromotionLog.add(link, text)
        trans_id = 0

    campaign.trans_id = trans_id
    campaign._commit()

    return bool(trans_id), reason

def auth_campaign(link, campaign_id, user, pay_id):
    """
    Authorizes (but doesn't charge) a bid with authorize.net.
    Args:
    - link: promoted link
    - campaign_id: long id of the campaign on link to be authorized
    - user: Account obj of the user doing the auth (usually the currently
        logged in user)
    - pay_id: customer payment profile id to use for this transaction. (One
        user can have more than one payment profile if, for instance, they have
        more than one credit card on file.) Set pay_id to -1 for freebies.

    Returns: (True, "") if successful or (False, error_msg) if not. 
    """
    try:
        campaign = PromoCampaign._byID(campaign_id, data=True)
    except NotFound:
        g.log.error("Ignoring attempt to auth non-existent campaign: %d" % campaign_id)
        return False, "Campaign not found."

    void_campaign(link, campaign_id)
    test = 1 if g.debug else None
    trans_id, reason = authorize.auth_transaction(campaign.bid, user, pay_id, link, campaign_id, test=test)

    if trans_id and not reason:
        promotion_log(
            link,
            "updated payment and/or bid for campaign %s: "
            "SUCCESS (trans_id: %d, amt: %0.2f)" % (campaign_id, trans_id, campaign.bid),
        )
        if trans_id < 0:
            promotion_log(link, "FREEBIE (campaign: %s)" % campaign_id)

        set_status(link, max(STATUS.unseen if trans_id else STATUS.unpaid, link.promote_status))
        # notify of campaign creation
        # update the query queue
        if user and (user._id == link.author_id) and trans_id > 0:
            emailer.promo_bid(link, campaign.bid, campaign.start_date)

    else:
        # something bad happend.
        promotion_log(link, "updated payment and/or bid for campaign %s: FAILED ('%s')" % (campaign_id, reason))
        trans_id = 0

    campaign.trans_id = trans_id
    campaign._commit()

    # dual-write update to link attribute in case we need to roll back
    with g.make_lock("promo_campaign", campaign_lock(link)):
        campaigns = getattr(link, "campaigns", {}).copy()
        if campaign_id in campaigns:
            campaigns[campaign_id] = (
                campaign.start_date,
                campaign.end_date,
                campaign.bid,
                campaign.sr_name,
                campaign.trans_id,
            )
            link.campaigns = {}
            link.campaigns = campaigns
            link._commit()

    return bool(trans_id), reason