@s2script/sdk 0.25.1 → 0.27.0

package/README.md

@@ -36,6 +36,19 @@ export function OnClientPostAdminCheck(client: Client): void {
 }
 ```
 
+For an existing plugin with `s2script.gamedata` declarations, run
+`npx @s2script/sdk migrate engine-functions [plugin-dir]`. The command analyzes the v1 declarations
+and source references, reports ambiguities, and writes `gamedata/functions.jsonc` only when the
+declared contract can be converted without loss. It refuses an existing destination unless you pass
+`--force`. Its JSON report lists files actually changed and the package/source edits you must make
+manually, including removal of the old `s2script.gamedata` field and authored engine permissions
+when adopting the v2 file. A successful conversion does not verify that the v1 declaration listed
+every native argument or that the resulting call works on the current game build. The command alone
+does not provide the runtime compatibility facades for old source code. V1 entity hooks are refused
+because their callbacks may receive a null receiver, which the current v2 receiver contract cannot
+preserve. With `--force`, the report identifies the exact create-or-replace path; concurrent prior
+existence cannot be established by the atomic rename.
+
 This package is **types-only** — the engine injects the implementation at load time, and
 `s2s build` marks `@s2script/*` external rather than bundling it. Capabilities are imported as
 per-capability subpaths (`@s2script/sdk/entity`, `@s2script/sdk/timers`, `@s2script/sdk/clients`, …);
@@ -110,3 +123,59 @@ reference. Source and issues: [GitHub](https://github.com/s2script/s2script).
 ## License
 
 MIT OR Apache-2.0
+
+### Typed plugin interfaces
+
+Opt in with `s2script.interfaceProtocol: 2`, export a self-contained `Contract` with `methods` and
+`forwards: { EventName: Notification<Payload> }`, then use `publish(name, implementation)` and
+`use(name)` without caller-selected generics. `s2s build` generates the name association and checks
+wire schemas; `s2s add` obtains only a plugin dependency's types. Include the generated
+`.s2script/interfaces.d.ts` in existing projects' tsconfig files. Protocol 2 needs host API 3.
+
+CJS module evaluation runs before the host opens its load window. Register publications,
+subscriptions, binding maps and optional watches inside `OnPluginStart`. Exported handler
+functions and imports can remain at module top level.
+
+Inline handlers infer their payload from the provider:
+
+```ts
+import { use } from "@s2script/sdk/plugin";
+export function OnPluginStart(): void {
+  use("@demo/racing").on("OnRunFinished", event => console.log(event.elapsedMs));
+}
+```
+
+Use an explicit binding map when a named local export has a different name from the provider
+forward. The returned subscription disposes the whole map:
+
+```ts
+import { bindForwards, command } from "@s2script/sdk";
+export function OnRaceFinished(event: { elapsedMs: number }): void {
+  console.log(event.elapsedMs);
+}
+export function OnPluginStart(): void {
+  const racing = bindForwards("@demo/racing", { OnRunFinished: OnRaceFinished });
+  command.server("sm_disable_racing", () => racing.dispose());
+}
+```
+
+`bindForwards` requires a hard plugin dependency. Optional providers continue to attach through
+`watchOptional`, where named local functions can be passed to the supplied `service.on`.
+See [the complete migration guide](https://github.com/s2script/s2script/blob/main/docs/PLUGIN_INTEROP.md)
+for supported types, copying, dispatch, and compatibility limits.
+
+
+Use `Hook<Payload>` for synchronous decisions and `Transform<Payload, WritableKeys>` for
+validated shallow patches. Producers call `dispatch`; notifications use `emit`. All crossings
+copy supported wire values. Listeners must return synchronously, and invalid/throwing listeners
+contribute Continue. Nested crossings stop at 32 active calls. Retained optional services throw
+`InterfaceUnavailable` after detach; reacquire through `watchOptional` on each provider generation
+and own resources in its scope. `tryUse` is a one-time lookup.
+
+For an existing consumer, declare the provider under `s2script.pluginDependencies` or
+`optionalPluginDependencies`, run `s2s add <provider>`, include `.s2script/interfaces.d.ts`, and
+rebuild with `s2s build`. Acquisition needs only the verified declaration. Rebuild and deploy the
+producer and consumers together for protocol 2; API 3 hosts still accept legacy API-2/protocol-1
+archives, while old API-2 hosts reject new API-3 builds. See the
+[acceptance workspace](https://github.com/s2script/s2script/tree/main/tools/interop-acceptance)
+for executable examples and the separate live verification sequence.

package/bans.d.ts

@@ -38,9 +38,12 @@ export interface BanEntry {
  * if (b && (b.until === 0 || b.until > Date.now() / 1000)) c.kickWithReason(b.reason);
  */
 export declare const Bans: {
-  /** Add (or overwrite) a ban and persist it to bans.json. `minutes <= 0` = permanent. */
+  /** Add/overwrite the host cache, then attempt to rewrite bans.json. Returns void;
+   * persistence failure is not acknowledged and does not roll back the cache.
+   * An immediate get() confirms cache visibility only, not a fresh or durable write.
+   * `minutes <= 0` = permanent. */
   add(steamId: string, minutes: number, reason?: string): void;
-  /** Remove a ban and persist. Returns whether the SteamID64 was banned. */
+  /** Remove from cache and attempt persistence. Returns whether a cache key existed, not disk acknowledgement. */
   remove(steamId: string): boolean;
   /** Get a ban by SteamID64, or null if not banned. */
   get(steamId: string): BanInfo | null;

package/clients.d.ts

@@ -3,11 +3,17 @@
  * Resolved at runtime via globalThis.__s2pkg_clients. Import: import { Client, Clients } from "./clients";
  */
 
-/** A connected client, identified by its 0-based slot (CPlayerSlot). Slot-backed; getters read live. */
+/**
+ * A handle to one connection lifetime. Reusing a slot, even for the same SteamID, never revives it.
+ * Stale handles return "0" for steamId, "" for name/ip, -1 for userId/signonState,
+ * false for booleans; void actions do nothing and command actions return false.
+ * OnClientDisconnect receives a read-only identity snapshot during its synchronous callback;
+ * isValid() is already false. Capture identity before awaiting; afterward stale defaults apply.
+ */
 export declare class Client {
-  /** The client's 0-based engine slot (`CPlayerSlot`) — the handle's stable identity for its connection. */
+  /** The client's 0-based engine slot (`CPlayerSlot`) — not sufficient by itself to identify a connection. */
   readonly slot: number;
-  /** True while a client occupies this slot. */
+  /** True while this exact connection occupies the slot. */
   isValid(): boolean;
   /** Decimal SteamID64; "0" for a bot or an unauthenticated client. */
   readonly steamId: string;
@@ -15,9 +21,9 @@ export declare class Client {
   readonly name: string;
   /** Engine user-id; -1 if none. */
   readonly userId: number;
-  /** Tracked signon state: 0 = none/disconnected, 2 = connected, 5 = spawned, 6 = full (in-game); -1 if the slot is out of range. */
+  /** Tracked signon state: 0 = none/disconnected, 2 = connected, 5 = spawned, 6 = full (in-game); -1 for a stale handle. */
   readonly signonState: number;
-  /** True for a fake client (bot) — derived from steamId === "0". */
+  /** True for a fake client (bot) — false for stale handles. */
   readonly isBot: boolean;
   /** Disconnect this client. */
   kick(reason?: string): void;

package/contracts/README.md

@@ -1,5 +1,9 @@
 # Standard interface contracts
 
+The [legacy-contracts example](../../../examples/legacy-contracts/README.md)
+demonstrates these protocol 1 community interfaces, including asynchronous
+workshop methods. It is a separate companion to the protocol 2 cookbook.
+
 These are **type-only contracts for inter-plugin interfaces** — not SDK capability modules.
 
 The framework deliberately ships **no implementation** for anything in here. Each contract describes

package/cookies.d.ts

@@ -41,15 +41,16 @@ export declare const Cookies: {
   register(name: string, opts?: CookieOptions): Cookie;
   /** Cache value for this client (a stored "" is a real value), else the cookie's default. Default for bots. */
   get(client: Client, cookie: Cookie): string;
-  /** Write the cache + mark dirty (flushed to the DB on disconnect). No-op for bots. */
-  set(client: Client, cookie: Cookie, value: string): void;
+  /** Accept a cache change into the bounded host persistence outbox. Returns false for invalid/stale/bot
+   * clients or exhausted capacity, without changing the cache. True remains host-owned until DB ACK;
+   * it is not a durability acknowledgement. Check false and report, shed, or retry the change. */
+  set(client: Client, cookie: Cookie, value: string): boolean;
   /** Has this client's cookies finished loading from the DB? */
   areCached(client: Client): boolean;
   /** Unix timestamp of the cookie's last write (set or DB load), or 0 if never set. 0 for bots. */
   getTime(client: Client, cookie: Cookie): number;
-  /** Write a cookie for a SteamID64 that may not be connected right now (`SetAuthIdCookie` parity):
-   * updates the cache immediately (an online client sees it right away) and queues the write for the
-   * clientprefs plugin to persist directly next frame — an offline SteamID never fires the disconnect
-   * flush. No-op for "0" (bot/unset). */
-  setAuthId(steamId: string, cookie: Cookie, value: string): void;
+  /** Accept an online or offline SteamID cookie change under the same bounded admission contract as set.
+   * False leaves both cache and outbox unchanged (including empty/"0" identity). Accepted writes
+   * survive clientprefs reload and same-process core reinit, but not process exit or library destruction. */
+  setAuthId(steamId: string, cookie: Cookie, value: string): boolean;
 };

package/damage.d.ts

@@ -1,22 +1,26 @@
 /**
- * @s2script/damage — the block-scoped {@link DamageInfo} view of a live `CTakeDamageInfo`.
- * NO runtime code (injected at load). Engine-generic: `CTakeDamageInfo` is a Source 2 type.
+ * @s2script/damage — the borrowed {@link DamageInfo} view of the current damage event.
+ * Type-only: the view is supplied by the selected game package (its damage function and damage-info
+ * layout are game facts; CS2 maps `CTakeDamageInfo`), through the engine-generic `SDKHook`.
  *
  * Subscribe with `SDKHook` (`SDKHookType.OnTakeDamage` / `OnTakeDamagePost`), not a global mux.
  */
 import type { EntityRef } from "./entity";
 
 /**
- * A block-scoped view of the current damage event (valid only inside an `OnTakeDamage` or
- * `OnTakeDamagePost` SDKHook).
+ * A borrowed view of the current damage event, valid only during the synchronous `OnTakeDamage` or
+ * `OnTakeDamagePost` SDKHook callback: reading or writing it afterwards (including after an `await`)
+ * throws "expired borrowed view". Returning `HookResult.Handled`/`Stop` from `OnTakeDamage` blocks the
+ * hit by setting damage to 0 after every handler ran; the engine's damage function still runs.
  * @example
  * import type { DamageInfo } from "@s2script/sdk";
  * function onTakeDamage(info: DamageInfo) { info.damage = info.damage / 2; }
  */
 export interface DamageInfo {
   /**
-   * The damage amount (`m_flDamage`). On the pre-hook, assigning MODIFIES the live damage; set to
-   * 0 to block. On `OnTakeDamagePost`, assignment is ignored (the original already ran).
+   * The damage amount (`m_flDamage`). On the pre-hook, assigning MODIFIES the damage the engine
+   * applies (later handlers see it); set to 0 to block. A non-finite value is refused (the damage
+   * keeps its prior value). On `OnTakeDamagePost`, assignment is ignored (the original already ran).
    */
   damage: number;
   /** The damage-type bit flags (m_bitsDamageType). */

package/db.d.ts

@@ -1,3 +1,4 @@
+/** Async queries/execute reject with AsyncQueueFull or AsyncPayloadTooLarge before acceptance. Queries exceeding the configured row or retained-byte limit reject with DatabaseResultTooLarge. */
 /** @s2script/db — engine-generic async SQLite database. NO runtime code (injected as __s2pkg_db). */
 
 /** A value bindable as a SQL parameter or returned in a {@link Row}. */