ResearchCave.Economy.Client (1.0.0)
Installation
dotnet nuget add source --name ResearchCave --username your_username --password your_token https://git.researchcave.com/api/packages/ResearchCave/nuget/index.jsondotnet add package --source ResearchCave --version 1.0.0 ResearchCave.Economy.ClientAbout this package
Mobile and service-friendly typed client for ResearchCave Economy catalogue, inventory, gifting, trades and marketplace.
ResearchCave.Economy.Client
Typed NuGet client for the ResearchCave item catalog, inventory, gifts, direct trades, containers, marketplace, and staff catalog management. The package targets .NET 10 and works in ASP.NET Core services, workers, and .NET mobile or desktop applications.
Service registration
Reference ResearchCave.Economy.Client, then use the standard service-discovery address:
{
"Services": {
"Economy": {
"BaseUrl": "https+http://researchcave-economy",
"UseServiceAuthentication": true,
"Scope": "economy.api",
"RewardsScope": "economy.rewards.write",
"TimeoutSeconds": 15
}
}
}
services.AddResearchCaveEconomyClient(configuration);
The default authentication provider obtains and caches a client-credentials token from the configured ResearchCave
OIDC authority. Callers may register their own IEconomyAccessTokenProvider before registration when they use a
different service-token mechanism.
Member operations
Inject IEconomyClient:
public sealed class GiftSender(IEconomyClient economy)
{
public async Task<GiftPurchaseDto> SendAsync(
Guid itemDefinitionId,
Guid priceOfferId,
Guid recipientUserId,
Guid postId,
CancellationToken cancellationToken)
{
return await economy.PurchaseGiftAsync(new PurchaseGiftRequest(
itemDefinitionId,
priceOfferId,
recipientUserId,
$"sentient:{postId:N}:{Guid.NewGuid():N}",
new GiftContextDto(
"ResearchCave.Sentient",
"Post",
postId.ToString("D"),
$"https://sentient.researchcave.com/posts/{postId:D}")), cancellationToken);
}
}
The member client includes:
- Full and gift-only catalogs.
- Available and historical inventory.
- Purchased gifts and transfers of already-owned items.
- Container opening.
- Public or invited trade creation, joining open public offers, offer editing, acceptance, cancellation, and observation.
- Marketplace browsing, listing management, purchasing, cancellation, and settlement lookup.
Every financial or inventory command requiring idempotency accepts a caller-created key. Reuse the same key only when retrying the same logical request.
Mobile applications
Interactive applications should disable service credentials and supply the signed-in member's access token:
services.AddResearchCaveEconomyClient(configuration, options =>
{
options.UseServiceAuthentication = false;
options.AccessTokenProvider = cancellationToken => tokenStore.GetAccessTokenAsync(cancellationToken);
});
The callback takes precedence over service authentication and allows the package DLL to be used directly by .NET MAUI and other .NET clients without depending on ASP.NET request state.
Staff operations
Inject IEconomyAdminClient for role-protected item/version creation, price and container-content management,
publishing, retirement, administrative minting, and operations-queue summaries. Authorization remains enforced by
the Economy server; resolving the staff interface does not grant staff access.
Rewards integrations inject IEconomyRewardsClient for the eligible content catalog, atomic campaign-package
creation, and participant-idempotent grants. Integration calls automatically request RewardsScope; production
authorization additionally requires the researchcave-rewards client identity.
Unsuccessful API calls throw EconomyApiException, which exposes the HTTP StatusCode and server
ResponseBody. Optional lookup methods return null for HTTP 404.
Live inventory integration
IEconomyLiveClient lists a member's giftable inventory and transfers a single owned
item for a Live stream. Only the researchcave-live service principal with
economy.live.gifts and the Economy audience can call these endpoints. Set
Services:Economy:Scope to economy.live.gifts in Live. Sender and recipient IDs
must come from Live's authenticated user and persisted broadcaster, never browser input.
Economy validates ownership, giftability, expiry and availability, records the stream
context, and deduplicates retries by sender plus client message ID. Reusing that ID
with different item, recipient or stream context is rejected.
Member clients can also call GET /api/v1/inventory/giftable with their own
Economy-audience user/personal-automation token; no owner parameter is accepted.