@super-line/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mert
+
+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,33 @@
+# @super-line/core
+
+Shared core for [**super-line**](https://mertdogar.github.io/super-line/) — end-to-end typesafe WebSockets for TypeScript. This package holds the pieces both ends import: `defineContract`, runtime validation, the `SocketError` model, and the `Serializer` / `Adapter` interfaces.
+
+```bash
+pnpm add @super-line/core zod
+```
+
+```ts
+import { z } from 'zod'
+import { defineContract } from '@super-line/core'
+
+export const api = defineContract({
+  shared: {
+    serverToClient: { message: { payload: z.object({ text: z.string() }) } },
+  },
+  roles: {
+    user: {
+      clientToServer: {
+        send: { input: z.object({ text: z.string() }), output: z.object({ id: z.string() }) },
+      },
+    },
+  },
+})
+```
+
+The contract is split by **direction** (`clientToServer` / `serverToClient`) and scoped by **role**, then implemented by [`@super-line/server`](https://www.npmjs.com/package/@super-line/server) and called by [`@super-line/client`](https://www.npmjs.com/package/@super-line/client).
+
+- 📖 Docs: <https://mertdogar.github.io/super-line/>
+- 📚 The contract model: <https://mertdogar.github.io/super-line/guide/the-contract>
+- 🧩 Source: <https://github.com/mertdogar/super-line>
+
+MIT © Mert

package/dist/index.cjs

@@ -0,0 +1,91 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  PROTOCOL: () => PROTOCOL,
+  SocketError: () => SocketError,
+  defineContract: () => defineContract,
+  jsonSerializer: () => jsonSerializer,
+  validate: () => validate,
+  validateSync: () => validateSync
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var SocketError = class extends Error {
+  /** The typed error code (e.g. `'FORBIDDEN'`), available on the client. */
+  code;
+  /** Optional structured data attached to the error, delivered to the client. */
+  data;
+  /**
+   * @param code - a {@link SocketErrorCode} or custom string.
+   * @param message - human-readable message (defaults to `code`).
+   * @param data - optional structured payload delivered to the client.
+   */
+  constructor(code, message, data) {
+    super(message ?? code);
+    this.name = "SocketError";
+    this.code = code;
+    this.data = data;
+  }
+};
+
+// src/serializer.ts
+var decoder = new TextDecoder();
+var jsonSerializer = {
+  encode: (value) => JSON.stringify(value),
+  decode: (data) => JSON.parse(typeof data === "string" ? data : decoder.decode(data))
+};
+
+// src/contract.ts
+function defineContract(contract) {
+  return contract;
+}
+async function validate(schema, value) {
+  let result = schema["~standard"].validate(value);
+  if (result instanceof Promise) result = await result;
+  if (result.issues) {
+    throw new SocketError("VALIDATION", "Validation failed", result.issues);
+  }
+  return result.value;
+}
+function validateSync(schema, value) {
+  const result = schema["~standard"].validate(value);
+  if (result instanceof Promise) {
+    throw new SocketError("INTERNAL", "Async schema not supported for synchronous validation");
+  }
+  if (result.issues) {
+    throw new SocketError("VALIDATION", "Validation failed", result.issues);
+  }
+  return result.value;
+}
+
+// src/wire.ts
+var PROTOCOL = "superline.v1";
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PROTOCOL,
+  SocketError,
+  defineContract,
+  jsonSerializer,
+  validate,
+  validateSync
+});

package/dist/index.d.cts

@@ -0,0 +1,248 @@
+import { StandardSchemaV1 } from '@standard-schema/spec';
+
+/** The built-in error codes super-line uses across the wire. */
+type SocketErrorCode = 'BAD_REQUEST' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'NOT_FOUND' | 'TIMEOUT' | 'VALIDATION' | 'DISCONNECTED' | 'INTERNAL';
+/** A built-in code or any custom string (autocomplete keeps the known set). */
+type ErrorCode = SocketErrorCode | (string & {});
+/**
+ * The error type carried end-to-end. Throw one from a handler and the client's
+ * promise rejects with the same `code` (and optional `data`). Unknown throws
+ * become `INTERNAL` so server internals aren't leaked.
+ */
+declare class SocketError<Data = unknown> extends Error {
+    /** The typed error code (e.g. `'FORBIDDEN'`), available on the client. */
+    readonly code: ErrorCode;
+    /** Optional structured data attached to the error, delivered to the client. */
+    readonly data?: Data;
+    /**
+     * @param code - a {@link SocketErrorCode} or custom string.
+     * @param message - human-readable message (defaults to `code`).
+     * @param data - optional structured payload delivered to the client.
+     */
+    constructor(code: ErrorCode, message?: string, data?: Data);
+}
+
+/**
+ * Wire encoder/decoder. The server and client **must** use the same one.
+ * Swap in `superjson`/msgpack to carry richer types than JSON.
+ */
+interface Serializer {
+    /** Encode a frame for the wire. */
+    encode(value: unknown): string | Uint8Array;
+    /** Decode a wire frame back to a value. */
+    decode(data: string | Uint8Array): unknown;
+}
+/** The default serializer (`JSON`). Note: turns `Date` into a string — see the serialization guide. */
+declare const jsonSerializer: Serializer;
+
+/**
+ * Cross-node fan-out seam. Rooms, topics, and serverToServer all compile down to
+ * channel pub/sub. A node subscribes to a channel only while it has a local member,
+ * and publishes always go through the adapter (the in-memory adapter loops back),
+ * so a node delivers to its local members on receipt — one code path, no double-send.
+ *
+ * The default is a per-server in-memory adapter; use `@super-line/adapter-redis`
+ * to fan out across processes.
+ */
+interface Adapter {
+    /** Start receiving messages published to `channel`. */
+    subscribe(channel: string): void | Promise<void>;
+    /** Stop receiving messages for `channel`. */
+    unsubscribe(channel: string): void | Promise<void>;
+    /** Publish an encoded payload to `channel` (delivered to every subscribed node). */
+    publish(channel: string, payload: string | Uint8Array): void | Promise<void>;
+    /** Register the handler invoked for each message on a subscribed channel. */
+    onMessage(handler: (channel: string, payload: string | Uint8Array) => void): void;
+    /** Optional teardown (e.g. close Redis connections). */
+    close?(): void | Promise<void>;
+}
+
+/** Any [Standard Schema](https://standardschema.dev) validator (Zod, Valibot, ArkType…). */
+type Schema = StandardSchemaV1;
+/**
+ * A client→server request (request/response). The client sends `input`; the
+ * server validates it, runs the handler, and replies with `output`.
+ * Fire-and-forget signals (no `output`) are not supported yet.
+ */
+interface RequestDef {
+    /** Schema for the request payload the client sends. */
+    input: Schema;
+    /** Schema for the reply the server returns. */
+    output: Schema;
+}
+/**
+ * A server→client message. With `subscribe: true` it becomes a client-subscribable
+ * **topic**; otherwise it is a server-pushed **event**.
+ */
+interface ServerMessageDef {
+    /** Schema for the message body. */
+    payload: Schema;
+    /** When `true`, clients opt in via `client.subscribe(...)` (a topic). Omit for a push event. */
+    subscribe?: boolean;
+}
+/** The two directions within a `shared` or role block. */
+interface Directional {
+    /** Requests this side may call (client→server). */
+    clientToServer?: Record<string, RequestDef>;
+    /** Events/topics this side may receive (server→client). */
+    serverToClient?: Record<string, ServerMessageDef>;
+}
+/**
+ * The single source of truth, imported by both server and client. Split by
+ * **direction** and scoped by **role**: a `shared` base every role inherits,
+ * plus one block per role. `serverToServer` is node↔node (not role-scoped).
+ */
+interface Contract {
+    /** Surface common to every role (merged into each role's effective surface). */
+    shared?: Directional;
+    /** Per-role surfaces. A connection's role selects which one (plus `shared`) it sees. */
+    roles: Record<string, Directional>;
+    /** Typed node-to-node event payloads, for {@link "@super-line/server"!}'s `emitServer`/`onServer`. */
+    serverToServer?: Record<string, Schema>;
+}
+/**
+ * Define a contract. An identity function — `const` preserves literal keys and
+ * `subscribe: true` so the full surface can be inferred on both ends.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod'
+ * import { defineContract } from '@super-line/core'
+ *
+ * export const api = defineContract({
+ *   shared: {
+ *     clientToServer: { join: { input: z.object({ room: z.string() }), output: z.object({ ok: z.boolean() }) } },
+ *     serverToClient: { message: { payload: z.object({ text: z.string() }) } },
+ *   },
+ *   roles: {
+ *     user:  { clientToServer: { say:      { input: z.object({ text: z.string() }), output: z.object({ id: z.string() }) } } },
+ *     agent: { clientToServer: { announce: { input: z.object({ text: z.string() }), output: z.object({ id: z.string() }) } } },
+ *   },
+ *   serverToServer: { rebalance: z.object({ shard: z.number() }) },
+ * })
+ * ```
+ */
+declare function defineContract<const C extends Contract>(contract: C): C;
+/** Union of a contract's role names. */
+type RoleOf<C extends Contract> = keyof C['roles'] & string;
+type CtsOf<D> = D extends {
+    clientToServer: infer M extends Record<string, RequestDef>;
+} ? M : {};
+type StcOf<D> = D extends {
+    serverToClient: infer M extends Record<string, ServerMessageDef>;
+} ? M : {};
+type EventsOf<M> = {
+    [K in keyof M as M[K] extends {
+        subscribe: true;
+    } ? never : K]: M[K];
+};
+type TopicsOf<M> = {
+    [K in keyof M as M[K] extends {
+        subscribe: true;
+    } ? K : never]: M[K];
+};
+/** A role's effective request map: `shared` ∪ `roles[R]` client→server requests. */
+type Requests<C extends Contract, R extends RoleOf<C>> = CtsOf<C['shared']> & CtsOf<C['roles'][R]>;
+/** A role's effective server→client map (events and topics combined). */
+type ServerMessages<C extends Contract, R extends RoleOf<C>> = StcOf<C['shared']> & StcOf<C['roles'][R]>;
+/** A role's push events (server→client entries without `subscribe`). */
+type Events<C extends Contract, R extends RoleOf<C>> = EventsOf<ServerMessages<C, R>>;
+/** A role's subscribable topics (server→client entries with `subscribe: true`). */
+type Topics<C extends Contract, R extends RoleOf<C>> = TopicsOf<ServerMessages<C, R>>;
+/** Requests in the `shared` block (every role can call these). */
+type SharedRequests<C extends Contract> = CtsOf<C['shared']>;
+/** Requests in one role's block (not including `shared`). */
+type RoleRequests<C extends Contract, R extends RoleOf<C>> = CtsOf<C['roles'][R]>;
+/** Push events in the `shared` block (broadcastable to a mixed-role room). */
+type SharedEvents<C extends Contract> = EventsOf<StcOf<C['shared']>>;
+/** Subscribable topics in the `shared` block (published via `srv.publish`). */
+type SharedTopics<C extends Contract> = TopicsOf<StcOf<C['shared']>>;
+/** Subscribable topics in one role's block (published via `srv.forRole(r).publish`). */
+type RoleTopics<C extends Contract, R extends RoleOf<C>> = TopicsOf<StcOf<C['roles'][R]>>;
+/** The `serverToServer` map, or `{}` if the contract has none. */
+type ServerEvents<C extends Contract> = C['serverToServer'] extends Record<string, Schema> ? C['serverToServer'] : {};
+/** The input type a client passes for a request (pre-validation). */
+type ClientInput<T> = T extends RequestDef ? InferIn<T['input']> : never;
+/** The input type a server handler receives for a request (post-validation). */
+type ServerInput<T> = T extends RequestDef ? InferOut<T['input']> : never;
+/** The reply type of a request (server returns / client receives). */
+type Output<T> = T extends RequestDef ? InferOut<T['output']> : never;
+/** The data a client receives for an event/topic (post-validation). */
+type EventData<T> = T extends ServerMessageDef ? InferOut<T['payload']> : never;
+/** The data a server sends for an event/topic (pre-validation). */
+type EmitData<T> = T extends ServerMessageDef ? InferIn<T['payload']> : never;
+/** The data a server sends for a serverToServer event. */
+type ServerEmit<T> = T extends Schema ? InferIn<T> : never;
+/** The data a server receives for a serverToServer event. */
+type ServerData<T> = T extends Schema ? InferOut<T> : never;
+/** Infer a schema's **input** type (what you pass into the validator). */
+type InferIn<S extends Schema> = StandardSchemaV1.InferInput<S>;
+/** Infer a schema's **output** type (the validated result). */
+type InferOut<S extends Schema> = StandardSchemaV1.InferOutput<S>;
+/**
+ * Validate a value against a Standard Schema validator (sync or async).
+ *
+ * @param schema - the validator to run.
+ * @param value - the untrusted value to validate.
+ * @returns the parsed, typed value.
+ * @throws {@link SocketError} with code `VALIDATION` if the value doesn't match.
+ */
+declare function validate<S extends Schema>(schema: S, value: unknown): Promise<StandardSchemaV1.InferOutput<S>>;
+/**
+ * Synchronous validation for hot paths (e.g. client inbound dispatch).
+ *
+ * @param schema - the validator to run.
+ * @param value - the untrusted value to validate.
+ * @returns the parsed, typed value.
+ * @throws {@link SocketError} with code `VALIDATION` on mismatch, or `INTERNAL` if the schema is async.
+ */
+declare function validateSync<S extends Schema>(schema: S, value: unknown): StandardSchemaV1.InferOutput<S>;
+
+/**
+ * The wire protocol below is an implementation detail — you rarely touch frames
+ * directly. It's exported for adapters, custom transports, and tooling.
+ */
+/** Protocol version string, negotiated via the WebSocket subprotocol at upgrade. */
+declare const PROTOCOL = "superline.v1";
+interface ReqFrame {
+    t: 'req';
+    i: number;
+    m: string;
+    d: unknown;
+}
+interface SubFrame {
+    t: 'sub';
+    i: number;
+    c: string;
+}
+interface UnsubFrame {
+    t: 'unsub';
+    c: string;
+}
+type ClientFrame = ReqFrame | SubFrame | UnsubFrame;
+interface ResFrame {
+    t: 'res';
+    i: number;
+    d: unknown;
+}
+interface ErrFrame {
+    t: 'err';
+    i?: number;
+    code: string;
+    m: string;
+    d?: unknown;
+}
+interface EvtFrame {
+    t: 'evt';
+    e: string;
+    d: unknown;
+}
+interface PubFrame {
+    t: 'pub';
+    c: string;
+    d: unknown;
+}
+type ServerFrame = ResFrame | ErrFrame | EvtFrame | PubFrame;
+type Frame = ClientFrame | ServerFrame;
+
+export { type Adapter, type ClientFrame, type ClientInput, type Contract, type Directional, type EmitData, type ErrFrame, type ErrorCode, type EventData, type Events, type EvtFrame, type Frame, type InferIn, type InferOut, type Output, PROTOCOL, type PubFrame, type ReqFrame, type RequestDef, type Requests, type ResFrame, type RoleOf, type RoleRequests, type RoleTopics, type Schema, type Serializer, type ServerData, type ServerEmit, type ServerEvents, type ServerFrame, type ServerInput, type ServerMessageDef, type ServerMessages, type SharedEvents, type SharedRequests, type SharedTopics, SocketError, type SocketErrorCode, type SubFrame, type Topics, type UnsubFrame, defineContract, jsonSerializer, validate, validateSync };

package/dist/index.d.ts

@@ -0,0 +1,248 @@
+import { StandardSchemaV1 } from '@standard-schema/spec';
+
+/** The built-in error codes super-line uses across the wire. */
+type SocketErrorCode = 'BAD_REQUEST' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'NOT_FOUND' | 'TIMEOUT' | 'VALIDATION' | 'DISCONNECTED' | 'INTERNAL';
+/** A built-in code or any custom string (autocomplete keeps the known set). */
+type ErrorCode = SocketErrorCode | (string & {});
+/**
+ * The error type carried end-to-end. Throw one from a handler and the client's
+ * promise rejects with the same `code` (and optional `data`). Unknown throws
+ * become `INTERNAL` so server internals aren't leaked.
+ */
+declare class SocketError<Data = unknown> extends Error {
+    /** The typed error code (e.g. `'FORBIDDEN'`), available on the client. */
+    readonly code: ErrorCode;
+    /** Optional structured data attached to the error, delivered to the client. */
+    readonly data?: Data;
+    /**
+     * @param code - a {@link SocketErrorCode} or custom string.
+     * @param message - human-readable message (defaults to `code`).
+     * @param data - optional structured payload delivered to the client.
+     */
+    constructor(code: ErrorCode, message?: string, data?: Data);
+}
+
+/**
+ * Wire encoder/decoder. The server and client **must** use the same one.
+ * Swap in `superjson`/msgpack to carry richer types than JSON.
+ */
+interface Serializer {
+    /** Encode a frame for the wire. */
+    encode(value: unknown): string | Uint8Array;
+    /** Decode a wire frame back to a value. */
+    decode(data: string | Uint8Array): unknown;
+}
+/** The default serializer (`JSON`). Note: turns `Date` into a string — see the serialization guide. */
+declare const jsonSerializer: Serializer;
+
+/**
+ * Cross-node fan-out seam. Rooms, topics, and serverToServer all compile down to
+ * channel pub/sub. A node subscribes to a channel only while it has a local member,
+ * and publishes always go through the adapter (the in-memory adapter loops back),
+ * so a node delivers to its local members on receipt — one code path, no double-send.
+ *
+ * The default is a per-server in-memory adapter; use `@super-line/adapter-redis`
+ * to fan out across processes.
+ */
+interface Adapter {
+    /** Start receiving messages published to `channel`. */
+    subscribe(channel: string): void | Promise<void>;
+    /** Stop receiving messages for `channel`. */
+    unsubscribe(channel: string): void | Promise<void>;
+    /** Publish an encoded payload to `channel` (delivered to every subscribed node). */
+    publish(channel: string, payload: string | Uint8Array): void | Promise<void>;
+    /** Register the handler invoked for each message on a subscribed channel. */
+    onMessage(handler: (channel: string, payload: string | Uint8Array) => void): void;
+    /** Optional teardown (e.g. close Redis connections). */
+    close?(): void | Promise<void>;
+}
+
+/** Any [Standard Schema](https://standardschema.dev) validator (Zod, Valibot, ArkType…). */
+type Schema = StandardSchemaV1;
+/**
+ * A client→server request (request/response). The client sends `input`; the
+ * server validates it, runs the handler, and replies with `output`.
+ * Fire-and-forget signals (no `output`) are not supported yet.
+ */
+interface RequestDef {
+    /** Schema for the request payload the client sends. */
+    input: Schema;
+    /** Schema for the reply the server returns. */
+    output: Schema;
+}
+/**
+ * A server→client message. With `subscribe: true` it becomes a client-subscribable
+ * **topic**; otherwise it is a server-pushed **event**.
+ */
+interface ServerMessageDef {
+    /** Schema for the message body. */
+    payload: Schema;
+    /** When `true`, clients opt in via `client.subscribe(...)` (a topic). Omit for a push event. */
+    subscribe?: boolean;
+}
+/** The two directions within a `shared` or role block. */
+interface Directional {
+    /** Requests this side may call (client→server). */
+    clientToServer?: Record<string, RequestDef>;
+    /** Events/topics this side may receive (server→client). */
+    serverToClient?: Record<string, ServerMessageDef>;
+}
+/**
+ * The single source of truth, imported by both server and client. Split by
+ * **direction** and scoped by **role**: a `shared` base every role inherits,
+ * plus one block per role. `serverToServer` is node↔node (not role-scoped).
+ */
+interface Contract {
+    /** Surface common to every role (merged into each role's effective surface). */
+    shared?: Directional;
+    /** Per-role surfaces. A connection's role selects which one (plus `shared`) it sees. */
+    roles: Record<string, Directional>;
+    /** Typed node-to-node event payloads, for {@link "@super-line/server"!}'s `emitServer`/`onServer`. */
+    serverToServer?: Record<string, Schema>;
+}
+/**
+ * Define a contract. An identity function — `const` preserves literal keys and
+ * `subscribe: true` so the full surface can be inferred on both ends.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod'
+ * import { defineContract } from '@super-line/core'
+ *
+ * export const api = defineContract({
+ *   shared: {
+ *     clientToServer: { join: { input: z.object({ room: z.string() }), output: z.object({ ok: z.boolean() }) } },
+ *     serverToClient: { message: { payload: z.object({ text: z.string() }) } },
+ *   },
+ *   roles: {
+ *     user:  { clientToServer: { say:      { input: z.object({ text: z.string() }), output: z.object({ id: z.string() }) } } },
+ *     agent: { clientToServer: { announce: { input: z.object({ text: z.string() }), output: z.object({ id: z.string() }) } } },
+ *   },
+ *   serverToServer: { rebalance: z.object({ shard: z.number() }) },
+ * })
+ * ```
+ */
+declare function defineContract<const C extends Contract>(contract: C): C;
+/** Union of a contract's role names. */
+type RoleOf<C extends Contract> = keyof C['roles'] & string;
+type CtsOf<D> = D extends {
+    clientToServer: infer M extends Record<string, RequestDef>;
+} ? M : {};
+type StcOf<D> = D extends {
+    serverToClient: infer M extends Record<string, ServerMessageDef>;
+} ? M : {};
+type EventsOf<M> = {
+    [K in keyof M as M[K] extends {
+        subscribe: true;
+    } ? never : K]: M[K];
+};
+type TopicsOf<M> = {
+    [K in keyof M as M[K] extends {
+        subscribe: true;
+    } ? K : never]: M[K];
+};
+/** A role's effective request map: `shared` ∪ `roles[R]` client→server requests. */
+type Requests<C extends Contract, R extends RoleOf<C>> = CtsOf<C['shared']> & CtsOf<C['roles'][R]>;
+/** A role's effective server→client map (events and topics combined). */
+type ServerMessages<C extends Contract, R extends RoleOf<C>> = StcOf<C['shared']> & StcOf<C['roles'][R]>;
+/** A role's push events (server→client entries without `subscribe`). */
+type Events<C extends Contract, R extends RoleOf<C>> = EventsOf<ServerMessages<C, R>>;
+/** A role's subscribable topics (server→client entries with `subscribe: true`). */
+type Topics<C extends Contract, R extends RoleOf<C>> = TopicsOf<ServerMessages<C, R>>;
+/** Requests in the `shared` block (every role can call these). */
+type SharedRequests<C extends Contract> = CtsOf<C['shared']>;
+/** Requests in one role's block (not including `shared`). */
+type RoleRequests<C extends Contract, R extends RoleOf<C>> = CtsOf<C['roles'][R]>;
+/** Push events in the `shared` block (broadcastable to a mixed-role room). */
+type SharedEvents<C extends Contract> = EventsOf<StcOf<C['shared']>>;
+/** Subscribable topics in the `shared` block (published via `srv.publish`). */
+type SharedTopics<C extends Contract> = TopicsOf<StcOf<C['shared']>>;
+/** Subscribable topics in one role's block (published via `srv.forRole(r).publish`). */
+type RoleTopics<C extends Contract, R extends RoleOf<C>> = TopicsOf<StcOf<C['roles'][R]>>;
+/** The `serverToServer` map, or `{}` if the contract has none. */
+type ServerEvents<C extends Contract> = C['serverToServer'] extends Record<string, Schema> ? C['serverToServer'] : {};
+/** The input type a client passes for a request (pre-validation). */
+type ClientInput<T> = T extends RequestDef ? InferIn<T['input']> : never;
+/** The input type a server handler receives for a request (post-validation). */
+type ServerInput<T> = T extends RequestDef ? InferOut<T['input']> : never;
+/** The reply type of a request (server returns / client receives). */
+type Output<T> = T extends RequestDef ? InferOut<T['output']> : never;
+/** The data a client receives for an event/topic (post-validation). */
+type EventData<T> = T extends ServerMessageDef ? InferOut<T['payload']> : never;
+/** The data a server sends for an event/topic (pre-validation). */
+type EmitData<T> = T extends ServerMessageDef ? InferIn<T['payload']> : never;
+/** The data a server sends for a serverToServer event. */
+type ServerEmit<T> = T extends Schema ? InferIn<T> : never;
+/** The data a server receives for a serverToServer event. */
+type ServerData<T> = T extends Schema ? InferOut<T> : never;
+/** Infer a schema's **input** type (what you pass into the validator). */
+type InferIn<S extends Schema> = StandardSchemaV1.InferInput<S>;
+/** Infer a schema's **output** type (the validated result). */
+type InferOut<S extends Schema> = StandardSchemaV1.InferOutput<S>;
+/**
+ * Validate a value against a Standard Schema validator (sync or async).
+ *
+ * @param schema - the validator to run.
+ * @param value - the untrusted value to validate.
+ * @returns the parsed, typed value.
+ * @throws {@link SocketError} with code `VALIDATION` if the value doesn't match.
+ */
+declare function validate<S extends Schema>(schema: S, value: unknown): Promise<StandardSchemaV1.InferOutput<S>>;
+/**
+ * Synchronous validation for hot paths (e.g. client inbound dispatch).
+ *
+ * @param schema - the validator to run.
+ * @param value - the untrusted value to validate.
+ * @returns the parsed, typed value.
+ * @throws {@link SocketError} with code `VALIDATION` on mismatch, or `INTERNAL` if the schema is async.
+ */
+declare function validateSync<S extends Schema>(schema: S, value: unknown): StandardSchemaV1.InferOutput<S>;
+
+/**
+ * The wire protocol below is an implementation detail — you rarely touch frames
+ * directly. It's exported for adapters, custom transports, and tooling.
+ */
+/** Protocol version string, negotiated via the WebSocket subprotocol at upgrade. */
+declare const PROTOCOL = "superline.v1";
+interface ReqFrame {
+    t: 'req';
+    i: number;
+    m: string;
+    d: unknown;
+}
+interface SubFrame {
+    t: 'sub';
+    i: number;
+    c: string;
+}
+interface UnsubFrame {
+    t: 'unsub';
+    c: string;
+}
+type ClientFrame = ReqFrame | SubFrame | UnsubFrame;
+interface ResFrame {
+    t: 'res';
+    i: number;
+    d: unknown;
+}
+interface ErrFrame {
+    t: 'err';
+    i?: number;
+    code: string;
+    m: string;
+    d?: unknown;
+}
+interface EvtFrame {
+    t: 'evt';
+    e: string;
+    d: unknown;
+}
+interface PubFrame {
+    t: 'pub';
+    c: string;
+    d: unknown;
+}
+type ServerFrame = ResFrame | ErrFrame | EvtFrame | PubFrame;
+type Frame = ClientFrame | ServerFrame;
+
+export { type Adapter, type ClientFrame, type ClientInput, type Contract, type Directional, type EmitData, type ErrFrame, type ErrorCode, type EventData, type Events, type EvtFrame, type Frame, type InferIn, type InferOut, type Output, PROTOCOL, type PubFrame, type ReqFrame, type RequestDef, type Requests, type ResFrame, type RoleOf, type RoleRequests, type RoleTopics, type Schema, type Serializer, type ServerData, type ServerEmit, type ServerEvents, type ServerFrame, type ServerInput, type ServerMessageDef, type ServerMessages, type SharedEvents, type SharedRequests, type SharedTopics, SocketError, type SocketErrorCode, type SubFrame, type Topics, type UnsubFrame, defineContract, jsonSerializer, validate, validateSync };

package/dist/index.js

@@ -0,0 +1,59 @@
+// src/errors.ts
+var SocketError = class extends Error {
+  /** The typed error code (e.g. `'FORBIDDEN'`), available on the client. */
+  code;
+  /** Optional structured data attached to the error, delivered to the client. */
+  data;
+  /**
+   * @param code - a {@link SocketErrorCode} or custom string.
+   * @param message - human-readable message (defaults to `code`).
+   * @param data - optional structured payload delivered to the client.
+   */
+  constructor(code, message, data) {
+    super(message ?? code);
+    this.name = "SocketError";
+    this.code = code;
+    this.data = data;
+  }
+};
+
+// src/serializer.ts
+var decoder = new TextDecoder();
+var jsonSerializer = {
+  encode: (value) => JSON.stringify(value),
+  decode: (data) => JSON.parse(typeof data === "string" ? data : decoder.decode(data))
+};
+
+// src/contract.ts
+function defineContract(contract) {
+  return contract;
+}
+async function validate(schema, value) {
+  let result = schema["~standard"].validate(value);
+  if (result instanceof Promise) result = await result;
+  if (result.issues) {
+    throw new SocketError("VALIDATION", "Validation failed", result.issues);
+  }
+  return result.value;
+}
+function validateSync(schema, value) {
+  const result = schema["~standard"].validate(value);
+  if (result instanceof Promise) {
+    throw new SocketError("INTERNAL", "Async schema not supported for synchronous validation");
+  }
+  if (result.issues) {
+    throw new SocketError("VALIDATION", "Validation failed", result.issues);
+  }
+  return result.value;
+}
+
+// src/wire.ts
+var PROTOCOL = "superline.v1";
+export {
+  PROTOCOL,
+  SocketError,
+  defineContract,
+  jsonSerializer,
+  validate,
+  validateSync
+};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@super-line/core",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Shared contract, validation, wire protocol and errors for super-line.",
+  "license": "MIT",
+  "author": "Mert",
+  "keywords": [
+    "websocket",
+    "typesafe",
+    "contract",
+    "standard-schema",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mertdogar/super-line.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://mertdogar.github.io/super-line/",
+  "bugs": "https://github.com/mertdogar/super-line/issues",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@standard-schema/spec": "^1.0.0"
+  },
+  "devDependencies": {
+    "zod": "^3.24.1"
+  },
+  "scripts": {
+    "build": "tsup"
+  }
+}