flowforge-client 0.1.2

package/dist/index.mjs

@@ -0,0 +1,774 @@
+// src/builder.ts
+var QueryBuilder = class {
+  constructor(request, basePath, responseKey) {
+    this.request = request;
+    this.basePath = basePath;
+    this.responseKey = responseKey;
+    this.params = { filters: {} };
+  }
+  /**
+   * Filter by exact match.
+   */
+  eq(field, value) {
+    this.params.filters[field] = value;
+    return this;
+  }
+  /**
+   * Order results by a field.
+   */
+  order(field, direction = "asc") {
+    this.params.orderBy = field;
+    this.params.orderDir = direction;
+    return this;
+  }
+  /**
+   * Limit the number of results.
+   */
+  limit(n) {
+    this.params.limitValue = n;
+    return this;
+  }
+  /**
+   * Skip the first n results (for pagination).
+   */
+  offset(n) {
+    this.params.offsetValue = n;
+    return this;
+  }
+  /**
+   * Build query string from params.
+   */
+  buildQueryString() {
+    const searchParams = new URLSearchParams();
+    for (const [key, value] of Object.entries(this.params.filters)) {
+      if (value !== void 0 && value !== null) {
+        searchParams.set(key, String(value));
+      }
+    }
+    if (this.params.orderBy) {
+      searchParams.set("order_by", this.params.orderBy);
+      searchParams.set("order_dir", this.params.orderDir || "asc");
+    }
+    if (this.params.limitValue !== void 0) {
+      searchParams.set("limit", String(this.params.limitValue));
+    }
+    if (this.params.offsetValue !== void 0) {
+      searchParams.set("offset", String(this.params.offsetValue));
+    }
+    const query = searchParams.toString();
+    return query ? `?${query}` : "";
+  }
+  /**
+   * Execute the query and return multiple results.
+   */
+  async execute() {
+    const path = `${this.basePath}${this.buildQueryString()}`;
+    const result = await this.request("GET", path);
+    if (result.error) {
+      return { data: null, error: result.error };
+    }
+    const items = result.data[this.responseKey] || [];
+    return { data: items, error: null };
+  }
+  /**
+   * Execute the query and return a single result.
+   * Returns an error if no results found.
+   */
+  async single() {
+    const result = await this.limit(1).execute();
+    if (result.error) {
+      return { data: null, error: result.error };
+    }
+    if (result.data.length === 0) {
+      const error = {
+        message: "No results found",
+        status: 404,
+        name: "FlowForgeError"
+      };
+      return { data: null, error };
+    }
+    return { data: result.data[0], error: null };
+  }
+};
+
+// src/resources/events.ts
+var EventsResource = class {
+  constructor(request) {
+    this.request = request;
+  }
+  /**
+   * Send an event to trigger matching workflows.
+   *
+   * @example
+   * ```ts
+   * const { data, error } = await ff.events.send('order/created', {
+   *   order_id: '123',
+   *   customer: 'Alice'
+   * });
+   * if (error) console.error(error.message);
+   * else console.log('Triggered runs:', data.runs);
+   * ```
+   */
+  async send(name, data, options) {
+    return this.request("POST", "/events", {
+      name,
+      data,
+      id: options?.id,
+      user_id: options?.user_id,
+      timestamp: options?.timestamp
+    });
+  }
+  /**
+   * Get a specific event by ID.
+   *
+   * @example
+   * ```ts
+   * const { data: event } = await ff.events.get('event-id');
+   * ```
+   */
+  async get(eventId) {
+    return this.request("GET", `/events/${eventId}`);
+  }
+  /**
+   * Start building a query to select events.
+   *
+   * @example
+   * ```ts
+   * const { data: events } = await ff.events
+   *   .select()
+   *   .eq('name', 'order/*')
+   *   .limit(10)
+   *   .execute();
+   * ```
+   */
+  select() {
+    return new QueryBuilder(
+      this.request,
+      "/events",
+      "events"
+    );
+  }
+};
+
+// src/resources/runs.ts
+var RunsResource = class {
+  constructor(request) {
+    this.request = request;
+  }
+  /**
+   * Get a run by ID, including its steps.
+   *
+   * @example
+   * ```ts
+   * const { data: run } = await ff.runs.get('run-id');
+   * console.log(run.status, run.steps);
+   * ```
+   */
+  async get(runId) {
+    return this.request("GET", `/runs/${runId}`);
+  }
+  /**
+   * Start building a query to select runs.
+   *
+   * @example
+   * ```ts
+   * const { data: runs } = await ff.runs
+   *   .select()
+   *   .eq('status', 'completed')
+   *   .order('created_at', 'desc')
+   *   .limit(10)
+   *   .execute();
+   * ```
+   */
+  select() {
+    return new QueryBuilder(this.request, "/runs", "runs");
+  }
+  /**
+   * Cancel a running workflow.
+   *
+   * @example
+   * ```ts
+   * const { error } = await ff.runs.cancel('run-id');
+   * if (error) console.error('Failed to cancel:', error.message);
+   * ```
+   */
+  async cancel(runId) {
+    return this.request(
+      "POST",
+      `/runs/${runId}/cancel`
+    );
+  }
+  /**
+   * Replay a completed or failed run.
+   *
+   * @example
+   * ```ts
+   * const { data: newRun } = await ff.runs.replay('run-id');
+   * console.log('New run ID:', newRun.id);
+   * ```
+   */
+  async replay(runId) {
+    return this.request("POST", `/runs/${runId}/replay`);
+  }
+  /**
+   * Wait for a run to complete (polling).
+   *
+   * @example
+   * ```ts
+   * const { data: completedRun, error } = await ff.runs.waitFor('run-id', {
+   *   timeout: 60000
+   * });
+   * if (error) console.error('Timeout or error:', error.message);
+   * else console.log('Run completed with status:', completedRun.status);
+   * ```
+   */
+  async waitFor(runId, options) {
+    const timeout = options?.timeout ?? 6e4;
+    const interval = options?.interval ?? 1e3;
+    const start = Date.now();
+    while (Date.now() - start < timeout) {
+      const result = await this.get(runId);
+      if (result.error) {
+        return result;
+      }
+      if (["completed", "failed", "cancelled"].includes(result.data.status)) {
+        return result;
+      }
+      await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+    const error = {
+      message: "Timeout waiting for run to complete",
+      status: 408,
+      name: "FlowForgeError"
+    };
+    return { data: null, error };
+  }
+};
+
+// src/resources/functions.ts
+var FunctionsResource = class {
+  constructor(request) {
+    this.request = request;
+  }
+  /**
+   * Get a function by ID.
+   *
+   * @example
+   * ```ts
+   * const { data: fn } = await ff.functions.get('my-function');
+   * console.log(fn.name, fn.is_active);
+   * ```
+   */
+  async get(functionId) {
+    return this.request("GET", `/functions/${functionId}`);
+  }
+  /**
+   * Start building a query to select functions.
+   *
+   * @example
+   * ```ts
+   * const { data: fns } = await ff.functions
+   *   .select()
+   *   .eq('is_active', true)
+   *   .eq('trigger_type', 'event')
+   *   .execute();
+   * ```
+   */
+  select() {
+    return new QueryBuilder(
+      this.request,
+      "/functions",
+      "functions"
+    );
+  }
+  /**
+   * Create a new function.
+   *
+   * @example
+   * ```ts
+   * const { data: fn, error } = await ff.functions.create({
+   *   id: 'order-processor',
+   *   name: 'Order Processor',
+   *   trigger_type: 'event',
+   *   trigger_value: 'order/created',
+   *   endpoint_url: 'http://localhost:3000/api/workflows/order',
+   * });
+   * ```
+   */
+  async create(input) {
+    return this.request("POST", "/functions", input);
+  }
+  /**
+   * Update an existing function.
+   *
+   * @example
+   * ```ts
+   * const { error } = await ff.functions.update('my-function', {
+   *   is_active: false
+   * });
+   * ```
+   */
+  async update(functionId, input) {
+    return this.request(
+      "PATCH",
+      `/functions/${functionId}`,
+      input
+    );
+  }
+  /**
+   * Delete a function.
+   *
+   * @example
+   * ```ts
+   * const { error } = await ff.functions.delete('my-function');
+   * if (error) console.error('Failed to delete:', error.message);
+   * ```
+   */
+  async delete(functionId) {
+    return this.request(
+      "DELETE",
+      `/functions/${functionId}`
+    );
+  }
+};
+
+// src/resources/tools.ts
+var ToolsResource = class {
+  constructor(request) {
+    this.request = request;
+  }
+  /**
+   * Get a tool by name.
+   *
+   * @example
+   * ```ts
+   * const { data: tool } = await ff.tools.get('send-email');
+   * console.log(tool.description, tool.requires_approval);
+   * ```
+   */
+  async get(toolName) {
+    return this.request("GET", `/tools/${toolName}`);
+  }
+  /**
+   * Start building a query to select tools.
+   *
+   * @example
+   * ```ts
+   * const { data: tools } = await ff.tools
+   *   .select()
+   *   .eq('requires_approval', true)
+   *   .eq('is_active', true)
+   *   .execute();
+   * ```
+   */
+  select() {
+    return new QueryBuilder(this.request, "/tools", "tools");
+  }
+  /**
+   * Create a new tool.
+   *
+   * @example
+   * ```ts
+   * const { data: tool, error } = await ff.tools.create({
+   *   name: 'send-email',
+   *   description: 'Send an email to a recipient',
+   *   parameters: {
+   *     type: 'object',
+   *     properties: {
+   *       to: { type: 'string', description: 'Recipient email' },
+   *       subject: { type: 'string', description: 'Email subject' },
+   *       body: { type: 'string', description: 'Email body' },
+   *     },
+   *     required: ['to', 'subject', 'body'],
+   *   },
+   *   requires_approval: true,
+   * });
+   * ```
+   */
+  async create(input) {
+    return this.request("POST", "/tools", input);
+  }
+  /**
+   * Update an existing tool.
+   *
+   * @example
+   * ```ts
+   * const { error } = await ff.tools.update('send-email', {
+   *   requires_approval: false
+   * });
+   * ```
+   */
+  async update(toolName, input) {
+    return this.request("PATCH", `/tools/${toolName}`, input);
+  }
+  /**
+   * Delete a tool.
+   *
+   * @example
+   * ```ts
+   * const { error } = await ff.tools.delete('my-tool');
+   * if (error) console.error('Failed to delete:', error.message);
+   * ```
+   */
+  async delete(toolName) {
+    return this.request(
+      "DELETE",
+      `/tools/${toolName}`
+    );
+  }
+};
+
+// src/resources/approvals.ts
+var ApprovalsResource = class {
+  constructor(request) {
+    this.request = request;
+  }
+  /**
+   * Get an approval by ID.
+   *
+   * @example
+   * ```ts
+   * const { data: approval } = await ff.approvals.get('approval-id');
+   * console.log(approval.tool_name, approval.status);
+   * ```
+   */
+  async get(approvalId) {
+    return this.request("GET", `/approvals/${approvalId}`);
+  }
+  /**
+   * Start building a query to select approvals.
+   *
+   * @example
+   * ```ts
+   * const { data: pending } = await ff.approvals
+   *   .select()
+   *   .eq('status', 'pending')
+   *   .execute();
+   * ```
+   */
+  select() {
+    return new QueryBuilder(
+      this.request,
+      "/approvals",
+      "approvals"
+    );
+  }
+  /**
+   * Approve a pending tool call.
+   *
+   * @example
+   * ```ts
+   * const { error } = await ff.approvals.approve('approval-id');
+   * if (error) console.error('Failed to approve:', error.message);
+   * ```
+   *
+   * @example With modified arguments
+   * ```ts
+   * const { error } = await ff.approvals.approve('approval-id', {
+   *   modifiedArguments: { amount: 50 } // Override the original amount
+   * });
+   * ```
+   */
+  async approve(approvalId, options) {
+    return this.request(
+      "POST",
+      `/approvals/${approvalId}/approve`,
+      {
+        modified_arguments: options?.modifiedArguments
+      }
+    );
+  }
+  /**
+   * Reject a pending tool call.
+   *
+   * @example
+   * ```ts
+   * const { error } = await ff.approvals.reject('approval-id', 'Too risky');
+   * if (error) console.error('Failed to reject:', error.message);
+   * ```
+   */
+  async reject(approvalId, reason) {
+    return this.request(
+      "POST",
+      `/approvals/${approvalId}/reject`,
+      { reason }
+    );
+  }
+};
+
+// src/resources/health.ts
+var HealthResource = class {
+  constructor(request) {
+    this.request = request;
+  }
+  /**
+   * Check if the server is healthy.
+   *
+   * @example
+   * ```ts
+   * const { data: healthy, error } = await ff.health.check();
+   * if (healthy) console.log('Server is healthy');
+   * else console.error('Server is unhealthy:', error?.message);
+   * ```
+   */
+  async check() {
+    const result = await this.request("GET", "/health");
+    if (result.error) {
+      return { data: false, error: null };
+    }
+    return { data: result.data.status === "healthy", error: null };
+  }
+  /**
+   * Get server statistics.
+   *
+   * @example
+   * ```ts
+   * const { data: stats } = await ff.health.stats();
+   * console.log('Total runs:', stats.runs.total);
+   * console.log('Active functions:', stats.functions.active);
+   * ```
+   */
+  async stats() {
+    return this.request("GET", "/stats");
+  }
+};
+
+// src/resources/users.ts
+var UsersResource = class {
+  constructor(request) {
+    this.request = request;
+  }
+  /**
+   * List all users (admin only).
+   *
+   * @param options - Filter options
+   * @returns List of users
+   *
+   * @example
+   * ```ts
+   * const { data } = await ff.users.list({ includeInactive: true });
+   * console.log('Total users:', data?.total);
+   * ```
+   */
+  async list(options) {
+    const params = new URLSearchParams();
+    if (options?.includeInactive) {
+      params.set("include_inactive", "true");
+    }
+    const query = params.toString();
+    return this.request(
+      "GET",
+      `/users${query ? `?${query}` : ""}`
+    );
+  }
+  /**
+   * Get a user by ID (admin only).
+   *
+   * @param userId - User ID
+   * @returns User details
+   */
+  async get(userId) {
+    return this.request("GET", `/users/${userId}`);
+  }
+  /**
+   * Create a new user (admin only).
+   *
+   * @param input - User details
+   * @returns Created user
+   *
+   * @example
+   * ```ts
+   * const { data, error } = await ff.users.create({
+   *   email: 'user@example.com',
+   *   password: 'securepassword',
+   *   name: 'John Doe',
+   *   role: 'member'
+   * });
+   * ```
+   */
+  async create(input) {
+    return this.request("POST", "/users", input);
+  }
+  /**
+   * Update a user (admin only).
+   *
+   * @param userId - User ID
+   * @param input - Fields to update
+   * @returns Updated user
+   */
+  async update(userId, input) {
+    return this.request("PATCH", `/users/${userId}`, input);
+  }
+  /**
+   * Delete a user (admin only).
+   *
+   * @param userId - User ID
+   * @returns Success message
+   */
+  async delete(userId) {
+    return this.request("DELETE", `/users/${userId}`);
+  }
+};
+
+// src/resources/api-keys.ts
+var ApiKeysResource = class {
+  constructor(request) {
+    this.request = request;
+  }
+  /**
+   * List all API keys for the tenant.
+   *
+   * @param options - Filter options
+   * @returns List of API keys (without the actual key values)
+   *
+   * @example
+   * ```ts
+   * const { data } = await ff.apiKeys.list();
+   * data?.keys.forEach(key => {
+   *   console.log(`${key.name}: ${key.key_prefix}... (${key.key_type})`);
+   * });
+   * ```
+   */
+  async list(options) {
+    const params = new URLSearchParams();
+    if (options?.includeRevoked) {
+      params.set("include_revoked", "true");
+    }
+    const query = params.toString();
+    return this.request(
+      "GET",
+      `/auth/keys${query ? `?${query}` : ""}`
+    );
+  }
+  /**
+   * Get an API key by ID.
+   *
+   * @param keyId - API key ID
+   * @returns API key details (without the actual key value)
+   */
+  async get(keyId) {
+    return this.request("GET", `/auth/keys/${keyId}`);
+  }
+  /**
+   * Create a new API key.
+   *
+   * @param input - API key configuration
+   * @returns Created API key WITH the actual key value (only returned once!)
+   *
+   * @example
+   * ```ts
+   * const { data, error } = await ff.apiKeys.create({
+   *   name: 'Production API Key',
+   *   key_type: 'live',
+   *   scopes: ['events:send', 'runs:read']
+   * });
+   *
+   * if (data) {
+   *   // IMPORTANT: Store this key - it won't be shown again!
+   *   console.log('New API key:', data.key);  // ff_live_a1b2c3...
+   * }
+   * ```
+   */
+  async create(input) {
+    return this.request("POST", "/auth/keys", input);
+  }
+  /**
+   * Revoke an API key.
+   *
+   * @param keyId - API key ID
+   * @param reason - Optional reason for revocation
+   * @returns Success message
+   *
+   * @example
+   * ```ts
+   * const { error } = await ff.apiKeys.revoke('key-id', 'Compromised');
+   * if (!error) {
+   *   console.log('Key revoked successfully');
+   * }
+   * ```
+   */
+  async revoke(keyId, reason) {
+    return this.request(
+      "DELETE",
+      `/auth/keys/${keyId}`,
+      reason ? { reason } : void 0
+    );
+  }
+};
+
+// src/client.ts
+function createClient(baseUrl, options = {}) {
+  const normalizedBaseUrl = baseUrl.replace(/\/$/, "");
+  const fetchFn = options.fetch || globalThis.fetch;
+  async function request(method, path, body) {
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (options.apiKey) {
+      headers["X-FlowForge-API-Key"] = options.apiKey;
+    }
+    try {
+      const response = await fetchFn(`${normalizedBaseUrl}/api/v1${path}`, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : void 0
+      });
+      if (!response.ok) {
+        const errorBody = await response.json().catch(() => ({}));
+        const error = {
+          message: errorBody.detail || `HTTP ${response.status}`,
+          status: response.status,
+          code: errorBody.code,
+          detail: errorBody,
+          name: "FlowForgeError"
+        };
+        return { data: null, error };
+      }
+      const data = await response.json();
+      return { data, error: null };
+    } catch (err) {
+      const error = {
+        message: err instanceof Error ? err.message : "Network error",
+        status: 0,
+        code: "NETWORK_ERROR",
+        detail: err,
+        name: "FlowForgeError"
+      };
+      return { data: null, error };
+    }
+  }
+  return {
+    events: new EventsResource(request),
+    runs: new RunsResource(request),
+    functions: new FunctionsResource(request),
+    tools: new ToolsResource(request),
+    approvals: new ApprovalsResource(request),
+    health: new HealthResource(request),
+    users: new UsersResource(request),
+    apiKeys: new ApiKeysResource(request)
+  };
+}
+
+// src/types.ts
+var FlowForgeError = class extends Error {
+  constructor(message, status, code, detail) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.detail = detail;
+    this.name = "FlowForgeError";
+  }
+};
+export {
+  ApiKeysResource,
+  ApprovalsResource,
+  EventsResource,
+  FlowForgeError,
+  FunctionsResource,
+  HealthResource,
+  QueryBuilder,
+  RunsResource,
+  ToolsResource,
+  UsersResource,
+  createClient
+};