StillDeep CartGet started

StillDeep SDK — Generate a POSClient in any language

Generate a StillDeep client in any gRPC language from the .proto files.

The .proto contracts are public. This guide explains how to generate a client and run a sale.

Overview

Every POS UI client talks to POSIntelligenceSvc over gRPC HTTP/2 on localhost:50051 (default). A sale uses these services:

Service Description .proto
UserService employee sign-in (Authenticate) user.proto
ShiftService open, read, pause, close the shift shift.proto
SalesService cart, payment, finalization sales.proto
CatalogService products, categories, taxes catalog.proto
MemberService members, memberships, wallets member.proto
DeviceService printers, scanners, terminals device.proto
EventService real-time stream of sale events events.proto

DeviceService and EventService are declared in the contract but not served by the current POSIntelligenceSvc: calls return UNIMPLEMENTED.

All services share the types in common.proto (Money, Quantity, Percentage, Pagination, ...). sales.proto imports receipt.proto, and events.proto imports sales.proto and device.proto: generate them together.

Conventions

  • Package stilldeep.v1. A V2 would be a separate package (no breaking change in V1).
  • Money: Money { int64 cents; string currency_code; }. Never double / float.
  • Percentages: Percentage { int64 basis_points; }, 1 basis point = 1/1,000,000.
  • Quantities: Quantity { int64 milli_units; }, 1 unit = 1000 (1500 = 1.5).
  • Timestamps: google.protobuf.Timestamp (UTC).
  • Ids are opaque strings returned by earlier calls. Never hardcode them; take the post id from your configuration.
  • Errors: standard gRPC status codes, with ErrorDetail in details[] when present.

Call sequence

Every call after OpenShift should carry the open shift id as gRPC metadata x-shift-id: <shift_id>. The server rejects a sensitive RPC without it (UNAUTHENTICATED) or with a shift that is not the open shift of this post (PERMISSION_DENIED).

Step RPC Required Notes
1 UserService.Authenticate yes post_id (from configuration), mode = AUTH_MODE_PASSWORD, login, password. Keep user.user_id. If must_change_password is true, call UserService.ChangePassword first.
2 ShiftService.GetCurrentShift optional post_id. Returns the open or paused Shift, or NOT_FOUND.
3 ShiftService.OpenShift yes, if step 2 returned NOT_FOUND post_id, user_id, opening_cash (Money, 0 cents allowed), idempotency_key. Keep shift.shift_id.
4 SalesService.CreateCart yes post_id, idempotency_key. cashier_user_id optional (defaults to the shift's employee). Keep cart.cart_id.
5 SalesService.AddItem yes, once per item cart_id, one of product_id / sku / barcode, quantity (Quantity, defaults to 1000 = 1 unit), idempotency_key.
6 SalesService.BeginPayment optional cart_id. Moves the cart to checkout. If CartResponse.question is set, replay with answers[question.code].
7 SalesService.SelectPaymentMethod optional cart_id, method_code. Begins payment if needed.
8 SalesService.ProcessPayment yes cart_id, method_code, amount (Money), idempotency_key. Selects the method and begins payment if not done. Repeat for split payments until cart.remaining_due.cents is 0. On PAYMENT_STATUS_DECLINED / PAYMENT_STATUS_FAILED, follow refusal_guide.
9 SalesService.FinalizeTransaction yes cart_id, idempotency_key. Returns transaction with transaction_id and receipt_number.

Payment method codes come from ConfigService.GetPostConfig (config.proto, payment_methods[].code). The client never sends totals: read them from CartResponse.cart (grand_total, remaining_due).

idempotency_key: a new UUID per logical operation, reused when retrying that same operation.

Get the .proto files

StillDeep's code is private; the client contract is public and versioned. The official website publishes the .proto files (stilldeep.v1, all except pos_proxy.proto, reserved for posts and Server.Service) in one archive: /downloads/stilldeep-contracts.zip. .NET clients use the StillDeep.Intelligence.Contracts NuGet package.

curl -fsSLO https://<site-address>/downloads/stilldeep-contracts.zip
unzip stilldeep-contracts.zip && cp -r stilldeep-contracts/protos ./protos

Guides per language

Language Guide
TypeScript / Node.js typescript.md
Python 3 python.md
Go go.md
.NET use the StillDeep.Intelligence.Contracts NuGet package directly

Other languages supported by official gRPC (Java, Kotlin, C++, Rust, Ruby, PHP, Dart, Swift) follow the same pattern: protoc --proto_path=./protos --<lang>_out=./generated protos/*.proto.

Versioning

  • No breaking change in V1. New fields are added as proto3 optional.
  • A field is never removed before 2 major versions in deprecated state.
  • A breaking change goes to a separate stilldeep.v2.* package.

See the generated gRPC reference for every service, message and call metadata.