Saizeriya Tool Suite

repository·main·Indexed 43 days ago

https://github.com/pnsk-lab/saizeriya

A suite of tools for interacting with Saizeriya services, featuring saizeriya.js (a TypeScript client library and CLI), a compatible server, and Betterzeriya, a high-performance client application. It supports browser mode via Playwright for DOM interactions and provides specialized 'skills' for AI agent integration.

Tokens
20.2K
Snippets
71
Records
96
Agent score
56%

What's inside Saizeriya

  1. Understand the Saizeriya Order Protocol scope and constraints

    main

    The Saizeriya Order Protocol defines a compatibility layer for a table-based ordering system. It exposes the same application under /saizeriya2/ and /saizeriya3/ paths.

    Core Workflow:

    1. A QR URL or direct URL resolves to a table session.
    2. The first access displays the entry page.
    3. Navigation is form-based: the client submits a form#frm_ctrl via POST to ./?{urlId}, setting hidden fields like proc and ctrl.
    4. Ajax endpoints under ./src/cmd/*.php handle status checks, item lookups, and staff calls.
    5. Submitting an order moves cart lines to submittedOrders, clears the cart, and renders the call page.

    Clean-Room Implementation Rules: When implementing a compatible server, you may preserve URL paths, HTTP methods, form/JSON field names, selector names (used as API hooks), page state names, and numeric limits.

    You must not copy the original source code, exact UI strings, HTML structure (except required hooks), CSS, images, icons, fonts, audio, or proprietary branding. Use semantic message keys (e.g., last_order_closed, empty_cart) instead of reproducing historical wording.

  2. Understand the Saizeriya Order Protocol Page Behavior

    main

    The Saizeriya Order Protocol defines the client-side behavior and required DOM hooks for various pages in the ordering flow. The system uses a state-driven approach where page transitions are triggered by POSTing specific proc (procedure) and ctrl (control) values.

    Key pages include:

    • entry: The initial landing page for a new table session.
    • top: The main landing/status page.
    • number: Handles party size (people count) selection.
    • menu: The item selection and lookup interface.
    • main: The shopping cart management page.
    • history: Displays previously submitted orders with reorder capabilities.
    • call: Interface for requesting staff assistance.
    • account: Final order review before receipt.
    • receipt: The final checkout/barcode display page.
  3. Manage the Shopping Cart on the `main` page

    main

    The main page displays the current cart and allows for quantity adjustments or item removal.

    Row Removal and Quantity

    • Remove Row: Clicking .del triggers a confirmation dialog. Upon confirmation, the row is removed and totals are recalculated.
    • Adjust Quantity:
      • .minus decrements the quantity (minimum 0 for .zero inputs, otherwise 1).
      • .plus increments the quantity up to 99.

    Submission Flow

    1. Add More: .command #menu checks last-order state. If clear, submits proc=menu.
    2. Submit Order: .command #order sums quantities and checks if the cart is empty. If valid, it shows a confirmation dialog.
    3. Finalize: Upon confirmation, it submits proc=order.

    Server Side Processing: On POST with proc=order, the server reads the following arrays:

    • item[id][]: Item IDs
    • item[count][]: Quantities
    • item[reorder][]: Reorder flags
    • item[mod_id][]: Modifier IDs
    • item[mod_count][]: Modifier quantities`
  4. Use the saizeriya.js client library and CLI

    main

    The saizeriya.js package provides a JS/TS client library and a CLI tool for interacting with the Saizeriya server.

    Install the library: bun add saizeriya.js

    Use the CLI: You can run the CLI via bunx or install it globally.

    bun add saizeriya.js
    
    # Run via bunx
    bunx saizeriya.js
    
    # Or install globally
    bun add -g saizeriya.js
    saizeriya --help
  5. Recreate the betterzeriya project configuration

    main

    To replicate the specific configuration used in this project (minimal template, TypeScript, Tailwind CSS with no plugins, and betterzeriya dependency), use the following bun x command. Note that this uses bun as the package manager and sv@0.15.2 specifically.

    bun x sv@0.15.2 create --template minimal --types ts --add tailwindcss="plugins:none" --install bun betterzeriya
  6. Deploy Betterzeriya to Cloudflare Workers

    main

    To deploy the Betterzeriya client to Cloudflare Workers, set the CLOUDFLARE=1 environment variable during the build process and use Wrangler to deploy.

    bun i
    cd apps/betterzeriya
    CLOUDFLARE=1 bun run build
    wrangler deploy
  7. HTML Rewrite Requirements for Saizeriya Server

    main

    When the server returns a page, it must perform specific HTML rewrites to ensure compatibility with the protocol. This includes updating action URLs, data attributes, and specific DOM element values.

    Required Rewrites:

    1. Actions: Replace action="./?..." with action="./?{nextId}".
    2. Data Attributes:
      • Replace data-shop="..." with the current shopId.
      • Replace data-tbl="..." with the current tableId.
    3. DOM Values:
      • Set #shop-id to shopId.
      • Set #table-no to tableId.
      • Set #session-id to sessionId.
      • Set #number to peopleCount.
      • Set hidden name="token" to token.
    4. Page-Specific Logic:
      • entry page: Expose current table ID and initial party-size in #number, keep cart empty, and render as a start-order page.
      • history / account pages: Replace submitted-order rows and totals.
      • receipt page: Replace table ID and checkout code.
  8. Saizeriya Order Flow and Request Mapping

    main

    The following table defines the expected flow of operations, the AJAX calls triggered, the submitted form fields, and the resulting page for each step in the ordering process.

    OriginOperationAjaxSubmitted fieldsResult page
    QRFirst accessnonenoneentry
    entryStart orderingcheck_lastorder, check_midnightproc=numbernumber
    entryChange party sizecheck_lastorderproc=number, ctrl=forcednumber
    topStart orderingcheck_lastorder, check_midnightproc=numbernumber
    topChange party sizecheck_lastorderproc=number, ctrl=forcednumber
    numberPreset/Manual sizenoneproc=menu, ctrl=number, number=nmenu
    menuConfirm itemget_item, (opt) put_alcoholproc=main, ctrl=add, code, amount, mod_code, mod_amountmain
    mainAdd morecheck_lastorderproc=menumenu
    mainSubmit cartcheck_lastorderproc=order, item[...][]call
    footerAdd morecheck_lastorderproc=menumenu
    footerOpen cartcheck_lastorderproc=mainmain
    footerOpen historynoneproc=historyhistory
    footerOpen call pagenoneproc=callcall
    footerOpen account pagenoneproc=accountaccount
    historyReorder(opt) check_lastorderproc=menu, ctrl=reorder, code={id}menu
    callStaff/Service calltbl_callproc=toptop
    accountProceed to receiptnoneproc=receiptreceipt
    headerReturn topnoneproc=toptop

    Note on Last-Order State: When the last-order state is closed, order-entry paths must submit proc=account and ctrl=clear.

  9. Extract QR URL from a photo using qr-scanner-cli

    main

    If you have a photo of a QR code instead of the URL string, you can use qr-scanner-cli to extract the text. Use the --clear flag to ensure only the raw QR value is printed, which can then be passed to the saizeriya.js start command.

    npx -y qr-scanner-cli /path/to/qr-photo.jpg --clear
  10. Deploy Betterzeriya to Vercel

    main

    Betterzeriya can be deployed to Vercel. The repository includes a vercel.json configured to use Bun and a Vercel adapter.

    Manual Build: bun run betterzeriya:build:vercel

    CLI Deployment: Use the Vercel CLI to deploy.

    Git Deployment: Import the repository into Vercel. Ensure the project root is set to the repository root. The build command is automatically handled by vercel.json.

    # Build for Vercel
    bun i
    bun run betterzeriya:build:vercel
    
    # Deploy via Vercel CLI
    bunx vercel
    bunx vercel --prod