@starcite/sdk 0.0.1

package/dist/index.cjs

@@ -0,0 +1,608 @@
+"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, {
+  StarciteApiError: () => StarciteApiError,
+  StarciteClient: () => StarciteClient,
+  StarciteConnectionError: () => StarciteConnectionError,
+  StarciteError: () => StarciteError,
+  StarciteSession: () => StarciteSession,
+  createStarciteClient: () => createStarciteClient,
+  normalizeBaseUrl: () => normalizeBaseUrl,
+  starcite: () => starcite
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var import_zod2 = require("zod");
+
+// src/errors.ts
+var StarciteError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "StarciteError";
+  }
+};
+var StarciteApiError = class extends StarciteError {
+  /** HTTP status code returned by the API. */
+  status;
+  /** Stable API error code (or synthesized `http_<status>` fallback). */
+  code;
+  /** Parsed API error payload when available. */
+  payload;
+  constructor(message, status, code, payload) {
+    super(message);
+    this.name = "StarciteApiError";
+    this.status = status;
+    this.code = code;
+    this.payload = payload;
+  }
+};
+var StarciteConnectionError = class extends StarciteError {
+  constructor(message) {
+    super(message);
+    this.name = "StarciteConnectionError";
+  }
+};
+
+// src/types.ts
+var import_zod = require("zod");
+var ArbitraryObjectSchema = import_zod.z.record(import_zod.z.unknown());
+var CreateSessionInputSchema = import_zod.z.object({
+  id: import_zod.z.string().optional(),
+  title: import_zod.z.string().optional(),
+  metadata: ArbitraryObjectSchema.optional()
+});
+var SessionRecordSchema = import_zod.z.object({
+  id: import_zod.z.string(),
+  title: import_zod.z.string().nullable().optional(),
+  metadata: ArbitraryObjectSchema,
+  last_seq: import_zod.z.number().int().nonnegative(),
+  created_at: import_zod.z.string(),
+  updated_at: import_zod.z.string()
+});
+var SessionListItemSchema = import_zod.z.object({
+  id: import_zod.z.string(),
+  title: import_zod.z.string().nullable().optional(),
+  metadata: ArbitraryObjectSchema,
+  created_at: import_zod.z.string()
+});
+var SessionListPageSchema = import_zod.z.object({
+  sessions: import_zod.z.array(SessionListItemSchema),
+  next_cursor: import_zod.z.string().nullable()
+});
+var AppendEventRequestSchema = import_zod.z.object({
+  type: import_zod.z.string().min(1),
+  payload: ArbitraryObjectSchema,
+  actor: import_zod.z.string().min(1),
+  producer_id: import_zod.z.string().min(1),
+  producer_seq: import_zod.z.number().int().positive(),
+  source: import_zod.z.string().optional(),
+  metadata: ArbitraryObjectSchema.optional(),
+  refs: ArbitraryObjectSchema.optional(),
+  idempotency_key: import_zod.z.string().optional(),
+  expected_seq: import_zod.z.number().int().nonnegative().optional()
+});
+var AppendEventResponseSchema = import_zod.z.object({
+  seq: import_zod.z.number().int().nonnegative(),
+  last_seq: import_zod.z.number().int().nonnegative(),
+  deduped: import_zod.z.boolean()
+});
+var TailEventSchema = import_zod.z.object({
+  seq: import_zod.z.number().int().nonnegative(),
+  type: import_zod.z.string().min(1),
+  payload: ArbitraryObjectSchema,
+  actor: import_zod.z.string().min(1),
+  producer_id: import_zod.z.string().min(1),
+  producer_seq: import_zod.z.number().int().positive(),
+  source: import_zod.z.string().optional(),
+  metadata: ArbitraryObjectSchema.optional(),
+  refs: ArbitraryObjectSchema.optional(),
+  idempotency_key: import_zod.z.string().nullable().optional(),
+  inserted_at: import_zod.z.string().optional()
+});
+var SessionEventInternalSchema = TailEventSchema.extend({
+  agent: import_zod.z.string().optional(),
+  text: import_zod.z.string().optional()
+});
+var SessionAppendInputSchema = import_zod.z.object({
+  agent: import_zod.z.string().trim().min(1),
+  producerId: import_zod.z.string().trim().min(1),
+  producerSeq: import_zod.z.number().int().positive(),
+  text: import_zod.z.string().optional(),
+  payload: ArbitraryObjectSchema.optional(),
+  type: import_zod.z.string().optional(),
+  source: import_zod.z.string().optional(),
+  metadata: ArbitraryObjectSchema.optional(),
+  refs: ArbitraryObjectSchema.optional(),
+  idempotencyKey: import_zod.z.string().optional(),
+  expectedSeq: import_zod.z.number().int().nonnegative().optional()
+}).refine((value) => !!(value.text || value.payload), {
+  message: "append() requires either 'text' or an object 'payload'"
+});
+var StarciteErrorPayloadSchema = import_zod.z.object({
+  error: import_zod.z.string().optional(),
+  message: import_zod.z.string().optional()
+}).catchall(import_zod.z.unknown());
+
+// src/client.ts
+var DEFAULT_BASE_URL = typeof process !== "undefined" && process.env.STARCITE_BASE_URL ? process.env.STARCITE_BASE_URL : "http://localhost:4000";
+var TRAILING_SLASHES_REGEX = /\/+$/;
+var BEARER_PREFIX_REGEX = /^bearer\s+/i;
+var TailFrameSchema = import_zod2.z.string().transform((frame, context) => {
+  try {
+    return JSON.parse(frame);
+  } catch {
+    context.addIssue({
+      code: import_zod2.z.ZodIssueCode.custom,
+      message: "Tail frame was not valid JSON"
+    });
+    return import_zod2.z.NEVER;
+  }
+}).pipe(TailEventSchema);
+var AsyncQueue = class {
+  items = [];
+  waiters = [];
+  settled = false;
+  push(value) {
+    if (this.settled) {
+      return;
+    }
+    this.enqueue({ type: "value", value });
+  }
+  close() {
+    if (this.settled) {
+      return;
+    }
+    this.settled = true;
+    this.enqueue({ type: "done" });
+  }
+  fail(error) {
+    if (this.settled) {
+      return;
+    }
+    this.settled = true;
+    this.enqueue({ type: "error", error: toError(error) });
+  }
+  async next() {
+    const item = this.items.shift() ?? await new Promise((resolve) => {
+      this.waiters.push(resolve);
+    });
+    if (item.type === "value") {
+      return { value: item.value, done: false };
+    }
+    if (item.type === "done") {
+      return { value: void 0, done: true };
+    }
+    throw item.error;
+  }
+  enqueue(item) {
+    const waiter = this.waiters.shift();
+    if (waiter) {
+      waiter(item);
+      return;
+    }
+    this.items.push(item);
+  }
+};
+function normalizeBaseUrl(baseUrl) {
+  const trimmed = baseUrl.trim().replace(TRAILING_SLASHES_REGEX, "");
+  return trimmed.endsWith("/v1") ? trimmed : `${trimmed}/v1`;
+}
+function toWebSocketBaseUrl(apiBaseUrl) {
+  if (apiBaseUrl.startsWith("https://")) {
+    return `wss://${apiBaseUrl.slice("https://".length)}`;
+  }
+  if (apiBaseUrl.startsWith("http://")) {
+    return `ws://${apiBaseUrl.slice("http://".length)}`;
+  }
+  throw new StarciteError(
+    `Invalid Starcite base URL '${apiBaseUrl}'. Use http:// or https://.`
+  );
+}
+function defaultWebSocketFactory(url, options = {}) {
+  if (typeof WebSocket === "undefined") {
+    throw new StarciteError(
+      "WebSocket is not available in this runtime. Provide websocketFactory in StarciteClientOptions."
+    );
+  }
+  const headers = new Headers(options.headers);
+  if (!hasAnyHeaders(headers)) {
+    return new WebSocket(url);
+  }
+  const headerObject = Object.fromEntries(headers.entries());
+  try {
+    return new WebSocket(url, { headers: headerObject });
+  } catch {
+    throw new StarciteError(
+      "This runtime cannot set WebSocket upgrade headers with the default factory. Provide websocketFactory in StarciteClientOptions."
+    );
+  }
+}
+function defaultFetch(input, init) {
+  if (typeof fetch === "undefined") {
+    throw new StarciteError(
+      "fetch is not available in this runtime. Provide fetch in StarciteClientOptions."
+    );
+  }
+  return fetch(input, init);
+}
+function toError(error) {
+  if (error instanceof Error) {
+    return error;
+  }
+  return new Error(typeof error === "string" ? error : "Unknown error");
+}
+function hasAnyHeaders(headers) {
+  for (const _ of headers.keys()) {
+    return true;
+  }
+  return false;
+}
+function formatAuthorizationHeader(apiKey) {
+  const normalized = apiKey.trim();
+  if (normalized.length === 0) {
+    throw new StarciteError("apiKey cannot be empty");
+  }
+  if (BEARER_PREFIX_REGEX.test(normalized)) {
+    return normalized;
+  }
+  return `Bearer ${normalized}`;
+}
+function parseEventFrame(data) {
+  const result = TailFrameSchema.safeParse(data);
+  if (!result.success) {
+    const reason = result.error.issues[0]?.message ?? "Tail frame did not match schema";
+    throw new StarciteConnectionError(reason);
+  }
+  return result.data;
+}
+function getEventData(event) {
+  if (event && typeof event === "object" && "data" in event) {
+    return event.data;
+  }
+  return void 0;
+}
+function agentFromActor(actor) {
+  if (actor.startsWith("agent:")) {
+    return actor.slice("agent:".length);
+  }
+  return void 0;
+}
+function toSessionEvent(event) {
+  const agent = agentFromActor(event.actor);
+  const text = typeof event.payload.text === "string" ? event.payload.text : void 0;
+  return {
+    ...event,
+    agent,
+    text
+  };
+}
+var StarciteSession = class {
+  /** Session identifier. */
+  id;
+  /** Optional session record captured at creation time. */
+  record;
+  client;
+  constructor(client, id, record) {
+    this.client = client;
+    this.id = id;
+    this.record = record;
+  }
+  /**
+   * Appends a high-level agent event to this session.
+   *
+   * Automatically prefixes `agent` as `agent:<name>` when needed.
+   */
+  append(input) {
+    const parsed = SessionAppendInputSchema.parse(input);
+    const actor = parsed.agent.startsWith("agent:") ? parsed.agent : `agent:${parsed.agent}`;
+    return this.client.appendEvent(this.id, {
+      type: parsed.type ?? "content",
+      payload: parsed.payload ?? { text: parsed.text },
+      actor,
+      producer_id: parsed.producerId,
+      producer_seq: parsed.producerSeq,
+      source: parsed.source ?? "agent",
+      metadata: parsed.metadata,
+      refs: parsed.refs,
+      idempotency_key: parsed.idempotencyKey,
+      expected_seq: parsed.expectedSeq
+    });
+  }
+  /**
+   * Appends a raw event payload as-is.
+   */
+  appendRaw(input) {
+    return this.client.appendEvent(this.id, input);
+  }
+  /**
+   * Streams transformed session events with SDK convenience fields (`agent`, `text`).
+   */
+  tail(options = {}) {
+    return this.client.tailEvents(this.id, options);
+  }
+  /**
+   * Streams raw tail events returned by the API.
+   */
+  tailRaw(options = {}) {
+    return this.client.tailRawEvents(this.id, options);
+  }
+};
+var StarciteClient = class {
+  /** Normalized API base URL ending with `/v1`. */
+  baseUrl;
+  websocketBaseUrl;
+  fetchFn;
+  headers;
+  websocketFactory;
+  /**
+   * Creates a new client instance.
+   */
+  constructor(options = {}) {
+    this.baseUrl = normalizeBaseUrl(options.baseUrl ?? DEFAULT_BASE_URL);
+    this.websocketBaseUrl = toWebSocketBaseUrl(this.baseUrl);
+    this.fetchFn = options.fetch ?? defaultFetch;
+    this.headers = new Headers(options.headers);
+    if (options.apiKey !== void 0) {
+      this.headers.set(
+        "authorization",
+        formatAuthorizationHeader(options.apiKey)
+      );
+    }
+    this.websocketFactory = options.websocketFactory ?? defaultWebSocketFactory;
+  }
+  /**
+   * Returns a session helper bound to an existing session id.
+   */
+  session(sessionId, record) {
+    return new StarciteSession(this, sessionId, record);
+  }
+  /**
+   * Creates a new session and returns a bound `StarciteSession` helper.
+   */
+  async create(input = {}) {
+    const record = await this.createSession(input);
+    return this.session(record.id, record);
+  }
+  /**
+   * Creates a new session and returns the raw session record.
+   */
+  createSession(input = {}) {
+    const payload = CreateSessionInputSchema.parse(input);
+    return this.request(
+      "/sessions",
+      {
+        method: "POST",
+        body: JSON.stringify(payload)
+      },
+      SessionRecordSchema
+    );
+  }
+  /**
+   * Lists sessions from the archive-backed catalog.
+   */
+  listSessions(options = {}) {
+    const query = new URLSearchParams();
+    if (options.limit !== void 0) {
+      if (!Number.isInteger(options.limit) || options.limit <= 0) {
+        throw new StarciteError(
+          "listSessions() limit must be a positive integer"
+        );
+      }
+      query.set("limit", `${options.limit}`);
+    }
+    if (options.cursor !== void 0) {
+      if (options.cursor.trim().length === 0) {
+        throw new StarciteError("listSessions() cursor cannot be empty");
+      }
+      query.set("cursor", options.cursor);
+    }
+    if (options.metadata !== void 0) {
+      for (const [key, value] of Object.entries(options.metadata)) {
+        if (key.trim().length === 0 || value.trim().length === 0) {
+          throw new StarciteError(
+            "listSessions() metadata filters must be non-empty strings"
+          );
+        }
+        query.set(`metadata.${key}`, value);
+      }
+    }
+    const suffix = query.size > 0 ? `?${query.toString()}` : "";
+    return this.request(
+      `/sessions${suffix}`,
+      {
+        method: "GET"
+      },
+      SessionListPageSchema
+    );
+  }
+  /**
+   * Appends a raw event payload to a specific session.
+   */
+  appendEvent(sessionId, input) {
+    const payload = AppendEventRequestSchema.parse(input);
+    return this.request(
+      `/sessions/${encodeURIComponent(sessionId)}/append`,
+      {
+        method: "POST",
+        body: JSON.stringify(payload)
+      },
+      AppendEventResponseSchema
+    );
+  }
+  /**
+   * Opens a WebSocket tail stream and yields raw events.
+   */
+  async *tailRawEvents(sessionId, options = {}) {
+    const queue = new AsyncQueue();
+    const cursor = options.cursor ?? 0;
+    if (!Number.isInteger(cursor) || cursor < 0) {
+      throw new StarciteError("tail() cursor must be a non-negative integer");
+    }
+    const wsUrl = `${this.websocketBaseUrl}/sessions/${encodeURIComponent(
+      sessionId
+    )}/tail?cursor=${cursor}`;
+    const websocketHeaders = new Headers();
+    const authorization = this.headers.get("authorization");
+    if (authorization) {
+      websocketHeaders.set("authorization", authorization);
+    }
+    const socket = this.websocketFactory(
+      wsUrl,
+      hasAnyHeaders(websocketHeaders) ? {
+        headers: websocketHeaders
+      } : void 0
+    );
+    const onMessage = (event) => {
+      try {
+        const parsed = parseEventFrame(getEventData(event));
+        if (options.agent && agentFromActor(parsed.actor) !== options.agent) {
+          return;
+        }
+        queue.push(parsed);
+      } catch (error) {
+        queue.fail(error);
+      }
+    };
+    const onError = () => {
+      queue.fail(
+        new StarciteConnectionError(
+          `Tail connection failed for session '${sessionId}'`
+        )
+      );
+    };
+    const onClose = () => {
+      queue.close();
+    };
+    socket.addEventListener("message", onMessage);
+    socket.addEventListener("error", onError);
+    socket.addEventListener("close", onClose);
+    const onAbort = () => {
+      queue.close();
+      socket.close(1e3, "aborted");
+    };
+    if (options.signal) {
+      if (options.signal.aborted) {
+        onAbort();
+      } else {
+        options.signal.addEventListener("abort", onAbort, { once: true });
+      }
+    }
+    try {
+      while (true) {
+        const next = await queue.next();
+        if (next.done) {
+          break;
+        }
+        yield next.value;
+      }
+    } finally {
+      socket.removeEventListener("message", onMessage);
+      socket.removeEventListener("error", onError);
+      socket.removeEventListener("close", onClose);
+      if (options.signal) {
+        options.signal.removeEventListener("abort", onAbort);
+      }
+      socket.close(1e3, "finished");
+    }
+  }
+  /**
+   * Opens a WebSocket tail stream and yields transformed session events.
+   */
+  async *tailEvents(sessionId, options = {}) {
+    for await (const rawEvent of this.tailRawEvents(sessionId, options)) {
+      yield toSessionEvent(rawEvent);
+    }
+  }
+  async request(path, init, schema) {
+    const headers = new Headers(this.headers);
+    if (!headers.has("content-type")) {
+      headers.set("content-type", "application/json");
+    }
+    if (init.headers) {
+      const perRequestHeaders = new Headers(init.headers);
+      for (const [key, value] of perRequestHeaders.entries()) {
+        headers.set(key, value);
+      }
+    }
+    let response;
+    try {
+      response = await this.fetchFn(`${this.baseUrl}${path}`, {
+        ...init,
+        headers
+      });
+    } catch (error) {
+      const rootCause = toError(error).message;
+      throw new StarciteConnectionError(
+        `Failed to connect to Starcite at ${this.baseUrl}: ${rootCause}`
+      );
+    }
+    if (!response.ok) {
+      const payload = await tryParseJson(response);
+      const code = typeof payload?.error === "string" ? payload.error : `http_${response.status}`;
+      const message = typeof payload?.message === "string" ? payload.message : response.statusText;
+      throw new StarciteApiError(message, response.status, code, payload);
+    }
+    if (response.status === 204) {
+      return void 0;
+    }
+    const responseBody = await response.json();
+    if (!schema) {
+      return responseBody;
+    }
+    const parsed = schema.safeParse(responseBody);
+    if (!parsed.success) {
+      const issue = parsed.error.issues[0]?.message ?? "invalid response";
+      throw new StarciteConnectionError(
+        `Received unexpected response payload from Starcite: ${issue}`
+      );
+    }
+    return parsed.data;
+  }
+};
+async function tryParseJson(response) {
+  try {
+    const parsed = await response.json();
+    const result = StarciteErrorPayloadSchema.safeParse(parsed);
+    return result.success ? result.data : null;
+  } catch {
+    return null;
+  }
+}
+
+// src/index.ts
+function createStarciteClient(options = {}) {
+  return new StarciteClient(options);
+}
+var starcite = createStarciteClient();
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  StarciteApiError,
+  StarciteClient,
+  StarciteConnectionError,
+  StarciteError,
+  StarciteSession,
+  createStarciteClient,
+  normalizeBaseUrl,
+  starcite
+});
+//# sourceMappingURL=index.cjs.map