@hotbunny/hackhub-content-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hot Bunny Games
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,252 @@
+# @hotbunny/hackhub-content-sdk
+
+Type definitions and API reference for creating HackHub mods.
+
+This package provides **TypeScript types only** -- no runtime code. The game loads your compiled `mod.js` at startup; this package gives you autocompletion and type checking while developing.
+
+## Installation
+
+```bash
+npm install @hotbunny/hackhub-content-sdk --save-dev
+```
+
+## Mod Structure
+
+A HackHub mod is a folder inside the game's `mods/` directory:
+
+```
+mods/
+  my-first-mod/
+    manifest.json
+    mod.js
+```
+
+### manifest.json
+
+```json
+{
+    "id": "my-first-mod",
+    "name": "My First Mod",
+    "version": "1.0.0",
+    "author": "YourName",
+    "description": "A simple HackHub mod",
+    "entry": "mod.js",
+    "permissions": ["network", "files", "events"],
+    "dependencies": []
+}
+```
+
+### Source Code (TypeScript)
+
+Write your mod in TypeScript, then compile to a single `mod.js` bundle.
+
+```typescript
+import {
+    Bootstrap,
+    Quest,
+    Events,
+    Network,
+    RegisterModPackage,
+    RegisterQuest,
+} from "@hotbunny/hackhub-content-sdk";
+
+@RegisterModPackage()
+class MyMod extends Bootstrap {
+    OnModPackageLoaded() {
+        console.log("My mod loaded!");
+    }
+}
+
+@RegisterQuest()
+class MyQuest extends Quest {
+    definition = {
+        name: "MyQuest",
+        title: "My Custom Quest",
+        description: "A quest added by a mod.",
+        rewards: { money: 100 },
+        objectives: [
+            {
+                name: "scan",
+                description: "Scan the target",
+                trigger: {
+                    event: "Terminal.NmapScan",
+                    condition: (data) => data.ip === "10.0.0.1",
+                },
+            },
+        ],
+    };
+
+    OnStart() {
+        Network.createSubnetNetwork({
+            ip: "10.0.0.1",
+            type: "ROUTER",
+            ports: [{ external: 80, internal: 80, active: true, service: "http" }],
+            users: [Network.createUser({ username: "admin" })],
+            children: [],
+        });
+    }
+}
+```
+
+## API Overview
+
+### Base Classes
+
+| Class | Purpose |
+|-------|---------|
+| `Bootstrap` | Mod entry point, receives lifecycle callbacks |
+| `Quest` | Define custom quests with objectives and rewards |
+| `Website` | Add in-game websites to the browser |
+| `Command` | Register custom terminal commands |
+| `App` | Create desktop applications |
+
+### API Namespaces
+
+| Namespace | Purpose |
+|-----------|---------|
+| `Events` | Listen to game events, emit custom cross-mod events |
+| `Files` | Create, read, write, delete files in the game filesystem |
+| `Network` | Create networks, manage ports, firewalls, domains |
+| `Mail` | Send in-game emails |
+| `Bank` | Manage bank transactions |
+| `Storage` | Persistent key-value storage (per-mod) |
+| `Variables` | Session-only variables (per-mod, reset on game close) |
+| `SharedStorage` | Persistent storage shared between mods |
+| `SharedVariables` | Session variables shared between mods |
+| `Shell` | Execute terminal commands programmatically |
+| `UI` | Show notifications and toasts |
+| `Twotter` | In-game Twitter -- create users, post tweets |
+| `Kisscord` | In-game Discord -- create users, send messages |
+| `WeeChat` | In-game IRC -- create servers, send messages |
+
+### Decorators
+
+```typescript
+@RegisterModPackage()   // Register the mod's Bootstrap class
+@RegisterQuest()        // Register a Quest
+@RegisterWebsite()      // Register a Website
+@RegisterCommand()      // Register a terminal Command
+@RegisterApp()          // Register a desktop App
+```
+
+## Events
+
+### Listening to Game Events
+
+```typescript
+import { Events } from "@hotbunny/hackhub-content-sdk";
+
+Events.on("Terminal.NmapScan", (data) => {
+    console.log(`Player scanned ${data.ip}`);
+});
+
+Events.on("Kisscord.Messaging", (data) => {
+    console.log(`Message on channel ${data.channel}`);
+});
+```
+
+### Custom Cross-Mod Events
+
+Register and emit your own typed events that other mods can listen to:
+
+```typescript
+// In your mod's type declarations
+declare module "@hotbunny/hackhub-content-sdk" {
+    interface ModEventMap {
+        "MyMod.BossDefeated": { bossName: string; reward: number };
+    }
+}
+
+// Emit
+Events.register("MyMod.BossDefeated");
+Events.emit("MyMod.BossDefeated", { bossName: "Hydra", reward: 500 });
+
+// Another mod can listen (with full type safety)
+Events.on("MyMod.BossDefeated", (data) => {
+    console.log(`Boss ${data.bossName} defeated! Reward: ${data.reward}`);
+});
+```
+
+## Messaging APIs
+
+### Twotter (in-game Twitter)
+
+```typescript
+import { Twotter } from "@hotbunny/hackhub-content-sdk";
+
+const user = Twotter.createUser({
+    username: "darknet_hacker",
+    bio: "I hack things.",
+    verified: true,
+});
+Twotter.addUser(user);
+
+Twotter.postTweet({
+    id: "my-tweet-1",
+    userId: user.id,
+    content: "Just breached the mainframe!",
+    interaction: { comments: 5, share: 2, likes: 42, views: 1000 },
+    showInTimeline: true,
+});
+```
+
+### Kisscord (in-game Discord)
+
+```typescript
+import { Kisscord, KisscordStatus } from "@hotbunny/hackhub-content-sdk";
+
+const npc = Kisscord.createUser({
+    username: "informant",
+    firstName: "John",
+    lastName: "Doe",
+    isFriend: true,
+    status: KisscordStatus.Online,
+});
+Kisscord.addUser(npc);
+Kisscord.sendMessage(npc.id, "I have the files you need.");
+```
+
+### WeeChat (in-game IRC)
+
+```typescript
+import { WeeChat } from "@hotbunny/hackhub-content-sdk";
+
+WeeChat.createServer("irc.darknet.org", "secret123");
+WeeChat.sendMessage({
+    host: "irc.darknet.org",
+    username: "informant",
+    message: "The target IP is 45.33.32.156",
+});
+```
+
+## Building Your Mod
+
+Use [esbuild](https://esbuild.github.io/) to compile your TypeScript source into a single `mod.js`:
+
+```bash
+npx esbuild src/index.ts --bundle --outfile=mod.js --format=cjs --platform=browser --target=es2020 --external:@hotbunny/hackhub-content-sdk
+```
+
+The `--external` flag is important: the game provides the SDK at runtime, so it must not be bundled into your mod.
+
+### tsconfig.json (recommended)
+
+```json
+{
+    "compilerOptions": {
+        "target": "ES2020",
+        "module": "ESNext",
+        "moduleResolution": "bundler",
+        "strict": true,
+        "experimentalDecorators": true,
+        "emitDecoratorMetadata": true,
+        "esModuleInterop": true,
+        "skipLibCheck": true
+    },
+    "include": ["src/**/*.ts"]
+}
+```
+
+## License
+
+MIT