stitchkit 0.93.0 → 0.94.1

package/dist/entrypoints/index.js

@@ -0,0 +1,764 @@
+import {
+  defineRealtimeContract
+} from "../index-p7hgdyhb.js";
+import {
+  BackoffPolicySchema,
+  createBackoff
+} from "../index-ngfhvfpd.js";
+import {
+  contractEndpointMatchers,
+  createClient,
+  createClients,
+  createScopedClients,
+  createScopedUrlBuilders,
+  createUrlBuilder,
+  createUrlBuilders,
+  parseNDJSON,
+  parseSSE
+} from "../index-ham5sz8m.js";
+import {
+  REALTIME_REJECTION_KEY,
+  asRealtimeRejection,
+  createValidatedRealtimeSocket,
+  isModuleNotFound,
+  parseRealtimeRequestAcknowledgement,
+  parseRealtimeRequestArguments
+} from "../index-ndddxtyx.js";
+import {
+  RealtimeRequestDisconnectedError,
+  RealtimeRequestInvalidAcknowledgementError,
+  RealtimeRequestPhaseEventSchema,
+  RealtimeRequestPhaseSchema,
+  RealtimeRequestRejectedError,
+  RealtimeRequestTimeoutError
+} from "../index-dce5wxcq.js";
+import"../index-48ffdxgk.js";
+import {
+  createContractFactory,
+  decodeCursor,
+  defineErrors,
+  encodeCursor,
+  paginatedSchema
+} from "../index-7p1f0vp2.js";
+import {
+  ContractStreamFrameSchema,
+  DEFAULT_CONTRACT_STREAM_FRAME_BYTES
+} from "../index-wqgjfstn.js";
+import {
+  LiveStateControllerStatusSchema,
+  LiveStatePhaseSchema,
+  LiveStateStopReasonSchema,
+  createLiveStateController
+} from "../index-1j8pm5t0.js";
+import"../index-d9pk3td4.js";
+import {
+  ApiError,
+  createHttpClient
+} from "../index-v260df89.js";
+import"../index-rxfy4cq7.js";
+import {
+  ALL_TRANSPORTS,
+  TOOL_TRANSPORTS,
+  defineContract,
+  withToolView
+} from "../index-k30h66yd.js";
+import"../index-4gcnakhx.js";
+import {
+  ManagedFilePathSchema,
+  ManagedFileRefSchema
+} from "../index-6k1937bx.js";
+import {
+  childSpan,
+  createTraceContext,
+  formatTraceparent,
+  parseTraceparent,
+  randomHex
+} from "../index-zcgf3gqf.js";
+import {
+  formatZodError,
+  zodIssues
+} from "../index-p5r7qpdd.js";
+import {
+  AppError,
+  STITCH_ERROR_STATUS,
+  appError,
+  badRequest,
+  conflict,
+  forbidden,
+  isRetryableStatus,
+  isStitchErrorCode,
+  notFound,
+  rateLimited,
+  unauthorized
+} from "../index-2vtcmrj9.js";
+import"../index-kzfs85xp.js";
+import"../index-hffjpmq9.js";
+// src/browser/socket-io-trace.ts
+var realtimeRequestTraces = new WeakMap;
+function observeRealtimeRequestPhase(trace, phase) {
+  const observation = {
+    requestId: trace.requestId,
+    event: trace.event,
+    phase,
+    elapsedMs: performance.now() - trace.startedAt
+  };
+  const observers = trace.observeRequest && trace.observeRequest !== trace.observeClient ? [trace.observeClient, trace.observeRequest] : [trace.observeClient ?? trace.observeRequest];
+  for (const observer of observers) {
+    if (!observer)
+      continue;
+    try {
+      const result = observer(observation);
+      if (result)
+        Promise.resolve(result).catch(() => {
+          return;
+        });
+    } catch {}
+  }
+}
+function socketIoPacketIdentity(data, expected) {
+  if (typeof data !== "string")
+    return null;
+  const type = data.charAt(0);
+  const binary = type === (expected === "event" ? "5" : "6");
+  if (type !== (expected === "event" ? "2" : "3") && !binary)
+    return null;
+  let offset = 1;
+  if (binary) {
+    const separator = data.indexOf("-", offset);
+    if (separator < 0)
+      return null;
+    for (let index = offset;index < separator; index += 1) {
+      const code = data.charCodeAt(index);
+      if (code < 48 || code > 57)
+        return null;
+    }
+    offset = separator + 1;
+  }
+  let namespace = "/";
+  if (data.charAt(offset) === "/") {
+    const separator = data.indexOf(",", offset);
+    if (separator < 0)
+      return null;
+    namespace = data.slice(offset, separator);
+    offset = separator + 1;
+  }
+  const start = offset;
+  while (offset < data.length) {
+    const code = data.charCodeAt(offset);
+    if (code < 48 || code > 57)
+      break;
+    offset += 1;
+  }
+  if (offset === start)
+    return null;
+  return { namespace, id: data.slice(start, offset) };
+}
+function packetIdentityKey(identity) {
+  return `${identity.namespace}:${identity.id}`;
+}
+function createRequestTracer(onRequestPhase) {
+  const requestTracesByNativeKey = new Map;
+  const observedRequestEngines = new WeakSet;
+  let startingRequestTrace = null;
+  return {
+    start(event, onPhase) {
+      if (!onRequestPhase && !onPhase)
+        return;
+      const trace = {
+        requestId: randomHex(16),
+        event,
+        startedAt: performance.now(),
+        observeClient: onRequestPhase,
+        observeRequest: onPhase,
+        closed: false
+      };
+      return trace;
+    },
+    close(trace, phase) {
+      if (!trace || trace.closed)
+        return;
+      trace.closed = true;
+      if (trace.nativeKey)
+        requestTracesByNativeKey.delete(trace.nativeKey);
+      observeRealtimeRequestPhase(trace, phase);
+    },
+    starting(trace, emit) {
+      startingRequestTrace = trace ?? null;
+      try {
+        return emit();
+      } finally {
+        startingRequestTrace = null;
+      }
+    },
+    observeEachOpen(target, current) {
+      if (!onRequestPhase)
+        return;
+      target.io.on("open", () => {
+        const socket = current();
+        if (socket)
+          this.observe(socket);
+      });
+    },
+    observe(target) {
+      const engine = target.io.engine;
+      if (!engine || observedRequestEngines.has(engine))
+        return;
+      observedRequestEngines.add(engine);
+      engine.on("packetCreate", (packet) => {
+        if (!startingRequestTrace || packet.type !== "message")
+          return;
+        const identity = socketIoPacketIdentity(packet.data, "event");
+        if (!identity)
+          return;
+        const key = packetIdentityKey(identity);
+        startingRequestTrace.nativeKey = key;
+        requestTracesByNativeKey.set(key, startingRequestTrace);
+        observeRealtimeRequestPhase(startingRequestTrace, "engine-handoff");
+      });
+      engine.on("packet", (packet) => {
+        if (packet.type !== "message")
+          return;
+        const identity = socketIoPacketIdentity(packet.data, "ack");
+        if (!identity)
+          return;
+        const key = packetIdentityKey(identity);
+        const trace = requestTracesByNativeKey.get(key);
+        if (!trace || trace.closed)
+          return;
+        observeRealtimeRequestPhase(trace, "engine-ack-received");
+        requestTracesByNativeKey.delete(key);
+      });
+    }
+  };
+}
+
+// src/browser/realtime-client.ts
+function assertRealtimeClientTransport(transport) {
+  for (const capability of ["on", "emit", "emitWithAck", "onConnectionChange"]) {
+    if (typeof Reflect.get(transport, capability) !== "function") {
+      throw new TypeError(`Realtime client transport does not implement ${capability}()`);
+    }
+  }
+  if (typeof transport.connected !== "boolean") {
+    throw new TypeError("Realtime client transport does not expose boolean connected");
+  }
+}
+function bindRealtimeClient(contract, transport, { onRejected, logger } = {}) {
+  assertRealtimeClientTransport(transport);
+  const events = createValidatedRealtimeSocket({
+    target: transport,
+    inbound: contract.serverToClient,
+    outbound: contract.clientToServer,
+    inboundDirection: "client-inbound",
+    outboundDirection: "client-outbound",
+    onRejected,
+    logger,
+    subscribe: (event, handler) => {
+      const subscribe = Reflect.get(transport, "on");
+      if (typeof subscribe !== "function") {
+        throw new Error("Socket.IO client does not implement on()");
+      }
+      const unsubscribe = Reflect.apply(subscribe, transport, [event, handler]);
+      if (typeof unsubscribe !== "function") {
+        throw new Error("Socket.IO client on() did not return an unsubscribe function");
+      }
+      return () => {
+        Reflect.apply(unsubscribe, undefined, []);
+      };
+    }
+  });
+  async function request(event, ...args) {
+    const options = args.at(-1);
+    if (!options || typeof options !== "object" || !("timeoutMs" in options)) {
+      throw new TypeError(`Realtime request "${event}" requires { timeoutMs }`);
+    }
+    const timeoutMs = options.timeoutMs;
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+      throw new RangeError(`Realtime request "${event}" timeoutMs must be finite and > 0`);
+    }
+    const values = args.slice(0, -1);
+    const parsedArgs = parseRealtimeRequestArguments(contract.clientToServer, event, "client-outbound", values);
+    const definition = contract.clientToServer[event];
+    if (!definition?.ack) {
+      throw new Error(`Realtime request "${event}" has no acknowledgement schema`);
+    }
+    const pending = transport.emitWithAck(event, parsedArgs, options);
+    const trace = realtimeRequestTraces.get(pending);
+    if (trace)
+      realtimeRequestTraces.delete(pending);
+    const value = await pending;
+    let acknowledgement;
+    try {
+      acknowledgement = parseRealtimeRequestAcknowledgement(definition.ack, event, "client-inbound", value, onRejected, logger);
+    } finally {
+      if (trace && !trace.closed) {
+        trace.closed = true;
+        observeRealtimeRequestPhase(trace, "settled");
+      }
+    }
+    return acknowledgement;
+  }
+  return {
+    ...events,
+    get connected() {
+      return transport.connected;
+    },
+    request,
+    onConnectionChange: (listener) => transport.onConnectionChange(listener)
+  };
+}
+// src/browser/resumable.ts
+var DEFAULT_RETRY = { minDelayMs: 100, maxDelayMs: 30000, jitter: 0.5 };
+
+class ResumableAbortError extends Error {
+  constructor() {
+    super("Resumable iterator was aborted");
+    this.name = "ResumableAbortError";
+  }
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    function onAbort() {
+      clearTimeout(timer);
+      reject(new ResumableAbortError);
+    }
+    if (signal?.aborted) {
+      clearTimeout(timer);
+      reject(new ResumableAbortError);
+      return;
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+async function* resumableIterator(config) {
+  const backoff = createBackoff(config.retry ?? DEFAULT_RETRY, config.random);
+  let cursor;
+  let attempt = 0;
+  for (;; ) {
+    if (config.signal?.aborted)
+      return;
+    try {
+      const source = await config.open(cursor);
+      for await (const item of source) {
+        if (config.signal?.aborted)
+          return;
+        attempt = 0;
+        backoff.reset();
+        cursor = config.advance(item, cursor);
+        yield item;
+        if (config.isTerminal?.(item))
+          return;
+      }
+      throw new Error("Resumable source ended without a terminal item");
+    } catch (error) {
+      if (config.signal?.aborted || error instanceof ResumableAbortError)
+        return;
+      attempt += 1;
+      const delayMs = backoff.next();
+      config.onAttempt?.({ number: attempt, delayMs, error });
+      try {
+        await sleep(delayMs, config.signal);
+      } catch {
+        return;
+      }
+    }
+  }
+}
+// src/browser/retained.ts
+function createRetainedTopics() {
+  const last = {};
+  return {
+    record(topic, payload) {
+      last[topic] = payload;
+    },
+    replay(topic, handler) {
+      const value = last[topic];
+      if (value !== undefined)
+        handler(value);
+    },
+    get(topic) {
+      return last[topic];
+    },
+    clear(topic) {
+      if (topic !== undefined) {
+        delete last[topic];
+        return;
+      }
+      for (const key of Object.keys(last))
+        Reflect.deleteProperty(last, key);
+    }
+  };
+}
+// src/browser/socket-io-connection.ts
+function toIoAuth(auth) {
+  if (typeof auth !== "function")
+    return auth;
+  return (cb) => {
+    Promise.resolve().then(auth).then(cb, () => cb({}));
+  };
+}
+function ioOptions(config) {
+  return {
+    path: config.path ?? "/socket.io/",
+    withCredentials: config.withCredentials ?? true,
+    auth: toIoAuth(config.auth),
+    ...config.query && { query: config.query },
+    ...config.extraHeaders && { extraHeaders: config.extraHeaders },
+    transports: config.transports ?? ["websocket", "polling"],
+    autoConnect: false,
+    reconnection: true,
+    reconnectionAttempts: config.reconnectionAttempts ?? Infinity,
+    reconnectionDelay: config.reconnectionDelay ?? 1000,
+    reconnectionDelayMax: config.reconnectionDelayMax ?? 5000,
+    timeout: config.timeout ?? 20000
+  };
+}
+function reportPeerFailure(config, error) {
+  if (!config.onConnectError)
+    throw error;
+  config.onConnectError({
+    message: error instanceof Error ? error.message : String(error),
+    data: error,
+    terminal: true
+  });
+}
+function awaitAcknowledgement(input) {
+  const { active, event } = input;
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (result) => {
+      if (settled)
+        return;
+      settled = true;
+      input.pendingRequestDisconnects.delete(onDisconnect);
+      active.off("disconnect", onDisconnect);
+      result();
+    };
+    const onDisconnect = () => {
+      finish(() => {
+        input.closeTrace("disconnected");
+        reject(new RealtimeRequestDisconnectedError(event));
+      });
+    };
+    input.pendingRequestDisconnects.add(onDisconnect);
+    active.on("disconnect", onDisconnect);
+    const acknowledgement = input.emit();
+    acknowledgement.then((value) => finish(() => resolve(value)), () => {
+      finish(() => {
+        const connected = active.connected;
+        input.closeTrace(connected ? "timeout" : "disconnected");
+        reject(connected ? new RealtimeRequestTimeoutError(event, input.timeoutMs) : new RealtimeRequestDisconnectedError(event));
+      });
+    });
+  });
+}
+function createStickyEvents(retain) {
+  const names = retain ? retain.map(String) : [];
+  const known = new Set(names);
+  const retained = names.length > 0 ? createRetainedTopics() : null;
+  return {
+    record(socket) {
+      if (!retained)
+        return;
+      for (const name of names) {
+        socket.on(name, (payload) => retained.record(name, payload));
+      }
+    },
+    replay(name, handler) {
+      if (retained && known.has(name))
+        retained.replay(name, (payload) => handler(payload));
+    }
+  };
+}
+function createRecycle(delay) {
+  let timer = null;
+  const clear = () => {
+    if (timer === null)
+      return;
+    clearTimeout(timer);
+    timer = null;
+  };
+  return {
+    clear,
+    schedule(run) {
+      if (delay === false)
+        return;
+      clear();
+      timer = setTimeout(() => {
+        timer = null;
+        run();
+      }, delay);
+    }
+  };
+}
+function connectErrorReport(error, socket) {
+  return {
+    message: error.message,
+    data: Reflect.get(error, "data"),
+    terminal: socket !== null && !socket.active
+  };
+}
+
+// src/browser/socket-io-peer.ts
+var SOCKET_IO_CLIENT = "socket.io-client";
+var ioLoader = null;
+function loadIo() {
+  if (!ioLoader) {
+    ioLoader = import(/* webpackIgnore: true */ SOCKET_IO_CLIENT).then((mod) => mod.io, (cause) => {
+      ioLoader = null;
+      throw new Error("stitchkit: createSocketIOClient needs the \"socket.io-client\" peer — install it (e.g. `bun add socket.io-client`). Shipping one self-contained artifact instead? Pass `peers: { client: () => import('socket.io-client') }` so your bundler puts it inside.", { cause });
+    });
+  }
+  return ioLoader;
+}
+function isIoModule(module) {
+  if (typeof module !== "object" || module === null)
+    return false;
+  return typeof Reflect.get(module, "io") === "function";
+}
+function createIoResolver(injected) {
+  if (!injected)
+    return loadIo;
+  let pending = null;
+  return () => {
+    if (!pending) {
+      pending = injected().then((module) => {
+        const io = isIoModule(module) ? module.io : null;
+        if (!io) {
+          pending = null;
+          throw new Error("stitchkit: the loader passed in `peers.client` did not return the \"socket.io-client\" module — it must resolve to the module itself, as `() => import('socket.io-client')`.");
+        }
+        return io;
+      }, (cause) => {
+        pending = null;
+        if (!isModuleNotFound(cause))
+          throw cause;
+        throw new Error('stitchkit: createSocketIOClient could not load "socket.io-client" through the loader passed in `peers` — the artifact does not contain it. Check that the loader is a literal `import(\'socket.io-client\')` your bundler can follow, and that "socket.io-client" is a dependency of the package being bundled.', { cause });
+      });
+    }
+    return pending;
+  };
+}
+
+// src/browser/socket-io.ts
+function createRealtimeClient(contract, { onRejected, logger, onRequestPhase, ...config }) {
+  const transport = createSocketIOClientInternal(config, onRequestPhase);
+  const bound = bindRealtimeClient(contract, transport, { onRejected, logger });
+  return {
+    ...bound,
+    get connected() {
+      return bound.connected;
+    },
+    connect: transport.connect,
+    disconnect: transport.disconnect
+  };
+}
+function createSocketIOClient(config) {
+  return createSocketIOClientInternal(config);
+}
+function createSocketIOClientInternal(config, onRequestPhase) {
+  let socket = null;
+  const resolveIo = createIoResolver(config.peers?.client);
+  let desiredConnected = false;
+  let loadingPeer = false;
+  const recycle = createRecycle(config.reconnectOnServerDisconnect ?? 1000);
+  const pendingRequestDisconnects = new Set;
+  const tracer = createRequestTracer(onRequestPhase);
+  const connectionListeners = new Set;
+  const subscriptions = new Set;
+  const sticky = createStickyEvents(config.retain);
+  function notifyConnection(connected, reason) {
+    for (const listener of connectionListeners)
+      listener(connected, reason);
+  }
+  function openSocket(io) {
+    if (!desiredConnected || socket)
+      return;
+    socket = io(config.url, ioOptions(config));
+    tracer.observeEachOpen(socket, () => socket);
+    socket.on("connect", () => notifyConnection(true));
+    socket.on("disconnect", (reason) => {
+      notifyConnection(false, reason);
+      if (reason === "io server disconnect") {
+        const current = socket;
+        recycle.schedule(() => {
+          if (socket === current && current && !current.connected)
+            current.connect();
+        });
+      }
+    });
+    socket.io.on("reconnect_failed", () => {
+      desiredConnected = false;
+    });
+    socket.on("connect_error", (error) => {
+      const report = connectErrorReport(error, socket);
+      if (report.terminal)
+        desiredConnected = false;
+      config.onConnectError?.(report);
+    });
+    sticky.record(socket);
+    for (const attach of subscriptions)
+      attach(socket);
+    socket.connect();
+  }
+  return {
+    get connected() {
+      return socket?.connected ?? false;
+    },
+    connect() {
+      if (socket?.connected || desiredConnected)
+        return;
+      desiredConnected = true;
+      if (socket) {
+        socket.connect();
+        return;
+      }
+      if (loadingPeer)
+        return;
+      loadingPeer = true;
+      resolveIo().then((io) => {
+        loadingPeer = false;
+        openSocket(io);
+      }, (error) => {
+        loadingPeer = false;
+        desiredConnected = false;
+        reportPeerFailure(config, error);
+      });
+    },
+    disconnect() {
+      desiredConnected = false;
+      recycle.clear();
+      for (const reject of [...pendingRequestDisconnects])
+        reject();
+      if (!socket)
+        return;
+      const wasConnected = socket.connected;
+      socket.removeAllListeners();
+      socket.disconnect();
+      socket = null;
+      if (wasConnected)
+        notifyConnection(false);
+    },
+    on(event, handler) {
+      const name = event;
+      const attach = (s) => {
+        s.on(name, handler);
+      };
+      subscriptions.add(attach);
+      if (socket)
+        attach(socket);
+      const fn = handler;
+      sticky.replay(name, fn);
+      return () => {
+        subscriptions.delete(attach);
+        socket?.off(name, handler);
+      };
+    },
+    emit(event, ...args) {
+      const name = event;
+      if (!socket?.connected) {
+        config.onDroppedEmit?.({ event: name, args });
+        return false;
+      }
+      socket.emit(name, ...args);
+      return true;
+    },
+    emitWithAck(event, args, options) {
+      const trace = tracer.start(event, options.onPhase);
+      const closeTrace = (phase) => tracer.close(trace, phase);
+      const active = socket;
+      if (!active?.connected) {
+        const pending2 = Promise.reject(new RealtimeRequestDisconnectedError(event));
+        closeTrace("disconnected");
+        if (trace)
+          realtimeRequestTraces.set(pending2, trace);
+        return pending2;
+      }
+      if (trace)
+        tracer.observe(active);
+      const pending = awaitAcknowledgement({
+        active,
+        event,
+        args,
+        timeoutMs: options.timeoutMs,
+        pendingRequestDisconnects,
+        closeTrace,
+        emit: () => tracer.starting(trace, () => active.timeout(options.timeoutMs).emitWithAck(event, ...args))
+      });
+      if (trace)
+        realtimeRequestTraces.set(pending, trace);
+      return pending;
+    },
+    onConnectionChange(listener) {
+      connectionListeners.add(listener);
+      return () => connectionListeners.delete(listener);
+    }
+  };
+}
+export {
+  zodIssues,
+  withToolView,
+  unauthorized,
+  resumableIterator,
+  rateLimited,
+  parseTraceparent,
+  parseSSE,
+  parseNDJSON,
+  paginatedSchema,
+  notFound,
+  isStitchErrorCode,
+  isRetryableStatus,
+  formatZodError,
+  formatTraceparent,
+  forbidden,
+  encodeCursor,
+  defineRealtimeContract,
+  defineErrors,
+  defineContract,
+  decodeCursor,
+  createUrlBuilders,
+  createUrlBuilder,
+  createTraceContext,
+  createSocketIOClient,
+  createScopedUrlBuilders,
+  createScopedClients,
+  createRetainedTopics,
+  createRealtimeClient,
+  createLiveStateController,
+  createHttpClient,
+  createContractFactory,
+  createClients,
+  createClient,
+  createBackoff,
+  contractEndpointMatchers,
+  conflict,
+  childSpan,
+  bindRealtimeClient,
+  badRequest,
+  asRealtimeRejection,
+  appError,
+  TOOL_TRANSPORTS,
+  STITCH_ERROR_STATUS,
+  RealtimeRequestTimeoutError,
+  RealtimeRequestRejectedError,
+  RealtimeRequestPhaseSchema,
+  RealtimeRequestPhaseEventSchema,
+  RealtimeRequestInvalidAcknowledgementError,
+  RealtimeRequestDisconnectedError,
+  REALTIME_REJECTION_KEY,
+  ManagedFileRefSchema,
+  ManagedFilePathSchema,
+  LiveStateStopReasonSchema,
+  LiveStatePhaseSchema,
+  LiveStateControllerStatusSchema,
+  DEFAULT_CONTRACT_STREAM_FRAME_BYTES,
+  ContractStreamFrameSchema,
+  BackoffPolicySchema,
+  AppError,
+  ApiError,
+  ALL_TRANSPORTS
+};