@s2script/sdk 0.25.1 → 0.26.0

package/http.d.ts

@@ -1,3 +1,4 @@
+/** Async calls reject with AsyncQueueFull or AsyncPayloadTooLarge before acceptance. Responses exceeding the configured retained UTF-8/header limit reject with HttpResponseTooLarge. */
 /** @s2script/http — async HTTP. NO runtime code (injected as __s2pkg_http). */
 
 /** Options for {@link fetch}. */

package/interfaces.d.ts

@@ -1,3 +1,4 @@
+import type { HookResultValue } from "./events";
 /**
  * @s2script/interfaces — author-time type stubs for typed inter-plugin interfaces.
  * NO runtime code: the engine injects the implementation at load time.
@@ -18,3 +19,122 @@ export interface PublishHandle {
    */
   emit(event: string, payload: unknown): void;
 }
+
+/** Type-only protocol 2 descriptor. Payloads must belong to the supported wire algebra. */
+export interface Notification<P> {
+  readonly __notificationPayload: P;
+}
+/** Synchronous decision forward. Changed does not imply payload mutation. */
+export interface Hook<P> {
+  readonly __hookPayload: P;
+}
+/** Synchronous shallow transformation; only W fields may be patched. */
+export interface Transform<P extends object, W extends keyof P> {
+  readonly __transformPayload: P;
+  readonly __transformWritable: W;
+}
+export type TransformResponse<P, W extends keyof P> =
+  | { result: 1; patch?: Partial<Pick<P, W>> }
+  | { result: Exclude<HookResultValue, 1>; patch?: never };
+/** CLI-generated association; an authored augmentation cannot authorize a build. */
+export interface InterfaceContracts {}
+export type ContractMethods<C> = C extends { methods: infer M extends object }
+  ? M
+  : never;
+export type ContractForwards<C> = C extends { forwards: infer F } ? F : never;
+export type NotificationPayload<D> = D extends Notification<infer P>
+  ? P
+  : never;
+export type ForwardPayload<D> = D extends Notification<infer P>
+  ? P
+  : D extends Hook<infer P>
+  ? P
+  : D extends Transform<infer P, infer W>
+  ? P
+  : never;
+export type ForwardResponse<D> = D extends Notification<infer P>
+  ? void
+  : D extends Hook<infer P>
+  ? HookResultValue
+  : D extends Transform<infer P, infer W>
+  ? TransformResponse<P, W>
+  : never;
+type ForwardNames<C, Mode> = {
+  [K in keyof ContractForwards<C>]: ContractForwards<C>[K] extends Mode
+    ? K
+    : never;
+}[keyof ContractForwards<C>] &
+  string;
+export type DispatchResponse<D> = D extends Hook<unknown>
+  ? HookResultValue
+  : D extends { readonly __transformPayload: object }
+  ? { result: HookResultValue; payload: ForwardPayload<D> }
+  : never;
+export type TypedPublishHandle<C> = {
+  emit<K extends ForwardNames<C, Notification<unknown>>>(
+    event: K,
+    payload: ForwardPayload<ContractForwards<C>[K]>
+  ): void;
+  dispatch<
+    K extends ForwardNames<
+      C,
+      Hook<unknown> | { readonly __transformPayload: object }
+    >
+  >(
+    event: K,
+    payload: ForwardPayload<ContractForwards<C>[K]>
+  ): DispatchResponse<ContractForwards<C>[K]>;
+};
+type ExtraPatchKeys<Patch, W> = Patch extends unknown
+  ? Exclude<keyof Patch, W>
+  : never;
+type ExtraResponseKeys<R, W> = R extends unknown
+  ?
+      | Exclude<keyof R, "result" | "patch">
+      | (R extends { patch?: infer Patch } ? ExtraPatchKeys<Patch, W> : never)
+  : never;
+type ExactForwardHandler<D, R> = D extends Transform<infer P, infer W>
+  ? ExtraResponseKeys<R, W> extends never
+    ? unknown
+    : never
+  : unknown;
+/** Provider forward names mapped to handlers with their exact payload and result types. */
+export type ForwardHandlers<C> = {
+  [K in keyof ContractForwards<C>]?: (
+    payload: ForwardPayload<ContractForwards<C>[K]>
+  ) => ForwardResponse<ContractForwards<C>[K]>;
+};
+/** Rejects keys and transform response fields outside the selected provider contract. */
+export type ExactForwardHandlers<
+  C,
+  H extends ForwardHandlers<C>
+> = H & {
+  [K in keyof H]: K extends keyof ContractForwards<C>
+    ? NonNullable<H[K]> extends (...args: never[]) => unknown
+      ? ExactForwardHandler<
+          ContractForwards<C>[K],
+          ReturnType<Extract<H[K], (...args: never[]) => unknown>>
+        >
+      : never
+    : never;
+} & {
+  [K in Exclude<keyof H, keyof ContractForwards<C>>]: never;
+};
+export type TypedInterfaceHandle<C> = ContractMethods<C> & {
+  on<
+    K extends keyof ContractForwards<C> & string,
+    H extends (
+      payload: ForwardPayload<ContractForwards<C>[K]>
+    ) => ForwardResponse<ContractForwards<C>[K]>
+  >(
+    event: K,
+    handler: H & ExactForwardHandler<ContractForwards<C>[K], ReturnType<H>>
+  ): Subscription;
+};
+
+/** A consumer-owned registration. Repeated disposal is a no-op. */
+export interface Subscription { dispose(): void; }
+/** Resources owned by one synchronous optional-provider attachment. */
+export interface AttachmentScope {
+  own<T extends { dispose(): void }>(resource: T): T;
+}

package/net.d.ts

@@ -2,8 +2,8 @@
 
 /** A connected TCP client socket — a per-plugin handle over a copied byte stream (no live socket crosses to JS). */
 export interface TcpSocket {
-  /** Send bytes; a `string` is sent as its UTF-8 encoding. */
-  send(data: Uint8Array | string): void;
+  /** Send bytes; a `string` is sent as its UTF-8 encoding. Returns false on closed/oversized/full admission. */
+  send(data: Uint8Array | string): boolean;
   /** Register a handler invoked for each inbound chunk of bytes. */
   onData(handler: (bytes: Uint8Array) => void): void;
   /** Register a handler for the peer closing the connection. */
@@ -15,8 +15,8 @@ export interface TcpSocket {
 }
 /** A bound UDP socket — a per-plugin handle for connectionless datagrams. */
 export interface UdpSocket {
-  /** Send a datagram to `host:port`; a `string` is sent as its UTF-8 encoding. */
-  sendTo(host: string, port: number, data: Uint8Array | string): void;
+  /** Send a datagram to `host:port`; a `string` is sent as its UTF-8 encoding. Returns false on closed/oversized/full admission. */
+  sendTo(host: string, port: number, data: Uint8Array | string): boolean;
   /** Register a handler invoked for each inbound datagram; `from` is the sender's address. */
   onMessage(handler: (from: { host: string; port: number }, bytes: Uint8Array) => void): void;
   /** Close the socket. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s2script/sdk",
-  "version": "0.25.1",
+  "version": "0.26.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/plugin.d.ts

@@ -1,3 +1,13 @@
+import type {
+  InterfaceContracts,
+  ContractMethods,
+  TypedPublishHandle,
+  TypedInterfaceHandle,
+  Subscription,
+  AttachmentScope,
+  ForwardHandlers,
+  ExactForwardHandlers,
+} from "./interfaces";
 /**
  * @s2script/sdk/plugin — load-window authoring (`hook`, `publish`, `translations`, `Scope`)
  * and the internal load-scoped {@link PluginContext} types. NO runtime code: the engine injects
@@ -52,20 +62,44 @@ export interface CtxClients {
   /** A client's persisted cookies finished loading and are now readable. */
   onCookiesCached(handler: (client: Client) => void): void;
   /** A client sent chat: return a {@link HookResultValue} to suppress it. @param teamonly - team-channel say. */
-  onSay(handler: (slot: number, text: string, teamonly: boolean) => HookResultValue | void): void;
+  onSay(
+    handler: (
+      slot: number,
+      text: string,
+      teamonly: boolean
+    ) => HookResultValue | void
+  ): void;
   /** Per-tick usercmd hook (SM `OnPlayerRunCmd`): read/modify {@link UserCmdView}; return `Handled` to block the tick. */
-  onRunCmd(handler: (cmd: UserCmdView, info: { slot: number }) => HookResultValue | void): void;
+  onRunCmd(
+    handler: (
+      cmd: UserCmdView,
+      info: { slot: number }
+    ) => HookResultValue | void
+  ): void;
 }
 /** Entity lifecycle / I/O subscriptions on this plugin's load-scope ({@link PluginContext.entities}). */
 export interface CtxEntities {
   /** An entity of `className` was created (not yet spawned). @param className - match, or `"*"` for all. */
-  onCreate(className: string, handler: (entity: EntityRef | null, className: string) => void): void;
+  onCreate(
+    className: string,
+    handler: (entity: EntityRef | null, className: string) => void
+  ): void;
   /** An entity of `className` spawned (post-`DispatchSpawn`). */
-  onSpawn(className: string, handler: (entity: EntityRef | null, className: string) => void): void;
+  onSpawn(
+    className: string,
+    handler: (entity: EntityRef | null, className: string) => void
+  ): void;
   /** An entity of `className` is being deleted; the ref goes stale right after. */
-  onDelete(className: string, handler: (entity: EntityRef | null, className: string) => void): void;
+  onDelete(
+    className: string,
+    handler: (entity: EntityRef | null, className: string) => void
+  ): void;
   /** Hook a named entity output (`FireOutputInternal`); return a {@link HookResultValue} to suppress it. */
-  onOutput(classname: string, output: string, handler: (ev: OutputEvent) => HookResultValue | void): void;
+  onOutput(
+    classname: string,
+    output: string,
+    handler: (ev: OutputEvent) => HookResultValue | void
+  ): void;
 }
 /** Per-frame + map/precache hooks on this plugin's load-scope ({@link PluginContext.server}). */
 export interface CtxServer {
@@ -79,7 +113,10 @@ export interface CtxServer {
    */
   onGameFrame(
     fn: () => void,
-    opts?: { priority?: "high" | "normal" | "low" | "monitor"; phase?: "pre" | "post" },
+    opts?: {
+      priority?: "high" | "normal" | "low" | "monitor";
+      phase?: "pre" | "post";
+    }
   ): void;
   /** A new map became live; `mapName` is the BSP name. */
   onMapStart(handler: (mapName: string) => void): void;
@@ -103,7 +140,7 @@ export interface CtxCommands {
    */
   onClientCommand(
     name: string,
-    handler: (slot: number, argString: string) => HookResultValue | void,
+    handler: (slot: number, argString: string) => HookResultValue | void
   ): void;
 }
 /**
@@ -147,7 +184,7 @@ export interface CtxTopMenu {
 /** A producer-backed inter-plugin interface: its methods, plus forward subscriptions. */
 export type InterfaceHandle<T extends object> = T & {
   /** Subscribe to a producer forward. Load-window only (buffered, armed at Active) — like every registration. */
-  on(event: string, handler: (payload: any) => void): void;
+  on(event: string, handler: (payload: any) => void): Subscription;
 };
 
 /**
@@ -198,11 +235,41 @@ export interface PluginContext {
   /** TopMenu (adminmenu) contribution ({@link CtxTopMenu}). */
   readonly topmenu: CtxTopMenu;
   /** Publish this plugin's manifest-declared interface. Buffered; goes live at Active. */
-  publish<T extends object>(name: string, impl: T): PublishHandle;
+  publish<N extends keyof InterfaceContracts>(
+    name: N,
+    impl: ContractMethods<InterfaceContracts[N]>
+  ): TypedPublishHandle<InterfaceContracts[N]>;
+  publish<T extends object>(
+    name: keyof InterfaceContracts extends never ? string : never,
+    impl: T
+  ): PublishHandle;
   /** Resolve a HARD dep (must be in `pluginDependencies`). Immediate — the proxy is callable during OnPluginStart. */
-  use<T extends object>(name: string): InterfaceHandle<T>;
+  use<N extends keyof InterfaceContracts>(
+    name: N
+  ): TypedInterfaceHandle<InterfaceContracts[N]>;
+  use<T extends object>(
+    name: keyof InterfaceContracts extends never ? string : never
+  ): InterfaceHandle<T>;
   /** Resolve an OPTIONAL dep (must be in `optionalPluginDependencies`); null while unpublished. */
-  tryUse<T extends object>(name: string): InterfaceHandle<T> | null;
+  tryUse<N extends keyof InterfaceContracts>(
+    name: N
+  ): TypedInterfaceHandle<InterfaceContracts[N]> | null;
+  tryUse<T extends object>(
+    name: keyof InterfaceContracts extends never ? string : never
+  ): InterfaceHandle<T> | null;
+  /** Observe a declared optional provider, after both plugins are Active. */
+  watchOptional<N extends keyof InterfaceContracts>(
+    name: N,
+    attach: (service: TypedInterfaceHandle<InterfaceContracts[N]>, scope: AttachmentScope) => void
+  ): Subscription;
+  /** Bind a provider-qualified map of forward names to local handlers. */
+  bindForwards<
+    N extends keyof InterfaceContracts,
+    H extends ForwardHandlers<InterfaceContracts[N]>
+  >(
+    name: N,
+    handlers: ExactForwardHandlers<InterfaceContracts[N], H>
+  ): Subscription;
   /** Allocate a disposable subscription scope (load-window only — the capability originates at load). */
   createScope(): Scope;
 }
@@ -254,7 +321,7 @@ export declare const hook: {
 export declare function onOutput(
   classname: string,
   output: string,
-  handler: (ev: OutputEvent) => HookResultValue | void,
+  handler: (ev: OutputEvent) => HookResultValue | void
 ): void;
 
 /**
@@ -277,18 +344,35 @@ export declare function createScope(): Scope;
  * Publish this plugin's manifest-declared interface. Load-window only (buffered, armed at Active).
  * Same contract as {@link PluginContext.publish}.
  */
-export declare function publish<T extends object>(name: string, impl: T): PublishHandle;
+export declare function publish<N extends keyof InterfaceContracts>(
+  name: N,
+  impl: ContractMethods<InterfaceContracts[N]>
+): TypedPublishHandle<InterfaceContracts[N]>;
+export declare function publish<T extends object>(
+  name: keyof InterfaceContracts extends never ? string : never,
+  impl: T
+): PublishHandle;
 /**
  * Resolve a HARD dep (must be in `pluginDependencies`). Load-window only.
  * Same contract as {@link PluginContext.use}. Prefer `import { greet } from "@demo/greeter"` for
  * the producer-as-import form; `use()` remains the explicit load-window form and the optional-dep path.
  */
-export declare function use<T extends object>(name: string): InterfaceHandle<T>;
+export declare function use<N extends keyof InterfaceContracts>(
+  name: N
+): TypedInterfaceHandle<InterfaceContracts[N]>;
+export declare function use<T extends object>(
+  name: keyof InterfaceContracts extends never ? string : never
+): InterfaceHandle<T>;
 /**
  * Resolve an OPTIONAL dep (must be in `optionalPluginDependencies`); null while unpublished.
  * Load-window only. Same contract as {@link PluginContext.tryUse}.
  */
-export declare function tryUse<T extends object>(name: string): InterfaceHandle<T> | null;
+export declare function tryUse<N extends keyof InterfaceContracts>(
+  name: N
+): TypedInterfaceHandle<InterfaceContracts[N]> | null;
+export declare function tryUse<T extends object>(
+  name: keyof InterfaceContracts extends never ? string : never
+): InterfaceHandle<T> | null;
 
 /**
  * Load-window TopMenu contribution. Same contract as {@link PluginContext.topmenu}.
@@ -302,3 +386,26 @@ export declare const topmenu: CtxTopMenu;
  * the same way they collect `ctx.translations.load(...)`.
  */
 export declare const translations: CtxTranslations;
+
+/**
+ * Declare an optional-provider watch during load. Requires optionalPluginDependencies.
+ * Attachment runs synchronously after both plugins are Active, once per compatible
+ * provider generation. Failed attachments roll back; reappearance creates a fresh scope.
+ * Only the supplied service permits forward registration during the attachment callback.
+ */
+export declare function watchOptional<N extends keyof InterfaceContracts>(
+  name: N,
+  attach: (service: TypedInterfaceHandle<InterfaceContracts[N]>, scope: AttachmentScope) => void
+): Subscription;
+
+/**
+ * Bind provider forward names to local functions during the normal load window.
+ * The returned subscription disposes every registration created by this call.
+ */
+export declare function bindForwards<
+  N extends keyof InterfaceContracts,
+  H extends ForwardHandlers<InterfaceContracts[N]>
+>(
+  name: N,
+  handlers: ExactForwardHandlers<InterfaceContracts[N], H>
+): Subscription;

package/timers.d.ts

@@ -5,21 +5,22 @@
 
 /**
  * Await a delay of `ms` milliseconds before continuing. Tick-integrated (resumes on a game frame).
+ * Rejects with `AsyncQueueFull` at the global or owning plugin timer limit.
  * @example
  * import { delay } from "@s2script/sdk/timers";
  * // plugins/funcommands/src/plugin.ts:77 — sm_freeze auto-unfreeze after `secs`
  * delay(secs * 1000).then(() => { const q = Player.fromSlot(slot); if (q && q.pawn) q.pawn.moveType = WALK; });
  */
 export declare function delay(ms: number): Promise<void>;
-/** Yield to the next microtick. */
+/** Yield to the next microtick. Rejects with `AsyncQueueFull` at the timer admission limit. */
 export declare function nextTick(): Promise<void>;
-/** Yield until the next game frame. */
+/** Yield until the next game frame. Rejects with `AsyncQueueFull` at the timer admission limit. */
 export declare function nextFrame(): Promise<void>;
 /**
- * Block the current thread (fiber) for `ms` milliseconds.
- * Only valid inside a threadSleep-capable fiber context.
+ * Sleep on a worker thread; the returned promise settles on a later game frame.
+ * Rejects with `AsyncQueueFull` when outstanding jobs or the worker queue are full.
  */
-export declare function threadSleep(ms: number): void;
+export declare function threadSleep(ms: number): Promise<void>;
 
 /**
  * A live callback timer, returned by {@link after} and {@link every}. Ledgered against the creating
@@ -35,6 +36,7 @@ export interface Timer {
 
 /**
  * Run `fn` once after `ms` milliseconds (SourceMod `CreateTimer` without `TIMER_REPEAT`).
+ * Throws an error named `AsyncQueueFull` if no timer slot is available.
  *
  * Prefer {@link delay} when you can `await`; use this when you need something cancellable.
  * A throwing callback is reported and contained — it never kills the frame or the timer system.
@@ -48,6 +50,7 @@ export declare function after(ms: number, fn: () => void): Timer;
 
 /**
  * Run `fn` every `ms` milliseconds until killed (SourceMod `CreateTimer` with `TIMER_REPEAT`).
+ * Throws an error named `AsyncQueueFull` if no timer slot is available.
  *
  * The next firing is scheduled *after* the callback returns, so a slow callback cannot pile up.
  * `ms` must be greater than 0 — a zero-interval repeat would re-arm every drain and starve the

package/ws.d.ts

@@ -9,7 +9,8 @@ export interface WebSocket {
   /** Register a handler for a transport error; `err` is the error text. */
   onError(handler: (err: string) => void): void;
   /** Send a text frame. */
-  send(data: string): void;
+  /** Returns false if closed, oversized, or the connection/global outbound budget is full. */
+  send(data: string): boolean;
   /** Close the connection. */
   close(): void;
 }