crowdin-api 1.13.0 → 1.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12f344cc4505d0b72b8aa88ad7be65075b4bd6528b001fcde826b40cf2dee874
-  data.tar.gz: 2164d78e4db36ae2e059a7bb9c26279962eeeb6e9f37937bd81ff00fca51201a
+  metadata.gz: 4bdb93529784382ee4d113d179869366097e30470da8e50e460d423df663f281
+  data.tar.gz: 0db2ee94c5d6ae47f6fb97421218297fdfccaffaf3c4c2f65dcc60332b7d9516
 SHA512:
-  metadata.gz: 708f2939ae29fbff6d80afc5e894aeaab6b57289fe1ce851e6ecd2de4570790e9965d325d860e2c7eebb770a592e6db9f90a44c9a4c35ba7c15150cdaa28eb0a
-  data.tar.gz: 85bae25c856683abae92d778987168d591848682679ce6d3db191c884607d208a2838882f9508ff8bc7ab4e29727d9a1791f3b14642e1291a37609334886ce77
+  metadata.gz: 47e744480df7814f0af17667a3353d1dc5d09857e94eb21d8aa2970ff5c7850882cd624a2f2f3ce5ed43573a4c3c812a8df8e143ec8a670f5a1bdca1165a8def
+  data.tar.gz: 794511fb64551fe49b67215d8213b793b8aa09f46eb5dbf8b6b31604f02d932f00986e0ad1e791e3d2dc2ee97398d594deed18b8408f378fdb8c9939786d4b36

data/.rubocop.yml

@@ -10,3 +10,7 @@ Gemspec/DevelopmentDependencies:
 Metrics/BlockLength:
   Exclude:
     - 'spec/**/*'
+
+Metrics/ModuleLength:
+  Exclude:
+    - 'lib/crowdin-api/api_resources/**/*'

data/.rubocop_todo.yml

@@ -119,6 +119,7 @@ Metrics/PerceivedComplexity:
 # Offense count: 1
 Naming/AccessorMethodName:
   Exclude:
+    - 'lib/crowdin-api/api_resources/organization.rb'
     - 'lib/crowdin-api/api_resources/users.rb'
 
 # Offense count: 1

data/AGENTS.md

@@ -0,0 +1,63 @@
+# AGENTS.md
+
+Ruby client for the Crowdin API v2 and Crowdin Enterprise API v2 (gem: `crowdin-api`, namespace `Crowdin`).
+
+The gemspec requires Ruby >= 2.4 while CI tests 3.0–3.3 — stay conservative with syntax (no pattern matching, no endless methods).
+
+## Layout
+
+- `lib/crowdin-api.rb` — entry point; the `API_RESOURCES_MODULES` array plus requires
+- `lib/crowdin-api/client/client.rb` — `Crowdin::Client`; mixes every resource module in
+- `lib/crowdin-api/api_resources/<name>.rb` — one module per API resource, plain instance methods
+- `lib/crowdin-api/core/` — request/response plumbing, errors, `fetch_all`, GraphQL
+- `spec/api_resources/<name>_spec.rb` — 1:1 with resources; WebMock, no fixtures directory
+
+## Commands
+
+- Install: `bundle install`
+- Test (all): `bundle exec rspec` (or `bundle exec rake`)
+- Test (one file): `bundle exec rspec spec/api_resources/<name>_spec.rb`
+- Lint (CI runs this before the specs): `bundle exec rubocop`
+- Lint autofix: `bundle exec rubocop -a`
+
+## Adding or changing an endpoint
+
+Fetch the endpoint spec first (see Crowdin API reference below). Then:
+
+1. Implement the method in `lib/crowdin-api/api_resources/<snake_case>.rb` (`# frozen_string_literal: true`, then `module Crowdin` > `module ApiResources` > `module <CamelCase>`):
+   - Argument order: required path ids, then the `query`/`body` hash, then optional `destination` (file downloads), then `project_id = config.project_id` last. RuboCop caps optional parameters at 4 and this pattern already uses them all.
+   - Guards: `project_id || raise_project_id_is_required_error`; Enterprise-only methods start with `enterprise_mode? || raise_only_for_enterprise_mode_error` and sit under a `# -- For Enterprise mode only --` comment.
+   - Body: build `Web::Request.new(connection, :get, "#{config.target_api_url}/projects/#{project_id}/...", { params: query })` and return `Web::SendRequest.new(request).perform` (pass `destination` as the second argument to `SendRequest` for downloads).
+   - Name list endpoints `list_*` — `fetch_all` refuses anything else (and hard-codes extra args for `list_terms` and `list_file_revisions` in `client.rb`).
+   - Doc comment: two `{https://support.crowdin.com/developer/... API Documentation}` links (base and enterprise) plus YARD `@param` lines.
+2. For a new resource, append the CamelCase symbol to `Crowdin::API_RESOURCES_MODULES` in `lib/crowdin-api.rb`. The file name must be the exact snake_case of that symbol: the require loop swallows `LoadError` silently and a mismatch surfaces later as an unrelated `NameError` from `const_get`. `client.rb` needs no edit — the include loop picks the module up.
+3. Spec in `spec/api_resources/<snake_case>_spec.rb`: tag examples `:default` or `:enterprise` — `spec_helper.rb` prebuilds `@crowdin` and sets the WebMock host (`https://api.crowdin.com` vs `https://domain.api.crowdin.com`) from the tag. House idiom: `stub_request(...)` with no `.to_return`, then `expect(result).to eq(200)` — `perform` returns the HTTP status for an empty body, a parsed Hash otherwise, and an error String on failure (HTTP errors are returned, not raised).
+
+A complete new resource touches exactly 3 files: the resource module, `lib/crowdin-api.rb`, and the spec.
+
+## Crowdin API reference
+
+Before implementing or changing any endpoint, fetch its spec from the llms.txt indexes (pick by environment, then project type):
+
+- https://support.crowdin.com/_llms-txt/api/crowdin/file-based.txt — Crowdin API, file-based projects (start here)
+- https://support.crowdin.com/_llms-txt/api/crowdin/string-based.txt — Crowdin API, string-based projects
+- https://support.crowdin.com/_llms-txt/api/enterprise/file-based.txt — Crowdin Enterprise API, file-based projects
+- https://support.crowdin.com/_llms-txt/api/enterprise/string-based.txt — Crowdin Enterprise API, string-based projects
+
+Each index links one spec file per route (e.g. `.../api.projects.strings.get.txt`) with the exact request and response shapes.
+
+## Conventions
+
+- Conventional Commits for commit messages and PR titles; CI lints PR titles.
+- PRs target `main`. CI runs RuboCop before the specs, so a lint failure blocks the test result.
+- Keep the public API backward compatible.
+- Never bump the version by hand — the Release workflow rewrites `lib/crowdin-api/client/version.rb`, the README install line, and `Gemfile.lock` together.
+
+## PR checklist
+
+A change is ready when:
+
+1. `bundle exec rubocop` is clean,
+2. `bundle exec rspec` passes,
+3. every new or changed endpoint method has a spec (tagged `:default`, plus `:enterprise` where the API differs), and
+4. every new or changed public method carries the two API documentation links.

data/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    crowdin-api (1.13.0)
+    crowdin-api (1.15.0)
       open-uri (>= 0.1.0, < 0.2.0)
       rest-client (>= 2.0.0, < 2.2.0)
 

data/README.md

@@ -35,7 +35,7 @@ Crowdin API is a full-featured RESTful API that helps you to integrate localizat
 Add this line to your application's Gemfile:
 
 ```gemfile
-gem 'crowdin-api', '~> 1.13.0'
+gem 'crowdin-api', '~> 1.15.0'
 ```
 
 And then execute:
@@ -134,6 +134,28 @@ file_revisions = crowdin.list_file_revisions(your_file_id, { limit: 10 }, your_p
 # Note: more examples you can find in spec folder
 ```
 
+### GraphQL API
+
+The client can send GraphQL requests to Crowdin's default API host or to an Enterprise organization endpoint.
+
+```ruby
+query = <<~GRAPHQL
+  query Viewer {
+    viewer {
+      id
+    }
+  }
+GRAPHQL
+
+response = crowdin.graphql({ query: query })
+```
+
+You can also provide a custom endpoint URL for testing.
+
+```ruby
+crowdin.graphql({ query: query }, url: 'http://localhost:3000/api/graphql')
+```
+
 ### Fetch all records
 
 There is a possibility to fetch all records from paginatable methods using `fetch_all` method.

data/lib/crowdin-api/api_resources/advisor.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Crowdin
+  module ApiResources
+    module Advisor
+      # @param body [Hash] Request Body
+      # * {https://support.crowdin.com/developer/api/v2/#operation/api.projects.advisors.checks.post  API Documentation}
+      # * {https://support.crowdin.com/developer/enterprise/api/v2/#operation/api.projects.advisors.checks.post  Enterprise API Documentation}
+      def create_advisor_check(body = {}, project_id = config.project_id)
+        project_id || raise_project_id_is_required_error
+
+        request = Web::Request.new(
+          connection,
+          :post,
+          "#{config.target_api_url}/projects/#{project_id}/advisors/checks",
+          { params: body }
+        )
+        Web::SendRequest.new(request).perform
+      end
+
+      # @param check_id [String] Advisor Check Identifier, consists of 36 characters
+      # * {https://support.crowdin.com/developer/api/v2/#operation/api.projects.advisors.checks.get  API Documentation}
+      # * {https://support.crowdin.com/developer/enterprise/api/v2/#operation/api.projects.advisors.checks.get  Enterprise API Documentation}
+      def get_advisor_check_status(check_id, project_id = config.project_id)
+        project_id || raise_project_id_is_required_error
+
+        request = Web::Request.new(
+          connection,
+          :get,
+          "#{config.target_api_url}/projects/#{project_id}/advisors/checks/#{check_id}"
+        )
+        Web::SendRequest.new(request).perform
+      end
+
+      # @param query [Hash] Request Query Parameters
+      # * {https://support.crowdin.com/developer/api/v2/#operation/api.projects.advisors.insights.getMany  API Documentation}
+      # * {https://support.crowdin.com/developer/enterprise/api/v2/#operation/api.projects.advisors.insights.getMany  Enterprise API Documentation}
+      def list_advisor_insights(query = {}, project_id = config.project_id)
+        project_id || raise_project_id_is_required_error
+
+        request = Web::Request.new(
+          connection,
+          :get,
+          "#{config.target_api_url}/projects/#{project_id}/advisors/insights",
+          { params: query }
+        )
+        Web::SendRequest.new(request).perform
+      end
+
+      # @param insight_id [Integer] Insight Identifier
+      # @param body [Array] Request Body
+      # * {https://support.crowdin.com/developer/api/v2/#operation/api.projects.advisors.insights.patch  API Documentation}
+      # * {https://support.crowdin.com/developer/enterprise/api/v2/#operation/api.projects.advisors.insights.patch  Enterprise API Documentation}
+      def edit_advisor_insight(insight_id, body = [], project_id = config.project_id)
+        project_id || raise_project_id_is_required_error
+
+        request = Web::Request.new(
+          connection,
+          :patch,
+          "#{config.target_api_url}/projects/#{project_id}/advisors/insights/#{insight_id}",
+          { params: body }
+        )
+        Web::SendRequest.new(request).perform
+      end
+
+      # @param application_identifier [String] applicationIdentifier
+      # @param module_key [String] moduleKey
+      # @param body [Hash] Request Body
+      # * {https://support.crowdin.com/developer/api/v2/#operation/api.projects.applications.modules.advisors.insights.put  API Documentation}
+      # * {https://support.crowdin.com/developer/enterprise/api/v2/#operation/api.projects.applications.modules.advisors.insights.put  Enterprise API Documentation}
+      def create_or_update_application_advisor_insight(application_identifier, module_key, body = {},
+                                                       project_id = config.project_id)
+        project_id || raise_project_id_is_required_error
+
+        endpoint = "projects/#{project_id}/applications/#{application_identifier}/modules/#{module_key}/advisors/insights"
+        request = Web::Request.new(
+          connection,
+          :put,
+          "#{config.target_api_url}/#{endpoint}",
+          { params: body }
+        )
+        Web::SendRequest.new(request).perform
+      end
+    end
+  end
+end