flatfile_api 0.1.0

data/lib/flatfile_api.rb

@@ -0,0 +1,447 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+
+require_relative "flatfile_api/version"
+require_relative "flatfile_api/response"
+require_relative "flatfile_api/paginated_response"
+require_relative "flatfile_api/string_tools"
+
+class FlatfileApi
+	class Error < StandardError; end
+
+	using StringTools
+
+	PROTO = "https"
+	HOST  = "api.us.flatfile.io"
+
+	def initialize(access_key_id: ENV['FLATFILE_ACCESS_KEY_ID'], secret_access_key: ENV['FLATFILE_SECRET_ACCESS_KEY'], debug: false)
+		@access_key_id = access_key_id
+		@secret_access_key = secret_access_key
+		@debug = debug
+		@redirect_limit = 5
+
+		@base_uri = URI "#{PROTO}://#{HOST}"
+		@agent = Net::HTTP.new @base_uri.host, @base_uri.port
+		@agent.use_ssl = PROTO == 'https'
+		@agent.keep_alive_timeout = 10
+		@agent.set_debug_output $stdout if @debug
+	end
+
+	def exchange_access_key_for_jwt(
+		access_key_id:,
+		expires_in:nil,
+		secret_access_key:
+	)
+
+		request(
+			:post,
+			"/auth/access-key-exchange",
+			body_params: {
+				accessKeyId: access_key_id, # Access Key generated in app
+				expiresIn: expires_in, # Sets an expiration (in seconds)
+				secretAccessKey: secret_access_key, # Secret Access Key generated in app
+			},
+		)
+	end
+
+	def download_an_upload(
+		batch_id:,
+		type:
+	)
+
+		request(
+			:get,
+			"/batch/%<batchId>s/export.csv",
+			path_params: {
+				batchId: batch_id, # A valid UUID
+			},
+			query_params: {
+				type: type, # File to download
+			},
+		)
+	end
+
+	def delete_an_upload(
+		batch_id:
+	)
+
+		request(
+			:delete,
+			"/batch/%<batchId>s",
+			path_params: {
+				batchId: batch_id, # A valid UUID
+			},
+		)
+	end
+
+	def bulk_delete_uploads(
+		older_than_quantity:,
+		older_than_unit:,
+		send_email:,
+		team_id:
+	)
+
+		request(
+			:get,
+			"/delete/batches",
+			query_params: {
+				olderThanQuantity: older_than_quantity,
+				olderThanUnit: older_than_unit,
+				sendEmail: send_email,
+				teamId: team_id,
+			},
+		)
+	end
+
+	def list_workspace_uploads(
+		end_user_id:nil,
+		environment_id:nil,
+		license_key:,
+		search:nil,
+		skip:nil,
+		take:nil,
+		workspace_id:nil
+	)
+
+		request(
+			:get,
+			"/rest/batches",
+			query_params: {
+				endUserId: end_user_id, # Valid endUserId for the Workspace
+				environmentId: environment_id, # Valid environmentId for the Workspace
+				licenseKey: license_key, # A valid licenseKey for the Workspace
+				search: search, # Searches fileName, originalFile, memo
+				skip: skip, # The rows to skip before listing
+				take: take, # The maximum number of rows to return
+				workspaceId: workspace_id, # Valid workspaceId for the Workspace
+			},
+		)
+	end
+
+	def file_upload_meta_data(
+		batch_id:
+	)
+
+		request(
+			:get,
+			"/rest/batch/%<batchId>s",
+			path_params: {
+				batchId: batch_id, # A valid UUID
+			},
+		)
+	end
+
+	def sheet_name_for_file_upload(
+		upload_id:,
+		license_key:nil
+	)
+
+		request(
+			:get,
+			"/upload/%<uploadId>s/dataSources",
+			path_params: {
+				uploadId: upload_id, # A valid UUID
+			},
+			query_params: {
+				licenseKey: license_key, # A valid licenseKey for the Workspace
+			},
+		)
+	end
+
+	def records_for_file_upload(
+		batch_id:,
+		created_at_end_date:nil,
+		created_at_start_date:nil,
+		deleted:nil,
+		skip:nil,
+		take:nil,
+		updated_at_end_date:nil,
+		updated_at_start_date:nil,
+		valid:nil
+	)
+
+		request(
+			:get,
+			"/rest/batch/%<batchId>s/rows",
+			path_params: {
+				batchId: batch_id, # A valid UUID
+			},
+			query_params: {
+				createdAtEndDate: created_at_end_date, # The maximum createdAt date to return
+				createdAtStartDate: created_at_start_date, # The minimum createdAt date to return
+				deleted: deleted, # Return only deleted rows
+				skip: skip, # The rows to skip before listing
+				take: take, # The maximum number of rows to return
+				updatedAtEndDate: updated_at_end_date, # The maximum updatedAt date to return
+				updatedAtStartDate: updated_at_start_date, # The minimum updatedAt date to return
+				valid: valid, # Return only valid rows
+			},
+		)
+	end
+
+	def upload_to_workspace_sheet(
+		sheet_id:,
+		workspace_id:
+	)
+
+		request(
+			:post,
+			"/workspace/%<workspaceId>s/sheet/%<sheetId>s/data",
+			path_params: {
+				sheetId: sheet_id, # A valid UUID
+				workspaceId: workspace_id, # A valid UUID
+			},
+		)
+	end
+
+	def fetch_workspace_sheet_records(
+		sheet_id:,
+		workspace_id:,
+		filter:nil,
+		merge_id:nil,
+		nested:nil,
+		record_ids:nil,
+		skip:nil,
+		take:nil,
+		valid:nil
+	)
+
+		request(
+			:get,
+			"/workspace/%<workspaceId>s/sheet/%<sheetId>s/records",
+			path_params: {
+				sheetId: sheet_id, # A valid UUID
+				workspaceId: workspace_id, # A valid UUID
+			},
+			query_params: {
+				filter: filter, # Return only the filtered rows
+				mergeId: merge_id,
+				nested: nested,
+				recordIds: record_ids,
+				skip: skip, # The rows to skip before listing
+				take: take, # The maximum number of rows to return
+				valid: valid, # Return only valid rows
+			},
+		)
+	end
+
+	def list_team_workspaces(
+		team_id:,
+		environment_id:nil,
+		skip:nil,
+		take:nil
+	)
+
+		request(
+			:get,
+			"/rest/teams/%<teamId>s/workspaces",
+			path_params: {
+				teamId: team_id,
+			},
+			query_params: {
+				environmentId: environment_id, # Valid environmentId for the Workspace
+				skip: skip, # The rows to skip before listing
+				take: take, # The maximum number of rows to return
+			},
+		)
+	end
+
+	def detail_workspace(
+		workspace_id:
+	)
+
+		request(
+			:get,
+			"/rest/workspace/%<workspaceId>s",
+			path_params: {
+				workspaceId: workspace_id, # A valid UUID
+			},
+		)
+	end
+
+	def invite_workspace_collaborator(
+		team_id:,
+		workspace_id:,
+		email:
+	)
+
+		request(
+			:post,
+			"/rest/teams/%<teamId>s/workspaces/%<workspaceId>s/invitations",
+			path_params: {
+				teamId: team_id,
+				workspaceId: workspace_id, # A valid UUID
+			},
+			body_params: {
+				email: email, # Email address of invited collaborator
+			},
+		)
+	end
+
+	def list_workspace_invitations(
+		team_id:,
+		workspace_id:
+	)
+
+		request(
+			:get,
+			"/rest/teams/%<teamId>s/workspaces/%<workspaceId>s/invitations",
+			path_params: {
+				teamId: team_id,
+				workspaceId: workspace_id, # A valid UUID
+			},
+		)
+	end
+
+	def list_workspace_collaborators(
+		team_id:,
+		workspace_id:
+	)
+
+		request(
+			:get,
+			"/rest/teams/%<teamId>s/workspaces/%<workspaceId>s/collaborators",
+			path_params: {
+				teamId: team_id,
+				workspaceId: workspace_id, # A valid UUID
+			},
+		)
+	end
+
+	def revoke_workspace_invitation(
+		team_id:,
+		workspace_id:,
+		email:
+	)
+
+		request(
+			:delete,
+			"/rest/teams/%<teamId>s/workspaces/%<workspaceId>s/invitations",
+			path_params: {
+				teamId: team_id,
+				workspaceId: workspace_id, # A valid UUID
+			},
+			body_params: {
+				email: email, # Email address of invited collaborator
+			},
+		)
+	end
+
+	def remove_workspace_collaborator(
+		team_id:,
+		user_id:,
+		workspace_id:,
+		email:
+	)
+
+		request(
+			:delete,
+			"/rest/teams/%<teamId>s/workspaces/%<workspaceId>s/collaborators/%<userId>s",
+			path_params: {
+				teamId: team_id,
+				userId: user_id,
+				workspaceId: workspace_id, # A valid UUID
+			},
+			body_params: {
+				email: email, # Email address of collaborator
+			},
+		)
+	end
+
+	# def inspect
+	# 	"#<#{self.class}:#{object_id}>"
+	# end
+
+	private
+
+	def ouroboros(node)
+		case node
+		when Array
+			node.map { |v| ouroboros(v) }
+		when Hash
+			node.each_with_object({}) { |(k, v), o| o[k.underscore.to_sym] = ouroboros(v) }
+		else
+			node
+		end
+	end
+
+	def request(method, path, path_params: {}, body_params: {}, query_params: nil)
+		uri = URI("#{PROTO}://#{HOST}")
+		uri.path = path % path_params
+		uri.query = URI.encode_www_form(query_params.compact) if query_params
+		request_uri(
+			method,
+			uri,
+			path_params: path_params,
+			body_params: body_params,
+			query_params: query_params
+		)
+	end
+
+	def request_uri(method, uri, path_params: {}, body_params: {}, query_params: nil, redirects: 0)
+		http             = Net::HTTP.new(uri.host, uri.port)
+		http.use_ssl     = true
+		http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+
+		case method
+		when :post
+			request =  Net::HTTP::Post.new uri
+			request['Content-Type'] = 'application/json; charset=UTF-8'
+			request.body = JSON.generate body_params.compact
+		when :get
+			request = Net::HTTP::Get.new uri
+		when :delete
+			request = Net::HTTP::Delete.new uri
+		else
+			raise NotImplementedError.new "Bad http method: #{method}"
+		end
+
+		# puts "\e[1;32mDespatching request to #{uri.path}\e[0m" if @debug
+
+		request["X-Api-Key"] = "#{@access_key_id}+#{@secret_access_key}"
+
+		@session = @agent.start unless @agent.started?
+		response = @session.request request
+
+		# puts "\e[1;32mResponse received\e[0m" if @debug
+
+		case response
+		when Net::HTTPOK
+			# Continue
+		when Net::HTTPRedirection
+			raise "Too many redirects" if redirects > @redirect_limit
+			# It's probably a file
+			next_uri = URI response['location']
+			return request_uri(method, next_uri, redirects: redirects + 1)
+		else
+			raise Error.new "Error response from #{uri} -> #{response.read_body}"
+		end
+
+		case response['content-type']
+		when /^application\/json/
+			data = ouroboros JSON.parse response.read_body
+		when /^text\/csv/, /^application\//
+			return Response.new(response.body)
+		else
+			raise NotImplementedError.new "Don't know how to parse #{response['content-type']}"
+		end
+
+		if data.key?(:pagination)
+			PaginatedResponse.new(
+				data,
+				self,
+				method,
+				uri.path,
+				path_params: path_params,
+				body_params: body_params,
+				query_params: query_params
+			)
+		else
+			Response.new data
+		end
+
+	end
+
+end

data/scripts/code_gen.rb

@@ -0,0 +1,54 @@
+require 'yaml'
+
+endpoints = YAML.load_file('spec_2022-12-02.yaml')
+
+def camel_to_snake(key)
+  key.gsub(/(?<=[a-z0-9])([A-Z])/) { "_#{$1}" }.downcase
+end
+
+def snake_to_camel(key)
+  key.gsub(/_([a-z0-9])/) { $1.upcase }
+end
+
+endpoints.each do |endpoint|
+	method_name = endpoint[:description].gsub(/[^a-z0-9_]/i, '_').downcase
+	combined_params = endpoint.values_at(
+		:path_params,
+		:query_params,
+		:body_params
+	).compact.flatten.each_with_object({}) do |param, o|
+		key = camel_to_snake param['Name']
+		puts "\e[31mOverwriting key: #{key}\e[0m" if o.key? key
+		o[camel_to_snake param['Name']] = /true/i === param['Required']
+	end
+
+	print "def #{method_name}("
+	puts "" if combined_params.any?
+	puts(combined_params.map do |k, v|
+		"	#{k}:#{v ? '' : 'nil'}"
+	end.join(",\n"))
+	puts ")"
+	puts ""
+
+	path = endpoint[:path].gsub(/\/:([a-z]+)\b/i) { ?/ + "\%<#{$1}>s" }
+
+	puts "	request("
+	puts "		:#{endpoint[:method].downcase},"
+	puts "		\"#{path}\","
+
+	[:path_params, :query_params, :body_params].each do |fields|
+		next unless endpoint.key? fields
+		puts "		#{fields}: {"
+		endpoint[fields].each do |param|
+			key = camel_to_snake param["Name"]
+			print "			#{param["Name"]}: #{key},"
+			print " # #{param["Description"]}" if param["Description"].length > 1
+			puts ""
+		end
+		puts "		},"
+	end
+	puts "	)"
+	puts "end"
+	puts ""
+
+end

data/scripts/doc_gen.rb

@@ -0,0 +1,38 @@
+require 'yaml'
+
+endpoints = YAML.load_file('spec_2022-12-02.yaml')
+
+def camel_to_snake(key)
+  key.gsub(/(?<=[a-z0-9])([A-Z])/) { "_#{$1}" }.downcase
+end
+
+def snake_to_camel(key)
+  key.gsub(/_([a-z0-9])/) { $1.upcase }
+end
+
+endpoints.each do |endpoint|
+	method_name = endpoint[:description].gsub(/[^a-z0-9_]/i, '_').downcase
+
+	puts "\n\n### #{method_name}\n"
+	combined_params = endpoint.values_at(
+		:path_params,
+		:query_params,
+		:body_params
+	).compact.flatten
+
+	combined_params.sort_by { |param|
+		camel_to_snake param['Name']
+	}.tap { |params|
+		if params.any?
+			puts "| Name | Required | Type | Value | Description |"
+			puts "| ---- | -------- | ---- | ----- | ----------- |"
+		end
+	}.each do |param, o|
+		key = camel_to_snake param['Name']
+		puts "| #{key} | #{param['Required']} | #{param['Type']} | #{param['Value']} | #{param['Description']} |"
+	end
+
+	paginated = combined_params.map { |x| x['Name'] }.include? 'take'
+	puts "\nResponse: `FlatfileApi::" + ( paginated ? 'Paginated' : '' ) + 'Response`'
+
+end

data/scripts/parse_docs.rb

@@ -0,0 +1,83 @@
+require 'nokogiri'
+require 'yaml'
+require 'open-uri'
+
+def body_params?(pointer)
+	/Request Body:/i === pointer.text
+end
+
+def example_response?(pointer)
+	/Example Reponse:/i === pointer.text
+end
+
+def extract_header(pointer)
+	/(POST|GET|DELETE|PATCH|PUT)\s+(.+)/ === pointer.text.strip.gsub(/[\u200B-\u200D\uFEFF]/, '')
+	$~.captures
+end
+
+def extract_params(pointer)
+	header, *rows = pointer.css('tr')
+	headers = header.css('th').map(&:text)
+	rows.each_with_object([]) do |row, o|
+		o << Hash[headers.zip(row.css('td').map(&:text))]
+	end
+end
+
+def extract_path(pointer)
+	/Endpoint:\s+(.*)/i === pointer.text&.strip
+	$~.captures.first
+end
+
+def header?(pointer)
+	/POST|GET|DELETE|PATCH|PUT/ === pointer.at_css('code')&.text
+end
+
+def param_table?(pointer)
+	/Name/i === pointer.at_css('th')&.text
+end
+
+def path?(pointer)
+	/Endpoint:\s+(.*)/i === pointer.text
+end
+
+def path_params?(pointer)
+	/Path Variables:/i === pointer.text
+end
+
+def query_params?(pointer)
+	/Query Params:/i === pointer.text
+end
+
+url = "https://flatfile.com/docs/api-reference/"
+doc = Nokogiri::HTML(URI.open(url))
+pointer = doc.at_css('#endpoints')
+
+endpoints = []
+context = nil
+spec = nil
+while pointer = pointer.next_sibling
+	case
+	when header?(pointer)
+		context = nil
+		spec = {}
+		endpoints << spec
+		spec[:method], spec[:description] = extract_header(pointer)
+	when path?(pointer)
+		spec[:path] = extract_path(pointer)
+	when body_params?(pointer)
+		context = :body_params
+	when path_params?(pointer)
+		context = :path_params
+	when query_params?(pointer)
+		context = :query_params
+	when param_table?(pointer)
+		spec[context] = extract_params(pointer)
+		context = nil
+	when example_response?(pointer)
+		context = nil
+	else
+		# puts "Don't know how to handle: #{pointer.text}"
+	end
+end
+
+puts endpoints.to_yaml