Creating a TypeScript types definition package

[eroncastro]

Hi.

In our company, we are trying to implement a TypeScript types definition package to be used along implementations that use Protected Audience.

Should we follow https://wicg.github.io/turtledove?

Thanks!

[JensenPaul]

https://wicg.github.io/turtledove is Protected Audience's most up-to-date spec. @eroncastro, could you please update your GitHub profile with your company affiliation?

[JacobGo]

+1 to Chrome contributing official TypeScript types for Privacy Sandbox APIs not included in the existing Microsoft @types/web package generated from browser specs. lib.dom.d.ts is a critical library when writing TypeScript on the browser. Manually maintained typings from the IDLs can fall out of sync and lead to errors as definitions evolve over time.

[eroncastro]

Hi @JensenPaul

https://wicg.github.io/turtledove is Protected Audience's most up-to-date spec.

Thanks for confirming. I want to point out, however, that while walking through it I could not find some of the signatures described in the FLEDGE explainer. For functions generateBid, reportResult, and reportWin, for example, I have found their return types but not their arguments. Am I missing something?

@eroncastro, could you please update your GitHub profile with your company affiliation?

Absolutely. Updated.

[JensenPaul]

generateBid, scoreAd, reportResult, and reportWin are not directly callable from web pages. They are implemented by people wishing to participate in Protected Audience auctions and called by the browser in a JavaScript environment separate from the typical web page JavaScript execution contexts.

[eroncastro]

@JensenPaul I understand that.

But, for people that are going to write JavaScript code to participate on the auctions, these methods signatures will be useful. And, by leveraging TypeScript static types, they can ensure they are doing it in a type safe way, preventing runtime errors.

Are there any official documents including these signatures?

[fhoering]

Most input types like interestGroup, perBuyerSignals, trustedBiddingSignals are custom. So it will be different for each implementer.

What about adding some index.d.ts file to this repo ? For browserSignals it seems useful to have the type of each field and as this is also different for generateBid & reportResult

Here is what we are using at Criteo as a buyer so far (no guarantee of correctness)

interface Ad {
    render_url: string
}

interface BidBrowserSignals {
    topWindowHostname: string;
    seller: string;
    topLevelSeller: string;
    joinCount: number;
    bidCount: number;
    prevWins: [number, Ad][];  
    dataVersion: number;
}

interface ReportWinBrowserSignals {
    topWindowHostname: string;
    interestGroupOwner: string;
    interestGroupName?: string;
    buyerReportingId?: string;
    buyerAndSellerReportingId?: string;
    renderUrl: string;
    bid: number;
    bidCurrency?: string;
    adCost: number;
    modelingSignals: number;
    joinCount: number;
    recency: number;
    highestScoringOtherBid: number;
    highestScoringOtherBidCurrency?: string;
    madeHighestScoringOtherBid: boolean;
    seller: string;
    topLevelSeller: string;    
    dataVersion: number;
}

interface GenerateBidAd {
    campaignId: number;
}

interface GenerateBidResult {
    ad?: GenerateBidAd;
    bid: number;
    render?: string,
    allowComponentAuction?: boolean,
    adComponents?: string[],
    modelingSignals?: number
}

declare function reportWin(auctionSignals: any, perBuyerSignals: any, sellerSignals: any, browserSignals: ReportWinBrowserSignals): void;
declare function generateBid(interestGroup: any, auctionSignals: any, perBuyerSignals: any, trustedBiddingSignals: any, browserSignals: BidBrowserSignals): GenerateBidResult;