HCFS/sdks/README.md

# HCFS Multi-Language SDKs

This directory contains SDK implementations for the HCFS API in multiple programming languages. Each SDK provides a consistent interface while following the idioms and conventions of its respective language.

## Available SDKs

| Language | Status | Features | Maintainer |
|----------|--------|----------|------------|
| [Python](../hcfs-python/) | ✅ Production | Full feature set, async/sync, WebSocket | Core Team |
| [JavaScript/TypeScript](./javascript/) | ✅ Production | Full feature set, Promise-based, WebSocket | Core Team |
| [Go](./go/) | ✅ Production | Full feature set, context-aware, channels | Core Team |
| [Rust](./rust/) | ✅ Production | Full feature set, async/await, type-safe | Core Team |
| [Java](./java/) | ✅ Production | Full feature set, reactive streams | Core Team |
| [C#](./csharp/) | ✅ Production | Full feature set, async/await, .NET Standard | Core Team |
| [PHP](./php/) | 🚧 Beta | Core features, PSR-compliant | Community |
| [Ruby](./ruby/) | 🚧 Beta | Core features, ActiveSupport style | Community |
| [Swift](./swift/) | 📋 Planned | iOS/macOS native support | Community |
| [Kotlin](./kotlin/) | 📋 Planned | Android/JVM support | Community |

## Common Features

All SDKs provide:

- **Context Management**: Create, read, update, delete contexts
- **Intelligent Search**: Semantic, keyword, and hybrid search
- **Batch Operations**: High-throughput batch processing
- **Authentication**: API key and JWT token support
- **Error Handling**: Comprehensive error types and handling
- **Configuration**: Flexible configuration options
- **Retry Logic**: Automatic retry with backoff strategies
- **Rate Limiting**: Built-in rate limiting support

Premium SDKs (maintained by core team) additionally include:

- **WebSocket Streaming**: Real-time event notifications
- **Advanced Caching**: Multiple caching strategies
- **Performance Monitoring**: Built-in metrics and analytics
- **Connection Pooling**: Optimized connection management
- **Type Safety**: Full type definitions and validation

## Quick Start Examples

### JavaScript/TypeScript
```javascript
import { HCFSClient, Context } from '@hcfs/sdk';

const client = new HCFSClient({
  baseUrl: 'https://api.hcfs.dev/v1',
  apiKey: 'your-api-key'
});

const context = new Context({
  path: '/docs/readme',
  content: 'Hello, HCFS!',
  summary: 'Getting started'
});

const created = await client.createContext(context);
console.log(`Created context: ${created.id}`);
```

### Go
```go
import "github.com/hcfs/hcfs-go"

client := hcfs.NewClient(&hcfs.Config{
    BaseURL: "https://api.hcfs.dev/v1",
    APIKey:  "your-api-key",
})

ctx := &hcfs.Context{
    Path:    "/docs/readme",
    Content: "Hello, HCFS!",
    Summary: "Getting started",
}

created, err := client.CreateContext(context.Background(), ctx)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Created context: %d\n", created.ID)
```

### Rust
```rust
use hcfs_sdk::{Client, Context, Config};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = Config::new("https://api.hcfs.dev/v1", "your-api-key");
    let client = Client::new(config);
    
    let context = Context::builder()
        .path("/docs/readme")
        .content("Hello, HCFS!")
        .summary("Getting started")
        .build()?;
    
    let created = client.create_context(context).await?;
    println!("Created context: {}", created.id);
    Ok(())
}
```

### Java
```java
import dev.hcfs.sdk.HCFSClient;
import dev.hcfs.sdk.Context;
import dev.hcfs.sdk.Config;

public class Example {
    public static void main(String[] args) {
        Config config = Config.builder()
            .baseUrl("https://api.hcfs.dev/v1")
            .apiKey("your-api-key")
            .build();
            
        HCFSClient client = new HCFSClient(config);
        
        Context context = Context.builder()
            .path("/docs/readme")
            .content("Hello, HCFS!")
            .summary("Getting started")
            .build();
        
        Context created = client.createContext(context).block();
        System.out.println("Created context: " + created.getId());
    }
}
```

### C#
```csharp
using HCFS.SDK;

var config = new HCFSConfig
{
    BaseUrl = "https://api.hcfs.dev/v1",
    ApiKey = "your-api-key"
};

using var client = new HCFSClient(config);

var context = new Context
{
    Path = "/docs/readme",
    Content = "Hello, HCFS!",
    Summary = "Getting started"
};

var created = await client.CreateContextAsync(context);
Console.WriteLine($"Created context: {created.Id}");
```

## Installation

Each SDK has its own installation method following language conventions:

| Language | Installation Command |
|----------|---------------------|
| Python | `pip install hcfs-sdk` |
| JavaScript | `npm install @hcfs/sdk` |
| Go | `go get github.com/hcfs/hcfs-go` |
| Rust | `cargo add hcfs-sdk` |
| Java | `implementation 'dev.hcfs:hcfs-sdk:2.0.0'` |
| C# | `dotnet add package HCFS.SDK` |

## Documentation

Each SDK includes comprehensive documentation:

- **API Reference**: Complete API documentation
- **Getting Started**: Quick start guides and tutorials  
- **Examples**: Common usage patterns and examples
- **Configuration**: Configuration options and environment setup
- **Error Handling**: Error types and handling strategies

## Contributing

We welcome contributions to all SDKs! Each SDK has its own contributing guidelines:

1. **Core SDKs** (Python, JS/TS, Go, Rust, Java, C#): Maintained by the core team
2. **Community SDKs**: Maintained by community contributors
3. **Planned SDKs**: Looking for maintainers

To contribute:

1. Fork the repository
2. Create a feature branch
3. Follow the language-specific style guides
4. Add tests for new functionality
5. Update documentation
6. Submit a pull request

## Support Matrix

| Feature | Python | JS/TS | Go | Rust | Java | C# |
|---------|--------|-------|----|----- |------|----| 
| Context CRUD | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Search | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Batch Operations | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| WebSocket Streaming | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Caching | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Retry Logic | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Type Safety | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Async/Await | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |

## License

All HCFS SDKs are released under the MIT License. See LICENSE file in each SDK directory for details.

## Getting Help

- **Documentation**: [https://docs.hcfs.dev](https://docs.hcfs.dev)
- **GitHub Issues**: [https://github.com/hcfs/hcfs/issues](https://github.com/hcfs/hcfs/issues)
- **Discord**: [https://discord.gg/hcfs](https://discord.gg/hcfs)
- **Email**: support@hcfs.dev