askrobots / dbbasic-object-server
Public
Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.
danq9
signup: the person chooses the password and name on the confirm page
83c7aa6
2 weeks, 5 days ago
History
dbbasic-package.json · 10.1 KB · 74 lines
| 1 | { |
| 2 | "id": "app-shop", |
| 3 | "name": "Shop", |
| 4 | "version": "0.7.0", |
| 5 | "description": "The missing doorway. Every piece a storefront connects to was already built -- products with prices, stock with books-aware moves, orders with lines and totals, Stripe checkout with a verified webhook, payment to invoice status to journal -- and none of it could be reached by somebody who just wanted to buy something. This package is the basket and the counter. A cart is NOT a draft order (an order is a commitment with a number and a books consequence; a basket is a browsing artefact that usually gets abandoned, and mixing them makes 'how many orders did we take?' unanswerable), it is keyed by a session token rather than an account (requiring signup before purchase is the biggest conversion loss in small-business retail), the price is stamped when a thing goes in and the DISAGREEMENT is surfaced at checkout rather than silently resolved either way, and stock is checked at checkout but moved only when money arrives -- decrementing on checkout would turn every abandoned payment into a phantom sale. The oversell race that leaves is real, documented rather than pretended away, and accepted at this scale because it surfaces at the stock move where it is visible and refundable. What makes this worth having is not the cart, which everybody has: it is that the sale posts itself. Stock moves, the invoice settles and the journal entry lands with no export, no CSV and nobody re-typing anything. Checkout now also raises that invoice and hands back the pay link in the same response: an order with no invoice gives the buyer nothing to pay, and a shopper who has just committed should not have to wait for an email to find the door. The invoice is issued 'sent', never 'draft' -- checkout IS the issuing act, and a draft would mean somebody in the back office must press a button before the person standing at the counter can hand over money. If the invoice cannot be raised the order still stands and says why; losing a sale to an invoicing hiccup is the expensive failure, and an unbilled order is visible and re-raisable. Two things a shop cannot be without now work: the basket survives leaving the page, and a product has somewhere to be read about. The basket was being minted fresh on every single visit because routed objects were never handed the request's cookies at all -- the browser sent `cart` faithfully and the platform dropped it on the floor, so the fix belongs in the server and not in this package: site objects now receive every cookie EXCEPT the identity session, which is not data but a credential, and may set exactly one response header, `set_cookie`, because a page has a real need to remember a basket and no business rewriting the server's CORS, redirect or caching posture. The product page at /shop/{product_id} is the same shop wearing a different view: full description, availability where stock is actually counted, silence where it is not, and an add form that posts to /shop like every other one, so there is one path into a basket and not two to keep in step. A withdrawn product and a mistyped id answer identically -- a friendly 404 in the same shell -- because a public page that distinguished them would be an oracle for which product ids exist. The shop now charges sales tax and postage, which it did not, and that was both a compliance problem and a straight money leak -- every parcel went out with the delivery paid by the seller. Tax and shipping are CHECKOUT MATH, not a reporting layer bolted on afterwards: retrofitting tax later means restating invoices that have already been sent to customers, which is the one repair a small business cannot make quietly. So v1 is deliberately honest rather than clever -- one flat `shop.tax_rate_bps` (0 = this shop owes none, a real answer), one `shop.tax_shipping` flag because jurisdictions genuinely disagree about whether delivery is taxable, one `shop.shipping_flat_cents` and one `shop.shipping_free_over_cents`. A flat rate admits to being a flat rate; a fake calculated one would not, and a real carrier quote needs an address, a weight and a connector that do not exist yet. The free-over threshold is in v1 rather than deferred because it is the one discount every small shop actually runs, and the page SAYS 'Free shipping' when it is earned -- a silent 0.00 reads as a shop that forgot to charge rather than one that gave the shopper something. The arithmetic lives in exactly one fold, object_cart.checkout_totals, which the order, the invoice, the preview and the basket footer all restate and none of them recompute: money added up twice is money that disagrees with itself eventually, and the disagreement always surfaces as a customer holding an invoice whose lines do not come to its total. Tax rounds half-up ONCE on the taxable base rather than per line, because tax is owed on a sale and not on each row of it -- four fifty-cent lines at 5% are 10c, not the 12c that four separately-rounded lines come to. Postage is an invoice LINE and tax is the invoice's tax_cents field: the line so a customer can see what delivery cost instead of finding it welded into a total they cannot check, and the field because invoices already have one that means exactly this, and giving the same money two homes is how totals rot. A shop that has configured none of it produces byte-identical invoices to the version before this one, because absent configuration must read as 'this shop does not do that' and never as a broken tax line. 0.5.0 is the merchandising layer, and every hard part of it was decided in app-catalog rather than here: a variant IS a product, so this package's basket, checkout, invoice and fulfillment path did not change one line to support sizes and colours -- they were already keyed on product_id, which is the entire argument for the model. What DID change is the page. The index collapses children under one parent card, because a grid showing Small, Medium and Large as three tiles is a grid nobody can read: the shopper is looking for a tote bag, not for the medium. It groups cards under flat category headings in alphabetical order and puts the uncategorised LAST under 'Everything else' rather than hiding them -- a product nobody got round to filing is still stock somebody paid for, and a shop that dropped it off the page would be losing sales it could not see it was losing. A shop that has categorised nothing gets exactly the ungrouped grid it had before, because it is not a shop with one category, it is a shop that does not use them. The product page renders a picker whose radios post the CHILD's product_id into the same add form every card uses, so there is still one path into a basket; out-of-stock variants are SHOWN and disabled rather than hidden, because hiding the medium is how a shopper concludes this shop does not sell their size and goes to one that does; and nothing is pre-selected, because a default that quietly ships the small is a wrong parcel, a return and a refund. action_cart refuses to add a parent that has variants and no price of its own -- it is a display heading, not a thing that can be picked -- and the refusal NAMES the options, in a sentence for the shopper and as a list of ids for an API client, because a 'no' that does not say what to do instead is a lost sale. Product images are a file id and a placeholder: the catalogue points at /api/files/{id} and the card draws a neutral block when there is no photograph, because a text-only shop is not a shop but a broken-image icon is worse than an honest blank. Checkout gains two optional fields, special instructions and a gift message, stamped on the cart and on the ORDER the moment orders declares the columns (the same _has_field posture shipping_cents already uses), and reported as carried-on-cart-only when it does not -- the packer reads the order, and a note nobody prints is a note the shopper paid for and never got. There is no gift flag and there does not need to be one: the packing slip carries no prices by construction, so every parcel is already gift-safe, and a flag somebody forgets to tick is exactly how a present arrives with the amount paid stapled to it. 0.6.0: action_checkout mints the ORDER's tracking token alongside the invoice's pay token and returns it as track_path, for the same reason the pay link is returned -- the shopper is standing there, and this response plus the confirmation email are the only two places a guest will ever be handed a way back to their own order. Minted synchronously rather than left to app-orders' system_order_portal_link, which is a post-commit reaction and therefore cannot put anything in this response; the handler skips an order that already has a token, so the two never fight. Written through the same _has_field check shipping_cents and the merchandising notes already use, so a shop still on orders v4 loses the link rather than the order, and with preserve_read_only because portal_token is schema read_only -- a capability URL a client could choose is not a capability.", |
| 6 | "compatibility": { |
| 7 | "dbbasic_object_server": ">=0.1.0" |
| 8 | }, |
| 9 | "dependencies": [ |
| 10 | "app-catalog", |
| 11 | "app-orders", |
| 12 | "app-invoices", |
| 13 | "app-shipping" |
| 14 | ], |
| 15 | "objects": [ |
| 16 | { |
| 17 | "id": "action_cart", |
| 18 | "path": "objects/action/cart.py" |
| 19 | }, |
| 20 | { |
| 21 | "id": "action_checkout", |
| 22 | "path": "objects/action/checkout.py" |
| 23 | }, |
| 24 | { |
| 25 | "id": "system_shop_fulfillment", |
| 26 | "path": "objects/system/shop_fulfillment.py" |
| 27 | }, |
| 28 | { |
| 29 | "id": "site_shop", |
| 30 | "path": "objects/site/shop.py" |
| 31 | } |
| 32 | ], |
| 33 | "schemas": [ |
| 34 | { |
| 35 | "collection": "carts", |
| 36 | "path": "schemas/carts.json" |
| 37 | }, |
| 38 | { |
| 39 | "collection": "cart_items", |
| 40 | "path": "schemas/cart_items.json" |
| 41 | } |
| 42 | ], |
| 43 | "permissions": [ |
| 44 | { |
| 45 | "path": "permissions/rules.json" |
| 46 | } |
| 47 | ], |
| 48 | "seed": [ |
| 49 | { |
| 50 | "collection": "carts", |
| 51 | "path": "seed/carts.tsv" |
| 52 | }, |
| 53 | { |
| 54 | "collection": "cart_items", |
| 55 | "path": "seed/cart_items.tsv" |
| 56 | }, |
| 57 | { |
| 58 | "collection": "site_routes", |
| 59 | "path": "seed/site_routes.tsv" |
| 60 | } |
| 61 | ], |
| 62 | "migrations": [], |
| 63 | "nav": [ |
| 64 | { |
| 65 | "id": "shop", |
| 66 | "label": "Shop", |
| 67 | "path": "/shop", |
| 68 | "blurb": "Browse what is for sale and buy it", |
| 69 | "surface": "public", |
| 70 | "group": "Commerce", |
| 71 | "order": 400 |
| 72 | } |
| 73 | ] |
| 74 | } |