angela-sdk 0.1.2 → 0.2.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 +76 -11
- package/dist/cjs/index.js +28 -1
- package/dist/esm/index.js +28 -1
- package/dist/types/index.d.ts +2 -2
- package/dist/types/ui.d.ts +44 -0
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -57,7 +57,7 @@ Zero external production dependencies. Requires Node 18+ for local tooling.
|
|
|
57
57
|
In `src/index.ts`:
|
|
58
58
|
|
|
59
59
|
```typescript
|
|
60
|
-
import { Game, Button, type Context } from "
|
|
60
|
+
import { Game, Button, type Context } from "angela-sdk";
|
|
61
61
|
|
|
62
62
|
const game = new Game("dice_game");
|
|
63
63
|
|
|
@@ -122,7 +122,7 @@ export function handle(eventStr: string): string {
|
|
|
122
122
|
In `main.js`:
|
|
123
123
|
|
|
124
124
|
```javascript
|
|
125
|
-
const { Game, Button } = require("
|
|
125
|
+
const { Game, Button } = require("angela-sdk");
|
|
126
126
|
|
|
127
127
|
const game = new Game("coin_toss");
|
|
128
128
|
|
|
@@ -373,7 +373,7 @@ ctx.inventory.removeSubItem(ctx.user.id, "sapphire_sardine", 1);
|
|
|
373
373
|
`ctx.ui.render()` compiles your layout automatically into the mode configured by the server (`AUTO`, `CV2`, or `CLASSIC_EMBED`):
|
|
374
374
|
|
|
375
375
|
```typescript
|
|
376
|
-
import { Button } from "
|
|
376
|
+
import { Button } from "angela-sdk";
|
|
377
377
|
|
|
378
378
|
ctx.ui.render({
|
|
379
379
|
title: "⚔️ Boss Raid: Abyssal Hydra",
|
|
@@ -405,7 +405,7 @@ import {
|
|
|
405
405
|
Separator,
|
|
406
406
|
ActionRow,
|
|
407
407
|
Button
|
|
408
|
-
} from "
|
|
408
|
+
} from "angela-sdk";
|
|
409
409
|
|
|
410
410
|
const container = new Container({ accentColor: "#5865F2" })
|
|
411
411
|
.add(
|
|
@@ -431,7 +431,7 @@ ctx.ui.renderCv2(container);
|
|
|
431
431
|
### Classic Embeds
|
|
432
432
|
|
|
433
433
|
```typescript
|
|
434
|
-
import { Embed, Button } from "
|
|
434
|
+
import { Embed, Button } from "angela-sdk";
|
|
435
435
|
|
|
436
436
|
const embed = new Embed({
|
|
437
437
|
title: "🎣 Catch of the Day",
|
|
@@ -450,7 +450,7 @@ ctx.ui.renderEmbed(embed, [
|
|
|
450
450
|
### Modals & Ephemeral Feedback
|
|
451
451
|
|
|
452
452
|
```typescript
|
|
453
|
-
import { TextInput } from "
|
|
453
|
+
import { TextInput } from "angela-sdk";
|
|
454
454
|
|
|
455
455
|
// Open modal
|
|
456
456
|
game.onButton("open_wager", (ctx) => {
|
|
@@ -473,6 +473,33 @@ game.onModal("wager_submitted", (ctx) => {
|
|
|
473
473
|
});
|
|
474
474
|
```
|
|
475
475
|
|
|
476
|
+
### Public Chat Delivery (`sendChat` vs `EDIT_MAIN`)
|
|
477
|
+
|
|
478
|
+
By default, games edit the existing game message (`target: "EDIT_MAIN"`). This keeps card tables, boards, and casino wheels compact without spamming Discord channels.
|
|
479
|
+
|
|
480
|
+
For games that announce new rounds, post trivia questions, or announce server-wide events, use `ctx.ui.sendChat(...)` or set `target: "NEW_MESSAGE"`:
|
|
481
|
+
|
|
482
|
+
```typescript
|
|
483
|
+
// Helper: sends a brand new public message to the channel
|
|
484
|
+
ctx.ui.sendChat({
|
|
485
|
+
title: "🧠 Trivia Round 1",
|
|
486
|
+
text: "What is the capital of Australia?",
|
|
487
|
+
buttons: [
|
|
488
|
+
new Button({ customId: "ans_canberra", label: "Canberra", style: "primary" }),
|
|
489
|
+
new Button({ customId: "ans_sydney", label: "Sydney", style: "secondary" }),
|
|
490
|
+
]
|
|
491
|
+
});
|
|
492
|
+
|
|
493
|
+
// Or using string shorthand:
|
|
494
|
+
ctx.ui.sendChat("⚔️ The boss has spawned! Click below to join the raid!");
|
|
495
|
+
```
|
|
496
|
+
|
|
497
|
+
| Method / Target | Visibility | Replaces Previous? | Best Used For |
|
|
498
|
+
|---|---|---|---|
|
|
499
|
+
| `target: "EDIT_MAIN"` (Default) | Public | Yes (Edits main message) | Lobbies, boards, scoreboards, casino wheels |
|
|
500
|
+
| `ctx.ui.sendChat(...)` / `target: "NEW_MESSAGE"` | Public | No (Sends new message) | Trivia rounds, event announcements, elimination logs |
|
|
501
|
+
| `ctx.ui.replyEphemeral(...)` | Only Clicker | No (Private reply) | Secret hands, balance checks, validation errors |
|
|
502
|
+
|
|
476
503
|
---
|
|
477
504
|
|
|
478
505
|
## 2D Canvas Graphics Engine
|
|
@@ -495,7 +522,7 @@ const scene = ctx.canvas.create({
|
|
|
495
522
|
Setting a `cacheKey` on static background layers caches the rendered graphic on disk — future turns skip all background pixel rendering and composite dynamic elements directly on top:
|
|
496
523
|
|
|
497
524
|
```typescript
|
|
498
|
-
import { Button } from "
|
|
525
|
+
import { Button } from "angela-sdk";
|
|
499
526
|
|
|
500
527
|
// Static background layer (cached on disk)
|
|
501
528
|
const bg = scene.layer("background", "ocean_base_v1");
|
|
@@ -626,18 +653,56 @@ ctx.media.searchGif("victory celebration", "on_gif_found");
|
|
|
626
653
|
|
|
627
654
|
---
|
|
628
655
|
|
|
629
|
-
## HTTP &
|
|
656
|
+
## HTTP & Safe Network Access
|
|
657
|
+
|
|
658
|
+
### Safe Outbound HTTP (`ctx.http.get` / `ctx.http.post`)
|
|
630
659
|
|
|
631
|
-
|
|
660
|
+
Angela games execute inside a secure WebAssembly (WASM) sandbox. Because the sandbox **does not possess raw POSIX OS sockets**, synchronous network calls (such as `fetch`, `axios`, `got`, or `node:http`) **cannot run** and will fail.
|
|
661
|
+
|
|
662
|
+
All network requests must be requested through Angela's host-mediated **two-phase HTTP gateway**:
|
|
663
|
+
1. **Phase 1 (Request)**: Your cartridge registers an intent via `ctx.http.get(url, { callback: "handler_name" })`.
|
|
664
|
+
2. **Phase 2 (Callback)**: Angela's host verifies SSRF policy, queries the API safely, and delivers parsed JSON to `ctx.args.callbackData`.
|
|
632
665
|
|
|
633
666
|
```typescript
|
|
634
667
|
game.onCommand("trivia", (ctx) => {
|
|
635
|
-
|
|
668
|
+
// Phase 1: Request data via host proxy
|
|
669
|
+
ctx.http.get("https://the-trivia-api.com/v2/questions?limit=1", {
|
|
636
670
|
callback: "on_trivia_received"
|
|
637
671
|
});
|
|
638
672
|
});
|
|
673
|
+
|
|
674
|
+
game.onCallback("on_trivia_received", (ctx) => {
|
|
675
|
+
// Phase 2: Host delivers payload
|
|
676
|
+
const questions = ctx.args.callbackData as any[];
|
|
677
|
+
if (questions && questions.length > 0) {
|
|
678
|
+
const q = questions[0];
|
|
679
|
+
ctx.ui.sendChat({
|
|
680
|
+
title: "🧠 Question Time!",
|
|
681
|
+
text: q.question.text,
|
|
682
|
+
buttons: [
|
|
683
|
+
new Button({ customId: "ans_correct", label: q.correctAnswer, style: "primary" }),
|
|
684
|
+
new Button({ customId: "ans_wrong", label: q.incorrectAnswers[0], style: "secondary" }),
|
|
685
|
+
]
|
|
686
|
+
});
|
|
687
|
+
}
|
|
688
|
+
});
|
|
639
689
|
```
|
|
640
690
|
|
|
691
|
+
---
|
|
692
|
+
|
|
693
|
+
## Sandboxing & Dependency Constraints
|
|
694
|
+
|
|
695
|
+
To guarantee zero latency spikes, airtight security, and deterministic runs across all Discord nodes:
|
|
696
|
+
|
|
697
|
+
1. **Pure JavaScript / TypeScript**: Cartridges must use standard JS built-ins (Arrays, Maps, Math, JSON, Date, RegExp).
|
|
698
|
+
2. **No Native C/C++ Addons**: Node addons (`.node` binaries) or packages relying on libuv/native OS handles (`fs`, `net`, `child_process`) are not supported in WASM.
|
|
699
|
+
3. **Official SDK Only**: Only import `angela-sdk`. All interactions with Discord, player balances, inventory, and network go through `ctx`.
|
|
700
|
+
4. **State Persistence**: Cartridges cannot write to local disk. State across turns is stored in `ctx.state` or `ctx.storage`.
|
|
701
|
+
|
|
702
|
+
---
|
|
703
|
+
|
|
704
|
+
## Discord Utilities
|
|
705
|
+
|
|
641
706
|
### Channel Management & Chat Listening
|
|
642
707
|
|
|
643
708
|
```typescript
|
|
@@ -665,7 +730,7 @@ my_game/
|
|
|
665
730
|
├── manifest.json # Game metadata, config schema, target slot
|
|
666
731
|
├── src/
|
|
667
732
|
│ └── index.ts # TypeScript entry script exporting handle
|
|
668
|
-
├── package.json # Dependencies (devDependencies:
|
|
733
|
+
├── package.json # Dependencies (devDependencies: angela-sdk, typescript)
|
|
669
734
|
└── assets/ # Game sprites referenced by ctx.canvas.sprite()
|
|
670
735
|
├── boss.png
|
|
671
736
|
└── coin.png
|
package/dist/cjs/index.js
CHANGED
|
@@ -1067,11 +1067,38 @@ var UIContext = class {
|
|
|
1067
1067
|
this.ctx.addIntent(intent);
|
|
1068
1068
|
return intent;
|
|
1069
1069
|
}
|
|
1070
|
+
sendChat(textOrOptions) {
|
|
1071
|
+
if (typeof textOrOptions === "string") {
|
|
1072
|
+
return this.render({ bodyLines: [textOrOptions], ephemeral: false, target: "NEW_MESSAGE" });
|
|
1073
|
+
}
|
|
1074
|
+
if (textOrOptions.embed) {
|
|
1075
|
+
return this.renderEmbed(textOrOptions.embed, {
|
|
1076
|
+
components: textOrOptions.buttons,
|
|
1077
|
+
ephemeral: false,
|
|
1078
|
+
target: "NEW_MESSAGE"
|
|
1079
|
+
});
|
|
1080
|
+
}
|
|
1081
|
+
return this.render({
|
|
1082
|
+
title: textOrOptions.title,
|
|
1083
|
+
subtitle: textOrOptions.subtitle,
|
|
1084
|
+
bodyLines: textOrOptions.text ? [textOrOptions.text] : [],
|
|
1085
|
+
buttons: textOrOptions.buttons,
|
|
1086
|
+
selects: textOrOptions.selects,
|
|
1087
|
+
image: textOrOptions.image,
|
|
1088
|
+
thumbnail: textOrOptions.thumbnail,
|
|
1089
|
+
accentColor: textOrOptions.accentColor,
|
|
1090
|
+
ephemeral: false,
|
|
1091
|
+
target: "NEW_MESSAGE"
|
|
1092
|
+
});
|
|
1093
|
+
}
|
|
1094
|
+
sendMessage = this.sendChat.bind(this);
|
|
1070
1095
|
// Snake_case aliases
|
|
1071
1096
|
render_cv2 = this.renderCv2.bind(this);
|
|
1072
1097
|
render_embed = this.renderEmbed.bind(this);
|
|
1073
1098
|
reply_ephemeral = this.replyEphemeral.bind(this);
|
|
1074
1099
|
open_modal = this.openModal.bind(this);
|
|
1100
|
+
send_chat = this.sendChat.bind(this);
|
|
1101
|
+
send_message = this.sendMessage.bind(this);
|
|
1075
1102
|
};
|
|
1076
1103
|
|
|
1077
1104
|
// src/context.ts
|
|
@@ -1335,7 +1362,7 @@ function dispatch(handler, event) {
|
|
|
1335
1362
|
}
|
|
1336
1363
|
|
|
1337
1364
|
// src/index.ts
|
|
1338
|
-
var VERSION = "0.
|
|
1365
|
+
var VERSION = "0.2.0";
|
|
1339
1366
|
// Annotate the CommonJS export names for ESM import in node:
|
|
1340
1367
|
0 && (module.exports = {
|
|
1341
1368
|
AIContext,
|
package/dist/esm/index.js
CHANGED
|
@@ -1010,11 +1010,38 @@ var UIContext = class {
|
|
|
1010
1010
|
this.ctx.addIntent(intent);
|
|
1011
1011
|
return intent;
|
|
1012
1012
|
}
|
|
1013
|
+
sendChat(textOrOptions) {
|
|
1014
|
+
if (typeof textOrOptions === "string") {
|
|
1015
|
+
return this.render({ bodyLines: [textOrOptions], ephemeral: false, target: "NEW_MESSAGE" });
|
|
1016
|
+
}
|
|
1017
|
+
if (textOrOptions.embed) {
|
|
1018
|
+
return this.renderEmbed(textOrOptions.embed, {
|
|
1019
|
+
components: textOrOptions.buttons,
|
|
1020
|
+
ephemeral: false,
|
|
1021
|
+
target: "NEW_MESSAGE"
|
|
1022
|
+
});
|
|
1023
|
+
}
|
|
1024
|
+
return this.render({
|
|
1025
|
+
title: textOrOptions.title,
|
|
1026
|
+
subtitle: textOrOptions.subtitle,
|
|
1027
|
+
bodyLines: textOrOptions.text ? [textOrOptions.text] : [],
|
|
1028
|
+
buttons: textOrOptions.buttons,
|
|
1029
|
+
selects: textOrOptions.selects,
|
|
1030
|
+
image: textOrOptions.image,
|
|
1031
|
+
thumbnail: textOrOptions.thumbnail,
|
|
1032
|
+
accentColor: textOrOptions.accentColor,
|
|
1033
|
+
ephemeral: false,
|
|
1034
|
+
target: "NEW_MESSAGE"
|
|
1035
|
+
});
|
|
1036
|
+
}
|
|
1037
|
+
sendMessage = this.sendChat.bind(this);
|
|
1013
1038
|
// Snake_case aliases
|
|
1014
1039
|
render_cv2 = this.renderCv2.bind(this);
|
|
1015
1040
|
render_embed = this.renderEmbed.bind(this);
|
|
1016
1041
|
reply_ephemeral = this.replyEphemeral.bind(this);
|
|
1017
1042
|
open_modal = this.openModal.bind(this);
|
|
1043
|
+
send_chat = this.sendChat.bind(this);
|
|
1044
|
+
send_message = this.sendMessage.bind(this);
|
|
1018
1045
|
};
|
|
1019
1046
|
|
|
1020
1047
|
// src/context.ts
|
|
@@ -1278,7 +1305,7 @@ function dispatch(handler, event) {
|
|
|
1278
1305
|
}
|
|
1279
1306
|
|
|
1280
1307
|
// src/index.ts
|
|
1281
|
-
var VERSION = "0.
|
|
1308
|
+
var VERSION = "0.2.0";
|
|
1282
1309
|
export {
|
|
1283
1310
|
AIContext,
|
|
1284
1311
|
ActionRow,
|
package/dist/types/index.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Angela TypeScript & JavaScript SDK (
|
|
2
|
+
* Angela TypeScript & JavaScript SDK (angela-sdk)
|
|
3
3
|
* The official developer kit for Angela Games Ecosystem cartridges.
|
|
4
4
|
*/
|
|
5
5
|
export * from "./ai.js";
|
|
@@ -12,4 +12,4 @@ export * from "./inventory.js";
|
|
|
12
12
|
export * from "./lobby.js";
|
|
13
13
|
export * from "./models.js";
|
|
14
14
|
export * from "./ui.js";
|
|
15
|
-
export declare const VERSION = "0.
|
|
15
|
+
export declare const VERSION = "0.2.0";
|
package/dist/types/ui.d.ts
CHANGED
|
@@ -196,6 +196,28 @@ export declare class UIContext {
|
|
|
196
196
|
container?: Container;
|
|
197
197
|
}): Intent;
|
|
198
198
|
openModal(title: string, inputs: (TextInput | Record<string, unknown>)[], callbackId: string): Intent;
|
|
199
|
+
sendChat(textOrOptions: string | {
|
|
200
|
+
text?: string;
|
|
201
|
+
title?: string;
|
|
202
|
+
subtitle?: string;
|
|
203
|
+
buttons?: (Button | Record<string, unknown>)[];
|
|
204
|
+
selects?: (Select | Record<string, unknown>)[];
|
|
205
|
+
embed?: Embed | Record<string, unknown>;
|
|
206
|
+
image?: string | CanvasScene;
|
|
207
|
+
thumbnail?: string;
|
|
208
|
+
accentColor?: string | number;
|
|
209
|
+
}): Intent;
|
|
210
|
+
sendMessage: (textOrOptions: string | {
|
|
211
|
+
text?: string;
|
|
212
|
+
title?: string;
|
|
213
|
+
subtitle?: string;
|
|
214
|
+
buttons?: (Button | Record<string, unknown>)[];
|
|
215
|
+
selects?: (Select | Record<string, unknown>)[];
|
|
216
|
+
embed?: Embed | Record<string, unknown>;
|
|
217
|
+
image?: string | CanvasScene;
|
|
218
|
+
thumbnail?: string;
|
|
219
|
+
accentColor?: string | number;
|
|
220
|
+
}) => Intent;
|
|
199
221
|
render_cv2: (container: Container | Record<string, unknown>, options?: {
|
|
200
222
|
ephemeral?: boolean;
|
|
201
223
|
target?: string;
|
|
@@ -213,4 +235,26 @@ export declare class UIContext {
|
|
|
213
235
|
container?: Container;
|
|
214
236
|
}) => Intent;
|
|
215
237
|
open_modal: (title: string, inputs: (TextInput | Record<string, unknown>)[], callbackId: string) => Intent;
|
|
238
|
+
send_chat: (textOrOptions: string | {
|
|
239
|
+
text?: string;
|
|
240
|
+
title?: string;
|
|
241
|
+
subtitle?: string;
|
|
242
|
+
buttons?: (Button | Record<string, unknown>)[];
|
|
243
|
+
selects?: (Select | Record<string, unknown>)[];
|
|
244
|
+
embed?: Embed | Record<string, unknown>;
|
|
245
|
+
image?: string | CanvasScene;
|
|
246
|
+
thumbnail?: string;
|
|
247
|
+
accentColor?: string | number;
|
|
248
|
+
}) => Intent;
|
|
249
|
+
send_message: (textOrOptions: string | {
|
|
250
|
+
text?: string;
|
|
251
|
+
title?: string;
|
|
252
|
+
subtitle?: string;
|
|
253
|
+
buttons?: (Button | Record<string, unknown>)[];
|
|
254
|
+
selects?: (Select | Record<string, unknown>)[];
|
|
255
|
+
embed?: Embed | Record<string, unknown>;
|
|
256
|
+
image?: string | CanvasScene;
|
|
257
|
+
thumbnail?: string;
|
|
258
|
+
accentColor?: string | number;
|
|
259
|
+
}) => Intent;
|
|
216
260
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "angela-sdk",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Official TypeScript & JavaScript SDK for Angela Games Ecosystem cartridges",
|
|
6
6
|
"main": "./dist/cjs/index.js",
|
|
@@ -41,6 +41,7 @@
|
|
|
41
41
|
"keywords": [
|
|
42
42
|
"angela",
|
|
43
43
|
"discord",
|
|
44
|
+
"custom",
|
|
44
45
|
"games",
|
|
45
46
|
"sdk",
|
|
46
47
|
"wasm",
|