@q32/core 0.2.2 → 0.3.0

package/README.md

@@ -8,6 +8,7 @@ The first release focuses on common infrastructure repeated across Q32 apps:
 - API operation registries
 - API/MCP discovery surfaces: OpenAPI docs, API catalogs, Agent Skills indexes, MCP manifests, and bearer challenges
 - framework-neutral auth/session/MCP auth services with thin Hono and React Router adapters
+- durable purchase-conversion outbox contracts and Google Ads click-conversion uploads
 - billing plan/status primitives
 - Cloudflare binding guards
 - environment parsing
@@ -67,6 +68,7 @@ import {
 ```
 
 See [docs/jobs.md](docs/jobs.md) for the shared jobs model.
+See [docs/conversion-outbox.md](docs/conversion-outbox.md) for the confirmed-purchase conversion contract.
 
 The root `@q32/core` export is kept dependency-light. Optional integrations that
 need peer packages should be imported from their subpaths, for example

package/dist/conversion-outbox.d.ts

@@ -0,0 +1,41 @@
+export type ConversionProvider = "google_ads" | "meta" | "microsoft_ads";
+export type ConversionDeliveryStatus = "pending" | "sending" | "sent" | "retry" | "dead" | "skipped";
+export type AdClickIds = {
+    gclid?: string | null;
+    gbraid?: string | null;
+    wbraid?: string | null;
+    fbclid?: string | null;
+    msclkid?: string | null;
+};
+export type PurchaseConversionEvent = {
+    eventId: string;
+    orderId: string;
+    productSlug: string;
+    conversionAt: string;
+    value: number;
+    currency: string;
+    clickIds: AdClickIds;
+    emailSha256?: string | null;
+    sourceUrl?: string | null;
+    metadata?: Record<string, unknown>;
+};
+export type ConversionDelivery = {
+    deliveryKey: string;
+    eventId: string;
+    provider: ConversionProvider;
+    status: ConversionDeliveryStatus;
+    attemptCount: number;
+    nextAttemptAt: string | null;
+    sentAt: string | null;
+    lastErrorCode: string | null;
+    lastErrorMessage: string | null;
+};
+export declare function createPurchaseConversionEvent(input: PurchaseConversionEvent): PurchaseConversionEvent;
+export declare function conversionDeliveryKey(eventId: string, provider: ConversionProvider): string;
+export declare function createConversionDelivery(eventId: string, provider: ConversionProvider): ConversionDelivery;
+export declare function nextConversionRetryAt(attemptCount: number, options?: {
+    now?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+}): string;
+//# sourceMappingURL=conversion-outbox.d.ts.map

package/dist/conversion-outbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversion-outbox.d.ts","sourceRoot":"","sources":["../src/conversion-outbox.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAAG,YAAY,GAAG,MAAM,GAAG,eAAe,CAAC;AACzE,MAAM,MAAM,wBAAwB,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;AAErG,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,UAAU,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,MAAM,EAAE,wBAAwB,CAAC;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC,CAAC;AAEF,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,uBAAuB,GAAG,uBAAuB,CAcrG;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,kBAAkB,GAAG,MAAM,CAG3F;AAED,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,kBAAkB,GAAG,kBAAkB,CAY1G;AAED,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GACxE,MAAM,CAMR"}

package/dist/conversion-outbox.js

@@ -0,0 +1,54 @@
+export function createPurchaseConversionEvent(input) {
+    if (!input.eventId.trim())
+        throw new Error("Purchase conversion eventId is required");
+    if (!input.orderId.trim())
+        throw new Error("Purchase conversion orderId is required");
+    if (!input.productSlug.trim())
+        throw new Error("Purchase conversion productSlug is required");
+    if (!Number.isFinite(input.value) || input.value < 0)
+        throw new Error("Purchase conversion value must be non-negative");
+    if (!/^[A-Z]{3}$/.test(input.currency))
+        throw new Error("Purchase conversion currency must be a three-letter uppercase code");
+    if (!Number.isFinite(Date.parse(input.conversionAt)))
+        throw new Error("Purchase conversion conversionAt must be an ISO date-time");
+    return {
+        ...input,
+        eventId: input.eventId.trim(),
+        orderId: input.orderId.trim(),
+        productSlug: input.productSlug.trim(),
+        clickIds: compactClickIds(input.clickIds),
+    };
+}
+export function conversionDeliveryKey(eventId, provider) {
+    if (!eventId.trim())
+        throw new Error("Conversion delivery eventId is required");
+    return `${eventId.trim()}:${provider}`;
+}
+export function createConversionDelivery(eventId, provider) {
+    return {
+        deliveryKey: conversionDeliveryKey(eventId, provider),
+        eventId: eventId.trim(),
+        provider,
+        status: "pending",
+        attemptCount: 0,
+        nextAttemptAt: null,
+        sentAt: null,
+        lastErrorCode: null,
+        lastErrorMessage: null,
+    };
+}
+export function nextConversionRetryAt(attemptCount, options = {}) {
+    if (!Number.isInteger(attemptCount) || attemptCount < 1)
+        throw new Error("Conversion attemptCount must be a positive integer");
+    const baseDelayMs = options.baseDelayMs ?? 30_000;
+    const maxDelayMs = options.maxDelayMs ?? 24 * 60 * 60 * 1000;
+    const delay = Math.min(maxDelayMs, baseDelayMs * 2 ** Math.min(attemptCount - 1, 20));
+    return new Date((options.now ?? Date.now()) + delay).toISOString();
+}
+function compactClickIds(input) {
+    return Object.fromEntries(Object.entries(input).flatMap(([key, value]) => {
+        const normalized = value?.trim();
+        return normalized ? [[key, normalized]] : [];
+    }));
+}
+//# sourceMappingURL=conversion-outbox.js.map

package/dist/conversion-outbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversion-outbox.js","sourceRoot":"","sources":["../src/conversion-outbox.ts"],"names":[],"mappings":"AAoCA,MAAM,UAAU,6BAA6B,CAAC,KAA8B;IAC1E,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;IACtF,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;IACtF,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IAC9F,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;IACxH,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,oEAAoE,CAAC,CAAC;IAC9H,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,2DAA2D,CAAC,CAAC;IACnI,OAAO;QACL,GAAG,KAAK;QACR,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE;QAC7B,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE;QAC7B,WAAW,EAAE,KAAK,CAAC,WAAW,CAAC,IAAI,EAAE;QACrC,QAAQ,EAAE,eAAe,CAAC,KAAK,CAAC,QAAQ,CAAC;KAC1C,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,OAAe,EAAE,QAA4B;IACjF,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;IAChF,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,IAAI,QAAQ,EAAE,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,OAAe,EAAE,QAA4B;IACpF,OAAO;QACL,WAAW,EAAE,qBAAqB,CAAC,OAAO,EAAE,QAAQ,CAAC;QACrD,OAAO,EAAE,OAAO,CAAC,IAAI,EAAE;QACvB,QAAQ;QACR,MAAM,EAAE,SAAS;QACjB,YAAY,EAAE,CAAC;QACf,aAAa,EAAE,IAAI;QACnB,MAAM,EAAE,IAAI;QACZ,aAAa,EAAE,IAAI;QACnB,gBAAgB,EAAE,IAAI;KACvB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,YAAoB,EACpB,UAAuE,EAAE;IAEzE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,YAAY,CAAC,IAAI,YAAY,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;IAC/H,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,MAAM,CAAC;IAClD,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAC7D,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,WAAW,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,YAAY,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IACtF,OAAO,IAAI,IAAI,CAAC,CAAC,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;AACrE,CAAC;AAED,SAAS,eAAe,CAAC,KAAiB;IACxC,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;QAC7C,MAAM,UAAU,GAAG,KAAK,EAAE,IAAI,EAAE,CAAC;QACjC,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/C,CAAC,CAAC,CACH,CAAC;AACJ,CAAC"}

package/dist/google-ads.d.ts

@@ -0,0 +1,36 @@
+import type { FetchLike } from "./http.js";
+import type { PurchaseConversionEvent } from "./conversion-outbox.js";
+export type GoogleAdsConversionConfig = {
+    developerToken: string;
+    clientId: string;
+    clientSecret: string;
+    refreshToken: string;
+    customerId: string;
+    conversionActionId: string;
+    loginCustomerId?: string;
+    apiVersion?: string;
+};
+export type GoogleAdsUploadResult = {
+    status: "sent";
+    jobId: string | null;
+    requestId: string | null;
+} | {
+    status: "skipped";
+    reason: "missing_google_click_id";
+};
+export declare class GoogleAdsConversionError extends Error {
+    readonly code: string;
+    readonly retryable: boolean;
+    readonly status: number | null;
+    constructor(message: string, code: string, retryable: boolean, status: number | null);
+}
+export declare class GoogleAdsConversionClient {
+    private readonly config;
+    private readonly fetchImpl;
+    private accessToken;
+    constructor(config: GoogleAdsConversionConfig, fetchImpl?: FetchLike);
+    uploadPurchase(event: PurchaseConversionEvent): Promise<GoogleAdsUploadResult>;
+    private getAccessToken;
+}
+export declare function googleAdsDateTime(value: string): string;
+//# sourceMappingURL=google-ads.d.ts.map

package/dist/google-ads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"google-ads.d.ts","sourceRoot":"","sources":["../src/google-ads.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAKtE,MAAM,MAAM,yBAAyB,GAAG;IACtC,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAC7B;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAClE;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,yBAAyB,CAAA;CAAE,CAAC;AAE7D,qBAAa,wBAAyB,SAAQ,KAAK;IAG/C,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,SAAS,EAAE,OAAO;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;gBAH9B,OAAO,EAAE,MAAM,EACN,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,OAAO,EAClB,MAAM,EAAE,MAAM,GAAG,IAAI;CAKjC;AAED,qBAAa,yBAAyB;IAIlC,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAJ5B,OAAO,CAAC,WAAW,CAAqD;gBAGrD,MAAM,EAAE,yBAAyB,EACjC,SAAS,GAAE,SAAwB;IAGhD,cAAc,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC,qBAAqB,CAAC;YAuCtE,cAAc;CAsB7B;AAYD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIvD"}

package/dist/google-ads.js

@@ -0,0 +1,159 @@
+import { defaultFetch } from "./http.js";
+const GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token";
+const GOOGLE_ADS_ORIGIN = "https://googleads.googleapis.com";
+export class GoogleAdsConversionError extends Error {
+    code;
+    retryable;
+    status;
+    constructor(message, code, retryable, status) {
+        super(message);
+        this.code = code;
+        this.retryable = retryable;
+        this.status = status;
+        this.name = "GoogleAdsConversionError";
+    }
+}
+export class GoogleAdsConversionClient {
+    config;
+    fetchImpl;
+    accessToken = null;
+    constructor(config, fetchImpl = defaultFetch) {
+        this.config = config;
+        this.fetchImpl = fetchImpl;
+    }
+    async uploadPurchase(event) {
+        const clickId = googleClickId(event);
+        if (!clickId)
+            return { status: "skipped", reason: "missing_google_click_id" };
+        const accessToken = await this.getAccessToken();
+        const customerId = digitsOnly(this.config.customerId, "customerId");
+        const actionId = digitsOnly(this.config.conversionActionId, "conversionActionId");
+        const apiVersion = this.config.apiVersion ?? "v24";
+        const conversion = {
+            conversionAction: `customers/${customerId}/conversionActions/${actionId}`,
+            conversionDateTime: googleAdsDateTime(event.conversionAt),
+            conversionValue: event.value,
+            currencyCode: event.currency,
+            orderId: event.orderId,
+            conversionEnvironment: "WEB",
+            [clickId.kind]: clickId.value,
+        };
+        const headers = {
+            authorization: `Bearer ${accessToken}`,
+            "content-type": "application/json",
+            "developer-token": this.config.developerToken,
+        };
+        if (this.config.loginCustomerId) {
+            headers["login-customer-id"] = digitsOnly(this.config.loginCustomerId, "loginCustomerId");
+        }
+        const response = await this.fetchImpl(`${GOOGLE_ADS_ORIGIN}/${apiVersion}/customers/${customerId}:uploadClickConversions`, { method: "POST", headers, body: JSON.stringify({ conversions: [conversion], partialFailure: true }) });
+        const payload = await readJson(response);
+        if (!response.ok)
+            throw googleAdsHttpError(response.status, payload);
+        const partialFailure = recordValue(payload, "partialFailureError");
+        if (partialFailure)
+            throw googleAdsPartialFailure(partialFailure);
+        return {
+            status: "sent",
+            jobId: stringValue(payload, "jobId"),
+            requestId: response.headers.get("request-id"),
+        };
+    }
+    async getAccessToken() {
+        if (this.accessToken && this.accessToken.expiresAt > Date.now() + 60_000)
+            return this.accessToken.value;
+        const response = await this.fetchImpl(GOOGLE_TOKEN_URL, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({
+                client_id: this.config.clientId,
+                client_secret: this.config.clientSecret,
+                refresh_token: this.config.refreshToken,
+                grant_type: "refresh_token",
+            }),
+        });
+        const payload = await readJson(response);
+        const token = stringValue(payload, "access_token");
+        if (!response.ok || !token) {
+            const code = stringValue(payload, "error") ?? "oauth_refresh_failed";
+            throw new GoogleAdsConversionError(`Google OAuth refresh failed: ${code}`, code, response.status >= 500, response.status);
+        }
+        const expiresIn = numberValue(payload, "expires_in") ?? 3600;
+        this.accessToken = { value: token, expiresAt: Date.now() + expiresIn * 1000 };
+        return token;
+    }
+}
+function googleClickId(event) {
+    const candidates = [
+        ["gclid", event.clickIds.gclid],
+        ["wbraid", event.clickIds.wbraid],
+        ["gbraid", event.clickIds.gbraid],
+    ];
+    for (const [kind, value] of candidates)
+        if (value?.trim())
+            return { kind, value: value.trim() };
+    return null;
+}
+export function googleAdsDateTime(value) {
+    const date = new Date(value);
+    if (!Number.isFinite(date.getTime()))
+        throw new Error("Google Ads conversion time must be a valid date-time");
+    return date.toISOString().replace("T", " ").replace(/\.\d{3}Z$/, "+00:00");
+}
+function digitsOnly(value, field) {
+    const normalized = value.replaceAll("-", "").trim();
+    if (!/^\d+$/.test(normalized))
+        throw new Error(`Google Ads ${field} must contain only digits`);
+    return normalized;
+}
+async function readJson(response) {
+    return (await response.json().catch(() => ({})));
+}
+function googleAdsHttpError(status, payload) {
+    const error = recordValue(payload, "error");
+    const code = stringValue(error ?? payload, "status") ?? `http_${status}`;
+    const message = stringValue(error ?? payload, "message") ?? `Google Ads upload failed with HTTP ${status}`;
+    return new GoogleAdsConversionError(message, code, status === 429 || status >= 500, status);
+}
+function googleAdsPartialFailure(error) {
+    const code = firstGoogleAdsErrorCode(error) ?? "partial_failure";
+    const message = stringValue(error, "message") ?? "Google Ads rejected the conversion";
+    const retryable = ["INTERNAL", "RESOURCE_EXHAUSTED", "UNAVAILABLE", "TOO_RECENT_CONVERSION_ACTION"].includes(code);
+    return new GoogleAdsConversionError(message, code, retryable, 200);
+}
+function firstGoogleAdsErrorCode(error) {
+    const details = error.details;
+    if (!Array.isArray(details))
+        return null;
+    for (const detail of details) {
+        if (!detail || typeof detail !== "object")
+            continue;
+        const errors = detail.errors;
+        if (!Array.isArray(errors))
+            continue;
+        for (const item of errors) {
+            if (!item || typeof item !== "object")
+                continue;
+            const errorCode = recordValue(item, "errorCode");
+            if (!errorCode)
+                continue;
+            for (const value of Object.values(errorCode))
+                if (typeof value === "string")
+                    return value;
+        }
+    }
+    return null;
+}
+function recordValue(input, key) {
+    const value = input[key];
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function stringValue(input, key) {
+    const value = input[key];
+    return typeof value === "string" ? value : typeof value === "number" ? String(value) : null;
+}
+function numberValue(input, key) {
+    const value = input[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+//# sourceMappingURL=google-ads.js.map

package/dist/google-ads.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"google-ads.js","sourceRoot":"","sources":["../src/google-ads.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -4,12 +4,14 @@ export * from "./auth.js";
 export * from "./aws.js";
 export * from "./billing.js";
 export * from "./cloudflare.js";
+export * from "./conversion-outbox.js";
 export * from "./crypto.js";
 export * from "./d1.js";
 export * from "./encoding.js";
 export * from "./email.js";
 export * from "./env.js";
 export * from "./hono.js";
+export * from "./google-ads.js";
 export * from "./http.js";
 export * from "./ids.js";
 export * from "./jobs.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}

package/dist/index.js

@@ -4,12 +4,14 @@ export * from "./auth.js";
 export * from "./aws.js";
 export * from "./billing.js";
 export * from "./cloudflare.js";
+export * from "./conversion-outbox.js";
 export * from "./crypto.js";
 export * from "./d1.js";
 export * from "./encoding.js";
 export * from "./email.js";
 export * from "./env.js";
 export * from "./hono.js";
+export * from "./google-ads.js";
 export * from "./http.js";
 export * from "./ids.js";
 export * from "./jobs.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}

package/docs/conversion-outbox.md

@@ -0,0 +1,39 @@
+# Purchase conversion outbox
+
+Commit the product purchase and its conversion event before calling an ad provider. Create one delivery per configured provider, acknowledge the verified payment webhook, and retry deliveries independently.
+
+```ts
+import { createConversionDelivery, createPurchaseConversionEvent } from "@q32/core/conversion-outbox";
+import { GoogleAdsConversionClient } from "@q32/core/google-ads";
+
+const purchase = createPurchaseConversionEvent({
+  eventId: `purchase:${order.id}`,
+  orderId: order.id,
+  productSlug: "example",
+  conversionAt: order.paidAt,
+  value: order.valueCents / 100,
+  currency: order.currency.toUpperCase(),
+  clickIds: { gclid: attribution.gclid, gbraid: attribution.gbraid, wbraid: attribution.wbraid },
+});
+const googleDelivery = createConversionDelivery(purchase.eventId, "google_ads");
+```
+
+Persist both records atomically with the purchase. The package intentionally does not prescribe D1 or Postgres table names.
+
+Upload with a client shared by the Worker isolate:
+
+```ts
+const google = new GoogleAdsConversionClient({
+  developerToken: env.GOOGLE_ADS_DEVELOPER_TOKEN,
+  clientId: env.GOOGLE_ADS_CLIENT_ID,
+  clientSecret: env.GOOGLE_ADS_CLIENT_SECRET,
+  refreshToken: env.GOOGLE_ADS_REFRESH_TOKEN,
+  customerId: env.GOOGLE_ADS_CUSTOMER_ID,
+  loginCustomerId: env.GOOGLE_ADS_LOGIN_CUSTOMER_ID,
+  conversionActionId: env.GOOGLE_ADS_PURCHASE_CONVERSION_ACTION_ID,
+});
+```
+
+`uploadPurchase` returns `skipped` when no Google click identifier is available. It throws `GoogleAdsConversionError` for provider failures; `retryable` distinguishes transient failures from permanent rejection. Store bounded error details and schedule retry with `nextConversionRetryAt`.
+
+Google requires an `UPLOAD_CLICKS` conversion action, `partialFailure: true`, and a unique order ID per conversion action. Keep browser purchase events when useful for diagnostics, but do not make the durable upload depend on a success-page visit.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@q32/core",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Shared TypeScript primitives for Q32 Cloudflare Worker projects.",
   "license": "MIT",
   "type": "module",
@@ -44,6 +44,10 @@
       "types": "./dist/cloudflare.d.ts",
       "default": "./dist/cloudflare.js"
     },
+    "./conversion-outbox": {
+      "types": "./dist/conversion-outbox.d.ts",
+      "default": "./dist/conversion-outbox.js"
+    },
     "./crypto": {
       "types": "./dist/crypto.d.ts",
       "default": "./dist/crypto.js"
@@ -72,6 +76,10 @@
       "types": "./dist/hono.d.ts",
       "default": "./dist/hono.js"
     },
+    "./google-ads": {
+      "types": "./dist/google-ads.d.ts",
+      "default": "./dist/google-ads.js"
+    },
     "./http": {
       "types": "./dist/http.d.ts",
       "default": "./dist/http.js"

package/src/conversion-outbox.ts

@@ -0,0 +1,90 @@
+export type ConversionProvider = "google_ads" | "meta" | "microsoft_ads";
+export type ConversionDeliveryStatus = "pending" | "sending" | "sent" | "retry" | "dead" | "skipped";
+
+export type AdClickIds = {
+  gclid?: string | null;
+  gbraid?: string | null;
+  wbraid?: string | null;
+  fbclid?: string | null;
+  msclkid?: string | null;
+};
+
+export type PurchaseConversionEvent = {
+  eventId: string;
+  orderId: string;
+  productSlug: string;
+  conversionAt: string;
+  value: number;
+  currency: string;
+  clickIds: AdClickIds;
+  emailSha256?: string | null;
+  sourceUrl?: string | null;
+  metadata?: Record<string, unknown>;
+};
+
+export type ConversionDelivery = {
+  deliveryKey: string;
+  eventId: string;
+  provider: ConversionProvider;
+  status: ConversionDeliveryStatus;
+  attemptCount: number;
+  nextAttemptAt: string | null;
+  sentAt: string | null;
+  lastErrorCode: string | null;
+  lastErrorMessage: string | null;
+};
+
+export function createPurchaseConversionEvent(input: PurchaseConversionEvent): PurchaseConversionEvent {
+  if (!input.eventId.trim()) throw new Error("Purchase conversion eventId is required");
+  if (!input.orderId.trim()) throw new Error("Purchase conversion orderId is required");
+  if (!input.productSlug.trim()) throw new Error("Purchase conversion productSlug is required");
+  if (!Number.isFinite(input.value) || input.value < 0) throw new Error("Purchase conversion value must be non-negative");
+  if (!/^[A-Z]{3}$/.test(input.currency)) throw new Error("Purchase conversion currency must be a three-letter uppercase code");
+  if (!Number.isFinite(Date.parse(input.conversionAt))) throw new Error("Purchase conversion conversionAt must be an ISO date-time");
+  return {
+    ...input,
+    eventId: input.eventId.trim(),
+    orderId: input.orderId.trim(),
+    productSlug: input.productSlug.trim(),
+    clickIds: compactClickIds(input.clickIds),
+  };
+}
+
+export function conversionDeliveryKey(eventId: string, provider: ConversionProvider): string {
+  if (!eventId.trim()) throw new Error("Conversion delivery eventId is required");
+  return `${eventId.trim()}:${provider}`;
+}
+
+export function createConversionDelivery(eventId: string, provider: ConversionProvider): ConversionDelivery {
+  return {
+    deliveryKey: conversionDeliveryKey(eventId, provider),
+    eventId: eventId.trim(),
+    provider,
+    status: "pending",
+    attemptCount: 0,
+    nextAttemptAt: null,
+    sentAt: null,
+    lastErrorCode: null,
+    lastErrorMessage: null,
+  };
+}
+
+export function nextConversionRetryAt(
+  attemptCount: number,
+  options: { now?: number; baseDelayMs?: number; maxDelayMs?: number } = {},
+): string {
+  if (!Number.isInteger(attemptCount) || attemptCount < 1) throw new Error("Conversion attemptCount must be a positive integer");
+  const baseDelayMs = options.baseDelayMs ?? 30_000;
+  const maxDelayMs = options.maxDelayMs ?? 24 * 60 * 60 * 1000;
+  const delay = Math.min(maxDelayMs, baseDelayMs * 2 ** Math.min(attemptCount - 1, 20));
+  return new Date((options.now ?? Date.now()) + delay).toISOString();
+}
+
+function compactClickIds(input: AdClickIds): AdClickIds {
+  return Object.fromEntries(
+    Object.entries(input).flatMap(([key, value]) => {
+      const normalized = value?.trim();
+      return normalized ? [[key, normalized]] : [];
+    }),
+  );
+}

package/src/google-ads.ts

@@ -0,0 +1,176 @@
+import type { FetchLike } from "./http.js";
+import { defaultFetch } from "./http.js";
+import type { PurchaseConversionEvent } from "./conversion-outbox.js";
+
+const GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token";
+const GOOGLE_ADS_ORIGIN = "https://googleads.googleapis.com";
+
+export type GoogleAdsConversionConfig = {
+  developerToken: string;
+  clientId: string;
+  clientSecret: string;
+  refreshToken: string;
+  customerId: string;
+  conversionActionId: string;
+  loginCustomerId?: string;
+  apiVersion?: string;
+};
+
+export type GoogleAdsUploadResult =
+  | { status: "sent"; jobId: string | null; requestId: string | null }
+  | { status: "skipped"; reason: "missing_google_click_id" };
+
+export class GoogleAdsConversionError extends Error {
+  constructor(
+    message: string,
+    readonly code: string,
+    readonly retryable: boolean,
+    readonly status: number | null,
+  ) {
+    super(message);
+    this.name = "GoogleAdsConversionError";
+  }
+}
+
+export class GoogleAdsConversionClient {
+  private accessToken: { value: string; expiresAt: number } | null = null;
+
+  constructor(
+    private readonly config: GoogleAdsConversionConfig,
+    private readonly fetchImpl: FetchLike = defaultFetch,
+  ) {}
+
+  async uploadPurchase(event: PurchaseConversionEvent): Promise<GoogleAdsUploadResult> {
+    const clickId = googleClickId(event);
+    if (!clickId) return { status: "skipped", reason: "missing_google_click_id" };
+    const accessToken = await this.getAccessToken();
+    const customerId = digitsOnly(this.config.customerId, "customerId");
+    const actionId = digitsOnly(this.config.conversionActionId, "conversionActionId");
+    const apiVersion = this.config.apiVersion ?? "v24";
+    const conversion = {
+      conversionAction: `customers/${customerId}/conversionActions/${actionId}`,
+      conversionDateTime: googleAdsDateTime(event.conversionAt),
+      conversionValue: event.value,
+      currencyCode: event.currency,
+      orderId: event.orderId,
+      conversionEnvironment: "WEB",
+      [clickId.kind]: clickId.value,
+    };
+    const headers: Record<string, string> = {
+      authorization: `Bearer ${accessToken}`,
+      "content-type": "application/json",
+      "developer-token": this.config.developerToken,
+    };
+    if (this.config.loginCustomerId) {
+      headers["login-customer-id"] = digitsOnly(this.config.loginCustomerId, "loginCustomerId");
+    }
+    const response = await this.fetchImpl(
+      `${GOOGLE_ADS_ORIGIN}/${apiVersion}/customers/${customerId}:uploadClickConversions`,
+      { method: "POST", headers, body: JSON.stringify({ conversions: [conversion], partialFailure: true }) },
+    );
+    const payload = await readJson(response);
+    if (!response.ok) throw googleAdsHttpError(response.status, payload);
+    const partialFailure = recordValue(payload, "partialFailureError");
+    if (partialFailure) throw googleAdsPartialFailure(partialFailure);
+    return {
+      status: "sent",
+      jobId: stringValue(payload, "jobId"),
+      requestId: response.headers.get("request-id"),
+    };
+  }
+
+  private async getAccessToken(): Promise<string> {
+    if (this.accessToken && this.accessToken.expiresAt > Date.now() + 60_000) return this.accessToken.value;
+    const response = await this.fetchImpl(GOOGLE_TOKEN_URL, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        client_id: this.config.clientId,
+        client_secret: this.config.clientSecret,
+        refresh_token: this.config.refreshToken,
+        grant_type: "refresh_token",
+      }),
+    });
+    const payload = await readJson(response);
+    const token = stringValue(payload, "access_token");
+    if (!response.ok || !token) {
+      const code = stringValue(payload, "error") ?? "oauth_refresh_failed";
+      throw new GoogleAdsConversionError(`Google OAuth refresh failed: ${code}`, code, response.status >= 500, response.status);
+    }
+    const expiresIn = numberValue(payload, "expires_in") ?? 3600;
+    this.accessToken = { value: token, expiresAt: Date.now() + expiresIn * 1000 };
+    return token;
+  }
+}
+
+function googleClickId(event: PurchaseConversionEvent): { kind: "gclid" | "wbraid" | "gbraid"; value: string } | null {
+  const candidates = [
+    ["gclid", event.clickIds.gclid],
+    ["wbraid", event.clickIds.wbraid],
+    ["gbraid", event.clickIds.gbraid],
+  ] as const;
+  for (const [kind, value] of candidates) if (value?.trim()) return { kind, value: value.trim() };
+  return null;
+}
+
+export function googleAdsDateTime(value: string): string {
+  const date = new Date(value);
+  if (!Number.isFinite(date.getTime())) throw new Error("Google Ads conversion time must be a valid date-time");
+  return date.toISOString().replace("T", " ").replace(/\.\d{3}Z$/, "+00:00");
+}
+
+function digitsOnly(value: string, field: string): string {
+  const normalized = value.replaceAll("-", "").trim();
+  if (!/^\d+$/.test(normalized)) throw new Error(`Google Ads ${field} must contain only digits`);
+  return normalized;
+}
+
+async function readJson(response: Response): Promise<Record<string, unknown>> {
+  return (await response.json().catch(() => ({}))) as Record<string, unknown>;
+}
+
+function googleAdsHttpError(status: number, payload: Record<string, unknown>): GoogleAdsConversionError {
+  const error = recordValue(payload, "error");
+  const code = stringValue(error ?? payload, "status") ?? `http_${status}`;
+  const message = stringValue(error ?? payload, "message") ?? `Google Ads upload failed with HTTP ${status}`;
+  return new GoogleAdsConversionError(message, code, status === 429 || status >= 500, status);
+}
+
+function googleAdsPartialFailure(error: Record<string, unknown>): GoogleAdsConversionError {
+  const code = firstGoogleAdsErrorCode(error) ?? "partial_failure";
+  const message = stringValue(error, "message") ?? "Google Ads rejected the conversion";
+  const retryable = ["INTERNAL", "RESOURCE_EXHAUSTED", "UNAVAILABLE", "TOO_RECENT_CONVERSION_ACTION"].includes(code);
+  return new GoogleAdsConversionError(message, code, retryable, 200);
+}
+
+function firstGoogleAdsErrorCode(error: Record<string, unknown>): string | null {
+  const details = error.details;
+  if (!Array.isArray(details)) return null;
+  for (const detail of details) {
+    if (!detail || typeof detail !== "object") continue;
+    const errors = (detail as Record<string, unknown>).errors;
+    if (!Array.isArray(errors)) continue;
+    for (const item of errors) {
+      if (!item || typeof item !== "object") continue;
+      const errorCode = recordValue(item as Record<string, unknown>, "errorCode");
+      if (!errorCode) continue;
+      for (const value of Object.values(errorCode)) if (typeof value === "string") return value;
+    }
+  }
+  return null;
+}
+
+function recordValue(input: Record<string, unknown>, key: string): Record<string, unknown> | null {
+  const value = input[key];
+  return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : null;
+}
+
+function stringValue(input: Record<string, unknown>, key: string): string | null {
+  const value = input[key];
+  return typeof value === "string" ? value : typeof value === "number" ? String(value) : null;
+}
+
+function numberValue(input: Record<string, unknown>, key: string): number | null {
+  const value = input[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}

package/src/index.ts

@@ -4,12 +4,14 @@ export * from "./auth.js";
 export * from "./aws.js";
 export * from "./billing.js";
 export * from "./cloudflare.js";
+export * from "./conversion-outbox.js";
 export * from "./crypto.js";
 export * from "./d1.js";
 export * from "./encoding.js";
 export * from "./email.js";
 export * from "./env.js";
 export * from "./hono.js";
+export * from "./google-ads.js";
 export * from "./http.js";
 export * from "./ids.js";
 export * from "./jobs.js";