Add support for listing and deleting streams

CHANGELOG.md

@@ -1,5 +1,142 @@
 # @agentuity/sdk Changelog
 
+## 0.0.156
+
+### Patch Changes
+
+- b7c6499: Make the logging around Telemetry more generic
+
+- You can now list and search through your streams with flexible filtering and pagination options.
+
+  ```typescript
+  import { streams } from "@agentuity/sdk";
+
+  // List all streams
+  const result = await streams.list();
+  console.log(`Found ${result.total} streams`);
+  result.streams.forEach((stream) => {
+    console.log(`${stream.name}: ${stream.url} (${stream.sizeBytes} bytes)`);
+  });
+
+  // Filter by name
+  const namedStreams = await streams.list({
+    name: "my-report",
+  });
+
+  // Filter by metadata
+  const customerStreams = await streams.list({
+    metadata: { customerId: "customer-123", type: "invoice" },
+  });
+
+  // Paginate results
+  const page1 = await streams.list({ limit: 10, offset: 0 });
+  const page2 = await streams.list({ limit: 10, offset: 10 });
+
+  // Combine filters
+  const filtered = await streams.list({
+    name: "analytics",
+    metadata: { department: "sales" },
+    limit: 50,
+    offset: 0,
+  });
+  ```
+
+  **Response Format:**
+
+  - `success`: Boolean indicating if the request succeeded
+  - `streams`: Array of stream objects with `id`, `name`, `metadata`, `url`, and `sizeBytes`
+  - `total`: Total count of streams matching your filters (useful for pagination)
+  - `message`: Optional error message if request failed
+
+  **Pagination:**
+
+  - Default limit: 100 streams
+  - Maximum limit: 1000 streams
+  - Use `offset` to skip streams for pagination
+
+  You can now delete streams by their ID when they're no longer needed.
+
+  ```typescript
+  import { streams } from "@agentuity/sdk";
+
+  // Delete a stream
+  await streams.delete("stream-id-123");
+
+  // Handle deletion with error checking
+  try {
+    await streams.delete(streamId);
+    console.log("Stream deleted successfully");
+  } catch (error) {
+    if (error.message.includes("not found")) {
+      console.log("Stream does not exist");
+    } else {
+      console.error("Failed to delete stream:", error);
+    }
+  }
+  ```
+
+  **Notes:**
+
+  - Returns nothing on success
+  - Throws error if stream ID is invalid or empty
+  - Throws "Stream not found" error if stream doesn't exist
+  - Stream IDs must be non-empty strings
+
+  ```typescript
+  import { streams } from "@agentuity/sdk";
+
+  // Create a stream
+  const stream = await streams.create("user-export", {
+    metadata: { userId: "user-123", format: "csv" },
+  });
+
+  await stream.write("Name,Email\n");
+  await stream.write("John,john@example.com\n");
+  await stream.close();
+
+  console.log(`Stream created: ${stream.url}`);
+
+  // List streams by metadata
+  const userStreams = await streams.list({
+    metadata: { userId: "user-123" },
+  });
+
+  console.log(`Found ${userStreams.total} streams for user`);
+
+  // Clean up old streams
+  for (const oldStream of userStreams.streams) {
+    await streams.delete(oldStream.id);
+    console.log(`Deleted: ${oldStream.name}`);
+  }
+  ```
+
+  If you're currently managing streams, you can now:
+
+  - **Search and organize**: Use the list API to find streams by name or metadata instead of tracking IDs manually
+  - **Paginate large lists**: Process streams in batches using limit/offset
+  - **Clean up**: Delete streams that are no longer needed to manage storage
+  - **Audit**: Use metadata filters to find streams by customer, project, or any custom tags
+
+  **Parameters:**
+
+  - `name` (optional): Filter streams by name
+  - `metadata` (optional): Object with key-value pairs to filter by metadata
+  - `limit` (optional): Maximum streams to return (1-1000, default: 100)
+  - `offset` (optional): Number of streams to skip for pagination
+
+  **Returns:** `Promise<ListStreamsResponse>`
+
+  **Parameters:**
+
+  - `id` (required): The stream ID to delete
+
+  **Returns:** `Promise<void>`
+
+  **Throws:**
+
+  - Error if ID is invalid, empty, or only whitespace
+  - "Stream not found" if stream doesn't exist
+
 ## 0.0.155
 
 ### Patch Changes