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 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 "@angela/sdk";
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("@angela/sdk");
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 "@angela/sdk";
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 "@angela/sdk";
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 "@angela/sdk";
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 "@angela/sdk";
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 "@angela/sdk";
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 & Discord Utilities
656
+ ## HTTP & Safe Network Access
657
+
658
+ ### Safe Outbound HTTP (`ctx.http.get` / `ctx.http.post`)
630
659
 
631
- ### Safe Outbound HTTP
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
- ctx.http.get("https://opentdb.com/api.php?amount=1&type=multiple", {
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: @angela/sdk, typescript)
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.1.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.1.0";
1308
+ var VERSION = "0.2.0";
1282
1309
  export {
1283
1310
  AIContext,
1284
1311
  ActionRow,
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Angela TypeScript & JavaScript SDK (@angela/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.1.0";
15
+ export declare const VERSION = "0.2.0";
@@ -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.1.2",
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",