@symbiote-native/tracking-transparency 0.0.1

package/build-ngc/core/tracking-transparency.d.ts

@@ -0,0 +1,19 @@
+import type { PermissionResponse } from 'expo-modules-core';
+/**
+ * Gets the advertising ID, a UUID string intended only for advertising. Returns `null` on the
+ * iOS simulator, when tracking hasn't been authorized via `requestTrackingPermissionsAsync`, or
+ * when the user declined.
+ */
+export declare function getAdvertisingId(): string | null;
+/**
+ * Requests the user to authorize or deny access to app-related data that can be used for
+ * tracking. On Android and web this always resolves granted.
+ */
+export declare function requestTrackingPermissionsAsync(): Promise<PermissionResponse>;
+/**
+ * Checks whether the user has authorized the app to access tracking-related data. On Android and
+ * web this always resolves granted.
+ */
+export declare function getTrackingPermissionsAsync(): Promise<PermissionResponse>;
+/** Whether the tracking-transparency native module resolved at all. */
+export declare function isAvailable(): boolean;

package/build-ngc/core/tracking-transparency.js

@@ -0,0 +1,59 @@
+// Hand-ported from .vendors/expo/packages/expo-tracking-transparency/src/TrackingTransparency.ts
+// (sdk-57, verified via `git -C .vendors/expo show origin/sdk-57:...` — the vendored working
+// tree is on `main` and imports createPermissionHook/PermissionResponse from the `expo`
+// meta-package instead of expo-modules-core). createPermissionHook/useTrackingPermissions are
+// NOT ported here — that helper is React-only (built on useState/useEffect), and this repo's
+// convention is for each adapter to hand-roll its own permission hook instead (react/hooks,
+// vue/composables, angular/services), same as brightness/cellular already do.
+import { Platform, PermissionStatus, UnavailabilityError } from 'expo-modules-core';
+import { expoTrackingTransparency } from './native-module';
+const NATIVE_MODULE_NAME = 'TrackingTransparency';
+/**
+ * Gets the advertising ID, a UUID string intended only for advertising. Returns `null` on the
+ * iOS simulator, when tracking hasn't been authorized via `requestTrackingPermissionsAsync`, or
+ * when the user declined.
+ */
+export function getAdvertisingId() {
+    const advertisingId = expoTrackingTransparency.getAdvertisingId();
+    if (advertisingId === '00000000-0000-0000-0000-000000000000') {
+        return null;
+    }
+    return advertisingId;
+}
+const androidAndWebPermissionsResponse = {
+    granted: true,
+    expires: 'never',
+    canAskAgain: true,
+    status: PermissionStatus.GRANTED,
+};
+/**
+ * Requests the user to authorize or deny access to app-related data that can be used for
+ * tracking. On Android and web this always resolves granted.
+ */
+export async function requestTrackingPermissionsAsync() {
+    if (Platform.OS !== 'ios') {
+        return Promise.resolve(androidAndWebPermissionsResponse);
+    }
+    if (!expoTrackingTransparency.requestPermissionsAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'requestPermissionsAsync');
+    }
+    return await expoTrackingTransparency.requestPermissionsAsync();
+}
+/**
+ * Checks whether the user has authorized the app to access tracking-related data. On Android and
+ * web this always resolves granted.
+ */
+export async function getTrackingPermissionsAsync() {
+    if (Platform.OS !== 'ios') {
+        return Promise.resolve(androidAndWebPermissionsResponse);
+    }
+    if (!expoTrackingTransparency.getPermissionsAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getPermissionsAsync');
+    }
+    return await expoTrackingTransparency.getPermissionsAsync();
+}
+/** Whether the tracking-transparency native module resolved at all. */
+export function isAvailable() {
+    return Boolean(expoTrackingTransparency);
+}
+//# sourceMappingURL=tracking-transparency.js.map

package/build-ngc/core/tracking-transparency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracking-transparency.js","sourceRoot":"","sources":["../../src/core/tracking-transparency.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,6FAA6F;AAC7F,wFAAwF;AACxF,8FAA8F;AAC9F,6FAA6F;AAC7F,4FAA4F;AAC5F,8EAA8E;AAC9E,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAGpF,OAAO,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAE3D,MAAM,kBAAkB,GAAG,sBAAsB,CAAC;AAElD;;;;GAIG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,aAAa,GAAG,wBAAwB,CAAC,gBAAgB,EAAE,CAAC;IAClE,IAAI,aAAa,KAAK,sCAAsC,EAAE,CAAC;QAC7D,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,aAAa,CAAC;AACvB,CAAC;AAED,MAAM,gCAAgC,GAAuB;IAC3D,OAAO,EAAE,IAAI;IACb,OAAO,EAAE,OAAO;IAChB,WAAW,EAAE,IAAI;IACjB,MAAM,EAAE,gBAAgB,CAAC,OAAO;CACjC,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,+BAA+B;IACnD,IAAI,QAAQ,CAAC,EAAE,KAAK,KAAK,EAAE,CAAC;QAC1B,OAAO,OAAO,CAAC,OAAO,CAAC,gCAAgC,CAAC,CAAC;IAC3D,CAAC;IACD,IAAI,CAAC,wBAAwB,CAAC,uBAAuB,EAAE,CAAC;QACtD,MAAM,IAAI,mBAAmB,CAAC,kBAAkB,EAAE,yBAAyB,CAAC,CAAC;IAC/E,CAAC;IACD,OAAO,MAAM,wBAAwB,CAAC,uBAAuB,EAAE,CAAC;AAClE,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B;IAC/C,IAAI,QAAQ,CAAC,EAAE,KAAK,KAAK,EAAE,CAAC;QAC1B,OAAO,OAAO,CAAC,OAAO,CAAC,gCAAgC,CAAC,CAAC;IAC3D,CAAC;IACD,IAAI,CAAC,wBAAwB,CAAC,mBAAmB,EAAE,CAAC;QAClD,MAAM,IAAI,mBAAmB,CAAC,kBAAkB,EAAE,qBAAqB,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,MAAM,wBAAwB,CAAC,mBAAmB,EAAE,CAAC;AAC9D,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,WAAW;IACzB,OAAO,OAAO,CAAC,wBAAwB,CAAC,CAAC;AAC3C,CAAC"}

package/native-link.json

@@ -0,0 +1,17 @@
+{
+  "android": {
+    "gradleProjectName": "expo-tracking-transparency",
+    "modules": [
+      {
+        "importPath": "expo.modules.trackingtransparency.TrackingTransparencyModule",
+        "className": "TrackingTransparencyModule",
+        "nativeName": "ExpoTrackingTransparency"
+      }
+    ]
+  },
+  "ios": {
+    "infoPlistKeys": {
+      "NSUserTrackingUsageDescription": "This app tracks your activity across other apps and websites."
+    }
+  }
+}

package/package.json

@@ -0,0 +1,107 @@
+{
+  "name": "@symbiote-native/tracking-transparency",
+  "version": "0.0.1",
+  "description": "expo-tracking-transparency wrapped for SymbioteNative — one framework-agnostic core, built once and reachable from the React, Vue, and Angular adapters. iOS App Tracking Transparency prompt (permission get/request, always-granted on Android/web) plus the advertising-ID getter.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OneEyed1366/symbiote-native.git",
+    "directory": "packages/tracking-transparency"
+  },
+  "homepage": "https://github.com/OneEyed1366/symbiote-native/tree/master/packages/tracking-transparency#readme",
+  "bugs": {
+    "url": "https://github.com/OneEyed1366/symbiote-native/issues"
+  },
+  "author": "Andrey Prokopenko <psevdoproger@gmail.com>",
+  "type": "module",
+  "main": "./build/core/index.js",
+  "module": "./build/core/index.js",
+  "types": "./build/core/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/core/index.d.ts",
+      "default": "./build/core/index.js"
+    },
+    "./vue": {
+      "types": "./build/vue/index.d.ts",
+      "default": "./build/vue/index.js"
+    },
+    "./react": {
+      "types": "./build/react/index.d.ts",
+      "default": "./build/react/index.js"
+    },
+    "./angular": {
+      "types": "./build-ngc/angular/index.d.ts",
+      "react-native": "./build-ngc/angular/index.js",
+      "default": "./src/angular/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "build",
+    "build-ngc",
+    "native-link.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "expo-tracking-transparency": "57.0.1",
+    "expo-modules-core": "57.0.5"
+  },
+  "peerDependencies": {
+    "@symbiote-native/engine": ">=0.1.7",
+    "@angular/core": ">=20",
+    "@vue/runtime-core": "^3.5.13",
+    "react": ">=19.0.0",
+    "react-native": ">=0.86",
+    "vue": ">=3.5.0",
+    "@symbiote-native/angular": "0.6.1",
+    "@symbiote-native/react": "0.2.8",
+    "@symbiote-native/vue": "0.3.8"
+  },
+  "peerDependenciesMeta": {
+    "@symbiote-native/angular": {
+      "optional": true
+    },
+    "@symbiote-native/react": {
+      "optional": true
+    },
+    "@symbiote-native/vue": {
+      "optional": true
+    },
+    "@angular/core": {
+      "optional": true
+    },
+    "@vue/runtime-core": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@angular/compiler": "^22",
+    "@angular/compiler-cli": "^22",
+    "@angular/core": "^22",
+    "@types/node": "^26.0.0",
+    "@types/react": "^19.2.0",
+    "@vue/runtime-core": "^3.5.13",
+    "react": "19.2.3",
+    "typescript": "~6.0.0",
+    "@symbiote-native/angular": "0.6.1",
+    "@symbiote-native/engine": "0.1.7",
+    "@symbiote-native/vue": "0.3.8",
+    "@symbiote-native/test-utils": "0.1.6",
+    "@symbiote-native/react": "0.2.8"
+  },
+  "scripts": {
+    "typecheck": "tsc --build",
+    "clean": "rm -rf build-ngc",
+    "ng:build": "pnpm run clean && ngc -p tsconfig.angular.json",
+    "format": "prettier --write \"src/**/*.{ts,tsx}\""
+  }
+}

package/src/angular/index.ts

@@ -0,0 +1,4 @@
+// PermissionsService is the Angular-only lifecycle half; getAdvertisingId/isAvailable are
+// stateless free functions, shared with React/Vue.
+export { PermissionsService } from './services/permissions.service';
+export * from '../core';

package/src/angular/services/permissions.service/index.ts

@@ -0,0 +1,37 @@
+// Angular twin of React's usePermissions hook and Vue's usePermissions composable.
+// `connect()` auto-fetches once (no ongoing subscription to clean up, so no Injector/effect
+// needed, unlike BatteryStateService) and returns a readonly signal; get()/request() are
+// imperative one-shot methods.
+//
+//   readonly status = inject(PermissionsService).connect();
+//   // template: {{ status()?.granted }}
+import { Injectable, signal, type Signal } from '@angular/core';
+import {
+  getTrackingPermissionsAsync,
+  requestTrackingPermissionsAsync,
+  type PermissionResponse,
+} from '../../../core';
+
+@Injectable({ providedIn: 'root' })
+export class PermissionsService {
+  private readonly status = signal<PermissionResponse | null>(null);
+
+  connect(): Signal<PermissionResponse | null> {
+    if (this.status() === null) {
+      void this.get();
+    }
+    return this.status.asReadonly();
+  }
+
+  async get(): Promise<PermissionResponse> {
+    const response = await getTrackingPermissionsAsync();
+    this.status.set(response);
+    return response;
+  }
+
+  async request(): Promise<PermissionResponse> {
+    const response = await requestTrackingPermissionsAsync();
+    this.status.set(response);
+    return response;
+  }
+}

package/src/angular/services/permissions.service/permissions.service.test.ts

@@ -0,0 +1,107 @@
+// Co-located Angular-driven test (ADR 0025) for PermissionsService. See battery's
+// battery-state.service.test.ts for the shared rationale.
+
+import '@angular/compiler';
+import { Component, inject, type Signal } from '@angular/core';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mount, unmount } from '@symbiote-native/angular';
+import { installFabric } from '@symbiote-native/test-utils';
+import { PermissionsService } from './index';
+import { PermissionStatus, type PermissionResponse } from '../../../core';
+
+const { getTrackingPermissionsAsync, requestTrackingPermissionsAsync } = vi.hoisted(() => ({
+  getTrackingPermissionsAsync: vi.fn(),
+  requestTrackingPermissionsAsync: vi.fn(),
+}));
+
+// Same enum-shaped-object mock trick packages/battery/src/angular/services/battery-state.service's
+// test uses for BatteryState.
+vi.mock('../../../core', () => ({
+  getTrackingPermissionsAsync,
+  requestTrackingPermissionsAsync,
+  PermissionStatus: { GRANTED: 'granted', DENIED: 'denied', UNDETERMINED: 'undetermined' },
+}));
+
+const GRANTED: PermissionResponse = {
+  status: PermissionStatus.GRANTED,
+  granted: true,
+  canAskAgain: true,
+  expires: 'never',
+};
+const DENIED: PermissionResponse = {
+  status: PermissionStatus.DENIED,
+  granted: false,
+  canAskAgain: true,
+  expires: 'never',
+};
+
+const ROOT_TAG = 974;
+const fabric = installFabric();
+const tick = (): Promise<void> => new Promise(resolve => setTimeout(resolve, 0));
+
+let capturedStatus: Signal<PermissionResponse | null> | undefined;
+let capturedService: PermissionsService | undefined;
+
+@Component({
+  selector: 'symbiote-permissions-host',
+  standalone: true,
+  template: '',
+})
+class PermissionsHost {
+  readonly service = inject(PermissionsService);
+  readonly status = this.service.connect();
+
+  constructor() {
+    capturedStatus = this.status;
+    capturedService = this.service;
+  }
+}
+
+beforeEach(() => {
+  capturedStatus = undefined;
+  capturedService = undefined;
+  vi.clearAllMocks();
+  getTrackingPermissionsAsync.mockResolvedValue(GRANTED);
+  requestTrackingPermissionsAsync.mockResolvedValue(GRANTED);
+});
+
+afterEach(() => {
+  unmount(ROOT_TAG);
+  fabric.reset();
+});
+
+describe('PermissionsService.connect', () => {
+  it('reports null before the initial fetch resolves', () => {
+    mount(ROOT_TAG, PermissionsHost);
+
+    expect(capturedStatus?.()).toBe(null);
+  });
+
+  it('reports the fetched status once getTrackingPermissionsAsync() resolves', async () => {
+    mount(ROOT_TAG, PermissionsHost);
+    await tick();
+
+    expect(capturedStatus?.()).toEqual(GRANTED);
+    expect(getTrackingPermissionsAsync).toHaveBeenCalledTimes(1);
+  });
+
+  it('request() delegates to requestTrackingPermissionsAsync and updates the signal', async () => {
+    mount(ROOT_TAG, PermissionsHost);
+    await tick();
+
+    requestTrackingPermissionsAsync.mockResolvedValueOnce(DENIED);
+    await capturedService?.request();
+
+    expect(capturedStatus?.()).toEqual(DENIED);
+  });
+
+  it('get() re-fetches and updates the signal', async () => {
+    mount(ROOT_TAG, PermissionsHost);
+    await tick();
+
+    getTrackingPermissionsAsync.mockResolvedValueOnce(DENIED);
+    await capturedService?.get();
+
+    expect(capturedStatus?.()).toEqual(DENIED);
+  });
+});

package/src/core/index.ts

@@ -0,0 +1,12 @@
+export {
+  getAdvertisingId,
+  requestTrackingPermissionsAsync,
+  getTrackingPermissionsAsync,
+  isAvailable,
+} from './tracking-transparency';
+export {
+  PermissionStatus,
+  type PermissionResponse,
+  type PermissionExpiration,
+  type PermissionHookOptions,
+} from 'expo-modules-core';

package/src/core/native-module.ts

@@ -0,0 +1,21 @@
+import { requireNativeModule } from 'expo-modules-core';
+import type { PermissionResponse } from 'expo-modules-core';
+
+const EXPO_TRACKING_TRANSPARENCY_MODULE_NAME = 'ExpoTrackingTransparency';
+
+// getAdvertisingId is unconditional (upstream's Kotlin/Swift always implement it); the two
+// permission methods are optional and iOS-only in practice — Android/web never reach the native
+// module for them at all (see tracking-transparency.ts's Platform.OS !== 'ios' short-circuit), so
+// the call site itself checks presence and throws an UnavailabilityError, matching upstream's own
+// per-platform capability check rather than assuming the native module implements the whole
+// surface (same convention as packages/device/src/core/native-module.ts and
+// packages/brightness/src/core/native-module.ts).
+export type INativeTrackingTransparencyModule = {
+  getAdvertisingId(): string | null;
+  requestPermissionsAsync?(): Promise<PermissionResponse>;
+  getPermissionsAsync?(): Promise<PermissionResponse>;
+};
+
+export const expoTrackingTransparency = requireNativeModule<INativeTrackingTransparencyModule>(
+  EXPO_TRACKING_TRANSPARENCY_MODULE_NAME,
+);

package/src/core/tracking-transparency.test.ts

@@ -0,0 +1,137 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+const FAKE_NATIVE_TRACKING_TRANSPARENCY = {
+  getAdvertisingId: vi.fn(() => 'E9228286-4C4E-4789-9D95-15827DCB291B'),
+  requestPermissionsAsync: vi.fn(async () => ({ status: 'granted', granted: true })),
+  getPermissionsAsync: vi.fn(async () => ({ status: 'granted', granted: true })),
+};
+
+// The real ExpoTrackingTransparency native module only exists on device — resolving it via
+// requireNativeModule() at import time would throw in this headless test run, so the
+// module-lookup file is faked in place of expo-modules-core's runtime resolution, same pattern
+// packages/brightness/src/core/brightness.test.ts and packages/device/src/core/device.test.ts use.
+vi.mock('./native-module', () => ({
+  expoTrackingTransparency: FAKE_NATIVE_TRACKING_TRANSPARENCY,
+}));
+
+// expo-modules-core's real entry transitively imports 'react-native' for Platform/
+// TurboModuleRegistry, whose Flow-typed source Vitest's Oxc transform can't parse — same fake
+// packages/brightness/src/core/brightness.test.ts uses, since Platform.OS gates the
+// Android/web-vs-iOS branch here.
+const fakePlatform = { OS: 'ios' as 'ios' | 'android' };
+
+vi.mock('expo-modules-core', () => ({
+  Platform: fakePlatform,
+  PermissionStatus: { GRANTED: 'granted', DENIED: 'denied', UNDETERMINED: 'undetermined' },
+  UnavailabilityError: class UnavailabilityError extends Error {
+    constructor(moduleName: string, propertyName: string) {
+      super(`${propertyName} is not available on ${moduleName}`);
+    }
+  },
+}));
+
+const {
+  getAdvertisingId,
+  requestTrackingPermissionsAsync,
+  getTrackingPermissionsAsync,
+  isAvailable,
+} = await import('./tracking-transparency');
+
+afterEach(() => {
+  fakePlatform.OS = 'ios';
+  vi.clearAllMocks();
+});
+
+describe('getAdvertisingId', () => {
+  it('returns the advertising ID straight from the native module', () => {
+    expect(getAdvertisingId()).toBe('E9228286-4C4E-4789-9D95-15827DCB291B');
+  });
+
+  it('maps the all-zero UUID sentinel to null', () => {
+    FAKE_NATIVE_TRACKING_TRANSPARENCY.getAdvertisingId.mockReturnValueOnce(
+      '00000000-0000-0000-0000-000000000000',
+    );
+
+    expect(getAdvertisingId()).toBeNull();
+  });
+});
+
+describe('requestTrackingPermissionsAsync', () => {
+  it('always resolves granted on Android without calling the native module', async () => {
+    fakePlatform.OS = 'android';
+
+    await expect(requestTrackingPermissionsAsync()).resolves.toEqual({
+      granted: true,
+      expires: 'never',
+      canAskAgain: true,
+      status: 'granted',
+    });
+    expect(FAKE_NATIVE_TRACKING_TRANSPARENCY.requestPermissionsAsync).not.toHaveBeenCalled();
+  });
+
+  it('delegates to the native module on iOS', async () => {
+    fakePlatform.OS = 'ios';
+
+    await expect(requestTrackingPermissionsAsync()).resolves.toEqual({
+      status: 'granted',
+      granted: true,
+    });
+    expect(FAKE_NATIVE_TRACKING_TRANSPARENCY.requestPermissionsAsync).toHaveBeenCalledTimes(1);
+  });
+
+  it('throws an UnavailabilityError-shaped error on iOS when the native method is absent', async () => {
+    fakePlatform.OS = 'ios';
+    const { requestPermissionsAsync: native } = FAKE_NATIVE_TRACKING_TRANSPARENCY;
+    // @ts-expect-error -- simulating a native module build missing this method
+    FAKE_NATIVE_TRACKING_TRANSPARENCY.requestPermissionsAsync = undefined;
+
+    await expect(requestTrackingPermissionsAsync()).rejects.toThrow(
+      'requestPermissionsAsync is not available on TrackingTransparency',
+    );
+
+    FAKE_NATIVE_TRACKING_TRANSPARENCY.requestPermissionsAsync = native;
+  });
+});
+
+describe('getTrackingPermissionsAsync', () => {
+  it('always resolves granted on Android without calling the native module', async () => {
+    fakePlatform.OS = 'android';
+
+    await expect(getTrackingPermissionsAsync()).resolves.toEqual({
+      granted: true,
+      expires: 'never',
+      canAskAgain: true,
+      status: 'granted',
+    });
+    expect(FAKE_NATIVE_TRACKING_TRANSPARENCY.getPermissionsAsync).not.toHaveBeenCalled();
+  });
+
+  it('delegates to the native module on iOS', async () => {
+    fakePlatform.OS = 'ios';
+
+    await expect(getTrackingPermissionsAsync()).resolves.toEqual({
+      status: 'granted',
+      granted: true,
+    });
+    expect(FAKE_NATIVE_TRACKING_TRANSPARENCY.getPermissionsAsync).toHaveBeenCalledTimes(1);
+  });
+
+  it('throws an UnavailabilityError-shaped error on iOS when the native method is absent', async () => {
+    fakePlatform.OS = 'ios';
+    const { getPermissionsAsync: native } = FAKE_NATIVE_TRACKING_TRANSPARENCY;
+    // @ts-expect-error -- simulating a native module build missing this method
+    FAKE_NATIVE_TRACKING_TRANSPARENCY.getPermissionsAsync = undefined;
+
+    await expect(getTrackingPermissionsAsync()).rejects.toThrow(
+      'getPermissionsAsync is not available on TrackingTransparency',
+    );
+
+    FAKE_NATIVE_TRACKING_TRANSPARENCY.getPermissionsAsync = native;
+  });
+});
+
+describe('isAvailable', () => {
+  it('resolves true when the native module resolved', () => {
+    expect(isAvailable()).toBe(true);
+  });
+});

package/src/core/tracking-transparency.ts

@@ -0,0 +1,66 @@
+// Hand-ported from .vendors/expo/packages/expo-tracking-transparency/src/TrackingTransparency.ts
+// (sdk-57, verified via `git -C .vendors/expo show origin/sdk-57:...` — the vendored working
+// tree is on `main` and imports createPermissionHook/PermissionResponse from the `expo`
+// meta-package instead of expo-modules-core). createPermissionHook/useTrackingPermissions are
+// NOT ported here — that helper is React-only (built on useState/useEffect), and this repo's
+// convention is for each adapter to hand-roll its own permission hook instead (react/hooks,
+// vue/composables, angular/services), same as brightness/cellular already do.
+import { Platform, PermissionStatus, UnavailabilityError } from 'expo-modules-core';
+import type { PermissionResponse } from 'expo-modules-core';
+
+import { expoTrackingTransparency } from './native-module';
+
+const NATIVE_MODULE_NAME = 'TrackingTransparency';
+
+/**
+ * Gets the advertising ID, a UUID string intended only for advertising. Returns `null` on the
+ * iOS simulator, when tracking hasn't been authorized via `requestTrackingPermissionsAsync`, or
+ * when the user declined.
+ */
+export function getAdvertisingId(): string | null {
+  const advertisingId = expoTrackingTransparency.getAdvertisingId();
+  if (advertisingId === '00000000-0000-0000-0000-000000000000') {
+    return null;
+  }
+  return advertisingId;
+}
+
+const androidAndWebPermissionsResponse: PermissionResponse = {
+  granted: true,
+  expires: 'never',
+  canAskAgain: true,
+  status: PermissionStatus.GRANTED,
+};
+
+/**
+ * Requests the user to authorize or deny access to app-related data that can be used for
+ * tracking. On Android and web this always resolves granted.
+ */
+export async function requestTrackingPermissionsAsync(): Promise<PermissionResponse> {
+  if (Platform.OS !== 'ios') {
+    return Promise.resolve(androidAndWebPermissionsResponse);
+  }
+  if (!expoTrackingTransparency.requestPermissionsAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'requestPermissionsAsync');
+  }
+  return await expoTrackingTransparency.requestPermissionsAsync();
+}
+
+/**
+ * Checks whether the user has authorized the app to access tracking-related data. On Android and
+ * web this always resolves granted.
+ */
+export async function getTrackingPermissionsAsync(): Promise<PermissionResponse> {
+  if (Platform.OS !== 'ios') {
+    return Promise.resolve(androidAndWebPermissionsResponse);
+  }
+  if (!expoTrackingTransparency.getPermissionsAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getPermissionsAsync');
+  }
+  return await expoTrackingTransparency.getPermissionsAsync();
+}
+
+/** Whether the tracking-transparency native module resolved at all. */
+export function isAvailable(): boolean {
+  return Boolean(expoTrackingTransparency);
+}

package/src/react/hooks/use-permissions/index.ts

@@ -0,0 +1,41 @@
+// React lifecycle wiring over the framework-agnostic core (core/tracking-transparency.ts) —
+// auto-fetches the current permission status on mount, then exposes get/request as imperative
+// callbacks. Mirrors the shape @symbiote-native/cellular's own usePermissions ships in parallel,
+// so both stay byte-for-byte consistent.
+import { useCallback, useEffect, useRef, useState } from 'react';
+import {
+  getTrackingPermissionsAsync,
+  requestTrackingPermissionsAsync,
+  type PermissionResponse,
+} from '../../../core';
+
+export function usePermissions(): [
+  PermissionResponse | null,
+  () => Promise<PermissionResponse>,
+  () => Promise<PermissionResponse>,
+] {
+  const isMounted = useRef(true);
+  const [status, setStatus] = useState<PermissionResponse | null>(null);
+
+  const getPermission = useCallback(async () => {
+    const response = await getTrackingPermissionsAsync();
+    if (isMounted.current) setStatus(response);
+    return response;
+  }, []);
+
+  const requestPermission = useCallback(async () => {
+    const response = await requestTrackingPermissionsAsync();
+    if (isMounted.current) setStatus(response);
+    return response;
+  }, []);
+
+  useEffect(() => {
+    isMounted.current = true;
+    void getPermission();
+    return () => {
+      isMounted.current = false;
+    };
+  }, [getPermission]);
+
+  return [status, requestPermission, getPermission];
+}