@joryio/web-sdk 0.0.0-stage → 1.3.0-beta.1

package/src/core/session.ts

@@ -0,0 +1,311 @@
+/**
+ * Session Manager for tracking user sessions
+ */
+
+import { StorageManager } from './storage';
+import { Logger } from '../utils/logger';
+import { generateShortId } from '../utils/uuid';
+
+export const SESSION_ID_KEY = 'session_id';
+const SESSION_START_KEY = 'session_start';
+const LAST_ACTIVITY_KEY = 'last_activity';
+/**
+ * How often the last-activity stamp is actually written to storage. It only
+ * feeds a 30-minute timeout decision, so a 30s resolution is far more precision
+ * than the decision needs — see updateActivity().
+ */
+const ACTIVITY_PERSIST_INTERVAL_MS = 30_000;
+const DEFAULT_SESSION_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+const MAX_SESSION_AGE_MS = 24 * 60 * 60 * 1000; // 24 hours max session age
+
+export interface SessionInfo {
+  sessionId: string;
+  sessionStart: number;
+  lastActivity: number;
+  isNewSession: boolean;
+}
+
+export class SessionManager {
+  private storage: StorageManager;
+  private logger: Logger;
+  private sessionTimeoutMs: number;
+  private currentSessionId: string | null = null;
+  /** Exact in-memory activity time; the persisted copy is throttled. */
+  private lastActivityAt = 0;
+  private lastActivityPersistedAt = 0;
+  private isNewSession: boolean = false;
+  private onNewSessionCallback: (() => void) | null = null;
+  private boundVisibilityHandler: (() => void) | null = null;
+
+  constructor(storage: StorageManager, logger: Logger, sessionTimeoutMs?: number) {
+    this.storage = storage;
+    this.logger = logger;
+    this.sessionTimeoutMs = sessionTimeoutMs || DEFAULT_SESSION_TIMEOUT_MS;
+
+    // Initialize session on construction
+    this.initializeSession();
+
+    // Listen for visibility changes to check session when tab becomes visible
+    if (typeof document !== 'undefined') {
+      this.boundVisibilityHandler = () => {
+        if (document.visibilityState === 'visible') {
+          this.checkAndRefreshSession();
+        }
+      };
+      document.addEventListener('visibilitychange', this.boundVisibilityHandler);
+    }
+  }
+
+  /**
+   * Set callback to be called when a new session is created (e.g., to track session start)
+   */
+  onNewSession(callback: () => void): void {
+    this.onNewSessionCallback = callback;
+  }
+
+  /**
+   * Initialize or resume session
+   */
+  private initializeSession(): void {
+    const existingSessionId = this.storage.get<string>(SESSION_ID_KEY);
+    const lastActivity = this.storage.get<number>(LAST_ACTIVITY_KEY);
+    const sessionStart = this.storage.get<number>(SESSION_START_KEY);
+
+    if (existingSessionId && lastActivity) {
+      const now = Date.now();
+      const timeSinceLastActivity = now - lastActivity;
+      const sessionAge = sessionStart ? now - sessionStart : Infinity;
+
+      // Check both inactivity timeout AND max session age
+      // This prevents sessions from being kept alive indefinitely by background tabs
+      if (timeSinceLastActivity < this.sessionTimeoutMs && sessionAge < MAX_SESSION_AGE_MS) {
+        // Resume existing session
+        this.currentSessionId = existingSessionId;
+        this.isNewSession = false;
+        this.updateActivity();
+        this.logger.debug(`Resumed session: ${this.currentSessionId}`);
+        return;
+      } else if (sessionAge >= MAX_SESSION_AGE_MS) {
+        this.logger.debug(`Session too old (${Math.round(sessionAge / 1000 / 60 / 60)}h), creating new session`);
+      } else {
+        this.logger.debug(`Session expired (${timeSinceLastActivity}ms since last activity)`);
+      }
+    }
+
+    // Create new session
+    this.startNewSession();
+  }
+
+  /**
+   * Start a new session
+   */
+  private startNewSession(): void {
+    const previousSessionId = this.currentSessionId;
+    this.currentSessionId = generateShortId();
+    this.isNewSession = true;
+    const now = Date.now();
+
+    this.storage.set(SESSION_ID_KEY, this.currentSessionId);
+    this.storage.set(SESSION_START_KEY, now);
+    this.storage.set(LAST_ACTIVITY_KEY, now);
+    this.lastActivityAt = now;
+    this.lastActivityPersistedAt = now;
+
+    this.logger.debug(`Started new session: ${this.currentSessionId}`);
+
+    // Call the callback if this is a session refresh (not initial creation)
+    if (previousSessionId && this.onNewSessionCallback) {
+      this.onNewSessionCallback();
+    }
+  }
+
+  /**
+   * Check session validity and refresh if needed (called when tab becomes visible)
+   */
+  private checkAndRefreshSession(): void {
+    const lastActivity = this.storage.get<number>(LAST_ACTIVITY_KEY);
+    const sessionStart = this.storage.get<number>(SESSION_START_KEY);
+
+    if (lastActivity && sessionStart) {
+      const now = Date.now();
+      const timeSinceLastActivity = now - lastActivity;
+      const sessionAge = now - sessionStart;
+
+      // Check if session should expire
+      if (timeSinceLastActivity >= this.sessionTimeoutMs) {
+        this.logger.debug(`Session expired on tab focus (${Math.round(timeSinceLastActivity / 1000 / 60)} min inactive)`);
+        this.startNewSession();
+      } else if (sessionAge >= MAX_SESSION_AGE_MS) {
+        this.logger.debug(`Session too old on tab focus (${Math.round(sessionAge / 1000 / 60 / 60)}h old)`);
+        this.startNewSession();
+      }
+    }
+  }
+
+  /**
+   * End the session if it timed out or outlived its maximum age, and start a
+   * new one (its Session Start comes from the onNewSession hook). Called on
+   * every track(): the visibility check alone never ended a session in a tab
+   * that stayed visible (contract item 32). Returns true when a new session
+   * began.
+   */
+  refreshIfExpired(): boolean {
+    if (!this.currentSessionId) return false;
+    const now = Date.now();
+    // The later of this tab's exact stamp and the stored one (another tab
+    // of the same site keeps the session alive too).
+    const lastActivity = Math.max(this.lastActivityAt, this.storage.get<number>(LAST_ACTIVITY_KEY) || 0) || now;
+    const sessionStart = this.storage.get<number>(SESSION_START_KEY) || now;
+    if (now - lastActivity >= this.sessionTimeoutMs) {
+      this.logger.debug(`Session expired (${Math.round((now - lastActivity) / 1000 / 60)} min inactive)`);
+      this.startNewSession();
+      return true;
+    }
+    if (now - sessionStart >= MAX_SESSION_AGE_MS) {
+      this.logger.debug('Session reached its maximum age');
+      this.startNewSession();
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Update last activity timestamp (call this when tracking events)
+   */
+  updateActivity(): void {
+    if (!this.currentSessionId) return;
+
+    // Written on EVERY tracked event, and localStorage.setItem is synchronous
+    // main-thread I/O. A page that tracks a burst (scroll, product impressions)
+    // paid one write per event: measured in headless Chrome as 40 writes for a
+    // 40-event burst.
+    //
+    // The stamp only has to be accurate enough to judge a 30-MINUTE session
+    // timeout, so persisting at most once every 30 seconds is ~60x fewer writes
+    // and cannot change a timeout decision. The in-memory value stays exact; only
+    // the persisted copy is throttled, so the worst case after an abrupt tab
+    // close is a stamp up to 30s stale against a 30min threshold.
+    const now = Date.now();
+    this.lastActivityAt = now;
+    if (now - this.lastActivityPersistedAt < ACTIVITY_PERSIST_INTERVAL_MS) return;
+    this.lastActivityPersistedAt = now;
+    this.storage.set(LAST_ACTIVITY_KEY, now);
+  }
+
+  /**
+   * Get current session information
+   */
+  getSessionInfo(): SessionInfo {
+    // A READ (rule 54): never starts or extends a session. With none (after
+    // wipeData(), before the next tracked event) the id is ''.
+    const sessionId = this.currentSessionId || this.storage.get<string>(SESSION_ID_KEY) || '';
+
+    const sessionStart = this.storage.get<number>(SESSION_START_KEY) || Date.now();
+    // In-memory value first: it is exact, whereas the persisted copy is
+    // throttled to one write per ACTIVITY_PERSIST_INTERVAL_MS.
+    const lastActivity =
+      this.lastActivityAt || this.storage.get<number>(LAST_ACTIVITY_KEY) || Date.now();
+
+    return {
+      sessionId,
+      sessionStart,
+      lastActivity,
+      isNewSession: this.isNewSession,
+    };
+  }
+
+  /**
+   * Get current session ID
+   */
+  getSessionId(): string {
+    // A READ (rule 54): in-app sync, resolve and impressions read the id, and
+    // a read used to start a session silently - one with no Session Start.
+    return this.currentSessionId || this.storage.get<string>(SESSION_ID_KEY) || '';
+  }
+
+  /**
+   * The lifecycle path: the current session, or a new one when there is none
+   * (after wipeData()). A new one is announced through onNewSession - which
+   * tracks its Session Start - so no session ever starts without one.
+   * Returns the session id.
+   */
+  ensureSession(): string {
+    if (this.currentSessionId) return this.currentSessionId;
+    const stored = this.storage.get<string>(SESSION_ID_KEY);
+    if (stored) {
+      this.currentSessionId = stored;
+      return stored;
+    }
+    this.currentSessionId = generateShortId();
+    this.isNewSession = true;
+    const now = Date.now();
+    this.storage.set(SESSION_ID_KEY, this.currentSessionId);
+    this.storage.set(SESSION_START_KEY, now);
+    this.storage.set(LAST_ACTIVITY_KEY, now);
+    this.lastActivityAt = now;
+    this.lastActivityPersistedAt = now;
+    this.logger.debug(`Started new session: ${this.currentSessionId}`);
+    if (this.onNewSessionCallback) this.onNewSessionCallback();
+    return this.currentSessionId;
+  }
+
+  /**
+   * Another tab changed the visitor (its reset()): take over the session it
+   * stored - it started that session and sent its Session Start - instead of
+   * carrying the outgoing visitor's session id in memory here. No stored
+   * session (a wipe there): this one is forgotten too, and the next call that
+   * needs one starts it (with its Session Start). Returns true when the
+   * session id here changed.
+   */
+  followStoredSession(): boolean {
+    const stored = this.storage.get<string>(SESSION_ID_KEY);
+    if (stored === this.currentSessionId) return false;
+    this.currentSessionId = stored || null;
+    this.isNewSession = false;
+    this.lastActivityAt = stored ? this.storage.get<number>(LAST_ACTIVITY_KEY) || Date.now() : 0;
+    this.lastActivityPersistedAt = this.lastActivityAt;
+    this.logger.debug(`Following the session another tab started: ${stored || '(none)'}`);
+    return true;
+  }
+
+  /**
+   * Manually renew the session (reset timeout)
+   */
+  renewSession(): void {
+    this.updateActivity();
+    this.logger.debug(`Session renewed: ${this.currentSessionId}`);
+  }
+
+  /**
+   * Force start a new session
+   */
+  resetSession(): void {
+    this.logger.debug(`Resetting session (was: ${this.currentSessionId})`);
+    this.startNewSession();
+  }
+
+  /**
+   * Forget the session entirely (wipeData). The next call that needs a session
+   * starts a fresh one; no Session Start is tracked for it, because nothing
+   * about the wiped visitor may carry over.
+   */
+  clear(): void {
+    this.currentSessionId = null;
+    this.isNewSession = false;
+    this.lastActivityAt = 0;
+    this.lastActivityPersistedAt = 0;
+    this.storage.remove(SESSION_ID_KEY);
+    this.storage.remove(SESSION_START_KEY);
+    this.storage.remove(LAST_ACTIVITY_KEY);
+  }
+
+  /**
+   * Cleanup session manager
+   */
+  destroy(): void {
+    if (this.boundVisibilityHandler && typeof document !== 'undefined') {
+      document.removeEventListener('visibilitychange', this.boundVisibilityHandler);
+      this.boundVisibilityHandler = null;
+    }
+  }
+}

package/src/core/storage.ts

@@ -0,0 +1,157 @@
+/**
+ * Storage Manager for localStorage with fallback to in-memory storage
+ */
+
+import { Logger } from '../utils/logger';
+import { bucketHash } from '../utils/bucket-hash';
+
+interface StorageItem<T = any> {
+  value: T;
+  expiresAt: number | null;
+}
+
+export class StorageManager {
+  private prefix: string;
+  private memoryStore: Map<string, StorageItem> = new Map();
+  private isLocalStorageAvailable: boolean;
+  private logger: Logger;
+
+  /**
+   * Namespaces this workspace's localStorage so two SDK keys on one origin do
+   * not share a deviceId, session or consent state.
+   *
+   * Was the Java String.hashCode recurrence (`hash * 31 + char`), the last
+   * inline copy of it in the repo after every bucketing site moved to the
+   * shared util. Measured on real-format keys (`jry_live_<32 random>`) that
+   * recurrence was only ~2x worse than ideal here rather than dangerous - the
+   * shared `jry_live_` prefix is the part it weights LEAST, and the random tail
+   * dominates - and a single origin carries one or two SDK keys, so collisions
+   * were never a practical risk.
+   *
+   * It was replaced anyway, and the reason is timing rather than risk: the
+   * prefix is baked into every stored key, so changing it orphans every
+   * browser's deviceId, session and consent. That costs nothing today and can
+   * never be done again once real visitors hold state. Taking the free move now
+   * leaves ONE hash in the codebase with no exception to remember.
+   */
+  private static hashKey(key: string): string {
+    return bucketHash(key).toString(36);
+  }
+
+  constructor(sdkKey: string, logger: Logger) {
+    this.prefix = `jry_${StorageManager.hashKey(sdkKey)}_`;
+    this.logger = logger;
+    this.isLocalStorageAvailable = this.checkLocalStorageAvailable();
+
+    if (!this.isLocalStorageAvailable) {
+      this.logger.warn('LocalStorage not available, using in-memory storage');
+    }
+  }
+
+  private checkLocalStorageAvailable(): boolean {
+    try {
+      const testKey = '__jry_test__';
+      localStorage.setItem(testKey, 'test');
+      localStorage.removeItem(testKey);
+      return true;
+    } catch (e) {
+      return false;
+    }
+  }
+
+  private getKey(key: string): string {
+    return `${this.prefix}${key}`;
+  }
+
+  /** The localStorage key one SDK key is stored under (to read `storage` events of other tabs). */
+  storageKeyFor(key: string): string {
+    return this.getKey(key);
+  }
+
+  set<T>(key: string, value: T, expiresInDays?: number): void {
+    const item: StorageItem<T> = {
+      value,
+      expiresAt: expiresInDays
+        ? Date.now() + expiresInDays * 24 * 60 * 60 * 1000
+        : null,
+    };
+
+    if (this.isLocalStorageAvailable) {
+      try {
+        localStorage.setItem(this.getKey(key), JSON.stringify(item));
+        this.memoryStore.delete(key);
+      } catch (e) {
+        this.logger.error('Failed to write to localStorage:', e);
+        // Fallback to memory - and the OLD stored value goes, or get() would
+        // keep preferring it (a stale event queue re-sent on the next page).
+        try {
+          localStorage.removeItem(this.getKey(key));
+        } catch {
+          // nothing more to do
+        }
+        this.memoryStore.set(key, item);
+      }
+    } else {
+      this.memoryStore.set(key, item);
+    }
+  }
+
+  get<T>(key: string): T | null {
+    let item: StorageItem<T> | null = null;
+
+    if (this.isLocalStorageAvailable) {
+      try {
+        const stored = localStorage.getItem(this.getKey(key));
+        if (stored) {
+          item = JSON.parse(stored);
+        }
+      } catch (e) {
+        this.logger.error('Failed to read from localStorage:', e);
+        try { localStorage.removeItem(this.getKey(key)); } catch {}
+      }
+    }
+
+    // Fallback to memory store
+    if (!item) {
+      item = this.memoryStore.get(key) as StorageItem<T> || null;
+    }
+
+    // Check expiration
+    if (item && item.expiresAt && item.expiresAt < Date.now()) {
+      this.remove(key);
+      return null;
+    }
+
+    return item?.value ?? null;
+  }
+
+  remove(key: string): void {
+    if (this.isLocalStorageAvailable) {
+      try {
+        localStorage.removeItem(this.getKey(key));
+      } catch (e) {
+        this.logger.error('Failed to remove from localStorage:', e);
+      }
+    }
+    this.memoryStore.delete(key);
+  }
+
+  clear(): void {
+    if (this.isLocalStorageAvailable) {
+      try {
+        // Remove only keys with our prefix
+        const keysToRemove: string[] = [];
+        for (let i = 0; i < localStorage.length; i++) {
+          const key = localStorage.key(i);
+          if (key && key.startsWith(this.prefix)) {
+            keysToRemove.push(key);
+          }
+        }
+        keysToRemove.forEach((key) => localStorage.removeItem(key));
+      } catch (e) {
+        this.logger.error('Failed to clear localStorage:', e);
+      }
+    }
+    this.memoryStore.clear();
+  }
+}

package/src/core/user.ts

@@ -0,0 +1,203 @@
+/**
+ * Joryio SDK User
+ * Provides methods to update user subscription status
+ * Write-only for security - no getter methods
+ */
+
+import { Logger } from '../utils/logger';
+import { NetworkClient } from './network';
+import { IdentityManager } from './identity';
+import type { WriteRunner, WriteRecord } from './write-retry';
+
+/**
+ * Subscription status types
+ * - OPTED_IN: User has explicitly opted in (e.g., confirmed double opt-in)
+ * - SUBSCRIBED: User is subscribed but hasn't explicitly opted in
+ * - UNSUBSCRIBED: User has opted out
+ */
+export enum SubscriptionStatus {
+  // Wire value MUST be camelCase `optedIn` — the backend `@IsIn`/`@IsEnum`
+  // (sdk-subscriptions.controller.ts, update-channel-subscription.dto.ts) 400s
+  // on snake_case `opted_in` (a NormalizeEnumCasing migration renamed the stored
+  // value). See docs/SSOT_DRIFT_AUDIT.md B7 — the enum NAME stays OPTED_IN.
+  OPTED_IN = 'optedIn',
+  SUBSCRIBED = 'subscribed',
+  UNSUBSCRIBED = 'unsubscribed',
+}
+
+/**
+ * Channel types for subscriptions
+ */
+/*
+ * MIRRORS the backend's SUBSCRIPTION_CHANNELS, which is five, not four.
+ *
+ * `viber` was added there and never here, so this SDK refused locally - with a
+ * logged error and no request - a channel the backend accepts. Viber is a
+ * first-class campaign channel, so a web preference centre simply could not
+ * offer it, and the failure was client-side and silent to the server.
+ */
+export type SubscriptionChannel = 'email' | 'sms' | 'whatsapp' | 'push' | 'viber';
+
+/** The runtime list, so validation and the type cannot drift apart. */
+export const SUBSCRIPTION_CHANNELS: readonly SubscriptionChannel[] = [
+  'email',
+  'sms',
+  'whatsapp',
+  'push',
+  'viber',
+];
+
+/**
+ * Subscription preferences object for bulk updates
+ */
+export type SubscriptionPreferences = Partial<Record<SubscriptionChannel, SubscriptionStatus>>;
+
+export class User {
+  private logger: Logger;
+  private network: NetworkClient;
+  private identity: IdentityManager;
+  private apiEndpoint: string;
+  private runWrite: WriteRunner;
+
+  constructor(
+    logger: Logger,
+    network: NetworkClient,
+    identity: IdentityManager,
+    apiEndpoint: string,
+    runWrite?: WriteRunner,
+  ) {
+    this.logger = logger;
+    this.network = network;
+    this.identity = identity;
+    this.apiEndpoint = apiEndpoint;
+    // Standalone use (tests): send once, immediately. The SDK passes its
+    // persisted, ordered outbox (outbox.ts) instead.
+    this.runWrite =
+      runWrite ||
+      ((label, record) => {
+        this.sendOnce(record).then(
+          (res) => {
+            if (!res.ok) this.logger.error(`${label} failed (HTTP ${res.status || 'no response'})`);
+          },
+          (error) => this.logger.error(`${label} failed:`, error),
+        );
+      });
+  }
+
+  private sendOnce(record: WriteRecord) {
+    if (record.kind === 'subscription') return this.network.sendSubscriptionUpdate(this.apiEndpoint, record.payload);
+    if (record.kind === 'group') return this.network.sendSubscriptionGroupUpdate(this.apiEndpoint, record.payload);
+    return Promise.resolve({ ok: false, status: 0 });
+  }
+
+  /**
+   * Both ids, captured NOW. The server resolves `userId` first and falls back
+   * to `anonymousId`, so a visitor whose identify has not been merged yet is
+   * still found. A write made while anonymous is sent with the user id once
+   * that anonymous id has been identified (resolved at send time by the
+   * outbox, contract item 38); a write of an earlier identity keeps its own.
+   */
+  private ids(): { userId?: string; anonymousId: string } {
+    const userId = this.identity.getUserId();
+    return { ...(userId ? { userId } : {}), anonymousId: this.identity.getAnonymousId() };
+  }
+
+  /**
+   * Set subscription status for a channel
+   * @param channel - The channel (email, sms, whatsapp, push, viber)
+   * @param status - The subscription status (OPTED_IN, SUBSCRIBED, UNSUBSCRIBED)
+   *
+   * @example
+   * user.setSubscription('email', SubscriptionStatus.OPTED_IN);
+   * user.setSubscription('sms', SubscriptionStatus.UNSUBSCRIBED);
+   */
+  setSubscription(channel: SubscriptionChannel, status: SubscriptionStatus): void {
+    // An unsubscribe is a WITHDRAWAL: it is delivered even after optOut(), a
+    // denied consent or wipeData() (contract item 36). Any other status stops
+    // with them.
+    // Validate channel
+    if (!SUBSCRIPTION_CHANNELS.includes(channel)) {
+      this.logger.error(
+        `Invalid channel: ${channel}. Must be one of: ${SUBSCRIPTION_CHANNELS.join(', ')}`,
+      );
+      return;
+    }
+
+    // Validate status
+    const validStatuses = Object.values(SubscriptionStatus);
+    if (!validStatuses.includes(status)) {
+      this.logger.error(`Invalid status: ${status}. Must be one of: ${validStatuses.join(', ')}`);
+      return;
+    }
+
+    this.logger.debug(`Setting ${channel} subscription status to ${status}`);
+    const payload = { channel, status, ...this.ids() };
+    this.runWrite(`Update ${channel} subscription`, { kind: 'subscription', payload });
+  }
+
+  /**
+   * Set multiple channel subscriptions at once
+   * @param preferences - Object mapping channels to their subscription status
+   *
+   * @example
+   * user.setSubscriptions({
+   *   email: SubscriptionStatus.OPTED_IN,
+   *   sms: SubscriptionStatus.SUBSCRIBED,
+   *   push: SubscriptionStatus.UNSUBSCRIBED
+   * });
+   */
+  setSubscriptions(preferences: SubscriptionPreferences): void {
+    if (!preferences || typeof preferences !== 'object') {
+      this.logger.error('setSubscriptions requires an object, e.g. { email: SubscriptionStatus.OPTED_IN }');
+      return;
+    }
+    for (const [channel, status] of Object.entries(preferences)) {
+      if (status !== undefined) {
+        this.setSubscription(channel as SubscriptionChannel, status);
+      }
+    }
+  }
+
+  /**
+   * Add user to a subscription group (list)
+   * @param groupId - The subscription group/list ID
+   * @param channel - Optional channel for the subscription (defaults to email)
+   *
+   * @example
+   * user.addToSubscriptionGroup('list_abc123');
+   * user.addToSubscriptionGroup('list_abc123', 'sms');
+   */
+  addToSubscriptionGroup(groupId: string, channel: SubscriptionChannel = 'email'): void {
+    this.updateGroup(groupId, channel, 'subscribe');
+  }
+
+  /**
+   * Remove user from a subscription group (list)
+   * @param groupId - The subscription group/list ID
+   * @param channel - Optional channel for the subscription (defaults to email)
+   *
+   * @example
+   * user.removeFromSubscriptionGroup('list_abc123');
+   * user.removeFromSubscriptionGroup('list_abc123', 'sms');
+   */
+  removeFromSubscriptionGroup(groupId: string, channel: SubscriptionChannel = 'email'): void {
+    this.updateGroup(groupId, channel, 'unsubscribe');
+  }
+
+  private updateGroup(groupId: string, channel: SubscriptionChannel, action: 'subscribe' | 'unsubscribe'): void {
+    if (typeof groupId !== 'string' || !groupId) {
+      this.logger.error(`Cannot ${action} subscription group: groupId is required`);
+      return;
+    }
+    if (!SUBSCRIPTION_CHANNELS.includes(channel)) {
+      this.logger.error(
+        `Invalid channel: ${channel}. Must be one of: ${SUBSCRIPTION_CHANNELS.join(', ')}`,
+      );
+      return;
+    }
+
+    this.logger.debug(`${action} subscription group ${groupId} for channel ${channel}`);
+    const payload = { groupId, channel, action, ...this.ids() };
+    this.runWrite(`Subscription group ${groupId} ${action}`, { kind: 'group', payload });
+  }
+}