Initial commit

Author: sferik

.editorconfig

@@ -0,0 +1,9 @@
+root = true
+
+[*.cr]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true

.gitignore

@@ -0,0 +1,9 @@
+/docs/
+/lib/
+/bin/
+/.shards/
+*.dwarf
+
+# Libraries don't need dependency lock
+# Dependencies will be locked in applications that use them
+/shard.lock

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Erik Berlin <sferik@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,115 @@
+# X
+
+#### A Crystal interface to the X API.
+
+## Installation
+
+Add the dependency to your `shard.yml`:
+
+```yaml
+dependencies:
+  x:
+    github: sferik/x-crystal
+```
+
+Then run:
+
+    shards install
+
+## Usage
+
+```crystal
+require "x"
+
+x_credentials = {
+  api_key:             "INSERT YOUR X API KEY HERE",
+  api_key_secret:      "INSERT YOUR X API KEY SECRET HERE",
+  access_token:        "INSERT YOUR X ACCESS TOKEN HERE",
+  access_token_secret: "INSERT YOUR X ACCESS TOKEN SECRET HERE",
+}
+
+# Initialize an X API client with your OAuth credentials
+x_client = X::Client.new(**x_credentials)
+
+# Get data about yourself
+x_client.get("users/me")
+# {"data"=>{"id"=>"7505382", "name"=>"Erik Berlin", "username"=>"sferik"}}
+
+# Post a tweet
+tweet = x_client.post("tweets", '{"text":"Hello, World! (from @gem)"}')
+# {"data"=>{"edit_history_tweet_ids"=>["1234567890123456789"], "id"=>"1234567890123456789", "text"=>"Hello, World! (from @gem)"}}
+
+# Delete the tweet you just posted
+x_client.delete("tweets/#{tweet["data"]["id"]}")
+# {"data"=>{"deleted"=>true}}
+
+# Initialize an API v1.1 client
+v1_client = X::Client.new(base_url: "https://api.twitter.com/1.1/", **x_credentials)
+
+# Request your account settings
+v1_client.get("account/settings.json")
+
+# Initialize an X Ads API client
+ads_client = X::Client.new(base_url: "https://ads-api.twitter.com/12/", **x_credentials)
+
+# Request your ad accounts
+ads_client.get("accounts")
+```
+
+## History and Philosophy
+
+This library is a port of the [X Ruby library](https://github.com/sferik/x-ruby), which is a rewrite of the [Twitter Ruby library](https://github.com/sferik/twitter). The Ruby and Crystal version have the same basic interface and design philosophy, but this is not a strict guarantee.
+
+## Development
+
+1. Checkout and repo:
+
+       git checkout git@github.com:sferik/x-crystal.git
+
+2. Enter the repo’s directory:
+
+       cd x-crystal
+
+3. Install dependencies via Shards:
+
+       shards install
+
+4. Ensure all tests pass:
+
+       crystal spec
+
+5. Create a new branch for your feature or bug fix:
+
+       git checkout -b my-new-feature
+
+6. Write your feature or bug fix
+
+7. Ensure the code is formatted properly:
+
+       crystal tool format
+
+8. Ensure the tests still pass:
+
+       crystal spec
+
+9. Write tests to cover your new feature and ensure they pass:
+
+       crystal spec
+
+10. Commit your changes:
+
+        git commit -am "Add some feature"
+
+11. Push to the branch:
+
+        git push origin my-new-feature
+
+12. Open a Pull Request on GitHub
+
+## Contributors
+
+- [Erik Berlin](https://github.com/sferik) - creator and maintainer
+
+## License
+
+The code is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

shard.yml

@@ -0,0 +1,14 @@
+name: x
+version: 0.1.0
+
+authors:
+  - Erik Berlin <sferik@gmail.com>
+
+crystal: 1.9.2
+
+development_dependencies:
+  webmock:
+    github: manastech/webmock.cr
+    branch: master
+
+license: MIT

spec/client_spec.cr

@@ -0,0 +1,45 @@
+require "./spec_helper"
+
+module X
+  describe Client do
+    client = Client.new(api_key: "api_key", api_key_secret: "api_key_secret", access_token: "access_token", access_token_secret: "access_token_secret")
+
+    describe "#get" do
+      it "sends a GET request" do
+        endpoint = "test_endpoint"
+        stub_request(:get, endpoint, 200)
+        response = client.get(endpoint)
+        response.should eq({} of String => String)
+      end
+    end
+
+    describe "#post" do
+      it "sends a POST request with body" do
+        endpoint = "test_endpoint"
+        body = "{\"data\":\"test\"}"
+        stub_request(:post, endpoint, 200)
+        response = client.post(endpoint, body)
+        response.should eq({} of String => String)
+      end
+    end
+
+    describe "#put" do
+      it "sends a PUT request with body" do
+        endpoint = "test_endpoint"
+        body = "{\"data\":\"test\"}"
+        stub_request(:put, endpoint, 200)
+        response = client.put(endpoint, body)
+        response.should eq({} of String => String)
+      end
+    end
+
+    describe "#delete" do
+      it "sends a DELETE request" do
+        endpoint = "test_endpoint"
+        stub_request(:delete, endpoint, 200)
+        response = client.delete(endpoint)
+        response.should eq({} of String => String)
+      end
+    end
+  end
+end

spec/response_handler_spec.cr

@@ -0,0 +1,84 @@
+require "./spec_helper"
+
+module X
+  describe ResponseHandler do
+    it "handles a successful response" do
+      response = HTTP::Client::Response.new(200, "{\"status\":\"success\"}")
+      handler = ResponseHandler.new
+      result = handler.handle(response)
+      result.should eq({"status" => "success"})
+    end
+
+    it "raises a BadRequestError for a 400 response" do
+      response = HTTP::Client::Response.new(400, "Bad Request")
+      handler = ResponseHandler.new
+      expect_raises BadRequestError, "400 Bad Request - Bad Request" do
+        handler.handle(response)
+      end
+    end
+
+    it "raises a AuthenticationError for a 401 response" do
+      response = HTTP::Client::Response.new(401, "Unauthorized")
+      handler = ResponseHandler.new
+      expect_raises AuthenticationError, "401 Unauthorized - Unauthorized" do
+        handler.handle(response)
+      end
+    end
+
+    it "raises a ForbiddenError for a 403 response" do
+      response = HTTP::Client::Response.new(403, "Forbidden")
+      handler = ResponseHandler.new
+      expect_raises ForbiddenError, "403 Forbidden - Forbidden" do
+        handler.handle(response)
+      end
+    end
+
+    it "raises a NotFoundError for a 404 response" do
+      response = HTTP::Client::Response.new(404, "Not Found")
+      handler = ResponseHandler.new
+      expect_raises NotFoundError, "404 Not Found - Not Found" do
+        handler.handle(response)
+      end
+    end
+
+    it "raises a TooManyRequestsError for a 429 response" do
+      response = HTTP::Client::Response.new(429, "Too Many Requests")
+      handler = ResponseHandler.new
+      expect_raises TooManyRequestsError, "429 Too Many Requests - Too Many Requests" do
+        handler.handle(response)
+      end
+    end
+
+    it "raises a ClientError for a 499 response" do
+      response = HTTP::Client::Response.new(499, "Client Error")
+      handler = ResponseHandler.new
+      expect_raises ClientError, "499 Client Error - Client Error" do
+        handler.handle(response)
+      end
+    end
+
+    it "raises a ServerError for a 500 response" do
+      response = HTTP::Client::Response.new(500, "Internal Server Error")
+      handler = ResponseHandler.new
+      expect_raises ServerError, "500 Server Error - Internal Server Error" do
+        handler.handle(response)
+      end
+    end
+
+    it "raises a ServerError for a 503 response" do
+      response = HTTP::Client::Response.new(503, "Service Unavailable")
+      handler = ResponseHandler.new
+      expect_raises ServiceUnavailableError, "503 Service Unavailable - Service Unavailable" do
+        handler.handle(response)
+      end
+    end
+
+    it "raises an Error for an unknown response" do
+      response = HTTP::Client::Response.new(600, "Unknown")
+      handler = ResponseHandler.new
+      expect_raises Error, "600 Unknown Response - Unknown" do
+        handler.handle(response)
+      end
+    end
+  end
+end

spec/spec_helper.cr

@@ -0,0 +1,16 @@
+require "../src/x"
+require "spec"
+require "webmock"
+
+module SpecHelper
+  def stub_request(http_method : Symbol, endpoint : String, status : Int32, headers : HTTP::Headers? = nil, body : String? = "{}")
+    full_url = "#{X::ClientDefaults::DEFAULT_BASE_URL}#{endpoint}"
+    WebMock.stub(http_method, full_url).to_return(status: status, body: body, headers: headers)
+  end
+end
+
+Spec.before_each do
+  WebMock.reset
+end
+
+include SpecHelper

spec/version_spec.cr

@@ -0,0 +1,25 @@
+require "./spec_helper"
+
+module X
+  describe VERSION do
+    it "has a version" do
+      X::VERSION.should_not be_nil
+    end
+
+    it "has a major version" do
+      X::VERSION.major.should_not be_nil
+    end
+
+    it "has a minor version" do
+      X::VERSION.minor.should_not be_nil
+    end
+
+    it "has a patch version" do
+      X::VERSION.patch.should_not be_nil
+    end
+
+    it "converts to a string" do
+      X::VERSION.to_s.should be_a(String)
+    end
+  end
+end

src/x.cr

@@ -0,0 +1 @@
+require "./x/client"

src/x/authenticator.cr

@@ -0,0 +1,26 @@
+require "oauth"
+require "uri"
+require "./client_defaults"
+
+module X
+  class Authenticator
+    include ClientDefaults
+
+    getter! api_key : String
+    getter! api_key_secret : String
+    getter! access_token : String
+    getter! access_token_secret : String
+    getter! oauth_access_token : OAuth::AccessToken
+    getter! oauth_consumer : OAuth::Consumer
+
+    def initialize(base_url : URI, @api_key : String, @api_key_secret : String, @access_token : String, @access_token_secret : String)
+      host = base_url.host || DEFAULT_HOST
+      @oauth_consumer = OAuth::Consumer.new(host, api_key, api_key_secret)
+      @oauth_access_token = OAuth::AccessToken.new(access_token, access_token_secret)
+    end
+
+    def authenticate(http_client : HTTP::Client)
+      oauth_consumer.authenticate(http_client, oauth_access_token)
+    end
+  end
+end