@knocklabs/client 0.14.10-canary.2 → 0.14.11

package/CHANGELOG.md

@@ -0,0 +1,332 @@
+# Changelog
+
+## 0.14.11
+
+### Patch Changes
+
+- 6539c97: patch fix package contents being built properly
+
+## 0.14.10
+
+### Patch Changes
+
+- e05ad61: feat: Migrates the internal store library from zustand to @tanstack/store. This is a non-breaking change that maintains backwards compatibility with the @knocklabs/client and @knocklabs/react-core packages.
+- e05ad61: feat: Migrates the internal store library from zustand to @tanstack/store. This is a non-breaking change that maintains backwards compatibility with the @knocklabs/client and @knocklabs/react-core packages.
+- e05ad61: feat: Migrates the internal store library from zustand to @tanstack/store. This is a non-breaking change that maintains backwards compatibility with the @knocklabs/client and @knocklabs/react-core packages.
+
+## 0.14.10-canary.2
+
+### Patch Changes
+
+- e69da7b: feat: Migrates the internal store library from zustand to @tanstack/store. This is a non-breaking change that maintains backwards compatibility with the @knocklabs/client and @knocklabs/react-core packages.
+
+## 0.14.10-canary.1
+
+### Patch Changes
+
+- c76b2d9: feat: Migrates the internal store library from zustand to @tanstack/store. This is a non-breaking change that maintains backwards compatibility with the @knocklabs/client and @knocklabs/react-core packages.
+
+## 0.14.10-canary.0
+
+### Patch Changes
+
+- 86a72cc: feat: Migrates the internal store library from zustand to @tanstack/store. This is a non-breaking change that maintains backwards compatibility with the @knocklabs/client and @knocklabs/react-core packages.
+
+## 0.14.9
+
+### Patch Changes
+
+- 4e73f12: fix: ensure this is bound to guide client instance in handleLocationChange
+
+## 0.14.8
+
+### Patch Changes
+
+- 329ee05: downgrade tanstack store deps to 0.6.x to work in older TS version
+
+## 0.14.7
+
+### Patch Changes
+
+- efd1005: Fix CJS builds
+
+  v0.14.6 of our client SDK did not support CJS. This version fixes CJS support.
+
+## 0.14.6
+
+### Patch Changes
+
+- a5c615e: Allow multiple instances of `Feed` to listen for real-time updates to the same notification feed
+
+  Previously, using two or more instances of `Feed` with the same in-app feed channel would result in
+  only the most recently connected `Feed` receiving real-time updates. Now, all instances of `Feed`
+  configured with the same in-app channel will receive real-time updates.
+
+## 0.14.5
+
+### Patch Changes
+
+- 8f00623: activation location rules support for guides
+
+## 0.14.4
+
+### Patch Changes
+
+- e800896: feat: typescript fixes + quality of life improvements
+
+## 0.14.3
+
+### Patch Changes
+
+- c97a1d9: Update TanStack Store
+
+## 0.14.2
+
+### Patch Changes
+
+- 00439a2: fix(KNO-7843): Fix types and stringify trigger_data for feed API requests
+
+## 0.14.1
+
+### Patch Changes
+
+- 4c41841: feat: accept options in the fetchNextPage method
+
+## 0.14.0
+
+### Minor Changes
+
+- 711948c: feat: add guide client, hooks, provider, and components
+
+## 0.13.1
+
+### Patch Changes
+
+- 187abc1: Allows the feed to accept date range options upon initialization.
+
+## 0.13.0
+
+### Minor Changes
+
+- 4cd1b1e: add support for filtering by date in the feed client
+
+## 0.12.0
+
+### Minor Changes
+
+- 8ba5dcb: [JS] Support React 19 in React SDKs
+
+## 0.11.4
+
+### Patch Changes
+
+- 8ea25f4: fix: include missing timestamp fields on FeedItem and Message
+
+## 0.11.3
+
+### Patch Changes
+
+- 4f76cd6: fix: raise when calling user methods before auth
+
+## 0.11.2
+
+### Patch Changes
+
+- 2161d3f: Make id and displayName required in MsTeamsTeam and MsTeamsChannel types
+- 2161d3f: Add `ms_teams_team_id` to MsTeamsChannelConnection type
+- 1ba1393: add TeamsKit hooks for teams and channels
+- b4b5c02: add getTeams and getChannels to MsTeamsClient
+
+## 0.11.1
+
+### Patch Changes
+
+- b9f6712: fix: types for userId should handle undefined and null
+
+## 0.11.0
+
+### Minor Changes
+
+- 013ad8d: feat: add MsTeamsAuthButton
+
+## 0.10.17
+
+### Patch Changes
+
+- 26db496: fix: ensure feed can render with empty/missing userId values
+- 988aaf9: fix: engagement_status in BulkUpdateMessagesInChannelProperties type
+
+## 0.10.16
+
+### Patch Changes
+
+- bc99374: fix: bundle client package using "compat" interop
+
+## 0.10.15
+
+### Patch Changes
+
+- 26166e3: fix: update preference set types
+- Updated dependencies [26166e3]
+  - @knocklabs/types@0.1.5
+
+## 0.10.14
+
+### Patch Changes
+
+- 7510909: fix: ensure axios is always imported correctly
+
+## 0.10.13
+
+### Patch Changes
+
+- 1d440f7: feat: add prebuilt In App Feed Components for React Native
+
+## 0.10.12
+
+### Patch Changes
+
+- 5545f9e: feat: support passing metadata for interactions
+
+## 0.10.11
+
+### Patch Changes
+
+- 395f0ca: fix: check type of zustand default import and fix cjs build
+
+## 0.10.10
+
+### Patch Changes
+
+- a4d520c: chore: update generic types
+- Updated dependencies [a4d520c]
+  - @knocklabs/types@0.1.4
+
+## 0.10.9
+
+### Patch Changes
+
+- d0adb14: fix: don't destroy the store, ever
+
+## 0.10.8
+
+### Patch Changes
+
+- 29e3942: fix: introduce new useNotificationStore hook to prevent issues that prevent state updates
+
+## 0.10.7
+
+### Patch Changes
+
+- f25b112: fix: ensure feed store reference re-renders after changes to user
+
+## 0.10.6
+
+### Patch Changes
+
+- b29a47a: Add KnockExpoPushNotificationProvider to react-native sdk
+
+## 0.10.5
+
+### Patch Changes
+
+- 044eb0f: fix: check if document is defined before setting up auto socket manager
+
+## 0.10.4
+
+### Patch Changes
+
+- 5a7c56e: fix: avoid adding duplicate visibiliy change event listeners
+
+## 0.10.3
+
+### Patch Changes
+
+- a71ce51: fix: event types to use items. and fix types
+
+## 0.10.2
+
+### Patch Changes
+
+- 42ba22c: fix: improve typing for react < 18
+
+## 0.10.1
+
+### Patch Changes
+
+- 3c277cb: fix: remove react-query and replace with swr for react 16+ support
+- 567e24f: fix: clean up visibility change event listener on feed teardown
+
+## 0.10.0
+
+### Minor Changes
+
+- 8bdc75b: Added a new MessageClient to access message api's independently from the Feed.
+
+## 0.9.4
+
+### Patch Changes
+
+- f58371c: Added user get and identify methods
+
+## 0.9.3
+
+### Patch Changes
+
+- bc69618: Add react-native to package.json files to fix a bug in our React Native SDK
+
+## 0.9.2
+
+### Patch Changes
+
+- fed0f8c: add support for actions in notification feed cells
+
+## 0.9.1
+
+### Patch Changes
+
+- f37d680: Update event format for client status updates
+
+## 0.9.0
+
+### Minor Changes
+
+- 627e643: Add SlackKit components, hooks, client JS functions, and example apps.
+
+## 0.8.21
+
+### Patch Changes
+
+- c9faba5: fix esm build issues with mjs files
+
+## 0.8.20
+
+### Patch Changes
+
+- Re-releasing packages
+
+## 0.8.19
+
+### Patch Changes
+
+- 7786ec5: chore: upgrade to yarn modern and update local package references
+- 9dd0d15: feat: add onUserTokenExpiring callback option to client
+
+## 0.8.18
+
+### Patch Changes
+
+- e53c200: fix: strip socket manager options from http requests
+- d4ba1f2: chore: add shared types package
+
+## 0.8.17
+
+### Patch Changes
+
+- 345ebc1: feat: add option to automatically manage open socket connections
+
+## 0.8.16
+
+### Patch Changes
+
+- 7bc5e4a: fix: add @babel/runtime dependency

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knocklabs/client",
-  "version": "0.14.10-canary.2",
+  "version": "0.14.11",
   "description": "The clientside library for interacting with Knock",
   "homepage": "https://github.com/knocklabs/javascript/tree/main/packages/client",
   "author": "@knocklabs",
@@ -68,7 +68,7 @@
   },
   "dependencies": {
     "@babel/runtime": "^7.27.1",
-    "@knocklabs/types": "workspace:^",
+    "@knocklabs/types": "^0.1.5",
     "@tanstack/store": "^0.7.1",
     "@types/phoenix": "^1.6.6",
     "axios": "^1.9.0",
@@ -79,4 +79,4 @@
     "phoenix": "1.7.19",
     "urlpattern-polyfill": "^10.0.0"
   }
-}
+}

package/test/README.md

@@ -0,0 +1,590 @@
+# Testing Guide for Knock Client
+
+This directory contains all tests for the Knock JavaScript client. This guide will help you understand our testing patterns, utilities, and how to write effective tests.
+
+## 📁 Test Structure
+
+```
+test/
+├── README.md               # This guide
+├── setup.ts                # Global test configuration
+├── test-utils/             # Shared testing utilities
+│   ├── fixtures.ts         # Test data generators
+│   ├── mocks.ts            # Mock factories
+│   └── property-testing.ts # Property-based testing tools
+├── clients/                # Client-specific tests
+│   ├── feed/               # Feed client tests
+│   ├── messages/           # Messages client tests
+│   ├── users/              # Users client tests
+│   └── ...                 # Other client tests
+├── knock.test.ts           # Main Knock class tests
+├── api.test.ts             # API client tests
+├── helpers.test.ts         # Utility functions tests
+└── ...                     # Other core tests
+```
+
+## 🚀 Quick Start: Writing Your First Test
+
+Here's a simple test to get you started:
+
+```typescript
+import { describe, expect, test } from "vitest";
+
+import { createMockKnock } from "./test-utils/mocks";
+
+describe("My Feature", () => {
+  test("should do something", () => {
+    const { knock } = createMockKnock();
+
+    // Your test logic here
+    expect(knock).toBeDefined();
+  });
+});
+```
+
+**Important:** Always add `` at the top of test files.
+
+## 🛠 Test Utilities
+
+### 1. Fixtures (`test-utils/fixtures.ts`)
+
+Fixtures create realistic test data. Use them instead of manually creating objects.
+
+**Feed Items:**
+
+```typescript
+import {
+  createArchivedFeedItem,
+  createMockFeedItem,
+  createReadFeedItem,
+  createUnreadFeedItem,
+} from "./test-utils/fixtures";
+
+// Create a basic feed item
+const item = createMockFeedItem();
+
+// Create specific states
+const unreadItem = createUnreadFeedItem();
+const readItem = createReadFeedItem({
+  read_at: "2024-01-01T00:00:00Z",
+});
+
+// Create multiple items
+const items = createMockFeedItems(5);
+```
+
+**Messages:**
+
+```typescript
+import {
+  createMockMessage,
+  createReadMessage,
+  createUnreadMessage,
+} from "./test-utils/fixtures";
+
+const message = createMockMessage({
+  id: "custom-id",
+});
+```
+
+**Users:**
+
+```typescript
+import { createMockUser, createMockUsers } from "./test-utils/fixtures";
+
+const user = createMockUser({ name: "John Doe" });
+const users = createMockUsers(10);
+```
+
+**Complex Scenarios:**
+
+```typescript
+import {
+  createBulkOperationScenario,
+  createErrorRecoveryScenario,
+  createUserJourneyScenario,
+} from "./test-utils/fixtures";
+
+// Pre-built realistic test scenarios
+const scenario = createUserJourneyScenario();
+```
+
+### 2. Mocks (`test-utils/mocks.ts`)
+
+Mocks handle external dependencies and API calls.
+
+**Basic Setup:**
+
+```typescript
+import { authenticateKnock, createMockKnock } from "./test-utils/mocks";
+
+test("my test", () => {
+  const { knock, mockApiClient } = createMockKnock();
+
+  // Authenticate if needed
+  authenticateKnock(knock);
+
+  // Your test logic
+});
+```
+
+**API Mocking:**
+
+```typescript
+import {
+  mockNetworkError,
+  mockNetworkFailure,
+  mockNetworkSuccess,
+} from "./test-utils/mocks";
+
+test("handles successful API call", async () => {
+  const { knock, mockApiClient } = createMockKnock();
+
+  // Mock successful response
+  mockNetworkSuccess(mockApiClient, { data: "success" });
+
+  // Test your code
+});
+
+test("handles API error", async () => {
+  const { knock, mockApiClient } = createMockKnock();
+
+  // Mock error response
+  mockNetworkError(mockApiClient, 400, "Bad Request");
+
+  // Test error handling
+});
+
+test("handles network failure", async () => {
+  const { knock, mockApiClient } = createMockKnock();
+
+  // Mock network failure
+  mockNetworkFailure(mockApiClient, new Error("Network down"));
+
+  // Test failure handling
+});
+```
+
+**Feed Mocking:**
+
+```typescript
+import { createMockFeed } from "./test-utils/mocks";
+
+test("feed operations", () => {
+  const { feed, mockApiClient, mockSocketManager } = createMockFeed(
+    "test-feed-id",
+    { page_size: 25 },
+  );
+
+  // Test feed operations
+});
+```
+
+### 3. Property Testing (`test-utils/property-testing.ts`)
+
+Property testing helps find edge cases by testing with generated data.
+
+```typescript
+import {
+  feedItemArbitrary,
+  generators,
+  property,
+} from "./test-utils/property-testing";
+
+test("property: all feed items should have valid IDs", async () => {
+  const result = await property.forAll(
+    feedItemArbitrary(),
+    (item) => item.id.length > 0,
+  );
+
+  expect(result.success).toBe(true);
+});
+
+test("property: numbers are always positive", async () => {
+  const result = await property.forAll(
+    generators.number(1, 1000),
+    (num) => num > 0,
+  );
+
+  expect(result.success).toBe(true);
+});
+```
+
+## 📝 Testing Patterns
+
+### 1. Test Organization
+
+**Use descriptive describe blocks:**
+
+```typescript
+describe("Feed Client", () => {
+  describe("Initialization", () => {
+    test("creates feed with valid options", () => {
+      // Test initialization
+    });
+  });
+
+  describe("Data Operations", () => {
+    test("fetches feed items successfully", () => {
+      // Test data fetching
+    });
+  });
+
+  describe("Error Handling", () => {
+    test("handles network errors gracefully", () => {
+      // Test error scenarios
+    });
+  });
+});
+```
+
+### 2. Setup and Cleanup
+
+**Use consistent setup:**
+
+```typescript
+import { afterEach, beforeEach, describe, test, vi } from "vitest";
+
+describe("My Feature", () => {
+  const getTestSetup = () => {
+    const { knock, mockApiClient } = createMockKnock();
+    authenticateKnock(knock);
+
+    return {
+      knock,
+      mockApiClient,
+      cleanup: () => vi.clearAllMocks(),
+    };
+  };
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  test("my test", () => {
+    const { knock, mockApiClient, cleanup } = getTestSetup();
+
+    try {
+      // Your test logic
+    } finally {
+      cleanup();
+    }
+  });
+});
+```
+
+### 3. Async Testing
+
+**Handle promises correctly:**
+
+```typescript
+test("async operation succeeds", async () => {
+  const { knock, mockApiClient } = createMockKnock();
+
+  mockNetworkSuccess(mockApiClient, { success: true });
+
+  const result = await knock.someAsyncOperation();
+
+  expect(result).toEqual({ success: true });
+});
+
+test("async operation fails", async () => {
+  const { knock, mockApiClient } = createMockKnock();
+
+  mockNetworkFailure(mockApiClient, new Error("Failed"));
+
+  await expect(knock.someAsyncOperation()).rejects.toThrow("Failed");
+});
+```
+
+### 4. State Testing
+
+**Test different states:**
+
+```typescript
+test("handles unread items", () => {
+  const items = [
+    createUnreadFeedItem(),
+    createReadFeedItem(),
+    createUnreadFeedItem(),
+  ];
+
+  const unreadCount = items.filter((item) => !item.read_at).length;
+  expect(unreadCount).toBe(2);
+});
+```
+
+## 🎯 Testing Specific Clients
+
+### Feed Client Tests
+
+```typescript
+import { createMockFeedItems } from "./test-utils/fixtures";
+import { createMockFeed } from "./test-utils/mocks";
+
+test("feed fetches items", async () => {
+  const { feed, mockApiClient } = createMockFeed();
+  const items = createMockFeedItems(5);
+
+  mockNetworkSuccess(mockApiClient, {
+    entries: items,
+    page_info: { page_size: 50 },
+  });
+
+  await feed.fetch();
+
+  expect(feed.store.items).toHaveLength(5);
+});
+```
+
+### Messages Client Tests
+
+```typescript
+import { createMockMessage } from "./test-utils/fixtures";
+
+test("messages client gets message", async () => {
+  const { knock, mockApiClient } = createMockKnock();
+  const message = createMockMessage();
+
+  mockNetworkSuccess(mockApiClient, message);
+
+  const result = await knock.messages.get(message.id);
+
+  expect(result).toEqual(message);
+});
+```
+
+### User Client Tests
+
+```typescript
+test("user client identifies user", async () => {
+  const { knock, mockApiClient } = createMockKnock();
+
+  mockNetworkSuccess(mockApiClient, { success: true });
+
+  await knock.user.identify("user_123", { name: "John" });
+
+  expect(mockApiClient.makeRequest).toHaveBeenCalledWith({
+    method: "PUT",
+    url: "/v1/users/user_123",
+    data: { name: "John" },
+  });
+});
+```
+
+## 🧪 Advanced Testing
+
+### Error Scenarios
+
+```typescript
+test("handles rate limiting", async () => {
+  const { knock, mockApiClient } = createMockKnock();
+
+  mockNetworkError(mockApiClient, 429, "Rate limited");
+
+  await expect(knock.someOperation()).rejects.toThrow();
+});
+
+test("retries on network failure", async () => {
+  const { knock, mockApiClient } = createMockKnock();
+
+  // First call fails, second succeeds
+  mockApiClient.makeRequest
+    .mockRejectedValueOnce(new Error("Network error"))
+    .mockResolvedValueOnce({ statusCode: "ok", body: { success: true } });
+
+  const result = await knock.someRetryableOperation();
+
+  expect(result).toEqual({ success: true });
+  expect(mockApiClient.makeRequest).toHaveBeenCalledTimes(2);
+});
+```
+
+### Performance Testing
+
+```typescript
+import { createLargeFeedDataset } from "./test-utils/fixtures";
+
+test("handles large datasets efficiently", () => {
+  const { items, metadata } = createLargeFeedDataset(10000);
+
+  const startTime = performance.now();
+
+  // Test operation
+  const result = processLargeDataset(items);
+
+  const endTime = performance.now();
+
+  expect(result).toBeDefined();
+  expect(endTime - startTime).toBeLessThan(1000); // Should complete in < 1s
+});
+```
+
+## 🔧 Configuration
+
+### Global Setup (`setup.ts`)
+
+The setup file handles:
+
+- Environment polyfills
+- Console output suppression during tests
+- Global error handling
+- Browser API mocks (localStorage, sessionStorage)
+
+You usually don't need to modify this file.
+
+### Environment
+
+All tests should run in Node environment:
+
+```typescript
+
+```
+
+## 🚨 Common Issues & Solutions
+
+### 1. Unhandled Promise Rejections
+
+**Problem:** Tests fail with unhandled promise rejections.
+
+**Solution:** Always handle promises properly:
+
+```typescript
+// ❌ Bad
+test("test", () => {
+  someAsyncFunction(); // Promise not handled
+});
+
+// ✅ Good
+test("test", async () => {
+  await someAsyncFunction();
+});
+
+// ✅ Also good
+test("test", () => {
+  return someAsyncFunction();
+});
+```
+
+### 2. Mock Cleanup
+
+**Problem:** Mocks from one test affect another.
+
+**Solution:** Always clean up:
+
+```typescript
+afterEach(() => {
+  vi.clearAllMocks();
+  vi.restoreAllMocks();
+});
+```
+
+### 3. Authentication Required
+
+**Problem:** Tests fail because client isn't authenticated.
+
+**Solution:** Use `authenticateKnock`:
+
+```typescript
+test("authenticated operation", () => {
+  const { knock } = createMockKnock();
+  authenticateKnock(knock); // Add this line
+
+  // Now test authenticated operations
+});
+```
+
+### 4. Network Mocking
+
+**Problem:** Real network calls in tests.
+
+**Solution:** Always mock network calls:
+
+```typescript
+test("API operation", async () => {
+  const { knock, mockApiClient } = createMockKnock();
+
+  // Mock the expected response
+  mockNetworkSuccess(mockApiClient, expectedData);
+
+  const result = await knock.apiOperation();
+
+  expect(result).toEqual(expectedData);
+});
+```
+
+## 📚 Examples
+
+### Complete Test File Example
+
+```typescript
+import { afterEach, describe, expect, test, vi } from "vitest";
+
+import { createMockFeedItem } from "./test-utils/fixtures";
+import {
+  authenticateKnock,
+  createMockKnock,
+  mockNetworkSuccess,
+} from "./test-utils/mocks";
+
+describe("My Feature", () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("Basic Operations", () => {
+    test("performs basic operation", () => {
+      const { knock } = createMockKnock();
+
+      expect(knock).toBeDefined();
+    });
+  });
+
+  describe("Authenticated Operations", () => {
+    test("performs authenticated operation", async () => {
+      const { knock, mockApiClient } = createMockKnock();
+      authenticateKnock(knock);
+
+      const expectedData = { success: true };
+      mockNetworkSuccess(mockApiClient, expectedData);
+
+      const result = await knock.authenticatedOperation();
+
+      expect(result).toEqual(expectedData);
+    });
+  });
+
+  describe("Data Operations", () => {
+    test("processes feed item", () => {
+      const item = createMockFeedItem({
+        read_at: null, // Unread item
+      });
+
+      const result = processItem(item);
+
+      expect(result.isUnread).toBe(true);
+    });
+  });
+
+  describe("Error Handling", () => {
+    test("handles errors gracefully", async () => {
+      const { knock, mockApiClient } = createMockKnock();
+
+      mockApiClient.makeRequest.mockRejectedValue(new Error("API Error"));
+
+      await expect(knock.faultyOperation()).rejects.toThrow("API Error");
+    });
+  });
+});
+```
+
+## 🎉 You're Ready!
+
+With this guide and the provided utilities, you should be able to write comprehensive tests for any part of the Knock client. Remember:
+
+1. **Use the test utilities** - they handle the complex setup for you
+2. **Follow the patterns** - consistent structure makes tests easier to understand
+3. **Test both success and failure cases** - robust testing catches more bugs
+4. **Clean up after yourself** - prevent test pollution
+
+Happy testing! 🧪