npm - @consentx/angular - Versions diffs - 1.0.0 - Mend

@consentx/angular 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (33) hide show

package/CHANGELOG.md +22 -0
package/LICENSE +21 -0
package/README.md +221 -0
package/assets/consentx-logo.svg +550 -0
package/dist/LICENSE +21 -0
package/dist/README.md +221 -0
package/dist/assets/consentx-logo.svg +550 -0
package/dist/esm2022/consentx-angular.mjs +5 -0
package/dist/esm2022/lib/consentx.module.mjs +57 -0
package/dist/esm2022/lib/consentx.providers.mjs +51 -0
package/dist/esm2022/lib/consentx.service.mjs +230 -0
package/dist/esm2022/lib/consentx.tokens.mjs +7 -0
package/dist/esm2022/lib/consentx.types.mjs +11 -0
package/dist/esm2022/public-api.mjs +9 -0
package/dist/fesm2022/consentx-angular.mjs +358 -0
package/dist/fesm2022/consentx-angular.mjs.map +1 -0
package/dist/index.d.ts +5 -0
package/dist/lib/consentx.module.d.ts +39 -0
package/dist/lib/consentx.providers.d.ts +26 -0
package/dist/lib/consentx.service.d.ts +71 -0
package/dist/lib/consentx.tokens.d.ts +7 -0
package/dist/lib/consentx.types.d.ts +82 -0
package/dist/public-api.d.ts +5 -0
package/ng-package.json +10 -0
package/package.json +53 -0
package/src/index.ts +1 -0
package/src/lib/consentx.module.ts +53 -0
package/src/lib/consentx.providers.ts +60 -0
package/src/lib/consentx.service.ts +262 -0
package/src/lib/consentx.tokens.ts +8 -0
package/src/lib/consentx.types.ts +93 -0
package/src/public-api.ts +20 -0
package/tsconfig.json +32 -0

package/package.json ADDED Viewed

@@ -0,0 +1,53 @@
+{
+  "name": "@consentx/angular",
+  "version": "1.0.0",
+  "description": "ConsentX cookie consent & CMP for Angular — GDPR, CCPA, DPDPA. Inject the ConsentX embed and read consent state from a service. Site-key model, no server handshake.",
+  "keywords": [
+    "consentx",
+    "angular",
+    "cookie-consent",
+    "cmp",
+    "gdpr",
+    "ccpa",
+    "dpdpa",
+    "consent-mode",
+    "privacy"
+  ],
+  "homepage": "https://consentx.io/integrations/angular",
+  "bugs": {
+    "url": "https://github.com/consentx/consentx-plugins/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/consentx/consentx-plugins.git",
+    "directory": "packages/angular"
+  },
+  "license": "MIT",
+  "author": "ConsentX <hello@consentx.io> (https://consentx.io)",
+  "sideEffects": false,
+  "scripts": {
+    "build": "ng-packagr -p ng-package.json",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@angular/common": ">=15.0.0",
+    "@angular/core": ">=15.0.0",
+    "rxjs": ">=7.0.0"
+  },
+  "dependencies": {
+    "tslib": "^2.6.0"
+  },
+  "devDependencies": {
+    "@angular/common": "^17.3.0",
+    "@angular/compiler": "^17.3.0",
+    "@angular/compiler-cli": "^17.3.0",
+    "@angular/core": "^17.3.0",
+    "ng-packagr": "^17.3.0",
+    "rxjs": "^7.8.0",
+    "typescript": "~5.4.0",
+    "zone.js": "~0.14.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts ADDED Viewed

	@@ -0,0 +1 @@
1	+ export * from './public-api';

package/src/lib/consentx.module.ts ADDED Viewed

@@ -0,0 +1,53 @@
+import { ModuleWithProviders, NgModule, Optional, SkipSelf } from '@angular/core';
+import { ConsentXService } from './consentx.service';
+import { consentxRootProviders } from './consentx.providers';
+import { ConsentXConfig } from './consentx.types';
+/**
+ * The ConsentX module for classic NgModule-based applications.
+ *
+ * Import once at the application root via `forRoot`:
+ *
+ * ```ts
+ * @NgModule({
+ *   imports: [
+ *     BrowserModule,
+ *     ConsentXModule.forRoot({ siteKey: 'YOUR_SITE_KEY' }),
+ *   ],
+ *   bootstrap: [AppComponent],
+ * })
+ * export class AppModule {}
+ * ```
+ *
+ * On app init the {@link ConsentXService} injects the ConsentX embed
+ * (`/api/SITE_KEY/embed.js`) into `<head>` and starts tracking `cx:consent`.
+ *
+ * For standalone (`bootstrapApplication`) apps use `provideConsentX()` instead.
+ */
+@NgModule()
+export class ConsentXModule {
+  /**
+   * Guard against importing `forRoot()` more than once — it would register the
+   * embed initialiser twice.
+   */
+  constructor(@Optional() @SkipSelf() parent?: ConsentXModule) {
+    if (parent) {
+      throw new Error(
+        'ConsentXModule.forRoot() was imported more than once. Import it only in ' +
+          'your root AppModule.',
+      );
+    }
+  }
+  /**
+   * Configure ConsentX with your Site Key (and optional overrides). Returns the
+   * module plus the root providers (config token, service, APP_INITIALIZER).
+   */
+  static forRoot(config: ConsentXConfig): ModuleWithProviders<ConsentXModule> {
+    return {
+      ngModule: ConsentXModule,
+      providers: consentxRootProviders(config),
+    };
+  }
+}

package/src/lib/consentx.providers.ts ADDED Viewed

@@ -0,0 +1,60 @@
+import {
+  APP_INITIALIZER,
+  EnvironmentProviders,
+  Provider,
+  makeEnvironmentProviders,
+} from '@angular/core';
+import { CONSENTX_CONFIG } from './consentx.tokens';
+import { ConsentXService } from './consentx.service';
+import { ConsentXConfig } from './consentx.types';
+/**
+ * Factory used by APP_INITIALIZER. Initialising on app boot means the embed is
+ * injected once the Angular application is ready (i.e. after hydration on SSR),
+ * which is the SPA-safe load point the Connect spec recommends so the
+ * framework's DOM reconciliation does not strip the appended
+ * `#consentx-cookie-consent` div.
+ */
+export function consentxInitFactory(service: ConsentXService): () => void {
+  return () => service.init();
+}
+/**
+ * Standalone-app provider. Use in `bootstrapApplication(...)`:
+ *
+ * ```ts
+ * bootstrapApplication(AppComponent, {
+ *   providers: [provideConsentX({ siteKey: 'YOUR_SITE_KEY' })],
+ * });
+ * ```
+ */
+export function provideConsentX(config: ConsentXConfig): EnvironmentProviders {
+  return makeEnvironmentProviders([
+    { provide: CONSENTX_CONFIG, useValue: config },
+    ConsentXService,
+    {
+      provide: APP_INITIALIZER,
+      multi: true,
+      useFactory: consentxInitFactory,
+      deps: [ConsentXService],
+    },
+  ]);
+}
+/**
+ * Internal: the providers `ConsentXModule.forRoot()` contributes. Kept separate
+ * so both the NgModule and the standalone API share one source of truth.
+ */
+export function consentxRootProviders(config: ConsentXConfig): Provider[] {
+  return [
+    { provide: CONSENTX_CONFIG, useValue: config },
+    ConsentXService,
+    {
+      provide: APP_INITIALIZER,
+      multi: true,
+      useFactory: consentxInitFactory,
+      deps: [ConsentXService],
+    },
+  ];
+}

package/src/lib/consentx.service.ts ADDED Viewed

@@ -0,0 +1,262 @@
+import {
+  Inject,
+  Injectable,
+  NgZone,
+  OnDestroy,
+  Optional,
+  PLATFORM_ID,
+} from '@angular/core';
+import { DOCUMENT, isPlatformBrowser } from '@angular/common';
+import { BehaviorSubject, Observable } from 'rxjs';
+import { distinctUntilChanged, map } from 'rxjs/operators';
+import { CONSENTX_CONFIG } from './consentx.tokens';
+import {
+  CONSENTX_DEFAULT_APP_URL,
+  ConsentGranted,
+  ConsentXConfig,
+  ConsentXConsentDetail,
+  ConsentXState,
+} from './consentx.types';
+const SCRIPT_ID = 'consentx-embed';
+const CONSENT_MODE_ID = 'consentx-consent-mode';
+/**
+ * Injects the ConsentX embed script (`/api/SITE_KEY/embed.js`) into `<head>`
+ * and exposes the visitor's consent state, derived from the widget's
+ * `cx:consent` events.
+ *
+ * Site-key model (Connect spec, Model C): no redirect handshake. The Site Key
+ * is supplied via configuration; this service only performs clean embed
+ * injection plus a consent hook.
+ *
+ * The service is `providedIn: 'root'` so it is a singleton across the app. It
+ * is SSR-safe: all DOM access is guarded behind `isPlatformBrowser`, so it is a
+ * no-op on the server and runs once the app boots in the browser.
+ */
+@Injectable({ providedIn: 'root' })
+export class ConsentXService implements OnDestroy {
+  private readonly appUrl: string;
+  private readonly isBrowser: boolean;
+  private listenerBound = false;
+  private boundConsentListener?: (event: Event) => void;
+  private readonly stateSubject = new BehaviorSubject<ConsentXState>({
+    loaded: false,
+    decided: false,
+    granted: [],
+    detail: null,
+  });
+  /** Full consent state as an observable. Emits an initial snapshot. */
+  readonly state$: Observable<ConsentXState> = this.stateSubject.asObservable();
+  /** Convenience stream of the granted category slugs. */
+  readonly granted$: Observable<ConsentGranted> = this.state$.pipe(
+    map((s) => s.granted),
+    distinctUntilChanged((a, b) => a.length === b.length && a.every((v, i) => v === b[i])),
+  );
+  constructor(
+    @Optional() @Inject(CONSENTX_CONFIG) private readonly config: ConsentXConfig | null,
+    @Inject(PLATFORM_ID) platformId: object,
+    @Inject(DOCUMENT) private readonly document: Document,
+    private readonly zone: NgZone,
+  ) {
+    this.isBrowser = isPlatformBrowser(platformId);
+    this.appUrl = this.normalizeAppUrl(this.config?.appUrl);
+    if (!this.config?.siteKey) {
+      // Misconfiguration is loud but non-fatal: the app keeps working without
+      // the banner instead of crashing bootstrap.
+      // eslint-disable-next-line no-console
+      console.error(
+        '[ConsentX] No siteKey provided. Pass { siteKey } to ConsentXModule.forRoot() ' +
+          'or provideConsentX(). Copy the Site Key from the ConsentX dashboard -> ' +
+          'Websites -> your site.',
+      );
+    }
+  }
+  /**
+   * Auto-init entry point. Called once during app initialisation (via an
+   * APP_INITIALIZER registered by the module/provider) unless `manualLoad` is
+   * set. Binds the consent listener and injects the embed.
+   */
+  init(): void {
+    if (!this.isBrowser) {
+      return;
+    }
+    this.bindConsentListener();
+    if (!this.config?.manualLoad) {
+      this.load();
+    }
+  }
+  /**
+   * Inject the ConsentX embed into `<head>`. Idempotent: a second call is a
+   * no-op if the script is already present. Safe to call manually when
+   * `manualLoad` is enabled (e.g. after a cookie-policy route is reached).
+   */
+  load(): void {
+    if (!this.isBrowser) {
+      return;
+    }
+    const siteKey = this.config?.siteKey?.trim();
+    if (!siteKey) {
+      return;
+    }
+    this.bindConsentListener();
+    if (this.config?.consentMode) {
+      this.injectConsentModeDefaults();
+    }
+    // Expose the key the way embed.js expects (window.consentx_key), matching
+    // the canonical embed contract.
+    this.document.defaultView!.consentx_key = siteKey;
+    if (this.document.getElementById(SCRIPT_ID)) {
+      // Already injected — make sure the loaded flag reflects reality.
+      this.patchState({ loaded: true });
+      return;
+    }
+    const head = this.document.head || this.document.getElementsByTagName('head')[0];
+    if (!head) {
+      return;
+    }
+    const script = this.document.createElement('script');
+    script.id = SCRIPT_ID;
+    script.type = 'module';
+    script.src = `${this.appUrl}/api/${encodeURIComponent(siteKey)}/embed.js`;
+    script.setAttribute('data-consentx', siteKey);
+    script.async = true;
+    script.addEventListener('load', () => {
+      this.zone.run(() => this.patchState({ loaded: true }));
+    });
+    script.addEventListener('error', () => {
+      // eslint-disable-next-line no-console
+      console.error(`[ConsentX] Failed to load embed from ${script.src}`);
+    });
+    head.appendChild(script);
+  }
+  /**
+   * Open the ConsentX preferences dialog. Requires the embed to have loaded and
+   * exposed `window.ConsentX`. Returns `true` if the call was dispatched.
+   */
+  openPreferences(): boolean {
+    if (!this.isBrowser) {
+      return false;
+    }
+    const api = this.document.defaultView?.ConsentX;
+    if (api && typeof api.open === 'function') {
+      api.open();
+      return true;
+    }
+    return false;
+  }
+  /** Latest granted category slugs (synchronous snapshot). */
+  getGranted(): ConsentGranted {
+    return this.stateSubject.value.granted;
+  }
+  /**
+   * Whether the visitor has granted a specific consent category slug, e.g.
+   * `hasConsent('analytics')`.
+   */
+  hasConsent(slug: string): boolean {
+    return this.stateSubject.value.granted.includes(slug);
+  }
+  /** Current full state snapshot (synchronous). */
+  getState(): ConsentXState {
+    return this.stateSubject.value;
+  }
+  ngOnDestroy(): void {
+    if (this.isBrowser && this.boundConsentListener) {
+      this.document.defaultView?.removeEventListener(
+        'cx:consent',
+        this.boundConsentListener as EventListener,
+      );
+    }
+  }
+  // --- internals -----------------------------------------------------------
+  /**
+   * Print the Google Consent Mode v2 denied-by-default stub before any
+   * analytics tag fires. Idempotent. Mirrors the canonical embed contract.
+   */
+  private injectConsentModeDefaults(): void {
+    const win = this.document.defaultView;
+    if (!win) {
+      return;
+    }
+    if (this.document.getElementById(CONSENT_MODE_ID)) {
+      return;
+    }
+    win.dataLayer = win.dataLayer || [];
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const gtag = (...args: unknown[]) => (win.dataLayer as any[]).push(args);
+    gtag('consent', 'default', {
+      ad_storage: 'denied',
+      analytics_storage: 'denied',
+      ad_user_data: 'denied',
+      ad_personalization: 'denied',
+      functionality_storage: 'denied',
+      personalization_storage: 'denied',
+      security_storage: 'granted',
+      wait_for_update: 500,
+    });
+    // Marker so a second call (or a duplicate inline tag) is a no-op.
+    const marker = this.document.createElement('script');
+    marker.id = CONSENT_MODE_ID;
+    marker.type = 'application/json';
+    marker.textContent = '{"consentx":"consent-mode-defaults"}';
+    (this.document.head || this.document.documentElement).appendChild(marker);
+  }
+  /** Subscribe to the widget's `cx:consent` events exactly once. */
+  private bindConsentListener(): void {
+    if (this.listenerBound || !this.isBrowser) {
+      return;
+    }
+    const win = this.document.defaultView;
+    if (!win) {
+      return;
+    }
+    this.boundConsentListener = (event: Event) => {
+      const detail = (event as CustomEvent<ConsentXConsentDetail>).detail;
+      const granted = Array.isArray(detail?.granted) ? detail!.granted : [];
+      // Re-enter Angular so bound templates/observables update.
+      this.zone.run(() =>
+        this.patchState({
+          decided: true,
+          granted,
+          detail: detail ?? null,
+        }),
+      );
+    };
+    win.addEventListener('cx:consent', this.boundConsentListener as EventListener);
+    this.listenerBound = true;
+  }
+  private patchState(partial: Partial<ConsentXState>): void {
+    this.stateSubject.next({ ...this.stateSubject.value, ...partial });
+  }
+  /** Resolve + sanitise the app host (strip trailing slash). */
+  private normalizeAppUrl(url?: string): string {
+    const raw = (url || CONSENTX_DEFAULT_APP_URL).trim();
+    return raw.replace(/\/+$/, '');
+  }
+}

package/src/lib/consentx.tokens.ts ADDED Viewed

@@ -0,0 +1,8 @@
+import { InjectionToken } from '@angular/core';
+import { ConsentXConfig } from './consentx.types';
+/**
+ * DI token carrying the resolved {@link ConsentXConfig}. Provided by
+ * `ConsentXModule.forRoot(...)` or `provideConsentX(...)`.
+ */
+export const CONSENTX_CONFIG = new InjectionToken<ConsentXConfig>('CONSENTX_CONFIG');

package/src/lib/consentx.types.ts ADDED Viewed

@@ -0,0 +1,93 @@
+/**
+ * Public types for @consentx/angular.
+ *
+ * ConsentX runs on the site-key model (Model C in the Connect spec): the user
+ * pastes the Site Key copied from the ConsentX dashboard (Websites -> their
+ * site) and ensures their domain is on that site's allowlist. The embed then
+ * loads with no server-side handshake.
+ */
+/** Default ConsentX application host (no trailing slash). */
+export const CONSENTX_DEFAULT_APP_URL = 'https://app.consentx.io';
+/**
+ * Configuration passed to `ConsentXModule.forRoot(...)` (NgModule apps) or
+ * `provideConsentX(...)` (standalone apps).
+ */
+export interface ConsentXConfig {
+  /**
+   * The ConsentX Site Key for this website. Copy it from the ConsentX
+   * dashboard -> Websites -> your site. Required.
+   */
+  siteKey: string;
+  /**
+   * Override the ConsentX app host (scheme + host, no trailing slash).
+   * Defaults to `https://app.consentx.io`. Use this for staging hosts such as
+   * `https://consentx1.satyamrastogi.com`.
+   */
+  appUrl?: string;
+  /**
+   * When `true`, the service prints the Google Consent Mode v2
+   * denied-by-default stub into `<head>` before the embed loads, so any
+   * analytics tag that fires before consent starts denied. The ConsentX
+   * widget emits the `gtag('consent','update',...)` calls on the visitor's
+   * choice. Defaults to `false`.
+   */
+  consentMode?: boolean;
+  /**
+   * Disable automatic embed injection on app init. Set this to `true` if you
+   * want to call `ConsentXService.load()` yourself at a custom point.
+   * Defaults to `false` (auto-inject on init).
+   */
+  manualLoad?: boolean;
+}
+/** The category slugs a visitor has granted, e.g. `['analytics','marketing']`. */
+export type ConsentGranted = string[];
+/**
+ * The detail payload of the `cx:consent` browser event emitted by the ConsentX
+ * widget. `granted` is the array of granted category slugs.
+ */
+export interface ConsentXConsentDetail {
+  granted: ConsentGranted;
+  [key: string]: unknown;
+}
+/** Snapshot of consent state exposed by `ConsentXService.state$`. */
+export interface ConsentXState {
+  /** Whether the embed script has loaded into the page. */
+  loaded: boolean;
+  /** Whether a `cx:consent` event has been received this session. */
+  decided: boolean;
+  /** Granted category slugs from the latest `cx:consent` event. */
+  granted: ConsentGranted;
+  /** Raw detail of the latest `cx:consent` event, if any. */
+  detail: ConsentXConsentDetail | null;
+}
+/**
+ * The `window.ConsentX` API the widget exposes once loaded. Currently used to
+ * re-open the preferences dialog.
+ */
+export interface ConsentXWidgetApi {
+  open?: () => void;
+  [key: string]: unknown;
+}
+declare global {
+  interface Window {
+    /** Carries the connected Site Key for the embed (read by embed.js). */
+    consentx_key?: string;
+    /** The widget API, present once embed.js has initialised. */
+    ConsentX?: ConsentXWidgetApi;
+    dataLayer?: unknown[];
+  }
+  interface WindowEventMap {
+    'cx:consent': CustomEvent<ConsentXConsentDetail>;
+  }
+}

package/src/public-api.ts ADDED Viewed

@@ -0,0 +1,20 @@
+/*
+ * Public API surface of @consentx/angular.
+ */
+export { ConsentXModule } from './lib/consentx.module';
+export { ConsentXService } from './lib/consentx.service';
+export {
+  provideConsentX,
+  consentxInitFactory,
+  consentxRootProviders,
+} from './lib/consentx.providers';
+export { CONSENTX_CONFIG } from './lib/consentx.tokens';
+export {
+  CONSENTX_DEFAULT_APP_URL,
+  ConsentXConfig,
+  ConsentXState,
+  ConsentGranted,
+  ConsentXConsentDetail,
+  ConsentXWidgetApi,
+} from './lib/consentx.types';

package/tsconfig.json ADDED Viewed

@@ -0,0 +1,32 @@
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "outDir": "./dist/out-tsc",
+    "declaration": true,
+    "declarationMap": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "moduleResolution": "node",
+    "importHelpers": true,
+    "strict": true,
+    "noImplicitOverride": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noPropertyAccessFromIndexSignature": false,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "module": "ES2022",
+    "target": "ES2022",
+    "useDefineForClassFields": false,
+    "lib": ["ES2022", "dom"]
+  },
+  "angularCompilerOptions": {
+    "enableI18nLegacyMessageIdFormat": false,
+    "strictInjectionParameters": true,
+    "strictInputAccessModifiers": true,
+    "strictTemplates": true,
+    "compilationMode": "partial"
+  },
+  "files": ["src/public-api.ts"]
+}