@staraio/sdk 0.0.0-stage → 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/README.md +64 -2
- package/client.js +85 -0
- package/index.js +83 -0
- package/package.json +8 -4
package/README.md
CHANGED
|
@@ -1,3 +1,65 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @staraio/sdk
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
JavaScript client for the [Star API](https://docs.staraio.co). Star waits in a sale's virtual
|
|
4
|
+
line for you and hands over each place as it reaches the front; you buy in your own browser. This
|
|
5
|
+
SDK turns that into a few lines: start a run, then follow it and take each hand-over as it lands.
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @staraio/sdk
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Start a run and follow it
|
|
12
|
+
|
|
13
|
+
```js
|
|
14
|
+
import { StarClient } from "@staraio/sdk";
|
|
15
|
+
|
|
16
|
+
const star = new StarClient({ key: process.env.STAR_API_KEY });
|
|
17
|
+
|
|
18
|
+
const run = await star.startRun({
|
|
19
|
+
event_url: "https://www.puntoticket.com/...",
|
|
20
|
+
passes: 2, // places to hand over, one per buyer
|
|
21
|
+
tasks: 20, // places Star holds in line to get them
|
|
22
|
+
proxies: ["host:port:user:pass"],
|
|
23
|
+
});
|
|
24
|
+
|
|
25
|
+
for await (const slot of star.handoffs(run.id)) {
|
|
26
|
+
if (slot.handoff?.method === "link") {
|
|
27
|
+
open(slot.handoff.url); // a place at the front: open and buy
|
|
28
|
+
} else if (slot.handoff?.method === "session") {
|
|
29
|
+
loadSession(slot.handoff); // url, user_agent, cookies to load into a browser you control
|
|
30
|
+
} else if (slot.next_action) {
|
|
31
|
+
// the site is asking for something (needs_login, needs_nomination, needs_seat_selection)
|
|
32
|
+
} else if (slot.state === "failed") {
|
|
33
|
+
console.error(slot.slot, slot.error);
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
`handoffs()` yields each slot once, the moment it needs you. Queue movement never wakes the loop,
|
|
39
|
+
and the loop ends when the run ends. Needs Node 20+ (global `fetch`).
|
|
40
|
+
|
|
41
|
+
## Keys and test mode
|
|
42
|
+
|
|
43
|
+
Use a test key (`sk_test_...`) to build against the simulation, a live key (`sk_live_...`) to run
|
|
44
|
+
for real. Create keys in the dashboard (dashboard.staraio.co, API Platform). Keep the key on the
|
|
45
|
+
machine that runs this, never in a browser.
|
|
46
|
+
|
|
47
|
+
## Account sites (Ticketmaster)
|
|
48
|
+
|
|
49
|
+
Pass `accounts` to `startRun` for a site whose line only lets signed-in accounts through. Each
|
|
50
|
+
slot's hand-over is then that account's session. See the [sites
|
|
51
|
+
reference](https://docs.staraio.co/sites).
|
|
52
|
+
|
|
53
|
+
## The raw client
|
|
54
|
+
|
|
55
|
+
`StarClient` wraps a thin HTTP client you can also use directly, plus `waitForChange` (one wait)
|
|
56
|
+
and `signature` (what a wait reacts to):
|
|
57
|
+
|
|
58
|
+
```js
|
|
59
|
+
import { client, waitForChange, StarError } from "@staraio/sdk";
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Every error is a `StarError` carrying the API's `{ code, message, suggested_action }`, so you act
|
|
63
|
+
on `code` instead of parsing prose.
|
|
64
|
+
|
|
65
|
+
Full docs: https://docs.staraio.co
|
package/client.js
ADDED
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
// Thin client for the Star API (/v1). Errors carry the API's {code, message, suggested_action}
|
|
2
|
+
// so the agent can act on `code` instead of parsing prose.
|
|
3
|
+
|
|
4
|
+
export class StarError extends Error {
|
|
5
|
+
constructor(status, detail) {
|
|
6
|
+
super(detail?.message ?? `HTTP ${status}`);
|
|
7
|
+
this.status = status;
|
|
8
|
+
this.detail = detail;
|
|
9
|
+
}
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
export function client({ baseUrl, key, fetchImpl = fetch }) {
|
|
13
|
+
async function call(method, path, body, headers = {}) {
|
|
14
|
+
const res = await fetchImpl(`${baseUrl.replace(/\/$/, "")}/v1${path}`, {
|
|
15
|
+
method,
|
|
16
|
+
headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json", ...headers },
|
|
17
|
+
body: body === undefined ? undefined : JSON.stringify(body),
|
|
18
|
+
});
|
|
19
|
+
if (res.status === 204) return null;
|
|
20
|
+
const data = await res.json().catch(() => ({}));
|
|
21
|
+
if (!res.ok) throw new StarError(res.status, data.detail);
|
|
22
|
+
return data;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
return {
|
|
26
|
+
sites: () => call("GET", "/sites"),
|
|
27
|
+
credits: () => call("GET", "/credits"),
|
|
28
|
+
startRun: (body, idempotencyKey) =>
|
|
29
|
+
call("POST", "/runs", body, idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}),
|
|
30
|
+
getRun: (id) => call("GET", `/runs/${encodeURIComponent(id)}`),
|
|
31
|
+
listRuns: (params = {}) => {
|
|
32
|
+
const query = new URLSearchParams(Object.entries(params).filter(([, v]) => v !== undefined && v !== ""));
|
|
33
|
+
return call("GET", `/runs${query.size ? `?${query}` : ""}`);
|
|
34
|
+
},
|
|
35
|
+
stopRun: (id) => call("DELETE", `/runs/${encodeURIComponent(id)}`),
|
|
36
|
+
reportIssue: (body) => call("POST", "/support", body),
|
|
37
|
+
};
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
// The part of a run an agent reacts to. Queue positions move every poll, so waiting on the
|
|
41
|
+
// whole object would wake the agent for nothing.
|
|
42
|
+
export function signature(run) {
|
|
43
|
+
return JSON.stringify([run.state, run.ended, run.next_action, run.slots?.map((s) => [s.state, s.next_action, !!s.handoff])]);
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
// Poll until the run changes in a way that needs the agent (state, next_action, a new
|
|
47
|
+
// handoff) or the timeout passes. Returns the latest run either way. Pass `from` (a run already
|
|
48
|
+
// seen) to wait for a change relative to it, so a caller that chains waits never misses the
|
|
49
|
+
// read in between; without it the baseline is the first fresh read, as before.
|
|
50
|
+
export async function waitForChange(api, id, { timeoutMs, intervalMs = 2000, from, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) }) {
|
|
51
|
+
const deadline = Date.now() + timeoutMs;
|
|
52
|
+
// A passing engine or network hiccup must not cut the wait short: retry until the deadline.
|
|
53
|
+
async function read(last) {
|
|
54
|
+
for (;;) {
|
|
55
|
+
try {
|
|
56
|
+
return await api.getRun(id);
|
|
57
|
+
} catch (err) {
|
|
58
|
+
if (!isTransient(err)) throw err;
|
|
59
|
+
if (Date.now() >= deadline) {
|
|
60
|
+
if (last) return last;
|
|
61
|
+
throw err;
|
|
62
|
+
}
|
|
63
|
+
await sleep(intervalMs);
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
const baseline = from ? signature(from) : null;
|
|
68
|
+
let run = await read(null);
|
|
69
|
+
const start = baseline ?? signature(run);
|
|
70
|
+
while (!run.ended && signature(run) === start && Date.now() < deadline) {
|
|
71
|
+
await sleep(intervalMs);
|
|
72
|
+
run = await read(run);
|
|
73
|
+
}
|
|
74
|
+
return run;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
function isTransient(err) {
|
|
78
|
+
// 429 is the per-run read limit: waiting longer is exactly the right answer to it.
|
|
79
|
+
if (err instanceof StarError) {
|
|
80
|
+
if (err.status === 429) return true;
|
|
81
|
+
// A 5xx with no API detail comes from the load balancer or a proxy, not from Star.
|
|
82
|
+
return err.status >= 500 && (!err.detail || err.detail.suggested_action === "retry");
|
|
83
|
+
}
|
|
84
|
+
return err instanceof TypeError; // fetch's network failure
|
|
85
|
+
}
|
package/index.js
ADDED
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
// @staraio/sdk: the Star API in a few lines. `StarClient` wraps the HTTP calls, and
|
|
2
|
+
// `handoffs()` yields each slot the moment its place reaches the front, so the caller follows
|
|
3
|
+
// a run without polling or tracking queue movement itself. The low-level client, StarError and
|
|
4
|
+
// waitForChange are re-exported for callers that want the raw calls.
|
|
5
|
+
import { StarError, client, signature, waitForChange } from "./client.js";
|
|
6
|
+
|
|
7
|
+
export { StarError, client, signature, waitForChange };
|
|
8
|
+
|
|
9
|
+
export class StarClient {
|
|
10
|
+
constructor({ key, baseUrl = "https://api.staraio.co", fetchImpl } = {}) {
|
|
11
|
+
if (!key) throw new Error("StarClient needs an API key");
|
|
12
|
+
this.api = client({ baseUrl, key, fetchImpl });
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
sites() {
|
|
16
|
+
return this.api.sites();
|
|
17
|
+
}
|
|
18
|
+
credits() {
|
|
19
|
+
return this.api.credits();
|
|
20
|
+
}
|
|
21
|
+
startRun(body, idempotencyKey) {
|
|
22
|
+
return this.api.startRun(body, idempotencyKey);
|
|
23
|
+
}
|
|
24
|
+
getRun(id) {
|
|
25
|
+
return this.api.getRun(id);
|
|
26
|
+
}
|
|
27
|
+
listRuns(params) {
|
|
28
|
+
return this.api.listRuns(params);
|
|
29
|
+
}
|
|
30
|
+
stopRun(id) {
|
|
31
|
+
return this.api.stopRun(id);
|
|
32
|
+
}
|
|
33
|
+
reportIssue(body) {
|
|
34
|
+
return this.api.reportIssue(body);
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
// Follow a run and yield each slot once, the moment it needs the caller: a place reached the
|
|
38
|
+
// front (`slot.handoff`, a link or a session to open), the site asks for something
|
|
39
|
+
// (`slot.next_action`) or the slot failed. Queue movement never yields. The generator ends
|
|
40
|
+
// when the run ends or `timeoutMs` passes, so a plain `for await` loop drives a whole run.
|
|
41
|
+
async *handoffs(runId, { timeoutMs = 6 * 60 * 60 * 1000, intervalMs = 2000 } = {}) {
|
|
42
|
+
const seen = new Map();
|
|
43
|
+
const deadline = Date.now() + timeoutMs;
|
|
44
|
+
// Drive every read through waitForChange, including the first: `FIRST_READ` is a baseline no
|
|
45
|
+
// real run matches, so the first wait returns the current run at once, and `from` the run
|
|
46
|
+
// just scanned on every wait after, so a change between scans is never swallowed as a
|
|
47
|
+
// baseline. One read path means the first read retries a transient error like the rest.
|
|
48
|
+
let from = FIRST_READ;
|
|
49
|
+
for (;;) {
|
|
50
|
+
const run = await waitForChange(this.api, runId, { timeoutMs: deadline - Date.now(), intervalMs, from });
|
|
51
|
+
let index = -1;
|
|
52
|
+
for (const slot of run.slots ?? []) {
|
|
53
|
+
index += 1;
|
|
54
|
+
if (!needsCaller(slot)) continue;
|
|
55
|
+
// Slots carry a 0-based `slot` index; fall back to position so id-less slots never
|
|
56
|
+
// collide on one key and re-yield each other every poll.
|
|
57
|
+
const key = slot.slot ?? index;
|
|
58
|
+
const sig = slotSignature(slot);
|
|
59
|
+
if (seen.get(key) === sig) continue;
|
|
60
|
+
seen.set(key, sig);
|
|
61
|
+
yield slot;
|
|
62
|
+
}
|
|
63
|
+
if (run.ended || Date.now() >= deadline) return;
|
|
64
|
+
from = run;
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
// A baseline whose signature no real run shares (every run has a non-null state), so a wait
|
|
70
|
+
// seeded with it returns the current run on the first read instead of waiting for a change.
|
|
71
|
+
const FIRST_READ = { state: null };
|
|
72
|
+
|
|
73
|
+
// A slot the caller has to act on: one carrying a hand-over, one the site is asking something
|
|
74
|
+
// of, or one that failed. A slot still in line carries none of these.
|
|
75
|
+
function needsCaller(slot) {
|
|
76
|
+
return Boolean(slot.handoff || slot.next_action || slot.state === "failed");
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
// Two yields for the same slot are the same event only when state, next_action and handoff all
|
|
80
|
+
// match, so a slot that fails after a hand-over, or gets a fresh action, yields again.
|
|
81
|
+
function slotSignature(slot) {
|
|
82
|
+
return JSON.stringify([slot.state, slot.next_action, slot.handoff]);
|
|
83
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,10 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@staraio/sdk",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "JavaScript client for the Star API: start a run, follow it and take each place at the front.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "index.js",
|
|
7
|
+
"files": ["index.js", "client.js"],
|
|
8
|
+
"engines": { "node": ">=20" },
|
|
9
|
+
"scripts": { "test": "node --test" }
|
|
10
|
+
}
|