rename lib/conversion to lib/capi; fix exports

src/lib/capi/connector.ts

@@ -0,0 +1,97 @@
+import { dev } from '$app/environment';
+import log from 'loglevel';
+import type { CAPIEvent } from './event.ts';
+
+const GRAPH_VERSION = 'v24.0';
+
+/**
+ * Response body from Meta Conversion API after sending events.
+ */
+export type CAPIRequestResponseBody = {
+	/** Dataset or Pixel ID to which the event successfully posted. */
+	pixelID: string;
+	/** fbtrace_id for debugging purposes. */
+	fbtrace_id: string;
+	/** Number of events received that were sent by the request. */
+	receivedEvents: number;
+	/** Number of events successfully posted by the request. */
+	processedEvents: number;
+	/** Messages returned by the server. */
+	messages: string[];
+};
+
+/**
+ * Connector class for Meta Conversion API (CAPI). Abstraction over direct HTTP
+ * requests to Meta's CAPI endpoint.
+ *
+ * See https://developers.facebook.com/docs/marketing-api/conversions-api/get-started
+ * for more information.
+ */
+export class CAPIConnector {
+	private _accessToken: string;
+	private _pixelID: string;
+	private _testEventCode?: string;
+
+	/**
+	 * Creates a new MCAPIControl instance.
+	 *
+	 * @param accessToken - Your Meta Pixel Conversion API access token.
+	 * @param pixelID - Your Meta Pixel ID.
+	 * @param testEventCode - Optional test event code used for all events if provided.
+	 */
+	constructor(accessToken: string, pixelID: string, testEventCode?: string) {
+		this._accessToken = accessToken;
+		this._pixelID = pixelID;
+		this._testEventCode = testEventCode;
+	}
+
+	/**
+	 * Sends conversion events to the Meta Conversion API.
+	 *
+	 * @param events - Array of CAPIEvent instances to send.
+	 * @returns The response from the Meta CAPI.
+	 * @throws Will throw an error if the request fails or the API returns an error.
+	 */
+	async sendEvents(events: CAPIEvent[]): Promise<CAPIRequestResponseBody> {
+		if (dev && !this._testEventCode) {
+			log.warn(
+				`[CAPIConnector] Sending ${events.length} event(s) in dev mode without a test event code. ` +
+					'Consider providing a test event code to avoid affecting real data.'
+			);
+		}
+
+		const url = `https://graph.facebook.com/${GRAPH_VERSION}/${this._pixelID}/events?access_token=${this._accessToken}`;
+
+		const body = {
+			data: events.map((e) => e.toObject()),
+			test_event_code: this._testEventCode
+		};
+
+		const resp = await fetch(url, {
+			method: 'POST',
+			headers: {
+				'Content-Type': 'application/json'
+			},
+			body: JSON.stringify(body)
+		});
+		const json = await resp.json();
+		console.log('CAPI response:', json);
+
+		if (!resp.ok) {
+			throw new Error(`Meta CAPI error ${resp.status}: ${JSON.stringify(json, null, 2)}`);
+		}
+
+		return {} as CAPIRequestResponseBody;
+	}
+
+	/**
+	 * Shorthand for sending a single event to the Meta Conversion API.
+	 *
+	 * @param event - The CAPIEvent instance to send.
+	 * @returns The response from the Meta CAPI.
+	 * @throws Will throw an error if the request fails or the API returns an error.
+	 */
+	async trackEvent(event: CAPIEvent): Promise<CAPIRequestResponseBody> {
+		return this.sendEvents([event]);
+	}
+}