tatvic-implementation-sdk 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,103 @@
-# Temporary Holding Version
+# Tatvic Universal First-Party App Wrapper & Morphed GTM Loader
 
-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.
+A zero-configuration, universal wrapper that converts all third-party analytics and tracking requests into **first-party requests**, preventing client-side ad blockers (like Brave Shields, uBlock Origin, and AdGuard) from blocking them.
+
+> 📖 **Looking for a deep-dive, framework-agnostic developer guide?**  
+> See the [Comprehensive Framework-Agnostic Developer Integration Guide (Normal vs. Server-Side sGTM)](./docs/INTEGRATION_GUIDE.md).
+
+---
+
+## 🎯 The Problem Solved
+
+Standard Google Tag Manager scripts request `https://www.googletagmanager.com/gtm.js`. Ad blockers immediately flag and block this request:
+1. `googletagmanager.com/gtm.js` is blocked at the network layer.
+2. Internal Google endpoints (`adservice.google.com`, `doubleclick.net`, `google-analytics.com`) called inside the container are blocked.
+
+### The Solution: Morphed First-Party Loader
+This SDK introduces a **Morphed First-Party GTM Loader** (`/_tatvic/gtm.js`):
+1. **First-Party Script Delivery:** Loads `gtm.js` from your own domain (`/_tatvic/gtm.js?id=GTM-XXXX`).
+2. **AST / Endpoint Morphing:** The server fetches Google's container server-to-server and dynamically rewrites internal tracking endpoints to route through your first-party relay (`/_tatvic/relay`).
+3. **Preserves Tag Assistant Preview & Debug Mode:**
+   - Detects `gtm_debug`, `gtm_auth`, `gtm_preview`, and `gtm_cookies_win` parameters.
+   - Forwards them upstream so Google serves the workspace draft container.
+   - Bypasses caching in debug mode (`Cache-Control: no-cache, no-store`).
+   - Keeps `tagassistant.google.com` postMessage handshake intact so Tag Assistant connects instantly.
+
+---
+
+## 🚀 Usage
+
+### 1. Plain HTML / PHP / WordPress
+
+```html
+<!-- 1. Load Tatvic Standalone Script in <head> -->
+<script src="/dist/tatvic.js"></script>
+
+<!-- 2. Wrap your entire application -->
+<tatvic-wrapper>
+  <!-- Morphed First-Party GTM Script (Zero Shields block!) -->
+  <script async src="/_tatvic/gtm.js?id=GTM-T32XGF8F"></script>
+  <script>
+    window.dataLayer = window.dataLayer || [];
+    function gtag(){dataLayer.push(arguments);}
+    gtag('js', new Date());
+  </script>
+
+  <!-- Your app code and buttons -->
+</tatvic-wrapper>
+```
+
+> **Note:** If you keep the original Google URL `<script async src="https://www.googletagmanager.com/gtm.js?id=GTM-T32XGF8F"></script>`, `<tatvic-wrapper>` will automatically intercept and morph it to `/_tatvic/gtm.js` at runtime!
+
+---
+
+### 2. React (Vite / CRA / Remix)
+
+```tsx
+import { TatvicWrapper } from 'tatvic-implementation-sdk';
+
+export default function Root() {
+  return (
+    <TatvicWrapper>
+      <App />
+    </TatvicWrapper>
+  );
+}
+```
+
+---
+
+### 3. Next.js (App Router)
+
+In `app/layout.tsx`:
+```tsx
+import { TatvicWrapper } from 'tatvic-implementation-sdk';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <script async src="/_tatvic/gtm.js?id=GTM-T32XGF8F" />
+      </head>
+      <body>
+        <TatvicWrapper>
+          {children}
+        </TatvicWrapper>
+      </body>
+    </html>
+  );
+}
+```
+
+In `app/_tatvic/[...path]/route.ts` or `app/_tatvic/relay/route.ts`:
+```typescript
+import { tatvicRelayRoute } from 'tatvic-implementation-sdk';
+export const { GET, POST, OPTIONS } = tatvicRelayRoute();
+```
+
+---
+
+### 4. Server-Side Morphed GTM Endpoints
+
+* **Node / Express / Bun:** Handled automatically by `createProxyHandler()` and `tatvicExpressMiddleware()`.
+* **PHP / WordPress:** Handled automatically by [`src/php/tatvic-proxy.php`](file:///home/jimitchavda/Jotaro/bakhodi/tatvic-implementation-sdk/src/php/tatvic-proxy.php).

package/dist/bundle.d.ts

@@ -0,0 +1,3 @@
+import { initFirstPartyWrapper, uninstallFirstPartyWrapper } from './index.js';
+import './custom-element.js';
+export { initFirstPartyWrapper, uninstallFirstPartyWrapper };

package/dist/custom-element.d.ts

@@ -0,0 +1,17 @@
+declare const TatvicWrapperElement_base: {
+    new (): HTMLElement;
+    prototype: HTMLElement;
+};
+/**
+ * Standard Web Component: <tatvic-wrapper>
+ *
+ * Allows wrapping the entire application in any framework or plain HTML/PHP:
+ *
+ * <tatvic-wrapper>
+ *   <app>...</app>
+ * </tatvic-wrapper>
+ */
+export declare class TatvicWrapperElement extends TatvicWrapperElement_base {
+    connectedCallback(): void;
+}
+export {};

package/dist/defaults.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Comprehensive pre-configured lists for zero-configuration setup.
+ */
+export declare const DEFAULT_PROXY_ENDPOINT = "/_tatvic/relay";
+export declare const DEFAULT_HEADER_NAME = "x-tatvic-target";
+/**
+ * Pre-configured list of all major third-party tracking, analytics, and advertising domains.
+ */
+export declare const DEFAULT_TARGET_DOMAINS: (string | RegExp)[];
+/**
+ * Sensitive services that must NEVER be intercepted (payment, auth, core cloud).
+ */
+export declare const DEFAULT_EXCLUDE_DOMAINS: (string | RegExp)[];

package/dist/express.d.ts

@@ -0,0 +1,28 @@
+import type { ServerProxyOptions } from './types.js';
+interface ExpressLikeRequest {
+    method: string;
+    url?: string;
+    originalUrl?: string;
+    headers: Record<string, string | string[] | undefined>;
+    body?: any;
+}
+interface ExpressLikeResponse {
+    status(code: number): this;
+    setHeader(name: string, value: string): this;
+    end(chunk?: any): void;
+    send(body?: any): void;
+}
+/**
+ * Express / Connect / Node.js middleware for the Tatvic First-Party Relay.
+ *
+ * Usage:
+ * ```typescript
+ * import express from 'express';
+ * import { tatvicExpressMiddleware } from 'tatvic-implementation-sdk/express';
+ *
+ * const app = express();
+ * app.use('/_tatvic/relay', tatvicExpressMiddleware());
+ * ```
+ */
+export declare function tatvicExpressMiddleware(options?: ServerProxyOptions): (req: ExpressLikeRequest, res: ExpressLikeResponse, next?: (err?: any) => void) => Promise<void>;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+import { RequestInterceptor } from './interceptor.js';
+import type { ProxySdkOptions } from './types.js';
+export * from './types.js';
+export * from './defaults.js';
+export * from './url-matcher.js';
+export * from './interceptor.js';
+export * from './server-proxy.js';
+export * from './morph-gtm.js';
+export * from './custom-element.js';
+export * from './react.js';
+export * from './next.js';
+export * from './express.js';
+/**
+ * Initialize the First-Party Request Wrapper SDK.
+ *
+ * Intercepts outgoing tracking/analytics requests (fetch, XMLHttpRequest, sendBeacon)
+ * and transparently routes them to your first-party relay endpoint.
+ *
+ * Zero-config: All standard analytics/tracking domains are enabled by default.
+ *
+ * @param options Configuration options (optional)
+ * @returns The active RequestInterceptor instance.
+ */
+export declare function initFirstPartyWrapper(options?: ProxySdkOptions): RequestInterceptor;
+/**
+ * Restore original native browser APIs and uninstall the wrapper.
+ */
+export declare function uninstallFirstPartyWrapper(): void;