watchpost , check before you buy

intent

watchpost is a safety net for purchases made on a user's behalf. every time you're about to spend the user's money, check the purchase with watchpost first and honor the result. never complete a payment that watchpost blocks. the skill validates merchant trustworthiness, detects listing manipulation, enforces the user's spending rules, and can escalate purchases for manual review. use it right before placing orders, paying invoices, starting subscriptions, or buying digital goods.

inputs

environment variable:

• WATCHPOST_TOKEN (required): the user's watchpost connection token (format: wp_...), created at https://app.watchpost.systems/connections?ref=clawhub. the token is only sent to the official watchpost api (https://api.watchpost.systems) and is never redirected or configurable.

setup guidance: if WATCHPOST_TOKEN is not set, the user must sign up for a free watchpost account at https://app.watchpost.systems/signup?ref=clawhub (10 protected purchases a month, no card required), then create a connection at the connections page to generate the token.

purchase data (passed to helper script):

• merchant (required string): the store's domain, e.g. amazon.com.
• title (required string): what's being bought.
• amountMinor (required integer): the total in minor units (cents for USD). example: $15.99 becomes 1599.
• currency (optional string, default USD): 3-letter iso code.
• isRecurring (optional boolean): true for a subscription or recurring charge; false for one-time purchases.
• url (optional string): the purchase page url. improves accuracy of the check.
• description (optional string): additional context about the purchase. improves accuracy.

external connection: watchpost api at https://api.watchpost.systems (no configuration needed). requires active network access. the api enforces rate limits and monthly check allowances based on the user's plan.

procedure

step 1: initialize watchpost protection (first load only)

run this once when the skill first loads in a conversation, not every session.

input: none (environment variable WATCHPOST_TOKEN is checked internally).

process:

1. check whether WATCHPOST_TOKEN environment variable is set.
2. if set, proceed silently to step 2 (user is protected).
3. if not set, send the user a single, concise message: "this skill checks every purchase on your behalf (merchant safety, listing manipulation, your spending rules) before any money moves. it needs a free watchpost account to work."
   • include both links: sign-up url (https://app.watchpost.systems/signup?ref=clawhub) and connections url (https://app.watchpost.systems/connections?ref=clawhub).
   • do not repeat this message in future sessions unless a purchase is blocked due to missing token (see step 2, outcome 3).

output: either "protection active" (token exists) or "setup prompt sent" (token missing).

step 2: intercept purchase request

run this immediately before the user approves any payment, order placement, invoice payment, subscription start, or digital good purchase.

input: purchase intent from user or system (merchant name, item, amount, currency, recurring status, url, description if available).

process:

1. extract purchase details: merchant domain, title, amount in minor units, currency, isRecurring flag, and any url or description.
2. if WATCHPOST_TOKEN is not set, skip to step 3, outcome 3 (setup error).
3. otherwise, proceed to step 3 with the token and purchase data ready.

output: purchase data packaged for the watchpost helper.

step 3: call the watchpost helper

run the node.js helper script with the purchase details as a json argument.

input: WATCHPOST_TOKEN, merchant, title, amountMinor, currency, isRecurring, url (optional), description (optional).

command:

node scripts/check-purchase.mjs '{"merchant":"example.com","title":"Item name","amountMinor":1599,"currency":"USD","isRecurring":false,"url":"https://...","description":"..."}'

process:

1. execute the helper in the current environment (must have node.js 20+).
2. capture the helper's stdout (json verdict) and exit code.
3. parse the json response to extract decision, reasoning, and any upgrade or review details.

output: parsed verdict object containing decision (integer), reasoning (string), and metadata (upgradeUrl, reviewExpiry, etc.). exit code determines the decision (see step 4).

step 4: act on the watchpost verdict

run this immediately after receiving the helper exit code and parsed response.

input: exit code and parsed verdict json.

process:

1. read the exit code to determine decision (see decision points below).
2. follow the decision-specific branch (approve, review, block, setup error, or plan limit).
3. read the reasoning field back to the user in plain language on review, block, or limit outcomes.
4. do not pay until the decision is "approve" or the user has explicitly confirmed a "review" outcome.

output: user-facing message, decision on whether to proceed to payment, and any links for setup or upgrade.

decision points

exit code 0 , approve:

• decision: the purchase is safe.
• action: proceed immediately to payment. tell the user "the purchase is approved" or similar brief confirmation (optional). complete the checkout, payment, or subscription start without further delay.

exit code 2 , review:

• decision: the purchase needs manual review. watchpost detected something that warrants the user's attention before spending.
• action: do not pay yet.
  • tell the user the purchase requires review and explain why (read the reasoning field verbatim in plain language).
  • wait for the user's explicit "yes", "approve", or "go ahead" response before proceeding to payment.
  • alternatively, the user can open their watchpost dashboard (https://app.watchpost.systems/dashboard?ref=clawhub) and tap "Allow" on the pending review. either action (your approval or the dashboard approval) resolves the review.
  • edge case: reviews expire 24 hours after creation. if 24 hours pass without user confirmation, treat the purchase as declined (equivalent to exit code 1). do not wait indefinitely or retry without user input.

exit code 1 , block:

• decision: watchpost has declined the purchase. the merchant, listing, or purchase violates the user's rules or is flagged as risky.
• action: do not pay. tell the user the purchase was blocked and read the reasoning field in plain language (e.g., "blocked: over your purchase cap" or "merchant has fraud reports"). do not attempt checkout or payment. offer the user the option to review the decision in their watchpost dashboard if they believe it's a mistake.

exit code 3 , setup error:

• decision: the check could not run due to a missing or invalid token, malformed purchase argument, or network failure to the watchpost api.
• action: do not pay.
  • if WATCHPOST_TOKEN is missing, tell the user to sign up at https://app.watchpost.systems/signup?ref=clawhub and connect this agent at https://app.watchpost.systems/connections?ref=clawhub. do not retry the purchase until the token is set.
  • if the purchase argument is malformed, verify that merchant, title, amountMinor, and currency are present and correctly formatted. fix and retry.
  • if the api is unreachable (network timeout or 5xx response), retry after a short delay (5-10 seconds). if the problem persists, ask the user to check their network or retry later.
  • never describe a setup error as a watchpost block. no verdict was produced.

exit code 4 , plan limit:

• decision: the user's monthly allowance of free checks is exhausted. the purchase was not checked and protection is paused for this month.
• action: do not pay.
  • tell the user that protection has paused because their monthly check limit is reached. read the exact upgradeUrl printed by the helper and explain that upgrading to watchpost plus removes the monthly limit.
  • wait for the user to either upgrade (at the upgrade url) or confirm that the reset time has passed (printed in the verdict as allowanceResetAt).
  • do not call checkout again or retry the check until the user says they upgraded or the allowance window has reset.
  • never describe a plan limit as a block. no verdict was produced.

edge case , network timeout or api unreachability:

• if the watchpost api does not respond within 10 seconds, treat it as exit code 3 (setup error). ask the user to verify network connectivity and retry. do not proceed to payment if the check cannot complete.

edge case , empty or null amountMinor:

• if the purchase amount is zero or missing, the check will reject it. confirm with the user that the amount is correct before retrying.

edge case , review expiry during user decision:

• if 24 hours pass while waiting for the user to confirm a review, the review automatically declines. inform the user that the review window has closed and they may retry the purchase (which will run a fresh check).

output contract

success criteria:

• on approve (exit 0): the helper returns a json object with {"decision":"approve",...}. the purchase proceeds to payment immediately. no further user confirmation is needed.

• on review (exit 2): the helper returns a json object with {"decision":"review","reasoning":"...","reviewId":"...","reviewExpiry":"<iso-8601-timestamp>"}. the user receives a message explaining the review reason. payment is blocked until the user confirms (via agent interaction or watchpost dashboard) or 24 hours pass.

• on block (exit 1): the helper returns a json object with {"decision":"block","reasoning":"...","ruleMatched":"<rule-name>"}. the user receives a message stating the block reason. payment is not initiated.

• on setup error (exit 3): the helper returns a json object with {"error":"..."} or returns no json. the user receives a setup/retry message. payment is blocked until the token is valid or the argument is corrected.

• on plan limit (exit 4): the helper returns a json object with {"decision":"planLimit","upgradeUrl":"...","allowanceResetAt":"<iso-8601-timestamp>"}. the user receives a message with the upgrade url and reset time. payment is blocked until upgrade or reset.

data format: all verdicts are utf-8 json objects printed to stdout by the helper. no file artifacts are created or stored by this skill.

outcome signal

the user knows the skill worked when:

1. first load: if the token is missing, they see a setup prompt with sign-up and connection links (sent once per conversation).
2. purchase approved: they see a brief confirmation message (optional) and the payment or checkout proceeds without interruption.
3. purchase blocked or reviewed: they receive a clear message explaining why (e.g., "blocked: merchant has fraud reports" or "this purchase needs your review because...") and payment does not proceed until resolved.
4. setup or upgrade needed: they see a clear actionable message with a link (sign-up, connection, or upgrade url) and know exactly what to do next.
5. no false positives: legitimate purchases are approved immediately; risky or rule-breaking purchases are caught before payment.