StoneCutter.Sdk 1.0.1

StoneCutter

A .NET API and lightweight client SDK for managing stone records. The SDK is built on .NET Standard 2.1, making it compatible with .NET Core 3.0+, .NET 5+, Xamarin, and Unity 2021.2+.

Table of Contents

• API Endpoints
  • POST /api/stones
  • GET /api/stones
• SDK Reference
  • StoneCutterClient
  • StoneData
  • StoneSizeType
  • PagedResponse<T>
• Unity Integration Guide
  • Prerequisites
  • Adding Newtonsoft.Json
  • Basic Usage in Unity
  • Coroutine Wrapper for UI
  • Infinite Scroll / Pagination
  • Error Handling
  • Best Practices

API Endpoints

POST /api/stones

Saves a new stone record to the database.

Request Body (application/json):

{
  "name": "Emerald Shard",
  "stoneSize": 1,
  "stoneColor": "Green",
  "jadeCount": 5,
  "jsonContext": "{\"origin\":\"cave\"}"
}

Response (201 Created):

{
  "id": 42,
  "name": "Emerald Shard",
  "stoneSize": 1,
  "stoneColor": "Green",
  "jadeCount": 5,
  "jsonContext": "{\"origin\":\"cave\"}",
  "createdAt": "2026-03-04T05:30:00Z"
}

GET /api/stones

Retrieves stone records from the database with pagination, sorting, and filtering.

Query Parameters:

Example Request:

GET /api/stones?page=1&pageSize=20&sortOrder=desc&stoneColor=Green&minJadeCount=3

Response (200 OK):

{
  "items": [
    {
      "id": 42,
      "name": "Emerald Shard",
      "stoneSize": 1,
      "stoneColor": "Green",
      "jadeCount": 5,
      "jsonContext": "{\"origin\":\"cave\"}",
      "createdAt": "2026-03-04T05:30:00Z"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "totalCount": 1,
  "totalPages": 1
}

SDK Reference

StoneCutterClient

The main entry point for all SDK operations. Implements IDisposable.

Constructors

Methods

SaveStone

Task<StoneData> SaveStone(
    string name,
    StoneSizeType stoneSize = StoneSizeType.Small,
    string stoneColor = "",
    int jadeCount = 0,
    string jsonContext = ""
)

Saves a new stone record via POST /api/stones.

Returns: StoneData — the persisted stone record including its server-assigned Id and CreatedAt.

GetStones

Task<List<StoneData>> GetStones()

Convenience method that returns the first 10 stones, sorted by date descending. Internally calls GET /api/stones?page=1&pageSize=10&sortOrder=desc.

Returns: List<StoneData>

GetStonesPaged

Task<PagedResponse<StoneData>> GetStonesPaged(
    int page = 1,
    int pageSize = 10,
    string sortOrder = "desc",
    StoneSizeType? stoneSize = null,
    string? stoneColor = null,
    int? minJadeCount = null,
    int? maxJadeCount = null
)

Full-featured paginated query with optional filters.

Returns: PagedResponse<StoneData> — includes Items, pagination metadata, and HasNextPage.

StoneData

Represents a single stone record returned by the API.

StoneSizeType

Enum representing stone size categories.

PagedResponse<T>

Generic wrapper for paginated API results.

Unity Integration Guide

Prerequisites

Adding Newtonsoft.Json

The SDK depends on Newtonsoft.Json. In Unity, install it via one of these methods:

Option A — Unity Package Manager (Recommended):

1. Open Window → Package Manager
2. Click + → Add package by name
3. Enter: com.unity.nuget.newtonsoft-json

Option B — Manual DLL:

1. Download Newtonsoft.Json.dll (v13.0.3, netstandard2.0 build) from NuGet
2. Place it in Assets/Plugins/Newtonsoft/

Basic Usage in Unity

Create a MonoBehaviour to interact with the SDK using async/await:

using UnityEngine;
using StoneCutter.Sdk;

public class StoneManager : MonoBehaviour
{
    private StoneCutterClient _client;

    [SerializeField] private string apiUrl = "https://your-api-url.com";

    private void Awake()
    {
        _client = new StoneCutterClient(apiUrl);
    }

    private void OnDestroy()
    {
        _client?.Dispose();
    }

    // Save a stone via POST /api/stones
    public async void SaveStone(string stoneName, StoneSizeType size, string color, int jade)
    {
        try
        {
            var stone = await _client.SaveStone(stoneName, size, color, jade);
            Debug.Log($"Stone saved! ID: {stone.Id}, Name: {stone.Name}, Color: {stone.StoneColor}");
        }
        catch (System.Exception ex)
        {
            Debug.LogError($"Failed to save stone: {ex.Message}");
        }
    }

    // Get stones via GET /api/stones with pagination
    public async void LoadFirstPage()
    {
        try
        {
            var page = await _client.GetStonesPaged(page: 1, pageSize: 20); // randomly load stones from datbase

            foreach (var stone in page.Items)
                Debug.Log($"{stone.Name} — Size: {stone.StoneSize}, Color: {stone.StoneColor}, Jade: {stone.JadeCount}");
        }
        catch (System.Exception ex)
        {
            Debug.LogError($"Failed to load stones: {ex.Message}");
        }
    }
}

Note: async void is acceptable for Unity event handlers (button clicks, lifecycle methods). For internal logic, prefer async Task and propagate exceptions properly.

Coroutine Wrapper for UI

If you prefer Unity coroutines over async/await (e.g., for progress indicators or frame-by-frame updates), wrap async calls like this:

using System.Collections;
using System.Threading.Tasks;
using UnityEngine;
using StoneCutter.Sdk;

public class StoneLoader : MonoBehaviour
{
    private StoneCutterClient _client;

    private void Awake()
    {
        _client = new StoneCutterClient("https://your-api-url.com");
    }

    private void OnDestroy()
    {
        _client?.Dispose();
    }

    public void StartLoading()
    {
        StartCoroutine(LoadStonesCoroutine());
    }

    private IEnumerator LoadStonesCoroutine()
    {
        var task = _client.GetStonesPaged(page: 1, pageSize: 10);

        // Wait for the async task to complete
        while (!task.IsCompleted)
            yield return null;

        if (task.IsFaulted)
        {
            Debug.LogError($"Error: {task.Exception?.InnerException?.Message}");
            yield break;
        }

        var result = task.Result;
        Debug.Log($"Loaded {result.Items.Count} of {result.TotalCount} stones");

        foreach (var stone in result.Items)
            Debug.Log($"  {stone.Name} — {stone.StoneColor}");
    }
}

Infinite Scroll / Pagination

Use GetStonesPaged with the HasNextPage property to implement dynamic loading as the user scrolls:

using System.Collections.Generic;
using UnityEngine;
using StoneCutter.Sdk;

public class InfiniteStoneScroller : MonoBehaviour
{
    private StoneCutterClient _client;
    private int _currentPage = 0;
    private bool _isLoading = false;
    private bool _hasMore = true;

    private readonly List<StoneData> _allStones = new List<StoneData>();

    [SerializeField] private int pageSize = 20;
    [SerializeField] private string apiUrl = "https://your-api-url.com";

    private void Awake()
    {
        _client = new StoneCutterClient(apiUrl);
    }

    private void OnDestroy()
    {
        _client?.Dispose();
    }

    /// <summary>
    /// Call this when the user scrolls near the bottom of the list.
    /// </summary>
    public async void LoadNextPage()
    {
        if (_isLoading || !_hasMore) return;

        _isLoading = true;
        _currentPage++;

        try
        {
            var page = await _client.GetStonesPaged(
                page: _currentPage,
                pageSize: pageSize,
                sortOrder: "desc"
            );

            _allStones.AddRange(page.Items);
            _hasMore = page.HasNextPage;

            Debug.Log($"Page {page.Page}/{page.TotalPages} loaded — " +
                      $"{_allStones.Count}/{page.TotalCount} total");

            // TODO: Update your ScrollView / ListView UI here
        }
        catch (System.Exception ex)
        {
            Debug.LogError($"Failed to load page {_currentPage}: {ex.Message}");
            _currentPage--; // Revert so user can retry
        }
        finally
        {
            _isLoading = false;
        }
    }

    /// <summary>
    /// Call this with filter parameters to load a filtered + paginated view.
    /// </summary>
    public async void LoadFiltered(StoneSizeType? size, string stoneColor, int? minJade, int? maxJade)
    {
        _allStones.Clear();
        _currentPage = 0;
        _hasMore = true;

        _isLoading = true;
        _currentPage = 1;

        try
        {
            var page = await _client.GetStonesPaged(
                page: 1,
                pageSize: pageSize,
                stoneSize: size,
                stoneColor: stoneColor,
                minJadeCount: minJade,
                maxJadeCount: maxJade
            );

            _allStones.AddRange(page.Items);
            _hasMore = page.HasNextPage;
        }
        catch (System.Exception ex)
        {
            Debug.LogError($"Filter query failed: {ex.Message}");
        }
        finally
        {
            _isLoading = false;
        }
    }
}

Error Handling

The SDK throws exceptions in the following scenarios:

Recommended Unity pattern:

public async void SafeApiCall()
{
    try
    {
        var stones = await _client.GetStones();
        // Process stones...
    }
    catch (System.Net.Http.HttpRequestException ex)
    {
        // Show "No connection" UI
        Debug.LogWarning($"Network error: {ex.Message}");
    }
    catch (System.InvalidOperationException ex)
    {
        // Unexpected API response format
        Debug.LogError($"Data error: {ex.Message}");
    }
    catch (System.Exception ex)
    {
        // Catch-all
        Debug.LogError($"Unexpected error: {ex.Message}");
    }
}

Best Practices

1. Single client instance — Create one StoneCutterClient in Awake() and dispose it in OnDestroy(). Avoid creating a new client per request.

2. Don't block the main thread — Always use async/await or coroutine wrappers. Never call .Result or .Wait() on the main thread — this will freeze your game.

3. Handle scene transitions — Dispose the client when changing scenes to avoid orphaned HTTP connections:

   private void OnDestroy()
   {
       _client?.Dispose();
   }
   

4. IL2CPP / AOT considerations — If building with IL2CPP (iOS, WebGL), ensure link.xml preserves the SDK types from being stripped:

   <linker>
       <assembly fullname="StoneCutter.Sdk" preserve="all"/>
       <assembly fullname="Newtonsoft.Json" preserve="all"/>
   </linker>
   

   Place this file at Assets/link.xml.

5. Thread safety — StoneCutterClient is not thread-safe. If you need concurrent access from multiple threads, create separate client instances or synchronize access.

6. Configure API URL — Use a [SerializeField] field or ScriptableObject for the API URL so it can be changed per environment (dev/staging/prod) without recompiling.