walmart-support 0.1.0__tar.gz

walmart_support-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "name": "walmart-support",
+  "description": "The walmart-support CLI and the skill that drives it.",
+  "owner": {
+    "name": "alyiox"
+  },
+  "plugins": [
+    {
+      "name": "walmart-support",
+      "source": "./",
+      "description": "Read, answer, and file Walmart Connect advertising support cases from the shell.",
+      "category": "productivity",
+      "homepage": "https://github.com/alyiox/walmart-support"
+    }
+  ]
+}

walmart_support-0.1.0/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "walmart-support",
+  "description": "Read, answer, and file Walmart Connect advertising support cases from the shell, using the walmart-support CLI.",
+  "version": "0.1.0",
+  "author": {
+    "name": "alyiox"
+  },
+  "homepage": "https://github.com/alyiox/walmart-support"
+}

walmart_support-0.1.0/.gitattributes

@@ -0,0 +1,3 @@
+* text=auto eol=lf
+*.{cmd,[cC][mM][dD]} text eol=crlf
+*.{bat,[bB][aA][tT]} text eol=crlf

walmart_support-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,69 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+    tags: ["*"]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@ae62891fec2bb8e7d6c99fc78c9fec3a63790f8d # v10.0.0
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Lint and Format
+        run: |
+          uv run ruff check src/ tests/
+          uv run ruff format --check src/ tests/
+
+      - name: Type check
+        run: uv run pyright
+
+      - name: Test
+        run: uv run pytest tests/ -v --tb=short
+
+  publish:
+    name: Release to PyPI
+    needs: test
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/walmart-support/${{ github.ref_name }}/
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+
+      - name: Install uv package manager
+        uses: astral-sh/setup-uv@ae62891fec2bb8e7d6c99fc78c9fec3a63790f8d # v10.0.0
+        with:
+          enable-cache: true
+
+      - name: Build Python package distributions
+        run: uv build
+
+      - name: Publish Python package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

walmart_support-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Local dev notes
+*-progress.md
+
+# Local secrets
+config.json
+*.pem
+smoke.curl.txt
+*.curl.txt

walmart_support-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

walmart_support-0.1.0/AGENTS.md

@@ -0,0 +1,117 @@
+# Agent Instructions
+
+Rules AI agents must follow when working in this repository.
+
+---
+
+## Commit messages
+
+Use **Conventional Commits**.
+
+### Header
+
+* Format: `<type>(optional scope): summary`
+* Use lowercase types (`feat`, `fix`, `ci`, `chore`, `docs`)
+* Use scopes when relevant
+* Write summaries in lowercase, imperative mood
+
+### Body
+
+* Leave a blank line after the header
+* Explain **why**, not what
+* Use imperative, present tense
+* Wrap lines at ~72 characters
+
+The body is optional for trivial changes.
+
+---
+
+## Release tags
+
+* Use the bare version as the tag name — **no `v` prefix** (e.g. `0.1.1`, not `v0.1.1`)
+* Prefer final versions over pre-releases: a resolver skips pre-releases unless
+  asked, so `uvx walmart-support` cannot see an `a`/`b`/`rc` build
+* Tags must be annotated (`git tag -a`) with a structured release-notes message
+
+---
+
+## Commits
+
+When generating commits via a shell:
+
+* Do **not** pass generated messages directly to `git commit -m`
+* Write the commit message to a file or standard input
+* Use `git commit -F <file>` or `git commit -F -`
+* Disable shell expansion when writing commit messages
+
+This avoids issues with backticks, quotes, and other shell-expanded
+characters in generated commit messages.
+
+---
+
+## Code style
+
+Follow existing project conventions.
+
+* Match formatting, naming, and file structure already in use
+* Do not reformat unrelated code
+* Prefer small, focused changes
+* Avoid introducing new patterns without clear benefit
+
+### Language-specific rules
+
+* Respect `.editorconfig` when present
+* Do not disable lint rules without justification
+* Prefer explicit, readable code over clever abstractions
+* Ensure all changes pass `ruff check .`, `ruff format --check .`, `pyright`, and `pytest`
+
+---
+
+## `uv` Workflow Rules
+
+* Use `uv` exclusively for dependency management instead of `pip`
+* Always prefix tool and script invocations with `uv run` so they execute inside the managed environment
+* Do not manually create, activate, or delete `.venv` directories
+* Use `uv version <new-version>` to bump the project version — do **not** edit `pyproject.toml` directly
+* Always commit both `pyproject.toml` and `uv.lock` together after a version bump
+
+---
+
+## Attribution
+
+All commits must include an `Assisted-by` trailer line:
+
+```
+Assisted-by: AGENT_NAME:MODEL_VERSION [TOOL1] [TOOL2]
+```
+
+* **AGENT_NAME** — the AI tool or framework used (e.g. `Claude`, `Cursor`, `Copilot`)
+* **MODEL_VERSION** — the specific model version (e.g. `claude-opus-4-6`)
+* **[TOOL1] [TOOL2]** — optional, space-separated list of specialized analysis tools used in the change (e.g. `coccinelle`, `sparse`, `smatch`, `clang-tidy`)
+* Do **not** list everyday tools like `git`, `gcc`, `make`, or editors
+
+Example:
+
+```
+Assisted-by: Claude:claude-opus-4-6 coccinelle sparse
+```
+
+---
+
+## CLI conventions
+
+The command surface is the product. Keep it predictable.
+
+* Group commands by the noun they act on (`cases`, `categories`, `auth`); the
+  group name carries the entity, the subcommand carries the verb
+* Every command MUST accept `--json` and emit machine-readable output under it,
+  with the human rendering as the default
+* Take prose (case bodies, replies) through a `--*-file` flag rather than an
+  argument, so long text never passes through shell quoting
+* A command that changes state at Walmart's end MUST NOT act on defaults alone:
+  `cases create` prints its payload unless `--submit` is given
+* Exit codes: `0` success, `1` portal or network failure, `2` usage, config, or
+  refused input
+* A change to a flag's behaviour or cost updates `skills/walmart-support/SKILL.md`
+  in the same commit: the skill documents the gates and per-case request costs
+  that the help text does not

walmart_support-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

walmart_support-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jon X
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

walmart_support-0.1.0/PKG-INFO

@@ -0,0 +1,259 @@
+Metadata-Version: 2.5
+Name: walmart-support
+Version: 0.1.0
+Summary: CLI for Walmart Connect advertising support cases
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: httpx>=0.27.0
+Description-Content-Type: text/markdown
+
+# Walmart Connect Advertising Support Cases
+
+[![CI](https://github.com/alyiox/walmart-support/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/alyiox/walmart-support/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/walmart-support.svg)](https://pypi.org/project/walmart-support/)
+[![Python 3.13+](https://img.shields.io/badge/python-3.13%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+CLI for reading and filing [Walmart Connect](https://advertisinghelp.walmart.com) advertising
+support cases without driving a browser.
+
+The Advertising Help portal is a Salesforce Experience Cloud site with no public API. Every click in
+its UI is one POST to `/s/sfsites/aura` naming an `@AuraEnabled` Apex method, so the flow is
+scriptable — which matters, because submitting a case body through a headless browser is slow and,
+in some environments, unreliable enough to leave you unsure whether a case was actually filed.
+
+## Status
+
+Working end to end: authentication, listing and reading cases, replying, attaching files, closing,
+and filing new cases. Each Aura payload was captured from the portal UI and verified against a real
+case, so treat behaviour outside the documented commands as unmapped rather than unsupported.
+
+## Requirements
+
+- Python 3.13+, or [uv](https://docs.astral.sh/uv/)
+- A Walmart Advertising Help portal account (the Partners → Help Site login)
+
+## Quick start
+
+There is nothing to install — `uvx` fetches and runs it:
+
+```bash
+mkdir -p ~/.config/walmart-support
+cp config.example.json ~/.config/walmart-support/config.json
+$EDITOR ~/.config/walmart-support/config.json
+
+uvx walmart-support auth check
+uvx walmart-support cases list --status "need info"
+uvx walmart-support cases get 15957474
+uvx walmart-support cases replies 15957474 --from-walmart
+
+uvx walmart-support cases create \
+  --platform display \
+  --category "API Support" --issue "Endpoint-specific problem" \
+  --subject "Display API: ..." --advertisers "241727, 244985" \
+  --description-file ./body.txt                # prints the payload
+uvx walmart-support cases create ... --submit   # actually files it
+
+# where the --category and --issue names come from
+uvx walmart-support categories list --platform sponsored-search
+```
+
+Reaching for it daily, or working offline? `uv tool install walmart-support`
+puts it on `PATH` and starts faster; `walmart-support --version` reports which
+build you are on either way. Inside a clone of this repo, use `uv run
+walmart-support ...` to exercise your working tree.
+
+## Replying and attaching
+
+`cases reply` posts a comment on an existing case, and `cases attach` uploads
+files to one:
+
+```bash
+walmart-support cases reply 15957474 --message-file answer.txt
+walmart-support cases attach 15957474 ./har.json ./adgroup.json
+```
+
+Neither is gated behind a confirmation flag, unlike `cases create`: they act on
+a case you already own, with no category mapping to get wrong. `create` files a
+*new* record into the support queue, which is the thing worth a second look.
+
+Both are writes, so **do not wrap them in a retry loop.** A network error after
+the write lands looks identical to one before it, and retrying uploads the file
+or posts the comment twice — the portal has no idempotency key.
+
+Deletion is asymmetric and this bites: an upload returns a **ContentVersion**
+id (`068…`), while the portal's delete actions want the **ContentDocument** id
+(`069…`) and silently do nothing when handed the other. The `069` ids are
+recoverable from a case's detail payload; `attachments.document_ids()` extracts
+them.
+
+Attaching *while filing* is not supported yet: `openCase` accepts a
+`documentId` list, but `saveChunk` requires a `parentId` and the case does not
+exist yet, so it is unclear what the portal passes at that point.
+
+## Filing a case
+
+`cases create` prints the exact `openCase` payload and files nothing unless
+`--submit` is given. That default is deliberate: a case goes to Walmart's
+support queue, and a mis-mapped category files a real but misrouted one.
+
+Categories are resolved by name against the portal's own dropdown data rather
+than hardcoded, so `categories list` shows exactly what the UI offers and both
+the UI label ("API Support") and the wizard's internal name ("API") match.
+
+`--platform` covers Display and Sponsored Search; the portal collapses Search
+onto its "Sponsored Products" ad unit, which is why a Search case shows
+Sponsored Products as its platform. Sponsored Brands and Videos are accepted
+but the portal publishes no categories for them on a partner account, and the
+error says so.
+
+`openCase` returns the new case's number, and the whole path is verified
+end to end — filed, replied to and closed. Three things had to be right, none
+of which the method signature revealed:
+
+* `additionalFieldsString` is a JSON **list** of `{title, value}` objects, not
+  an object. Apex deserializes it into a `List` and names any unexpected key.
+* `partnershipType`/`partnershipId` must be **empty**. `Partnership__c` is a
+  lookup to a Partnership record for supplier and seller channels, so an
+  account id there fails the insert with `FIELD_INTEGRITY_EXCEPTION`.
+* Category routing comes from the resolved level-1/level-2 pair, and a filed
+  case reports `API-AdCases` / `Endpoint-specific problem` back.
+
+> **Known defect:** the portal resolves additional fields loosely against the
+> `title` we send. On the first CLI-filed case, `Advertiser Account Name` and
+> `Advertisers Affected` collided on their shared prefix and the account name
+> was stored under the advertisers field, dropping the ids. The colliding field
+> is no longer sent, which should fix it, but that is **unconfirmed until the
+> next filing** — and the wrapper evidently carries an identifier beyond
+> `title`/`value` (its deserializer also accepts `fieldName`).
+>
+> Either way, put anything that matters in the description body: it is stored
+> verbatim, whereas these fields are not reliably addressable.
+
+### Closing and replying
+
+```bash
+walmart-support cases reply 15971149 --message-file answer.txt
+walmart-support cases close 15971149   # New -> Closed
+```
+
+## Sessions
+
+Each invocation is its own process, so session cookies are cached in
+`$XDG_CACHE_HOME/walmart-support/session.json` (mode `0600`) and reused
+until the portal rejects them. Without that, every command would pay a full
+login — four requests and a Salesforce login event before doing any work; with
+it, a warm command is roughly twice as fast and logs in only when it must.
+
+A session that dies mid-command is retried once from a clean login, because
+Salesforce reports an invalid session in the middle of a request rather than up
+front. `walmart-support auth logout` discards the cached session.
+
+## Configuration
+
+`~/.config/walmart-support/config.json`:
+
+| Key | Required | Description |
+| --- | --- | --- |
+| `base_url` | no | Portal origin. Defaults to `https://advertisinghelp.walmart.com`. |
+| `username` | yes | Portal login email. |
+| `password` | yes | Portal password. |
+| `timeout` | no | Per-request timeout in seconds (default 60). |
+
+Every key can be overridden by an environment variable — `WALMART_SUPPORT_USERNAME`,
+`WALMART_SUPPORT_PASSWORD`, `WALMART_SUPPORT_BASE_URL`, `WALMART_SUPPORT_TIMEOUT` — so CI needs no
+file on disk.
+
+Credentials are the only way in, deliberately. A session cookie cannot be configured by hand:
+Salesforce `sid` cookies are session-scoped, expire on their own, and cannot renew themselves, so a
+configured one becomes a stale secret that fails in a way the tool can do nothing about. Sessions
+are managed by the cache below instead.
+
+## Reading a case
+
+`cases list` is backed by one action that returns every case at once, but it
+**abbreviates** `subject` and `description` — the trailing `...` comes from
+Walmart. `cases get` uses the detail action instead, which returns the full text
+plus status, priority, category and the submitted form fields.
+
+### Searching
+
+`cases list --query` filters on the text the list action returns — and that text
+is **abbreviated**: subjects are cut to roughly 46 characters, and some cases
+carry almost no description at all. So a plain `--query` can miss a case whose
+real body contains the term.
+
+`--deep` re-reads each candidate's full text *and its replies* instead, at one
+request per candidate:
+
+```bash
+# finds nothing: the term sits past where the list truncates the subject
+walmart-support cases list --query "targeting of a LIVE ad group"
+
+# finds both cases
+walmart-support cases list --query "targeting of a LIVE ad group" --since 2026-08-01 --deep
+```
+
+Because it fans out, `--deep` refuses to run on more candidates than its cap
+(25) and asks you to narrow with `--status`/`--since`/`--limit` rather than
+firing a request per case in the account.
+
+`--limit` on its own is handed to the portal as a SOQL `LIMIT`. Combined with a
+filter it stays client-side, since the server would otherwise apply it *before*
+filtering and return matches from an arbitrary slice.
+
+`cases replies` shows the case conversation, flattened from the HTML the portal
+stores, with each message attributed to `us` or `WALMART`:
+
+```bash
+walmart-support cases replies 15957474                  # whole thread
+walmart-support cases replies 15957474 --from-walmart   # skip our own posts
+walmart-support cases replies 15957474 --latest 1       # just the newest
+```
+
+Support's acknowledgement mails quote the entire case body back, and later
+replies quote the ones before them, so an unfiltered thread is mostly repetition
+of what you already sent — `--from-walmart --latest 1` is usually what you want.
+
+## Claude Code plugin
+
+The repo doubles as a [Claude Code](https://claude.com/claude-code) plugin, so the workflow
+knowledge travels with the CLI instead of living in one person's `~/.claude`:
+
+```
+/plugin marketplace add alyiox/walmart-support
+/plugin install walmart-support@walmart-support
+```
+
+That installs a skill covering the parts the `--help` output cannot express — that `--deep` costs
+one request per case, that support's replies quote the whole thread back, that `cases create` files
+nothing without `--submit`, and that `cases close` is one-way. The plugin does not install the CLI;
+`walmart-support --version` tells you whether you still need to.
+
+## How it works
+
+```
+GET  /s/contact                     scrape the Aura context (fwuid, apck, lrmc, markup hash)
+POST /s/sfsites/aura?r=N&...login   authenticate via LightningLoginFormController
+POST /s/sfsites/aura?r=N&other....  call @AuraEnabled Apex methods through ApexActionController
+```
+
+Aura rejects any call whose framework context does not match the deployed build, and that context
+rotates with every Salesforce release, so it is scraped on each run and never hardcoded. All of this
+lives in `aura.py`; when Walmart's contract shifts, that is the one module to re-capture against.
+
+## Development
+
+```bash
+uv sync --group dev
+uv run ruff check src/ tests/
+uv run ruff format --check src/ tests/
+uv run pyright
+uv run pytest tests/ -v
+```
+
+Tests are offline: they exercise recorded page shapes and Aura envelopes through `httpx.MockTransport`.
+
+## License
+
+MIT