tebex-plugin-api 0.1.0 → 0.1.1
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 +95 -12
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,23 +1,106 @@
|
|
|
1
|
-
#
|
|
1
|
+
# tebex-plugin-api
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/tebex-plugin-api)
|
|
4
|
+
[](https://github.com/heyxmirko/tebex-plugin-api/actions/workflows/ci.yml)
|
|
4
5
|
|
|
5
|
-
|
|
6
|
+
Unofficial, fully typed TypeScript SDK for the [Tebex Plugin API](https://docs.tebex.io/plugin) (also called the Game Server API).
|
|
7
|
+
Zero dependencies. Node 22+, Bun, Deno and edge runtimes.
|
|
6
8
|
|
|
7
|
-
|
|
9
|
+
Having to repeatedly write the same API calls for things like coupons, gift cards, and payments as part of commission work made me create this SDK to make things easier.
|
|
8
10
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
+
> **Server-side only.** Your secret key gives access to private store data. Call this from your backend and only return what's safe to show.
|
|
12
|
+
|
|
13
|
+
## Install
|
|
14
|
+
|
|
15
|
+
```sh
|
|
16
|
+
npm install tebex-plugin-api
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Usage
|
|
20
|
+
|
|
21
|
+
Get your secret key at [creator.tebex.io/game-servers](https://creator.tebex.io/game-servers) and set it as `TEBEX_SECRET`:
|
|
22
|
+
|
|
23
|
+
```ts
|
|
24
|
+
import { TebexClient } from "tebex-plugin-api";
|
|
25
|
+
|
|
26
|
+
const tebex = new TebexClient(); // reads TEBEX_SECRET (or pass { secret })
|
|
27
|
+
|
|
28
|
+
const goals = await tebex.communityGoals.list();
|
|
29
|
+
const payments = await tebex.payments.list({ limit: 10 });
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## Recipes
|
|
33
|
+
|
|
34
|
+
**Create a coupon**
|
|
35
|
+
|
|
36
|
+
```ts
|
|
37
|
+
const coupon = await tebex.coupons.create({
|
|
38
|
+
code: "SUMMER25",
|
|
39
|
+
effective_on: "cart",
|
|
40
|
+
discount_type: "percentage",
|
|
41
|
+
discount_percentage: 25,
|
|
42
|
+
redeem_unlimited: true,
|
|
43
|
+
expire_never: false,
|
|
44
|
+
expire_date: "2026-09-01",
|
|
45
|
+
start_date: "2026-06-01",
|
|
46
|
+
basket_type: "single",
|
|
47
|
+
});
|
|
11
48
|
```
|
|
12
49
|
|
|
13
|
-
|
|
50
|
+
**Issue and top up a gift card**
|
|
14
51
|
|
|
15
|
-
```
|
|
16
|
-
|
|
52
|
+
```ts
|
|
53
|
+
const card = await tebex.giftCards.create({ amount: 25, note: "Giveaway winner" });
|
|
54
|
+
await tebex.giftCards.topUp(card.id, 10);
|
|
17
55
|
```
|
|
18
56
|
|
|
19
|
-
|
|
57
|
+
**Create a manual payment**
|
|
20
58
|
|
|
21
|
-
```
|
|
22
|
-
|
|
59
|
+
```ts
|
|
60
|
+
const fields = await tebex.payments.requiredFields(1234); // option fields the package needs
|
|
61
|
+
|
|
62
|
+
await tebex.payments.create({
|
|
63
|
+
ign: "Notch",
|
|
64
|
+
price: 0,
|
|
65
|
+
packages: [{ id: 1234 }],
|
|
66
|
+
note: "Compensation",
|
|
67
|
+
});
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
**Loop through every payment**
|
|
71
|
+
|
|
72
|
+
```ts
|
|
73
|
+
let page = 1;
|
|
74
|
+
while (true) {
|
|
75
|
+
const result = await tebex.payments.listPaged(page++);
|
|
76
|
+
for (const payment of result.items) console.log(payment.id, payment.amount);
|
|
77
|
+
if (!result.hasNext) break;
|
|
78
|
+
}
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
**Handle errors**
|
|
82
|
+
|
|
83
|
+
```ts
|
|
84
|
+
import { TebexError } from "tebex-plugin-api";
|
|
85
|
+
|
|
86
|
+
try {
|
|
87
|
+
await tebex.giftCards.lookup("0000");
|
|
88
|
+
} catch (error) {
|
|
89
|
+
if (error instanceof TebexError) console.error(error.status, error.message);
|
|
90
|
+
else throw error;
|
|
91
|
+
}
|
|
23
92
|
```
|
|
93
|
+
|
|
94
|
+
## Good to know
|
|
95
|
+
|
|
96
|
+
- **Resources:** `information`, `communityGoals`, `payments`, `coupons`, `giftCards`, `bans`, `sales`, `players`, `checkout`, `packages`, `queue`.
|
|
97
|
+
- **Types match the API exactly** (snake_case, money as strings). Nothing is renamed.
|
|
98
|
+
- **Responses are tidied up:** `{ data }` wrappers are removed, and paginated endpoints return `{ items, page, lastPage, total, hasNext }`.
|
|
99
|
+
- **Payments include customer emails.** Don't send them to the browser.
|
|
100
|
+
- **Rate limit:** 500 requests per 5 minutes per secret. There are no automatic retries, so cache results in your app.
|
|
101
|
+
- **Timeouts and cancelling:** requests time out after 10s (`timeout` option), and every method accepts `{ signal }` as its last argument.
|
|
102
|
+
- **Listings and package reads** are deprecated by Tebex. Use the [Headless API](https://docs.tebex.io/developers/headless-api/introduction) for those.
|
|
103
|
+
|
|
104
|
+
## License
|
|
105
|
+
|
|
106
|
+
MIT
|