Merge branch 'main' into remove/BSB-6-sdk-starkex-guardian-client

Author: JCSanPedro

.github/CODEOWNERS

@@ -21,6 +21,7 @@ package.json @immutable/blockchain-services
 /packages/blockchain-data @immutable/activation
 /packages/minting-backend @shineli1984
 /packages/webhook @shineli1984
+/packages/audience @immutable/ped-stream-sdk-integrations-list
 /packages/game-bridge @immutable/gamesdk @immutable/blockchain-services
 /examples @immutable/devgrowth
 **/package.json @immutable/blockchain-services

packages/audience/core/.eslintrc.cjs

@@ -0,0 +1,7 @@
+module.exports = {
+  extends: ['../../../.eslintrc'],
+  parserOptions: {
+    project: './tsconfig.eslint.json',
+    tsconfigRootDir: __dirname,
+  },
+};

packages/audience/core/jest.config.ts

@@ -0,0 +1,14 @@
+import type { Config } from 'jest';
+
+const config: Config = {
+  roots: ['<rootDir>/src'],
+  moduleDirectories: ['node_modules', 'src'],
+  moduleNameMapper: { '^@imtbl/(.*)$': '<rootDir>/../../../node_modules/@imtbl/$1/src' },
+  testEnvironment: 'jsdom',
+  transform: {
+    '^.+\\.(t|j)sx?$': '@swc/jest',
+  },
+  transformIgnorePatterns: [],
+};
+
+export default config;

packages/audience/core/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@imtbl/audience-core",
+  "description": "Shared core for Immutable Audience SDKs: transport, queue, cookie, context collection",
+  "version": "0.0.0",
+  "author": "Immutable",
+  "private": true,
+  "bugs": "https://github.com/immutable/ts-immutable-sdk/issues",
+  "dependencies": {
+    "@imtbl/metrics": "workspace:*"
+  },
+  "devDependencies": {
+    "@swc/core": "^1.4.2",
+    "@swc/jest": "^0.2.37",
+    "@types/jest": "^29.5.12",
+    "eslint": "^8.56.0",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.4.3",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.2"
+  },
+  "exports": {
+    "development": {
+      "types": "./src/index.ts",
+      "browser": "./dist/browser/index.js",
+      "require": "./dist/node/index.cjs",
+      "default": "./dist/node/index.js"
+    },
+    "default": {
+      "types": "./dist/types/index.d.ts",
+      "browser": "./dist/browser/index.js",
+      "require": "./dist/node/index.cjs",
+      "default": "./dist/node/index.js"
+    }
+  },
+  "files": ["dist"],
+  "main": "dist/node/index.cjs",
+  "module": "dist/node/index.js",
+  "browser": "dist/browser/index.js",
+  "homepage": "https://github.com/immutable/ts-immutable-sdk#readme",
+  "repository": "immutable/ts-immutable-sdk.git",
+  "scripts": {
+    "build": "pnpm transpile && pnpm typegen",
+    "transpile": "tsup src/index.ts --config ../../../tsup.config.js",
+    "typegen": "tsc --customConditions default --emitDeclarationOnly --outDir dist/types",
+    "lint": "eslint ./src --ext .ts --max-warnings=0",
+    "test": "jest --passWithNoTests",
+    "typecheck": "tsc --customConditions default --noEmit"
+  },
+  "type": "module",
+  "types": "./dist/types/index.d.ts"
+}

packages/audience/core/src/config.test.ts

@@ -0,0 +1,15 @@
+import { getBaseUrl } from './config';
+
+describe('getBaseUrl', () => {
+  it('returns dev URL', () => {
+    expect(getBaseUrl('dev')).toBe('https://api.dev.immutable.com');
+  });
+
+  it('returns sandbox URL', () => {
+    expect(getBaseUrl('sandbox')).toBe('https://api.sandbox.immutable.com');
+  });
+
+  it('returns production URL', () => {
+    expect(getBaseUrl('production')).toBe('https://api.immutable.com');
+  });
+});

packages/audience/core/src/config.ts

@@ -0,0 +1,19 @@
+import type { Environment } from './types';
+
+const BASE_URLS: Record<Environment, string> = {
+  dev: 'https://api.dev.immutable.com',
+  sandbox: 'https://api.sandbox.immutable.com',
+  production: 'https://api.immutable.com',
+};
+
+export const INGEST_PATH = '/v1/audience/messages';
+export const CONSENT_PATH = '/v1/audience/tracking-consent';
+
+export const FLUSH_INTERVAL_MS = 5_000;
+export const FLUSH_SIZE = 20;
+
+export const COOKIE_NAME = 'imtbl_anon_id';
+export const SESSION_COOKIE = '_imtbl_sid';
+export const COOKIE_MAX_AGE_SECONDS = 365 * 24 * 60 * 60 * 2; // 2 years
+
+export const getBaseUrl = (environment: Environment): string => BASE_URLS[environment];

packages/audience/core/src/context.test.ts

@@ -0,0 +1,31 @@
+import { collectContext } from './context';
+
+describe('collectContext', () => {
+  it('defaults to @imtbl/audience library name', () => {
+    const ctx = collectContext();
+    expect(ctx.library).toBe('@imtbl/audience');
+    expect(ctx.libraryVersion).toBeDefined();
+  });
+
+  it('accepts custom library name and version', () => {
+    const ctx = collectContext('@imtbl/audience-web-sdk', '1.0.0');
+    expect(ctx.library).toBe('@imtbl/audience-web-sdk');
+    expect(ctx.libraryVersion).toBe('1.0.0');
+  });
+
+  it('collects browser signals in jsdom', () => {
+    const ctx = collectContext();
+    expect(ctx.userAgent).toBeDefined();
+    expect(ctx.locale).toBeDefined();
+    expect(ctx.timezone).toBeDefined();
+    expect(ctx.screen).toMatch(/^\d+x\d+$/);
+  });
+
+  it('collects page info', () => {
+    const ctx = collectContext();
+    expect(ctx.pageUrl).toBeDefined();
+    expect(ctx.pagePath).toBeDefined();
+    expect(typeof ctx.pageReferrer).toBe('string');
+    expect(typeof ctx.pageTitle).toBe('string');
+  });
+});

packages/audience/core/src/context.ts

@@ -0,0 +1,35 @@
+import type { EventContext } from './types';
+import { isBrowser } from './utils';
+
+// WARNING: DO NOT CHANGE THE STRING BELOW. IT GETS REPLACED AT BUILD TIME.
+const SDK_VERSION = '__SDK_VERSION__';
+
+/**
+ * Collect browser context for event payloads.
+ *
+ * Callers may pass their own library name and version when multiple surfaces
+ * (web SDK, pixel, Unity, Unreal) share this function and each must identify
+ * itself. Defaults to '@imtbl/audience' with the build-time SDK version.
+ */
+export function collectContext(
+  library = '@imtbl/audience',
+  version = SDK_VERSION,
+): EventContext {
+  const context: EventContext = {
+    library,
+    libraryVersion: version,
+  };
+
+  if (!isBrowser()) return context;
+
+  context.userAgent = navigator.userAgent;
+  context.locale = navigator.language;
+  context.timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+  context.screen = `${window.screen.width}x${window.screen.height}`;
+  context.pageUrl = window.location.href;
+  context.pagePath = window.location.pathname;
+  context.pageReferrer = document.referrer;
+  context.pageTitle = document.title;
+
+  return context;
+}

packages/audience/core/src/cookie.test.ts

@@ -0,0 +1,46 @@
+import { getOrCreateAnonymousId, getAnonymousId } from './cookie';
+import { COOKIE_NAME } from './config';
+
+function clearCookies() {
+  document.cookie.split(';').forEach((c) => {
+    const name = c.split('=')[0].trim();
+    document.cookie = `${name}=; max-age=0; path=/`;
+  });
+}
+
+beforeEach(clearCookies);
+
+describe('getOrCreateAnonymousId', () => {
+  it('generates a new ID when no cookie exists', () => {
+    const id = getOrCreateAnonymousId();
+    expect(id).toBeTruthy();
+    expect(typeof id).toBe('string');
+  });
+
+  it('persists the ID in a cookie', () => {
+    const id = getOrCreateAnonymousId();
+    expect(document.cookie).toContain(`${COOKIE_NAME}=${id}`);
+  });
+
+  it('returns the same ID on subsequent calls', () => {
+    const first = getOrCreateAnonymousId();
+    const second = getOrCreateAnonymousId();
+    expect(second).toBe(first);
+  });
+
+  it('returns an existing cookie value if already set', () => {
+    document.cookie = `${COOKIE_NAME}=existing-id; path=/`;
+    expect(getOrCreateAnonymousId()).toBe('existing-id');
+  });
+});
+
+describe('getAnonymousId', () => {
+  it('returns undefined when no cookie exists', () => {
+    expect(getAnonymousId()).toBeUndefined();
+  });
+
+  it('returns the cookie value when set', () => {
+    document.cookie = `${COOKIE_NAME}=test-id; path=/`;
+    expect(getAnonymousId()).toBe('test-id');
+  });
+});

packages/audience/core/src/cookie.ts

@@ -0,0 +1,38 @@
+import { COOKIE_NAME, COOKIE_MAX_AGE_SECONDS } from './config';
+import { isBrowser, generateId } from './utils';
+
+export function getCookie(name: string): string | undefined {
+  if (!isBrowser()) return undefined;
+  const match = document.cookie.match(new RegExp(`(?:^|; )${name}=([^;]*)`));
+  return match ? decodeURIComponent(match[1]) : undefined;
+}
+
+export function setCookie(name: string, value: string, maxAge: number, domain?: string): void {
+  if (!isBrowser()) return;
+  const secure = window.location.protocol === 'https:' ? '; Secure' : '';
+  const domainAttr = domain ? `; domain=${domain}` : '';
+  document.cookie = `${name}=${encodeURIComponent(value)}`
+    + `; path=/; max-age=${maxAge}; SameSite=Lax${domainAttr}${secure}`;
+}
+
+export function deleteCookie(name: string, domain?: string): void {
+  setCookie(name, '', 0, domain);
+}
+
+/**
+ * Returns the anonymous ID from the shared cookie, creating one if it doesn't exist.
+ * Both the web SDK and pixel read/write the same cookie so identity stitching
+ * works across surfaces on the same domain.
+ */
+export function getOrCreateAnonymousId(domain?: string): string {
+  const existing = getCookie(COOKIE_NAME);
+  if (existing) return existing;
+
+  const id = generateId();
+  setCookie(COOKIE_NAME, id, COOKIE_MAX_AGE_SECONDS, domain);
+  return id;
+}
+
+export function getAnonymousId(): string | undefined {
+  return getCookie(COOKIE_NAME);
+}