EncoreBilisim.VisionSecurity 2.1.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

For a POS integration, use VisionSecurityRuntime and its Session. A POS has its own lifecycle, often learns the lane at run time, and must keep selling when the configuration is bad. The runtime supports all three. For an app on the Generic Host, the DI path registers the same parts.

Recommended for a POS: VisionSecurityRuntime

using Encore.VisionSecurity.Runtime;

var created = VisionSecurityRuntime.TryCreate(options, loggerFactory);   // never throws
if (created.TryGetError(out var error)) { /* log it; the POS keeps selling */ }
else if (created.TryGetValue(out var runtime))
{
    runtime.StartFeed(new MyAlertHandler(runtime.Session, runtime.MediaResolver), new MyNotificationHandler());
    // ...
    await runtime.DisposeAsync();   // stops the feed, sends pending events, releases HTTP
}

Create the runtime when the lane is known (for example, after the POS database loads). If the lane or the address changes, dispose the runtime and create a new one.

With the Generic Host (DI)

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

.AddEventQueue() also registers IVisionSecuritySession. AddVisionSecurity also registers IAlertMediaResolver.

Which entry point

Sending events

using Encore.VisionSecurity.Contracts;
using Encore.VisionSecurity.Session;

session.Start(txId);                                   // every call returns immediately
session.Scan(txId, Barcode.Parse("8690504010012"), ScanType.Product, ScanMode.Regular, mobileScan: false);
session.ScanInfo(txId, Barcode.Parse("8690504010012"), "Milk 1L", 32.50m, quantity: 1, weight: 0m, voided: false, scanType: ScanInfoScanType.Product);
session.UiState(UiState.Payment);
session.End(EndType.Complete);                         // closes the open transaction

The session keeps one open transaction per lane:

• Scan and ScanInfo send a tx-start first if the transaction is not open.
• If transaction A is open and B starts, the session sends tx-end VOID for A and logs a warning.
• End, Operator, UiState and WeightScaleInfo return Failure if no transaction is open.
• UiState does not send the same state two times in a row.

Do not send events through the queue and the session for the same lane.

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 that logs on both sides correlate.

Handling alerts

public sealed class MyAlertHandler(IVisionSecuritySession session, IAlertMediaResolver media) : IAlertHandler
{
    public async Task<VisionSecurityResult<AlertFeedbackType>> HandleAsync(AlertResponse alert, CancellationToken ct)
    {
        if (!session.IsOpen(alert.TxId))   // the sale ended; your policy decides
            return VisionSecurityResult<AlertFeedbackType>.Success(AlertFeedbackType.For(alert.PresentationType, AlertOutcome.NotShown));

        var image = media.ResolveAsync(alert, ct);              // gif or gifUrl -> bytes, with size and time limits
        AlertOutcome outcome = await ShowOnScreenAsync(alert, image, ct);
        return VisionSecurityResult<AlertFeedbackType>.Success(AlertFeedbackType.For(alert.PresentationType, outcome));
    }
}

AlertFeedbackType.For maps the screen outcome (Rescan, NoAction, TimedOut, NotShown) to the contract value. NUDGE_* values are used only for SOFT_NUDGE. NO_FEEDBACK is used only for NotShown.

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, or compose with Match / Map / Bind. 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.