@flowcore/pathways 0.16.0 → 0.16.1

package/CHANGELOG.md

@@ -1,81 +1,94 @@
 # Changelog
 
-## [0.16.0](https://github.com/flowcore-io/flowcore-pathways/compare/v0.15.3...v0.16.0) (2025-06-03)
+## [0.16.1](https://github.com/flowcore-io/flowcore-pathways/compare/v0.16.0...v0.16.1) (2025-06-04)
 
 
-### Features
+### Bug Fixes
+
+* **session-pathway:** :art: update write method to accept structured input ([86e54a7](https://github.com/flowcore-io/flowcore-pathways/commit/86e54a79cb8bef32677f308eb51a50eef6d1f071))
 
-* **postgres:** :sparkles: add connection pool configuration options for PostgreSQL ([9ba9966](https://github.com/flowcore-io/flowcore-pathways/commit/9ba9966706c13bba441ef8538a0ecfe405191307))
+## [0.16.0](https://github.com/flowcore-io/flowcore-pathways/compare/v0.15.3...v0.16.0) (2025-06-03)
+
+### Features
 
+- **postgres:** :sparkles: add connection pool configuration options for PostgreSQL
+  ([9ba9966](https://github.com/flowcore-io/flowcore-pathways/commit/9ba9966706c13bba441ef8538a0ecfe405191307))
 
 ### Bug Fixes
 
-* **postgres:** :art: clean up whitespace in postgres-adapter.ts ([d16e0a9](https://github.com/flowcore-io/flowcore-pathways/commit/d16e0a9dfc0b02e533143dfcc5fe34e57bf22cea))
-* **postgres:** :art: update PostgresJsOptions interface for better type safety ([0fee92e](https://github.com/flowcore-io/flowcore-pathways/commit/0fee92eaad3ceb9a387cb6cee9d3029a254b8c15))
+- **postgres:** :art: clean up whitespace in postgres-adapter.ts
+  ([d16e0a9](https://github.com/flowcore-io/flowcore-pathways/commit/d16e0a9dfc0b02e533143dfcc5fe34e57bf22cea))
+- **postgres:** :art: update PostgresJsOptions interface for better type safety
+  ([0fee92e](https://github.com/flowcore-io/flowcore-pathways/commit/0fee92eaad3ceb9a387cb6cee9d3029a254b8c15))
 
 ## [0.15.3](https://github.com/flowcore-io/flowcore-pathways/compare/v0.15.2...v0.15.3) (2025-06-03)
 
-
 ### Bug Fixes
 
-* add debug ([c5b0776](https://github.com/flowcore-io/flowcore-pathways/commit/c5b0776af5edfb64a568e497e31ed5181c59bb2d))
+- add debug
+  ([c5b0776](https://github.com/flowcore-io/flowcore-pathways/commit/c5b0776af5edfb64a568e497e31ed5181c59bb2d))
 
 ## [0.15.2](https://github.com/flowcore-io/flowcore-pathways/compare/v0.15.1...v0.15.2) (2025-06-03)
 
-
 ### Bug Fixes
 
-* update transformer core ([1b621ef](https://github.com/flowcore-io/flowcore-pathways/commit/1b621ef076016d6ef0cf378a883a113df6c022c0))
+- update transformer core
+  ([1b621ef](https://github.com/flowcore-io/flowcore-pathways/commit/1b621ef076016d6ef0cf378a883a113df6c022c0))
 
 ## [0.15.1](https://github.com/flowcore-io/flowcore-pathways/compare/v0.15.0...v0.15.1) (2025-05-28)
 
-
 ### Bug Fixes
 
-* export file types ([203cc73](https://github.com/flowcore-io/flowcore-pathways/commit/203cc735aaedcf9bf44f045fd8a15916917b7ac1))
+- export file types
+  ([203cc73](https://github.com/flowcore-io/flowcore-pathways/commit/203cc735aaedcf9bf44f045fd8a15916917b7ac1))
 
 ## [0.15.0](https://github.com/flowcore-io/flowcore-pathways/compare/v0.14.0...v0.15.0) (2025-05-27)
 
-
 ### Features
 
-* file writer + changes to write and writeBatch args ([5cbbb8f](https://github.com/flowcore-io/flowcore-pathways/commit/5cbbb8f83c5b8cdba11436565c4d36c1ad3faa61))
-* unified write method ([19f00bd](https://github.com/flowcore-io/flowcore-pathways/commit/19f00bd550d5b167e0104d9c8ef5a2751a909041))
-
+- file writer + changes to write and writeBatch args
+  ([5cbbb8f](https://github.com/flowcore-io/flowcore-pathways/commit/5cbbb8f83c5b8cdba11436565c4d36c1ad3faa61))
+- unified write method
+  ([19f00bd](https://github.com/flowcore-io/flowcore-pathways/commit/19f00bd550d5b167e0104d9c8ef5a2751a909041))
 
 ### Bug Fixes
 
-* fix session pathway ([5b8b1a0](https://github.com/flowcore-io/flowcore-pathways/commit/5b8b1a0b846f97adb679ce79ddd61bdc8868caf9))
-* fix types ([2235058](https://github.com/flowcore-io/flowcore-pathways/commit/22350588845db0a1e320d80928653210048b9a29))
-* update readme ([2285c96](https://github.com/flowcore-io/flowcore-pathways/commit/2285c960d9f3d95c09092c91ab8b93b4fc98a94f))
-* update tests and readme ([c3af713](https://github.com/flowcore-io/flowcore-pathways/commit/c3af7133196bb5da5cf7f342c2922bb7ad778fe9))
+- fix session pathway
+  ([5b8b1a0](https://github.com/flowcore-io/flowcore-pathways/commit/5b8b1a0b846f97adb679ce79ddd61bdc8868caf9))
+- fix types
+  ([2235058](https://github.com/flowcore-io/flowcore-pathways/commit/22350588845db0a1e320d80928653210048b9a29))
+- update readme
+  ([2285c96](https://github.com/flowcore-io/flowcore-pathways/commit/2285c960d9f3d95c09092c91ab8b93b4fc98a94f))
+- update tests and readme
+  ([c3af713](https://github.com/flowcore-io/flowcore-pathways/commit/c3af7133196bb5da5cf7f342c2922bb7ad778fe9))
 
 ## [0.14.0](https://github.com/flowcore-io/flowcore-pathways/compare/v0.13.2...v0.14.0) (2025-05-23)
 
-
 ### Features
 
-* switch from typebox to zod ([e20e8f8](https://github.com/flowcore-io/flowcore-pathways/commit/e20e8f81a9cf68eaa598be5d43ef34f346f136ea))
-
+- switch from typebox to zod
+  ([e20e8f8](https://github.com/flowcore-io/flowcore-pathways/commit/e20e8f81a9cf68eaa598be5d43ef34f346f136ea))
 
 ### Bug Fixes
 
-* fix tests ([05496b9](https://github.com/flowcore-io/flowcore-pathways/commit/05496b993669449d8bfe758e2647d4f2a2dbbf06))
-* set defaults on write and process ([c01ac59](https://github.com/flowcore-io/flowcore-pathways/commit/c01ac59cd4097d832c009e90e7259644e84a9612))
+- fix tests
+  ([05496b9](https://github.com/flowcore-io/flowcore-pathways/commit/05496b993669449d8bfe758e2647d4f2a2dbbf06))
+- set defaults on write and process
+  ([c01ac59](https://github.com/flowcore-io/flowcore-pathways/commit/c01ac59cd4097d832c009e90e7259644e84a9612))
 
 ## [0.13.2](https://github.com/flowcore-io/flowcore-pathways/compare/v0.13.1...v0.13.2) (2025-05-14)
 
-
 ### Performance Improvements
 
-* ability to adjust the log level of internal logs ([eaeb9c5](https://github.com/flowcore-io/flowcore-pathways/commit/eaeb9c58a53be3effb6ba54621535a531b11e82e))
+- ability to adjust the log level of internal logs
+  ([eaeb9c5](https://github.com/flowcore-io/flowcore-pathways/commit/eaeb9c58a53be3effb6ba54621535a531b11e82e))
 
 ## [0.13.1](https://github.com/flowcore-io/flowcore-pathways/compare/v0.13.0...v0.13.1) (2025-04-22)
 
-
 ### Bug Fixes
 
-* **pathways:** :art: extract audit constants for better readability ([9a349b8](https://github.com/flowcore-io/flowcore-pathways/commit/9a349b865e8bc5627a50a4b132d368fcba4bf986))
+- **pathways:** :art: extract audit constants for better readability
+  ([9a349b8](https://github.com/flowcore-io/flowcore-pathways/commit/9a349b865e8bc5627a50a4b132d368fcba4bf986))
 
 ## [0.13.0](https://github.com/flowcore-io/flowcore-pathways/compare/v0.12.0...v0.13.0) (2025-04-22)
 

package/README.md

@@ -23,6 +23,7 @@ Pathways helps you build event-driven applications with type-safe pathways for p
   - [Custom Loggers](#custom-loggers)
   - [Retry Mechanisms](#retry-mechanisms)
   - [Session Pathways](#session-pathways)
+- [File Pathways](#file-pathways)
 - [API Reference](#api-reference)
 
 ## Installation
@@ -210,6 +211,21 @@ const eventId3 = await pathways.write("order/placed", {
     fireAndForget: true,
   },
 })
+
+// Batch write multiple events
+const eventIds = await pathways.write("order/placed", {
+  batch: true,
+  data: [orderData1, orderData2, orderData3],
+})
+
+// Batch write with metadata
+const eventIds2 = await pathways.write("order/placed", {
+  batch: true,
+  data: [orderData1, orderData2],
+  metadata: {
+    source: "bulk-import",
+  },
+})
 ```
 
 ### Error Handling
@@ -354,18 +370,18 @@ Enable auditing to track events:
 
 ```typescript
 // Set up auditing
-pathways.withAudit(
-  // Audit handler
-  (path, event) => {
+pathways
+  .withAudit((path, event) => {
     console.log(`Audit: ${path} event ${event.eventId}`)
     logToAuditSystem(path, event)
-  },
-  // User ID resolver
-  async () => {
+  })
+  .withUserResolver(async () => {
     // Get the current user ID from context
-    return getCurrentUserId()
-  },
-)
+    return {
+      entityId: "user-123",
+      entityType: "user",
+    }
+  })
 ```
 
 ### Custom Loggers
@@ -502,6 +518,12 @@ await session.write("order/placed", {
   data: orderData,
   options: { sessionId: "different-session" },
 })
+
+// Batch write events with session context
+await session.write("user/actions", {
+  batch: true,
+  data: [actionData1, actionData2, actionData3],
+})
 ```
 
 #### Session ID in Audit Events
@@ -520,6 +542,228 @@ await session.write("order/placed", { data: orderData })
 // The session ID is automatically included in the audit metadata
 ```
 
+### File Pathways
+
+File pathways provide a specialized way to handle file uploads and processing in your Flowcore applications. They
+automatically handle file type detection, binary content processing, and provide a structured approach to file
+management.
+
+#### Registering File Pathways
+
+Register a file pathway by setting the `isFilePathway` flag to `true`:
+
+```typescript
+import { z } from "zod"
+
+// Define additional properties schema for your file
+const documentSchema = z.object({
+  documentType: z.enum(["invoice", "receipt", "contract"]),
+  department: z.string(),
+  metadata: z.record(z.string()).optional(),
+})
+
+// Register a file pathway
+pathways.register({
+  flowType: "document",
+  eventType: "uploaded",
+  schema: documentSchema, // Additional properties beyond the file itself
+  isFilePathway: true, // This marks it as a file pathway
+  writable: true,
+})
+```
+
+#### Writing Files to Pathways
+
+File pathways use a special input format that includes file content and metadata:
+
+```typescript
+import { readFile } from "node:fs/promises"
+
+// Read file content (as Buffer for Node.js/Bun, Uint8Array for Deno)
+const fileContent = await readFile("./invoice.pdf")
+
+// Write a file to a pathway
+const eventId = await pathways.write("document/uploaded", {
+  data: {
+    fileId: "file-123", // Unique identifier for the file
+    fileName: "invoice-2024.pdf", // Original filename
+    fileContent: fileContent, // File content as Buffer/Uint8Array
+    // Additional properties defined in your schema
+    documentType: "invoice",
+    department: "finance",
+    metadata: {
+      customer: "ACME Corp",
+      amount: "1500.00",
+    },
+  },
+})
+```
+
+#### File Input Schema
+
+File pathways automatically include these required fields:
+
+```typescript
+// Built-in file fields (automatically added)
+interface FileInput {
+  fileId: string // Unique identifier for the file
+  fileName: string // Original filename with extension
+  fileContent: Buffer | Uint8Array // Binary file content
+  // ... your additional schema properties
+}
+```
+
+#### File Event Schema
+
+When processed, file events include automatic file type detection:
+
+```typescript
+// Built-in file event fields (automatically added to your schema)
+interface FileEvent {
+  fileId: string // Unique identifier for the file
+  fileName: string // Original filename
+  fileType: string // MIME type (automatically detected)
+  fileContent: Blob // File content as Blob
+  // ... your additional schema properties
+}
+```
+
+#### Handling File Events
+
+Handle file events just like regular events, but with access to file-specific properties:
+
+```typescript
+pathways.handle("document/uploaded", async (event) => {
+  const { fileId, fileName, fileType, fileContent, documentType, department } = event.payload
+
+  console.log(`Processing file: ${fileName} (${fileType})`)
+  console.log(`Document type: ${documentType}, Department: ${department}`)
+
+  // Process the file content
+  if (fileType === "application/pdf") {
+    await processPDFDocument(fileContent, event.payload.metadata)
+  } else if (fileType.startsWith("image/")) {
+    await processImageFile(fileContent, documentType)
+  }
+
+  // Store file metadata
+  await storeFileMetadata({
+    fileId,
+    fileName,
+    fileType,
+    documentType,
+    department,
+    processedAt: new Date(),
+  })
+})
+```
+
+#### File Pathway Limitations
+
+File pathways have some specific limitations:
+
+```typescript
+// ❌ Batch writes are NOT supported for file pathways
+// This will throw an error:
+await pathways.write("document/uploaded", {
+  batch: true, // Error: Batch is not possible for file pathways
+  data: [fileData1, fileData2],
+})
+
+// ✅ Write files individually instead:
+for (const fileData of fileDataArray) {
+  await pathways.write("document/uploaded", { data: fileData })
+}
+```
+
+#### Complete File Pathway Example
+
+Here's a complete example of setting up and using file pathways:
+
+```typescript
+import { PathwaysBuilder } from "@flowcore/pathways"
+import { z } from "zod"
+import { readFile } from "node:fs/promises"
+
+// Define schema for additional file properties
+const documentSchema = z.object({
+  documentType: z.enum(["invoice", "receipt", "contract", "report"]),
+  department: z.string(),
+  tags: z.array(z.string()).optional(),
+  metadata: z.record(z.string()).optional(),
+})
+
+const pathways = new PathwaysBuilder({
+  baseUrl: "https://api.flowcore.io",
+  tenant: "your-tenant",
+  dataCore: "your-data-core",
+  apiKey: "your-api-key",
+})
+
+// Register file pathway
+pathways
+  .register({
+    flowType: "document",
+    eventType: "uploaded",
+    schema: documentSchema,
+    isFilePathway: true,
+  })
+  .handle("document/uploaded", async (event) => {
+    const { fileId, fileName, fileType, documentType, department } = event.payload
+
+    console.log(`Processing ${documentType} from ${department}: ${fileName}`)
+
+    // File type-specific processing
+    switch (fileType) {
+      case "application/pdf":
+        await extractPDFText(event.payload.fileContent)
+        break
+      case "image/jpeg":
+      case "image/png":
+        await extractImageMetadata(event.payload.fileContent)
+        break
+      default:
+        console.log(`Unsupported file type: ${fileType}`)
+    }
+
+    // Trigger downstream processing
+    await pathways.write("document/processed", {
+      data: {
+        fileId,
+        fileName,
+        documentType,
+        department,
+        processedAt: new Date().toISOString(),
+        status: "completed",
+      },
+    })
+  })
+
+// Upload a file
+async function uploadDocument(filePath: string, documentType: string, department: string) {
+  const fileContent = await readFile(filePath)
+  const fileName = filePath.split("/").pop() || "unknown"
+
+  return await pathways.write("document/uploaded", {
+    data: {
+      fileId: `doc-${Date.now()}`,
+      fileName,
+      fileContent,
+      documentType,
+      department,
+      tags: ["automated-upload"],
+      metadata: {
+        uploadedAt: new Date().toISOString(),
+        source: "api",
+      },
+    },
+  })
+}
+
+// Usage
+await uploadDocument("./invoice.pdf", "invoice", "finance")
+```
+
 ## API Reference
 
 For a complete API reference, please see the [API documentation](https://jsr.io/@flowcore/pathways).

package/esm/pathways/session-pathway.d.ts

@@ -33,8 +33,14 @@ import type { EventMetadata, PathwayWriteOptions } from "./types.js";
  * session.withUserResolver(async () => getCurrentUserId());
  *
  * // Write events with session context
- * await session.write("order/placed", orderData);
- * await session.write("user/action", actionData);
+ * await session.write("order/placed", { data: orderData });
+ * await session.write("user/action", { data: actionData });
+ *
+ * // Write batch events with session context
+ * await session.write("user/actions", {
+ *   batch: true,
+ *   data: [actionData1, actionData2]
+ * });
  *
  * // All events will be associated with the same session ID
  * ```
@@ -84,7 +90,7 @@ export declare class SessionPathwayBuilder<TPathway extends Record<string, {
      * });
      *
      * // When writing events, the user ID will be automatically included
-     * await session.write("user/action", actionData);
+     * await session.write("user/action", { data: actionData });
      * ```
      */
     withUserResolver(resolver: UserIdResolver): this;
@@ -92,11 +98,14 @@ export declare class SessionPathwayBuilder<TPathway extends Record<string, {
      * Writes data to a pathway, proxying to the underlying PathwaysBuilder
      *
      * @param path The pathway to write to
-     * @param data The data to write
-     * @param metadata Optional metadata to include with the event
-     * @param options Optional write options
+     * @param input Object containing the data, metadata, options, and optional batch flag
      * @returns A promise that resolves to the event ID(s)
      */
-    write<TPath extends TWritablePaths>(path: TPath, data: TPathway[TPath]["input"], metadata?: EventMetadata, options?: PathwayWriteOptions): Promise<string | string[]>;
+    write<TPath extends TWritablePaths, B extends boolean = false>(path: TPath, input: {
+        batch?: B;
+        data: B extends true ? TPathway[TPath]["input"][] : TPathway[TPath]["input"];
+        metadata?: EventMetadata;
+        options?: PathwayWriteOptions;
+    }): Promise<string | string[]>;
 }
 //# sourceMappingURL=session-pathway.d.ts.map

package/esm/pathways/session-pathway.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-pathway.d.ts","sourceRoot":"","sources":["../../src/pathways/session-pathway.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAqBpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBAAa,qBAAqB,CAEhC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC,GAAG,EAAE,EACzE,cAAc,SAAS,MAAM,QAAQ,GAAG,KAAK;IAE7C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA2C;IAC3E,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAElC;;;;;OAKG;gBAED,eAAe,EAAE,eAAe,CAAC,QAAQ,EAAE,cAAc,CAAC,EAC1D,SAAS,CAAC,EAAE,MAAM;IAMpB;;;;OAIG;IACH,YAAY,IAAI,MAAM;IAItB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,gBAAgB,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI;IAKhD;;;;;;;;OAQG;IACG,KAAK,CAAC,KAAK,SAAS,cAAc,EACtC,IAAI,EAAE,KAAK,EACX,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,EAC9B,QAAQ,CAAC,EAAE,aAAa,EACxB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC;CAU9B"}
+{"version":3,"file":"session-pathway.d.ts","sourceRoot":"","sources":["../../src/pathways/session-pathway.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAqBpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,qBAAa,qBAAqB,CAEhC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC,GAAG,EAAE,EACzE,cAAc,SAAS,MAAM,QAAQ,GAAG,KAAK;IAE7C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA2C;IAC3E,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAElC;;;;;OAKG;gBAED,eAAe,EAAE,eAAe,CAAC,QAAQ,EAAE,cAAc,CAAC,EAC1D,SAAS,CAAC,EAAE,MAAM;IAMpB;;;;OAIG;IACH,YAAY,IAAI,MAAM;IAItB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,gBAAgB,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI;IAKhD;;;;;;OAMG;IACG,KAAK,CAAC,KAAK,SAAS,cAAc,EAAE,CAAC,SAAS,OAAO,GAAG,KAAK,EACjE,IAAI,EAAE,KAAK,EACX,KAAK,EAAE;QACL,KAAK,CAAC,EAAE,CAAC,CAAA;QACT,IAAI,EAAE,CAAC,SAAS,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,EAAE,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,CAAA;QAC5E,QAAQ,CAAC,EAAE,aAAa,CAAA;QACxB,OAAO,CAAC,EAAE,mBAAmB,CAAA;KAC9B,GACA,OAAO,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC;CAiB9B"}

package/esm/pathways/session-pathway.js

@@ -48,8 +48,14 @@ function generateUUID() {
  * session.withUserResolver(async () => getCurrentUserId());
  *
  * // Write events with session context
- * await session.write("order/placed", orderData);
- * await session.write("user/action", actionData);
+ * await session.write("order/placed", { data: orderData });
+ * await session.write("user/action", { data: actionData });
+ *
+ * // Write batch events with session context
+ * await session.write("user/actions", {
+ *   batch: true,
+ *   data: [actionData1, actionData2]
+ * });
  *
  * // All events will be associated with the same session ID
  * ```
@@ -111,7 +117,7 @@ export class SessionPathwayBuilder {
      * });
      *
      * // When writing events, the user ID will be automatically included
-     * await session.write("user/action", actionData);
+     * await session.write("user/action", { data: actionData });
      * ```
      */
     withUserResolver(resolver) {
@@ -122,17 +128,21 @@ export class SessionPathwayBuilder {
      * Writes data to a pathway, proxying to the underlying PathwaysBuilder
      *
      * @param path The pathway to write to
-     * @param data The data to write
-     * @param metadata Optional metadata to include with the event
-     * @param options Optional write options
+     * @param input Object containing the data, metadata, options, and optional batch flag
      * @returns A promise that resolves to the event ID(s)
      */
-    async write(path, data, metadata, options) {
+    async write(path, input) {
+        const { data, metadata, options, batch } = input;
         // Create new options object with session ID
         const finalOptions = options ? { ...options } : {};
         // Always include the session ID in the options
         finalOptions.sessionId = options?.sessionId ?? this.sessionId;
         // The PathwaysBuilder will handle session-specific user resolvers
-        return await this.pathwaysBuilder.write(path, { data, metadata, options: finalOptions });
+        return await this.pathwaysBuilder.write(path, {
+            batch,
+            data,
+            metadata,
+            options: finalOptions,
+        });
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowcore/pathways",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "description": "A TypeScript Library for creating Flowcore Pathways, simplifying the integration with the flowcore platform",
   "homepage": "https://github.com/flowcore-io/flowcore-pathways#readme",
   "repository": {

package/script/pathways/session-pathway.d.ts

@@ -33,8 +33,14 @@ import type { EventMetadata, PathwayWriteOptions } from "./types.js";
  * session.withUserResolver(async () => getCurrentUserId());
  *
  * // Write events with session context
- * await session.write("order/placed", orderData);
- * await session.write("user/action", actionData);
+ * await session.write("order/placed", { data: orderData });
+ * await session.write("user/action", { data: actionData });
+ *
+ * // Write batch events with session context
+ * await session.write("user/actions", {
+ *   batch: true,
+ *   data: [actionData1, actionData2]
+ * });
  *
  * // All events will be associated with the same session ID
  * ```
@@ -84,7 +90,7 @@ export declare class SessionPathwayBuilder<TPathway extends Record<string, {
      * });
      *
      * // When writing events, the user ID will be automatically included
-     * await session.write("user/action", actionData);
+     * await session.write("user/action", { data: actionData });
      * ```
      */
     withUserResolver(resolver: UserIdResolver): this;
@@ -92,11 +98,14 @@ export declare class SessionPathwayBuilder<TPathway extends Record<string, {
      * Writes data to a pathway, proxying to the underlying PathwaysBuilder
      *
      * @param path The pathway to write to
-     * @param data The data to write
-     * @param metadata Optional metadata to include with the event
-     * @param options Optional write options
+     * @param input Object containing the data, metadata, options, and optional batch flag
      * @returns A promise that resolves to the event ID(s)
      */
-    write<TPath extends TWritablePaths>(path: TPath, data: TPathway[TPath]["input"], metadata?: EventMetadata, options?: PathwayWriteOptions): Promise<string | string[]>;
+    write<TPath extends TWritablePaths, B extends boolean = false>(path: TPath, input: {
+        batch?: B;
+        data: B extends true ? TPathway[TPath]["input"][] : TPathway[TPath]["input"];
+        metadata?: EventMetadata;
+        options?: PathwayWriteOptions;
+    }): Promise<string | string[]>;
 }
 //# sourceMappingURL=session-pathway.d.ts.map

package/script/pathways/session-pathway.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-pathway.d.ts","sourceRoot":"","sources":["../../src/pathways/session-pathway.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAqBpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBAAa,qBAAqB,CAEhC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC,GAAG,EAAE,EACzE,cAAc,SAAS,MAAM,QAAQ,GAAG,KAAK;IAE7C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA2C;IAC3E,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAElC;;;;;OAKG;gBAED,eAAe,EAAE,eAAe,CAAC,QAAQ,EAAE,cAAc,CAAC,EAC1D,SAAS,CAAC,EAAE,MAAM;IAMpB;;;;OAIG;IACH,YAAY,IAAI,MAAM;IAItB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,gBAAgB,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI;IAKhD;;;;;;;;OAQG;IACG,KAAK,CAAC,KAAK,SAAS,cAAc,EACtC,IAAI,EAAE,KAAK,EACX,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,EAC9B,QAAQ,CAAC,EAAE,aAAa,EACxB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC;CAU9B"}
+{"version":3,"file":"session-pathway.d.ts","sourceRoot":"","sources":["../../src/pathways/session-pathway.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAqBpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,qBAAa,qBAAqB,CAEhC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC,GAAG,EAAE,EACzE,cAAc,SAAS,MAAM,QAAQ,GAAG,KAAK;IAE7C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA2C;IAC3E,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAElC;;;;;OAKG;gBAED,eAAe,EAAE,eAAe,CAAC,QAAQ,EAAE,cAAc,CAAC,EAC1D,SAAS,CAAC,EAAE,MAAM;IAMpB;;;;OAIG;IACH,YAAY,IAAI,MAAM;IAItB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,gBAAgB,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI;IAKhD;;;;;;OAMG;IACG,KAAK,CAAC,KAAK,SAAS,cAAc,EAAE,CAAC,SAAS,OAAO,GAAG,KAAK,EACjE,IAAI,EAAE,KAAK,EACX,KAAK,EAAE;QACL,KAAK,CAAC,EAAE,CAAC,CAAA;QACT,IAAI,EAAE,CAAC,SAAS,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,EAAE,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,CAAA;QAC5E,QAAQ,CAAC,EAAE,aAAa,CAAA;QACxB,OAAO,CAAC,EAAE,mBAAmB,CAAA;KAC9B,GACA,OAAO,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC;CAiB9B"}

package/script/pathways/session-pathway.js

@@ -51,8 +51,14 @@ function generateUUID() {
  * session.withUserResolver(async () => getCurrentUserId());
  *
  * // Write events with session context
- * await session.write("order/placed", orderData);
- * await session.write("user/action", actionData);
+ * await session.write("order/placed", { data: orderData });
+ * await session.write("user/action", { data: actionData });
+ *
+ * // Write batch events with session context
+ * await session.write("user/actions", {
+ *   batch: true,
+ *   data: [actionData1, actionData2]
+ * });
  *
  * // All events will be associated with the same session ID
  * ```
@@ -114,7 +120,7 @@ class SessionPathwayBuilder {
      * });
      *
      * // When writing events, the user ID will be automatically included
-     * await session.write("user/action", actionData);
+     * await session.write("user/action", { data: actionData });
      * ```
      */
     withUserResolver(resolver) {
@@ -125,18 +131,22 @@ class SessionPathwayBuilder {
      * Writes data to a pathway, proxying to the underlying PathwaysBuilder
      *
      * @param path The pathway to write to
-     * @param data The data to write
-     * @param metadata Optional metadata to include with the event
-     * @param options Optional write options
+     * @param input Object containing the data, metadata, options, and optional batch flag
      * @returns A promise that resolves to the event ID(s)
      */
-    async write(path, data, metadata, options) {
+    async write(path, input) {
+        const { data, metadata, options, batch } = input;
         // Create new options object with session ID
         const finalOptions = options ? { ...options } : {};
         // Always include the session ID in the options
         finalOptions.sessionId = options?.sessionId ?? this.sessionId;
         // The PathwaysBuilder will handle session-specific user resolvers
-        return await this.pathwaysBuilder.write(path, { data, metadata, options: finalOptions });
+        return await this.pathwaysBuilder.write(path, {
+            batch,
+            data,
+            metadata,
+            options: finalOptions,
+        });
     }
 }
 exports.SessionPathwayBuilder = SessionPathwayBuilder;