---
name: ralphs-grocery-sync
description: Sync Ralphs grocery orders from the last 7 days into the canonical grocery ledger and yearly merchant CSV files. Use when you need to collect Ralphs purchase history, recover after missed syncs, or run a scheduled grocery import with the authenticated automation browser profile.
---

# Ralphs Grocery Sync

## Standing Rules for All Merchant Skills

These rules are the inherited baseline for all new merchant skills derived from this template.

### Native Input Only
- All credential and form-field entry must use native typing semantics (`CDP Input.insertText` or equivalent keystroke dispatch).
- Never use direct JS value assignment for credential entry.
- JS fill on modern React/controlled inputs is a confirmed failure mode and must be treated as prohibited for login flows.
- Shared utility for future implementations: `../shared/common_input.js`

### Credential Emission Normalization
- Before submitting any credential value retrieved from LastPass CLI or local credential helpers, normalize whitespace.
- Always strip leading/trailing whitespace and carriage returns.
- Emit only clean values to the browser interaction layer.

### Login Entry Point
- Always enter through the merchant’s order-history URL (for example `/orders`, `/mypurchases`, or the merchant equivalent), not the bare `/login` URL.
- Bare login URLs frequently render non-interactive shells with missing form controls and should be treated as a known failure mode.

### Humanization Checklist
- Every merchant skill must include a site-specific humanization section.
- Minimum baseline requirements:
  - introduce randomized delays between interactions (100–400ms baseline)
  - use native input events only
  - avoid instant sequential navigation
  - check for bot-detection signals before proceeding (CAPTCHA, challenge pages, blank/non-interactive form renders)
- Document any site-specific humanization adaptations in the merchant’s notes section.

## Ralphs Humanization
- Use native typing only for any credential or recovery prompt.
- Introduce randomized delays between major interactions (100–400ms baseline; longer if Ralphs hydration is slow).
- Avoid back-to-back navigation clicks before the SPA visibly hydrates.
- Check for CAPTCHA, sign-in challenge pages, or blank/incomplete renders before proceeding with extraction.
- If Ralphs-specific anti-bot or hydration anomalies are observed, record them in `references/extraction-notes.md`.

1. Confirm the automation browser profile (`/Users/openclaw/.openclaw/browser/merchant-automation/user-data`) is attached and that Ralphs is reachable.
2. Detect logged-out state before extraction (URL contains `/signin` or page shows sign-in prompts). If logged out, retrieve credentials with `scripts/get_credential.sh ralphs.com`, perform login with slow native typing semantics, and enable any remember-me/stay-signed-in option present.
3. Open `https://www.ralphs.com/mypurchases` and confirm the purchase list is visible before scraping.
4. Collect only orders from the last 7 days. Capture `order_date`, `order_id`, `fulfillment_type`, `order_total`, and the detail-page URL.
5. Open each qualifying detail page and expand the full order before extraction.
6. Sanity-check the item list before extraction:
   - Click any `Show all`, `View all items`, or `See all N items` control.
   - Scroll to the bottom to trigger lazy loading.
   - Take another snapshot and compare the visible item count.
   - Repeat expand + scroll + snapshot until no new items appear.
   - If the page still looks truncated, stop and report a partial-sync blocker instead of writing incomplete data.
7. Extract all visible line items and every visible adjustment line exactly as shown. Preserve repeated adjustment labels such as `CA Redem Val` as separate rows.
8. Write the normalized payload to `scripts/sync_to_grocery_db.py` and merge the yearly exports with `scripts/merge_grocery_csv.py`.
9. Stop immediately and report if login fails, browser attachment fails, CAPTCHA appears, or the order page cannot be expanded to a stable full list.

## References
- Shared schema: `../grocery-shared/references/schema.md`
- Shared input utility: `../shared/common_input.js`
- Merchant notes: `references/extraction-notes.md`

## Completion Contract

```text
Completion Contract
Done: Ralphs sync attempted for the last 7 days and all successful outputs were written.
Findings: orders found, orders inserted, items written, adjustments written, CSV paths, and any reconciliation anomalies.
Decision needed: only if login failed, CAPTCHA appeared, or page expansion stayed incomplete.
Next step: recommended retry window or manual follow-up if blocked.
```