feat: Implement goals for client-side SDKs. (#585)

Implements goals. Additionally adds browser specific configuration as it
is required by goals.

Also addresses SDK-563

packages/sdk/browser/__tests__/goals/GoalManager.test.ts

@@ -0,0 +1,114 @@
+import { jest } from '@jest/globals';
+
+import { LDUnexpectedResponseError, Requests } from '@launchdarkly/js-client-sdk-common';
+
+import GoalManager from '../../src/goals/GoalManager';
+import { Goal } from '../../src/goals/Goals';
+import { LocationWatcher } from '../../src/goals/LocationWatcher';
+
+describe('given a GoalManager with mocked dependencies', () => {
+  let mockRequests: jest.Mocked<Requests>;
+  let mockReportError: jest.Mock;
+  let mockReportGoal: jest.Mock;
+  let mockLocationWatcherFactory: () => { cb?: () => void } & LocationWatcher;
+  let mockLocationWatcher: { cb?: () => void } & LocationWatcher;
+  let goalManager: GoalManager;
+  const mockCredential = 'test-credential';
+
+  beforeEach(() => {
+    mockRequests = { fetch: jest.fn() } as any;
+    mockReportError = jest.fn();
+    mockReportGoal = jest.fn();
+    mockLocationWatcher = { close: jest.fn() };
+    // @ts-expect-error The type is correct, but TS cannot handle the jest.fn typing
+    mockLocationWatcherFactory = jest.fn((cb: () => void) => {
+      mockLocationWatcher.cb = cb;
+      return mockLocationWatcher;
+    });
+
+    goalManager = new GoalManager(
+      mockCredential,
+      mockRequests,
+      'polling',
+      mockReportError,
+      mockReportGoal,
+      mockLocationWatcherFactory,
+    );
+  });
+
+  it('should fetch goals and set up the location watcher', async () => {
+    const mockGoals: Goal[] = [
+      { key: 'goal1', kind: 'click', selector: '#button1' },
+      { key: 'goal2', kind: 'click', selector: '#button2' },
+    ];
+
+    mockRequests.fetch.mockResolvedValue({
+      json: () => Promise.resolve(mockGoals),
+    } as any);
+
+    await goalManager.initialize();
+
+    expect(mockRequests.fetch).toHaveBeenCalledWith('polling/sdk/goals/test-credential');
+    expect(mockLocationWatcherFactory).toHaveBeenCalled();
+  });
+
+  it('should handle failed initial fetch by reporting an unexpected response error', async () => {
+    const error = new Error('Fetch failed');
+
+    mockRequests.fetch.mockRejectedValue(error);
+
+    await goalManager.initialize();
+
+    expect(mockReportError).toHaveBeenCalledWith(expect.any(LDUnexpectedResponseError));
+  });
+
+  it('should close the watcher and tracker when closed', () => {
+    goalManager.close();
+
+    expect(mockLocationWatcher.close).toHaveBeenCalled();
+  });
+
+  it('should not emit a goal on initial for a non-matching URL, but should emit after URL change to a matching URL', async () => {
+    const mockGoals: Goal[] = [
+      {
+        key: 'goal1',
+        kind: 'pageview',
+        urls: [
+          {
+            kind: 'exact',
+            url: 'https://example.com/target',
+          },
+        ],
+      },
+    ];
+
+    Object.defineProperty(window, 'location', {
+      value: { href: 'https://example.com/not-target' },
+      writable: true,
+    });
+
+    mockRequests.fetch.mockResolvedValue({
+      json: () => Promise.resolve(mockGoals),
+    } as any);
+    await goalManager.initialize();
+
+    // Check that no goal was emitted on initial load
+    expect(mockReportGoal).not.toHaveBeenCalled();
+
+    // Simulate URL change to match the goal
+    Object.defineProperty(window, 'location', {
+      value: { href: 'https://example.com/target' },
+      writable: true,
+    });
+
+    // Trigger the location change callback
+    mockLocationWatcher.cb?.();
+
+    // Check that the goal was emitted after URL change
+    expect(mockReportGoal).toHaveBeenCalledWith('https://example.com/target', {
+      key: 'goal1',
+      kind: 'pageview',
+      urls: [{ kind: 'exact', url: 'https://example.com/target' }],
+    });
+  });
+});

packages/sdk/browser/__tests__/goals/GoalTracker.matchesUrl.test.ts

@@ -0,0 +1,115 @@
+import { Matcher } from '../../src/goals/Goals';
+import { matchesUrl } from '../../src/goals/GoalTracker';
+
+it.each([
+  ['https://example.com', '', '', 'https://example.com'],
+  [
+    'https://example.com?potato=true#hash',
+    '?potato=true',
+    '#hash',
+    'https://example.com?potato=true#hash',
+  ],
+])('returns true for exact match with "exact" matcher kind', (href, query, hash, matcherUrl) => {
+  const matcher: Matcher = { kind: 'exact', url: matcherUrl };
+  const result = matchesUrl(matcher, href, query, hash);
+  expect(result).toBe(true);
+});
+
+it.each([
+  ['https://example.com/potato', '', '', 'https://example.com'],
+  [
+    'https://example.com?potato=true#hash',
+    '?potato=true',
+    '#hash',
+    'https://example.com?potato=true#brown',
+  ],
+])('returns false for non-matching "exact" matcher kind', (href, query, hash, matcherUrl) => {
+  const matcher: Matcher = { kind: 'exact', url: matcherUrl };
+  const result = matchesUrl(matcher, href, query, hash);
+  expect(result).toBe(false);
+});
+
+it('returns true for canonical match with "canonical" matcher kind', () => {
+  // For this type of match the hash and query parameters are not included.
+  const matcher: Matcher = { kind: 'canonical', url: 'https://example.com/some-path' };
+  const result = matchesUrl(
+    matcher,
+    'https://example.com/some-path?query=1#hash',
+    '?query=1',
+    '#hash',
+  );
+  expect(result).toBe(true);
+});
+
+it('returns true for substring match with "substring" matcher kind', () => {
+  const matcher: Matcher = { kind: 'substring', substring: 'example' };
+  const result = matchesUrl(
+    matcher,
+    'https://example.com/some-path?query=1#hash',
+    '?query=1',
+    '#hash',
+  );
+  expect(result).toBe(true);
+});
+
+it('returns false for non-matching substring with "substring" matcher kind', () => {
+  const matcher: Matcher = { kind: 'substring', substring: 'nonexistent' };
+  const result = matchesUrl(
+    matcher,
+    'https://example.com/some-path?query=1#hash',
+    '?query=1',
+    '#hash',
+  );
+  expect(result).toBe(false);
+});
+
+it('returns true for regex match with "regex" matcher kind', () => {
+  const matcher: Matcher = { kind: 'regex', pattern: 'example\\.com' };
+  const result = matchesUrl(
+    matcher,
+    'https://example.com/some-path?query=1#hash',
+    '?query=1',
+    '#hash',
+  );
+  expect(result).toBe(true);
+});
+
+it('returns false for non-matching regex with "regex" matcher kind', () => {
+  const matcher: Matcher = { kind: 'regex', pattern: 'nonexistent\\.com' };
+  const result = matchesUrl(
+    matcher,
+    'https://example.com/some-path?query=1#hash',
+    '?query=1',
+    '#hash',
+  );
+  expect(result).toBe(false);
+});
+
+it('includes the hash for "path-like" hashes for "substring" matchers', () => {
+  const matcher: Matcher = { kind: 'substring', substring: 'example' };
+  const result = matchesUrl(
+    matcher,
+    'https://example.com/some-path?query=1#/hash/path',
+    '?query=1',
+    '#/hash/path',
+  );
+  expect(result).toBe(true);
+});
+
+it('includes the hash for "path-like" hashes for "regex" matchers', () => {
+  const matcher: Matcher = { kind: 'regex', pattern: 'hash' };
+  const result = matchesUrl(
+    matcher,
+    'https://example.com/some-path?query=1#/hash/path',
+    '?query=1',
+    '#/hash/path',
+  );
+  expect(result).toBe(true);
+});
+
+it('returns false for unsupported matcher kind', () => {
+  // @ts-expect-error
+  const matcher: Matcher = { kind: 'unsupported' };
+  const result = matchesUrl(matcher, 'https://example.com', '', '');
+  expect(result).toBe(false);
+});