@ziggy-ai/client-sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,738 @@
+// src/types.ts
+var ZiggyError = class extends Error {
+  constructor(message, status, code, details) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.details = details;
+    this.name = "ZiggyError";
+  }
+};
+var ZiggyConnectionError = class extends ZiggyError {
+  constructor(message, retryable = true) {
+    super(message, 0, "CONNECTION_ERROR");
+    this.retryable = retryable;
+    this.name = "ZiggyConnectionError";
+  }
+};
+
+// src/auth.ts
+function buildHeaders(config, extra) {
+  return {
+    "Content-Type": "application/json",
+    "X-API-Key": config.apiKey,
+    ...extra
+  };
+}
+
+// src/connection.ts
+var Connection = class {
+  config;
+  constructor(config) {
+    this.config = config;
+  }
+  /**
+   * Make an authenticated JSON request.
+   */
+  async request(method, path, body, extraHeaders) {
+    const url = `${this.config.baseUrl}/v1${path}`;
+    const headers = buildHeaders(this.config, extraHeaders);
+    const timeout = this.config.timeout ?? 3e4;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeout);
+    try {
+      const response = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        let errorBody;
+        try {
+          errorBody = await response.json();
+        } catch {
+          errorBody = await response.text();
+        }
+        const message = typeof errorBody === "object" && errorBody !== null && "error" in errorBody ? errorBody.error : `HTTP ${response.status}`;
+        throw new ZiggyError(message, response.status, void 0, errorBody);
+      }
+      return await response.json();
+    } catch (error) {
+      if (error instanceof ZiggyError) throw error;
+      if (error instanceof DOMException && error.name === "AbortError") {
+        throw new ZiggyConnectionError("Request timed out", true);
+      }
+      throw new ZiggyConnectionError(
+        error instanceof Error ? error.message : "Connection failed",
+        true
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  /**
+   * Make an authenticated request that returns a ReadableStream (for ndjson).
+   */
+  async streamRequest(method, path, body) {
+    const url = `${this.config.baseUrl}/v1${path}`;
+    const headers = buildHeaders(this.config);
+    try {
+      const response = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : void 0
+      });
+      if (!response.ok) {
+        let errorBody;
+        try {
+          errorBody = await response.json();
+        } catch {
+          errorBody = await response.text();
+        }
+        const message = typeof errorBody === "object" && errorBody !== null && "error" in errorBody ? errorBody.error : `HTTP ${response.status}`;
+        throw new ZiggyError(message, response.status, void 0, errorBody);
+      }
+      return response;
+    } catch (error) {
+      if (error instanceof ZiggyError) throw error;
+      throw new ZiggyConnectionError(
+        error instanceof Error ? error.message : "Connection failed",
+        true
+      );
+    }
+  }
+};
+
+// src/session.ts
+var SessionManager = class {
+  connection;
+  appId;
+  _sessionId = null;
+  _conversationId = null;
+  constructor(connection, config) {
+    this.connection = connection;
+    this.appId = config.appId;
+  }
+  get sessionId() {
+    return this._sessionId;
+  }
+  get conversationId() {
+    return this._conversationId;
+  }
+  /**
+   * Create or resume a session.
+   * Replaces 4 separate calls (brand + context + triggers + actions).
+   */
+  async create(request) {
+    const response = await this.connection.request("POST", "/sessions", {
+      appId: this.appId,
+      ...request,
+      capabilities: request.capabilities ?? ["streaming", "actions"]
+    });
+    this._sessionId = response.sessionId;
+    this._conversationId = response.conversationId;
+    return response;
+  }
+  /**
+   * Push context update (delta merge) with piggybacked trigger evaluation.
+   */
+  async pushContext(userId, context, events) {
+    if (!this._sessionId) {
+      throw new Error("No active session \u2014 call create() first");
+    }
+    return this.connection.request(
+      "POST",
+      `/sessions/${this._sessionId}/context`,
+      { userId, context, events }
+    );
+  }
+  /**
+   * End the current session.
+   */
+  async destroy() {
+    if (!this._sessionId) return;
+    await this.connection.request("DELETE", `/sessions/${this._sessionId}`);
+    this._sessionId = null;
+    this._conversationId = null;
+  }
+};
+
+// src/stream-parser.ts
+async function* parseNdjsonStream(response) {
+  const reader = response.body?.getReader();
+  if (!reader) throw new Error("Response has no body");
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() || "";
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        try {
+          const event = JSON.parse(trimmed);
+          yield event;
+        } catch {
+          console.warn("[ZiggySDK] Malformed ndjson line:", trimmed);
+        }
+      }
+    }
+    if (buffer.trim()) {
+      try {
+        const event = JSON.parse(buffer.trim());
+        yield event;
+      } catch {
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+var SequenceTracker = class {
+  _lastSeq = -1;
+  _streamId = null;
+  get lastSeq() {
+    return this._lastSeq;
+  }
+  get streamId() {
+    return this._streamId;
+  }
+  update(event) {
+    if ("seq" in event && typeof event.seq === "number") {
+      this._lastSeq = event.seq;
+    }
+    if (event.type === "stream.start") {
+      this._streamId = event.streamId;
+    }
+  }
+  reset() {
+    this._lastSeq = -1;
+    this._streamId = null;
+  }
+};
+
+// src/chat.ts
+var ChatClient = class {
+  connection;
+  sessionManager;
+  userId = null;
+  constructor(connection, sessionManager) {
+    this.connection = connection;
+    this.sessionManager = sessionManager;
+  }
+  /** Set the current user ID (called after session creation) */
+  setUserId(userId) {
+    this.userId = userId;
+  }
+  /**
+   * Send a non-streaming chat message.
+   */
+  async send(request) {
+    const sessionId = this.sessionManager.sessionId;
+    if (!sessionId) throw new Error("No active session");
+    if (!this.userId) throw new Error("No user ID set");
+    return this.connection.request("POST", "/chat", {
+      sessionId,
+      userId: this.userId,
+      ...request
+    });
+  }
+  /**
+   * Send a streaming chat message.
+   * Returns an async iterable of structured stream events.
+   */
+  async *stream(request) {
+    const sessionId = this.sessionManager.sessionId;
+    if (!sessionId) throw new Error("No active session");
+    if (!this.userId) throw new Error("No user ID set");
+    const response = await this.connection.streamRequest("POST", "/chat/stream", {
+      sessionId,
+      userId: this.userId,
+      ...request
+    });
+    const tracker = new SequenceTracker();
+    for await (const event of parseNdjsonStream(response)) {
+      tracker.update(event);
+      yield event;
+    }
+  }
+  /**
+   * Resume an interrupted stream from a given sequence number.
+   */
+  async *resume(streamId, afterSeq) {
+    const response = await this.connection.streamRequest(
+      "GET",
+      `/chat/stream/${streamId}?after_seq=${afterSeq}`
+    );
+    for await (const event of parseNdjsonStream(response)) {
+      yield event;
+    }
+  }
+};
+
+// src/context.ts
+var FLUSH_INTERVAL_MS = 1e4;
+var IMPORTANT_FIELDS = ["page", "errors", "process"];
+var ContextManager = class {
+  sessionManager;
+  userId = null;
+  pendingContext = {};
+  pendingEvents = [];
+  flushTimer = null;
+  onTrigger;
+  constructor(sessionManager) {
+    this.sessionManager = sessionManager;
+  }
+  /** Set user ID and start batching */
+  start(userId, onTrigger) {
+    this.userId = userId;
+    this.onTrigger = onTrigger;
+    this.flushTimer = setInterval(() => {
+      this.flush().catch(() => {
+      });
+    }, FLUSH_INTERVAL_MS);
+  }
+  /** Stop batching */
+  stop() {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+  }
+  /**
+   * Queue a context update. Merges with pending batch.
+   * Flushes immediately for important changes.
+   */
+  update(context) {
+    Object.assign(this.pendingContext, context);
+    const hasImportant = Object.keys(context).some((k) => IMPORTANT_FIELDS.includes(k));
+    if (hasImportant) {
+      this.flush().catch(() => {
+      });
+    }
+  }
+  /**
+   * Queue an event for the next flush.
+   */
+  addEvent(event) {
+    this.pendingEvents.push(event);
+  }
+  /**
+   * Flush pending context and events to the server.
+   */
+  async flush() {
+    if (!this.userId) return;
+    if (Object.keys(this.pendingContext).length === 0 && this.pendingEvents.length === 0) return;
+    const context = { ...this.pendingContext };
+    const events = [...this.pendingEvents];
+    this.pendingContext = {};
+    this.pendingEvents = [];
+    try {
+      const response = await this.sessionManager.pushContext(this.userId, context, events.length > 0 ? events : void 0);
+      if (response.trigger && this.onTrigger) {
+        this.onTrigger(response);
+      }
+    } catch {
+      this.pendingContext = { ...context, ...this.pendingContext };
+      this.pendingEvents = [...events, ...this.pendingEvents];
+    }
+  }
+};
+
+// src/tools.ts
+var ToolClient = class {
+  connection;
+  sessionManager;
+  userId = null;
+  constructor(connection, sessionManager) {
+    this.connection = connection;
+    this.sessionManager = sessionManager;
+  }
+  setUserId(userId) {
+    this.userId = userId;
+  }
+  /**
+   * Invoke a tool (non-streaming).
+   */
+  async invoke(toolId, input) {
+    const sessionId = this.sessionManager.sessionId;
+    if (!sessionId) throw new Error("No active session");
+    if (!this.userId) throw new Error("No user ID set");
+    return this.connection.request("POST", "/tools/invoke", {
+      sessionId,
+      userId: this.userId,
+      toolId,
+      input: input ?? {}
+    });
+  }
+  /**
+   * Invoke a tool with streaming (for long-running tools).
+   */
+  async *invokeStream(toolId, input) {
+    const sessionId = this.sessionManager.sessionId;
+    if (!sessionId) throw new Error("No active session");
+    if (!this.userId) throw new Error("No user ID set");
+    const response = await this.connection.streamRequest("POST", "/tools/invoke/stream", {
+      sessionId,
+      userId: this.userId,
+      toolId,
+      input: input ?? {}
+    });
+    for await (const event of parseNdjsonStream(response)) {
+      yield event;
+    }
+  }
+};
+
+// src/feedback.ts
+var FeedbackClient = class {
+  connection;
+  constructor(connection) {
+    this.connection = connection;
+  }
+  /**
+   * Quick reaction on a message.
+   */
+  async react(messageId, reaction) {
+    await this.connection.request("POST", "/feedback/reaction", {
+      messageId,
+      reaction
+    });
+  }
+  /**
+   * Submit detailed feedback.
+   */
+  async submit(feedback) {
+    await this.connection.request("POST", "/feedback", feedback);
+  }
+  /**
+   * Record an outcome.
+   */
+  async recordOutcome(outcome) {
+    await this.connection.request("POST", "/feedback/outcome", {
+      ...outcome,
+      agentIds: outcome.agentIds ?? []
+    });
+  }
+};
+
+// src/quests.ts
+var QuestClient = class {
+  connection;
+  constructor(connection) {
+    this.connection = connection;
+  }
+  /**
+   * Create a new quest.
+   */
+  async create(request) {
+    const result = await this.connection.request(
+      "POST",
+      "/quests",
+      request
+    );
+    return result.quest;
+  }
+  /**
+   * Get quest status.
+   */
+  async get(questId) {
+    const result = await this.connection.request("GET", `/quests/${questId}`);
+    return result.quest;
+  }
+  /**
+   * Update quest status, context, or result.
+   */
+  async update(questId, updates) {
+    const result = await this.connection.request(
+      "PATCH",
+      `/quests/${questId}`,
+      updates
+    );
+    return result.quest;
+  }
+  /**
+   * Update a specific quest step.
+   */
+  async updateStep(questId, stepId, updates) {
+    const result = await this.connection.request(
+      "PATCH",
+      `/quests/${questId}/steps/${stepId}`,
+      updates
+    );
+    return result.quest;
+  }
+  /**
+   * Cancel a quest.
+   */
+  async cancel(questId) {
+    return this.update(questId, { status: "cancelled" });
+  }
+  /**
+   * List quests for a session.
+   */
+  async list(sessionId) {
+    const result = await this.connection.request(
+      "GET",
+      `/quests/session/${sessionId}`
+    );
+    return result.quests;
+  }
+  /**
+   * Stream quest updates with optional resumption.
+   */
+  async *stream(questId, afterSeq) {
+    const path = afterSeq !== void 0 ? `/quests/${questId}/stream?afterSeq=${afterSeq}` : `/quests/${questId}/stream`;
+    const response = await this.connection.streamRequest("GET", path);
+    for await (const event of parseNdjsonStream(response)) {
+      yield event;
+    }
+  }
+};
+
+// src/analytics.ts
+var FLUSH_INTERVAL_MS2 = 3e4;
+var AnalyticsClient = class {
+  connection;
+  sessionId = null;
+  pending = [];
+  flushTimer = null;
+  constructor(connection) {
+    this.connection = connection;
+  }
+  /** Start batching for a session */
+  start(sessionId) {
+    this.sessionId = sessionId;
+    this.flushTimer = setInterval(() => {
+      this.flush().catch(() => {
+      });
+    }, FLUSH_INTERVAL_MS2);
+  }
+  /** Stop batching and flush remaining events */
+  async stop() {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+    await this.flush();
+  }
+  /** Track an event */
+  track(type, data) {
+    this.pending.push({
+      type,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      data
+    });
+  }
+  /** Flush pending events */
+  async flush() {
+    if (!this.sessionId || this.pending.length === 0) return;
+    const events = [...this.pending];
+    this.pending = [];
+    try {
+      await this.connection.request("POST", "/feedback/analytics/events", {
+        sessionId: this.sessionId,
+        events
+      });
+    } catch {
+      this.pending = [...events, ...this.pending];
+    }
+  }
+};
+
+// src/app.ts
+var AppClient = class {
+  connection;
+  constructor(connection) {
+    this.connection = connection;
+  }
+  // ─── Triggers ──────────────────────────────────────────────────────────────
+  /**
+   * Register triggers (full sync — replaces all existing triggers).
+   */
+  async registerTriggers(request) {
+    return this.connection.request("POST", "/apps/triggers", request);
+  }
+  /**
+   * List all registered triggers.
+   */
+  async listTriggers() {
+    return this.connection.request("GET", "/apps/triggers");
+  }
+  /**
+   * Delete a specific trigger by ID.
+   */
+  async deleteTrigger(triggerId) {
+    return this.connection.request("DELETE", `/apps/triggers/${triggerId}`);
+  }
+  // ─── Quick Actions ─────────────────────────────────────────────────────────
+  /**
+   * Register quick action sets (full sync — replaces all existing sets).
+   */
+  async registerQuickActions(request) {
+    return this.connection.request("POST", "/apps/quick-actions", request);
+  }
+  /**
+   * List all registered quick action sets.
+   */
+  async listQuickActions() {
+    return this.connection.request("GET", "/apps/quick-actions");
+  }
+  /**
+   * Delete a specific quick action set by ID.
+   */
+  async deleteQuickActionSet(setId) {
+    return this.connection.request("DELETE", `/apps/quick-actions/${setId}`);
+  }
+  // ─── Brand ─────────────────────────────────────────────────────────────────
+  /**
+   * Set or update brand configuration.
+   */
+  async setBrand(brand) {
+    return this.connection.request("PUT", "/apps/brand", brand);
+  }
+  /**
+   * Get brand configuration.
+   */
+  async getBrand() {
+    return this.connection.request("GET", "/apps/brand");
+  }
+  // ─── Credentials ────────────────────────────────────────────────────────────
+  /**
+   * Set or update tool credentials (encrypted at rest).
+   * Merges with existing credentials — pass only the ones to update.
+   */
+  async setCredentials(request) {
+    return this.connection.request("PUT", "/apps/credentials", request);
+  }
+  /**
+   * List which credential keys are stored (values are never returned).
+   */
+  async getCredentials() {
+    return this.connection.request("GET", "/apps/credentials");
+  }
+  /**
+   * Delete all stored credentials.
+   */
+  async deleteCredentials() {
+    return this.connection.request("DELETE", "/apps/credentials");
+  }
+};
+
+// src/callback-handler.ts
+var CallbackHandler = class {
+  handlers = /* @__PURE__ */ new Map();
+  /**
+   * Register a handler for a specific tool ID.
+   */
+  on(toolId, handler) {
+    this.handlers.set(toolId, handler);
+    return this;
+  }
+  /**
+   * Remove a handler for a specific tool ID.
+   */
+  off(toolId) {
+    this.handlers.delete(toolId);
+    return this;
+  }
+  /**
+   * Handle an incoming callback request from Ziggy.
+   * Returns a response object suitable for sending back as JSON.
+   */
+  async handle(request) {
+    const { toolId, params, requestId, sessionId } = request;
+    const handler = this.handlers.get(toolId);
+    if (!handler) {
+      return {
+        requestId,
+        success: false,
+        error: `No handler registered for tool: ${toolId}`
+      };
+    }
+    try {
+      const result = await handler(params, sessionId);
+      return { requestId, success: true, result };
+    } catch (error) {
+      return {
+        requestId,
+        success: false,
+        error: error instanceof Error ? error.message : "Handler failed"
+      };
+    }
+  }
+  /**
+   * List all registered tool IDs.
+   */
+  get registeredTools() {
+    return Array.from(this.handlers.keys());
+  }
+};
+
+// src/index.ts
+var ZiggyClient = class {
+  /** Session lifecycle */
+  sessions;
+  /** Chat (non-streaming and streaming) */
+  chat;
+  /** Context updates (auto-batched) */
+  context;
+  /** Tool invocation */
+  tools;
+  /** Feedback and reactions */
+  feedback;
+  /** Quest tracking */
+  quests;
+  /** Analytics (batched) */
+  analytics;
+  /** App configuration (triggers, quick actions, brand) */
+  app;
+  /** Callback handler for tool execution requests from Ziggy */
+  callbacks;
+  connection;
+  constructor(config) {
+    this.connection = new Connection(config);
+    this.sessions = new SessionManager(this.connection, config);
+    this.chat = new ChatClient(this.connection, this.sessions);
+    this.context = new ContextManager(this.sessions);
+    this.tools = new ToolClient(this.connection, this.sessions);
+    this.feedback = new FeedbackClient(this.connection);
+    this.quests = new QuestClient(this.connection);
+    this.analytics = new AnalyticsClient(this.connection);
+    this.app = new AppClient(this.connection);
+    this.callbacks = new CallbackHandler();
+  }
+  /**
+   * Initialize the client for a user.
+   * Creates a session and starts context batching + analytics.
+   */
+  async connect(request) {
+    const session = await this.sessions.create(request);
+    this.chat.setUserId(request.userId);
+    this.tools.setUserId(request.userId);
+    this.context.start(request.userId, request.onTrigger);
+    this.analytics.start(session.sessionId);
+    return session;
+  }
+  /**
+   * Disconnect — flush analytics, stop batching, end session.
+   */
+  async disconnect() {
+    this.context.stop();
+    await this.analytics.stop();
+    await this.sessions.destroy();
+  }
+};
+export {
+  CallbackHandler,
+  SequenceTracker,
+  ZiggyClient,
+  ZiggyConnectionError,
+  ZiggyError,
+  parseNdjsonStream
+};