Rasepi .NET SDK

Official .NET client library for the Rasepi API — a multilingual-first collaborative documentation platform with forced expiry and plugin architecture.

Installation

dotnet add package Rasepi.SDK

Or via NuGet Package Manager:

Install-Package Rasepi.SDK

Quick Start

using Rasepi.SDK;

// Create client with API token
var client = new RasepiClient(new RasepiClientOptions
{
    BaseUrl = "https://your-instance.rasepi.com",
    AccessToken = "your-access-token"
});

// List hubs
var hubs = await client.Hubs.ListAsync();
foreach (var hub in hubs)
{
    Console.WriteLine($"{hub.Name} ({hub.Key})");
}

// Get an entry
var entry = await client.Entries.GetAsync(entryId);
Console.WriteLine(entry.Title);

// Create a new entry
var newEntry = await client.Entries.CreateAsync(new CreateEntryRequest
{
    HubKey = "engineering",
    Key = "getting-started",
    Title = "Getting Started Guide",
    Content = "<p>Hello world</p>",
    OriginalLanguage = "en",
    ExpiryDays = 90
});

Authentication

OAuth 2.0 Flow

var client = new RasepiClient(new RasepiClientOptions
{
    BaseUrl = "https://your-instance.rasepi.com"
});

// Step 1: Get the OAuth login URL
var loginUrl = client.Auth.GetLoginUrl("google", "https://your-app.com/callback");

// Step 2: After user completes OAuth, exchange the code
var tokens = await client.Auth.ExchangeCodeAsync(authCode);

// Step 3: Client automatically uses the tokens
// Tokens are refreshed automatically when expired

Token Refresh

The SDK automatically refreshes expired access tokens using the refresh token. You can also manually refresh:

var newTokens = await client.Auth.RefreshTokenAsync(refreshToken);

Development Token

For local development:

var client = new RasepiClient(new RasepiClientOptions
{
    BaseUrl = "http://localhost:5000",
    DevToken = new DevToken(tenantId, userId)
});

API Reference

Hubs

// List all accessible hubs
var hubs = await client.Hubs.ListAsync();

// Get a hub by key
var hub = await client.Hubs.GetAsync("engineering");

// Create a hub
var hub = await client.Hubs.CreateAsync(new CreateHubRequest
{
    Key = "engineering",
    Name = "Engineering",
    DefaultExpiryDays = 90,
    Icon = "mdi-code-braces",
    IconColor = "#4CAF50"
});

// Update a hub
await client.Hubs.UpdateAsync("engineering", new UpdateHubRequest
{
    Name = "Engineering Docs",
    DefaultExpiryDays = 120
});

// Delete a hub
await client.Hubs.DeleteAsync("engineering");

// Transfer ownership
await client.Hubs.TransferOwnershipAsync("engineering", newOwnerId);

Entries

// List entries in a hub
var entries = await client.Entries.ListByHubAsync("engineering");

// Get root entry
var root = await client.Entries.GetRootEntryAsync("engineering");

// Get entry by ID
var entry = await client.Entries.GetAsync(entryId);

// Create entry
var entry = await client.Entries.CreateAsync(new CreateEntryRequest { ... });

// Update entry
await client.Entries.UpdateAsync(entryId, new UpdateEntryRequest
{
    Title = "Updated Title",
    Content = "<p>Updated content</p>"
}, language: "en");

// Publish entry
await client.Entries.PublishAsync(entryId);

// Renew entry expiry
await client.Entries.RenewAsync(entryId);

// Delete entry
await client.Entries.DeleteAsync(entryId);

Translations

// List translations for an entry
var translations = await client.Translations.ListAsync(entryId);

// Get specific translation
var translation = await client.Translations.GetAsync(entryId, "de");

// Create/update translation
await client.Translations.CreateAsync(entryId, "de", new CreateTranslationRequest
{
    Title = "Erste Schritte",
    Content = "<p>Hallo Welt</p>",
    UseAutoTranslation = true,
    TranslationProvider = "deepl"
});

// Get translation status
var status = await client.Translations.GetStatusAsync(entryId, "de");

// Get stale blocks
var staleBlocks = await client.Translations.GetStaleBlocksAsync(entryId, "de");

// Mark translation as up-to-date
await client.Translations.MarkUpToDateAsync(entryId, "de");

Analytics

// Get entry analytics summary
var summary = await client.Analytics.GetSummaryAsync(entryId);

// Get activity events (paginated)
var events = await client.Analytics.GetEventsAsync(entryId, skip: 0, take: 50);

// Report time spent
await client.Analytics.ReportTimeSpentAsync(entryId, seconds: 120);

AI & Search

// Semantic search
var results = await client.AI.SearchAsync(new SearchRequest
{
    Query = "how to deploy",
    Mode = SearchMode.Hybrid,
    TopK = 20
});

// Agent conversations
var conversation = await client.AI.CreateConversationAsync("My Question");
var response = await client.AI.SendMessageAsync(conversation.Id, new SendMessageRequest
{
    Content = "How do I set up CI/CD?",
    HubKey = "engineering"
});

Knowledge Portal (Read API)

// Get portal feed
var feed = await client.Portal.GetFeedAsync();

// Get topics
var topics = await client.Portal.GetTopicsAsync();

// Get content
var content = await client.Portal.GetContentAsync("engineering", "getting-started", language: "en");

// Search
var results = await client.Portal.SearchAsync("deployment guide");

Sharing

// Create share link
var link = await client.Sharing.CreateAsync("getting-started", expiresAt: DateTime.UtcNow.AddDays(7));

// List share links
var links = await client.Sharing.ListAsync("getting-started");

// Revoke share link
await client.Sharing.RevokeAsync("getting-started", linkId);

Administration

// Expiry templates
var templates = await client.ExpiryTemplates.ListAsync();

// Tags & Categories
var tags = await client.Tags.ListAsync();
var categories = await client.Categories.ListAsync();

// Glossaries
var glossaries = await client.Glossaries.ListAsync();

// Languages
var languages = await client.Languages.ListEnabledAsync();

// Plugins
var plugins = await client.Plugins.ListAsync();

Configuration

var options = new RasepiClientOptions
{
    BaseUrl = "https://your-instance.rasepi.com",
    AccessToken = "your-token",
    
    // Optional: custom HttpClient
    HttpClient = myHttpClient,
    
    // Optional: timeouts
    Timeout = TimeSpan.FromSeconds(30),
    
    // Optional: retry policy
    MaxRetries = 3,
    RetryDelay = TimeSpan.FromSeconds(1)
};

Error Handling

try
{
    var hub = await client.Hubs.GetAsync("non-existent");
}
catch (RasepiApiException ex) when (ex.StatusCode == 404)
{
    Console.WriteLine("Hub not found");
}
catch (RasepiApiException ex) when (ex.StatusCode == 403)
{
    Console.WriteLine("Access denied");
}
catch (RasepiApiException ex)
{
    Console.WriteLine($"API error {ex.StatusCode}: {ex.Message}");
}

Requirements

• .NET 8.0 or later
• System.Net.Http.Json
• System.Text.Json

License

MIT — see LICENSE for details.