@s2script/sdk 0.25.1 → 0.26.0

package/README.md

@@ -110,3 +110,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/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}. */