@shopback/cli 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/LICENSE +29 -0
  2. package/README.md +80 -0
  3. package/dist/sb.js +224 -0
  4. package/package.json +42 -0
package/LICENSE ADDED
@@ -0,0 +1,29 @@
1
+ Copyright (c) 2026 ShopBack Pte. Ltd. All rights reserved.
2
+
3
+ This software and the accompanying documentation (the "Software") are the
4
+ proprietary and confidential property of ShopBack Pte. Ltd. and its
5
+ affiliates ("ShopBack").
6
+
7
+ ShopBack grants you a limited, non-exclusive, non-transferable,
8
+ non-sublicensable, revocable licence to install and run the Software for the
9
+ sole purpose of accessing ShopBack services through it, subject to the
10
+ ShopBack Terms of Service and Privacy Policy published at
11
+ https://www.shopback.com.
12
+
13
+ Except as permitted above, or to the extent such a restriction is
14
+ unenforceable under applicable law, you may not copy, modify, adapt,
15
+ translate, merge, publish, distribute, sublicense, sell, rent, lease, host as
16
+ a service, or create derivative works of the Software, nor reverse engineer,
17
+ decompile or disassemble it, in whole or in part, without the prior written
18
+ consent of ShopBack.
19
+
20
+ No trademark, patent, or other intellectual property right of ShopBack is
21
+ granted by this licence, whether by implication, estoppel or otherwise. All
22
+ rights not expressly granted are reserved by ShopBack.
23
+
24
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
25
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
26
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
27
+ SHOPBACK BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
28
+ ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
29
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,80 @@
1
+ # shopback-cli (`sb`)
2
+
3
+ A command-line tool that AI agents use to find the best ShopBack cashback for a
4
+ purchase and open the store through a tracked ShopBack link.
5
+
6
+ Every command prints exactly one JSON document on stdout, so an agent can parse
7
+ the result and follow its `next` suggestions.
8
+
9
+ ## Install
10
+
11
+ Requires Node ≥ 22.23.4 (the October 2026 security release; 22.x, 24.x and
12
+ 26.x below their patched versions are refused).
13
+
14
+ ```sh
15
+ npm i -g @shopback/cli && sb agent setup # install `sb` and teach your agents
16
+ npx @shopback/cli --help # or run without installing
17
+ ```
18
+
19
+ `sb agent setup` teaches the coding agents on your machine about `sb` (Claude
20
+ Code gets a skill, Codex a block in its global `AGENTS.md`). Until it has run,
21
+ every other command suggests it in `next`, so an agent that only installed the
22
+ CLI sets itself up.
23
+
24
+ ```sh
25
+ sb agent setup # every agent found; --agent codex for one
26
+ sb agent remove # take it out again
27
+ ```
28
+
29
+ Then sign in:
30
+
31
+ ```sh
32
+ sb login
33
+ ```
34
+
35
+ `sb login` uses the device-code flow: it prints a verification URL and a user
36
+ code, which you approve in any browser. Tokens are stored only in the OS
37
+ keychain. `sb whoami` shows the signed-in member, and `sb logout` revokes
38
+ access and removes the stored tokens.
39
+
40
+ ## Commands
41
+
42
+ | Command | What it does |
43
+ | --- | --- |
44
+ | `sb login` | Sign in with the device-code flow (approve in any browser) |
45
+ | `sb signup` | Same flow as `login`; new members choose the Sign Up tab on the page that opens |
46
+ | `sb logout` / `sb whoami` | Revoke access / show the signed-in member |
47
+ | `sb search <query> [--limit N]` | Find stores and their merchant IDs. Matches store names and some category keywords (e.g. "shirt" finds ZALORA, H&M, Uniqlo, but "shoe" finds nothing useful), so search brands or stores when results look unrelated |
48
+ | `sb offer <merchantId> [--amount N]` | Active rate with tiers and caps, upcoming upsizes, the store's T&C, and the estimated cashback per tier (labelled with the tier name) |
49
+ | `sb go <merchantId> [--no-open]` | Start a shopping trip and open the store in the default browser on this machine; the link stays out of the output. Each call creates a new trip, so ask the user first whether to open it in their default browser or give them the link (`--no-open`, e.g. for an in-app browser), then run it once. When no browser opens (CI, SSH, a sandbox, `SB_NO_BROWSER`) or with `--no-open`, the link is returned instead |
50
+ | `sb agent setup [--agent <name>]` | Install a guide to `sb` for coding agents: `~/.claude/skills/shopback/SKILL.md` for Claude Code, a marked block in `~/.codex/AGENTS.md` for Codex (`CLAUDE_CONFIG_DIR` / `CODEX_HOME` respected). Without `--agent`, every agent found; run again to update |
51
+ | `sb agent remove [--agent <name>]` | Remove what `agent setup` installed, leaving the rest of `AGENTS.md` untouched |
52
+ | `sb schema [command]` | JSON Schema of a command's output |
53
+
54
+ Every shopping command needs `sb login` first. A typical agent flow:
55
+
56
+ ```sh
57
+ sb search nike # store or brand names work best
58
+ sb offer 19160 --amount 150
59
+ sb go 19160 # opens the store; always show the returned disclosure
60
+ ```
61
+
62
+ The market comes from the signed-in account. `--country` (default `US`) only
63
+ applies when signed out; a `--country` (or `SB_COUNTRY`) that disagrees with
64
+ the signed-in account stops shopping commands with `invalid_usage`.
65
+
66
+ Sign-in and data both go to `https://connect.shopback.com`.
67
+
68
+ ### Exit codes
69
+
70
+ | Code | `error.code` | Meaning |
71
+ | --- | --- | --- |
72
+ | 0 | — | Success |
73
+ | 1 | `internal_error` | Unexpected internal error |
74
+ | 2 | `invalid_usage` | Bad flags or arguments |
75
+ | 3 | `login_required` | Not signed in, or the session expired |
76
+ | 4 | `rate_limited` | Too many requests. `details.retryAfterSeconds` is usually null, which means the wait is unknown rather than zero |
77
+ | 5 | `not_found` | Store not found |
78
+ | 6 | `unsupported` | Country or feature not supported |
79
+ | 7 | `upstream_error` | ShopBack service error |
80
+ | 8 | `blocked` | Signed in, but ShopBack refused the request (e.g. a risk check). Signing in again does not help |