@starcite/sdk 0.0.1

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/client.ts","../src/errors.ts","../src/types.ts"],"sourcesContent":["import { StarciteClient } from \"./client\";\nimport type { StarciteClientOptions } from \"./types\";\n\n// biome-ignore lint/performance/noBarrelFile: package entrypoint intentionally re-exports public API.\nexport { normalizeBaseUrl, StarciteClient, StarciteSession } from \"./client\";\nexport {\n  StarciteApiError,\n  StarciteConnectionError,\n  StarciteError,\n} from \"./errors\";\nexport type {\n  AppendEventRequest,\n  AppendEventResponse,\n  CreateSessionInput,\n  SessionAppendInput,\n  SessionEvent,\n  SessionListItem,\n  SessionListOptions,\n  SessionListPage,\n  SessionRecord,\n  SessionTailOptions,\n  StarciteClientOptions,\n  StarciteErrorPayload,\n  StarciteWebSocket,\n  StarciteWebSocketConnectOptions,\n  StarciteWebSocketFactory,\n  TailEvent,\n} from \"./types\";\n/**\n * Creates a new {@link StarciteClient} instance.\n */\nexport function createStarciteClient(\n  options: StarciteClientOptions = {}\n): StarciteClient {\n  return new StarciteClient(options);\n}\n\n/**\n * Default singleton client using environment/default configuration.\n */\nexport const starcite = createStarciteClient();\n","import { z } from \"zod\";\nimport {\n  StarciteApiError,\n  StarciteConnectionError,\n  StarciteError,\n} from \"./errors\";\nimport type {\n  AppendEventRequest,\n  AppendEventResponse,\n  CreateSessionInput,\n  SessionAppendInput,\n  SessionEvent,\n  SessionListOptions,\n  SessionListPage,\n  SessionRecord,\n  SessionTailOptions,\n  StarciteClientOptions,\n  StarciteErrorPayload,\n  StarciteWebSocket,\n  StarciteWebSocketConnectOptions,\n  TailEvent,\n} from \"./types\";\nimport {\n  AppendEventRequestSchema,\n  AppendEventResponseSchema,\n  CreateSessionInputSchema,\n  SessionAppendInputSchema,\n  SessionListPageSchema,\n  SessionRecordSchema,\n  StarciteErrorPayloadSchema,\n  TailEventSchema,\n} from \"./types\";\n\nconst DEFAULT_BASE_URL =\n  typeof process !== \"undefined\" && process.env.STARCITE_BASE_URL\n    ? process.env.STARCITE_BASE_URL\n    : \"http://localhost:4000\";\nconst TRAILING_SLASHES_REGEX = /\\/+$/;\nconst BEARER_PREFIX_REGEX = /^bearer\\s+/i;\n\nconst TailFrameSchema = z\n  .string()\n  .transform((frame, context): unknown => {\n    try {\n      return JSON.parse(frame) as unknown;\n    } catch {\n      context.addIssue({\n        code: z.ZodIssueCode.custom,\n        message: \"Tail frame was not valid JSON\",\n      });\n      return z.NEVER;\n    }\n  })\n  .pipe(TailEventSchema);\n\nclass AsyncQueue<T> {\n  private readonly items: Array<\n    | { type: \"value\"; value: T }\n    | { type: \"done\" }\n    | { type: \"error\"; error: Error }\n  > = [];\n  private readonly waiters: Array<\n    (\n      item:\n        | { type: \"value\"; value: T }\n        | { type: \"done\" }\n        | { type: \"error\"; error: Error }\n    ) => void\n  > = [];\n  private settled = false;\n\n  push(value: T): void {\n    if (this.settled) {\n      return;\n    }\n\n    this.enqueue({ type: \"value\", value });\n  }\n\n  close(): void {\n    if (this.settled) {\n      return;\n    }\n\n    this.settled = true;\n    this.enqueue({ type: \"done\" });\n  }\n\n  fail(error: unknown): void {\n    if (this.settled) {\n      return;\n    }\n\n    this.settled = true;\n    this.enqueue({ type: \"error\", error: toError(error) });\n  }\n\n  async next(): Promise<IteratorResult<T>> {\n    const item =\n      this.items.shift() ??\n      (await new Promise<(typeof this.items)[number]>((resolve) => {\n        this.waiters.push(resolve);\n      }));\n\n    if (item.type === \"value\") {\n      return { value: item.value, done: false };\n    }\n\n    if (item.type === \"done\") {\n      return { value: undefined, done: true };\n    }\n\n    throw item.error;\n  }\n\n  private enqueue(item: (typeof this.items)[number]): void {\n    const waiter = this.waiters.shift();\n\n    if (waiter) {\n      waiter(item);\n      return;\n    }\n\n    this.items.push(item);\n  }\n}\n\n/**\n * Normalizes a Starcite base URL to the `/v1` API root used by this SDK.\n */\nexport function normalizeBaseUrl(baseUrl: string): string {\n  const trimmed = baseUrl.trim().replace(TRAILING_SLASHES_REGEX, \"\");\n  return trimmed.endsWith(\"/v1\") ? trimmed : `${trimmed}/v1`;\n}\n\nfunction toWebSocketBaseUrl(apiBaseUrl: string): string {\n  if (apiBaseUrl.startsWith(\"https://\")) {\n    return `wss://${apiBaseUrl.slice(\"https://\".length)}`;\n  }\n\n  if (apiBaseUrl.startsWith(\"http://\")) {\n    return `ws://${apiBaseUrl.slice(\"http://\".length)}`;\n  }\n\n  throw new StarciteError(\n    `Invalid Starcite base URL '${apiBaseUrl}'. Use http:// or https://.`\n  );\n}\n\nfunction defaultWebSocketFactory(\n  url: string,\n  options: StarciteWebSocketConnectOptions = {}\n): StarciteWebSocket {\n  if (typeof WebSocket === \"undefined\") {\n    throw new StarciteError(\n      \"WebSocket is not available in this runtime. Provide websocketFactory in StarciteClientOptions.\"\n    );\n  }\n\n  const headers = new Headers(options.headers);\n\n  if (!hasAnyHeaders(headers)) {\n    return new WebSocket(url) as unknown as StarciteWebSocket;\n  }\n\n  const headerObject = Object.fromEntries(headers.entries());\n\n  try {\n    return new (\n      WebSocket as unknown as {\n        new (\n          websocketUrl: string,\n          options: { headers: Record<string, string> }\n        ): StarciteWebSocket;\n      }\n    )(url, { headers: headerObject });\n  } catch {\n    throw new StarciteError(\n      \"This runtime cannot set WebSocket upgrade headers with the default factory. Provide websocketFactory in StarciteClientOptions.\"\n    );\n  }\n}\n\nfunction defaultFetch(\n  input: RequestInfo | URL,\n  init?: RequestInit\n): Promise<Response> {\n  if (typeof fetch === \"undefined\") {\n    throw new StarciteError(\n      \"fetch is not available in this runtime. Provide fetch in StarciteClientOptions.\"\n    );\n  }\n\n  return fetch(input, init);\n}\n\nfunction toError(error: unknown): Error {\n  if (error instanceof Error) {\n    return error;\n  }\n\n  return new Error(typeof error === \"string\" ? error : \"Unknown error\");\n}\n\nfunction hasAnyHeaders(headers: Headers): boolean {\n  for (const _ of headers.keys()) {\n    return true;\n  }\n\n  return false;\n}\n\nfunction formatAuthorizationHeader(apiKey: string): string {\n  const normalized = apiKey.trim();\n\n  if (normalized.length === 0) {\n    throw new StarciteError(\"apiKey cannot be empty\");\n  }\n\n  if (BEARER_PREFIX_REGEX.test(normalized)) {\n    return normalized;\n  }\n\n  return `Bearer ${normalized}`;\n}\n\nfunction parseEventFrame(data: unknown): TailEvent {\n  const result = TailFrameSchema.safeParse(data);\n\n  if (!result.success) {\n    const reason =\n      result.error.issues[0]?.message ?? \"Tail frame did not match schema\";\n    throw new StarciteConnectionError(reason);\n  }\n\n  return result.data;\n}\n\nfunction getEventData(event: unknown): unknown {\n  if (event && typeof event === \"object\" && \"data\" in event) {\n    return (event as { data?: unknown }).data;\n  }\n\n  return undefined;\n}\n\nfunction agentFromActor(actor: string): string | undefined {\n  if (actor.startsWith(\"agent:\")) {\n    return actor.slice(\"agent:\".length);\n  }\n\n  return undefined;\n}\n\nfunction toSessionEvent(event: TailEvent): SessionEvent {\n  const agent = agentFromActor(event.actor);\n  const text =\n    typeof event.payload.text === \"string\" ? event.payload.text : undefined;\n\n  return {\n    ...event,\n    agent,\n    text,\n  };\n}\n\n/**\n * Session-scoped helper for append and tail operations.\n */\nexport class StarciteSession {\n  /** Session identifier. */\n  readonly id: string;\n  /** Optional session record captured at creation time. */\n  readonly record?: SessionRecord;\n\n  private readonly client: StarciteClient;\n\n  constructor(client: StarciteClient, id: string, record?: SessionRecord) {\n    this.client = client;\n    this.id = id;\n    this.record = record;\n  }\n\n  /**\n   * Appends a high-level agent event to this session.\n   *\n   * Automatically prefixes `agent` as `agent:<name>` when needed.\n   */\n  append(input: SessionAppendInput): Promise<AppendEventResponse> {\n    const parsed = SessionAppendInputSchema.parse(input);\n    const actor = parsed.agent.startsWith(\"agent:\")\n      ? parsed.agent\n      : `agent:${parsed.agent}`;\n\n    return this.client.appendEvent(this.id, {\n      type: parsed.type ?? \"content\",\n      payload: parsed.payload ?? { text: parsed.text },\n      actor,\n      producer_id: parsed.producerId,\n      producer_seq: parsed.producerSeq,\n      source: parsed.source ?? \"agent\",\n      metadata: parsed.metadata,\n      refs: parsed.refs,\n      idempotency_key: parsed.idempotencyKey,\n      expected_seq: parsed.expectedSeq,\n    });\n  }\n\n  /**\n   * Appends a raw event payload as-is.\n   */\n  appendRaw(input: AppendEventRequest): Promise<AppendEventResponse> {\n    return this.client.appendEvent(this.id, input);\n  }\n\n  /**\n   * Streams transformed session events with SDK convenience fields (`agent`, `text`).\n   */\n  tail(options: SessionTailOptions = {}): AsyncIterable<SessionEvent> {\n    return this.client.tailEvents(this.id, options);\n  }\n\n  /**\n   * Streams raw tail events returned by the API.\n   */\n  tailRaw(options: SessionTailOptions = {}): AsyncIterable<TailEvent> {\n    return this.client.tailRawEvents(this.id, options);\n  }\n}\n\n/**\n * Starcite API client for HTTP and WebSocket session operations.\n */\nexport class StarciteClient {\n  /** Normalized API base URL ending with `/v1`. */\n  readonly baseUrl: string;\n\n  private readonly websocketBaseUrl: string;\n  private readonly fetchFn: typeof fetch;\n  private readonly headers: Headers;\n  private readonly websocketFactory: (\n    url: string,\n    options?: StarciteWebSocketConnectOptions\n  ) => StarciteWebSocket;\n\n  /**\n   * Creates a new client instance.\n   */\n  constructor(options: StarciteClientOptions = {}) {\n    this.baseUrl = normalizeBaseUrl(options.baseUrl ?? DEFAULT_BASE_URL);\n    this.websocketBaseUrl = toWebSocketBaseUrl(this.baseUrl);\n    this.fetchFn = options.fetch ?? defaultFetch;\n    this.headers = new Headers(options.headers);\n\n    if (options.apiKey !== undefined) {\n      this.headers.set(\n        \"authorization\",\n        formatAuthorizationHeader(options.apiKey)\n      );\n    }\n\n    this.websocketFactory = options.websocketFactory ?? defaultWebSocketFactory;\n  }\n\n  /**\n   * Returns a session helper bound to an existing session id.\n   */\n  session(sessionId: string, record?: SessionRecord): StarciteSession {\n    return new StarciteSession(this, sessionId, record);\n  }\n\n  /**\n   * Creates a new session and returns a bound `StarciteSession` helper.\n   */\n  async create(input: CreateSessionInput = {}): Promise<StarciteSession> {\n    const record = await this.createSession(input);\n    return this.session(record.id, record);\n  }\n\n  /**\n   * Creates a new session and returns the raw session record.\n   */\n  createSession(input: CreateSessionInput = {}): Promise<SessionRecord> {\n    const payload = CreateSessionInputSchema.parse(input);\n\n    return this.request(\n      \"/sessions\",\n      {\n        method: \"POST\",\n        body: JSON.stringify(payload),\n      },\n      SessionRecordSchema\n    );\n  }\n\n  /**\n   * Lists sessions from the archive-backed catalog.\n   */\n  listSessions(options: SessionListOptions = {}): Promise<SessionListPage> {\n    const query = new URLSearchParams();\n\n    if (options.limit !== undefined) {\n      if (!Number.isInteger(options.limit) || options.limit <= 0) {\n        throw new StarciteError(\n          \"listSessions() limit must be a positive integer\"\n        );\n      }\n\n      query.set(\"limit\", `${options.limit}`);\n    }\n\n    if (options.cursor !== undefined) {\n      if (options.cursor.trim().length === 0) {\n        throw new StarciteError(\"listSessions() cursor cannot be empty\");\n      }\n\n      query.set(\"cursor\", options.cursor);\n    }\n\n    if (options.metadata !== undefined) {\n      for (const [key, value] of Object.entries(options.metadata)) {\n        if (key.trim().length === 0 || value.trim().length === 0) {\n          throw new StarciteError(\n            \"listSessions() metadata filters must be non-empty strings\"\n          );\n        }\n\n        query.set(`metadata.${key}`, value);\n      }\n    }\n\n    const suffix = query.size > 0 ? `?${query.toString()}` : \"\";\n\n    return this.request(\n      `/sessions${suffix}`,\n      {\n        method: \"GET\",\n      },\n      SessionListPageSchema\n    );\n  }\n\n  /**\n   * Appends a raw event payload to a specific session.\n   */\n  appendEvent(\n    sessionId: string,\n    input: AppendEventRequest\n  ): Promise<AppendEventResponse> {\n    const payload = AppendEventRequestSchema.parse(input);\n\n    return this.request(\n      `/sessions/${encodeURIComponent(sessionId)}/append`,\n      {\n        method: \"POST\",\n        body: JSON.stringify(payload),\n      },\n      AppendEventResponseSchema\n    );\n  }\n\n  /**\n   * Opens a WebSocket tail stream and yields raw events.\n   */\n  async *tailRawEvents(\n    sessionId: string,\n    options: SessionTailOptions = {}\n  ): AsyncGenerator<TailEvent> {\n    const queue = new AsyncQueue<TailEvent>();\n    const cursor = options.cursor ?? 0;\n\n    if (!Number.isInteger(cursor) || cursor < 0) {\n      throw new StarciteError(\"tail() cursor must be a non-negative integer\");\n    }\n\n    const wsUrl = `${this.websocketBaseUrl}/sessions/${encodeURIComponent(\n      sessionId\n    )}/tail?cursor=${cursor}`;\n\n    const websocketHeaders = new Headers();\n    const authorization = this.headers.get(\"authorization\");\n\n    if (authorization) {\n      websocketHeaders.set(\"authorization\", authorization);\n    }\n\n    const socket = this.websocketFactory(\n      wsUrl,\n      hasAnyHeaders(websocketHeaders)\n        ? {\n            headers: websocketHeaders,\n          }\n        : undefined\n    );\n\n    const onMessage = (event: unknown): void => {\n      try {\n        const parsed = parseEventFrame(getEventData(event));\n\n        if (options.agent && agentFromActor(parsed.actor) !== options.agent) {\n          return;\n        }\n\n        queue.push(parsed);\n      } catch (error) {\n        queue.fail(error);\n      }\n    };\n\n    const onError = (): void => {\n      queue.fail(\n        new StarciteConnectionError(\n          `Tail connection failed for session '${sessionId}'`\n        )\n      );\n    };\n\n    const onClose = (): void => {\n      queue.close();\n    };\n\n    socket.addEventListener(\"message\", onMessage);\n    socket.addEventListener(\"error\", onError);\n    socket.addEventListener(\"close\", onClose);\n\n    const onAbort = (): void => {\n      queue.close();\n      socket.close(1000, \"aborted\");\n    };\n\n    if (options.signal) {\n      if (options.signal.aborted) {\n        onAbort();\n      } else {\n        options.signal.addEventListener(\"abort\", onAbort, { once: true });\n      }\n    }\n\n    try {\n      while (true) {\n        const next = await queue.next();\n\n        if (next.done) {\n          break;\n        }\n\n        yield next.value;\n      }\n    } finally {\n      socket.removeEventListener(\"message\", onMessage);\n      socket.removeEventListener(\"error\", onError);\n      socket.removeEventListener(\"close\", onClose);\n\n      if (options.signal) {\n        options.signal.removeEventListener(\"abort\", onAbort);\n      }\n\n      socket.close(1000, \"finished\");\n    }\n  }\n\n  /**\n   * Opens a WebSocket tail stream and yields transformed session events.\n   */\n  async *tailEvents(\n    sessionId: string,\n    options: SessionTailOptions = {}\n  ): AsyncGenerator<SessionEvent> {\n    for await (const rawEvent of this.tailRawEvents(sessionId, options)) {\n      yield toSessionEvent(rawEvent);\n    }\n  }\n\n  private async request<T>(\n    path: string,\n    init: RequestInit,\n    schema?: z.ZodType<T>\n  ): Promise<T> {\n    const headers = new Headers(this.headers);\n\n    if (!headers.has(\"content-type\")) {\n      headers.set(\"content-type\", \"application/json\");\n    }\n\n    if (init.headers) {\n      const perRequestHeaders = new Headers(init.headers);\n      for (const [key, value] of perRequestHeaders.entries()) {\n        headers.set(key, value);\n      }\n    }\n\n    let response: Response;\n\n    try {\n      response = await this.fetchFn(`${this.baseUrl}${path}`, {\n        ...init,\n        headers,\n      });\n    } catch (error) {\n      const rootCause = toError(error).message;\n      throw new StarciteConnectionError(\n        `Failed to connect to Starcite at ${this.baseUrl}: ${rootCause}`\n      );\n    }\n\n    if (!response.ok) {\n      const payload = await tryParseJson(response);\n      const code =\n        typeof payload?.error === \"string\"\n          ? payload.error\n          : `http_${response.status}`;\n      const message =\n        typeof payload?.message === \"string\"\n          ? payload.message\n          : response.statusText;\n\n      throw new StarciteApiError(message, response.status, code, payload);\n    }\n\n    if (response.status === 204) {\n      return undefined as T;\n    }\n\n    const responseBody = (await response.json()) as unknown;\n\n    if (!schema) {\n      return responseBody as T;\n    }\n\n    const parsed = schema.safeParse(responseBody);\n    if (!parsed.success) {\n      const issue = parsed.error.issues[0]?.message ?? \"invalid response\";\n      throw new StarciteConnectionError(\n        `Received unexpected response payload from Starcite: ${issue}`\n      );\n    }\n\n    return parsed.data;\n  }\n}\n\nasync function tryParseJson(\n  response: Response\n): Promise<StarciteErrorPayload | null> {\n  try {\n    const parsed = (await response.json()) as unknown;\n    const result = StarciteErrorPayloadSchema.safeParse(parsed);\n    return result.success ? result.data : null;\n  } catch {\n    return null;\n  }\n}\n","import type { StarciteErrorPayload } from \"./types\";\n\n/**\n * Base error type for SDK-level failures.\n */\nexport class StarciteError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"StarciteError\";\n  }\n}\n\n/**\n * Thrown when the Starcite API responds with a non-2xx status code.\n */\nexport class StarciteApiError extends StarciteError {\n  /** HTTP status code returned by the API. */\n  readonly status: number;\n  /** Stable API error code (or synthesized `http_<status>` fallback). */\n  readonly code: string;\n  /** Parsed API error payload when available. */\n  readonly payload: StarciteErrorPayload | null;\n\n  constructor(\n    message: string,\n    status: number,\n    code: string,\n    payload: StarciteErrorPayload | null\n  ) {\n    super(message);\n    this.name = \"StarciteApiError\";\n    this.status = status;\n    this.code = code;\n    this.payload = payload;\n  }\n}\n\n/**\n * Thrown when the SDK cannot reach Starcite or receives invalid transport payloads.\n */\nexport class StarciteConnectionError extends StarciteError {\n  constructor(message: string) {\n    super(message);\n    this.name = \"StarciteConnectionError\";\n  }\n}\n","import { z } from \"zod\";\n\nconst ArbitraryObjectSchema = z.record(z.unknown());\n\n/**\n * Request payload for creating a session.\n */\nexport const CreateSessionInputSchema = z.object({\n  id: z.string().optional(),\n  title: z.string().optional(),\n  metadata: ArbitraryObjectSchema.optional(),\n});\n\n/**\n * Inferred TypeScript type for {@link CreateSessionInputSchema}.\n */\nexport type CreateSessionInput = z.infer<typeof CreateSessionInputSchema>;\n\n/**\n * Session record returned by the Starcite API.\n */\nexport const SessionRecordSchema = z.object({\n  id: z.string(),\n  title: z.string().nullable().optional(),\n  metadata: ArbitraryObjectSchema,\n  last_seq: z.number().int().nonnegative(),\n  created_at: z.string(),\n  updated_at: z.string(),\n});\n\n/**\n * Inferred TypeScript type for {@link SessionRecordSchema}.\n */\nexport type SessionRecord = z.infer<typeof SessionRecordSchema>;\n\n/**\n * Session item returned by the list endpoint.\n */\nexport const SessionListItemSchema = z.object({\n  id: z.string(),\n  title: z.string().nullable().optional(),\n  metadata: ArbitraryObjectSchema,\n  created_at: z.string(),\n});\n\n/**\n * Inferred TypeScript type for {@link SessionListItemSchema}.\n */\nexport type SessionListItem = z.infer<typeof SessionListItemSchema>;\n\n/**\n * Paginated session list response.\n */\nexport const SessionListPageSchema = z.object({\n  sessions: z.array(SessionListItemSchema),\n  next_cursor: z.string().nullable(),\n});\n\n/**\n * Inferred TypeScript type for {@link SessionListPageSchema}.\n */\nexport type SessionListPage = z.infer<typeof SessionListPageSchema>;\n\n/**\n * Low-level request payload for appending an event to a session.\n */\nexport const AppendEventRequestSchema = z.object({\n  type: z.string().min(1),\n  payload: ArbitraryObjectSchema,\n  actor: z.string().min(1),\n  producer_id: z.string().min(1),\n  producer_seq: z.number().int().positive(),\n  source: z.string().optional(),\n  metadata: ArbitraryObjectSchema.optional(),\n  refs: ArbitraryObjectSchema.optional(),\n  idempotency_key: z.string().optional(),\n  expected_seq: z.number().int().nonnegative().optional(),\n});\n\n/**\n * Inferred TypeScript type for {@link AppendEventRequestSchema}.\n */\nexport type AppendEventRequest = z.infer<typeof AppendEventRequestSchema>;\n\n/**\n * API response returned after appending an event.\n */\nexport const AppendEventResponseSchema = z.object({\n  seq: z.number().int().nonnegative(),\n  last_seq: z.number().int().nonnegative(),\n  deduped: z.boolean(),\n});\n\n/**\n * Inferred TypeScript type for {@link AppendEventResponseSchema}.\n */\nexport type AppendEventResponse = z.infer<typeof AppendEventResponseSchema>;\n\n/**\n * Raw event frame shape emitted by the Starcite tail stream.\n */\nexport const TailEventSchema = z.object({\n  seq: z.number().int().nonnegative(),\n  type: z.string().min(1),\n  payload: ArbitraryObjectSchema,\n  actor: z.string().min(1),\n  producer_id: z.string().min(1),\n  producer_seq: z.number().int().positive(),\n  source: z.string().optional(),\n  metadata: ArbitraryObjectSchema.optional(),\n  refs: ArbitraryObjectSchema.optional(),\n  idempotency_key: z.string().nullable().optional(),\n  inserted_at: z.string().optional(),\n});\n\n/**\n * Inferred TypeScript type for {@link TailEventSchema}.\n */\nexport type TailEvent = z.infer<typeof TailEventSchema>;\n\n/**\n * Convenience tail event shape with SDK-derived fields (`agent`, `text`).\n */\nconst SessionEventInternalSchema = TailEventSchema.extend({\n  agent: z.string().optional(),\n  text: z.string().optional(),\n});\n\n/**\n * Inferred TypeScript type for the SDK-level enriched tail event.\n */\nexport type SessionEvent = z.infer<typeof SessionEventInternalSchema>;\n\n/**\n * High-level `session.append()` input.\n *\n * You must provide producer identity (`producerId`, `producerSeq`) and either\n * `text` or `payload`.\n */\nexport const SessionAppendInputSchema = z\n  .object({\n    agent: z.string().trim().min(1),\n    producerId: z.string().trim().min(1),\n    producerSeq: z.number().int().positive(),\n    text: z.string().optional(),\n    payload: ArbitraryObjectSchema.optional(),\n    type: z.string().optional(),\n    source: z.string().optional(),\n    metadata: ArbitraryObjectSchema.optional(),\n    refs: ArbitraryObjectSchema.optional(),\n    idempotencyKey: z.string().optional(),\n    expectedSeq: z.number().int().nonnegative().optional(),\n  })\n  .refine((value) => !!(value.text || value.payload), {\n    message: \"append() requires either 'text' or an object 'payload'\",\n  });\n\n/**\n * Inferred TypeScript type for {@link SessionAppendInputSchema}.\n */\nexport type SessionAppendInput = z.infer<typeof SessionAppendInputSchema>;\n\n/**\n * Options for streaming events from a session.\n */\nexport interface SessionTailOptions {\n  /**\n   * Starting cursor (inclusive) in the event stream.\n   */\n  cursor?: number;\n  /**\n   * Optional filter for `agent:<name>` events.\n   */\n  agent?: string;\n  /**\n   * Optional abort signal to close the stream.\n   */\n  signal?: AbortSignal;\n}\n\n/**\n * Options for listing sessions.\n */\nexport interface SessionListOptions {\n  /**\n   * Maximum rows to return. Must be a positive integer.\n   */\n  limit?: number;\n  /**\n   * Optional cursor from the previous response.\n   */\n  cursor?: string;\n  /**\n   * Optional flat metadata exact-match filters.\n   */\n  metadata?: Record<string, string>;\n}\n\n/**\n * Minimal WebSocket contract required by the SDK.\n */\nexport interface StarciteWebSocket {\n  addEventListener(type: string, listener: (event: unknown) => void): void;\n  removeEventListener(type: string, listener: (event: unknown) => void): void;\n  close(code?: number, reason?: string): void;\n}\n\n/**\n * Factory used to create the WebSocket connection for `tail`.\n */\nexport interface StarciteWebSocketConnectOptions {\n  /**\n   * Headers to include with the WebSocket handshake request.\n   */\n  headers?: HeadersInit;\n}\n\n/**\n * Factory used to create the WebSocket connection for `tail`.\n */\nexport type StarciteWebSocketFactory = (\n  url: string,\n  options?: StarciteWebSocketConnectOptions\n) => StarciteWebSocket;\n\n/**\n * Client construction options.\n */\nexport interface StarciteClientOptions {\n  /**\n   * Base API URL. Defaults to `process.env.STARCITE_BASE_URL` or `http://localhost:4000`.\n   */\n  baseUrl?: string;\n  /**\n   * Custom fetch implementation for non-standard runtimes.\n   */\n  fetch?: typeof fetch;\n  /**\n   * Headers applied to every HTTP request.\n   */\n  headers?: HeadersInit;\n  /**\n   * Service key / JWT token. When set, the SDK automatically sends\n   * `Authorization: Bearer <token>` for HTTP requests and WebSocket upgrades.\n   */\n  apiKey?: string;\n  /**\n   * Custom WebSocket factory for non-browser runtimes.\n   */\n  websocketFactory?: StarciteWebSocketFactory;\n}\n\n/**\n * Error payload shape returned by non-2xx API responses.\n */\nexport const StarciteErrorPayloadSchema = z\n  .object({\n    error: z.string().optional(),\n    message: z.string().optional(),\n  })\n  .catchall(z.unknown());\n\n/**\n * Inferred TypeScript type for {@link StarciteErrorPayloadSchema}.\n */\nexport type StarciteErrorPayload = z.infer<typeof StarciteErrorPayloadSchema>;\n"],"mappings":"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","names":["import_zod"]}

package/dist/index.d.cts

@@ -0,0 +1,555 @@
+import { z } from 'zod';
+
+/**
+ * Request payload for creating a session.
+ */
+declare const CreateSessionInputSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    id?: string | undefined;
+    title?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}, {
+    id?: string | undefined;
+    title?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}>;
+/**
+ * Inferred TypeScript type for {@link CreateSessionInputSchema}.
+ */
+type CreateSessionInput = z.infer<typeof CreateSessionInputSchema>;
+/**
+ * Session record returned by the Starcite API.
+ */
+declare const SessionRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    last_seq: z.ZodNumber;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    metadata: Record<string, unknown>;
+    last_seq: number;
+    created_at: string;
+    updated_at: string;
+    title?: string | null | undefined;
+}, {
+    id: string;
+    metadata: Record<string, unknown>;
+    last_seq: number;
+    created_at: string;
+    updated_at: string;
+    title?: string | null | undefined;
+}>;
+/**
+ * Inferred TypeScript type for {@link SessionRecordSchema}.
+ */
+type SessionRecord = z.infer<typeof SessionRecordSchema>;
+/**
+ * Session item returned by the list endpoint.
+ */
+declare const SessionListItemSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    created_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    metadata: Record<string, unknown>;
+    created_at: string;
+    title?: string | null | undefined;
+}, {
+    id: string;
+    metadata: Record<string, unknown>;
+    created_at: string;
+    title?: string | null | undefined;
+}>;
+/**
+ * Inferred TypeScript type for {@link SessionListItemSchema}.
+ */
+type SessionListItem = z.infer<typeof SessionListItemSchema>;
+/**
+ * Paginated session list response.
+ */
+declare const SessionListPageSchema: z.ZodObject<{
+    sessions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        created_at: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        metadata: Record<string, unknown>;
+        created_at: string;
+        title?: string | null | undefined;
+    }, {
+        id: string;
+        metadata: Record<string, unknown>;
+        created_at: string;
+        title?: string | null | undefined;
+    }>, "many">;
+    next_cursor: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    sessions: {
+        id: string;
+        metadata: Record<string, unknown>;
+        created_at: string;
+        title?: string | null | undefined;
+    }[];
+    next_cursor: string | null;
+}, {
+    sessions: {
+        id: string;
+        metadata: Record<string, unknown>;
+        created_at: string;
+        title?: string | null | undefined;
+    }[];
+    next_cursor: string | null;
+}>;
+/**
+ * Inferred TypeScript type for {@link SessionListPageSchema}.
+ */
+type SessionListPage = z.infer<typeof SessionListPageSchema>;
+/**
+ * Low-level request payload for appending an event to a session.
+ */
+declare const AppendEventRequestSchema: z.ZodObject<{
+    type: z.ZodString;
+    payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    actor: z.ZodString;
+    producer_id: z.ZodString;
+    producer_seq: z.ZodNumber;
+    source: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    refs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    idempotency_key: z.ZodOptional<z.ZodString>;
+    expected_seq: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: string;
+    payload: Record<string, unknown>;
+    actor: string;
+    producer_id: string;
+    producer_seq: number;
+    metadata?: Record<string, unknown> | undefined;
+    source?: string | undefined;
+    refs?: Record<string, unknown> | undefined;
+    idempotency_key?: string | undefined;
+    expected_seq?: number | undefined;
+}, {
+    type: string;
+    payload: Record<string, unknown>;
+    actor: string;
+    producer_id: string;
+    producer_seq: number;
+    metadata?: Record<string, unknown> | undefined;
+    source?: string | undefined;
+    refs?: Record<string, unknown> | undefined;
+    idempotency_key?: string | undefined;
+    expected_seq?: number | undefined;
+}>;
+/**
+ * Inferred TypeScript type for {@link AppendEventRequestSchema}.
+ */
+type AppendEventRequest = z.infer<typeof AppendEventRequestSchema>;
+/**
+ * API response returned after appending an event.
+ */
+declare const AppendEventResponseSchema: z.ZodObject<{
+    seq: z.ZodNumber;
+    last_seq: z.ZodNumber;
+    deduped: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    last_seq: number;
+    seq: number;
+    deduped: boolean;
+}, {
+    last_seq: number;
+    seq: number;
+    deduped: boolean;
+}>;
+/**
+ * Inferred TypeScript type for {@link AppendEventResponseSchema}.
+ */
+type AppendEventResponse = z.infer<typeof AppendEventResponseSchema>;
+/**
+ * Raw event frame shape emitted by the Starcite tail stream.
+ */
+declare const TailEventSchema: z.ZodObject<{
+    seq: z.ZodNumber;
+    type: z.ZodString;
+    payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    actor: z.ZodString;
+    producer_id: z.ZodString;
+    producer_seq: z.ZodNumber;
+    source: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    refs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    idempotency_key: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    inserted_at: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: string;
+    payload: Record<string, unknown>;
+    actor: string;
+    producer_id: string;
+    producer_seq: number;
+    seq: number;
+    metadata?: Record<string, unknown> | undefined;
+    source?: string | undefined;
+    refs?: Record<string, unknown> | undefined;
+    idempotency_key?: string | null | undefined;
+    inserted_at?: string | undefined;
+}, {
+    type: string;
+    payload: Record<string, unknown>;
+    actor: string;
+    producer_id: string;
+    producer_seq: number;
+    seq: number;
+    metadata?: Record<string, unknown> | undefined;
+    source?: string | undefined;
+    refs?: Record<string, unknown> | undefined;
+    idempotency_key?: string | null | undefined;
+    inserted_at?: string | undefined;
+}>;
+/**
+ * Inferred TypeScript type for {@link TailEventSchema}.
+ */
+type TailEvent = z.infer<typeof TailEventSchema>;
+/**
+ * Convenience tail event shape with SDK-derived fields (`agent`, `text`).
+ */
+declare const SessionEventInternalSchema: z.ZodObject<{
+    seq: z.ZodNumber;
+    type: z.ZodString;
+    payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    actor: z.ZodString;
+    producer_id: z.ZodString;
+    producer_seq: z.ZodNumber;
+    source: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    refs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    idempotency_key: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    inserted_at: z.ZodOptional<z.ZodString>;
+} & {
+    agent: z.ZodOptional<z.ZodString>;
+    text: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: string;
+    payload: Record<string, unknown>;
+    actor: string;
+    producer_id: string;
+    producer_seq: number;
+    seq: number;
+    metadata?: Record<string, unknown> | undefined;
+    source?: string | undefined;
+    refs?: Record<string, unknown> | undefined;
+    idempotency_key?: string | null | undefined;
+    inserted_at?: string | undefined;
+    agent?: string | undefined;
+    text?: string | undefined;
+}, {
+    type: string;
+    payload: Record<string, unknown>;
+    actor: string;
+    producer_id: string;
+    producer_seq: number;
+    seq: number;
+    metadata?: Record<string, unknown> | undefined;
+    source?: string | undefined;
+    refs?: Record<string, unknown> | undefined;
+    idempotency_key?: string | null | undefined;
+    inserted_at?: string | undefined;
+    agent?: string | undefined;
+    text?: string | undefined;
+}>;
+/**
+ * Inferred TypeScript type for the SDK-level enriched tail event.
+ */
+type SessionEvent = z.infer<typeof SessionEventInternalSchema>;
+/**
+ * High-level `session.append()` input.
+ *
+ * You must provide producer identity (`producerId`, `producerSeq`) and either
+ * `text` or `payload`.
+ */
+declare const SessionAppendInputSchema: z.ZodEffects<z.ZodObject<{
+    agent: z.ZodString;
+    producerId: z.ZodString;
+    producerSeq: z.ZodNumber;
+    text: z.ZodOptional<z.ZodString>;
+    payload: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    type: z.ZodOptional<z.ZodString>;
+    source: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    refs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
+    expectedSeq: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    agent: string;
+    producerId: string;
+    producerSeq: number;
+    type?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+    payload?: Record<string, unknown> | undefined;
+    source?: string | undefined;
+    refs?: Record<string, unknown> | undefined;
+    text?: string | undefined;
+    idempotencyKey?: string | undefined;
+    expectedSeq?: number | undefined;
+}, {
+    agent: string;
+    producerId: string;
+    producerSeq: number;
+    type?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+    payload?: Record<string, unknown> | undefined;
+    source?: string | undefined;
+    refs?: Record<string, unknown> | undefined;
+    text?: string | undefined;
+    idempotencyKey?: string | undefined;
+    expectedSeq?: number | undefined;
+}>, {
+    agent: string;
+    producerId: string;
+    producerSeq: number;
+    type?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+    payload?: Record<string, unknown> | undefined;
+    source?: string | undefined;
+    refs?: Record<string, unknown> | undefined;
+    text?: string | undefined;
+    idempotencyKey?: string | undefined;
+    expectedSeq?: number | undefined;
+}, {
+    agent: string;
+    producerId: string;
+    producerSeq: number;
+    type?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+    payload?: Record<string, unknown> | undefined;
+    source?: string | undefined;
+    refs?: Record<string, unknown> | undefined;
+    text?: string | undefined;
+    idempotencyKey?: string | undefined;
+    expectedSeq?: number | undefined;
+}>;
+/**
+ * Inferred TypeScript type for {@link SessionAppendInputSchema}.
+ */
+type SessionAppendInput = z.infer<typeof SessionAppendInputSchema>;
+/**
+ * Options for streaming events from a session.
+ */
+interface SessionTailOptions {
+    /**
+     * Starting cursor (inclusive) in the event stream.
+     */
+    cursor?: number;
+    /**
+     * Optional filter for `agent:<name>` events.
+     */
+    agent?: string;
+    /**
+     * Optional abort signal to close the stream.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Options for listing sessions.
+ */
+interface SessionListOptions {
+    /**
+     * Maximum rows to return. Must be a positive integer.
+     */
+    limit?: number;
+    /**
+     * Optional cursor from the previous response.
+     */
+    cursor?: string;
+    /**
+     * Optional flat metadata exact-match filters.
+     */
+    metadata?: Record<string, string>;
+}
+/**
+ * Minimal WebSocket contract required by the SDK.
+ */
+interface StarciteWebSocket {
+    addEventListener(type: string, listener: (event: unknown) => void): void;
+    removeEventListener(type: string, listener: (event: unknown) => void): void;
+    close(code?: number, reason?: string): void;
+}
+/**
+ * Factory used to create the WebSocket connection for `tail`.
+ */
+interface StarciteWebSocketConnectOptions {
+    /**
+     * Headers to include with the WebSocket handshake request.
+     */
+    headers?: HeadersInit;
+}
+/**
+ * Factory used to create the WebSocket connection for `tail`.
+ */
+type StarciteWebSocketFactory = (url: string, options?: StarciteWebSocketConnectOptions) => StarciteWebSocket;
+/**
+ * Client construction options.
+ */
+interface StarciteClientOptions {
+    /**
+     * Base API URL. Defaults to `process.env.STARCITE_BASE_URL` or `http://localhost:4000`.
+     */
+    baseUrl?: string;
+    /**
+     * Custom fetch implementation for non-standard runtimes.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Headers applied to every HTTP request.
+     */
+    headers?: HeadersInit;
+    /**
+     * Service key / JWT token. When set, the SDK automatically sends
+     * `Authorization: Bearer <token>` for HTTP requests and WebSocket upgrades.
+     */
+    apiKey?: string;
+    /**
+     * Custom WebSocket factory for non-browser runtimes.
+     */
+    websocketFactory?: StarciteWebSocketFactory;
+}
+/**
+ * Error payload shape returned by non-2xx API responses.
+ */
+declare const StarciteErrorPayloadSchema: z.ZodObject<{
+    error: z.ZodOptional<z.ZodString>;
+    message: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodUnknown, z.objectOutputType<{
+    error: z.ZodOptional<z.ZodString>;
+    message: z.ZodOptional<z.ZodString>;
+}, z.ZodUnknown, "strip">, z.objectInputType<{
+    error: z.ZodOptional<z.ZodString>;
+    message: z.ZodOptional<z.ZodString>;
+}, z.ZodUnknown, "strip">>;
+/**
+ * Inferred TypeScript type for {@link StarciteErrorPayloadSchema}.
+ */
+type StarciteErrorPayload = z.infer<typeof StarciteErrorPayloadSchema>;
+
+/**
+ * Normalizes a Starcite base URL to the `/v1` API root used by this SDK.
+ */
+declare function normalizeBaseUrl(baseUrl: string): string;
+/**
+ * Session-scoped helper for append and tail operations.
+ */
+declare class StarciteSession {
+    /** Session identifier. */
+    readonly id: string;
+    /** Optional session record captured at creation time. */
+    readonly record?: SessionRecord;
+    private readonly client;
+    constructor(client: StarciteClient, id: string, record?: SessionRecord);
+    /**
+     * Appends a high-level agent event to this session.
+     *
+     * Automatically prefixes `agent` as `agent:<name>` when needed.
+     */
+    append(input: SessionAppendInput): Promise<AppendEventResponse>;
+    /**
+     * Appends a raw event payload as-is.
+     */
+    appendRaw(input: AppendEventRequest): Promise<AppendEventResponse>;
+    /**
+     * Streams transformed session events with SDK convenience fields (`agent`, `text`).
+     */
+    tail(options?: SessionTailOptions): AsyncIterable<SessionEvent>;
+    /**
+     * Streams raw tail events returned by the API.
+     */
+    tailRaw(options?: SessionTailOptions): AsyncIterable<TailEvent>;
+}
+/**
+ * Starcite API client for HTTP and WebSocket session operations.
+ */
+declare class StarciteClient {
+    /** Normalized API base URL ending with `/v1`. */
+    readonly baseUrl: string;
+    private readonly websocketBaseUrl;
+    private readonly fetchFn;
+    private readonly headers;
+    private readonly websocketFactory;
+    /**
+     * Creates a new client instance.
+     */
+    constructor(options?: StarciteClientOptions);
+    /**
+     * Returns a session helper bound to an existing session id.
+     */
+    session(sessionId: string, record?: SessionRecord): StarciteSession;
+    /**
+     * Creates a new session and returns a bound `StarciteSession` helper.
+     */
+    create(input?: CreateSessionInput): Promise<StarciteSession>;
+    /**
+     * Creates a new session and returns the raw session record.
+     */
+    createSession(input?: CreateSessionInput): Promise<SessionRecord>;
+    /**
+     * Lists sessions from the archive-backed catalog.
+     */
+    listSessions(options?: SessionListOptions): Promise<SessionListPage>;
+    /**
+     * Appends a raw event payload to a specific session.
+     */
+    appendEvent(sessionId: string, input: AppendEventRequest): Promise<AppendEventResponse>;
+    /**
+     * Opens a WebSocket tail stream and yields raw events.
+     */
+    tailRawEvents(sessionId: string, options?: SessionTailOptions): AsyncGenerator<TailEvent>;
+    /**
+     * Opens a WebSocket tail stream and yields transformed session events.
+     */
+    tailEvents(sessionId: string, options?: SessionTailOptions): AsyncGenerator<SessionEvent>;
+    private request;
+}
+
+/**
+ * Base error type for SDK-level failures.
+ */
+declare class StarciteError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when the Starcite API responds with a non-2xx status code.
+ */
+declare class StarciteApiError extends StarciteError {
+    /** HTTP status code returned by the API. */
+    readonly status: number;
+    /** Stable API error code (or synthesized `http_<status>` fallback). */
+    readonly code: string;
+    /** Parsed API error payload when available. */
+    readonly payload: StarciteErrorPayload | null;
+    constructor(message: string, status: number, code: string, payload: StarciteErrorPayload | null);
+}
+/**
+ * Thrown when the SDK cannot reach Starcite or receives invalid transport payloads.
+ */
+declare class StarciteConnectionError extends StarciteError {
+    constructor(message: string);
+}
+
+/**
+ * Creates a new {@link StarciteClient} instance.
+ */
+declare function createStarciteClient(options?: StarciteClientOptions): StarciteClient;
+/**
+ * Default singleton client using environment/default configuration.
+ */
+declare const starcite: StarciteClient;
+
+export { type AppendEventRequest, type AppendEventResponse, type CreateSessionInput, type SessionAppendInput, type SessionEvent, type SessionListItem, type SessionListOptions, type SessionListPage, type SessionRecord, type SessionTailOptions, StarciteApiError, StarciteClient, type StarciteClientOptions, StarciteConnectionError, StarciteError, type StarciteErrorPayload, StarciteSession, type StarciteWebSocket, type StarciteWebSocketConnectOptions, type StarciteWebSocketFactory, type TailEvent, createStarciteClient, normalizeBaseUrl, starcite };