fal 0.0.1 → 0.1.0

data/lib/fal/webhook_request.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Fal
+  # WebhookRequest parses incoming webhook payloads from fal and exposes
+  # convenient helpers to inspect success/error and access the response payload.
+  # Follows Rails-like naming with predicate helpers.
+  class WebhookRequest
+    # Webhook status values.
+    module Status
+      # @return [String]
+      OK = "OK"
+      # @return [String]
+      ERROR = "ERROR"
+    end
+
+    # @return [String, nil] The request identifier
+    attr_reader :request_id
+    # @return [String, nil] The gateway request identifier, when present
+    attr_reader :gateway_request_id
+    # @return [String, nil] Webhook status (OK/ERROR) when provided
+    attr_reader :status
+    # @return [String, nil] Error message when provided
+    attr_reader :error
+    # @return [Hash, nil] Model-specific response payload
+    attr_reader :response
+    # @return [Array<Hash>, nil] Log entries, when present
+    attr_reader :logs
+    # @return [Hash, nil] Metrics, when present
+    attr_reader :metrics
+    # @return [Hash] The raw parsed payload
+    attr_reader :raw
+
+    # Initialize from a parsed payload Hash (string keys expected, tolerant of symbol keys).
+    # @param attributes [Hash]
+    def initialize(attributes)
+      @raw = attributes
+      reset_attributes(attributes)
+    end
+
+    class << self
+      # Build from a JSON string body.
+      # @param json [String]
+      # @return [Fal::WebhookRequest]
+      def from_json(json)
+        new(JSON.parse(json))
+      end
+
+      # Build from a Rack::Request.
+      # @param request [#body]
+      # @return [Fal::WebhookRequest]
+      def from_rack_request(request)
+        body = request.body.read
+        request.body.rewind if request.body.respond_to?(:rewind)
+        from_json(body)
+      end
+
+      # Build from a Hash payload.
+      # @param payload [Hash]
+      # @return [Fal::WebhookRequest]
+      def from_hash(payload)
+        new(payload)
+      end
+    end
+
+    # @return [Boolean]
+    def success?
+      @status == Status::OK || (
+        @status.nil? && @error.nil?
+      )
+    end
+
+    # @return [Boolean]
+    def error?
+      !success?
+    end
+
+    # Back-compat alias matching older naming (payload vs response).
+    # @return [Hash, nil]
+    def payload
+      @response
+    end
+
+    # @return [String, nil] Any nested error detail
+    def error_detail = @response&.dig(:detail)
+
+    private
+
+    def reset_attributes(attributes)
+      attributes = Fal.deep_symbolize_keys(attributes)
+      @request_id = attributes[:request_id]
+      @gateway_request_id = attributes[:gateway_request_id]
+      @status = attributes[:status]
+      @error = attributes[:error]
+      @response = attributes[:payload]
+      @logs = attributes[:logs]
+      @metrics = attributes[:metrics]
+    end
+  end
+end

data/lib/fal.rb

@@ -2,6 +2,108 @@
 
 require "faraday"
 require "time"
+require "json"
+require "cgi"
+require "uri"
+
+require_relative "fal/version"
 
 module Fal
+  # Base error class for all fal-related errors.
+  class Error < StandardError; end
+  # Raised when a request is unauthorized (HTTP 401).
+  class UnauthorizedError < Error; end
+  # Raised when a requested resource is not found (HTTP 404).
+  class NotFoundError < Error; end
+  # Raised when the server returns an unexpected error (HTTP 5xx or others).
+  class ServerError < Error; end
+  # Raised when the client is misconfigured.
+  class ConfigurationError < Error; end
+  # Raised when access is forbidden (HTTP 403).
+  class ForbiddenError < Error; end
+
+  # Global configuration for the fal client.
+  class Configuration
+    DEFAULT_QUEUE_BASE = "https://queue.fal.run"
+    DEFAULT_SYNC_BASE = "https://fal.run"
+    DEFAULT_API_BASE = "https://api.fal.ai/v1"
+    DEFAULT_REQUEST_TIMEOUT = 120
+
+    # API key used for authenticating with fal endpoints.
+    # Defaults to ENV["FAL_KEY"].
+    # @return [String]
+    attr_accessor :api_key
+
+    # Base URL for fal queue endpoints.
+    # @return [String]
+    attr_accessor :queue_base
+
+    # Base URL for synchronous streaming endpoints (fal.run).
+    # @return [String]
+    attr_accessor :sync_base
+
+    # Base URL for platform API endpoints (api.fal.ai/v1).
+    # @return [String]
+    attr_accessor :api_base
+
+    # Timeout in seconds for opening and processing HTTP requests.
+    # @return [Integer]
+    attr_accessor :request_timeout
+
+    # Initialize configuration with sensible defaults.
+    # @return [Fal::Configuration]
+    def initialize
+      @api_key = ENV.fetch("FAL_KEY", nil)
+      @queue_base = DEFAULT_QUEUE_BASE
+      @sync_base = DEFAULT_SYNC_BASE
+      @api_base = DEFAULT_API_BASE
+      @request_timeout = DEFAULT_REQUEST_TIMEOUT
+    end
+  end
+
+  class << self
+    # The global configuration instance.
+    # @return [Fal::Configuration]
+    attr_accessor :configuration
+
+    # Configure the fal client.
+    # @yield [Fal::Configuration] the configuration object to mutate
+    # @return [void]
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration)
+    end
+
+    # Global client accessor using the configured settings.
+    # @return [Fal::Client]
+    def client
+      configuration = self.configuration || Configuration.new
+      @client ||= Fal::Client.new(configuration)
+    end
+
+    # Deep symbolize keys of a Hash or Array.
+    # @param obj [Hash, Array]
+    # @return [Hash, Array]
+    def deep_symbolize_keys(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) do |(k, v), result|
+          key = k.is_a?(String) ? k.to_sym : k
+          result[key] = deep_symbolize_keys(v)
+        end
+      when Array
+        obj.map { |e| deep_symbolize_keys(e) }
+      else
+        obj
+      end
+    end
+  end
 end
+
+require_relative "fal/client"
+require_relative "fal/request"
+require_relative "fal/stream"
+require_relative "fal/webhook_request"
+require_relative "fal/price"
+require_relative "fal/price_estimate"
+require_relative "fal/model"

data/rbi/fal/client.rbi

@@ -0,0 +1,59 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Fal
+  class Client
+    sig { returns(Fal::Configuration) }
+    def configuration; end
+
+    sig { params(value: Fal::Configuration).returns(Fal::Configuration) }
+    def configuration=(value); end
+
+    sig { params(configuration: T.nilable(Fal::Configuration)).void }
+    def initialize(configuration = nil); end
+
+    sig { params(path: String, payload: T.untyped, headers: T.untyped).returns(T.untyped) }
+    def post(path, payload = nil, headers: {}); end
+
+    sig do
+      params(
+        path: String,
+        payload: T.untyped,
+        on_data: T.proc.params(arg0: String, arg1: T.untyped).void
+      ).void
+    end
+    def post_stream(path, payload = nil, on_data:); end
+
+    sig { params(path: String, query: T.untyped, headers: T.untyped).returns(T.untyped) }
+    def get(path, query: nil, headers: {}); end
+
+    sig { params(path: String, query: T.untyped, headers: T.untyped).returns(T.untyped) }
+    def get_api(path, query: nil, headers: {}); end
+
+    sig { params(path: String, payload: T.untyped, headers: T.untyped).returns(T.untyped) }
+    def post_api(path, payload = nil, headers: {}); end
+
+    sig { params(path: String).returns(T.untyped) }
+    def put(path); end
+
+    sig { params(response: T.untyped).void }
+    def handle_error(response); end
+
+    private
+
+    sig { params(body: T.untyped).returns(T.untyped) }
+    def parse_json(body); end
+
+    sig { params(path: String).returns(String) }
+    def build_url(path); end
+
+    sig { params(path: String).returns(String) }
+    def build_sync_url(path); end
+
+    sig { params(path: String).returns(String) }
+    def build_api_url(path); end
+
+    sig { returns(T.untyped) }
+    def connection; end
+  end
+end

data/rbi/fal/fal.rbi

@@ -0,0 +1,68 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Fal
+  class Error < StandardError; end
+  class UnauthorizedError < Error; end
+  class NotFoundError < Error; end
+  class ServerError < Error; end
+  class ConfigurationError < Error; end
+  class ForbiddenError < Error; end
+
+  class Configuration
+    # api_key
+    sig { returns(T.nilable(String)) }
+    def api_key; end
+
+    sig { params(value: T.nilable(String)).returns(T.nilable(String)) }
+    def api_key=(value); end
+
+    # queue_base
+    sig { returns(String) }
+    def queue_base; end
+
+    sig { params(value: String).returns(String) }
+    def queue_base=(value); end
+
+    # sync_base
+    sig { returns(String) }
+    def sync_base; end
+
+    sig { params(value: String).returns(String) }
+    def sync_base=(value); end
+
+    # api_base
+    sig { returns(String) }
+    def api_base; end
+
+    sig { params(value: String).returns(String) }
+    def api_base=(value); end
+
+    # request_timeout
+    sig { returns(Integer) }
+    def request_timeout; end
+
+    sig { params(value: Integer).returns(Integer) }
+    def request_timeout=(value); end
+
+    sig { void }
+    def initialize; end
+  end
+
+  class << self
+    sig { returns(Fal::Configuration) }
+    def configuration; end
+
+    sig { params(value: Fal::Configuration).returns(Fal::Configuration) }
+    def configuration=(value); end
+
+    sig { params(block: T.proc.params(arg0: Fal::Configuration).void).void }
+    def configure(&block); end
+
+    sig { returns(Fal::Client) }
+    def client; end
+
+    sig { params(obj: T.untyped).returns(T.untyped) }
+    def deep_symbolize_keys(obj); end
+  end
+end

data/rbi/fal/model.rbi

@@ -0,0 +1,130 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Fal
+  class Model
+    MODELS_PATH = T.let(T.unsafe(nil), String)
+
+    sig { returns(String) }
+    def endpoint_id; end
+
+    sig { returns(T.nilable(String)) }
+    def display_name; end
+
+    sig { returns(T.nilable(String)) }
+    def category; end
+
+    sig { returns(T.nilable(String)) }
+    def description; end
+
+    sig { returns(T.nilable(String)) }
+    def status; end
+
+    sig { returns(T.nilable(T::Array[String])) }
+    def tags; end
+
+    sig { returns(T.nilable(String)) }
+    def updated_at; end
+
+    sig { returns(T.nilable(T::Boolean)) }
+    def is_favorited; end
+
+    sig { returns(T.nilable(String)) }
+    def thumbnail_url; end
+
+    sig { returns(T.nilable(String)) }
+    def thumbnail_animated_url; end
+
+    sig { returns(T.nilable(String)) }
+    def model_url; end
+
+    sig { returns(T.nilable(String)) }
+    def github_url; end
+
+    sig { returns(T.nilable(String)) }
+    def license_type; end
+
+    sig { returns(T.nilable(String)) }
+    def date; end
+
+    sig { returns(T.nilable(T::Hash[T.untyped, T.untyped])) }
+    def group; end
+
+    sig { returns(T.nilable(T::Boolean)) }
+    def highlighted; end
+
+    sig { returns(T.nilable(String)) }
+    def kind; end
+
+    sig { returns(T.nilable(T::Array[String])) }
+    def training_endpoint_ids; end
+
+    sig { returns(T.nilable(T::Array[String])) }
+    def inference_endpoint_ids; end
+
+    sig { returns(T.nilable(String)) }
+    def stream_url; end
+
+    sig { returns(T.nilable(Float)) }
+    def duration_estimate; end
+
+    sig { returns(T.nilable(T::Boolean)) }
+    def pinned; end
+
+    sig { returns(T.nilable(T::Hash[T.untyped, T.untyped])) }
+    def openapi; end
+
+    sig { params(attributes: T.untyped, client: Fal::Client).void }
+    def initialize(attributes, client: Fal.client); end
+
+    sig { returns(T.nilable(Fal::Price)) }
+    def price; end
+
+    sig { params(input: T.untyped, webhook_url: T.nilable(String)).returns(Fal::Request) }
+    def run(input:, webhook_url: nil); end
+
+    class << self
+      sig { params(endpoint_id: String, client: Fal::Client).returns(T.nilable(Fal::Model)) }
+      def find_by(endpoint_id:, client: Fal.client); end
+
+      sig do
+        params(
+          client: Fal::Client,
+          query: T.nilable(String),
+          category: T.nilable(String),
+          status: T.nilable(String),
+          expand: T.nilable(T.any(String, T::Array[String])),
+          block: T.proc.params(arg0: Fal::Model).void
+        ).void
+      end
+      def each(client: Fal.client, query: nil, category: nil, status: nil, expand: nil, &block); end
+
+      sig do
+        params(
+          client: Fal::Client,
+          query: T.nilable(String),
+          category: T.nilable(String),
+          status: T.nilable(String),
+          expand: T.nilable(T.any(String, T::Array[String]))
+        ).returns(T::Array[Fal::Model])
+      end
+      def all(client: Fal.client, query: nil, category: nil, status: nil, expand: nil); end
+
+      sig do
+        params(
+          query: T.nilable(String),
+          category: T.nilable(String),
+          status: T.nilable(String),
+          expand: T.nilable(T.any(String, T::Array[String])),
+          client: Fal::Client
+        ).returns(T::Array[Fal::Model])
+      end
+      def search(query: nil, category: nil, status: nil, expand: nil, client: Fal.client); end
+    end
+
+    private
+
+    sig { params(attributes: T.untyped).void }
+    def reset_attributes(attributes); end
+  end
+end

data/rbi/fal/price.rbi

@@ -0,0 +1,49 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Fal
+  class Price
+    MODELS_PATH = T.let(T.unsafe(nil), String)
+    PRICING_PATH = T.let(T.unsafe(nil), String)
+
+    module Unit
+      IMAGES = T.let(T.unsafe(nil), String)
+      VIDEOS = T.let(T.unsafe(nil), String)
+      MEGAPIXELS = T.let(T.unsafe(nil), String)
+      GPU_SECONDS = T.let(T.unsafe(nil), String)
+      GPU_MINUTES = T.let(T.unsafe(nil), String)
+      GPU_HOURS = T.let(T.unsafe(nil), String)
+    end
+
+    sig { returns(String) }
+    def endpoint_id; end
+
+    sig { returns(Float) }
+    def unit_price; end
+
+    sig { returns(String) }
+    def unit; end
+
+    sig { returns(String) }
+    def currency; end
+
+    sig { params(attributes: T.untyped, client: Fal::Client).void }
+    def initialize(attributes, client: Fal.client); end
+
+    class << self
+      sig { params(endpoint_id: String, client: Fal::Client).returns(T.nilable(Fal::Price)) }
+      def find_by(endpoint_id:, client: Fal.client); end
+
+      sig { params(client: Fal::Client, block: T.proc.params(arg0: Fal::Price).void).void }
+      def each(client: Fal.client, &block); end
+
+      sig { params(client: Fal::Client).returns(T::Array[Fal::Price]) }
+      def all(client: Fal.client); end
+    end
+
+    private
+
+    sig { params(attributes: T.untyped).void }
+    def reset_attributes(attributes); end
+  end
+end

data/rbi/fal/price_estimate.rbi

@@ -0,0 +1,61 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Fal
+  class PriceEstimate
+    ESTIMATE_PATH = T.let(T.unsafe(nil), String)
+
+    module EstimateType
+      HISTORICAL_API_PRICE = T.let(T.unsafe(nil), String)
+      UNIT_PRICE = T.let(T.unsafe(nil), String)
+    end
+
+    class Endpoint
+      sig { returns(String) }
+      def endpoint_id; end
+
+      sig { returns(T.nilable(Integer)) }
+      def call_quantity; end
+
+      sig { returns(T.nilable(Float)) }
+      def unit_quantity; end
+
+      sig do
+        params(
+          endpoint_id: String,
+          call_quantity: T.nilable(Integer),
+          unit_quantity: T.nilable(Float)
+        ).void
+      end
+      def initialize(endpoint_id:, call_quantity: nil, unit_quantity: nil); end
+    end
+
+    sig { returns(String) }
+    def estimate_type; end
+
+    sig { returns(Float) }
+    def total_cost; end
+
+    sig { returns(String) }
+    def currency; end
+
+    sig { params(attributes: T.untyped, client: Fal::Client).void }
+    def initialize(attributes, client: Fal.client); end
+
+    class << self
+      sig do
+        params(
+          estimate_type: String,
+          endpoints: T::Array[T.any(Fal::PriceEstimate::Endpoint, T.untyped)],
+          client: Fal::Client
+        ).returns(Fal::PriceEstimate)
+      end
+      def create(estimate_type:, endpoints:, client: Fal.client); end
+    end
+
+    private
+
+    sig { params(attributes: T.untyped).void }
+    def reset_attributes(attributes); end
+  end
+end

data/rbi/fal/request.rbi

@@ -0,0 +1,88 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Fal
+  class Request
+    sig { returns(String) }
+    def id; end
+
+    sig { returns(String) }
+    def status; end
+
+    sig { returns(T.nilable(Integer)) }
+    def queue_position; end
+
+    sig { returns(T.untyped) }
+    def logs; end
+
+    sig { returns(T.untyped) }
+    def response; end
+
+    sig { returns(String) }
+    def endpoint_id; end
+
+    sig do
+      params(
+        attributes: T.untyped,
+        endpoint_id: String,
+        client: Fal::Client
+      ).void
+    end
+    def initialize(attributes, endpoint_id:, client:); end
+
+    class << self
+      sig do
+        params(
+          endpoint_id: String,
+          input: T.untyped,
+          client: Fal::Client,
+          webhook_url: T.nilable(String)
+        ).returns(Fal::Request)
+      end
+      def create!(endpoint_id:, input:, client:, webhook_url: nil); end
+
+      sig do
+        params(
+          id: String,
+          endpoint_id: String,
+          client: Fal::Client,
+          logs: T::Boolean
+        ).returns(Fal::Request)
+      end
+      def find_by!(id:, endpoint_id:, client:, logs: false); end
+
+      sig do
+        params(
+          endpoint_id: String,
+          input: T.untyped,
+          client: Fal::Client,
+          block: T.nilable(T.proc.params(arg0: T.untyped).void)
+        ).returns(Fal::Request)
+      end
+      def stream!(endpoint_id:, input:, client: Fal.client, &block); end
+    end
+
+    sig { returns(String) }
+    def endpoint_id_without_subpath; end
+
+    sig { params(logs: T::Boolean).returns(Fal::Request) }
+    def reload!(logs: false); end
+
+    sig { returns(T.untyped) }
+    def cancel!; end
+
+    sig { returns(T::Boolean) }
+    def in_queue?; end
+
+    sig { returns(T::Boolean) }
+    def in_progress?; end
+
+    sig { returns(T::Boolean) }
+    def completed?; end
+
+    private
+
+    sig { params(attributes: T.untyped).void }
+    def reset_attributes(attributes); end
+  end
+end

data/rbi/fal/stream.rbi

@@ -0,0 +1,37 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Fal
+  class Stream
+    sig { returns(String) }
+    def path; end
+
+    sig do
+      params(
+        path: String,
+        input: T.untyped,
+        client: Fal::Client
+      ).void
+    end
+    def initialize(path:, input:, client: Fal.client); end
+
+    sig do
+      params(block: T.proc.params(arg0: T.untyped)
+      .void).void
+    end
+    def each(&block); end
+
+    class SSEDecoder
+      sig { void }
+      def initialize; end
+
+      sig { params(line: String).returns(T.untyped) }
+      def decode(line); end
+
+      private
+
+      sig { returns(T.untyped) }
+      def flush_event; end
+    end
+  end
+end

data/rbi/fal/version.rbi

@@ -0,0 +1,6 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Fal
+  VERSION = T.let(T.unsafe(nil), String)
+end