@23blocks/block-search 4.0.0 → 4.1.0

package/README.md

@@ -1,7 +1,300 @@
-# block-search
+# @23blocks/block-search
 
-This library was generated with [Nx](https://nx.dev).
+Search block for the 23blocks SDK - full-text search, suggestions, and favorites.
 
-## Building
+[![npm version](https://img.shields.io/npm/v/@23blocks/block-search.svg)](https://www.npmjs.com/package/@23blocks/block-search)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Run `nx build block-search` to build the library.
+## Installation
+
+```bash
+npm install @23blocks/block-search @23blocks/transport-http
+```
+
+## Overview
+
+This package provides comprehensive search functionality including:
+
+- **Search** - Full-text search with filtering and pagination
+- **Suggestions** - Autocomplete and typeahead
+- **Search History** - Recent searches and query management
+- **Favorites** - Save and manage favorite entities
+
+## Quick Start
+
+```typescript
+import { createHttpTransport } from '@23blocks/transport-http';
+import { createSearchBlock } from '@23blocks/block-search';
+
+// Create transport
+const transport = createHttpTransport({
+  baseUrl: 'https://api.yourapp.com',
+  headers: () => {
+    const token = localStorage.getItem('access_token');
+    return token ? { Authorization: `Bearer ${token}` } : {};
+  },
+});
+
+// Create block
+const search = createSearchBlock(transport, {
+  apiKey: 'your-api-key',
+});
+
+// Execute search
+const { results, totalRecords } = await search.search.search({
+  query: 'hello world',
+  limit: 20,
+});
+
+results.forEach((result) => {
+  console.log(result.title, result.score);
+});
+```
+
+## Services
+
+### search - Full-text Search
+
+```typescript
+// Basic search
+const { results, query, totalRecords, elapsedTime } = await search.search.search({
+  query: 'laptop',
+  limit: 20,
+  offset: 0,
+});
+
+// Search with entity type filtering
+const { results } = await search.search.search({
+  query: 'john',
+  entityTypes: ['users', 'contacts'],
+  limit: 10,
+});
+
+// Search with include/exclude terms
+const { results } = await search.search.search({
+  query: 'programming',
+  include: ['javascript', 'typescript'],
+  exclude: ['java'],
+});
+
+// Get search suggestions (autocomplete)
+const suggestions = await search.search.suggest('lap', 5);
+suggestions.forEach((s) => console.log(s.title));
+
+// Get available entity types
+const entityTypes = await search.search.entityTypes();
+entityTypes.forEach((type) => {
+  console.log(type.name, type.count);
+});
+```
+
+### history - Search History
+
+```typescript
+// Get recent searches
+const recentSearches = await search.history.recent(20);
+recentSearches.forEach((q) => {
+  console.log(q.query, q.totalRecords);
+});
+
+// Get specific query details
+const queryDetails = await search.history.get('query-id');
+
+// Clear all search history
+await search.history.clear();
+
+// Delete specific query from history
+await search.history.delete('query-id');
+```
+
+### favorites - Favorites Management
+
+```typescript
+// List favorites with pagination
+const { data: favorites, meta } = await search.favorites.list({
+  page: 1,
+  perPage: 20,
+});
+
+favorites.forEach((fav) => {
+  console.log(fav.entityAlias, fav.entityType);
+});
+
+// Get a specific favorite
+const favorite = await search.favorites.get('favorite-id');
+
+// Add to favorites
+const newFavorite = await search.favorites.add({
+  entityUniqueId: 'product-123',
+  entityType: 'Product',
+  entityAlias: 'MacBook Pro',
+  entityUrl: '/products/product-123',
+  entityAvatarUrl: 'https://example.com/image.jpg',
+});
+
+// Remove from favorites
+await search.favorites.remove('favorite-id');
+
+// Check if entity is favorited
+const isFavorited = await search.favorites.isFavorite('product-123');
+if (isFavorited) {
+  console.log('This item is in your favorites');
+}
+```
+
+## Types
+
+```typescript
+import type {
+  // Search types
+  SearchResult,
+  SearchQuery,
+  SearchRequest,
+  SearchResponse,
+
+  // History types
+  LastQuery,
+
+  // Favorites types
+  FavoriteEntity,
+  AddFavoriteRequest,
+
+  // Entity types
+  EntityType,
+} from '@23blocks/block-search';
+```
+
+### SearchRequest
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `query` | `string` | Search query text |
+| `entityTypes` | `string[]` | Filter by entity types |
+| `include` | `string[]` | Terms to include |
+| `exclude` | `string[]` | Terms to exclude |
+| `limit` | `number` | Max results to return |
+| `offset` | `number` | Pagination offset |
+
+### SearchResponse
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `results` | `SearchResult[]` | Search results |
+| `query` | `SearchQuery` | Query details |
+| `totalRecords` | `number` | Total matching records |
+| `elapsedTime` | `number` | Search duration (ms) |
+
+### SearchResult
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `id` | `string` | Result ID |
+| `uniqueId` | `string` | Unique identifier |
+| `title` | `string` | Display title |
+| `description` | `string` | Description text |
+| `entityType` | `string` | Type of entity |
+| `entityUniqueId` | `string` | Entity unique ID |
+| `score` | `number` | Relevance score |
+| `url` | `string` | Entity URL |
+| `avatarUrl` | `string` | Avatar/image URL |
+
+### FavoriteEntity
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `id` | `string` | Favorite ID |
+| `uniqueId` | `string` | Unique identifier |
+| `entityUniqueId` | `string` | Favorited entity ID |
+| `entityType` | `string` | Type of favorited entity |
+| `entityAlias` | `string` | Display name |
+| `entityUrl` | `string` | Entity URL |
+| `entityAvatarUrl` | `string` | Entity image URL |
+| `createdAt` | `Date` | When favorited |
+
+## Error Handling
+
+```typescript
+import { isBlockErrorException, ErrorCodes } from '@23blocks/contracts';
+
+try {
+  const results = await search.search.search({ query: '' });
+} catch (error) {
+  if (isBlockErrorException(error)) {
+    switch (error.code) {
+      case ErrorCodes.VALIDATION_ERROR:
+        console.log('Invalid search query');
+        break;
+      case ErrorCodes.UNAUTHORIZED:
+        console.log('Please sign in to search');
+        break;
+    }
+  }
+}
+```
+
+## Advanced Usage
+
+### Building a Search Component
+
+```typescript
+import { createSearchBlock } from '@23blocks/block-search';
+
+// Debounced search with suggestions
+let debounceTimer: NodeJS.Timeout;
+
+async function handleSearchInput(query: string) {
+  clearTimeout(debounceTimer);
+
+  debounceTimer = setTimeout(async () => {
+    if (query.length < 2) return;
+
+    // Get suggestions for autocomplete
+    const suggestions = await search.search.suggest(query, 5);
+    updateSuggestions(suggestions);
+  }, 300);
+}
+
+async function executeSearch(query: string) {
+  const { results, totalRecords } = await search.search.search({
+    query,
+    limit: 20,
+  });
+
+  updateResults(results);
+  updateResultCount(totalRecords);
+}
+```
+
+### Favorites Toggle
+
+```typescript
+async function toggleFavorite(entityId: string, entityType: string, entityName: string) {
+  const isFavorited = await search.favorites.isFavorite(entityId);
+
+  if (isFavorited) {
+    // Find and remove the favorite
+    const { data: favorites } = await search.favorites.list({
+      filter: { entity_unique_id: entityId },
+    });
+    if (favorites.length > 0) {
+      await search.favorites.remove(favorites[0].id);
+    }
+  } else {
+    await search.favorites.add({
+      entityUniqueId: entityId,
+      entityType,
+      entityAlias: entityName,
+    });
+  }
+}
+```
+
+## Related Packages
+
+- [`@23blocks/angular`](https://www.npmjs.com/package/@23blocks/angular) - Angular integration
+- [`@23blocks/react`](https://www.npmjs.com/package/@23blocks/react) - React integration
+- [`@23blocks/sdk`](https://www.npmjs.com/package/@23blocks/sdk) - Full SDK package
+
+## License
+
+MIT - Copyright (c) 2024 23blocks

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@23blocks/block-search",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "Search block for 23blocks SDK - full-text search, history, favorites",
   "license": "MIT",
   "author": "23blocks <hello@23blocks.com>",