@traqio/core 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Khufu FZCO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,70 @@
-# Temporary Holding Version
+# @traqio/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The platform-neutral JavaScript engine of the [Traqio](https://traqio.app) SDKs:
+a persisted offline event queue with batching and retries, SKAdNetwork conversion
+values, Apple Ads attribution and deep-link resolution. No advertising id (IDFA /
+GAID) unless the host opts in (`collectAdvertisingId`, read through the native bridge,
+never prompting), no fingerprinting, no pasteboard — the device id is a random
+first-party id.
+
+It has no React Native, Expo or browser dependency: everything platform-specific
+(the Google Play Install Referrer, SKAdNetwork) arrives through a native bridge.
+**Most apps should not install it directly** — install the package for your
+platform, which includes it:
+
+| Your app | Install |
+| --- | --- |
+| Expo | `@traqio/expo` |
+| React Native | `@traqio/react-native` |
+| Capacitor / Ionic | `@traqio/capacitor` |
+
+## Install
+
+```bash
+npm install @traqio/core
+```
+
+## Initialize
+
+```ts
+import { Traqio } from "@traqio/core";
+
+await Traqio.init({
+  sdkKey: "YOUR_SDK_KEY",              // from the Traqio console — public by design
+  endpoint: "https://api.traqio.app",  // origin only
+  storage,                             // { getItem, setItem } — makes the install fire once
+  native,                              // a NativeBridge; without one there is no attribution
+});
+```
+
+## Track events
+
+```ts
+Traqio.setUserId(user.id); // the same id you give RevenueCat (app_user_id)
+
+Traqio.track("purchase", {
+  value: 9.99,
+  currency: "EUR",
+  transactionId: purchase.transactionId, // the store's id: counts the purchase once
+});
+```
+
+Use the event names Meta and TikTok can optimise on (`purchase`, `signup`,
+`subscribe`, `trial`, `add_to_cart`, `checkout`…) — any other name is stored but
+reaches the networks as a custom event.
+
+## Requirements
+
+- A JavaScript runtime with `fetch`.
+- Persistent storage passed as `storage` (React Native's AsyncStorage is picked up
+  automatically when installed).
+
+## Documentation
+
+The full API reference — every `init` option, `trackAdRevenue`, `setConsent`,
+`forgetMe`, deep links, the native bridge — is at
+**https://traqio.app/docs/sdks/javascript**.
+
+## License
+
+MIT

package/build/adservices.d.ts

@@ -0,0 +1,31 @@
+/** Native surface the Expo module exposes. Absent on Android and pre-iOS 14.3. */
+export interface AdServicesNative {
+    /** The opaque 24h token, or null when the framework has none on this device. */
+    getAttributionToken(): Promise<string | null>;
+}
+export interface AdServicesOptions {
+    endpoint: string;
+    sdkKey: string;
+    deviceId?: string;
+    userId?: string;
+    native?: AdServicesNative;
+    /** Same store the event queue uses, so "already sent" survives a restart. */
+    storage?: {
+        getItem(key: string): Promise<string | null>;
+        setItem(key: string, value: string): Promise<void>;
+    };
+    /** Injectable for tests; defaults to the global fetch. */
+    fetchFn?: typeof fetch;
+}
+export declare const ADSERVICES_SENT_KEY = "traq_adservices_sent";
+export declare const ADSERVICES_ATTEMPTS_KEY = "traq_adservices_attempts";
+/**
+ * Hand the token over, at most once per install.
+ *
+ * Returns what happened, so a host app can debug the integration without reading our
+ * logs. Never throws: there is no user-visible consequence to any outcome here, and
+ * an exception in `init()` would take the whole SDK down for a signal most installs
+ * do not have.
+ */
+export declare function reportAdServicesToken(opts: AdServicesOptions): Promise<"sent" | "already-sent" | "no-token" | "unsupported" | "post-failed">;
+//# sourceMappingURL=adservices.d.ts.map

package/build/adservices.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adservices.d.ts","sourceRoot":"","sources":["../src/adservices.ts"],"names":[],"mappings":"AAmBA,kFAAkF;AAClF,MAAM,WAAW,gBAAgB;IAC/B,gFAAgF;IAChF,mBAAmB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC/C;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,6EAA6E;IAC7E,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;QAAC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC;IAC/G,0DAA0D;IAC1D,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACxB;AAED,eAAO,MAAM,mBAAmB,yBAAyB,CAAC;AAC1D,eAAO,MAAM,uBAAuB,6BAA6B,CAAC;AAUlE;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,MAAM,GAAG,cAAc,GAAG,UAAU,GAAG,aAAa,GAAG,aAAa,CAAC,CA2C/E"}

package/build/adservices.js

@@ -0,0 +1,101 @@
+"use strict";
+// Apple Ads (Search Ads) attribution — the JS half.
+//
+// What it buys: the one DETERMINISTIC attribution iOS still allows. Every other iOS
+// signal is SKAdNetwork, which is aggregated, six bits wide and 24h+ late. Apple
+// Search Ads self-attributes through the AdServices framework, and any developer may
+// resolve their own app's tokens — no partner programme, no allowlist.
+//
+// What it is NOT: an identifier. `AAAttribution.attributionToken()` returns an
+// opaque, single-purpose claim ticket valid for **24 hours**. No IDFA, no ATT prompt
+// of our own, no fingerprinting. Apple decides how much of the answer to return from
+// the ATT status the user already chose — detailed with consent, standard without.
+//
+// Why the SERVER resolves it: Apple answers 404 until the token is known on its side,
+// which right after an install is the normal first answer. That retry has to outlive
+// the app process, so the device's only job is to hand the token over before it
+// expires. See apps/api/src/apple-ads/.
+//
+// https://developer.apple.com/documentation/adservices
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ADSERVICES_ATTEMPTS_KEY = exports.ADSERVICES_SENT_KEY = void 0;
+exports.reportAdServicesToken = reportAdServicesToken;
+exports.ADSERVICES_SENT_KEY = "traq_adservices_sent";
+exports.ADSERVICES_ATTEMPTS_KEY = "traq_adservices_attempts";
+/**
+ * How many launches we keep asking before giving up on this install. The framework
+ * can answer later in an install's life, but on a device where it never will —
+ * a simulator, an install with no attribution record at all, which is MOST installs —
+ * asking forever is work with no answer to it.
+ */
+const MAX_ATTEMPTS = 5;
+/**
+ * Hand the token over, at most once per install.
+ *
+ * Returns what happened, so a host app can debug the integration without reading our
+ * logs. Never throws: there is no user-visible consequence to any outcome here, and
+ * an exception in `init()` would take the whole SDK down for a signal most installs
+ * do not have.
+ */
+async function reportAdServicesToken(opts) {
+    if (!opts.native?.getAttributionToken)
+        return "unsupported";
+    if (await read(opts, exports.ADSERVICES_SENT_KEY))
+        return "already-sent";
+    let token = null;
+    try {
+        token = await opts.native.getAttributionToken();
+    }
+    catch {
+        // The framework throws on a device with nothing to give. Treated as "no token".
+    }
+    if (!token || !token.trim()) {
+        const attempts = Number(await read(opts, exports.ADSERVICES_ATTEMPTS_KEY)) || 0;
+        await write(opts, exports.ADSERVICES_ATTEMPTS_KEY, String(attempts + 1));
+        // Bounded: stop asking a device that will never answer.
+        if (attempts + 1 >= MAX_ATTEMPTS)
+            await write(opts, exports.ADSERVICES_SENT_KEY, "1");
+        return "no-token";
+    }
+    const doFetch = opts.fetchFn ?? (typeof fetch === "function" ? fetch : undefined);
+    if (!doFetch)
+        return "post-failed";
+    try {
+        const res = await doFetch(`${opts.endpoint}/ingest/adservices`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                sdkKey: opts.sdkKey,
+                token: token.trim(),
+                deviceId: opts.deviceId,
+                appUserId: opts.userId,
+            }),
+        });
+        if (!res.ok)
+            return "post-failed";
+    }
+    catch {
+        return "post-failed";
+    }
+    // Only mark sent on success, so a failed post retries on the next launch — inside
+    // the 24h window, which is what makes the retry worth anything.
+    await write(opts, exports.ADSERVICES_SENT_KEY, "1");
+    return "sent";
+}
+async function read(opts, key) {
+    try {
+        return (await opts.storage?.getItem(key)) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+async function write(opts, key, value) {
+    try {
+        await opts.storage?.setItem(key, value);
+    }
+    catch {
+        /* storage full/unavailable */
+    }
+}
+//# sourceMappingURL=adservices.js.map

package/build/adservices.js.map

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

package/build/deeplink.d.ts

@@ -0,0 +1,29 @@
+/** Where a link wants the app to land. */
+export interface DeepLink {
+    /**
+     * The destination set on the link in the console — an in-app path
+     * ("/product/42") or an app URL ("myapp://product/42"). Null when the link
+     * carries none: the app still learns WHICH link brought the user (`code`).
+     */
+    deepLink: string | null;
+    /** The link's slug (the `<code>` of `/c/<code>`). */
+    code: string | null;
+    /** True when the link was tapped BEFORE the install; false when it opened the app. */
+    deferred: boolean;
+    /** How it was resolved. `ip_match` is a probabilistic guess — see the docs. */
+    via: "referrer" | "ip_match" | "link";
+    /** The URL that opened the app (direct opens only). */
+    url?: string;
+}
+/** What `/deeplink/deferred` and `/deeplink/open` answer. */
+export interface DeepLinkAnswer {
+    matched: boolean;
+    via: "referrer" | "ip_match" | "link" | null;
+    code: string | null;
+    deepLink: string | null;
+}
+/** True when `url` is one of our tracking links (`http(s)://<host>/c/<code>`). */
+export declare function isTrackingUrl(url: string): boolean;
+/** An API answer → the callback's shape, or null when nothing matched. */
+export declare function toDeepLink(answer: DeepLinkAnswer | null, deferred: boolean, url?: string): DeepLink | null;
+//# sourceMappingURL=deeplink.d.ts.map

package/build/deeplink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deeplink.d.ts","sourceRoot":"","sources":["../src/deeplink.ts"],"names":[],"mappings":"AAcA,0CAA0C;AAC1C,MAAM,WAAW,QAAQ;IACvB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,qDAAqD;IACrD,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,sFAAsF;IACtF,QAAQ,EAAE,OAAO,CAAC;IAClB,+EAA+E;IAC/E,GAAG,EAAE,UAAU,GAAG,UAAU,GAAG,MAAM,CAAC;IACtC,uDAAuD;IACvD,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,6DAA6D;AAC7D,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,EAAE,UAAU,GAAG,UAAU,GAAG,MAAM,GAAG,IAAI,CAAC;IAC7C,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAMD,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAGlD;AAED,0EAA0E;AAC1E,wBAAgB,UAAU,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAG1G"}

package/build/deeplink.js

@@ -0,0 +1,32 @@
+"use strict";
+// Deep linking — the SDK half (docs/DEEP_LINKING.md).
+//
+// Two moments, one callback:
+//   - DIRECT: a universal link / App Link (`https://<your host>/c/<code>`) opened
+//     the installed app. The OS never hit our server, so the SDK resolves the
+//     code — which also records the click the OS skipped.
+//   - DEFERRED: the app was installed FROM a link. On the very first launch the
+//     SDK asks where that link wanted the user to land. Android answers from the
+//     Play Install Referrer (deterministic); iOS only when the app opted into the
+//     IP match in the console (probabilistic, off by default).
+//
+// Privacy: nothing new leaves the device. The referrer is already sent with the
+// install; the URL is the one that opened the app. No pasteboard, no IDFA.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTrackingUrl = isTrackingUrl;
+exports.toDeepLink = toDeepLink;
+// Mirrors `parseTrackingUrl` in apps/api/src/tracking/link-rules.ts. Checked on
+// the device so the app's OWN URLs (most of what opens an app) never leave it.
+const TRACKING_PATH = /^\/c\/[A-Za-z0-9_-]{1,50}\/?$/;
+/** True when `url` is one of our tracking links (`http(s)://<host>/c/<code>`). */
+function isTrackingUrl(url) {
+    const m = /^https?:\/\/[^/?#]+(\/[^?#]*)?/i.exec(url);
+    return Boolean(m && TRACKING_PATH.test(m[1] ?? ""));
+}
+/** An API answer → the callback's shape, or null when nothing matched. */
+function toDeepLink(answer, deferred, url) {
+    if (!answer?.matched || !answer.via)
+        return null;
+    return { deepLink: answer.deepLink, code: answer.code, deferred, via: answer.via, ...(url ? { url } : {}) };
+}
+//# sourceMappingURL=deeplink.js.map

package/build/deeplink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deeplink.js","sourceRoot":"","sources":["../src/deeplink.ts"],"names":[],"mappings":";AAAA,sDAAsD;AACtD,EAAE;AACF,6BAA6B;AAC7B,kFAAkF;AAClF,8EAA8E;AAC9E,0DAA0D;AAC1D,gFAAgF;AAChF,iFAAiF;AACjF,kFAAkF;AAClF,+DAA+D;AAC/D,EAAE;AACF,gFAAgF;AAChF,2EAA2E;;AAiC3E,sCAGC;AAGD,gCAGC;AAdD,gFAAgF;AAChF,+EAA+E;AAC/E,MAAM,aAAa,GAAG,+BAA+B,CAAC;AAEtD,kFAAkF;AAClF,SAAgB,aAAa,CAAC,GAAW;IACvC,MAAM,CAAC,GAAG,iCAAiC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtD,OAAO,OAAO,CAAC,CAAC,IAAI,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;AACtD,CAAC;AAED,0EAA0E;AAC1E,SAAgB,UAAU,CAAC,MAA6B,EAAE,QAAiB,EAAE,GAAY;IACvF,IAAI,CAAC,MAAM,EAAE,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AAC9G,CAAC"}