@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.
- package/LICENSE +29 -0
- package/README.md +80 -0
- package/dist/sb.js +224 -0
- 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 |
|