EncoreBilisim.VisionSecurity 2.0.0

Encore Vision Security

Client library for the SaiGroups Vision Security API (.NET 8, trim/AOT compatible). One process = one self-checkout lane.

dotnet add package EncoreBilisim.VisionSecurity

Setup

using Encore.VisionSecurity.Common.Configuration;
using Encore.VisionSecurity.Common.Primitives;

services
    .AddVisionSecurity(options =>
    {
        options.BaseAddress = new Uri("http://vision-security.store.local:8080");
        options.Lane = Lane.Parse(3);
        options.StoreNumber = StoreNumber.Parse("1042"); // optional
    })
    .AddEventQueue()                                      // POS -> AI, ordered, non-blocking
    .AddFeed<MyAlertHandler, MyNotificationHandler>();    // AI -> POS, polled in the background

Which entry point

Sending events

using Encore.VisionSecurity.Contracts;
using Encore.VisionSecurity.EventQueue;

var queue = provider.GetRequiredService<IVisionSecurityEventQueue>();

queue.TxStart(txId);                                   // every call returns immediately
queue.Scan(txId, Barcode.Parse("8690504010012"), ScanType.Product, ScanMode.Regular, mobileScan: false);
queue.ScanInfo(txId, Barcode.Parse("8690504010012"), "Milk 1L", 32.50m, quantity: 1, weight: 0m, voided: false, scanType: ScanInfoScanType.Product);
queue.UiState(txId, UiState.Payment);
queue.TxEnd(txId, EndType.Complete);

The return value is the enqueue result: Failure(ValidationError) means the request was invalid (rejected immediately), the queue is full, or the queue is stopped. Send outcomes are reported through ILogger<VisionSecurityEventQueue> and the encore.visionsecurity.eventqueue.* metrics. The queue is in-memory: pending events are lost if the process dies.

TxId is yours to supply — derive it from the POS receipt identity so logs on both sides correlate. Only one transaction may be open per lane; the queue does not enforce this.

Handling alerts

public sealed class MyAlertHandler : IAlertHandler
{
    public Task<VisionSecurityResult<AlertFeedbackType>> HandleAsync(AlertResponse alert, CancellationToken ct)
        => Task.FromResult(VisionSecurityResult<AlertFeedbackType>.Success(AlertFeedbackType.NoAction));
}

Never throw from a handler; return a Failure instead. The feed still sends NO_FEEDBACK if a handler fails, so the AI side never waits on a lost alert.

Errors

Nothing throws after construction. Every operation returns VisionSecurityResult / VisionSecurityResult<T>; inspect with TryGetValue / TryGetError. Error kinds: ApiError (4xx/5xx), TransportError, TimeoutError, ParseError, ValidationError, UnknownEnumError, CancelledError, HandlerError.

Full documentation (architecture, configuration, feed flows, domain rules, library invariants) lives in the repository: README.md, docs/kurallar.md, docs/invariants.md.