@s2script/sdk 0.18.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s2script/sdk",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "license": "MIT OR Apache-2.0",
   "description": "s2script SDK — the builtin capability types (imported as @s2script/sdk/entity, …) plus the `s2s` CLI for building Source 2 / CS2 plugins.",
   "type": "module",

package/ws.d.ts

@@ -13,17 +13,36 @@ export interface WebSocket {
   /** Close the connection. */
   close(): void;
 }
+/** Options for {@link WebSocket.connect}. */
+export interface WebSocketInit {
+  /**
+   * Extra headers to send on the opening handshake — the usual reason being a
+   * credential the server requires, e.g. `Authorization: Bearer <token>`.
+   *
+   * Headers the handshake owns are refused, and the connect rejects rather than
+   * silently dropping them: `Host`, `Connection`, `Upgrade`, any
+   * `Sec-WebSocket-*`, `Content-Length`, `Transfer-Encoding`. Values containing
+   * control characters are refused for the same reason.
+   */
+  headers?: Record<string, string>;
+}
+
 /** Entry point for opening WebSocket connections. */
 export declare const WebSocket: {
   /**
    * Connect to a WebSocket server (`wss://` for TLS) off the game thread.
    * @returns Resolves on the open handshake with the live {@link WebSocket} handle.
-   * @throws Rejects on connect failure (bad URL, refused, TLS/handshake error).
+   * @throws Rejects on connect failure (bad URL, refused, TLS/handshake error, or a refused header).
    * @example
    * import { WebSocket } from "@s2script/sdk/ws";
    * const ws = await WebSocket.connect("wss://ws.postman-echo.com/raw");
    * ws.onMessage((data) => { console.log("echo:", data); ws.close(); });
    * ws.send("hello-from-s2script");
+   * @example
+   * // A server that authenticates the handshake rather than the first frame.
+   * const ws = await WebSocket.connect("wss://maul.example/v2/ws", {
+   *   headers: { Authorization: `Bearer ${jwt}` },
+   * });
    */
-  connect(url: string): Promise<WebSocket>;
+  connect(url: string, init?: WebSocketInit): Promise<WebSocket>;
 };