DeepSeekManualRAG.Bale 1.0.9

DeepSeekManualRAG.Bale

Reusable in-process NuGet adapter for Bale bot/payment integration.

The package contains:

• Bale Bot API HTTPS client
• optional single-owner getUpdates long polling
• ?start=chk1_... checkout flow
• sendInvoice
• pre-checkout callback into the host
• SuccessfulPayment + inquireTransaction verification
• checkout token/link helpers
• host contracts: IBaleCheckoutHandler, IBalePreCheckoutHandler, IBalePaymentHandler

The package does not own users, orders, prices, payment attempts, subscriptions, provider transaction uniqueness, or fulfillment. Those remain authoritative host state.

Register

builder.Services.AddBaleIntegration(
    builder.Configuration.GetSection("Bale"));

builder.Services.AddScoped<IBaleCheckoutHandler, HostBaleCheckoutHandler>();
builder.Services.AddScoped<IBalePreCheckoutHandler, HostBalePreCheckoutHandler>();
builder.Services.AddScoped<IBalePaymentHandler, HostBalePaymentHandler>();

Namespaces:

using DeepSeekManualRAG.Bale;
using DeepSeekManualRAG.Bale.Contracts;

Polling ownership

If long polling is used, exactly one process for a BotToken may set:

"Polling": { "Enabled": true }

All other replicas/processes must set it to false. Multiple consumers must not compete over Bale getUpdates offset state.

Create a checkout link

The host owns the checkout record. The package creates only an opaque token and Bale URL:

string token = tokenGenerator.Create();
// Persist a hash/state record for token -> PaymentAttempt/Expiry in the host.
string url = linkBuilder.Build(token);

The URL contains no Product/User/Price business data:

https://ble.ir/<bot_username>?start=chk1_<opaque-token>

IBaleCheckoutHandler.ResolveAsync receives BaleUpdateId and BaleMessageId; the host must use those together with checkout state to make the callback idempotent.

Payment authority

SuccessfulPayment is reconciled with Bale inquireTransaction before IBalePaymentHandler.ConfirmAsync is called.

ConfirmAsync is at-least-once and must enforce provider transaction uniqueness. If the same verified payment is delivered again after a crash/retry, return AlreadyConfirmed rather than applying business state twice.

HttpClient behavior

The package uses IHttpClientFactory with one short-lived factory client per API operation. Handler/connection pooling remains managed by the factory. Request-URI logging for this named client is disabled because Bale places BotToken in the URL path.

Long polling and command calls have separate client-side deadlines. No blanket infinite operation is exposed to the host.

Pre-checkout

Bale requires pre-checkout to be answered quickly. The package reserves separate host-decision and provider-answer budgets and prioritizes pre-checkout updates within each fetched batch. Failed/expired provider answers are consumed so they cannot permanently poison the polling stream.

Host-side provider verification

BaleApiClient remains injectable by the host, but only the provider inquiry seam is public:

Task<BaleTransaction> InquireTransactionAsync(
    string transactionId,
    CancellationToken cancellationToken)

All bot mutation operations remain package-internal.

Secret ownership

Bale:BotToken and Bale:Payments:ProviderToken are runtime configuration. BaleInvoiceDefinition never carries credentials.

Polling-owner secret boundary

Only the process with Bale:Polling:Enabled=true requires BotToken. When payments are enabled, only that polling owner requires ProviderToken. Other processes may use checkout-link/token helpers without carrying provider credentials.

Same-batch pre_checkout_query updates are started concurrently to protect Bale's provider deadline. A provider transaction returned as pending by inquireTransaction is retried by preserving the update offset.