Smartpress

Add the current session configuration to the cart. Calls the add-to-cart endpoint which translates the session's selections into the format required by the external cart service. On success, returns a **clientKey** (anonymous cart identifier) and a **cartLink** (shareable URL to view the cart). These are also persisted on the session and will appear in all subsequent session responses. If neither clientKey nor userId is provided, a new anonymous cart is created. Repeat calls add the item again (no idempotency). **Files are attached automatically.** If the session was linked to a file session (via create_file_session with productConfigSessionId, link_file_session, or create_config_session called with a fileSessionId), the backend resolves the file session from the configuration session — you do NOT need to pass fileSessionId. Only pass fileSessionId to override that durable link with a specific file session. The cartLink opens the cart on the Smartpress website, where the customer reviews the order and checks out.

Read a file already uploaded to a file session: its finished size, page count and orientation. Returns facts in a few seconds, not a reading of the file's content (no text, colors or design classification). The finished size is the file's trim box when it has one. Without one, a page that is a standard product size plus standard bleed (0.125 in a side) is read as that size with bleed; otherwise the page is the size. recommendedSelections carries that finished size (left out when it can't be told), ready to compare with a configuration. Works on PDF, PNG and JPEG (an image needs a resolution to have a size). Pass the result, or just the fileSessionId, to recommend_products to find products that print this size.

Copy a file session — files, approved proofs, and completed check results — into a NEW file session, leaving the original and its configuration join untouched. Optionally link the CLONE to a configuration session in the same call. Use this instead of link_file_session whenever the source file session is one a page is currently displaying: linking would MOVE the single join pointer and strip the files off that page, while cloning gives the target configuration its own copy. Typical case: the customer is on a product page and selects a recommended candidate — clone the page's file session and link the clone to the candidate's configuration session. Returns the new **fileSessionId** (the clone), the sourceFileSessionId, and fileCount.

Create a product configuration: the customer's order for one product, with its live price. **Name the options:** pass productId, quantity, and `options` with the customer's choices by name, e.g. {"productId": "SLS_12", "quantity": 500, "options": {"paper": "120# Cover Coated Gloss", "backInk": "None", "finishing": {"rounded corners": "1/4 inch"}}}. Names are matched to the product's choices; you don't need get_product_config first. Every choice left out keeps the product's default. The result leads with productConfigSessionId and a one-line summary, then `chosen` (every choice by name), `applied`, and `notApplied`: options that matched nothing or more than one choice, or that need an answer, each with the reason and the valid names. Ask the customer about each notApplied entry, then fix it with update_config_session. It also has quote, selections, validation (with selectionChangeMessages) and configurationUrl (a link to the configuration on the storefront). Provide either a productId (to start from product defaults) or a productConfigId (to bootstrap from an existing blueprint or configuration). Once the order is right, use add_to_cart. **Exact ids instead of names (selections):** the rest of this description covers `selections`, which takes the product's ids from get_product_config. Use names unless you already hold the ids. **IMPORTANT — selections structure:** The selections object must use nested objects that mirror the structure of the selections field in the response. Flat keys are silently ignored (no error returned). Always verify the response's selections match what you requested. Known selection keys and their required structure: - **Size** — nested sizeSelection object: {"sizeSelection": {"width": 6, "height": 9, "presetDimensionsId": 15}} For custom dimensions, omit presetDimensionsId or set it to null. - **Quantity & Pages** — flat top-level keys (these DO work as simple values): {"quantity": 1200, "pages": 20} - **Paper** — nested paperSelection object: {"paperSelection": {"pressSheetTypeId": 78, "pressSheetWeightId": 5, "coverPressSheetTypeId": 78, "coverPressSheetWeightId": 3}} - **Ink** — nested objects per ink position: {"coverSide1Ink": {"id": 146}, "coverSide2Ink": {"id": 146}, "interiorSide1AndSide2Ink": {"id": 146}} - **Proof** — nested proofSelection: {"proofSelection": {"proofId": 1}} - **Turnaround** — nested turnTimeSelection: {"turnTimeSelection": {"turnTimeId": 13}} - **Operations** — nested operationSelections with operation name keys: {"operationSelections": {"laminatingCoverOnly": {"operationId": 81, "itemId": 2323}}} An entry accepts ONLY operationId, itemId, operationName, itemName, followUpQuestionAnswer, followUpQuestion and followUpQuestionDataType — any other key is rejected with a validation error. - **Follow-up answers** — when an operation in availableOptions has a followUpQuestion (e.g. shrink-wrapping "How many pieces per bundle do you want?", drilling "Please note placement."), put the customer's answer in followUpQuestionAnswer on the SAME entry, as a string even for integer questions: {"operationSelections": {"shrinkwrappingService": {"operationId": 14, "itemId": 42, "followUpQuestionAnswer": "20"}}} Each update replaces the whole entry, so resend followUpQuestionAnswer whenever you resend that operation. Ask the customer if they chose the operation without answering its question. **General rule:** Look at the selections object in the response — use the same key names and nesting structure when sending updates. Invalid or unrecognized keys are silently ignored.

Run (enqueue) a file check for a file in a file session: the proof service preflights the file against the product's print specs and produces a report of errors/warnings. Unlike create_proof it makes NO proof file — the report is the whole result, and there is nothing to approve. Use it when the session is NOT proofable but isFileCheckAvailable is true (read get_file_session_proofs first). When the session is proofable, prefer create_proof. Returns { checkId, ... } once enqueued. A check takes tens of seconds — after calling this, poll get_file_session_proofs until the `checks` entry whose `id` equals checkId reaches status COMPLETED, then report its errors/warnings. Refuses (tool error, nothing queued) when the session or file isn't eligible for a file check — do not retry a refusal. ONLY call this on the customer's explicit go-ahead (a run-file-check quick-action click or a clear yes) — never unprompted. The file must already be uploaded to the session.

Create a file session for uploading proof/artwork files. Returns a **fileSessionId**. Once it is joined to a configuration session, add_to_cart attaches its files without you passing the ID. **Two workflows:** - **File-first** (no product chosen yet): call with no arguments. A placeholder product is used. When the product is chosen, you MUST pass this fileSessionId to create_config_session (or call link_file_session): nothing joins them otherwise, and the configuration has no files. The real product is then reconciled automatically. - **Config-first** (configuration session already exists): pass productConfigSessionId (and ideally the productId). The file session is created and linked immediately, so add_to_cart needs only the configuration sessionId. Once joined, the link is persisted server-side, so later tools (add_to_cart) need only the configuration sessionId.

Generate (enqueue) a preflight proof for a file in a file session: the proof service checks the file against the product's print specs and produces a proof with any errors/warnings. Returns { proofId, sessionId } once enqueued. Proof generation takes tens of seconds — after calling this, poll get_file_session_proofs until the proof whose `id` equals proofId reaches status COMPLETED, then report its errors/warnings. **Artwork orientation (checked before every proof).** If the artwork is turned against the configured size (e.g. 6 x 4 landscape art on a 4 x 6 portrait postcard) and swapping width and height fits it, this tool CHANGES THE CONFIGURED SIZE to match the artwork before proofing. The result then carries `orientation`: - `changedNow` (on the swap actions) is true only when THIS call changed the size. Announce a size change to the customer ONLY when `changedNow` is true, never otherwise. - `action: "swapped"` (`changedNow: true`): the size was changed (`from` → `to`, plus the new `price`) and the proof uses the new size. You MUST tell the customer the size changed, and the price if it changed, in your next message. - `action: "swapped-not-synced"` (`changedNow: true`): this call changed the size (`from` → `to`) but NO proof was started yet (no proofId) because the file service hasn't picked it up. Tell the customer the size changed, then call create_proof again in a few seconds. - `action: "swapped-earlier"` (`changedNow: false`): the configuration already had the size that fits the artwork (an earlier create_proof changed it, or the customer chose it); nothing was changed now and this proof uses it. Don't announce it as a new change. - `action: "warned"`: the artwork is turned but the size was NOT changed (`message` says why; `reason: "config-not-synced"` means the file service had not caught up with the configuration, so the proof may come back invalid and need re-running). The proof will show the artwork unrotated, possibly cut off, with a warning. Tell the customer before they review it; offer a corrected file or a different size. `orientation.message` states what happened in plain words. No `orientation` means the artwork already fits the size's orientation. ONLY call this on the customer's explicit go-ahead (a create-proof quick-action click or a clear yes) — never unprompted. The file must already be uploaded to the session. Read get_file_session_proofs first: a session or file with isProofable false (and no isProofableUnknown) can't be proofed, and this call refuses it.

Find Smartpress products matching a name or description. Returns matching products with their id, name, and description (plus group, link, image and a relevance score). Only products that can be configured through this assistant are returned. If nothing fits, say so and point the customer to smartpress.com rather than suggesting a product from memory. Use this to discover products by what the user is trying to print (e.g. "saddle stitch booklet", "matte business cards"). Take the "id" of the best match (e.g. "SLS_7") and pass it to create_config_session as productId to configure the product, then add_to_cart.

Read the stored file summary for a file session. Returns { analysis } where analysis is the summary analyze_file stored (page count, finished size, size without bleed, and the file-derived selections), or null when the file session carries no stored summary. Summaries stored before this tool read only sizes may also carry a classification and color palette. Use this on a fresh product-page arrival to decide whether to open with a file summary and offer to match the configuration. Absence of a summary means "no analysis → start from scratch".

Read the proof AND file-check state for a file session. Returns a compact view: - isProofable: whether the session's product/config supports proofing. With isProofableUnknown: true the service didn't report it (isProofable then reads false but isn't a refusal: create_proof still runs). - isFileCheckAvailable: whether a file check can run. A file check is a preflight report only (no proof file) and is often available when proofing is not. - files: [{ fileName, isProofable, isProofableUnknown?, isFileCheckAvailable }] per uploaded file (isProofableUnknown: neither the file nor the session reported the flag, so its false means unknown). - proofs: newest-first, each { id, fileName, type, status, approvalStatus, invalid, invalidReason, errors[], warnings[], noReport, createdAt, proofFileUrl, totalPages }. - checks: newest-first file checks, each { id, fileName, type, status, invalid, errors[], warnings[], noReport, createdAt }. `id` is the proofId / checkId the create call returned — match on it to find the job you just started (an older proof or check for the same file may still be listed). A proof or check is "ready to report" when status is COMPLETED. `invalid: true` means a later configuration change made it stale and it needs re-running — it is computed server-side; just read it. Checks carry no invalidReason (only one reason is kept per session, chosen for proofs, so it reads wrong for checks), so describe a stale check in your own words. `errors`/`warnings` are the preflight messages shown to the customer (capped for length). `noReport: true` means a COMPLETED proof or check has no preflight report (for example a proof copied from a past order), so its errors and warnings are unknown, not empty: never tell the customer it has no issues. `proofFileUrl` is a signed link to the proof PDF. For each file currently in the session, only the latest proof that is neither invalid nor failed can carry it, and only once that proof is COMPLETED. While a newer proof of that file is still running, or if the file was replaced or removed, there is no link. It stops working within 24 hours of this read, possibly sooner; read again for a fresh one. If you pass it on, use it exactly as returned: never shorten, rebuild, or guess it, or the signature breaks. `productConfigSessionId` is the configuration session this file session is linked to: the sessionId add_to_cart takes. Use this to suggest a proof (or a file check when not proofable), report issues, answer questions about them, and detect when a config change invalidated a proof or check.

Mint a short-lived presigned URL that a client (a browser, an app, or the user) can use to upload a file directly to storage, attached to a file session. Use this when the bytes are NOT on the machine running this server — e.g. the remote/hosted server, or a file the user has in a browser. (If this server also offers a tool that uploads a file from the local machine, prefer it for local files: it performs the upload for you.) **Easiest for a person:** if the response includes **uploadPageUrl**, give that link to the user. It opens a simple Smartpress upload page in their browser where they pick the file; the page uploads it directly and securely (the file never passes through the chat). **For a programmatic client:** issue a single HTTP **PUT** to **url** with the raw file bytes as the body and **no extra headers** — do not set Content-Type and do not add x-amz-* headers; everything required is already baked into the URL. The URL expires (default 15 minutes), so use it promptly. Confirm the result with list_session_files. Returns **uploadPageUrl** (when the server has a public base URL configured), the raw **url**, the assigned **sessionFileId**, the storage **key**, and **expiresAt**.

A product's menu: every choice the customer can make, by name and id, with the defaults and the starting price. Call it when the customer asks what's available, or to show choices; to configure, create_config_session takes the choices by name and doesn't need this first. - **availableOptions**: the choices by category: - **presetDimensions**: standard sizes; customDimensionsSupported and customSizeLimits for custom sizes. - **pressSheets**: papers (type, then weight, then color). - **side1Inks / side2Inks**: front and back ink (side2 "None" = blank back). - **turnaroundTypes**: turnaround times, with estimatedDeliveryDate and maxQuantity. - **operations**: finishing options keyed by camelCase name, each with its items; a followUpQuestion is asked when that option is chosen. - An option whose `disabled` is true can't be chosen with the defaults; `disabledReason` says why. - **selections**: the default choices. - **quote**: the default price. - **validation**: messages about the default choices.

Get the downloadable print templates and design guides for a Smartpress product. Returns: - **summary**: a one-line description of what this product has — paraphrase this rather than counting the arrays yourself. - **designGuides**: instructional PDFs about how to set artwork up (bleed, folding). Not tied to a size. - **templateGroups**: the print templates, in the groups the layout team defined (e.g. "Flat", "Single Fold"). `group` is omitted when a product's templates are not grouped, which is common. - Each entry has a **label** (what to call it to the customer) and **files** (format -> download URL, e.g. `{"pdf": "https://...", "idml": "https://..."}`). Use this when a customer asks for a template, a layout guide, artwork setup help, dimensions to design to, or an InDesign file. If you only know the product by name, call find_products first and pass its "id" (e.g. "SLS_7") here. Rules: - Give customers the exact URLs this tool returned. Never construct, guess, or edit a template URL. - Use the **label** verbatim when naming a template. Labels are display text written by the layout team — do NOT parse them as dimensions or assume a label matches the customer's configured size. - Only offer a format that appears in that entry's **files**. Most templates have PDF and InDesign, but some have only one, and a few are Illustrator or spreadsheets. - If a product has none, say so plainly. Many products have no templates yet — that is normal, not an error, and you must not substitute another product's template.

Retrieve the latest state of a configuration session. Returns the full ProductConfiguration response with current selections, validation messages, and available options. Use this to check session state without making changes.

Durably join a file session to a configuration session (last-write-wins). Use this when files were uploaded in one context and the configuration was created in another, or to re-link a configuration to a different file session. After linking, add_to_cart needs only the configuration sessionId — the backend resolves the file session automatically. The real productId is reconciled onto the file session from the configuration session.

List the files currently attached to a file session, including each file's name, size, type, and sessionFileId. Use this to confirm an upload landed or to show the user what is attached.

Find products that print an uploaded file. The file's finished size and page count are checked against every product you can offer: a standard size of the product first, then a custom size within its limits; products that can't print it are left out. When there are words to go on (the customer's own, passed as query, else the file's name), the products those words match come first. Returns up to 5 candidates, each with productId, productName, a rationale, a 0-1 confidence, matchSignals, and initialSelections in the configuration's shape (the size, with the standard size's id, and the page count for a booklet). When the file may include bleed and that can't be told, the candidates carry no size and a note says so: ask the customer which size they want. Pass the uploaded file's fileSessionId, or the result of analyze_file. Then create the configuration with the customer's choice: create_config_session takes initialSelections as selections and the customer's other choices by name in options.

Send the user's feedback to the Smartpress team: a problem they ran into, a suggestion, or praise. Rules: - Call this ONLY when the user asks to send feedback, report a problem, or pass on praise. Never call it on your own after an error; you may offer it. - Before calling, show the user what you'll send (type, and the message) and get their yes. - Put the user's own words in "message". Leave out payment details, passwords and anything they asked you not to share. - Pass the ids of what the conversation was working on (product, configuration, artwork, proof), and for a failed tool call its name and error, so the team can find it. Afterwards, give the user the reference (e.g. FB-3F9K). Nobody replies through this channel; for help with an order, point them to Smartpress customer support.

Record the customer's decision on a proof: APPROVED (they sign off on the proof as shown), FURTHER_REVIEW (a Smartpress expert checks the file before printing), or DECLINED. An approved proof is what prints: when the order is placed, the approved proof file goes to production and the order item is marked "User approved their instant proof through an AI assistant." Before calling this, ALL of these must be true: 1. The customer has seen the proof: you gave them its `proofFileUrl` from get_file_session_proofs (exactly as returned) or they opened it on smartpress.com. "It's in the file area" alone is not enough. 2. In the same message as the offer, you restated the product, the proof, and every preflight error and warning. 3. The customer then confirmed with an approve / expert-review action click or a clear yes to that restatement. Never call this unprompted or on an ambiguous reply. Which statuses to offer: if the proof has preflight ERRORS, or `noReport: true` (no report, so its errors are unknown), do not offer approval. Offer expert review (FURTHER_REVIEW) first, or a corrected file and a new proof. If it has only WARNINGS (or nothing), offer approval and expert review side by side. Declining is always available. The tool re-reads the session and refuses (tool error, nothing written) when the proof isn't in this file session, isn't COMPLETED, or is out of date (`invalid`); refuses APPROVED and FURTHER_REVIEW when the proof carries no `proofFileUrl` (not the current proof the customer could have opened); and refuses APPROVED when the proof has errors or no report. Don't retry a refusal; explain it and offer what it suggests. Approving or requesting review of one proof clears that status from the session's other proofs. Returns { proofId, fileSessionId, approvalStatus, approvalOrigin, productConfigSessionId, nextStep }. After APPROVED or FURTHER_REVIEW, follow `nextStep`: call add_to_cart with that productConfigSessionId and give the customer the cartLink. Do not stop at the approval.

Change a configuration: pass sessionId and only what changes, by name, e.g. {"sessionId": "...", "quantity": 1000, "options": {"turnaround": "3 Business Days", "finishing": {"coating": null}}}. The result has the same shape as create_config_session's (summary, chosen, applied, notApplied, quote, selections, validation, configurationUrl); it leaves out availableOptions: get_session_latest returns the full state, including which choices are now disabled. **Exact ids instead of names (selections):** the rest of this description covers `selections`, which takes ids from get_product_config. Use names unless you already hold the ids. **IMPORTANT — selections structure:** The selections object must use nested objects that mirror the structure of the selections field in the response. Flat keys are silently ignored (no error returned). Always verify the response's selections match what you requested. Known selection keys and their required structure: - **Size** — nested sizeSelection object: {"sizeSelection": {"width": 6, "height": 9, "presetDimensionsId": 15}} For custom dimensions, omit presetDimensionsId or set it to null. - **Quantity & Pages** — flat top-level keys (these DO work as simple values): {"quantity": 1200, "pages": 20} - **Paper** — nested paperSelection object: {"paperSelection": {"pressSheetTypeId": 78, "pressSheetWeightId": 5, "coverPressSheetTypeId": 78, "coverPressSheetWeightId": 3}} - **Ink** — nested objects per ink position: {"coverSide1Ink": {"id": 146}, "coverSide2Ink": {"id": 146}, "interiorSide1AndSide2Ink": {"id": 146}} - **Proof** — nested proofSelection: {"proofSelection": {"proofId": 1}} - **Turnaround** — nested turnTimeSelection: {"turnTimeSelection": {"turnTimeId": 13}} - **Operations** — nested operationSelections with operation name keys: {"operationSelections": {"laminatingCoverOnly": {"operationId": 81, "itemId": 2323}}} An entry accepts ONLY operationId, itemId, operationName, itemName, followUpQuestionAnswer, followUpQuestion and followUpQuestionDataType — any other key is rejected with a validation error. - **Follow-up answers** — when an operation in availableOptions has a followUpQuestion (e.g. shrink-wrapping "How many pieces per bundle do you want?", drilling "Please note placement."), put the customer's answer in followUpQuestionAnswer on the SAME entry, as a string even for integer questions: {"operationSelections": {"shrinkwrappingService": {"operationId": 14, "itemId": 42, "followUpQuestionAnswer": "20"}}} Each update replaces the whole entry, so resend followUpQuestionAnswer whenever you resend that operation. Ask the customer if they chose the operation without answering its question. **General rule:** Look at the selections object in the response — use the same key names and nesting structure when sending updates. Invalid or unrecognized keys are silently ignored. **Example — multiple changes in one call:** {"quantity": 500, "sizeSelection": {"width": 8.5, "height": 11, "presetDimensionsId": 1}, "paperSelection": {"pressSheetTypeId": 78, "pressSheetWeightId": 5}, "turnTimeSelection": {"turnTimeId": 13}} The response includes: - **validation**: Messages indicating issues with current selections. Check globalMessages and fieldMessages to understand what needs to change. - **selectionChangeMessages**: Indicates if any of your selections were automatically adjusted by the system. Always check these after every update — the system may change your selections due to dependency rules. - **availableOptionChangeMessages**: Indicates which available options changed as a result of your selections. - **configurationUrl**: A direct link to view the configuration on the storefront website (when available). Use this iteratively: update selections, review validation, update again until validation is clean. **Send ONLY the selections you are changing.** Every field you send counts as something you asked for, and the server now holds it to that (below). **⚠ SELECTION_CONFLICT — a refusal, never a transport failure.** If a rule would remove a selection you just changed, the call fails with code `SELECTION_CONFLICT` and **nothing is saved** — the session still holds exactly what it held before, so there is no partial state to clean up. The error carries `conflicts: [{ requested, ruleId, ruleName, message }]`, where `message` is the rule's own explanation, e.g. "Not compatible with textured papers". When you see it: 1. **Do NOT retry the same call.** It is not a network or server error and will fail identically every time. 2. Tell the customer what is incompatible, using the conflict `message`. 3. Either pick a compatible alternative, or change the blocking selection first (e.g. move to a coatable stock before selecting coating) — then update again. **Avoid the conflict up front: never select an option whose `disabled` is true** in `availableOptions`. Disabled options carry a `disabledReason` explaining why. Reading `disabled` before choosing is the difference between a smooth change and a refused one. Note the server only refuses selections you CHANGED. A rule removing something you did not touch (e.g. raising the quantity past a turnaround band, which drops a turnaround you never mentioned) still succeeds with a 200 and reports it in `selectionChangeMessages` — so keep checking those.