fal 0.0.3 → 0.1.0

data/lib/fal/price_estimate.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Fal
+  # Represents a cost estimate response from the Platform API.
+  # Computes estimates via POST /models/pricing/estimate.
+  class PriceEstimate
+    ESTIMATE_PATH = "/models/pricing/estimate"
+
+    # Supported estimate types.
+    module EstimateType
+      # @return [String]
+      HISTORICAL_API_PRICE = "historical_api_price"
+      # @return [String]
+      UNIT_PRICE = "unit_price"
+    end
+
+    # Simple value object for endpoint inputs.
+    class Endpoint
+      # @return [String]
+      attr_reader :endpoint_id
+      # @return [Integer, nil]
+      attr_reader :call_quantity
+      # @return [Float, nil]
+      attr_reader :unit_quantity
+
+      # @param endpoint_id [String]
+      # @param call_quantity [Integer, nil]
+      # @param unit_quantity [Float, nil]
+      def initialize(endpoint_id:, call_quantity: nil, unit_quantity: nil)
+        @endpoint_id = endpoint_id
+        @call_quantity = call_quantity
+        @unit_quantity = unit_quantity
+      end
+    end
+
+    # @return [String]
+    attr_reader :estimate_type
+    # @return [Float]
+    attr_reader :total_cost
+    # @return [String]
+    attr_reader :currency
+
+    # @param attributes [Hash]
+    # @param client [Fal::Client]
+    def initialize(attributes, client: Fal.client)
+      @client = client
+      reset_attributes(attributes)
+    end
+
+    class << self
+      # Create a new cost estimate.
+      # Corresponds to POST https://api.fal.ai/v1/models/pricing/estimate
+      # @param estimate_type [String] one of EstimateType constants
+      # @param endpoints [Array<Fal::PriceEstimate::Endpoint, Hash>]
+      # @param client [Fal::Client]
+      # @return [Fal::PriceEstimate]
+      def create(estimate_type:, endpoints:, client: Fal.client)
+        endpoint_map = {}
+        Array(endpoints).each do |ep|
+          endpoint = ep.is_a?(Endpoint) ? ep : Endpoint.new(**ep)
+          quantity = endpoint.unit_quantity || endpoint.call_quantity
+
+          if estimate_type == EstimateType::UNIT_PRICE
+            # Accept either unit_quantity or call_quantity (treated as units) for convenience.
+            endpoint_map[endpoint.endpoint_id] = { "unit_quantity" => quantity }
+          else
+            endpoint_map[endpoint.endpoint_id] = { "call_quantity" => quantity }
+          end
+        end
+
+        payload = {
+          estimate_type: estimate_type,
+          endpoints: endpoint_map
+        }
+
+        attributes = client.post_api(ESTIMATE_PATH, payload)
+        new(attributes, client: client)
+      end
+    end
+
+    private
+
+    def reset_attributes(attributes)
+      @estimate_type = attributes["estimate_type"]
+      @total_cost = attributes["total_cost"]
+      @currency = attributes["currency"]
+    end
+  end
+end

data/lib/fal/request.rb

@@ -27,57 +27,58 @@ module Fal
     # @return [Hash, nil] Response payload when status is COMPLETED
     attr_reader :response
     # @return [String] The model identifier used when creating this request
-    attr_reader :model_id
+    attr_reader :endpoint_id
 
     # @param attributes [Hash] Raw attributes from fal Queue API
-    # @param model_id [String] Model ID in "namespace/name" format
+    # @param endpoint_id [String] Model ID in "namespace/name" format
     # @param client [Fal::Client] HTTP client to use for subsequent calls
-    def initialize(attributes, model_id:, client: Fal.client)
+    def initialize(attributes, endpoint_id:, client: Fal.client)
       @client = client
-      @model_id = model_id
+      @endpoint_id = endpoint_id
       reset_attributes(attributes)
     end
 
     class << self
       # Create a new queued request for a model.
-      # Corresponds to POST https://queue.fal.run/{model_id}
+      # Corresponds to POST https://queue.fal.run/{endpoint_id}
       # Optionally appends fal_webhook query param per docs.
-      # @param model_id [String]
+      # @param endpoint_id [String]
       # @param input [Hash]
       # @param webhook_url [String, nil]
       # @param client [Fal::Client]
       # @return [Fal::Request]
-      def create!(model_id:, input:, webhook_url: nil, client: Fal.client)
-        path = "/#{model_id}"
+      def create!(endpoint_id:, input:, webhook_url: nil, client: Fal.client)
+        path = "/#{endpoint_id}"
         body = input || {}
         path = "#{path}?fal_webhook=#{CGI.escape(webhook_url)}" if webhook_url
-        attrs = client.post(path, body)
-        new(attrs, model_id: model_id, client: client)
+        attributes = client.post(path, body)
+        new(attributes, endpoint_id: endpoint_id, client: client)
       end
 
       # Find the current status for a given request.
-      # Corresponds to GET https://queue.fal.run/{model_id}/requests/{request_id}/status
+      # Corresponds to GET https://queue.fal.run/{endpoint_id}/requests/{request_id}/status
       # @param id [String]
-      # @param model_id [String]
+      # @param endpoint_id [String]
       # @param logs [Boolean] include logs if true
       # @param client [Fal::Client]
       # @return [Fal::Request]
-      def find_by!(id:, model_id:, logs: false, client: Fal.client)
-        model_id_without_subpath = model_id.split("/").slice(0, 2).join("/")
-        attrs = client.get("/#{model_id_without_subpath}/requests/#{id}/status", query: (logs ? { logs: 1 } : nil))
-        new(attrs, model_id: model_id, client: client)
+      def find_by!(id:, endpoint_id:, logs: false, client: Fal.client)
+        endpoint_id_without_subpath = endpoint_id.split("/").slice(0, 2).join("/")
+        attributes = client.get("/#{endpoint_id_without_subpath}/requests/#{id}/status",
+                                query: (logs ? { logs: 1 } : nil))
+        new(attributes, endpoint_id: endpoint_id, client: client)
       end
 
       # Stream a synchronous request using SSE and yield response chunks as they arrive.
       # It returns a Fal::Request initialized with the last streamed data in the response field.
-      # @param model_id [String]
+      # @param endpoint_id [String]
       # @param input [Hash]
       # @param client [Fal::Client]
       # @yield [chunk] yields each parsed chunk Hash from the stream
       # @yieldparam chunk [Hash]
       # @return [Fal::Request]
-      def stream!(model_id:, input:, client: Fal.client, &block)
-        path = "/#{model_id}/stream"
+      def stream!(endpoint_id:, input:, client: Fal.client, &block)
+        path = "/#{endpoint_id}/stream"
         last_data = nil
 
         Stream.new(path: path, input: input, client: client).each do |event|
@@ -93,18 +94,18 @@ module Fal
                            else
                              last_data
                            end
-        attrs = {
+        attributes = {
           "request_id" => last_data && last_data["request_id"],
           "status" => last_data && last_data["status"],
           "response" => response_payload
         }.compact
-        new(attrs, model_id: model_id, client: client)
+        new(attributes, endpoint_id: endpoint_id, client: client)
       end
     end
 
     # @return [String] The model ID without the subpath
-    def model_id_without_subpath
-      @model_id.split("/").slice(0, 2).join("/")
+    def endpoint_id_without_subpath
+      @endpoint_id.split("/").slice(0, 2).join("/")
     end
 
     # Reload the current status from the Queue API.
@@ -112,11 +113,12 @@ module Fal
     # @return [Fal::Request]
     def reload!(logs: false)
       if @status == Status::IN_PROGRESS || @status == Status::IN_QUEUE
-        attrs = @client.get("/#{model_id_without_subpath}/requests/#{@id}/status", query: (logs ? { logs: 1 } : nil))
-        reset_attributes(attrs)
+        attributes = @client.get("/#{endpoint_id_without_subpath}/requests/#{@id}/status",
+                                 query: (logs ? { logs: 1 } : nil))
+        reset_attributes(attributes)
       end
 
-      @response = @client.get("/#{model_id_without_subpath}/requests/#{@id}") if @status == Status::COMPLETED
+      @response = @client.get("/#{endpoint_id_without_subpath}/requests/#{@id}") if @status == Status::COMPLETED
 
       self
     end
@@ -124,7 +126,7 @@ module Fal
     # Attempt to cancel the request if still in queue.
     # @return [Hash] cancellation response
     def cancel!
-      @client.put("/#{model_id_without_subpath}/requests/#{@id}/cancel")
+      @client.put("/#{endpoint_id_without_subpath}/requests/#{@id}/cancel")
     end
 
     # @return [Boolean]

data/lib/fal/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Fal
-  VERSION = "0.0.3"
+  VERSION = "0.1.0"
 end

data/lib/fal/webhook_request.rb

@@ -46,11 +46,11 @@ module Fal
       end
 
       # Build from a Rack::Request.
-      # @param req [#body]
+      # @param request [#body]
       # @return [Fal::WebhookRequest]
-      def from_rack_request(req)
-        body = req.body.read
-        req.body.rewind if req.body.respond_to?(:rewind)
+      def from_rack_request(request)
+        body = request.body.read
+        request.body.rewind if request.body.respond_to?(:rewind)
         from_json(body)
       end
 

data/lib/fal.rb

@@ -26,6 +26,7 @@ module Fal
   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.
@@ -41,6 +42,10 @@ module Fal
     # @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
@@ -51,6 +56,7 @@ module Fal
       @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
@@ -98,3 +104,6 @@ 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