@dawdlo/sdk

Advertiser SDK for Dawdlo — manage campaigns and track conversions without hand-rolling HTTP calls. It wraps the dwref attribution flow end to end: capture the token on your landing page, then post back the conversion you care about (signup, activation, purchase).

npm install @dawdlo/sdk

Zero runtime dependencies. Ships ESM + CJS + types, plus a browser drop-in.

The flow

1. A developer clicks your sponsor line → Dawdlo redirects to your landing page with ?dwref=<token>.
2. Capture the token and store it against the visitor.
3. When that visitor converts, post the token back. Dawdlo bills your CPA and credits the developer's cashback — once, idempotently.

1. Capture the dwref

Server-side (Express):

import { expressCapture, readStoredDwref } from '@dawdlo/sdk';

app.use(expressCapture()); // sets a `dwref` cookie from ?dwref on any request

Server-side (Next.js / fetch handlers):

import { captureFromRequest } from '@dawdlo/sdk';

export function middleware(request: Request) {
  const { setCookie } = captureFromRequest(request);
  const res = NextResponse.next();
  if (setCookie) res.headers.set('Set-Cookie', setCookie);
  return res;
}

Browser drop-in (no server capture available):

<script src="https://unpkg.com/@dawdlo/sdk/dist/dawdlo-capture.global.js"></script>
<!-- auto-captures ?dwref on load; read later with Dawdlo.getStoredDwref() -->

2. Report the conversion

import { DawdloAdvertiser, readStoredDwref } from '@dawdlo/sdk';

const dawdlo = new DawdloAdvertiser({ apiKey: process.env.DAWDLO_ADV_KEY! });

app.post('/signup', async (req, res) => {
  const user = await createUser(req.body);
  const dwref = readStoredDwref(req);
  if (dwref) {
    await dawdlo.reportConversion({
      dwref,
      dedupeKey: user.id,      // idempotency — safe to retry
      eventType: 'signup',
    });
  }
  res.json({ ok: true });
});

Idempotent: a duplicate dedupeKey (or replayed token) returns { duplicate: true } and never double-charges. An expired (7-day) or forged token throws a DawdloApiError (err.isExpired, err.isInvalidToken).

3. Manage & track campaigns

// Create a CPC campaign (advertiser billed per click).
const { id } = await dawdlo.createCampaign({
  creativeText: 'Acme — ship faster',
  url: 'https://acme.dev',
  budgetUsd: 500,
  pricingModel: 'cpc',
  cpcUsd: 0.5,
});

// Or pay per conversion (CPA) with a developer cashback share.
await dawdlo.createCampaign({
  creativeText: 'Acme — ship faster',
  url: 'https://acme.dev',
  budgetUsd: 500,
  pricingModel: 'cpa',
  cpaUsd: 50,
  cashbackPct: 55,
});

// Track performance.
const { balanceUsd, campaigns } = await dawdlo.listCampaigns();
for (const c of campaigns) {
  console.log(c.id, c.status, c.clicks, c.conversions, `$${c.spentUsd}`);
}

await dawdlo.updateCampaign(id, { status: 'paused' });

Pricing models

| pricingModel | Advertiser pays… | Required field | | --- | --- | --- | | cpm | per 1,000 impressions | bidCpmUsd | | cpa | per confirmed conversion | cpaUsd (+ cashbackPct) | | cpc | per click | cpcUsd | | hybrid | impressions and conversions | bidCpmUsd + cpaUsd |

Configuration

new DawdloAdvertiser({
  apiKey: 'advk_…',            // required
  host: 'https://dawdlo-api.fly.dev', // default
  timeoutMs: 10_000,           // per request
  fetch: customFetch,          // optional injection
});

License

MIT