@shiftengineering/folio 0.1.12 → 0.1.13

package/README.md

@@ -245,17 +245,23 @@ function FolioProjectManager() {
 
 ## Google Analytics 4 Integration
 
-Folio now supports Google Analytics 4 tracking. This feature enables tracking key user interactions and provides visibility into how users engage with the application.
+Folio supports analytics event tracking that can be used with Google Analytics 4 or any other analytics provider. This feature enables tracking key user interactions and provides visibility into how users engage with the application.
 
 ### Configuration
 
-To enable Google Analytics 4 tracking, add the measurement ID to your environment variables:
+#### For Google Analytics 4
+
+To enable built-in Google Analytics 4 tracking, add the measurement ID to your environment variables provided to the docker container:
 
 ```
 VITE_GA4_MEASUREMENT_ID=G-XXXXXXXXXX
 ```
 
-When this environment variable is present, Folio will automatically initialize GA4 and start tracking events. If the variable is not present, tracking will be disabled but the event stream will still be available to host applications.
+When this environment variable is present, Folio will automatically initialize GA4 and send events to Google Analytics.
+
+#### For Any Analytics Provider
+
+**Important:** Even if you don't configure GA4, you can still capture all analytics events by providing the `onAnalyticsEvent` callback to the `FolioProvider`. This gives you complete flexibility to use any analytics provider of your choice.
 
 ### Events Tracked
 
@@ -269,6 +275,29 @@ The following events are tracked automatically:
 6. `switch_project` - When a user switches between projects
 7. `file_view` - When a user views a file
 
+### Analytics Event Structure
+
+All analytics events follow this structure:
+
+```typescript
+export type AnalyticsEvent =
+  | { name: "page_view"; data: { pathname: string; projectId?: string } }
+  | { name: "chat_sent"; data: { query: string } }
+  | { name: "highlight"; data: { filePath: string; selectionLength: number } }
+  | { name: "add_to_chat"; data: { filePath: string; snippetSize: number } }
+  | { name: "extract"; data: { filePath: string; extractor: string } }
+  | {
+      name: "switch_project";
+      data: { fromProjectId: string; toProjectId: string };
+    }
+  | { name: "file_view"; data: { filePath: string } };
+```
+
+Each event has:
+
+- A `name` property identifying the event type
+- A `data` object with event-specific parameters
+
 ### Host Integration
 
 If you're embedding Folio in your application, you can access the analytics event stream by providing the `onAnalyticsEvent` callback to the `FolioProvider`:
@@ -290,6 +319,13 @@ function YourApp() {
     if (window.mixpanel) {
       window.mixpanel.track(event.name, event.data);
     }
+
+    // Example: Send to custom analytics endpoint
+    fetch('https://your-analytics-api.com/track', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(event)
+    });
   };
 
   return (
@@ -317,7 +353,7 @@ window.addEventListener("folio-analytics", (event) => {
 });
 ```
 
-Both approaches allow host applications to consume the same events being sent to GA4, enabling integration with other analytics services or custom tracking solutions.
+Both approaches allow host applications to consume the same events regardless of whether GA4 is configured, enabling integration with any analytics service or custom tracking solution.
 
 ## API Reference
 
@@ -414,14 +450,14 @@ Hook for adding one or more directories with files to a project. Directory names
 
 The library exports these TypeScript types:
 
-| Type                 | Description                                                                                                                                                               |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `FolioFile`          | Represents a file in Folio. Contains properties: `id`, `name`, `blobUrl`, `parentId` (null for root items), and `isDirectory` (boolean)                                   |
-| `FolioProject`       | Represents a project in Folio                                                                                                                                             |
-| `MetadataValue`      | Represents metadata values that can be nested. Can be a string, number, boolean, null, object, or array of these types                                                    |
-| `DirectoryEntry`     | Represents a directory with metadata and files to be added to Folio. Contains properties: `directoryName`, `directoryMetadata` (now supports nested objects), and `files` |
-| `AnalyticsEvent`     | Represents an analytics event from Folio. Contains properties: `name` (event name) and `data` (event-specific data)                                                       |
-| `FolioEmbedProps`    | Props for the FolioEmbed component                                                                                                                                        |
-| `FolioProviderProps` | Props for the FolioProvider component                                                                                                                                     |
+| Type                 | Description                                                                                                                                                                                                                                                                     |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `FolioFile`          | Represents a file in Folio. Contains properties: `id`, `name`, `blobUrl`, `parentId` (null for root items), and `isDirectory` (boolean)                                                                                                                                         |
+| `FolioProject`       | Represents a project in Folio                                                                                                                                                                                                                                                   |
+| `MetadataValue`      | Represents metadata values that can be nested. Can be a string, number, boolean, null, object, or array of these types                                                                                                                                                          |
+| `DirectoryEntry`     | Represents a directory with metadata and files to be added to Folio. Contains properties: `directoryName`, `directoryMetadata` (now supports nested objects), and `files`                                                                                                       |
+| `AnalyticsEvent`     | A union type for analytics events sent by Folio. Each event has a `name` property (like "page_view" or "file_view") and a `data` object with event-specific parameters. See the [Analytics Event Structure](#analytics-event-structure) section for details on all event types. |
+| `FolioEmbedProps`    | Props for the FolioEmbed component                                                                                                                                                                                                                                              |
+| `FolioProviderProps` | Props for the FolioProvider component                                                                                                                                                                                                                                           |
 
 ## License

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shiftengineering/folio",
   "private": false,
-  "version": "0.1.12",
+  "version": "0.1.13",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShiftEngineering/folio.git"