mixpeek 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mixpeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,369 @@
+# Mixpeek TypeScript/JavaScript SDK
+
+Official TypeScript/JavaScript SDK for the [Mixpeek](https://mixpeek.com) multimodal data processing and retrieval platform.
+
+[![npm version](https://badge.fury.io/js/mixpeek.svg)](https://www.npmjs.com/package/mixpeek)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- ✅ **100% Type-Safe** - Built with TypeScript for complete type safety
+- ✅ **Auto-Generated** - Always up-to-date with the latest Mixpeek API
+- ✅ **Runtime Validation** - Zod schemas for request/response validation
+- ✅ **Modern** - Supports both CommonJS and ESM
+- ✅ **Promise-Based** - Clean async/await API
+- ✅ **Comprehensive** - Covers all Mixpeek API endpoints
+- ✅ **Developer-Friendly** - Intuitive method names and excellent autocomplete
+
+## Installation
+
+```bash
+# npm
+npm install mixpeek
+
+# yarn
+yarn add mixpeek
+
+# pnpm
+pnpm add mixpeek
+```
+
+## Quick Start
+
+```typescript
+import { Mixpeek } from 'mixpeek';
+
+// Initialize the client
+const client = new Mixpeek({
+  apiKey: process.env.MIXPEEK_API_KEY, // Get your API key at https://dash.mixpeek.com
+  namespace: 'my-namespace' // Optional: for multi-tenant isolation
+});
+
+// List collections
+const collections = await client.collections.listCollections();
+console.log('Collections:', collections);
+
+// Create a collection
+const newCollection = await client.collections.createCollection({
+  alias: 'my-collection',
+  description: 'My first collection'
+});
+
+// Execute a retriever
+const results = await client.retrievers.executeRetriever({
+  retrieverId: 'ret_abc123',
+  query: 'find relevant documents'
+});
+```
+
+## Configuration
+
+### Environment Variables
+
+The SDK can be configured using environment variables:
+
+```bash
+# Required
+MIXPEEK_API_KEY=sk_your_api_key_here
+
+# Optional
+MIXPEEK_BASE_URL=https://api.mixpeek.com  # Default
+MIXPEEK_NAMESPACE=default                 # Default
+```
+
+### Constructor Options
+
+```typescript
+const client = new Mixpeek({
+  apiKey: 'sk_...',              // Required (or set MIXPEEK_API_KEY)
+  baseUrl: 'https://...',        // Optional: custom API endpoint
+  namespace: 'my-namespace',     // Optional: namespace for isolation
+  timeout: 30000,                // Optional: request timeout in ms
+  axiosConfig: {                 // Optional: additional axios config
+    // Any axios configuration options
+  }
+});
+```
+
+## Usage Examples
+
+### Collections
+
+```typescript
+// Create a collection
+const collection = await client.collections.createCollection({
+  alias: 'my-collection',
+  description: 'Store multimodal documents',
+  metadata: { project: 'demo' }
+});
+
+// Get a collection
+const retrieved = await client.collections.getCollection({
+  collectionIdentifier: 'my-collection'
+});
+
+// List all collections
+const allCollections = await client.collections.listCollections();
+
+// Delete a collection
+await client.collections.deleteCollection({
+  collectionIdentifier: 'my-collection'
+});
+```
+
+### Retrievers
+
+```typescript
+// Create a retriever
+const retriever = await client.retrievers.createRetriever({
+  retrieverName: 'semantic-search',
+  description: 'Search across all documents',
+  collectionIdentifiers: ['my-collection'],
+  stages: [
+    {
+      type: 'embed',
+      model: 'openai-text-embedding-3-small'
+    },
+    {
+      type: 'vector_search',
+      top_k: 10
+    }
+  ]
+});
+
+// Execute a retriever
+const results = await client.retrievers.executeRetriever({
+  retrieverId: retriever.retrieverId,
+  query: 'find relevant documents about AI'
+});
+
+// List retrievers
+const retrievers = await client.retrievers.listRetrievers();
+```
+
+### Documents
+
+```typescript
+// Upload documents to a collection
+const documents = await client.documents.uploadDocuments({
+  collectionId: 'col_abc123',
+  documents: [
+    {
+      url: 's3://bucket/video.mp4',
+      metadata: { title: 'Demo Video' }
+    },
+    {
+      url: 's3://bucket/image.jpg',
+      metadata: { title: 'Demo Image' }
+    }
+  ]
+});
+
+// Search documents
+const searchResults = await client.documents.searchDocuments({
+  collectionId: 'col_abc123',
+  query: 'search query',
+  limit: 20
+});
+```
+
+### Buckets (Object Storage)
+
+```typescript
+// Create a bucket
+const bucket = await client.buckets.createBucket({
+  alias: 'my-bucket',
+  provider: 's3',
+  credentials: {
+    accessKeyId: 'YOUR_ACCESS_KEY',
+    secretAccessKey: 'YOUR_SECRET_KEY',
+    region: 'us-east-1'
+  }
+});
+
+// List buckets
+const buckets = await client.buckets.listBuckets();
+```
+
+## Error Handling
+
+The SDK provides comprehensive error handling:
+
+```typescript
+try {
+  const collection = await client.collections.getCollection({
+    collectionIdentifier: 'non-existent'
+  });
+} catch (error) {
+  if (error.response) {
+    // API error
+    console.error('Status:', error.response.status);
+    console.error('Message:', error.response.data?.error?.message);
+  } else if (error.request) {
+    // Network error
+    console.error('Network error:', error.message);
+  } else {
+    // Other error
+    console.error('Error:', error.message);
+  }
+}
+```
+
+## TypeScript Support
+
+The SDK is built with TypeScript and provides full type definitions:
+
+```typescript
+import { Mixpeek, MixpeekOptions } from 'mixpeek';
+import type {
+  Collection,
+  Retriever,
+  CreateCollectionRequest,
+  CreateRetrieverRequest
+} from 'mixpeek';
+
+// All types are fully typed
+const options: MixpeekOptions = {
+  apiKey: 'sk_...',
+  namespace: 'default'
+};
+
+const client = new Mixpeek(options);
+
+// TypeScript will autocomplete and type-check all methods
+const collection: Collection = await client.collections.createCollection({
+  alias: 'typed-collection'
+  // TypeScript will suggest all available fields
+});
+```
+
+## Advanced Usage
+
+### Custom Axios Configuration
+
+```typescript
+const client = new Mixpeek({
+  apiKey: 'sk_...',
+  axiosConfig: {
+    timeout: 60000,
+    headers: {
+      'X-Custom-Header': 'value'
+    },
+    proxy: {
+      host: 'proxy.example.com',
+      port: 8080
+    }
+  }
+});
+```
+
+### Updating Configuration
+
+```typescript
+const client = new Mixpeek({ apiKey: 'sk_old' });
+
+// Update API key
+client.setApiKey('sk_new');
+
+// Update namespace
+client.setNamespace('new-namespace');
+
+// Get current configuration
+const config = client.getConfig();
+console.log(config);
+// { apiKey: 'sk_new...', baseUrl: '...', namespace: 'new-namespace' }
+```
+
+### Raw HTTP Requests
+
+For endpoints not yet covered by the SDK:
+
+```typescript
+const client = new Mixpeek({ apiKey: 'sk_...' });
+
+// Make a raw request
+const response = await client.request({
+  method: 'GET',
+  url: '/v1/custom-endpoint',
+  params: { limit: 10 }
+});
+```
+
+## Examples
+
+See the [`examples/`](./examples) directory for complete working examples:
+
+- [Quickstart](./examples/quickstart.ts) - Basic usage
+- [Collections](./examples/collections.ts) - Working with collections
+- [Retrievers](./examples/retrievers.ts) - Creating and executing retrievers
+- [Error Handling](./examples/error-handling.ts) - Comprehensive error handling
+
+## API Documentation
+
+For complete API documentation, visit:
+
+- **API Reference**: https://docs.mixpeek.com/api-reference
+- **Guides**: https://docs.mixpeek.com/guides
+- **Examples**: https://docs.mixpeek.com/examples
+
+## Development
+
+### Building from Source
+
+```bash
+# Clone the repository
+git clone https://github.com/mixpeek/server.git
+cd server/sdk/javascript-client
+
+# Install dependencies
+npm install
+
+# Generate SDK from OpenAPI spec
+npm run generate
+
+# Build
+npm run build
+
+# Run tests
+npm test
+```
+
+### Regenerating the SDK
+
+The SDK is auto-generated from the Mixpeek OpenAPI specification:
+
+```bash
+# Download latest OpenAPI spec
+curl -s https://api.mixpeek.com/docs/openapi.json -o openapi.json
+
+# Generate SDK
+npm run generate
+
+# Build
+npm run build
+```
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](../../CONTRIBUTING.md) for details.
+
+## Support
+
+- **Documentation**: https://docs.mixpeek.com
+- **Discord**: https://discord.gg/mixpeek
+- **Email**: support@mixpeek.com
+- **GitHub Issues**: https://github.com/mixpeek/server/issues
+
+## License
+
+MIT License - see [LICENSE](./LICENSE) for details.
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for version history.
+
+---
+
+**Built with** ❤️ **by the Mixpeek team**
+
+Auto-generated from OpenAPI spec using [OpenAPI Generator](https://openapi-generator.tech)