> Documentation index: https://stilldeeppos.com/llms.txt

# Build a register screen on StillDeep

> From the stilldeep.v1 .proto files to a first finalized sale: generate the client, open a shift, fill a cart, take a payment and listen to events.

Source: https://stilldeeppos.com/docs/build-a-client

## With a coding agent

Claude Code, Codex, Cursor and other agents read this documentation as is:

- [llms.txt](/llms.txt) lists every page in Markdown; add `.md` to any address for its Markdown version.
- The read-only MCP server at `/mcp` searches and reads the docs and the contract (`search_docs`, `read_page`, `list_pages`, `get_contract`). Claude Code: `claude mcp add --transport http stilldeep <site>/mcp`.
- The skill `/.well-known/agent-skills/stilldeep-pos-screen/SKILL.md` gives the agent the steps below.
- Each `.proto` file is served in plain text at `/contracts/<file>.proto`.

Describe your business and the screen you want; the agent follows the steps below and the engine checks every sale.

## Get the contract

The `.proto` files of the `stilldeep.v1` package describe every service of the register: sales, catalog, members, cards, devices, events, receipts, reservations, appointments, rentals, inventory, shifts and configuration. .NET clients use the `StillDeep.Intelligence.Contracts` package; other languages generate their code from the same files.

## Generate the client

Use the gRPC tools of your language:

- **TypeScript and Node.js:** `@grpc/grpc-js` with `ts-proto` or `protoc-gen-ts`.
- **Python:** `grpcio-tools`.
- **Go:** `protoc-gen-go` and `protoc-gen-go-grpc`.
- **.NET, Java, Kotlin, Rust, C++:** the official gRPC generators.

Step-by-step guides with commands are in the reference (French): [generate a client](/fr/docs/reference/sdk), [TypeScript client](/fr/docs/reference/sdk/typescript), [Python client](/fr/docs/reference/sdk/python), [Go client](/fr/docs/reference/sdk/go).

## Connect to the register

The register engine listens on the register itself (HTTP/2, port 50051 by default). The screen never talks to the business server: the register handles the proxy, the outbox and offline mode for it.

## Make a first sale
### Open a shift
Sign the employee in by badge or password and open a shift. Each following call carries the shift identifier.

### Open a cart and add items
Add items by barcode scan or catalog search, with quantities (decimals for weighed goods). Attach a customer if the sale needs one.

### Take the payment
List the enabled payment methods, choose one, tender the amount. Several payments can share a sale.

### Finalize
Finalize the sale: the engine writes it locally, sends it through the outbox and returns the receipt to print.

## Handle refusals

Every refusal comes as a `google.rpc.Status` with a stable code (for example `shift_paused` or `stock_short`). Show a message to the cashier from the code; never retry blindly. The server re-checks every sale, so a refusal can come after the screen thought everything was fine.

## Listen to events

The event service streams what happens on the register: availability of limited resources, chat messages, server decisions. A screen subscribes once and updates itself.

## Start from an example

The example clients cover a simple store, a shop, a cinema, a ticket office, a self-service kiosk, a pet shop with grooming, and web clients in Node.js and Go. Start from the one closest to your business and replace its screen.

## Contract rules

- Version 1 never receives a breaking change; a version 2 would be a separate package.
- Money as `int64` cents, percentages as basis points, quantities in thousandths.
- Timestamps in UTC.
- Never trust the screen: the engine and the server validate everything, so keep business rules out of the client.