SectlClient 1.0.0

SECTL Client for .NET

SECTL OAuth API 的 .NET 客户端库，支持 .NET 6.0 及以上版本。

功能特性

• OAuth 2.0 授权流程（强制 PKCE）
• Token 管理（获取、刷新、验证、撤销）
• 用户信息获取
• 云存储功能（文件上传、下载、分享、KV 存储）
• 通知管理
• 统计功能
• 认证客户端与云存储客户端职责分离

安装

通过 NuGet 安装

dotnet add package SectlClient

手动安装

将本项目添加到你的解决方案中，或直接引用项目文件。

快速开始

1. OAuth 认证

using SectlClient;
using SectlClient.Models;

// 创建客户端实例
using var client = new SectlAuthClient(
    platformId: "pf_your_platform_id",
    callbackUrl: "http://localhost:5000/callback"
);

// 生成授权 URL（强制使用 PKCE）
var authUrl = client.GetAuthorizationUrl(
    state: "random_state_string",
    scope: new List<string> { "user:read", "cloud:read", "cloud:write" }
);

Console.WriteLine($"请在浏览器中打开以下链接进行授权:\n{authUrl}");

// 用户授权后，使用授权码换取 Token
Console.Write("请输入授权码: ");
var authCode = Console.ReadLine();

var tokenResponse = await client.ExchangeCodeForTokenAsync(
    code: authCode,
    deviceUuid: Guid.NewGuid().ToString()
);

Console.WriteLine($"授权成功! Access Token: {tokenResponse.AccessToken}");

2. Token 管理

// 从文件加载已保存的 Token
if (client.LoadToken())
{
    Console.WriteLine("已从文件加载 Token");
}

// 验证 Token 有效性
var introspection = await client.IntrospectTokenAsync();
if (introspection.Active)
{
    Console.WriteLine($"Token 有效，用户 ID: {introspection.UserId}");
}

// 刷新 Token
var newToken = await client.RefreshAccessTokenAsync();

// 登出（撤销 Token）
await client.LogoutAsync();

3. 获取用户信息

var userInfo = await client.GetUserInfoAsync();
Console.WriteLine($"用户 ID: {userInfo.UserId}");
Console.WriteLine($"邮箱: {userInfo.Email}");
Console.WriteLine($"名称: {userInfo.Name}");

4. 云存储

Bearer Token 调用云存储接口时，userId 通常可省略；仅在服务端 / API Key 模式下才建议显式传入。

using SectlClient;

// 创建云存储客户端
using var storageClient = new CloudStorageClient(
    platformId: "pf_your_platform_id",
    accessToken: accessToken,
    userId: userId
);

// 上传文件
var uploadResult = await storageClient.UploadFileAsync(
    filePath: "./document.pdf"
);
Console.WriteLine($"文件上传成功，ID: {uploadResult.FileId}");

// 获取文件列表
var fileList = await storageClient.ListFilesAsync(limit: 20);
foreach (var file in fileList.Files)
{
    Console.WriteLine($"- {file.Filename} ({file.Size} 字节)");
}

// 下载文件
var downloadInfo = await storageClient.DownloadFileAsync(fileId);
Console.WriteLine($"下载链接: {downloadInfo.DownloadUrl}");

// 创建分享链接
var shareResult = await storageClient.CreateShareAsync(
    fileId: fileId,
    expiresIn: 86400, // 1 天
    password: "123456"
);
Console.WriteLine($"分享链接: {shareResult.ShareUrl}");

// KV 存储
await storageClient.SetKvAsync("settings", new { theme = "dark" });
await storageClient.UpdateKvFieldAsync("settings", "theme", "light");
var kvItem = await storageClient.GetKvAsync("settings");
Console.WriteLine($"设置: {kvItem.Value}");

5. 通知管理

// 获取通知列表
var notifications = await client.GetNotificationsAsync(unreadOnly: true);
foreach (var notification in notifications.Notifications)
{
    Console.WriteLine($"- {notification.Title}: {notification.Content}");
}

// 标记通知为已读
await client.MarkNotificationReadAsync(notificationId);

// 标记所有通知为已读
await client.MarkAllNotificationsReadAsync();

// 发送通知（需要平台认证）
await client.SendNotificationAsync(
    userId: "user_id",
    title: "系统通知",
    content: "您有新的消息",
    priority: "normal"
);

6. 统计功能

// 上报在线状态
var onlineStatus = await client.ReportOnlineAsync(
    deviceUuid: Guid.NewGuid().ToString(),
    customData: new Dictionary<string, object> { ["version"] = "1.0.0" }
);
Console.WriteLine($"当前在线人数: {onlineStatus.OnlineCount}");

// 上报访问记录
var visitStats = await client.ReportVisitAsync(deviceUuid: "device-uuid");
Console.WriteLine($"今日访问次数: {visitStats.VisitCount}");

// 获取平台统计数据
var platformStats = await client.GetPlatformStatsAsync();
Console.WriteLine($"总访问量: {platformStats.Visits?.TotalVisits}");

API 参考

SectlAuthClient

主要的 OAuth 认证客户端类。

构造函数

public SectlAuthClient(
    string platformId,
    string callbackUrl,
    string? baseUrl = null,
    int callbackPort = 5000)

主要方法

CloudStorageClient

云存储客户端类。

构造函数

public CloudStorageClient(
    string platformId,
    string accessToken,
    string baseUrl = "https://appwrite.sectl.top",
    string? userId = null)

主要方法

异常处理

SDK 提供了完整的异常类型体系：

using SectlClient.Exceptions;

try
{
    var userInfo = await client.GetUserInfoAsync();
}
catch (AuthenticationException ex)
{
    // 认证失败
    Console.WriteLine($"认证失败: {ex.Message}");
}
catch (TokenException ex)
{
    // Token 相关错误
    Console.WriteLine($"Token 错误: {ex.Message}");
}
catch (TokenExpiredException ex)
{
    // Token 已过期
    Console.WriteLine($"Token 已过期: {ex.Message}");
}
catch (CloudStorageException ex)
{
    // 云存储错误
    Console.WriteLine($"云存储错误: {ex.Message}");
}
catch (NetworkException ex)
{
    // 网络错误
    Console.WriteLine($"网络错误: {ex.Message}");
}
catch (SectlAuthException ex)
{
    // 通用 SECTL 异常
    Console.WriteLine($"SECTL 错误: {ex.Message}");
}

权限说明

配置

基础 URL

• 默认 API URL: https://appwrite.sectl.top
• 默认认证 URL: https://sectl.top

超时设置

• 默认请求超时: 60 秒
• 文件上传超时: 120 秒

示例项目

查看 Examples/ 目录获取完整的示例代码：

• OAuthExample.cs - OAuth 认证流程示例
• CloudStorageExample.cs - 云存储功能示例
• NotificationExample.cs - 通知和统计功能示例

许可证

MIT License